vscode-cowriting-plugin-content/specs/coauthoring-out-of-workspace.md

status

status
graduated

Solution Design: Out-of-Workspace Authoring (F8)

Author(s)	Ben Stull (with Claude)
Reviewers / approvers	Ben Stull
Status	draft
Version	v0.1.0
Source artifacts	Feature benstull/vscode-cowriting-plugin#25 (F8) · Epic #1 (closed) · Capture session vscode-cowriting-plugin-0023 · Parent specs (all graduated): specs/coauthoring-inner-loop.md, specs/coauthoring-attribution.md, specs/coauthoring-propose-accept.md, specs/coauthoring-cross-rung-format.md, specs/coauthoring-sidecar-contract.md, specs/coauthoring-diff-view.md (F6, the global-storage-by-URI-hash precedent) · Direct precursors: F6 #17/#19 (PR #18/#20), session-0022 guard fix #24 (PR #24) · Lineage: ben.stull/rfc-app#48

Change log

Date	Version	Change	By
2026-06-11	v0.1.0	Initial draft — brainstorming session 0024. Hybrid persistence model (repo sidecar in-workspace · global-storage sidecar out-of-workspace/untitled); F5 non-shareability and URI-rename orphaning settled. INV-24/INV-25.	Ben Stull + Claude

---

1. Business Context

1.1 Executive Summary

F8 removes a surprising asymmetry in the coauthoring surface. F6 (diff-view, #19) and F7 (rendered preview, #21) were broadened to work on any document the editor will show — in-folder, out-of-folder, or untitled — because they persist nothing in the repo (F6's baseline lives in VS Code global storage keyed by a URI hash, INV-19; F7 persists nothing). But the authoring surfaces — F2 threads, F3 attribution, F4 "Ask Claude to Edit Selection" — still refuse any document that is not a saved file: under workspaceFolders[0], because they persist a git-native .threads/<repo-relative-path>.json sidecar under the workspace root, which has no home for an out-of-workspace file. The result is the "why does diff/preview work here but I can't ask Claude to edit?" friction the operator hit during F7 manual testing.

F8's load-bearing move is a hybrid persistence model: a single SidecarStore abstraction the three authoring controllers share, routed per-document — in-workspace file: docs keep their committable repo .threads/ sidecar byte-for-byte unchanged (INV-2 preserved; no migration), while out-of-workspace file: docs and untitled: buffers fall back to a global-storage sidecar keyed by sha256(documentUri), mirroring F6's BaselineStore (INV-19). The persisted artifact JSON is identical either way — same shape, same SCHEMA_VERSION — so mergeArtifacts and the F5 cross-rung contract need no change. Two consequences are stated as design contract, not discovered later: a global-storage artifact is not a committed file, so it is never cross-rung-shareable (acceptable — an out-of-repo file isn't shared via the repo anyway), and URI-hash keying means renaming/moving an out-of-workspace file orphans its artifact (the repo sidecar, by contrast, moves with the file in git).

1.2 Background

The inner-loop triad shipped across F2–F4 (threads · attribution · propose/accept); F5 made the sidecar a cross-rung contract; F6 added a diff-view; F7 a rendered track-changes preview. F6's #19 follow-up established the pattern this Feature generalizes: a view that needs only a stable document identity and a storage home — not a .threads/ sidecar — can serve any document by persisting its state in global storage under sha256(uri). F8 asks the symmetric question for authoring: the authoring controllers also need only a stable identity and a storage home for their artifact; the sole reason they refuse out-of-workspace docs is that their one storage implementation (CoauthorStore) is workspace-root-bound. Issue #25 routes the design forks — the storage abstraction shape, untitled identity, F5 non-shareability, and the rename-orphaning caveat — to this session; all are resolved here (§6.7, §9).

1.3 Business Actors / Roles

• Coauthor (human) — the writer/engineer (PP-1); F8's sole user. F8 exists to make "ask Claude to edit" available on the same documents diff/preview already serve.
• Coauthor (machine) — Claude via @cline/sdk; not a new actor in F8. Its edits still enter only through the F4 seam (INV-9); F8 changes where the artifact is stored, not how machine text lands.

1.4 Problem Statement

The human can diff (F6) and preview (F7) a document the extension is not anchored to, but cannot ask Claude to edit it: threads, attribution, and propose/accept refuse any document that is not a saved file: under the opened workspace folder, because they persist to a workspace-rooted .threads/ sidecar. Authoring is the only surface still gated to in-workspace files.

1.5 Pain Points

• A file opened from a sibling repo, a scratch file outside the folder, or an untitled buffer can be diffed and previewed but not edited by Claude — an inconsistency with no cause the user can see.
• Until session-0022 (#24) the refusal even misreported the reason ("select some text" for an out-of-workspace file). #24 fixed the message; F8 fixes what is accepted.
• The asymmetry undercuts the "ask Claude to edit anything you're looking at" mental model the universal diff/preview already set.

1.6 Targeted Business Outcomes

The human can select text and ask Claude to edit it in any document the editor will show — saved-in-folder, saved-out-of-folder, or untitled — so the authoring loop matches the (already universal) diff/preview loop. Authoring on a workspace file is byte-for-byte unchanged; authoring on an out-of-workspace/untitled file simply works, with its state kept where a repo sidecar can't live.

1.7 Scope (business)

In scope: a hybrid persistence model — one SidecarStore abstraction the three authoring controllers (thread · attribution · proposal) share, routed per-document: in-workspace file: → repo .threads/ (CoauthorStore, unchanged); out-of-workspace file: + untitled: → global-storage sidecar (GlobalSidecarStore, URI-hash key). Widening the editSelection guard and the three controllers' membership predicate to accept the additional documents (routing them to the global store). Re-anchoring (content-based, F2) and reload-restore for global-storage docs. Host E2E (no LLM) covering an out-of-workspace file and an untitled buffer. Docs: the hybrid model + the F5 non-shareability note.

Out of scope (deferred, not forgotten): untitled→saved artifact migration (when an untitled buffer is saved, its in-memory artifact is not carried to the new file: sidecar in v1 — §6.7/§9); a re-key/recover gesture for an orphaned global artifact after a rename (§9); any per-author coloring or UI change beyond accepting more documents.

Non-goals (firm, from #25): uniform global storage — moving in-workspace docs off the committable sidecar is explicitly rejected (it would lose committable threads/attribution, the point of INV-2); migrating existing repo sidecars; cross-rung sharing of global-storage artifacts (designed-out, §6.7); adding any LLM/network/credential surface (INV-8 untouched).

1.8 Assumptions · Constraints · Dependencies

• Anchor: Feature #25 (F8). Builds on F2 #4 · F3 #6 · F4 #12 · F5 #14 · F6 #17/#19 · the #24 guard fix; Epic #1 is closed.
• The artifact shape is stable across storage homes: Artifact (model.ts) and SCHEMA_VERSION = 1 (model.ts:11) are untouched — only where the JSON is written differs. So mergeArtifacts and the cross-rung contract (INV-14..17) need no change (INV-25).
• The global-storage precedent is load-bearing and proven: F6's BaselineStore (src/baselineStore.ts) already persists per-document JSON under context.globalStorageUri keyed by sha256(uri), with untitled buffers held in-memory only. F8 mirrors it for the artifact.
• This touches INV-2 (git-native sidecar) by adding an alternative persistence path — a load-bearing change, hence this Feature needs a Solution Design before implementation (handbook §3.4 R3); INV-2 itself is preserved for in-workspace docs (no migration).
• No LLM/network/credential surface added (INV-8 untouched); the seam (INV-9/10) is unchanged.

1.9 Business Use Cases

• BUC-1 (sibling-repo file) The operator opens a markdown file from a sibling repo (outside the workspace folder), selects a paragraph, asks Claude to edit it, reviews the proposal, accepts — and the thread/attribution survive a reload.
• BUC-2 (scratch / untitled) The operator drafts in an untitled buffer, asks Claude to edit a selection, accepts — works within the session (state is in-memory; the rename/orphaning limits are surfaced, §6.7).

---

2. Solution Proposal

Introduce one persistence abstraction the three authoring controllers depend on — SidecarStore (load / save / update / consumeSelfWrite over a per-document document key) — and a router that selects the implementation per document by the same isUnderRoot predicate #24 added:

• In-workspace file: docs → the existing repo-rooted CoauthorStore, keyed by the repo-relative path, writing .threads/<path>.json — byte-for-byte unchanged (INV-2). This is the only path the cross-rung contract (F5) ever sees.
• Out-of-workspace file: and untitled: docs → a new GlobalSidecarStore mirroring BaselineStore: per-document Artifact JSON under <context.globalStorageUri>/sidecars/<sha256(documentUri)>.json (INV-19's storage home, never the repo). Untitled buffers, having no durable identity, are held in-memory only (the F6 degrade).

The document key — repo-relative path for in-workspace docs, the URI string otherwise — is the single identity used as the store key, as the artifact's document.path, and in each controller's in-memory state map and test-facing surface. Because the key for an out-of-workspace artifact is a machine-local URI (and the file isn't committed), such artifacts are never read by mergeArtifacts / shared across rungs (INV-25) — stated as contract, not happenstance.

The authoring gate widens to accept the additional documents: the editSelection selectionRejection and the three controllers' membership predicate become a shared isAuthorable(document) = scheme ∈ {file:, untitled:}; isUnderRoot is demoted from a gate to a routing input (it now only picks the store, never refuses the document). As in F6, the authoring commands therefore become workspace-independent — live even with no folder open (every doc then routes to global storage).

---

3. Product Personas

• PP-1 Inner-loop coauthor — the human writer/engineer (as F2–F7); the only persona F8 serves.

4. Product Use Cases

• PUC-1 (edit an out-of-folder file) Open a saved file outside the workspace folder, select text, run "Ask Claude to Edit Selection" → a proposal appears (F4); accept → the text lands Claude-attributed (F3) and a thread can be opened (F2); the artifact persists to global storage and survives a reload.
• PUC-2 (edit an untitled buffer) In an untitled buffer, select text, ask Claude to edit → propose/accept/thread all work within the session; state is in-memory and is lost on reload or on save (§6.7) — the rest of the loop is identical.
• PUC-3 (in-workspace unchanged) On a saved file inside the workspace folder, every authoring gesture behaves exactly as before F8 — same .threads/ sidecar, same cross-rung shareability, byte-for-byte (INV-2).
• PUC-4 (re-anchor + reload, global doc) After Claude edits an out-of-folder file, the operator edits around the anchored span; anchors re-resolve content-based (F2); on reload the threads/attributions/proposals are restored from the global-storage sidecar at their re-anchored positions.
• PUC-5 (graceful edges) Global storage unavailable → in-memory fallback + one warning (the session still works; reload-survival is lost) — the F6 degrade. A focus that is neither file: nor untitled: (e.g. an output: or git: read-only doc) → the existing per-condition warning, no authoring. A renamed out-of-folder file → its prior artifact is orphaned (a self-describing, recoverable empty state — §6.7/§9).

5. UX Layout

No bespoke UI surface — the existing F2–F4 affordances unchanged (comment threads, attribution tints, proposal diffs). The only visible change is that "Ask Claude to Edit Selection" (and threads/attribution) now succeed on more documents instead of warning. The session-0022 (#24) per-condition messaging is retained for the documents F8 still declines (non-text-editor focus; a scheme other than file:/untitled:; an empty selection). The authoring commands are registered workspace-independently (the F6 #19 precedent) so they are live folder-less. No status-bar item, no new command, no keybinding.

---

6. Technical Design

6.1 Invariants

Parent invariants INV-1..INV-23 carry over unchanged. F8 adds:

• INV-24 (hybrid persistence routing) Every authoring artifact is persisted through one SidecarStore abstraction, routed per-document by membership: an in-workspace file: document persists to the committable repo .threads/<repo-relative-path>.json sidecar byte-for-byte unchanged (INV-2 preserved — no migration, no behavior change); an out-of-workspace file: or untitled: document persists to a global-storage sidecar keyed by sha256(documentUri) under context.globalStorageUri, never the repo (mirroring INV-19). The Artifact shape and SCHEMA_VERSION are identical across both homes — only the storage location differs. The document key (repo-relative path in-workspace; the URI string otherwise) is the single identity used as store key, as artifact.document.path, and in the controllers' in-memory state.
• INV-25 (global artifacts are single-rung) A global-storage artifact is not a committed file, so it is never read by mergeArtifacts or shared across rungs (F5); out-of-workspace/untitled authoring is session-/machine-local by construction. Its document.path is a machine-local URI that carries no cross-rung meaning. The cross-rung contract (INV-14..17) and the in-workspace committable sidecar (INV-2) are untouched.

6.2 High-level architecture

One new vscode-free store + one routing façade + one identity helper; the three controllers are re-pointed from the concrete CoauthorStore onto the SidecarStore interface, and their workspace-root gate is replaced by a shared authorability predicate.

• SidecarStore (interface, src/sidecarStore.ts) — the surface the controllers depend on: load(key) : Artifact | null · save(key, artifact) · update(key, mutate) : Artifact · consumeSelfWrite(fsPath) : boolean. The existing CoauthorStore already satisfies this shape (it becomes the in-workspace implementation, unchanged).
• GlobalSidecarStore (src/globalSidecarStore.ts, vscode-free) — the out-of-workspace/untitled implementation, mirroring BaselineStore: per-key Artifact JSON at <storageDir>/sidecars/<key>.json where key = sha256(documentUri); consumeSelfWrite is a no-op returning false (global storage is outside the **/.threads/** watcher — no self-write storm to suppress). Untitled docs are held in-memory only (no disk write), the F6 degrade.
• SidecarRouter (src/sidecarRouter.ts) — implements SidecarStore and owns the routing: given a document's identity ({ uri, fsPath, scheme }) and the workspace root, it (a) computes the document key — asRelativePath-style repo-relative path when scheme === "file" && isUnderRoot(fsPath, root), else the URI string — and (b) dispatches load/save/update to CoauthorStore (repo) or GlobalSidecarStore (global) by the same predicate. Exposes keyOf(document) : string so controllers and tests share the one identity. Vscode-free (takes the extracted identity primitives, not a vscode.TextDocument), so it is unit-testable.
• isAuthorable(document) (in src/workspacePath.ts) — scheme ∈ {file:, untitled:}. Replaces the three controllers' near-identical isInRoot/isTracked (scheme === "file" && isUnderRoot(...)) gate. #24's isUnderRoot is retained — now consumed by the router for store selection, never as an authoring gate.
• The three controllers (threadController.ts, attributionController.ts, proposalController.ts) — constructor store param re-typed CoauthorStore → SidecarStore (receives the router); rootDir no longer used for gating (membership → isAuthorable); per-document key via store.keyOf(document) (replacing direct asRelativePath). The seam (applyAgentEdit, INV-9) and all artifact logic are unchanged — they already operate on Artifact and a docPath string.
• VersionGuard — re-pointed at the SidecarStore interface so INV-16's schemaVersion check applies uniformly to both homes (a global artifact can be stale from an older plugin build even though it never merges).
• Everything else reused unchanged: Anchorer (content-based, storage-agnostic already), the F4 seam, mergeArtifacts (only ever sees committed repo sidecars), F6/F7 controllers.

flowchart TD
  cmd["editSelection / thread / attribution\nentry points"] --> gate{"isAuthorable?\n(scheme ∈ file/untitled)"}
  gate -- no --> warn["per-condition warning (#24)"]
  gate -- yes --> router["SidecarRouter\nkeyOf(doc) + route"]
  router --> isroot{"scheme=file &&\nisUnderRoot(fsPath, root)?"}
  isroot -- yes --> repo["CoauthorStore\n.threads/<repo-rel>.json\n(committable, INV-2)\n→ F5 cross-rung"]
  isroot -- "no (out-of-folder / untitled)" --> glob["GlobalSidecarStore\n<globalStorageUri>/sidecars/\nsha256(uri).json (INV-19)\nuntitled: in-memory only\n→ single-rung (INV-25)"]
  repo & glob --> art["identical Artifact JSON\n(SCHEMA_VERSION=1, INV-24)"]

6.3 Data model & ownership

The persisted artifact is the existing Artifact (model.ts:95-106), unchanged in shape or version:

interface Artifact {
  schemaVersion: number;            // SCHEMA_VERSION = 1, identical both homes
  document: { path: string };       // the document key (see below)
  anchors: Record<string, Anchor>;  // SHARED primitive (INV-4)
  threads: Thread[];
  attributions: AttributionRecord[];
  proposals: Proposal[];
}

The document key (document.path) is the single identity, and its value depends on home:

Document	Key (document.path)	On-disk location	Cross-rung
In-workspace file:	repo-relative path (e.g. notes/ch-1.md)	<root>/.threads/<path>.json	yes (F5, INV-2)
Out-of-workspace file:	the URI string file:///abs/path	<globalStorageUri>/sidecars/<sha256(uri)>.json	no (INV-25)
untitled:	the URI string untitled:Untitled-1	in-memory only (no disk)	no (INV-25)

• One artifact per document — the store key is the document key; no history.
• Owner: for in-workspace, the repo (committable, mergeable — unchanged). For global, the extension alone: the file lives in VS Code's machine-wide global storage, outside any repo, so it can never be committed, merged, or read by another rung — unknown-field preservation (INV-17) is moot for it.
• Capture/identity source is the document URI (document.uri.toString()), matching BaselineStore.uri — the same identity F6 already keys on, so a doc's baseline and its authoring artifact share a hash.

6.4 Interfaces & contracts

• SidecarStore (the controllers' dependency; CoauthorStore already conforms): load(key): Artifact | null · save(key, artifact): void · update(key, mutate): Artifact · consumeSelfWrite(fsPath): boolean.
• GlobalSidecarStore (vscode-free): same SidecarStore surface; constructed with the global storage dir (context.globalStorageUri?.fsPath, the F6 wiring at extension.ts:57); `sidecarPath(key) = /sidecars/.json`; `consumeSelfWrite` ⇒ `false`. Untitled keys resolve to an in-memory map, never disk.
• SidecarRouter (implements SidecarStore): constructed with CoauthorStore, GlobalSidecarStore, and the workspace root (or undefined when no folder is open ⇒ everything routes global). keyOf(docIdentity): string; load/save/update/consumeSelfWrite dispatch by isUnderRoot.
• isAuthorable(document): boolean (workspacePath.ts) — scheme ∈ {file:, untitled:}. Used by the three controllers' membership predicate and by selectionRejection.
• selectionRejection (workspacePath.ts:42-56) — the scheme !== "file" and !isUnderRoot branches are replaced by a single !isAuthorable branch (rejecting only schemes outside {file, untitled}); the no-editor and empty-selection branches are retained verbatim. The "save this to a file first" / "outside your workspace folder" messages are removed (those documents are now accepted).
• Controllers — constructor store: CoauthorStore → store: SidecarStore; rootDir dropped from the gate (membership = isAuthorable), key via store.keyOf. The CowritingApi test handles (threadController, attributionController, proposalController) and their test-facing surfaces (getRendered(key), getSpans(key)) are unchanged — they accept the document key, which for in-workspace docs is still the repo-relative path the existing tests pass.
• package.json / activation — the authoring commands move to the workspace-independent registration path (the F6 #19 precedent): live even with no folder open. The **/.threads/**/*.json watcher (extension.ts:127) is unchanged (it only ever matters for repo sidecars).

6.5 Per–Product-Use-Case design

• PUC-1 (out-of-folder file): editSelection passes isAuthorable; the router keys by the file URI and routes to GlobalSidecarStore; propose/accept and threads run exactly as in-workspace (the controllers are storage-agnostic above the SidecarStore seam). The seam (INV-9) lands text and fires onDidApplyAgentEdit — F6's baseline advance still works (F6 already serves this doc). Reload: ensureState loads the global sidecar by the same hash.
• PUC-2 (untitled): identical control flow; the router routes to GlobalSidecarStore's in-memory branch (no durable URI). State lives for the session; lost on reload or on save (§6.7). The diff/preview (F6/F7) already behave this way for untitled, so the whole stack is consistent.
• PUC-3 (in-workspace unchanged): the router computes the repo-relative key and dispatches to CoauthorStore; not one byte of the persisted path, filename, or JSON differs from pre-F8 (INV-2). This is the byte-for-byte acceptance criterion and is asserted directly in E2E (§6.8).
• PUC-4 (re-anchor + reload, global): anchoring is content-based and storage-agnostic (Anchorer is unchanged), so re-anchoring works identically; on reload renderAll reloads the global sidecar and re-resolves anchors against the current buffer — the F2 restore path, now fed by the router.
• PUC-5 (edges): global storage write failure ⇒ GlobalSidecarStore degrades to in-memory + one warning (F6's exact degrade) — authoring works for the session, reload-survival lost. A non-{file,untitled} scheme ⇒ selectionRejection warns. A renamed out-of-folder file ⇒ new URI ⇒ new hash ⇒ empty artifact (its prior state orphaned under the old hash); recovery is re-authoring (§9 notes a future re-key gesture).

6.6 Non-functional requirements & cross-cutting concerns

Storage is one document-sized Artifact JSON per out-of-workspace doc in VS Code's global storage (local machine, same trust domain as the working tree; artifact content is operator/coauthoring data, the document's own sensitivity class — identical to F6 baselines, which already store full document text there, a strictly larger footprint than F8's anchored metadata). No LLM, no network, no new credential surface (INV-8). The router adds O(1) dispatch per store call; keying is one sha256 of a URI per call (F6's cost). The **/.threads/** watcher never fires for global artifacts (they're outside the workspace), so there is no self-write/re-anchor storm — consumeSelfWrite is a no-op there. Non-text/oversized skipping (the F2 rule) is unchanged and applies in both homes.

6.7 Key decisions & alternatives considered

Decision	Chosen	Alternatives rejected
Persistence model (the load-bearing fork)	Hybrid: in-workspace file: keep the committable repo .threads/ sidecar (INV-2, byte-for-byte); out-of-workspace file: + untitled: use a global-storage sidecar keyed by sha256(uri) (INV-19/24). One SidecarStore abstraction, routed per-document by #24's isUnderRoot	Uniform global storage (move all docs off the committable sidecar — explicitly rejected by #25: loses committable threads/attribution, the entire point of INV-2, and breaks F5 cross-rung for in-workspace docs); per-document opt-in/config (a setting for where to store — no user story, just friction); gitignored repo cache for out-of-folder docs (litters the working tree, risks accidental commit, needs .gitignore management — F6 rejected this for the same reason)
Storage abstraction shape	SidecarStore interface + SidecarRouter façade with two impls (existing CoauthorStore, new GlobalSidecarStore mirroring BaselineStore); controllers depend on the interface; the router owns identity (keyOf) and routing	Branch inside each controller (if isUnderRoot … else … in all three — triples the routing logic, three places to drift, couples each controller to both stores); a second store passed alongside the first with per-call selection in the controller (same drift, leaks routing into callers); subclass CoauthorStore (the workspace-root binding is in the base — inheritance fights it)
Document key / artifact.document.path	One key: repo-relative path in-workspace (unchanged, cross-rung-meaningful), the URI string otherwise (self-consistent, machine-local — reinforces INV-25). The router's keyOf is the single source, used as store key, document.path, in-memory map key, and test surface	Always the URI (would change the in-workspace document.path ⇒ breaks INV-2/F5 and existing sidecars); a synthetic opaque id (needs a side mapping to recover identity; URI already is the identity); hash as the key everywhere (loses the human-readable repo-relative path the cross-rung contract relies on)
Untitled identity & on-save migration	In-memory only (no durable URI — the F6 degrade); on save the in-memory artifact is not migrated to the new file: sidecar in v1 (a fresh empty artifact is created for the saved file). Documented limitation; migration is an additive follow-up (§9)	Persist by the untitled URI (untitled:Untitled-1 is not stable across reloads — a persisted artifact would mis-bind to a different buffer next session: worse than losing it); block authoring on untitled (re-introduces the very asymmetry F8 removes — diff/preview serve untitled); auto-migrate on save in v1 (real value but needs old-URI→new-URI artifact transfer with edge cases — deferred, not blocking the core win)
F5 cross-rung shareability of global artifacts	Not shareable, by design (INV-25) — a global artifact is not a committed file, so mergeArtifacts/the cross-rung sync never see it; stated as contract. Acceptable: an out-of-repo file isn't shared via the repo anyway	Force-share via a synthetic committed file (would have to invent a repo home for an out-of-repo file — defeats the hybrid model and pollutes the repo); export/import command (no user story; out-of-scope per #25)
URI-rename orphaning	Accepted & documented (§6.5/§9, INV-24 commentary) — sha256(uri) keying means rename/move ⇒ new hash ⇒ orphaned artifact; recovery is re-authoring. This is the inherent cost of URI-hash keying (F6 baselines already have it; less painful there because a baseline is disposable)	Track renames via onDidRenameFiles (only fires for workspace files — useless for the out-of-folder docs this affects); content-hash keying (a single edit changes the content hash ⇒ orphans on every keystroke — far worse); store-by-inode (non-portable, fragile) — a re-key/recover gesture is the right additive answer (§9), not v1
Membership gate	Replace the three controllers' scheme=file && isUnderRoot gate with shared isAuthorable (scheme ∈ file/untitled); isUnderRoot demoted to a router input (store selection), never a refusal. Authoring commands registered folder-independently (F6 #19 precedent)	Keep isUnderRoot as a gate and add a parallel out-of-root gate (two predicates to keep in sync across three controllers); accept every scheme (read-only git:/output: docs aren't editable — must still decline non-{file,untitled})

6.8 Testing strategy

• Unit (vitest, vscode-free):
  • GlobalSidecarStore round-trip (save → load by sha256(uri) key, overwrite-in-place, missing → null, consumeSelfWrite ⇒ false); in-memory untitled branch (save→load in-session, absent after a simulated reload).
  • SidecarRouter: keyOf returns the repo-relative path for an in-root file and the URI string for an out-of-root file / untitled; load/save/update dispatch to the correct impl per isUnderRoot; root = undefined ⇒ everything routes global.
  • isAuthorable / selectionRejection: accepts in-root file, out-of-root file, and untitled; still rejects no-editor, empty-selection, and a non-{file,untitled} scheme, each with its own message (extends test/workspacePath.test.ts).
• Host E2E (@vscode/test-electron, the F2–F6 seam pattern, no LLM):
  • Out-of-workspace file: open a saved file outside the workspace folder → programmatic propose via the cowriting.proposeAgentEdit seam → accept → text replaced + Claude-attributed + proposal removed (INV-9/11/13) → a thread opens → renderAll after a simulated reload restores threads/attributions/proposals from the global sidecar at the re-anchored span → assert the artifact file exists under <globalStorageUri>/sidecars/<hash>.json and no .threads/ was written.
  • Untitled buffer: same propose→accept→thread loop in an untitled doc; assert state is present in-session and no disk artifact was written (in-memory only).
  • In-workspace regression (byte-for-byte, INV-2): the existing F2–F4 E2E continue to pass unchanged, and an assertion that the in-workspace artifact still lands at <root>/.threads/<repo-rel>.json with the repo-relative document.path — proving the hybrid routing left the committable path untouched.
• Live smoke (manual, docs/MANUAL-SMOKE-F8.md): open a file from a sibling repo → select → "Ask Claude to Edit Selection" → review proposal → accept → open a thread → reload → state restored; repeat in an untitled buffer (note the in-memory/reload caveat).

E2E are first-class plan tasks (handbook §9/§4; this app's required tier is host E2E — a VS Code extension has no browser surface or deploy stage, the F2–F7 precedent).

6.9 Failure modes, rollback & flags

• Global storage unavailable / write failure → GlobalSidecarStore degrades to in-memory + one warning (F6's exact path); authoring works for the session, reload- survival lost.
• Renamed/moved out-of-folder file → orphaned artifact (old hash stranded, new file empty); self-describing (the new doc simply has no threads) and recoverable by re-authoring; a future re-key gesture is the additive fix (§9).
• Untitled saved mid-session → in-memory artifact dropped (no v1 migration); the saved file starts fresh under its new file: home (repo sidecar if in-folder, global if not). Documented; deferred migration (§9).
• Crash between a seam landing and a global-sidecar write → the stored global artifact is one update behind (the same one-landing-stale window F6's baseline has); the next edit/save reconciles. The update write is synchronous in the handler to keep the window minimal (the CoauthorStore precedent).
• No feature flag: F8 only widens what is accepted and adds an alternative storage path; in-workspace behavior is byte-for-byte unchanged (INV-2), so rollback is reverting the PR with zero data migration — in-workspace sidecars are untouched and global-storage artifacts are disposable by design.

---

7. Delivery Plan

7.1 Approach / strategy

One planning-and-executing session (F8 = #25), plan written just-in-time from this spec — the F2–F7 precedent. The work is a focused refactor (introduce one seam, route through it, widen one gate) plus one new store and its tests; no contract or schema change.

7.2 Slicing plan

• SLICE-1 SidecarStore interface + GlobalSidecarStore (vscode-free, mirroring BaselineStore; in-memory untitled branch; no-op consumeSelfWrite) + SidecarRouter (keyOf + per-document routing) + isAuthorable. Unit tests (round-trip, routing, keyOf, predicate).
• SLICE-2 Re-point the three controllers (threadController, attributionController, proposalController) and VersionGuard onto SidecarStore (the router); replace the isInRoot/isTracked gate with isAuthorable; key via store.keyOf. Construct the router in extension.ts from CoauthorStore + GlobalSidecarStore + root.
• SLICE-3 Widen selectionRejection (drop the file-scheme/under-root rejections for !isAuthorable); move the authoring commands to the workspace-independent registration path (F6 #19 precedent) so they are live folder-less.
• SLICE-4 Host E2E per §6.8 (out-of-workspace file + untitled + in-workspace byte-for-byte regression) + docs/MANUAL-SMOKE-F8.md + README note on the hybrid model and F5 non-shareability.

7.3 Rollout / launch plan

Still non-shippable (no marketplace publish). "Done" = issue #25 acceptance met: "Ask Claude to Edit Selection" (and threads/attribution) succeed on a saved out-of-folder file and an untitled buffer; in-workspace files byte-for-byte unchanged (INV-2); out-of-workspace/untitled artifacts persist in global storage keyed by URI hash (in-memory for untitled); re-anchoring + reload restore for a global-storage doc; unit + host E2E green; live smoke performed once on this machine.

7.4 Risks & mitigations

Risk	Mitigation
Routing refactor regresses the in-workspace path (INV-2)	The E2E byte-for-byte regression (§6.8) asserts the .threads/ path, filename, and document.path are unchanged; CoauthorStore itself is not modified (only its consumers re-point to the interface it already satisfies)
Operator surprised that untitled state is lost on reload/save	Documented in §6.7/§9 and MANUAL-SMOKE-F8.md; consistent with F6/F7 untitled behavior the operator already knows; migration is the named follow-up
Operator surprised an out-of-folder thread vanished after a rename	The orphaning caveat is stated (INV-24 commentary, §6.5); the new file shows an honest empty state; re-key gesture is the additive fix (§9)
Someone expects to cross-rung-share an out-of-folder artifact	INV-25 states non-shareability as contract; the README note makes it explicit; the in-repo path (the only shareable one) is unchanged
A read-only scheme (git:, output:) slips through as authorable	isAuthorable is an allowlist (scheme ∈ {file, untitled}); unit-tested to reject others

---

8. Traceability matrix

Requirement (issue #25 acceptance)	Use case	Design	Slice
Authoring succeeds on out-of-folder file + untitled buffer	PUC-1/2	§6.2 (isAuthorable + router), §6.4	SLICE-2/3
In-workspace files byte-for-byte unchanged (INV-2)	PUC-3	INV-24, §6.5, §6.8 regression	SLICE-2
Out-of-workspace/untitled persist in global storage by URI hash	PUC-1/2	INV-24, §6.3 (GlobalSidecarStore)	SLICE-1
Re-anchoring + reload restore for a global-storage doc	PUC-4	§6.5 (Anchorer unchanged)	SLICE-1/4
One storage abstraction shared by the three controllers	—	§6.2 (SidecarStore + router)	SLICE-1/2
Accurate scope in the editSelection guard	PUC-5	§6.4 (selectionRejection widen)	SLICE-3
F5 non-shareability of global artifacts stated	—	INV-25, §6.7	SLICE-4 (docs)
URI-rename orphaning caveat called out	PUC-5	§6.5/§6.7/§9	SLICE-4 (docs)
Host E2E coverage, no LLM	—	§6.8	SLICE-1/4
Artifact shape / SCHEMA_VERSION / cross-rung format unchanged	—	INV-24/25, §6.3	all

9. Open Questions & Decisions log

• RESOLVED (this session — the forks routed by #25): (a) persistence model = hybrid — in-workspace repo .threads/ sidecar (INV-2, byte-for-byte) · out-of-workspace file: + untitled: global-storage sidecar keyed by sha256(uri) (INV-19/24); uniform global storage rejected (loses committable threads — INV-2); (b) abstraction shape = SidecarStore interface + SidecarRouter façade, two impls (existing CoauthorStore, new GlobalSidecarStore mirroring BaselineStore), selected by #24's isUnderRoot; (c) document key = repo-relative path in-workspace · URI string otherwise, the one identity (keyOf) used as store key, document.path, and in-memory state; (d) F5 cross-rung = global artifacts are not shareable, by design (INV-25) — not a committed file, never seen by mergeArtifacts; (e) URI-rename orphaning = accepted & documented (inherent to URI-hash keying; F6 baselines already have it); (f) untitled = in-memory only (F6 degrade), no on-save migration in v1; (g) gate = shared isAuthorable (scheme ∈ file/untitled); isUnderRoot demoted to a routing input; authoring commands registered folder-independently.
• OPEN → later (additive, on the same abstraction):
  • untitled→saved artifact migration — carry the in-memory artifact to the new file: sidecar on save (needs old-URI→new-URI transfer; edge cases when the saved location is in- vs out-of-folder).
  • re-key / recover gesture — a command to re-bind an orphaned global artifact to a renamed file's new URI hash (or, more generally, a "import sidecar from URI" pick).
  • auto-rename tracking for out-of-folder files (no reliable VS Code signal today — onDidRenameFiles is workspace-only).
• Deferred decisions (autonomous-mode calls logged for the operator): the no-migration-on-save choice for untitled buffers and the demotion of isUnderRoot from gate to routing input were decided without operator input; both are cheap to revisit and are the least-churn, F6-consistent answers. Surface at review if either should change before implementation.

10. Glossary & References

• Hybrid persistence — the F8 model: the same Artifact is written to a committable repo .threads/ sidecar for in-workspace docs and to a global-storage sidecar for out-of-workspace/untitled docs (INV-24). Document key — the single per-document identity (SidecarRouter.keyOf): repo-relative path in-workspace, the URI string otherwise; serves as store key, artifact.document.path, and in-memory state key. SidecarStore — the interface the three authoring controllers depend on; implementations: CoauthorStore (repo) and GlobalSidecarStore (global). Orphaning — the loss of binding between a global artifact and its file when the file's URI changes (rename/move), because the key is sha256(uri). Single-rung — an artifact never shared across rungs (INV-25), because it is not a committed file.
• Feature #25 (F8) · Epic #1 (closed) · capture vscode-cowriting-plugin-0023 · F6 #17/#19 (PR #18/#20, the global-storage-by-URI-hash precedent) · #24 (PR #24, the isUnderRoot guard fix) · F5 #14 (PR #15) · F4 #12 (PR #13) · F3 #6 (PR #7) · F2 #4 (PR #5) · parent specs coauthoring-inner-loop.md, coauthoring-attribution.md, coauthoring-propose-accept.md, coauthoring-cross-rung-format.md, coauthoring-sidecar-contract.md, coauthoring-diff-view.md · lineage ben.stull/rfc-app#48.