From 9641f7d2c8255080cc44361316cca63744fac5f0 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 15:15:08 +0800
Subject: [PATCH 01/20] docs(storage): respecify phase 4.6 around the four
 dispositions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first Phase 4.6 attempt is withdrawn. It moved application reads onto
the portable ports correctly, but sorted every residual per-Space file into
one disposition — Disk-only, with the HTTP API as the single route out — and
fenced the Disk tree behind a free function rather than the Space it
describes. Review found that right for the families that are genuinely about
a filesystem and wrong for the rest: worker state, the memory body,
skill.md, and upload scratch want a port, and an API hop in front of
unportable state does not make it portable.

Carry the reworked proposal onto a fresh base and respecify the phase around
it. §6.4 keeps its settled direction — one `space(canvasId)` handle joining
both ports above them, four dispositions, and an extension substrate that
hands out a connection point rather than a data API. §12.6 becomes one
planned phase that builds all of it, absorbing what the withdrawn attempt
would have deferred to a 4.7, so everything the second structured adapter
needs is in place before SQLite arrives.

Phase references throughout now describe the attempt as withdrawn rather
than landed, and §12.5.6 goes back to naming `spaceDirectory()`, which is
what Phase 4.5 actually shipped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/proposals/multi-backend-storage.md | 644 +++++++++++++++++++++++-
 1 file changed, 629 insertions(+), 15 deletions(-)

diff --git a/docs/proposals/multi-backend-storage.md b/docs/proposals/multi-backend-storage.md
index b787dd494..454f9a6a6 100644
--- a/docs/proposals/multi-backend-storage.md
+++ b/docs/proposals/multi-backend-storage.md
@@ -1,15 +1,15 @@
 # Multi-Backend Storage
 
-Status: Phases 1–4 implemented
-Last updated: 2026-08-11
+Status: Phases 1–4.5 implemented; Phase 4.6 specified in §6.4 and §12.6
+Last updated: 2026-08-19
 
 > **Scope and decision confidence.** This proposal records the two-port
 > `StructuredStore` / `BlobStore` split and their target backend families as
 > the settled direction. The Blob contract, the structured module/repository
 > shape, the Space catalogue/lifecycle, async node repository, and minimal ordered
 > writer are accepted. Exact schemas, stronger transactional APIs, migration
-> mechanics, backend-selection scope, virtual filesystem behavior, agent
-> workspace materialization, and write-back are still design space. Remaining
+> mechanics, backend-selection scope, and virtual-filesystem and agent
+> write-back semantics are still design space. Remaining
 > candidate interfaces below are discussion aids, not implementation
 > instructions.
 >
@@ -47,11 +47,28 @@ Last updated: 2026-08-11
 > Corrections made during implementation and adversarial
 > review are recorded in place, including the CAS race ordering (§12.2.5),
 > log-family interface segregation (§12.2.6), and retained-handle Workspace
-> guards (§12.2.4). Remaining Disk-only read and physical capabilities still
-> keep non-Disk profiles unselectable. No SQLite, Postgres, or Azure adapter
-> exists. §12 is the
+> guards (§12.2.4). Phase 4.5 moved storage-owned Disk layout behind the
+> storage boundary in PR #93 and is the newest implemented phase. Phase 4.6 is
+> specified in §6.4 and §12.6 and is **not implemented**: it is the whole
+> remaining bridge between the portable contracts and a second structured
+> adapter — application reads off `CanvasStore`, one `space(canvasId)` handle,
+> a disposition for every residual per-Space file, and a Workspace mount
+> lifecycle. No SQLite, Postgres, or Azure adapter exists on `main`. §12 is the
 > authoritative phase plan; the decision table in §2 marks what each phase
 > has actually settled.
+>
+> **Revision, 2026-08-19.** A first attempt at Phase 4.6 was written and
+> withdrawn without merging. It collapsed every consumer that needs a real
+> directory into a single residual "Space-file" capability and gave them one
+> route out: stop needing a tree and reach a Space over the HTTP API. Review
+> found that route correct for some of those consumers and wrong for the rest
+> — several of them want a _port_, not an API — and found the capability
+> fenced off behind a free function rather than reachable from the Space it
+> describes. §6.4 replaces the one capability with four dispositions and
+> states the composition-layer Space handle that joins both ports; §12.6 is
+> respecified around them and now carries the work the withdrawn attempt would
+> have split across two phases. Nothing implemented is affected: the attempt
+> reached no branch that Phase 4.6 builds on.
 
 ---
 
@@ -91,7 +108,10 @@ built above these ports, but its form is intentionally unresolved here.
 | Blob key, staging, deletion, and GC semantics          | Proposed / open           | Names are the existing `<artifactId><ext>` keys; `deleteAll()` covers Space destruction. Staging, reference counting, and GC remain undesigned. Per-key deletion stays out of the public port, but the absence of any cleanup path is what makes atomic replace mandatory (§6.2).                                                                                                          |
 | Space-handle identity and caching                      | **Corrected** (P1)        | `space(id)` returning a stable handle is bounded by the LRU behind it, not guaranteed. In-memory tombstones and the filename index are therefore adapter-local caches, never durable state (§12.1.1, §12.2.4).                                                                                                                                                                             |
 | Backend selection scope                                | Open                      | Process-global today because the profile is read from env. Per-Workspace or per-Space selection has not been fixed.                                                                                                                                                                                                                                                                        |
-| Logical filesystem view                                | Open                      | A possible `SpaceFileView` above both stores; name and contract are not accepted yet.                                                                                                                                                                                                                                                                                                      |
+| Unified per-Space handle                               | **Settled direction**     | One composition-layer `space(canvasId)` vends every storage capability for one Space: its structured parts, its blob scope, and any backend-specific extras. The two ports stay independent and are joined above them, never inside one (§6.4.1).                                                                                                                                          |
+| Storage for owners outside this port                   | **Settled direction**     | The Space handle vends an isolated _substrate_ per namespace — a directory, a table prefix, a schema — and the owner brings its own store implementation and SQL. Storage owns namespace isolation and lifecycle only, and never sees the data (§6.4.4).                                                                                                                                   |
+| Disposition of residual per-Space files                | **Settled direction**     | Four outcomes, not one: Disk-only and unimplemented elsewhere; portable capability with a per-backend implementation; a structured record; or a blob. The withdrawn Phase 4.6 attempt applied the first of the four to all of them; §6.4.3 assigns each family individually and §12.6 builds them (§6.4.2).                                                                                |
+| Logical filesystem view                                | Open                      | A possible `SpaceFileView` above both stores; name and contract are not accepted yet. §6.4 narrows what such a view would have to synthesize — named files become blobs — without deciding to build it.                                                                                                                                                                                    |
 | Real agent workspace                                   | Open                      | Materialized directory, OS mount, protocol-only access, or a combination remain under evaluation.                                                                                                                                                                                                                                                                                          |
 | Agent-authored filesystem write-back                   | Open                      | Read-only projection, explicit checkout/commit, and live bidirectional sync are alternatives, not decisions.                                                                                                                                                                                                                                                                               |
 
@@ -204,6 +224,11 @@ remains the sole owner of its existing `ThreadStore`, `EventLogStore`, and
 backend family and inject matching adapters into both domains, but it must not
 move L2 persistence ownership back into `CanvasStore`.
 
+The one thing this port offers another domain is a _connection point_
+(§6.4.4): an isolated substrate per namespace — a directory, a table prefix, a
+schema — that the owner builds its own store on. Storage never sees the data,
+so no ownership moves and no schema is shared.
+
 Every current Canvas structured port is asynchronous so a synchronous Disk or
 SQLite implementation does not constrain Postgres or another remote adapter.
 The corresponding migration for Agenetes ports that are synchronous today
@@ -316,6 +341,274 @@ rejects kinds that are named but not implemented, so an unsupported profile
 fails at startup with an actionable message rather than nondeterministically
 while serving data.
 
+### 6.4 One Space handle, four dispositions — revised direction
+
+Phases 1–4.5 established the two ports and pulled storage-owned layout inside
+the boundary. What no phase has settled is the residue: the per-Space state
+that is still a file because it always was one, and the fact that reaching a
+Space means calling two unrelated functions. This section settles both and
+supersedes the single "Space materialization" framing of §12.5.4. Phase 4.6
+(§12.6) builds what it settles.
+
+Confidence: §6.4.1, the four-outcome test in §6.4.2, the assignments in
+§6.4.3, and the opaque-state member in §6.4.4 are a **settled direction**.
+What remains open is scheduling — which adapter pays for which move (§12.6,
+§12.7) — and the concrete member names, which are still discussion aids.
+
+#### 6.4.1 One handle per Space
+
+A Space's durable state spans both ports — its record and nodes are
+structured, its files are bytes — so the application should reach all of it
+through one object, from one function, on the object that already holds both
+ports:
+
+```ts
+interface Storage {
+  readonly profile: StorageProfile;
+  readonly workspacePath: string;
+  readonly structured: StructuredStore;
+  readonly blobs: BlobStore;
+  space(canvasId: string): Space;
+}
+```
+
+`Storage` is the composition root's own type — it is what `getStorage()`
+already returns, and it is the only object in the process that holds both
+ports, so it is where the two are allowed to meet. The barrel exports a free
+`space(canvasId)` that is exactly `getStorage().space(canvasId)`, matching how
+`canvasBlobs()` is already called; that is an ergonomic shorthand for the same
+method, not a second design.
+
+`Space` is a **composition-layer facade, not a port type**.
+`StructuredStore.space()` keeps returning the structured-only `SpaceHandle`,
+`BlobStore.scope()` keeps returning a `BlobScope`, and neither port imports the
+other (§6.3). They are joined in the layer that already owns every cross-store
+rule: the blob-put precondition ("bytes only for a Space whose record exists")
+and the blob-first delete saga.
+
+The join cannot move down into a port, for three separate reasons:
+
+- the two axes are configured independently, so a `SpaceHandle` that vended
+  blobs would oblige the Disk structured adapter to construct an Azure blob
+  scope;
+- deletion ordering deliberately keeps remote blob I/O outside any database
+  transaction (§6.1); a handle owning both would move that ordering inside an
+  adapter;
+- `BlobScopeRef` is a union whose only member is `canvas` today. Workspace
+  assets and agent scratch have no Space, and a blob store reachable only
+  through a Space handle could not serve them.
+
+What is wrong today is therefore only the spelling.
+`getStructuredStore().space(id)` and `canvasBlobs(id)` are two entry points —
+37 and 21 production call sites — that never say they address one Space.
+
+**Backend-specific members hang off the same handle.** A capability only some
+backends implement is named for the backend that has it and typed by its
+absence (`null`), not hidden behind a parallel free function and not present as
+a stub that throws:
+
+```ts
+interface Space {
+  readonly canvasId: string;
+  read(): Promise<CanvasFile | null>;
+  write(input: SpaceWriteInput): Promise<SpaceWriteResult>;
+  readonly nodes: SpaceNodes;
+  readonly changes: SpaceChanges;
+  readonly tasks: SpaceTasks;
+  readonly events: SpaceEvents;
+  extension(namespace: string): SpaceSubstrate; // §6.4.4
+  readonly blobs: BlobScope;
+  /** Disk's directory for this Space. `null` on every other backend. */
+  readonly diskTree: DiskSpaceTree | null;
+}
+```
+
+A caller branching on `null` is told the truth once; a caller that must
+remember a second import is being asked to know the storage module's internal
+topology. The withdrawn Phase 4.6 attempt exposed the Disk tree as a standalone
+`diskSpaceTree()` free function to keep an unportable surface from looking
+portable; the fence that actually does that work is the name and the enumerated
+consumer list, and both survive the move onto the handle.
+
+#### 6.4.2 The disposition test
+
+§12.5.2 asked of a _symbol_: is it still useful, unchanged, when the structured
+backend becomes SQLite? That question sorted `paths.ts`. Asked of a _consumer_
+it sorts the residual filesystem population — and it returns four answers, not
+one:
+
+| Disposition                     | The question under SQLite                         | Consequence                                                             |
+| ------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
+| **A. Disk-only**                | Meaningless — the feature is _about_ a filesystem | Not implemented off Disk. The feature is **unavailable**, not emulated. |
+| **B. Portable, re-implemented** | Survives; only the mechanism dies                 | A declared capability every backend answers in its own way.             |
+| **C. Structured record**        | It was a record wearing a file's clothes          | Moves to `StructuredStore`.                                             |
+| **D. Blob**                     | It is genuinely a named file                      | Moves to `BlobStore`.                                                   |
+
+The withdrawn Phase 4.6 attempt assigned **A** to all of them and offered one
+route out: features stop needing a tree, and an agent reaches a Space over
+Huabu's HTTP API. That is right for A and wrong for the other three. B, C, and
+D do not need the HTTP API — they need a port, and routing them through an API
+instead would leave the same state unportable behind a network hop.
+
+An outcome of A is an acceptable, stated product limitation, not debt. It
+belongs in a capability matrix that `validateStorageProfile()` can consult,
+alongside the existing rule that an unimplemented kind fails at startup.
+
+**A is the default answer, and the cheap one.** B, C, and D each cost a port
+change, a contract suite, and a migration; A costs a row in the matrix. A
+family earns B, C, or D by a product need that survives being told plainly
+"this is not available on that backend" — not by being technically portable.
+Where the two are close, take A and say so. A workaround that makes a feature
+_nearly_ work on a backend is worse than its absence: it has to be built,
+tested, and explained, and it hides the limitation instead of stating it.
+
+**Nothing here is built before a backend needs it.** Assigning a disposition
+fixes the direction; it does not schedule the work. B and the open parts of C
+and D land with the adapter that first requires them, so the second backend
+pays for its own portability rather than Disk paying in advance for a
+requirement nobody has stated. The exception is a move that simplifies Disk on
+its own merits — deleting an ad-hoc file format in favour of a record the Space
+handle already writes — which is worth doing whenever it comes up.
+
+#### 6.4.3 Inventory
+
+Every consumer that reaches a Space as a filesystem tree today, with its
+disposition. Every assignment is settled; what is deferred is _when_ each is
+built, not _where_ it goes — §12.6 builds most of them (§6.4.2, §12.7).
+
+| Consumer                                                   | What it does today                                             | Disposition                                                                                                                                                                                                                                 |
+| ---------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /:id/export` — Space bundle                           | `archiver.glob('**/*', {cwd: spaceDir, dot: true})`            | **A**, accepted. A _portable_ export generated from records plus reachable blob references is a separate later design (§11); the current bundle is a Disk projection.                                                                       |
+| `POST /import` — Space bundle                              | Unzip into a staging dir, rename into place                    | **A**, accepted. Same pairing as export.                                                                                                                                                                                                    |
+| `POST /:id/reveal-nodes`                                   | `openInFileManager(nodesDir)`                                  | **A**, accepted. The feature _is_ "show me this in Finder".                                                                                                                                                                                 |
+| Built-in `read`/`write`/`glob`/`grep` tools (`fs-sandbox`) | Space directory as the sandbox root                            | **A**, accepted. Off Disk the first-party agent uses RFS/HTTP, which is what external agents already use (§9).                                                                                                                              |
+| `import-node-src` artifact-ref classification              | `path.relative(spaceDir, abs)`                                 | **A**, accepted — and it should ask `fs-sandbox` for its root, not storage. Not a storage consumer at all.                                                                                                                                  |
+| Windows directory-handle coordination                      | `registerHandleOwner` around `fs.watch` handles                | **A**, accepted. Exists so a directory rename can succeed; no directory, no problem.                                                                                                                                                        |
+| External-note observation and claim                        | `fs.watch` on `nodes/`, then read + unlink                     | **A** as a product feature; **B** for the notification underneath it. Nothing is built until a second backend exists — see below.                                                                                                           |
+| RFS path → node resolution                                 | `nodeIdForPath('nodes/Foo.md')` inverts Disk's filename        | **B**, deferred. Every backend can mint `nodes/<label>.md` names from records; Disk keeps inverting the real filename because the file is really there. Until a second backend exists, RFS's file plane is Disk's.                          |
+| Memory-worker state (`.memory/state.json`)                 | `atomicWriteJson` of `{counter, lastAnalyzedAt, cursor}`       | **C**, accepted. Per-Space bookkeeping with no reason to be a file; a small store on the §6.4.4 substrate.                                                                                                                                  |
+| Space-existence guard (`existsSync(spaceDir)`)             | Resurrection guard in the memory trigger                       | **C**, accepted — and it disappears rather than moving. The guard exists because an ad-hoc file write can recreate a deleted Space's directory; a structured record write cannot, because the port refuses a write to a Space that is gone. |
+| ACP session state (`.history/acp-sessions.json`)           | Handed to the ACP driver as `storage.root`                     | **C**, accepted. Storage supplies an isolated substrate under a namespace (§6.4.4); Agenetes keeps its own ports, its own store, and its own schema (§6.1).                                                                                 |
+| Chat prompt log (`.history/chat/<thread>.prompt.log`)      | Written under `HUABU_DEBUG_PROMPT`, never read by the app      | **C**, accepted. One namespace on the §6.4.4 substrate, one entry per thread.                                                                                                                                                               |
+| Memory body (`.memory/space.md`)                           | AI-private Markdown an agent reads and rewrites                | **D**, accepted. A document the agent edits as a file.                                                                                                                                                                                      |
+| `skill.md` (per-Space RFS access guide)                    | User-authored override read at the Space root                  | **D**, accepted. A future `AGENTS.md` is the same case.                                                                                                                                                                                     |
+| Upload scratch (`.upload/`)                                | RFS upload and interactive-view write here through the sandbox | **D**, accepted. Its own scope kind, so retention can differ from artifacts later without moving the bytes again.                                                                                                                           |
+
+Three consequences worth stating separately.
+
+**B is where "watch" belongs — later.** Change notification is not a
+filesystem primitive a database lacks; it is a database primitive a filesystem
+happens to also have (`fs.watch`, a SQLite update hook, Postgres
+`LISTEN`/`NOTIFY`). That is why the disposition is B rather than A.
+
+The product behaviour layered on it today does _not_ generalize: external-note
+discovery watches for documents that arrived **without going through the
+application**, and a database backend has no such arrival path unless someone
+writes to the store out of band. Rather than invent one, external-note
+discovery is simply unavailable off Disk, and the notification capability is
+declared only when a second backend has a consumer for it. Building a portable
+watch port now would buy nothing — the one caller is the Disk-only feature.
+
+**D changes what `BlobStore` is for, minimally.** §6.2 says blobs are "opaque
+bytes, not application records", with names that are the existing
+`<artifactId><ext>` keys. Named user-authored documents — `skill.md`, a future
+`AGENTS.md`, the memory body — are still opaque to storage, so the contract
+holds unchanged. One detail needs a decision and it has a cheap answer: the
+Disk adapter maps the single canvas scope onto `.artifacts/`, so a blob named
+`skill.md` would land in a hidden directory rather than at the Space root where
+a user authors it. Add one `BlobScopeRef` kind per user-visible area. That is a
+union member and a directory constant per adapter; it keeps the Disk layout a
+user sees unchanged, and it avoids hierarchical names, which §7.1 excluded for
+every backend and which would be the expensive answer to the same problem.
+
+Rename and per-key delete stay **unsupported**, as they are today. A human will
+eventually want to remove a `skill.md`, and the honest answer until some
+product operation actually requires it is that storage does not offer it —
+overwriting is the supported edit. Adding per-key deletion drags in the
+reference-counting and GC design §14 already parks, which is a large bill for a
+small convenience.
+
+#### 6.4.4 The extension point is a connection, not a data API
+
+Disposition C must not grow `StructuredStore` one member per feature —
+`memory`, `acpSessions`, `promptLogs` — obliging every future backend to model
+data it has no stake in. §12.5.7 rejected exactly that when it declined a
+`SpaceChats.list()` port.
+
+A namespaced opaque key/value member on the port is the obvious repair and is
+also wrong, for a reason worth recording: it fixes one access shape —
+whole-value rewrite, no queries, no indexes — for every owner, forever. An
+owner with real query needs then encodes its own index inside an opaque value,
+which is the two-authorities hazard reappearing one level down. The sibling
+`../octostaff` bubble runtime shows what the owners actually look like: each
+extension ships its own `repository-contract.ts` with `repository-memory.ts`
+and `repository-postgres.ts` beside it, and the Postgres one is constructed
+with an injected `PostgresConnection` carrying `sql` and a `schema` name.
+
+So the port exposes **the connection point and nothing else**. The owner brings
+its own store implementations and its own SQL:
+
+```ts
+/** What a namespace gets to build on. Discriminated by the live backend. */
+type SpaceSubstrate =
+  | { kind: 'disk'; directory: string }
+  | { kind: 'sqlite'; db: SqliteDatabase; tablePrefix: string }
+  | { kind: 'postgres'; sql: Sql; schema: string };
+
+interface Space {
+  /** Isolated substrate for one namespace's own store. */
+  extension(namespace: string): SpaceSubstrate;
+}
+```
+
+The namespace is the isolation token and the only thing storage validates: a
+reserved directory on Disk, a table prefix on SQLite, a schema on Postgres.
+Storage guarantees the namespace is unique and unshared. It guarantees nothing
+about what is inside, and cannot, because it never sees the data.
+
+**Storage keeps lifecycle, because only it can.** A namespace is created on
+demand and destroyed with the Space — `rm -rf` the directory, drop tables
+matching the prefix, drop the schema. That keeps `beginDelete`/`finish` whole
+without any owner registering a cleanup hook, and it is the one operation an
+owner cannot perform without knowing a layout that is not its own.
+
+**An extension supports the backends it chooses.** One that implements only
+`disk` does not load under Postgres, and that is a stated limitation rather
+than a defect — disposition A applied one level out (§6.4.2). Storage's
+contract suites cover none of this: there is no portable behaviour to assert
+about data the port cannot read.
+
+**Ownership does not move.** Agenetes keeps `ThreadStore`, `EventLogStore`, and
+`TurnStore` as its contracts (§6.1) and gains a substrate to implement them
+over, in place of a bare directory path. What §12.5.7 forbade — Huabu's ports
+learning the shape of agent-runtime data — is stronger here than under a
+key/value member: the port does not store the data, it hands over a place to
+put it.
+
+Three consequences to accept openly rather than design against:
+
+- **The backend kind is part of the extension API.** An owner written against
+  `sqlite` breaks if a deployment moves to Postgres. That is inherent in
+  letting owners write their own SQL, and the alternative is the lowest common
+  denominator this section exists to avoid.
+- **The substrate is unfenced.** A live `sql` handle can run arbitrary DDL
+  outside its schema, and a directory path is the very thing §12.5.4 pulled
+  back inside the boundary. The namespace bounds it by convention, not by
+  enforcement. Extensions are in-process code, trusted at the same level as the
+  Server; an untrusted or out-of-process extension model is not supported and is
+  not being designed here.
+- **First-party state pays the same price.** Memory-worker state is three
+  fields, and under a substrate it needs a small store per backend kind rather
+  than a `put()`. Phase 4.6 writes the Disk one directly. If a second owner
+  wants the same shape, extract a shared key/value helper **over** the
+  substrate, in `utils/` — never as a port member, because that is the design
+  this section rejected.
+
+`Namespace.storage.root` follows from this. Under bubble's pattern the driver
+is constructed with its substrate by the composition root, so the serializable
+`Namespace` carries only the scope name and never a path or a live handle —
+which is also what §14 asked for.
+
 ## 7. Contracts
 
 ### 7.1 BlobStore — normative
@@ -572,6 +865,13 @@ This would centralize path mapping and visibility rules without promising an
 OS mount. Its exact path vocabulary, search behavior, ACL model, generated
 `space.json` semantics, and write surface are open.
 
+§6.4 shrinks what such a view would have to invent without deciding to build
+it. Once named user files are blobs and node documents are structured records,
+the view synthesizes only a _path vocabulary_ over state the ports already
+hold, rather than deriving both the names and the bytes. That is also what RFS
+path resolution needs (§6.4.3, disposition B), so the two questions have
+converged even though neither is answered here.
+
 ### 10.2 Materialized agent workspace
 
 A materializer could create a real directory on the machine where Codex,
@@ -1805,6 +2105,14 @@ Consumers needing a Space's real directory ask `storage/`, so the current
 `storage → workspace/disk` edge inverts to `workspace ← storage` plus an
 explicit capability — instead of every domain reaching into a shared layout.
 
+**Superseded in part by §6.4.** The dependency direction this subsection
+settles — consumers ask `storage/` for a Space's real directory, rather than
+every domain reaching into a shared layout module — stands. What does not is
+the assumption that one declared capability serves all of them. Applying the
+disposition test to each consumer individually (§6.4.3) sends most of them to a
+port instead, and leaves the capability covering only the families that are
+genuinely about a filesystem.
+
 #### 12.5.5 Scope
 
 In:
@@ -1908,6 +2216,13 @@ not own — `legacy/canvas-store.ts` states plainly that threads and turns
 belong to the agent runtime — and would oblige every future structured backend
 to model Agenetes' turn log, which is the two-authorities hazard in §13.
 
+The extension substrate (§6.4.4) is not a reversal of this. What was rejected
+is a port that _knows the shape_ of agent-runtime data. What is offered is a
+place to put data — a directory, a table prefix, a schema — that the owner
+builds its own store on. A `list()` over chat turns is no more available
+through storage than it was before; it is Agenetes' own query against Agenetes'
+own tables.
+
 **Follow-up (open):** decide whether the memory agent should see conversation
 turns at all, and if so reinstate the digest against `agenetes.history()` —
 the call `canvas-search.ts` already uses for exactly this data. That is a
@@ -1916,17 +2231,253 @@ no working behavior moves. The `latestChatTs` field and its
 `lastSeenThreadCursor` plumbing survive the removal because they are the
 resume point such a digest would need.
 
-### 12.6 Later phases — provisional
+### 12.6 Phase 4.6 — one Space handle, backend-neutral application, and Workspace mount
+
+Phase 4.6 closes the whole application-side gap between the portable storage
+contracts and a second structured adapter. It contains no SQLite schema,
+driver, migration, or profile-selectability branch. It implements §6.4, and its
+exit criterion has two halves:
+
+- **Neutrality.** Adding another `StructuredStore` changes adapter,
+  composition, and migration code, but does not require Canvas, agent, web,
+  RFS, interactive-view, Task, or Workspace feature modules to learn that
+  backend's record layout.
+- **One handle.** Every storage capability for one Space is reached through one
+  `space(canvasId)` handle, and every family that is still a bare file is one
+  the capability matrix declares Disk-only.
+
+An earlier attempt at this phase satisfied the first half only, and reached the
+second by fencing the residual filesystem population behind a separate free
+function under a single disposition. §6.4 explains why that was one answer too
+few. This specification replaces it; nothing from the attempt is depended upon.
+
+#### 12.6.1 Portable read completion
+
+Every production structured read uses `StructuredStore`: Space topology through
+`SpaceHandle.read()`, single node content through `SpaceNodes.read()`, a named
+subset through `SpaceNodes.readMany()`, and whole-Space or incremental scans
+through `SpaceNodes.list()` / `SpaceNodes.stream()`. All of them return the
+same complete node records and opaque storage revisions; the streaming callback
+is delivery order only and promises neither query ordering nor a backend
+cursor. Search keeps its progressive metadata delivery without naming a
+filesystem scan.
+
+`readMany` exists because most readers want a handful of named nodes rather
+than the Space — a selection to describe, a neighbourhood to render, one View
+to serve. Expressing those as `list()` makes an unrelated node somewhere else
+cost the request, and it is a shape every backend serves better than a scan.
+Whole-Space reads stay on `list()` where the work genuinely is whole-Space:
+executor prestate hydration, the Space GET, the canvas outline, cross-node
+inspection.
+
+`CanvasStore` remains inside the Disk adapter and compatibility tests only. It
+is not an application service, and production module-boundary tests reject new
+or remaining feature imports. Pure Canvas context builders accept already-read
+`CanvasFile` / node-record values instead of reaching into storage themselves;
+their async adapters own repository access once per request.
+
+#### 12.6.2 One `space(canvasId)` handle
+
+`Storage` gains `space(canvasId)`, the composition-layer facade of §6.4.1,
+joining the structured handle with the Space's blob scope and any
+backend-specific members; the barrel exports a free `space(canvasId)`
+shorthand for `getStorage().space(canvasId)`, matching how `canvasBlobs()` is
+already called. `StructuredStore` and `BlobStore` keep their current interfaces
+and their independence — neither imports the other — and the facade is the only
+new type. The existing `getStructuredStore().space(id)` and `canvasBlobs(id)`
+call sites migrate to it.
+
+The residual Disk Space directory becomes `diskTree` on that handle, typed by
+its absence (`null` on every other backend) rather than reached through a
+parallel import or stubbed to throw. It is **not a port and not portable**, and
+it does not live in `ports/`: `StructuredStore` and `BlobStore` remain the whole
+portable surface. A Space directory is Disk's, and a backend that keeps Spaces
+in tables does not have one — a capability missing from a backend is an
+acceptable outcome, and the honest one. Making every backend promise a
+directory would mean fabricating one, which moves the failure somewhere less
+obvious than the refusal.
+
+The capability owns a Workspace-bound Space directory, bundle publication, the
+sidecar-to-record mapping, and directory-handle coordination. Consumers may
+interpret their own public virtual paths and the public `.huabu.zip` format,
+but cannot infer the active backend's structured record layout.
+`module-boundaries.test.ts` holds the member name and the exact consumer list,
+so the surface can only shrink, and asserts the barrel exposes nothing that
+reads as a portable path API. Because §12.6.3 relocates every consumer that is
+not disposition **A**, that list shrinks by construction rather than by
+exemption.
+
+#### 12.6.3 The four dispositions applied
+
+§6.4.3 assigns a disposition to every consumer of the Space-tree capability.
+This phase builds the assignments that pay for themselves on Disk alone and
+writes down the rest.
+
+**A — Disk-only, written down.** Bundle export and import, reveal-in-file
+manager, the built-in `read`/`write`/`glob`/`grep` tools, external-note
+discovery, and Windows directory-handle coordination stay Disk-only. They
+become entries in a capability matrix `validateStorageProfile()` can consult,
+so an operator selecting a profile learns up front which product features it
+does not offer, alongside the existing rule that an unimplemented kind fails at
+startup. Off Disk these features are **unavailable, not emulated**.
+
+**C — structured record.** Memory-worker state (`.memory/state.json`) and the
+debug chat prompt log (`.history/chat/<thread>.prompt.log`) become the first two
+namespaces on the extension substrate (§12.6.4), each with its own small Disk
+store, retiring two ad-hoc file formats. The `existsSync(spaceDir)` resurrection
+guard in the memory trigger disappears rather than moving: it exists because an
+ad-hoc file write can recreate a deleted Space's directory, and a structured
+record write cannot, because the port refuses a write to a Space that is gone.
+
+ACP session state (`.history/acp-sessions.json`) keeps disposition **C** but
+moves with phase 6: `Namespace.storage.root` is a filesystem path in the shared
+`@agenetes/protocol` contract, and replacing it with a composition-injected
+substrate is an Agenetes port change, not a storage one.
+
+**D — blob.** `skill.md`, the memory body (`.memory/space.md`), and upload
+scratch (`.upload/`) become blobs, each user-visible area getting its own
+`BlobScopeRef` kind so the Disk paths a user sees are unchanged and retention
+can diverge from artifacts later without moving bytes again. These qualify
+under §6.4.2's "simplifies Disk on its own merits" exception: each is a bare
+`readFileSync` / `writeFile` against a path the caller assembled, and the move
+retires those plus one resolver in the memory sandbox. The new machinery is a
+union member and a directory constant per area. Rename and per-key delete stay
+unsupported, as they are today.
+
+**B — deferred to the adapter that needs it.** The portable change-notification
+capability and RFS's backend-neutral path vocabulary are assigned but not
+built: change notification's only consumer today is the Disk-only external-note
+feature, and until a second backend exists RFS's file plane is Disk's. This is
+§6.4.2's rule that the second backend pays for its own portability rather than
+Disk paying in advance for a requirement nobody has stated.
+
+This phase does not choose bidirectional projection or native write-back
+semantics: external-note claim and bundle import continue to enter the
+authoritative application commands and repositories they use today, while
+unowned scratch and agent-domain files stay ordinary materialized files.
+
+#### 12.6.4 The extension substrate
+
+§6.4.4 lands as one Space-handle member with a Disk case, namespace validation,
+and destruction with the Space. The port exposes the connection point and
+nothing else — a reserved directory on Disk, a table prefix on SQLite, a schema
+on Postgres — and the owner brings its own store implementation and its own
+queries. Its contract is isolation and lifecycle only; there is no data
+behaviour to assert, because the port never sees the data.
+
+Storage keeps lifecycle because only it can: a namespace is created on demand
+and destroyed with the Space, which keeps `beginDelete()` / `finish()` whole
+without any owner registering a cleanup hook.
+
+This is not a reversal of §12.5.7's refusal to add a `SpaceChats.list()` port.
+What was rejected there is a port that knows the _shape_ of agent-runtime data;
+what is offered here is a place to put data. The first-party consumers in
+§12.6.3 are the proof that the substrate is usable without one; a shared
+key/value helper **over** the substrate may be extracted into `utils/` if a
+second owner wants the same access shape, but never as a port member.
+
+#### 12.6.5 Workspace-scoped storage lifecycle and World bootstrap
+
+Storage construction receives the resolved Workspace path. Startup may hold
+only a validated profile while free mode has no active Workspace; activating
+one stages and initializes both backend connections, asks the structured
+collection to ensure its one stable World, commits the Workspace path,
+atomically swaps the process-wide storage holder, and then closes the previous
+connections. A failed stage leaves the old Workspace and connections active.
+Graceful Server shutdown closes the mounted stores.
+
+`SpaceRepository.ensureWorld()` is the backend-neutral bootstrap hook. It
+returns the existing stable World or creates exactly one version-0 World when
+the namespace is new; an established malformed World remains an integrity
+error. Disk delegates to its existing `.world` bootstrap. The older on-disk
+preparation path may call the same idempotent Disk primitive before the mount
+while legacy migrations remain filesystem-based.
+
+#### 12.6.6 Proof and scope boundary
+
+The reusable node and Space-collection contracts cover `readMany` / list /
+stream equivalence and both branches of World bootstrap — the existing World,
+and the empty namespace a new backend meets first. The substrate's contract
+covers namespace isolation and destruction with the Space, and nothing about
+its contents.
+
+The product-level harness is `storage/testing.ts`: it mounts a real profile
+onto a temporary Workspace through the production lifecycle — prepared
+Workspace, staged connections, `ensureWorld()`, atomic swap — rather than
+swapping in a stub. `product-boundary.test.ts` runs the exit criterion against
+every profile in `PRODUCT_STORAGE_PROFILES`, naming no directory, filename, or
+`space.json`; Phase 5 adds one entry to that list and the same behaviours are
+covered for SQLite. Elsewhere, product tests replace only storage connections
+or the Disk tree; real Canvas services, serializers, repository behavior, and
+filesystem materialization inside the claimed boundary remain real.
+
+A module-boundary guard rejects production `CanvasStore` imports, and rejects
+Disk-layout imports from every production module outside `storage/` — not
+merely the workspace module. The check is import-level, so a local variable
+that happens to be called `artifactPath` is not a violation while importing
+`canvasRoot` is. Migrations are exempt (they rewrite frozen historical on-disk
+shapes); tests are exempt for the same reason they may name an adapter, and the
+shim-importer snapshots pin which ones do.
+
+One behavioural hardening rides along and is not implied by either half of the
+criterion: two Space directories carrying the same `canvasId` resolve last-wins
+today, and will raise from the directory scan. That makes a Finder-side
+duplication a loud failure of every catalogue read rather than a Space that
+silently resolves to an arbitrary copy.
+
+In scope: Canvas/agent/web/interactive-view/Task structured reads, World target
+reads, RFS node metadata, built-in file-tool node enrichment, external-note
+membership checks, the `space(canvasId)` facade and its `diskTree` member, the
+extension substrate and its first two namespaces, the disposition-D blob
+scopes, the capability matrix for the A families, storage mount/remount/close,
+World bootstrap, architecture documentation, and the shared product-level
+backend harness needed for Phase 5.
+
+Out of scope: a SQLite adapter or schema, Disk→SQLite data migration, SQLite
+profile registration, Postgres/Azure, the portable change-notification
+capability, RFS's backend-neutral path vocabulary, ACP session relocation
+(phase 6's `Namespace` change), the rest of the Agenetes persistence migration,
+the portable export format, a writable general-purpose virtual filesystem or OS
+mount, protocol or UI changes, and stronger crash/distributed transaction
+guarantees.
+
+### 12.7 Later phases — provisional
 
 5. Add one new adapter at a time — SQLite, then Postgres, then Azure Blob —
    running the same contract suites, migration fixtures, failure injection,
    and concurrency tests against each. An adapter may exist for isolated
    testing before its backend profile is selectable; profile validation keeps
    rejecting it until the required capability matrix is satisfied.
+
+   The SQLite preview branch forks from Phase 4.5, so it does not yet satisfy
+   the port it will be rebased onto. What it owes against §12.6, concretely:
+   `SpaceRepository.ensureWorld()`; `SpaceNodes.readMany` / `list` / `stream`;
+   the `sqlite` case of the extension substrate (§6.4.4); an entry in
+   `PRODUCT_STORAGE_PROFILES`, which is what runs the product-level boundary
+   suite against it; and its place in the implemented-backend and
+   selectable-backend lists.
+
+   It owes **no** Space directory and no portable materialization. A backend
+   that keeps Spaces in tables does not have a tree, and §6.4.2 makes that a
+   declared outcome rather than something to fabricate: what it owes instead is
+   an entry in the capability matrix declaring the disposition-**A** families
+   unavailable, plus whatever disposition **B** its own consumers turn out to
+   need (§6.4.3). Its existing note that SQLite stays unselectable while
+   physical Disk reads, World bootstrap, blob placement, import/export, and
+   Workspace remounting have one authority only in the Disk profile is the same
+   list §12.6 resolves — some by porting, the rest by declaring.
+
 6. Migrate the currently synchronous Agenetes persistence ports without
-   changing their persist-before-notify, sequence, and fencing semantics.
+   changing their persist-before-notify, sequence, and fencing semantics. This
+   is also where ACP session state leaves `.history/`: `Namespace` stops carrying
+   a filesystem path and carries only its scope name, while the composition root
+   injects the substrate the session store builds on (§6.4.4). The same route is
+   available to the `chat_v2` turn and event logs, which keep their own
+   contracts either way.
 7. Refactor RFS and built-in file tools only after a logical file-view contract
-   is accepted, if that option is chosen.
+   is accepted, if that option is chosen. §6.4 removes part of the reason such
+   a view would need to synthesize anything: named files are blobs, node
+   documents are structured records, and only the path vocabulary is left.
 8. Prototype native CLI access separately and decide between protocol-only,
    materialization, and mounting from measured product requirements.
 9. Design and implement backend migration/export/import only after source and
@@ -1966,6 +2517,30 @@ resume point such a digest would need.
   export/import.
 - A local projection may expose private memory/history or host paths to an
   external agent unless visibility is capability-scoped.
+- A composition-layer Space facade that vends both ports is one import away
+  from becoming the place cross-store invariants accumulate silently. Every
+  rule it enforces has to be stated as a rule, or the facade becomes a third
+  authority with no contract suite of its own (§6.4.1).
+- Declaring a family Disk-only (§6.4.2, disposition A) is honest but is also
+  the cheapest answer available at any moment. Without a capability matrix an
+  operator can read before selecting a profile, "unavailable" degrades from a
+  stated product limitation into a surprise at first use.
+- Moving user-authored files into `BlobStore` (disposition D) puts documents a
+  human edits behind a port with no rename and no per-key delete — omissions
+  sized for artifacts nobody edits by hand (§6.2, §7.1). §6.4.3 keeps them
+  unsupported deliberately; the risk is that a product requirement for
+  "delete my skill.md" arrives and reopens the GC design §14 parks.
+- Declaring dispositions without building them (§6.4.2) leaves the direction on
+  paper, where it can quietly stop matching the code. The capability matrix is
+  the mitigation only if a profile is actually validated against it.
+- The extension substrate (§6.4.4) hands out a live SQL handle and a real
+  directory path. A namespace bounds an owner by convention; nothing stops DDL
+  outside its schema, a long-held transaction, or a write into a sibling
+  directory. This is the deliberate cost of letting owners write their own SQL,
+  and it makes every extension trusted Server code.
+- The substrate makes the backend kind part of the extension API, so a profile
+  change can break owners that a storage contract suite will never exercise —
+  by construction, since the port cannot read their data.
 
 ## 14. Open questions
 
@@ -2021,7 +2596,21 @@ resume point such a digest would need.
   changing their persist-before-notify, sequence, and fencing semantics?
 - Where do user memory, Space memory, memory-worker state, chat digest, and
   user-authored skills belong? The analyzer's Space record, action-event, and
-  intent inputs moved in P3; these physical files did not.
+  intent inputs moved in P3; these physical files did not. §6.4.3 answers the
+  per-Space half — worker state is a structured record, the memory body is a
+  blob — and leaves the Workspace-scoped ones (`setting/user.md`, user skills)
+  untouched, because a Workspace is not a Space and no port scopes to it yet.
+- Does an extension namespace need an owner registry, or is a string convention
+  (`huabu.memory`, `agenetes.acp`) enough? A registry buys collision detection
+  and a place to hang the supported-backend list; a convention buys nothing to
+  maintain.
+- Is the substrate per Space, per Workspace, or both? Every consumer today is
+  per Space, so that is what §6.4.4 defines. A Workspace-scoped extension —
+  bubble's schedules are deployment-scoped, not per-conversation — is the same
+  idea one level up and is not designed here.
+- Who runs an extension's schema migrations, and when? Storage creates and
+  destroys the namespace but knows nothing inside it, so an owner arriving at a
+  populated namespace it wrote a previous version of has no hook to migrate on.
 
 ### Blob storage
 
@@ -2031,14 +2620,23 @@ resume point such a digest would need.
   bypasses `sendBlob` entirely — which means `put()` grows an options
   parameter (§7.1).
 - Should any scope kind ever need hierarchical names? The contract currently
-  collapses names to a single segment for every backend (§7.1).
+  collapses names to a single segment for every backend (§7.1). §6.4.3 proposes
+  answering "no" and adding a `BlobScopeRef` kind per user-visible area
+  instead, so `skill.md`, the memory body, artifacts, and upload scratch stay
+  where a user sees them today without the port learning paths.
+- Do user-authored blobs need rename and per-key delete? Answered "not until a
+  product operation requires it" (§6.4.3): overwriting is the supported edit,
+  because per-key deletion reopens reference counting and GC. Revisit if a
+  product surface offers deleting one.
 - Does `health()` need a failure mode? It cannot currently report one, and the
   contract suite asserts success, so an unhealthy backend fails the suite
   rather than reporting itself unhealthy.
 - Where do staging state, orphan detection, reference counts, retention, and GC
   live?
 - Is an upload scratch area durable BlobStore state, leased temporary state, or
-  agent-workspace state?
+  agent-workspace state? Answered: durable blob state under its own scope kind
+  (§6.4.3), which leaves retention free to diverge from artifacts later without
+  relocating bytes.
 - How are encryption, credentials, tenancy prefixes, and Azure container
   lifecycle configured?
 
@@ -2072,9 +2670,25 @@ resume point such a digest would need.
 - How is a stable directory refreshed across a long-lived ACP session?
 - How do rename, delete, duplicate IDs, filename collisions, and conflict files
   map back to domain mutations?
-- Does external-note discovery remain a Disk-only optional capability?
 - Is an OS mount justified on every supported desktop platform?
 
+Settled by §6.4, recorded here because this section asked them:
+
+- **Does external-note discovery remain a Disk-only optional capability?** Yes.
+  It watches for documents that arrived without going through the application,
+  and no database backend has such an arrival path (§6.4.3).
+- **Are the built-in file tools, reveal, and bundle export/import portable?**
+  No. They are Disk-only and declared as such, rather than emulated over a
+  synthesized tree. Off Disk the first-party agent uses RFS/HTTP, which is
+  already how external agents reach a Space (§9).
+
+- **Where do the ACP sessions, memory-worker state, and the debug prompt log
+  live?** All three become structured state on an isolated substrate under
+  their own namespace (§6.4.4). Storage owns namespace isolation and lifecycle;
+  each owner brings its own store.
+- **Is upload scratch durable blob state?** Yes, under its own blob scope kind,
+  so retention can diverge from artifacts later without relocating bytes.
+
 ## 15. Validation criteria for a later implementation
 
 Before a new backend is production-ready:

From 470437a478aa0efdac6641b8fe5b269fa8b923f7 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 15:25:05 +0800
Subject: [PATCH 02/20] feat(storage): complete the portable node read surface
 and World bootstrap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`SpaceNodes` had one read — by id — so every reader wanting more than one
node had to go around the port to the legacy Disk store. Add the three
shapes the application actually asks for: `readMany` for a named selection,
`list` for work that genuinely spans the Space, and `stream` for a reader
that can show partial results while the rest arrives.

`readMany` is the one that matters for cost. Most readers want a handful of
named nodes — a selection to describe, a neighbourhood to render, one View
to serve — and expressing those as a whole-Space scan makes an unrelated
node somewhere else part of the bill. Disk resolves each id through the same
strict read `read()` uses, so a selection sees exactly what reading each id
would, including the index rebuild that finds an externally renamed sidecar.

`SpaceRepository.ensureWorld()` is the backend-neutral bootstrap hook. Every
backend meets an empty namespace the first time it is mounted, and a
Workspace with no World has no Portal target, so ensuring one cannot stay a
Disk step run before the store exists. It delegates to the same idempotent
Disk primitive Workspace preparation calls — one writer for one file, since
the legacy preparation path still runs before the mount.

The node contract now asserts the four read shapes never disagree about a
node: an adapter whose scan parsed more leniently than its single read, or
minted a different revision, would pass a suite written against one shape
alone. The Space-collection contract covers both bootstrap branches, which
needs a harness that can open a namespace nobody has mounted yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../modules/canvas/write-coordinator.test.ts  | 20 ++++
 .../storage/backends/disk/space-nodes.ts      | 48 +++++++++
 .../backends/disk/space-repository.test.ts    | 11 +++
 .../storage/backends/disk/space-repository.ts | 22 +++++
 apps/server/src/modules/storage/index.ts      |  1 +
 .../ports/contracts/space-nodes.contract.ts   | 98 +++++++++++++++++++
 .../contracts/space-repository.contract.ts    | 57 +++++++++++
 .../src/modules/storage/ports/structured.ts   | 63 ++++++++++++
 8 files changed, 320 insertions(+)

diff --git a/apps/server/src/modules/canvas/write-coordinator.test.ts b/apps/server/src/modules/canvas/write-coordinator.test.ts
index a720b8a3a..1b9960f80 100644
--- a/apps/server/src/modules/canvas/write-coordinator.test.ts
+++ b/apps/server/src/modules/canvas/write-coordinator.test.ts
@@ -33,6 +33,26 @@ function fakeRepository(canvasId = 'c1') {
       if (revision === null) throw new Error('test storage token is missing');
       return { record, revision };
     },
+    // This fake holds one node, so the collection reads are the same record
+    // under its own id. `updateNode` never calls them; they exist because the
+    // port has them.
+    async readMany(nodeIds): Promise<Map<string, NodeSnapshot>> {
+      const snapshot = await nodes.read('');
+      return snapshot !== null && nodeIds.includes(snapshot.record.nodeId)
+        ? new Map([[snapshot.record.nodeId, snapshot]])
+        : new Map();
+    },
+    async list(): Promise<Map<string, NodeSnapshot>> {
+      const snapshot = await nodes.read('');
+      return snapshot === null
+        ? new Map()
+        : new Map([[snapshot.record.nodeId, snapshot]]);
+    },
+    async stream(onNode): Promise<Map<string, NodeSnapshot>> {
+      const all = await nodes.list();
+      for (const snapshot of all.values()) onNode(snapshot);
+      return all;
+    },
     async put(input) {
       if (suppressed) return { ok: false, reason: 'write-suppressed' };
       const currentRevision = storageRevisionOf(record);
diff --git a/apps/server/src/modules/storage/backends/disk/space-nodes.ts b/apps/server/src/modules/storage/backends/disk/space-nodes.ts
index 759d07a1c..9fc2783f0 100644
--- a/apps/server/src/modules/storage/backends/disk/space-nodes.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-nodes.ts
@@ -15,6 +15,7 @@ import type {
   NodePutInput,
   NodePutResult,
   NodeSnapshot,
+  NodeStreamOptions,
   SpaceNodes,
 } from '../../ports/structured.js';
 
@@ -30,6 +31,14 @@ function snapshotOf(record: NodeContent): NodeSnapshot {
   return { record, revision };
 }
 
+function snapshotsOf(
+  contents: ReadonlyMap<string, NodeContent>,
+): Map<string, NodeSnapshot> {
+  const out = new Map<string, NodeSnapshot>();
+  for (const [nodeId, record] of contents) out.set(nodeId, snapshotOf(record));
+  return out;
+}
+
 export class DiskSpaceNodes implements SpaceNodes {
   readonly canvasId: string;
 
@@ -48,6 +57,45 @@ export class DiskSpaceNodes implements SpaceNodes {
     return record === null ? null : snapshotOf(record);
   }
 
+  /**
+   * Named nodes only.
+   *
+   * Resolved one id at a time through the same strict read {@link read} uses,
+   * so a selection sees exactly what reading each id would — including the
+   * index rebuild that resolves an externally renamed sidecar. Disk pays one
+   * directory scan to warm the id index and then one file read per requested
+   * id, which is the cost this member exists to keep proportional. Duplicate
+   * ids in the request collapse, as they do in the returned map.
+   */
+  async readMany(
+    nodeIds: readonly string[],
+  ): Promise<Map<string, NodeSnapshot>> {
+    this.#assertActiveWorkspace();
+    const out = new Map<string, NodeSnapshot>();
+    for (const nodeId of new Set(nodeIds)) {
+      const record = this.#store.readNodeStrict(nodeId);
+      if (record !== null) out.set(nodeId, snapshotOf(record));
+    }
+    return out;
+  }
+
+  async list(): Promise<Map<string, NodeSnapshot>> {
+    this.#assertActiveWorkspace();
+    return snapshotsOf(await this.#store.readAllNodes());
+  }
+
+  async stream(
+    onNode: (snapshot: NodeSnapshot) => void,
+    options?: NodeStreamOptions,
+  ): Promise<Map<string, NodeSnapshot>> {
+    this.#assertActiveWorkspace();
+    const contents = await this.#store.streamAllNodes(
+      (_id, content) => onNode(snapshotOf(content)),
+      options?.signal,
+    );
+    return snapshotsOf(contents);
+  }
+
   async put(input: NodePutInput): Promise<NodePutResult> {
     this.#assertActiveWorkspace();
     if (input.record.nodeId !== input.nodeId) {
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
index dd7ab747d..9f19aff10 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
@@ -115,6 +115,17 @@ describeSpaceRepositoryContract('Disk', () => {
         },
       }),
     worldCanvasId: WORLD_ID,
+    // A Disk namespace is a Workspace directory, so an unmounted one is a
+    // fresh temp root with no `.world`. Activating it invalidates the store
+    // above, which is exactly the licence the harness member documents.
+    openEmptyNamespace: () => {
+      makeWorkspace('huabu-space-repository-contract-empty-');
+      const empty = new DiskStructuredStore();
+      return {
+        repository: empty.spaces(),
+        read: (canvasId: string) => empty.space(canvasId).read(),
+      };
+    },
   };
 });
 
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.ts b/apps/server/src/modules/storage/backends/disk/space-repository.ts
index e59b78fd2..ea8d30456 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.ts
@@ -36,6 +36,7 @@ import {
   titleForAllocatedDirectory,
   titleVisibleAtDirectory,
 } from './space-title.js';
+import { ensureWorldCanvasOnDisk } from './world-canvas.js';
 import { atomicWriteJson, mkdirp, sanitizeId } from '../../../../utils/fs.js';
 import { normalizeForCompare } from '../../../../utils/naming.js';
 import { getWorkspacePath } from '../../../workspace.js';
@@ -91,6 +92,27 @@ export class DiskSpaceRepository implements SpaceRepository {
     return this.#requireWorld();
   }
 
+  /**
+   * Bootstrap the World, delegating to the same idempotent Disk primitive
+   * Workspace preparation calls.
+   *
+   * One writer for one file: the preparation path may still run before the
+   * store is mounted (legacy migrations remain filesystem-based), so a second
+   * implementation here would be a second authority over `.world/space.json`
+   * that could disagree about what counts as established. The primitive
+   * already reads an existing `.world` as established storage and raises on a
+   * malformed one, which is exactly what the port promises.
+   *
+   * The directory index is refreshed afterwards because a freshly created
+   * World is a new member of the collection every later read resolves through.
+   */
+  async ensureWorld(): Promise<string> {
+    this.#assertActiveWorkspace();
+    const canvasId = ensureWorldCanvasOnDisk(this.#workspacePath);
+    refreshCanvasDirIndex();
+    return canvasId;
+  }
+
   async create(input: SpaceCreateInput): Promise<SpaceCreateResult> {
     this.#assertActiveWorkspace();
     const canvasId = sanitizeId(input.canvasId, 'canvasId');
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index 88d251d1b..e1bca057d 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -98,6 +98,7 @@ export type {
   NodePutInput,
   NodePutResult,
   NodeSnapshot,
+  NodeStreamOptions,
   SpaceBeginDeleteResult,
   SpaceChanges,
   SpaceCreateInput,
diff --git a/apps/server/src/modules/storage/ports/contracts/space-nodes.contract.ts b/apps/server/src/modules/storage/ports/contracts/space-nodes.contract.ts
index f6499cf9b..3d70bbd8f 100644
--- a/apps/server/src/modules/storage/ports/contracts/space-nodes.contract.ts
+++ b/apps/server/src/modules/storage/ports/contracts/space-nodes.contract.ts
@@ -66,6 +66,104 @@ export function describeSpaceNodesContract(
       await expect(repository.read('contract-missing')).resolves.toBeNull();
     });
 
+    /**
+     * The four read shapes are one view of one collection.
+     *
+     * Each is free to reach the backend differently — a lookup by id, a
+     * selection, a scan, a scan that yields — so what has to be asserted is
+     * that they never disagree about a node. An adapter whose scan parsed
+     * records more leniently than its single read, or minted a different
+     * revision, would pass every test written against one shape alone.
+     */
+    it('agrees across read, readMany, list, and stream', async () => {
+      const { repository } = await open();
+      const ids = ['contract-agree-a', 'contract-agree-b', 'contract-agree-c'];
+      for (const nodeId of ids) {
+        await putSuccessfully(repository, {
+          nodeId,
+          record: note(nodeId, `Contract ${nodeId}`, `body of ${nodeId}`),
+        });
+      }
+
+      const listed = await repository.list();
+      for (const nodeId of ids) {
+        expect(listed.get(nodeId)).toEqual(await repository.read(nodeId));
+      }
+
+      const selection = ids.slice(0, 2);
+      const many = await repository.readMany(selection);
+      expect([...many.keys()].sort()).toEqual(selection);
+      for (const nodeId of selection) {
+        expect(many.get(nodeId)).toEqual(listed.get(nodeId));
+      }
+
+      const delivered: NodeSnapshot[] = [];
+      const streamed = await repository.stream((snapshot) => {
+        delivered.push(snapshot);
+      });
+      expect(streamed).toEqual(listed);
+      // Delivery order is unspecified, so compare as a set keyed by id.
+      expect(
+        new Map(
+          delivered.map((snapshot) => [snapshot.record.nodeId, snapshot]),
+        ),
+      ).toEqual(listed);
+      expect(delivered).toHaveLength(listed.size);
+    });
+
+    it('omits absent ids from readMany rather than failing', async () => {
+      const { repository } = await open();
+      const present = 'contract-partial-present';
+      await putSuccessfully(repository, {
+        nodeId: present,
+        record: note(present, 'Contract partial', 'here'),
+      });
+
+      const many = await repository.readMany([
+        present,
+        'contract-partial-absent',
+        // A repeated id is one node, not two reads with two answers.
+        present,
+      ]);
+
+      expect([...many.keys()]).toEqual([present]);
+      await expect(repository.readMany([])).resolves.toEqual(new Map());
+    });
+
+    it('reads an absent Space as an empty collection', async () => {
+      const { missingRepository } = await open();
+
+      await expect(missingRepository.list()).resolves.toEqual(new Map());
+      await expect(
+        missingRepository.readMany(['contract-missing-space-node']),
+      ).resolves.toEqual(new Map());
+
+      const delivered: NodeSnapshot[] = [];
+      await expect(
+        missingRepository.stream((snapshot) => delivered.push(snapshot)),
+      ).resolves.toEqual(new Map());
+      expect(delivered).toEqual([]);
+    });
+
+    it('stops delivering to an aborted stream', async () => {
+      const { repository } = await open();
+      const nodeId = 'contract-stream-abort';
+      await putSuccessfully(repository, {
+        nodeId,
+        record: note(nodeId, 'Contract abort', 'body'),
+      });
+
+      const delivered: NodeSnapshot[] = [];
+      // Already aborted, so no adapter has an excuse to deliver: this pins
+      // that the promise still settles rather than that a mid-scan abort is
+      // observed at any particular node.
+      await repository.stream((snapshot) => delivered.push(snapshot), {
+        signal: { aborted: true },
+      });
+
+      expect(delivered).toEqual([]);
+    });
+
     it('returns the exact persisted record and its matching revision from put', async () => {
       const { repository } = await open();
       const input: NodePutInput = {
diff --git a/apps/server/src/modules/storage/ports/contracts/space-repository.contract.ts b/apps/server/src/modules/storage/ports/contracts/space-repository.contract.ts
index 32cdf2909..fb34ef2d0 100644
--- a/apps/server/src/modules/storage/ports/contracts/space-repository.contract.ts
+++ b/apps/server/src/modules/storage/ports/contracts/space-repository.contract.ts
@@ -23,9 +23,27 @@ export interface SpaceRepositoryContractHarness {
   readonly worldCanvasId: string;
   /** One representative portable mutation for deletion-fence checks. */
   readonly attemptMutation: (canvasId: string) => Promise<unknown>;
+  /**
+   * Bind to a namespace that has never been mounted — no World, no Spaces.
+   *
+   * This is the state every backend meets first, and the only place the
+   * creating branch of {@link SpaceRepository.ensureWorld} can be observed;
+   * the main harness namespace always has a World already. Invalidating the
+   * other harness members is allowed: a case that opens this uses nothing
+   * else afterwards.
+   */
+  readonly openEmptyNamespace: () =>
+    | Promise<EmptyNamespaceHarness>
+    | EmptyNamespaceHarness;
   readonly cleanup?: () => Promise<void> | void;
 }
 
+/** A backend namespace with nothing in it yet. */
+export interface EmptyNamespaceHarness {
+  readonly repository: SpaceRepository;
+  readonly read: (canvasId: string) => Promise<CanvasFile | null>;
+}
+
 export function describeSpaceRepositoryContract(
   name: string,
   createHarness: () =>
@@ -94,6 +112,45 @@ export function describeSpaceRepositoryContract(
       ).not.toContain(worldCanvasId);
     });
 
+    it('returns the established World from ensureWorld without replacing it', async () => {
+      const { repository, worldCanvasId, read } = await open();
+      const before = await read(worldCanvasId);
+
+      await expect(repository.ensureWorld()).resolves.toBe(worldCanvasId);
+      await expect(repository.ensureWorld()).resolves.toBe(worldCanvasId);
+
+      // Identity is what Portals reference, so a bootstrap that ran against an
+      // established World must be indistinguishable from not having run.
+      await expect(read(worldCanvasId)).resolves.toEqual(before);
+      expect(
+        (await repository.list()).map((row) => row.canvasId),
+      ).not.toContain(worldCanvasId);
+    });
+
+    it('bootstraps exactly one version-0 World in an empty namespace', async () => {
+      const { openEmptyNamespace } = await open();
+      const { repository, read } = await openEmptyNamespace();
+
+      const worldCanvasId = await repository.ensureWorld();
+      expect(worldCanvasId).toEqual(expect.any(String));
+      expect(worldCanvasId).not.toHaveLength(0);
+
+      const created = await read(worldCanvasId);
+      expect(created).toMatchObject({
+        canvasId: worldCanvasId,
+        version: 0,
+        state: { nodes: [], edges: [] },
+      });
+
+      // Idempotent, and the World it minted is the one `worldId()` resolves —
+      // a second bootstrap that minted a second identity would orphan every
+      // Portal written against the first.
+      await expect(repository.ensureWorld()).resolves.toBe(worldCanvasId);
+      await expect(repository.worldId()).resolves.toBe(worldCanvasId);
+      await expect(read(worldCanvasId)).resolves.toEqual(created);
+      await expect(repository.list()).resolves.toEqual([]);
+    });
+
     it('creates and returns the authoritative empty version-0 record', async () => {
       const { repository, read } = await open();
       const result = await repository.create({
diff --git a/apps/server/src/modules/storage/ports/structured.ts b/apps/server/src/modules/storage/ports/structured.ts
index 274074304..5ce4eed17 100644
--- a/apps/server/src/modules/storage/ports/structured.ts
+++ b/apps/server/src/modules/storage/ports/structured.ts
@@ -180,6 +180,21 @@ export interface SpaceRepository {
    * A missing or malformed World is an integrity failure and rejects.
    */
   worldId(): Promise<string>;
+  /**
+   * Return the stable World, creating it once if this namespace is new.
+   *
+   * The backend-neutral bootstrap hook. Every backend meets an empty
+   * namespace the first time it is mounted, and a Workspace without a World
+   * has no Portal target and no home view — so ensuring one cannot stay a
+   * Disk-shaped step run before the store exists.
+   *
+   * Idempotent, and deliberately narrower than "create if absent": it mints a
+   * version-0 World only when the namespace holds no World at all. An
+   * *established* World that is missing or malformed stays the integrity
+   * error {@link worldId} reports, because regenerating identity there would
+   * silently orphan every Portal that referenced it.
+   */
+  ensureWorld(): Promise<string>;
   create(input: SpaceCreateInput): Promise<SpaceCreateResult>;
   /**
    * Fence mutations before cross-store cleanup begins.
@@ -471,6 +486,54 @@ export interface SpaceNodes {
    */
   readonly canvasId: string;
   read(nodeId: string): Promise<NodeSnapshot | null>;
+  /**
+   * The named nodes that exist, keyed by stable id.
+   *
+   * An absent id is a missing key, not an error: a caller asking for a
+   * selection is describing what it wants, not asserting that all of it is
+   * there. Reading the same id through {@link read} yields the same record and
+   * the same revision.
+   *
+   * This is the shape most readers want — a selection to describe, a
+   * neighbourhood to render, one View to serve — and it exists so their cost
+   * stays proportional to the request. Expressed as {@link list} the same read
+   * makes an unrelated node somewhere else part of the bill, and no backend
+   * serves that better than it serves a lookup by id.
+   */
+  readMany(nodeIds: readonly string[]): Promise<Map<string, NodeSnapshot>>;
+  /**
+   * Every node in this Space, keyed by stable id.
+   *
+   * For work that genuinely spans the Space — executor prestate hydration,
+   * the Space GET, the canvas outline, cross-node inspection. Iteration order
+   * is unspecified; a caller that needs an order imposes it.
+   */
+  list(): Promise<Map<string, NodeSnapshot>>;
+  /**
+   * {@link list}, delivering each record as it lands.
+   *
+   * `onNode` is invoked once per node, never concurrently with itself, before
+   * the returned map settles; the map is the same collection {@link list}
+   * would return. Delivery order is arrival order, and is deliberately not a
+   * query order — a backend may serve in whatever order is cheapest, and none
+   * of them promises a resumable cursor. This is a latency shape for a reader
+   * that can show partial results, not a pagination contract.
+   */
+  stream(
+    onNode: (snapshot: NodeSnapshot) => void,
+    options?: NodeStreamOptions,
+  ): Promise<Map<string, NodeSnapshot>>;
   put(input: NodePutInput): Promise<NodePutResult>;
   delete(nodeId: string): Promise<NodeDeleteResult>;
 }
+
+export interface NodeStreamOptions {
+  /**
+   * Polled as the scan proceeds; an aborted scan stops delivering early.
+   *
+   * The returned promise still settles, so an adapter never leaks a pending
+   * scan, but its map is then partial by definition. A caller that aborts
+   * must check its own signal rather than reading the result.
+   */
+  readonly signal?: { readonly aborted: boolean };
+}

From d249505fdfabbdb383e26db70ccff7d52d8b3326 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 15:33:51 +0800
Subject: [PATCH 03/20] feat(storage): reach one Space through one handle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reaching a Space meant calling two unrelated functions that never said they
addressed the same thing: `getStructuredStore().space(id)` for its record and
nodes, `canvasBlobs(id)` for its bytes, `spaceDirectory(id)` for its
directory. Three entry points, one subject.

`Storage.space(canvasId)` joins them, with a free `space()` shorthand on the
barrel. It is a composition-layer facade, not a port type: `StructuredStore`
and `BlobStore` keep their interfaces and their independence, and they are
joined in the layer that already owns every cross-store rule — the blob-put
precondition and the blob-first delete saga. The join cannot move down into a
port, because the two axes are configured independently, deletion ordering
deliberately keeps blob I/O outside any database transaction, and blob scopes
exist that have no Space at all.

The Disk directory becomes `diskTree`, typed by its absence rather than
hidden behind a parallel import or stubbed to throw. A caller branching on
`null` is told the truth once. It stays unportable and stays out of `ports/`:
a backend that keeps Spaces in tables has no tree, and promising one would
mean fabricating it. The fence is the Disk name plus the census in
`module-boundaries.test.ts`, which may shrink and must not grow — every entry
is a family §6.4.3 assigns a disposition.

Two things fall out. `import-node-src` asked storage where a Space was in
order to classify a path it had already resolved in sandbox coordinates; it
now asks `fs-sandbox` for its own root, which is not a storage question at
all. And `space()` composes from the receiver rather than a captured local,
so `{...storage, blobs: fake}` — the obvious way to stub one axis, and what
the artifact tests already do — gets Spaces built on the store it substituted
instead of silently keeping the original.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../agent/conversation/prompt/attachments.ts  |   4 +-
 .../src/modules/agent/memory/trigger.ts       |   9 +-
 .../agent/tools/handlers/fs-sandbox.ts        |  28 +++-
 .../agent/tools/handlers/image-generation.ts  |   4 +-
 .../modules/artifact/artifact.route.test.ts   |  16 +--
 .../src/modules/artifact/artifact.route.ts    |  10 +-
 apps/server/src/modules/artifact/utils.ts     |   4 +-
 .../modules/canvas/canvas-executor.test.ts    |   6 +-
 .../src/modules/canvas/canvas-executor.ts     |   4 +-
 .../src/modules/canvas/canvas.route.test.ts   |   6 +-
 .../server/src/modules/canvas/canvas.route.ts |  15 +-
 .../src/modules/canvas/external.route.ts      |  11 +-
 .../modules/canvas/import-node-src.test.ts    |  28 ++--
 .../src/modules/canvas/import-node-src.ts     |   9 +-
 .../src/modules/canvas/snapshot-nodes.ts      |  10 +-
 .../interactive-view.route.ts                 |   4 +-
 .../interactive-view.service.ts               |   8 +-
 .../src/modules/preprocessing/dispatcher.ts   |   4 +-
 .../remote_fs/interactive-view.rfs.test.ts    |   8 +-
 .../src/modules/remote_fs/rfs.route.test.ts   |  20 ++-
 apps/server/src/modules/remote_fs/skill.ts    |  15 +-
 .../backends/disk/legacy/canvas-store.ts      |   2 +-
 .../storage/backends/disk/space-tree.ts       |  44 ++++++
 .../backends/disk/storage-recovery.test.ts    |  14 +-
 .../compatibility/delete-canvas.test.ts       |  38 ++---
 apps/server/src/modules/storage/index.ts      |   7 +-
 .../modules/storage/module-boundaries.test.ts |  58 ++++++++
 apps/server/src/modules/storage/storage.ts    | 134 +++++++++++++++---
 .../legacy-workspace-activation.test.ts       |  20 ++-
 apps/server/src/modules/workspace/paths.ts    |  28 +++-
 30 files changed, 424 insertions(+), 144 deletions(-)
 create mode 100644 apps/server/src/modules/storage/backends/disk/space-tree.ts

diff --git a/apps/server/src/modules/agent/conversation/prompt/attachments.ts b/apps/server/src/modules/agent/conversation/prompt/attachments.ts
index b0bb8ca75..05389c52c 100644
--- a/apps/server/src/modules/agent/conversation/prompt/attachments.ts
+++ b/apps/server/src/modules/agent/conversation/prompt/attachments.ts
@@ -37,7 +37,7 @@ import { resolveImageUrl, MAX_INLINE_IMAGE_BYTES } from './image-inlining.js';
 import { escapeXmlAttr, escapeXmlText } from './node-element.js';
 import { isRasterizableImageMime } from '../../../../utils/mime.js';
 import { ARTIFACT_URL_REGEX } from '../../../artifact/utils.js';
-import { canvasBlobs } from '../../../storage/index.js';
+import { space } from '../../../storage/index.js';
 
 import type { AgentInputPart } from '@agenetes/protocol';
 import type { ChatAttachment } from '@huabu/shared';
@@ -223,7 +223,7 @@ export async function buildAttachmentParts(
           if (resolvedCanvasId && resolvedFilename) {
             try {
               const bytes =
-                await canvasBlobs(resolvedCanvasId).read(resolvedFilename);
+                await space(resolvedCanvasId).blobs.read(resolvedFilename);
               // Attachments are inlined as text; binary bytes simply
               // decode to mojibake and the URL-only branch is used instead.
               if (bytes) fileContent = bytes.toString('utf-8');
diff --git a/apps/server/src/modules/agent/memory/trigger.ts b/apps/server/src/modules/agent/memory/trigger.ts
index 6367f1c58..1b619b7ca 100644
--- a/apps/server/src/modules/agent/memory/trigger.ts
+++ b/apps/server/src/modules/agent/memory/trigger.ts
@@ -26,7 +26,7 @@ import { existsSync } from 'node:fs';
 
 import { atomicWriteJson, mkdirp, readJson } from '../../../utils/fs.js';
 import { createKeyedMutex } from '../../../utils/keyed-mutex.js';
-import { spaceDirectory } from '../../storage/index.js';
+import { space } from '../../storage/index.js';
 import { memoryStatePath, canvasMemoryDir } from '../../workspace/paths.js';
 
 /** Op-count threshold that triggers a memory analysis pass. */
@@ -83,7 +83,12 @@ export function writeMemoryState(canvasId: string, state: MemoryState): void {
   // file. Same hazard for any in-flight memory worker that calls
   // `markAnalyzed` post-delete. Skip the write when the canvas root
   // is gone; losing one bookkeeping write is harmless.
-  if (!existsSync(spaceDirectory(canvasId))) return;
+  // Disk-only by construction: the hazard is an ad-hoc file write
+  // recreating a directory the delete removed, and a backend with no
+  // directory has no such hazard. Phase 4.6 retires the guard entirely when
+  // this state moves onto the extension substrate (proposal §12.6.3).
+  const tree = space(canvasId).diskTree;
+  if (tree && !existsSync(tree.directory())) return;
   mkdirp(canvasMemoryDir(canvasId));
   atomicWriteJson(memoryStatePath(canvasId), state);
 }
diff --git a/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts b/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
index 18b80a5ea..62ef0b5d2 100644
--- a/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
+++ b/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
@@ -30,7 +30,7 @@ import { readFileSync, readdirSync, statSync, type Dirent } from 'node:fs';
 import path from 'node:path';
 
 import { parseFrontmatter } from '../../../../utils/markdown-frontmatter.js';
-import { getCanvasStore, spaceDirectory } from '../../../storage/index.js';
+import { getCanvasStore, space } from '../../../storage/index.js';
 
 // ─── Always-skipped directory names ─────────────────────────────────────────
 
@@ -143,7 +143,18 @@ export function safeResolve(canvasId: string, rel: string): string {
   ) {
     throw new Error(`Invalid canvasId: ${canvasId}`);
   }
-  const root = spaceDirectory(canvasId);
+  // The built-in file tools are Disk-only and stated as such (proposal
+  // §6.4.3, disposition A): off Disk the first-party agent reaches a Space
+  // over RFS/HTTP, which is what external agents already use. Refusing here
+  // is the backstop behind the capability matrix, not the primary check.
+  const tree = space(canvasId).diskTree;
+  if (!tree) {
+    throw new Error(
+      'Built-in file tools need a Space directory, which the active ' +
+        'structured backend does not provide.',
+    );
+  }
+  const root = tree.directory();
   // Accept the clean virtual prefixes (`upload/`, `artifacts/`) as aliases
   // for their hidden on-disk dirs so agents can reference either form.
   const target = path.resolve(root, toPhysicalRel(rel));
@@ -155,6 +166,19 @@ export function safeResolve(canvasId: string, rel: string): string {
   return target;
 }
 
+/**
+ * The sandbox root for one Space.
+ *
+ * Exported because classifying a resolved path as "inside this Space" is a
+ * question about the sandbox, not about storage: the caller that asks is
+ * already working in sandbox coordinates, and routing it through storage
+ * would make it a consumer of a backend capability it has no stake in
+ * (proposal §6.4.3).
+ */
+export function sandboxRoot(canvasId: string): string {
+  return safeResolve(canvasId, '');
+}
+
 /** Normalise a relative path to forward slashes. */
 export function normalizeRel(rel: string): string {
   return rel.split(path.sep).join('/');
diff --git a/apps/server/src/modules/agent/tools/handlers/image-generation.ts b/apps/server/src/modules/agent/tools/handlers/image-generation.ts
index 0c00a23d4..966913750 100644
--- a/apps/server/src/modules/agent/tools/handlers/image-generation.ts
+++ b/apps/server/src/modules/agent/tools/handlers/image-generation.ts
@@ -52,7 +52,7 @@ import {
 } from '@huabu/shared';
 
 import { getLogger } from '../../../../utils/logger.js';
-import { canvasBlobs } from '../../../storage/index.js';
+import { space } from '../../../storage/index.js';
 import { getAzureImageConfig } from '../../llm.js';
 
 import type { generateImageParamsSchema } from '../definitions.js';
@@ -131,7 +131,7 @@ export async function handleGenerateImage(
   // ── Load reference artifacts upfront ──────────────────────────────────
   // Any missing/invalid ref is an early hard error — better than sending
   // a partial set to Azure and getting cryptic results.
-  const blobs = canvasBlobs(args.canvasId);
+  const blobs = space(args.canvasId).blobs;
   const refImages: Array<{ key: string; bytes: Buffer }> = [];
   for (const key of refs) {
     if (typeof key !== 'string' || !key.trim()) {
diff --git a/apps/server/src/modules/artifact/artifact.route.test.ts b/apps/server/src/modules/artifact/artifact.route.test.ts
index 3010fbec7..1bd48e187 100644
--- a/apps/server/src/modules/artifact/artifact.route.test.ts
+++ b/apps/server/src/modules/artifact/artifact.route.test.ts
@@ -23,7 +23,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import artifactRoute from './artifact.route.js';
 import { createCanvas, deleteCanvas } from '../storage/compatibility/canvas.js';
 import {
-  canvasBlobs,
+  space,
   getStorage,
   resetStorageCache,
   setStorageForTesting,
@@ -194,7 +194,7 @@ describe('artifact route', () => {
     });
 
     expect(upload.statusCode).toBe(500);
-    expect(await canvasBlobs('missing').list()).toEqual([]);
+    expect(await space('missing').blobs.list()).toEqual([]);
     await app.close();
   });
 
@@ -234,7 +234,7 @@ describe('artifact route', () => {
       const upload = await uploading;
       expect(upload.statusCode).toBe(500);
       expect(blocker.putCalls()).toBe(0);
-      expect(await canvasBlobs('c1').list()).toEqual([]);
+      expect(await space('c1').blobs.list()).toEqual([]);
     } finally {
       blocker.releaseDelete();
       blocker.restore();
@@ -244,7 +244,7 @@ describe('artifact route', () => {
 
   it('serves a byte range so media nodes can seek', async () => {
     const app = await buildApp();
-    await canvasBlobs('c1').put('a.png', png);
+    await space('c1').blobs.put('a.png', png);
 
     const res = await app.inject({
       method: 'GET',
@@ -260,7 +260,7 @@ describe('artifact route', () => {
 
   it('answers 304 for an unchanged artifact', async () => {
     const app = await buildApp();
-    await canvasBlobs('c1').put('a.png', png);
+    await space('c1').blobs.put('a.png', png);
 
     const first = await app.inject({
       method: 'GET',
@@ -332,7 +332,7 @@ describe('artifact route', () => {
 
   it('clones an artifact into another canvas under a fresh key', async () => {
     const app = await buildApp();
-    await canvasBlobs('src-canvas').put('a.png', png);
+    await space('src-canvas').blobs.put('a.png', png);
 
     const res = await app.inject({
       method: 'POST',
@@ -346,8 +346,8 @@ describe('artifact route', () => {
     expect(uri).toMatch(/\.png$/);
 
     // Destination owns its own copy; the source is untouched.
-    expect(await canvasBlobs('dst-canvas').read(uri)).toEqual(png);
-    expect(await canvasBlobs('src-canvas').read('a.png')).toEqual(png);
+    expect(await space('dst-canvas').blobs.read(uri)).toEqual(png);
+    expect(await space('src-canvas').blobs.read('a.png')).toEqual(png);
 
     await app.close();
   });
diff --git a/apps/server/src/modules/artifact/artifact.route.ts b/apps/server/src/modules/artifact/artifact.route.ts
index 26354399a..1d9a8f70e 100644
--- a/apps/server/src/modules/artifact/artifact.route.ts
+++ b/apps/server/src/modules/artifact/artifact.route.ts
@@ -8,7 +8,7 @@ import { type FastifyPluginAsync } from 'fastify';
 import { cloneArtifactBodySchema, createId } from '@huabu/shared';
 
 import { sendBlob } from './send-blob.js';
-import { canvasBlobs } from '../storage/index.js';
+import { space } from '../storage/index.js';
 import { extractHtmlFromMhtml, injectBaseHref } from '../web/mhtml.js';
 
 import type {
@@ -61,7 +61,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
     const name = `${id}${ext}`;
 
     try {
-      await canvasBlobs(canvasId).put(name, data.file);
+      await space(canvasId).blobs.put(name, data.file);
     } catch (error) {
       request.log.error({ err: error }, 'Failed to stream artifact to storage');
       return reply.code(500).send({ message: 'Failed to save file' });
@@ -82,7 +82,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
     '/:canvasId/artifact/:filename',
     async (request, reply) => {
       const { canvasId, filename } = request.params;
-      const blobs = canvasBlobs(canvasId);
+      const blobs = space(canvasId).blobs;
       const safeName = path.basename(filename);
 
       // `.mhtml` snapshots are stored as proper multipart/related MHTML
@@ -151,7 +151,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
 
     let buffer: Buffer | null;
     try {
-      buffer = await canvasBlobs(srcCanvasId).read(srcKey);
+      buffer = await space(srcCanvasId).blobs.read(srcKey);
     } catch (err) {
       request.log.error({ err }, 'Failed to read source artifact for clone');
       return reply
@@ -167,7 +167,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
     const name = `${id}${ext}`;
 
     try {
-      await canvasBlobs(dstCanvasId).put(name, buffer);
+      await space(dstCanvasId).blobs.put(name, buffer);
     } catch (err) {
       request.log.error({ err }, 'Failed to clone artifact');
       return reply
diff --git a/apps/server/src/modules/artifact/utils.ts b/apps/server/src/modules/artifact/utils.ts
index 58ab48d45..e27b69aa8 100644
--- a/apps/server/src/modules/artifact/utils.ts
+++ b/apps/server/src/modules/artifact/utils.ts
@@ -7,7 +7,7 @@ import { ARTIFACT_URL_REGEX } from '@huabu/shared';
 
 import { getLogger } from '../../utils/logger.js';
 import { IMAGE_MIME_MAP } from '../../utils/mime.js';
-import { canvasBlobs } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 const log = getLogger('artifact');
 
@@ -56,7 +56,7 @@ export async function resolveArtifactImageUrl(
   if (!canvasId || !filename) return url;
 
   try {
-    const buffer = await canvasBlobs(canvasId).read(filename);
+    const buffer = await space(canvasId).blobs.read(filename);
     if (!buffer) return url;
     const ext = path.extname(filename).toLowerCase();
     // Never guess `image/png` for an unknown extension: callers forward this
diff --git a/apps/server/src/modules/canvas/canvas-executor.test.ts b/apps/server/src/modules/canvas/canvas-executor.test.ts
index 8bf897503..67bd529f7 100644
--- a/apps/server/src/modules/canvas/canvas-executor.test.ts
+++ b/apps/server/src/modules/canvas/canvas-executor.test.ts
@@ -30,7 +30,7 @@ import { nodeRevisionOf } from '@huabu/shared/canvas-engine';
 
 import { applyDeltasOnServer, executeOnServer } from './canvas-executor.js';
 import {
-  canvasBlobs,
+  space,
   getCanvasStore,
   getStructuredStore,
   updateNode,
@@ -273,7 +273,7 @@ describe('executeOnServer — MERGE_NODE_DATA CAS', () => {
       src: 'old.svg',
       content: '',
     });
-    await canvasBlobs('c1').put(
+    await space('c1').blobs.put(
       'new.svg',
       Buffer.from(
         '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100"></svg>',
@@ -329,7 +329,7 @@ describe('executeOnServer — MERGE_NODE_DATA CAS', () => {
       src: 'pic.svg',
       content: '',
     });
-    await canvasBlobs('c1').put(
+    await space('c1').blobs.put(
       'pic.svg',
       Buffer.from(
         '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100"></svg>',
diff --git a/apps/server/src/modules/canvas/canvas-executor.ts b/apps/server/src/modules/canvas/canvas-executor.ts
index 30461bec6..a59a62b46 100644
--- a/apps/server/src/modules/canvas/canvas-executor.ts
+++ b/apps/server/src/modules/canvas/canvas-executor.ts
@@ -64,7 +64,7 @@ import {
 } from './world-portal-policy.js';
 import { getLogger } from '../../utils/logger.js';
 import {
-  canvasBlobs,
+  space,
   getCanvasStore,
   getStructuredStore,
   withCanvasMutex,
@@ -375,7 +375,7 @@ async function aspectHeightForWidth(
   width: number,
 ): Promise<number | null> {
   try {
-    const dim = await readImageDimensions(canvasBlobs(canvasId), src);
+    const dim = await readImageDimensions(space(canvasId).blobs, src);
     if (!dim?.width || !dim?.height || dim.width <= 0 || dim.height <= 0) {
       return null;
     }
diff --git a/apps/server/src/modules/canvas/canvas.route.test.ts b/apps/server/src/modules/canvas/canvas.route.test.ts
index bbfeac7a8..c34a7a81a 100644
--- a/apps/server/src/modules/canvas/canvas.route.test.ts
+++ b/apps/server/src/modules/canvas/canvas.route.test.ts
@@ -39,7 +39,7 @@ import canvasRoutes from './canvas.route.js';
 import { withSpaceDirHandlesReleased } from '../storage/backends/disk/space-dir-handles.js';
 import { createCanvas, deleteCanvas } from '../storage/compatibility/canvas.js';
 import {
-  canvasBlobs,
+  space,
   getCanvasStore,
   getStructuredStore,
   resetStorageCache,
@@ -738,7 +738,7 @@ describe('Space export/import persistence', () => {
       change,
     ]);
     const blob = Buffer.from([0, 1, 2, 3, 255]);
-    await canvasBlobs('c1').put('asset.bin', blob);
+    await space('c1').blobs.put('asset.bin', blob);
 
     const app = await buildApp();
     try {
@@ -790,7 +790,7 @@ describe('Space export/import persistence', () => {
       expect(await importedSpace.changes.read('thread-export')).toEqual(
         storedChanges,
       );
-      expect(await canvasBlobs(importedId).read('asset.bin')).toEqual(blob);
+      expect(await space(importedId).blobs.read('asset.bin')).toEqual(blob);
     } finally {
       await app.close();
     }
diff --git a/apps/server/src/modules/canvas/canvas.route.ts b/apps/server/src/modules/canvas/canvas.route.ts
index b6ffedde6..c77be6838 100644
--- a/apps/server/src/modules/canvas/canvas.route.ts
+++ b/apps/server/src/modules/canvas/canvas.route.ts
@@ -54,12 +54,11 @@ import {
   suggestCanvasDir,
 } from '../storage/canvas-dirs.js';
 import {
-  canvasBlobs,
+  space,
   createSpace,
   deleteSpace,
   getCanvasStore,
   getStructuredStore,
-  spaceDirectory,
   type CanvasFile,
   type UpdateNodeOutcome,
   updateNode,
@@ -337,7 +336,7 @@ async function singleArtifactProbe(
 ): Promise<(key: string) => boolean> {
   const key = extractArtifactKey(src);
   if (!key) return () => false;
-  const exists = (await canvasBlobs(canvasId).hasMany([key])).has(key);
+  const exists = (await space(canvasId).blobs.hasMany([key])).has(key);
   return (candidate) => candidate === key && exists;
 }
 
@@ -527,7 +526,7 @@ async function hydrateNodeContent(
   const present =
     referenced.size === 0
       ? new Set<string>()
-      : await canvasBlobs(store.canvasId).hasMany([...referenced]);
+      : await space(store.canvasId).blobs.hasMany([...referenced]);
   const artifactExists = (key: string): boolean => present.has(key);
 
   return nodes.map((node) => {
@@ -1610,8 +1609,12 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
       return reply.code(404).send({ message: 'Canvas not found' });
     }
 
-    const canvasDir = spaceDirectory(canvasId);
-    if (!existsSync(canvasDir)) {
+    // The Space bundle is a Disk projection (proposal §6.4.3, disposition
+    // A); a portable export generated from records plus reachable blob
+    // references is a separate later design.
+    const tree = space(canvasId).diskTree;
+    const canvasDir = tree?.directory();
+    if (canvasDir === undefined || !existsSync(canvasDir)) {
       return reply.code(404).send({ message: 'Canvas directory not found' });
     }
 
diff --git a/apps/server/src/modules/canvas/external.route.ts b/apps/server/src/modules/canvas/external.route.ts
index 0984daa1c..6460a9ad8 100644
--- a/apps/server/src/modules/canvas/external.route.ts
+++ b/apps/server/src/modules/canvas/external.route.ts
@@ -17,7 +17,7 @@ import {
   takeExternalNote,
 } from './external-watcher.js';
 import { parseFrontmatter } from '../../utils/markdown-frontmatter.js';
-import { spaceDirectory } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type { FastifyPluginAsync } from 'fastify';
 
@@ -95,7 +95,14 @@ const externalRoutes: FastifyPluginAsync = async (fastify): Promise<void> => {
       return reply.code(404).send({ message: 'External note not found' });
     }
 
-    const abs = path.join(spaceDirectory(canvasId), item.relativePath);
+    // External-note claim is Disk-only (proposal §6.4.3, disposition A): it
+    // exists to adopt documents that arrived without going through the
+    // application, and no database backend has such an arrival path.
+    const tree = space(canvasId).diskTree;
+    if (!tree) {
+      return reply.code(404).send({ message: 'External note not found' });
+    }
+    const abs = path.join(tree.directory(), item.relativePath);
     let raw: string;
     try {
       raw = await readFile(abs, 'utf8');
diff --git a/apps/server/src/modules/canvas/import-node-src.test.ts b/apps/server/src/modules/canvas/import-node-src.test.ts
index 089ad92ac..731608357 100644
--- a/apps/server/src/modules/canvas/import-node-src.test.ts
+++ b/apps/server/src/modules/canvas/import-node-src.test.ts
@@ -15,15 +15,23 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { importForeignNodeSources } from './import-node-src.js';
 import { createCanvas } from '../storage/compatibility/canvas.js';
-import {
-  canvasBlobs,
-  getCanvasStore,
-  spaceDirectory,
-} from '../storage/index.js';
+import { space, getCanvasStore } from '../storage/index.js';
 import { setWorkspacePath } from '../workspace.js';
 
 import type { CanvasCommand } from '@huabu/shared';
 
+/**
+ * The Space's Disk directory, or a test failure.
+ *
+ * These cases are Disk-specific by construction; the assertion states that
+ * rather than letting an optional-chained `undefined` quietly pass.
+ */
+function diskDirOf(canvasId: string): string {
+  const tree = space(canvasId).diskTree;
+  if (!tree) throw new Error('Expected the Disk backend in this test');
+  return tree.directory();
+}
+
 let tmp: string;
 
 beforeEach(() => {
@@ -49,7 +57,7 @@ afterEach(() => {
 
 /** Stage a file under the canvas's hidden `.upload/` scratch dir. */
 function stageUpload(canvasId: string, name: string, body: string): string {
-  const uploadDir = path.join(spaceDirectory(canvasId), '.upload');
+  const uploadDir = path.join(diskDirOf(canvasId), '.upload');
   mkdirSync(uploadDir, { recursive: true });
   const abs = path.join(uploadDir, name);
   writeFileSync(abs, body);
@@ -125,7 +133,7 @@ describe('importForeignNodeSources — web nodes', () => {
     // …whose file exists in the artifact store…
     expect(src).toBeDefined();
     if (src === undefined) throw new Error('Expected a rewritten web src');
-    expect(await canvasBlobs(canvasId).head(src)).not.toBeNull();
+    expect(await space(canvasId).blobs.head(src)).not.toBeNull();
     // …and the staging upload was reclaimed (move semantics).
     expect(existsSync(uploadAbs)).toBe(false);
   });
@@ -221,7 +229,7 @@ describe('importForeignNodeSources — web nodes', () => {
     expect(src).toMatch(/^artifact-[^/]+\.html$/);
     expect(src).toBeDefined();
     if (src === undefined) throw new Error('Expected a rewritten web src');
-    expect(await canvasBlobs(canvasId).head(src)).not.toBeNull();
+    expect(await space(canvasId).blobs.head(src)).not.toBeNull();
     expect(existsSync(uploadAbs)).toBe(false);
   });
 
@@ -268,13 +276,13 @@ describe('importForeignNodeSources — media nodes (regression)', () => {
     expect(src).toMatch(/^artifact-[^/]+\.png$/);
     expect(src).toBeDefined();
     if (src === undefined) throw new Error('Expected a rewritten image src');
-    expect(await canvasBlobs(canvasId).head(src)).not.toBeNull();
+    expect(await space(canvasId).blobs.head(src)).not.toBeNull();
   });
 
   it('canonicalizes an artifact path that leaves and re-enters the Space', async () => {
     const canvasId = 'c-image-reentered';
     const store = getCanvasStore(canvasId);
-    const spaceDir = spaceDirectory(canvasId);
+    const spaceDir = diskDirOf(canvasId);
     const artifactsDir = path.join(spaceDir, '.artifacts');
     mkdirSync(artifactsDir, { recursive: true });
     writeFileSync(path.join(artifactsDir, 'pic.png'), 'existing artifact');
diff --git a/apps/server/src/modules/canvas/import-node-src.ts b/apps/server/src/modules/canvas/import-node-src.ts
index 39837f701..77f39c27f 100644
--- a/apps/server/src/modules/canvas/import-node-src.ts
+++ b/apps/server/src/modules/canvas/import-node-src.ts
@@ -39,9 +39,10 @@ import { getLogger } from '../../utils/logger.js';
 import {
   safeResolve,
   isArtifactsRel,
+  sandboxRoot,
   toPhysicalRel,
 } from '../agent/tools/handlers/fs-sandbox.js';
-import { canvasBlobs, spaceDirectory } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type { CanvasStore } from '../storage/index.js';
 
@@ -272,7 +273,7 @@ async function resolveImportedSrc(
   // is judged by where it actually lands, while the helper still owns the
   // virtual/physical `.artifacts` vocabulary. A nested path is not a blob key,
   // so it falls through and is copied into the artifact root below.
-  const resolvedPhysicalRel = path.relative(spaceDirectory(canvasId), absPath);
+  const resolvedPhysicalRel = path.relative(sandboxRoot(canvasId), absPath);
   if (isArtifactsRel(resolvedPhysicalRel)) {
     const key = path.basename(absPath);
     const canonicalPath = safeResolve(
@@ -309,7 +310,7 @@ async function copyToArtifact(
     const id = createId('artifact');
     const key = `${id}${ext}`;
     const buffer = await readFile(absPath);
-    await canvasBlobs(store.canvasId).put(key, buffer);
+    await space(store.canvasId).blobs.put(key, buffer);
 
     // Move semantics: reclaim RFS scratch uploads once they are safely
     // stored. Never delete user node files or other canvas content —
@@ -365,7 +366,7 @@ async function downloadToArtifact(
     }
     const ext = pickDownloadExt(pathname, contentType);
     const key = `${createId('artifact')}${ext}`;
-    await canvasBlobs(store.canvasId).put(key, buffer);
+    await space(store.canvasId).blobs.put(key, buffer);
     return key;
   } catch (err) {
     log.warn({ err, url }, 'Failed to download online node src into artifacts');
diff --git a/apps/server/src/modules/canvas/snapshot-nodes.ts b/apps/server/src/modules/canvas/snapshot-nodes.ts
index 9d79bbdc2..356f5c048 100644
--- a/apps/server/src/modules/canvas/snapshot-nodes.ts
+++ b/apps/server/src/modules/canvas/snapshot-nodes.ts
@@ -68,7 +68,7 @@ import {
 import { getSketchRenderedSize } from '@huabu/shared/canvas-engine';
 
 import { RASTERIZABLE_IMAGE_EXT_MIME } from '../../utils/mime.js';
-import { canvasBlobs, getCanvasStore } from '../storage/index.js';
+import { space, getCanvasStore } from '../storage/index.js';
 
 import type {
   SketchNodeData,
@@ -450,7 +450,7 @@ async function loadContextImage(
   if (!mimeType) return null;
   const { width, height } = nodeBoxSize(node);
   if (width <= 0 || height <= 0) return null;
-  const bytes = await canvasBlobs(store.canvasId).read(src);
+  const bytes = await space(store.canvasId).blobs.read(src);
   if (!bytes) return null;
   return { node, resolvedSrc: src, bytes, mimeType, width, height };
 }
@@ -799,7 +799,7 @@ async function maybeResizeImageArtifact(
   src: string,
   maxEdge: number,
 ): Promise<{ src: string; width: number; height: number } | null> {
-  const blobs = canvasBlobs(store.canvasId);
+  const blobs = space(store.canvasId).blobs;
   const ext = path.extname(src).toLowerCase();
   const mimeType = IMAGE_EXT_MIME[ext];
   if (!mimeType) return null;
@@ -1060,10 +1060,10 @@ export async function snapshotNodesToArtifacts(
         ? `sketch-raster-${fingerprint}`
         : `sketch-raster-${fingerprint}-${maxEdge}`;
     const filename = `${id}.png`;
-    const existing = await canvasBlobs(store.canvasId).head(filename);
+    const existing = await space(store.canvasId).blobs.head(filename);
     if (!existing) {
       const png = await renderClusterPng(built.svg, built.width);
-      await canvasBlobs(store.canvasId).put(filename, png);
+      await space(store.canvasId).blobs.put(filename, png);
     }
     results.push({
       src: filename,
diff --git a/apps/server/src/modules/interactive-view/interactive-view.route.ts b/apps/server/src/modules/interactive-view/interactive-view.route.ts
index 0e8124c97..a404fe0e8 100644
--- a/apps/server/src/modules/interactive-view/interactive-view.route.ts
+++ b/apps/server/src/modules/interactive-view/interactive-view.route.ts
@@ -20,7 +20,7 @@ import {
   interactiveViewService,
 } from './interactive-view.service.js';
 import { sendBlob } from '../artifact/send-blob.js';
-import { canvasBlobs } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type { FastifyPluginAsync } from 'fastify';
 
@@ -84,7 +84,7 @@ const interactiveViewRoutes: FastifyPluginAsync = async (app) => {
       const sent = await sendBlob(
         request,
         reply,
-        canvasBlobs(params.data.canvasId),
+        space(params.data.canvasId).blobs,
         resource.rendererArtifact,
       );
       if (!sent) {
diff --git a/apps/server/src/modules/interactive-view/interactive-view.service.ts b/apps/server/src/modules/interactive-view/interactive-view.service.ts
index 7d91903e9..251acdf3b 100644
--- a/apps/server/src/modules/interactive-view/interactive-view.service.ts
+++ b/apps/server/src/modules/interactive-view/interactive-view.service.ts
@@ -32,11 +32,7 @@ import {
   executeOnServer,
   type InteractiveViewConflict,
 } from '../canvas/canvas-executor.js';
-import {
-  canvasBlobs,
-  getCanvasStore,
-  getStructuredStore,
-} from '../storage/index.js';
+import { space, getCanvasStore, getStructuredStore } from '../storage/index.js';
 
 import type { FastifyBaseLogger } from 'fastify';
 
@@ -346,7 +342,7 @@ export class InteractiveViewService {
       : null;
     const rendererExists = request.rendererArtifact.startsWith('upload/')
       ? stagedPath !== null && existsSync(stagedPath)
-      : Boolean(await canvasBlobs(canvasId).head(request.rendererArtifact));
+      : Boolean(await space(canvasId).blobs.head(request.rendererArtifact));
     if (!rendererExists) {
       throw new InteractiveViewServiceError(
         'renderer_not_found',
diff --git a/apps/server/src/modules/preprocessing/dispatcher.ts b/apps/server/src/modules/preprocessing/dispatcher.ts
index c15fb02e2..1f1652bb2 100644
--- a/apps/server/src/modules/preprocessing/dispatcher.ts
+++ b/apps/server/src/modules/preprocessing/dispatcher.ts
@@ -14,7 +14,7 @@ import { isLabelProtected } from './label-policy.js';
 import { runPipeline, type PipelineDeps } from './pipeline.js';
 import { getProfile } from './profiles.js';
 import { ProviderManager } from './provider-manager.js';
-import { canvasBlobs, getStructuredStore } from '../storage/index.js';
+import { space, getStructuredStore } from '../storage/index.js';
 
 import type {
   Capability,
@@ -166,7 +166,7 @@ export class PreprocessDispatcher {
 
     const deps: PipelineDeps = {
       nodes: getStructuredStore().space(request.canvasId).nodes,
-      blobs: canvasBlobs(request.canvasId),
+      blobs: space(request.canvasId).blobs,
       provider: this.provider,
     };
 
diff --git a/apps/server/src/modules/remote_fs/interactive-view.rfs.test.ts b/apps/server/src/modules/remote_fs/interactive-view.rfs.test.ts
index 934ca5e9c..3f41c9b06 100644
--- a/apps/server/src/modules/remote_fs/interactive-view.rfs.test.ts
+++ b/apps/server/src/modules/remote_fs/interactive-view.rfs.test.ts
@@ -17,11 +17,7 @@ import {
   type AcpWorkloadSpec,
 } from '../agent/agenetes/drivers.js';
 import interactiveViewRoutes from '../interactive-view/interactive-view.route.js';
-import {
-  canvasBlobs,
-  getCanvasStore,
-  resetStorageCache,
-} from '../storage/index.js';
+import { space, getCanvasStore, resetStorageCache } from '../storage/index.js';
 import { canvasAcpNamespace } from '../workspace/paths.js';
 import { setWorkspacePath } from '../workspace.js';
 
@@ -220,7 +216,7 @@ describe('Interactive View RFS resources', () => {
         code: 'renderer_not_found',
       });
 
-      await canvasBlobs('c1').put('view.html', Buffer.from('<p>view</p>'));
+      await space('c1').blobs.put('view.html', Buffer.from('<p>view</p>'));
       const invalidState = await app.inject({
         method: 'POST',
         url: '/rfs/c1/interactive-views',
diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts
index 7fcd331b3..544b525fd 100644
--- a/apps/server/src/modules/remote_fs/rfs.route.test.ts
+++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts
@@ -56,11 +56,7 @@ import {
   agentThreadService,
 } from '../agent/agent-thread.service.js';
 import * as selectableProfiles from '../agent/selectable-agent-profile.js';
-import {
-  getCanvasStore,
-  resetStorageCache,
-  spaceDirectory,
-} from '../storage/index.js';
+import { getCanvasStore, resetStorageCache, space } from '../storage/index.js';
 import {
   RunCompletionError,
   runCompletionService,
@@ -72,6 +68,18 @@ import { setWorkspacePath } from '../workspace.js';
 import type { FixedAgentNodeTarget } from '../agent/agent-thread-resolver.js';
 import type { CanvasNodeId } from '@huabu/shared';
 
+/**
+ * The Space's Disk directory, or a test failure.
+ *
+ * These cases are Disk-specific by construction; the assertion states that
+ * rather than letting an optional-chained `undefined` quietly pass.
+ */
+function diskDirOf(canvasId: string): string {
+  const tree = space(canvasId).diskTree;
+  if (!tree) throw new Error('Expected the Disk backend in this test');
+  return tree.directory();
+}
+
 let tmp: string;
 
 async function buildApp() {
@@ -159,7 +167,7 @@ describe('GET /api/rfs/:canvasId/skill', () => {
   it('returns only the bundled root guide without authorization', async () => {
     seedNote('c1', 'node-1', 'Anchor', 'content');
     writeFileSync(
-      join(spaceDirectory('c1'), 'skill.md'),
+      join(diskDirOf('c1'), 'skill.md'),
       '# Private Space Override',
       'utf8',
     );
diff --git a/apps/server/src/modules/remote_fs/skill.ts b/apps/server/src/modules/remote_fs/skill.ts
index 7dcbb5c97..213dd690a 100644
--- a/apps/server/src/modules/remote_fs/skill.ts
+++ b/apps/server/src/modules/remote_fs/skill.ts
@@ -15,7 +15,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { renderPromptFile } from '../../prompt/agents/loader.js';
-import { spaceDirectory } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 /** PROMPT-ROOT-relative path of the bundled access guide. */
 const ACCESS_GUIDE_TEMPLATE = 'external-agent/access-huabu.md';
@@ -40,9 +40,16 @@ export function resolveBundledRootSkill(): string {
  * markdown text (served with `Content-Type: text/markdown`).
  */
 export function resolveCanvasSkill(canvasId: string): string {
-  const override = path.join(spaceDirectory(canvasId), 'skill.md');
-  if (existsSync(override)) {
-    return readFileSync(override, 'utf8');
+  // A user-authored override read from the Space root. Disposition D
+  // (proposal §6.4.3): it becomes a blob under its own scope kind, at which
+  // point this reads through the port and the branch goes away. Until then a
+  // backend without a directory simply has no override to find.
+  const tree = space(canvasId).diskTree;
+  if (tree) {
+    const override = path.join(tree.directory(), 'skill.md');
+    if (existsSync(override)) {
+      return readFileSync(override, 'utf8');
+    }
   }
   return resolveBundledRootSkill();
 }
diff --git a/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts b/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
index d020fd9bd..7d9b5d429 100644
--- a/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
@@ -1288,7 +1288,7 @@ export class CanvasStore {
   // ── Artifacts ────────────────────────────────────────────────────────────
   //
   // Artifact bytes are NOT owned here. They live behind the `BlobStore`
-  // port — `canvasBlobs(canvasId)` in `storage.js` — so this store holds
+  // port — `space(canvasId).blobs` in `storage.js` — so this store holds
   // structured records only and a non-filesystem blob backend can be
   // configured independently. See docs/proposals/multi-backend-storage.md.
 
diff --git a/apps/server/src/modules/storage/backends/disk/space-tree.ts b/apps/server/src/modules/storage/backends/disk/space-tree.ts
new file mode 100644
index 000000000..a11e1fb01
--- /dev/null
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.ts
@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * The Disk backend's real directory for one Space.
+ *
+ * **Not a port, and deliberately not in `ports/`.** `StructuredStore` and
+ * `BlobStore` are the whole portable surface. A Space directory is Disk's, and
+ * a backend that keeps Spaces in tables does not have one; making every
+ * backend promise a directory would mean fabricating one, which moves the
+ * failure somewhere less obvious than the refusal
+ * (docs/proposals/multi-backend-storage.md §6.4.1, §12.6.2).
+ *
+ * It reaches consumers as `space(canvasId).diskTree`, typed by its absence —
+ * `null` on any other backend — so a caller is told the truth once, at the
+ * same handle it asks every other storage question. The fence that keeps an
+ * unportable capability from reading as a portable one is the name and the
+ * enumerated consumer list in `module-boundaries.test.ts`, not the shape of
+ * the accessor.
+ */
+
+import { canvasRoot } from './layout.js';
+
+export interface DiskSpaceTree {
+  readonly canvasId: string;
+  /**
+   * Absolute path to this Space's directory in the active Workspace.
+   *
+   * A method rather than a property because it is not a constant: the
+   * directory name is derived from the Space's title, so a Finder-side rename
+   * moves it, and a Workspace switch invalidates it entirely. Resolving per
+   * call keeps a retained tree from handing back a path that was true when the
+   * handle was made. It raises rather than improvising when the id is
+   * malformed or the resolved path escapes the Workspace.
+   */
+  directory(): string;
+}
+
+export function diskSpaceTree(canvasId: string): DiskSpaceTree {
+  return {
+    canvasId,
+    directory: () => canvasRoot(canvasId),
+  };
+}
diff --git a/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts b/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
index 26bac81f9..3f02d662b 100644
--- a/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
@@ -32,11 +32,7 @@ import {
   resetStorageCache,
 } from './legacy/canvas-store-cache.js';
 import { DiskStructuredStore } from './structured-store.js';
-import {
-  canvasBlobs,
-  createStorage,
-  setStorageForTesting,
-} from '../../storage.js';
+import { space, createStorage, setStorageForTesting } from '../../storage.js';
 
 import type { CanvasFile } from '../../../canvas/persistence-types.js';
 
@@ -468,7 +464,7 @@ describe('Space lifecycle guards and reopen', () => {
       handle.changes.append('thread-1', [change('n1')]),
     ).rejects.toThrow(/missing Space/);
     await expect(
-      canvasBlobs('missing-space').put('x.bin', rejectedBuffer),
+      space('missing-space').blobs.put('x.bin', rejectedBuffer),
     ).rejects.toThrow(/missing Space/);
 
     expect(rejectedBuffer.toString()).toBe('x');
@@ -480,7 +476,7 @@ describe('Space lifecycle guards and reopen', () => {
     const ended = once(body, 'end');
 
     await expect(
-      canvasBlobs('missing-stream-space').put('x.bin', body),
+      space('missing-stream-space').blobs.put('x.bin', body),
     ).rejects.toThrow(/missing Space/);
     await ended;
 
@@ -505,7 +501,7 @@ describe('Space lifecycle guards and reopen', () => {
     const storedChanges = await first.changes.append('thread-1', [
       change('n1'),
     ]);
-    await canvasBlobs('reopen').put('payload.bin', Buffer.from('persisted'));
+    await space('reopen').blobs.put('payload.bin', Buffer.from('persisted'));
 
     resetStorageCache();
     const reopened = new DiskStructuredStore().space('reopen');
@@ -516,7 +512,7 @@ describe('Space lifecycle guards and reopen', () => {
       7,
     ]);
     expect(await reopened.changes.read('thread-1')).toEqual(storedChanges);
-    expect((await canvasBlobs('reopen').read('payload.bin'))?.toString()).toBe(
+    expect((await space('reopen').blobs.read('payload.bin'))?.toString()).toBe(
       'persisted',
     );
   });
diff --git a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
index cbcda58cc..741182470 100644
--- a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
+++ b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
@@ -21,10 +21,10 @@ import { resetStorageCache } from '../backends/disk/legacy/canvas-store-cache.js
 import { DiskStructuredStore } from '../backends/disk/structured-store.js';
 import { getCanvasStore } from '../index.js';
 import {
-  canvasBlobs,
+  composeStorage,
+  space,
   deleteSpace,
   setStorageForTesting,
-  type Storage,
 } from '../storage.js';
 
 import type {
@@ -195,11 +195,13 @@ let restoreStorage: () => void;
 
 function installBlobStore(next: BlobStore): void {
   restoreStorage();
-  restoreStorage = setStorageForTesting({
-    profile: { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
-    structured: new DiskStructuredStore(),
-    blobs: next,
-  } satisfies Storage);
+  restoreStorage = setStorageForTesting(
+    composeStorage(
+      { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
+      new DiskStructuredStore(),
+      next,
+    ),
+  );
 }
 
 beforeEach(() => {
@@ -211,11 +213,13 @@ beforeEach(() => {
   resetStorageCache();
 
   blobs = new OrderRecordingBlobStore();
-  restoreStorage = setStorageForTesting({
-    profile: { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
-    structured: new DiskStructuredStore(),
-    blobs,
-  } satisfies Storage);
+  restoreStorage = setStorageForTesting(
+    composeStorage(
+      { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
+      new DiskStructuredStore(),
+      blobs,
+    ),
+  );
 });
 
 afterEach(() => {
@@ -309,7 +313,7 @@ describe('deleteSpace composition', () => {
     controlled.blockPuts = true;
     installBlobStore(controlled);
 
-    const putting = canvasBlobs('canvas-a').put(
+    const putting = space('canvas-a').blobs.put(
       'in-flight.bin',
       Buffer.from('bytes'),
     );
@@ -349,7 +353,7 @@ describe('deleteSpace composition', () => {
     const deleting = deleteSpace('canvas-a');
     await controlled.deleteStarted.promise;
     expect(workspaceState.leaseCount).toBe(1);
-    const putting = canvasBlobs('canvas-a').put(
+    const putting = space('canvas-a').blobs.put(
       'too-late.bin',
       Buffer.from('orphan'),
     );
@@ -462,8 +466,8 @@ describe('deleteSpace composition', () => {
     controlled.blockPuts = true;
     installBlobStore(controlled);
 
-    const first = canvasBlobs('canvas-a').put('first.bin', Buffer.from('1'));
-    const second = canvasBlobs('canvas-a').put('second.bin', Buffer.from('2'));
+    const first = space('canvas-a').blobs.put('first.bin', Buffer.from('1'));
+    const second = space('canvas-a').blobs.put('second.bin', Buffer.from('2'));
 
     await vi.waitFor(() => expect(controlled.putCalls).toBe(2));
     controlled.releasePuts();
@@ -484,7 +488,7 @@ describe('deleteSpace composition', () => {
     await controlled.deleteStarted.promise;
 
     await expect(
-      canvasBlobs('canvas-b').put('independent.bin', Buffer.from('free')),
+      space('canvas-b').blobs.put('independent.bin', Buffer.from('free')),
     ).resolves.toMatchObject({ name: 'independent.bin' });
     expect(existsSync(artifactPath('canvas-b', 'independent.bin'))).toBe(true);
 
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index e1bca057d..9b4abed8e 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -61,7 +61,7 @@ export type {
 // ─── Storage ports and composition ─────────────────────────────────────────
 
 export {
-  canvasBlobs,
+  composeStorage,
   createSpace,
   createStorage,
   deleteSpace,
@@ -70,10 +70,11 @@ export {
   getStructuredStore,
   initStorage,
   setStorageForTesting,
-  spaceDirectory,
+  space,
   storageHealth,
 } from './storage.js';
-export type { SpaceDeleteOutcome, Storage } from './storage.js';
+export type { Space, SpaceDeleteOutcome, Storage } from './storage.js';
+export type { DiskSpaceTree } from './backends/disk/space-tree.js';
 export {
   parseStorageProfile,
   StorageProfileError,
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index 80fdca34e..628415e20 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -282,6 +282,64 @@ describe('workspace module names no backend', () => {
   });
 });
 
+/**
+ * The Disk Space directory, fenced by name and by census (proposal §12.6.2).
+ *
+ * `diskTree` is not a port and is not portable: a backend that keeps Spaces in
+ * tables has no directory, and the member is typed by that absence. What keeps
+ * an unportable capability from reading as a portable one is not where it
+ * hangs — it is on the Space handle, beside everything else about a Space —
+ * but its name and the fact that every consumer is written down here.
+ *
+ * This list may shrink and must not grow. Each entry is a family §6.4.3
+ * assigns a disposition: the **A** families stay and become capability-matrix
+ * rows, and the rest leave as they move onto a port.
+ */
+describe('Disk Space tree capability', () => {
+  const EXPECTED_CONSUMERS = [
+    // A — the built-in file tools' sandbox root.
+    'modules/agent/tools/handlers/fs-sandbox.ts',
+    // A — bundle export.
+    'modules/canvas/canvas.route.ts',
+    // A — external-note claim.
+    'modules/canvas/external.route.ts',
+    // C — the resurrection guard, which disappears with the substrate.
+    'modules/agent/memory/trigger.ts',
+    // D — the per-Space RFS access guide, headed for a blob.
+    'modules/remote_fs/skill.ts',
+    // C and D — memory files, the debug prompt log, ACP session state.
+    'modules/workspace/paths.ts',
+  ].sort();
+
+  it('keeps the exact production consumer census', () => {
+    const consumers = sourceFiles
+      .filter((file) => !file.startsWith('modules/storage/'))
+      .filter((file) => !file.endsWith('.test.ts'))
+      .filter((file) => /\.diskTree\b/.test(read(file)));
+
+    expect(consumers.sort()).toEqual(EXPECTED_CONSUMERS);
+  });
+
+  it('exposes no portable path accessor from the barrel', () => {
+    const barrel = read('modules/storage/index.ts');
+
+    // A Space's directory is reachable only through the Disk-named member on
+    // the Space handle. A free `spaceDirectory()`-shaped export would read as
+    // something every backend answers, which is the claim being prevented.
+    expect(barrel).not.toMatch(/\bspaceDirectory\b/);
+    expect(barrel).toMatch(/\bDiskSpaceTree\b/);
+  });
+
+  it('names Disk at the type, so a consumer cannot mistake it for a port', () => {
+    const tree = read('modules/storage/backends/disk/space-tree.ts');
+
+    expect(tree).toMatch(/export interface DiskSpaceTree/);
+    // Living under `backends/disk/` is what the `ports/` census already
+    // guarantees; this states the intent the file exists to carry.
+    expect(tree).toMatch(/not a port/i);
+  });
+});
+
 describe('structured write authority', () => {
   it('does not expose compatibility create/delete writers from the public barrel', () => {
     expect(read('modules/storage/index.ts')).not.toMatch(
diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts
index c11a93e0b..bbe024fb9 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -28,7 +28,7 @@ import {
   getWorkspacePath,
 } from '../workspace.js';
 import { DiskBlobStore } from './backends/disk/blob-store.js';
-import { canvasRoot } from './backends/disk/layout.js';
+import { diskSpaceTree } from './backends/disk/space-tree.js';
 import { DiskStructuredStore } from './backends/disk/structured-store.js';
 import {
   parseStorageProfile,
@@ -39,6 +39,7 @@ import {
 } from './profile.js';
 import { withSpacePutAdmission } from './space-lifecycle-admission.js';
 
+import type { DiskSpaceTree } from './backends/disk/space-tree.js';
 import type {
   BlobInfo,
   BlobLease,
@@ -51,6 +52,7 @@ import type { StorageHealth } from './ports/common.js';
 import type {
   SpaceCreateResult,
   SpaceDeleteFinishResult,
+  SpaceHandle,
   StructuredStore,
 } from './ports/structured.js';
 import type { Readable } from 'node:stream';
@@ -99,6 +101,70 @@ export interface Storage {
   readonly profile: StorageProfile;
   readonly structured: StructuredStore;
   readonly blobs: BlobStore;
+  /**
+   * Every storage capability for one Space, from one call.
+   *
+   * A Space's durable state spans both ports — its record and nodes are
+   * structured, its files are bytes — so the application reaches all of it
+   * through one object rather than remembering which axis holds what
+   * (§6.4.1).
+   */
+  space(canvasId: string): Space;
+}
+
+/**
+ * One Space across every axis that holds part of it.
+ *
+ * A **composition-layer facade, not a port type**. `StructuredStore.space()`
+ * keeps returning the structured-only {@link SpaceHandle}, `BlobStore.scope()`
+ * keeps returning a {@link BlobScope}, and neither port imports the other.
+ * They are joined here because this is the only object in the process that
+ * holds both, and because this layer already owns every cross-store rule: the
+ * blob-put precondition and the blob-first delete saga.
+ *
+ * The join cannot move down into a port. The two axes are configured
+ * independently, so a `SpaceHandle` that vended blobs would oblige the Disk
+ * structured adapter to construct an Azure blob scope; deletion ordering
+ * deliberately keeps remote blob I/O outside any database transaction; and
+ * `BlobScopeRef` covers scopes that have no Space at all, which a blob store
+ * reachable only through a Space handle could not serve.
+ */
+export interface Space extends SpaceHandle {
+  /**
+   * This Space's blobs, with the cross-store precondition applied.
+   *
+   * Bytes may only be added to a Space whose record exists. Reads and
+   * `deleteAll()` stay available for cleanup when a record has already gone.
+   */
+  readonly blobs: BlobScope;
+  /**
+   * Disk's directory for this Space. `null` on every other backend.
+   *
+   * A capability only some backends implement, named for the backend that has
+   * it and typed by its absence — not hidden behind a parallel free function,
+   * and not a stub that throws. A caller branching on `null` is told the truth
+   * once; a caller that must remember a second import is being asked to know
+   * this module's internal topology.
+   */
+  readonly diskTree: DiskSpaceTree | null;
+}
+
+function composeSpace(storage: Storage, canvasId: string): Space {
+  const handle = storage.structured.space(canvasId);
+  return {
+    canvasId: handle.canvasId,
+    read: () => handle.read(),
+    write: (input) => handle.write(input),
+    nodes: handle.nodes,
+    changes: handle.changes,
+    tasks: handle.tasks,
+    events: handle.events,
+    blobs: guardedBlobScope(storage, canvasId),
+    diskTree:
+      storage.profile.structured.kind === 'disk'
+        ? diskSpaceTree(canvasId)
+        : null,
+  };
 }
 
 function buildBlobStore(profile: StorageProfile): BlobStore {
@@ -122,14 +188,42 @@ function buildStructuredStore(profile: StorageProfile): StructuredStore {
   }
 }
 
+/**
+ * Assemble a {@link Storage} from connections the caller already holds.
+ *
+ * Does not validate the profile and opens nothing — it only wires the Space
+ * facade over two given stores. Exists so anything holding its own
+ * connections composes the same facade the process does, rather than a
+ * partial object literal that would go stale the next time {@link Storage}
+ * gains a member.
+ */
+export function composeStorage(
+  profile: StorageProfile,
+  structured: StructuredStore,
+  blobs: BlobStore,
+): Storage {
+  return {
+    profile,
+    structured,
+    blobs,
+    // Composes from the receiver, not from a captured local. Substituting one
+    // axis by spreading — `{...storage, blobs: fake}` — is the obvious way to
+    // stub a backend, and a closure over the original object would hand that
+    // copy Spaces built on the stores it just replaced, silently.
+    space(this: Storage, canvasId: string): Space {
+      return composeSpace(this, canvasId);
+    },
+  };
+}
+
 /** Validate a profile and construct both connections. Does not `init()`. */
 export function createStorage(profile: StorageProfile): Storage {
   validateStorageProfile(profile);
-  return {
+  return composeStorage(
     profile,
-    structured: buildStructuredStore(profile),
-    blobs: buildBlobStore(profile),
-  };
+    buildStructuredStore(profile),
+    buildBlobStore(profile),
+  );
 }
 
 // ─── Process-wide holder ────────────────────────────────────────────────────
@@ -265,15 +359,18 @@ export async function deleteSpace(
 }
 
 /**
- * Blob scope for one Space — the only scope kind today.
+ * Blob scope for one Space, with the cross-store precondition applied.
  *
  * The raw BlobStore intentionally knows nothing about structured lifecycle,
  * so composition owns the one cross-store invariant: bytes may only be added
  * to a Space whose record exists. Reads and `deleteAll()` stay available for
  * cleanup/recovery when a record has already gone missing.
+ *
+ * Takes its {@link Storage} rather than resolving the process-wide holder, so
+ * one Space facade is composed entirely from the connections it was built
+ * against — a scope that re-resolved the holder could outlive them.
  */
-export function canvasBlobs(canvasId: string): BlobScope {
-  const storage = ensure();
+function guardedBlobScope(storage: Storage, canvasId: string): BlobScope {
   const workspacePath = activeWorkspacePath();
   const delegate = storage.blobs.scope({ kind: 'canvas', canvasId });
 
@@ -332,22 +429,15 @@ export async function storageHealth(): Promise<StorageHealth[]> {
 }
 
 /**
- * The real directory backing a Space — the materialization capability.
- *
- * Some consumers genuinely need a filesystem path rather than a record: an
- * ACP agent needs a working directory, the external watcher needs something
- * to watch, RFS exposes a tree. That is a product requirement, not a leak
- * (proposal §12.5.4), and it is the Space-level counterpart to
- * `BlobScope.materialize()`.
+ * Every storage capability for one Space — the shorthand call sites use.
  *
- * It lives in the composition root because only this module may ask a named
- * backend where anything is. Every profile selectable today materializes, so
- * this resolves unconditionally; a backend that stores Spaces without a
- * directory would refuse here rather than hand back a path that does not
- * exist.
+ * Exactly `getStorage().space(canvasId)`, and an ergonomic spelling of the
+ * same method rather than a second design. One function answers every storage
+ * question about a Space: its record, its nodes, its logs, its Tasks, its
+ * bytes, and — where the backend has one — its directory.
  */
-export function spaceDirectory(canvasId: string): string {
-  return canvasRoot(canvasId);
+export function space(canvasId: string): Space {
+  return ensure().space(canvasId);
 }
 
 /**
diff --git a/apps/server/src/modules/workspace/legacy-workspace-activation.test.ts b/apps/server/src/modules/workspace/legacy-workspace-activation.test.ts
index 756569b33..0842b1708 100644
--- a/apps/server/src/modules/workspace/legacy-workspace-activation.test.ts
+++ b/apps/server/src/modules/workspace/legacy-workspace-activation.test.ts
@@ -5,7 +5,7 @@
  * End-to-end activation of a legacy workspace, over the production routes.
  *
  * Phase 4.5 moved the Disk record layout inside the storage boundary and
- * routed every "where is this Space" question through `spaceDirectory()`. This
+ * routed every "where is this Space" question through one accessor. This
  * suite exists to prove that the move did not change what the app can read or
  * write. It does not test a module — it activates a workspace the way a launch
  * does (`setWorkspacePath` → `prepareWorkspaceOnDisk` → every migration) and
@@ -57,11 +57,23 @@ import agentRoutes from '../agent/agent.route.js';
 import artifactRoute from '../artifact/artifact.route.js';
 import canvasRoutes from '../canvas/canvas.route.js';
 import { createCanvas } from '../storage/compatibility/canvas.js';
-import { resetStorageCache, spaceDirectory } from '../storage/index.js';
+import { resetStorageCache, space } from '../storage/index.js';
 import { setWorkspacePath } from '../workspace.js';
 
 import type { FastifyInstance } from 'fastify';
 
+/**
+ * The Space's Disk directory, or a test failure.
+ *
+ * These cases are Disk-specific by construction; the assertion states that
+ * rather than letting an optional-chained `undefined` quietly pass.
+ */
+function diskDirOf(canvasId: string): string {
+  const tree = space(canvasId).diskTree;
+  if (!tree) throw new Error('Expected the Disk backend in this test');
+  return tree.directory();
+}
+
 /** The Space under test: title-derived directory name ≠ canvasId. */
 const CANVAS_ID = 'legacy-space-1';
 const SPACE_TITLE = 'Legacy Space';
@@ -203,7 +215,7 @@ async function seedLegacyWorkspace(): Promise<void> {
   }
 
   // A legacy artifact, in the layout the Disk backend has always used.
-  const spaceDir = spaceDirectory(CANVAS_ID);
+  const spaceDir = diskDirOf(CANVAS_ID);
   mkdirSync(join(spaceDir, '.artifacts'), { recursive: true });
   writeFileSync(
     join(spaceDir, '.artifacts', 'art_legacy.txt'),
@@ -408,7 +420,7 @@ describe('activating a legacy workspace on the new storage boundary', () => {
 
       // 2. Execute a real command batch that imports a staged local file into
       //    the artifact store through the blob port.
-      const uploadDir = join(spaceDirectory(CANVAS_ID), '.upload');
+      const uploadDir = join(diskDirOf(CANVAS_ID), '.upload');
       mkdirSync(uploadDir, { recursive: true });
       writeFileSync(join(uploadDir, 'fresh.txt'), 'freshly imported bytes');
       const exec = await app.inject({
diff --git a/apps/server/src/modules/workspace/paths.ts b/apps/server/src/modules/workspace/paths.ts
index 773816e27..de4407ae4 100644
--- a/apps/server/src/modules/workspace/paths.ts
+++ b/apps/server/src/modules/workspace/paths.ts
@@ -11,7 +11,7 @@
  *     Untouched by a backend switch.
  *   - Per-Space state owned by *other* domains — memory, ACP sessions, the
  *     debug prompt log — which need a materialized directory but not the Disk
- *     record layout. They anchor on `spaceDirectory()` from the storage
+ *     record layout. They anchor on the Space's Disk tree from the storage
  *     facade, so they no longer consult the Disk name index (§12.5.4).
  *
  * The Disk record and blob layout moved to `storage/backends/disk/layout.ts`.
@@ -36,7 +36,7 @@
 import path from 'node:path';
 
 import { sanitizeId } from '../../utils/fs.js';
-import { spaceDirectory } from '../storage/index.js';
+import { space } from '../storage/index.js';
 import { getWorkspacePath } from '../workspace.js';
 
 import type { Namespace } from '@agenetes/protocol';
@@ -49,8 +49,28 @@ import type { Namespace } from '@agenetes/protocol';
  */
 const LEGACY_HISTORY_DIR_NAME = '.history';
 
+/**
+ * The Space's real directory, or a refusal.
+ *
+ * Every path this module builds is for a family Phase 4.6 relocates — memory
+ * state and the debug prompt log to the extension substrate, the memory body
+ * to a blob, ACP sessions with phase 6 (proposal §6.4.3). Until then they are
+ * bare files, so one branch here says once what each of them would otherwise
+ * repeat: these paths exist only where the backend has a tree.
+ */
+function spaceRoot(canvasId: string): string {
+  const tree = space(canvasId).diskTree;
+  if (!tree) {
+    throw new Error(
+      `Per-Space files for "${canvasId}" need a Space directory, which the ` +
+        'active structured backend does not provide.',
+    );
+  }
+  return tree.directory();
+}
+
 function legacyHistoryDir(canvasId: string): string {
-  return path.join(spaceDirectory(canvasId), LEGACY_HISTORY_DIR_NAME);
+  return path.join(spaceRoot(canvasId), LEGACY_HISTORY_DIR_NAME);
 }
 
 // ─── Memory module paths ───────────────────────────────────────────────────
@@ -71,7 +91,7 @@ export function workspaceMemoryPath(): string {
 export const WORKING_MEMORY_DIR_NAME = '.memory';
 
 export function canvasMemoryDir(canvasId: string): string {
-  return path.join(spaceDirectory(canvasId), WORKING_MEMORY_DIR_NAME);
+  return path.join(spaceRoot(canvasId), WORKING_MEMORY_DIR_NAME);
 }
 
 /** Working memory body for a canvas. */

From 29388969c5149eecb5591cc6745070152b11128f Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 17:14:15 +0800
Subject: [PATCH 04/20] refactor(agent): read Agent-thread targets through the
 ports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The thread resolver and RFS node lookup reached the legacy Disk store for
both the Space record and node content. Both now go through
`space(canvasId)`, which makes the resolver chain async up to its already-
async callers: the RFS route, the agent route, and the interactive-view
owner-thread check.

RFS's file → node mapping does not become portable, and should not. Every
backend could mint `nodes/<label>.md` from records, but Disk inverts the
*real* filename, because the file is really there and a user may have
renamed it; the two agree only when nothing has touched the directory from
outside, which is the one case Disk cannot assume. So it moves onto
`diskTree.nodeIdForPath()` — named for the backend that has it, and listed
in the census as disposition B, deferred (§6.4.3). The record and the
sidecar around it come from the ports.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../agent/agent-thread-resolver.test.ts       | 44 ++++++++++---------
 .../modules/agent/agent-thread-resolver.ts    | 29 ++++++------
 .../agent/agent-thread.service.test.ts        | 16 +++----
 .../src/modules/agent/agent-thread.service.ts | 14 +++---
 apps/server/src/modules/agent/agent.route.ts  |  2 +-
 .../interactive-view.service.ts               | 10 ++---
 .../server/src/modules/remote_fs/node-meta.ts | 27 ++++++------
 .../src/modules/remote_fs/rfs.route.test.ts   | 32 +++++++++-----
 .../server/src/modules/remote_fs/rfs.route.ts | 11 +++--
 .../storage/backends/disk/space-tree.ts       | 28 ++++++++++++
 .../modules/storage/module-boundaries.test.ts |  3 ++
 11 files changed, 135 insertions(+), 81 deletions(-)

diff --git a/apps/server/src/modules/agent/agent-thread-resolver.test.ts b/apps/server/src/modules/agent/agent-thread-resolver.test.ts
index 20f1a9b5b..21c3dbe5e 100644
--- a/apps/server/src/modules/agent/agent-thread-resolver.test.ts
+++ b/apps/server/src/modules/agent/agent-thread-resolver.test.ts
@@ -16,8 +16,8 @@ function createResolver(
   content = '',
 ) {
   return new AgentThreadResolver({
-    readCanvasNodes: () => nodes,
-    readNodeContent: () => content,
+    readCanvasNodes: async () => nodes,
+    readNodeContent: async () => content,
   });
 }
 
@@ -41,8 +41,8 @@ const FIXED_NODE = {
 };
 
 describe('AgentThreadResolver', () => {
-  it('resolves a fixed external Agent Node from Canvas storage', () => {
-    const target = createResolver(
+  it('resolves a fixed external Agent Node from Canvas storage', async () => {
+    const target = await createResolver(
       [FIXED_NODE],
       'Existing prompt',
     ).resolveFixedAgentNode('canvas-a', 'thread-a');
@@ -65,36 +65,36 @@ describe('AgentThreadResolver', () => {
     });
   });
 
-  it('falls back for selectable or unrelated threads', () => {
+  it('falls back for selectable or unrelated threads', async () => {
     const selectable = {
       ...FIXED_NODE,
       data: { ...FIXED_NODE.data, agentBindingPolicy: 'selectable' },
     };
-    expect(
+    await expect(
       createResolver([selectable]).resolveFixedAgentNode(
         'canvas-a',
         'thread-a',
       ),
-    ).toBeNull();
-    expect(
+    ).resolves.toBeNull();
+    await expect(
       createResolver([FIXED_NODE]).resolveFixedAgentNode(
         'canvas-a',
         'thread-other',
       ),
-    ).toBeNull();
+    ).resolves.toBeNull();
   });
 
-  it('resolves any Question Node as a possible parent', () => {
+  it('resolves any Question Node as a possible parent', async () => {
     const selectable = {
       ...FIXED_NODE,
       data: { ...FIXED_NODE.data, agentBindingPolicy: 'selectable' },
     };
-    expect(
+    await expect(
       createResolver([selectable]).resolveAgentNodeId('canvas-a', 'thread-a'),
-    ).toBe('node-agent');
+    ).resolves.toBe('node-agent');
   });
 
-  it('resolves a Huabu Agent binding for invocation', () => {
+  it('resolves a Huabu Agent binding for invocation', async () => {
     const internal = {
       ...FIXED_NODE,
       data: {
@@ -103,19 +103,23 @@ describe('AgentThreadResolver', () => {
       },
     };
     expect(
-      createResolver([internal]).resolveFixedAgentNode('canvas-a', 'thread-a')
-        ?.agentBinding,
+      (
+        await createResolver([internal]).resolveFixedAgentNode(
+          'canvas-a',
+          'thread-a',
+        )
+      )?.agentBinding,
     ).toEqual({ kind: 'internal' });
   });
 
-  it('rejects duplicate threads and corrupt fixed-node metadata', () => {
+  it('rejects duplicate threads and corrupt fixed-node metadata', async () => {
     const duplicateResolver = createResolver([
       FIXED_NODE,
       { ...FIXED_NODE, id: 'node-agent-2' },
     ]);
-    expect(() =>
+    await expect(
       duplicateResolver.resolveFixedAgentNode('canvas-a', 'thread-a'),
-    ).toThrowError(
+    ).rejects.toThrowError(
       expect.objectContaining<Partial<AgentThreadResolutionError>>({
         code: 'duplicate_thread',
       }),
@@ -124,9 +128,9 @@ describe('AgentThreadResolver', () => {
     const corruptResolver = createResolver([
       { ...FIXED_NODE, data: { ...FIXED_NODE.data, agentBinding: null } },
     ]);
-    expect(() =>
+    await expect(
       corruptResolver.resolveFixedAgentNode('canvas-a', 'thread-a'),
-    ).toThrowError(
+    ).rejects.toThrowError(
       expect.objectContaining<Partial<AgentThreadResolutionError>>({
         code: 'invalid_binding',
       }),
diff --git a/apps/server/src/modules/agent/agent-thread-resolver.ts b/apps/server/src/modules/agent/agent-thread-resolver.ts
index b8afef64e..f1a44ecb7 100644
--- a/apps/server/src/modules/agent/agent-thread-resolver.ts
+++ b/apps/server/src/modules/agent/agent-thread-resolver.ts
@@ -14,7 +14,7 @@ import {
   InvalidAgentLaunchOverridesError,
   parseAgentLaunchOverrides,
 } from './agent-launch-overrides.js';
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 interface StoredNode {
   id: string;
@@ -23,8 +23,8 @@ interface StoredNode {
 }
 
 interface ResolverDependencies {
-  readCanvasNodes: (canvasId: string) => StoredNode[] | null;
-  readNodeContent: (canvasId: string, nodeId: string) => string | null;
+  readCanvasNodes: (canvasId: string) => Promise<StoredNode[] | null>;
+  readNodeContent: (canvasId: string, nodeId: string) => Promise<string | null>;
 }
 
 export interface FixedAgentNodeTarget {
@@ -55,12 +55,12 @@ export class AgentThreadResolutionError extends Error {
 }
 
 const DEFAULT_DEPENDENCIES: ResolverDependencies = {
-  readCanvasNodes: (canvasId) => {
-    const canvas = getCanvasStore(canvasId).read();
+  readCanvasNodes: async (canvasId) => {
+    const canvas = await space(canvasId).read();
     return canvas ? (canvas.state.nodes as StoredNode[]) : null;
   },
-  readNodeContent: (canvasId, nodeId) =>
-    getCanvasStore(canvasId).readNode(nodeId)?.content ?? null,
+  readNodeContent: async (canvasId, nodeId) =>
+    (await space(canvasId).nodes.read(nodeId))?.record.content ?? null,
 };
 
 /**
@@ -74,8 +74,11 @@ export class AgentThreadResolver {
     private readonly dependencies: ResolverDependencies = DEFAULT_DEPENDENCIES,
   ) {}
 
-  resolveAgentNodeId(canvasId: string, threadId: string): CanvasNodeId | null {
-    const nodes = this.dependencies.readCanvasNodes(canvasId);
+  async resolveAgentNodeId(
+    canvasId: string,
+    threadId: string,
+  ): Promise<CanvasNodeId | null> {
+    const nodes = await this.dependencies.readCanvasNodes(canvasId);
     if (!nodes) {
       throw new AgentThreadResolutionError(
         'canvas_not_found',
@@ -93,11 +96,11 @@ export class AgentThreadResolver {
     return node?.type === 'question' ? (node.id as CanvasNodeId) : null;
   }
 
-  resolveFixedAgentNode(
+  async resolveFixedAgentNode(
     canvasId: string,
     threadId: string,
-  ): FixedAgentNodeTarget | null {
-    const nodes = this.dependencies.readCanvasNodes(canvasId);
+  ): Promise<FixedAgentNodeTarget | null> {
+    const nodes = await this.dependencies.readCanvasNodes(canvasId);
     if (!nodes) {
       throw new AgentThreadResolutionError(
         'canvas_not_found',
@@ -145,7 +148,7 @@ export class AgentThreadResolver {
       throw error;
     }
 
-    const content = this.dependencies.readNodeContent(canvasId, node.id);
+    const content = await this.dependencies.readNodeContent(canvasId, node.id);
     if (content === null) {
       throw new AgentThreadResolutionError(
         'missing_node_content',
diff --git a/apps/server/src/modules/agent/agent-thread.service.test.ts b/apps/server/src/modules/agent/agent-thread.service.test.ts
index d1bfcc7c9..3d5232558 100644
--- a/apps/server/src/modules/agent/agent-thread.service.test.ts
+++ b/apps/server/src/modules/agent/agent-thread.service.test.ts
@@ -106,7 +106,7 @@ function createHarness(options?: {
     return emptyInternalStream();
   });
   const service = new AgentThreadService({
-    resolveFixedAgentNode: () =>
+    resolveFixedAgentNode: async () =>
       options && 'target' in options ? (options.target ?? null) : TARGET,
     resolvePersistedExternalBinding: () =>
       options && 'persistedBinding' in options
@@ -164,7 +164,7 @@ describe('AgentThreadService', () => {
     expect(externalBindingFromWorkloadSpec({ binding: {} })).toBeNull();
   });
 
-  it('resolves a persisted external Thread without a fixed Agent Node', () => {
+  it('resolves a persisted external Thread without a fixed Agent Node', async () => {
     const binding = {
       kind: 'external' as const,
       profileId: 'profile-selectable',
@@ -172,12 +172,12 @@ describe('AgentThreadService', () => {
     };
     const harness = createHarness({ target: null, persistedBinding: binding });
 
-    expect(
+    await expect(
       harness.service.resolveExternalTarget('canvas-a', 'thread-a'),
-    ).toEqual({ binding, fixedTarget: null });
+    ).resolves.toEqual({ binding, fixedTarget: null });
   });
 
-  it('prefers the fixed Agent Node binding when one exists', () => {
+  it('prefers the fixed Agent Node binding when one exists', async () => {
     const harness = createHarness({
       persistedBinding: {
         kind: 'external',
@@ -186,9 +186,9 @@ describe('AgentThreadService', () => {
       },
     });
 
-    expect(
+    await expect(
       harness.service.resolveExternalTarget('canvas-a', 'thread-a'),
-    ).toEqual({ binding: TARGET.agentBinding, fixedTarget: TARGET });
+    ).resolves.toEqual({ binding: TARGET.agentBinding, fixedTarget: TARGET });
   });
 
   it('uses persisted fixed binding and overrides under one leased lifecycle', async () => {
@@ -356,7 +356,7 @@ describe('AgentThreadService', () => {
       return events([{ type: 'done', data: { message: 'Done' } }]);
     });
     const service = new AgentThreadService({
-      resolveFixedAgentNode: () => TARGET,
+      resolveFixedAgentNode: async () => TARGET,
       resolvePersistedExternalBinding: () => null,
       waitForTurnRelease: vi.fn().mockResolvedValue(undefined),
       acquireTurn: vi.fn(() => vi.fn()),
diff --git a/apps/server/src/modules/agent/agent-thread.service.ts b/apps/server/src/modules/agent/agent-thread.service.ts
index 1ab52dab2..64075e3de 100644
--- a/apps/server/src/modules/agent/agent-thread.service.ts
+++ b/apps/server/src/modules/agent/agent-thread.service.ts
@@ -34,7 +34,7 @@ interface AgentThreadServiceDependencies {
   resolveFixedAgentNode: (
     canvasId: string,
     threadId: string,
-  ) => FixedAgentNodeTarget | null;
+  ) => Promise<FixedAgentNodeTarget | null>;
   resolvePersistedExternalBinding: (
     canvasId: string,
     threadId: string,
@@ -160,20 +160,20 @@ export class AgentThreadService {
     private readonly dependencies: AgentThreadServiceDependencies = DEFAULT_DEPENDENCIES,
   ) {}
 
-  resolveFixedTarget(
+  async resolveFixedTarget(
     canvasId: string | undefined,
     threadId: string,
-  ): FixedAgentNodeTarget | null {
+  ): Promise<FixedAgentNodeTarget | null> {
     return canvasId
       ? this.dependencies.resolveFixedAgentNode(canvasId, threadId)
       : null;
   }
 
-  resolveExternalTarget(
+  async resolveExternalTarget(
     canvasId: string,
     threadId: string,
-  ): ExternalAgentThreadTarget | null {
-    const fixedTarget = this.resolveFixedTarget(canvasId, threadId);
+  ): Promise<ExternalAgentThreadTarget | null> {
+    const fixedTarget = await this.resolveFixedTarget(canvasId, threadId);
     if (fixedTarget) {
       return fixedTarget.agentBinding.kind === 'external'
         ? { binding: fixedTarget.agentBinding, fixedTarget }
@@ -197,7 +197,7 @@ export class AgentThreadService {
   ): Promise<AgentThreadInvocation> {
     const fixedTarget =
       options.fixedTarget === undefined
-        ? this.resolveFixedTarget(options.canvasId, options.threadId)
+        ? await this.resolveFixedTarget(options.canvasId, options.threadId)
         : options.fixedTarget;
     const binding: AgentBinding = fixedTarget?.agentBinding ??
       options.requestBinding ?? { kind: 'internal' };
diff --git a/apps/server/src/modules/agent/agent.route.ts b/apps/server/src/modules/agent/agent.route.ts
index 597a2fb53..1ce5a34e2 100644
--- a/apps/server/src/modules/agent/agent.route.ts
+++ b/apps/server/src/modules/agent/agent.route.ts
@@ -546,7 +546,7 @@ const agentRoutes: FastifyPluginAsync = async (
     } = parsed.data;
 
     const resolvedThreadId = getOrCreateThreadId(threadId);
-    const fixedTarget = agentThreadService.resolveFixedTarget(
+    const fixedTarget = await agentThreadService.resolveFixedTarget(
       canvasId,
       resolvedThreadId,
     );
diff --git a/apps/server/src/modules/interactive-view/interactive-view.service.ts b/apps/server/src/modules/interactive-view/interactive-view.service.ts
index 251acdf3b..4903acbcf 100644
--- a/apps/server/src/modules/interactive-view/interactive-view.service.ts
+++ b/apps/server/src/modules/interactive-view/interactive-view.service.ts
@@ -70,12 +70,12 @@ export class InteractiveViewServiceError extends Error {
   }
 }
 
-function resolveOwnerThread(
+async function resolveOwnerThread(
   canvasId: string,
   threadId: string,
-): ExternalAgentThreadTarget | null {
+): Promise<ExternalAgentThreadTarget | null> {
   try {
-    return agentThreadService.resolveExternalTarget(canvasId, threadId);
+    return await agentThreadService.resolveExternalTarget(canvasId, threadId);
   } catch (error) {
     if (error instanceof AgentThreadResolutionError) {
       throw new InteractiveViewServiceError(
@@ -331,7 +331,7 @@ export class InteractiveViewService {
         `Canvas ${canvasId} does not exist`,
       );
     }
-    if (!resolveOwnerThread(canvasId, request.ownerThreadId)) {
+    if (!(await resolveOwnerThread(canvasId, request.ownerThreadId))) {
       throw new InteractiveViewServiceError(
         'invalid_owner_thread',
         `Owner thread ${request.ownerThreadId} is not an external Agent thread in this Canvas`,
@@ -501,7 +501,7 @@ export class InteractiveViewService {
       ...(input !== undefined ? { input } : {}),
       viewRevision: resource.revision,
     };
-    const ownerTarget = resolveOwnerThread(
+    const ownerTarget = await resolveOwnerThread(
       canvasId,
       resource.definition.ownerThreadId,
     );
diff --git a/apps/server/src/modules/remote_fs/node-meta.ts b/apps/server/src/modules/remote_fs/node-meta.ts
index b92a4e144..5faf1fed2 100644
--- a/apps/server/src/modules/remote_fs/node-meta.ts
+++ b/apps/server/src/modules/remote_fs/node-meta.ts
@@ -38,7 +38,7 @@ import {
   safeResolve,
   toPhysicalRel,
 } from '../agent/tools/handlers/fs-sandbox.js';
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type { CanvasNodeType } from '@huabu/shared';
 import type { CanvasNode, CanvasEdge } from '@huabu/shared/canvas-engine';
@@ -88,31 +88,32 @@ const NODE_FILE_RE = /^nodes\/[^/]+\.md$/;
  * the path is not a node file or no node currently claims it — callers then
  * serve the bytes without `X-Huabu-*` headers.
  *
- * The file → node mapping goes through the store's frontmatter-`id` index
- * ({@link CanvasStore.nodeIdForFilename}), NOT a re-derived
- * `toSafeFilename(label)` — topology never carries `data.label`, so the
- * derived path would collapse to `nodes/<id>.md` and never match a real
- * label-named file. `label` / `rev` are then sourced from the sidecar.
+ * The file → node mapping is the Disk tree's sidecar-to-record mapping, NOT a
+ * re-derived `toSafeFilename(label)` — topology never carries `data.label`, so
+ * the derived path would collapse to `nodes/<id>.md` and never match a real
+ * label-named file. It stays Disk-shaped on purpose (§6.4.3, disposition B):
+ * inverting a filename is only meaningful where the file is really there, so
+ * until a second backend exists RFS's file plane is Disk's. The record and the
+ * sidecar themselves come from the portable ports.
  */
-export function lookupNodeByPath(
+export async function lookupNodeByPath(
   canvasId: string,
   physicalRel: string,
-): RfsNodeLookup | null {
+): Promise<RfsNodeLookup | null> {
   if (!NODE_FILE_RE.test(physicalRel)) return null;
 
-  const store = getCanvasStore(canvasId);
-  const canvas = store.read();
+  const handle = space(canvasId);
+  const canvas = await handle.read();
   if (!canvas) return null;
 
-  const filename = physicalRel.slice('nodes/'.length);
-  const nodeId = store.nodeIdForFilename(filename);
+  const nodeId = handle.diskTree?.nodeIdForPath(physicalRel) ?? null;
   if (!nodeId) return null;
 
   const nodes = (canvas.state.nodes ?? []) as CanvasNode[];
   const match = nodes.find((n) => n.id === nodeId);
   if (!match) return null;
 
-  const sidecar = store.readNode(nodeId);
+  const sidecar = (await handle.nodes.read(nodeId))?.record ?? null;
   const data = (match.data ?? {}) as {
     locked?: boolean;
     src?: string;
diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts
index 544b525fd..0d8090276 100644
--- a/apps/server/src/modules/remote_fs/rfs.route.test.ts
+++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts
@@ -1329,7 +1329,7 @@ describe('node download revision (ETag / conditional GET)', () => {
 
 describe('POST /api/rfs/:canvasId/agent', () => {
   it('creates an idle Agent and connects its parent when available', async () => {
-    vi.spyOn(agentThreadResolver, 'resolveAgentNodeId').mockReturnValue(
+    vi.spyOn(agentThreadResolver, 'resolveAgentNodeId').mockResolvedValue(
       'node-parent' as CanvasNodeId,
     );
     const create = vi.spyOn(agentNodeService, 'create').mockResolvedValue({
@@ -1427,7 +1427,9 @@ describe('POST /api/rfs/:canvasId/agent', () => {
       content: '',
     });
 
-    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockReturnValue(target);
+    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockResolvedValue(
+      target,
+    );
     const dispose = vi.fn().mockResolvedValue(undefined);
     const invoke = vi
       .spyOn(agentThreadService, 'invoke')
@@ -1490,7 +1492,9 @@ describe('POST /api/rfs/:canvasId/agent', () => {
       profileId: 'huabu',
       parentConnection: 'not_requested',
     });
-    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockReturnValue(target);
+    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockResolvedValue(
+      target,
+    );
     vi.spyOn(agentThreadService, 'invoke').mockImplementation(
       async (options) => ({
         binding: target.agentBinding,
@@ -1537,7 +1541,7 @@ describe('POST /api/rfs/:canvasId/agent', () => {
       profileId: 'huabu',
       parentConnection: 'not_requested',
     });
-    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockReturnValue(null);
+    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockResolvedValue(null);
 
     const app = await buildApp();
     try {
@@ -1569,7 +1573,9 @@ describe('POST /api/rfs/:canvasId/agent', () => {
       status: 'done',
       content: 'Earlier request',
     };
-    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockReturnValue(target);
+    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockResolvedValue(
+      target,
+    );
     const invoke = vi
       .spyOn(agentThreadService, 'invoke')
       .mockImplementation(async (options) => ({
@@ -1618,7 +1624,7 @@ describe('POST /api/rfs/:canvasId/agent', () => {
   });
 
   it('returns thread_not_found before opening SSE', async () => {
-    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockReturnValue(null);
+    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockResolvedValue(null);
 
     const app = await buildApp();
     try {
@@ -1638,7 +1644,7 @@ describe('POST /api/rfs/:canvasId/agent', () => {
 
   it('creates the Agent when its requested parent cannot be found', async () => {
     seedNote('c1', 'node-anchor', 'Anchor', 'content');
-    vi.spyOn(agentThreadResolver, 'resolveAgentNodeId').mockReturnValue(null);
+    vi.spyOn(agentThreadResolver, 'resolveAgentNodeId').mockResolvedValue(null);
     vi.spyOn(agentNodeService, 'create').mockResolvedValue({
       canvasId: 'c1',
       nodeId: 'node-independent' as CanvasNodeId,
@@ -1685,7 +1691,9 @@ describe('POST /api/rfs/:canvasId/agent', () => {
       status: 'running',
       content: 'Working',
     };
-    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockReturnValue(target);
+    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockResolvedValue(
+      target,
+    );
     vi.spyOn(agentThreadService, 'invoke').mockRejectedValue(
       new AgentThreadBusyError('thread-busy'),
     );
@@ -1715,7 +1723,9 @@ describe('POST /api/rfs/:canvasId/agent', () => {
       status: 'idle',
       content: '',
     };
-    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockReturnValue(target);
+    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockResolvedValue(
+      target,
+    );
     vi.spyOn(agentThreadService, 'invoke').mockImplementation(
       async (options) => ({
         binding: target.agentBinding,
@@ -1754,7 +1764,9 @@ describe('POST /api/rfs/:canvasId/agent', () => {
       status: 'idle',
       content: '',
     };
-    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockReturnValue(target);
+    vi.spyOn(agentThreadService, 'resolveFixedTarget').mockResolvedValue(
+      target,
+    );
     vi.spyOn(agentThreadService, 'invoke').mockImplementation(
       async (options) => ({
         binding: target.agentBinding,
diff --git a/apps/server/src/modules/remote_fs/rfs.route.ts b/apps/server/src/modules/remote_fs/rfs.route.ts
index 495d4c484..d2997b10f 100644
--- a/apps/server/src/modules/remote_fs/rfs.route.ts
+++ b/apps/server/src/modules/remote_fs/rfs.route.ts
@@ -667,7 +667,7 @@ const rfsRoutes: FastifyPluginAsync = async (app) => {
         return reply.code(404).send(rfsError(`No file at "${requestRel}".`));
       }
 
-      const lookup = lookupNodeByPath(canvasId, physicalRel);
+      const lookup = await lookupNodeByPath(canvasId, physicalRel);
 
       // Node files carry a revision ETag (hash of authored content) so an
       // agent can conditional-GET: an unchanged node returns `304` and the
@@ -1064,7 +1064,7 @@ const rfsRoutes: FastifyPluginAsync = async (app) => {
       let parentLookupFailed = false;
       if (parentThreadId) {
         try {
-          parentNodeId = agentThreadResolver.resolveAgentNodeId(
+          parentNodeId = await agentThreadResolver.resolveAgentNodeId(
             canvasId,
             parentThreadId,
           );
@@ -1185,7 +1185,7 @@ const rfsRoutes: FastifyPluginAsync = async (app) => {
           .send(rfsError('An initial prompt is required.', 'prompt_required'));
       }
 
-      const target = agentThreadService.resolveFixedTarget(
+      const target = await agentThreadService.resolveFixedTarget(
         canvasId,
         created.threadId,
       );
@@ -1325,7 +1325,10 @@ const rfsRoutes: FastifyPluginAsync = async (app) => {
 
       let target;
       try {
-        target = agentThreadService.resolveFixedTarget(canvasId, threadId);
+        target = await agentThreadService.resolveFixedTarget(
+          canvasId,
+          threadId,
+        );
       } catch (error) {
         if (error instanceof AgentThreadResolutionError) {
           return reply
diff --git a/apps/server/src/modules/storage/backends/disk/space-tree.ts b/apps/server/src/modules/storage/backends/disk/space-tree.ts
index a11e1fb01..ceb06a77f 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tree.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.ts
@@ -20,6 +20,10 @@
  */
 
 import { canvasRoot } from './layout.js';
+import { getCanvasStore } from './legacy/canvas-store-cache.js';
+
+/** A node sidecar, as RFS and the file tools address one. */
+const NODE_SIDECAR_RE = /^nodes\/([^/]+\.md)$/;
 
 export interface DiskSpaceTree {
   readonly canvasId: string;
@@ -34,11 +38,35 @@ export interface DiskSpaceTree {
    * malformed or the resolved path escapes the Workspace.
    */
   directory(): string;
+  /**
+   * Which node record the materialized file at `relativePath` carries.
+   *
+   * `relativePath` is Space-relative (`nodes/My note.md`); anything that is
+   * not a node sidecar, and any name no node currently claims, returns `null`.
+   *
+   * This is the **sidecar-to-record mapping**, and it belongs to the tree
+   * rather than to a port for the reason §6.4.3 gives under disposition B:
+   * every backend could mint `nodes/<label>.md` names from records, but Disk
+   * inverts the *real* filename, because the file is really there and a user
+   * may have renamed it. The two are only the same answer when nothing has
+   * touched the directory from outside — which is exactly the case Disk
+   * cannot assume. Until a second backend exists, RFS's file plane is Disk's.
+   *
+   * Resolved through the frontmatter-`id` index rather than by re-deriving
+   * `toSafeFilename(label)`: topology never carries a label, so a derived path
+   * would collapse to `nodes/<id>.md` and never match a label-named file.
+   */
+  nodeIdForPath(relativePath: string): string | null;
 }
 
 export function diskSpaceTree(canvasId: string): DiskSpaceTree {
   return {
     canvasId,
     directory: () => canvasRoot(canvasId),
+    nodeIdForPath: (relativePath: string) => {
+      const filename = NODE_SIDECAR_RE.exec(relativePath)?.[1];
+      if (filename === undefined) return null;
+      return getCanvasStore(canvasId).nodeIdForFilename(filename);
+    },
   };
 }
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index 628415e20..f9eaf5e0c 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -305,6 +305,9 @@ describe('Disk Space tree capability', () => {
     'modules/canvas/external.route.ts',
     // C — the resurrection guard, which disappears with the substrate.
     'modules/agent/memory/trigger.ts',
+    // B, deferred — RFS's sidecar-to-record mapping. Portable in principle,
+    // Disk's in practice until a second backend has a file plane at all.
+    'modules/remote_fs/node-meta.ts',
     // D — the per-Space RFS access guide, headed for a blob.
     'modules/remote_fs/skill.ts',
     // C and D — memory files, the debug prompt log, ACP session state.

From 53051479b26150e8236d7eb95da38da74e039353 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 17:24:40 +0800
Subject: [PATCH 05/20] refactor(canvas): read World, spatial, and prompt
 context through the ports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The World resolvers, the spatial queries, and the prompt assemblers all
reached the legacy synchronous Disk store. They now go through
`space(canvasId)`, which makes each entry point async up to its already-async
caller: the space-query facade, the agent tool executor, and the chat
envelope builder.

Three things worth calling out beyond the mechanical move.

`node-prompt` stops taking a `CanvasStore`. It is a pure merge — the caller's
authored fields win, the stored record fills the gaps — and it took a store
only so it could lazily read a record the caller had not supplied. That made
a pure function into a synchronous Disk dependency no async port can satisfy.
The record is now an argument, so each caller reads what it needs in the
shape that suits its request: `readMany` for a selection the wire already
named, `list` where the work genuinely spans the Space (the outline
describes every node, inspect filters over all of them).

`readWorldTargetCanvasesStrict` walked the Workspace itself, reading
`space.json` files, which made a reference resolver a consumer of the Disk
record layout and cost it the whole Workspace per call. It now reads the ids
it was asked for. Its duplicate-topology check moves to where duplicates are
actually observable — the Disk directory scan, which resolved two
directories claiming one `canvasId` last-wins and now raises. A Finder-side
duplication becomes a loud failure of every catalogue read instead of a Space
that silently resolves to an arbitrary copy.

One behaviour change, deliberately. World reference resolution read source
nodes strictly and rejected on malformed frontmatter, so one hand-edited file
made the entire World view 500. The port's documented stance is the opposite
and has been since phase 4: broken frontmatter is not a read failure,
because a node whose YAML a user broke must stay repairable through the
content PUT. The resolver now follows the port, and the test says so.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../modules/agent/conversation/envelope.ts    |  42 +++---
 .../src/modules/agent/tools/executor.ts       |  20 +--
 .../agent/tools/handlers/canvas-query.ts      |   6 +-
 .../src/modules/canvas/canvas-spatial.test.ts |  18 +--
 .../src/modules/canvas/canvas-spatial.ts      |  60 ++++-----
 .../src/modules/canvas/node-neighbourhood.ts  |  40 +++---
 .../src/modules/canvas/node-prompt.test.ts    | 125 ++++++++++--------
 apps/server/src/modules/canvas/node-prompt.ts |  56 ++++----
 apps/server/src/modules/canvas/space-query.ts |   6 +-
 .../src/modules/canvas/world-portals.ts       |  31 +++--
 .../canvas/world-reference-resolver.test.ts   |  17 ++-
 .../canvas/world-reference-resolver.ts        |  36 ++---
 .../src/modules/canvas/world-target-access.ts |  89 ++++++-------
 .../storage/backends/disk/canvas-dirs.ts      |  18 ++-
 .../modules/storage/module-boundaries.test.ts |   9 --
 .../src/modules/storage/ports/structured.ts   |   8 ++
 16 files changed, 308 insertions(+), 273 deletions(-)

diff --git a/apps/server/src/modules/agent/conversation/envelope.ts b/apps/server/src/modules/agent/conversation/envelope.ts
index f4250ec7b..be7242aeb 100644
--- a/apps/server/src/modules/agent/conversation/envelope.ts
+++ b/apps/server/src/modules/agent/conversation/envelope.ts
@@ -24,10 +24,11 @@ import { getSkill } from '../../../prompt/index.js';
 import { getNodeNeighbourhood } from '../../canvas/node-neighbourhood.js';
 import { describeNode } from '../../canvas/node-prompt.js';
 import { snapshotNodesToArtifacts } from '../../canvas/snapshot-nodes.js';
-import { getCanvasStore } from '../../storage/index.js';
+import { space } from '../../storage/index.js';
 import { isUserInvokableSkill } from '../skills.route.js';
 
 import type { NodeNeighbourhoodContext } from '../../canvas/node-neighbourhood.js';
+import type { NodeSnapshot } from '../../storage/index.js';
 import type { AgentNodePreview } from '../node-ref.js';
 import type {
   ChatAttachment,
@@ -200,21 +201,26 @@ function collectSketchStrokeSubsets(
  * The `preview` is picked server-side via the shared
  * {@link extractAgentNodePreview} ladder (`summary > content[:120] > src`)
  * — the SAME policy the node-neighbourhood uses — by reading each node's
- * on-disk sidecar from the canvas store. Full content is still one tool
- * call away; the preview is only a scan hint. When `canvasId` is null the
- * store is unavailable, so refs fall back to bare `{ id, type, label?,
- * filename }` (no preview).
+ * stored record. Full content is still one tool call away; the preview is
+ * only a scan hint. When `canvasId` is null there is no Space to read, so
+ * refs fall back to bare `{ id, type, label?, filename }` (no preview).
+ *
+ * A selection is a named subset, so it is read as one — `readMany` over the
+ * ids the wire already named, rather than a scan of the Space or a read per
+ * node (§12.6.1).
  */
-function collectSelectedNodeRefs(
+async function collectSelectedNodeRefs(
   nodes: WireSelectionNode[],
   canvasId: string | null,
-): AgentNodePreview[] {
-  let store: ReturnType<typeof getCanvasStore> | null = null;
+): Promise<AgentNodePreview[]> {
+  let records = new Map<string, NodeSnapshot>();
   if (canvasId) {
     try {
-      store = getCanvasStore(canvasId);
+      records = await space(canvasId).nodes.readMany(
+        collectSelectedNodeIds(nodes),
+      );
     } catch {
-      store = null;
+      /* Space unreadable — refs stay bare. */
     }
   }
   const refs: AgentNodePreview[] = [];
@@ -226,7 +232,6 @@ function collectSelectedNodeRefs(
       // label + file + preview + rev for every server-side node context.
       refs.push(
         describeNode(
-          store,
           {
             id: n.id,
             type: n.type,
@@ -234,6 +239,7 @@ function collectSelectedNodeRefs(
             ...(n.src !== undefined ? { src: n.src } : {}),
           },
           'preview',
+          records.get(n.id)?.record ?? null,
         ),
       );
       if (n.children) walk(n.children);
@@ -408,13 +414,10 @@ export async function buildChatEnvelope(
   let anchor: ChatEnvelope['focus']['anchor'];
   if (anchorNodeId && canvasId) {
     const neighbourhood =
-      getNodeNeighbourhood(canvasId, anchorNodeId) ?? undefined;
+      (await getNodeNeighbourhood(canvasId, anchorNodeId)) ?? undefined;
     let label: string | undefined;
     try {
-      const meta = getCanvasStore(canvasId).readNode(anchorNodeId) as Record<
-        string,
-        unknown
-      > | null;
+      const meta = (await space(canvasId).nodes.read(anchorNodeId))?.record;
       if (typeof meta?.label === 'string') label = meta.label;
     } catch {
       /* store unavailable — anchor still useful by id */
@@ -427,6 +430,9 @@ export async function buildChatEnvelope(
   }
 
   // Focus: selection refs + derived snapshot artifacts.
+  const selectionRefs = selectedNodes
+    ? await collectSelectedNodeRefs(selectedNodes, canvasId)
+    : [];
   const selectionImageAttachments = selectedNodes
     ? collectImageAttachments(selectedNodes)
     : [];
@@ -462,9 +468,7 @@ export async function buildChatEnvelope(
     },
     focus: {
       selection: {
-        refs: selectedNodes
-          ? collectSelectedNodeRefs(selectedNodes, canvasId)
-          : [],
+        refs: selectionRefs,
         selectedIds: selectedNodes ? collectSelectedNodeIds(selectedNodes) : [],
         imageAttachments: dedupedImageAttachments,
         snapshotAttachments,
diff --git a/apps/server/src/modules/agent/tools/executor.ts b/apps/server/src/modules/agent/tools/executor.ts
index deca047e6..f63d6c75e 100644
--- a/apps/server/src/modules/agent/tools/executor.ts
+++ b/apps/server/src/modules/agent/tools/executor.ts
@@ -119,10 +119,10 @@ export async function executeTool(
   };
   const withCanvasId = <T>(value: Record<string, unknown>, toolName: string) =>
     ({ ...value, canvasId: requireCanvasId(toolName) }) as unknown as T;
-  const withReadCanvasId = <T>(
+  const withReadCanvasId = async <T>(
     value: Record<string, unknown>,
     toolName: string,
-  ): T => {
+  ): Promise<T> => {
     const ownerCanvasId = requireCanvasId(toolName);
     const requested = value.targetCanvasId;
     if (requested !== undefined && typeof requested !== 'string') {
@@ -131,7 +131,7 @@ export async function executeTool(
     const { targetCanvasId: _targetCanvasId, ...toolArgs } = value;
     return {
       ...toolArgs,
-      canvasId: resolveWorldReadCanvasId(ownerCanvasId, requested),
+      canvasId: await resolveWorldReadCanvasId(ownerCanvasId, requested),
     } as unknown as T;
   };
 
@@ -141,31 +141,31 @@ export async function executeTool(
 
     case 'get_space_outline':
       return handleGetCanvasOutline(
-        withReadCanvasId<GetCanvasOutlineArgs>(args, 'get_space_outline'),
+        await withReadCanvasId<GetCanvasOutlineArgs>(args, 'get_space_outline'),
       );
 
     case 'inspect_nodes':
       return handleInspectNodes(
-        withReadCanvasId<InspectNodesArgs>(args, 'inspect_nodes'),
+        await withReadCanvasId<InspectNodesArgs>(args, 'inspect_nodes'),
       );
 
     case 'inspect_edges':
       return handleInspectEdges(
-        withReadCanvasId<InspectEdgesArgs>(args, 'inspect_edges'),
+        await withReadCanvasId<InspectEdgesArgs>(args, 'inspect_edges'),
       );
 
     case 'grep':
-      return handleGrep(withReadCanvasId<GrepArgs>(args, 'grep'));
+      return handleGrep(await withReadCanvasId<GrepArgs>(args, 'grep'));
 
     case 'find':
-      return handleFind(withReadCanvasId<FindArgs>(args, 'find'));
+      return handleFind(await withReadCanvasId<FindArgs>(args, 'find'));
 
     case 'ls':
-      return handleLs(withReadCanvasId<LsArgs>(args, 'ls'));
+      return handleLs(await withReadCanvasId<LsArgs>(args, 'ls'));
 
     case 'read': {
       const ownerCanvasId = requireCanvasId('read');
-      const readArgs = withReadCanvasId<ReadArgs>(args, 'read');
+      const readArgs = await withReadCanvasId<ReadArgs>(args, 'read');
       return handleRead(
         readArgs,
         readArgs.canvasId === ownerCanvasId ? context?.readSet : undefined,
diff --git a/apps/server/src/modules/agent/tools/handlers/canvas-query.ts b/apps/server/src/modules/agent/tools/handlers/canvas-query.ts
index 178b7fe2a..13a268204 100644
--- a/apps/server/src/modules/agent/tools/handlers/canvas-query.ts
+++ b/apps/server/src/modules/agent/tools/handlers/canvas-query.ts
@@ -50,7 +50,7 @@ export type InspectEdgesArgs = InspectEdgesQueryParams & {
 export async function handleGetCanvasOutline(
   args: GetCanvasOutlineArgs,
 ): Promise<string> {
-  const outline = buildCanvasOutline(args.canvasId, {
+  const outline = await buildCanvasOutline(args.canvasId, {
     includePreviews: args.includePreviews,
     includeStyle: args.includeStyle,
   });
@@ -64,7 +64,7 @@ export async function handleInspectNodes(
   args: InspectNodesArgs,
 ): Promise<string> {
   const { canvasId, ...predicates } = args;
-  const result = inspectNodes(canvasId, predicates);
+  const result = await inspectNodes(canvasId, predicates);
   // `inspectNodes` returns either a result object or `{ error }` when a
   // referenced node is missing. Promote the error case to a throw so
   // pi-agent-core flags the tool result as `isError: true`.
@@ -78,7 +78,7 @@ export async function handleInspectEdges(
   args: InspectEdgesArgs,
 ): Promise<string> {
   const { canvasId, ...predicates } = args;
-  const result = inspectEdges(canvasId, predicates);
+  const result = await inspectEdges(canvasId, predicates);
   if ('error' in result) {
     throw new Error(result.error);
   }
diff --git a/apps/server/src/modules/canvas/canvas-spatial.test.ts b/apps/server/src/modules/canvas/canvas-spatial.test.ts
index 70b98ceb0..a95900181 100644
--- a/apps/server/src/modules/canvas/canvas-spatial.test.ts
+++ b/apps/server/src/modules/canvas/canvas-spatial.test.ts
@@ -50,7 +50,7 @@ function seed(canvasId: string, nodes: SeedNode[]): void {
   });
 }
 
-function byId(result: ReturnType<typeof inspectNodes>): Map<
+function byId(result: Awaited<ReturnType<typeof inspectNodes>>): Map<
   string,
   {
     position: { x: number; y: number };
@@ -113,18 +113,18 @@ describe('inspect_nodes / outline — dual-field coordinates', () => {
     ]);
   }
 
-  it('root node reports position == absolutePosition', () => {
+  it('root node reports position == absolutePosition', async () => {
     seedScene();
-    const m = byId(inspectNodes(CANVAS, { ids: ['root'] }));
+    const m = byId(await inspectNodes(CANVAS, { ids: ['root'] }));
     expect(m.get('root')).toEqual({
       position: { x: 100, y: 100 },
       absolutePosition: { x: 100, y: 100 },
     });
   });
 
-  it('framed child reports parent-local position and world absolutePosition', () => {
+  it('framed child reports parent-local position and world absolutePosition', async () => {
     seedScene();
-    const m = byId(inspectNodes(CANVAS, { ids: ['child'] }));
+    const m = byId(await inspectNodes(CANVAS, { ids: ['child'] }));
     expect(m.get('child')).toEqual({
       // raw stored value = frame-relative
       position: { x: 50, y: 60 },
@@ -133,9 +133,9 @@ describe('inspect_nodes / outline — dual-field coordinates', () => {
     });
   });
 
-  it('resolves absolutePosition through a nested frame chain', () => {
+  it('resolves absolutePosition through a nested frame chain', async () => {
     seedScene();
-    const m = byId(inspectNodes(CANVAS, { ids: ['grandchild'] }));
+    const m = byId(await inspectNodes(CANVAS, { ids: ['grandchild'] }));
     expect(m.get('grandchild')).toEqual({
       // raw stored value = relative to inner frame
       position: { x: 10, y: 20 },
@@ -144,9 +144,9 @@ describe('inspect_nodes / outline — dual-field coordinates', () => {
     });
   });
 
-  it('get_canvas_outline emits the same dual fields', () => {
+  it('get_canvas_outline emits the same dual fields', async () => {
     seedScene();
-    const outline = buildCanvasOutline(CANVAS);
+    const outline = await buildCanvasOutline(CANVAS);
     if (!outline) throw new Error('no outline');
     const child = outline.nodes.find((n) => n.id === 'child');
     expect(child?.position).toEqual({ x: 50, y: 60 });
diff --git a/apps/server/src/modules/canvas/canvas-spatial.ts b/apps/server/src/modules/canvas/canvas-spatial.ts
index d96911163..06a2245f1 100644
--- a/apps/server/src/modules/canvas/canvas-spatial.ts
+++ b/apps/server/src/modules/canvas/canvas-spatial.ts
@@ -53,10 +53,10 @@ import {
 } from '@huabu/shared/canvas-engine';
 
 import { describeNode, nodeLabel, type NodeInput } from './node-prompt.js';
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type { AgentNodeOutline } from '../agent/node-ref.js';
-import type { CanvasFile } from '../storage/canvas-store.js';
+import type { CanvasFile } from '../storage/index.js';
 import type {
   CanvasNodeType,
   CardinalDirection,
@@ -282,14 +282,20 @@ export interface CanvasOutlineOpts {
  * Build the one-shot "map" of a canvas: every node's geometry + edges +
  * spatial clusters. Returns `null` when the canvas does not exist.
  */
-export function buildCanvasOutline(
+export async function buildCanvasOutline(
   canvasId: string,
   opts: CanvasOutlineOpts = {},
-): CanvasOutline | null {
-  const store = getCanvasStore(canvasId);
-  const canvas = store.read();
+): Promise<CanvasOutline | null> {
+  const handle = space(canvasId);
+  const canvas = await handle.read();
   if (!canvas) return null;
 
+  // Whole-Space work: the outline describes every node, so one scan is the
+  // shape (§12.6.1). It also replaces the lazy per-node reads the memo below
+  // used to guard, which no async port could serve from inside a synchronous
+  // map.
+  const records = await handle.nodes.list();
+
   const bundle = buildSpatialBundle(canvas);
   const summary = buildSpatialSummary(bundle.spatialNodes, bundle.edges);
 
@@ -311,25 +317,20 @@ export function buildCanvasOutline(
 
   // Resolve display labels from the sidecar (topology never carries
   // them), memoized so a frame referenced as many nodes' parent is read once.
-  const labelMemo = new Map<string, string | undefined>();
-  const memoLabel = (id: string): string | undefined => {
-    if (labelMemo.has(id)) return labelMemo.get(id);
-    const l = nodeLabel(store, id);
-    labelMemo.set(id, l);
-    return l;
-  };
+  const labelOf = (id: string): string | undefined =>
+    nodeLabel(records.get(id)?.record ?? null);
 
   const nodes: CanvasOutlineNode[] = bundle.spatialNodes.map((s) => {
     const raw = bundle.rawById.get(s.id);
-    const parentLabel = s.parentId ? memoLabel(s.parentId) : undefined;
+    const parentLabel = s.parentId ? labelOf(s.parentId) : undefined;
     const style = opts.includeStyle ? readVisualStyle(raw) : undefined;
     const out: CanvasOutlineNode = describeNode(
-      store,
       {
         ...spatialNodeInput(s, raw, parentLabel),
         ...(style ? { style } : {}),
       },
       'outline',
+      records.get(s.id)?.record ?? null,
     );
     // The shared builder attaches `summary` (authored abstract) and
     // `preview` (raw body excerpt) from the sidecar; both are text scan
@@ -449,25 +450,23 @@ const DEFAULT_INSPECT_LIMIT = 50;
  * direction, edgeIds, hops, clusterId) are computed during filtering
  * and merged into the final result row.
  */
-export function inspectNodes(
+export async function inspectNodes(
   canvasId: string,
   args: InspectNodesArgs,
-): InspectNodesResult | InspectNodesError {
-  const store = getCanvasStore(canvasId);
-  const canvas = store.read();
+): Promise<InspectNodesResult | InspectNodesError> {
+  const handle = space(canvasId);
+  const canvas = await handle.read();
   if (!canvas) return { error: `Canvas ${canvasId} not found` };
 
   const bundle = buildSpatialBundle(canvas);
+  // An unfiltered inspect returns every node, and `labelPattern` has to test
+  // every candidate, so the candidate set is the Space (§12.6.1).
+  const records = await handle.nodes.list();
 
   // Display labels come from the sidecar (topology never carries them);
   // memoize so the `labelPattern` filter and the result map read each once.
-  const labelMemo = new Map<string, string | undefined>();
-  const memoLabel = (id: string): string | undefined => {
-    if (labelMemo.has(id)) return labelMemo.get(id);
-    const l = nodeLabel(store, id);
-    labelMemo.set(id, l);
-    return l;
-  };
+  const memoLabel = (id: string): string | undefined =>
+    nodeLabel(records.get(id)?.record ?? null);
 
   // Per-node derived fields accumulated during filter passes.
   const derived = new Map<string, Partial<InspectNodeResult>>();
@@ -713,9 +712,9 @@ export function inspectNodes(
     const raw = bundle.rawById.get(s.id);
     const parentLabel = s.parentId ? memoLabel(s.parentId) : undefined;
     const base = describeNode(
-      store,
       spatialNodeInput(s, raw, parentLabel),
       'outline',
+      records.get(s.id)?.record ?? null,
     );
     // Inspect deliberately omits text hints (`summary` / `preview`); agents
     // that need text use `get_canvas_outline({ includePreviews: true })` or
@@ -815,12 +814,11 @@ export type InspectEdgesError = { error: string };
  * `inspect_nodes({ connectedTo }).edgeIds` or directly from a styling
  * task, so even the unfiltered case is bounded in practice.
  */
-export function inspectEdges(
+export async function inspectEdges(
   canvasId: string,
   args: InspectEdgesArgs,
-): InspectEdgesResult | InspectEdgesError {
-  const store = getCanvasStore(canvasId);
-  const canvas = store.read();
+): Promise<InspectEdgesResult | InspectEdgesError> {
+  const canvas = await space(canvasId).read();
   if (!canvas) return { error: `Canvas ${canvasId} not found` };
 
   const bundle = buildSpatialBundle(canvas);
diff --git a/apps/server/src/modules/canvas/node-neighbourhood.ts b/apps/server/src/modules/canvas/node-neighbourhood.ts
index 350f3d78b..710d5e8d4 100644
--- a/apps/server/src/modules/canvas/node-neighbourhood.ts
+++ b/apps/server/src/modules/canvas/node-neighbourhood.ts
@@ -46,7 +46,7 @@ import {
   renderNodes,
 } from '../agent/conversation/prompt/node-element.js';
 import { buildAgentNodePreview } from '../agent/node-ref.js';
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type { AgentNodePreview } from '../agent/node-ref.js';
 import type { CanvasNodeType, SpatialNode } from '@huabu/shared';
@@ -67,39 +67,39 @@ import type { CanvasNodeType, SpatialNode } from '@huabu/shared';
  * Owns the preview-extraction policy. Forwards each node through the
  * shared {@link extractAgentNodePreview} ladder
  * (`summary > content[:120] > src`) with two inputs merged in one
- * pass: the on-disk frontmatter (via `readNode` — canonical for note
- * nodes whose body lives in `nodes/<file>.md`) and the inline
- * `data.content` / `data.src` (text-on-canvas nodes whose body never
- * touches disk). Per-node disk reads are memoized.
+ * pass: the stored node record (canonical for note nodes whose body lives
+ * outside the topology) and the inline `data.content` / `data.src`
+ * (text-on-canvas nodes whose body is never a separate record).
+ *
+ * Records are read once, up front, for the whole Space. The neighbourhood
+ * is a subset, so this reads more than the old lazy per-node path did on a
+ * sparse canvas — but a lazy read cannot cross an async port without making
+ * the pure walk below async too, and the walk already visits every node to
+ * build the spatial bundle (§12.6.1).
  */
-export function getNodeNeighbourhood(
+export async function getNodeNeighbourhood(
   canvasId: string,
   anchorNodeId: string,
-): NodeNeighbourhoodContext | null {
-  const canvas = getCanvasStore(canvasId).read();
+): Promise<NodeNeighbourhoodContext | null> {
+  const handle = space(canvasId);
+  const canvas = await handle.read();
   if (!canvas) return null;
   const bundle = buildSpatialBundle(canvas);
   const target = bundle.spatialNodes.find((n) => n.id === anchorNodeId);
   if (!target) return null;
 
-  const store = getCanvasStore(canvasId);
-  const cache = new Map<string, AgentNodePreview>();
+  const records = await handle.nodes.list();
   // One assembler for every neighbour: the node carries whatever the spatial
   // bundle knows (id / type; its `data.label` is always empty), and
-  // `describeNode` fills label + body from the sidecar, then derives the
+  // `describeNode` fills label + body from the record, then derives the
   // `file=` path, preview line, and `rev` token (in lock-step with the RFS
-  // `ETag`). Memoized so a node referenced twice is read once.
-  const describe = (n: SpatialNode): AgentNodePreview => {
-    const hit = cache.get(n.id);
-    if (hit) return hit;
-    const preview = describeNode(
-      store,
+  // `ETag`).
+  const describe = (n: SpatialNode): AgentNodePreview =>
+    describeNode(
       { id: n.id, type: n.type, ...(n.label ? { label: n.label } : {}) },
       'preview',
+      records.get(n.id)?.record ?? null,
     );
-    cache.set(n.id, preview);
-    return preview;
-  };
 
   return buildNodeNeighbourhoodContext(
     target,
diff --git a/apps/server/src/modules/canvas/node-prompt.test.ts b/apps/server/src/modules/canvas/node-prompt.test.ts
index e8f309348..8c509d479 100644
--- a/apps/server/src/modules/canvas/node-prompt.test.ts
+++ b/apps/server/src/modules/canvas/node-prompt.test.ts
@@ -6,42 +6,43 @@
  * ({@link describeNode} / {@link nodeLabel} / {@link renderNodes}).
  *
  * Focus: the ONE rule — the caller's own fields win, anything missing is
- * filled from the on-disk sidecar — plus the two agent-facing levels
+ * filled from the stored record — plus the two agent-facing levels
  * (`preview` / `outline`), `rev` presence, the summary/preview split, the
- * null-store degenerate path, and the `<node/>` rendering.
+ * no-record degenerate path, and the `<node/>` rendering.
  */
 
 import { describe, expect, it } from 'vitest';
 
 import { describeNode, nodeLabel, renderNodes } from './node-prompt.js';
 
-import type { CanvasStore, NodeContent } from '../storage/canvas-store.js';
+import type { NodeContent } from '../storage/index.js';
 
-/** Minimal stub: only `readNode` is exercised by this module. */
-function stubStore(
-  nodes: Record<string, Partial<NodeContent> | null>,
-): CanvasStore {
+/** One stored record, as a caller would have already read it. */
+function record(
+  id: string,
+  fields: Partial<NodeContent> | null,
+): NodeContent | null {
+  if (fields === null) return null;
   return {
-    readNode(id: string): NodeContent | null {
-      const n = nodes[id];
-      if (n == null) return null;
-      return {
-        nodeId: id,
-        type: 'note',
-        label: null,
-        content: '',
-        ...n,
-      } as NodeContent;
-    },
-  } as unknown as CanvasStore;
+    nodeId: id,
+    type: 'note',
+    label: null,
+    content: '',
+    ...fields,
+  } as NodeContent;
 }
 
 describe('describeNode — preview level', () => {
   it('fills label + body from the sidecar when the caller has none', () => {
-    const store = stubStore({
-      n1: { label: 'My Note', content: 'Hello body', summary: 'Abstract' },
-    });
-    const node = describeNode(store, { id: 'n1', type: 'note' }, 'preview');
+    const node = describeNode(
+      { id: 'n1', type: 'note' },
+      'preview',
+      record('n1', {
+        label: 'My Note',
+        content: 'Hello body',
+        summary: 'Abstract',
+      }),
+    );
 
     expect(node.label).toBe('My Note');
     // filename is derived from the (sidecar) label — the real on-disk path,
@@ -53,19 +54,22 @@ describe('describeNode — preview level', () => {
   });
 
   it("prefers the caller's own field over the sidecar (own wins)", () => {
-    const store = stubStore({ n1: { label: 'Sidecar Label', content: 'x' } });
     const node = describeNode(
-      store,
       { id: 'n1', type: 'note', label: 'Wire Label' },
       'preview',
+      record('n1', { label: 'Sidecar Label', content: 'x' }),
     );
     expect(node.label).toBe('Wire Label');
     expect(node.filename).toBe('nodes/Wire Label.md');
   });
 
   it('omits rev / summary / preview for a node with no body or summary', () => {
-    const store = stubStore({ n1: { label: 'Empty' } }); // content '' by default
-    const node = describeNode(store, { id: 'n1', type: 'note' }, 'preview');
+    // content '' by default
+    const node = describeNode(
+      { id: 'n1', type: 'note' },
+      'preview',
+      record('n1', { label: 'Empty' }),
+    );
     expect(node.label).toBe('Empty');
     expect(node.rev).toBeUndefined();
     expect(node.summary).toBeUndefined();
@@ -73,54 +77,54 @@ describe('describeNode — preview level', () => {
   });
 
   it('emits summary and preview as INDEPENDENT fields', () => {
-    const store = stubStore({
-      n1: { label: 'L', summary: 'The abstract', content: 'The full body' },
-    });
-    const node = describeNode(store, { id: 'n1', type: 'note' }, 'preview');
+    const node = describeNode(
+      { id: 'n1', type: 'note' },
+      'preview',
+      record('n1', {
+        label: 'L',
+        summary: 'The abstract',
+        content: 'The full body',
+      }),
+    );
     expect(node.summary).toBe('The abstract');
     expect(node.preview).toBe('The full body');
   });
 
   it('hashes rev from a source-backed node with no body', () => {
-    const store = stubStore({
-      n1: { type: 'image', label: 'Pic', src: 'artifacts/a.png' },
-    });
-    const node = describeNode(store, { id: 'n1', type: 'image' }, 'preview');
+    const node = describeNode(
+      { id: 'n1', type: 'image' },
+      'preview',
+      record('n1', { type: 'image', label: 'Pic', src: 'artifacts/a.png' }),
+    );
     expect(typeof node.rev).toBe('string');
     expect(node.preview).toBeUndefined(); // src is not a content preview
   });
 
-  it('with a null store, uses only the caller-supplied fields', () => {
+  it('with no stored record, uses only the caller-supplied fields', () => {
     const node = describeNode(
-      null,
       { id: 'n1', type: 'note', label: 'L', content: 'Body' },
       'preview',
+      null,
     );
     expect(node.label).toBe('L');
     expect(node.preview).toBe('Body');
     expect(typeof node.rev).toBe('string');
   });
 
-  it('with meta=null, forces "no sidecar" even when a store is passed', () => {
-    const store = stubStore({ n1: { label: 'Sidecar', content: 'x' } });
+  it('treats a null record as "this node has none"', () => {
     const node = describeNode(
-      store,
       { id: 'n1', type: 'note', label: 'Own' },
       'preview',
       null,
     );
     expect(node.label).toBe('Own');
-    expect(node.preview).toBeUndefined(); // sidecar body ignored
+    expect(node.preview).toBeUndefined();
   });
 });
 
 describe('describeNode — outline level', () => {
   it('layers spatial metadata on top of the sidecar-sourced fields', () => {
-    const store = stubStore({
-      n1: { label: 'Node', content: 'Body', summary: 'Sum' },
-    });
     const node = describeNode(
-      store,
       {
         id: 'n1',
         type: 'note',
@@ -130,6 +134,7 @@ describe('describeNode — outline level', () => {
         style: { color: 'red' },
       },
       'outline',
+      record('n1', { label: 'Node', content: 'Body', summary: 'Sum' }),
     );
     expect(node.position).toEqual({ x: 10, y: 20 });
     expect(node.size).toEqual({ width: 30, height: 40 });
@@ -144,9 +149,7 @@ describe('describeNode — outline level', () => {
   });
 
   it('carries an explicit absolutePosition distinct from parent-local position', () => {
-    const store = stubStore({ n1: { label: 'Node' } });
     const node = describeNode(
-      store,
       {
         id: 'n1',
         type: 'note',
@@ -156,6 +159,7 @@ describe('describeNode — outline level', () => {
         parentFrame: { id: 'f1', label: 'Frame' },
       },
       'outline',
+      record('n1', { label: 'Node' }),
     );
     expect(node.position).toEqual({ x: 50, y: 60 });
     expect(node.absolutePosition).toEqual({ x: 1050, y: 560 });
@@ -163,15 +167,15 @@ describe('describeNode — outline level', () => {
 });
 
 describe('nodeLabel', () => {
-  it('returns the sidecar label', () => {
-    const store = stubStore({ n1: { label: 'Frame Title' } });
-    expect(nodeLabel(store, 'n1')).toBe('Frame Title');
+  it('returns the record label', () => {
+    expect(nodeLabel(record('n1', { label: 'Frame Title' }))).toBe(
+      'Frame Title',
+    );
   });
 
-  it('returns undefined when the node has no sidecar or no label', () => {
-    const store = stubStore({ n1: null, n2: { label: null } });
-    expect(nodeLabel(store, 'n1')).toBeUndefined();
-    expect(nodeLabel(store, 'n2')).toBeUndefined();
+  it('returns undefined when there is no record or no label', () => {
+    expect(nodeLabel(record('n1', null))).toBeUndefined();
+    expect(nodeLabel(record('n2', { label: null }))).toBeUndefined();
   });
 });
 
@@ -205,10 +209,15 @@ describe('renderNodes', () => {
   });
 
   it('renders the summary/preview split from describeNode end-to-end', () => {
-    const store = stubStore({
-      n1: { label: 'Risks', summary: 'FX exposure', content: 'Full body' },
-    });
-    const node = describeNode(store, { id: 'n1', type: 'note' }, 'preview');
+    const node = describeNode(
+      { id: 'n1', type: 'note' },
+      'preview',
+      record('n1', {
+        label: 'Risks',
+        summary: 'FX exposure',
+        content: 'Full body',
+      }),
+    );
     const xml = renderNodes([node]);
     expect(xml).toBe(
       '<node id="n1" type="note" label="Risks" file="nodes/Risks.md" ' +
diff --git a/apps/server/src/modules/canvas/node-prompt.ts b/apps/server/src/modules/canvas/node-prompt.ts
index 9ea262b11..d81355e15 100644
--- a/apps/server/src/modules/canvas/node-prompt.ts
+++ b/apps/server/src/modules/canvas/node-prompt.ts
@@ -2,11 +2,11 @@
 // Licensed under the MIT license.
 
 /**
- * Store-aware "node → context" assembly.
+ * "node → context" assembly, over records the caller has already read.
  *
  * ONE rule: a node is carried into the prompt with whatever authored info
  * the caller already has; anything missing (label / body / summary / src)
- * is filled from the node's on-disk `.md` sidecar — the CANONICAL source.
+ * is filled from the node's stored record — the CANONICAL source.
  * Topology never persists `data.label` or note bodies, so a
  * caller that only has the raw canvas node hands in almost nothing and the
  * sidecar supplies the rest. This is the single place assembly lives, so
@@ -22,7 +22,14 @@
  *
  * The pure ladder (`buildAgentNodePreview` / `buildAgentNodeOutline`) stays
  * in `agent/node-ref.ts` and owns the filename rule / preview ladder / rev
- * hash; this module only adds the store lookup that feeds it.
+ * hash; this module only adds the merge that feeds it.
+ *
+ * Nothing here reaches storage. These builders used to take a `CanvasStore`
+ * and read a node lazily when the caller supplied no record, which made a
+ * pure merge into a synchronous Disk dependency that no async port could
+ * satisfy. The record is now an argument: each caller reads what it needs
+ * once, in whatever shape suits its request, and hands the result down
+ * (proposal §12.6.1).
  */
 
 import {
@@ -31,7 +38,7 @@ import {
 } from '../agent/node-ref.js';
 
 import type { AgentNodeOutline, AgentNodePreview } from '../agent/node-ref.js';
-import type { CanvasStore, NodeContent } from '../storage/canvas-store.js';
+import type { NodeContent } from '../storage/index.js';
 import type { CanvasNodeType } from '@huabu/shared';
 
 export { renderNodes } from '../agent/conversation/prompt/node-element.js';
@@ -69,16 +76,13 @@ function pick(own: unknown, fromStore: unknown): string | undefined {
 }
 
 /**
- * Merge the caller's authored fields with the sidecar's (own wins). Pass a
- * pre-read `meta` (e.g. from a batch {@link CanvasStore.readAllNodes}) to
- * skip the per-node disk read; pass `null` to force "no sidecar".
+ * Merge the caller's authored fields with the stored record's (own wins).
+ * `null` means the caller looked and there is no record.
  */
 function authoredFields(
-  store: CanvasStore | null,
   input: NodeInput,
-  meta?: NodeContent | null,
+  m: NodeContent | null,
 ): { label?: string; summary?: string; content?: string; src?: string } {
-  const m = meta !== undefined ? meta : store ? store.readNode(input.id) : null;
   const out: {
     label?: string;
     summary?: string;
@@ -101,33 +105,30 @@ function authoredFields(
 
 /**
  * Node → LLM-facing data object at the requested `level`. Carries the
- * caller's authored fields and fills any gaps from the sidecar; always
- * emits `rev` for content-bearing nodes (the freshness / CAS token).
- * `store` may be `null` (e.g. the store is unavailable) — then only the
- * caller's own fields are used.
+ * caller's authored fields and fills any gaps from `record`; always emits
+ * `rev` for content-bearing nodes (the freshness / CAS token). Pass `null`
+ * when the node has no stored record — then only the caller's own fields
+ * are used.
  */
 export function describeNode(
-  store: CanvasStore | null,
   input: NodeInput,
   level: 'preview',
-  meta?: NodeContent | null,
+  record: NodeContent | null,
 ): AgentNodePreview;
 export function describeNode(
-  store: CanvasStore | null,
   input: NodeInput,
   level: 'outline',
-  meta?: NodeContent | null,
+  record: NodeContent | null,
 ): AgentNodeOutline;
 export function describeNode(
-  store: CanvasStore | null,
   input: NodeInput,
   level: NodeLevel,
-  meta?: NodeContent | null,
+  record: NodeContent | null,
 ): AgentNodePreview | AgentNodeOutline {
   const common = {
     id: input.id,
     type: (input.type ?? 'note') as CanvasNodeType,
-    ...authoredFields(store, input, meta),
+    ...authoredFields(input, record),
   };
   if (level === 'outline') {
     return buildAgentNodeOutline({
@@ -147,15 +148,12 @@ export function describeNode(
 }
 
 /**
- * Resolve just a node's display label from the sidecar. Used for the
+ * Resolve just a node's display label from its stored record. Used for the
  * parent-frame `label=` hint — a plain string, not an agent-facing node,
  * so it needs no rev.
  */
-export function nodeLabel(
-  store: CanvasStore,
-  nodeId: string,
-  meta?: NodeContent | null,
-): string | undefined {
-  const m = meta !== undefined ? meta : store.readNode(nodeId);
-  return typeof m?.label === 'string' && m.label ? m.label : undefined;
+export function nodeLabel(record: NodeContent | null): string | undefined {
+  return typeof record?.label === 'string' && record.label
+    ? record.label
+    : undefined;
 }
diff --git a/apps/server/src/modules/canvas/space-query.ts b/apps/server/src/modules/canvas/space-query.ts
index df480323e..7864e2813 100644
--- a/apps/server/src/modules/canvas/space-query.ts
+++ b/apps/server/src/modules/canvas/space-query.ts
@@ -47,7 +47,7 @@ export async function executeSpaceQuery(
   switch (query.type) {
     case 'GET_SPACE_OUTLINE': {
       const { type: _type, ...params } = query;
-      const result = buildCanvasOutline(canvasId, params);
+      const result = await buildCanvasOutline(canvasId, params);
       if (!result) {
         throw new SpaceQueryError(
           `Canvas ${canvasId} not found`,
@@ -58,7 +58,7 @@ export async function executeSpaceQuery(
     }
     case 'INSPECT_NODES': {
       const { type: _type, ...params } = query;
-      const result = inspectNodes(canvasId, params);
+      const result = await inspectNodes(canvasId, params);
       if ('error' in result) throwQueryError(result.error);
       return {
         type: query.type,
@@ -67,7 +67,7 @@ export async function executeSpaceQuery(
     }
     case 'INSPECT_EDGES': {
       const { type: _type, ...params } = query;
-      const result = inspectEdges(canvasId, params);
+      const result = await inspectEdges(canvasId, params);
       if ('error' in result) throwQueryError(result.error);
       return {
         type: query.type,
diff --git a/apps/server/src/modules/canvas/world-portals.ts b/apps/server/src/modules/canvas/world-portals.ts
index 57625b23c..61e6b9d09 100644
--- a/apps/server/src/modules/canvas/world-portals.ts
+++ b/apps/server/src/modules/canvas/world-portals.ts
@@ -13,11 +13,7 @@ import {
 } from '@huabu/shared/canvas-engine';
 
 import { executeOnServer } from './canvas-executor.js';
-import {
-  listCanvasDirEntries,
-  requireWorldCanvasId,
-} from '../storage/canvas-dirs.js';
-import { getCanvasStore } from '../storage/index.js';
+import { getStructuredStore, space } from '../storage/index.js';
 
 const PORTAL_WIDTH = PORTAL_DEFAULT_WIDTH;
 const PORTAL_HEIGHT = PORTAL_DEFAULT_HEIGHT;
@@ -113,9 +109,13 @@ interface WorldPortalReconciliationPlan {
   inputs: CanvasNodeCreateInput[];
 }
 
-function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
-  const worldCanvasId = requireWorldCanvasId();
-  const world = getCanvasStore(worldCanvasId).read();
+async function planWorldPortalReconciliation(): Promise<WorldPortalReconciliationPlan> {
+  // One repository instance spans World resolution and membership, so a
+  // Workspace switch between them is rejected by the handle rather than
+  // reconciling one Workspace's Portals against another's Space list.
+  const spaces = getStructuredStore().spaces();
+  const worldCanvasId = await spaces.worldId();
+  const world = await space(worldCanvasId).read();
   if (!world) {
     throw new WorldPortalIntegrityError('World Canvas is not readable');
   }
@@ -141,9 +141,12 @@ function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
     portalByTarget.set(targetCanvasId, node);
   }
 
-  const spaces = listCanvasDirEntries()
-    .filter((entry) => !portalByTarget.has(entry.id))
-    .sort((a, b) => a.id.localeCompare(b.id));
+  const unreconciled = (await spaces.list())
+    .filter((summary) => !portalByTarget.has(summary.canvasId))
+    // `list()` promises no order, and slot allocation is positional, so the
+    // deterministic layout comes from sorting here rather than from a backend
+    // happening to scan in a stable order.
+    .sort((a, b) => a.canvasId.localeCompare(b.canvasId));
   const byId = new Map(nodes.map((node) => [node.id, node]));
   const occupied: Rect[] = nodes.map((node) => {
     const position = absolutePosition(node, byId);
@@ -155,7 +158,7 @@ function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
     };
   });
 
-  const inputs: CanvasNodeCreateInput[] = spaces.map((space) => {
+  const inputs: CanvasNodeCreateInput[] = unreconciled.map((summary) => {
     const position = findOpenPortalSlot(occupied);
     occupied.push({
       ...position,
@@ -168,7 +171,7 @@ function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
       position,
       size: { width: PORTAL_WIDTH, height: PORTAL_HEIGHT },
       data: {
-        targetCanvasId: space.id,
+        targetCanvasId: summary.canvasId,
       },
       selectOnCreate: false,
     };
@@ -178,7 +181,7 @@ function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
 }
 
 async function reconcileWorldPortalsOnce(): Promise<void> {
-  const { worldCanvasId, inputs } = planWorldPortalReconciliation();
+  const { worldCanvasId, inputs } = await planWorldPortalReconciliation();
   if (inputs.length === 0) return;
 
   const command: CanvasCommand = {
diff --git a/apps/server/src/modules/canvas/world-reference-resolver.test.ts b/apps/server/src/modules/canvas/world-reference-resolver.test.ts
index cb986841d..10ce2b9c5 100644
--- a/apps/server/src/modules/canvas/world-reference-resolver.test.ts
+++ b/apps/server/src/modules/canvas/world-reference-resolver.test.ts
@@ -219,14 +219,17 @@ describe('World reference resolution', () => {
     ).toBeUndefined();
   });
 
-  it('surfaces malformed source topology and sidecar data', async () => {
+  it('surfaces a malformed source Space record', async () => {
     writeFileSync(
       path.join(workspaceState.path, 'Project A', 'space.json'),
       '{',
       'utf8',
     );
+
     await expect(resolveWorldReferences('canvas-world')).rejects.toThrow();
+  });
 
+  it('still resolves a reference whose node record is hand-broken', async () => {
     const sourceRoot = writeCanvas('Project A', 'canvas-a', [
       {
         id: 'node-source',
@@ -240,6 +243,16 @@ describe('World reference resolution', () => {
       '---\ninvalid: "\n---\nbody',
       'utf8',
     );
-    await expect(resolveWorldReferences('canvas-world')).rejects.toThrow();
+
+    // Broken frontmatter is not a read failure — the storage port keeps such
+    // a node readable so it stays repairable through the content PUT. This
+    // resolver used to read source nodes strictly and 500 the whole World
+    // view for one hand-edited file; now the reference resolves with whatever
+    // survived the parse.
+    const { references } = await resolveWorldReferences('canvas-world');
+    const resolved = references.find(
+      (reference) => reference.referenceNodeId === 'node-ref-ok',
+    );
+    expect(resolved?.status).toBe('ok');
   });
 });
diff --git a/apps/server/src/modules/canvas/world-reference-resolver.ts b/apps/server/src/modules/canvas/world-reference-resolver.ts
index d3c2b7276..75d9b86d7 100644
--- a/apps/server/src/modules/canvas/world-reference-resolver.ts
+++ b/apps/server/src/modules/canvas/world-reference-resolver.ts
@@ -5,13 +5,9 @@ import { agentBindingSchema, getQuestionNodeStatus } from '@huabu/shared';
 
 import { describeNode } from './node-prompt.js';
 import { readWorldTargetCanvasesStrict } from './world-target-access.js';
-import {
-  isWorldCanvasId,
-  refreshCanvasDirIndex,
-} from '../storage/canvas-dirs.js';
-import { getCanvasStore } from '../storage/index.js';
+import { getStructuredStore, space } from '../storage/index.js';
 
-import type { CanvasFile, NodeContent } from '../storage/canvas-store.js';
+import type { CanvasFile, NodeContent } from '../storage/index.js';
 import type {
   CanvasNodeType,
   GetWorldReferencesResponse,
@@ -40,12 +36,12 @@ interface SourceCanvas {
 export async function resolveWorldReferences(
   worldCanvasId: string,
 ): Promise<GetWorldReferencesResponse> {
-  if (!isWorldCanvasId(worldCanvasId)) {
+  if (worldCanvasId !== (await getStructuredStore().spaces().worldId())) {
     throw new WorldReferenceResolutionError(
       'References can be resolved only for the World Canvas',
     );
   }
-  const world = getCanvasStore(worldCanvasId).read();
+  const world = await space(worldCanvasId).read();
   if (!world) {
     throw new WorldReferenceResolutionError('World Canvas is not readable');
   }
@@ -76,18 +72,23 @@ export async function resolveWorldReferences(
   }
 
   const sources = new Map<string, SourceCanvas>();
-  const sourceCanvases = readWorldTargetCanvasesStrict(sourceCanvasIds);
-  refreshCanvasDirIndex();
+  const sourceCanvases = await readWorldTargetCanvasesStrict(sourceCanvasIds);
   await Promise.all(
     [...sourceCanvasIds].map(async (canvasId) => {
-      const store = getCanvasStore(canvasId);
       const canvas = sourceCanvases.get(canvasId) ?? null;
-      sources.set(canvasId, {
-        canvas,
-        ...(canvas
-          ? { content: await store.readAllNodes({ strict: true }) }
-          : {}),
-      });
+      if (!canvas) {
+        sources.set(canvasId, { canvas: null });
+        return;
+      }
+      // A reference can address any node in the source Space, and the
+      // references are discovered as the World topology is walked below, so
+      // the source's nodes are read whole rather than per reference.
+      const records = await space(canvasId).nodes.list();
+      const content = new Map<string, NodeContent>();
+      for (const [nodeId, snapshot] of records) {
+        content.set(nodeId, snapshot.record);
+      }
+      sources.set(canvasId, { canvas, content });
     }),
   );
 
@@ -141,7 +142,6 @@ export async function resolveWorldReferences(
 
     const sourceContent = source.content?.get(target.nodeId) ?? null;
     const resolved = describeNode(
-      getCanvasStore(target.canvasId),
       {
         id: target.nodeId,
         type: sourceNode.type as CanvasNodeType,
diff --git a/apps/server/src/modules/canvas/world-target-access.ts b/apps/server/src/modules/canvas/world-target-access.ts
index 714a54174..5a932be95 100644
--- a/apps/server/src/modules/canvas/world-target-access.ts
+++ b/apps/server/src/modules/canvas/world-target-access.ts
@@ -1,18 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import path from 'node:path';
+import { getStructuredStore, space } from '../storage/index.js';
 
-import {
-  isWorldCanvasId,
-  refreshCanvasDirIndex,
-} from '../storage/canvas-dirs.js';
-import { getCanvasStore } from '../storage/index.js';
-import { SPACE_JSON_FILENAME } from '../storage/paths.js';
-import { getWorkspacePath } from '../workspace.js';
-
-import type { CanvasFile } from '../storage/canvas-store.js';
+import type { CanvasFile } from '../storage/index.js';
 
 interface StoredNode {
   type?: string;
@@ -26,38 +17,39 @@ export class WorldTargetAccessError extends Error {
   }
 }
 
-export function readWorldTargetCanvasesStrict(
+/**
+ * Read the Space records a World reference addresses, strictly.
+ *
+ * "Strictly" means an unreadable or malformed record raises rather than
+ * resolving to a broken reference: a World Portal that silently rendered as
+ * "missing" because a record could not be parsed would hide an integrity
+ * problem behind an ordinary-looking empty state.
+ *
+ * Every requested id appears in the result; one that has no Space maps to
+ * `null`. This used to walk the Workspace directory reading `space.json`
+ * files itself, which made a reference resolver a consumer of the Disk record
+ * layout, and made the read cost the whole Workspace rather than the ids
+ * asked for.
+ */
+export async function readWorldTargetCanvasesStrict(
   canvasIds: ReadonlySet<string>,
-): Map<string, CanvasFile | null> {
-  const matches = new Map<string, CanvasFile | null>(
-    [...canvasIds].map((canvasId) => [canvasId, null] as const),
+): Promise<Map<string, CanvasFile | null>> {
+  const entries = await Promise.all(
+    [...canvasIds].map(async (canvasId) => {
+      const record = await space(canvasId).read();
+      if (
+        record &&
+        (!Array.isArray(record.state?.nodes) ||
+          !Array.isArray(record.state.edges))
+      ) {
+        throw new WorldTargetAccessError(
+          `Canvas ${canvasId} has malformed topology`,
+        );
+      }
+      return [canvasId, record] as const;
+    }),
   );
-  const workspace = getWorkspacePath();
-  for (const entry of readdirSync(workspace)) {
-    if (entry.startsWith('.')) continue;
-    const root = path.join(workspace, entry);
-    if (!statSync(root).isDirectory()) continue;
-    const topologyPath = path.join(root, SPACE_JSON_FILENAME);
-    if (!existsSync(topologyPath)) continue;
-    const raw = readFileSync(topologyPath, 'utf8');
-    const canvas = JSON.parse(raw) as CanvasFile;
-    if (!canvasIds.has(canvas.canvasId)) continue;
-    if (matches.get(canvas.canvasId)) {
-      throw new WorldTargetAccessError(
-        `Canvas ${canvas.canvasId} has duplicate topology`,
-      );
-    }
-    if (
-      !Array.isArray(canvas.state?.nodes) ||
-      !Array.isArray(canvas.state.edges)
-    ) {
-      throw new WorldTargetAccessError(
-        `Canvas ${canvas.canvasId} has malformed topology`,
-      );
-    }
-    matches.set(canvas.canvasId, canvas);
-  }
-  return matches;
+  return new Map(entries);
 }
 
 /**
@@ -65,18 +57,20 @@ export function readWorldTargetCanvasesStrict(
  * Explicit cross-Canvas reads are available only from World and only through
  * one canonical Portal in the current World topology.
  */
-export function resolveWorldReadCanvasId(
+export async function resolveWorldReadCanvasId(
   ownerCanvasId: string,
   targetCanvasId: string | undefined,
-): string {
+): Promise<string> {
   if (!targetCanvasId) return ownerCanvasId;
-  if (!isWorldCanvasId(ownerCanvasId)) {
+
+  const spaces = getStructuredStore().spaces();
+  if (ownerCanvasId !== (await spaces.worldId())) {
     throw new WorldTargetAccessError(
       'targetCanvasId is available only in a World conversation',
     );
   }
 
-  const world = getCanvasStore(ownerCanvasId).read();
+  const world = await space(ownerCanvasId).read();
   if (!world) {
     throw new WorldTargetAccessError('World Canvas is not readable');
   }
@@ -90,7 +84,8 @@ export function resolveWorldReadCanvasId(
       `Canvas ${targetCanvasId} is not addressed by one canonical World Portal`,
     );
   }
-  readWorldTargetCanvasesStrict(new Set([targetCanvasId]));
-  refreshCanvasDirIndex();
+  // The Portal names it; confirm the Space itself is readable before handing
+  // the id to a tool that will read from it.
+  await readWorldTargetCanvasesStrict(new Set([targetCanvasId]));
   return targetCanvasId;
 }
diff --git a/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts b/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts
index 1780e1065..b77b9e376 100644
--- a/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts
+++ b/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts
@@ -115,6 +115,8 @@ function scanWorkspace(): void {
     }
   }
 
+  /** Stable id → the directory that already claimed it, for duplicate detection. */
+  const duplicateOf = new Map<string, string>();
   for (const entry of readdirSync(ws)) {
     if (entry.startsWith('.')) continue;
     const full = path.join(ws, entry);
@@ -124,7 +126,21 @@ function scanWorkspace(): void {
       continue;
     }
     const canvasEntry = readCanvasDirEntry(full, entry);
-    if (canvasEntry) index.add(canvasEntry);
+    if (!canvasEntry) continue;
+    // Two directories claiming one stable id used to resolve last-wins, so a
+    // Finder-side duplication of a Space silently became an arbitrary copy —
+    // and every later read, write, and delete addressed whichever the scan
+    // happened to see last. Raise instead: a loud failure of every catalogue
+    // read is recoverable by hand, an arbitrary winner is not.
+    const duplicate = duplicateOf.get(canvasEntry.id);
+    if (duplicate !== undefined) {
+      throw new Error(
+        `Space ${canvasEntry.id} has duplicate directories: ` +
+          `"${duplicate}" and "${entry}". Remove or re-identify one of them.`,
+      );
+    }
+    duplicateOf.set(canvasEntry.id, entry);
+    index.add(canvasEntry);
   }
   if (worldEntry && index.has(worldEntry.id)) {
     throw new Error(
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index f9eaf5e0c..4513f5be1 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -422,12 +422,7 @@ describe('root forwarding shims', () => {
     'storage/canvas-store.js': [
       'modules/canvas/canvas-search.test.ts',
       'modules/canvas/canvas-search.ts',
-      'modules/canvas/canvas-spatial.ts',
       'modules/canvas/canvas.route.ts',
-      'modules/canvas/node-prompt.test.ts',
-      'modules/canvas/node-prompt.ts',
-      'modules/canvas/world-reference-resolver.ts',
-      'modules/canvas/world-target-access.ts',
     ],
     'storage/canvas-dirs.js': [
       'modules/agent/tools/world-target-read.test.ts',
@@ -438,10 +433,7 @@ describe('root forwarding shims', () => {
       'modules/canvas/external-watcher.ts',
       'modules/canvas/world-portal-policy.ts',
       'modules/canvas/world-portals.test.ts',
-      'modules/canvas/world-portals.ts',
       'modules/canvas/world-reference-resolver.test.ts',
-      'modules/canvas/world-reference-resolver.ts',
-      'modules/canvas/world-target-access.ts',
       'modules/workspace.ts',
     ],
     'storage/paths.js': [
@@ -449,7 +441,6 @@ describe('root forwarding shims', () => {
       'modules/canvas/canvas.route.test.ts',
       'modules/canvas/canvas.route.ts',
       'modules/canvas/external-watcher.ts',
-      'modules/canvas/world-target-access.ts',
       'modules/workspace/migrations/migrate-acp-sessions.ts',
     ],
   };
diff --git a/apps/server/src/modules/storage/ports/structured.ts b/apps/server/src/modules/storage/ports/structured.ts
index 5ce4eed17..099988725 100644
--- a/apps/server/src/modules/storage/ports/structured.ts
+++ b/apps/server/src/modules/storage/ports/structured.ts
@@ -507,6 +507,14 @@ export interface SpaceNodes {
    * For work that genuinely spans the Space — executor prestate hydration,
    * the Space GET, the canvas outline, cross-node inspection. Iteration order
    * is unspecified; a caller that needs an order imposes it.
+   *
+   * One deliberate divergence from {@link read}: a record this scan cannot
+   * retrieve is **omitted**, where reading that id directly surfaces the
+   * failure. A caller naming one node needs to know it could not be served;
+   * a caller asking for the collection is better served the rest of it than
+   * refused everything because of one damaged member. Both still parse
+   * content the same lenient way, so a record a user broke by hand appears
+   * identically through either.
    */
   list(): Promise<Map<string, NodeSnapshot>>;
   /**

From da953bfb66a4a56818cc1a96e093524f44c3c9bc Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 17:35:33 +0800
Subject: [PATCH 06/20] refactor: move the remaining feature reads onto the
 storage ports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent Node placement, Task run launching, the SSE snapshot, web previews,
Portal-Pin routing, snapshot rendering, Interactive Views, the executor
prestate, external-note filtering, and the built-in file tools all read
through `space(canvasId)` now. Only `canvas.route.ts` and the search
adapter still hold a legacy store.

Each read is expressed in the shape its request actually has, rather than
whatever the synchronous store made convenient:

- Executor prestate hydration and Interactive View listing scan the Space,
  because they genuinely span it.
- Portal-Pin routing pre-reads exactly the source Spaces the command
  references. The set is knowable without running the passes — a source is
  either named by an update or referenced by a World node — so the memoized
  lazy reads become one batch and the passes stay synchronous.
- Snapshot rendering, `fs-read`, and Interactive View `get` read one node.

`importForeignNodeSources` stops taking a `CanvasStore` altogether: it used
it for one topology read and for `store.canvasId`, both of which it already
had as an argument.

Two places needed care rather than a mechanical await. The external-note
snapshot both reads and prunes pending items, and the caller depends on
registering its listener and taking the snapshot with no await between them,
so the known-node set is now read before that block and passed in. The
built-in file tools' node lookup reads its Space record up front for the same
reason — the lookup itself is called synchronously from the search passes,
and only that half crosses the port. Its directory scan stays put: those
tools are Disk-only, and mapping real filenames to records is what they are.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../modules/agent/agent-node.service.test.ts  |  2 +-
 .../src/modules/agent/agent-node.service.ts   | 18 ++++---
 .../modules/agent/tools/handlers/fs-read.ts   | 13 ++---
 .../agent/tools/handlers/fs-sandbox.ts        | 25 +++++----
 .../modules/agent/tools/handlers/fs-search.ts |  4 +-
 .../modules/canvas/canvas-command-router.ts   | 54 ++++++++++++-------
 .../src/modules/canvas/canvas-executor.ts     | 41 +++++++-------
 .../modules/canvas/external-watcher.test.ts   | 21 ++++----
 .../src/modules/canvas/external-watcher.ts    | 24 ++++++---
 .../modules/canvas/import-node-src.test.ts    | 24 +++------
 .../src/modules/canvas/import-node-src.ts     | 24 ++++-----
 .../src/modules/canvas/snapshot-nodes.ts      | 41 +++++++-------
 apps/server/src/modules/canvas/sync.route.ts  |  4 +-
 .../interactive-view.route.ts                 |  7 ++-
 .../interactive-view.service.ts               | 53 ++++++++++++------
 .../server/src/modules/remote_fs/rfs.route.ts |  9 ++--
 .../modules/storage/module-boundaries.test.ts |  1 -
 .../src/modules/task/run-launcher.test.ts     |  2 +-
 apps/server/src/modules/task/run-launcher.ts  | 12 ++---
 apps/server/src/modules/web/web.route.ts      | 10 ++--
 20 files changed, 217 insertions(+), 172 deletions(-)

diff --git a/apps/server/src/modules/agent/agent-node.service.test.ts b/apps/server/src/modules/agent/agent-node.service.test.ts
index 01ea97f79..04dd07003 100644
--- a/apps/server/src/modules/agent/agent-node.service.test.ts
+++ b/apps/server/src/modules/agent/agent-node.service.test.ts
@@ -62,7 +62,7 @@ function createHarness(options?: {
           : null,
       listSelectableProfileIds: () => options?.selectableIds ?? ['profile-a'],
     }),
-    readCanvasNodes: () =>
+    readCanvasNodes: async () =>
       options?.nodes === undefined
         ? [
             { id: NOTE_ID, type: 'note' },
diff --git a/apps/server/src/modules/agent/agent-node.service.ts b/apps/server/src/modules/agent/agent-node.service.ts
index 74b072e71..a7b8ba469 100644
--- a/apps/server/src/modules/agent/agent-node.service.ts
+++ b/apps/server/src/modules/agent/agent-node.service.ts
@@ -25,7 +25,7 @@ import {
 import { getLogger } from '../../utils/logger.js';
 import { executeCanvasCommandsOnHost } from '../canvas/canvas-command-router.js';
 import { buildSpatialBundle } from '../canvas/canvas-spatial.js';
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type { ExecuteOnServerOutput } from '../canvas/canvas-executor.js';
 
@@ -87,7 +87,7 @@ interface StoredNode {
 
 interface AgentNodeServiceDependencies {
   getProfileRegistry: () => AgentProfileRegistryPort | null;
-  readCanvasNodes: (canvasId: string) => StoredNode[] | null;
+  readCanvasNodes: (canvasId: string) => Promise<StoredNode[] | null>;
   execute: (input: {
     canvasId: string;
     commands: readonly CanvasCommand[];
@@ -95,8 +95,10 @@ interface AgentNodeServiceDependencies {
   }) => Promise<ExecuteOnServerOutput>;
 }
 
-function defaultReadCanvasNodes(canvasId: string): StoredNode[] | null {
-  const canvas = getCanvasStore(canvasId).read();
+async function defaultReadCanvasNodes(
+  canvasId: string,
+): Promise<StoredNode[] | null> {
+  const canvas = await space(canvasId).read();
   if (!canvas) return null;
   return canvas.state.nodes as StoredNode[];
 }
@@ -153,11 +155,11 @@ function resolveAnchor(
   return nodeId;
 }
 
-export function resolveAgentNodePosition(
+export async function resolveAgentNodePosition(
   canvasId: string,
   parentNodeId?: CanvasNodeId,
-): Point {
-  const canvas = getCanvasStore(canvasId).read();
+): Promise<Point> {
+  const canvas = await space(canvasId).read();
   if (!canvas) {
     throw new AgentNodeCreationError(
       'canvas_not_found',
@@ -201,7 +203,7 @@ export class AgentNodeService {
       throw error;
     }
 
-    const nodes = this.dependencies.readCanvasNodes(input.canvasId);
+    const nodes = await this.dependencies.readCanvasNodes(input.canvasId);
     if (!nodes) {
       throw new AgentNodeCreationError(
         'canvas_not_found',
diff --git a/apps/server/src/modules/agent/tools/handlers/fs-read.ts b/apps/server/src/modules/agent/tools/handlers/fs-read.ts
index 780da71bf..c3abcc468 100644
--- a/apps/server/src/modules/agent/tools/handlers/fs-read.ts
+++ b/apps/server/src/modules/agent/tools/handlers/fs-read.ts
@@ -39,7 +39,7 @@ import { normalizeRel, safeResolve } from './fs-sandbox.js';
 import { readSkillFile, resolveSkillPath } from '../../../../prompt/index.js';
 import { parseFrontmatter } from '../../../../utils/markdown-frontmatter.js';
 import { IMAGE_MIME_MAP, isVisionImageMime } from '../../../../utils/mime.js';
-import { getCanvasStore } from '../../../storage/index.js';
+import { space } from '../../../storage/index.js';
 import { readCanvasMemory, readWorkspaceMemory } from '../../memory/index.js';
 
 import type { readParamsSchema } from '../definitions.js';
@@ -76,25 +76,26 @@ const NODE_FILE_RE = /^nodes\/[^/]+\.md$/;
  * content, and the same revision used by executor CAS. When supplied, the
  * turn read-set receives that revision for guarded follow-up writes.
  */
-function projectNodeRead(
+async function projectNodeRead(
   rel: string,
   canvasId: string,
   fileText: string,
   readSet?: Map<string, string>,
-):
+): Promise<
   | {
       content: string;
       frontmatter: Record<string, unknown>;
       rev: string;
     }
-  | undefined {
+  | undefined
+> {
   if (!NODE_FILE_RE.test(rel)) return undefined;
   const parsed = parseFrontmatter(fileText);
   const rawId = parsed.meta['id'];
   const nodeId = typeof rawId === 'string' && rawId ? rawId : undefined;
   if (!nodeId) return undefined;
   try {
-    const nc = getCanvasStore(canvasId).readNode(nodeId);
+    const nc = (await space(canvasId).nodes.read(nodeId))?.record;
     if (!nc) return undefined;
     const rev = nodeRevisionOf({
       content: nc.content,
@@ -260,7 +261,7 @@ export async function handleRead(
   }
 
   const text = buf.toString('utf8');
-  const nodeRead = projectNodeRead(rel, args.canvasId, text, readSet);
+  const nodeRead = await projectNodeRead(rel, args.canvasId, text, readSet);
   if (nodeRead) {
     return renderTextResponse(rel, nodeRead.content, offset, limit, {
       frontmatter: nodeRead.frontmatter,
diff --git a/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts b/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
index 62ef0b5d2..90de3f1b6 100644
--- a/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
+++ b/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
@@ -30,7 +30,7 @@ import { readFileSync, readdirSync, statSync, type Dirent } from 'node:fs';
 import path from 'node:path';
 
 import { parseFrontmatter } from '../../../../utils/markdown-frontmatter.js';
-import { getCanvasStore, space } from '../../../storage/index.js';
+import { space } from '../../../storage/index.js';
 
 // ─── Always-skipped directory names ─────────────────────────────────────────
 
@@ -320,22 +320,27 @@ export interface NodeMeta {
  * frontmatter `id:` plus `space.json` metadata.
  * Returns `null` otherwise.
  */
-export function makeNodeLookup(
+export async function makeNodeLookup(
   canvasId: string,
-): (canvasRelPath: string) => NodeMeta | null {
+): Promise<(canvasRelPath: string) => NodeMeta | null> {
+  // The Space record is read up front rather than inside the lazy build: the
+  // returned lookup is called synchronously from the search passes, and only
+  // this half of the work crosses the storage port. The directory scan below
+  // stays where it is — the built-in file tools are Disk-only (§6.4.3,
+  // disposition A) and this maps real filenames to records.
+  let file;
+  try {
+    file = await space(canvasId).read();
+  } catch {
+    file = null;
+  }
+
   let cache: Map<string, NodeMeta> | null = null;
   const ensure = (): Map<string, NodeMeta> => {
     if (cache) return cache;
 
     const byId = new Map<string, NodeMeta>();
     const byPath = new Map<string, NodeMeta>();
-
-    let file;
-    try {
-      file = getCanvasStore(canvasId).read();
-    } catch {
-      file = null;
-    }
     if (file) {
       const nodes = (file.state.nodes ?? []) as Array<Record<string, unknown>>;
       for (const n of nodes) {
diff --git a/apps/server/src/modules/agent/tools/handlers/fs-search.ts b/apps/server/src/modules/agent/tools/handlers/fs-search.ts
index d4fe60e43..a90c68b85 100644
--- a/apps/server/src/modules/agent/tools/handlers/fs-search.ts
+++ b/apps/server/src/modules/agent/tools/handlers/fs-search.ts
@@ -168,7 +168,7 @@ export async function handleGrep(args: GrepArgs): Promise<string> {
   const globRe = effectiveGlob ? globToRegExp(effectiveGlob) : null;
   const effectiveLimit = Math.max(1, limit ?? DEFAULT_GREP_LIMIT);
   const ctxN = Math.max(0, ctxLines ?? 0);
-  const lookup = makeNodeLookup(args.canvasId);
+  const lookup = await makeNodeLookup(args.canvasId);
   const deadline = Date.now() + GREP_DEADLINE_MS;
 
   // Enumerate candidate files, recording each as a canvas-relative
@@ -289,7 +289,7 @@ export async function handleFind(args: FindArgs): Promise<string> {
   }
 
   const effectiveLimit = Math.max(1, limit ?? DEFAULT_FIND_LIMIT);
-  const lookup = makeNodeLookup(args.canvasId);
+  const lookup = await makeNodeLookup(args.canvasId);
 
   const results: Array<Record<string, unknown>> = [];
   let truncated = false;
diff --git a/apps/server/src/modules/canvas/canvas-command-router.ts b/apps/server/src/modules/canvas/canvas-command-router.ts
index fc38724ed..e85d14d6f 100644
--- a/apps/server/src/modules/canvas/canvas-command-router.ts
+++ b/apps/server/src/modules/canvas/canvas-command-router.ts
@@ -23,11 +23,7 @@ import {
 } from './canvas-executor.js';
 import { reconcileWorldPortals } from './world-portals.js';
 import { createKeyedMutex } from '../../utils/keyed-mutex.js';
-import {
-  listCanvasDirEntries,
-  requireWorldCanvasId,
-} from '../storage/canvas-dirs.js';
-import { getCanvasStore } from '../storage/index.js';
+import { getStructuredStore, space } from '../storage/index.js';
 
 type PortalCommand = Extract<CanvasCommand, { type: 'SET_PORTAL_NODE_PINS' }>;
 const withPortalRoutingMutex = createKeyedMutex<string>();
@@ -210,7 +206,7 @@ async function ensureCanonicalPortals(
   worldCanvasId: string,
   commands: readonly PortalCommand[],
 ): Promise<void> {
-  const world = getCanvasStore(worldCanvasId).read() as StoredCanvas | null;
+  const world = (await space(worldCanvasId).read()) as StoredCanvas | null;
   const targets = new Set<string>();
   for (const node of (world?.state.nodes ?? []) as NestableNode[]) {
     const target = portalTarget(node);
@@ -249,14 +245,15 @@ async function executeCanvasCommandsOnHostInternal(
 
   assertConsistentDesiredStates(portalCommands);
 
-  const worldCanvasId = requireWorldCanvasId();
+  const spaces = getStructuredStore().spaces();
+  const worldCanvasId = await spaces.worldId();
   if (!routingLockHeld) {
     return withPortalRoutingMutex(worldCanvasId, () =>
       executeCanvasCommandsOnHostInternal(input, true),
     );
   }
   await ensureCanonicalPortals(worldCanvasId, portalCommands);
-  const world = getCanvasStore(worldCanvasId).read() as StoredCanvas | null;
+  const world = (await space(worldCanvasId).read()) as StoredCanvas | null;
   if (!world || !Array.isArray(world.state.nodes)) {
     throw new CanvasCommandRoutingError('World Canvas is unavailable');
   }
@@ -335,18 +332,39 @@ async function executeCanvasCommandsOnHostInternal(
   }
 
   const liveCanvasIds = new Set(
-    listCanvasDirEntries().map((entry) => entry.id),
+    (await spaces.list()).map((summary) => summary.canvasId),
   );
-  const sourceStates = new Map<string, SourceState | null>();
-  const readSource = (canvasId: string): SourceState | null => {
-    if (!sourceStates.has(canvasId)) {
-      sourceStates.set(
-        canvasId,
-        sourceStateOf(getCanvasStore(canvasId).read() as StoredCanvas | null),
-      );
+
+  // Every source Space the passes below can ask about, read once up front.
+  // The set is knowable without running them: a source is either named by a
+  // Portal-Pin update or referenced by a World node, and both are already in
+  // hand. That keeps the reads to what this command touches while letting the
+  // passes themselves stay synchronous.
+  const referencedCanvasIds = new Set<string>();
+  for (const command of portalCommands) {
+    for (const update of command.updates) {
+      referencedCanvasIds.add(update.sourceCanvasId);
     }
-    return sourceStates.get(canvasId) ?? null;
-  };
+  }
+  for (const node of worldNodes) {
+    const target = referenceTarget(node);
+    if (target) referencedCanvasIds.add(target.canvasId);
+  }
+  const sourceStates = new Map<string, SourceState | null>(
+    await Promise.all(
+      [...referencedCanvasIds].map(
+        async (canvasId) =>
+          [
+            canvasId,
+            sourceStateOf(
+              (await space(canvasId).read()) as StoredCanvas | null,
+            ),
+          ] as const,
+      ),
+    ),
+  );
+  const readSource = (canvasId: string): SourceState | null =>
+    sourceStates.get(canvasId) ?? null;
 
   const requested = new Map<string, boolean>();
   for (const command of portalCommands) {
diff --git a/apps/server/src/modules/canvas/canvas-executor.ts b/apps/server/src/modules/canvas/canvas-executor.ts
index a59a62b46..97b5eadc7 100644
--- a/apps/server/src/modules/canvas/canvas-executor.ts
+++ b/apps/server/src/modules/canvas/canvas-executor.ts
@@ -65,14 +65,12 @@ import {
 import { getLogger } from '../../utils/logger.js';
 import {
   space,
-  getCanvasStore,
-  getStructuredStore,
   withCanvasMutex,
   type BlobScope,
   type CanvasFile,
-  type CanvasStore,
   type DeltaLogEntry,
   type NodeContent,
+  type NodeSnapshot,
   type SpaceNodeMutation,
 } from '../storage/index.js';
 
@@ -140,7 +138,7 @@ function stripNodesForCanvas(nodes: readonly CanvasNode[]): CanvasNode[] {
 }
 
 function hydrateNodes(
-  store: CanvasStore,
+  records: ReadonlyMap<string, NodeSnapshot>,
   nodes: readonly CanvasNode[],
 ): CanvasNode[] {
   return nodes.map((node) => {
@@ -149,12 +147,7 @@ function hydrateNodes(
     const nodeType = typeof node.type === 'string' ? node.type : '';
     if (!MD_BACKED_NODE_TYPES.has(nodeType)) return { ...node };
 
-    let content: NodeContent | null = null;
-    try {
-      content = store.readNode(nodeId);
-    } catch {
-      content = null;
-    }
+    const content = records.get(nodeId)?.record ?? null;
     if (!content) return { ...node };
 
     const data: Record<string, unknown> = { ...(node.data ?? {}) };
@@ -692,11 +685,7 @@ export async function executeOnServer(
   // writes to the same canvas. Idempotent for values that are already artifact
   // keys / `/api/` URLs / `data:` URIs.
   if (originator.source === 'agent') {
-    commands = await importForeignNodeSources(
-      getCanvasStore(canvasId),
-      canvasId,
-      commands,
-    );
+    commands = await importForeignNodeSources(canvasId, commands);
 
     // For image nodes with only width specified, calculate height from actual
     // image aspect ratio. This ensures correct proportions for all image sources.
@@ -704,18 +693,21 @@ export async function executeOnServer(
   }
 
   return await withCanvasMutex(canvasId, async () => {
-    const store = getCanvasStore(canvasId);
-    const handle = getStructuredStore().space(canvasId);
-    const canvas = store.read();
+    const handle = space(canvasId);
+    const canvas = await handle.read();
     if (!canvas) throw new CanvasNotFoundError(canvasId);
 
+    // Executor prestate is whole-Space work: every md-backed node in the
+    // topology needs its stored content before the engine sees it.
+    const records = await handle.nodes.list();
+
     const fromVersion = canvas.version;
 
     // Hydrate per-node content from .md sidecars before the engine sees
     // the prestate — handlers like MERGE_NODE_DATA need the current
     // `data.content` to merge against, but topology never carries it.
     const prestateNodes = hydrateNodes(
-      store,
+      records,
       canvas.state.nodes as CanvasNode[],
     );
     const prestateEdges = (canvas.state.edges ?? []) as CanvasEdge[];
@@ -1123,14 +1115,17 @@ export async function applyDeltasOnServer(input: {
   const { canvasId, originator, runId } = input;
 
   return await withCanvasMutex(canvasId, async () => {
-    const store = getCanvasStore(canvasId);
-    const handle = getStructuredStore().space(canvasId);
-    const canvas = store.read();
+    const handle = space(canvasId);
+    const canvas = await handle.read();
     if (!canvas) throw new CanvasNotFoundError(canvasId);
 
+    // Executor prestate is whole-Space work: every md-backed node in the
+    // topology needs its stored content before the engine sees it.
+    const records = await handle.nodes.list();
+
     const fromVersion = canvas.version;
     const prestateNodes = hydrateNodes(
-      store,
+      records,
       canvas.state.nodes as CanvasNode[],
     );
     const prestateEdges = (canvas.state.edges ?? []) as CanvasEdge[];
diff --git a/apps/server/src/modules/canvas/external-watcher.test.ts b/apps/server/src/modules/canvas/external-watcher.test.ts
index cf3de2474..b2b26e777 100644
--- a/apps/server/src/modules/canvas/external-watcher.test.ts
+++ b/apps/server/src/modules/canvas/external-watcher.test.ts
@@ -68,18 +68,19 @@ vi.mock('../storage/canvas-dirs.js', () => ({
   listAllCanvasDirEntries: () => canvasDirs.list(),
 }));
 
-const canvasStore = vi.hoisted(() => ({
-  read: vi.fn(() => ({ state: { nodes: [] } })),
+const spaceHandle = vi.hoisted(() => ({
+  read: vi.fn(async () => ({ state: { nodes: [] } })),
 }));
 
-// The facade is stubbed for the store, but the handle helpers must stay the
-// real ones: these cases drive `withSpaceDirHandlesReleased` and assert the
-// watcher released its handles, which only works if both sides share the one
-// module instance that holds the registry.
+// The facade is stubbed for the Space handle, but the directory-handle
+// helpers must stay the real ones: these cases drive
+// `withSpaceDirHandlesReleased` and assert the watcher released its handles,
+// which only works if both sides share the one module instance that holds the
+// registry.
 vi.mock('../storage/index.js', async () => {
   const handles = await import('../storage/backends/disk/space-dir-handles.js');
   return {
-    getCanvasStore: () => canvasStore,
+    space: () => spaceHandle,
     registerSpaceDirHandleOwner: handles.registerSpaceDirHandleOwner,
     withSpaceDirHandlesReleased: handles.withSpaceDirHandlesReleased,
   };
@@ -146,7 +147,7 @@ beforeEach(() => {
     isFile: () => true,
     isDirectory: () => false,
   });
-  canvasStore.read.mockClear();
+  spaceHandle.read.mockClear();
   canvasDirs.list.mockReturnValue([]);
   state.configured = true;
 });
@@ -552,7 +553,7 @@ describe('openExternalNoteSession', () => {
 
     emitNativeWatcherEvent('later.md');
     await vi.waitFor(() => {
-      expect(canvasStore.read).toHaveBeenCalled();
+      expect(spaceHandle.read).toHaveBeenCalled();
     });
     expect(listener).not.toHaveBeenCalled();
 
@@ -687,7 +688,7 @@ describe('native note events', () => {
     // A repeat observation replaces the entry instead of duplicating it.
     emitNativeWatcherEvent('later.md');
     await vi.waitFor(() => {
-      expect(canvasStore.read.mock.calls.length).toBeGreaterThan(1);
+      expect(spaceHandle.read.mock.calls.length).toBeGreaterThan(1);
     });
     expect(events).toHaveLength(1);
 
diff --git a/apps/server/src/modules/canvas/external-watcher.ts b/apps/server/src/modules/canvas/external-watcher.ts
index fc37894a7..f9a4cb435 100644
--- a/apps/server/src/modules/canvas/external-watcher.ts
+++ b/apps/server/src/modules/canvas/external-watcher.ts
@@ -33,7 +33,7 @@ import path from 'node:path';
 import { getLogger } from '../../utils/logger.js';
 import { parseFrontmatter } from '../../utils/markdown-frontmatter.js';
 import { listAllCanvasDirEntries } from '../storage/canvas-dirs.js';
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 import { registerSpaceDirHandleOwner } from '../storage/index.js';
 import { SPACE_JSON_FILENAME } from '../storage/paths.js';
 import { getWorkspacePath, isWorkspaceConfigured } from '../workspace.js';
@@ -130,8 +130,8 @@ function noteIdsFromCanvas(canvas: CanvasFile | null): Set<string> {
   return ids;
 }
 
-function canvasNoteIds(canvasId: string): Set<string> {
-  return noteIdsFromCanvas(getCanvasStore(canvasId).read());
+async function canvasNoteIds(canvasId: string): Promise<Set<string>> {
+  return noteIdsFromCanvas(await space(canvasId).read());
 }
 
 async function readInitialCanvasNoteIds(
@@ -195,8 +195,16 @@ function forgetItem(session: ActiveSpaceWatch, relativePath: string): void {
   emit(session, { type: 'removed', data: { relativePath } });
 }
 
-function snapshotOf(session: ActiveSpaceWatch): ExternalNoteItem[] {
-  const known = canvasNoteIds(session.canvasId);
+/**
+ * `known` is passed in rather than read here because this must stay
+ * synchronous: it both reads and prunes `pendingItems`, and the caller relies
+ * on registering its listener and taking the snapshot without an await
+ * between them, so no event can slip through.
+ */
+function snapshotOf(
+  session: ActiveSpaceWatch,
+  known: ReadonlySet<string>,
+): ExternalNoteItem[] {
   const out: ExternalNoteItem[] = [];
   for (const [rel, item] of session.pendingItems) {
     if (item.noteId && known.has(item.noteId)) {
@@ -228,7 +236,7 @@ function scheduleNodeEvent(session: ActiveSpaceWatch, basename: string): void {
         .then(async (fileStat) => {
           if (!fileStat.isFile()) return;
           const item = await buildItem(absPath, relativePath, () =>
-            Promise.resolve(canvasNoteIds(session.canvasId)),
+            canvasNoteIds(session.canvasId),
           );
           if (!item || !isSessionCurrent(session, stamp)) return;
           recordItem(session, item);
@@ -787,11 +795,13 @@ export async function openExternalNoteSession(
     await ensureInitialScan(active);
   }
 
+  const known = await canvasNoteIds(active.canvasId);
+
   // Registering the listener and reading the snapshot must stay in one
   // synchronous block so no event can slip between them.
   if (released || !isSessionCurrent(active)) return { snapshot: [], close };
   active.listeners.add(listener);
-  return { snapshot: snapshotOf(active), close };
+  return { snapshot: snapshotOf(active, known), close };
 }
 
 /** Remove and return a pending item — used by the import endpoint. */
diff --git a/apps/server/src/modules/canvas/import-node-src.test.ts b/apps/server/src/modules/canvas/import-node-src.test.ts
index 731608357..5df3b819b 100644
--- a/apps/server/src/modules/canvas/import-node-src.test.ts
+++ b/apps/server/src/modules/canvas/import-node-src.test.ts
@@ -105,7 +105,6 @@ function seedWebNode(canvasId: string, nodeId: string, src: string): void {
 describe('importForeignNodeSources — web nodes', () => {
   it('relocates a locally-staged HTML upload into .artifacts/ and reclaims it', async () => {
     const canvasId = 'c-web-local';
-    const store = getCanvasStore(canvasId);
     const uploadAbs = stageUpload(
       canvasId,
       'index.html',
@@ -125,7 +124,7 @@ describe('importForeignNodeSources — web nodes', () => {
       },
     ];
 
-    const out = await importForeignNodeSources(store, canvasId, commands);
+    const out = await importForeignNodeSources(canvasId, commands);
     const src = firstSrc(out);
 
     // Rewritten to a bare artifact key…
@@ -140,7 +139,6 @@ describe('importForeignNodeSources — web nodes', () => {
 
   it('rejects a non-HTML local upload without reclaiming it', async () => {
     const canvasId = 'c-web-invalid-local';
-    const store = getCanvasStore(canvasId);
     const uploadAbs = stageUpload(canvasId, 'document.pdf', 'not html');
 
     const commands: CanvasCommand[] = [
@@ -156,7 +154,7 @@ describe('importForeignNodeSources — web nodes', () => {
       },
     ];
 
-    const out = await importForeignNodeSources(store, canvasId, commands);
+    const out = await importForeignNodeSources(canvasId, commands);
 
     expect(firstSrc(out)).toBe('upload/document.pdf');
     expect(existsSync(uploadAbs)).toBe(true);
@@ -164,7 +162,6 @@ describe('importForeignNodeSources — web nodes', () => {
 
   it('leaves a live remote URL untouched (never downloads it)', async () => {
     const canvasId = 'c-web-remote';
-    const store = getCanvasStore(canvasId);
     const remote = 'https://example.com/some/page.html';
 
     const commands: CanvasCommand[] = [
@@ -180,13 +177,12 @@ describe('importForeignNodeSources — web nodes', () => {
       },
     ];
 
-    const out = await importForeignNodeSources(store, canvasId, commands);
+    const out = await importForeignNodeSources(canvasId, commands);
     expect(firstSrc(out)).toBe(remote);
   });
 
   it('leaves a data: URL untouched', async () => {
     const canvasId = 'c-web-data';
-    const store = getCanvasStore(canvasId);
     const dataUrl = 'data:text/html,<h1>inline</h1>';
 
     const commands: CanvasCommand[] = [
@@ -202,7 +198,7 @@ describe('importForeignNodeSources — web nodes', () => {
       },
     ];
 
-    const out = await importForeignNodeSources(store, canvasId, commands);
+    const out = await importForeignNodeSources(canvasId, commands);
     expect(firstSrc(out)).toBe(dataUrl);
   });
 
@@ -210,7 +206,6 @@ describe('importForeignNodeSources — web nodes', () => {
     const canvasId = 'c-web-merge-local';
     const nodeId = 'node-web-merge-local';
     seedWebNode(canvasId, nodeId, 'https://example.com/old');
-    const store = getCanvasStore(canvasId);
     const uploadAbs = stageUpload(
       canvasId,
       'replacement.html',
@@ -223,7 +218,7 @@ describe('importForeignNodeSources — web nodes', () => {
       },
     ];
 
-    const out = await importForeignNodeSources(store, canvasId, commands);
+    const out = await importForeignNodeSources(canvasId, commands);
     const src = firstPatchedSrc(out);
 
     expect(src).toMatch(/^artifact-[^/]+\.html$/);
@@ -237,7 +232,6 @@ describe('importForeignNodeSources — web nodes', () => {
     const canvasId = 'c-web-merge-remote';
     const nodeId = 'node-web-merge-remote';
     seedWebNode(canvasId, nodeId, 'https://example.com/old');
-    const store = getCanvasStore(canvasId);
     const remote = 'https://example.com/new';
     const commands: CanvasCommand[] = [
       {
@@ -246,7 +240,7 @@ describe('importForeignNodeSources — web nodes', () => {
       },
     ];
 
-    const out = await importForeignNodeSources(store, canvasId, commands);
+    const out = await importForeignNodeSources(canvasId, commands);
 
     expect(firstPatchedSrc(out)).toBe(remote);
   });
@@ -255,7 +249,6 @@ describe('importForeignNodeSources — web nodes', () => {
 describe('importForeignNodeSources — media nodes (regression)', () => {
   it('still relocates a locally-staged image upload', async () => {
     const canvasId = 'c-image-local';
-    const store = getCanvasStore(canvasId);
     stageUpload(canvasId, 'pic.png', 'not-a-real-png-but-bytes');
 
     const commands: CanvasCommand[] = [
@@ -271,7 +264,7 @@ describe('importForeignNodeSources — media nodes (regression)', () => {
       },
     ];
 
-    const out = await importForeignNodeSources(store, canvasId, commands);
+    const out = await importForeignNodeSources(canvasId, commands);
     const src = firstSrc(out);
     expect(src).toMatch(/^artifact-[^/]+\.png$/);
     expect(src).toBeDefined();
@@ -281,7 +274,6 @@ describe('importForeignNodeSources — media nodes (regression)', () => {
 
   it('canonicalizes an artifact path that leaves and re-enters the Space', async () => {
     const canvasId = 'c-image-reentered';
-    const store = getCanvasStore(canvasId);
     const spaceDir = diskDirOf(canvasId);
     const artifactsDir = path.join(spaceDir, '.artifacts');
     mkdirSync(artifactsDir, { recursive: true });
@@ -306,7 +298,7 @@ describe('importForeignNodeSources — media nodes (regression)', () => {
       },
     ];
 
-    const out = await importForeignNodeSources(store, canvasId, commands);
+    const out = await importForeignNodeSources(canvasId, commands);
 
     expect(firstSrc(out)).toBe('pic.png');
   });
diff --git a/apps/server/src/modules/canvas/import-node-src.ts b/apps/server/src/modules/canvas/import-node-src.ts
index 77f39c27f..9a33d14f9 100644
--- a/apps/server/src/modules/canvas/import-node-src.ts
+++ b/apps/server/src/modules/canvas/import-node-src.ts
@@ -44,8 +44,6 @@ import {
 } from '../agent/tools/handlers/fs-sandbox.js';
 import { space } from '../storage/index.js';
 
-import type { CanvasStore } from '../storage/index.js';
-
 const log = getLogger('canvas.import-node-src');
 
 /** Hidden RFS scratch dir; only files here are reclaimed (move semantics). */
@@ -137,7 +135,6 @@ function srcNormalizeMode(type: string): SrcNormalizeMode | null {
  * preserved so a single unreachable URL never fails the whole batch.
  */
 export async function importForeignNodeSources(
-  store: CanvasStore,
   canvasId: string,
   commands: readonly CanvasCommand[],
 ): Promise<CanvasCommand[]> {
@@ -145,10 +142,10 @@ export async function importForeignNodeSources(
   // patches (CREATE_NODES carries `nodeType` inline). Node type is immutable,
   // so reading the pre-batch snapshot here is race-free.
   let typeById: Map<string, string> | null = null;
-  const nodeType = (nodeId: string): string => {
+  const nodeType = async (nodeId: string): Promise<string> => {
     if (!typeById) {
       typeById = new Map();
-      const canvas = store.read();
+      const canvas = await space(canvasId).read();
       for (const raw of canvas?.state.nodes ?? []) {
         const n = raw as { id?: unknown; type?: unknown };
         if (typeof n.id === 'string' && typeof n.type === 'string') {
@@ -168,7 +165,6 @@ export async function importForeignNodeSources(
           if (!mode) return node;
           const data = node.data as Record<string, unknown> | undefined;
           const key = await resolveImportedSrc(
-            store,
             canvasId,
             data?.['src'],
             mode.allowRemoteDownload,
@@ -189,10 +185,9 @@ export async function importForeignNodeSources(
     if (cmd.type === 'MERGE_NODE_DATA') {
       const patches = await Promise.all(
         cmd.patches.map(async (entry) => {
-          const mode = srcNormalizeMode(nodeType(entry.nodeId));
+          const mode = srcNormalizeMode(await nodeType(entry.nodeId));
           if (!mode) return entry;
           const key = await resolveImportedSrc(
-            store,
             canvasId,
             entry.patch?.['src'],
             mode.allowRemoteDownload,
@@ -223,7 +218,6 @@ export async function importForeignNodeSources(
  * preserved in place and left unchanged.
  */
 async function resolveImportedSrc(
-  store: CanvasStore,
   canvasId: string,
   raw: unknown,
   allowRemoteDownload: boolean,
@@ -249,7 +243,7 @@ async function resolveImportedSrc(
     ) {
       return null;
     }
-    return await downloadToArtifact(store, src, pathname);
+    return await downloadToArtifact(canvasId, src, pathname);
   }
 
   // Already an in-app API path — leave it for the web resolver.
@@ -296,12 +290,12 @@ async function resolveImportedSrc(
     return null;
   }
 
-  return await copyToArtifact(store, absPath, physicalRel);
+  return await copyToArtifact(canvasId, absPath, physicalRel);
 }
 
 /** Copy a canvas-local file into blob storage, returning the new key. */
 async function copyToArtifact(
-  store: CanvasStore,
+  canvasId: string,
   absPath: string,
   physicalRel: string,
 ): Promise<string | null> {
@@ -310,7 +304,7 @@ async function copyToArtifact(
     const id = createId('artifact');
     const key = `${id}${ext}`;
     const buffer = await readFile(absPath);
-    await space(store.canvasId).blobs.put(key, buffer);
+    await space(canvasId).blobs.put(key, buffer);
 
     // Move semantics: reclaim RFS scratch uploads once they are safely
     // stored. Never delete user node files or other canvas content —
@@ -335,7 +329,7 @@ async function copyToArtifact(
 
 /** Download an online resource into `.artifacts/`, returning the new key. */
 async function downloadToArtifact(
-  store: CanvasStore,
+  canvasId: string,
   url: string,
   pathname: string,
 ): Promise<string | null> {
@@ -366,7 +360,7 @@ async function downloadToArtifact(
     }
     const ext = pickDownloadExt(pathname, contentType);
     const key = `${createId('artifact')}${ext}`;
-    await space(store.canvasId).blobs.put(key, buffer);
+    await space(canvasId).blobs.put(key, buffer);
     return key;
   } catch (err) {
     log.warn({ err, url }, 'Failed to download online node src into artifacts');
diff --git a/apps/server/src/modules/canvas/snapshot-nodes.ts b/apps/server/src/modules/canvas/snapshot-nodes.ts
index 356f5c048..faf621b69 100644
--- a/apps/server/src/modules/canvas/snapshot-nodes.ts
+++ b/apps/server/src/modules/canvas/snapshot-nodes.ts
@@ -68,8 +68,9 @@ import {
 import { getSketchRenderedSize } from '@huabu/shared/canvas-engine';
 
 import { RASTERIZABLE_IMAGE_EXT_MIME } from '../../utils/mime.js';
-import { space, getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
+import type { Space } from '../storage/index.js';
 import type {
   SketchNodeData,
   SnapshotNodesQueryParams,
@@ -404,14 +405,14 @@ const IMAGE_EXT_MIME = RASTERIZABLE_IMAGE_EXT_MIME;
  * Returns `null` when the node has no sidecar or the key is
  * missing/blank.
  */
-function readSidecarString(
-  store: ReturnType<typeof getCanvasStore>,
+async function readSidecarString(
+  handle: Space,
   nodeId: string,
   key: 'src',
-): string | null {
-  const sidecar = store.readNode(nodeId);
-  if (!sidecar) return null;
-  const value = sidecar[key];
+): Promise<string | null> {
+  const record = (await handle.nodes.read(nodeId))?.record;
+  if (!record) return null;
+  const value = record[key];
   return typeof value === 'string' && value.length > 0 ? value : null;
 }
 
@@ -440,17 +441,17 @@ export interface ContextImage {
  * this image.
  */
 async function loadContextImage(
-  store: ReturnType<typeof getCanvasStore>,
+  handle: Space,
   node: CanvasNode,
 ): Promise<ContextImage | null> {
-  const src = readSidecarString(store, node.id, 'src');
+  const src = await readSidecarString(handle, node.id, 'src');
   if (!src) return null;
   const ext = path.extname(src).toLowerCase();
   const mimeType = IMAGE_EXT_MIME[ext];
   if (!mimeType) return null;
   const { width, height } = nodeBoxSize(node);
   if (width <= 0 || height <= 0) return null;
-  const bytes = await space(store.canvasId).blobs.read(src);
+  const bytes = await handle.blobs.read(src);
   if (!bytes) return null;
   return { node, resolvedSrc: src, bytes, mimeType, width, height };
 }
@@ -795,11 +796,11 @@ async function resampleImageBytes(
  * so repeated calls with the same parameters are O(1) cache hits.
  */
 async function maybeResizeImageArtifact(
-  store: ReturnType<typeof getCanvasStore>,
+  handle: Space,
   src: string,
   maxEdge: number,
 ): Promise<{ src: string; width: number; height: number } | null> {
-  const blobs = space(store.canvasId).blobs;
+  const blobs = handle.blobs;
   const ext = path.extname(src).toLowerCase();
   const mimeType = IMAGE_EXT_MIME[ext];
   if (!mimeType) return null;
@@ -860,8 +861,8 @@ export async function snapshotNodesToArtifacts(
     Math.min(SPACE_SNAPSHOT_MAX_PIXELS, args.maxPixels ?? CLUSTER_MAX_PIXELS),
   );
 
-  const store = getCanvasStore(args.canvasId);
-  const canvas = store.read();
+  const handle = space(args.canvasId);
+  const canvas = await handle.read();
   if (!canvas) {
     throw new SnapshotNodeError(
       `Canvas ${args.canvasId} not found`,
@@ -974,7 +975,7 @@ export async function snapshotNodesToArtifacts(
     // resvg downscale, instead of building a full composite SVG.
     if (cluster.length === 1 && cluster[0].type === 'image') {
       const entry = cluster[0];
-      const src = readSidecarString(store, entry.node.id, 'src');
+      const src = await readSidecarString(handle, entry.node.id, 'src');
       if (!src) {
         if (entry.fromFrame) continue;
         throw new SnapshotNodeError(
@@ -982,7 +983,7 @@ export async function snapshotNodesToArtifacts(
           'invalid_snapshot_request',
         );
       }
-      const resized = await maybeResizeImageArtifact(store, src, maxEdge);
+      const resized = await maybeResizeImageArtifact(handle, src, maxEdge);
       if (resized) {
         results.push({
           src: resized.src,
@@ -1012,7 +1013,7 @@ export async function snapshotNodesToArtifacts(
 
     const contextImages: ContextImage[] = [];
     for (const entry of imageEntries) {
-      const loaded = await loadContextImage(store, entry.node);
+      const loaded = await loadContextImage(handle, entry.node);
       if (loaded) {
         contextImages.push(loaded);
         continue;
@@ -1025,7 +1026,7 @@ export async function snapshotNodesToArtifacts(
       // (the strokes will still render; losing one backdrop is
       // preferable to failing the whole batch).
       if (entry.fromFrame) continue;
-      const src = readSidecarString(store, entry.node.id, 'src');
+      const src = await readSidecarString(handle, entry.node.id, 'src');
       if (!src) {
         throw new SnapshotNodeError(
           `Node ${entry.node.id} (image) has no src — nothing to return. The artifact may have been deleted, or the node's markdown sidecar (nodes/<label>.md) is missing its \`src:\` frontmatter entry.`,
@@ -1060,10 +1061,10 @@ export async function snapshotNodesToArtifacts(
         ? `sketch-raster-${fingerprint}`
         : `sketch-raster-${fingerprint}-${maxEdge}`;
     const filename = `${id}.png`;
-    const existing = await space(store.canvasId).blobs.head(filename);
+    const existing = await handle.blobs.head(filename);
     if (!existing) {
       const png = await renderClusterPng(built.svg, built.width);
-      await space(store.canvasId).blobs.put(filename, png);
+      await handle.blobs.put(filename, png);
     }
     results.push({
       src: filename,
diff --git a/apps/server/src/modules/canvas/sync.route.ts b/apps/server/src/modules/canvas/sync.route.ts
index add7e4978..aeea8b174 100644
--- a/apps/server/src/modules/canvas/sync.route.ts
+++ b/apps/server/src/modules/canvas/sync.route.ts
@@ -14,7 +14,7 @@
  */
 
 import { subscribeCanvasUpdates } from './canvas-sync.js';
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type { CanvasSyncEvent } from '@huabu/shared';
 import type { FastifyPluginAsync } from 'fastify';
@@ -51,7 +51,7 @@ const syncRoutes: FastifyPluginAsync = async (fastify): Promise<void> => {
       // Subscribe before reading the baseline. Updates committed while the
       // snapshot is read are buffered and delivered after it, closing the
       // handshake race without reordering updates ahead of the snapshot.
-      const canvas = getCanvasStore(canvasId).read();
+      const canvas = await space(canvasId).read();
       writeSSE(reply.raw, {
         type: 'snapshot',
         data: { version: canvas?.version ?? 0 },
diff --git a/apps/server/src/modules/interactive-view/interactive-view.route.ts b/apps/server/src/modules/interactive-view/interactive-view.route.ts
index a404fe0e8..d14e687b8 100644
--- a/apps/server/src/modules/interactive-view/interactive-view.route.ts
+++ b/apps/server/src/modules/interactive-view/interactive-view.route.ts
@@ -58,7 +58,7 @@ const interactiveViewRoutes: FastifyPluginAsync = async (app) => {
       });
     }
     try {
-      const resource = interactiveViewService.get(
+      const resource = await interactiveViewService.get(
         params.data.canvasId,
         params.data.nodeId,
       );
@@ -153,7 +153,10 @@ const interactiveViewRoutes: FastifyPluginAsync = async (app) => {
     }
     try {
       return reply.send(
-        interactiveViewService.get(parsed.data.canvasId, parsed.data.nodeId),
+        await interactiveViewService.get(
+          parsed.data.canvasId,
+          parsed.data.nodeId,
+        ),
       );
     } catch (error) {
       if (error instanceof InteractiveViewServiceError) {
diff --git a/apps/server/src/modules/interactive-view/interactive-view.service.ts b/apps/server/src/modules/interactive-view/interactive-view.service.ts
index 4903acbcf..cadedc5ec 100644
--- a/apps/server/src/modules/interactive-view/interactive-view.service.ts
+++ b/apps/server/src/modules/interactive-view/interactive-view.service.ts
@@ -32,8 +32,9 @@ import {
   executeOnServer,
   type InteractiveViewConflict,
 } from '../canvas/canvas-executor.js';
-import { space, getCanvasStore, getStructuredStore } from '../storage/index.js';
+import { space, getStructuredStore } from '../storage/index.js';
 
+import type { NodeContent } from '../storage/index.js';
 import type { FastifyBaseLogger } from 'fastify';
 
 interface StoredNode {
@@ -156,8 +157,8 @@ function validateDefinition(definition: InteractiveViewDefinitionV1): void {
 }
 
 function resourceFromNode(
-  canvasId: string,
   node: StoredNode,
+  record: NodeContent | null,
 ): InteractiveViewResource | null {
   if (node.type !== 'web' || typeof node.id !== 'string') return null;
   const data =
@@ -168,10 +169,9 @@ function resourceFromNode(
     data.interactiveView,
   );
   if (!parsed.success) return null;
-  const sidecar = getCanvasStore(canvasId).readNode(node.id);
   const rendererArtifact =
-    typeof sidecar?.src === 'string'
-      ? sidecar.src
+    typeof record?.src === 'string'
+      ? record.src
       : typeof data.src === 'string'
         ? data.src
         : null;
@@ -186,16 +186,28 @@ function resourceFromNode(
 }
 
 export class InteractiveViewService {
-  list(canvasId: string, viewKey?: string): InteractiveViewResource[] {
-    const canvas = getCanvasStore(canvasId).read();
+  async list(
+    canvasId: string,
+    viewKey?: string,
+  ): Promise<InteractiveViewResource[]> {
+    const handle = space(canvasId);
+    const canvas = await handle.read();
     if (!canvas) {
       throw new InteractiveViewServiceError(
         'canvas_not_found',
         `Canvas ${canvasId} does not exist`,
       );
     }
+    // Every `web` node is a candidate View and each needs its record's `src`,
+    // so the candidate set is the Space.
+    const records = await handle.nodes.list();
     return (canvas.state.nodes as StoredNode[]).flatMap((node) => {
-      const resource = resourceFromNode(canvasId, node);
+      const resource = resourceFromNode(
+        node,
+        typeof node.id === 'string'
+          ? (records.get(node.id)?.record ?? null)
+          : null,
+      );
       if (
         !resource ||
         (viewKey !== undefined && resource.viewKey !== viewKey)
@@ -206,8 +218,12 @@ export class InteractiveViewService {
     });
   }
 
-  get(canvasId: string, nodeId: string): InteractiveViewResource {
-    const canvas = getCanvasStore(canvasId).read();
+  async get(
+    canvasId: string,
+    nodeId: string,
+  ): Promise<InteractiveViewResource> {
+    const handle = space(canvasId);
+    const canvas = await handle.read();
     if (!canvas) {
       throw new InteractiveViewServiceError(
         'canvas_not_found',
@@ -217,7 +233,12 @@ export class InteractiveViewService {
     const node = (canvas.state.nodes as StoredNode[]).find(
       (candidate) => candidate.id === nodeId,
     );
-    const resource = node ? resourceFromNode(canvasId, node) : null;
+    const resource = node
+      ? resourceFromNode(
+          node,
+          (await handle.nodes.read(nodeId))?.record ?? null,
+        )
+      : null;
     if (!resource) {
       throw new InteractiveViewServiceError(
         'view_not_found',
@@ -231,7 +252,7 @@ export class InteractiveViewService {
     canvasId: string,
     nodeId: string,
   ): Promise<InteractiveViewRuntimeSnapshot> {
-    const resource = this.get(canvasId, nodeId);
+    const resource = await this.get(canvasId, nodeId);
     const data: InteractiveViewRuntimeSnapshot['data'] = {};
     for (const binding of resource.definition.bindings) {
       let value: InteractiveViewJsonValue;
@@ -273,7 +294,7 @@ export class InteractiveViewService {
           if (run.rootThreadId) threadIds.add(run.rootThreadId);
         }
       } else {
-        const canvas = getCanvasStore(canvasId).read();
+        const canvas = await space(canvasId).read();
         if (!canvas) {
           throw new InteractiveViewServiceError(
             'canvas_not_found',
@@ -324,7 +345,7 @@ export class InteractiveViewService {
     canvasId: string,
     request: CreateInteractiveViewRequest,
   ): Promise<InteractiveViewResource> {
-    const canvas = getCanvasStore(canvasId).read();
+    const canvas = await space(canvasId).read();
     if (!canvas) {
       throw new InteractiveViewServiceError(
         'canvas_not_found',
@@ -404,7 +425,7 @@ export class InteractiveViewService {
     value: InteractiveViewJsonValue,
     actor: 'host-bridge' | 'trusted-agent',
   ): Promise<InteractiveViewResource> {
-    const current = this.get(canvasId, nodeId);
+    const current = await this.get(canvasId, nodeId);
     if (
       actor === 'host-bridge' &&
       !current.definition.actions.some(
@@ -477,7 +498,7 @@ export class InteractiveViewService {
     if (inputIssue) {
       throw new InteractiveViewServiceError('invalid_definition', inputIssue);
     }
-    const resource = this.get(canvasId, nodeId);
+    const resource = await this.get(canvasId, nodeId);
     const grant = resource.definition.actions.find(
       (candidate) => candidate.actionId === actionId,
     );
diff --git a/apps/server/src/modules/remote_fs/rfs.route.ts b/apps/server/src/modules/remote_fs/rfs.route.ts
index d2997b10f..8e2293891 100644
--- a/apps/server/src/modules/remote_fs/rfs.route.ts
+++ b/apps/server/src/modules/remote_fs/rfs.route.ts
@@ -317,7 +317,7 @@ const rfsRoutes: FastifyPluginAsync = async (app) => {
     }
     try {
       return reply.send({
-        views: interactiveViewService.list(
+        views: await interactiveViewService.list(
           request.params.canvasId,
           query.data.viewKey,
         ),
@@ -391,7 +391,10 @@ const rfsRoutes: FastifyPluginAsync = async (app) => {
     }
     try {
       return reply.send(
-        interactiveViewService.get(params.data.canvasId, params.data.nodeId),
+        await interactiveViewService.get(
+          params.data.canvasId,
+          params.data.nodeId,
+        ),
       );
     } catch (error) {
       if (error instanceof InteractiveViewServiceError) {
@@ -1081,7 +1084,7 @@ const rfsRoutes: FastifyPluginAsync = async (app) => {
       try {
         position =
           creation.position ??
-          resolveAgentNodePosition(canvasId, parentNodeId ?? undefined);
+          (await resolveAgentNodePosition(canvasId, parentNodeId ?? undefined));
       } catch (error) {
         if (
           error instanceof AgentNodeCreationError &&
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index 4513f5be1..66209c999 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -427,7 +427,6 @@ describe('root forwarding shims', () => {
     'storage/canvas-dirs.js': [
       'modules/agent/tools/world-target-read.test.ts',
       'modules/canvas/canvas-command-router.test.ts',
-      'modules/canvas/canvas-command-router.ts',
       'modules/canvas/canvas.route.ts',
       'modules/canvas/external-watcher.test.ts',
       'modules/canvas/external-watcher.ts',
diff --git a/apps/server/src/modules/task/run-launcher.test.ts b/apps/server/src/modules/task/run-launcher.test.ts
index 47ef4cabe..569b8a009 100644
--- a/apps/server/src/modules/task/run-launcher.test.ts
+++ b/apps/server/src/modules/task/run-launcher.test.ts
@@ -114,7 +114,7 @@ function createHarness(options?: {
     requireProfile: vi.fn(() => {
       if (options?.profileError) throw options.profileError;
     }),
-    resolveRootPosition: vi.fn(() => {
+    resolveRootPosition: vi.fn(async () => {
       calls.push('resolve-position');
       if (options?.positionError) throw options.positionError;
       return { x: 420, y: 20 };
diff --git a/apps/server/src/modules/task/run-launcher.ts b/apps/server/src/modules/task/run-launcher.ts
index 5fddbbbba..bad82c5bf 100644
--- a/apps/server/src/modules/task/run-launcher.ts
+++ b/apps/server/src/modules/task/run-launcher.ts
@@ -33,7 +33,7 @@ import {
   SelectableAgentProfileError,
 } from '../agent/selectable-agent-profile.js';
 import { buildSpatialBundle } from '../canvas/canvas-spatial.js';
-import { getStructuredStore, getCanvasStore } from '../storage/index.js';
+import { getStructuredStore, space } from '../storage/index.js';
 
 import type { ChatEnvelope } from '../agent/conversation/envelope.js';
 import type { SpaceTasks } from '../storage/index.js';
@@ -57,12 +57,12 @@ function createRootEnvelope(goal: string): ChatEnvelope {
   };
 }
 
-export function resolveRootAgentPosition(
+export async function resolveRootAgentPosition(
   canvasId: string,
   anchorNodeId: string,
   runOrdinal: number,
-): Point {
-  const canvas = getCanvasStore(canvasId).read();
+): Promise<Point> {
+  const canvas = await space(canvasId).read();
   if (!canvas) throw new Error(`Canvas ${canvasId} does not exist`);
   const bundle = buildSpatialBundle(canvas);
   const anchor = bundle.spatialById.get(anchorNodeId);
@@ -91,7 +91,7 @@ interface RunLauncherDependencies {
     canvasId: string,
     anchorNodeId: string,
     runOrdinal: number,
-  ) => Point;
+  ) => Promise<Point>;
   createAgentNode: (
     input: CreateAgentNodeInput,
   ) => Promise<CreateAgentNodeResult>;
@@ -337,7 +337,7 @@ export class RunLauncher {
       if (runOrdinal < 0) {
         throw new Error(`Run ${runId} disappeared after creation`);
       }
-      return this.dependencies.resolveRootPosition(
+      return await this.dependencies.resolveRootPosition(
         task.canvasId,
         task.anchorNodeId,
         runOrdinal,
diff --git a/apps/server/src/modules/web/web.route.ts b/apps/server/src/modules/web/web.route.ts
index 171125926..73dea7c22 100644
--- a/apps/server/src/modules/web/web.route.ts
+++ b/apps/server/src/modules/web/web.route.ts
@@ -9,7 +9,7 @@ import {
   webLookupQuerySchema,
 } from '@huabu/shared';
 
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type {
   WebLookupQuery,
@@ -168,7 +168,7 @@ const webRoutes: FastifyPluginAsync = async (fastify) => {
 
       const { canvasId, nodeId } = parsed.data;
 
-      const source = getCanvasStore(canvasId).readNode(nodeId);
+      const source = (await space(canvasId).nodes.read(nodeId))?.record;
       if (!source || source.type !== 'web') {
         return reply.code(404).send({ message: 'Source not ingested' });
       }
@@ -227,7 +227,7 @@ const webRoutes: FastifyPluginAsync = async (fastify) => {
 
       const { canvasId, nodeId } = parsed.data;
 
-      const source = getCanvasStore(canvasId).readNode(nodeId);
+      const source = (await space(canvasId).nodes.read(nodeId))?.record;
       if (!source || source.type !== 'web') {
         return reply.code(404).send({ message: 'Source not ingested' });
       }
@@ -284,7 +284,7 @@ const webRoutes: FastifyPluginAsync = async (fastify) => {
 
     const { canvasId, nodeId } = parsed.data;
 
-    const source = getCanvasStore(canvasId).readNode(nodeId);
+    const source = (await space(canvasId).nodes.read(nodeId))?.record;
     if (!source || source.type !== 'web') {
       return reply.code(404).send({ message: 'Source not ingested' });
     }
@@ -342,7 +342,7 @@ const webRoutes: FastifyPluginAsync = async (fastify) => {
       return reply.send(payload);
     }
 
-    const structuralNodes = getCanvasStore(canvasId).read()?.state.nodes as
+    const structuralNodes = (await space(canvasId).read())?.state.nodes as
       | Array<{
           id?: unknown;
           type?: unknown;

From c6fe3ac26505d7b08536f4c614b9b157efbd6877 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 17:40:57 +0800
Subject: [PATCH 07/20] refactor(canvas): finish the portable read surface and
 retire a shim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Space GET, single-node content, search, export, reveal, and the
preprocess guard were the last production readers on the legacy Disk store.
With them on `space(canvasId)`, `storage/canvas-store.js` has no importers
left and is deleted — the first of the three Phase-4.5 forwarding shims to go
entirely, rather than just shrink.

Search moves to `SpaceNodes.stream`, which is what that member existed for:
it emits meta-tier matches as each record lands instead of waiting for the
whole scan, and the map it returns still feeds the content tier with no
second read.

Two Disk facts that were reached through the legacy store move onto
`diskTree` rather than disappearing:

- Duplicate sidecars. Only a filesystem can have two files claiming one node
  id, and the read path deliberately reports it as a non-blocking hint while
  a write hard-fails — a user who broke it by hand needs to see the node in
  order to fix it. `hydrateOneNode` now takes the record and the duplicate
  list as arguments and reaches nothing itself.
- The explicit `revalidateNodeForRead` before a single-node read is gone: the
  port's own `read` already reconciles the adapter's cached index before
  answering, so the route was asking for something it now gets by default.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/modules/canvas/canvas-search.test.ts  | 48 ++++++-----
 .../src/modules/canvas/canvas-search.ts       | 55 +++++++-----
 .../server/src/modules/canvas/canvas.route.ts | 83 ++++++++-----------
 apps/server/src/modules/canvas/space-query.ts |  4 +-
 .../storage/backends/disk/space-tree.ts       | 18 ++++
 .../src/modules/storage/canvas-store.ts       | 13 ---
 .../modules/storage/module-boundaries.test.ts | 16 +---
 7 files changed, 116 insertions(+), 121 deletions(-)
 delete mode 100644 apps/server/src/modules/storage/canvas-store.ts

diff --git a/apps/server/src/modules/canvas/canvas-search.test.ts b/apps/server/src/modules/canvas/canvas-search.test.ts
index 9677f057b..22cc2c60c 100644
--- a/apps/server/src/modules/canvas/canvas-search.test.ts
+++ b/apps/server/src/modules/canvas/canvas-search.test.ts
@@ -7,7 +7,7 @@
  * Covers the streaming {@link searchCanvas} driver. The route layer is
  * a thin NDJSON adapter, so the interesting behaviour — tiered emission
  * order, field filtering, snippet construction, limits, abort semantics
- * — all lives here and is exercised against a fake `CanvasStore` whose
+ * — all lives here and is exercised against a fake `Space` whose
  * `streamAllNodes` walks an in-memory snapshot. Production reads sidecars
  * off disk, but the scanner takes a callback so the two are wire-compatible.
  */
@@ -24,7 +24,7 @@ import {
 import { createChatSubmission } from '../agent/agenetes/handle.js';
 
 import type { ChatEnvelope } from '../agent/conversation/envelope.js';
-import type { CanvasStore, NodeContent } from '../storage/canvas-store.js';
+import type { NodeContent, NodeSnapshot, Space } from '../storage/index.js';
 import type { AgentTurn } from '@agenetes/protocol';
 import type { CanvasSearchEvent, CanvasSearchRequest } from '@huabu/shared';
 
@@ -76,16 +76,16 @@ function mkEdge(
 }
 
 /**
- * Build a duck-typed `CanvasStore` that satisfies just the two methods
+ * Build a duck-typed `Space` that satisfies just the two members
  * `searchCanvas` actually reads from: `read()` (for the static node + edge
  * shape) and `streamAllNodes()` (for the sidecar bodies). The rest of the
  * store surface is irrelevant here, so we cast through `unknown`.
  */
-function makeFakeStore(opts: {
+function makeFakeSpace(opts: {
   nodes: readonly SearchableNode[];
   contents: readonly NodeContent[];
   edges?: readonly SearchableEdge[];
-}): CanvasStore {
+}): Space {
   const stateNodes = opts.nodes.map((n) => ({
     id: n.id,
     type: n.type,
@@ -100,21 +100,25 @@ function makeFakeStore(opts: {
   }));
   const fake = {
     canvasId: 'test-canvas',
-    read: () => ({ state: { nodes: stateNodes, edges: stateEdges } }),
-    streamAllNodes: async (
-      onNode: (id: string, content: NodeContent) => void,
-      signal?: { readonly aborted: boolean },
-    ): Promise<Map<string, NodeContent>> => {
-      const map = new Map<string, NodeContent>();
-      for (const c of opts.contents) {
-        if (signal?.aborted) return map;
-        map.set(c.nodeId, c);
-        onNode(c.nodeId, c);
-      }
-      return map;
+    read: async () => ({ state: { nodes: stateNodes, edges: stateEdges } }),
+    nodes: {
+      canvasId: 'test-canvas',
+      stream: async (
+        onNode: (snapshot: NodeSnapshot) => void,
+        options?: { signal?: { readonly aborted: boolean } },
+      ): Promise<Map<string, NodeSnapshot>> => {
+        const map = new Map<string, NodeSnapshot>();
+        for (const c of opts.contents) {
+          if (options?.signal?.aborted) return map;
+          const snapshot = { record: c, revision: `rev-${c.nodeId}` };
+          map.set(c.nodeId, snapshot);
+          onNode(snapshot);
+        }
+        return map;
+      },
     },
   };
-  return fake as unknown as CanvasStore;
+  return fake as unknown as Space;
 }
 
 async function collect(
@@ -124,9 +128,9 @@ async function collect(
   signal?: AbortSignal,
   edges?: SearchableEdge[],
 ): Promise<CanvasSearchEvent[]> {
-  const store = makeFakeStore({ nodes, contents, edges });
+  const handle = makeFakeSpace({ nodes, contents, edges });
   const events: CanvasSearchEvent[] = [];
-  await searchCanvas(store, request, (e) => events.push(e), signal);
+  await searchCanvas(handle, request, (e) => events.push(e), signal);
   return events;
 }
 
@@ -390,9 +394,9 @@ describe('searchCanvas — abort', () => {
     }
     const ctrl = new AbortController();
     const events: CanvasSearchEvent[] = [];
-    const store = makeFakeStore({ nodes, contents });
+    const handle = makeFakeSpace({ nodes, contents });
     await searchCanvas(
-      store,
+      handle,
       { query: 'hit' },
       (e) => {
         events.push(e);
diff --git a/apps/server/src/modules/canvas/canvas-search.ts b/apps/server/src/modules/canvas/canvas-search.ts
index 17e0754d6..3be81d2c1 100644
--- a/apps/server/src/modules/canvas/canvas-search.ts
+++ b/apps/server/src/modules/canvas/canvas-search.ts
@@ -46,7 +46,7 @@ import { agenetes } from '../agent/agenetes/drivers.js';
 import { chatEnvelopeFromSubmission } from '../agent/agenetes/handle.js';
 import { canvasAcpNamespace } from '../workspace/paths.js';
 
-import type { CanvasStore, NodeContent } from '../storage/canvas-store.js';
+import type { NodeContent, Space } from '../storage/index.js';
 import type { AgentTurn } from '@agenetes/protocol';
 
 /** Window of characters shown around each match in `snippet`. */
@@ -531,20 +531,20 @@ export function extractSearchableEdges(state: unknown): SearchableEdge[] {
 }
 
 /**
- * Drive a search directly off a {@link CanvasStore}.
+ * Drive a search off one Space.
  *
- * Streams meta-tier matches as each sidecar lands (no `await`-all
+ * Streams meta-tier matches as each record lands (no `await`-all
  * barrier in front of the first emit). Content tier runs after the
  * stream settles, scanning the in-memory cache that was built as a
- * side effect of the meta walk — zero extra disk reads.
+ * side effect of the meta walk — zero extra reads.
  */
 export async function searchCanvas(
-  store: CanvasStore,
+  handle: Space,
   request: CanvasSearchRequest,
   emit: (event: CanvasSearchEvent) => void,
   signal?: AbortSignal,
 ): Promise<void> {
-  const file = store.read();
+  const file = await handle.read();
   if (!file) {
     emit({ type: 'error', message: 'Canvas not found' });
     return;
@@ -583,22 +583,31 @@ export async function searchCanvas(
   // invokes the callback synchronously as each file resolves, so a
   // match against the very first parsed file ships before any of the
   // remaining files are even opened.
-  const contentByNodeId = await store.streamAllNodes((id, content) => {
-    if (signal?.aborted) return;
-    if (!wantsMeta) return;
-    if (totalEmitted >= limit) {
-      truncated = true;
-      return;
-    }
-    const node = candidateById.get(id);
-    // Skip sidecars that belong to nodes filtered out by
-    // `nodeId` / `nodeTypes` — we still read them (the directory
-    // walk is unfiltered) but they contribute nothing here.
-    if (!node) return;
-    scanNodeMeta(node, content, fields, needleLower, needleLen, (m) =>
-      tryEmitMatch('meta', m),
-    );
-  }, signal);
+  const streamed = await handle.nodes.stream(
+    (snapshot) => {
+      const id = snapshot.record.nodeId;
+      const content = snapshot.record;
+      if (signal?.aborted) return;
+      if (!wantsMeta) return;
+      if (totalEmitted >= limit) {
+        truncated = true;
+        return;
+      }
+      const node = candidateById.get(id);
+      // Skip sidecars that belong to nodes filtered out by
+      // `nodeId` / `nodeTypes` — we still read them (the directory
+      // walk is unfiltered) but they contribute nothing here.
+      if (!node) return;
+      scanNodeMeta(node, content, fields, needleLower, needleLen, (m) =>
+        tryEmitMatch('meta', m),
+      );
+    },
+    signal ? { signal } : undefined,
+  );
+  const contentByNodeId = new Map<string, NodeContent>();
+  for (const [id, snapshot] of streamed) {
+    contentByNodeId.set(id, snapshot.record);
+  }
 
   if (signal?.aborted) return;
 
@@ -677,7 +686,7 @@ export async function searchCanvas(
       const label = content?.label ?? null;
       scanNodeConversation(
         node,
-        store.canvasId,
+        handle.canvasId,
         label,
         needleLower,
         needleLen,
diff --git a/apps/server/src/modules/canvas/canvas.route.ts b/apps/server/src/modules/canvas/canvas.route.ts
index c77be6838..f6e49f3db 100644
--- a/apps/server/src/modules/canvas/canvas.route.ts
+++ b/apps/server/src/modules/canvas/canvas.route.ts
@@ -57,16 +57,16 @@ import {
   space,
   createSpace,
   deleteSpace,
-  getCanvasStore,
   getStructuredStore,
   type CanvasFile,
+  type NodeContent,
+  type Space,
   type UpdateNodeOutcome,
   updateNode,
 } from '../storage/index.js';
 import { nodesDir, SPACE_JSON_FILENAME } from '../storage/paths.js';
 import { getWorkspacePath } from '../workspace.js';
 
-import type { CanvasStore, NodeContent } from '../storage/canvas-store.js';
 import type { CanvasNodeType } from '@huabu/shared';
 import type {
   ApiResult,
@@ -356,10 +356,10 @@ async function singleArtifactProbe(
  * callers can rely on identity-based diffing.
  */
 function hydrateOneNode(
-  store: CanvasStore,
   node: NodeLike,
   artifactExists: (key: string) => boolean,
-  preloaded?: NodeContent | null,
+  nodeContent: NodeContent | null,
+  duplicateSidecars: readonly string[],
 ): NodeLike {
   const nodeId = typeof node.id === 'string' ? node.id : '';
   if (!nodeId) return node;
@@ -374,17 +374,6 @@ function hydrateOneNode(
   // is the only source of truth for those fields, so we read it before
   // any check that depends on them (notably the artifact-missing probe,
   // which needs the hydrated `src`).
-  let nodeContent: NodeContent | null;
-  if (preloaded !== undefined) {
-    nodeContent = preloaded;
-  } else {
-    try {
-      nodeContent = store.readNode(nodeId);
-    } catch {
-      nodeContent = null;
-    }
-  }
-
   if (!nodeContent) {
     if (MD_BACKED_NODE_TYPES.has(nodeType)) {
       data['contentMissing'] = true;
@@ -406,9 +395,9 @@ function hydrateOneNode(
   // duplicate. The duplicate set was already populated by the
   // `readAllNodes()` scan that produced `preloaded`, so this is a cheap
   // in-memory lookup with no extra disk I/O.
-  if (store.isDuplicateNode(nodeId)) {
+  if (duplicateSidecars.length > 0) {
     data['contentDuplicate'] = true;
-    data['duplicateFiles'] = store.duplicateNodeFiles(nodeId);
+    data['duplicateFiles'] = [...duplicateSidecars];
   } else {
     if ('contentDuplicate' in data) {
       delete data['contentDuplicate'];
@@ -507,13 +496,17 @@ function hydrateOneNode(
  * load on cold cache.
  */
 async function hydrateNodeContent(
-  store: CanvasStore,
+  handle: Space,
   nodes: NodeLike[],
 ): Promise<NodeLike[]> {
   // Read sidecars first because they are the source of truth for `src`.
   // Probe only the keys referenced by artifact-backed nodes; enumerating the
   // entire scope would make hydration cost grow with unrelated blob count.
-  const contentByNodeId = await store.readAllNodes();
+  const records = await handle.nodes.list();
+  const contentByNodeId = new Map<string, NodeContent>();
+  for (const [nodeId, snapshot] of records) {
+    contentByNodeId.set(nodeId, snapshot.record);
+  }
   const referenced = new Set<string>();
   for (const node of nodes) {
     const nodeType = typeof node.type === 'string' ? node.type : '';
@@ -526,16 +519,16 @@ async function hydrateNodeContent(
   const present =
     referenced.size === 0
       ? new Set<string>()
-      : await space(store.canvasId).blobs.hasMany([...referenced]);
+      : await handle.blobs.hasMany([...referenced]);
   const artifactExists = (key: string): boolean => present.has(key);
 
   return nodes.map((node) => {
     const nodeId = typeof node.id === 'string' ? node.id : '';
     return hydrateOneNode(
-      store,
       node,
       artifactExists,
       contentByNodeId.get(nodeId) ?? null,
+      handle.diskTree?.duplicateSidecars(nodeId) ?? [],
     );
   });
 }
@@ -881,20 +874,12 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
   }>('/:canvasId/nodes/:nodeId/content', async function (request, reply) {
     const { canvasId, nodeId } = request.params;
 
-    const store = getCanvasStore(canvasId);
-    const canvas = store.read();
+    const handle = space(canvasId);
+    const canvas = await handle.read();
     if (!canvas) {
       return reply.code(404).send({ message: 'Canvas not found' });
     }
 
-    // Reconcile the cached node index against disk before this read.
-    // Only re-scans when warranted: a node already flagged duplicate
-    // always re-reads (so a hand-resolved duplicate is detected — the
-    // cheap count probe alone can't see that case), otherwise it falls
-    // back to the names-only staleness probe. Keeps the common healthy
-    // read off the full content rescan.
-    store.revalidateNodeForRead(nodeId);
-
     // Find this node in the persisted canvas state so we know its type
     // (without it we can't apply the artifact-missing branch). For
     // nodes that exist in `.md` but not in canvas state we fall back
@@ -904,9 +889,12 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     let nodeType =
       stateNode && typeof stateNode.type === 'string' ? stateNode.type : '';
 
+    // The port's single-node read reconciles the adapter's cached index
+    // against storage before answering, so a hand-resolved duplicate or an
+    // external rename is picked up here rather than needing its own probe.
     let existing: NodeContent | null = null;
     try {
-      existing = store.readNode(nodeId);
+      existing = (await handle.nodes.read(nodeId))?.record ?? null;
     } catch {
       existing = null;
     }
@@ -933,13 +921,14 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     // Reuse the batched hydration helper so single-node and whole-
     // canvas reads stay in lock-step.
     const hydrated = hydrateOneNode(
-      store,
       {
         id: nodeId,
         type: nodeType,
         data: { ...(stateNode?.data ?? {}) },
       },
-      await singleArtifactProbe(store.canvasId, existing.src),
+      await singleArtifactProbe(canvasId, existing.src),
+      existing,
+      handle.diskTree?.duplicateSidecars(nodeId) ?? [],
     );
     const data = (hydrated.data ?? {}) as Record<string, unknown>;
 
@@ -1009,9 +998,10 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     const { nodeType, trigger, snapshot, previousSnapshot, options } =
       parsed.data;
     const dispatcher = getPreprocessDispatcher();
-    const store = getCanvasStore(canvasId);
-
-    if (MD_BACKED_NODE_TYPES.has(nodeType) && !store.readNode(nodeId)) {
+    if (
+      MD_BACKED_NODE_TYPES.has(nodeType) &&
+      !(await space(canvasId).nodes.read(nodeId))
+    ) {
       return reply.send({
         nodeId,
         success: false,
@@ -1097,8 +1087,8 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     if (isWorldCanvasId(canvasId)) {
       await reconcileWorldPortals();
     }
-    const store = getCanvasStore(canvasId);
-    const canvas = store.read();
+    const handle = space(canvasId);
+    const canvas = await handle.read();
 
     if (!canvas) {
       return reply.code(404).send({ message: 'Canvas not found' });
@@ -1107,7 +1097,7 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     // Hydrate node content from the per-canvas store so clients always
     // receive fresh markdown bodies.
     const nodes = canvas.state.nodes as NodeLike[];
-    const hydratedNodes = await hydrateNodeContent(store, nodes);
+    const hydratedNodes = await hydrateNodeContent(handle, nodes);
 
     return reply.send({
       canvasId: canvas.canvasId,
@@ -1569,8 +1559,7 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     Reply: ApiResult<RevealNodesFolderResponse>;
   }>('/:canvasId/reveal-nodes', async function (request, reply) {
     const { canvasId } = request.params;
-    const store = getCanvasStore(canvasId);
-    if (!store.read()) {
+    if (!(await space(canvasId).read())) {
       return reply.code(404).send({ message: 'Canvas not found' });
     }
     const dir = nodesDir(canvasId);
@@ -1603,8 +1592,7 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     }
     const includeHistory = parsedQuery.data.includeHistory !== 'false';
 
-    const store = getCanvasStore(canvasId);
-    const canvas = store.read();
+    const canvas = await space(canvasId).read();
     if (!canvas) {
       return reply.code(404).send({ message: 'Canvas not found' });
     }
@@ -1843,9 +1831,8 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
         });
       }
 
-      const store = getCanvasStore(canvasId);
-      const canvas = store.read();
-      if (!canvas) {
+      const handle = space(canvasId);
+      if (!(await handle.read())) {
         return reply.code(404).send({ message: 'Canvas not found' });
       }
 
@@ -1883,7 +1870,7 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
       request.raw.on('close', onClose);
 
       try {
-        await searchCanvas(store, parsed.data, writeEvent, abort.signal);
+        await searchCanvas(handle, parsed.data, writeEvent, abort.signal);
       } catch (err) {
         request.log.error({ err, canvasId }, 'Canvas search failed');
         writeEvent({
diff --git a/apps/server/src/modules/canvas/space-query.ts b/apps/server/src/modules/canvas/space-query.ts
index 7864e2813..1aa4669ea 100644
--- a/apps/server/src/modules/canvas/space-query.ts
+++ b/apps/server/src/modules/canvas/space-query.ts
@@ -13,7 +13,7 @@ import {
   snapshotNodesToArtifacts,
   SnapshotNodeError,
 } from './snapshot-nodes.js';
-import { getCanvasStore } from '../storage/index.js';
+import { space } from '../storage/index.js';
 
 import type {
   CanvasSearchMatch,
@@ -86,7 +86,7 @@ export async function executeSpaceQuery(
       }> = [];
       let truncated = false;
       let error: string | undefined;
-      await searchCanvas(getCanvasStore(canvasId), request, (event) => {
+      await searchCanvas(space(canvasId), request, (event) => {
         if (event.type === 'match') {
           matches.push({ tier: event.tier, match: event.match });
         } else if (event.type === 'done') {
diff --git a/apps/server/src/modules/storage/backends/disk/space-tree.ts b/apps/server/src/modules/storage/backends/disk/space-tree.ts
index ceb06a77f..8de0047af 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tree.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.ts
@@ -57,6 +57,18 @@ export interface DiskSpaceTree {
    * would collapse to `nodes/<id>.md` and never match a label-named file.
    */
   nodeIdForPath(relativePath: string): string | null;
+  /**
+   * Every sidecar filename currently claiming `nodeId`; empty when there is
+   * no conflict.
+   *
+   * Only a filesystem can produce this: two files can both say they are one
+   * node, and a table with a primary key cannot. The read path surfaces it as
+   * a non-blocking hint — the index keeps the last-scanned file, so the node
+   * still renders — while a write hard-fails with `duplicate-node`. That
+   * asymmetry is deliberate: a user who broke it by hand needs to see the node
+   * to fix it.
+   */
+  duplicateSidecars(nodeId: string): readonly string[];
 }
 
 export function diskSpaceTree(canvasId: string): DiskSpaceTree {
@@ -68,5 +80,11 @@ export function diskSpaceTree(canvasId: string): DiskSpaceTree {
       if (filename === undefined) return null;
       return getCanvasStore(canvasId).nodeIdForFilename(filename);
     },
+    duplicateSidecars: (nodeId: string) => {
+      const store = getCanvasStore(canvasId);
+      return store.isDuplicateNode(nodeId)
+        ? store.duplicateNodeFiles(nodeId)
+        : [];
+    },
   };
 }
diff --git a/apps/server/src/modules/storage/canvas-store.ts b/apps/server/src/modules/storage/canvas-store.ts
deleted file mode 100644
index cdef1d074..000000000
--- a/apps/server/src/modules/storage/canvas-store.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-
-/**
- * @deprecated Forwarding shim — the legacy Disk store lives under
- * `backends/disk/legacy/canvas-store.js` now.
- *
- * Import the class and its result types from `storage/index.js` (the public
- * facade) instead. This file exists only so the existing `CanvasStore` type
- * imports keep resolving while they migrate; it must never contain logic, and
- * no new call site may import it (enforced by the module-boundary test).
- */
-export * from './backends/disk/legacy/canvas-store.js';
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index 66209c999..42e70016f 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -10,7 +10,7 @@
  * one import".
  *
  * What this is **not**: evidence that every read capability is portable. The
- * compatibility facade and three root forwarding shims still serve explicit
+ * compatibility facade and two root forwarding shims still serve explicit
  * Disk-only/read paths. This asserts that the portable write boundary and
  * dependency direction stay intact while that remaining list only shrinks.
  */
@@ -78,14 +78,13 @@ function inLayer(relative: string, layer: string): boolean {
 }
 
 describe('storage module tree', () => {
-  it('keeps only the barrel, composition, and the three shims at the root', () => {
+  it('keeps only the barrel, composition, and the two shims at the root', () => {
     const rootFiles = storageFiles
       .filter((f) => path.dirname(f) === 'modules/storage')
       .map((f) => path.basename(f));
 
     expect(rootFiles.sort()).toEqual([
       'canvas-dirs.ts',
-      'canvas-store.ts',
       'index.ts',
       'module-boundaries.test.ts',
       'paths.ts',
@@ -397,11 +396,7 @@ describe('structured write authority', () => {
 });
 
 describe('root forwarding shims', () => {
-  const SHIMS = [
-    'modules/storage/canvas-store.ts',
-    'modules/storage/canvas-dirs.ts',
-    'modules/storage/paths.ts',
-  ];
+  const SHIMS = ['modules/storage/canvas-dirs.ts', 'modules/storage/paths.ts'];
 
   it.each(SHIMS)('%s contains no logic', (shim) => {
     const body = read(shim)
@@ -419,11 +414,6 @@ describe('root forwarding shims', () => {
 
   /** Exact snapshot of the remaining deprecated-path importers. */
   const EXPECTED_IMPORTERS: Record<string, readonly string[]> = {
-    'storage/canvas-store.js': [
-      'modules/canvas/canvas-search.test.ts',
-      'modules/canvas/canvas-search.ts',
-      'modules/canvas/canvas.route.ts',
-    ],
     'storage/canvas-dirs.js': [
       'modules/agent/tools/world-target-read.test.ts',
       'modules/canvas/canvas-command-router.test.ts',

From abf0bcf440a79c06e0a57bd77978144dde046194 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 18:44:38 +0800
Subject: [PATCH 08/20] feat(storage): mount storage onto a Workspace as an
 explicit lifecycle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Storage had no idea which Workspace it belonged to. The connections were
built once, and only the handles derived from them carried a Workspace and
rejected after a switch. That works while every adapter resolves paths
lazily from module state; it does not survive a backend that opens a
connection, because there is nothing to open it against and nothing to close
when the Workspace moves.

`Storage` now carries the Workspace it was opened for, and activation is a
staged mount:

  prepare (child process) → stage connections + ensureWorld → publish

Everything that can fail happens in the stage, while the previous Workspace
and its connections are still serving: an unimplemented backend, a
connection that will not open, a namespace whose World is malformed. Only
`commit()` makes the new mount reachable, and it takes the caller's own
publish step — for a switch, making the path active — so the path and the
mount that serves it change in one synchronous block. A request cannot land
in a gap where one moved and the other did not.

That ordering is why the Disk connection is constructed with an explicit
path: `ensureWorld()` runs before the Workspace is active, so it has to
bootstrap the one being activated rather than the one being replaced.

Writing the swap test surfaced a leak worth stating: committing a Workspace
path detaches the mount that no longer describes it, so a `commit()` reading
the holder at swap time would find nothing to close and drop the previous
connections on the floor. The staged mount captures what it replaces when it
is staged, not when it is published.

Free mode gets the case it always needed: startup validates the profile
without opening anything when no Workspace has been chosen yet, instead of
requiring one to exist. And `app.close()` now closes the mount — Disk has
nothing to release, but a mount outliving the process that owned it is
exactly the leak that only shows up under the backend nobody has written.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 apps/server/src/app.ts                        |   6 +
 .../storage/backends/disk/space-nodes.test.ts |   7 +-
 .../backends/disk/space-repository.test.ts    |   6 +-
 .../storage/backends/disk/space-repository.ts |  21 +-
 .../storage/backends/disk/space-write.test.ts |   7 +-
 .../backends/disk/storage-recovery.test.ts    |   5 +-
 .../storage/backends/disk/structured-store.ts |  21 +-
 .../compatibility/delete-canvas.test.ts       |   2 +
 apps/server/src/modules/storage/index.ts      |  11 +-
 .../modules/storage/module-boundaries.test.ts |   1 +
 .../src/modules/storage/storage.test.ts       | 238 ++++++++++++++++++
 apps/server/src/modules/storage/storage.ts    | 214 +++++++++++++---
 .../src/modules/workspace-activation.ts       |  25 +-
 apps/server/src/modules/workspace.ts          |  11 +
 apps/server/src/server.ts                     |   9 +-
 15 files changed, 537 insertions(+), 47 deletions(-)
 create mode 100644 apps/server/src/modules/storage/storage.test.ts

diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts
index a2d0fd579..fd1fad5e0 100644
--- a/apps/server/src/app.ts
+++ b/apps/server/src/app.ts
@@ -56,6 +56,7 @@ import {
   originGuardPlugin,
   resolveAllowedHostnames,
 } from './modules/security/index.js';
+import { closeStorage } from './modules/storage/index.js';
 import webRoutes from './modules/web/web.route.js';
 import {
   initWorkspaceFromEnv,
@@ -364,6 +365,11 @@ if (bundledAgentTeamsPath) {
 // after the process is gone. Closing them here lets `app.close()` (driven
 // by the SIGTERM/SIGINT handlers in server.ts) tear them down gracefully.
 app.addHook('onClose', async () => resetExternalNoteSessions());
+// Close the mounted storage connections on graceful shutdown. Disk has
+// nothing to release, but a connection-holding backend does, and a mount that
+// outlives the process that owned it is exactly the kind of leak that only
+// shows up under the backend nobody has written yet.
+app.addHook('onClose', async () => closeStorage());
 // Capture the bound TCP port for L1-owned reachback (RFS): the
 // canvas-scoped `HUABU_RFS_URL` base is built from this. RFS is
 // canvas-coupled and therefore a pure L1 concern, so the port lives in
diff --git a/apps/server/src/modules/storage/backends/disk/space-nodes.test.ts b/apps/server/src/modules/storage/backends/disk/space-nodes.test.ts
index b688e8fbb..38ca626a9 100644
--- a/apps/server/src/modules/storage/backends/disk/space-nodes.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-nodes.test.ts
@@ -26,7 +26,7 @@ import { DiskSpaceNodes } from './space-nodes.js';
 import { DiskSpaceRepository } from './space-repository.js';
 import { DiskStructuredStore } from './structured-store.js';
 import { ensureWorldCanvasOnDisk } from './world-canvas.js';
-import { setWorkspacePath } from '../../../workspace.js';
+import { getWorkspacePath, setWorkspacePath } from '../../../workspace.js';
 import { describeSpaceNodesContract } from '../../ports/contracts/space-nodes.contract.js';
 
 import type { NodeContent } from '../../../canvas/persistence-types.js';
@@ -70,7 +70,10 @@ describe('DiskSpaceNodes', () => {
 
   beforeEach(async () => {
     workspacePath = freshWorkspace('huabu-node-repository-');
-    const created = await new DiskSpaceRepository(() => 1).create({
+    const created = await new DiskSpaceRepository(
+      getWorkspacePath(),
+      () => 1,
+    ).create({
       canvasId: 'canvas-a',
       title: 'Shared title',
     });
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
index 9f19aff10..e8ff2374a 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
@@ -263,7 +263,7 @@ describe('DiskSpaceRepository lifecycle', () => {
   it('persists the de-duplicated title and reports explicit delete outcomes', async () => {
     const root = makeWorkspace('huabu-space-lifecycle-titles-');
     seedWorld(root);
-    const spaces = new DiskSpaceRepository(() => 1);
+    const spaces = new DiskSpaceRepository(workspaceState.path, () => 1);
     const first = await spaces.create({
       canvasId: 'canvas-a',
       title: 'Shared title',
@@ -298,7 +298,7 @@ describe('DiskSpaceRepository lifecycle', () => {
   it('refreshes membership before allocating around an externally imported Space', async () => {
     const root = makeWorkspace('huabu-space-lifecycle-imported-');
     seedWorld(root);
-    const spaces = new DiskSpaceRepository(() => 1);
+    const spaces = new DiskSpaceRepository(workspaceState.path, () => 1);
     await spaces.create({ canvasId: 'warm-index', title: 'Warm index' });
     const importedRoot = path.join(root, 'Taken');
     mkdirSync(importedRoot, { recursive: true });
@@ -333,7 +333,7 @@ describe('DiskSpaceRepository lifecycle', () => {
   it('keeps an allocated null title consistent in the record and the listing', async () => {
     const root = makeWorkspace('huabu-space-lifecycle-null-title-');
     seedWorld(root);
-    const spaces = new DiskSpaceRepository(() => 1);
+    const spaces = new DiskSpaceRepository(workspaceState.path, () => 1);
     await spaces.create({
       canvasId: 'physical-name-owner',
       title: 'null-title-space',
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.ts b/apps/server/src/modules/storage/backends/disk/space-repository.ts
index ea8d30456..3393b06d0 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.ts
@@ -67,8 +67,17 @@ export class DiskSpaceRepository implements SpaceRepository {
   readonly #workspacePath: string;
   readonly #now: () => number;
 
-  constructor(now: () => number = Date.now) {
-    this.#workspacePath = path.resolve(getWorkspacePath());
+  /**
+   * @param workspacePath Workspace this repository is bound to. Defaults to
+   *   the active one, which is what every caller outside the mount lifecycle
+   *   wants; the lifecycle passes the Workspace being staged, because
+   *   {@link ensureWorld} runs before that Workspace becomes active.
+   */
+  constructor(
+    workspacePath: string = getWorkspacePath(),
+    now: () => number = Date.now,
+  ) {
+    this.#workspacePath = path.resolve(workspacePath);
     this.#now = now;
   }
 
@@ -107,8 +116,14 @@ export class DiskSpaceRepository implements SpaceRepository {
    * World is a new member of the collection every later read resolves through.
    */
   async ensureWorld(): Promise<string> {
-    this.#assertActiveWorkspace();
+    // Deliberately no active-Workspace assertion. Bootstrap is the one
+    // operation defined *before* its Workspace is active: the mount stages a
+    // connection, ensures the World, and only then commits the path and swaps
+    // (proposal §12.6.5). It works on the bound path directly rather than
+    // through the active-Workspace layout, so it is safe either way.
     const canvasId = ensureWorldCanvasOnDisk(this.#workspacePath);
+    // Lazy invalidation only; the next read rescans whichever Workspace is
+    // active by then.
     refreshCanvasDirIndex();
     return canvasId;
   }
diff --git a/apps/server/src/modules/storage/backends/disk/space-write.test.ts b/apps/server/src/modules/storage/backends/disk/space-write.test.ts
index 2707301f0..62e454ed6 100644
--- a/apps/server/src/modules/storage/backends/disk/space-write.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-write.test.ts
@@ -23,7 +23,7 @@ import { DiskSpaceRepository } from './space-repository.js';
 import { createDiskSpaceWrite } from './space-write.js';
 import { DiskStructuredStore } from './structured-store.js';
 import { ensureWorldCanvasOnDisk } from './world-canvas.js';
-import { setWorkspacePath } from '../../../workspace.js';
+import { getWorkspacePath, setWorkspacePath } from '../../../workspace.js';
 import { describeSpaceWriteContract } from '../../ports/contracts/space-write.contract.js';
 
 import type {
@@ -95,7 +95,10 @@ describe('Disk ordered Space write', () => {
 
   beforeEach(async () => {
     workspacePath = freshWorkspace('huabu-ordered-writer-');
-    const created = await new DiskSpaceRepository(() => 1).create({
+    const created = await new DiskSpaceRepository(
+      getWorkspacePath(),
+      () => 1,
+    ).create({
       canvasId: 'canvas-a',
       title: 'Shared title',
     });
diff --git a/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts b/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
index 3f02d662b..1440f7b44 100644
--- a/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
@@ -122,7 +122,10 @@ beforeEach(() => {
   workspaceState.path = root;
   resetStorageCache();
   restoreStorage = setStorageForTesting(
-    createStorage({ structured: { kind: 'disk' }, blobs: { kind: 'disk' } }),
+    createStorage(
+      { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
+      root,
+    ),
   );
 });
 
diff --git a/apps/server/src/modules/storage/backends/disk/structured-store.ts b/apps/server/src/modules/storage/backends/disk/structured-store.ts
index e02f25d49..fc5a61506 100644
--- a/apps/server/src/modules/storage/backends/disk/structured-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/structured-store.ts
@@ -28,6 +28,7 @@ import { createDiskSpaceRecordReader } from './space-record.js';
 import { DiskSpaceRepository } from './space-repository.js';
 import { DiskSpaceTasks } from './space-tasks.js';
 import { createDiskSpaceWrite } from './space-write.js';
+import { getWorkspacePath } from '../../../workspace.js';
 
 import type { StorageHealth } from '../../ports/common.js';
 import type { SpaceHandle, StructuredStore } from '../../ports/structured.js';
@@ -35,6 +36,24 @@ import type { SpaceHandle, StructuredStore } from '../../ports/structured.js';
 export class DiskStructuredStore implements StructuredStore {
   readonly kind = 'disk' as const;
 
+  readonly #workspacePath: string;
+
+  /**
+   * @param workspacePath Workspace this connection is mounted on. Defaults to
+   *   the active one, which is what every caller outside the mount lifecycle
+   *   means.
+   *
+   * The lifecycle passes it explicitly because a mount is staged *before* its
+   * Workspace becomes active: `ensureWorld()` has to bootstrap the Workspace
+   * being activated, not the one being replaced (proposal §12.6.5). The rest
+   * of the adapter still resolves through the active-Workspace layout and
+   * guards against a mismatch, so a staged connection is usable for bootstrap
+   * and nothing else until the swap.
+   */
+  constructor(workspacePath: string = getWorkspacePath()) {
+    this.#workspacePath = workspacePath;
+  }
+
   async init(): Promise<void> {
     // The workspace directory is prepared by `workspace-prepare.ts`; Space
     // directories are created on demand by the lifecycle repository.
@@ -47,7 +66,7 @@ export class DiskStructuredStore implements StructuredStore {
   async close(): Promise<void> {}
 
   spaces(): DiskSpaceRepository {
-    return new DiskSpaceRepository();
+    return new DiskSpaceRepository(this.#workspacePath);
   }
 
   space(canvasId: string): SpaceHandle {
diff --git a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
index 741182470..1120ffae5 100644
--- a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
+++ b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
@@ -198,6 +198,7 @@ function installBlobStore(next: BlobStore): void {
   restoreStorage = setStorageForTesting(
     composeStorage(
       { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
+      workspaceState.path,
       new DiskStructuredStore(),
       next,
     ),
@@ -216,6 +217,7 @@ beforeEach(() => {
   restoreStorage = setStorageForTesting(
     composeStorage(
       { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
+      workspaceState.path,
       new DiskStructuredStore(),
       blobs,
     ),
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index 9b4abed8e..c255bf27b 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -61,19 +61,28 @@ export type {
 // ─── Storage ports and composition ─────────────────────────────────────────
 
 export {
+  closeStorage,
   composeStorage,
   createSpace,
   createStorage,
   deleteSpace,
+  detachStorage,
   getBlobStore,
   getStorage,
   getStructuredStore,
   initStorage,
+  mountStorage,
   setStorageForTesting,
   space,
+  stageStorage,
   storageHealth,
 } from './storage.js';
-export type { Space, SpaceDeleteOutcome, Storage } from './storage.js';
+export type {
+  Space,
+  SpaceDeleteOutcome,
+  StagedStorage,
+  Storage,
+} from './storage.js';
 export type { DiskSpaceTree } from './backends/disk/space-tree.js';
 export {
   parseStorageProfile,
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index 42e70016f..124c62e1d 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -91,6 +91,7 @@ describe('storage module tree', () => {
       'profile.test.ts',
       'profile.ts',
       'space-lifecycle-admission.ts',
+      'storage.test.ts',
       'storage.ts',
     ]);
   });
diff --git a/apps/server/src/modules/storage/storage.test.ts b/apps/server/src/modules/storage/storage.test.ts
new file mode 100644
index 000000000..8a38e4f18
--- /dev/null
+++ b/apps/server/src/modules/storage/storage.test.ts
@@ -0,0 +1,238 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * The Workspace mount lifecycle (proposal §12.6.5).
+ *
+ * What these cases are really about is the ordering guarantee: everything that
+ * can fail happens while the previous Workspace is still serving, and the swap
+ * that makes a new mount reachable cannot fail. That is only observable across
+ * two Workspaces, so every case here drives a real Disk profile against two
+ * temporary roots rather than a stub.
+ */
+
+import { existsSync, mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const workspaceState = vi.hoisted(() => ({ path: '' }));
+
+vi.mock('../workspace.js', () => ({
+  getWorkspacePath: () => {
+    if (!workspaceState.path) throw new Error('No workspace configured');
+    return workspaceState.path;
+  },
+  isWorkspaceConfigured: () => workspaceState.path !== '',
+  acquireWorkspaceOperationLease: () => ({
+    workspacePath: workspaceState.path,
+    release: () => {},
+  }),
+}));
+
+import { refreshCanvasDirIndex } from './backends/disk/canvas-dirs.js';
+import { resetStorageCache } from './backends/disk/legacy/canvas-store-cache.js';
+import {
+  closeStorage,
+  composeStorage,
+  createStorage,
+  detachStorage,
+  getStorage,
+  initStorage,
+  setStorageForTesting,
+  stageStorage,
+} from './storage.js';
+
+import type { BlobStore } from './ports/blob.js';
+import type { StructuredStore } from './ports/structured.js';
+import type { StorageProfile } from './profile.js';
+
+const DISK: StorageProfile = {
+  structured: { kind: 'disk' },
+  blobs: { kind: 'disk' },
+};
+
+const WORLD_RECORD = {
+  canvasId: 'world-existing',
+  title: 'World',
+  version: 0,
+  state: { nodes: [], edges: [] },
+  createdAt: 1,
+  updatedAt: 1,
+};
+
+function makeWorkspace(prefix: string): string {
+  return mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+/** Activate `root` the way the synchronous switch does. */
+function activate(root: string): void {
+  workspaceState.path = root;
+  detachStorage();
+  resetStorageCache();
+  refreshCanvasDirIndex();
+}
+
+function seedWorld(root: string, record: unknown = WORLD_RECORD): void {
+  const worldRoot = path.join(root, '.world');
+  mkdirSync(worldRoot, { recursive: true });
+  writeFileSync(
+    path.join(worldRoot, 'space.json'),
+    JSON.stringify(record),
+    'utf8',
+  );
+}
+
+/** A mount whose connections record whether they were closed. */
+function countingStorage(root: string): {
+  storage: ReturnType<typeof composeStorage>;
+  closed: () => number;
+} {
+  let closes = 0;
+  const count = async (): Promise<void> => {
+    closes += 1;
+  };
+  const real = createStorage(DISK, root);
+  return {
+    storage: composeStorage(
+      DISK,
+      root,
+      { ...real.structured, close: count } as unknown as StructuredStore,
+      { ...real.blobs, close: count } as unknown as BlobStore,
+    ),
+    closed: () => closes,
+  };
+}
+
+afterEach(() => {
+  detachStorage();
+  workspaceState.path = '';
+  resetStorageCache();
+  refreshCanvasDirIndex();
+});
+
+describe('storage mount lifecycle', () => {
+  it('bootstraps the Workspace being staged, not the active one', async () => {
+    const active = makeWorkspace('huabu-mount-active-');
+    seedWorld(active);
+    activate(active);
+    const target = makeWorkspace('huabu-mount-target-');
+
+    const staged = await stageStorage(target, DISK);
+
+    // The staged Workspace got its World even though it is not active yet —
+    // the whole reason the connection is constructed with an explicit path.
+    expect(existsSync(path.join(target, '.world', 'space.json'))).toBe(true);
+    expect(staged.storage.workspacePath).toBe(target);
+    // Nothing about the active Workspace moved.
+    expect(getStorage().workspacePath).toBe(active);
+
+    await staged.abort();
+  });
+
+  it('leaves the previous mount serving when staging fails', async () => {
+    const active = makeWorkspace('huabu-mount-keep-active-');
+    seedWorld(active);
+    activate(active);
+    const before = getStorage();
+
+    // An established World that is malformed is an integrity error, never a
+    // signal to mint a replacement identity — so bootstrap refuses.
+    const target = makeWorkspace('huabu-mount-bad-world-');
+    seedWorld(target, { canvasId: 'broken' });
+
+    await expect(stageStorage(target, DISK)).rejects.toThrow();
+
+    expect(getStorage()).toBe(before);
+    expect(getStorage().workspacePath).toBe(active);
+    expect(workspaceState.path).toBe(active);
+  });
+
+  it('publishes the staged mount and closes the one it replaced', async () => {
+    const active = makeWorkspace('huabu-mount-swap-active-');
+    seedWorld(active);
+    activate(active);
+    const previous = countingStorage(active);
+    setStorageForTesting(previous.storage);
+
+    const target = makeWorkspace('huabu-mount-swap-target-');
+    const staged = await stageStorage(target, DISK);
+    expect(previous.closed()).toBe(0);
+
+    // The real sequence: the Workspace path and the mount are published
+    // together. Committing the path detaches the mount that no longer
+    // describes it, which is exactly the case that used to leave the replaced
+    // connections unclosed.
+    await staged.commit(() => {
+      workspaceState.path = target;
+      detachStorage();
+    });
+
+    expect(getStorage()).toBe(staged.storage);
+    // Both axes of the replaced mount are released.
+    expect(previous.closed()).toBe(2);
+  });
+
+  it('closes the staged connections on abort and keeps the active mount', async () => {
+    const active = makeWorkspace('huabu-mount-abort-active-');
+    seedWorld(active);
+    activate(active);
+    const before = getStorage();
+
+    const target = makeWorkspace('huabu-mount-abort-target-');
+    const staged = await stageStorage(target, DISK);
+    await staged.abort();
+
+    expect(getStorage()).toBe(before);
+  });
+
+  it('closes the active mount on shutdown', async () => {
+    const active = makeWorkspace('huabu-mount-close-');
+    seedWorld(active);
+    activate(active);
+    const mounted = countingStorage(active);
+    setStorageForTesting(mounted.storage);
+
+    await closeStorage();
+
+    expect(mounted.closed()).toBe(2);
+  });
+
+  it('validates the profile without mounting when no Workspace is active', async () => {
+    workspaceState.path = '';
+
+    // Free mode at startup: the profile has to be checkable before anyone has
+    // picked a folder, so this opens nothing rather than failing.
+    await expect(initStorage(DISK)).resolves.toBeNull();
+  });
+
+  it('mounts at startup when a Workspace is already active', async () => {
+    const active = makeWorkspace('huabu-mount-managed-');
+    activate(active);
+
+    const mounted = await initStorage(DISK);
+
+    expect(mounted?.workspacePath).toBe(active);
+    // Managed startup meets an empty namespace on first run, and the mount is
+    // what bootstraps it.
+    expect(existsSync(path.join(active, '.world', 'space.json'))).toBe(true);
+  });
+
+  it('drops a mount left behind by a Workspace that moved underneath it', async () => {
+    const first = makeWorkspace('huabu-mount-drift-first-');
+    seedWorld(first);
+    activate(first);
+    expect(getStorage().workspacePath).toBe(first);
+
+    // The synchronous switch detaches; this asserts the guard behind it, for
+    // any path that changes the active Workspace without one.
+    const second = makeWorkspace('huabu-mount-drift-second-');
+    seedWorld(second);
+    workspaceState.path = second;
+    resetStorageCache();
+    refreshCanvasDirIndex();
+
+    expect(getStorage().workspacePath).toBe(second);
+  });
+});
diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts
index bbe024fb9..5ae5a7e16 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -8,17 +8,20 @@
  * validated {@link StorageProfile} and holds them for the process. This is
  * the only place that maps a backend kind to an adapter.
  *
- * The module-level holder mirrors `workspace.ts`, which keeps the active
- * workspace path in module state set once at boot. Call {@link initStorage}
- * from the server entry point so a bad profile fails at startup with an
- * actionable message.
+ * A mount belongs to one Workspace. Switching Workspaces is therefore a
+ * remount rather than a reconfiguration in place, and the lifecycle that does
+ * it — {@link stageStorage} / {@link StagedStorage.commit} — exists so every
+ * step that can fail happens while the previous Workspace is still serving
+ * (proposal §12.6.5). Call {@link initStorage} from the server entry point so
+ * a bad profile fails at startup with an actionable message, before anything
+ * has been opened.
  *
- * Anything that reaches for storage without that — tests, scripts — builds
- * the adapters on demand. That path is synchronous, so it cannot `await
- * init()`, and it is therefore only legal for backends that have nothing to
- * open; see {@link requiresExplicitInit}. It is not a lazy version of
- * {@link initStorage}, and a connection-holding backend must not be reached
- * through it.
+ * Anything that reaches for storage without going through a mount — tests,
+ * scripts, the synchronous Workspace switch — builds the adapters on demand.
+ * That path is synchronous, so it cannot `await init()`, and it is therefore
+ * only legal for backends that have nothing to open; see
+ * {@link requiresExplicitInit}. It is not a lazy version of the mount, and a
+ * connection-holding backend must not be reached through it.
  */
 
 import path from 'node:path';
@@ -26,6 +29,7 @@ import path from 'node:path';
 import {
   acquireWorkspaceOperationLease,
   getWorkspacePath,
+  isWorkspaceConfigured,
 } from '../workspace.js';
 import { DiskBlobStore } from './backends/disk/blob-store.js';
 import { diskSpaceTree } from './backends/disk/space-tree.js';
@@ -99,6 +103,14 @@ function drainRejectedBody(body: Readable | Buffer): void {
 
 export interface Storage {
   readonly profile: StorageProfile;
+  /**
+   * Workspace these connections were opened against.
+   *
+   * A mount belongs to one Workspace. Switching Workspaces is a remount, not
+   * a reconfiguration of the connections in place, so this is what makes a
+   * stale mount recognisable rather than silently serving the wrong data.
+   */
+  readonly workspacePath: string;
   readonly structured: StructuredStore;
   readonly blobs: BlobStore;
   /**
@@ -177,10 +189,13 @@ function buildBlobStore(profile: StorageProfile): BlobStore {
   }
 }
 
-function buildStructuredStore(profile: StorageProfile): StructuredStore {
+function buildStructuredStore(
+  profile: StorageProfile,
+  workspacePath: string,
+): StructuredStore {
   switch (profile.structured.kind) {
     case 'disk':
-      return new DiskStructuredStore();
+      return new DiskStructuredStore(workspacePath);
     default:
       throw new Error(
         `Unsupported structured backend: ${profile.structured.kind}`,
@@ -199,11 +214,13 @@ function buildStructuredStore(profile: StorageProfile): StructuredStore {
  */
 export function composeStorage(
   profile: StorageProfile,
+  workspacePath: string,
   structured: StructuredStore,
   blobs: BlobStore,
 ): Storage {
   return {
     profile,
+    workspacePath: path.resolve(workspacePath),
     structured,
     blobs,
     // Composes from the receiver, not from a captured local. Substituting one
@@ -216,12 +233,21 @@ export function composeStorage(
   };
 }
 
-/** Validate a profile and construct both connections. Does not `init()`. */
-export function createStorage(profile: StorageProfile): Storage {
+/**
+ * Validate a profile and construct both connections for one Workspace.
+ *
+ * Does not `init()` — opening is the mount's job, so a caller can build a
+ * connection it has not committed to using.
+ */
+export function createStorage(
+  profile: StorageProfile,
+  workspacePath: string,
+): Storage {
   validateStorageProfile(profile);
   return composeStorage(
     profile,
-    buildStructuredStore(profile),
+    workspacePath,
+    buildStructuredStore(profile, workspacePath),
     buildBlobStore(profile),
   );
 }
@@ -253,37 +279,167 @@ function serializeSpaceCreate<T>(operation: () => Promise<T>): Promise<T> {
 }
 
 function ensure(): Storage {
-  if (current) return current;
+  const workspacePath = activeWorkspacePath();
+  if (current) {
+    if (current.workspacePath === workspacePath) return current;
+    // The active Workspace moved without going through the mount lifecycle —
+    // the synchronous `setWorkspacePath` path, and the tests that drive it.
+    // Drop the stale mount rather than serving another Workspace's data
+    // through it; the rebuild below either succeeds or says why it cannot.
+    current = null;
+  }
 
   const profile = parseStorageProfile();
   // Build first, so an unimplemented backend reports that rather than the
-  // initialization complaint below.
-  const storage = createStorage(profile);
+  // mount complaint below.
+  const storage = createStorage(profile, workspacePath);
   if (requiresExplicitInit(profile)) {
     throw new StorageProfileError(
-      `Storage was used before initStorage(). The ` +
+      `Storage is not mounted on the active Workspace. The ` +
         `"${profile.structured.kind}" / "${profile.blobs.kind}" profile has ` +
-        `connections to open, and the on-demand path cannot await init(). ` +
-        `Call initStorage() during startup.`,
+        `connections to open, and this path cannot await init(). Activate the ` +
+        `Workspace through the mount lifecycle instead.`,
     );
   }
   current = storage;
   return current;
 }
 
+// ─── Workspace mount lifecycle ──────────────────────────────────────────────
+
 /**
- * Build the storage connections and open them.
+ * Connections opened for a Workspace that is not active yet.
  *
- * Called at server boot so an invalid profile surfaces immediately rather
- * than on the first upload.
+ * Staging exists so activation can fail without consequences. Everything that
+ * can go wrong — an unimplemented backend, a connection that will not open, a
+ * namespace whose World is malformed — happens here, while the previous
+ * Workspace and its connections are still serving. Only {@link commit} makes
+ * the new mount reachable, and it cannot fail.
  */
-export async function initStorage(
+export interface StagedStorage {
+  readonly storage: Storage;
+  /**
+   * Publish this mount and close the one it replaced.
+   *
+   * `publish` is the caller's own commit — for a Workspace switch, making the
+   * new path the active one. It runs in the same synchronous block as the
+   * swap, so no request can land in a gap where the path has moved but the
+   * mount serving it has not. Closing the replaced connections happens after,
+   * where a slow close cannot delay the first request against the new
+   * Workspace.
+   *
+   * A `publish` that throws leaves the active mount exactly as it was; the
+   * caller should then {@link abort}. The swap itself cannot fail.
+   */
+  commit(publish?: () => void): Promise<void>;
+  /** Close the staged connections. The active mount is untouched. */
+  abort(): Promise<void>;
+}
+
+async function closeQuietly(storage: Storage): Promise<void> {
+  await Promise.all([
+    storage.structured.close().catch(() => undefined),
+    storage.blobs.close().catch(() => undefined),
+  ]);
+}
+
+/**
+ * Open connections for `workspacePath` and bootstrap its World.
+ *
+ * Does not touch the active mount, the active Workspace path, or any
+ * process-wide state. A rejection here leaves the previous Workspace fully
+ * serving, which is the whole point of separating this from {@link
+ * StagedStorage.commit} (proposal §12.6.5).
+ */
+export async function stageStorage(
+  workspacePath: string,
   profile: StorageProfile = parseStorageProfile(),
+): Promise<StagedStorage> {
+  // The mount this one replaces, captured now rather than at commit time.
+  // Committing a Workspace path detaches the mount that no longer describes
+  // it, so by the time the swap runs there may be nothing left to read — and
+  // the connections would never be closed.
+  const replaced = current;
+  const storage = createStorage(profile, workspacePath);
+  try {
+    await Promise.all([storage.structured.init(), storage.blobs.init()]);
+    // Every backend meets an empty namespace the first time it is mounted, and
+    // a Workspace with no World has no Portal target. This runs before the
+    // path is committed, so it must address the Workspace being staged rather
+    // than the active one — which is why the connection is constructed with an
+    // explicit path.
+    await storage.structured.spaces().ensureWorld();
+  } catch (error) {
+    await closeQuietly(storage);
+    throw error;
+  }
+
+  return {
+    storage,
+    async commit(publish?: () => void): Promise<void> {
+      publish?.();
+      current = storage;
+      if (replaced && replaced !== storage) await closeQuietly(replaced);
+    },
+    /** Leaves `replaced` alone — it is still the active mount. */
+    abort(): Promise<void> {
+      return closeQuietly(storage);
+    },
+  };
+}
+
+/**
+ * Mount storage onto `workspacePath` in one step.
+ *
+ * For callers that have nothing to do between staging and publishing. An
+ * activation that must commit the Workspace path between the two — every
+ * runtime switch — drives {@link stageStorage} directly instead.
+ */
+export async function mountStorage(
+  workspacePath: string,
+  profile?: StorageProfile,
 ): Promise<Storage> {
-  const storage = createStorage(profile);
-  await Promise.all([storage.structured.init(), storage.blobs.init()]);
-  current = storage;
-  return storage;
+  const staged = await stageStorage(workspacePath, profile);
+  await staged.commit();
+  return staged.storage;
+}
+
+/**
+ * Detach the current mount without closing it, returning what was detached.
+ *
+ * The escape hatch for the synchronous Workspace switch, which cannot await a
+ * close. Returning the detached mount rather than closing it here keeps the
+ * decision with the caller: a backend whose `close()` matters is one that
+ * cannot be reached through the synchronous path anyway, because `ensure()`
+ * refuses to build it.
+ */
+export function detachStorage(): Storage | null {
+  const previous = current;
+  current = null;
+  return previous;
+}
+
+/** Close the active mount. Called on graceful Server shutdown. */
+export async function closeStorage(): Promise<void> {
+  const previous = detachStorage();
+  if (previous) await closeQuietly(previous);
+}
+
+/**
+ * Validate the configured profile, and mount it when a Workspace is already
+ * active.
+ *
+ * Called at server boot so an unknown or unimplemented backend fails there
+ * with an actionable message rather than on the first upload. In free mode
+ * there is no Workspace yet, so this validates and returns without opening
+ * anything; the mount happens when one is activated.
+ */
+export async function initStorage(
+  profile: StorageProfile = parseStorageProfile(),
+): Promise<Storage | null> {
+  validateStorageProfile(profile);
+  if (!isWorkspaceConfigured()) return null;
+  return mountStorage(activeWorkspacePath(), profile);
 }
 
 export function getStorage(): Storage {
diff --git a/apps/server/src/modules/workspace-activation.ts b/apps/server/src/modules/workspace-activation.ts
index ca2144d05..27f9ac52a 100644
--- a/apps/server/src/modules/workspace-activation.ts
+++ b/apps/server/src/modules/workspace-activation.ts
@@ -15,6 +15,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { stageStorage } from './storage/index.js';
 import {
   commitWorkspacePath,
   isManagedMode,
@@ -176,7 +177,17 @@ export function runWorkspacePreparation(
   });
 }
 
-/** Prepare a free-mode workspace and commit it only after full success. */
+/**
+ * Prepare a free-mode workspace and commit it only after full success.
+ *
+ * Ordering is the contract (proposal §12.6.5). The disposable child prepares
+ * and migrates the directory; storage then stages its connections against the
+ * *new* path and bootstraps its World; only once both have succeeded is the
+ * Workspace path committed and the mount published. Anything that fails before
+ * the commit leaves the previous Workspace and its connections serving, which
+ * is why staging is separate from publishing — a half-activated Workspace is
+ * the one outcome this sequence exists to prevent.
+ */
 export async function activateWorkspacePath(
   newPath: string,
   options: PreparationOptions = {},
@@ -194,7 +205,17 @@ export async function activateWorkspacePath(
   activationInProgress = true;
   try {
     await runWorkspacePreparation(resolvedPath, options);
-    commitWorkspacePath(resolvedPath);
+    const staged = await stageStorage(resolvedPath);
+    try {
+      // The path and the mount that serves it are published together, so no
+      // request can observe one without the other.
+      await staged.commit(() => commitWorkspacePath(resolvedPath));
+    } catch (error) {
+      // The path change was refused — an in-flight operation still holds the
+      // previous Workspace. Discard the connections nobody will reach.
+      await staged.abort();
+      throw error;
+    }
   } finally {
     activationInProgress = false;
   }
diff --git a/apps/server/src/modules/workspace.ts b/apps/server/src/modules/workspace.ts
index 235042a92..324dfccb9 100644
--- a/apps/server/src/modules/workspace.ts
+++ b/apps/server/src/modules/workspace.ts
@@ -40,6 +40,7 @@ import path from 'node:path';
 
 import { resetExternalNoteSessions } from './canvas/external-watcher.js';
 import { refreshCanvasDirIndex } from './storage/canvas-dirs.js';
+import { detachStorage } from './storage/storage.js';
 import { prepareWorkspaceOnDisk } from './workspace-prepare.js';
 import { invalidateUserSkill } from '../prompt/index.js';
 
@@ -211,7 +212,17 @@ export function resolveWorkspacePath(newPath: string): string {
  */
 export function commitWorkspacePath(resolvedPath: string): void {
   assertWorkspacePathChangeAllowed(resolvedPath);
+  const changed = _workspacePath !== resolvedPath;
   _workspacePath = resolvedPath;
+  if (changed) {
+    // A mount belongs to one Workspace, so the previous one no longer
+    // describes anything reachable. Detach rather than close: this function is
+    // synchronous and cannot await, and a backend whose `close()` matters is
+    // one the lazy rebuild refuses to construct anyway — such a profile is
+    // mounted through `stageStorage`, which closes the mount it replaces
+    // (proposal §12.6.5).
+    detachStorage();
+  }
   // Drop the cached canvas-dir index so subsequent lookups (used by
   // migrations and route handlers) reflect the new workspace.
   refreshCanvasDirIndex();
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 4b22089c4..6d418ac51 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -33,12 +33,15 @@ async function start(): Promise<void> {
     }
 
     // Before anything serves: an unknown or unimplemented backend must
-    // fail here with an actionable message, not on the first upload.
+    // fail here with an actionable message, not on the first upload. In free
+    // mode there is no Workspace yet, so this validates the profile and the
+    // mount waits for activation.
     const storage = await initStorage();
     log.info(
       {
-        structured: storage.profile.structured.kind,
-        blobs: storage.profile.blobs.kind,
+        structured: storage?.profile.structured.kind,
+        blobs: storage?.profile.blobs.kind,
+        workspace: storage ? 'mounted' : 'awaiting activation',
       },
       'Storage backends ready',
     );

From 20dd70e158dc03ff1d65683cce525f14f5ff0872 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 11:24:56 +0800
Subject: [PATCH 09/20] feat(storage): hand extensions a place, not a data API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two families were files only because they always had been: memory-worker
bookkeeping in `.memory/state.json`, and the debug prompt log under
`.history/chat/`. Neither is a Space record and neither is a blob — they are
some other module's own state, which happened to live next to storage's.

The obvious repair is a port member per feature (`memory`, `promptLogs`),
which obliges every future backend to model data it has no stake in — the
thing §12.5.7 rejected when it declined a `SpaceChats.list()` port. The
next-obvious one is a namespaced key/value member, and it is wrong for a
reason worth recording: it fixes one access shape — whole-value rewrite, no
queries, no indexes — for every owner forever, and an owner with real query
needs then encodes its own index inside an opaque value.

So `SpaceHandle.extension(namespace)` hands over a connection point and
nothing else: a reserved directory on Disk today, a table prefix or schema
when those adapters exist. The owner brings its own store and its own
queries. Storage keeps lifecycle, because only it can — a namespace is
created on demand and destroyed with the Space, which keeps `beginDelete()`
whole without any owner registering a cleanup hook.

The substrate returns null for a Space that does not exist, and that is
load-bearing rather than defensive. The memory trigger carried its own
resurrection guard: its op-counter hook fires *after* a delete has removed
the Space, and a bare write would recreate the directory as a stub holding
nothing but bookkeeping. Every owner writing through an ad-hoc path needed
that guard. Refusing a substrate for a Space that is gone states it once, in
the one place that can, and the guard is deleted rather than moved.

The namespace grammar is narrower than it looks like it needs to be, and the
reasons are recorded where it is defined: an owner prefix is required because
storage cannot arbitrate a collision it never sees the data behind, and `_`
is reserved because a backend keyed on identifiers has to fold the dots into
something legal and the obvious fold is `_`.

The contract asserts isolation and lifecycle only — there is no data
behaviour to assert about data the port cannot read — so the harness supplies
the read and write, and the suite says what must be true of whatever an owner
stored. Destruction is checked by recreating the Space under the same id,
because on Disk it falls out of placement and on another backend it will not.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../agent/conversation/prompt/debug-prompt.ts |  50 +++++-
 .../src/modules/agent/memory/trigger.test.ts  | 117 +++++++++++++
 .../src/modules/agent/memory/trigger.ts       |  91 ++++++----
 .../storage/backends/disk/space-extension.ts  |  58 ++++++
 .../backends/disk/space-repository.test.ts    |  21 +++
 .../storage/backends/disk/structured-store.ts |   7 +-
 apps/server/src/modules/storage/index.ts      |   5 +
 .../modules/storage/module-boundaries.test.ts |   6 +-
 .../contracts/space-extension.contract.ts     | 165 ++++++++++++++++++
 .../modules/storage/ports/namespace.test.ts   |  46 +++++
 .../src/modules/storage/ports/namespace.ts    |  55 ++++++
 .../src/modules/storage/ports/structured.ts   |  56 ++++++
 apps/server/src/modules/storage/storage.ts    |   1 +
 apps/server/src/modules/workspace/paths.ts    |  40 +----
 14 files changed, 640 insertions(+), 78 deletions(-)
 create mode 100644 apps/server/src/modules/agent/memory/trigger.test.ts
 create mode 100644 apps/server/src/modules/storage/backends/disk/space-extension.ts
 create mode 100644 apps/server/src/modules/storage/ports/contracts/space-extension.contract.ts
 create mode 100644 apps/server/src/modules/storage/ports/namespace.test.ts
 create mode 100644 apps/server/src/modules/storage/ports/namespace.ts

diff --git a/apps/server/src/modules/agent/conversation/prompt/debug-prompt.ts b/apps/server/src/modules/agent/conversation/prompt/debug-prompt.ts
index d5f703834..2eaf8a697 100644
--- a/apps/server/src/modules/agent/conversation/prompt/debug-prompt.ts
+++ b/apps/server/src/modules/agent/conversation/prompt/debug-prompt.ts
@@ -17,9 +17,10 @@
 import { appendFileSync } from 'node:fs';
 import path from 'node:path';
 
-import { mkdirp } from '../../../../utils/fs.js';
-import { chatPromptLogPath } from '../../../workspace/paths.js';
+import { sanitizeId } from '../../../../utils/fs.js';
+import { space } from '../../../storage/index.js';
 
+import type { SpaceSubstrate } from '../../../storage/index.js';
 import type { Context } from '@earendil-works/pi-ai';
 import type { FastifyBaseLogger } from 'fastify';
 
@@ -133,10 +134,31 @@ export interface DumpPromptParams {
   logger: FastifyBaseLogger;
 }
 
+/** This module's namespace on the storage extension substrate. */
+const PROMPT_LOG_NAMESPACE = 'huabu.prompt.log';
+
+/**
+ * Appends chained so turns land in the log in the order they were dumped.
+ *
+ * Resolving a substrate is asynchronous while the call site is a synchronous
+ * driver callback, so the write cannot happen inline any more. Each turn's
+ * text is still rendered synchronously — a snapshot of the messages as they
+ * were — and only the append is deferred.
+ */
+let appendTail: Promise<void> = Promise.resolve();
+
+/** Where this module keeps one log per thread on a Disk substrate. */
+function diskLogPath(substrate: SpaceSubstrate, threadId: string): string {
+  return path.join(
+    substrate.directory,
+    `${sanitizeId(threadId, 'threadId')}.prompt.log`,
+  );
+}
+
 /**
  * Append a readable dump of the assembled prompt for one turn. No-op
- * unless `HUABU_DEBUG_PROMPT` is set or `canvasId` is missing (the log
- * lives under the canvas chat dir). Never throws.
+ * unless `HUABU_DEBUG_PROMPT` is set, or `canvasId` is missing (the log is
+ * per-Space state). Never throws, and never blocks the turn.
  */
 export function dumpAssembledPrompt(params: DumpPromptParams): void {
   if (!isPromptDebugEnabled()) return;
@@ -167,13 +189,25 @@ export function dumpAssembledPrompt(params: DumpPromptParams): void {
     });
     out.push('', '');
 
-    const logPath = chatPromptLogPath(canvasId, params.threadId);
-    mkdirp(path.dirname(logPath));
-    appendFileSync(logPath, out.join('\n'), 'utf-8');
+    const block = out.join('\n');
+    appendTail = appendTail
+      .then(async () => {
+        // A Space deleted mid-turn has no substrate, and this is the last
+        // thing that should recreate one for a debug file.
+        const substrate = await space(canvasId).extension(PROMPT_LOG_NAMESPACE);
+        if (!substrate) return;
+        appendFileSync(diskLogPath(substrate, params.threadId), block, 'utf-8');
+      })
+      .catch((err: unknown) => {
+        params.logger.warn(
+          { err: String(err) },
+          'dumpAssembledPrompt: failed to write prompt debug log',
+        );
+      });
   } catch (err) {
     params.logger.warn(
       { err: String(err) },
-      'dumpAssembledPrompt: failed to write prompt debug log',
+      'dumpAssembledPrompt: failed to render prompt debug log',
     );
   }
 }
diff --git a/apps/server/src/modules/agent/memory/trigger.test.ts b/apps/server/src/modules/agent/memory/trigger.test.ts
new file mode 100644
index 000000000..f661111ee
--- /dev/null
+++ b/apps/server/src/modules/agent/memory/trigger.test.ts
@@ -0,0 +1,117 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Memory-worker bookkeeping over the storage extension substrate.
+ *
+ * This is the first owner to build a store on a substrate, so it doubles as
+ * evidence that the substrate is usable without the port growing a data API:
+ * everything here is this module's own format, in a place storage handed it
+ * and never reads (proposal §6.4.4).
+ */
+
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  bumpOpCounter,
+  markAnalyzed,
+  OP_THRESHOLD,
+  readMemoryState,
+} from './trigger.js';
+import { createSpace, deleteSpace, space } from '../../storage/index.js';
+import { setWorkspacePath } from '../../workspace.js';
+
+const CANVAS = 'canvas-memory-trigger';
+let tmp: string;
+
+beforeEach(async () => {
+  tmp = mkdtempSync(path.join(tmpdir(), 'huabu-memory-trigger-'));
+  setWorkspacePath(tmp);
+  const created = await createSpace(CANVAS, 'Trigger');
+  if (!created.ok) throw new Error('Expected to create the Space');
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe('memory trigger state', () => {
+  it('starts from zero and persists what it counts', async () => {
+    await expect(readMemoryState(CANVAS)).resolves.toEqual({
+      counter: 0,
+      lastAnalyzedAt: null,
+      lastSeenThreadCursor: null,
+    });
+
+    await expect(bumpOpCounter(CANVAS, 3)).resolves.toBe(false);
+    await expect(bumpOpCounter(CANVAS, 4)).resolves.toBe(false);
+
+    await expect(readMemoryState(CANVAS)).resolves.toMatchObject({
+      counter: 7,
+    });
+  });
+
+  it('signals once at the threshold and resets in the same write', async () => {
+    await expect(bumpOpCounter(CANVAS, OP_THRESHOLD)).resolves.toBe(true);
+
+    // Reset in the same write, so the very next op batch cannot double-fire.
+    await expect(readMemoryState(CANVAS)).resolves.toMatchObject({
+      counter: 0,
+    });
+    await expect(bumpOpCounter(CANVAS, 1)).resolves.toBe(false);
+  });
+
+  it('keeps concurrent bumps from losing increments', async () => {
+    await Promise.all(
+      Array.from({ length: 10 }, () => bumpOpCounter(CANVAS, 1)),
+    );
+
+    await expect(readMemoryState(CANVAS)).resolves.toMatchObject({
+      counter: 10,
+    });
+  });
+
+  it('records an analysis pass without touching the counter', async () => {
+    await bumpOpCounter(CANVAS, 5);
+    await markAnalyzed(CANVAS, { lastSeenThreadCursor: 42 });
+
+    const state = await readMemoryState(CANVAS);
+    expect(state.counter).toBe(5);
+    expect(state.lastSeenThreadCursor).toBe(42);
+    expect(state.lastAnalyzedAt).toEqual(expect.any(Number));
+  });
+
+  it('keeps each Space to its own bookkeeping', async () => {
+    const other = 'canvas-memory-trigger-other';
+    const created = await createSpace(other, 'Other');
+    if (!created.ok) throw new Error('Expected to create the second Space');
+
+    await bumpOpCounter(CANVAS, 4);
+    await bumpOpCounter(other, 9);
+
+    await expect(readMemoryState(CANVAS)).resolves.toMatchObject({
+      counter: 4,
+    });
+    await expect(readMemoryState(other)).resolves.toMatchObject({ counter: 9 });
+  });
+
+  it('drops a write for a Space that was deleted mid-flight', async () => {
+    await bumpOpCounter(CANVAS, 1);
+    const spaceDir = space(CANVAS).diskTree?.directory();
+    if (!spaceDir) throw new Error('Expected the Disk backend in this test');
+
+    await deleteSpace(CANVAS);
+
+    // The op-counter hook fires after the delete has already removed the
+    // Space. This used to need a guard here — a bare write would recreate the
+    // directory as a stub holding nothing but bookkeeping. The port refuses a
+    // substrate for a Space that is gone, so the write is a silent no-op and
+    // nothing is resurrected.
+    await expect(bumpOpCounter(CANVAS, 1)).resolves.toBe(false);
+    expect(existsSync(spaceDir)).toBe(false);
+  });
+});
diff --git a/apps/server/src/modules/agent/memory/trigger.ts b/apps/server/src/modules/agent/memory/trigger.ts
index 1b619b7ca..f2d4b1ced 100644
--- a/apps/server/src/modules/agent/memory/trigger.ts
+++ b/apps/server/src/modules/agent/memory/trigger.ts
@@ -15,19 +15,38 @@
  *                       legacy chat digest. Existing state files preserve it,
  *                       but current analysis passes do not advance it.
  *
- * Persisted at `<canvasDir>/.memory/state.json` so the counter
- * survives process restarts. The file is kept tiny (<128 B) and
- * atomic-written; read / write failures are reported but never thrown
- * — losing this state at worst means we miss or duplicate one
- * analysis pass, which is harmless.
+ * Persisted on the storage extension substrate under the `huabu.memory`
+ * namespace, so the counter survives process restarts. Storage hands this
+ * module a place and nothing else — it never sees these three fields, and this
+ * module owns the format, one small store per backend kind (proposal §6.4.4).
+ * The state is kept tiny (<128 B) and atomic-written; read / write failures are
+ * reported but never thrown — losing it at worst means we miss or duplicate
+ * one analysis pass, which is harmless.
  */
 
-import { existsSync } from 'node:fs';
+import path from 'node:path';
 
-import { atomicWriteJson, mkdirp, readJson } from '../../../utils/fs.js';
+import { atomicWriteJson, readJson } from '../../../utils/fs.js';
 import { createKeyedMutex } from '../../../utils/keyed-mutex.js';
 import { space } from '../../storage/index.js';
-import { memoryStatePath, canvasMemoryDir } from '../../workspace/paths.js';
+
+import type { SpaceSubstrate } from '../../storage/index.js';
+
+/** This module's namespace on the substrate. */
+const MEMORY_NAMESPACE = 'huabu.memory';
+
+/**
+ * Where this module keeps its state on a Disk substrate.
+ *
+ * The whole store, because the state is one whole-value rewrite. A key/value
+ * member on the port would have covered exactly this and nothing else, for
+ * every owner forever — which is why the port hands over a place instead
+ * (§6.4.4). An owner that later wants the same shape extracts a helper *over*
+ * the substrate, never a port member.
+ */
+function diskStatePath(substrate: SpaceSubstrate): string {
+  return path.join(substrate.directory, 'state.json');
+}
 
 /** Op-count threshold that triggers a memory analysis pass. */
 export const OP_THRESHOLD = 50;
@@ -59,9 +78,10 @@ const EMPTY_STATE: MemoryState = {
  * we'd rather miscount a few ops than crash the request pipeline on
  * a corrupted bookkeeping file.
  */
-export function readMemoryState(canvasId: string): MemoryState {
-  if (!existsSync(memoryStatePath(canvasId))) return { ...EMPTY_STATE };
-  const raw = readJson<Partial<MemoryState>>(memoryStatePath(canvasId));
+export async function readMemoryState(canvasId: string): Promise<MemoryState> {
+  const substrate = await space(canvasId).extension(MEMORY_NAMESPACE);
+  if (!substrate) return { ...EMPTY_STATE };
+  const raw = readJson<Partial<MemoryState>>(diskStatePath(substrate));
   if (!raw || typeof raw !== 'object') return { ...EMPTY_STATE };
   return {
     counter: typeof raw.counter === 'number' ? raw.counter : 0,
@@ -74,23 +94,24 @@ export function readMemoryState(canvasId: string): MemoryState {
   };
 }
 
-/** Atomic write of the memory state, creating `.memory/` on demand. */
-export function writeMemoryState(canvasId: string, state: MemoryState): void {
-  // Resurrection guard: the op-counter `onResponse` hook fires
-  // *after* DELETE /api/canvas/:id has rm -rf'd the canvas dir, and
-  // would otherwise mkdirp `.memory/` + drop a fresh `state.json`
-  // here \u2014 leaving behind a stub canvas dir containing only that
-  // file. Same hazard for any in-flight memory worker that calls
-  // `markAnalyzed` post-delete. Skip the write when the canvas root
-  // is gone; losing one bookkeeping write is harmless.
-  // Disk-only by construction: the hazard is an ad-hoc file write
-  // recreating a directory the delete removed, and a backend with no
-  // directory has no such hazard. Phase 4.6 retires the guard entirely when
-  // this state moves onto the extension substrate (proposal §12.6.3).
-  const tree = space(canvasId).diskTree;
-  if (tree && !existsSync(tree.directory())) return;
-  mkdirp(canvasMemoryDir(canvasId));
-  atomicWriteJson(memoryStatePath(canvasId), state);
+/**
+ * Atomic write of the memory state.
+ *
+ * No resurrection guard of its own. The op-counter `onResponse` hook fires
+ * *after* DELETE /api/canvas/:id has removed the Space, and this module used
+ * to check the Space directory itself before writing — otherwise it would drop
+ * a fresh `state.json` into a directory the delete had just removed, leaving a
+ * stub Space behind. `extension()` refuses a substrate for a Space that is
+ * gone, so the guard now lives in the one place that can state it for every
+ * owner rather than being re-derived by each (proposal §12.6.3).
+ */
+export async function writeMemoryState(
+  canvasId: string,
+  state: MemoryState,
+): Promise<void> {
+  const substrate = await space(canvasId).extension(MEMORY_NAMESPACE);
+  if (!substrate) return;
+  atomicWriteJson(diskStatePath(substrate), state);
 }
 
 /**
@@ -112,16 +133,16 @@ export async function bumpOpCounter(
   delta: number,
 ): Promise<boolean> {
   if (!Number.isFinite(delta) || delta <= 0) return false;
-  return stateLock(canvasId, () => {
-    const state = readMemoryState(canvasId);
+  return stateLock(canvasId, async () => {
+    const state = await readMemoryState(canvasId);
     state.counter += delta;
     if (state.counter < OP_THRESHOLD) {
-      writeMemoryState(canvasId, state);
+      await writeMemoryState(canvasId, state);
       return false;
     }
     // Threshold crossed: reset and signal.
     state.counter = 0;
-    writeMemoryState(canvasId, state);
+    await writeMemoryState(canvasId, state);
     return true;
   });
 }
@@ -144,12 +165,12 @@ export async function markAnalyzed(
     lastSeenThreadCursor?: number;
   } = {},
 ): Promise<void> {
-  await stateLock(canvasId, () => {
-    const state = readMemoryState(canvasId);
+  await stateLock(canvasId, async () => {
+    const state = await readMemoryState(canvasId);
     state.lastAnalyzedAt = Date.now();
     if (opts.lastSeenThreadCursor !== undefined) {
       state.lastSeenThreadCursor = opts.lastSeenThreadCursor;
     }
-    writeMemoryState(canvasId, state);
+    await writeMemoryState(canvasId, state);
   });
 }
diff --git a/apps/server/src/modules/storage/backends/disk/space-extension.ts b/apps/server/src/modules/storage/backends/disk/space-extension.ts
new file mode 100644
index 000000000..588419a1e
--- /dev/null
+++ b/apps/server/src/modules/storage/backends/disk/space-extension.ts
@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Disk implementation of the extension substrate.
+ *
+ * One reserved directory per namespace, under a hidden `.ext/` tier inside the
+ * Space — the same tier as `.artifacts/` and `.history/`, because an
+ * extension's store is machine state rather than something a user authors.
+ *
+ * Destruction is free here, and that is worth stating rather than relying on:
+ * the namespace lives *inside* the Space directory, so the existing
+ * `store.destroy()` removes it with everything else. A backend that keys
+ * extensions by table prefix or schema has no such placement and must drop
+ * them explicitly — which is why the contract asserts the outcome instead of
+ * trusting the mechanism.
+ */
+
+import path from 'node:path';
+
+import { canvasRoot } from './layout.js';
+import { mkdirp } from '../../../../utils/fs.js';
+import { assertValidNamespace } from '../../ports/namespace.js';
+
+import type { CanvasStore } from './legacy/canvas-store.js';
+import type { SpaceHandle, SpaceSubstrate } from '../../ports/structured.js';
+
+/** Hidden tier holding one directory per extension namespace. */
+export const EXTENSIONS_DIR_NAME = '.ext';
+
+export function createDiskSpaceExtension(
+  store: CanvasStore,
+  readRecord: SpaceHandle['read'],
+): SpaceHandle['extension'] {
+  return async function extension(
+    namespace: string,
+  ): Promise<SpaceSubstrate | null> {
+    assertValidNamespace(namespace);
+    // The existence check is the point, not a courtesy. Owners write through
+    // ordinary filesystem calls, so handing back a path for a Space that was
+    // just deleted would let the first write recreate its directory as a stub
+    // holding nothing but bookkeeping. Every owner used to carry its own guard
+    // against that; this is the one place that can state it.
+    if ((await readRecord()) === null) return null;
+
+    const directory = path.join(
+      canvasRoot(store.canvasId),
+      EXTENSIONS_DIR_NAME,
+      namespace,
+    );
+    // Created on demand, so an owner receives somewhere it can write rather
+    // than a path it has to prepare. The window between the check above and
+    // an owner's own write stays open — a Space deleted inside it is the same
+    // race the per-owner guards had — but nothing widens it.
+    mkdirp(directory);
+    return { kind: 'disk', directory };
+  };
+}
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
index e8ff2374a..caa3fe63d 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
@@ -2,6 +2,7 @@
 // Licensed under the MIT license.
 
 import {
+  existsSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
@@ -27,6 +28,7 @@ import { resetStorageCache } from './legacy/canvas-store-cache.js';
 import { DiskSpaceRepository } from './space-repository.js';
 import { DiskStructuredStore } from './structured-store.js';
 import { toSafeFilename } from '../../../../utils/naming.js';
+import { describeSpaceExtensionContract } from '../../ports/contracts/space-extension.contract.js';
 import { describeSpaceRepositoryContract } from '../../ports/contracts/space-repository.contract.js';
 
 import type { CanvasFile } from '../../../canvas/persistence-types.js';
@@ -129,6 +131,25 @@ describeSpaceRepositoryContract('Disk', () => {
   };
 });
 
+describeSpaceExtensionContract('Disk', () => {
+  const root = makeWorkspace('huabu-space-extension-contract-');
+  seedWorld(root);
+  const store = new DiskStructuredStore();
+  return {
+    repository: store.spaces(),
+    space: (canvasId: string) => store.space(canvasId),
+    // An owner of a Disk namespace writes files into its directory; nothing
+    // about the shape is storage's business, so the suite borrows the
+    // simplest one an owner could pick.
+    write: (substrate, value) =>
+      writeFileSync(path.join(substrate.directory, 'value'), value, 'utf8'),
+    read: (substrate) => {
+      const file = path.join(substrate.directory, 'value');
+      return existsSync(file) ? readFileSync(file, 'utf8') : null;
+    },
+  };
+});
+
 describe('DiskSpaceRepository membership', () => {
   it('refreshes external additions, deletions, and directory renames', async () => {
     const root = makeWorkspace('huabu-space-membership-refresh-');
diff --git a/apps/server/src/modules/storage/backends/disk/structured-store.ts b/apps/server/src/modules/storage/backends/disk/structured-store.ts
index fc5a61506..665a0926e 100644
--- a/apps/server/src/modules/storage/backends/disk/structured-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/structured-store.ts
@@ -22,6 +22,7 @@
  */
 
 import { getCanvasStore } from './legacy/canvas-store-cache.js';
+import { createDiskSpaceExtension } from './space-extension.js';
 import { createDiskSpaceLogs } from './space-logs.js';
 import { DiskSpaceNodes } from './space-nodes.js';
 import { createDiskSpaceRecordReader } from './space-record.js';
@@ -73,14 +74,18 @@ export class DiskStructuredStore implements StructuredStore {
     // `getCanvasStore` validates the id and owns the instance cache.
     const store = getCanvasStore(canvasId);
     const { events, changes } = createDiskSpaceLogs(store);
+    const read = createDiskSpaceRecordReader(store);
     return {
       canvasId: store.canvasId,
-      read: createDiskSpaceRecordReader(store),
+      read,
       write: createDiskSpaceWrite(store),
       nodes: new DiskSpaceNodes(store),
       changes,
       tasks: new DiskSpaceTasks(store),
       events,
+      // Shares the handle's own record read, so the existence check that
+      // guards a substrate is the same one every other member answers to.
+      extension: createDiskSpaceExtension(store, read),
     };
   }
 }
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index c255bf27b..bc82ec6d7 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -90,6 +90,10 @@ export {
   validateStorageProfile,
 } from './profile.js';
 export type { StorageProfile } from './profile.js';
+export {
+  assertValidNamespace,
+  SpaceNamespaceError,
+} from './ports/namespace.js';
 export { BlobNameError, normalizeBlobName } from './ports/blob.js';
 export type {
   BlobBackendKind,
@@ -123,6 +127,7 @@ export type {
   SpaceRenameInput,
   SpaceRenameResult,
   SpaceRepository,
+  SpaceSubstrate,
   SpaceTaskRuns,
   SpaceTasks,
   SpaceWriteInput,
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index 124c62e1d..a9a1784be 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -303,14 +303,14 @@ describe('Disk Space tree capability', () => {
     'modules/canvas/canvas.route.ts',
     // A — external-note claim.
     'modules/canvas/external.route.ts',
-    // C — the resurrection guard, which disappears with the substrate.
-    'modules/agent/memory/trigger.ts',
     // B, deferred — RFS's sidecar-to-record mapping. Portable in principle,
     // Disk's in practice until a second backend has a file plane at all.
     'modules/remote_fs/node-meta.ts',
     // D — the per-Space RFS access guide, headed for a blob.
     'modules/remote_fs/skill.ts',
-    // C and D — memory files, the debug prompt log, ACP session state.
+    // D and C — the memory body, and ACP session state until phase 6. The
+    // memory bookkeeping and the debug prompt log have already left, onto the
+    // extension substrate.
     'modules/workspace/paths.ts',
   ].sort();
 
diff --git a/apps/server/src/modules/storage/ports/contracts/space-extension.contract.ts b/apps/server/src/modules/storage/ports/contracts/space-extension.contract.ts
new file mode 100644
index 000000000..4f2f7cbb9
--- /dev/null
+++ b/apps/server/src/modules/storage/ports/contracts/space-extension.contract.ts
@@ -0,0 +1,165 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Reusable contract for the extension substrate.
+ *
+ * Isolation and lifecycle, and nothing else — there is no data behaviour to
+ * assert, because the port never sees what an owner puts in a namespace. That
+ * is also why the harness supplies the read and write: the suite states what
+ * must be true of *whatever* an owner stored, and each backend says how one
+ * stores it.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import type {
+  SpaceHandle,
+  SpaceRepository,
+  SpaceSubstrate,
+} from '../structured.js';
+
+export interface SpaceExtensionContractHarness {
+  /** Collection, so a case can create and destroy the Space it works on. */
+  readonly repository: SpaceRepository;
+  readonly space: (canvasId: string) => SpaceHandle;
+  /** Store `value` in a substrate the way an owner of it would. */
+  readonly write: (
+    substrate: SpaceSubstrate,
+    value: string,
+  ) => Promise<void> | void;
+  /** Read back what {@link write} stored, or null when nothing is there. */
+  readonly read: (
+    substrate: SpaceSubstrate,
+  ) => Promise<string | null> | string | null;
+  readonly cleanup?: () => Promise<void> | void;
+}
+
+const OWNED = 'contract.owner';
+const OTHER = 'contract.other';
+
+export function describeSpaceExtensionContract(
+  name: string,
+  createHarness: () =>
+    | Promise<SpaceExtensionContractHarness>
+    | SpaceExtensionContractHarness,
+): void {
+  describe(`Space extension contract: ${name}`, () => {
+    let harness: SpaceExtensionContractHarness | null = null;
+
+    async function open(): Promise<SpaceExtensionContractHarness> {
+      harness = await createHarness();
+      return harness;
+    }
+
+    afterEach(async () => {
+      await harness?.cleanup?.();
+      harness = null;
+    });
+
+    /** Create a Space and return a substrate for it. */
+    async function substrateFor(
+      h: SpaceExtensionContractHarness,
+      canvasId: string,
+      namespace = OWNED,
+    ): Promise<SpaceSubstrate> {
+      const created = await h.repository.create({ canvasId, title: canvasId });
+      if (!created.ok && created.reason !== 'already-exists') {
+        throw new Error(`Expected to create ${canvasId}`);
+      }
+      const substrate = await h.space(canvasId).extension(namespace);
+      if (!substrate) {
+        throw new Error(`Expected a substrate for ${canvasId}/${namespace}`);
+      }
+      return substrate;
+    }
+
+    it('refuses a namespace without an owner prefix', async () => {
+      const { repository, space } = await open();
+      await repository.create({
+        canvasId: 'contract-ext-grammar',
+        title: 'Grammar',
+      });
+
+      // The owner prefix is what makes a collision the owner's problem rather
+      // than storage's, so a bare name is refused rather than accommodated.
+      await expect(
+        space('contract-ext-grammar').extension('memory'),
+      ).rejects.toThrow();
+      await expect(
+        space('contract-ext-grammar').extension('Huabu.Memory'),
+      ).rejects.toThrow();
+      await expect(
+        space('contract-ext-grammar').extension('huabu.mem_ory'),
+      ).rejects.toThrow();
+    });
+
+    it('has no substrate for a Space that does not exist', async () => {
+      const { space } = await open();
+
+      // Load-bearing: an owner writing through a substrate it was handed for a
+      // deleted Space could recreate that Space as a stub.
+      await expect(
+        space('contract-ext-absent').extension(OWNED),
+      ).resolves.toBeNull();
+    });
+
+    it('keeps two namespaces on one Space apart', async () => {
+      const h = await open();
+      const owned = await substrateFor(h, 'contract-ext-two-ns', OWNED);
+      const other = await substrateFor(h, 'contract-ext-two-ns', OTHER);
+
+      await h.write(owned, 'owned value');
+      await h.write(other, 'other value');
+
+      await expect(await h.read(owned)).toBe('owned value');
+      await expect(await h.read(other)).toBe('other value');
+    });
+
+    it('keeps one namespace on two Spaces apart', async () => {
+      const h = await open();
+      const first = await substrateFor(h, 'contract-ext-space-a');
+      const second = await substrateFor(h, 'contract-ext-space-b');
+
+      await h.write(first, 'first value');
+      await h.write(second, 'second value');
+
+      await expect(await h.read(first)).toBe('first value');
+      await expect(await h.read(second)).toBe('second value');
+    });
+
+    it('resolves the same namespace to the same place every time', async () => {
+      const h = await open();
+      const first = await substrateFor(h, 'contract-ext-stable');
+      await h.write(first, 'written once');
+
+      const again = await h.space('contract-ext-stable').extension(OWNED);
+      if (!again) throw new Error('Expected a substrate');
+
+      await expect(await h.read(again)).toBe('written once');
+    });
+
+    it('destroys a namespace with the Space', async () => {
+      const h = await open();
+      const canvasId = 'contract-ext-lifecycle';
+      const substrate = await substrateFor(h, canvasId);
+      await h.write(substrate, 'should not survive');
+      await expect(await h.read(substrate)).toBe('should not survive');
+
+      const started = await h.repository.beginDelete({ canvasId });
+      if (!started.ok) throw new Error('Ordinary Space must be deletable');
+      await expect(started.session.finish()).resolves.toEqual({
+        ok: true,
+        reason: 'deleted',
+      });
+
+      // Recreated under the same id, so this asserts the namespace was
+      // destroyed rather than merely unreachable. Storage owns this because
+      // only it can: no owner can clean up a layout that is not its own, and
+      // requiring one to register a hook would make deletion depend on every
+      // extension being loaded.
+      const recreated = await substrateFor(h, canvasId);
+      await expect(await h.read(recreated)).toBeNull();
+    });
+  });
+}
diff --git a/apps/server/src/modules/storage/ports/namespace.test.ts b/apps/server/src/modules/storage/ports/namespace.test.ts
new file mode 100644
index 000000000..f44522c9c
--- /dev/null
+++ b/apps/server/src/modules/storage/ports/namespace.test.ts
@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { describe, expect, it } from 'vitest';
+
+import { assertValidNamespace, SpaceNamespaceError } from './namespace.js';
+
+describe('extension namespace grammar', () => {
+  it.each(['huabu.memory', 'agenetes.acp', 'huabu.prompt.log', 'owner2.name3'])(
+    'accepts %s',
+    (namespace) => {
+      expect(assertValidNamespace(namespace)).toBe(namespace);
+    },
+  );
+
+  it.each([
+    // No owner prefix — the collision this token exists to prevent.
+    ['memory'],
+    ['huabu'],
+    // Reserved because a backend keyed on identifiers folds the dots into
+    // `_`; allowing it here would make that fold ambiguous.
+    ['huabu.mem_ory'],
+    ['huabu_memory'],
+    ['huabu.prompt-log'],
+    // Case-insensitive filesystems and case-folding identifiers would let
+    // these share one place with their lowercase spelling.
+    ['Huabu.Memory'],
+    // Empty or digit-led segments have no legal spelling as an identifier.
+    ['huabu.'],
+    ['.memory'],
+    ['huabu..memory'],
+    ['1huabu.memory'],
+    ['huabu.2memory'],
+    // Path traversal is not special-cased; it simply is not the grammar.
+    ['../escape'],
+    ['huabu/memory'],
+    [''],
+  ])('rejects %j', (namespace) => {
+    expect(() => assertValidNamespace(namespace)).toThrow(SpaceNamespaceError);
+  });
+
+  it('rejects a namespace too long to leave room for an owner’s own suffixes', () => {
+    const long = `huabu.${'a'.repeat(64)}`;
+    expect(() => assertValidNamespace(long)).toThrow(/longer than/);
+  });
+});
diff --git a/apps/server/src/modules/storage/ports/namespace.ts b/apps/server/src/modules/storage/ports/namespace.ts
new file mode 100644
index 000000000..f41fb744b
--- /dev/null
+++ b/apps/server/src/modules/storage/ports/namespace.ts
@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Extension-namespace validation.
+ *
+ * The namespace is the isolation token for {@link SpaceHandle.extension}, and
+ * the only thing storage validates about an extension. It has to be safe as a
+ * directory name on every host, and as part of an identifier in every backend
+ * an adapter may later target — so the grammar is the intersection, decided
+ * once here rather than per adapter.
+ */
+
+/**
+ * `<owner>.<name>`, lowercase, dot-separated.
+ *
+ * Each segment is a letter followed by letters and digits. Deliberately narrow:
+ *
+ * - **An owner prefix is required.** A bare `memory` invites the collision the
+ *   namespace exists to prevent; `huabu.memory` and `agenetes.acp` say whose
+ *   it is. Storage cannot arbitrate a conflict it never sees the data behind.
+ * - **No `_` or `-`.** A backend keyed on identifiers rather than directories
+ *   has to fold the dots into something legal, and the obvious fold is `_`.
+ *   Allowing `_` in a namespace would make that fold ambiguous — `a.b` and
+ *   `a_b` would land in the same place — so the character is reserved.
+ * - **Lowercase only.** Case-insensitive filesystems and case-folding
+ *   identifier rules would otherwise let two namespaces that look distinct
+ *   share one directory or one table.
+ */
+const NAMESPACE_RE = /^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/;
+
+/** Bounded so a namespace stays inside identifier-length limits with room for
+ * an owner's own suffixes. */
+const MAX_NAMESPACE_LENGTH = 64;
+
+export class SpaceNamespaceError extends Error {
+  override name = 'SpaceNamespaceError';
+}
+
+/** Validate an extension namespace, returning it unchanged. */
+export function assertValidNamespace(namespace: string): string {
+  if (namespace.length > MAX_NAMESPACE_LENGTH) {
+    throw new SpaceNamespaceError(
+      `Extension namespace is longer than ${MAX_NAMESPACE_LENGTH} characters: ` +
+        `${JSON.stringify(namespace)}`,
+    );
+  }
+  if (!NAMESPACE_RE.test(namespace)) {
+    throw new SpaceNamespaceError(
+      `Extension namespace ${JSON.stringify(namespace)} is not of the form ` +
+        '"<owner>.<name>" in lowercase letters and digits (e.g. "huabu.memory").',
+    );
+  }
+  return namespace;
+}
diff --git a/apps/server/src/modules/storage/ports/structured.ts b/apps/server/src/modules/storage/ports/structured.ts
index 099988725..9394de28d 100644
--- a/apps/server/src/modules/storage/ports/structured.ts
+++ b/apps/server/src/modules/storage/ports/structured.ts
@@ -250,8 +250,64 @@ export interface SpaceHandle {
    * learns nothing from. A second kind of past record can reintroduce it.
    */
   readonly events: SpaceEvents;
+  /**
+   * An isolated place for one namespace to build its own store on.
+   *
+   * The port hands over a *connection point* and nothing else. It never sees
+   * what the owner puts there, has no opinion about the shape, and offers no
+   * read or write of its own — because the alternative is one port member per
+   * feature (`memory`, `acpSessions`, `promptLogs`), obliging every future
+   * backend to model data it has no stake in. §12.5.7 rejected exactly that
+   * when it declined a `SpaceChats.list()` port.
+   *
+   * A namespaced opaque key/value member would be the obvious repair and is
+   * also wrong: it fixes one access shape — whole-value rewrite, no queries,
+   * no indexes — for every owner forever, and an owner with real query needs
+   * then encodes its own index inside an opaque value. So the owner brings its
+   * own store implementation and its own queries, per backend kind, and
+   * storage supplies only the place (§6.4.4).
+   *
+   * Storage keeps *lifecycle*, because only it can: a namespace is created on
+   * demand here and destroyed with the Space, which keeps
+   * {@link SpaceRepository.beginDelete} whole without any owner registering a
+   * cleanup hook — the one operation an owner could not perform without
+   * knowing a layout that is not its own.
+   *
+   * Returns `null` when the Space does not exist. That is deliberate and
+   * load-bearing: an owner writing through an ad-hoc path could recreate a
+   * Space that was just deleted, leaving a stub behind, and every such owner
+   * grew its own existence guard. Refusing to hand out a substrate for a Space
+   * that is gone puts that guard in the one place that can state it.
+   *
+   * Two consequences to accept openly rather than design against. The backend
+   * kind is part of the extension API, so an owner written against one kind
+   * does not load under another — inherent in letting owners write their own
+   * queries, and the alternative is the lowest common denominator this member
+   * exists to avoid. And the substrate is *unfenced*: the namespace bounds an
+   * owner by convention, not by enforcement. Extensions are in-process code,
+   * trusted at the same level as the Server.
+   *
+   * @param namespace Isolation token, `<owner>.<name>` (see
+   *   {@link assertValidNamespace}). Storage guarantees it is unique and
+   *   unshared, and guarantees nothing about what is inside.
+   */
+  extension(namespace: string): Promise<SpaceSubstrate | null>;
 }
 
+/**
+ * What a namespace gets to build on, discriminated by the live backend.
+ *
+ * One member per backend that exists, like {@link StructuredBackendKind} and
+ * for the same reason: a union that named `sqlite` today would advertise a
+ * substrate no adapter can supply. It grows with each adapter — a table prefix
+ * for SQLite, a schema for Postgres — and an owner switches on `kind`.
+ */
+export type SpaceSubstrate = {
+  readonly kind: 'disk';
+  /** A directory reserved for this namespace, created and ready to write. */
+  readonly directory: string;
+};
+
 // ─── The ordered Space write ─────────────────────────────────────────────────
 
 export type SpaceWriteResult =
diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts
index 5ae5a7e16..c8e208774 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -171,6 +171,7 @@ function composeSpace(storage: Storage, canvasId: string): Space {
     changes: handle.changes,
     tasks: handle.tasks,
     events: handle.events,
+    extension: (namespace) => handle.extension(namespace),
     blobs: guardedBlobScope(storage, canvasId),
     diskTree:
       storage.profile.structured.kind === 'disk'
diff --git a/apps/server/src/modules/workspace/paths.ts b/apps/server/src/modules/workspace/paths.ts
index de4407ae4..64e4e08a9 100644
--- a/apps/server/src/modules/workspace/paths.ts
+++ b/apps/server/src/modules/workspace/paths.ts
@@ -9,10 +9,15 @@
  *
  *   - Workspace-level, no canvasId: `setting/` and the user memory file.
  *     Untouched by a backend switch.
- *   - Per-Space state owned by *other* domains — memory, ACP sessions, the
- *     debug prompt log — which need a materialized directory but not the Disk
- *     record layout. They anchor on the Space's Disk tree from the storage
- *     facade, so they no longer consult the Disk name index (§12.5.4).
+ *   - Per-Space state owned by *other* domains — the memory body and ACP
+ *     sessions — which need a materialized directory but not the Disk record
+ *     layout. They anchor on the Space's Disk tree from the storage facade,
+ *     so they no longer consult the Disk name index (§12.5.4).
+ *
+ * Two families have already left: memory-worker bookkeeping and the debug
+ * prompt log now build their own stores on the storage extension substrate
+ * (§6.4.4), which is a place rather than a path. The memory body follows as a
+ * blob, and ACP sessions with phase 6.
  *
  * The Disk record and blob layout moved to `storage/backends/disk/layout.ts`.
  *
@@ -24,10 +29,8 @@
  *   <spaceDir>/
  *     .memory/                      Space-scoped memory (AI-private)
  *       space.md                    Space memory body
- *       state.json                  memory worker bookkeeping
  *     .history/
  *       acp-sessions.json           per-thread ACP sessionId map (optional)
- *       chat/<threadId>.prompt.log  debug dump, opt-in
  *
  * Naming convention: anything prefixed with `.` is hidden / AI-private;
  * anything without the prefix is user-visible.
@@ -35,7 +38,6 @@
 
 import path from 'node:path';
 
-import { sanitizeId } from '../../utils/fs.js';
 import { space } from '../storage/index.js';
 import { getWorkspacePath } from '../workspace.js';
 
@@ -99,16 +101,6 @@ export function canvasMemoryPath(canvasId: string): string {
   return path.join(canvasMemoryDir(canvasId), 'space.md');
 }
 
-/**
- * Bookkeeping JSON for the memory worker, per canvas:
- *   `{ counter, lastAnalyzedAt, lastSeenThreadCursor }`
- *
- * Read/written by `modules/agent/memory/trigger.ts` (PR-B/C).
- */
-export function memoryStatePath(canvasId: string): string {
-  return path.join(canvasMemoryDir(canvasId), 'state.json');
-}
-
 // ─── Workspace-level setting / user skills ─────────────────────────────────
 
 /**
@@ -129,20 +121,6 @@ export function userSkillsDir(): string {
   return path.join(settingDir(), 'skills');
 }
 
-/**
- * Human-readable debug dump of the assembled prompt sent to the agent,
- * one block per turn with strong turn separators. Append-only, written
- * only when the `HUABU_DEBUG_PROMPT` env flag is set. Never read by the
- * app — purely a developer post-mortem aid. See `conversation/prompt/debug-prompt.ts`.
- */
-export function chatPromptLogPath(canvasId: string, threadId: string): string {
-  return path.join(
-    legacyHistoryDir(canvasId),
-    'chat',
-    `${sanitizeId(threadId, 'threadId')}.prompt.log`,
-  );
-}
-
 /**
  * ACP session persistence — maps each Huabu thread on this canvas
  * to the live ACP `sessionId` returned by `session/new`, so we can

From 4a5fd682979e89cb3166374c92703d052913566b Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 12:57:44 +0800
Subject: [PATCH 10/20] feat(storage): give each user-visible area of a Space
 its own blob scope
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`BlobScopeRef` had one kind, mapped onto `.artifacts/`, so anything else a
Space holds as bytes stayed a bare `readFileSync` against a path the caller
assembled: the RFS access guide at the Space root, the agent's memory body,
the upload scratch. Naming one blob `skill.md` would have put it in a hidden
directory rather than where a user authors it, and the alternative —
hierarchical blob names — §7.1 excluded for every backend.

So there is now one kind per **user-visible area**: artifacts, guide, memory,
upload. A kind is a union member and one placement rule per adapter; a path
separator inside a name would have been a contract change. It also lets
retention diverge later — scratch is not an artifact — without moving bytes
a second time.

The guide scope is the interesting one. Its area *is* the Space root, which
also holds `space.json` and every node directory, so a scope that claimed the
folder would list storage's own records and delete the Space on
`deleteAll()`. It is therefore bounded by its member names instead — a fixed
set is a tighter namespace than a directory, not a looser one — and the
adapter refuses a name the scope does not own before it reaches the
filesystem. The contract pins both halves, because "answers for the folder"
is the shape an adapter would naturally reach for.

Deletion now sweeps every per-Space scope, derived from one list so the saga
cannot fall behind the union. On Disk the extra sweeps are redundant with
removing the directory; on a backend where dropping the record does not
remove the area the bytes sit in, an unswept kind is an orphan.

Two consumers changed shape rather than just changing calls. The memory
writers took an absolute path and a parent directory, which stopped being
expressible once one of their three tiers was a blob and the other two were
still Workspace-scoped files — so they take a document instead, and every
rule about content above it stopped caring which. And the memory body's
sandbox resolver is gone: the port's own precondition already refuses a write
to a Space whose record does not exist, which is what that resolver's
directory check was approximating.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/modules/agent/memory/analyzer.test.ts |  23 ++-
 .../src/modules/agent/memory/analyzer.ts      |  12 +-
 apps/server/src/modules/agent/memory/read.ts  |  21 ++-
 .../src/modules/agent/memory/sandbox.ts       |  17 +-
 .../src/modules/agent/memory/writers.ts       | 117 ++++++++++----
 .../modules/agent/tools/handlers/fs-read.ts   |   2 +-
 .../agent/tools/handlers/fs-write.test.ts     |  35 ++--
 .../modules/agent/tools/handlers/fs-write.ts  |  73 ++++++---
 .../server/src/modules/remote_fs/rfs.route.ts |   2 +-
 apps/server/src/modules/remote_fs/skill.ts    |  27 ++--
 .../disk/blob-store.rename-retry.test.ts      |   2 +-
 .../storage/backends/disk/blob-store.test.ts  |  14 +-
 .../storage/backends/disk/blob-store.ts       | 152 +++++++++++++-----
 .../modules/storage/backends/disk/layout.ts   |  20 +++
 .../compatibility/delete-canvas.test.ts       |  10 +-
 apps/server/src/modules/storage/index.ts      |   9 +-
 .../modules/storage/module-boundaries.test.ts |   9 +-
 apps/server/src/modules/storage/ports/blob.ts |  66 +++++++-
 .../ports/contracts/blob-store.contract.ts    |  64 +++++++-
 apps/server/src/modules/storage/storage.ts    |  35 +++-
 apps/server/src/modules/workspace/paths.ts    |  12 --
 21 files changed, 517 insertions(+), 205 deletions(-)

diff --git a/apps/server/src/modules/agent/memory/analyzer.test.ts b/apps/server/src/modules/agent/memory/analyzer.test.ts
index caa15d40e..6aaa95b7a 100644
--- a/apps/server/src/modules/agent/memory/analyzer.test.ts
+++ b/apps/server/src/modules/agent/memory/analyzer.test.ts
@@ -7,17 +7,32 @@ import path from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-const physicalState = vi.hoisted(() => ({ root: '' }));
+const physicalState = vi.hoisted(() => ({
+  root: '',
+  canvasMemory: null as string | null,
+}));
 
 vi.mock('../agent.service.js', () => ({ runAgent: vi.fn() }));
 vi.mock('../../../prompt/index.js', () => ({
   loadAgent: vi.fn(),
   listSkills: vi.fn(),
 }));
-vi.mock('../../storage/index.js', () => ({ getStructuredStore: vi.fn() }));
+vi.mock('../../storage/index.js', () => ({
+  getStructuredStore: vi.fn(),
+  // The memory body is a blob under the Space's own scope now, so the
+  // snapshot reads it through here rather than off a path.
+  space: (canvasId: string) => ({
+    memory: {
+      read: async () =>
+        physicalState.canvasMemory === null
+          ? null
+          : Buffer.from(physicalState.canvasMemory, 'utf8'),
+      canvasId,
+    },
+  }),
+  SPACE_MEMORY_BLOB_NAME: 'space.md',
+}));
 vi.mock('../../workspace/paths.js', () => ({
-  canvasMemoryPath: (canvasId: string) =>
-    `${physicalState.root}/${canvasId}/.memory/space.md`,
   workspaceMemoryPath: () => `${physicalState.root}/setting/user.md`,
 }));
 
diff --git a/apps/server/src/modules/agent/memory/analyzer.ts b/apps/server/src/modules/agent/memory/analyzer.ts
index fb21fc66f..e5da5d82f 100644
--- a/apps/server/src/modules/agent/memory/analyzer.ts
+++ b/apps/server/src/modules/agent/memory/analyzer.ts
@@ -33,11 +33,9 @@ import {
   type CanvasFile,
   type SpaceHandle,
 } from '../../storage/index.js';
-import {
-  canvasMemoryPath,
-  workspaceMemoryPath,
-} from '../../workspace/paths.js';
+import { workspaceMemoryPath } from '../../workspace/paths.js';
 import { runAgent } from '../agent.service.js';
+import { readCanvasMemory } from './read.js';
 
 import type { MemoryLogger } from './index.js';
 import type { WriteResult } from './writers.js';
@@ -197,7 +195,7 @@ async function assembleContext(
     parts.push(`${events.count} ops`);
   }
 
-  const memorySnapshot = readMemorySnapshot(canvasId);
+  const memorySnapshot = await readMemorySnapshot(canvasId);
   messages.push({
     role: 'user',
     content: `[SYSTEM Current memory]\n${memorySnapshot}`,
@@ -279,14 +277,14 @@ function readEventsDigest(events: readonly CanvasEvent[]): EventsDigest | null {
   return { text: summaries.join('\n'), count: events.length };
 }
 
-function readMemorySnapshot(canvasId: string): string {
+async function readMemorySnapshot(canvasId: string): Promise<string> {
   const parts: string[] = [];
 
   const longTerm = readFileSafe(workspaceMemoryPath());
   parts.push('## Long-term memory');
   parts.push(longTerm.trim().length > 0 ? longTerm.trim() : '(empty)');
 
-  const canvas = readFileSafe(canvasMemoryPath(canvasId));
+  const canvas = (await readCanvasMemory(canvasId)) ?? '';
   parts.push('');
   parts.push('## Canvas memory');
   parts.push(canvas.trim().length > 0 ? canvas.trim() : '(empty)');
diff --git a/apps/server/src/modules/agent/memory/read.ts b/apps/server/src/modules/agent/memory/read.ts
index c8776b05f..a9f6fa8df 100644
--- a/apps/server/src/modules/agent/memory/read.ts
+++ b/apps/server/src/modules/agent/memory/read.ts
@@ -15,10 +15,8 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 
-import {
-  workspaceMemoryPath,
-  canvasMemoryPath,
-} from '../../workspace/paths.js';
+import { space, SPACE_MEMORY_BLOB_NAME } from '../../storage/index.js';
+import { workspaceMemoryPath } from '../../workspace/paths.js';
 
 /**
  * Read the user memory body.
@@ -34,12 +32,19 @@ export function readWorkspaceMemory(): string | null {
 }
 
 /**
- * Read the per-canvas canvas memory body.
+ * Read the per-Space memory body.
  *
- * Same null-on-empty contract as {@link readWorkspaceMemory}.
+ * Same null-on-empty contract as {@link readWorkspaceMemory}. A blob under the
+ * Space's own memory scope (proposal §6.4.3, disposition D) — unlike the
+ * Workspace memory above, which is not scoped to a Space and stays a file.
  */
-export function readCanvasMemory(canvasId: string): string | null {
-  return readNonEmpty(canvasMemoryPath(canvasId));
+export async function readCanvasMemory(
+  canvasId: string,
+): Promise<string | null> {
+  const bytes = await space(canvasId).memory.read(SPACE_MEMORY_BLOB_NAME);
+  if (bytes === null) return null;
+  const raw = bytes.toString('utf8');
+  return raw.trim().length === 0 ? null : raw;
 }
 
 function readNonEmpty(file: string): string | null {
diff --git a/apps/server/src/modules/agent/memory/sandbox.ts b/apps/server/src/modules/agent/memory/sandbox.ts
index 0085b4e43..24d34ae19 100644
--- a/apps/server/src/modules/agent/memory/sandbox.ts
+++ b/apps/server/src/modules/agent/memory/sandbox.ts
@@ -13,7 +13,7 @@
  *
  * Everything else is rejected. Each writer goes through
  * {@link resolveLongTermPath} / {@link resolveUserSkillPath} /
- * {@link resolveWorkingMemoryPath} so the security model lives in one
+ * one resolver per tier so the security model lives in one
  * place — same posture as the chat sandbox at
  * `modules/agent/tools/handlers/fs-sandbox.ts`.
  *
@@ -29,8 +29,6 @@ import {
   workspaceMemoryPath,
   settingDir,
   userSkillsDir,
-  canvasMemoryDir,
-  canvasMemoryPath,
 } from '../../workspace/paths.js';
 
 /** Thrown by every resolver below on out-of-sandbox attempts. */
@@ -97,16 +95,3 @@ export function resolveUserSkillPath(id: string): string {
   ensureUnderRoot(root, target, 'user skills');
   return target;
 }
-
-/**
- * Resolve the absolute Space memory file path. Throws if the resolved path
- * escapes the canvas's `.memory/` root (a defensive check — the path
- * computation in `workspace/paths.ts` already constrains the result,
- * but going through `ensureUnderRoot` keeps the invariant explicit).
- */
-export function resolveWorkingMemoryPath(canvasId: string): string {
-  const root = canvasMemoryDir(canvasId);
-  const target = canvasMemoryPath(canvasId);
-  ensureUnderRoot(root, target, 'canvas memory');
-  return target;
-}
diff --git a/apps/server/src/modules/agent/memory/writers.ts b/apps/server/src/modules/agent/memory/writers.ts
index 9462eb871..fa50c83f9 100644
--- a/apps/server/src/modules/agent/memory/writers.ts
+++ b/apps/server/src/modules/agent/memory/writers.ts
@@ -12,10 +12,14 @@
  *                                          unique substring (Claude
  *                                          Code style edit).
  *
- * Both take an already-sandbox-resolved absolute path; callers
- * (currently `tools/handlers/fs-write.ts`) own the path → tier
- * mapping. The `tier` knob here is purely for behaviour that varies
- * by destination:
+ * Both take a {@link MemoryDocument} — where the bytes live, resolved by the
+ * caller (currently `tools/handlers/fs-write.ts`), which owns the tier
+ * mapping. The indirection exists because the tiers no longer share a
+ * substrate: the Workspace-scoped ones are files, while a Space's memory body
+ * is a blob under its own scope (proposal §6.4.3, disposition D). Everything
+ * below is rules about the *content*, so none of it should know which.
+ *
+ * The `tier` knob is purely for behaviour that varies by destination:
  *
  *   - cap enforcement (workspace + canvas only — skill bodies are
  *     allowed to grow larger)
@@ -38,6 +42,58 @@ import { atomicWriteText, mkdirp } from '../../../utils/fs.js';
 import { createKeyedMutex } from '../../../utils/keyed-mutex.js';
 
 import type { MemoryLogger } from './index.js';
+import type { BlobScope } from '../../storage/index.js';
+
+// ─── Where a document lives ────────────────────────────────────────────────
+
+/**
+ * One memory document, addressed however its tier stores it.
+ *
+ * `target` is what a {@link WriteResult} names, so it is the caller's own
+ * vocabulary rather than a physical location — an agent that reads
+ * `memory/space.md` should see that spelling back, not wherever the bytes
+ * happen to sit.
+ */
+export interface MemoryDocument {
+  readonly target: string;
+  read(): Promise<string | null>;
+  write(body: string): Promise<void>;
+}
+
+/** A document that is a real file — the Workspace-scoped tiers. */
+export function fileDocument(
+  absPath: string,
+  parentDir: string,
+): MemoryDocument {
+  return {
+    target: absPath,
+    async read(): Promise<string | null> {
+      return existsSync(absPath) ? readFileSync(absPath, 'utf8') : null;
+    },
+    async write(body: string): Promise<void> {
+      mkdirp(parentDir);
+      atomicWriteText(absPath, body);
+    },
+  };
+}
+
+/** A document that is a blob — a Space's memory body. */
+export function blobDocument(
+  scope: BlobScope,
+  name: string,
+  target: string,
+): MemoryDocument {
+  return {
+    target,
+    async read(): Promise<string | null> {
+      const bytes = await scope.read(name);
+      return bytes === null ? null : bytes.toString('utf8');
+    },
+    async write(body: string): Promise<void> {
+      await scope.put(name, Buffer.from(body, 'utf8'));
+    },
+  };
+}
 
 // ─── Concurrency guards ────────────────────────────────────────────────────
 //
@@ -71,10 +127,8 @@ export const SKILL_CREATE_RATIONALE_MIN = 20;
 
 interface CommonArgs {
   tier: MemoryTier;
-  /** Absolute path, already sandbox-validated by the caller. */
-  absPath: string;
-  /** Directory to `mkdirp` before writing. */
-  parentDir: string;
+  /** Where the bytes live, already sandbox-validated by the caller. */
+  document: MemoryDocument;
   /**
    * Required when `tier === 'skill'` — used to invalidate the user
    * skill loader cache after a successful write. Ignored otherwise.
@@ -102,24 +156,24 @@ export async function overwriteMemoryFile(
   return runForTier(args.tier, () => doOverwrite(args));
 }
 
-function doOverwrite(args: OverwriteArgs): WriteResult {
+async function doOverwrite(args: OverwriteArgs): Promise<WriteResult> {
+  const { target } = args.document;
   try {
     const body = ensureTrailingNewline(args.body);
     if (args.tier !== 'skill') {
       const capCheck = checkCap(body);
-      if (!capCheck.ok) return reject(args.absPath, capCheck.reason);
+      if (!capCheck.ok) return reject(target, capCheck.reason);
     }
-    mkdirp(args.parentDir);
-    atomicWriteText(args.absPath, body);
+    await args.document.write(body);
     if (args.tier === 'skill' && args.skillId) {
       invalidateUserSkill(args.skillId);
     }
     args.logger?.info(
-      `[memory] ${args.tier} overwritten at ${args.absPath} (${body.length} bytes)`,
+      `[memory] ${args.tier} overwritten at ${target} (${body.length} bytes)`,
     );
-    return { ok: true, target: args.absPath, reason: 'overwritten' };
+    return { ok: true, target, reason: 'overwritten' };
   } catch (err) {
-    return rejectFromError(err, args.absPath);
+    return rejectFromError(err, target);
   }
 }
 
@@ -147,34 +201,32 @@ export async function replaceStringInMemoryFile(
   return runForTier(args.tier, () => doReplaceString(args));
 }
 
-function doReplaceString(args: ReplaceStringArgs): WriteResult {
+async function doReplaceString(args: ReplaceStringArgs): Promise<WriteResult> {
+  const { target } = args.document;
   try {
     if (typeof args.oldString !== 'string' || args.oldString.length === 0) {
-      return reject(args.absPath, 'oldString is required and non-empty');
+      return reject(target, 'oldString is required and non-empty');
     }
     if (typeof args.newString !== 'string') {
-      return reject(args.absPath, 'newString is required (use "" to delete)');
+      return reject(target, 'newString is required (use "" to delete)');
     }
     if (args.oldString === args.newString) {
-      return reject(args.absPath, 'oldString and newString are identical');
+      return reject(target, 'oldString and newString are identical');
     }
-    if (!existsSync(args.absPath)) {
+    const before = await args.document.read();
+    if (before === null) {
       return reject(
-        args.absPath,
+        target,
         `file does not exist — use mode="overwrite" to create it`,
       );
     }
-    const before = readFileSync(args.absPath, 'utf8');
     const idx = before.indexOf(args.oldString);
     if (idx === -1) {
-      return reject(
-        args.absPath,
-        'oldString not found in file — no edit applied',
-      );
+      return reject(target, 'oldString not found in file — no edit applied');
     }
     if (before.indexOf(args.oldString, idx + 1) !== -1) {
       return reject(
-        args.absPath,
+        target,
         'oldString matches multiple times — add more surrounding context to make it unique',
       );
     }
@@ -185,19 +237,18 @@ function doReplaceString(args: ReplaceStringArgs): WriteResult {
     );
     if (args.tier !== 'skill') {
       const capCheck = checkCap(after);
-      if (!capCheck.ok) return reject(args.absPath, capCheck.reason);
+      if (!capCheck.ok) return reject(target, capCheck.reason);
     }
-    mkdirp(args.parentDir);
-    atomicWriteText(args.absPath, after);
+    await args.document.write(after);
     if (args.tier === 'skill' && args.skillId) {
       invalidateUserSkill(args.skillId);
     }
     args.logger?.info(
-      `[memory] ${args.tier} edited at ${args.absPath} (${after.length} bytes)`,
+      `[memory] ${args.tier} edited at ${target} (${after.length} bytes)`,
     );
-    return { ok: true, target: args.absPath, reason: 'edited' };
+    return { ok: true, target, reason: 'edited' };
   } catch (err) {
-    return rejectFromError(err, args.absPath);
+    return rejectFromError(err, target);
   }
 }
 
diff --git a/apps/server/src/modules/agent/tools/handlers/fs-read.ts b/apps/server/src/modules/agent/tools/handlers/fs-read.ts
index c3abcc468..2931d9857 100644
--- a/apps/server/src/modules/agent/tools/handlers/fs-read.ts
+++ b/apps/server/src/modules/agent/tools/handlers/fs-read.ts
@@ -177,7 +177,7 @@ export async function handleRead(
           'memory/space.md is Space-scoped but no canvasId is bound to this request',
         );
       }
-      content = readCanvasMemory(args.canvasId);
+      content = await readCanvasMemory(args.canvasId);
     } else {
       throw new Error(
         `Unknown memory path "${rel}". Valid: memory/user.md, memory/space.md`,
diff --git a/apps/server/src/modules/agent/tools/handlers/fs-write.test.ts b/apps/server/src/modules/agent/tools/handlers/fs-write.test.ts
index 5f17d9ae1..ce4d010aa 100644
--- a/apps/server/src/modules/agent/tools/handlers/fs-write.test.ts
+++ b/apps/server/src/modules/agent/tools/handlers/fs-write.test.ts
@@ -13,26 +13,27 @@
  *   ✓ result envelope shape (`{ ok, target, reason }`) for both ok and reject
  */
 
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-} from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { handleFsWrite } from './fs-write.js';
+import { createSpace, space } from '../../../storage/index.js';
 import {
-  canvasMemoryPath,
   userSkillsDir,
   workspaceMemoryPath,
 } from '../../../workspace/paths.js';
 import { setWorkspacePath } from '../../../workspace.js';
 
+/** Where Disk places the Space memory blob. */
+function memoryBlobFile(canvasId: string): string {
+  const tree = space(canvasId).diskTree;
+  if (!tree) throw new Error('Expected the Disk backend in this test');
+  return join(tree.directory(), '.memory', 'space.md');
+}
+
 interface ParsedResult {
   ok: boolean;
   target: string;
@@ -46,15 +47,14 @@ function parse(raw: string): ParsedResult {
 let tmp: string;
 const canvasId = 'cv-fs-write-test';
 
-beforeEach(() => {
+beforeEach(async () => {
   tmp = mkdtempSync(join(tmpdir(), 'huabu-fs-write-'));
   setWorkspacePath(tmp);
-  // `canvasRoot(canvasId)` falls back to `<workspace>/<canvasId>` when the
-  // canvas-dir index has no entry for the id (see `canvasDirName` in
-  // `storage/backends/disk/canvas-dirs.ts`). We just need the directory to
-  // exist so
-  // writes can land in it.
-  mkdirSync(join(tmp, canvasId), { recursive: true });
+  // A real Space, not just a directory: the memory body is a blob under the
+  // Space's own scope now, and blobs may only be written for a Space whose
+  // record exists.
+  const created = await createSpace(canvasId, canvasId);
+  if (!created.ok) throw new Error('Expected to create the Space');
 });
 
 afterEach(() => {
@@ -172,8 +172,9 @@ describe('handleFsWrite — overwrite', () => {
       } as never),
     );
     expect(r.ok).toBe(true);
-    expect(r.target).toBe(canvasMemoryPath(canvasId));
-    expect(readFileSync(canvasMemoryPath(canvasId), 'utf8')).toBe(
+    // The agent sees back the path it asked for, not wherever the bytes sit.
+    expect(r.target).toBe('memory/space.md');
+    expect(readFileSync(memoryBlobFile(canvasId), 'utf8')).toBe(
       'canvas briefing\n',
     );
   });
diff --git a/apps/server/src/modules/agent/tools/handlers/fs-write.ts b/apps/server/src/modules/agent/tools/handlers/fs-write.ts
index 501d8527a..da6c039ff 100644
--- a/apps/server/src/modules/agent/tools/handlers/fs-write.ts
+++ b/apps/server/src/modules/agent/tools/handlers/fs-write.ts
@@ -32,20 +32,19 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { normalizeRel } from './fs-sandbox.js';
-import {
-  canvasMemoryDir,
-  settingDir,
-  userSkillsDir,
-} from '../../../workspace/paths.js';
+import { space, SPACE_MEMORY_BLOB_NAME } from '../../../storage/index.js';
+import { settingDir, userSkillsDir } from '../../../workspace/paths.js';
 import {
   resolveLongTermPath,
   resolveUserSkillPath,
-  resolveWorkingMemoryPath,
 } from '../../memory/sandbox.js';
 import {
+  blobDocument,
+  fileDocument,
   overwriteMemoryFile,
   replaceStringInMemoryFile,
   SKILL_CREATE_RATIONALE_MIN,
+  type MemoryDocument,
   type MemoryTier,
   type WriteResult,
 } from '../../memory/writers.js';
@@ -79,7 +78,7 @@ export async function handleFsWrite(args: FsWriteArgs): Promise<string> {
   // future literal added to the schema produces a clear runtime error
   // until the dispatcher is updated.
   return reject(
-    target.absPath,
+    target.document.target,
     `unknown mode: ${(args as { mode?: string }).mode ?? '(missing)'}`,
   );
 }
@@ -88,9 +87,16 @@ export async function handleFsWrite(args: FsWriteArgs): Promise<string> {
 
 interface ResolvedTarget {
   tier: MemoryTier;
-  absPath: string;
-  parentDir: string;
+  /** Where the bytes live — a file for the Workspace tiers, a blob for a
+   * Space's memory body. */
+  document: MemoryDocument;
   skillId?: string;
+  /**
+   * Skill tier only. The create-rationale rule asks whether the file exists
+   * yet and where its parent is, which are questions about a real path — and
+   * user skills are Workspace-scoped, so they have one.
+   */
+  skillPaths?: { absPath: string; parentDir: string };
   /** The normalised relative path, for error messages. */
   path: string;
 }
@@ -106,8 +112,7 @@ function resolveTarget(
   if (rel === 'memory/user.md') {
     return {
       tier: 'workspace',
-      absPath: resolveLongTermPath(),
-      parentDir: settingDir(),
+      document: fileDocument(resolveLongTermPath(), settingDir()),
       path: rel,
     };
   }
@@ -122,8 +127,15 @@ function resolveTarget(
     }
     return {
       tier: 'canvas',
-      absPath: resolveWorkingMemoryPath(args.canvasId),
-      parentDir: canvasMemoryDir(args.canvasId),
+      // A blob under the Space's own memory scope (proposal §6.4.3,
+      // disposition D). The agent still sees the path it asked for; the
+      // sandbox resolver this used to need is gone, and so is the ad-hoc
+      // write against a directory it assembled.
+      document: blobDocument(
+        space(args.canvasId).memory,
+        SPACE_MEMORY_BLOB_NAME,
+        rel,
+      ),
       path: rel,
     };
   }
@@ -144,10 +156,11 @@ function resolveTarget(
     const skillId = segs[1];
     try {
       const absPath = resolveUserSkillPath(skillId);
+      const parentDir = path.dirname(absPath);
       return {
         tier: 'skill',
-        absPath,
-        parentDir: path.dirname(absPath),
+        document: fileDocument(absPath, parentDir),
+        skillPaths: { absPath, parentDir },
         skillId,
         path: rel,
       };
@@ -169,7 +182,7 @@ async function handleOverwrite(
   target: ResolvedTarget,
 ): Promise<string> {
   if (typeof args.body !== 'string') {
-    return reject(target.absPath, 'mode="overwrite" requires "body"');
+    return reject(target.document.target, 'mode="overwrite" requires "body"');
   }
 
   // Skill create rule: when the target file does not yet exist on a
@@ -178,11 +191,15 @@ async function handleOverwrite(
   // hard-require a rationale (≥ N chars) here so the LLM cannot
   // sneak a new skill in without justifying why an existing one
   // could not be edited.
-  if (target.tier === 'skill' && !existsSync(target.absPath)) {
+  if (
+    target.tier === 'skill' &&
+    target.skillPaths &&
+    !existsSync(target.skillPaths.absPath)
+  ) {
     const r = (args.rationale ?? '').trim();
     if (r.length < SKILL_CREATE_RATIONALE_MIN) {
       return reject(
-        target.absPath,
+        target.document.target,
         `skill create rejected: provide a "rationale" (>= ${SKILL_CREATE_RATIONALE_MIN} chars) explaining why no existing skill can be updated`,
       );
     }
@@ -190,9 +207,9 @@ async function handleOverwrite(
     // exists even before the writer's mkdirp runs, so a malformed
     // resolveUserSkillPath result surfaces as a clear error here
     // rather than mid-write.
-    if (!target.parentDir.startsWith(userSkillsDir())) {
+    if (!target.skillPaths.parentDir.startsWith(userSkillsDir())) {
       return reject(
-        target.absPath,
+        target.document.target,
         'skill target escapes the user skills sandbox',
       );
     }
@@ -200,8 +217,7 @@ async function handleOverwrite(
 
   const result = await overwriteMemoryFile({
     tier: target.tier,
-    absPath: target.absPath,
-    parentDir: target.parentDir,
+    document: target.document,
     skillId: target.skillId,
     body: args.body,
   });
@@ -213,15 +229,20 @@ async function handleReplaceString(
   target: ResolvedTarget,
 ): Promise<string> {
   if (typeof args.oldString !== 'string') {
-    return reject(target.absPath, 'mode="replace_string" requires "oldString"');
+    return reject(
+      target.document.target,
+      'mode="replace_string" requires "oldString"',
+    );
   }
   if (typeof args.newString !== 'string') {
-    return reject(target.absPath, 'mode="replace_string" requires "newString"');
+    return reject(
+      target.document.target,
+      'mode="replace_string" requires "newString"',
+    );
   }
   const result = await replaceStringInMemoryFile({
     tier: target.tier,
-    absPath: target.absPath,
-    parentDir: target.parentDir,
+    document: target.document,
     skillId: target.skillId,
     oldString: args.oldString,
     newString: args.newString,
diff --git a/apps/server/src/modules/remote_fs/rfs.route.ts b/apps/server/src/modules/remote_fs/rfs.route.ts
index 8e2293891..d72d38465 100644
--- a/apps/server/src/modules/remote_fs/rfs.route.ts
+++ b/apps/server/src/modules/remote_fs/rfs.route.ts
@@ -270,7 +270,7 @@ const rfsRoutes: FastifyPluginAsync = async (app) => {
       const { canvasId } = request.params;
       try {
         const guide = request.headers.authorization
-          ? resolveCanvasSkill(canvasId)
+          ? await resolveCanvasSkill(canvasId)
           : resolveBundledRootSkill();
         return reply
           .header('Content-Type', 'text/markdown; charset=utf-8')
diff --git a/apps/server/src/modules/remote_fs/skill.ts b/apps/server/src/modules/remote_fs/skill.ts
index 213dd690a..7de40554a 100644
--- a/apps/server/src/modules/remote_fs/skill.ts
+++ b/apps/server/src/modules/remote_fs/skill.ts
@@ -11,11 +11,8 @@
  * there is no pushed copy to drift from (see the proposal §6c).
  */
 
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-
 import { renderPromptFile } from '../../prompt/agents/loader.js';
-import { space } from '../storage/index.js';
+import { space, SPACE_GUIDE_SKILL_NAME } from '../storage/index.js';
 
 /** PROMPT-ROOT-relative path of the bundled access guide. */
 const ACCESS_GUIDE_TEMPLATE = 'external-agent/access-huabu.md';
@@ -39,19 +36,15 @@ export function resolveBundledRootSkill(): string {
  * override when it exists, otherwise the bundled default. Returned as raw
  * markdown text (served with `Content-Type: text/markdown`).
  */
-export function resolveCanvasSkill(canvasId: string): string {
-  // A user-authored override read from the Space root. Disposition D
-  // (proposal §6.4.3): it becomes a blob under its own scope kind, at which
-  // point this reads through the port and the branch goes away. Until then a
-  // backend without a directory simply has no override to find.
-  const tree = space(canvasId).diskTree;
-  if (tree) {
-    const override = path.join(tree.directory(), 'skill.md');
-    if (existsSync(override)) {
-      return readFileSync(override, 'utf8');
-    }
-  }
-  return resolveBundledRootSkill();
+export async function resolveCanvasSkill(canvasId: string): Promise<string> {
+  // A user-authored override, read as a blob under the Space's guide scope
+  // (proposal §6.4.3, disposition D). The scope is the Space root bounded to
+  // the guide names, so the file a user authors is exactly where they left it
+  // and this no longer assembles a path.
+  const override = await space(canvasId).guide.read(SPACE_GUIDE_SKILL_NAME);
+  return override === null
+    ? resolveBundledRootSkill()
+    : override.toString('utf8');
 }
 
 /** Resolve one fixed, authenticated advanced guide. */
diff --git a/apps/server/src/modules/storage/backends/disk/blob-store.rename-retry.test.ts b/apps/server/src/modules/storage/backends/disk/blob-store.rename-retry.test.ts
index 1d5fbefa3..23cb013ee 100644
--- a/apps/server/src/modules/storage/backends/disk/blob-store.rename-retry.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/blob-store.rename-retry.test.ts
@@ -39,7 +39,7 @@ describe('DiskBlobStore retry cleanup', () => {
 
     try {
       const scope = new DiskBlobStore().scope({
-        kind: 'canvas',
+        kind: 'space-artifacts',
         canvasId: 'canvas-under-test',
       });
 
diff --git a/apps/server/src/modules/storage/backends/disk/blob-store.test.ts b/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
index 7d287192f..fdc8fb497 100644
--- a/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
@@ -28,7 +28,7 @@ describeBlobStoreContract('DiskBlobStore', () => {
   workspaceState.path = root;
   return {
     store: new DiskBlobStore(),
-    ref: { kind: 'canvas', canvasId: 'canvas-under-test' },
+    ref: { kind: 'space-artifacts', canvasId: 'canvas-under-test' },
     cleanup: () => rmSync(root, { recursive: true, force: true }),
   };
 });
@@ -54,7 +54,10 @@ describe('DiskBlobStore temp file hygiene', () => {
   });
 
   it('cleans up after both successful and failed writes', async () => {
-    const scope = new DiskBlobStore().scope({ kind: 'canvas', canvasId });
+    const scope = new DiskBlobStore().scope({
+      kind: 'space-artifacts',
+      canvasId,
+    });
 
     await scope.put('kept.bin', Buffer.from('fine'));
     await scope.put('streamed.bin', Readable.from([Buffer.from('also fine')]));
@@ -78,7 +81,7 @@ describe('DiskBlobStore temp file hygiene', () => {
 
   it('cleans up siblings from concurrent writers to one key', async () => {
     const scope = new DiskBlobStore().scope({
-      kind: 'canvas',
+      kind: 'space-artifacts',
       canvasId: 'concurrent-canvas',
     });
 
@@ -95,7 +98,10 @@ describe('DiskBlobStore temp file hygiene', () => {
 
   it('binds in-flight paths to their original workspace and rejects a held scope after activation', async () => {
     const otherRoot = mkdtempSync(path.join(tmpdir(), 'huabu-blob-switched-'));
-    const scope = new DiskBlobStore().scope({ kind: 'canvas', canvasId });
+    const scope = new DiskBlobStore().scope({
+      kind: 'space-artifacts',
+      canvasId,
+    });
     let signalStarted = (): void => {};
     const started = new Promise<void>((resolve) => {
       signalStarted = resolve;
diff --git a/apps/server/src/modules/storage/backends/disk/blob-store.ts b/apps/server/src/modules/storage/backends/disk/blob-store.ts
index 88dd8eb6d..0a45f0516 100644
--- a/apps/server/src/modules/storage/backends/disk/blob-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/blob-store.ts
@@ -26,10 +26,20 @@ import {
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 
-import { artifactsDir } from './layout.js';
+import {
+  artifactsDir,
+  canvasRoot,
+  spaceMemoryDir,
+  spaceUploadDir,
+} from './layout.js';
 import { renameOverWithRetry } from '../../../../utils/fs.js';
 import { getWorkspacePath } from '../../../workspace.js';
-import { createBlobLease, normalizeBlobName } from '../../ports/blob.js';
+import {
+  BlobNameError,
+  createBlobLease,
+  normalizeBlobName,
+  SPACE_GUIDE_BLOB_NAMES,
+} from '../../ports/blob.js';
 
 import type {
   BlobInfo,
@@ -57,8 +67,34 @@ function isTempEntry(entry: string): boolean {
 }
 
 /** Resolve a scope to its backing directory. */
-function scopeDir(ref: BlobScopeRef): string {
-  return artifactsDir(ref.canvasId);
+/**
+ * Where one scope's bytes sit, and which names it owns there.
+ *
+ * `members: null` means the directory *is* the scope — everything in it
+ * belongs. A name list means the scope is bounded by its members instead, for
+ * an area shared with files that are not blobs at all.
+ */
+interface ScopePlacement {
+  readonly directory: string;
+  readonly members: readonly string[] | null;
+}
+
+function scopePlacement(ref: BlobScopeRef): ScopePlacement {
+  switch (ref.kind) {
+    case 'space-artifacts':
+      return { directory: artifactsDir(ref.canvasId), members: null };
+    case 'space-memory':
+      return { directory: spaceMemoryDir(ref.canvasId), members: null };
+    case 'space-upload':
+      return { directory: spaceUploadDir(ref.canvasId), members: null };
+    case 'space-guide':
+      // The Space root, which also holds `space.json` and every node
+      // directory — so this scope is the guide names, not the folder.
+      return {
+        directory: canvasRoot(ref.canvasId),
+        members: SPACE_GUIDE_BLOB_NAMES,
+      };
+  }
 }
 
 /** Resolve one blob beneath an already-bound scope directory. */
@@ -80,7 +116,7 @@ class DiskBlobScope implements BlobScope {
     this.#workspacePath = path.resolve(getWorkspacePath());
   }
 
-  #resolveDir(): string {
+  #placement(): ScopePlacement {
     const active = path.resolve(getWorkspacePath());
     if (active !== this.#workspacePath) {
       throw new Error(
@@ -91,7 +127,41 @@ class DiskBlobScope implements BlobScope {
     // Resolve once per operation, before its first await. Every later path in
     // that operation is derived from this absolute directory, so a workspace
     // switch cannot combine a temp in A with a destination in B.
-    return scopeDir(this.#ref);
+    return scopePlacement(this.#ref);
+  }
+
+  /** Names this scope owns in `dir`, given what is actually there. */
+  async #entries(placement: ScopePlacement): Promise<string[]> {
+    if (placement.members) {
+      // A member-bounded scope never reads the directory: everything else in
+      // it belongs to someone else, and listing it would claim otherwise.
+      const present = await Promise.all(
+        placement.members.map(async (name) =>
+          (await this.#headAt(placement.directory, name)) ? name : null,
+        ),
+      );
+      return present.filter((name): name is string => name !== null);
+    }
+    try {
+      return (await readdir(placement.directory)).filter(
+        (entry) => !isTempEntry(entry),
+      );
+    } catch (err) {
+      if (isMissing(err)) return [];
+      throw err;
+    }
+  }
+
+  /** Refuse a name this scope does not own, before it reaches the filesystem. */
+  #assertMember(placement: ScopePlacement, name: string): string {
+    const safe = normalizeBlobName(name);
+    if (placement.members && !placement.members.includes(safe)) {
+      throw new BlobNameError(
+        `"${safe}" is not a member of the ${this.#ref.kind} scope. ` +
+          `It holds: ${placement.members.join(', ')}.`,
+      );
+    }
+    return safe;
   }
 
   async #headAt(dir: string, name: string): Promise<BlobInfo | null> {
@@ -122,8 +192,9 @@ class DiskBlobScope implements BlobScope {
    * no per-key delete to clean up.
    */
   async put(name: string, body: Readable | Buffer): Promise<BlobInfo> {
-    const safe = normalizeBlobName(name);
-    const dir = this.#resolveDir();
+    const placement = this.#placement();
+    const safe = this.#assertMember(placement, name);
+    const dir = placement.directory;
     await mkdir(dir, { recursive: true });
 
     const full = blobPath(dir, safe);
@@ -152,12 +223,17 @@ class DiskBlobScope implements BlobScope {
   }
 
   async head(name: string): Promise<BlobInfo | null> {
-    return this.#headAt(this.#resolveDir(), name);
+    const placement = this.#placement();
+    return this.#headAt(
+      placement.directory,
+      this.#assertMember(placement, name),
+    );
   }
 
   async open(name: string, range?: BlobRange): Promise<BlobRead | null> {
-    const dir = this.#resolveDir();
-    const info = await this.#headAt(dir, name);
+    const placement = this.#placement();
+    const dir = placement.directory;
+    const info = await this.#headAt(dir, this.#assertMember(placement, name));
     if (!info) return null;
     // `info.size` stays the full blob size; the range only bounds the body.
     const body = createReadStream(blobPath(dir, info.name), {
@@ -168,9 +244,10 @@ class DiskBlobScope implements BlobScope {
   }
 
   async read(name: string): Promise<Buffer | null> {
-    const dir = this.#resolveDir();
+    const placement = this.#placement();
+    const safe = this.#assertMember(placement, name);
     try {
-      return await readFile(blobPath(dir, name));
+      return await readFile(blobPath(placement.directory, safe));
     } catch (err) {
       if (isMissing(err)) return null;
       throw err;
@@ -178,48 +255,32 @@ class DiskBlobScope implements BlobScope {
   }
 
   async hasMany(names: readonly string[]): Promise<ReadonlySet<string>> {
-    const dir = this.#resolveDir();
+    const placement = this.#placement();
     const requested = new Set(names.map(normalizeBlobName));
     if (requested.size === 0) return new Set();
 
-    let entries: string[];
-    try {
-      entries = await readdir(dir);
-    } catch (err) {
-      if (isMissing(err)) return new Set();
-      throw err;
-    }
-
-    const candidates = entries.filter(
-      (entry) => !isTempEntry(entry) && requested.has(entry),
+    const entries = (await this.#entries(placement)).filter((entry) =>
+      requested.has(entry),
     );
     const infos = await Promise.all(
-      candidates.map((entry) => this.#headAt(dir, entry)),
+      entries.map((entry) => this.#headAt(placement.directory, entry)),
     );
     return new Set(infos.flatMap((info) => (info === null ? [] : [info.name])));
   }
 
   async list(): Promise<BlobInfo[]> {
-    const dir = this.#resolveDir();
-    let entries: string[];
-    try {
-      entries = await readdir(dir);
-    } catch (err) {
-      if (isMissing(err)) return [];
-      throw err;
-    }
-
+    const placement = this.#placement();
+    const entries = await this.#entries(placement);
     const infos = await Promise.all(
-      entries
-        .filter((entry) => !isTempEntry(entry))
-        .map((entry) => this.#headAt(dir, entry)),
+      entries.map((entry) => this.#headAt(placement.directory, entry)),
     );
     return infos.filter((info): info is BlobInfo => info !== null);
   }
 
   async materialize(name: string): Promise<BlobLease | null> {
-    const dir = this.#resolveDir();
-    const info = await this.#headAt(dir, name);
+    const placement = this.#placement();
+    const dir = placement.directory;
+    const info = await this.#headAt(dir, this.#assertMember(placement, name));
     if (!info) return null;
     // Disk already *is* a filesystem: hand back the real path and make
     // release a no-op. No copy, so this costs nothing today. The lease
@@ -229,7 +290,18 @@ class DiskBlobScope implements BlobScope {
   }
 
   async deleteAll(): Promise<void> {
-    await rm(this.#resolveDir(), { recursive: true, force: true });
+    const placement = this.#placement();
+    if (!placement.members) {
+      await rm(placement.directory, { recursive: true, force: true });
+      return;
+    }
+    // Removing the directory would take the Space with it. Only the members
+    // are this scope's to delete.
+    await Promise.all(
+      placement.members.map((name) =>
+        rm(blobPath(placement.directory, name), { force: true }),
+      ),
+    );
   }
 }
 
diff --git a/apps/server/src/modules/storage/backends/disk/layout.ts b/apps/server/src/modules/storage/backends/disk/layout.ts
index fe2a400ac..500dd658f 100644
--- a/apps/server/src/modules/storage/backends/disk/layout.ts
+++ b/apps/server/src/modules/storage/backends/disk/layout.ts
@@ -80,6 +80,26 @@ export function artifactsDir(canvasId: string): string {
   return path.join(canvasRoot(canvasId), ARTIFACTS_DIR_NAME);
 }
 
+/**
+ * Hidden directory holding the agent's private memory document.
+ *
+ * Named here rather than in the workspace module because it is now a blob
+ * scope's placement — where Disk puts the bytes of one user-visible area —
+ * and every other such placement already lives beside this one.
+ */
+export const MEMORY_DIR_NAME = '.memory';
+
+export function spaceMemoryDir(canvasId: string): string {
+  return path.join(canvasRoot(canvasId), MEMORY_DIR_NAME);
+}
+
+/** Hidden scratch an upload lands in before anything claims it. */
+export const UPLOAD_DIR_NAME = '.upload';
+
+export function spaceUploadDir(canvasId: string): string {
+  return path.join(canvasRoot(canvasId), UPLOAD_DIR_NAME);
+}
+
 export function artifactPath(canvasId: string, filename: string): string {
   const base = path.basename(filename);
   if (!base || base === '.' || base === '..') {
diff --git a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
index 1120ffae5..93f893999 100644
--- a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
+++ b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
@@ -20,6 +20,7 @@ import { artifactPath, canvasJsonPath } from '../backends/disk/layout.js';
 import { resetStorageCache } from '../backends/disk/legacy/canvas-store-cache.js';
 import { DiskStructuredStore } from '../backends/disk/structured-store.js';
 import { getCanvasStore } from '../index.js';
+import { spaceBlobScopes } from '../ports/blob.js';
 import {
   composeStorage,
   space,
@@ -245,7 +246,12 @@ describe('deleteSpace composition', () => {
 
     // Blobs first: after the structured record is gone nothing names them,
     // so a failed sweep on a remote backend would strand them permanently.
-    expect(blobs.recordPresentAtSweep).toEqual([true]);
+    // One sweep per user-visible area — a Space's bytes are spread across a
+    // scope each, and an unswept kind is an orphan on a backend where
+    // dropping the record does not remove the area they sit in.
+    expect(blobs.recordPresentAtSweep).toEqual(
+      spaceBlobScopes('canvas-a').map(() => true),
+    );
     expect(existsSync(artifactPath('canvas-a', 'art_1.png'))).toBe(false);
     expect(existsSync(canvasJsonPath('canvas-a'))).toBe(false);
   });
@@ -342,7 +348,7 @@ describe('deleteSpace composition', () => {
     await putting;
     await expect(deleting).resolves.toEqual({ ok: true, reason: 'deleted' });
 
-    expect(controlled.deleteCalls).toBe(1);
+    expect(controlled.deleteCalls).toBe(spaceBlobScopes('canvas-a').length);
     expect(existsSync(canvasJsonPath('canvas-a'))).toBe(false);
     expect(existsSync(artifactPath('canvas-a', 'in-flight.bin'))).toBe(false);
   });
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index bc82ec6d7..6601bdd56 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -94,7 +94,14 @@ export {
   assertValidNamespace,
   SpaceNamespaceError,
 } from './ports/namespace.js';
-export { BlobNameError, normalizeBlobName } from './ports/blob.js';
+export {
+  BlobNameError,
+  normalizeBlobName,
+  SPACE_GUIDE_BLOB_NAMES,
+  SPACE_GUIDE_SKILL_NAME,
+  SPACE_MEMORY_BLOB_NAME,
+  spaceBlobScopes,
+} from './ports/blob.js';
 export type {
   BlobBackendKind,
   BlobInfo,
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index a9a1784be..21b66502b 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -306,11 +306,10 @@ describe('Disk Space tree capability', () => {
     // B, deferred — RFS's sidecar-to-record mapping. Portable in principle,
     // Disk's in practice until a second backend has a file plane at all.
     'modules/remote_fs/node-meta.ts',
-    // D — the per-Space RFS access guide, headed for a blob.
-    'modules/remote_fs/skill.ts',
-    // D and C — the memory body, and ACP session state until phase 6. The
-    // memory bookkeeping and the debug prompt log have already left, onto the
-    // extension substrate.
+    // C — ACP session state, which leaves with phase 6's `Namespace` change.
+    // Everything else this module addressed has already left: the memory
+    // bookkeeping and debug prompt log onto the extension substrate, the
+    // memory body and the RFS access guide into blob scopes.
     'modules/workspace/paths.ts',
   ].sort();
 
diff --git a/apps/server/src/modules/storage/ports/blob.ts b/apps/server/src/modules/storage/ports/blob.ts
index c710d0f05..14f2d6a0c 100644
--- a/apps/server/src/modules/storage/ports/blob.ts
+++ b/apps/server/src/modules/storage/ports/blob.ts
@@ -26,10 +26,70 @@ export type BlobBackendKind = 'disk' | 'azure';
 /**
  * Identifies a bounded namespace of blobs within a connection.
  *
- * A one-member union today. Adding a scope kind (workspace assets, agent
- * scratch) extends this type; the connection interface is unaffected.
+ * One kind per **user-visible area**, not one per Space. That distinction is
+ * what keeps names flat: a Space's bytes live in several places a user can
+ * tell apart — the artifacts the app writes, the guide they author, the memory
+ * the agent keeps, the scratch an upload lands in — and the alternative to
+ * naming those areas is hierarchical blob names, which §7.1 excluded for every
+ * backend. A kind is a union member and one placement rule per adapter; a path
+ * separator inside a name is a contract change.
+ *
+ * It also lets retention diverge later — scratch is not an artifact — without
+ * moving any bytes a second time.
+ *
+ * Adding a scope with no Space (workspace assets, agent scratch) extends this
+ * type the same way; the connection interface is unaffected.
+ */
+export type BlobScopeRef =
+  /** Artifacts the application writes and the client fetches by key. */
+  | { kind: 'space-artifacts'; canvasId: string }
+  /**
+   * User-authored guide documents at the Space root.
+   *
+   * Bounded by {@link SPACE_GUIDE_BLOB_NAMES} rather than by a directory,
+   * because the area a user authors in *is* the Space root — which also holds
+   * storage's own record. A scope that claimed the whole directory would list
+   * `space.json` and delete the Space on `deleteAll()`. Naming the members is
+   * what makes the boundary real, and a fixed set is a tighter namespace than
+   * a directory, not a looser one.
+   */
+  | { kind: 'space-guide'; canvasId: string }
+  /** The agent's private memory document for a Space. */
+  | { kind: 'space-memory'; canvasId: string }
+  /** Scratch an upload lands in before anything claims it. */
+  | { kind: 'space-upload'; canvasId: string };
+
+/**
+ * Every blob name the `space-guide` scope may hold.
+ *
+ * Product vocabulary rather than adapter detail: these are the documents a
+ * user is invited to author at the Space root, so the set belongs beside the
+ * scope it defines.
+ */
+export const SPACE_GUIDE_SKILL_NAME = 'skill.md';
+
+export const SPACE_GUIDE_BLOB_NAMES: readonly string[] = [
+  SPACE_GUIDE_SKILL_NAME,
+];
+
+/** The one blob in the `space-memory` scope: the agent's memory document. */
+export const SPACE_MEMORY_BLOB_NAME = 'space.md';
+
+/**
+ * Every scope holding bytes for one Space.
+ *
+ * Deletion has to sweep all of them, and a kind added without being swept
+ * would orphan bytes on a backend where dropping the Space does not remove
+ * the area they sit in. Derived here so the saga cannot fall behind the union.
  */
-export type BlobScopeRef = { kind: 'canvas'; canvasId: string };
+export function spaceBlobScopes(canvasId: string): readonly BlobScopeRef[] {
+  return [
+    { kind: 'space-artifacts', canvasId },
+    { kind: 'space-guide', canvasId },
+    { kind: 'space-memory', canvasId },
+    { kind: 'space-upload', canvasId },
+  ];
+}
 
 export interface BlobInfo {
   /** Scope-relative name, e.g. `artifact_abc123.png`. */
diff --git a/apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts b/apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts
index 9623fcd8f..2b40a5922 100644
--- a/apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts
+++ b/apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts
@@ -24,7 +24,11 @@ import { Readable } from 'node:stream';
 
 import { afterEach, describe, expect, it } from 'vitest';
 
-import { BlobLeaseError, BlobNameError } from '../blob.js';
+import {
+  BlobLeaseError,
+  BlobNameError,
+  SPACE_GUIDE_SKILL_NAME,
+} from '../blob.js';
 
 import type { BlobScope, BlobScopeRef, BlobStore } from '../blob.js';
 
@@ -67,6 +71,59 @@ export function describeBlobStoreContract(
       harness = null;
     });
 
+    /**
+     * A member-bounded scope is a real scope, not a filtered view of a
+     * directory. Disk maps `space-guide` onto the Space root — shared with
+     * `space.json` and every node directory — so a scope that answered for
+     * the folder would list storage's own records and take the Space with it
+     * on `deleteAll()`. These pin the boundary that makes the mapping safe.
+     */
+    it('answers only for the names a bounded scope owns', async () => {
+      const h = await createHarness();
+      harness = h;
+      await h.store.init();
+      const guide = h.store.scope({
+        kind: 'space-guide',
+        canvasId: h.ref.canvasId,
+      });
+
+      await guide.put(SPACE_GUIDE_SKILL_NAME, Buffer.from('# guide'));
+      expect(await guide.read(SPACE_GUIDE_SKILL_NAME)).toEqual(
+        Buffer.from('# guide'),
+      );
+      expect((await guide.list()).map((info) => info.name)).toEqual([
+        SPACE_GUIDE_SKILL_NAME,
+      ]);
+
+      // A name outside the scope is refused before it reaches the backend,
+      // rather than resolving to whatever sits next to the members.
+      await expect(guide.read('space.json')).rejects.toThrow();
+      await expect(guide.head('space.json')).rejects.toThrow();
+      await expect(
+        guide.put('space.json', Buffer.from('{}')),
+      ).rejects.toThrow();
+    });
+
+    it('deletes only its members when a scope is bounded by name', async () => {
+      const h = await createHarness();
+      harness = h;
+      await h.store.init();
+      const artifacts = h.store.scope(h.ref);
+      const guide = h.store.scope({
+        kind: 'space-guide',
+        canvasId: h.ref.canvasId,
+      });
+      await artifacts.put('kept.bin', Buffer.from('artifact'));
+      await guide.put(SPACE_GUIDE_SKILL_NAME, Buffer.from('# guide'));
+
+      await guide.deleteAll();
+
+      expect(await guide.read(SPACE_GUIDE_SKILL_NAME)).toBeNull();
+      // The neighbours are not this scope's to remove — on Disk they are the
+      // Space itself.
+      expect(await artifacts.read('kept.bin')).toEqual(Buffer.from('artifact'));
+    });
+
     it('reports its backend kind and health', async () => {
       const s = await createHarness();
       harness = s;
@@ -332,7 +389,10 @@ export function describeBlobStoreContract(
       await s.store.init();
 
       const a = s.store.scope(s.ref);
-      const b = s.store.scope({ kind: 'canvas', canvasId: 'other-canvas-id' });
+      const b = s.store.scope({
+        kind: 'space-artifacts',
+        canvasId: 'other-canvas-id',
+      });
 
       await a.put('shared-name.txt', Buffer.from('from a'));
       expect(await b.head('shared-name.txt')).toBeNull();
diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts
index c8e208774..29fdcf966 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -34,6 +34,7 @@ import {
 import { DiskBlobStore } from './backends/disk/blob-store.js';
 import { diskSpaceTree } from './backends/disk/space-tree.js';
 import { DiskStructuredStore } from './backends/disk/structured-store.js';
+import { spaceBlobScopes } from './ports/blob.js';
 import {
   parseStorageProfile,
   requiresExplicitInit,
@@ -50,6 +51,7 @@ import type {
   BlobRange,
   BlobRead,
   BlobScope,
+  BlobScopeRef,
   BlobStore,
 } from './ports/blob.js';
 import type { StorageHealth } from './ports/common.js';
@@ -143,12 +145,23 @@ export interface Storage {
  */
 export interface Space extends SpaceHandle {
   /**
-   * This Space's blobs, with the cross-store precondition applied.
+   * This Space's artifacts, with the cross-store precondition applied.
    *
    * Bytes may only be added to a Space whose record exists. Reads and
    * `deleteAll()` stay available for cleanup when a record has already gone.
+   *
+   * The unqualified name because artifacts are what almost every caller
+   * means. The other areas below are the same guarded scope over a different
+   * {@link BlobScopeRef} kind — one member each, so a caller reaches every
+   * area of a Space from the one handle rather than assembling a scope ref.
    */
   readonly blobs: BlobScope;
+  /** User-authored guide documents at the Space root (`skill.md`). */
+  readonly guide: BlobScope;
+  /** The agent's private memory document. */
+  readonly memory: BlobScope;
+  /** Scratch an upload lands in before anything claims it. */
+  readonly uploads: BlobScope;
   /**
    * Disk's directory for this Space. `null` on every other backend.
    *
@@ -172,7 +185,10 @@ function composeSpace(storage: Storage, canvasId: string): Space {
     tasks: handle.tasks,
     events: handle.events,
     extension: (namespace) => handle.extension(namespace),
-    blobs: guardedBlobScope(storage, canvasId),
+    blobs: guardedBlobScope(storage, { kind: 'space-artifacts', canvasId }),
+    guide: guardedBlobScope(storage, { kind: 'space-guide', canvasId }),
+    memory: guardedBlobScope(storage, { kind: 'space-memory', canvasId }),
+    uploads: guardedBlobScope(storage, { kind: 'space-upload', canvasId }),
     diskTree:
       storage.profile.structured.kind === 'disk'
         ? diskSpaceTree(canvasId)
@@ -504,7 +520,15 @@ export async function deleteSpace(
     try {
       // Preserve the old retryable cleanup behavior: sweep even when the
       // structured record is already absent, so orphan blobs can be removed.
-      await storage.blobs.scope({ kind: 'canvas', canvasId }).deleteAll();
+      // Every area, not just artifacts: a Space's bytes are spread across one
+      // scope per user-visible area, and on a backend where dropping the
+      // structured record does not remove the area they sit in, an unswept
+      // kind is an orphan.
+      await Promise.all(
+        spaceBlobScopes(canvasId).map((ref) =>
+          storage.blobs.scope(ref).deleteAll(),
+        ),
+      );
       return await started.session.finish();
     } catch (error) {
       await started.session.abort();
@@ -527,9 +551,10 @@ export async function deleteSpace(
  * one Space facade is composed entirely from the connections it was built
  * against — a scope that re-resolved the holder could outlive them.
  */
-function guardedBlobScope(storage: Storage, canvasId: string): BlobScope {
+function guardedBlobScope(storage: Storage, ref: BlobScopeRef): BlobScope {
+  const { canvasId } = ref;
   const workspacePath = activeWorkspacePath();
-  const delegate = storage.blobs.scope({ kind: 'canvas', canvasId });
+  const delegate = storage.blobs.scope(ref);
 
   async function requireSpace(): Promise<void> {
     const record = await storage.structured.space(canvasId).read();
diff --git a/apps/server/src/modules/workspace/paths.ts b/apps/server/src/modules/workspace/paths.ts
index 64e4e08a9..5071f68f0 100644
--- a/apps/server/src/modules/workspace/paths.ts
+++ b/apps/server/src/modules/workspace/paths.ts
@@ -89,18 +89,6 @@ export function workspaceMemoryPath(): string {
   return path.join(settingDir(), 'user.md');
 }
 
-/** Hidden directory holding canvas-scoped canvas memory + bookkeeping. */
-export const WORKING_MEMORY_DIR_NAME = '.memory';
-
-export function canvasMemoryDir(canvasId: string): string {
-  return path.join(spaceRoot(canvasId), WORKING_MEMORY_DIR_NAME);
-}
-
-/** Working memory body for a canvas. */
-export function canvasMemoryPath(canvasId: string): string {
-  return path.join(canvasMemoryDir(canvasId), 'space.md');
-}
-
 // ─── Workspace-level setting / user skills ─────────────────────────────────
 
 /**

From e23964d7fa6968d4d2316955ec027487a1149cfc Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 13:00:59 +0800
Subject: [PATCH 11/20] feat(storage): declare what a profile cannot do, not
 just what it cannot be
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six features are about a filesystem rather than about storage: revealing a
Space in Finder, adopting a document dropped in from outside, a bundle that
is a directory zipped up, the built-in file tools, and the Windows handle
dance that lets a watched directory be renamed. A backend keeping Spaces in
tables has no honest answer for any of them.

Until now that was only knowable by reading the code, or by clicking the
button. An outcome of "unavailable" is an acceptable product limitation
rather than debt — but only if an operator can learn it when they select a
profile, so the matrix sits beside profile validation and is reported at
startup.

Reported, not raised. A profile that offers fewer features is a stated
limitation; a profile naming a backend with no adapter is a
misconfiguration and still fails fast. Conflating the two would either
refuse a legitimate deployment or let a real misconfiguration through as a
warning.

The matrix is an exception list, not an inventory. Listing the portable
features too would mean editing it whenever anything was built, and it would
go stale silently — so an id nobody wrote down is available by construction,
and adding a portable feature is not a matrix edit.

Each listed feature still refuses at its own call site, because a matrix
nobody consults at runtime is documentation. Those refusals now share the
matrix's wording, so the sentence an operator read when they chose the
profile is the sentence they see in the failure.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../agent/tools/handlers/fs-sandbox.ts        |  18 +-
 .../server/src/modules/canvas/canvas.route.ts |   6 +-
 .../src/modules/canvas/external.route.ts      |   4 +-
 .../src/modules/storage/capabilities.test.ts  |  99 +++++++++++
 .../src/modules/storage/capabilities.ts       | 167 ++++++++++++++++++
 apps/server/src/modules/storage/index.ts      |   8 +
 .../modules/storage/module-boundaries.test.ts |   2 +
 apps/server/src/modules/storage/profile.ts    |   7 +
 apps/server/src/server.ts                     |  17 +-
 9 files changed, 309 insertions(+), 19 deletions(-)
 create mode 100644 apps/server/src/modules/storage/capabilities.test.ts
 create mode 100644 apps/server/src/modules/storage/capabilities.ts

diff --git a/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts b/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
index 90de3f1b6..076739824 100644
--- a/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
+++ b/apps/server/src/modules/agent/tools/handlers/fs-sandbox.ts
@@ -30,7 +30,7 @@ import { readFileSync, readdirSync, statSync, type Dirent } from 'node:fs';
 import path from 'node:path';
 
 import { parseFrontmatter } from '../../../../utils/markdown-frontmatter.js';
-import { space } from '../../../storage/index.js';
+import { space, unavailableCapabilityMessage } from '../../../storage/index.js';
 
 // ─── Always-skipped directory names ─────────────────────────────────────────
 
@@ -143,17 +143,13 @@ export function safeResolve(canvasId: string, rel: string): string {
   ) {
     throw new Error(`Invalid canvasId: ${canvasId}`);
   }
-  // The built-in file tools are Disk-only and stated as such (proposal
-  // §6.4.3, disposition A): off Disk the first-party agent reaches a Space
-  // over RFS/HTTP, which is what external agents already use. Refusing here
-  // is the backstop behind the capability matrix, not the primary check.
+  // Disk-only, and declared as such: `builtin-file-tools` is a
+  // capability-matrix entry, so an operator learns this when they select a
+  // profile rather than when an agent calls a tool. Refusing here is the
+  // backstop behind that declaration, phrased the same way.
   const tree = space(canvasId).diskTree;
-  if (!tree) {
-    throw new Error(
-      'Built-in file tools need a Space directory, which the active ' +
-        'structured backend does not provide.',
-    );
-  }
+  if (!tree)
+    throw new Error(unavailableCapabilityMessage('builtin-file-tools'));
   const root = tree.directory();
   // Accept the clean virtual prefixes (`upload/`, `artifacts/`) as aliases
   // for their hidden on-disk dirs so agents can reference either form.
diff --git a/apps/server/src/modules/canvas/canvas.route.ts b/apps/server/src/modules/canvas/canvas.route.ts
index f6e49f3db..1ea8f538d 100644
--- a/apps/server/src/modules/canvas/canvas.route.ts
+++ b/apps/server/src/modules/canvas/canvas.route.ts
@@ -1597,9 +1597,9 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
       return reply.code(404).send({ message: 'Canvas not found' });
     }
 
-    // The Space bundle is a Disk projection (proposal §6.4.3, disposition
-    // A); a portable export generated from records plus reachable blob
-    // references is a separate later design.
+    // Disk-only, declared as `space-bundle-export` in the capability matrix;
+    // a portable export generated from records plus reachable blob references
+    // is a separate later design.
     const tree = space(canvasId).diskTree;
     const canvasDir = tree?.directory();
     if (canvasDir === undefined || !existsSync(canvasDir)) {
diff --git a/apps/server/src/modules/canvas/external.route.ts b/apps/server/src/modules/canvas/external.route.ts
index 6460a9ad8..e5fc9e18a 100644
--- a/apps/server/src/modules/canvas/external.route.ts
+++ b/apps/server/src/modules/canvas/external.route.ts
@@ -95,8 +95,8 @@ const externalRoutes: FastifyPluginAsync = async (fastify): Promise<void> => {
       return reply.code(404).send({ message: 'External note not found' });
     }
 
-    // External-note claim is Disk-only (proposal §6.4.3, disposition A): it
-    // exists to adopt documents that arrived without going through the
+    // Disk-only, declared as `external-note-discovery` in the capability
+    // matrix: it adopts documents that arrived without going through the
     // application, and no database backend has such an arrival path.
     const tree = space(canvasId).diskTree;
     if (!tree) {
diff --git a/apps/server/src/modules/storage/capabilities.test.ts b/apps/server/src/modules/storage/capabilities.test.ts
new file mode 100644
index 000000000..527dd8b2c
--- /dev/null
+++ b/apps/server/src/modules/storage/capabilities.test.ts
@@ -0,0 +1,99 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * The capability matrix (proposal §6.4.2, disposition A).
+ *
+ * What is worth asserting is not the contents — those change as features do —
+ * but that the matrix stays a *declaration an operator can act on*: every
+ * entry names a backend that exists, the Disk profile loses nothing, and an
+ * unavailable feature is reported rather than raised.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  describeUnavailableCapabilities,
+  hasStorageCapability,
+  STORAGE_CAPABILITIES,
+  unavailableCapabilities,
+} from './capabilities.js';
+import { validateStorageProfile } from './profile.js';
+
+import type { StorageProfile } from './profile.js';
+
+const DISK: StorageProfile = {
+  structured: { kind: 'disk' },
+  blobs: { kind: 'disk' },
+};
+
+/**
+ * A profile naming a structured backend that has no adapter.
+ *
+ * The matrix has to answer for one before it exists — that is the point of
+ * declaring rather than discovering — so this stands in for the first backend
+ * that keeps Spaces in tables.
+ */
+const TABLES: StorageProfile = {
+  structured: { kind: 'sqlite' },
+  blobs: { kind: 'disk' },
+};
+
+describe('storage capability matrix', () => {
+  it('lists only real, identifiable capabilities', () => {
+    const ids = STORAGE_CAPABILITIES.map((capability) => capability.id);
+    expect(new Set(ids).size).toBe(ids.length);
+
+    for (const capability of STORAGE_CAPABILITIES) {
+      expect(capability.backends.length).toBeGreaterThan(0);
+      // A capability nothing can serve is not a limitation, it is a removed
+      // feature; a capability every backend serves does not belong here.
+      expect(capability.summary).not.toHaveLength(0);
+      expect(capability.rationale).not.toHaveLength(0);
+    }
+  });
+
+  it('offers every capability on the Disk profile', () => {
+    expect(unavailableCapabilities(DISK)).toEqual([]);
+    expect(describeUnavailableCapabilities(DISK)).toEqual([]);
+  });
+
+  it('answers for a backend that has no adapter yet', () => {
+    const missing = unavailableCapabilities(TABLES);
+
+    // Every entry is Disk-only today, so a structured backend that is not
+    // Disk loses all of them. The assertion is the shape, not the count.
+    expect(missing).toEqual(STORAGE_CAPABILITIES);
+    expect(hasStorageCapability(TABLES, 'reveal-space-folder')).toBe(false);
+    expect(hasStorageCapability(DISK, 'reveal-space-folder')).toBe(true);
+  });
+
+  it('treats an unknown id as available rather than guessing', () => {
+    // The matrix is an exception list. A feature nobody wrote down is
+    // portable by construction, and inventing a refusal for it would make
+    // adding a portable feature a matrix edit.
+    expect(hasStorageCapability(TABLES, 'something-portable')).toBe(true);
+  });
+
+  it('states a limitation without making it a misconfiguration', () => {
+    // A profile that merely offers fewer features must not fail validation —
+    // that is reserved for a backend that cannot serve at all. `sqlite` has
+    // no adapter yet, so it does fail; the distinction is which check
+    // rejects it.
+    expect(describeUnavailableCapabilities(TABLES).length).toBeGreaterThan(0);
+    expect(() => validateStorageProfile(TABLES)).toThrow(/not implemented/);
+    expect(() => validateStorageProfile(DISK)).not.toThrow();
+  });
+
+  it('describes each loss in operator terms', () => {
+    const lines = describeUnavailableCapabilities(TABLES);
+
+    for (const capability of STORAGE_CAPABILITIES) {
+      const line = lines.find((entry) => entry.startsWith(`${capability.id}:`));
+      expect(line).toBeDefined();
+      // The id to search for, what is lost, and why it cannot be emulated.
+      expect(line).toContain(capability.summary);
+      expect(line).toContain('sqlite');
+    }
+  });
+});
diff --git a/apps/server/src/modules/storage/capabilities.ts b/apps/server/src/modules/storage/capabilities.ts
new file mode 100644
index 000000000..68c412685
--- /dev/null
+++ b/apps/server/src/modules/storage/capabilities.ts
@@ -0,0 +1,167 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Which product features a storage profile can actually serve.
+ *
+ * Some features are *about* a filesystem — showing a folder in Finder,
+ * adopting a document a user dropped in from outside, a bundle that is a
+ * directory zipped up. A backend that keeps Spaces in tables has no honest
+ * answer for them, and the honest outcome is that the feature is
+ * **unavailable, not emulated** (proposal §6.4.2, disposition A). A
+ * workaround that makes such a feature *nearly* work is worse than its
+ * absence: it has to be built, tested, and explained, and it hides the
+ * limitation instead of stating it.
+ *
+ * "Stated" is what this file is for. An outcome of A is an acceptable product
+ * limitation only if an operator can learn it when they select a profile
+ * rather than when a user clicks the button — so the matrix sits beside
+ * profile validation, which is the one place a profile is inspected before
+ * anything opens.
+ *
+ * This is a *declaration*, not an enforcement point. Each listed feature also
+ * refuses at its own call site, because a matrix nobody consults at runtime is
+ * documentation. What the matrix adds is the up-front answer.
+ */
+
+import type { StructuredBackendKind } from './ports/structured.js';
+import type { StorageProfile } from './profile.js';
+
+/**
+ * A product feature whose availability depends on the structured backend.
+ *
+ * Keyed by structured kind alone: every entry here needs a Space to be a real
+ * directory, which is a structured-backend property. A feature that turned on
+ * the blob backend instead would be a second matrix, and there are none.
+ */
+export interface StorageCapability {
+  /** Stable id, for a diagnostic an operator can search for. */
+  readonly id: string;
+  /** What a user loses, in their vocabulary rather than the port's. */
+  readonly summary: string;
+  /** Structured backends that serve it. */
+  readonly backends: readonly StructuredBackendKind[];
+  /** Why it cannot be served elsewhere, and what remains instead. */
+  readonly rationale: string;
+}
+
+/**
+ * Every feature that is not available on every backend.
+ *
+ * Deliberately not "every feature" — a matrix that listed the portable ones
+ * too would need updating whenever anything was built, and would go stale
+ * silently. What must stay accurate is the exception list.
+ */
+export const STORAGE_CAPABILITIES: readonly StorageCapability[] = [
+  {
+    id: 'space-bundle-export',
+    summary: 'Export a Space as a .huabu.zip bundle',
+    backends: ['disk'],
+    rationale:
+      'The bundle is a Disk projection — the Space directory, archived. A ' +
+      'portable export generated from records plus reachable blob references ' +
+      'is a separate design.',
+  },
+  {
+    id: 'space-bundle-import',
+    summary: 'Import a Space from a .huabu.zip bundle',
+    backends: ['disk'],
+    rationale: 'Pairs with export; unzips into place.',
+  },
+  {
+    id: 'reveal-space-folder',
+    summary: 'Reveal a Space in the OS file manager',
+    backends: ['disk'],
+    rationale:
+      'The feature is "show me this in Finder". Without a folder there is ' +
+      'nothing to show.',
+  },
+  {
+    id: 'builtin-file-tools',
+    summary: 'Built-in agent file tools (read, write, glob, grep)',
+    backends: ['disk'],
+    rationale:
+      'They sandbox on the Space directory. Off Disk the first-party agent ' +
+      'reaches a Space over RFS/HTTP, which is what external agents already ' +
+      'use.',
+  },
+  {
+    id: 'external-note-discovery',
+    summary: 'Adopt Markdown files dropped into a Space from outside the app',
+    backends: ['disk'],
+    rationale:
+      'It watches for documents that arrived without going through the ' +
+      'application. A database backend has no such arrival path unless ' +
+      'someone writes to the store out of band, and inventing one would buy ' +
+      'nothing.',
+  },
+  {
+    id: 'space-directory-handle-coordination',
+    summary: 'Windows: rename or delete a Space while a watcher holds it open',
+    backends: ['disk'],
+    rationale:
+      'Exists so a directory rename can succeed against a live `fs.watch` ' +
+      'handle. No directory, no problem.',
+  },
+];
+
+/** Capabilities this profile cannot serve. */
+export function unavailableCapabilities(
+  profile: StorageProfile,
+): readonly StorageCapability[] {
+  return STORAGE_CAPABILITIES.filter(
+    (capability) =>
+      !(capability.backends as readonly string[]).includes(
+        profile.structured.kind,
+      ),
+  );
+}
+
+/** Whether this profile serves `id`. Unknown ids are available by omission. */
+export function hasStorageCapability(
+  profile: StorageProfile,
+  id: string,
+): boolean {
+  const capability = STORAGE_CAPABILITIES.find((entry) => entry.id === id);
+  if (!capability) return true;
+  return (capability.backends as readonly string[]).includes(
+    profile.structured.kind,
+  );
+}
+
+/**
+ * The refusal a Disk-only feature raises when it finds no Space directory.
+ *
+ * Shares its wording with the startup declaration, so the sentence an
+ * operator read when they chose the profile is the sentence they see in the
+ * failure. A feature that phrased its own refusal would drift from the
+ * matrix, and the drift would only show up in a support thread.
+ */
+export function unavailableCapabilityMessage(id: string): string {
+  const capability = STORAGE_CAPABILITIES.find((entry) => entry.id === id);
+  if (!capability) {
+    return `Storage capability "${id}" is not available on this backend.`;
+  }
+  return (
+    `${capability.summary} is not available on this storage backend ` +
+    `(capability "${capability.id}"). ${capability.rationale}`
+  );
+}
+
+/**
+ * One operator-facing line per feature this profile does not offer.
+ *
+ * Rendered at startup rather than raised: an unavailable feature is a stated
+ * limitation, not a misconfiguration, so it must not stop the Server. The
+ * distinction matters — a profile naming an unimplemented backend *is* a
+ * misconfiguration and still fails fast in `validateStorageProfile`.
+ */
+export function describeUnavailableCapabilities(
+  profile: StorageProfile,
+): readonly string[] {
+  return unavailableCapabilities(profile).map(
+    (capability) =>
+      `${capability.id}: ${capability.summary} — unavailable on the ` +
+      `"${profile.structured.kind}" structured backend. ${capability.rationale}`,
+  );
+}
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index 6601bdd56..107861816 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -89,6 +89,14 @@ export {
   StorageProfileError,
   validateStorageProfile,
 } from './profile.js';
+export {
+  describeUnavailableCapabilities,
+  hasStorageCapability,
+  STORAGE_CAPABILITIES,
+  unavailableCapabilities,
+  unavailableCapabilityMessage,
+} from './capabilities.js';
+export type { StorageCapability } from './capabilities.js';
 export type { StorageProfile } from './profile.js';
 export {
   assertValidNamespace,
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index 21b66502b..fdb65c37a 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -85,6 +85,8 @@ describe('storage module tree', () => {
 
     expect(rootFiles.sort()).toEqual([
       'canvas-dirs.ts',
+      'capabilities.test.ts',
+      'capabilities.ts',
       'index.ts',
       'module-boundaries.test.ts',
       'paths.ts',
diff --git a/apps/server/src/modules/storage/profile.ts b/apps/server/src/modules/storage/profile.ts
index f548af174..f962e8717 100644
--- a/apps/server/src/modules/storage/profile.ts
+++ b/apps/server/src/modules/storage/profile.ts
@@ -89,6 +89,13 @@ export function parseStorageProfile(
  * cross-axis rules belong as backends land — for example, Postgres paired
  * with a node-local disk blob root is unsafe across replicas unless the
  * path is a deliberately shared filesystem.
+ *
+ * A profile that merely offers *fewer features* is not rejected here. Those
+ * are stated limitations rather than misconfigurations, and they are declared
+ * in `capabilities.ts` and reported at startup — see
+ * {@link describeUnavailableCapabilities}. Conflating the two would either
+ * refuse a legitimate deployment or let a real misconfiguration through as a
+ * warning.
  */
 export function validateStorageProfile(profile: StorageProfile): void {
   if (!IMPLEMENTED_STRUCTURED.includes(profile.structured.kind)) {
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 6d418ac51..277b9267d 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -7,7 +7,11 @@ import { app } from './app.js';
 import { resolveBindHost } from './bind-host.js';
 import { prewarmOAuthCredentials } from './modules/agent/oauth.js';
 import { resolveDeploymentConfig } from './modules/security/deployment-config.js';
-import { initStorage } from './modules/storage/index.js';
+import {
+  describeUnavailableCapabilities,
+  initStorage,
+  parseStorageProfile,
+} from './modules/storage/index.js';
 import { initializeSecretStore } from './security/secret-store.js';
 import { getLogger } from './utils/logger.js';
 
@@ -37,14 +41,21 @@ async function start(): Promise<void> {
     // mode there is no Workspace yet, so this validates the profile and the
     // mount waits for activation.
     const storage = await initStorage();
+    const profile = storage?.profile ?? parseStorageProfile();
     log.info(
       {
-        structured: storage?.profile.structured.kind,
-        blobs: storage?.profile.blobs.kind,
+        structured: profile.structured.kind,
+        blobs: profile.blobs.kind,
         workspace: storage ? 'mounted' : 'awaiting activation',
       },
       'Storage backends ready',
     );
+    // Not a warning about a misconfiguration — a stated product limitation of
+    // the selected profile, said up front rather than when a user clicks the
+    // button (proposal §6.4.2). Startup continues either way.
+    for (const line of describeUnavailableCapabilities(profile)) {
+      log.info({ capability: line }, 'Storage capability unavailable');
+    }
 
     await initializeSecretStore();
     await app.listen({ port: PORT, host: HOST });

From 076437c895f70edd2ff59a8e2a1e6efdb33e864d Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 13:07:08 +0800
Subject: [PATCH 12/20] test(storage): prove the exit criterion against a
 mounted backend
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 4.6's criterion is about code that does not exist yet: adding another
`StructuredStore` must not require feature modules to learn its record
layout. No suite can assert that directly, so this asserts the observable
half — every durable thing the product does with a Space, driven through the
portable surface, against a profile mounted the way a Server mounts one.

`storage/testing.ts` does the mounting, and does it through the production
lifecycle rather than by swapping in a stub. The distinction is the whole
point: a suite over a stub proves the application talks to an interface,
while this one proves a backend serves the product. A backend whose mount is
broken now fails in the harness instead of surfacing later as a confusing
product failure.

Phase 5 adds SQLite to `PRODUCT_STORAGE_PROFILES` and every case runs against
it unchanged. That only holds while the suite stays ignorant of the backend,
so `module-boundaries.test.ts` reads its source and rejects Disk vocabulary
and any import outside the portable surface. The failure mode this guards is
not malice — it is a helpful-looking `existsSync` someone adds to make a case
more specific, which would keep passing for Disk and fail for the first
backend that has no directory.

Writing it surfaced one trap already documented one layer down: a change
record with an empty `revertDeltas` is silently dropped by `coalesceChanges`,
so a hand-rolled fixture asserts nothing. The log contract had hit this and
said so; the product suite builds its record through the engine for the same
reason.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../modules/storage/module-boundaries.test.ts |  58 +++
 .../modules/storage/product-boundary.test.ts  | 357 ++++++++++++++++++
 apps/server/src/modules/storage/testing.ts    | 100 +++++
 3 files changed, 515 insertions(+)
 create mode 100644 apps/server/src/modules/storage/product-boundary.test.ts
 create mode 100644 apps/server/src/modules/storage/testing.ts

diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index fdb65c37a..ae908c93d 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -90,11 +90,13 @@ describe('storage module tree', () => {
       'index.ts',
       'module-boundaries.test.ts',
       'paths.ts',
+      'product-boundary.test.ts',
       'profile.test.ts',
       'profile.ts',
       'space-lifecycle-admission.ts',
       'storage.test.ts',
       'storage.ts',
+      'testing.ts',
     ]);
   });
 
@@ -344,6 +346,62 @@ describe('Disk Space tree capability', () => {
   });
 });
 
+/**
+ * The product suite proves the exit criterion only while it stays ignorant of
+ * the backend (proposal §12.6.6).
+ *
+ * A case that reaches for a directory or a filename has stopped being
+ * evidence that anything is portable — it would keep passing for Disk and
+ * fail for the first backend that has neither, which is exactly backwards
+ * from what the suite is for. Enforced by reading the source, because the
+ * failure mode is a helpful-looking assertion someone adds later.
+ */
+describe('product boundary suite stays backend-blind', () => {
+  const SUITE = 'modules/storage/product-boundary.test.ts';
+
+  it('names no Disk record, blob, or directory vocabulary', () => {
+    // Quoted forms for the hidden tiers, so a scope *member* named `memory`
+    // — which is portable vocabulary — is not confused for the directory
+    // `.memory/`, which is not.
+    const DISK_VOCABULARY = [
+      "'space.json'",
+      "'.artifacts",
+      "'.history",
+      "'.memory",
+      "'.upload",
+      "'.world",
+      'diskTree',
+      'canvasRoot',
+      'nodesDir',
+      'readFileSync',
+      'existsSync',
+      'mkdirSync',
+    ];
+    const source = read(SUITE);
+    const found = DISK_VOCABULARY.filter((token) => source.includes(token));
+
+    expect(found).toEqual([]);
+  });
+
+  it('reaches storage only through the portable surface and the harness', () => {
+    const allowed = new Set([
+      'modules/storage/storage',
+      'modules/storage/testing',
+      'modules/storage/profile',
+      'modules/storage/ports/blob',
+      'modules/canvas/persistence-types',
+    ]);
+    const violations = specifiersOf(SUITE)
+      .map((spec) => resolveSpecifier(SUITE, spec))
+      .filter((target): target is string => target !== null)
+      .filter((target) => !allowed.has(target));
+
+    // A backend import would let a case assert against an adapter directly,
+    // which is what the per-adapter suites are for.
+    expect(violations).toEqual([]);
+  });
+});
+
 describe('structured write authority', () => {
   it('does not expose compatibility create/delete writers from the public barrel', () => {
     expect(read('modules/storage/index.ts')).not.toMatch(
diff --git a/apps/server/src/modules/storage/product-boundary.test.ts b/apps/server/src/modules/storage/product-boundary.test.ts
new file mode 100644
index 000000000..169198942
--- /dev/null
+++ b/apps/server/src/modules/storage/product-boundary.test.ts
@@ -0,0 +1,357 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Phase 4.6's exit criterion, run against a real backend.
+ *
+ * The criterion: adding another `StructuredStore` changes adapter,
+ * composition, and migration code, but does not require Canvas, agent, web,
+ * RFS, interactive-view, Task, or Workspace feature modules to learn that
+ * backend's record layout (proposal §12.6).
+ *
+ * A suite cannot assert that about code it does not run, so this asserts the
+ * observable half: every durable thing the product does with a Space, driven
+ * through the portable surface, against a profile mounted the way a Server
+ * mounts one. **It names no directory, no filename, and no `space.json`** —
+ * `module-boundaries.test.ts` enforces that mechanically, because the moment a
+ * case reaches for a path it stops being evidence of anything portable.
+ *
+ * Phase 5 adds SQLite to `PRODUCT_STORAGE_PROFILES` and every case below runs
+ * against it unchanged. A case that then fails is a real gap in the adapter;
+ * a case that needs editing to pass is a leak in this suite.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { extractCanvasChanges } from '@huabu/shared/canvas-engine';
+
+import {
+  SPACE_GUIDE_SKILL_NAME,
+  SPACE_MEMORY_BLOB_NAME,
+} from './ports/blob.js';
+import { deleteSpace } from './storage.js';
+import {
+  forEachProductProfile,
+  mountTestWorkspace,
+  type MountedTestStorage,
+} from './testing.js';
+
+
+import type { StorageProfile } from './profile.js';
+import type { CanvasFile } from '../canvas/persistence-types.js';
+import type { CanvasNode } from '@huabu/shared/canvas-engine';
+
+const NODE_A = 'node-product-a';
+const NODE_B = 'node-product-b';
+
+function record(canvasId: string, version: number): CanvasFile {
+  return {
+    canvasId,
+    title: 'Product Space',
+    version,
+    state: {
+      nodes: [
+        { id: NODE_A, type: 'note', position: { x: 0, y: 0 }, data: {} },
+        { id: NODE_B, type: 'note', position: { x: 10, y: 0 }, data: {} },
+      ],
+      edges: [],
+    },
+    createdAt: 1,
+    updatedAt: 2,
+  } as CanvasFile;
+}
+
+function note(nodeId: string, content: string) {
+  return { nodeId, type: 'note', label: nodeId, content };
+}
+
+/**
+ * A real change record, built through the engine rather than hand-rolled.
+ *
+ * `coalesceChanges` groups by the forward delta it reconstructs from
+ * `revertDeltas`, so a fabricated record with none is silently dropped and
+ * the case would assert nothing.
+ */
+function change(nodeId: string) {
+  const [built] = extractCanvasChanges([
+    {
+      type: 'INSERT_NODE',
+      node: {
+        id: nodeId,
+        type: 'note',
+        position: { x: 0, y: 0 },
+        data: { label: nodeId, content: 'body' },
+      } as CanvasNode,
+    },
+  ]);
+  return built;
+}
+
+forEachProductProfile((profile: StorageProfile, label: string) => {
+  describe(`product storage boundary (${label})`, () => {
+    let mounted: MountedTestStorage | null = null;
+
+    async function open(): Promise<MountedTestStorage> {
+      mounted = await mountTestWorkspace(profile, `huabu-product-${label}-`);
+      return mounted;
+    }
+
+    /** A Space with two nodes, created the way the product creates one. */
+    async function seedSpace(canvasId: string): Promise<MountedTestStorage> {
+      const m = await open();
+      const created = await m.storage.structured
+        .spaces()
+        .create({ canvasId, title: 'Product Space' });
+      if (!created.ok) throw new Error('Expected to create the Space');
+
+      const write = await m.storage.space(canvasId).write({
+        expectedVersion: 0,
+        nextRecord: {
+          ...record(canvasId, 1),
+          title: created.record.title,
+          createdAt: created.record.createdAt,
+        },
+        nodeMutations: [
+          { kind: 'put', nodeId: NODE_A, record: note(NODE_A, 'alpha') },
+          { kind: 'put', nodeId: NODE_B, record: note(NODE_B, 'beta') },
+        ],
+      });
+      expect(write).toEqual({ ok: true });
+      return m;
+    }
+
+    afterEach(async () => {
+      await mounted?.close();
+      mounted = null;
+    });
+
+    it('bootstraps a World that ordinary listings exclude', async () => {
+      const m = await open();
+      const spaces = m.storage.structured.spaces();
+
+      // The mount already ensured it — a Workspace with no World has no
+      // Portal target, so this is not something the product does later.
+      const worldId = await spaces.worldId();
+      expect(worldId).toEqual(expect.any(String));
+      await expect(spaces.list()).resolves.toEqual([]);
+      await expect(spaces.ensureWorld()).resolves.toBe(worldId);
+    });
+
+    it('creates a Space and reads back the record it was promised', async () => {
+      const m = await open();
+      const spaces = m.storage.structured.spaces();
+      const created = await spaces.create({
+        canvasId: 'space-product-create',
+        title: 'Product Space',
+      });
+      if (!created.ok) throw new Error('Expected to create the Space');
+
+      expect(created.record).toMatchObject({
+        canvasId: 'space-product-create',
+        version: 0,
+        state: { nodes: [], edges: [] },
+      });
+      await expect(
+        m.storage.space('space-product-create').read(),
+      ).resolves.toEqual(created.record);
+      expect((await spaces.list()).map((row) => row.canvasId)).toEqual([
+        'space-product-create',
+      ]);
+    });
+
+    it('serves one ordered write through every node read shape', async () => {
+      const canvasId = 'space-product-nodes';
+      const m = await seedSpace(canvasId);
+      const nodes = m.storage.space(canvasId).nodes;
+
+      await expect(m.storage.space(canvasId).read()).resolves.toMatchObject({
+        version: 1,
+      });
+
+      const single = await nodes.read(NODE_A);
+      expect(single?.record.content).toBe('alpha');
+
+      const listed = await nodes.list();
+      expect([...listed.keys()].sort()).toEqual([NODE_A, NODE_B].sort());
+      expect(listed.get(NODE_A)).toEqual(single);
+
+      const selection = await nodes.readMany([NODE_B]);
+      expect([...selection.keys()]).toEqual([NODE_B]);
+
+      const delivered: string[] = [];
+      const streamed = await nodes.stream((snapshot) =>
+        delivered.push(snapshot.record.nodeId),
+      );
+      expect(streamed).toEqual(listed);
+      expect(delivered.sort()).toEqual([NODE_A, NODE_B].sort());
+    });
+
+    it('refuses a write from a version the caller no longer holds', async () => {
+      const canvasId = 'space-product-cas';
+      const m = await seedSpace(canvasId);
+
+      await expect(
+        m.storage.space(canvasId).write({
+          expectedVersion: 0,
+          nextRecord: record(canvasId, 1),
+          nodeMutations: [],
+        }),
+      ).resolves.toEqual({
+        ok: false,
+        reason: 'version-conflict',
+        actualVersion: 1,
+      });
+    });
+
+    it('keeps bytes for every area of a Space and tells them apart', async () => {
+      const canvasId = 'space-product-blobs';
+      const m = await seedSpace(canvasId);
+      const handle = m.storage.space(canvasId);
+
+      await handle.blobs.put('artifact.bin', Buffer.from('artifact bytes'));
+      await handle.memory.put(SPACE_MEMORY_BLOB_NAME, Buffer.from('# memory'));
+      await handle.guide.put(SPACE_GUIDE_SKILL_NAME, Buffer.from('# guide'));
+      await handle.uploads.put('staged.bin', Buffer.from('staged bytes'));
+
+      expect(await handle.blobs.read('artifact.bin')).toEqual(
+        Buffer.from('artifact bytes'),
+      );
+      expect(await handle.memory.read(SPACE_MEMORY_BLOB_NAME)).toEqual(
+        Buffer.from('# memory'),
+      );
+      // Areas are separate namespaces, so one area's name is not another's.
+      expect(await handle.blobs.read(SPACE_MEMORY_BLOB_NAME)).toBeNull();
+      expect((await handle.uploads.list()).map((info) => info.name)).toEqual([
+        'staged.bin',
+      ]);
+    });
+
+    it('refuses bytes for a Space that does not exist', async () => {
+      const m = await open();
+
+      // The one cross-store rule: bytes only for a Space whose record exists.
+      await expect(
+        m.storage
+          .space('space-product-absent')
+          .blobs.put('orphan.bin', Buffer.from('x')),
+      ).rejects.toThrow();
+    });
+
+    it('gives a namespace an isolated place and destroys it with the Space', async () => {
+      const canvasId = 'space-product-extension';
+      const m = await seedSpace(canvasId);
+
+      const substrate = await m.storage
+        .space(canvasId)
+        .extension('product.owner');
+      expect(substrate?.kind).toBe(profile.structured.kind);
+
+      // A Space that is gone has no substrate, which is what keeps an owner
+      // from resurrecting one by writing its own bookkeeping.
+      await deleteSpace(canvasId);
+      await expect(
+        m.storage.space(canvasId).extension('product.owner'),
+      ).resolves.toBeNull();
+    });
+
+    it('appends and reads the Space log families', async () => {
+      const canvasId = 'space-product-logs';
+      const m = await seedSpace(canvasId);
+      const handle = m.storage.space(canvasId);
+
+      await handle.events.append([
+        {
+          payload: {
+            action: 'node_created',
+            nodes: [{ id: NODE_A, type: 'note' }],
+          },
+          ts: 10,
+        },
+      ]);
+      const events = await handle.events.read();
+      expect(events).toHaveLength(1);
+
+      const appended = await handle.changes.append('thread-product', [
+        change(NODE_A),
+      ]);
+      expect(appended).toHaveLength(1);
+      const changeId = appended[0].id;
+      await expect(handle.changes.read('thread-product')).resolves.toHaveLength(
+        1,
+      );
+      await expect(
+        handle.changes.delete('thread-product', changeId),
+      ).resolves.toMatchObject({ id: changeId });
+      await expect(handle.changes.read('thread-product')).resolves.toEqual([]);
+    });
+
+    it('keeps a Task and its Runs in one ledger', async () => {
+      const canvasId = 'space-product-tasks';
+      const m = await seedSpace(canvasId);
+      const tasks = m.storage.space(canvasId).tasks;
+
+      await tasks.create({
+        taskId: 'task-1',
+        canvasId,
+        goal: 'Do the thing',
+        defaultRootProfileId: 'profile-1',
+        anchorNodeId: NODE_A,
+        createdAt: 1,
+      });
+      await tasks.runs.create({
+        runId: 'run-1',
+        taskId: 'task-1',
+        canvasIdSnapshot: canvasId,
+        goalSnapshot: 'Do the thing',
+        rootProfileIdSnapshot: 'profile-1',
+        status: 'pending',
+        createdAt: 2,
+      });
+
+      const snapshot = await tasks.read();
+      expect(snapshot.tasks.map((task) => task.taskId)).toEqual(['task-1']);
+      expect(snapshot.runs.map((run) => run.runId)).toEqual(['run-1']);
+
+      await tasks.runs.update('run-1', { status: 'running', startedAt: 3 });
+      const completed = await tasks.runs.complete('task-1', 'run-1', {
+        completedAt: 4,
+        message: 'done',
+      });
+      expect(completed.outcome).toBe('completed');
+    });
+
+    it('removes a Space and everything it held', async () => {
+      const canvasId = 'space-product-delete';
+      const m = await seedSpace(canvasId);
+      const handle = m.storage.space(canvasId);
+      await handle.blobs.put('artifact.bin', Buffer.from('bytes'));
+      await handle.memory.put(SPACE_MEMORY_BLOB_NAME, Buffer.from('# memory'));
+
+      await expect(deleteSpace(canvasId)).resolves.toEqual({
+        ok: true,
+        reason: 'deleted',
+      });
+
+      const after = m.storage.space(canvasId);
+      await expect(after.read()).resolves.toBeNull();
+      await expect(after.nodes.list()).resolves.toEqual(new Map());
+      // Every area, not only artifacts: an unswept one is an orphan on a
+      // backend where dropping the record does not remove the area.
+      expect(await after.blobs.read('artifact.bin')).toBeNull();
+      expect(await after.memory.read(SPACE_MEMORY_BLOB_NAME)).toBeNull();
+      await expect(m.storage.structured.spaces().list()).resolves.toEqual([]);
+    });
+
+    it('refuses to delete the World', async () => {
+      const m = await open();
+      const spaces = m.storage.structured.spaces();
+      const worldId = await spaces.worldId();
+
+      await expect(deleteSpace(worldId)).resolves.toEqual({
+        ok: false,
+        reason: 'world-forbidden',
+      });
+      await expect(spaces.worldId()).resolves.toBe(worldId);
+    });
+  });
+});
diff --git a/apps/server/src/modules/storage/testing.ts b/apps/server/src/modules/storage/testing.ts
new file mode 100644
index 000000000..6cf5d6eda
--- /dev/null
+++ b/apps/server/src/modules/storage/testing.ts
@@ -0,0 +1,100 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Product-level storage harness.
+ *
+ * Mounts a **real** profile onto a temporary Workspace through the production
+ * lifecycle — prepared Workspace, staged connections, `ensureWorld()`, atomic
+ * swap — rather than swapping in a stub. That distinction is the whole point:
+ * a suite written against a stub proves that the application talks to an
+ * interface, while this one proves that a *backend* serves the product
+ * (proposal §12.6.6).
+ *
+ * It exists so a product test is written once and run against every profile.
+ * Phase 5 adds one entry to {@link PRODUCT_STORAGE_PROFILES} and the same
+ * behaviours are covered for SQLite, without a line of the suite changing —
+ * which is also the check that the suite never learned a backend's layout.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { closeStorage, stageStorage } from './storage.js';
+import { setWorkspacePath } from '../workspace.js';
+
+import type { StorageProfile } from './profile.js';
+import type { Storage } from './storage.js';
+
+/**
+ * Every profile the product suite must pass against.
+ *
+ * A backend joins this list when it claims to serve the product, not when its
+ * adapter first compiles — an adapter may exist for isolated testing before
+ * its profile is selectable.
+ */
+export const PRODUCT_STORAGE_PROFILES: readonly StorageProfile[] = [
+  { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
+];
+
+/** Readable name for a profile, for test titles. */
+export function describeProfile(profile: StorageProfile): string {
+  return `${profile.structured.kind}/${profile.blobs.kind}`;
+}
+
+export interface MountedTestStorage {
+  readonly profile: StorageProfile;
+  readonly storage: Storage;
+  /** The temporary Workspace. Only the harness itself should name paths. */
+  readonly workspacePath: string;
+  close(): Promise<void>;
+}
+
+/**
+ * Mount `profile` onto a fresh temporary Workspace.
+ *
+ * Goes through `setWorkspacePath` and {@link stageStorage} rather than
+ * reaching for the adapters, so a test exercises the same preparation,
+ * bootstrap, and swap a running Server does. A backend whose mount is broken
+ * fails here, in the harness, instead of surfacing as a confusing product
+ * failure later.
+ */
+export async function mountTestWorkspace(
+  profile: StorageProfile,
+  prefix = 'huabu-product-',
+): Promise<MountedTestStorage> {
+  // A profile label reads as `disk/disk`, which is not a directory name.
+  const safePrefix = prefix.replace(/[^a-zA-Z0-9._-]/g, '-');
+  const workspacePath = mkdtempSync(path.join(tmpdir(), safePrefix));
+  // Prepares and commits the Workspace, exactly as a synchronous activation
+  // does; the mount below is then the async half of the same sequence.
+  setWorkspacePath(workspacePath);
+
+  const staged = await stageStorage(workspacePath, profile);
+  await staged.commit();
+
+  return {
+    profile,
+    storage: staged.storage,
+    workspacePath,
+    async close(): Promise<void> {
+      await closeStorage();
+      rmSync(workspacePath, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Run `body` once per product profile.
+ *
+ * The suite names the profile only in its title. Anything a case needs to
+ * know about the backend it is running against would be a leak.
+ */
+export function forEachProductProfile(
+  body: (profile: StorageProfile, label: string) => void,
+): void {
+  for (const profile of PRODUCT_STORAGE_PROFILES) {
+    body(profile, describeProfile(profile));
+  }
+}

From 6526af6a442f5ef0ea0e34843f01aaa230d9e41d Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 13:15:06 +0800
Subject: [PATCH 13/20] docs(storage): record phase 4.6 as implemented
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The architecture doc now describes what a reader will find: one
`space(canvasId)` handle over both ports, a mount that belongs to one
Workspace and is staged before it is published, one blob scope per
user-visible area, an extension substrate that lends a place rather than a
data API, and a capability matrix for the features that are about a
filesystem rather than about storage.

The proposal marks the phase implemented and carries four findings that came
out of building rather than reading, because each is the kind of thing that
would otherwise be rediscovered by the next adapter:

- a pure merge cannot hold a lazy store read across an async port;
- a staged mount must capture what it replaces when it is staged, not when it
  swaps, or committing the Workspace path leaves the previous connections
  unclosed;
- a blob scope whose area is the Space root has to be bounded by its member
  names, since the folder holds storage's own records;
- the resurrection guard several owners each carried belongs in the port, as
  a substrate that does not exist for a Space that does not exist.

One item is recorded as deliberately narrowed. Upload scratch got its scope
kind — named, swept on delete, free to diverge in retention — but its writers
still reach it through the sandbox path, because RFS upload is a streaming
handler and path classification rather than the bare file read the "simplifies
Disk on its own merits" exception describes. It moves with RFS's path
vocabulary, not before.

Phase 5's owed list is rewritten against what actually landed. The honest
measure of this phase is that all of it is additive: nothing SQLite owes asks
a feature module to change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../modules/storage/product-boundary.test.ts  |   1 -
 docs/architecture/canvas-storage.md           | 106 ++++++++++++-----
 docs/proposals/multi-backend-storage.md       | 111 +++++++++++++-----
 3 files changed, 159 insertions(+), 59 deletions(-)

diff --git a/apps/server/src/modules/storage/product-boundary.test.ts b/apps/server/src/modules/storage/product-boundary.test.ts
index 169198942..c7d8851e4 100644
--- a/apps/server/src/modules/storage/product-boundary.test.ts
+++ b/apps/server/src/modules/storage/product-boundary.test.ts
@@ -36,7 +36,6 @@ import {
   type MountedTestStorage,
 } from './testing.js';
 
-
 import type { StorageProfile } from './profile.js';
 import type { CanvasFile } from '../canvas/persistence-types.js';
 import type { CanvasNode } from '@huabu/shared/canvas-engine';
diff --git a/docs/architecture/canvas-storage.md b/docs/architecture/canvas-storage.md
index 39a9cabb9..ba4df69d1 100644
--- a/docs/architecture/canvas-storage.md
+++ b/docs/architecture/canvas-storage.md
@@ -1,12 +1,53 @@
 # Canvas Storage Architecture
 
-> Last updated: 2026-08-11
+> Last updated: 2026-08-20
 
 ## 1. Overview
 
-Every Space remains fully self-contained on Disk by default, but storage no longer presents one all-purpose `CanvasStore` as its backend contract. `apps/server/src/modules/storage/` separates backend-neutral blob and structured ports, Disk adapters, process-wide composition, and a shrinking Disk compatibility facade. Opaque artifact bytes flow through `BlobStore`; `StructuredStore` exposes one `spaces()` repository for the Space collection — membership, World identity, and create/delete/rename — while `SpaceHandle` exposes the Space's own async record read and ordered write plus the parts it holds: `nodes`, `changes`, `tasks`, and `events`. Space creation and deletion, standalone node writes, executor and revert batches, preprocessing persistence, and event/change mutations enter these ports. The remaining compatibility consumers are explicit Disk capabilities and paths such as ZIP import/export, RFS upload/delete, external-note observation/claim, bootstrap/migration, and hydration helpers; some read and some mutate physical files, so they keep non-Disk profiles unselectable until their own contracts are designed.
-
-Runtime Home-folder activation prepares and migrates the selected directory in a disposable child process before committing it as the active workspace. This isolation is required because synchronous filesystem calls against cloud, network, or virtual drives can block indefinitely; a stuck preparation is terminated after 70 seconds with `WORKSPACE_ACTIVATION_TIMEOUT`, while the Server event loop and previously active workspace remain available. Concurrent activation attempts return `WORKSPACE_ACTIVATION_IN_PROGRESS`. Managed-mode startup still prepares synchronously before the Server accepts requests.
+Every Space remains fully self-contained on Disk by default, but storage no
+longer presents one all-purpose `CanvasStore` as its application contract.
+`apps/server/src/modules/storage/` separates backend-neutral blob and
+structured ports, Disk adapters, process-wide composition, and a shrinking
+compatibility facade.
+
+**One handle per Space.** `space(canvasId)` vends every storage capability for
+one Space: its record (`read`/`write`), the parts it holds (`nodes`, `changes`,
+`tasks`, `events`), an isolated substrate for a namespace's own store
+(`extension`), one blob scope per user-visible area (`blobs`, `guide`,
+`memory`, `uploads`), and — where the backend has one — its directory
+(`diskTree`, `null` elsewhere). It is a composition-layer facade, not a port
+type: `StructuredStore` and `BlobStore` keep their interfaces and their
+independence, and are joined only in the layer that already owns every
+cross-store rule.
+
+Production Canvas, agent, web, RFS, interactive-view, Task, and Workspace
+reads and writes all go through those ports. `CanvasStore` remains an internal
+Disk primitive and compatibility-test seam, not an application service, and
+nothing in production imports it.
+
+**A mount belongs to one Workspace.** Startup validates the profile without
+opening anything when free mode has no Workspace yet. Activating one prepares
+and migrates the directory in a disposable child process, then stages both
+backend connections, bootstraps the Workspace's World through
+`SpaceRepository.ensureWorld()`, and only then publishes the path and the
+mount together — in one synchronous block, so no request sees one moved
+without the other. Everything that can fail happens while the previous
+Workspace is still serving, and a failure leaves it serving. Graceful shutdown
+closes the mount. The child-process isolation is required because synchronous
+filesystem calls against cloud, network, or virtual drives can block
+indefinitely; a stuck preparation is terminated after 70 seconds with
+`WORKSPACE_ACTIVATION_TIMEOUT`. Concurrent activation attempts return
+`WORKSPACE_ACTIVATION_IN_PROGRESS`. Managed-mode startup prepares
+synchronously before the Server accepts requests, then mounts.
+
+**What is not portable is declared, not emulated.** Six features are about a
+filesystem rather than about storage — bundle export and import,
+reveal-in-file-manager, the built-in agent file tools, external-note
+discovery, and Windows directory-handle coordination. `capabilities.ts` lists
+them, `validateStorageProfile` sits beside it, and startup logs what the
+selected profile does not offer, so an operator learns it when they choose a
+profile rather than when a user clicks the button. Each also refuses at its own
+call site, sharing the matrix's wording.
 
 ## 2. Disk Layout
 
@@ -23,9 +64,11 @@ Runtime Home-folder activation prepares and migrates the selected directory in a
       <safe(label)>.md            # frontmatter: id/type/label/src/... + content(markdown body)
     .artifacts/                   # Disk BlobStore mapping for this Space
       <artifactId><ext>           # raw uploads (PDF / image / video / cover)
-    .memory/                      # hidden, AI-private canvas memory
-      space.md                    # canvas memory body
-      state.json                  # memory worker bookkeeping
+    skill.md                      # user-authored RFS access guide (space-guide blob scope)
+    .memory/                      # hidden, AI-private (space-memory blob scope)
+      space.md                    # Space memory body
+    .upload/                      # hidden upload scratch (space-upload blob scope)
+    .ext/<owner>.<name>/          # one directory per extension namespace
     .history/                     # hidden dir; also the Agenetes namespace storage.root
       chat_v2/                    # canonical chat log — owned by Agenetes L2, NOT CanvasStore
         <threadId>.events.jsonl   # Tier-1: append-only AgentStreamEvent delta log (live turn)
@@ -41,21 +84,23 @@ Runtime Home-folder activation prepares and migrates the selected directory in a
 Key points:
 
 - An ordinary Space **directory name** is derived from its title via `toSafeFilename(title)`, not from `canvasId`. The stable `canvasId` only lives inside `space.json`; the World is the reserved `.world` exception.
-- `SpaceRepository.list()` rescans on every call, returns ordinary Spaces only, skips ordinary directories without `space.json`, rejects malformed records (including a corrupt established World), and leaves ordering to the caller. `worldId()` resolves the hidden World from the same rescan and rejects missing or malformed state; it is the single World resolution point the collection's own create/delete/rename refusals also go through.
+- `SpaceRepository.list()` rescans on every call, returns ordinary Spaces only, skips ordinary directories without `space.json`, rejects malformed records (including a corrupt established World), and leaves ordering to the caller. Two directories carrying the same `canvasId` are an integrity error raised by the scan, so a Finder-side duplication fails every catalogue read instead of resolving to an arbitrary copy. `worldId()` resolves the hidden World from the same rescan and rejects missing or malformed state; it is the single World resolution point the collection's own create/delete/rename refusals also go through.
 - The `canvasId -> directory name` index in `canvas-dirs.ts` is invalidated **lazily**, never by a live filesystem watcher. Catalogue reads and the World resolvers re-scan unconditionally, server-owned create/rename register the new directory directly, and `CanvasStore.read()` re-scans and retries when `space.json` is missing — which is also how a Finder-side Space rename is adopted as the new title. A stale index therefore self-heals on the next read of the affected Space.
 - External-note observation exists for one feature: surfacing user-authored `.md` files dropped into `<Space>/nodes/` from outside the app. There is **no workspace-level watcher**. In steady state there is at most one native `fs.watch` handle per **active Space session**; concurrent SSE subscribers to the same Space share that session, watcher, and scan, so watcher count follows distinct active Spaces rather than open streams. Opening a Space's stream arms its native watcher _before_ the one lazy scan begins (closing the scan-then-watch gap), limits that scan to eight concurrent file reads plus one asynchronous topology read for filtering known note ids, and returns a single merged snapshot; live events read the latest topology synchronously and always win over an older scan observation of the same path. When `nodes/` does not exist, non-Windows sessions watch the Space root and promote themselves to the child directory as soon as it appears. Windows sessions use one periodic existence probe instead, avoiding a root handle that would block external Space rename/delete. If an active `nodes/` directory is deleted or replaced, the session verifies its filesystem identity before emitting an empty snapshot, re-resolves a Finder-renamed Space by `canvasId`, then waits for the path and resumes child watching instead of remaining attached to the stale inode. The final `close()` releases the watcher, clears pending timers, and drops the Space's discovery state. A failed scan is not cached, so a later subscription retries. Workspace and session generations reject scans and events that resolve after a workspace switch or a close/reopen. Inactive Spaces hold no watcher and no in-memory state; their eventual state is rebuilt by the first lazy scan when they are next opened.
 - Because a live `fs.watch` handle inside a Space subtree makes `renameSync` / `rmSync` fail with EPERM on Windows, `space-dir-handles.ts` arbitrates between handle owners and directory mutations. Each active external-note session registers itself against its `canvasId`; server-owned Space rename and delete bracket the mutation with `withSpaceDirHandlesReleased(canvasId, fn)`, which releases that Space's handles and lets the owner re-acquire afterwards — re-resolving the directory, so a rename re-arms at the new path and a delete collapses the session to an empty snapshot. A Space with no open stream has no registered owner, so the bracket is a plain passthrough. Neither side knows about the other.
-- Workspace preparation creates exactly one hidden `.world/space.json` after migrations. Its generated `canvasId` remains stable, resolves through the normal `CanvasStore`, and is exposed separately as `WorkspaceInfo.worldCanvasId`; ordinary Canvas lists continue to omit it.
+- Workspace preparation and `SpaceRepository.ensureWorld()` share one idempotent Disk primitive, so `.world/space.json` has a single writer even though the legacy preparation path still runs before the mount. Exactly one is created after migrations; its generated `canvasId` remains stable, resolves through the normal `SpaceHandle`, and is exposed separately as `WorkspaceInfo.worldCanvasId`; ordinary Space lists continue to omit it.
 - An established `.world` directory with a missing or malformed `space.json` is an integrity error. World identity is never silently regenerated, and the World cannot be deleted or directory-renamed through ordinary Space lifecycle operations.
 - Reading the World reconciles one canonical `canvasRef` Portal for every live ordinary Space; a Portal Pin whose source Space has no Portal yet runs the same reconciliation first, so pinning never depends on the user having opened the World. Reconciliation creates only missing Portals in deterministic open grid slots, preserves every existing node and position, rejects duplicate or malformed Portal identities, and leaves a broken Portal when its source Space is deleted.
 - Canonical Portal identity is server-owned: non-system commands cannot create or repoint a `canvasRef`, a live Portal cannot be deleted, and only a broken Portal may be removed. Portal geometry may move like ordinary World geometry, but its size is content-managed rather than manually resized.
 - Persistent `frameRef` and `nodeRef` nodes have no markdown sidecars and store only their respective type plus `{ target: { canvasId, nodeId } }` and World-owned React Flow state. A `frameRef` is a Container snapshot of a source Frame, may recursively own matching `frameRef` / `nodeRef` descendants, and never reconciles later source hierarchy changes; direct references remain children of the matching `canvasRef`. `SET_PORTAL_NODE_PINS` is their sole create/remove path.
 - `GET /api/canvas/:worldCanvasId/references` batch-resolves Portal titles and pinned source-node display data for both reference types without writing it into World topology. Results distinguish `ok`, `canvas-missing`, and `node-missing`; storage or parse failures remain request errors.
 - Node filenames are `safe(label).md`; the node's stable id lives in the `id:` frontmatter field.
-- The Disk `BlobStore` maps each Space scope to `.artifacts/`, with blobs named `<artifactId><ext>` and no manifest file — the filename is the URL key. Ordinary callers resolve the scope through `canvasBlobs(canvasId)`: `put()` requires an existing Space record, while reads and `deleteAll()` remain available for recovery after a record goes missing. `CanvasStore` owns no artifact methods. Only the Disk blob and structured backends are implemented and selectable today.
+- The Disk `BlobStore` maps **one scope per user-visible area** of a Space: artifacts to `.artifacts/` (blobs named `<artifactId><ext>`, no manifest — the filename is the URL key), the memory body to `.memory/`, upload scratch to `.upload/`, and the user-authored guide to the Space root. Naming the areas is what keeps blob names flat; hierarchical names are excluded for every backend. Callers reach them as `space(canvasId).blobs` / `.memory` / `.uploads` / `.guide`: `put()` requires an existing Space record, while reads and `deleteAll()` remain available for recovery after a record goes missing. The guide scope is bounded by its **member names** rather than by a directory, because its area is the Space root — a scope that claimed the folder would list `space.json` and delete the Space on `deleteAll()`. Space deletion sweeps every area, since on a backend where dropping the record does not remove the area the bytes sit in, an unswept kind is an orphan. `CanvasStore` owns no artifact methods. Only the Disk blob and structured backends are implemented and selectable today.
+
+- **Storage lends a place, not a data API.** `space(canvasId).extension(namespace)` returns an isolated substrate — a reserved directory on Disk, a table prefix or schema on a future backend — that a namespace builds its own store on. Storage validates the `<owner>.<name>` token, creates the namespace on demand, and destroys it with the Space; it never sees what is inside, and offers no read or write of its own. A port member per feature would oblige every future backend to model data it has no stake in, and a namespaced key/value member would fix one access shape for every owner forever. `extension()` returns `null` for a Space that does not exist, which is what stops an owner's bookkeeping write from resurrecting a Space that was just deleted. Memory-worker state (`huabu.memory`) and the debug prompt log (`huabu.prompt.log`) are the first two namespaces.
 - Remote PDF preprocessing writes the already-fetched source bytes into the Space BlobStore as `artifact-<id>.pdf` before structured persistence and replaces the node's remote `src` with that key. As with other artifact imports, this blob write precedes the node write operation; a later structured persistence failure may therefore leave an unreferenced blob until Space deletion, while a blob-write failure degrades to retaining the remote URL.
 - Events are append-only JSONL (`events.jsonl`); each line is `{ ts: number, payload: RecentAction }`.
-- The memory analyzer reads Space existence and at most 100 recent action events through one `SpaceHandle`. A missing Space skips the pass before reading memory files or calling the model; corrupt part data still fails the pass. Memory body/state files remain materialized workspace paths, while Agenetes-owned chat history is not part of the curator bundle.
+- The memory analyzer reads Space existence and at most 100 recent action events through one `SpaceHandle`. A missing Space skips the pass before reading memory or calling the model; corrupt part data still fails the pass. The memory body is a blob and the worker's bookkeeping is an extension namespace, so neither is a path any more; Agenetes-owned chat history is not part of the curator bundle.
 - **Chat history is Chat-V2, owned by Agenetes L2 — not `CanvasStore`.** The canonical per-thread conversation is a two-tier append-only log under `chat_v2/`: Tier-1 `<threadId>.events.jsonl` (`AgentStreamEvent` deltas a running turn appends, written by `FileEventLogStore`) and Tier-2 `<threadId>.turns.jsonl` (folded `AgentTurn`s, written by `FileTurnStore` — the only tier `history()` reads back). These files sit under the canvas `.history/` only because it is the Agenetes namespace `storage.root` (`canvasAcpNamespace(canvasId)`); `CanvasStore` never touches them. Do **not** confuse `chat_v2/<threadId>.events.jsonl` (agent stream events) with the sibling `events.jsonl` (canvas action log) — same suffix, unrelated content.
 - Durable Agenetes workload records live in `.history/threads.json` (`agenetes-v2` schema, one record per thread; written by `FileThreadStore`). The host-local `namespace.storage.root` is never persisted: reads bind each record to the current Space namespace, so a Home synchronized across computers cannot redirect storage back to another machine's absolute path.
 - Canonical Task and Run records live in `.history/tasks.json`, owned by Huabu Server through the async `SpaceTasks` ledger (`read`, `create`, and `runs.create`/`runs.update`). The Disk adapter validates the versioned snapshot and referential integrity on every read, rejects duplicate identifiers and Runs whose Task is absent, serializes read-modify-write operations with an independent per-Canvas process-local mutex, and atomically replaces the file. This mutex is intentionally separate from the Canvas topology write coordinator, so Task metadata does not participate in `space.json` version CAS.
@@ -65,24 +110,27 @@ Key points:
 
 `apps/server/src/modules/storage/` has three layers plus its composition root:
 
-| Path                                            | Responsibility                                                                                                                                                      |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ports/blob.ts`                                 | Backend-neutral `BlobStore` connection/scope contract for opaque bytes and bounded materialization leases.                                                          |
-| `ports/structured.ts`                           | Backend-neutral `StructuredStore`, the `SpaceRepository` collection, and the `SpaceHandle` composite: record read/ordered write, nodes, changes, Tasks, and events. |
-| `ports/contracts/`                              | Reusable Space-collection, node, Space-write, log, blob, and store suites; guarantees are the minimum every adapter implements.                                     |
-| `backends/disk/`                                | Disk implementations plus before-image restoration for rejected in-process ordered batches; no journal or startup recovery.                                         |
-| `backends/disk/legacy/`                         | The legacy `CanvasStore` and its synchronous adapter primitives, bounded Workspace-qualified cache, and process-local node tombstones.                              |
-| `compatibility/canvas.ts`                       | Residual Disk reads plus direct-module create/delete test fixtures; lifecycle writers are not exported from the public storage barrel.                              |
-| `space-lifecycle-admission.ts`                  | Backend-neutral, writer-preferring single-process coordinator shared by structured mutations and blob puts during a delete session.                                 |
-| `profile.ts` and `storage.ts`                   | Two-axis backend selection, validation, adapter construction, process-wide lifecycle, blob scopes, and the blob-first deletion saga.                                |
-| `index.ts`                                      | Public exports only; application code imports here rather than reaching into an adapter.                                                                            |
-| `canvas-store.ts`, `paths.ts`, `canvas-dirs.ts` | Deprecated forwarding shims with no logic, retained only for high-fanout compatibility imports.                                                                     |
-
-The Disk structured adapter and compatibility facade resolve the same cached legacy object, so migration does not create two in-memory authorities. All portable repository methods are async. `SpaceRepository` owns membership reads, structured create/rename, and an exclusive `beginDelete()` session; composition holds that session across the existing blob-first delete saga and then calls `finish()` or `abort()`. Every Space-record write goes through `SpaceHandle.write`, which is the version-checked replacement with the node and delta batch attached; `SpaceHandle.read` reads only. `SpaceNodes` returns complete records plus revision tokens without exposing filenames. `write` preserves the old node mutations → Space record → optional delta order. When a normal in-process node → record → delta batch rejects, the adapter must restore that batch's prestate before returning the rejection. An explicit title rename remains the preceding ordered, best-effort boundary and is not rolled back with the batch. The port does not promise process-crash or power-loss recovery, a determinate result after an unknown remote outcome, multi-process serialization, idempotent retry, or publication. Disk meets the in-process restoration requirement with its existing before-image rollback; a SQL adapter may use a native transaction.
-
-Canvas persistence DTOs and the write coordinator live under `modules/canvas/`; physical Workspace paths, name indexes, directory-handle arbitration, and boot migrations live under `modules/workspace/`; generic filesystem and Markdown codecs live under `utils/`. `canvasRoot()` validates the identifier and then verifies that the resolved Space directory remains a strict descendant of the active Workspace before any downstream Disk operation receives it. `module-boundaries.test.ts` enforces the storage dependency direction and prevents new consumers of the forwarding shims.
-
-Space deletion is serialized against composed blob puts by a writer-preferring admission coordinator and holds an active-Workspace lease across blob cleanup and structured destruction. `beginDelete()` acquires the exclusive session before blob I/O; `finish()` removes structured state, while `abort()` releases the fence without doing so. Blobs are swept before structure so a failed sweep can be retried while the Space record still names them. Puts already admitted may finish; a put queued behind a successful deletion rechecks existence and fails without recreating blobs, while a failed blob sweep leaves the record available for retry. Mutations through existing Space handles and repositories reject while deletion is active or queued; reads remain available for cleanup. Residual direct-filesystem capabilities such as ZIP import, RFS upload/delete, and external-note claim are outside this repository fence and remain blockers for a non-Disk profile.
+| Path                           | Responsibility                                                                                                                                                                                           |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ports/blob.ts`                | Backend-neutral `BlobStore` connection/scope contract for opaque bytes and bounded materialization leases.                                                                                               |
+| `ports/structured.ts`          | Backend-neutral `StructuredStore`, the `SpaceRepository` collection, and the `SpaceHandle` composite: record read/ordered write, nodes, changes, Tasks, events, and the extension substrate.             |
+| `ports/namespace.ts`           | The `<owner>.<name>` grammar for an extension namespace — the only thing storage validates about an extension.                                                                                           |
+| `ports/contracts/`             | Reusable Space-collection, node, Space-write, log, blob, extension, and store suites; guarantees are the minimum every adapter implements.                                                               |
+| `backends/disk/`               | Disk implementations plus before-image restoration for rejected in-process ordered batches; no journal or startup recovery. `space-tree.ts` holds the Disk-only Space directory capability — not a port. |
+| `backends/disk/legacy/`        | The legacy `CanvasStore` and its synchronous adapter primitives, bounded Workspace-qualified cache, and process-local node tombstones.                                                                   |
+| `compatibility/canvas.ts`      | Residual Disk reads plus direct-module create/delete test fixtures; lifecycle writers are not exported from the public storage barrel.                                                                   |
+| `space-lifecycle-admission.ts` | Backend-neutral, writer-preferring single-process coordinator shared by structured mutations and blob puts during a delete session.                                                                      |
+| `profile.ts` and `storage.ts`  | Backend selection, cross-axis validation, the Workspace-scoped staged mount, the `space(canvasId)` facade, blob scopes, and the blob-first deletion saga.                                                |
+| `capabilities.ts`              | Which product features a profile cannot serve, and why — consulted at startup and by each Disk-only feature's own refusal.                                                                               |
+| `testing.ts`                   | Mounts a real profile onto a temporary Workspace through the production lifecycle, so a product test is written once and run against every profile.                                                      |
+| `index.ts`                     | Public exports only; application code imports here rather than reaching into an adapter.                                                                                                                 |
+| `paths.ts`, `canvas-dirs.ts`   | Deprecated forwarding shims with no logic, retained only for high-fanout compatibility imports. The third, `canvas-store.ts`, reached zero importers and is gone.                                        |
+
+The Disk structured adapter and compatibility facade resolve the same cached legacy object, so migration does not create two in-memory authorities. All portable repository methods are async. `SpaceRepository` owns membership reads, idempotent World bootstrap, structured create/rename, and an exclusive `beginDelete()` session; composition holds that session across the existing blob-first delete saga and then calls `finish()` or `abort()`. Every Space-record write goes through `SpaceHandle.write`, which is the version-checked replacement with the node and delta batch attached; `SpaceHandle.read` reads only. `SpaceNodes.read` / `readMany` / `list` / `stream` return complete records plus opaque revision tokens without exposing filenames. `readMany` is the shape most readers want — a selection, a neighbourhood, one View — and keeps their cost proportional to the request rather than to the Space; `list` / `stream` stay for work that genuinely spans it, and `stream` delivers each record as it lands. One deliberate divergence: a record a scan cannot retrieve is omitted, where reading that id directly surfaces the failure. `write` preserves the old node mutations → Space record → optional delta order. When a normal in-process node → record → delta batch rejects, the adapter must restore that batch's prestate before returning the rejection. An explicit title rename remains the preceding ordered, best-effort boundary and is not rolled back with the batch. The port does not promise process-crash or power-loss recovery, a determinate result after an unknown remote outcome, multi-process serialization, idempotent retry, or publication. Disk meets the in-process restoration requirement with its existing before-image rollback; a SQL adapter may use a native transaction.
+
+Canvas persistence DTOs and the write coordinator live under `modules/canvas/`; Disk record paths, name indexes, and directory-handle arbitration live inside the Disk adapter; boot migrations remain under `modules/workspace/migrations/`; generic filesystem and Markdown codecs live under `utils/`. `canvasRoot()` validates the identifier and then verifies that the resolved Space directory remains a strict descendant of the active Workspace before any downstream Disk operation receives it. `module-boundaries.test.ts` enforces the storage dependency direction, keeps the deprecated forwarding-shim importer lists shrinking, pins the exact production consumer list of the Disk `diskTree` capability, and reads `product-boundary.test.ts` to reject Disk vocabulary in the suite that is supposed to prove portability.
+
+Space deletion is serialized against composed blob puts by a writer-preferring admission coordinator and holds an active-Workspace lease across blob cleanup and structured destruction. `beginDelete()` acquires the exclusive session before blob I/O; `finish()` removes structured state, while `abort()` releases the fence without doing so. Blobs are swept before structure so a failed sweep can be retried while the Space record still names them. Puts already admitted may finish; a put queued behind a successful deletion rechecks existence and fails without recreating blobs, while a failed blob sweep leaves the record available for retry. Mutations through existing Space handles and repositories reject while deletion is active or queued; reads remain available for cleanup. Residual direct-filesystem features — bundle import/export, reveal, the built-in file tools, external-note claim, and Windows handle coordination — are outside this repository fence; they are declared Disk-only in the capability matrix rather than treated as blockers, and off Disk they are unavailable rather than emulated.
 
 Retained Disk Space repository and handle instances, blob scopes, and legacy `CanvasStore` instances reject use after the active Workspace changes. Each `spaces()` call returns a fresh Workspace-bound handle and each read rescans current Disk state. The Workspace-qualified LRU is cleared and rebuilt on the next lookup after a switch. The delete-session contract covers overlapping operations through one configured backend instance. Disk realizes it with the shared process-local coordinator; it is not a multi-process transaction or distributed lock, and a SQL adapter must supply an equivalent backend-instance fence using its own mechanisms.
 
diff --git a/docs/proposals/multi-backend-storage.md b/docs/proposals/multi-backend-storage.md
index 454f9a6a6..208b4e1d7 100644
--- a/docs/proposals/multi-backend-storage.md
+++ b/docs/proposals/multi-backend-storage.md
@@ -1,7 +1,7 @@
 # Multi-Backend Storage
 
-Status: Phases 1–4.5 implemented; Phase 4.6 specified in §6.4 and §12.6
-Last updated: 2026-08-19
+Status: Phases 1–4.6 implemented
+Last updated: 2026-08-20
 
 > **Scope and decision confidence.** This proposal records the two-port
 > `StructuredStore` / `BlobStore` split and their target backend families as
@@ -48,14 +48,15 @@ Last updated: 2026-08-19
 > review are recorded in place, including the CAS race ordering (§12.2.5),
 > log-family interface segregation (§12.2.6), and retained-handle Workspace
 > guards (§12.2.4). Phase 4.5 moved storage-owned Disk layout behind the
-> storage boundary in PR #93 and is the newest implemented phase. Phase 4.6 is
-> specified in §6.4 and §12.6 and is **not implemented**: it is the whole
-> remaining bridge between the portable contracts and a second structured
-> adapter — application reads off `CanvasStore`, one `space(canvasId)` handle,
-> a disposition for every residual per-Space file, and a Workspace mount
-> lifecycle. No SQLite, Postgres, or Azure adapter exists on `main`. §12 is the
-> authoritative phase plan; the decision table in §2 marks what each phase
-> has actually settled.
+> storage boundary in PR #93. Phase 4.6 is specified in §6.4 and §12.6 and is
+> **implemented**: it is the whole bridge between the portable contracts and a
+> second structured adapter — production reads off `CanvasStore`, one
+> `space(canvasId)` handle joining both ports, a disposition acted on for every
+> residual per-Space file, a Workspace mount lifecycle, and a product-level
+> suite that runs against every profile in `PRODUCT_STORAGE_PROFILES`. No
+> SQLite, Postgres, or Azure adapter exists on `main`; what Phase 5 owes is
+> listed in §12.7. §12 is the authoritative phase plan; the decision table in
+> §2 marks what each phase has actually settled.
 >
 > **Revision, 2026-08-19.** A first attempt at Phase 4.6 was written and
 > withdrawn without merging. It collapsed every consumer that needs a real
@@ -108,9 +109,9 @@ built above these ports, but its form is intentionally unresolved here.
 | Blob key, staging, deletion, and GC semantics          | Proposed / open           | Names are the existing `<artifactId><ext>` keys; `deleteAll()` covers Space destruction. Staging, reference counting, and GC remain undesigned. Per-key deletion stays out of the public port, but the absence of any cleanup path is what makes atomic replace mandatory (§6.2).                                                                                                          |
 | Space-handle identity and caching                      | **Corrected** (P1)        | `space(id)` returning a stable handle is bounded by the LRU behind it, not guaranteed. In-memory tombstones and the filename index are therefore adapter-local caches, never durable state (§12.1.1, §12.2.4).                                                                                                                                                                             |
 | Backend selection scope                                | Open                      | Process-global today because the profile is read from env. Per-Workspace or per-Space selection has not been fixed.                                                                                                                                                                                                                                                                        |
-| Unified per-Space handle                               | **Settled direction**     | One composition-layer `space(canvasId)` vends every storage capability for one Space: its structured parts, its blob scope, and any backend-specific extras. The two ports stay independent and are joined above them, never inside one (§6.4.1).                                                                                                                                          |
-| Storage for owners outside this port                   | **Settled direction**     | The Space handle vends an isolated _substrate_ per namespace — a directory, a table prefix, a schema — and the owner brings its own store implementation and SQL. Storage owns namespace isolation and lifecycle only, and never sees the data (§6.4.4).                                                                                                                                   |
-| Disposition of residual per-Space files                | **Settled direction**     | Four outcomes, not one: Disk-only and unimplemented elsewhere; portable capability with a per-backend implementation; a structured record; or a blob. The withdrawn Phase 4.6 attempt applied the first of the four to all of them; §6.4.3 assigns each family individually and §12.6 builds them (§6.4.2).                                                                                |
+| Unified per-Space handle                               | **Accepted** (P4.6)       | One composition-layer `space(canvasId)` vends every storage capability for one Space: its structured parts, its blob scope, and any backend-specific extras. The two ports stay independent and are joined above them, never inside one (§6.4.1).                                                                                                                                          |
+| Storage for owners outside this port                   | **Accepted** (P4.6)       | The Space handle vends an isolated _substrate_ per namespace — a directory, a table prefix, a schema — and the owner brings its own store implementation and SQL. Storage owns namespace isolation and lifecycle only, and never sees the data (§6.4.4).                                                                                                                                   |
+| Disposition of residual per-Space files                | **Accepted** (P4.6)       | Four outcomes, not one: Disk-only and unimplemented elsewhere; portable capability with a per-backend implementation; a structured record; or a blob. Each family is assigned in §6.4.3 and acted on in §12.6 — A declared in a capability matrix, C on the extension substrate, D as blob scopes, B deferred to the adapter that needs it.                                                |
 | Logical filesystem view                                | Open                      | A possible `SpaceFileView` above both stores; name and contract are not accepted yet. §6.4 narrows what such a view would have to synthesize — named files become blobs — without deciding to build it.                                                                                                                                                                                    |
 | Real agent workspace                                   | Open                      | Materialized directory, OS mount, protocol-only access, or a combination remain under evaluation.                                                                                                                                                                                                                                                                                          |
 | Agent-authored filesystem write-back                   | Open                      | Read-only projection, explicit checkout/commit, and live bidirectional sync are alternatives, not decisions.                                                                                                                                                                                                                                                                               |
@@ -474,7 +475,7 @@ handle already writes — which is worth doing whenever it comes up.
 
 Every consumer that reaches a Space as a filesystem tree today, with its
 disposition. Every assignment is settled; what is deferred is _when_ each is
-built, not _where_ it goes — §12.6 builds most of them (§6.4.2, §12.7).
+built, not _where_ it goes — §12.6 built most of them (§6.4.2, §12.7).
 
 | Consumer                                                   | What it does today                                             | Disposition                                                                                                                                                                                                                                 |
 | ---------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -2231,7 +2232,7 @@ no working behavior moves. The `latestChatTs` field and its
 `lastSeenThreadCursor` plumbing survive the removal because they are the
 resume point such a digest would need.
 
-### 12.6 Phase 4.6 — one Space handle, backend-neutral application, and Workspace mount
+### 12.6 Phase 4.6 — one Space handle, backend-neutral application, and Workspace mount — **implemented**
 
 Phase 4.6 closes the whole application-side gap between the portable storage
 contracts and a second structured adapter. It contains no SQLite schema,
@@ -2249,7 +2250,41 @@ exit criterion has two halves:
 An earlier attempt at this phase satisfied the first half only, and reached the
 second by fencing the residual filesystem population behind a separate free
 function under a single disposition. §6.4 explains why that was one answer too
-few. This specification replaces it; nothing from the attempt is depended upon.
+few. This specification replaced it; nothing from the attempt was depended upon.
+
+**Implemented.** What landed matches the specification below, with four
+findings worth carrying forward because each was surfaced by building rather
+than by reading:
+
+- **`node-prompt` could not stay store-aware.** It is a pure merge that took a
+  `CanvasStore` solely to lazily read a record its caller had not supplied,
+  which made a pure function into a synchronous Disk dependency no async port
+  can satisfy. The record became an argument, and each caller now reads in the
+  shape its request has — which is what made `readMany` earn its place rather
+  than merely have one.
+- **A staged mount must capture what it replaces when it is staged.**
+  Committing a Workspace path detaches the mount that no longer describes it,
+  so a `commit()` reading the process holder at swap time finds nothing to
+  close and drops the previous connections. Invisible on Disk, whose `close()`
+  is a no-op; a connection leak the moment SQLite lands.
+- **A blob scope for the Space root cannot be a directory scope.** Its area is
+  shared with `space.json` and every node directory, so `list()` would claim
+  storage's own records and `deleteAll()` would remove the Space. The
+  `space-guide` scope is bounded by its member names instead — a fixed set is a
+  tighter namespace than a directory, not a looser one.
+- **The resurrection guard belonged in the port.** Several owners each carried
+  their own check that a Space directory still existed before writing ad-hoc
+  bookkeeping into it. `extension()` returning `null` for an absent Space
+  states it once, and the per-owner guards were deleted rather than moved.
+
+One item in scope below was **narrowed deliberately**. Upload scratch received
+its own `BlobScopeRef` kind, so the area is named, swept on delete, and free to
+diverge in retention — but its writers still reach it through the `fs-sandbox`
+path, because RFS upload is a streaming HTTP handler and path classification,
+not the bare `readFileSync`/`writeFile` §6.4.2's exception describes. Routing
+it through the port would have added machinery rather than retiring any: the
+sandbox still needs the physical path for the Disk-only file tools. It moves
+with RFS's path vocabulary (disposition B), not before.
 
 #### 12.6.1 Portable read completion
 
@@ -2344,6 +2379,14 @@ retires those plus one resolver in the memory sandbox. The new machinery is a
 union member and a directory constant per area. Rename and per-key delete stay
 unsupported, as they are today.
 
+Upload scratch got its scope kind — so the area is named, swept on delete, and
+free to diverge in retention — but its writers still reach it through the
+`fs-sandbox` path. RFS upload is a streaming HTTP handler plus path
+classification, not the bare `readFileSync` / `writeFile` the exception above
+describes, and routing it through the port would add machinery rather than
+retire any: the sandbox still needs the physical path for the Disk-only file
+tools. It moves with RFS's path vocabulary (**B**), not before.
+
 **B — deferred to the adapter that needs it.** The portable change-notification
 capability and RFS's backend-neutral path vocabulary are assigned but not
 built: change notification's only consumer today is the Disk-only external-note
@@ -2421,7 +2464,7 @@ shim-importer snapshots pin which ones do.
 
 One behavioural hardening rides along and is not implied by either half of the
 criterion: two Space directories carrying the same `canvasId` resolve last-wins
-today, and will raise from the directory scan. That makes a Finder-side
+today, and now raise from the directory scan. That makes a Finder-side
 duplication a loud failure of every catalogue read rather than a Space that
 silently resolves to an arbitrary copy.
 
@@ -2450,22 +2493,32 @@ guarantees.
    rejecting it until the required capability matrix is satisfied.
 
    The SQLite preview branch forks from Phase 4.5, so it does not yet satisfy
-   the port it will be rebased onto. What it owes against §12.6, concretely:
-   `SpaceRepository.ensureWorld()`; `SpaceNodes.readMany` / `list` / `stream`;
-   the `sqlite` case of the extension substrate (§6.4.4); an entry in
-   `PRODUCT_STORAGE_PROFILES`, which is what runs the product-level boundary
-   suite against it; and its place in the implemented-backend and
-   selectable-backend lists.
+   the port it will be rebased onto. What it owes against the implemented
+   §12.6, concretely:
+   - `SpaceRepository.ensureWorld()`, and a mount that survives being staged
+     against a Workspace that is not active yet;
+   - `SpaceNodes.readMany` / `list` / `stream`, agreeing with `read` about a
+     node — the node contract asserts exactly this;
+   - the `sqlite` case of `SpaceSubstrate`, plus destroying a namespace with
+     the Space, which on Disk falls out of placement and there will not;
+   - one blob-scope placement per `BlobScopeRef` kind, or an explicit refusal
+     for an area it does not serve;
+   - an entry in `PRODUCT_STORAGE_PROFILES`, which is what runs
+     `product-boundary.test.ts` against it, and its place in the
+     implemented-backend and selectable-backend lists.
 
    It owes **no** Space directory and no portable materialization. A backend
    that keeps Spaces in tables does not have a tree, and §6.4.2 makes that a
    declared outcome rather than something to fabricate: what it owes instead is
-   an entry in the capability matrix declaring the disposition-**A** families
-   unavailable, plus whatever disposition **B** its own consumers turn out to
-   need (§6.4.3). Its existing note that SQLite stays unselectable while
-   physical Disk reads, World bootstrap, blob placement, import/export, and
-   Workspace remounting have one authority only in the Disk profile is the same
-   list §12.6 resolves — some by porting, the rest by declaring.
+   a row in `capabilities.ts` for each disposition-**A** family, plus whatever
+   disposition **B** its own consumers turn out to need (§6.4.3). Its existing
+   note that SQLite stays unselectable while physical Disk reads, World
+   bootstrap, blob placement, import/export, and Workspace remounting have one
+   authority only in the Disk profile is the same list §12.6 resolved — some by
+   porting, the rest by declaring.
+
+   The honest measure of Phase 4.6 is how much of this list is _additive_.
+   Nothing above asks for a feature module to change.
 
 6. Migrate the currently synchronous Agenetes persistence ports without
    changing their persist-before-notify, sequence, and fencing semantics. This

From b0155d06005cece815ff27a5eb2f5b14425004f4 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 13:21:52 +0800
Subject: [PATCH 14/20] refactor(storage): close the last Disk-layout imports
 outside the boundary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The exit criterion says no production module outside `storage/` may name how
a backend stores a Space. Three still did, and each was a different kind of
leak rather than an oversight.

The external-note watcher read the Space record off the file beside `nodes/`.
That path read was equivalent only because Disk keeps the two together, and
"what does this Space contain" is a question every backend answers — so it
goes through the port. Reveal-nodes assembled the sidecar directory itself;
the Disk capability now answers "which folder holds the notes", which is what
having one owner for the layout is for.

Bundle import was the real one. It owned the staging location, the
title-derived directory name, the record filename, and the directory index
entry — all four are placement, and none of them are the `.huabu.zip` format
the route legitimately interprets. `stageSpaceImport` takes them, and the
route keeps unzipping, the manifest, and artifact-URL remapping.

Splitting it surfaced something worth naming: the bundle's record filename
and Disk's record filename are the same string for a historical reason, not a
shared one. One is a wire format frozen by every bundle already exported; the
other is how a backend files a record today. They are separate constants now,
because they drift the moment a backend that is not Disk exports a bundle.

With those gone, `storage/paths.js` has one production importer left and it is
a migration — exempt by construction, since rewriting a frozen historical
shape is the one legitimate reason to know a layout that is no longer current.
The guard the criterion asks for is now writable as specified: import-level,
repo-wide, migrations and tests exempt.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../server/src/modules/canvas/canvas.route.ts |  93 +++++--------
 .../modules/canvas/external-watcher.test.ts   |   8 +-
 .../src/modules/canvas/external-watcher.ts    |  20 +--
 .../storage/backends/disk/space-import.ts     | 124 ++++++++++++++++++
 .../storage/backends/disk/space-tree.ts       |  13 +-
 apps/server/src/modules/storage/index.ts      |   2 +
 .../modules/storage/module-boundaries.test.ts |  90 ++++++++++++-
 apps/server/src/modules/storage/storage.ts    |  15 +++
 8 files changed, 289 insertions(+), 76 deletions(-)
 create mode 100644 apps/server/src/modules/storage/backends/disk/space-import.ts

diff --git a/apps/server/src/modules/canvas/canvas.route.ts b/apps/server/src/modules/canvas/canvas.route.ts
index 1ea8f538d..1be700444 100644
--- a/apps/server/src/modules/canvas/canvas.route.ts
+++ b/apps/server/src/modules/canvas/canvas.route.ts
@@ -2,8 +2,8 @@
 // Licensed under the MIT license.
 
 import { spawn } from 'node:child_process';
-import { createWriteStream, existsSync, mkdirSync, renameSync } from 'node:fs';
-import { mkdir, readFile, rm, unlink, writeFile } from 'node:fs/promises';
+import { createWriteStream, existsSync, mkdirSync } from 'node:fs';
+import { mkdir, rm, unlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
@@ -43,20 +43,16 @@ import {
   WorldReferenceResolutionError,
 } from './world-reference-resolver.js';
 import { MAX_UPLOAD_BYTES } from '../../upload-limits.js';
-import { toSafeFilename } from '../../utils/naming.js';
 import { ARTIFACT_URL_REGEX } from '../artifact/utils.js';
 import { getPreprocessDispatcher, getProfile } from '../preprocessing/index.js';
 import { stripOfficeparserPreamble } from '../preprocessing/loaders/office-strip.js';
-import {
-  isWorldCanvasId,
-  refreshCanvasDirIndex,
-  registerCanvasDir,
-  suggestCanvasDir,
-} from '../storage/canvas-dirs.js';
+import { isWorldCanvasId } from '../storage/canvas-dirs.js';
 import {
   space,
   createSpace,
   deleteSpace,
+  stageSpaceImport,
+  unavailableCapabilityMessage,
   getStructuredStore,
   type CanvasFile,
   type NodeContent,
@@ -64,8 +60,6 @@ import {
   type UpdateNodeOutcome,
   updateNode,
 } from '../storage/index.js';
-import { nodesDir, SPACE_JSON_FILENAME } from '../storage/paths.js';
-import { getWorkspacePath } from '../workspace.js';
 
 import type { CanvasNodeType } from '@huabu/shared';
 import type {
@@ -1562,8 +1556,10 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     if (!(await space(canvasId).read())) {
       return reply.code(404).send({ message: 'Canvas not found' });
     }
-    const dir = nodesDir(canvasId);
-    if (!existsSync(dir)) {
+    // Disk-only, declared as `reveal-space-folder`: the feature *is* "show me
+    // this in Finder", so a backend without a folder has nothing to show.
+    const dir = space(canvasId).diskTree?.nodesDirectory();
+    if (dir === undefined || !existsSync(dir)) {
       return reply.code(404).send({ message: 'Nodes folder not found' });
     }
     // Fire-and-forget: `openInFileManager` is best-effort and never
@@ -1662,13 +1658,17 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
       // Stream the upload to a temp zip file
       const tmpZip = path.join(tmpdir(), `${createId('import')}.zip`);
       const targetCanvasId = createId('canvas');
-      // Extract into a hidden staging dir so `scanWorkspace()` ignores it
-      // (it skips dot-prefixed entries) and the as-yet-unrenamed dir cannot
-      // be picked up by `read()`'s self-heal as a canvas titled `<canvasId>`.
-      const stagingDir = path.join(
-        getWorkspacePath(),
-        `.import-${targetCanvasId}`,
-      );
+      // Where an imported Space lands is the backend's business — the
+      // staging location, the title-derived directory, the record filename,
+      // and the index entry are all layout. This route owns the `.huabu.zip`
+      // format and nothing else (proposal §12.6.2).
+      const staged = stageSpaceImport(targetCanvasId);
+      if (!staged) {
+        return reply.code(400).send({
+          message: unavailableCapabilityMessage('space-bundle-import'),
+        });
+      }
+      const stagingDir = staged.stagingDirectory;
       let stagingCleanedUp = false;
       try {
         await new Promise<void>((resolve, reject) => {
@@ -1734,64 +1734,33 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
           await writeFile(dest, new Uint8Array(buf));
         });
 
-        // Rewrite the topology file so canvasId matches the new directory.
-        // New bundles carry `space.json`; still accept legacy `canvas.json`
-        // exports and normalise them to the new name on the way in.
-        const stagedJsonPath = path.join(stagingDir, SPACE_JSON_FILENAME);
-        const legacyJsonPath = path.join(stagingDir, 'canvas.json');
-        const sourceJsonPath = existsSync(stagedJsonPath)
-          ? stagedJsonPath
-          : existsSync(legacyJsonPath)
-            ? legacyJsonPath
-            : null;
-        if (!sourceJsonPath) {
-          await rm(stagingDir, { recursive: true, force: true });
+        const parsed = await staged.readRecord();
+        if (!parsed) {
+          await staged.discard();
           stagingCleanedUp = true;
           return reply.code(400).send({
-            message: 'Invalid bundle: missing space.json',
+            message: 'Invalid bundle: missing Space record',
           });
         }
-        const raw = await readFile(sourceJsonPath, 'utf-8');
-        const parsed = JSON.parse(raw) as CanvasFile;
         const sourceCanvasId = parsed.canvasId;
         const importedManifest = manifest as ImportManifest | null;
         const targetTitle =
           importedManifest?.title ?? parsed.title ?? 'Imported canvas';
-        const finalDirName = suggestCanvasDir(targetTitle, targetCanvasId);
-        const safeFromTitle = toSafeFilename(targetTitle, targetCanvasId);
-        const dedupeSuffix =
-          finalDirName === safeFromTitle
-            ? ''
-            : finalDirName.slice(safeFromTitle.length);
-        const resolvedTitle =
-          dedupeSuffix === '' ? targetTitle : targetTitle + dedupeSuffix;
-
-        const remapped: CanvasFile = {
+
+        // Artifact URLs are the bundle's own vocabulary, so they are rewritten
+        // here; where the result is filed is not, so `publish` decides that —
+        // including the de-duplication suffix it may have to add to the title.
+        await staged.publish({
           ...parsed,
           canvasId: targetCanvasId,
-          title: resolvedTitle,
+          title: targetTitle,
           state: rewriteCanvasArtifactUrls(
             parsed.state,
             sourceCanvasId,
             targetCanvasId,
           ),
-        };
-        // Always persist under the new name so the storage layer (which
-        // addresses `space.json`) can find it; drop a legacy source file.
-        await writeFile(stagedJsonPath, JSON.stringify(remapped));
-        if (sourceJsonPath !== stagedJsonPath) {
-          await rm(sourceJsonPath, { force: true });
-        }
-
-        // Move the staged dir into its final, title-derived location so
-        // the on-disk basename matches the title and `read()` will not
-        // self-heal-overwrite the title with the staging dir basename on
-        // the next access.
-        const finalDir = path.join(getWorkspacePath(), finalDirName);
-        renameSync(stagingDir, finalDir);
+        });
         stagingCleanedUp = true;
-        registerCanvasDir(targetCanvasId, finalDirName, resolvedTitle);
-        refreshCanvasDirIndex();
 
         const response: ImportCanvasResponse = {
           canvasId: targetCanvasId,
diff --git a/apps/server/src/modules/canvas/external-watcher.test.ts b/apps/server/src/modules/canvas/external-watcher.test.ts
index b2b26e777..8203416e8 100644
--- a/apps/server/src/modules/canvas/external-watcher.test.ts
+++ b/apps/server/src/modules/canvas/external-watcher.test.ts
@@ -261,15 +261,17 @@ describe('openExternalNoteSession', () => {
     ]);
 
     const first = await openExternalNoteSession('canvas-a', vi.fn());
+    const afterFirst = spaceHandle.read.mock.calls.length;
     const second = await openExternalNoteSession('canvas-a', vi.fn());
 
     const readPaths = fileIO.readFile.mock.calls.map(([filePath]) => filePath);
     expect(
       readPaths.filter((filePath) => filePath.endsWith('.md')),
     ).toHaveLength(2);
-    expect(
-      readPaths.filter((filePath) => filePath.endsWith('space.json')),
-    ).toHaveLength(1);
+    // Topology comes from the Space record now, not a file beside `nodes/`,
+    // so the invariant is counted on the port: the second subscriber shares
+    // the first's scan and pays only for its own snapshot.
+    expect(spaceHandle.read.mock.calls.length - afterFirst).toBe(1);
     expect(fileIO.readdir).toHaveBeenCalledTimes(1);
     expect(first.snapshot).toHaveLength(2);
 
diff --git a/apps/server/src/modules/canvas/external-watcher.ts b/apps/server/src/modules/canvas/external-watcher.ts
index f9a4cb435..c20430521 100644
--- a/apps/server/src/modules/canvas/external-watcher.ts
+++ b/apps/server/src/modules/canvas/external-watcher.ts
@@ -35,7 +35,6 @@ import { parseFrontmatter } from '../../utils/markdown-frontmatter.js';
 import { listAllCanvasDirEntries } from '../storage/canvas-dirs.js';
 import { space } from '../storage/index.js';
 import { registerSpaceDirHandleOwner } from '../storage/index.js';
-import { SPACE_JSON_FILENAME } from '../storage/paths.js';
 import { getWorkspacePath, isWorkspaceConfigured } from '../workspace.js';
 
 import type { CanvasFile } from '../storage/index.js';
@@ -134,15 +133,20 @@ async function canvasNoteIds(canvasId: string): Promise<Set<string>> {
   return noteIdsFromCanvas(await space(canvasId).read());
 }
 
+/**
+ * The scan's view of which notes the Space already knows.
+ *
+ * Read through the port rather than off the record file beside `nodes/`. The
+ * path read was equivalent only because Disk keeps the two together, and this
+ * question — what does the Space contain — is one every backend answers.
+ * Failure degrades to "knows nothing", as before: a scan that cannot read
+ * topology surfaces every file rather than silently hiding some.
+ */
 async function readInitialCanvasNoteIds(
-  nodesPath: string,
+  canvasId: string,
 ): Promise<Set<string>> {
   try {
-    const raw = await readFile(
-      path.join(path.dirname(nodesPath), SPACE_JSON_FILENAME),
-      'utf8',
-    );
-    return noteIdsFromCanvas(JSON.parse(raw) as CanvasFile);
+    return await canvasNoteIds(canvasId);
   } catch {
     return new Set();
   }
@@ -682,7 +686,7 @@ async function runInitialScan(session: ActiveSpaceWatch): Promise<void> {
 
     let topology: Promise<Set<string>> | null = null;
     const knownNoteIds = (): Promise<Set<string>> =>
-      (topology ??= readInitialCanvasNoteIds(session.nodesPath));
+      (topology ??= readInitialCanvasNoteIds(session.canvasId));
 
     let nextIndex = 0;
     const worker = async (): Promise<void> => {
diff --git a/apps/server/src/modules/storage/backends/disk/space-import.ts b/apps/server/src/modules/storage/backends/disk/space-import.ts
new file mode 100644
index 000000000..b9bdf181f
--- /dev/null
+++ b/apps/server/src/modules/storage/backends/disk/space-import.ts
@@ -0,0 +1,124 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Disk bundle publication — where an imported Space lands.
+ *
+ * The route owns the `.huabu.zip` format: unzipping it, reading its manifest,
+ * remapping artifact URLs. That is a *public* format, and §12.6.2 explicitly
+ * lets a consumer interpret one. What it must not own is where the result goes
+ * on the active backend — the staging location that the Space scan is
+ * guaranteed to ignore, the title-derived directory name, the record filename,
+ * and the directory index entry. All four are this backend's layout, so they
+ * live here (proposal §12.5.2).
+ *
+ * Disk-only by construction, reached through `space(canvasId).diskTree`'s
+ * sibling on the barrel, and declared as `space-bundle-import` in the
+ * capability matrix.
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  refreshCanvasDirIndex,
+  registerCanvasDir,
+  suggestCanvasDir,
+} from './canvas-dirs.js';
+import { SPACE_JSON_FILENAME } from './layout.js';
+import { toSafeFilename } from '../../../../utils/naming.js';
+import { getWorkspacePath } from '../../../workspace.js';
+
+import type { CanvasFile } from '../../../canvas/persistence-types.js';
+
+/**
+ * The filename a bundle carries its record under, before this backend
+ * existed to disagree.
+ *
+ * Historically the same name Disk uses, and deliberately *not* the same
+ * constant: one is a wire format frozen by every bundle already exported, the
+ * other is how a backend files a record today. They drift the moment a backend
+ * that is not Disk exports one.
+ */
+const BUNDLE_RECORD_FILENAMES = [SPACE_JSON_FILENAME, 'canvas.json'] as const;
+
+export interface DiskSpaceImport {
+  /** Where the bundle's entries should be written. */
+  readonly stagingDirectory: string;
+  /** The record the bundle carried, or null when it has none. */
+  readRecord(): Promise<CanvasFile | null>;
+  /**
+   * Install the staged directory as a Space, returning the title actually
+   * allocated — which may carry a de-duplication suffix the caller did not
+   * ask for.
+   */
+  publish(record: CanvasFile): Promise<{ title: string | null }>;
+  /** Remove the staging directory. Idempotent. */
+  discard(): Promise<void>;
+}
+
+/**
+ * Open a staging area for one imported Space.
+ *
+ * The directory is hidden so `scanWorkspace()` skips it: an unpublished
+ * import must not be visible as a Space, and must not be picked up by the
+ * record reader's self-heal as one titled after its own directory.
+ */
+export function stageDiskSpaceImport(canvasId: string): DiskSpaceImport {
+  const stagingDirectory = path.join(getWorkspacePath(), `.import-${canvasId}`);
+
+  return {
+    stagingDirectory,
+
+    async readRecord(): Promise<CanvasFile | null> {
+      for (const name of BUNDLE_RECORD_FILENAMES) {
+        const candidate = path.join(stagingDirectory, name);
+        if (!existsSync(candidate)) continue;
+        return JSON.parse(await readFile(candidate, 'utf8')) as CanvasFile;
+      }
+      return null;
+    },
+
+    async publish(record: CanvasFile): Promise<{ title: string | null }> {
+      const requestedTitle = record.title;
+      const directoryName = suggestCanvasDir(requestedTitle, canvasId);
+      // `suggestCanvasDir` may append a de-duplication suffix. Carry it into
+      // the title so the name a user sees and the directory agree — otherwise
+      // the record reader's self-heal rewrites the title on first read.
+      const safeFromTitle = toSafeFilename(requestedTitle, canvasId);
+      const suffix =
+        directoryName === safeFromTitle
+          ? ''
+          : directoryName.slice(safeFromTitle.length);
+      const title =
+        suffix === '' || requestedTitle === null
+          ? requestedTitle
+          : requestedTitle + suffix;
+
+      // Written under this backend's name, whatever the bundle called it, and
+      // any other spelling removed so two records cannot disagree.
+      await writeFile(
+        path.join(stagingDirectory, SPACE_JSON_FILENAME),
+        JSON.stringify({ ...record, canvasId, title }),
+      );
+      for (const name of BUNDLE_RECORD_FILENAMES) {
+        if (name === SPACE_JSON_FILENAME) continue;
+        await rm(path.join(stagingDirectory, name), { force: true });
+      }
+
+      await mkdir(path.dirname(stagingDirectory), { recursive: true });
+      await rename(
+        stagingDirectory,
+        path.join(getWorkspacePath(), directoryName),
+      );
+      registerCanvasDir(canvasId, directoryName, title);
+      refreshCanvasDirIndex();
+      return { title };
+    },
+
+    async discard(): Promise<void> {
+      await rm(stagingDirectory, { recursive: true, force: true });
+    },
+  };
+}
diff --git a/apps/server/src/modules/storage/backends/disk/space-tree.ts b/apps/server/src/modules/storage/backends/disk/space-tree.ts
index 8de0047af..76676e11e 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tree.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.ts
@@ -19,7 +19,7 @@
  * the accessor.
  */
 
-import { canvasRoot } from './layout.js';
+import { canvasRoot, nodesDir } from './layout.js';
 import { getCanvasStore } from './legacy/canvas-store-cache.js';
 
 /** A node sidecar, as RFS and the file tools address one. */
@@ -57,6 +57,16 @@ export interface DiskSpaceTree {
    * would collapse to `nodes/<id>.md` and never match a label-named file.
    */
   nodeIdForPath(relativePath: string): string | null;
+  /**
+   * Where this Space's node sidecars are, for a feature that shows a user
+   * their own files.
+   *
+   * `directory()` plus a segment the caller would otherwise have to know. The
+   * point of the capability is that the layout has one owner, so a consumer
+   * asking "which folder holds the notes" gets an answer rather than assembles
+   * one.
+   */
+  nodesDirectory(): string;
   /**
    * Every sidecar filename currently claiming `nodeId`; empty when there is
    * no conflict.
@@ -75,6 +85,7 @@ export function diskSpaceTree(canvasId: string): DiskSpaceTree {
   return {
     canvasId,
     directory: () => canvasRoot(canvasId),
+    nodesDirectory: () => nodesDir(canvasId),
     nodeIdForPath: (relativePath: string) => {
       const filename = NODE_SIDECAR_RE.exec(relativePath)?.[1];
       if (filename === undefined) return null;
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index 107861816..554c649a8 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -74,6 +74,7 @@ export {
   mountStorage,
   setStorageForTesting,
   space,
+  stageSpaceImport,
   stageStorage,
   storageHealth,
 } from './storage.js';
@@ -84,6 +85,7 @@ export type {
   Storage,
 } from './storage.js';
 export type { DiskSpaceTree } from './backends/disk/space-tree.js';
+export type { DiskSpaceImport } from './backends/disk/space-import.js';
 export {
   parseStorageProfile,
   StorageProfileError,
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index ae908c93d..fbf1edf1e 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -402,6 +402,92 @@ describe('product boundary suite stays backend-blind', () => {
   });
 });
 
+/**
+ * Phase 4.6's exit criterion, at the import level (proposal §12.6.6).
+ *
+ * The `workspace module names no backend` group above pinned Phase 4.5's
+ * correction for one module. The criterion is wider: **no** production module
+ * outside `storage/` may name how a backend stores a Space, because that is
+ * exactly the knowledge a second adapter would have to re-satisfy.
+ *
+ * Migrations are exempt — they rewrite frozen historical on-disk shapes, which
+ * is the one legitimate reason to know a layout that is no longer current.
+ * Tests are exempt for the same reason they may name an adapter: a test that
+ * names one is choosing its subject.
+ */
+describe('no production module outside storage names a Disk layout', () => {
+  /** Members of `backends/disk/layout.ts` and the Disk directory index. */
+  const DISK_LAYOUT = [
+    'SPACE_JSON_FILENAME',
+    'WORLD_CANVAS_DIR_NAME',
+    'canvasJsonPath',
+    'nodesDir',
+    'nodeFilePath',
+    'ARTIFACTS_DIR_NAME',
+    'artifactsDir',
+    'artifactPath',
+    'HISTORY_DIR_NAME',
+    'historyDir',
+    'chatDir',
+    'tasksPath',
+    'eventsPath',
+    'deltaLogPath',
+    'changesPath',
+    'canvasRoot',
+    'spaceMemoryDir',
+    'spaceUploadDir',
+    'suggestCanvasDir',
+    'registerCanvasDir',
+    'renameCanvasDirOnDisk',
+  ];
+
+  it('imports no Disk layout symbol', () => {
+    const violations: string[] = [];
+    for (const file of sourceFiles) {
+      if (file.startsWith('modules/storage/')) continue;
+      if (file.endsWith('.test.ts')) continue;
+      if (file.startsWith('modules/workspace/migrations/')) continue;
+
+      // Import-level, deliberately: a local variable that happens to be
+      // called `artifactPath` is not a violation, while importing the symbol
+      // is. The check is about where knowledge comes from, not vocabulary.
+      const source = read(file);
+      const imported = new Set<string>();
+      for (const match of source.matchAll(
+        /import\s*(?:type\s*)?\{([^}]*)\}\s*from/g,
+      )) {
+        for (const raw of match[1].split(',')) {
+          const name = raw
+            .trim()
+            .replace(/^type\s+/, '')
+            .split(/\s+as\s+/)[0];
+          if (name) imported.add(name.trim());
+        }
+      }
+      for (const symbol of DISK_LAYOUT) {
+        if (imported.has(symbol)) violations.push(`${file} → ${symbol}`);
+      }
+    }
+    expect(violations).toEqual([]);
+  });
+
+  it('rejects a production import of the legacy CanvasStore', () => {
+    const violations = sourceFiles
+      .filter((file) => !file.startsWith('modules/storage/'))
+      .filter((file) => !file.endsWith('.test.ts'))
+      .filter((file) =>
+        specifiersOf(file).some((spec) => {
+          const target = resolveSpecifier(file, spec);
+          return target?.includes('legacy/canvas-store') === true;
+        }),
+      );
+
+    // The root forwarding shim that used to make this reachable had no
+    // importers left and was deleted; this keeps the path closed.
+    expect(violations).toEqual([]);
+  });
+});
+
 describe('structured write authority', () => {
   it('does not expose compatibility create/delete writers from the public barrel', () => {
     expect(read('modules/storage/index.ts')).not.toMatch(
@@ -488,8 +574,8 @@ describe('root forwarding shims', () => {
     'storage/paths.js': [
       'modules/canvas/canvas-content-cas.test.ts',
       'modules/canvas/canvas.route.test.ts',
-      'modules/canvas/canvas.route.ts',
-      'modules/canvas/external-watcher.ts',
+      // The one production importer left is a migration, which rewrites a
+      // frozen historical on-disk shape and is exempt by construction.
       'modules/workspace/migrations/migrate-acp-sessions.ts',
     ],
   };
diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts
index 29fdcf966..edc797e07 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -32,6 +32,7 @@ import {
   isWorkspaceConfigured,
 } from '../workspace.js';
 import { DiskBlobStore } from './backends/disk/blob-store.js';
+import { stageDiskSpaceImport } from './backends/disk/space-import.js';
 import { diskSpaceTree } from './backends/disk/space-tree.js';
 import { DiskStructuredStore } from './backends/disk/structured-store.js';
 import { spaceBlobScopes } from './ports/blob.js';
@@ -44,6 +45,7 @@ import {
 } from './profile.js';
 import { withSpacePutAdmission } from './space-lifecycle-admission.js';
 
+import type { DiskSpaceImport } from './backends/disk/space-import.js';
 import type { DiskSpaceTree } from './backends/disk/space-tree.js';
 import type {
   BlobInfo,
@@ -610,6 +612,19 @@ export async function storageHealth(): Promise<StorageHealth[]> {
   return Promise.all([storage.structured.health(), storage.blobs.health()]);
 }
 
+/**
+ * Open a staging area for one imported Space, or `null` off Disk.
+ *
+ * Bundle import is Disk-only and declared as such. It is not a member of
+ * {@link Space} because it addresses a Space that does not exist yet — there
+ * is nothing to hang it off until it has been published.
+ */
+export function stageSpaceImport(canvasId: string): DiskSpaceImport | null {
+  return ensure().profile.structured.kind === 'disk'
+    ? stageDiskSpaceImport(canvasId)
+    : null;
+}
+
 /**
  * Every storage capability for one Space — the shorthand call sites use.
  *

From 6724716b5c52917ab248a63ae65a50a781b2bb4d Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 13:24:06 +0800
Subject: [PATCH 15/20] docs(storage): name the Disk-only capabilities and
 their guard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two capabilities are reachable by name from outside the boundary — the Space
directory and bundle publication — and one guard keeps that list from growing.
Both were missing from the architecture doc's account of what a reader will
find.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/architecture/canvas-storage.md | 40 ++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/docs/architecture/canvas-storage.md b/docs/architecture/canvas-storage.md
index ba4df69d1..3d53885e4 100644
--- a/docs/architecture/canvas-storage.md
+++ b/docs/architecture/canvas-storage.md
@@ -40,6 +40,16 @@ indefinitely; a stuck preparation is terminated after 70 seconds with
 `WORKSPACE_ACTIVATION_IN_PROGRESS`. Managed-mode startup prepares
 synchronously before the Server accepts requests, then mounts.
 
+The Disk-only capabilities a feature can still reach are named for the backend
+that has them: `space(canvasId).diskTree` for the Space directory, the sidecar
+name a record carries, the notes folder, and the duplicate-sidecar hint;
+`stageSpaceImport(canvasId)` for where an imported bundle lands. Both are
+`null` off Disk. `module-boundaries.test.ts` pins the exact production consumer
+list of the first and rejects, repo-wide and at the import level, any
+production module outside `storage/` naming a Disk layout symbol — migrations
+excepted, since rewriting a frozen historical shape is the one legitimate
+reason to know a layout that is no longer current.
+
 **What is not portable is declared, not emulated.** Six features are about a
 filesystem rather than about storage — bundle export and import,
 reveal-in-file-manager, the built-in agent file tools, external-note
@@ -110,21 +120,21 @@ Key points:
 
 `apps/server/src/modules/storage/` has three layers plus its composition root:
 
-| Path                           | Responsibility                                                                                                                                                                                           |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ports/blob.ts`                | Backend-neutral `BlobStore` connection/scope contract for opaque bytes and bounded materialization leases.                                                                                               |
-| `ports/structured.ts`          | Backend-neutral `StructuredStore`, the `SpaceRepository` collection, and the `SpaceHandle` composite: record read/ordered write, nodes, changes, Tasks, events, and the extension substrate.             |
-| `ports/namespace.ts`           | The `<owner>.<name>` grammar for an extension namespace — the only thing storage validates about an extension.                                                                                           |
-| `ports/contracts/`             | Reusable Space-collection, node, Space-write, log, blob, extension, and store suites; guarantees are the minimum every adapter implements.                                                               |
-| `backends/disk/`               | Disk implementations plus before-image restoration for rejected in-process ordered batches; no journal or startup recovery. `space-tree.ts` holds the Disk-only Space directory capability — not a port. |
-| `backends/disk/legacy/`        | The legacy `CanvasStore` and its synchronous adapter primitives, bounded Workspace-qualified cache, and process-local node tombstones.                                                                   |
-| `compatibility/canvas.ts`      | Residual Disk reads plus direct-module create/delete test fixtures; lifecycle writers are not exported from the public storage barrel.                                                                   |
-| `space-lifecycle-admission.ts` | Backend-neutral, writer-preferring single-process coordinator shared by structured mutations and blob puts during a delete session.                                                                      |
-| `profile.ts` and `storage.ts`  | Backend selection, cross-axis validation, the Workspace-scoped staged mount, the `space(canvasId)` facade, blob scopes, and the blob-first deletion saga.                                                |
-| `capabilities.ts`              | Which product features a profile cannot serve, and why — consulted at startup and by each Disk-only feature's own refusal.                                                                               |
-| `testing.ts`                   | Mounts a real profile onto a temporary Workspace through the production lifecycle, so a product test is written once and run against every profile.                                                      |
-| `index.ts`                     | Public exports only; application code imports here rather than reaching into an adapter.                                                                                                                 |
-| `paths.ts`, `canvas-dirs.ts`   | Deprecated forwarding shims with no logic, retained only for high-fanout compatibility imports. The third, `canvas-store.ts`, reached zero importers and is gone.                                        |
+| Path                           | Responsibility                                                                                                                                                                                                                                        |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ports/blob.ts`                | Backend-neutral `BlobStore` connection/scope contract for opaque bytes and bounded materialization leases.                                                                                                                                            |
+| `ports/structured.ts`          | Backend-neutral `StructuredStore`, the `SpaceRepository` collection, and the `SpaceHandle` composite: record read/ordered write, nodes, changes, Tasks, events, and the extension substrate.                                                          |
+| `ports/namespace.ts`           | The `<owner>.<name>` grammar for an extension namespace — the only thing storage validates about an extension.                                                                                                                                        |
+| `ports/contracts/`             | Reusable Space-collection, node, Space-write, log, blob, extension, and store suites; guarantees are the minimum every adapter implements.                                                                                                            |
+| `backends/disk/`               | Disk implementations plus before-image restoration for rejected in-process ordered batches; no journal or startup recovery. `space-tree.ts` and `space-import.ts` hold the Disk-only Space directory and bundle-publication capabilities — not ports. |
+| `backends/disk/legacy/`        | The legacy `CanvasStore` and its synchronous adapter primitives, bounded Workspace-qualified cache, and process-local node tombstones.                                                                                                                |
+| `compatibility/canvas.ts`      | Residual Disk reads plus direct-module create/delete test fixtures; lifecycle writers are not exported from the public storage barrel.                                                                                                                |
+| `space-lifecycle-admission.ts` | Backend-neutral, writer-preferring single-process coordinator shared by structured mutations and blob puts during a delete session.                                                                                                                   |
+| `profile.ts` and `storage.ts`  | Backend selection, cross-axis validation, the Workspace-scoped staged mount, the `space(canvasId)` facade, blob scopes, and the blob-first deletion saga.                                                                                             |
+| `capabilities.ts`              | Which product features a profile cannot serve, and why — consulted at startup and by each Disk-only feature's own refusal.                                                                                                                            |
+| `testing.ts`                   | Mounts a real profile onto a temporary Workspace through the production lifecycle, so a product test is written once and run against every profile.                                                                                                   |
+| `index.ts`                     | Public exports only; application code imports here rather than reaching into an adapter.                                                                                                                                                              |
+| `paths.ts`, `canvas-dirs.ts`   | Deprecated forwarding shims with no logic, retained only for high-fanout compatibility imports. The third, `canvas-store.ts`, reached zero importers and is gone.                                                                                     |
 
 The Disk structured adapter and compatibility facade resolve the same cached legacy object, so migration does not create two in-memory authorities. All portable repository methods are async. `SpaceRepository` owns membership reads, idempotent World bootstrap, structured create/rename, and an exclusive `beginDelete()` session; composition holds that session across the existing blob-first delete saga and then calls `finish()` or `abort()`. Every Space-record write goes through `SpaceHandle.write`, which is the version-checked replacement with the node and delta batch attached; `SpaceHandle.read` reads only. `SpaceNodes.read` / `readMany` / `list` / `stream` return complete records plus opaque revision tokens without exposing filenames. `readMany` is the shape most readers want — a selection, a neighbourhood, one View — and keeps their cost proportional to the request rather than to the Space; `list` / `stream` stay for work that genuinely spans it, and `stream` delivers each record as it lands. One deliberate divergence: a record a scan cannot retrieve is omitted, where reading that id directly surfaces the failure. `write` preserves the old node mutations → Space record → optional delta order. When a normal in-process node → record → delta batch rejects, the adapter must restore that batch's prestate before returning the rejection. An explicit title rename remains the preceding ordered, best-effort boundary and is not rolled back with the batch. The port does not promise process-crash or power-loss recovery, a determinate result after an unknown remote outcome, multi-process serialization, idempotent retry, or publication. Disk meets the in-process restoration requirement with its existing before-image rollback; a SQL adapter may use a native transaction.
 

From 96debc6ad8d7cfac3af41d937897f6c465e75b76 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 18:12:38 +0800
Subject: [PATCH 16/20] refactor(storage): reach a Space's bytes the same way
 as its records
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`StructuredStore` vended a handle per Space while `BlobStore` made the
caller assemble a `BlobScopeRef` first — the same subject reached two
different ways, and the asymmetry showed up in the facade, where four
scope refs were built by hand beside the structured handle.

`BlobStore.space(canvasId)` now returns `SpaceBlobs`: one member per
user-visible area, named rather than tagged. The areas are what the
union's `kind`s already were, so nothing about placement, name bounding,
or the delete sweep changes — only how a caller says which one it means.

`Space` composes the two handles flat, so every durable part of a Space
sits at one level and which axis stores it stays this module's business.
The artifact area loses its unqualified spelling: `space(id).blobs`
became `space(id).artifacts`, beside `.guide`, `.memory`, and `.uploads`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ufq2A7GReTSpRdtApkpdNZ
---
 .../agent/conversation/prompt/attachments.ts  |  2 +-
 .../agent/tools/handlers/image-generation.ts  |  6 +-
 .../modules/artifact/artifact.route.test.ts   | 38 ++++++----
 .../src/modules/artifact/artifact.route.ts    | 12 ++--
 apps/server/src/modules/artifact/utils.ts     |  2 +-
 .../modules/canvas/canvas-content-cas.test.ts |  7 +-
 .../modules/canvas/canvas-executor.test.ts    |  4 +-
 .../src/modules/canvas/canvas-executor.ts     |  2 +-
 .../src/modules/canvas/canvas.route.test.ts   |  4 +-
 .../server/src/modules/canvas/canvas.route.ts |  4 +-
 .../modules/canvas/import-node-src.test.ts    |  6 +-
 .../src/modules/canvas/import-node-src.ts     |  4 +-
 .../src/modules/canvas/snapshot-nodes.ts      | 14 ++--
 .../interactive-view.route.ts                 |  2 +-
 .../interactive-view.service.ts               |  2 +-
 .../src/modules/preprocessing/dispatcher.ts   |  2 +-
 .../modules/preprocessing/pipeline.test.ts    |  2 +-
 .../src/modules/preprocessing/pipeline.ts     |  8 +--
 .../remote_fs/interactive-view.rfs.test.ts    |  2 +-
 .../disk/blob-store.rename-retry.test.ts      |  5 +-
 .../storage/backends/disk/blob-store.test.ts  | 17 ++---
 .../storage/backends/disk/blob-store.ts       | 69 ++++++++++--------
 .../backends/disk/storage-recovery.test.ts    | 15 ++--
 .../compatibility/delete-canvas.test.ts       | 64 +++++++++++------
 apps/server/src/modules/storage/index.ts      |  4 +-
 apps/server/src/modules/storage/ports/blob.ts | 70 +++++++++----------
 .../ports/contracts/blob-store.contract.ts    | 31 +++-----
 .../modules/storage/product-boundary.test.ts  | 12 ++--
 apps/server/src/modules/storage/storage.ts    | 68 ++++++++----------
 29 files changed, 246 insertions(+), 232 deletions(-)

diff --git a/apps/server/src/modules/agent/conversation/prompt/attachments.ts b/apps/server/src/modules/agent/conversation/prompt/attachments.ts
index 05389c52c..dc896e8d7 100644
--- a/apps/server/src/modules/agent/conversation/prompt/attachments.ts
+++ b/apps/server/src/modules/agent/conversation/prompt/attachments.ts
@@ -223,7 +223,7 @@ export async function buildAttachmentParts(
           if (resolvedCanvasId && resolvedFilename) {
             try {
               const bytes =
-                await space(resolvedCanvasId).blobs.read(resolvedFilename);
+                await space(resolvedCanvasId).artifacts.read(resolvedFilename);
               // Attachments are inlined as text; binary bytes simply
               // decode to mojibake and the URL-only branch is used instead.
               if (bytes) fileContent = bytes.toString('utf-8');
diff --git a/apps/server/src/modules/agent/tools/handlers/image-generation.ts b/apps/server/src/modules/agent/tools/handlers/image-generation.ts
index 966913750..4655bee5e 100644
--- a/apps/server/src/modules/agent/tools/handlers/image-generation.ts
+++ b/apps/server/src/modules/agent/tools/handlers/image-generation.ts
@@ -131,7 +131,7 @@ export async function handleGenerateImage(
   // ── Load reference artifacts upfront ──────────────────────────────────
   // Any missing/invalid ref is an early hard error — better than sending
   // a partial set to Azure and getting cryptic results.
-  const blobs = space(args.canvasId).blobs;
+  const artifacts = space(args.canvasId).artifacts;
   const refImages: Array<{ key: string; bytes: Buffer }> = [];
   for (const key of refs) {
     if (typeof key !== 'string' || !key.trim()) {
@@ -139,7 +139,7 @@ export async function handleGenerateImage(
         `Invalid reference artifact key: ${JSON.stringify(key)}. Use the bare \`src\` string returned by snapshot_nodes.`,
       );
     }
-    const bytes = await blobs.read(key);
+    const bytes = await artifacts.read(key);
     if (!bytes) {
       throw new Error(
         `Reference artifact "${key}" not found on canvas ${args.canvasId}. It may have been deleted.`,
@@ -272,7 +272,7 @@ export async function handleGenerateImage(
   // `canvas_commands` insert or embeds them in a note body — from
   // user-uploaded artifacts that should never be auto-collected.
   const name = `${createId('gen')}.png`;
-  await blobs.put(name, png);
+  await artifacts.put(name, png);
 
   // The requested size string ("auto" included) drives what we
   // report back; gpt-image-* generally honours the request size, and
diff --git a/apps/server/src/modules/artifact/artifact.route.test.ts b/apps/server/src/modules/artifact/artifact.route.test.ts
index 1bd48e187..fee9b55b6 100644
--- a/apps/server/src/modules/artifact/artifact.route.test.ts
+++ b/apps/server/src/modules/artifact/artifact.route.test.ts
@@ -86,9 +86,8 @@ function installDeleteBlock(canvasId: string): {
     init: () => current.blobs.init(),
     health: () => current.blobs.health(),
     close: () => current.blobs.close(),
-    scope(ref) {
-      const delegate = current.blobs.scope(ref);
-      return {
+    space(id) {
+      const observe = (delegate: BlobScope): BlobScope => ({
         put(name, body) {
           putCalls += 1;
           return delegate.put(name, body);
@@ -100,12 +99,19 @@ function installDeleteBlock(canvasId: string): {
         list: () => delegate.list(),
         materialize: (name) => delegate.materialize(name),
         async deleteAll() {
-          if (ref.canvasId === canvasId) {
+          if (id === canvasId) {
             started.resolve();
             await release.promise;
           }
           await delegate.deleteAll();
         },
+      });
+      const areas = current.blobs.space(id);
+      return {
+        artifacts: observe(areas.artifacts),
+        guide: observe(areas.guide),
+        memory: observe(areas.memory),
+        uploads: observe(areas.uploads),
       };
     },
   };
@@ -194,7 +200,7 @@ describe('artifact route', () => {
     });
 
     expect(upload.statusCode).toBe(500);
-    expect(await space('missing').blobs.list()).toEqual([]);
+    expect(await space('missing').artifacts.list()).toEqual([]);
     await app.close();
   });
 
@@ -234,7 +240,7 @@ describe('artifact route', () => {
       const upload = await uploading;
       expect(upload.statusCode).toBe(500);
       expect(blocker.putCalls()).toBe(0);
-      expect(await space('c1').blobs.list()).toEqual([]);
+      expect(await space('c1').artifacts.list()).toEqual([]);
     } finally {
       blocker.releaseDelete();
       blocker.restore();
@@ -244,7 +250,7 @@ describe('artifact route', () => {
 
   it('serves a byte range so media nodes can seek', async () => {
     const app = await buildApp();
-    await space('c1').blobs.put('a.png', png);
+    await space('c1').artifacts.put('a.png', png);
 
     const res = await app.inject({
       method: 'GET',
@@ -260,7 +266,7 @@ describe('artifact route', () => {
 
   it('answers 304 for an unchanged artifact', async () => {
     const app = await buildApp();
-    await space('c1').blobs.put('a.png', png);
+    await space('c1').artifacts.put('a.png', png);
 
     const first = await app.inject({
       method: 'GET',
@@ -295,12 +301,18 @@ describe('artifact route', () => {
         return { ok: false, kind: 'disk' };
       },
       async close() {},
-      scope() {
-        return {
+      space() {
+        const unavailable = {
           async head() {
             throw new Error('blob backend unavailable');
           },
         } as unknown as BlobScope;
+        return {
+          artifacts: unavailable,
+          guide: unavailable,
+          memory: unavailable,
+          uploads: unavailable,
+        };
       },
     };
     const restore = setStorageForTesting({ ...current, blobs: failingBlobs });
@@ -332,7 +344,7 @@ describe('artifact route', () => {
 
   it('clones an artifact into another canvas under a fresh key', async () => {
     const app = await buildApp();
-    await space('src-canvas').blobs.put('a.png', png);
+    await space('src-canvas').artifacts.put('a.png', png);
 
     const res = await app.inject({
       method: 'POST',
@@ -346,8 +358,8 @@ describe('artifact route', () => {
     expect(uri).toMatch(/\.png$/);
 
     // Destination owns its own copy; the source is untouched.
-    expect(await space('dst-canvas').blobs.read(uri)).toEqual(png);
-    expect(await space('src-canvas').blobs.read('a.png')).toEqual(png);
+    expect(await space('dst-canvas').artifacts.read(uri)).toEqual(png);
+    expect(await space('src-canvas').artifacts.read('a.png')).toEqual(png);
 
     await app.close();
   });
diff --git a/apps/server/src/modules/artifact/artifact.route.ts b/apps/server/src/modules/artifact/artifact.route.ts
index 1d9a8f70e..c544480e3 100644
--- a/apps/server/src/modules/artifact/artifact.route.ts
+++ b/apps/server/src/modules/artifact/artifact.route.ts
@@ -61,7 +61,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
     const name = `${id}${ext}`;
 
     try {
-      await space(canvasId).blobs.put(name, data.file);
+      await space(canvasId).artifacts.put(name, data.file);
     } catch (error) {
       request.log.error({ err: error }, 'Failed to stream artifact to storage');
       return reply.code(500).send({ message: 'Failed to save file' });
@@ -82,7 +82,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
     '/:canvasId/artifact/:filename',
     async (request, reply) => {
       const { canvasId, filename } = request.params;
-      const blobs = space(canvasId).blobs;
+      const artifacts = space(canvasId).artifacts;
       const safeName = path.basename(filename);
 
       // `.mhtml` snapshots are stored as proper multipart/related MHTML
@@ -91,7 +91,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
       // we strip the wrapper on the fly and serve the inner HTML as
       // `text/html` so no browser-side MHTML handler is required.
       if (safeName.toLowerCase().endsWith('.mhtml')) {
-        const buffer = await blobs.read(safeName);
+        const buffer = await artifacts.read(safeName);
         if (!buffer) {
           return reply.code(404).send({ message: 'Artifact not found' });
         }
@@ -115,7 +115,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
         );
       }
 
-      const served = await sendBlob(request, reply, blobs, safeName);
+      const served = await sendBlob(request, reply, artifacts, safeName);
       if (!served) {
         return reply.code(404).send({ message: 'Artifact not found' });
       }
@@ -151,7 +151,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
 
     let buffer: Buffer | null;
     try {
-      buffer = await space(srcCanvasId).blobs.read(srcKey);
+      buffer = await space(srcCanvasId).artifacts.read(srcKey);
     } catch (err) {
       request.log.error({ err }, 'Failed to read source artifact for clone');
       return reply
@@ -167,7 +167,7 @@ const artifactRoute: FastifyPluginAsync = async (fastify) => {
     const name = `${id}${ext}`;
 
     try {
-      await space(dstCanvasId).blobs.put(name, buffer);
+      await space(dstCanvasId).artifacts.put(name, buffer);
     } catch (err) {
       request.log.error({ err }, 'Failed to clone artifact');
       return reply
diff --git a/apps/server/src/modules/artifact/utils.ts b/apps/server/src/modules/artifact/utils.ts
index e27b69aa8..d5962c383 100644
--- a/apps/server/src/modules/artifact/utils.ts
+++ b/apps/server/src/modules/artifact/utils.ts
@@ -56,7 +56,7 @@ export async function resolveArtifactImageUrl(
   if (!canvasId || !filename) return url;
 
   try {
-    const buffer = await space(canvasId).blobs.read(filename);
+    const buffer = await space(canvasId).artifacts.read(filename);
     if (!buffer) return url;
     const ext = path.extname(filename).toLowerCase();
     // Never guess `image/png` for an unknown extension: callers forward this
diff --git a/apps/server/src/modules/canvas/canvas-content-cas.test.ts b/apps/server/src/modules/canvas/canvas-content-cas.test.ts
index bb0b55b5f..80ab39231 100644
--- a/apps/server/src/modules/canvas/canvas-content-cas.test.ts
+++ b/apps/server/src/modules/canvas/canvas-content-cas.test.ts
@@ -531,7 +531,12 @@ describe('artifact presence hydration', () => {
         return { ok: true, kind: 'disk' };
       },
       async close() {},
-      scope: () => scope,
+      space: () => ({
+        artifacts: scope,
+        guide: scope,
+        memory: scope,
+        uploads: scope,
+      }),
     };
   }
 
diff --git a/apps/server/src/modules/canvas/canvas-executor.test.ts b/apps/server/src/modules/canvas/canvas-executor.test.ts
index 67bd529f7..cf54e7269 100644
--- a/apps/server/src/modules/canvas/canvas-executor.test.ts
+++ b/apps/server/src/modules/canvas/canvas-executor.test.ts
@@ -273,7 +273,7 @@ describe('executeOnServer — MERGE_NODE_DATA CAS', () => {
       src: 'old.svg',
       content: '',
     });
-    await space('c1').blobs.put(
+    await space('c1').artifacts.put(
       'new.svg',
       Buffer.from(
         '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100"></svg>',
@@ -329,7 +329,7 @@ describe('executeOnServer — MERGE_NODE_DATA CAS', () => {
       src: 'pic.svg',
       content: '',
     });
-    await space('c1').blobs.put(
+    await space('c1').artifacts.put(
       'pic.svg',
       Buffer.from(
         '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100"></svg>',
diff --git a/apps/server/src/modules/canvas/canvas-executor.ts b/apps/server/src/modules/canvas/canvas-executor.ts
index 97b5eadc7..a8a9b47bd 100644
--- a/apps/server/src/modules/canvas/canvas-executor.ts
+++ b/apps/server/src/modules/canvas/canvas-executor.ts
@@ -368,7 +368,7 @@ async function aspectHeightForWidth(
   width: number,
 ): Promise<number | null> {
   try {
-    const dim = await readImageDimensions(space(canvasId).blobs, src);
+    const dim = await readImageDimensions(space(canvasId).artifacts, src);
     if (!dim?.width || !dim?.height || dim.width <= 0 || dim.height <= 0) {
       return null;
     }
diff --git a/apps/server/src/modules/canvas/canvas.route.test.ts b/apps/server/src/modules/canvas/canvas.route.test.ts
index c34a7a81a..6e5e68558 100644
--- a/apps/server/src/modules/canvas/canvas.route.test.ts
+++ b/apps/server/src/modules/canvas/canvas.route.test.ts
@@ -738,7 +738,7 @@ describe('Space export/import persistence', () => {
       change,
     ]);
     const blob = Buffer.from([0, 1, 2, 3, 255]);
-    await space('c1').blobs.put('asset.bin', blob);
+    await space('c1').artifacts.put('asset.bin', blob);
 
     const app = await buildApp();
     try {
@@ -790,7 +790,7 @@ describe('Space export/import persistence', () => {
       expect(await importedSpace.changes.read('thread-export')).toEqual(
         storedChanges,
       );
-      expect(await space(importedId).blobs.read('asset.bin')).toEqual(blob);
+      expect(await space(importedId).artifacts.read('asset.bin')).toEqual(blob);
     } finally {
       await app.close();
     }
diff --git a/apps/server/src/modules/canvas/canvas.route.ts b/apps/server/src/modules/canvas/canvas.route.ts
index 1be700444..634e663cf 100644
--- a/apps/server/src/modules/canvas/canvas.route.ts
+++ b/apps/server/src/modules/canvas/canvas.route.ts
@@ -330,7 +330,7 @@ async function singleArtifactProbe(
 ): Promise<(key: string) => boolean> {
   const key = extractArtifactKey(src);
   if (!key) return () => false;
-  const exists = (await space(canvasId).blobs.hasMany([key])).has(key);
+  const exists = (await space(canvasId).artifacts.hasMany([key])).has(key);
   return (candidate) => candidate === key && exists;
 }
 
@@ -513,7 +513,7 @@ async function hydrateNodeContent(
   const present =
     referenced.size === 0
       ? new Set<string>()
-      : await handle.blobs.hasMany([...referenced]);
+      : await handle.artifacts.hasMany([...referenced]);
   const artifactExists = (key: string): boolean => present.has(key);
 
   return nodes.map((node) => {
diff --git a/apps/server/src/modules/canvas/import-node-src.test.ts b/apps/server/src/modules/canvas/import-node-src.test.ts
index 5df3b819b..061b2f9ee 100644
--- a/apps/server/src/modules/canvas/import-node-src.test.ts
+++ b/apps/server/src/modules/canvas/import-node-src.test.ts
@@ -132,7 +132,7 @@ describe('importForeignNodeSources — web nodes', () => {
     // …whose file exists in the artifact store…
     expect(src).toBeDefined();
     if (src === undefined) throw new Error('Expected a rewritten web src');
-    expect(await space(canvasId).blobs.head(src)).not.toBeNull();
+    expect(await space(canvasId).artifacts.head(src)).not.toBeNull();
     // …and the staging upload was reclaimed (move semantics).
     expect(existsSync(uploadAbs)).toBe(false);
   });
@@ -224,7 +224,7 @@ describe('importForeignNodeSources — web nodes', () => {
     expect(src).toMatch(/^artifact-[^/]+\.html$/);
     expect(src).toBeDefined();
     if (src === undefined) throw new Error('Expected a rewritten web src');
-    expect(await space(canvasId).blobs.head(src)).not.toBeNull();
+    expect(await space(canvasId).artifacts.head(src)).not.toBeNull();
     expect(existsSync(uploadAbs)).toBe(false);
   });
 
@@ -269,7 +269,7 @@ describe('importForeignNodeSources — media nodes (regression)', () => {
     expect(src).toMatch(/^artifact-[^/]+\.png$/);
     expect(src).toBeDefined();
     if (src === undefined) throw new Error('Expected a rewritten image src');
-    expect(await space(canvasId).blobs.head(src)).not.toBeNull();
+    expect(await space(canvasId).artifacts.head(src)).not.toBeNull();
   });
 
   it('canonicalizes an artifact path that leaves and re-enters the Space', async () => {
diff --git a/apps/server/src/modules/canvas/import-node-src.ts b/apps/server/src/modules/canvas/import-node-src.ts
index 9a33d14f9..c018257fc 100644
--- a/apps/server/src/modules/canvas/import-node-src.ts
+++ b/apps/server/src/modules/canvas/import-node-src.ts
@@ -304,7 +304,7 @@ async function copyToArtifact(
     const id = createId('artifact');
     const key = `${id}${ext}`;
     const buffer = await readFile(absPath);
-    await space(canvasId).blobs.put(key, buffer);
+    await space(canvasId).artifacts.put(key, buffer);
 
     // Move semantics: reclaim RFS scratch uploads once they are safely
     // stored. Never delete user node files or other canvas content —
@@ -360,7 +360,7 @@ async function downloadToArtifact(
     }
     const ext = pickDownloadExt(pathname, contentType);
     const key = `${createId('artifact')}${ext}`;
-    await space(canvasId).blobs.put(key, buffer);
+    await space(canvasId).artifacts.put(key, buffer);
     return key;
   } catch (err) {
     log.warn({ err, url }, 'Failed to download online node src into artifacts');
diff --git a/apps/server/src/modules/canvas/snapshot-nodes.ts b/apps/server/src/modules/canvas/snapshot-nodes.ts
index faf621b69..92b7b3336 100644
--- a/apps/server/src/modules/canvas/snapshot-nodes.ts
+++ b/apps/server/src/modules/canvas/snapshot-nodes.ts
@@ -451,7 +451,7 @@ async function loadContextImage(
   if (!mimeType) return null;
   const { width, height } = nodeBoxSize(node);
   if (width <= 0 || height <= 0) return null;
-  const bytes = await handle.blobs.read(src);
+  const bytes = await handle.artifacts.read(src);
   if (!bytes) return null;
   return { node, resolvedSrc: src, bytes, mimeType, width, height };
 }
@@ -800,11 +800,11 @@ async function maybeResizeImageArtifact(
   src: string,
   maxEdge: number,
 ): Promise<{ src: string; width: number; height: number } | null> {
-  const blobs = handle.blobs;
+  const artifacts = handle.artifacts;
   const ext = path.extname(src).toLowerCase();
   const mimeType = IMAGE_EXT_MIME[ext];
   if (!mimeType) return null;
-  const bytes = await blobs.read(src);
+  const bytes = await artifacts.read(src);
   if (!bytes) return null;
   const dims = readImageDimensions(bytes, mimeType);
   if (!dims) return null;
@@ -816,7 +816,7 @@ async function maybeResizeImageArtifact(
   const originalStem = path.basename(src, path.extname(src));
   const id = `${originalStem}-resized-${maxEdge}`;
   const filename = `${id}.png`;
-  const cachedBytes = await blobs.read(filename);
+  const cachedBytes = await artifacts.read(filename);
   if (cachedBytes) {
     // Re-derive dimensions from the cached blob so the result is
     // accurate without paying for another resvg pass.
@@ -837,7 +837,7 @@ async function maybeResizeImageArtifact(
     dims.height,
     maxEdge,
   );
-  await blobs.put(filename, resized.png);
+  await artifacts.put(filename, resized.png);
   return { src: filename, width: resized.width, height: resized.height };
 }
 
@@ -1061,10 +1061,10 @@ export async function snapshotNodesToArtifacts(
         ? `sketch-raster-${fingerprint}`
         : `sketch-raster-${fingerprint}-${maxEdge}`;
     const filename = `${id}.png`;
-    const existing = await handle.blobs.head(filename);
+    const existing = await handle.artifacts.head(filename);
     if (!existing) {
       const png = await renderClusterPng(built.svg, built.width);
-      await handle.blobs.put(filename, png);
+      await handle.artifacts.put(filename, png);
     }
     results.push({
       src: filename,
diff --git a/apps/server/src/modules/interactive-view/interactive-view.route.ts b/apps/server/src/modules/interactive-view/interactive-view.route.ts
index d14e687b8..0eb09618d 100644
--- a/apps/server/src/modules/interactive-view/interactive-view.route.ts
+++ b/apps/server/src/modules/interactive-view/interactive-view.route.ts
@@ -84,7 +84,7 @@ const interactiveViewRoutes: FastifyPluginAsync = async (app) => {
       const sent = await sendBlob(
         request,
         reply,
-        space(params.data.canvasId).blobs,
+        space(params.data.canvasId).artifacts,
         resource.rendererArtifact,
       );
       if (!sent) {
diff --git a/apps/server/src/modules/interactive-view/interactive-view.service.ts b/apps/server/src/modules/interactive-view/interactive-view.service.ts
index cadedc5ec..917f64e82 100644
--- a/apps/server/src/modules/interactive-view/interactive-view.service.ts
+++ b/apps/server/src/modules/interactive-view/interactive-view.service.ts
@@ -363,7 +363,7 @@ export class InteractiveViewService {
       : null;
     const rendererExists = request.rendererArtifact.startsWith('upload/')
       ? stagedPath !== null && existsSync(stagedPath)
-      : Boolean(await space(canvasId).blobs.head(request.rendererArtifact));
+      : Boolean(await space(canvasId).artifacts.head(request.rendererArtifact));
     if (!rendererExists) {
       throw new InteractiveViewServiceError(
         'renderer_not_found',
diff --git a/apps/server/src/modules/preprocessing/dispatcher.ts b/apps/server/src/modules/preprocessing/dispatcher.ts
index 1f1652bb2..6e00db2e7 100644
--- a/apps/server/src/modules/preprocessing/dispatcher.ts
+++ b/apps/server/src/modules/preprocessing/dispatcher.ts
@@ -166,7 +166,7 @@ export class PreprocessDispatcher {
 
     const deps: PipelineDeps = {
       nodes: getStructuredStore().space(request.canvasId).nodes,
-      blobs: space(request.canvasId).blobs,
+      artifacts: space(request.canvasId).artifacts,
       provider: this.provider,
     };
 
diff --git a/apps/server/src/modules/preprocessing/pipeline.test.ts b/apps/server/src/modules/preprocessing/pipeline.test.ts
index 77f2d7a6a..e81ead721 100644
--- a/apps/server/src/modules/preprocessing/pipeline.test.ts
+++ b/apps/server/src/modules/preprocessing/pipeline.test.ts
@@ -35,7 +35,7 @@ function deps(release: () => Promise<void>) {
         canvasId: request.canvasId,
         read: async () => null,
       } as unknown as SpaceNodes,
-      blobs: { materialize, put } as unknown as BlobScope,
+      artifacts: { materialize, put } as unknown as BlobScope,
       provider: {} as ProviderManager,
     },
   };
diff --git a/apps/server/src/modules/preprocessing/pipeline.ts b/apps/server/src/modules/preprocessing/pipeline.ts
index e312dcc25..2d5f5ae93 100644
--- a/apps/server/src/modules/preprocessing/pipeline.ts
+++ b/apps/server/src/modules/preprocessing/pipeline.ts
@@ -39,7 +39,7 @@ const log = getLogger('preprocessing.pipeline');
 /** Dependencies injected into the pipeline runner. */
 export interface PipelineDeps {
   nodes: SpaceNodes;
-  blobs: BlobScope;
+  artifacts: BlobScope;
   provider: ProviderManager;
 }
 
@@ -106,7 +106,7 @@ async function runPipelineStages(
       // other blob reader takes bytes.
       const artifactName = ctx.resolved.artifactName;
       if (artifactName) {
-        const lease = await deps.blobs.materialize(artifactName);
+        const lease = await deps.artifacts.materialize(artifactName);
         if (lease) {
           leases.push(lease);
           ctx.resolved.filePath = lease.path;
@@ -176,7 +176,7 @@ async function runPipelineStages(
       ) {
         try {
           const artifactName = `${createId('artifact')}.pdf`;
-          const info = await deps.blobs.put(artifactName, ctx.extracted.rawPdf);
+          const info = await deps.artifacts.put(artifactName, ctx.extracted.rawPdf);
           ctx.resolved.artifactUri = info.name;
           ctx.resolved.artifactName = info.name;
         } catch (snapshotError) {
@@ -213,7 +213,7 @@ async function runPipelineStages(
               ? ctx.extracted.title
               : ctx.resolved.normalizedUri,
           );
-          await deps.blobs.put(artifactName, buffer);
+          await deps.artifacts.put(artifactName, buffer);
           // Inject the artifact key into metadata so the Normalize →
           // Persist chain writes it as a top-level YAML field on the
           // node sidecar. The web route reads `mhtmlArtifact` directly
diff --git a/apps/server/src/modules/remote_fs/interactive-view.rfs.test.ts b/apps/server/src/modules/remote_fs/interactive-view.rfs.test.ts
index 3f41c9b06..55c26b3dc 100644
--- a/apps/server/src/modules/remote_fs/interactive-view.rfs.test.ts
+++ b/apps/server/src/modules/remote_fs/interactive-view.rfs.test.ts
@@ -216,7 +216,7 @@ describe('Interactive View RFS resources', () => {
         code: 'renderer_not_found',
       });
 
-      await space('c1').blobs.put('view.html', Buffer.from('<p>view</p>'));
+      await space('c1').artifacts.put('view.html', Buffer.from('<p>view</p>'));
       const invalidState = await app.inject({
         method: 'POST',
         url: '/rfs/c1/interactive-views',
diff --git a/apps/server/src/modules/storage/backends/disk/blob-store.rename-retry.test.ts b/apps/server/src/modules/storage/backends/disk/blob-store.rename-retry.test.ts
index 23cb013ee..142e0806f 100644
--- a/apps/server/src/modules/storage/backends/disk/blob-store.rename-retry.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/blob-store.rename-retry.test.ts
@@ -38,10 +38,7 @@ describe('DiskBlobStore retry cleanup', () => {
     testState.renameAsync.mockRejectedValue(error);
 
     try {
-      const scope = new DiskBlobStore().scope({
-        kind: 'space-artifacts',
-        canvasId: 'canvas-under-test',
-      });
+      const scope = new DiskBlobStore().space('canvas-under-test').artifacts;
 
       await expect(scope.put('blocked.bin', Buffer.from('bytes'))).rejects.toBe(
         error,
diff --git a/apps/server/src/modules/storage/backends/disk/blob-store.test.ts b/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
index fdc8fb497..ba7317708 100644
--- a/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
@@ -28,7 +28,7 @@ describeBlobStoreContract('DiskBlobStore', () => {
   workspaceState.path = root;
   return {
     store: new DiskBlobStore(),
-    ref: { kind: 'space-artifacts', canvasId: 'canvas-under-test' },
+    canvasId: 'canvas-under-test',
     cleanup: () => rmSync(root, { recursive: true, force: true }),
   };
 });
@@ -54,10 +54,7 @@ describe('DiskBlobStore temp file hygiene', () => {
   });
 
   it('cleans up after both successful and failed writes', async () => {
-    const scope = new DiskBlobStore().scope({
-      kind: 'space-artifacts',
-      canvasId,
-    });
+    const scope = new DiskBlobStore().space(canvasId).artifacts;
 
     await scope.put('kept.bin', Buffer.from('fine'));
     await scope.put('streamed.bin', Readable.from([Buffer.from('also fine')]));
@@ -80,10 +77,7 @@ describe('DiskBlobStore temp file hygiene', () => {
   });
 
   it('cleans up siblings from concurrent writers to one key', async () => {
-    const scope = new DiskBlobStore().scope({
-      kind: 'space-artifacts',
-      canvasId: 'concurrent-canvas',
-    });
+    const scope = new DiskBlobStore().space('concurrent-canvas').artifacts;
 
     await Promise.all(
       Array.from({ length: 8 }, (_, i) =>
@@ -98,10 +92,7 @@ describe('DiskBlobStore temp file hygiene', () => {
 
   it('binds in-flight paths to their original workspace and rejects a held scope after activation', async () => {
     const otherRoot = mkdtempSync(path.join(tmpdir(), 'huabu-blob-switched-'));
-    const scope = new DiskBlobStore().scope({
-      kind: 'space-artifacts',
-      canvasId,
-    });
+    const scope = new DiskBlobStore().space(canvasId).artifacts;
     let signalStarted = (): void => {};
     const started = new Promise<void>((resolve) => {
       signalStarted = resolve;
diff --git a/apps/server/src/modules/storage/backends/disk/blob-store.ts b/apps/server/src/modules/storage/backends/disk/blob-store.ts
index 0a45f0516..9404f22a0 100644
--- a/apps/server/src/modules/storage/backends/disk/blob-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/blob-store.ts
@@ -4,9 +4,9 @@
 /**
  * Disk implementation of the blob port.
  *
- * Maps a canvas scope to `<canvasDir>/.artifacts/`, preserving the layout
- * the workspace format has always used: one file per blob, named by the
- * URL key, no manifest indirection.
+ * Maps each area of a Space to a directory under its Space folder, preserving
+ * the layout the workspace format has always used: one file per blob, named by
+ * the URL key, no manifest indirection.
  *
  * Each scope is bound to the workspace active when it is created. A fresh
  * scope follows a free-mode workspace switch; a retained scope rejects the
@@ -47,8 +47,8 @@ import type {
   BlobRange,
   BlobRead,
   BlobScope,
-  BlobScopeRef,
   BlobStore,
+  SpaceBlobs,
 } from '../../ports/blob.js';
 import type { StorageHealth } from '../../ports/common.js';
 import type { Readable } from 'node:stream';
@@ -66,32 +66,34 @@ function isTempEntry(entry: string): boolean {
   return entry.startsWith(TEMP_PREFIX);
 }
 
-/** Resolve a scope to its backing directory. */
+/** The areas of a Space, as this adapter places them. */
+type SpaceBlobArea = keyof SpaceBlobs;
+
 /**
- * Where one scope's bytes sit, and which names it owns there.
+ * Where one area's bytes sit, and which names it owns there.
  *
- * `members: null` means the directory *is* the scope — everything in it
- * belongs. A name list means the scope is bounded by its members instead, for
- * an area shared with files that are not blobs at all.
+ * `members: null` means the directory *is* the area — everything in it
+ * belongs. A name list means the area is bounded by its members instead, for
+ * a directory shared with files that are not blobs at all.
  */
 interface ScopePlacement {
   readonly directory: string;
   readonly members: readonly string[] | null;
 }
 
-function scopePlacement(ref: BlobScopeRef): ScopePlacement {
-  switch (ref.kind) {
-    case 'space-artifacts':
-      return { directory: artifactsDir(ref.canvasId), members: null };
-    case 'space-memory':
-      return { directory: spaceMemoryDir(ref.canvasId), members: null };
-    case 'space-upload':
-      return { directory: spaceUploadDir(ref.canvasId), members: null };
-    case 'space-guide':
+function scopePlacement(area: SpaceBlobArea, canvasId: string): ScopePlacement {
+  switch (area) {
+    case 'artifacts':
+      return { directory: artifactsDir(canvasId), members: null };
+    case 'memory':
+      return { directory: spaceMemoryDir(canvasId), members: null };
+    case 'uploads':
+      return { directory: spaceUploadDir(canvasId), members: null };
+    case 'guide':
       // The Space root, which also holds `space.json` and every node
-      // directory — so this scope is the guide names, not the folder.
+      // directory — so this area is the guide names, not the folder.
       return {
-        directory: canvasRoot(ref.canvasId),
+        directory: canvasRoot(canvasId),
         members: SPACE_GUIDE_BLOB_NAMES,
       };
   }
@@ -108,11 +110,13 @@ function isMissing(err: unknown): boolean {
 }
 
 class DiskBlobScope implements BlobScope {
-  readonly #ref: BlobScopeRef;
+  readonly #area: SpaceBlobArea;
+  readonly #canvasId: string;
   readonly #workspacePath: string;
 
-  constructor(ref: BlobScopeRef) {
-    this.#ref = ref;
+  constructor(area: SpaceBlobArea, canvasId: string) {
+    this.#area = area;
+    this.#canvasId = canvasId;
     this.#workspacePath = path.resolve(getWorkspacePath());
   }
 
@@ -120,14 +124,14 @@ class DiskBlobScope implements BlobScope {
     const active = path.resolve(getWorkspacePath());
     if (active !== this.#workspacePath) {
       throw new Error(
-        `DiskBlobScope(${this.#ref.canvasId}) belongs to an inactive workspace. ` +
+        `DiskBlobScope(${this.#canvasId}) belongs to an inactive workspace. ` +
           `Resolve a fresh scope after workspace activation.`,
       );
     }
     // Resolve once per operation, before its first await. Every later path in
     // that operation is derived from this absolute directory, so a workspace
     // switch cannot combine a temp in A with a destination in B.
-    return scopePlacement(this.#ref);
+    return scopePlacement(this.#area, this.#canvasId);
   }
 
   /** Names this scope owns in `dir`, given what is actually there. */
@@ -157,7 +161,7 @@ class DiskBlobScope implements BlobScope {
     const safe = normalizeBlobName(name);
     if (placement.members && !placement.members.includes(safe)) {
       throw new BlobNameError(
-        `"${safe}" is not a member of the ${this.#ref.kind} scope. ` +
+        `"${safe}" is not a member of the ${this.#area} area. ` +
           `It holds: ${placement.members.join(', ')}.`,
       );
     }
@@ -296,7 +300,7 @@ class DiskBlobScope implements BlobScope {
       return;
     }
     // Removing the directory would take the Space with it. Only the members
-    // are this scope's to delete.
+    // are this area's to delete.
     await Promise.all(
       placement.members.map((name) =>
         rm(blobPath(placement.directory, name), { force: true }),
@@ -309,7 +313,7 @@ export class DiskBlobStore implements BlobStore {
   readonly kind = 'disk' as const;
 
   async init(): Promise<void> {
-    // Scope directories are created on first write; nothing to prepare.
+    // Area directories are created on first write; nothing to prepare.
   }
 
   async health(): Promise<StorageHealth> {
@@ -318,7 +322,12 @@ export class DiskBlobStore implements BlobStore {
 
   async close(): Promise<void> {}
 
-  scope(ref: BlobScopeRef): BlobScope {
-    return new DiskBlobScope(ref);
+  space(canvasId: string): SpaceBlobs {
+    return {
+      artifacts: new DiskBlobScope('artifacts', canvasId),
+      guide: new DiskBlobScope('guide', canvasId),
+      memory: new DiskBlobScope('memory', canvasId),
+      uploads: new DiskBlobScope('uploads', canvasId),
+    };
   }
 }
diff --git a/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts b/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
index 1440f7b44..fc1b8ad45 100644
--- a/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
@@ -467,7 +467,7 @@ describe('Space lifecycle guards and reopen', () => {
       handle.changes.append('thread-1', [change('n1')]),
     ).rejects.toThrow(/missing Space/);
     await expect(
-      space('missing-space').blobs.put('x.bin', rejectedBuffer),
+      space('missing-space').artifacts.put('x.bin', rejectedBuffer),
     ).rejects.toThrow(/missing Space/);
 
     expect(rejectedBuffer.toString()).toBe('x');
@@ -479,7 +479,7 @@ describe('Space lifecycle guards and reopen', () => {
     const ended = once(body, 'end');
 
     await expect(
-      space('missing-stream-space').blobs.put('x.bin', body),
+      space('missing-stream-space').artifacts.put('x.bin', body),
     ).rejects.toThrow(/missing Space/);
     await ended;
 
@@ -504,7 +504,10 @@ describe('Space lifecycle guards and reopen', () => {
     const storedChanges = await first.changes.append('thread-1', [
       change('n1'),
     ]);
-    await space('reopen').blobs.put('payload.bin', Buffer.from('persisted'));
+    await space('reopen').artifacts.put(
+      'payload.bin',
+      Buffer.from('persisted'),
+    );
 
     resetStorageCache();
     const reopened = new DiskStructuredStore().space('reopen');
@@ -515,8 +518,8 @@ describe('Space lifecycle guards and reopen', () => {
       7,
     ]);
     expect(await reopened.changes.read('thread-1')).toEqual(storedChanges);
-    expect((await space('reopen').blobs.read('payload.bin'))?.toString()).toBe(
-      'persisted',
-    );
+    expect(
+      (await space('reopen').artifacts.read('payload.bin'))?.toString(),
+    ).toBe('persisted');
   });
 });
diff --git a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
index 93f893999..10050904e 100644
--- a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
+++ b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
@@ -20,7 +20,7 @@ import { artifactPath, canvasJsonPath } from '../backends/disk/layout.js';
 import { resetStorageCache } from '../backends/disk/legacy/canvas-store-cache.js';
 import { DiskStructuredStore } from '../backends/disk/structured-store.js';
 import { getCanvasStore } from '../index.js';
-import { spaceBlobScopes } from '../ports/blob.js';
+import { spaceBlobAreas } from '../ports/blob.js';
 import {
   composeStorage,
   space,
@@ -33,8 +33,8 @@ import type {
   BlobRange,
   BlobRead,
   BlobScope,
-  BlobScopeRef,
   BlobStore,
+  SpaceBlobs,
 } from '../ports/blob.js';
 import type { Readable } from 'node:stream';
 
@@ -57,6 +57,24 @@ vi.mock('../../workspace.js', () => ({
   },
 }));
 
+/** Every area of one Space, each wrapped the same way. */
+function wrapAreas(
+  blobs: SpaceBlobs,
+  wrap: (scope: BlobScope) => BlobScope,
+): SpaceBlobs {
+  return {
+    artifacts: wrap(blobs.artifacts),
+    guide: wrap(blobs.guide),
+    memory: wrap(blobs.memory),
+    uploads: wrap(blobs.uploads),
+  };
+}
+
+/** How many sweeps one Space deletion must perform. */
+const SPACE_AREA_COUNT = spaceBlobAreas(
+  new DiskBlobStore().space('probe'),
+).length;
+
 function writeCanvas(directory: string, canvasId: string, title: string): void {
   const root = path.join(workspaceState.path, directory);
   mkdirSync(root, { recursive: true });
@@ -101,10 +119,9 @@ class OrderRecordingBlobStore implements BlobStore {
     return this.inner.close();
   }
 
-  scope(ref: BlobScopeRef): BlobScope {
-    const scope = this.inner.scope(ref);
+  space(canvasId: string): SpaceBlobs {
     const seen = this.recordPresentAtSweep;
-    return {
+    return wrapAreas(this.inner.space(canvasId), (scope) => ({
       put: (name: string, body: Readable | Buffer): Promise<BlobInfo> =>
         scope.put(name, body),
       head: (name: string): Promise<BlobInfo | null> => scope.head(name),
@@ -116,10 +133,10 @@ class OrderRecordingBlobStore implements BlobStore {
       list: (): Promise<BlobInfo[]> => scope.list(),
       materialize: (name: string) => scope.materialize(name),
       deleteAll: async (): Promise<void> => {
-        seen.push(existsSync(canvasJsonPath(ref.canvasId)));
+        seen.push(existsSync(canvasJsonPath(canvasId)));
         await scope.deleteAll();
       },
-    };
+    }));
   }
 }
 
@@ -164,9 +181,8 @@ class ControllableBlobStore implements BlobStore {
     return this.#inner.close();
   }
 
-  scope(ref: BlobScopeRef): BlobScope {
-    const scope = this.#inner.scope(ref);
-    return {
+  space(canvasId: string): SpaceBlobs {
+    return wrapAreas(this.#inner.space(canvasId), (scope) => ({
       put: async (name: string, body: Readable | Buffer): Promise<BlobInfo> => {
         this.putCalls += 1;
         this.putStarted.resolve();
@@ -187,7 +203,7 @@ class ControllableBlobStore implements BlobStore {
         if (this.blockDeletes) await this.#deletesReleased.promise;
         await scope.deleteAll();
       },
-    };
+    }));
   }
 }
 
@@ -246,11 +262,11 @@ describe('deleteSpace composition', () => {
 
     // Blobs first: after the structured record is gone nothing names them,
     // so a failed sweep on a remote backend would strand them permanently.
-    // One sweep per user-visible area — a Space's bytes are spread across a
-    // scope each, and an unswept kind is an orphan on a backend where
-    // dropping the record does not remove the area they sit in.
+    // One sweep per user-visible area — a Space's bytes are spread across an
+    // area each, and an unswept one is an orphan on a backend where dropping
+    // the record does not remove the place they sit in.
     expect(blobs.recordPresentAtSweep).toEqual(
-      spaceBlobScopes('canvas-a').map(() => true),
+      Array.from({ length: SPACE_AREA_COUNT }, () => true),
     );
     expect(existsSync(artifactPath('canvas-a', 'art_1.png'))).toBe(false);
     expect(existsSync(canvasJsonPath('canvas-a'))).toBe(false);
@@ -321,7 +337,7 @@ describe('deleteSpace composition', () => {
     controlled.blockPuts = true;
     installBlobStore(controlled);
 
-    const putting = space('canvas-a').blobs.put(
+    const putting = space('canvas-a').artifacts.put(
       'in-flight.bin',
       Buffer.from('bytes'),
     );
@@ -348,7 +364,7 @@ describe('deleteSpace composition', () => {
     await putting;
     await expect(deleting).resolves.toEqual({ ok: true, reason: 'deleted' });
 
-    expect(controlled.deleteCalls).toBe(spaceBlobScopes('canvas-a').length);
+    expect(controlled.deleteCalls).toBe(SPACE_AREA_COUNT);
     expect(existsSync(canvasJsonPath('canvas-a'))).toBe(false);
     expect(existsSync(artifactPath('canvas-a', 'in-flight.bin'))).toBe(false);
   });
@@ -361,7 +377,7 @@ describe('deleteSpace composition', () => {
     const deleting = deleteSpace('canvas-a');
     await controlled.deleteStarted.promise;
     expect(workspaceState.leaseCount).toBe(1);
-    const putting = space('canvas-a').blobs.put(
+    const putting = space('canvas-a').artifacts.put(
       'too-late.bin',
       Buffer.from('orphan'),
     );
@@ -474,8 +490,14 @@ describe('deleteSpace composition', () => {
     controlled.blockPuts = true;
     installBlobStore(controlled);
 
-    const first = space('canvas-a').blobs.put('first.bin', Buffer.from('1'));
-    const second = space('canvas-a').blobs.put('second.bin', Buffer.from('2'));
+    const first = space('canvas-a').artifacts.put(
+      'first.bin',
+      Buffer.from('1'),
+    );
+    const second = space('canvas-a').artifacts.put(
+      'second.bin',
+      Buffer.from('2'),
+    );
 
     await vi.waitFor(() => expect(controlled.putCalls).toBe(2));
     controlled.releasePuts();
@@ -496,7 +518,7 @@ describe('deleteSpace composition', () => {
     await controlled.deleteStarted.promise;
 
     await expect(
-      space('canvas-b').blobs.put('independent.bin', Buffer.from('free')),
+      space('canvas-b').artifacts.put('independent.bin', Buffer.from('free')),
     ).resolves.toMatchObject({ name: 'independent.bin' });
     expect(existsSync(artifactPath('canvas-b', 'independent.bin'))).toBe(true);
 
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index 554c649a8..2265ee9f5 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -110,7 +110,7 @@ export {
   SPACE_GUIDE_BLOB_NAMES,
   SPACE_GUIDE_SKILL_NAME,
   SPACE_MEMORY_BLOB_NAME,
-  spaceBlobScopes,
+  spaceBlobAreas,
 } from './ports/blob.js';
 export type {
   BlobBackendKind,
@@ -119,8 +119,8 @@ export type {
   BlobRange,
   BlobRead,
   BlobScope,
-  BlobScopeRef,
   BlobStore,
+  SpaceBlobs,
 } from './ports/blob.js';
 export type { StorageHealth } from './ports/common.js';
 export type {
diff --git a/apps/server/src/modules/storage/ports/blob.ts b/apps/server/src/modules/storage/ports/blob.ts
index 14f2d6a0c..3f324dd75 100644
--- a/apps/server/src/modules/storage/ports/blob.ts
+++ b/apps/server/src/modules/storage/ports/blob.ts
@@ -4,10 +4,11 @@
 /**
  * Blob storage port — opaque bytes, not application records.
  *
- * The connection ({@link BlobStore}) is the primary object; a
- * {@link BlobScope} is a bounded namespace derived from it. Blob storage is
- * not canvas-specific — canvas scoping is one derived view, and new scope
- * kinds extend {@link BlobScopeRef} without changing the connection.
+ * The connection ({@link BlobStore}) is the primary object; it vends one
+ * {@link SpaceBlobs} handle per Space, mirroring how `StructuredStore` vends
+ * one {@link SpaceHandle} per Space. Both ports are reached the same way for
+ * the same reason: a Space is the unit the application addresses, and a port
+ * that made the caller assemble a descriptor first would be the odd one out.
  *
  * Artifact identity, ownership, MIME representation, and lifecycle are
  * application concerns; this port only moves bytes. Today the HTTP boundary
@@ -24,47 +25,45 @@ import type { Readable } from 'node:stream';
 export type BlobBackendKind = 'disk' | 'azure';
 
 /**
- * Identifies a bounded namespace of blobs within a connection.
+ * Every area of one Space that holds bytes.
  *
- * One kind per **user-visible area**, not one per Space. That distinction is
- * what keeps names flat: a Space's bytes live in several places a user can
- * tell apart — the artifacts the app writes, the guide they author, the memory
- * the agent keeps, the scratch an upload lands in — and the alternative to
- * naming those areas is hierarchical blob names, which §7.1 excluded for every
- * backend. A kind is a union member and one placement rule per adapter; a path
- * separator inside a name is a contract change.
+ * One member per **user-visible area**, not one bag per Space. That
+ * distinction is what keeps blob names flat: a Space's bytes live in several
+ * places a user can tell apart — the artifacts the app writes, the guide they
+ * author, the memory the agent keeps, the scratch an upload lands in — and the
+ * alternative to naming those areas is hierarchical blob names, which §7.1
+ * excluded for every backend. An area is a member here and one placement rule
+ * per adapter; a path separator inside a name is a contract change.
  *
  * It also lets retention diverge later — scratch is not an artifact — without
  * moving any bytes a second time.
- *
- * Adding a scope with no Space (workspace assets, agent scratch) extends this
- * type the same way; the connection interface is unaffected.
  */
-export type BlobScopeRef =
+export interface SpaceBlobs {
   /** Artifacts the application writes and the client fetches by key. */
-  | { kind: 'space-artifacts'; canvasId: string }
+  readonly artifacts: BlobScope;
   /**
    * User-authored guide documents at the Space root.
    *
    * Bounded by {@link SPACE_GUIDE_BLOB_NAMES} rather than by a directory,
    * because the area a user authors in *is* the Space root — which also holds
-   * storage's own record. A scope that claimed the whole directory would list
+   * storage's own record. An area that claimed the whole directory would list
    * `space.json` and delete the Space on `deleteAll()`. Naming the members is
    * what makes the boundary real, and a fixed set is a tighter namespace than
    * a directory, not a looser one.
    */
-  | { kind: 'space-guide'; canvasId: string }
+  readonly guide: BlobScope;
   /** The agent's private memory document for a Space. */
-  | { kind: 'space-memory'; canvasId: string }
+  readonly memory: BlobScope;
   /** Scratch an upload lands in before anything claims it. */
-  | { kind: 'space-upload'; canvasId: string };
+  readonly uploads: BlobScope;
+}
 
 /**
- * Every blob name the `space-guide` scope may hold.
+ * Every blob name the `guide` area may hold.
  *
  * Product vocabulary rather than adapter detail: these are the documents a
  * user is invited to author at the Space root, so the set belongs beside the
- * scope it defines.
+ * area it defines.
  */
 export const SPACE_GUIDE_SKILL_NAME = 'skill.md';
 
@@ -72,23 +71,19 @@ export const SPACE_GUIDE_BLOB_NAMES: readonly string[] = [
   SPACE_GUIDE_SKILL_NAME,
 ];
 
-/** The one blob in the `space-memory` scope: the agent's memory document. */
+/** The one blob in the `memory` area: the agent's memory document. */
 export const SPACE_MEMORY_BLOB_NAME = 'space.md';
 
 /**
- * Every scope holding bytes for one Space.
+ * Every area of a Space, as a list.
  *
- * Deletion has to sweep all of them, and a kind added without being swept
- * would orphan bytes on a backend where dropping the Space does not remove
- * the area they sit in. Derived here so the saga cannot fall behind the union.
+ * Deletion has to sweep all of them, and an area added without being swept
+ * would orphan bytes on a backend where dropping the Space does not remove the
+ * place they sit in. Written once here, beside the interface it enumerates,
+ * rather than restated by the saga.
  */
-export function spaceBlobScopes(canvasId: string): readonly BlobScopeRef[] {
-  return [
-    { kind: 'space-artifacts', canvasId },
-    { kind: 'space-guide', canvasId },
-    { kind: 'space-memory', canvasId },
-    { kind: 'space-upload', canvasId },
-  ];
+export function spaceBlobAreas(blobs: SpaceBlobs): readonly BlobScope[] {
+  return [blobs.artifacts, blobs.guide, blobs.memory, blobs.uploads];
 }
 
 export interface BlobInfo {
@@ -185,13 +180,14 @@ export interface BlobScope {
   deleteAll(): Promise<void>;
 }
 
-/** A connection to a blob backend. Process-wide; scopes are derived. */
+/** A connection to a blob backend. Process-wide; handles are derived. */
 export interface BlobStore {
   readonly kind: BlobBackendKind;
   init(): Promise<void>;
   health(): Promise<StorageHealth>;
   close(): Promise<void>;
-  scope(ref: BlobScopeRef): BlobScope;
+  /** The areas holding this Space's bytes. */
+  space(canvasId: string): SpaceBlobs;
 }
 
 /** Thrown when a blob name is not a usable single path segment. */
diff --git a/apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts b/apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts
index 2b40a5922..61539556b 100644
--- a/apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts
+++ b/apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts
@@ -30,11 +30,12 @@ import {
   SPACE_GUIDE_SKILL_NAME,
 } from '../blob.js';
 
-import type { BlobScope, BlobScopeRef, BlobStore } from '../blob.js';
+import type { BlobScope, BlobStore } from '../blob.js';
 
 export interface BlobContractHarness {
   store: BlobStore;
-  ref: BlobScopeRef;
+  /** The Space every case addresses. */
+  canvasId: string;
   /** Release any resources the harness allocated. */
   cleanup?: () => Promise<void> | void;
 }
@@ -63,7 +64,7 @@ export function describeBlobStoreContract(
     async function scope(): Promise<BlobScope> {
       harness = await createHarness();
       await harness.store.init();
-      return harness.store.scope(harness.ref);
+      return harness.store.space(harness.canvasId).artifacts;
     }
 
     afterEach(async () => {
@@ -72,8 +73,8 @@ export function describeBlobStoreContract(
     });
 
     /**
-     * A member-bounded scope is a real scope, not a filtered view of a
-     * directory. Disk maps `space-guide` onto the Space root — shared with
+     * A member-bounded area is a real scope, not a filtered view of a
+     * directory. Disk maps `guide` onto the Space root — shared with
      * `space.json` and every node directory — so a scope that answered for
      * the folder would list storage's own records and take the Space with it
      * on `deleteAll()`. These pin the boundary that makes the mapping safe.
@@ -82,10 +83,7 @@ export function describeBlobStoreContract(
       const h = await createHarness();
       harness = h;
       await h.store.init();
-      const guide = h.store.scope({
-        kind: 'space-guide',
-        canvasId: h.ref.canvasId,
-      });
+      const guide = h.store.space(h.canvasId).guide;
 
       await guide.put(SPACE_GUIDE_SKILL_NAME, Buffer.from('# guide'));
       expect(await guide.read(SPACE_GUIDE_SKILL_NAME)).toEqual(
@@ -108,11 +106,7 @@ export function describeBlobStoreContract(
       const h = await createHarness();
       harness = h;
       await h.store.init();
-      const artifacts = h.store.scope(h.ref);
-      const guide = h.store.scope({
-        kind: 'space-guide',
-        canvasId: h.ref.canvasId,
-      });
+      const { artifacts, guide } = h.store.space(h.canvasId);
       await artifacts.put('kept.bin', Buffer.from('artifact'));
       await guide.put(SPACE_GUIDE_SKILL_NAME, Buffer.from('# guide'));
 
@@ -383,16 +377,13 @@ export function describeBlobStoreContract(
       }
     });
 
-    it('isolates scopes from one another', async () => {
+    it('isolates Spaces and areas from one another', async () => {
       const s = await createHarness();
       harness = s;
       await s.store.init();
 
-      const a = s.store.scope(s.ref);
-      const b = s.store.scope({
-        kind: 'space-artifacts',
-        canvasId: 'other-canvas-id',
-      });
+      const a = s.store.space(s.canvasId).artifacts;
+      const b = s.store.space('other-canvas-id').artifacts;
 
       await a.put('shared-name.txt', Buffer.from('from a'));
       expect(await b.head('shared-name.txt')).toBeNull();
diff --git a/apps/server/src/modules/storage/product-boundary.test.ts b/apps/server/src/modules/storage/product-boundary.test.ts
index c7d8851e4..e034f0dd0 100644
--- a/apps/server/src/modules/storage/product-boundary.test.ts
+++ b/apps/server/src/modules/storage/product-boundary.test.ts
@@ -207,19 +207,19 @@ forEachProductProfile((profile: StorageProfile, label: string) => {
       const m = await seedSpace(canvasId);
       const handle = m.storage.space(canvasId);
 
-      await handle.blobs.put('artifact.bin', Buffer.from('artifact bytes'));
+      await handle.artifacts.put('artifact.bin', Buffer.from('artifact bytes'));
       await handle.memory.put(SPACE_MEMORY_BLOB_NAME, Buffer.from('# memory'));
       await handle.guide.put(SPACE_GUIDE_SKILL_NAME, Buffer.from('# guide'));
       await handle.uploads.put('staged.bin', Buffer.from('staged bytes'));
 
-      expect(await handle.blobs.read('artifact.bin')).toEqual(
+      expect(await handle.artifacts.read('artifact.bin')).toEqual(
         Buffer.from('artifact bytes'),
       );
       expect(await handle.memory.read(SPACE_MEMORY_BLOB_NAME)).toEqual(
         Buffer.from('# memory'),
       );
       // Areas are separate namespaces, so one area's name is not another's.
-      expect(await handle.blobs.read(SPACE_MEMORY_BLOB_NAME)).toBeNull();
+      expect(await handle.artifacts.read(SPACE_MEMORY_BLOB_NAME)).toBeNull();
       expect((await handle.uploads.list()).map((info) => info.name)).toEqual([
         'staged.bin',
       ]);
@@ -232,7 +232,7 @@ forEachProductProfile((profile: StorageProfile, label: string) => {
       await expect(
         m.storage
           .space('space-product-absent')
-          .blobs.put('orphan.bin', Buffer.from('x')),
+          .artifacts.put('orphan.bin', Buffer.from('x')),
       ).rejects.toThrow();
     });
 
@@ -323,7 +323,7 @@ forEachProductProfile((profile: StorageProfile, label: string) => {
       const canvasId = 'space-product-delete';
       const m = await seedSpace(canvasId);
       const handle = m.storage.space(canvasId);
-      await handle.blobs.put('artifact.bin', Buffer.from('bytes'));
+      await handle.artifacts.put('artifact.bin', Buffer.from('bytes'));
       await handle.memory.put(SPACE_MEMORY_BLOB_NAME, Buffer.from('# memory'));
 
       await expect(deleteSpace(canvasId)).resolves.toEqual({
@@ -336,7 +336,7 @@ forEachProductProfile((profile: StorageProfile, label: string) => {
       await expect(after.nodes.list()).resolves.toEqual(new Map());
       // Every area, not only artifacts: an unswept one is an orphan on a
       // backend where dropping the record does not remove the area.
-      expect(await after.blobs.read('artifact.bin')).toBeNull();
+      expect(await after.artifacts.read('artifact.bin')).toBeNull();
       expect(await after.memory.read(SPACE_MEMORY_BLOB_NAME)).toBeNull();
       await expect(m.storage.structured.spaces().list()).resolves.toEqual([]);
     });
diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts
index edc797e07..9db07cc19 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -35,7 +35,7 @@ import { DiskBlobStore } from './backends/disk/blob-store.js';
 import { stageDiskSpaceImport } from './backends/disk/space-import.js';
 import { diskSpaceTree } from './backends/disk/space-tree.js';
 import { DiskStructuredStore } from './backends/disk/structured-store.js';
-import { spaceBlobScopes } from './ports/blob.js';
+import { spaceBlobAreas } from './ports/blob.js';
 import {
   parseStorageProfile,
   requiresExplicitInit,
@@ -53,8 +53,8 @@ import type {
   BlobRange,
   BlobRead,
   BlobScope,
-  BlobScopeRef,
   BlobStore,
+  SpaceBlobs,
 } from './ports/blob.js';
 import type { StorageHealth } from './ports/common.js';
 import type {
@@ -132,38 +132,21 @@ export interface Storage {
  * One Space across every axis that holds part of it.
  *
  * A **composition-layer facade, not a port type**. `StructuredStore.space()`
- * keeps returning the structured-only {@link SpaceHandle}, `BlobStore.scope()`
- * keeps returning a {@link BlobScope}, and neither port imports the other.
- * They are joined here because this is the only object in the process that
- * holds both, and because this layer already owns every cross-store rule: the
- * blob-put precondition and the blob-first delete saga.
+ * returns the structured {@link SpaceHandle}, `BlobStore.space()` returns the
+ * {@link SpaceBlobs} areas, and neither port imports the other. They are
+ * joined here because this is the only object in the process that holds both,
+ * and because this layer already owns the one cross-store rule the join needs:
+ * bytes may only be added to a Space whose record exists.
  *
  * The join cannot move down into a port. The two axes are configured
  * independently, so a `SpaceHandle` that vended blobs would oblige the Disk
- * structured adapter to construct an Azure blob scope; deletion ordering
- * deliberately keeps remote blob I/O outside any database transaction; and
- * `BlobScopeRef` covers scopes that have no Space at all, which a blob store
- * reachable only through a Space handle could not serve.
+ * structured adapter to construct an Azure blob handle, and deletion ordering
+ * deliberately keeps remote blob I/O outside any database transaction.
+ *
+ * Every member is a durable part of one Space, flat: which axis stores a part
+ * is this module's business, not its callers' (§6.4.1).
  */
-export interface Space extends SpaceHandle {
-  /**
-   * This Space's artifacts, with the cross-store precondition applied.
-   *
-   * Bytes may only be added to a Space whose record exists. Reads and
-   * `deleteAll()` stay available for cleanup when a record has already gone.
-   *
-   * The unqualified name because artifacts are what almost every caller
-   * means. The other areas below are the same guarded scope over a different
-   * {@link BlobScopeRef} kind — one member each, so a caller reaches every
-   * area of a Space from the one handle rather than assembling a scope ref.
-   */
-  readonly blobs: BlobScope;
-  /** User-authored guide documents at the Space root (`skill.md`). */
-  readonly guide: BlobScope;
-  /** The agent's private memory document. */
-  readonly memory: BlobScope;
-  /** Scratch an upload lands in before anything claims it. */
-  readonly uploads: BlobScope;
+export interface Space extends SpaceHandle, SpaceBlobs {
   /**
    * Disk's directory for this Space. `null` on every other backend.
    *
@@ -178,6 +161,9 @@ export interface Space extends SpaceHandle {
 
 function composeSpace(storage: Storage, canvasId: string): Space {
   const handle = storage.structured.space(canvasId);
+  const blobs = storage.blobs.space(canvasId);
+  const guarded = (scope: BlobScope): BlobScope =>
+    guardedBlobScope(storage, canvasId, scope);
   return {
     canvasId: handle.canvasId,
     read: () => handle.read(),
@@ -187,10 +173,10 @@ function composeSpace(storage: Storage, canvasId: string): Space {
     tasks: handle.tasks,
     events: handle.events,
     extension: (namespace) => handle.extension(namespace),
-    blobs: guardedBlobScope(storage, { kind: 'space-artifacts', canvasId }),
-    guide: guardedBlobScope(storage, { kind: 'space-guide', canvasId }),
-    memory: guardedBlobScope(storage, { kind: 'space-memory', canvasId }),
-    uploads: guardedBlobScope(storage, { kind: 'space-upload', canvasId }),
+    artifacts: guarded(blobs.artifacts),
+    guide: guarded(blobs.guide),
+    memory: guarded(blobs.memory),
+    uploads: guarded(blobs.uploads),
     diskTree:
       storage.profile.structured.kind === 'disk'
         ? diskSpaceTree(canvasId)
@@ -527,8 +513,8 @@ export async function deleteSpace(
       // structured record does not remove the area they sit in, an unswept
       // kind is an orphan.
       await Promise.all(
-        spaceBlobScopes(canvasId).map((ref) =>
-          storage.blobs.scope(ref).deleteAll(),
+        spaceBlobAreas(storage.blobs.space(canvasId)).map((area) =>
+          area.deleteAll(),
         ),
       );
       return await started.session.finish();
@@ -542,7 +528,7 @@ export async function deleteSpace(
 }
 
 /**
- * Blob scope for one Space, with the cross-store precondition applied.
+ * One blob area, with the cross-store precondition applied.
  *
  * The raw BlobStore intentionally knows nothing about structured lifecycle,
  * so composition owns the one cross-store invariant: bytes may only be added
@@ -553,10 +539,12 @@ export async function deleteSpace(
  * one Space facade is composed entirely from the connections it was built
  * against — a scope that re-resolved the holder could outlive them.
  */
-function guardedBlobScope(storage: Storage, ref: BlobScopeRef): BlobScope {
-  const { canvasId } = ref;
+function guardedBlobScope(
+  storage: Storage,
+  canvasId: string,
+  delegate: BlobScope,
+): BlobScope {
   const workspacePath = activeWorkspacePath();
-  const delegate = storage.blobs.scope(ref);
 
   async function requireSpace(): Promise<void> {
     const record = await storage.structured.space(canvasId).read();

From f43a3cf41c6bee9cb8fffd669285c72cfa0dd99f Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 18:29:11 +0800
Subject: [PATCH 17/20] feat(workspace): serve one workspace per process,
 change it by restart
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A mount belonged to a Workspace, so storage carried `workspacePath` and a
staged-swap lifecycle — connections opened against a not-yet-active path,
an atomic publish, a captured mount to close afterwards, leases to stop an
operation being stranded mid-switch, and a stale-mount check on every
access. All of it existed to move a live process from workspace A to B.

Issue #126 says that is not a product requirement, and the price is
visible: every layer had to answer "which workspace am I looking at?"
before it could do its job, and a backend with no workspace at all —
Postgres plus Azure Blob — would have had to answer it too.

So the workspace is now fixed for a process. Storage mounts once, serves,
and closes: no `workspacePath`, no `stageStorage`/`StagedStorage`, no
stale-mount recovery, no operation lease, and the blob/structured
admission gate keys on the Space alone. Choosing a different folder saves
the choice and restarts — the desktop shell does it, since it owns both
`workspace.json` and the server child; a browser tab says so instead.

The shell hands its choice to the server as `HUABU_WORKSPACE_STARTUP`,
deliberately not `HUABU_WORKSPACE`: the operator's variable locks the
workspace, hides the path, and fails the boot when the folder cannot be
opened, which is right for a deployment and wrong for a user whose drive
is unplugged. A shell-chosen workspace that will not open leaves the
process unconfigured with the reason in `WorkspaceInfo.startupError`, so
the client shows the picker rather than the app being unusable.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ufq2A7GReTSpRdtApkpdNZ
---
 apps/desktop/src/main.ts                      |  34 ++-
 apps/desktop/src/preload.ts                   |   8 +
 .../src/modules/preprocessing/pipeline.ts     |   5 +-
 .../backends/disk/legacy/canvas-store.ts      |  10 +-
 .../storage/backends/disk/space-logs.ts       |   2 +-
 .../storage/backends/disk/space-nodes.test.ts |   7 +-
 .../backends/disk/space-repository.test.ts    |   6 +-
 .../storage/backends/disk/space-repository.ts |  32 +-
 .../storage/backends/disk/space-tasks.ts      |   2 +-
 .../storage/backends/disk/space-write.test.ts |   7 +-
 .../backends/disk/storage-recovery.test.ts    |   5 +-
 .../storage/backends/disk/structured-store.ts |  21 +-
 .../compatibility/delete-canvas.test.ts       |  22 +-
 apps/server/src/modules/storage/index.ts      |  10 +-
 .../storage/space-lifecycle-admission.ts      |  47 ++-
 .../src/modules/storage/storage.test.ts       | 156 ++++------
 apps/server/src/modules/storage/storage.ts    | 287 +++++-------------
 apps/server/src/modules/storage/testing.ts    |  31 +-
 .../src/modules/workspace-activation.test.ts  |  57 +++-
 .../src/modules/workspace-activation.ts       |  93 ++++--
 apps/server/src/modules/workspace.route.ts    |  10 +
 apps/server/src/modules/workspace.test.ts     | 152 +++++++---
 apps/server/src/modules/workspace.ts          | 259 ++++++++--------
 apps/server/src/server.ts                     |  12 +-
 apps/web/src/hooks/useElectron.ts             |   7 +
 apps/web/src/i18n/resources/en/common.json    |   5 +-
 apps/web/src/i18n/resources/zh-CN/common.json |   5 +-
 apps/web/src/store/workspaceStore.ts          |  77 ++++-
 packages/shared/src/types/api/workspace.ts    |  18 +-
 29 files changed, 716 insertions(+), 671 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 13e5a43d7..afcd7d480 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -456,9 +456,8 @@ function buildServerEnv(port: number): NodeJS.ProcessEnv {
 
   // Ensure the data directory exists so the server doesn't have to
   // race-condition on first-use creation. The workspace directory is
-  // intentionally NOT pre-created: in free mode the user picks it via
-  // the in-app UI (folder picker / path input), and the web client
-  // persists the selection across launches via localStorage.
+  // intentionally NOT pre-created: on first launch the user picks it via the
+  // in-app UI (folder picker / path input), and we remember it from then on.
   mkdirSync(dataDir, { recursive: true });
 
   if (IS_DEV && webDistPath && !existsSync(webDistPath)) {
@@ -469,8 +468,17 @@ function buildServerEnv(port: number): NodeJS.ProcessEnv {
     );
   }
 
-  // Notably absent: HUABU_WORKSPACE. Omitting it puts the server in
-  // free mode, so the web UI shows its workspace picker on first launch.
+  // The workspace the user last chose, handed to the server at fork.
+  //
+  // A server process serves one workspace for its lifetime, so this is where
+  // the choice takes effect — the shell owns both `workspace.json` and the
+  // child process, which makes it the only thing that can apply a new one.
+  // Deliberately *not* `HUABU_WORKSPACE`: that is the operator's lock, and it
+  // hides the path, removes the picker, and fails the boot when the folder
+  // cannot be opened. This is the user's own choice, so it stays free mode —
+  // the picker remains available and a folder that has gone missing lands the
+  // user back on it instead of killing the app. Absent on first launch, which
+  // is what shows the picker then.
   //
   // External-agent (ACP) integration: the server embeds an `agentlet`
   // daemon supervisor (`DaemonSupervisor`) which fork()s the daemon
@@ -480,12 +488,15 @@ function buildServerEnv(port: number): NodeJS.ProcessEnv {
   // in dev it falls back to `external/agentlet/packages/local/dist/index.js`.
   // No env var injection is needed here \u2014 the resolver in
   // `daemon-supervisor.ts` covers both layouts.
+  const savedWorkspace = readWorkspaceStore().path;
+
   return {
     ...process.env,
     SERVER_PORT: String(port),
     HUABU_BIND_HOST: '127.0.0.1',
     HUABU_DATA_DIR: dataDir,
     HUABU_SECRET_BRIDGE: '1',
+    ...(savedWorkspace ? { HUABU_WORKSPACE_STARTUP: savedWorkspace } : {}),
     ...(webDistPath ? { WEB_DIST_PATH: webDistPath } : {}),
     NODE_ENV: IS_DEV ? 'development' : 'production',
   };
@@ -786,6 +797,19 @@ function registerWorkspaceIpc(): void {
     return next;
   });
 
+  /**
+   * Restart the app so the server comes up on the saved workspace.
+   *
+   * The renderer calls this after `workspace:set` when a workspace is already
+   * active. Relaunching the whole app rather than re-forking the server keeps
+   * one rule about what a running process is looking at: the window, its
+   * caches, and the server all start again on the same choice.
+   */
+  ipcMain.handle('workspace:restart', () => {
+    app.relaunch();
+    app.quit();
+  });
+
   ipcMain.handle('workspace:remove-recent', (_event, rawPath: unknown) => {
     if (typeof rawPath !== 'string') {
       throw new Error('workspace:remove-recent requires a string path');
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index c3efef445..5b5c866fb 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -87,6 +87,14 @@ contextBridge.exposeInMainWorld('electronBridge', {
         'workspace:remove-recent',
         path,
       ) as Promise<WorkspaceStoreSnapshot>,
+    /**
+     * Restart the app onto the saved workspace.
+     *
+     * A server process serves one workspace for its lifetime, so this is how a
+     * new choice takes effect. Never resolves — the app is on its way down.
+     */
+    restart: (): Promise<void> =>
+      ipcRenderer.invoke('workspace:restart') as Promise<void>,
   },
 
   window: {
diff --git a/apps/server/src/modules/preprocessing/pipeline.ts b/apps/server/src/modules/preprocessing/pipeline.ts
index 2d5f5ae93..ff9c09fd8 100644
--- a/apps/server/src/modules/preprocessing/pipeline.ts
+++ b/apps/server/src/modules/preprocessing/pipeline.ts
@@ -176,7 +176,10 @@ async function runPipelineStages(
       ) {
         try {
           const artifactName = `${createId('artifact')}.pdf`;
-          const info = await deps.artifacts.put(artifactName, ctx.extracted.rawPdf);
+          const info = await deps.artifacts.put(
+            artifactName,
+            ctx.extracted.rawPdf,
+          );
           ctx.resolved.artifactUri = info.name;
           ctx.resolved.artifactName = info.name;
         } catch (snapshotError) {
diff --git a/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts b/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
index 7d9b5d429..09e61197e 100644
--- a/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
@@ -387,7 +387,7 @@ export class CanvasStore {
         updatedAt: Date.now(),
       };
       try {
-        assertSpaceMutationAllowed(this.#workspacePath, this.canvasId);
+        assertSpaceMutationAllowed(this.canvasId);
         atomicWriteJson(canvasJsonPath(this.canvasId), next);
         patchCanvasDirTitle(this.canvasId, visibleTitle);
         return next;
@@ -410,7 +410,7 @@ export class CanvasStore {
 
   private writeRecord(canvas: CanvasFile, reconcileTombstones: boolean): void {
     this.assertActiveWorkspace();
-    assertSpaceMutationAllowed(this.#workspacePath, this.canvasId);
+    assertSpaceMutationAllowed(this.canvasId);
     if (canvas.canvasId !== this.canvasId) {
       throw new Error(
         `CanvasStore(${this.canvasId}) refusing to write canvas with id "${canvas.canvasId}"`,
@@ -467,7 +467,7 @@ export class CanvasStore {
    * the legacy reader can self-heal and rewrite them.
    */
   private readValidSpaceForMutation(operation: string): CanvasFile | null {
-    assertSpaceMutationAllowed(this.#workspacePath, this.canvasId);
+    assertSpaceMutationAllowed(this.canvasId);
     try {
       let record = readValidCanvasFile(
         canvasJsonPath(this.canvasId),
@@ -492,7 +492,7 @@ export class CanvasStore {
 
   private requireExistingSpaceForMutation(operation: string): void {
     if (this.nodeMutationTransactionDepth > 0) {
-      assertSpaceMutationAllowed(this.#workspacePath, this.canvasId);
+      assertSpaceMutationAllowed(this.canvasId);
       return;
     }
     const record = this.readValidSpaceForMutation(operation);
@@ -571,7 +571,7 @@ export class CanvasStore {
    */
   renameSelf(newTitle: string | null): RenameSelfResult {
     this.assertActiveWorkspace();
-    assertSpaceMutationAllowed(this.#workspacePath, this.canvasId);
+    assertSpaceMutationAllowed(this.canvasId);
     if (isWorldCanvasId(this.canvasId)) {
       return { ok: false, reason: 'forbidden' };
     }
diff --git a/apps/server/src/modules/storage/backends/disk/space-logs.ts b/apps/server/src/modules/storage/backends/disk/space-logs.ts
index 322966b84..e1d9f4354 100644
--- a/apps/server/src/modules/storage/backends/disk/space-logs.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-logs.ts
@@ -116,7 +116,7 @@ class DiskSpaceLogCoordinator {
   }
 
   private requireSpace(): void {
-    assertSpaceMutationAllowed(this.#workspacePath, this.#store.canvasId);
+    assertSpaceMutationAllowed(this.#store.canvasId);
     if (!readDiskSpaceRecord(this.#store)) {
       throw new Error(
         `Space logs(${this.#store.canvasId}) cannot write logs for a missing Space`,
diff --git a/apps/server/src/modules/storage/backends/disk/space-nodes.test.ts b/apps/server/src/modules/storage/backends/disk/space-nodes.test.ts
index 38ca626a9..b688e8fbb 100644
--- a/apps/server/src/modules/storage/backends/disk/space-nodes.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-nodes.test.ts
@@ -26,7 +26,7 @@ import { DiskSpaceNodes } from './space-nodes.js';
 import { DiskSpaceRepository } from './space-repository.js';
 import { DiskStructuredStore } from './structured-store.js';
 import { ensureWorldCanvasOnDisk } from './world-canvas.js';
-import { getWorkspacePath, setWorkspacePath } from '../../../workspace.js';
+import { setWorkspacePath } from '../../../workspace.js';
 import { describeSpaceNodesContract } from '../../ports/contracts/space-nodes.contract.js';
 
 import type { NodeContent } from '../../../canvas/persistence-types.js';
@@ -70,10 +70,7 @@ describe('DiskSpaceNodes', () => {
 
   beforeEach(async () => {
     workspacePath = freshWorkspace('huabu-node-repository-');
-    const created = await new DiskSpaceRepository(
-      getWorkspacePath(),
-      () => 1,
-    ).create({
+    const created = await new DiskSpaceRepository(() => 1).create({
       canvasId: 'canvas-a',
       title: 'Shared title',
     });
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
index caa3fe63d..250a61022 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
@@ -284,7 +284,7 @@ describe('DiskSpaceRepository lifecycle', () => {
   it('persists the de-duplicated title and reports explicit delete outcomes', async () => {
     const root = makeWorkspace('huabu-space-lifecycle-titles-');
     seedWorld(root);
-    const spaces = new DiskSpaceRepository(workspaceState.path, () => 1);
+    const spaces = new DiskSpaceRepository(() => 1);
     const first = await spaces.create({
       canvasId: 'canvas-a',
       title: 'Shared title',
@@ -319,7 +319,7 @@ describe('DiskSpaceRepository lifecycle', () => {
   it('refreshes membership before allocating around an externally imported Space', async () => {
     const root = makeWorkspace('huabu-space-lifecycle-imported-');
     seedWorld(root);
-    const spaces = new DiskSpaceRepository(workspaceState.path, () => 1);
+    const spaces = new DiskSpaceRepository(() => 1);
     await spaces.create({ canvasId: 'warm-index', title: 'Warm index' });
     const importedRoot = path.join(root, 'Taken');
     mkdirSync(importedRoot, { recursive: true });
@@ -354,7 +354,7 @@ describe('DiskSpaceRepository lifecycle', () => {
   it('keeps an allocated null title consistent in the record and the listing', async () => {
     const root = makeWorkspace('huabu-space-lifecycle-null-title-');
     seedWorld(root);
-    const spaces = new DiskSpaceRepository(workspaceState.path, () => 1);
+    const spaces = new DiskSpaceRepository(() => 1);
     await spaces.create({
       canvasId: 'physical-name-owner',
       title: 'null-title-space',
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.ts b/apps/server/src/modules/storage/backends/disk/space-repository.ts
index 3393b06d0..4fe1e245a 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.ts
@@ -67,17 +67,8 @@ export class DiskSpaceRepository implements SpaceRepository {
   readonly #workspacePath: string;
   readonly #now: () => number;
 
-  /**
-   * @param workspacePath Workspace this repository is bound to. Defaults to
-   *   the active one, which is what every caller outside the mount lifecycle
-   *   wants; the lifecycle passes the Workspace being staged, because
-   *   {@link ensureWorld} runs before that Workspace becomes active.
-   */
-  constructor(
-    workspacePath: string = getWorkspacePath(),
-    now: () => number = Date.now,
-  ) {
-    this.#workspacePath = path.resolve(workspacePath);
+  constructor(now: () => number = Date.now) {
+    this.#workspacePath = path.resolve(getWorkspacePath());
     this.#now = now;
   }
 
@@ -116,14 +107,10 @@ export class DiskSpaceRepository implements SpaceRepository {
    * World is a new member of the collection every later read resolves through.
    */
   async ensureWorld(): Promise<string> {
-    // Deliberately no active-Workspace assertion. Bootstrap is the one
-    // operation defined *before* its Workspace is active: the mount stages a
-    // connection, ensures the World, and only then commits the path and swaps
-    // (proposal §12.6.5). It works on the bound path directly rather than
-    // through the active-Workspace layout, so it is safe either way.
+    this.#assertActiveWorkspace();
     const canvasId = ensureWorldCanvasOnDisk(this.#workspacePath);
-    // Lazy invalidation only; the next read rescans whichever Workspace is
-    // active by then.
+    // A freshly created World is a new member of the collection every later
+    // read resolves through.
     refreshCanvasDirIndex();
     return canvasId;
   }
@@ -131,7 +118,7 @@ export class DiskSpaceRepository implements SpaceRepository {
   async create(input: SpaceCreateInput): Promise<SpaceCreateResult> {
     this.#assertActiveWorkspace();
     const canvasId = sanitizeId(input.canvasId, 'canvasId');
-    assertSpaceMutationAllowed(this.#workspacePath, canvasId);
+    assertSpaceMutationAllowed(canvasId);
     // Creation owns membership allocation. Refresh here rather than relying
     // on a caller having listed first: an externally imported Space must
     // participate in both stable-id and directory-name collision checks.
@@ -176,10 +163,7 @@ export class DiskSpaceRepository implements SpaceRepository {
     }
 
     const store = getCanvasStore(canvasId);
-    const release = await beginSpaceDeleteAdmission(
-      this.#workspacePath,
-      canvasId,
-    );
+    const release = await beginSpaceDeleteAdmission(canvasId);
     let state: 'open' | 'finishing' | 'closed' = 'open';
     const close = (): void => {
       if (state === 'closed') return;
@@ -219,7 +203,7 @@ export class DiskSpaceRepository implements SpaceRepository {
   async rename(input: SpaceRenameInput): Promise<SpaceRenameResult> {
     this.#assertActiveWorkspace();
     const canvasId = sanitizeId(input.canvasId, 'canvasId');
-    assertSpaceMutationAllowed(this.#workspacePath, canvasId);
+    assertSpaceMutationAllowed(canvasId);
     if (this.#isWorld(canvasId)) {
       return { ok: false, reason: 'world-forbidden' };
     }
diff --git a/apps/server/src/modules/storage/backends/disk/space-tasks.ts b/apps/server/src/modules/storage/backends/disk/space-tasks.ts
index 35e91e34e..bcc8d8728 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tasks.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tasks.ts
@@ -129,7 +129,7 @@ export class DiskSpaceTasks implements SpaceTasks {
   }
 
   #requireSpace(): void {
-    assertSpaceMutationAllowed(this.#workspacePath, this.#store.canvasId);
+    assertSpaceMutationAllowed(this.#store.canvasId);
     if (!readDiskSpaceRecord(this.#store)) {
       throw new Error(
         `Space Tasks(${this.#store.canvasId}) cannot write a missing Space`,
diff --git a/apps/server/src/modules/storage/backends/disk/space-write.test.ts b/apps/server/src/modules/storage/backends/disk/space-write.test.ts
index 62e454ed6..2707301f0 100644
--- a/apps/server/src/modules/storage/backends/disk/space-write.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-write.test.ts
@@ -23,7 +23,7 @@ import { DiskSpaceRepository } from './space-repository.js';
 import { createDiskSpaceWrite } from './space-write.js';
 import { DiskStructuredStore } from './structured-store.js';
 import { ensureWorldCanvasOnDisk } from './world-canvas.js';
-import { getWorkspacePath, setWorkspacePath } from '../../../workspace.js';
+import { setWorkspacePath } from '../../../workspace.js';
 import { describeSpaceWriteContract } from '../../ports/contracts/space-write.contract.js';
 
 import type {
@@ -95,10 +95,7 @@ describe('Disk ordered Space write', () => {
 
   beforeEach(async () => {
     workspacePath = freshWorkspace('huabu-ordered-writer-');
-    const created = await new DiskSpaceRepository(
-      getWorkspacePath(),
-      () => 1,
-    ).create({
+    const created = await new DiskSpaceRepository(() => 1).create({
       canvasId: 'canvas-a',
       title: 'Shared title',
     });
diff --git a/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts b/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
index fc1b8ad45..47858cbd2 100644
--- a/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/storage-recovery.test.ts
@@ -122,10 +122,7 @@ beforeEach(() => {
   workspaceState.path = root;
   resetStorageCache();
   restoreStorage = setStorageForTesting(
-    createStorage(
-      { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
-      root,
-    ),
+    createStorage({ structured: { kind: 'disk' }, blobs: { kind: 'disk' } }),
   );
 });
 
diff --git a/apps/server/src/modules/storage/backends/disk/structured-store.ts b/apps/server/src/modules/storage/backends/disk/structured-store.ts
index 665a0926e..af4f133cc 100644
--- a/apps/server/src/modules/storage/backends/disk/structured-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/structured-store.ts
@@ -29,7 +29,6 @@ import { createDiskSpaceRecordReader } from './space-record.js';
 import { DiskSpaceRepository } from './space-repository.js';
 import { DiskSpaceTasks } from './space-tasks.js';
 import { createDiskSpaceWrite } from './space-write.js';
-import { getWorkspacePath } from '../../../workspace.js';
 
 import type { StorageHealth } from '../../ports/common.js';
 import type { SpaceHandle, StructuredStore } from '../../ports/structured.js';
@@ -37,24 +36,6 @@ import type { SpaceHandle, StructuredStore } from '../../ports/structured.js';
 export class DiskStructuredStore implements StructuredStore {
   readonly kind = 'disk' as const;
 
-  readonly #workspacePath: string;
-
-  /**
-   * @param workspacePath Workspace this connection is mounted on. Defaults to
-   *   the active one, which is what every caller outside the mount lifecycle
-   *   means.
-   *
-   * The lifecycle passes it explicitly because a mount is staged *before* its
-   * Workspace becomes active: `ensureWorld()` has to bootstrap the Workspace
-   * being activated, not the one being replaced (proposal §12.6.5). The rest
-   * of the adapter still resolves through the active-Workspace layout and
-   * guards against a mismatch, so a staged connection is usable for bootstrap
-   * and nothing else until the swap.
-   */
-  constructor(workspacePath: string = getWorkspacePath()) {
-    this.#workspacePath = workspacePath;
-  }
-
   async init(): Promise<void> {
     // The workspace directory is prepared by `workspace-prepare.ts`; Space
     // directories are created on demand by the lifecycle repository.
@@ -67,7 +48,7 @@ export class DiskStructuredStore implements StructuredStore {
   async close(): Promise<void> {}
 
   spaces(): DiskSpaceRepository {
-    return new DiskSpaceRepository(this.#workspacePath);
+    return new DiskSpaceRepository();
   }
 
   space(canvasId: string): SpaceHandle {
diff --git a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
index 10050904e..b89fdeb87 100644
--- a/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
+++ b/apps/server/src/modules/storage/compatibility/delete-canvas.test.ts
@@ -38,23 +38,11 @@ import type {
 } from '../ports/blob.js';
 import type { Readable } from 'node:stream';
 
-const workspaceState = vi.hoisted(() => ({ path: '', leaseCount: 0 }));
+const workspaceState = vi.hoisted(() => ({ path: '' }));
 
 vi.mock('../../workspace.js', () => ({
   getWorkspacePath: () => workspaceState.path,
-  acquireWorkspaceOperationLease: () => {
-    const workspacePath = workspaceState.path;
-    workspaceState.leaseCount += 1;
-    let released = false;
-    return Object.freeze({
-      workspacePath,
-      release: () => {
-        if (released) return;
-        released = true;
-        workspaceState.leaseCount -= 1;
-      },
-    });
-  },
+  isWorkspaceConfigured: () => workspaceState.path !== '',
 }));
 
 /** Every area of one Space, each wrapped the same way. */
@@ -215,7 +203,6 @@ function installBlobStore(next: BlobStore): void {
   restoreStorage = setStorageForTesting(
     composeStorage(
       { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
-      workspaceState.path,
       new DiskStructuredStore(),
       next,
     ),
@@ -224,7 +211,6 @@ function installBlobStore(next: BlobStore): void {
 
 beforeEach(() => {
   workspaceState.path = mkdtempSync(path.join(tmpdir(), 'huabu-delete-'));
-  workspaceState.leaseCount = 0;
   writeCanvas('.world', 'canvas-world', 'World');
   writeCanvas('Project A', 'canvas-a', 'Project A');
   refreshCanvasDirIndex();
@@ -234,7 +220,6 @@ beforeEach(() => {
   restoreStorage = setStorageForTesting(
     composeStorage(
       { structured: { kind: 'disk' }, blobs: { kind: 'disk' } },
-      workspaceState.path,
       new DiskStructuredStore(),
       blobs,
     ),
@@ -242,7 +227,6 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  expect(workspaceState.leaseCount).toBe(0);
   restoreStorage();
   resetStorageCache();
   rmSync(workspaceState.path, { recursive: true, force: true });
@@ -376,7 +360,6 @@ describe('deleteSpace composition', () => {
 
     const deleting = deleteSpace('canvas-a');
     await controlled.deleteStarted.promise;
-    expect(workspaceState.leaseCount).toBe(1);
     const putting = space('canvas-a').artifacts.put(
       'too-late.bin',
       Buffer.from('orphan'),
@@ -387,7 +370,6 @@ describe('deleteSpace composition', () => {
 
     controlled.releaseDeletes();
     await expect(deleting).resolves.toEqual({ ok: true, reason: 'deleted' });
-    expect(workspaceState.leaseCount).toBe(0);
     await expect(putting).rejects.toThrow(/missing Space/);
 
     expect(controlled.putCalls).toBe(0);
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index 2265ee9f5..b25faf2b6 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -66,24 +66,18 @@ export {
   createSpace,
   createStorage,
   deleteSpace,
-  detachStorage,
   getBlobStore,
   getStorage,
   getStructuredStore,
   initStorage,
   mountStorage,
+  resetStorage,
   setStorageForTesting,
   space,
   stageSpaceImport,
-  stageStorage,
   storageHealth,
 } from './storage.js';
-export type {
-  Space,
-  SpaceDeleteOutcome,
-  StagedStorage,
-  Storage,
-} from './storage.js';
+export type { Space, SpaceDeleteOutcome, Storage } from './storage.js';
 export type { DiskSpaceTree } from './backends/disk/space-tree.js';
 export type { DiskSpaceImport } from './backends/disk/space-import.js';
 export {
diff --git a/apps/server/src/modules/storage/space-lifecycle-admission.ts b/apps/server/src/modules/storage/space-lifecycle-admission.ts
index 260e7f8ab..650c69de9 100644
--- a/apps/server/src/modules/storage/space-lifecycle-admission.ts
+++ b/apps/server/src/modules/storage/space-lifecycle-admission.ts
@@ -96,64 +96,51 @@ class SpaceLifecycleGate {
 
 const gates = new Map<string, SpaceLifecycleGate>();
 
-function key(workspacePath: string, canvasId: string): string {
-  return `${workspacePath}\0${canvasId}`;
-}
-
-function gateFor(workspacePath: string, canvasId: string): SpaceLifecycleGate {
-  const gateKey = key(workspacePath, canvasId);
-  let gate = gates.get(gateKey);
+/**
+ * Keyed by Space alone.
+ *
+ * A process serves one Workspace for its lifetime, so a Space id already
+ * denotes one Space; a Workspace component in the key would distinguish
+ * nothing.
+ */
+function gateFor(canvasId: string): SpaceLifecycleGate {
+  let gate = gates.get(canvasId);
   if (!gate) {
     gate = new SpaceLifecycleGate();
-    gates.set(gateKey, gate);
+    gates.set(canvasId, gate);
   }
   return gate;
 }
 
-async function withPutAdmission<T>(
-  workspacePath: string,
+export async function withSpacePutAdmission<T>(
   canvasId: string,
   operation: () => Promise<T>,
 ): Promise<T> {
-  const gateKey = key(workspacePath, canvasId);
-  const gate = gateFor(workspacePath, canvasId);
+  const gate = gateFor(canvasId);
   try {
     return await gate.withPut(operation);
   } finally {
-    if (gate.idle && gates.get(gateKey) === gate) gates.delete(gateKey);
+    if (gate.idle && gates.get(canvasId) === gate) gates.delete(canvasId);
   }
 }
 
-export function withSpacePutAdmission<T>(
-  workspacePath: string,
-  canvasId: string,
-  operation: () => Promise<T>,
-): Promise<T> {
-  return withPutAdmission(workspacePath, canvasId, operation);
-}
-
 export async function beginSpaceDeleteAdmission(
-  workspacePath: string,
   canvasId: string,
 ): Promise<() => void> {
-  const gateKey = key(workspacePath, canvasId);
-  const gate = gateFor(workspacePath, canvasId);
+  const gate = gateFor(canvasId);
   const releaseGate = await gate.acquireDelete();
   let released = false;
   return () => {
     if (released) return;
     released = true;
     releaseGate();
-    if (gate.idle && gates.get(gateKey) === gate) gates.delete(gateKey);
+    if (gate.idle && gates.get(canvasId) === gate) gates.delete(canvasId);
   };
 }
 
 /** Reject a structured mutation once deletion is active or queued. */
-export function assertSpaceMutationAllowed(
-  workspacePath: string,
-  canvasId: string,
-): void {
-  if (gates.get(key(workspacePath, canvasId))?.deletionPending) {
+export function assertSpaceMutationAllowed(canvasId: string): void {
+  if (gates.get(canvasId)?.deletionPending) {
     throw new Error(
       `Cannot mutate Space "${canvasId}" while deletion is pending`,
     );
diff --git a/apps/server/src/modules/storage/storage.test.ts b/apps/server/src/modules/storage/storage.test.ts
index 8a38e4f18..a22f8f472 100644
--- a/apps/server/src/modules/storage/storage.test.ts
+++ b/apps/server/src/modules/storage/storage.test.ts
@@ -4,11 +4,11 @@
 /**
  * The Workspace mount lifecycle (proposal §12.6.5).
  *
- * What these cases are really about is the ordering guarantee: everything that
- * can fail happens while the previous Workspace is still serving, and the swap
- * that makes a new mount reachable cannot fail. That is only observable across
- * two Workspaces, so every case here drives a real Disk profile against two
- * temporary roots rather than a stub.
+ * A process serves one Workspace, so the lifecycle is mount, serve, close.
+ * What these cases pin is what "mounted" has to mean before anything is
+ * served — an opened connection on each axis and a World that exists — and
+ * that a mount which cannot reach that state is not published at all. Every
+ * case drives a real Disk profile against a temporary root rather than a stub.
  */
 
 import { existsSync, mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
@@ -25,10 +25,6 @@ vi.mock('../workspace.js', () => ({
     return workspaceState.path;
   },
   isWorkspaceConfigured: () => workspaceState.path !== '',
-  acquireWorkspaceOperationLease: () => ({
-    workspacePath: workspaceState.path,
-    release: () => {},
-  }),
 }));
 
 import { refreshCanvasDirIndex } from './backends/disk/canvas-dirs.js';
@@ -37,11 +33,11 @@ import {
   closeStorage,
   composeStorage,
   createStorage,
-  detachStorage,
   getStorage,
   initStorage,
+  mountStorage,
+  resetStorage,
   setStorageForTesting,
-  stageStorage,
 } from './storage.js';
 
 import type { BlobStore } from './ports/blob.js';
@@ -66,10 +62,10 @@ function makeWorkspace(prefix: string): string {
   return mkdtempSync(path.join(tmpdir(), prefix));
 }
 
-/** Activate `root` the way the synchronous switch does. */
+/** Activate `root` the way startup does, before anything is mounted. */
 function activate(root: string): void {
   workspaceState.path = root;
-  detachStorage();
+  resetStorage();
   resetStorageCache();
   refreshCanvasDirIndex();
 }
@@ -85,7 +81,7 @@ function seedWorld(root: string, record: unknown = WORLD_RECORD): void {
 }
 
 /** A mount whose connections record whether they were closed. */
-function countingStorage(root: string): {
+function countingStorage(): {
   storage: ReturnType<typeof composeStorage>;
   closed: () => number;
 } {
@@ -93,11 +89,10 @@ function countingStorage(root: string): {
   const count = async (): Promise<void> => {
     closes += 1;
   };
-  const real = createStorage(DISK, root);
+  const real = createStorage(DISK);
   return {
     storage: composeStorage(
       DISK,
-      root,
       { ...real.structured, close: count } as unknown as StructuredStore,
       { ...real.blobs, close: count } as unknown as BlobStore,
     ),
@@ -106,92 +101,68 @@ function countingStorage(root: string): {
 }
 
 afterEach(() => {
-  detachStorage();
+  resetStorage();
   workspaceState.path = '';
   resetStorageCache();
   refreshCanvasDirIndex();
 });
 
 describe('storage mount lifecycle', () => {
-  it('bootstraps the Workspace being staged, not the active one', async () => {
-    const active = makeWorkspace('huabu-mount-active-');
-    seedWorld(active);
+  it('mounts at startup when a Workspace is active', async () => {
+    const active = makeWorkspace('huabu-mount-startup-');
     activate(active);
-    const target = makeWorkspace('huabu-mount-target-');
-
-    const staged = await stageStorage(target, DISK);
 
-    // The staged Workspace got its World even though it is not active yet —
-    // the whole reason the connection is constructed with an explicit path.
-    expect(existsSync(path.join(target, '.world', 'space.json'))).toBe(true);
-    expect(staged.storage.workspacePath).toBe(target);
-    // Nothing about the active Workspace moved.
-    expect(getStorage().workspacePath).toBe(active);
+    const mounted = await initStorage(DISK);
 
-    await staged.abort();
+    expect(mounted).not.toBeNull();
+    expect(getStorage()).toBe(mounted);
+    // Startup meets an empty namespace on first run, and the mount is what
+    // bootstraps it.
+    expect(existsSync(path.join(active, '.world', 'space.json'))).toBe(true);
   });
 
-  it('leaves the previous mount serving when staging fails', async () => {
-    const active = makeWorkspace('huabu-mount-keep-active-');
-    seedWorld(active);
-    activate(active);
-    const before = getStorage();
+  it('validates the profile without mounting when no Workspace is active', async () => {
+    workspaceState.path = '';
 
+    // Free mode at startup: the profile has to be checkable before anyone has
+    // picked a folder, so this opens nothing rather than failing.
+    await expect(initStorage(DISK)).resolves.toBeNull();
+  });
+
+  it('publishes nothing when the World cannot be bootstrapped', async () => {
+    const active = makeWorkspace('huabu-mount-bad-world-');
     // An established World that is malformed is an integrity error, never a
     // signal to mint a replacement identity — so bootstrap refuses.
-    const target = makeWorkspace('huabu-mount-bad-world-');
-    seedWorld(target, { canvasId: 'broken' });
+    seedWorld(active, { canvasId: 'broken' });
+    activate(active);
 
-    await expect(stageStorage(target, DISK)).rejects.toThrow();
+    await expect(mountStorage(DISK)).rejects.toThrow();
 
-    expect(getStorage()).toBe(before);
-    expect(getStorage().workspacePath).toBe(active);
-    expect(workspaceState.path).toBe(active);
+    // A half-mounted Workspace is the one outcome this must not produce: the
+    // lazy rebuild below is a fresh attempt, not the failed mount published.
+    const rebuilt = getStorage();
+    await expect(rebuilt.structured.spaces().worldId()).rejects.toThrow();
   });
 
-  it('publishes the staged mount and closes the one it replaced', async () => {
-    const active = makeWorkspace('huabu-mount-swap-active-');
+  it('closes the mount it replaces', async () => {
+    const active = makeWorkspace('huabu-mount-replace-');
     seedWorld(active);
     activate(active);
-    const previous = countingStorage(active);
+    const previous = countingStorage();
     setStorageForTesting(previous.storage);
 
-    const target = makeWorkspace('huabu-mount-swap-target-');
-    const staged = await stageStorage(target, DISK);
-    expect(previous.closed()).toBe(0);
-
-    // The real sequence: the Workspace path and the mount are published
-    // together. Committing the path detaches the mount that no longer
-    // describes it, which is exactly the case that used to leave the replaced
-    // connections unclosed.
-    await staged.commit(() => {
-      workspaceState.path = target;
-      detachStorage();
-    });
-
-    expect(getStorage()).toBe(staged.storage);
-    // Both axes of the replaced mount are released.
-    expect(previous.closed()).toBe(2);
-  });
+    await mountStorage(DISK);
 
-  it('closes the staged connections on abort and keeps the active mount', async () => {
-    const active = makeWorkspace('huabu-mount-abort-active-');
-    seedWorld(active);
-    activate(active);
-    const before = getStorage();
-
-    const target = makeWorkspace('huabu-mount-abort-target-');
-    const staged = await stageStorage(target, DISK);
-    await staged.abort();
-
-    expect(getStorage()).toBe(before);
+    // Both axes of the replaced mount are released. On Disk `close()` is a
+    // no-op, so nothing here would notice a leak — SQLite would.
+    expect(previous.closed()).toBe(2);
   });
 
   it('closes the active mount on shutdown', async () => {
     const active = makeWorkspace('huabu-mount-close-');
     seedWorld(active);
     activate(active);
-    const mounted = countingStorage(active);
+    const mounted = countingStorage();
     setStorageForTesting(mounted.storage);
 
     await closeStorage();
@@ -199,40 +170,17 @@ describe('storage mount lifecycle', () => {
     expect(mounted.closed()).toBe(2);
   });
 
-  it('validates the profile without mounting when no Workspace is active', async () => {
-    workspaceState.path = '';
-
-    // Free mode at startup: the profile has to be checkable before anyone has
-    // picked a folder, so this opens nothing rather than failing.
-    await expect(initStorage(DISK)).resolves.toBeNull();
-  });
-
-  it('mounts at startup when a Workspace is already active', async () => {
-    const active = makeWorkspace('huabu-mount-managed-');
+  it('rebuilds after the mount is dropped', async () => {
+    const active = makeWorkspace('huabu-mount-reset-');
+    seedWorld(active);
     activate(active);
-
     const mounted = await initStorage(DISK);
 
-    expect(mounted?.workspacePath).toBe(active);
-    // Managed startup meets an empty namespace on first run, and the mount is
-    // what bootstraps it.
-    expect(existsSync(path.join(active, '.world', 'space.json'))).toBe(true);
-  });
+    resetStorage();
 
-  it('drops a mount left behind by a Workspace that moved underneath it', async () => {
-    const first = makeWorkspace('huabu-mount-drift-first-');
-    seedWorld(first);
-    activate(first);
-    expect(getStorage().workspacePath).toBe(first);
-
-    // The synchronous switch detaches; this asserts the guard behind it, for
-    // any path that changes the active Workspace without one.
-    const second = makeWorkspace('huabu-mount-drift-second-');
-    seedWorld(second);
-    workspaceState.path = second;
-    resetStorageCache();
-    refreshCanvasDirIndex();
-
-    expect(getStorage().workspacePath).toBe(second);
+    // Dropping the mount is what `commitWorkspacePath` does when a test moves
+    // between temporary Workspaces. Disk has nothing to open, so the next use
+    // rebuilds rather than refusing.
+    expect(getStorage()).not.toBe(mounted);
   });
 });
diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts
index 9db07cc19..30bb27295 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -8,29 +8,23 @@
  * validated {@link StorageProfile} and holds them for the process. This is
  * the only place that maps a backend kind to an adapter.
  *
- * A mount belongs to one Workspace. Switching Workspaces is therefore a
- * remount rather than a reconfiguration in place, and the lifecycle that does
- * it — {@link stageStorage} / {@link StagedStorage.commit} — exists so every
- * step that can fail happens while the previous Workspace is still serving
- * (proposal §12.6.5). Call {@link initStorage} from the server entry point so
- * a bad profile fails at startup with an actionable message, before anything
+ * The lifecycle is linear, because the Workspace a process serves is fixed
+ * for its lifetime (proposal §12.6.5): mount once, serve, close on shutdown.
+ * Selecting a different Workspace is a restart, so there is no remount, no
+ * staged swap, and nothing here has to describe *which* Workspace it was
+ * opened against — a mount that exists is the mount for the Workspace this
+ * process serves. Call {@link initStorage} from the server entry point so a
+ * bad profile fails at startup with an actionable message, before anything
  * has been opened.
  *
- * Anything that reaches for storage without going through a mount — tests,
- * scripts, the synchronous Workspace switch — builds the adapters on demand.
- * That path is synchronous, so it cannot `await init()`, and it is therefore
- * only legal for backends that have nothing to open; see
- * {@link requiresExplicitInit}. It is not a lazy version of the mount, and a
- * connection-holding backend must not be reached through it.
+ * Anything that reaches for storage without a mount — tests, scripts — builds
+ * the adapters on demand. That path is synchronous, so it cannot `await
+ * init()`, and it is therefore only legal for backends that have nothing to
+ * open; see {@link requiresExplicitInit}. It is not a lazy version of the
+ * mount, and a connection-holding backend must not be reached through it.
  */
 
-import path from 'node:path';
-
-import {
-  acquireWorkspaceOperationLease,
-  getWorkspacePath,
-  isWorkspaceConfigured,
-} from '../workspace.js';
+import { isWorkspaceConfigured } from '../workspace.js';
 import { DiskBlobStore } from './backends/disk/blob-store.js';
 import { stageDiskSpaceImport } from './backends/disk/space-import.js';
 import { diskSpaceTree } from './backends/disk/space-tree.js';
@@ -76,19 +70,6 @@ export type SpaceDeleteOutcome =
   | SpaceDeleteFinishResult
   | { readonly ok: false; readonly reason: 'world-forbidden' };
 
-function activeWorkspacePath(): string {
-  return path.resolve(getWorkspacePath());
-}
-
-function assertActiveWorkspace(workspacePath: string, canvasId: string): void {
-  if (activeWorkspacePath() !== workspacePath) {
-    throw new Error(
-      `Blob scope for Space "${canvasId}" belongs to an inactive workspace. ` +
-        `Resolve a fresh scope after workspace activation.`,
-    );
-  }
-}
-
 /**
  * Release a rejected streaming body that storage never fully consumed.
  *
@@ -107,14 +88,6 @@ function drainRejectedBody(body: Readable | Buffer): void {
 
 export interface Storage {
   readonly profile: StorageProfile;
-  /**
-   * Workspace these connections were opened against.
-   *
-   * A mount belongs to one Workspace. Switching Workspaces is a remount, not
-   * a reconfiguration of the connections in place, so this is what makes a
-   * stale mount recognisable rather than silently serving the wrong data.
-   */
-  readonly workspacePath: string;
   readonly structured: StructuredStore;
   readonly blobs: BlobStore;
   /**
@@ -194,13 +167,10 @@ function buildBlobStore(profile: StorageProfile): BlobStore {
   }
 }
 
-function buildStructuredStore(
-  profile: StorageProfile,
-  workspacePath: string,
-): StructuredStore {
+function buildStructuredStore(profile: StorageProfile): StructuredStore {
   switch (profile.structured.kind) {
     case 'disk':
-      return new DiskStructuredStore(workspacePath);
+      return new DiskStructuredStore();
     default:
       throw new Error(
         `Unsupported structured backend: ${profile.structured.kind}`,
@@ -219,13 +189,11 @@ function buildStructuredStore(
  */
 export function composeStorage(
   profile: StorageProfile,
-  workspacePath: string,
   structured: StructuredStore,
   blobs: BlobStore,
 ): Storage {
   return {
     profile,
-    workspacePath: path.resolve(workspacePath),
     structured,
     blobs,
     // Composes from the receiver, not from a captured local. Substituting one
@@ -239,20 +207,16 @@ export function composeStorage(
 }
 
 /**
- * Validate a profile and construct both connections for one Workspace.
+ * Validate a profile and construct both connections.
  *
  * Does not `init()` — opening is the mount's job, so a caller can build a
  * connection it has not committed to using.
  */
-export function createStorage(
-  profile: StorageProfile,
-  workspacePath: string,
-): Storage {
+export function createStorage(profile: StorageProfile): Storage {
   validateStorageProfile(profile);
   return composeStorage(
     profile,
-    workspacePath,
-    buildStructuredStore(profile, workspacePath),
+    buildStructuredStore(profile),
     buildBlobStore(profile),
   );
 }
@@ -284,26 +248,18 @@ function serializeSpaceCreate<T>(operation: () => Promise<T>): Promise<T> {
 }
 
 function ensure(): Storage {
-  const workspacePath = activeWorkspacePath();
-  if (current) {
-    if (current.workspacePath === workspacePath) return current;
-    // The active Workspace moved without going through the mount lifecycle —
-    // the synchronous `setWorkspacePath` path, and the tests that drive it.
-    // Drop the stale mount rather than serving another Workspace's data
-    // through it; the rebuild below either succeeds or says why it cannot.
-    current = null;
-  }
+  if (current) return current;
 
   const profile = parseStorageProfile();
   // Build first, so an unimplemented backend reports that rather than the
   // mount complaint below.
-  const storage = createStorage(profile, workspacePath);
+  const storage = createStorage(profile);
   if (requiresExplicitInit(profile)) {
     throw new StorageProfileError(
-      `Storage is not mounted on the active Workspace. The ` +
+      `Storage was used before it was mounted. The ` +
         `"${profile.structured.kind}" / "${profile.blobs.kind}" profile has ` +
-        `connections to open, and this path cannot await init(). Activate the ` +
-        `Workspace through the mount lifecycle instead.`,
+        `connections to open, and this path cannot await init(). Mount it ` +
+        `during startup instead.`,
     );
   }
   current = storage;
@@ -312,35 +268,6 @@ function ensure(): Storage {
 
 // ─── Workspace mount lifecycle ──────────────────────────────────────────────
 
-/**
- * Connections opened for a Workspace that is not active yet.
- *
- * Staging exists so activation can fail without consequences. Everything that
- * can go wrong — an unimplemented backend, a connection that will not open, a
- * namespace whose World is malformed — happens here, while the previous
- * Workspace and its connections are still serving. Only {@link commit} makes
- * the new mount reachable, and it cannot fail.
- */
-export interface StagedStorage {
-  readonly storage: Storage;
-  /**
-   * Publish this mount and close the one it replaced.
-   *
-   * `publish` is the caller's own commit — for a Workspace switch, making the
-   * new path the active one. It runs in the same synchronous block as the
-   * swap, so no request can land in a gap where the path has moved but the
-   * mount serving it has not. Closing the replaced connections happens after,
-   * where a slow close cannot delay the first request against the new
-   * Workspace.
-   *
-   * A `publish` that throws leaves the active mount exactly as it was; the
-   * caller should then {@link abort}. The swap itself cannot fail.
-   */
-  commit(publish?: () => void): Promise<void>;
-  /** Close the staged connections. The active mount is untouched. */
-  abort(): Promise<void>;
-}
-
 async function closeQuietly(storage: Storage): Promise<void> {
   await Promise.all([
     storage.structured.close().catch(() => undefined),
@@ -349,102 +276,66 @@ async function closeQuietly(storage: Storage): Promise<void> {
 }
 
 /**
- * Open connections for `workspacePath` and bootstrap its World.
+ * Open both connections for the active Workspace and bootstrap its World.
  *
- * Does not touch the active mount, the active Workspace path, or any
- * process-wide state. A rejection here leaves the previous Workspace fully
- * serving, which is the whole point of separating this from {@link
- * StagedStorage.commit} (proposal §12.6.5).
+ * The whole lifecycle, because a process serves one Workspace: this runs once,
+ * after the Workspace path has been committed and before anything is served.
+ * A rejection leaves the process with no mount, which is the honest outcome —
+ * the alternative is serving a Workspace whose World was never established.
  */
-export async function stageStorage(
-  workspacePath: string,
+export async function mountStorage(
   profile: StorageProfile = parseStorageProfile(),
-): Promise<StagedStorage> {
-  // The mount this one replaces, captured now rather than at commit time.
-  // Committing a Workspace path detaches the mount that no longer describes
-  // it, so by the time the swap runs there may be nothing left to read — and
-  // the connections would never be closed.
-  const replaced = current;
-  const storage = createStorage(profile, workspacePath);
+): Promise<Storage> {
+  await closeStorage();
+  const storage = createStorage(profile);
   try {
     await Promise.all([storage.structured.init(), storage.blobs.init()]);
     // Every backend meets an empty namespace the first time it is mounted, and
-    // a Workspace with no World has no Portal target. This runs before the
-    // path is committed, so it must address the Workspace being staged rather
-    // than the active one — which is why the connection is constructed with an
-    // explicit path.
+    // a Workspace with no World has no Portal target.
     await storage.structured.spaces().ensureWorld();
   } catch (error) {
     await closeQuietly(storage);
     throw error;
   }
-
-  return {
-    storage,
-    async commit(publish?: () => void): Promise<void> {
-      publish?.();
-      current = storage;
-      if (replaced && replaced !== storage) await closeQuietly(replaced);
-    },
-    /** Leaves `replaced` alone — it is still the active mount. */
-    abort(): Promise<void> {
-      return closeQuietly(storage);
-    },
-  };
-}
-
-/**
- * Mount storage onto `workspacePath` in one step.
- *
- * For callers that have nothing to do between staging and publishing. An
- * activation that must commit the Workspace path between the two — every
- * runtime switch — drives {@link stageStorage} directly instead.
- */
-export async function mountStorage(
-  workspacePath: string,
-  profile?: StorageProfile,
-): Promise<Storage> {
-  const staged = await stageStorage(workspacePath, profile);
-  await staged.commit();
-  return staged.storage;
+  current = storage;
+  return storage;
 }
 
 /**
- * Detach the current mount without closing it, returning what was detached.
+ * Drop the mount without closing it.
  *
- * The escape hatch for the synchronous Workspace switch, which cannot await a
- * close. Returning the detached mount rather than closing it here keeps the
- * decision with the caller: a backend whose `close()` matters is one that
- * cannot be reached through the synchronous path anyway, because `ensure()`
- * refuses to build it.
+ * The synchronous counterpart to {@link closeStorage}, for a caller that
+ * cannot await — {@link commitWorkspacePath} publishing a Workspace, and the
+ * tests that move between temporary ones. A backend whose `close()` matters is
+ * one {@link ensure} refuses to rebuild here anyway, so nothing that holds a
+ * connection is reachable through this path.
  */
-export function detachStorage(): Storage | null {
-  const previous = current;
+export function resetStorage(): void {
   current = null;
-  return previous;
 }
 
 /** Close the active mount. Called on graceful Server shutdown. */
 export async function closeStorage(): Promise<void> {
-  const previous = detachStorage();
+  const previous = current;
+  current = null;
   if (previous) await closeQuietly(previous);
 }
 
 /**
- * Validate the configured profile, and mount it when a Workspace is already
- * active.
+ * Validate the configured profile, and mount it when a Workspace is active.
  *
  * Called at server boot so an unknown or unimplemented backend fails there
- * with an actionable message rather than on the first upload. In free mode
- * there is no Workspace yet, so this validates and returns without opening
- * anything; the mount happens when one is activated.
+ * with an actionable message rather than on the first upload. A free-mode
+ * process may still be waiting for the user to choose a folder, so this
+ * validates and returns without opening anything; the mount then happens when
+ * one is activated, once.
  */
 export async function initStorage(
   profile: StorageProfile = parseStorageProfile(),
 ): Promise<Storage | null> {
   validateStorageProfile(profile);
   if (!isWorkspaceConfigured()) return null;
-  return mountStorage(activeWorkspacePath(), profile);
+  return mountStorage(profile);
 }
 
 export function getStorage(): Storage {
@@ -463,28 +354,19 @@ export function getStructuredStore(): StructuredStore {
  * Create one ordinary Space through the selected structured backend.
  *
  * Default-title allocation and lifecycle creation share one process-local
- * serialization point. The Workspace lease is acquired before queueing, so
- * an async catalogue read cannot strand the request in a newly activated
- * Workspace and concurrent defaults remain Untitled, Untitled (1), ... .
+ * serialization point, so concurrent defaults remain Untitled, Untitled (1),
+ * ... rather than colliding on one name.
  */
 export function createSpace(
   canvasId: string,
   title?: string | null,
 ): Promise<SpaceCreateResult> {
   const structured = ensure().structured;
-  const workspaceLease = acquireWorkspaceOperationLease();
   return serializeSpaceCreate(async () => {
-    try {
-      // One repository instance spans the read and the create, so a Workspace
-      // switch between them is rejected by the handle rather than silently
-      // creating the Space in the newly activated Workspace.
-      const spaces = structured.spaces();
-      const effectiveTitle =
-        title === undefined ? defaultSpaceTitle(await spaces.list()) : title;
-      return await spaces.create({ canvasId, title: effectiveTitle });
-    } finally {
-      workspaceLease.release();
-    }
+    const spaces = structured.spaces();
+    const effectiveTitle =
+      title === undefined ? defaultSpaceTitle(await spaces.list()) : title;
+    return spaces.create({ canvasId, title: effectiveTitle });
   });
 }
 
@@ -500,30 +382,25 @@ export function createSpace(
 export async function deleteSpace(
   canvasId: string,
 ): Promise<SpaceDeleteOutcome> {
-  const workspaceLease = acquireWorkspaceOperationLease();
+  const storage = ensure();
+  const started = await storage.structured.spaces().beginDelete({ canvasId });
+  if (!started.ok) return started;
   try {
-    const storage = ensure();
-    const started = await storage.structured.spaces().beginDelete({ canvasId });
-    if (!started.ok) return started;
-    try {
-      // Preserve the old retryable cleanup behavior: sweep even when the
-      // structured record is already absent, so orphan blobs can be removed.
-      // Every area, not just artifacts: a Space's bytes are spread across one
-      // scope per user-visible area, and on a backend where dropping the
-      // structured record does not remove the area they sit in, an unswept
-      // kind is an orphan.
-      await Promise.all(
-        spaceBlobAreas(storage.blobs.space(canvasId)).map((area) =>
-          area.deleteAll(),
-        ),
-      );
-      return await started.session.finish();
-    } catch (error) {
-      await started.session.abort();
-      throw error;
-    }
-  } finally {
-    workspaceLease.release();
+    // Preserve the old retryable cleanup behavior: sweep even when the
+    // structured record is already absent, so orphan blobs can be removed.
+    // Every area, not just artifacts: a Space's bytes are spread across one
+    // area per user-visible place, and on a backend where dropping the
+    // structured record does not remove that place, an unswept area is an
+    // orphan.
+    await Promise.all(
+      spaceBlobAreas(storage.blobs.space(canvasId)).map((area) =>
+        area.deleteAll(),
+      ),
+    );
+    return await started.session.finish();
+  } catch (error) {
+    await started.session.abort();
+    throw error;
   }
 }
 
@@ -544,8 +421,6 @@ function guardedBlobScope(
   canvasId: string,
   delegate: BlobScope,
 ): BlobScope {
-  const workspacePath = activeWorkspacePath();
-
   async function requireSpace(): Promise<void> {
     const record = await storage.structured.space(canvasId).read();
     if (!record) {
@@ -556,16 +431,10 @@ function guardedBlobScope(
   return {
     async put(name: string, body: Readable | Buffer): Promise<BlobInfo> {
       try {
-        return await withSpacePutAdmission(
-          workspacePath,
-          canvasId,
-          async () => {
-            assertActiveWorkspace(workspacePath, canvasId);
-            await requireSpace();
-            assertActiveWorkspace(workspacePath, canvasId);
-            return delegate.put(name, body);
-          },
-        );
+        return await withSpacePutAdmission(canvasId, async () => {
+          await requireSpace();
+          return delegate.put(name, body);
+        });
       } catch (error) {
         drainRejectedBody(body);
         throw error;
diff --git a/apps/server/src/modules/storage/testing.ts b/apps/server/src/modules/storage/testing.ts
index 6cf5d6eda..89e1989b3 100644
--- a/apps/server/src/modules/storage/testing.ts
+++ b/apps/server/src/modules/storage/testing.ts
@@ -5,11 +5,11 @@
  * Product-level storage harness.
  *
  * Mounts a **real** profile onto a temporary Workspace through the production
- * lifecycle — prepared Workspace, staged connections, `ensureWorld()`, atomic
- * swap — rather than swapping in a stub. That distinction is the whole point:
- * a suite written against a stub proves that the application talks to an
- * interface, while this one proves that a *backend* serves the product
- * (proposal §12.6.6).
+ * lifecycle — prepared Workspace, opened connections, `ensureWorld()` — rather
+ * than swapping in a stub. That distinction is the whole point: a suite
+ * written against a stub proves that the application talks to an interface,
+ * while this one proves that a *backend* serves the product (proposal
+ * §12.6.6).
  *
  * It exists so a product test is written once and run against every profile.
  * Phase 5 adds one entry to {@link PRODUCT_STORAGE_PROFILES} and the same
@@ -21,7 +21,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
-import { closeStorage, stageStorage } from './storage.js';
+import { closeStorage, mountStorage } from './storage.js';
 import { setWorkspacePath } from '../workspace.js';
 
 import type { StorageProfile } from './profile.js';
@@ -54,11 +54,10 @@ export interface MountedTestStorage {
 /**
  * Mount `profile` onto a fresh temporary Workspace.
  *
- * Goes through `setWorkspacePath` and {@link stageStorage} rather than
- * reaching for the adapters, so a test exercises the same preparation,
- * bootstrap, and swap a running Server does. A backend whose mount is broken
- * fails here, in the harness, instead of surfacing as a confusing product
- * failure later.
+ * Goes through `setWorkspacePath` and {@link mountStorage} rather than
+ * reaching for the adapters, so a test exercises the same preparation and
+ * bootstrap a running Server does. A backend whose mount is broken fails here,
+ * in the harness, instead of surfacing as a confusing product failure later.
  */
 export async function mountTestWorkspace(
   profile: StorageProfile,
@@ -67,16 +66,14 @@ export async function mountTestWorkspace(
   // A profile label reads as `disk/disk`, which is not a directory name.
   const safePrefix = prefix.replace(/[^a-zA-Z0-9._-]/g, '-');
   const workspacePath = mkdtempSync(path.join(tmpdir(), safePrefix));
-  // Prepares and commits the Workspace, exactly as a synchronous activation
-  // does; the mount below is then the async half of the same sequence.
+  // Prepares and commits the Workspace; the mount below is the second half of
+  // the same startup sequence.
   setWorkspacePath(workspacePath);
-
-  const staged = await stageStorage(workspacePath, profile);
-  await staged.commit();
+  const storage = await mountStorage(profile);
 
   return {
     profile,
-    storage: staged.storage,
+    storage,
     workspacePath,
     async close(): Promise<void> {
       await closeStorage();
diff --git a/apps/server/src/modules/workspace-activation.test.ts b/apps/server/src/modules/workspace-activation.test.ts
index ac05eadca..7d89789ec 100644
--- a/apps/server/src/modules/workspace-activation.test.ts
+++ b/apps/server/src/modules/workspace-activation.test.ts
@@ -10,8 +10,14 @@ import {
   runWorkspacePreparation,
   WorkspaceActivationInProgressError,
   WorkspaceActivationTimeoutError,
+  WorkspaceRestartRequiredError,
 } from './workspace-activation.js';
-import { getWorkspacePath, setWorkspacePath } from './workspace.js';
+import {
+  clearWorkspacePath,
+  getWorkspacePath,
+  isWorkspaceConfigured,
+  setWorkspacePath,
+} from './workspace.js';
 
 describe('workspace activation isolation', () => {
   const roots: string[] = [];
@@ -29,7 +35,14 @@ describe('workspace activation isolation', () => {
     return file;
   }
 
+  beforeEach(() => {
+    // Every case decides for itself whether a workspace is already active,
+    // because that is the branch under test.
+    clearWorkspacePath();
+  });
+
   afterAll(() => {
+    clearWorkspacePath();
     for (const root of roots) {
       rmSync(root, { recursive: true, force: true });
     }
@@ -55,16 +68,50 @@ describe('workspace activation isolation', () => {
     ).rejects.toBeInstanceOf(WorkspaceActivationTimeoutError);
   });
 
-  it('keeps the previous workspace active after preparation times out', async () => {
-    const previous = tempDir('huabu-workspace-previous-');
+  it('leaves the process unconfigured when preparation times out', async () => {
     const next = tempDir('huabu-workspace-next-');
     const workerPath = worker(`setInterval(() => {}, 1_000);`);
-    setWorkspacePath(previous);
 
     await expect(
       activateWorkspacePath(next, { workerPath, timeoutMs: 30 }),
     ).rejects.toBeInstanceOf(WorkspaceActivationTimeoutError);
-    expect(getWorkspacePath()).toBe(path.resolve(previous));
+    // Nothing half-activated: the client sees the same state it started from
+    // and can pick again.
+    expect(isWorkspaceConfigured()).toBe(false);
+  });
+
+  /**
+   * The restart rule (issue #126). A process serves one workspace, so the
+   * second choice is the client's to persist and the next process's to open —
+   * and refusing it has to leave this process exactly as it was, including not
+   * running preparation against the folder it was asked for.
+   */
+  it('refuses a different workspace once one is active, and touches nothing', async () => {
+    const active = tempDir('huabu-workspace-active-');
+    const other = tempDir('huabu-workspace-other-');
+    setWorkspacePath(active);
+    // A worker that would fail loudly if it ever ran.
+    const workerPath = worker(`process.send({ ok: false, message: 'ran' });`);
+
+    const refusal = activateWorkspacePath(other, { workerPath });
+    await expect(refusal).rejects.toBeInstanceOf(WorkspaceRestartRequiredError);
+    await expect(refusal).rejects.toMatchObject({
+      requestedPath: path.resolve(other),
+    });
+    expect(getWorkspacePath()).toBe(path.resolve(active));
+  });
+
+  it('accepts the active workspace again without reactivating it', async () => {
+    const active = tempDir('huabu-workspace-idempotent-');
+    setWorkspacePath(active);
+    const workerPath = worker(`process.send({ ok: false, message: 'ran' });`);
+
+    // The client re-sends its remembered path on every boot, and a second tab
+    // must not be told to restart.
+    await expect(
+      activateWorkspacePath(active, { workerPath }),
+    ).resolves.toBeUndefined();
+    expect(getWorkspacePath()).toBe(path.resolve(active));
   });
 
   it('rejects a concurrent activation while preparation is running', async () => {
diff --git a/apps/server/src/modules/workspace-activation.ts b/apps/server/src/modules/workspace-activation.ts
index 27f9ac52a..c4135ea05 100644
--- a/apps/server/src/modules/workspace-activation.ts
+++ b/apps/server/src/modules/workspace-activation.ts
@@ -15,14 +15,20 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { stageStorage } from './storage/index.js';
+import { initStorage, mountStorage } from './storage/index.js';
 import {
+  clearWorkspacePath,
   commitWorkspacePath,
+  getWorkspacePath,
   isManagedMode,
+  isWorkspaceConfigured,
+  reportWorkspaceStartupFailure,
   resolveWorkspacePath,
 } from './workspace.js';
 import { getLogger } from '../utils/logger.js';
 
+import type { Storage } from './storage/index.js';
+
 const DEFAULT_ACTIVATION_TIMEOUT_MS = 70_000;
 
 /**
@@ -63,6 +69,29 @@ export class WorkspaceActivationInProgressError extends Error {
   }
 }
 
+/**
+ * Raised when the caller asks for a workspace other than the active one.
+ *
+ * Not a failure of the request — the choice is valid and the client should
+ * persist it. What cannot happen is this process serving it: connections,
+ * caches, and directory indexes are opened against one workspace and the
+ * machinery to move a live process between two of them costs more than the
+ * feature is worth (issue #126). The client saves the path and restarts.
+ */
+export class WorkspaceRestartRequiredError extends Error {
+  /** The workspace the caller asked for, to persist for the next launch. */
+  readonly requestedPath: string;
+
+  constructor(requestedPath: string) {
+    super(
+      'Changing the workspace takes effect after a restart. The selection has ' +
+        'been validated; save it and start the server again to open it.',
+    );
+    this.name = 'WorkspaceRestartRequiredError';
+    this.requestedPath = requestedPath;
+  }
+}
+
 interface PreparationOptions {
   timeoutMs?: number;
   workerPath?: string;
@@ -178,15 +207,19 @@ export function runWorkspacePreparation(
 }
 
 /**
- * Prepare a free-mode workspace and commit it only after full success.
+ * Prepare and open the one workspace this process will serve.
+ *
+ * Free mode's first — and only — activation. The disposable child prepares and
+ * migrates the directory, the path is committed, and storage mounts against
+ * it; the sequence is linear because there is no previous workspace to keep
+ * serving while it runs (proposal §12.6.5). A failure leaves the process
+ * unconfigured, which is the state the client already knows how to recover
+ * from, rather than half-activated.
  *
- * Ordering is the contract (proposal §12.6.5). The disposable child prepares
- * and migrates the directory; storage then stages its connections against the
- * *new* path and bootstraps its World; only once both have succeeded is the
- * Workspace path committed and the mount published. Anything that fails before
- * the commit leaves the previous Workspace and its connections serving, which
- * is why staging is separate from publishing — a half-activated Workspace is
- * the one outcome this sequence exists to prevent.
+ * Asking for a *different* workspace once one is active raises
+ * {@link WorkspaceRestartRequiredError} without touching a thing. Asking for
+ * the active one again is a no-op, because the client re-sends its remembered
+ * path on every boot and a second tab must not be told to restart.
  */
 export async function activateWorkspacePath(
   newPath: string,
@@ -197,26 +230,52 @@ export async function activateWorkspacePath(
       'Server is in managed mode; the workspace is fixed at startup',
     );
   }
+  const resolvedPath = resolveWorkspacePath(newPath);
+  if (isWorkspaceConfigured()) {
+    if (getWorkspacePath() === resolvedPath) return;
+    throw new WorkspaceRestartRequiredError(resolvedPath);
+  }
   if (activationInProgress) {
     throw new WorkspaceActivationInProgressError();
   }
 
-  const resolvedPath = resolveWorkspacePath(newPath);
   activationInProgress = true;
   try {
     await runWorkspacePreparation(resolvedPath, options);
-    const staged = await stageStorage(resolvedPath);
+    commitWorkspacePath(resolvedPath);
     try {
-      // The path and the mount that serves it are published together, so no
-      // request can observe one without the other.
-      await staged.commit(() => commitWorkspacePath(resolvedPath));
+      await mountStorage();
     } catch (error) {
-      // The path change was refused — an in-flight operation still holds the
-      // previous Workspace. Discard the connections nobody will reach.
-      await staged.abort();
+      // The path is committed but nothing serves it. Unconfigure rather than
+      // leave a workspace that looks active and has no store behind it — the
+      // client would then be told it is ready, and every later request would
+      // fail in a place that cannot explain why.
+      clearWorkspacePath();
       throw error;
     }
   } finally {
     activationInProgress = false;
   }
 }
+
+/**
+ * Open storage on the workspace this process was started on.
+ *
+ * The startup counterpart to {@link activateWorkspacePath}, and the same
+ * failure rule as {@link initWorkspaceFromEnv}: an operator's workspace that
+ * will not open fails the boot, a shell-chosen one leaves the process
+ * unconfigured with the reason recorded, and a process with no workspace yet
+ * only has its profile validated. Returns the mount, or `null` when there was
+ * nothing to mount.
+ */
+export async function mountStartupWorkspace(): Promise<Storage | null> {
+  try {
+    return await initStorage();
+  } catch (error) {
+    // Nothing was configured, so this is the profile itself refusing — a
+    // misconfiguration no workspace choice can recover from.
+    if (isManagedMode() || !isWorkspaceConfigured()) throw error;
+    reportWorkspaceStartupFailure(error);
+    return null;
+  }
+}
diff --git a/apps/server/src/modules/workspace.route.ts b/apps/server/src/modules/workspace.route.ts
index 1a0f98353..75035c243 100644
--- a/apps/server/src/modules/workspace.route.ts
+++ b/apps/server/src/modules/workspace.route.ts
@@ -14,10 +14,12 @@ import {
   activateWorkspacePath,
   WorkspaceActivationInProgressError,
   WorkspaceActivationTimeoutError,
+  WorkspaceRestartRequiredError,
 } from './workspace-activation.js';
 import {
   getWorkspaceName,
   getWorkspacePath,
+  getWorkspaceStartupError,
   isManagedMode,
   isWorkspaceConfigured,
 } from './workspace.js';
@@ -166,6 +168,7 @@ async function buildWorkspaceState(): Promise<WorkspaceInfo> {
     worldCanvasId: configured
       ? await getStructuredStore().spaces().worldId()
       : null,
+    startupError: getWorkspaceStartupError(),
     capabilities: {
       canChangeWorkspace: !managed,
       nativePicker: !managed && canShowNativePicker(),
@@ -286,6 +289,13 @@ const workspaceRoutes: FastifyPluginAsync = async (app) => {
           'WORKSPACE_ACTIVATION_IN_PROGRESS',
         );
       }
+      // Not a rejection of the choice — the path is valid and the client
+      // should save it. This process just cannot be the one to open it.
+      if (e instanceof WorkspaceRestartRequiredError) {
+        return sendError(reply, 409, e.message, 'WORKSPACE_RESTART_REQUIRED', {
+          path: e.requestedPath,
+        });
+      }
       return sendError(reply, 400, (e as Error).message);
     }
   });
diff --git a/apps/server/src/modules/workspace.test.ts b/apps/server/src/modules/workspace.test.ts
index 882a36fde..a9a27930d 100644
--- a/apps/server/src/modules/workspace.test.ts
+++ b/apps/server/src/modules/workspace.test.ts
@@ -1,19 +1,28 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+/**
+ * Adopting the workspace a process was started on.
+ *
+ * The two env forms exist to differ in one place — what a failure means — so
+ * every case here is about that difference, or about the state a client is
+ * left in when a remembered workspace cannot be opened (issue #126).
+ */
+
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import {
-  acquireWorkspaceOperationLease,
-  commitWorkspacePath,
+  clearWorkspacePath,
   getWorkspacePath,
-  setWorkspacePath,
-  WorkspaceOperationInProgressError,
+  getWorkspaceStartupError,
+  initWorkspaceFromEnv,
+  isManagedMode,
+  isWorkspaceConfigured,
 } from './workspace.js';
 
-describe('workspace operation leases', () => {
+describe('startup workspace adoption', () => {
   const roots: string[] = [];
 
   function tempDir(prefix: string): string {
@@ -22,57 +31,100 @@ describe('workspace operation leases', () => {
     return dir;
   }
 
+  /** A path *inside a file*, so creating the directory fails with ENOTDIR. */
+  function unopenable(): string {
+    const blocker = path.join(tempDir('huabu-workspace-blocked-'), 'not-a-dir');
+    writeFileSync(blocker, 'occupied', 'utf8');
+    return path.join(blocker, 'workspace');
+  }
+
+  beforeEach(() => {
+    delete process.env.HUABU_WORKSPACE;
+    delete process.env.HUABU_WORKSPACE_STARTUP;
+    clearWorkspacePath();
+  });
+
   afterAll(() => {
+    delete process.env.HUABU_WORKSPACE;
+    delete process.env.HUABU_WORKSPACE_STARTUP;
+    initWorkspaceFromEnv();
+    clearWorkspacePath();
     for (const root of roots) {
       rmSync(root, { recursive: true, force: true });
     }
   });
 
-  it('blocks a commit to another workspace until every lease is released', () => {
-    const current = tempDir('huabu-workspace-current-');
-    const next = tempDir('huabu-workspace-next-');
-    expect(() => setWorkspacePath(current)).not.toThrow();
-
-    const first = acquireWorkspaceOperationLease();
-    const second = acquireWorkspaceOperationLease();
-    expect(first.workspacePath).toBe(path.resolve(current));
-    expect(second.workspacePath).toBe(path.resolve(current));
-
-    expect(() => commitWorkspacePath(path.resolve(next))).toThrow(
-      WorkspaceOperationInProgressError,
-    );
-    expect(getWorkspacePath()).toBe(path.resolve(current));
-
-    first.release();
-    first.release();
-    expect(() => commitWorkspacePath(path.resolve(next))).toThrow(
-      WorkspaceOperationInProgressError,
-    );
-
-    second.release();
-    expect(() => commitWorkspacePath(path.resolve(next))).not.toThrow();
-    expect(getWorkspacePath()).toBe(path.resolve(next));
+  it('starts unconfigured when neither variable is set', () => {
+    initWorkspaceFromEnv();
+
+    expect(isManagedMode()).toBe(false);
+    expect(isWorkspaceConfigured()).toBe(false);
+    expect(getWorkspaceStartupError()).toBeNull();
+  });
+
+  it('locks the operator-named workspace and prepares it', () => {
+    const root = tempDir('huabu-workspace-managed-');
+    process.env.HUABU_WORKSPACE = root;
+
+    initWorkspaceFromEnv();
+
+    expect(isManagedMode()).toBe(true);
+    expect(getWorkspacePath()).toBe(path.resolve(root));
+  });
+
+  it('adopts a shell-chosen workspace without locking it', () => {
+    const root = tempDir('huabu-workspace-startup-');
+    process.env.HUABU_WORKSPACE_STARTUP = root;
+
+    initWorkspaceFromEnv();
+
+    // Free mode: the path is the user's own choice, so the picker stays
+    // available and the path stays visible.
+    expect(isManagedMode()).toBe(false);
+    expect(getWorkspacePath()).toBe(path.resolve(root));
+    expect(getWorkspaceStartupError()).toBeNull();
+  });
+
+  it('prefers the operator variable when both are set', () => {
+    const managed = tempDir('huabu-workspace-both-managed-');
+    const shell = tempDir('huabu-workspace-both-shell-');
+    process.env.HUABU_WORKSPACE = managed;
+    process.env.HUABU_WORKSPACE_STARTUP = shell;
+
+    initWorkspaceFromEnv();
+
+    expect(isManagedMode()).toBe(true);
+    expect(getWorkspacePath()).toBe(path.resolve(managed));
   });
 
-  it('allows same-path activation but rejects setWorkspacePath before preparing another path', () => {
-    const current = tempDir('huabu-workspace-current-');
-    const parent = tempDir('huabu-workspace-parent-');
-    const next = path.join(parent, 'not-created');
-    setWorkspacePath(current);
-
-    const lease = acquireWorkspaceOperationLease();
-    expect(() => setWorkspacePath(path.join(current, '.'))).not.toThrow();
-    expect(getWorkspacePath()).toBe(path.resolve(current));
-
-    expect(() => setWorkspacePath(next)).toThrow(
-      WorkspaceOperationInProgressError,
-    );
-    expect(existsSync(next)).toBe(false);
-    expect(getWorkspacePath()).toBe(path.resolve(current));
-
-    lease.release();
-    expect(() => setWorkspacePath(next)).not.toThrow();
-    expect(existsSync(next)).toBe(true);
-    expect(getWorkspacePath()).toBe(path.resolve(next));
+  it('fails startup when the operator names a workspace it cannot open', () => {
+    const blocked = unopenable();
+    process.env.HUABU_WORKSPACE = blocked;
+
+    // A deployment misconfiguration. Coming up unconfigured instead would
+    // offer a remote user a folder picker for the host filesystem.
+    expect(() => initWorkspaceFromEnv()).toThrow();
+    expect(existsSync(blocked)).toBe(false);
+  });
+
+  it('recovers to the picker when a shell-chosen workspace cannot be opened', () => {
+    process.env.HUABU_WORKSPACE_STARTUP = unopenable();
+
+    initWorkspaceFromEnv();
+
+    // The user's folder moved, was renamed, or lives on a drive that is not
+    // mounted today. The recovery for that is picking another one, so the
+    // process serves nothing and says why rather than dying.
+    expect(isWorkspaceConfigured()).toBe(false);
+    expect(getWorkspaceStartupError()).toBeTruthy();
+  });
+
+  it('rejects a relative path in either variable', () => {
+    process.env.HUABU_WORKSPACE_STARTUP = 'relative/path';
+    expect(() => initWorkspaceFromEnv()).toThrow(/absolute/);
+
+    delete process.env.HUABU_WORKSPACE_STARTUP;
+    process.env.HUABU_WORKSPACE = 'relative/path';
+    expect(() => initWorkspaceFromEnv()).toThrow(/absolute/);
   });
 });
diff --git a/apps/server/src/modules/workspace.ts b/apps/server/src/modules/workspace.ts
index 324dfccb9..587f7e27e 100644
--- a/apps/server/src/modules/workspace.ts
+++ b/apps/server/src/modules/workspace.ts
@@ -4,26 +4,38 @@
 /**
  * Centralised workspace path management.
  *
- * Two operating modes, decided at process startup by the presence of the
- * `HUABU_WORKSPACE` environment variable:
+ * **A process serves one workspace.** Once a workspace is active it does not
+ * change for the lifetime of the process; selecting a different one persists
+ * the choice and takes effect on restart (issue #126). That is what lets every
+ * storage connection, cache, and directory index be opened once and trusted
+ * afterwards, instead of each one carrying its own answer to "which workspace
+ * am I looking at?".
  *
- *   ── Free mode (default for local dev) ──
- *     `HUABU_WORKSPACE` is *unset*.
- *     The user picks any absolute directory at runtime via the client
- *     (folder picker / path input). `setWorkspacePath(absPath)` is the
- *     entry point. The active path can change during the process lifetime.
+ * Three ways the one workspace is chosen, in precedence order:
  *
- *   ── Managed mode (recommended for remote / single-tenant deployments) ──
- *     `HUABU_WORKSPACE=/abs/path` is set at process start.
- *     The path is locked at boot via {@link initWorkspaceFromEnv} and
- *     CANNOT be changed at runtime. The client gets a read-only label
- *     (the basename of the path) and no folder-picker UI. To run a
- *     different workspace, restart the process with a different env
- *     value — typically one process per user / per workspace, with the
- *     network access controlled by your reverse proxy.
+ *   ── Managed: `HUABU_WORKSPACE=/abs/path` ──
+ *     The operator's choice, for remote / single-tenant deployments. Locked at
+ *     boot by {@link initWorkspaceFromEnv}; the client gets a read-only label
+ *     (the basename) and no folder-picker UI, and a workspace that cannot be
+ *     prepared fails startup rather than degrading to a picker a remote user
+ *     should not see. To run a different workspace, restart the process with a
+ *     different env value.
  *
- * Either way, every storage layer resolves its directory relative to a
- * single workspace root.
+ *   ── Shell-chosen: `HUABU_WORKSPACE_STARTUP=/abs/path` ──
+ *     The user's own choice, remembered by a shell that owns both the saved
+ *     path and the server process — today the Electron main process and its
+ *     `workspace.json`. Free mode otherwise: the path is shown, the picker is
+ *     offered, and picking another one is a restart. A path that cannot be
+ *     prepared leaves the process unconfigured with
+ *     {@link getWorkspaceStartupError} set, so the shell can show the picker
+ *     instead of dying.
+ *
+ *   ── Runtime activation (free mode, first time only) ──
+ *     Neither variable is set, so the process starts unconfigured and the
+ *     client activates a path through `PUT /api/workspace`. That is the
+ *     browser deployment's only route, since `localStorage` cannot configure a
+ *     server before it starts. It happens at most once per process; see
+ *     `workspace-activation.ts`.
  *
  * Directory layout inside the active workspace (canvas-centric):
  *
@@ -40,38 +52,16 @@ import path from 'node:path';
 
 import { resetExternalNoteSessions } from './canvas/external-watcher.js';
 import { refreshCanvasDirIndex } from './storage/canvas-dirs.js';
-import { detachStorage } from './storage/storage.js';
+import { resetStorage } from './storage/storage.js';
 import { prepareWorkspaceOnDisk } from './workspace-prepare.js';
 import { invalidateUserSkill } from '../prompt/index.js';
 
 const ENV_KEY = 'HUABU_WORKSPACE';
+const STARTUP_ENV_KEY = 'HUABU_WORKSPACE_STARTUP';
 
 let _workspacePath: string | null = null;
 let _managed = false;
-let _leasedWorkspacePath: string | null = null;
-let _workspaceOperationLeaseCount = 0;
-
-/**
- * A short-lived claim that keeps an async operation on one workspace.
- *
- * The release callback is deliberately synchronous and idempotent so callers
- * can always put it in a `finally` block without masking the operation's
- * original result.
- */
-export interface WorkspaceOperationLease {
-  readonly workspacePath: string;
-  release(): void;
-}
-
-/** Raised when a workspace switch would strand an in-flight operation. */
-export class WorkspaceOperationInProgressError extends Error {
-  constructor() {
-    super(
-      'Cannot change workspace while an operation is still using the active workspace',
-    );
-    this.name = 'WorkspaceOperationInProgressError';
-  }
-}
+let _startupError: string | null = null;
 
 // ──────────────────────────────────────────────────────────────────────
 // Mode + lifecycle
@@ -90,26 +80,69 @@ export function isWorkspaceConfigured(): boolean {
 }
 
 /**
- * If `HUABU_WORKSPACE` is set, lock the server to that path.
- * Must be called once at startup, before any request handlers run.
- * Throws if the env value is invalid (non-absolute) so misconfiguration
- * is surfaced loudly.
+ * Adopt the workspace this process was started on, if it was given one.
+ *
+ * Must be called once at startup, before any request handlers run. Handles
+ * both env forms, and they differ in exactly one place — what a failure means.
+ * An operator naming a workspace that cannot be prepared has misconfigured the
+ * deployment, and a server that quietly came up unconfigured would offer a
+ * remote user a folder picker for the host filesystem. A *shell* naming one
+ * has a user whose folder moved, was renamed, or lives on a drive that is not
+ * mounted today, and the recovery for that is the picker.
  */
 export function initWorkspaceFromEnv(): void {
-  const fromEnv = process.env[ENV_KEY];
-  if (!fromEnv) {
-    _managed = false;
-    return;
-  }
-  if (!path.isAbsolute(fromEnv)) {
-    throw new Error(
-      `${ENV_KEY} must be an absolute path, got: ${JSON.stringify(fromEnv)}`,
-    );
+  const managedPath = readEnvPath(ENV_KEY);
+  const startupPath = managedPath ? null : readEnvPath(STARTUP_ENV_KEY);
+  const resolvedPath = managedPath ?? startupPath;
+  _managed = managedPath !== null;
+  _startupError = null;
+  if (!resolvedPath) return;
+
+  try {
+    prepareWorkspaceOnDisk(resolvedPath);
+    commitWorkspacePath(resolvedPath);
+  } catch (error) {
+    if (_managed) throw error;
+    reportWorkspaceStartupFailure(error);
   }
-  const resolvedPath = path.resolve(fromEnv);
-  _managed = true;
-  prepareWorkspaceOnDisk(resolvedPath);
-  commitWorkspacePath(resolvedPath);
+}
+
+/**
+ * Give up on the workspace this process was started on.
+ *
+ * Leaves the process unconfigured with the reason recorded, which is a state
+ * the client already knows how to recover from: it shows the picker. Only ever
+ * right for a *shell-chosen* workspace — an operator's `HUABU_WORKSPACE` that
+ * cannot be opened is a misconfiguration, and offering a remote user a folder
+ * picker for the host filesystem instead is not a recovery.
+ */
+export function reportWorkspaceStartupFailure(error: unknown): void {
+  clearWorkspacePath();
+  _startupError =
+    error instanceof Error ? error.message : 'Workspace could not be opened';
+}
+
+/**
+ * Return the process to its unconfigured state.
+ *
+ * Not a way to change workspaces — nothing is put in the old one's place. It
+ * exists so an activation that fails partway leaves no half-open workspace
+ * behind, and so tests can start from a clean process.
+ */
+export function clearWorkspacePath(): void {
+  _workspacePath = null;
+  dropWorkspaceScopedState();
+}
+
+/**
+ * Why the workspace this process was started on could not be opened.
+ *
+ * `null` when there was nothing to open or it opened fine. Reported to the
+ * client so a shell-chosen workspace that has gone missing explains itself in
+ * the picker rather than looking like a first launch.
+ */
+export function getWorkspaceStartupError(): string | null {
+  return _startupError;
 }
 
 // ──────────────────────────────────────────────────────────────────────
@@ -131,40 +164,6 @@ export function getWorkspacePath(): string {
   return _workspacePath;
 }
 
-/**
- * Keep the currently-active workspace stable for an async operation.
- *
- * Multiple operations may hold leases concurrently. Switching to another
- * workspace is rejected until every lease has been released; recommitting the
- * same path remains allowed.
- */
-export function acquireWorkspaceOperationLease(): WorkspaceOperationLease {
-  const workspacePath = getWorkspacePath();
-
-  if (
-    _workspaceOperationLeaseCount > 0 &&
-    _leasedWorkspacePath !== workspacePath
-  ) {
-    throw new Error('Workspace operation lease invariant violated');
-  }
-
-  _leasedWorkspacePath = workspacePath;
-  _workspaceOperationLeaseCount += 1;
-
-  let released = false;
-  return Object.freeze({
-    workspacePath,
-    release(): void {
-      if (released) return;
-      released = true;
-      _workspaceOperationLeaseCount -= 1;
-      if (_workspaceOperationLeaseCount === 0) {
-        _leasedWorkspacePath = null;
-      }
-    },
-  });
-}
-
 /**
  * Display label for the currently-active workspace. In managed mode this
  * is the basename of the locked path; in free mode it's also the basename
@@ -179,12 +178,17 @@ export function getWorkspaceName(): string | null {
 }
 
 /**
- * (Free mode) Activate any absolute path as the current workspace and
- * create the workspace folder. Rejected in managed mode — the workspace
- * is locked at boot.
+ * Prepare an absolute path and make it the active workspace, synchronously.
+ *
+ * The primitive underneath both startup paths. Production reaches a workspace
+ * through {@link initWorkspaceFromEnv} or `activateWorkspacePath`, which is
+ * where the "one workspace per process" rule is enforced and where preparation
+ * runs in a disposable child; this function does the preparation inline and
+ * enforces nothing, so it stays available to tests that drive many temporary
+ * workspaces through one process.
  *
- * Also converts any legacy pi-ai `Context` chat threads on the new
- * workspace to structured turns (idempotent).
+ * Also converts any legacy pi-ai `Context` chat threads on the new workspace
+ * to structured turns (idempotent).
  */
 export function setWorkspacePath(newPath: string): void {
   if (_managed) {
@@ -193,7 +197,6 @@ export function setWorkspacePath(newPath: string): void {
     );
   }
   const resolvedPath = resolveWorkspacePath(newPath);
-  assertWorkspacePathChangeAllowed(resolvedPath);
   prepareWorkspaceOnDisk(resolvedPath);
   commitWorkspacePath(resolvedPath);
 }
@@ -209,31 +212,31 @@ export function resolveWorkspacePath(newPath: string): string {
  *
  * This function intentionally performs no disk I/O. Runtime activation calls
  * it only after the isolated preparation process has completed successfully.
+ *
+ * Production commits once, before anything has been opened against a
+ * workspace. It still drops every workspace-scoped cache below, because tests
+ * drive it repeatedly to move between temporary workspaces and nothing should
+ * keep serving the previous one.
  */
 export function commitWorkspacePath(resolvedPath: string): void {
-  assertWorkspacePathChangeAllowed(resolvedPath);
-  const changed = _workspacePath !== resolvedPath;
   _workspacePath = resolvedPath;
-  if (changed) {
-    // A mount belongs to one Workspace, so the previous one no longer
-    // describes anything reachable. Detach rather than close: this function is
-    // synchronous and cannot await, and a backend whose `close()` matters is
-    // one the lazy rebuild refuses to construct anyway — such a profile is
-    // mounted through `stageStorage`, which closes the mount it replaces
-    // (proposal §12.6.5).
-    detachStorage();
-  }
-  // Drop the cached canvas-dir index so subsequent lookups (used by
-  // migrations and route handlers) reflect the new workspace.
+  _startupError = null;
+  dropWorkspaceScopedState();
+}
+
+/**
+ * Drop everything opened against whichever workspace was active.
+ *
+ * A mount, a directory index, a skill cache, and the external-note watchers
+ * are all workspace-scoped. The import cycle with the prompt loader (which
+ * depends on `getWorkspacePath` from this module) is safe because Node ESM
+ * allows cycles as long as no top-level code on either side dereferences the
+ * late-bound import — `invalidateUserSkill` is only called from inside a
+ * function body, after both modules have finished evaluating.
+ */
+function dropWorkspaceScopedState(): void {
+  resetStorage();
   refreshCanvasDirIndex();
-  // Drop any user-skill cache built against the previous workspace so
-  // the next `listSkills` / `read("skills/...")` call rescans the new
-  // `<workspace>/setting/skills/` from scratch. The import-cycle with
-  // the prompt loader (which depends on `getWorkspacePath` from this
-  // module) is safe because Node ESM allows cycles as long as no
-  // top-level code on either side dereferences the late-bound import
-  // — here `invalidateUserSkill` is only ever called from within
-  // function bodies, after both modules have finished evaluating.
   invalidateUserSkill();
   resetExternalNoteSessions();
 }
@@ -258,12 +261,14 @@ function validateAbsolutePath(p: string): void {
   }
 }
 
-function assertWorkspacePathChangeAllowed(resolvedPath: string): void {
-  if (
-    _workspaceOperationLeaseCount > 0 &&
-    _leasedWorkspacePath !== null &&
-    _leasedWorkspacePath !== resolvedPath
-  ) {
-    throw new WorkspaceOperationInProgressError();
+/** Read one env var as an absolute path, or `null` when unset. */
+function readEnvPath(key: string): string | null {
+  const raw = process.env[key];
+  if (!raw) return null;
+  if (!path.isAbsolute(raw)) {
+    throw new Error(
+      `${key} must be an absolute path, got: ${JSON.stringify(raw)}`,
+    );
   }
+  return path.resolve(raw);
 }
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 277b9267d..8ae9509fd 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -9,9 +9,9 @@ import { prewarmOAuthCredentials } from './modules/agent/oauth.js';
 import { resolveDeploymentConfig } from './modules/security/deployment-config.js';
 import {
   describeUnavailableCapabilities,
-  initStorage,
   parseStorageProfile,
 } from './modules/storage/index.js';
+import { mountStartupWorkspace } from './modules/workspace-activation.js';
 import { initializeSecretStore } from './security/secret-store.js';
 import { getLogger } from './utils/logger.js';
 
@@ -37,16 +37,16 @@ async function start(): Promise<void> {
     }
 
     // Before anything serves: an unknown or unimplemented backend must
-    // fail here with an actionable message, not on the first upload. In free
-    // mode there is no Workspace yet, so this validates the profile and the
-    // mount waits for activation.
-    const storage = await initStorage();
+    // fail here with an actionable message, not on the first upload. A
+    // process with no Workspace yet has nothing to mount, so this validates
+    // the profile and the mount waits for the one activation.
+    const storage = await mountStartupWorkspace();
     const profile = storage?.profile ?? parseStorageProfile();
     log.info(
       {
         structured: profile.structured.kind,
         blobs: profile.blobs.kind,
-        workspace: storage ? 'mounted' : 'awaiting activation',
+        workspace: storage ? 'mounted' : 'awaiting selection',
       },
       'Storage backends ready',
     );
diff --git a/apps/web/src/hooks/useElectron.ts b/apps/web/src/hooks/useElectron.ts
index 8b2605044..b505dd107 100644
--- a/apps/web/src/hooks/useElectron.ts
+++ b/apps/web/src/hooks/useElectron.ts
@@ -30,6 +30,13 @@ interface ElectronWorkspaceApi {
   get: () => Promise<WorkspaceStoreSnapshot>;
   set: (path: string) => Promise<WorkspaceStoreSnapshot>;
   removeRecent: (path: string) => Promise<WorkspaceStoreSnapshot>;
+  /**
+   * Restart the app onto the saved workspace.
+   *
+   * Present only on builds whose shell can apply a new workspace, which is
+   * what makes switching offerable at all once one is active. Never resolves.
+   */
+  restart?: () => Promise<void>;
 }
 
 interface ElectronWindowApi {
diff --git a/apps/web/src/i18n/resources/en/common.json b/apps/web/src/i18n/resources/en/common.json
index f70c2244f..46d67d99f 100644
--- a/apps/web/src/i18n/resources/en/common.json
+++ b/apps/web/src/i18n/resources/en/common.json
@@ -321,7 +321,10 @@
     "clickToSwitch": "Click to switch",
     "openPathFailed": "Failed to open path",
     "activationTimeout": "Opening Home folder “{{path}}” took longer than {{seconds}} seconds. Check that the cloud or network drive is available, then try again.",
-    "activationInProgress": "Another Home folder is still opening. Please wait for it to finish."
+    "activationInProgress": "Another Home folder is still opening. Please wait for it to finish.",
+    "restartRequired": "“{{path}}” has been saved as your Home folder. Restart the server to open it.",
+    "restarting": "Restarting to open “{{path}}”…",
+    "startupFailed": "Could not open your saved Home folder: {{reason}} Choose a folder to continue."
   },
   "canvasList": {
     "title": "Spaces",
diff --git a/apps/web/src/i18n/resources/zh-CN/common.json b/apps/web/src/i18n/resources/zh-CN/common.json
index 7619a3c24..847e34994 100644
--- a/apps/web/src/i18n/resources/zh-CN/common.json
+++ b/apps/web/src/i18n/resources/zh-CN/common.json
@@ -321,7 +321,10 @@
     "clickToSwitch": "点击切换",
     "openPathFailed": "打开路径失败",
     "activationTimeout": "打开“{{path}}”已超过 {{seconds}} 秒。请检查云盘或网络磁盘是否可用，然后重试。",
-    "activationInProgress": "另一个主目录仍在打开，请等待其完成。"
+    "activationInProgress": "另一个主目录仍在打开，请等待其完成。",
+    "restartRequired": "已将“{{path}}”保存为你的 Home 文件夹。重启服务器后生效。",
+    "restarting": "正在重启以打开“{{path}}”…",
+    "startupFailed": "无法打开已保存的 Home 文件夹：{{reason}} 请选择一个文件夹以继续。"
   },
   "canvasList": {
     "title": "Space",
diff --git a/apps/web/src/store/workspaceStore.ts b/apps/web/src/store/workspaceStore.ts
index db6f43d5e..f79f23959 100644
--- a/apps/web/src/store/workspaceStore.ts
+++ b/apps/web/src/store/workspaceStore.ts
@@ -35,6 +35,15 @@ interface WorkspacePersistence {
   load: () => Promise<{ path: string | null; recent: string[] }>;
   save: (path: string) => Promise<string[]>;
   remove: (path: string) => Promise<string[]>;
+  /**
+   * Restart onto the saved path, or `null` where nothing can.
+   *
+   * A server process serves one workspace for its lifetime, so a second
+   * choice only takes effect on restart. The Electron shell owns both the
+   * saved path and the server child, so it can do it; a browser tab cannot
+   * restart the server it is talking to, and says so instead.
+   */
+  restart: (() => Promise<void>) | null;
 }
 
 function loadLocalStorageRecents(): string[] {
@@ -75,6 +84,7 @@ const localStoragePersistence: WorkspacePersistence = {
     }
     return list;
   },
+  restart: null,
 };
 
 /**
@@ -88,11 +98,13 @@ interface ElectronWorkspaceLike {
   removeRecent: (
     path: string,
   ) => Promise<{ path: string | null; recent: string[] }>;
+  restart?: () => Promise<void>;
 }
 
 function makeElectronPersistence(
   api: ElectronWorkspaceLike,
 ): WorkspacePersistence {
+  const restart = api.restart;
   return {
     load: async () => {
       const snap = await api.get();
@@ -118,6 +130,7 @@ function makeElectronPersistence(
       const snap = await api.removeRecent(path);
       return snap.recent;
     },
+    restart: restart ? (): Promise<void> => restart() : null,
   };
 }
 
@@ -157,6 +170,15 @@ interface WorkspaceState {
   isSyncing: boolean;
   /** Last sync error, if any. */
   error: string | null;
+  /**
+   * A saved choice this server process will not adopt.
+   *
+   * Set when the user picks a different Home folder while one is already
+   * open and nothing here can restart the server — a browser tab. The
+   * selection is persisted, so the next launch opens it; until then the
+   * current one keeps serving.
+   */
+  pendingWorkspacePath: string | null;
 
   /**
    * Number of canvases currently in the active workspace. `null` means
@@ -220,8 +242,18 @@ function emitWorkspaceChanged(): void {
   window.dispatchEvent(new Event('workspace-changed'));
 }
 
+/** Whether the server refused because this process already has a workspace. */
+function isRestartRequired(error: unknown): boolean {
+  return (
+    error instanceof ApiError && error.code === 'WORKSPACE_RESTART_REQUIRED'
+  );
+}
+
 function workspaceActivationError(error: unknown, path: string): string {
   if (error instanceof ApiError) {
+    if (error.code === 'WORKSPACE_RESTART_REQUIRED') {
+      return i18n.t('workspace.restartRequired', { path });
+    }
     if (error.code === 'WORKSPACE_ACTIVATION_TIMEOUT') {
       const seconds =
         typeof (error.details as { seconds?: unknown } | undefined)?.seconds ===
@@ -263,6 +295,7 @@ export const useWorkspaceStore = create<WorkspaceState>()((set, get) => ({
   isReady: false,
   isSyncing: false,
   error: null,
+  pendingWorkspacePath: null,
   canvasCount: null,
 
   setWorldEnabled: (worldEnabled) => {
@@ -311,6 +344,17 @@ export const useWorkspaceStore = create<WorkspaceState>()((set, get) => ({
 
     set(fromInfo(info));
 
+    // A remembered folder the server could not open — moved, renamed, or on a
+    // drive that is not mounted. It came up serving nothing, so this is the
+    // picker with a reason rather than a first launch.
+    if (info.startupError) {
+      set({
+        error: i18n.t('workspace.startupFailed', {
+          reason: info.startupError,
+        }),
+      });
+    }
+
     // ── Managed mode: server has already activated; nothing to do. ──
     if (info.mode === 'managed') {
       // Free-mode leftovers are meaningless here.
@@ -366,17 +410,48 @@ export const useWorkspaceStore = create<WorkspaceState>()((set, get) => ({
     return false;
   },
 
+  /**
+   * Choose the Home folder.
+   *
+   * Two outcomes, and which one applies is the server's to say. With nothing
+   * open yet it activates and the app is ready. With a folder already open
+   * this process will not change what it is serving, so the choice is saved
+   * and applied by a restart — performed here where a shell can do it, and
+   * reported for the user to do where none can.
+   */
   selectWorkspace: async (path: string) => {
     if (get().mode === 'managed') {
       throw new Error('Workspace is locked by the server (managed mode)');
     }
-    set({ isSyncing: true, error: null, canvasCount: null });
+    set({
+      isSyncing: true,
+      error: null,
+      pendingWorkspacePath: null,
+      canvasCount: null,
+    });
     try {
       const info = await putWorkspacePath(path);
       const recent = await persistence.save(path);
       set({ ...fromInfo(info), recentWorkspaces: recent, isSyncing: false });
       emitWorkspaceChanged();
     } catch (err) {
+      if (isRestartRequired(err)) {
+        // Save first, then restart: the restart is what opens it, so a
+        // relaunch that raced an unsaved choice would reopen the old folder.
+        const recent = await persistence.save(path);
+        set({ recentWorkspaces: recent });
+        if (persistence.restart) {
+          set({ error: i18n.t('workspace.restarting', { path }) });
+          await persistence.restart();
+          return;
+        }
+        set({
+          pendingWorkspacePath: path,
+          error: workspaceActivationError(err, path),
+          isSyncing: false,
+        });
+        throw err;
+      }
       const message = workspaceActivationError(err, path);
       set({ error: message, isSyncing: false });
       throw err;
diff --git a/packages/shared/src/types/api/workspace.ts b/packages/shared/src/types/api/workspace.ts
index d370839ac..69ab4036c 100644
--- a/packages/shared/src/types/api/workspace.ts
+++ b/packages/shared/src/types/api/workspace.ts
@@ -22,7 +22,14 @@ export const workspaceModeSchema = z.enum(['free', 'managed']);
 export type WorkspaceMode = z.infer<typeof workspaceModeSchema>;
 
 export const workspaceCapabilitiesSchema = z.object({
-  /** Whether the user is allowed to change workspace at runtime. */
+  /**
+   * Whether the user may choose the workspace at all.
+   *
+   * False only in managed mode, where the operator fixed it. True does not
+   * mean the running server will adopt the choice: a process serves one
+   * workspace for its lifetime, so once `configured` is true a different
+   * selection is saved and applied on restart.
+   */
   canChangeWorkspace: z.boolean(),
   /** Whether the server can show a native folder picker. */
   nativePicker: z.boolean(),
@@ -38,6 +45,15 @@ export const workspaceInfoSchema = z.object({
   name: z.string().nullable(),
   /** Stable hidden World canvas identity, or null before configuration. */
   worldCanvasId: z.string().min(1).nullable(),
+  /**
+   * Why the workspace this server was started on could not be opened.
+   *
+   * Non-null only when the process was given a remembered path and failed to
+   * open it — a folder that moved, was renamed, or sits on a drive that is not
+   * mounted. The server then serves nothing, so the client shows the picker;
+   * this is what distinguishes that from a first launch.
+   */
+  startupError: z.string().nullable(),
   capabilities: workspaceCapabilitiesSchema,
 });
 export type WorkspaceInfo = z.infer<typeof workspaceInfoSchema>;

From cb6540737fc4954c132e21cfcf06076d9a0ec15c Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 18:33:43 +0800
Subject: [PATCH 18/20] docs(storage): record the symmetric ports and the
 one-Workspace process
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two designs the code no longer has: a blob port reached through a scope
descriptor, and a storage lifecycle built to move a live process between
Workspaces. The proposal now says why the second one went — issue #126,
and the staged-mount finding that reads as a bug report against it —
rather than leaving §12.6.5 specifying machinery nothing implements.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ufq2A7GReTSpRdtApkpdNZ
---
 docs/architecture/canvas-storage.md     |  62 ++++++----
 docs/architecture/desktop-startup.md    |  12 +-
 docs/proposals/multi-backend-storage.md | 153 +++++++++++++++---------
 3 files changed, 139 insertions(+), 88 deletions(-)

diff --git a/docs/architecture/canvas-storage.md b/docs/architecture/canvas-storage.md
index 3d53885e4..3e076305d 100644
--- a/docs/architecture/canvas-storage.md
+++ b/docs/architecture/canvas-storage.md
@@ -13,10 +13,13 @@ compatibility facade.
 **One handle per Space.** `space(canvasId)` vends every storage capability for
 one Space: its record (`read`/`write`), the parts it holds (`nodes`, `changes`,
 `tasks`, `events`), an isolated substrate for a namespace's own store
-(`extension`), one blob scope per user-visible area (`blobs`, `guide`,
+(`extension`), one blob scope per user-visible area (`artifacts`, `guide`,
 `memory`, `uploads`), and — where the backend has one — its directory
-(`diskTree`, `null` elsewhere). It is a composition-layer facade, not a port
-type: `StructuredStore` and `BlobStore` keep their interfaces and their
+(`diskTree`, `null` elsewhere). Both ports are reached the same way —
+`StructuredStore.space(id)` returns the structured handle, `BlobStore.space(id)`
+returns the blob areas — and the facade flattens them, so which axis holds a
+part is storage's business rather than its callers'. It is a composition-layer
+facade, not a port type: the two ports keep their interfaces and their
 independence, and are joined only in the layer that already owns every
 cross-store rule.
 
@@ -25,20 +28,29 @@ reads and writes all go through those ports. `CanvasStore` remains an internal
 Disk primitive and compatibility-test seam, not an application service, and
 nothing in production imports it.
 
-**A mount belongs to one Workspace.** Startup validates the profile without
-opening anything when free mode has no Workspace yet. Activating one prepares
-and migrates the directory in a disposable child process, then stages both
-backend connections, bootstraps the Workspace's World through
-`SpaceRepository.ensureWorld()`, and only then publishes the path and the
-mount together — in one synchronous block, so no request sees one moved
-without the other. Everything that can fail happens while the previous
-Workspace is still serving, and a failure leaves it serving. Graceful shutdown
-closes the mount. The child-process isolation is required because synchronous
-filesystem calls against cloud, network, or virtual drives can block
-indefinitely; a stuck preparation is terminated after 70 seconds with
+**A process serves one Workspace** (issue #126), so the storage lifecycle is
+linear: mount, serve, close. Startup validates the profile without opening
+anything when there is no Workspace yet; adopting one prepares and migrates
+the directory in a disposable child process, commits the path, opens both
+backend connections, and bootstraps the Workspace's World through
+`SpaceRepository.ensureWorld()`. A failure at any step leaves the process
+unconfigured rather than half-activated — the state the client already
+recovers from by showing the picker. Graceful shutdown closes the mount.
+Nothing in storage records _which_ Workspace it was opened against, because a
+mount that exists is the mount for the one this process serves.
+
+The child-process isolation is required because synchronous filesystem calls
+against cloud, network, or virtual drives can block indefinitely; a stuck
+preparation is terminated after 70 seconds with
 `WORKSPACE_ACTIVATION_TIMEOUT`. Concurrent activation attempts return
-`WORKSPACE_ACTIVATION_IN_PROGRESS`. Managed-mode startup prepares
-synchronously before the Server accepts requests, then mounts.
+`WORKSPACE_ACTIVATION_IN_PROGRESS`, and asking for a Workspace other than the
+active one returns `WORKSPACE_RESTART_REQUIRED` without mutating anything —
+the choice is valid, and applying it is the next process's job. The Workspace
+is named by `HUABU_WORKSPACE` (the operator's, locked, and a failure to open
+it fails the boot), by `HUABU_WORKSPACE_STARTUP` (the shell's record of the
+user's own choice, which stays free mode and reports a failure through
+`WorkspaceInfo.startupError`), or by the single runtime activation a
+still-unconfigured process accepts.
 
 The Disk-only capabilities a feature can still reach are named for the backend
 that has them: `space(canvasId).diskTree` for the Space directory, the sidecar
@@ -72,12 +84,12 @@ call site, sharing the matrix's wording.
     space.json                   # { canvasId, title, version, state:{nodes,edges,...}, createdAt, updatedAt }
     nodes/
       <safe(label)>.md            # frontmatter: id/type/label/src/... + content(markdown body)
-    .artifacts/                   # Disk BlobStore mapping for this Space
+    .artifacts/                   # `artifacts` blob area for this Space
       <artifactId><ext>           # raw uploads (PDF / image / video / cover)
-    skill.md                      # user-authored RFS access guide (space-guide blob scope)
-    .memory/                      # hidden, AI-private (space-memory blob scope)
+    skill.md                      # user-authored RFS access guide (`guide` blob area)
+    .memory/                      # hidden, AI-private (`memory` blob area)
       space.md                    # Space memory body
-    .upload/                      # hidden upload scratch (space-upload blob scope)
+    .upload/                      # hidden upload scratch (`uploads` blob area)
     .ext/<owner>.<name>/          # one directory per extension namespace
     .history/                     # hidden dir; also the Agenetes namespace storage.root
       chat_v2/                    # canonical chat log — owned by Agenetes L2, NOT CanvasStore
@@ -105,7 +117,7 @@ Key points:
 - Persistent `frameRef` and `nodeRef` nodes have no markdown sidecars and store only their respective type plus `{ target: { canvasId, nodeId } }` and World-owned React Flow state. A `frameRef` is a Container snapshot of a source Frame, may recursively own matching `frameRef` / `nodeRef` descendants, and never reconciles later source hierarchy changes; direct references remain children of the matching `canvasRef`. `SET_PORTAL_NODE_PINS` is their sole create/remove path.
 - `GET /api/canvas/:worldCanvasId/references` batch-resolves Portal titles and pinned source-node display data for both reference types without writing it into World topology. Results distinguish `ok`, `canvas-missing`, and `node-missing`; storage or parse failures remain request errors.
 - Node filenames are `safe(label).md`; the node's stable id lives in the `id:` frontmatter field.
-- The Disk `BlobStore` maps **one scope per user-visible area** of a Space: artifacts to `.artifacts/` (blobs named `<artifactId><ext>`, no manifest — the filename is the URL key), the memory body to `.memory/`, upload scratch to `.upload/`, and the user-authored guide to the Space root. Naming the areas is what keeps blob names flat; hierarchical names are excluded for every backend. Callers reach them as `space(canvasId).blobs` / `.memory` / `.uploads` / `.guide`: `put()` requires an existing Space record, while reads and `deleteAll()` remain available for recovery after a record goes missing. The guide scope is bounded by its **member names** rather than by a directory, because its area is the Space root — a scope that claimed the folder would list `space.json` and delete the Space on `deleteAll()`. Space deletion sweeps every area, since on a backend where dropping the record does not remove the area the bytes sit in, an unswept kind is an orphan. `CanvasStore` owns no artifact methods. Only the Disk blob and structured backends are implemented and selectable today.
+- `BlobStore.space(canvasId)` returns **one scope per user-visible area** of a Space, which Disk maps to: artifacts to `.artifacts/` (blobs named `<artifactId><ext>`, no manifest — the filename is the URL key), the memory body to `.memory/`, upload scratch to `.upload/`, and the user-authored guide to the Space root. Naming the areas is what keeps blob names flat; hierarchical names are excluded for every backend. Callers reach them through the facade as `space(canvasId).artifacts` / `.memory` / `.uploads` / `.guide`: `put()` requires an existing Space record, while reads and `deleteAll()` remain available for recovery after a record goes missing. The guide area is bounded by its **member names** rather than by a directory, because it sits at the Space root — a scope that claimed the folder would list `space.json` and delete the Space on `deleteAll()`. Space deletion sweeps every area, since on a backend where dropping the record does not remove the place the bytes sit in, an unswept area is an orphan. `CanvasStore` owns no artifact methods. Only the Disk blob and structured backends are implemented and selectable today.
 
 - **Storage lends a place, not a data API.** `space(canvasId).extension(namespace)` returns an isolated substrate — a reserved directory on Disk, a table prefix or schema on a future backend — that a namespace builds its own store on. Storage validates the `<owner>.<name>` token, creates the namespace on demand, and destroys it with the Space; it never sees what is inside, and offers no read or write of its own. A port member per feature would oblige every future backend to model data it has no stake in, and a namespaced key/value member would fix one access shape for every owner forever. `extension()` returns `null` for a Space that does not exist, which is what stops an owner's bookkeeping write from resurrecting a Space that was just deleted. Memory-worker state (`huabu.memory`) and the debug prompt log (`huabu.prompt.log`) are the first two namespaces.
 - Remote PDF preprocessing writes the already-fetched source bytes into the Space BlobStore as `artifact-<id>.pdf` before structured persistence and replaces the node's remote `src` with that key. As with other artifact imports, this blob write precedes the node write operation; a later structured persistence failure may therefore leave an unreferenced blob until Space deletion, while a blob-write failure degrades to retaining the remote URL.
@@ -122,7 +134,7 @@ Key points:
 
 | Path                           | Responsibility                                                                                                                                                                                                                                        |
 | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ports/blob.ts`                | Backend-neutral `BlobStore` connection/scope contract for opaque bytes and bounded materialization leases.                                                                                                                                            |
+| `ports/blob.ts`                | Backend-neutral `BlobStore` connection, its per-Space `SpaceBlobs` areas, and bounded materialization leases.                                                                                                                                         |
 | `ports/structured.ts`          | Backend-neutral `StructuredStore`, the `SpaceRepository` collection, and the `SpaceHandle` composite: record read/ordered write, nodes, changes, Tasks, events, and the extension substrate.                                                          |
 | `ports/namespace.ts`           | The `<owner>.<name>` grammar for an extension namespace — the only thing storage validates about an extension.                                                                                                                                        |
 | `ports/contracts/`             | Reusable Space-collection, node, Space-write, log, blob, extension, and store suites; guarantees are the minimum every adapter implements.                                                                                                            |
@@ -130,7 +142,7 @@ Key points:
 | `backends/disk/legacy/`        | The legacy `CanvasStore` and its synchronous adapter primitives, bounded Workspace-qualified cache, and process-local node tombstones.                                                                                                                |
 | `compatibility/canvas.ts`      | Residual Disk reads plus direct-module create/delete test fixtures; lifecycle writers are not exported from the public storage barrel.                                                                                                                |
 | `space-lifecycle-admission.ts` | Backend-neutral, writer-preferring single-process coordinator shared by structured mutations and blob puts during a delete session.                                                                                                                   |
-| `profile.ts` and `storage.ts`  | Backend selection, cross-axis validation, the Workspace-scoped staged mount, the `space(canvasId)` facade, blob scopes, and the blob-first deletion saga.                                                                                             |
+| `profile.ts` and `storage.ts`  | Backend selection, cross-axis validation, the process-wide mount, the `space(canvasId)` facade, blob areas, and the blob-first deletion saga.                                                                                                         |
 | `capabilities.ts`              | Which product features a profile cannot serve, and why — consulted at startup and by each Disk-only feature's own refusal.                                                                                                                            |
 | `testing.ts`                   | Mounts a real profile onto a temporary Workspace through the production lifecycle, so a product test is written once and run against every profile.                                                                                                   |
 | `index.ts`                     | Public exports only; application code imports here rather than reaching into an adapter.                                                                                                                                                              |
@@ -140,9 +152,9 @@ The Disk structured adapter and compatibility facade resolve the same cached leg
 
 Canvas persistence DTOs and the write coordinator live under `modules/canvas/`; Disk record paths, name indexes, and directory-handle arbitration live inside the Disk adapter; boot migrations remain under `modules/workspace/migrations/`; generic filesystem and Markdown codecs live under `utils/`. `canvasRoot()` validates the identifier and then verifies that the resolved Space directory remains a strict descendant of the active Workspace before any downstream Disk operation receives it. `module-boundaries.test.ts` enforces the storage dependency direction, keeps the deprecated forwarding-shim importer lists shrinking, pins the exact production consumer list of the Disk `diskTree` capability, and reads `product-boundary.test.ts` to reject Disk vocabulary in the suite that is supposed to prove portability.
 
-Space deletion is serialized against composed blob puts by a writer-preferring admission coordinator and holds an active-Workspace lease across blob cleanup and structured destruction. `beginDelete()` acquires the exclusive session before blob I/O; `finish()` removes structured state, while `abort()` releases the fence without doing so. Blobs are swept before structure so a failed sweep can be retried while the Space record still names them. Puts already admitted may finish; a put queued behind a successful deletion rechecks existence and fails without recreating blobs, while a failed blob sweep leaves the record available for retry. Mutations through existing Space handles and repositories reject while deletion is active or queued; reads remain available for cleanup. Residual direct-filesystem features — bundle import/export, reveal, the built-in file tools, external-note claim, and Windows handle coordination — are outside this repository fence; they are declared Disk-only in the capability matrix rather than treated as blockers, and off Disk they are unavailable rather than emulated.
+Space deletion is serialized against composed blob puts by a writer-preferring admission coordinator keyed on the Space. `beginDelete()` acquires the exclusive session before blob I/O; `finish()` removes structured state, while `abort()` releases the fence without doing so. Blobs are swept before structure so a failed sweep can be retried while the Space record still names them. Puts already admitted may finish; a put queued behind a successful deletion rechecks existence and fails without recreating blobs, while a failed blob sweep leaves the record available for retry. Mutations through existing Space handles and repositories reject while deletion is active or queued; reads remain available for cleanup. Residual direct-filesystem features — bundle import/export, reveal, the built-in file tools, external-note claim, and Windows handle coordination — are outside this repository fence; they are declared Disk-only in the capability matrix rather than treated as blockers, and off Disk they are unavailable rather than emulated.
 
-Retained Disk Space repository and handle instances, blob scopes, and legacy `CanvasStore` instances reject use after the active Workspace changes. Each `spaces()` call returns a fresh Workspace-bound handle and each read rescans current Disk state. The Workspace-qualified LRU is cleared and rebuilt on the next lookup after a switch. The delete-session contract covers overlapping operations through one configured backend instance. Disk realizes it with the shared process-local coordinator; it is not a multi-process transaction or distributed lock, and a SQL adapter must supply an equivalent backend-instance fence using its own mechanisms.
+Retained Disk Space repository and handle instances, blob scopes, and legacy `CanvasStore` instances reject use after the active Workspace changes — a state production no longer reaches, and the guard that keeps a test moving between temporary Workspaces from reading a stale one. Each `spaces()` call returns a fresh Workspace-bound handle and each read rescans current Disk state. The Workspace-qualified LRU is cleared and rebuilt on the next lookup. The delete-session contract covers overlapping operations through one configured backend instance. Disk realizes it with the shared process-local coordinator; it is not a multi-process transaction or distributed lock, and a SQL adapter must supply an equivalent backend-instance fence using its own mechanisms.
 
 The `chat_v2/` two-tier log and `threads.json` remain owned by Agenetes L2 (`FileEventLogStore`, `FileTurnStore`, and `FileThreadStore`), wired in [agenetes/drivers.ts](../../apps/server/src/modules/agent/agenetes/drivers.ts); see [agent-architecture.md](./agent-architecture.md) §5. Workspace activation is coordinated by `apps/server/src/modules/workspace-activation.ts`; the isolated child entry is `workspace-prepare.worker.ts`, and the ordered migration sequence is centralized in `workspace-prepare.ts` with migration implementations under `modules/workspace/migrations/`.
 
diff --git a/docs/architecture/desktop-startup.md b/docs/architecture/desktop-startup.md
index 4056daa40..2326ae9eb 100644
--- a/docs/architecture/desktop-startup.md
+++ b/docs/architecture/desktop-startup.md
@@ -1,7 +1,7 @@
 # Desktop Cold Start
 
 > What the user sees between double-clicking Huabu and the canvas list appearing, and which parts of the system own each phase.
-> Last updated: 2026-07-31
+> Last updated: 2026-08-20
 
 ---
 
@@ -11,20 +11,22 @@
 app.whenReady()
   ├─ splash window opens                 ← first thing on screen
   ├─ shell-PATH probe, port allocation
-  ├─ server fork + TCP readiness wait
+  ├─ server fork + TCP readiness wait    ← HUABU_WORKSPACE_STARTUP = saved path,
+  │                                        so the server mounts while forking
   ├─ main window created (show: false), loadURL(http://127.0.0.1:<port>)
   ├─ renderer parses the entry graph     ← nothing paints during this
   ├─ 'ready-to-show'  → main window shown, splash closed
-  └─ renderer: init() → GET /api/workspace → PUT /api/workspace (activation)
+  └─ renderer: init() → GET /api/workspace → ready
+                        (first launch only: PUT /api/workspace to activate)
                                            ← WorkspaceLoadingScreen covers this
 ```
 
-When no remembered workspace can be activated, the workspace guard redirects to the stable `/setup` route instead of rendering the setup page inside the guard. This keeps the route that owns the post-activation navigation mounted while `selectWorkspace()` publishes `isReady`; after activation it navigates through `/` to `/spaces` (or World when enabled).
+When there is no remembered workspace, or the server reports it could not open one (`WorkspaceInfo.startupError`), the workspace guard redirects to the stable `/setup` route instead of rendering the setup page inside the guard. This keeps the route that owns the post-activation navigation mounted while `selectWorkspace()` publishes `isReady`; after activation it navigates through `/` to `/spaces` (or World when enabled).
 
 Two independent costs dominate a cold start:
 
 1. **Entry-graph evaluation.** One long synchronous task in the renderer. Its cost is the size of the first-screen JavaScript graph, and it is paid in full on the first launch after an install or an update, when Chromium's per-origin code cache is empty. (It is also paid on _every_ launch when the shell cannot get its preferred port, because the origin — and therefore the cache — changes with the port.)
-2. **Workspace activation.** The server always boots with no workspace; the remembered path lives in the main process, so the renderer has to `PUT /api/workspace` after it loads. Activation forks the preparation worker and runs the migration chain over the workspace root, which is sub-second on local disk and seconds on a cloud-sync mount (Google Drive, iCloud, OneDrive).
+2. **Workspace preparation.** The migration chain runs over the workspace root, which is sub-second on local disk and seconds on a cloud-sync mount (Google Drive, iCloud, OneDrive). Because the shell owns `workspace.json` and the server child, it hands the remembered path over at fork time as `HUABU_WORKSPACE_STARTUP` — so this happens in parallel with the window opening rather than after the renderer loads. The renderer only activates on a first launch, when there is nothing remembered to hand over. A process serves one workspace for its lifetime (issue #126): choosing another saves it and relaunches the app, which is the same sequence again.
 
 ## 2. Why the splash is a separate window
 
diff --git a/docs/proposals/multi-backend-storage.md b/docs/proposals/multi-backend-storage.md
index 208b4e1d7..ed73e76bf 100644
--- a/docs/proposals/multi-backend-storage.md
+++ b/docs/proposals/multi-backend-storage.md
@@ -366,7 +366,6 @@ ports:
 ```ts
 interface Storage {
   readonly profile: StorageProfile;
-  readonly workspacePath: string;
   readonly structured: StructuredStore;
   readonly blobs: BlobStore;
   space(canvasId: string): Space;
@@ -380,24 +379,32 @@ ports, so it is where the two are allowed to meet. The barrel exports a free
 `canvasBlobs()` is already called; that is an ergonomic shorthand for the same
 method, not a second design.
 
-`Space` is a **composition-layer facade, not a port type**.
-`StructuredStore.space()` keeps returning the structured-only `SpaceHandle`,
-`BlobStore.scope()` keeps returning a `BlobScope`, and neither port imports the
-other (§6.3). They are joined in the layer that already owns every cross-store
-rule: the blob-put precondition ("bytes only for a Space whose record exists")
-and the blob-first delete saga.
+**Both ports are reached the same way.** `StructuredStore.space(id)` returns
+the structured `SpaceHandle`; `BlobStore.space(id)` returns `SpaceBlobs`, one
+member per user-visible area. A Space is the unit the application addresses on
+either axis, so a port that made the caller assemble a descriptor first would
+be the odd one out — and the asymmetry was visible in the facade, which built
+four scope descriptors by hand beside one structured handle.
 
-The join cannot move down into a port, for three separate reasons:
+`Space` is a **composition-layer facade, not a port type**. The two ports keep
+their interfaces and their independence — neither imports the other (§6.3) —
+and are joined in the layer that already owns every cross-store rule: the
+blob-put precondition ("bytes only for a Space whose record exists") and the
+blob-first delete saga. The facade flattens both handles, so every durable part
+of a Space sits at one level and which axis stores it stays storage's business.
+
+The join cannot move down into a port, for two separate reasons:
 
 - the two axes are configured independently, so a `SpaceHandle` that vended
   blobs would oblige the Disk structured adapter to construct an Azure blob
-  scope;
+  handle;
 - deletion ordering deliberately keeps remote blob I/O outside any database
   transaction (§6.1); a handle owning both would move that ordering inside an
-  adapter;
-- `BlobScopeRef` is a union whose only member is `canvas` today. Workspace
-  assets and agent scratch have no Space, and a blob store reachable only
-  through a Space handle could not serve them.
+  adapter.
+
+A blob area with no Space — workspace assets, agent scratch — is a different
+entry point on the connection when something needs one, not a reason to make
+every caller name a descriptor today.
 
 What is wrong today is therefore only the spelling.
 `getStructuredStore().space(id)` and `canvasBlobs(id)` are two entry points —
@@ -517,10 +524,10 @@ bytes, not application records", with names that are the existing
 holds unchanged. One detail needs a decision and it has a cheap answer: the
 Disk adapter maps the single canvas scope onto `.artifacts/`, so a blob named
 `skill.md` would land in a hidden directory rather than at the Space root where
-a user authors it. Add one `BlobScopeRef` kind per user-visible area. That is a
-union member and a directory constant per adapter; it keeps the Disk layout a
-user sees unchanged, and it avoids hierarchical names, which §7.1 excluded for
-every backend and which would be the expensive answer to the same problem.
+a user authors it. Give `SpaceBlobs` one member per user-visible area. That is
+a member and a placement rule per adapter; it keeps the Disk layout a user sees
+unchanged, and it avoids hierarchical names, which §7.1 excluded for every
+backend and which would be the expensive answer to the same problem.
 
 Rename and per-key delete stay **unsupported**, as they are today. A human will
 eventually want to remove a `skill.md`, and the honest answer until some
@@ -620,8 +627,8 @@ port in
 contract suite is
 [`ports/contracts/blob-store.contract.ts`](../../apps/server/src/modules/storage/ports/contracts/blob-store.contract.ts).
 This section is a transcription of that file and must be updated with it; the
-code is authoritative when they disagree. The shape is connection → scope
-rather than one flat key space:
+code is authoritative when they disagree. The shape is connection → Space →
+area rather than one flat key space:
 
 ```ts
 interface BlobStore {
@@ -629,7 +636,14 @@ interface BlobStore {
   init(): Promise<void>;
   health(): Promise<StorageHealth>;
   close(): Promise<void>;
-  scope(ref: BlobScopeRef): BlobScope;
+  space(canvasId: string): SpaceBlobs;
+}
+
+interface SpaceBlobs {
+  readonly artifacts: BlobScope;
+  readonly guide: BlobScope;
+  readonly memory: BlobScope;
+  readonly uploads: BlobScope;
 }
 
 interface BlobScope {
@@ -660,7 +674,7 @@ they bind every future adapter:
   must emulate rather than a neutral one. It is accepted — callers pass
   `src`-shaped values and the basename rule is what makes that work — but it
   is the mirror image of the §13 risk about SQL backends emulating a directory
-  tree, and it should be revisited before a scope kind needs hierarchy.
+  tree, and it should be revisited before an area needs hierarchy.
 - **`put()` has no options.** Content type is not stored; it is inferred from
   the name at the HTTP boundary. That is sufficient while `sendBlob` is the
   only delivery path, and it is exactly what a signed-URL delivery capability
@@ -2262,15 +2276,21 @@ than by reading:
   can satisfy. The record became an argument, and each caller now reads in the
   shape its request has — which is what made `readMany` earn its place rather
   than merely have one.
-- **A staged mount must capture what it replaces when it is staged.**
-  Committing a Workspace path detaches the mount that no longer describes it,
-  so a `commit()` reading the process holder at swap time finds nothing to
-  close and drops the previous connections. Invisible on Disk, whose `close()`
-  is a no-op; a connection leak the moment SQLite lands.
+- **The staged mount was the wrong answer to a question nobody asked.** The
+  first implementation of §12.6.5 opened connections against a Workspace that
+  was not active yet, published them and the path in one synchronous block, and
+  captured the mount it replaced so a later `commit()` could close it — because
+  committing a path detaches the mount that no longer describes it, and a
+  `commit()` reading the process holder at swap time would find nothing to
+  close and leak the previous connections. Every part of that existed to move a
+  live process between two Workspaces. Issue #126 established that this is not
+  a product requirement; §12.6.5 below is the lifecycle that replaced it, and
+  the leak, the leases, the stale-mount check, and `Storage.workspacePath` all
+  went with the staging.
 - **A blob scope for the Space root cannot be a directory scope.** Its area is
   shared with `space.json` and every node directory, so `list()` would claim
-  storage's own records and `deleteAll()` would remove the Space. The
-  `space-guide` scope is bounded by its member names instead — a fixed set is a
+  storage's own records and `deleteAll()` would remove the Space. The `guide`
+  area is bounded by its member names instead — a fixed set is a
   tighter namespace than a directory, not a looser one.
 - **The resurrection guard belonged in the port.** Several owners each carried
   their own check that a Space directory still existed before writing ad-hoc
@@ -2278,7 +2298,7 @@ than by reading:
   states it once, and the per-owner guards were deleted rather than moved.
 
 One item in scope below was **narrowed deliberately**. Upload scratch received
-its own `BlobScopeRef` kind, so the area is named, swept on delete, and free to
+its own `SpaceBlobs` area, so it is named, swept on delete, and free to
 diverge in retention — but its writers still reach it through the `fs-sandbox`
 path, because RFS upload is a streaming HTTP handler and path classification,
 not the bare `readFileSync`/`writeFile` §6.4.2's exception describes. Routing
@@ -2314,12 +2334,12 @@ their async adapters own repository access once per request.
 #### 12.6.2 One `space(canvasId)` handle
 
 `Storage` gains `space(canvasId)`, the composition-layer facade of §6.4.1,
-joining the structured handle with the Space's blob scope and any
+joining the structured handle with the Space's blob areas and any
 backend-specific members; the barrel exports a free `space(canvasId)`
 shorthand for `getStorage().space(canvasId)`, matching how `canvasBlobs()` is
-already called. `StructuredStore` and `BlobStore` keep their current interfaces
-and their independence — neither imports the other — and the facade is the only
-new type. The existing `getStructuredStore().space(id)` and `canvasBlobs(id)`
+already called. `StructuredStore` and `BlobStore` keep their independence —
+neither imports the other — and both vend one handle per Space, so the facade
+is the only new type. The existing `getStructuredStore().space(id)` and `canvasBlobs(id)`
 call sites migrate to it.
 
 The residual Disk Space directory becomes `diskTree` on that handle, typed by
@@ -2371,12 +2391,12 @@ substrate is an Agenetes port change, not a storage one.
 
 **D — blob.** `skill.md`, the memory body (`.memory/space.md`), and upload
 scratch (`.upload/`) become blobs, each user-visible area getting its own
-`BlobScopeRef` kind so the Disk paths a user sees are unchanged and retention
+`SpaceBlobs` member so the Disk paths a user sees are unchanged and retention
 can diverge from artifacts later without moving bytes again. These qualify
 under §6.4.2's "simplifies Disk on its own merits" exception: each is a bare
 `readFileSync` / `writeFile` against a path the caller assembled, and the move
 retires those plus one resolver in the memory sandbox. The new machinery is a
-union member and a directory constant per area. Rename and per-key delete stay
+handle member and a directory constant per area. Rename and per-key delete stay
 unsupported, as they are today.
 
 Upload scratch got its scope kind — so the area is named, swept on delete, and
@@ -2419,15 +2439,32 @@ what is offered here is a place to put data. The first-party consumers in
 key/value helper **over** the substrate may be extracted into `utils/` if a
 second owner wants the same access shape, but never as a port member.
 
-#### 12.6.5 Workspace-scoped storage lifecycle and World bootstrap
-
-Storage construction receives the resolved Workspace path. Startup may hold
-only a validated profile while free mode has no active Workspace; activating
-one stages and initializes both backend connections, asks the structured
-collection to ensure its one stable World, commits the Workspace path,
-atomically swaps the process-wide storage holder, and then closes the previous
-connections. A failed stage leaves the old Workspace and connections active.
-Graceful Server shutdown closes the mounted stores.
+#### 12.6.5 One Workspace per process, and World bootstrap
+
+Startup may hold only a validated profile while there is no active Workspace;
+adopting one
+prepares and migrates the directory, commits the path, opens both backend
+connections, and asks the structured collection to ensure its one stable World.
+A failure at any step leaves the process unconfigured rather than
+half-activated. Graceful Server shutdown closes the mounted stores.
+
+**A process serves one Workspace.** Issue #126 settled that changing it is
+restart-bound, and that removed the whole staged-swap apparatus this section
+originally specified — no connection is opened against an inactive path, no
+mount is published atomically beside a path, nothing captures what it replaces,
+no operation lease keeps a request on one Workspace, and `Storage` carries no
+`workspacePath` to recognise a stale mount by. Asking a running server for a
+different Workspace returns `WORKSPACE_RESTART_REQUIRED` and mutates nothing.
+The Workspace is named at startup by `HUABU_WORKSPACE` (the operator's, locked,
+failing the boot if it cannot be opened), by `HUABU_WORKSPACE_STARTUP` (a
+shell's record of the user's own choice, which stays free mode and reports a
+failure through `WorkspaceInfo.startupError` so the client can pick again), or
+by the single runtime activation a still-unconfigured process accepts — the
+only route a browser deployment has, since `localStorage` cannot configure a
+server before it starts.
+
+This is also what lets a backend with no Workspace at all — Postgres paired
+with Azure Blob — stop answering a question that was never its own.
 
 `SpaceRepository.ensureWorld()` is the backend-neutral bootstrap hook. It
 returns the existing stable World or creates exactly one version-0 World when
@@ -2446,8 +2483,8 @@ its contents.
 
 The product-level harness is `storage/testing.ts`: it mounts a real profile
 onto a temporary Workspace through the production lifecycle — prepared
-Workspace, staged connections, `ensureWorld()`, atomic swap — rather than
-swapping in a stub. `product-boundary.test.ts` runs the exit criterion against
+Workspace, opened connections, `ensureWorld()` — rather than swapping in a
+stub. `product-boundary.test.ts` runs the exit criterion against
 every profile in `PRODUCT_STORAGE_PROFILES`, naming no directory, filename, or
 `space.json`; Phase 5 adds one entry to that list and the same behaviours are
 covered for SQLite. Elsewhere, product tests replace only storage connections
@@ -2472,9 +2509,9 @@ In scope: Canvas/agent/web/interactive-view/Task structured reads, World target
 reads, RFS node metadata, built-in file-tool node enrichment, external-note
 membership checks, the `space(canvasId)` facade and its `diskTree` member, the
 extension substrate and its first two namespaces, the disposition-D blob
-scopes, the capability matrix for the A families, storage mount/remount/close,
-World bootstrap, architecture documentation, and the shared product-level
-backend harness needed for Phase 5.
+areas, the capability matrix for the A families, storage mount/close, World
+bootstrap, architecture documentation, and the shared product-level backend
+harness needed for Phase 5.
 
 Out of scope: a SQLite adapter or schema, Disk→SQLite data migration, SQLite
 profile registration, Postgres/Azure, the portable change-notification
@@ -2495,14 +2532,13 @@ guarantees.
    The SQLite preview branch forks from Phase 4.5, so it does not yet satisfy
    the port it will be rebased onto. What it owes against the implemented
    §12.6, concretely:
-   - `SpaceRepository.ensureWorld()`, and a mount that survives being staged
-     against a Workspace that is not active yet;
+   - `SpaceRepository.ensureWorld()`, run once as part of opening the mount;
    - `SpaceNodes.readMany` / `list` / `stream`, agreeing with `read` about a
      node — the node contract asserts exactly this;
    - the `sqlite` case of `SpaceSubstrate`, plus destroying a namespace with
      the Space, which on Disk falls out of placement and there will not;
-   - one blob-scope placement per `BlobScopeRef` kind, or an explicit refusal
-     for an area it does not serve;
+   - one blob placement per `SpaceBlobs` area, or an explicit refusal for an
+     area it does not serve;
    - an entry in `PRODUCT_STORAGE_PROFILES`, which is what runs
      `product-boundary.test.ts` against it, and its place in the
      implemented-backend and selectable-backend lists.
@@ -2513,9 +2549,10 @@ guarantees.
    a row in `capabilities.ts` for each disposition-**A** family, plus whatever
    disposition **B** its own consumers turn out to need (§6.4.3). Its existing
    note that SQLite stays unselectable while physical Disk reads, World
-   bootstrap, blob placement, import/export, and Workspace remounting have one
-   authority only in the Disk profile is the same list §12.6 resolved — some by
-   porting, the rest by declaring.
+   bootstrap, blob placement, and import/export have one authority only in the
+   Disk profile is the same list §12.6 resolved — some by porting, the rest by
+   declaring. Workspace remounting is off that list entirely: there is no
+   remount to have an authority for.
 
    The honest measure of Phase 4.6 is how much of this list is _additive_.
    Nothing above asks for a feature module to change.
@@ -2672,9 +2709,9 @@ guarantees.
   name-derived value computed at the HTTP boundary, because signed delivery
   bypasses `sendBlob` entirely — which means `put()` grows an options
   parameter (§7.1).
-- Should any scope kind ever need hierarchical names? The contract currently
+- Should any blob area ever need hierarchical names? The contract currently
   collapses names to a single segment for every backend (§7.1). §6.4.3 proposes
-  answering "no" and adding a `BlobScopeRef` kind per user-visible area
+  answering "no" and giving each user-visible area its own `SpaceBlobs` member
   instead, so `skill.md`, the memory body, artifacts, and upload scratch stay
   where a user sees them today without the port learning paths.
 - Do user-authored blobs need rename and per-key delete? Answered "not until a

From 8bb382e0e624451fe2efb9aba2afe70ab75a68fe Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 20 Aug 2026 19:00:51 +0800
Subject: [PATCH 19/20] refactor(storage): stop asking which workspace a Disk
 handle belongs to
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every Disk handle, repository, blob scope, and log/task/node writer captured
the workspace active when it was built and refused to run once the active one
moved. The registries did the same by other means: the `CanvasStore` LRU
self-detected a switch and cleared itself, and its key — along with the node
tombstone map's and the Task mutation mutex's — carried a workspace path
beside the Space id.

All of it answered a question a process can no longer ask. The workspace is
fixed for a process lifetime, so a Space id already denotes one Space, and a
handle can only have been built against the workspace being served.

The guards are gone, the keys are Space ids, and the one thing that was
genuinely load-bearing is now explicit: committing a workspace drops the
mount, the instance cache, and the node fences together, which is what keeps
a test moving through several temporary workspaces from reading a stale one.

The blob adapter keeps resolving each operation's directory once before its
first await — that was never about workspaces. It stops a Space directory
renamed mid-write from landing the temp file in one place and the destination
in another, so its test now says so.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ufq2A7GReTSpRdtApkpdNZ
---
 .../storage/backends/disk/blob-store.test.ts  | 11 ++-
 .../storage/backends/disk/blob-store.ts       | 24 ++----
 .../backends/disk/cache-boundaries.test.ts    | 69 +++++++----------
 .../disk/legacy/canvas-store-cache.ts         | 64 ++++------------
 .../backends/disk/legacy/canvas-store.ts      | 67 +++--------------
 .../backends/disk/legacy/node-tombstones.ts   | 75 ++++++++-----------
 .../storage/backends/disk/space-logs.ts       | 19 -----
 .../storage/backends/disk/space-nodes.ts      | 20 -----
 .../storage/backends/disk/space-record.ts     | 15 +---
 .../backends/disk/space-repository.test.ts    | 11 +--
 .../storage/backends/disk/space-repository.ts | 15 ----
 .../storage/backends/disk/space-tasks.ts      | 20 +----
 .../storage/backends/disk/space-write.ts      | 18 +----
 .../backends/disk/structured-store.test.ts    | 11 ---
 .../storage/backends/disk/structured-store.ts |  7 +-
 apps/server/src/modules/storage/storage.ts    | 11 ++-
 apps/server/src/modules/workspace.route.ts    |  6 +-
 docs/architecture/canvas-storage.md           |  4 +-
 docs/proposals/multi-backend-storage.md       | 11 ++-
 19 files changed, 127 insertions(+), 351 deletions(-)

diff --git a/apps/server/src/modules/storage/backends/disk/blob-store.test.ts b/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
index ba7317708..e538eef21 100644
--- a/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/blob-store.test.ts
@@ -90,7 +90,7 @@ describe('DiskBlobStore temp file hygiene', () => {
     ).toEqual(['hot.bin']);
   });
 
-  it('binds in-flight paths to their original workspace and rejects a held scope after activation', async () => {
+  it("resolves an operation's paths once, before its first await", async () => {
     const otherRoot = mkdtempSync(path.join(tmpdir(), 'huabu-blob-switched-'));
     const scope = new DiskBlobStore().space(canvasId).artifacts;
     let signalStarted = (): void => {};
@@ -119,12 +119,11 @@ describe('DiskBlobStore temp file hygiene', () => {
       expect(
         readFileSync(path.join(root, canvasId, '.artifacts', 'bound.bin')),
       ).toEqual(Buffer.from('bound bytes'));
+      // Every path in one operation derives from the directory it resolved
+      // before its first await, so a Space directory that moves underneath a
+      // streaming write cannot land the temp file in one place and the
+      // destination in another.
       expect(existsSync(path.join(otherRoot, canvasId))).toBe(false);
-
-      await expect(scope.read('bound.bin')).rejects.toThrow(
-        /inactive workspace/,
-      );
-      await expect(scope.deleteAll()).rejects.toThrow(/inactive workspace/);
     } finally {
       workspaceState.path = root;
       rmSync(otherRoot, { recursive: true, force: true });
diff --git a/apps/server/src/modules/storage/backends/disk/blob-store.ts b/apps/server/src/modules/storage/backends/disk/blob-store.ts
index 9404f22a0..0fe8f0214 100644
--- a/apps/server/src/modules/storage/backends/disk/blob-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/blob-store.ts
@@ -7,10 +7,6 @@
  * Maps each area of a Space to a directory under its Space folder, preserving
  * the layout the workspace format has always used: one file per blob, named by
  * the URL key, no manifest indirection.
- *
- * Each scope is bound to the workspace active when it is created. A fresh
- * scope follows a free-mode workspace switch; a retained scope rejects the
- * next operation instead of silently redirecting it into the new workspace.
  */
 
 import { randomUUID } from 'node:crypto';
@@ -33,7 +29,6 @@ import {
   spaceUploadDir,
 } from './layout.js';
 import { renameOverWithRetry } from '../../../../utils/fs.js';
-import { getWorkspacePath } from '../../../workspace.js';
 import {
   BlobNameError,
   createBlobLease,
@@ -112,25 +107,20 @@ function isMissing(err: unknown): boolean {
 class DiskBlobScope implements BlobScope {
   readonly #area: SpaceBlobArea;
   readonly #canvasId: string;
-  readonly #workspacePath: string;
 
   constructor(area: SpaceBlobArea, canvasId: string) {
     this.#area = area;
     this.#canvasId = canvasId;
-    this.#workspacePath = path.resolve(getWorkspacePath());
   }
 
+  /**
+   * Resolve once per operation, before its first await.
+   *
+   * Every later path in that operation derives from this absolute directory,
+   * so an externally renamed Space directory cannot combine a temp file under
+   * the old name with a destination under the new one.
+   */
   #placement(): ScopePlacement {
-    const active = path.resolve(getWorkspacePath());
-    if (active !== this.#workspacePath) {
-      throw new Error(
-        `DiskBlobScope(${this.#canvasId}) belongs to an inactive workspace. ` +
-          `Resolve a fresh scope after workspace activation.`,
-      );
-    }
-    // Resolve once per operation, before its first await. Every later path in
-    // that operation is derived from this absolute directory, so a workspace
-    // switch cannot combine a temp in A with a destination in B.
     return scopePlacement(this.#area, this.#canvasId);
   }
 
diff --git a/apps/server/src/modules/storage/backends/disk/cache-boundaries.test.ts b/apps/server/src/modules/storage/backends/disk/cache-boundaries.test.ts
index 41903fb0a..e0335e771 100644
--- a/apps/server/src/modules/storage/backends/disk/cache-boundaries.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/cache-boundaries.test.ts
@@ -120,7 +120,13 @@ describe('CanvasStore cache boundaries', () => {
     expect(afterEviction.isNodeWriteSuppressed('n1')).toBe(false);
   });
 
-  it('invalidates cache state on a direct workspace switch and rejects a held handle', () => {
+  /**
+   * A process serves one Workspace, so nothing here carries an answer to
+   * "which Workspace am I?" — committing one drops the cached instances and
+   * their warm filename indexes instead. That is the whole invariant: after a
+   * commit, every handle is new.
+   */
+  it('drops cached instances when a Workspace is committed', () => {
     const firstRoot = activateWorkspace('huabu-cache-workspace-a-');
     createSpace('shared-id', 'First');
     const held = getCanvasStore('shared-id');
@@ -133,20 +139,15 @@ describe('CanvasStore cache boundaries', () => {
     expect(active).not.toBe(held);
     expect(active.writeNode('node-b', note('node-b', 'From B')).ok).toBe(true);
     expect(active.nodeIdForFilename('From B.md')).toBe('node-b');
+    // A's warm index is not consulted for B's Space.
+    expect(active.nodeIdForFilename('From A.md')).toBeNull();
 
-    // The old instance has a warm filename index from workspace A. It must not
-    // be allowed to consult that index — or the new workspace's disk — while B
-    // is active.
-    expect(() => held.nodeIdForFilename('From B.md')).toThrow(
-      /inactive workspace.*Resolve a fresh Space handle/s,
-    );
-    expect(() => held.readNode('node-a')).toThrow(/inactive workspace/);
-
-    // Switching back also invalidates B's cache rather than reviving A's old
-    // instance and its potentially stale in-memory index.
+    // Committing back to A also drops B's instance rather than reviving one
+    // whose in-memory index describes the other Workspace.
     setWorkspacePath(firstRoot);
     const reopened = getCanvasStore('shared-id');
     expect(reopened).not.toBe(held);
+    expect(reopened).not.toBe(active);
     expect(reopened.nodeIdForFilename('From A.md')).toBe('node-a');
   });
 
@@ -166,11 +167,10 @@ describe('CanvasStore cache boundaries', () => {
     expect(getCanvasStore('canvas-b').read()?.canvasId).toBe('canvas-b');
   });
 
-  it('rejects a held event repository after a workspace switch', async () => {
+  it('reads the committed Workspace through a freshly resolved handle', async () => {
     activateWorkspace('huabu-log-workspace-a-');
     createSpace('shared-id', 'First');
-    const held = new DiskStructuredStore().space('shared-id');
-    await held.events.append([
+    await new DiskStructuredStore().space('shared-id').events.append([
       {
         payload: {
           action: 'node_selected',
@@ -193,47 +193,34 @@ describe('CanvasStore cache boundaries', () => {
       },
     ]);
 
-    // This read uses strict JSONL helpers directly. Without its own
-    // workspace-lifetime guard, the retained A facade would silently read
-    // B's same-id file instead of rejecting the stale handle.
-    await expect(held.events.read()).rejects.toThrow(/inactive workspace/);
+    // The same Space id in two Workspaces is two different logs, and the
+    // handle resolved after the commit reads the one that is active.
     expect((await active.events.read()).map((event) => event.ts)).toEqual([2]);
   });
 
-  it('guards a held record repository before probing the active workspace', async () => {
+  it("reports a corrupt record rather than the previous Workspace's copy", async () => {
     activateWorkspace('huabu-record-workspace-a-');
-    const first = createSpace('shared-id', 'First');
-    const held = new DiskStructuredStore().space('shared-id');
-    await expect(held.read()).resolves.toMatchObject({ title: 'First' });
+    createSpace('shared-id', 'First');
+    await expect(
+      new DiskStructuredStore().space('shared-id').read(),
+    ).resolves.toMatchObject({ title: 'First' });
 
     activateWorkspace('huabu-record-workspace-b-');
     createSpace('shared-id', 'Second');
-    const active = new DiskStructuredStore().space('shared-id');
-    await expect(active.read()).resolves.toMatchObject({
-      title: 'Second',
-    });
-
-    await expect(held.read()).rejects.toThrow(/inactive workspace/);
     await expect(
-      held.write({
-        expectedVersion: first.version,
-        nextRecord: {
-          ...first,
-          version: first.version + 1,
-          updatedAt: first.updatedAt + 1,
-        },
-        nodeMutations: [],
-      }),
-    ).rejects.toThrow(/inactive workspace/);
+      new DiskStructuredStore().space('shared-id').read(),
+    ).resolves.toMatchObject({ title: 'Second' });
 
-    // Even a corrupt same-id record in B must not leak through the strict
-    // probe as a SyntaxError before the retained A handle is rejected.
+    // A same-id record the user broke by hand surfaces as the integrity error
+    // it is. Nothing falls back to the copy another Workspace happens to hold.
     writeFileSync(
       path.join(canvasRoot('shared-id'), SPACE_JSON_FILENAME),
       '{broken',
       'utf8',
     );
-    await expect(held.read()).rejects.toThrow(/inactive workspace/);
+    await expect(
+      new DiskStructuredStore().space('shared-id').read(),
+    ).rejects.toThrow();
   });
 
   it('does not create a Space directory for a node write to a missing Space', async () => {
diff --git a/apps/server/src/modules/storage/backends/disk/legacy/canvas-store-cache.ts b/apps/server/src/modules/storage/backends/disk/legacy/canvas-store-cache.ts
index 5a4ee1d61..09aaa3147 100644
--- a/apps/server/src/modules/storage/backends/disk/legacy/canvas-store-cache.ts
+++ b/apps/server/src/modules/storage/backends/disk/legacy/canvas-store-cache.ts
@@ -18,27 +18,22 @@
  * promised: an entry can be evicted and rebuilt. Anything that must survive
  * eviction is either durable state in a repository or explicitly-scoped,
  * expiring coordination state such as node tombstones.
+ *
+ * Keyed by Space id alone. A process serves one Workspace for its lifetime, so
+ * there is no second Workspace an id could mean something else in; committing
+ * a Workspace calls {@link resetStorageCache}, which is what keeps that true
+ * for a test moving through several temporary ones.
  */
 
-import path from 'node:path';
-
 import { CanvasStore } from './canvas-store.js';
 import { sanitizeId } from '../../../../../utils/fs.js';
-import { getWorkspacePath } from '../../../../workspace.js';
-import { refreshCanvasDirIndex } from '../canvas-dirs.js';
 
 const MAX_CACHE = 16;
 const cache = new Map<string, CanvasStore>();
-let cacheWorkspacePath: string | null = null;
 
-function cacheKey(workspacePath: string, canvasId: string): string {
-  // NUL is not legal in either an OS path or a validated canvas id.
-  return `${workspacePath}\0${canvasId}`;
-}
-
-function rememberInstance(key: string, store: CanvasStore): CanvasStore {
-  cache.delete(key);
-  cache.set(key, store);
+function rememberInstance(canvasId: string, store: CanvasStore): CanvasStore {
+  cache.delete(canvasId);
+  cache.set(canvasId, store);
   if (cache.size > MAX_CACHE) {
     const firstKey = cache.keys().next().value;
     if (firstKey !== undefined) cache.delete(firstKey);
@@ -46,58 +41,27 @@ function rememberInstance(key: string, store: CanvasStore): CanvasStore {
   return store;
 }
 
-/**
- * `setWorkspacePath()` intentionally knows nothing about storage backends.
- * Detect its effect here so even a direct activation invalidates all cached
- * per-workspace indexes before the next handle is handed out.
- */
-function activateCacheWorkspace(workspacePath: string): void {
-  if (cacheWorkspacePath === workspacePath) return;
-  cache.clear();
-  cacheWorkspacePath = workspacePath;
-  // The directory index is process-global too. Refresh it before constructing
-  // a handle so an id from the previous workspace cannot resolve through a
-  // same-named directory in the newly-active one.
-  refreshCanvasDirIndex();
-}
-
 /**
  * Get (or create) the `CanvasStore` for the given canvas id. Instances
  * are cheap; the cache only avoids re-validating ids on hot paths.
  */
 export function getCanvasStore(canvasId: string): CanvasStore {
   const safeId = sanitizeId(canvasId, 'canvasId');
-  const workspacePath = path.resolve(getWorkspacePath());
-  activateCacheWorkspace(workspacePath);
-  const key = cacheKey(workspacePath, safeId);
-  const cached = cache.get(key);
+  const cached = cache.get(safeId);
   if (cached) {
-    cache.delete(key);
-    cache.set(key, cached);
+    cache.delete(safeId);
+    cache.set(safeId, cached);
     return cached;
   }
-  return rememberInstance(key, new CanvasStore(safeId, workspacePath));
+  return rememberInstance(safeId, new CanvasStore(safeId));
 }
 
 /** Drop a single cached instance. */
 export function forgetCanvasStore(canvasId: string): void {
-  const safeId = sanitizeId(canvasId, 'canvasId');
-  // Before first activation there cannot be an instance to forget, and
-  // `getWorkspacePath()` deliberately throws. Keep cleanup harmless during
-  // boot without weakening get/create operations.
-  if (cacheWorkspacePath === null) return;
-  const workspacePath = path.resolve(getWorkspacePath());
-  activateCacheWorkspace(workspacePath);
-  cache.delete(cacheKey(workspacePath, safeId));
+  cache.delete(sanitizeId(canvasId, 'canvasId'));
 }
 
-/** Clear the instance cache explicitly (workspace changes are auto-detected). */
+/** Drop every cached instance. */
 export function resetStorageCache(): void {
   cache.clear();
-  // Initial null is also the pre-Workspace state. `commitWorkspacePath()`
-  // refreshes the directory index when the first Workspace is activated, so
-  // there is nothing further to invalidate here.
-  if (cacheWorkspacePath === null) return;
-  cacheWorkspacePath = path.resolve(getWorkspacePath());
-  refreshCanvasDirIndex();
 }
diff --git a/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts b/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
index 09e61197e..521f5de3b 100644
--- a/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/legacy/canvas-store.ts
@@ -44,7 +44,6 @@ import {
   toFrontmatter,
 } from '../../../../../utils/markdown-frontmatter.js';
 import { toSafeFilename } from '../../../../../utils/naming.js';
-import { getWorkspacePath } from '../../../../workspace.js';
 import { assertSpaceMutationAllowed } from '../../../space-lifecycle-admission.js';
 import {
   patchCanvasDirTitle,
@@ -297,8 +296,6 @@ function readNodeSidecar(
 
 export class CanvasStore {
   readonly canvasId: string;
-  /** Workspace this handle was created for; handles never follow activation. */
-  readonly #workspacePath: string;
   private nodes: NameIndex<NodeFileEntry> | null = null;
   /** Whether the cached index was built without swallowing sidecar failures. */
   private nodeIndexIsConclusive = false;
@@ -323,24 +320,8 @@ export class CanvasStore {
   /** Live ids from the latest structural write, reconciled after log commit. */
   private deferredTombstoneReconciliationNodeIds: Set<string> | null = null;
 
-  constructor(canvasId: string, workspacePath = getWorkspacePath()) {
+  constructor(canvasId: string) {
     this.canvasId = sanitizeId(canvasId, 'canvasId');
-    this.#workspacePath = path.resolve(workspacePath);
-  }
-
-  /**
-   * A cached handle is scoped to the workspace that created it. Without this
-   * guard, a caller retaining a handle across `setWorkspacePath()` would send
-   * its cached node filename/index state into the newly-active workspace.
-   */
-  private assertActiveWorkspace(): void {
-    const active = path.resolve(getWorkspacePath());
-    if (active !== this.#workspacePath) {
-      throw new Error(
-        `CanvasStore(${this.canvasId}) belongs to an inactive workspace. ` +
-          `Resolve a fresh Space handle after workspace activation.`,
-      );
-    }
   }
 
   // ── Canvas structure ─────────────────────────────────────────────────────
@@ -355,7 +336,6 @@ export class CanvasStore {
    * would silently strip the user's typed characters from the title.
    */
   read(): CanvasFile | null {
-    this.assertActiveWorkspace();
     let file = readJson<CanvasFile>(canvasJsonPath(this.canvasId));
     if (!file) {
       refreshCanvasDirIndex();
@@ -368,7 +348,6 @@ export class CanvasStore {
 
   /** @internal Apply legacy Finder-title semantics without rereading disk. */
   reconcileValidatedRecord(file: CanvasFile): CanvasFile {
-    this.assertActiveWorkspace();
     if (file.canvasId !== this.canvasId) {
       throw new Error(
         `CanvasStore(${this.canvasId}) cannot reconcile record "${file.canvasId}"`,
@@ -409,7 +388,6 @@ export class CanvasStore {
   }
 
   private writeRecord(canvas: CanvasFile, reconcileTombstones: boolean): void {
-    this.assertActiveWorkspace();
     assertSpaceMutationAllowed(this.canvasId);
     if (canvas.canvasId !== this.canvasId) {
       throw new Error(
@@ -425,7 +403,7 @@ export class CanvasStore {
     const reconcileNodeIds = new Set<string>();
     if (reconcileTombstones) {
       const tombstonedLiveIds = [...liveNodeIds].filter((id) =>
-        isNodeTombstoned(this.#workspacePath, this.canvasId, id),
+        isNodeTombstoned(this.canvasId, id),
       );
       if (tombstonedLiveIds.length > 0) {
         const previous = readJson<CanvasFile>(canvasJsonPath(this.canvasId));
@@ -456,7 +434,7 @@ export class CanvasStore {
       return;
     }
     for (const id of reconcileNodeIds) {
-      clearNodeTombstone(this.#workspacePath, this.canvasId, id);
+      clearNodeTombstone(this.canvasId, id);
     }
   }
 
@@ -519,7 +497,6 @@ export class CanvasStore {
     },
     callback: () => T,
   ): T {
-    this.assertActiveWorkspace();
     if (this.nodeMutationTransactionDepth > 0) {
       throw new Error('CanvasStore node mutation transactions cannot nest');
     }
@@ -536,7 +513,6 @@ export class CanvasStore {
     // mutex, on the hottest write path there is.
 
     const tombstoneSnapshot = captureNodeTombstones(
-      this.#workspacePath,
       this.canvasId,
       options.affectedNodeIds,
     );
@@ -548,15 +524,11 @@ export class CanvasStore {
       // `callback` includes the structural write and delta-log append. Only
       // after both return successfully may a listed id clear its tombstone.
       for (const id of this.deferredTombstoneReconciliationNodeIds) {
-        clearNodeTombstone(this.#workspacePath, this.canvasId, id);
+        clearNodeTombstone(this.canvasId, id);
       }
       return result;
     } catch (error) {
-      restoreNodeTombstones(
-        this.#workspacePath,
-        this.canvasId,
-        tombstoneSnapshot,
-      );
+      restoreNodeTombstones(this.canvasId, tombstoneSnapshot);
       throw error;
     } finally {
       this.deferredTombstoneReconciliationNodeIds = null;
@@ -570,7 +542,6 @@ export class CanvasStore {
    * throwing so the route layer can map it to a 409.
    */
   renameSelf(newTitle: string | null): RenameSelfResult {
-    this.assertActiveWorkspace();
     assertSpaceMutationAllowed(this.canvasId);
     if (isWorldCanvasId(this.canvasId)) {
       return { ok: false, reason: 'forbidden' };
@@ -668,7 +639,6 @@ export class CanvasStore {
    * `readdir`; per-file contents are only re-read when a rescan fires.
    */
   revalidateNodeForRead(nodeId: string, strict = false): void {
-    this.assertActiveWorkspace();
     const idx = this.nodeIndex(strict);
     if (this.nodeDuplicateIds.has(nodeId) || this.nodeIndexCountStale(idx)) {
       this.invalidateNodeIndex();
@@ -683,7 +653,6 @@ export class CanvasStore {
    * populated the set, so no extra scan happens there.
    */
   isDuplicateNode(nodeId: string): boolean {
-    this.assertActiveWorkspace();
     this.nodeIndex();
     return this.nodeDuplicateIds.has(nodeId);
   }
@@ -696,7 +665,6 @@ export class CanvasStore {
    * O(directory size) — only called on the rare duplicate path.
    */
   duplicateNodeFiles(nodeId: string): string[] {
-    this.assertActiveWorkspace();
     return this.duplicateNodeFilenames(nodeId);
   }
 
@@ -781,12 +749,10 @@ export class CanvasStore {
    * not match `toSafeFilename(label)` (dedupe suffixes, external renames).
    */
   nodeIdForFilename(filename: string): string | null {
-    this.assertActiveWorkspace();
     return this.nodeIndex().findByName(filename)?.id ?? null;
   }
 
   readNode(nodeId: string): NodeContent | null {
-    this.assertActiveWorkspace();
     const filename = this.nodeFilenameOf(nodeId);
     const fullPath = nodeFilePath(this.canvasId, filename);
     let raw = readText(fullPath);
@@ -821,7 +787,6 @@ export class CanvasStore {
    * outcome instead of overwriting either file.
    */
   readNodeStrict(nodeId: string): NodeContent | null {
-    this.assertActiveWorkspace();
     this.revalidateNodeForRead(nodeId, true);
 
     const read = (filename: string): string | null =>
@@ -883,7 +848,6 @@ export class CanvasStore {
   async readAllNodes(options?: {
     strict?: boolean;
   }): Promise<Map<string, NodeContent>> {
-    this.assertActiveWorkspace();
     const generation = this.nodeIndexGeneration;
     const contents = new Map<string, NodeContent>();
     const idx = new NameIndex<NodeFileEntry>();
@@ -953,7 +917,6 @@ export class CanvasStore {
     onNode: (id: string, content: NodeContent) => void,
     signal?: { readonly aborted: boolean },
   ): Promise<Map<string, NodeContent>> {
-    this.assertActiveWorkspace();
     const generation = this.nodeIndexGeneration;
     const contents = new Map<string, NodeContent>();
     const idx = new NameIndex<NodeFileEntry>();
@@ -1005,7 +968,6 @@ export class CanvasStore {
     content: NodeContent,
     opts: { strictRename?: boolean } = {},
   ): RenameResult {
-    this.assertActiveWorkspace();
     if (content.nodeId !== nodeId) {
       throw new Error(
         `nodeId mismatch: argument="${nodeId}" payload="${content.nodeId}"`,
@@ -1193,7 +1155,6 @@ export class CanvasStore {
    * `.md` stays on disk as a permanent orphan.
    */
   deleteNode(nodeId: string): 'deleted' | 'absent' {
-    this.assertActiveWorkspace();
     // Keep idempotent delete semantics, but do not retain a tombstone for an
     // id whose Space itself does not exist.
     if (
@@ -1211,7 +1172,7 @@ export class CanvasStore {
     // in-flight write cannot resurrect the sidecar regardless of which delete
     // branch we take. The process registry outlives an evicted LRU instance
     // and expires the entry on its own timer.
-    markNodeDeleted(this.#workspacePath, this.canvasId, nodeId);
+    markNodeDeleted(this.canvasId, nodeId);
 
     const idx = this.nodeIndex();
     const filename = idx.get(nodeId)?.filename ?? this.nodeFilenameOf(nodeId);
@@ -1259,8 +1220,7 @@ export class CanvasStore {
    * recently-deleted id (the common case short-circuits on an empty map).
    */
   isNodeWriteSuppressed(nodeId: string): boolean {
-    this.assertActiveWorkspace();
-    if (!isNodeTombstoned(this.#workspacePath, this.canvasId, nodeId)) {
+    if (!isNodeTombstoned(this.canvasId, nodeId)) {
       return false;
     }
     // An authoritative INSERT (undo/revert or explicit id reuse) may recreate
@@ -1309,7 +1269,6 @@ export class CanvasStore {
    * un-coalesced sidecar.
    */
   readChanges(threadId: string): CanvasChangeRecord[] {
-    this.assertActiveWorkspace();
     return coalesceChanges(
       readJson<CanvasChangeRecord[]>(changesPath(this.canvasId, threadId)) ??
         [],
@@ -1332,7 +1291,6 @@ export class CanvasStore {
     threadId: string,
     records: CanvasChangeRecord[],
   ): CanvasChangeRecord[] {
-    this.assertActiveWorkspace();
     this.requireExistingSpaceForMutation('append change records');
     const existing = this.readChanges(threadId);
     const merged = coalesceChanges([...existing, ...records]);
@@ -1345,7 +1303,6 @@ export class CanvasStore {
    * record, or null when the id was not present.
    */
   removeChange(threadId: string, changeId: string): CanvasChangeRecord | null {
-    this.assertActiveWorkspace();
     this.requireExistingSpaceForMutation('remove a change record');
     const existing = this.readChanges(threadId);
     const idx = existing.findIndex((r) => r.id === changeId);
@@ -1367,7 +1324,6 @@ export class CanvasStore {
   appendEvents(
     events: ReadonlyArray<{ payload: RecentAction; ts?: number }>,
   ): void {
-    this.assertActiveWorkspace();
     this.requireExistingSpaceForMutation('append events');
     if (events.length === 0) return;
     const now = Date.now();
@@ -1383,7 +1339,6 @@ export class CanvasStore {
    * most recent `limit` records are returned (tail read).
    */
   readEvents(limit?: number): CanvasEvent[] {
-    this.assertActiveWorkspace();
     return readJsonLines<CanvasEvent>(eventsPath(this.canvasId), limit);
   }
 
@@ -1400,7 +1355,6 @@ export class CanvasStore {
   // crash mid-write drops the trailing partial line on read.
 
   appendDeltaLogEntry(entry: DeltaLogEntry): void {
-    this.assertActiveWorkspace();
     this.requireExistingSpaceForMutation('append a delta');
     appendJsonLine<DeltaLogEntry>(deltaLogPath(this.canvasId), entry);
   }
@@ -1412,7 +1366,6 @@ export class CanvasStore {
    * guarantees monotonic appends).
    */
   readDeltaLogSince(fromVersion: number): DeltaLogEntry[] {
-    this.assertActiveWorkspace();
     const all = readJsonLines<DeltaLogEntry>(deltaLogPath(this.canvasId));
     if (fromVersion <= 0) return all;
     return all.filter((row) => row.version > fromVersion);
@@ -1427,7 +1380,6 @@ export class CanvasStore {
    * out-of-order append without paying O(log size) on every write.
    */
   lastDeltaLogEntry(): DeltaLogEntry | null {
-    this.assertActiveWorkspace();
     const tail = readJsonLines<DeltaLogEntry>(deltaLogPath(this.canvasId), 1);
     return tail[tail.length - 1] ?? null;
   }
@@ -1442,7 +1394,6 @@ export class CanvasStore {
 
   /** Recursively delete the entire canvas directory. */
   destroy(): boolean {
-    this.assertActiveWorkspace();
     if (isWorldCanvasId(this.canvasId)) {
       throw new Error('World canvas cannot be deleted');
     }
@@ -1450,7 +1401,7 @@ export class CanvasStore {
     if (!existsSync(root)) {
       unregisterCanvasDir(this.canvasId);
       this.invalidateNodeIndex();
-      clearSpaceNodeTombstones(this.#workspacePath, this.canvasId);
+      clearSpaceNodeTombstones(this.canvasId);
       return false;
     }
     rmSync(root, {
@@ -1461,7 +1412,7 @@ export class CanvasStore {
     });
     unregisterCanvasDir(this.canvasId);
     this.invalidateNodeIndex();
-    clearSpaceNodeTombstones(this.#workspacePath, this.canvasId);
+    clearSpaceNodeTombstones(this.canvasId);
     return true;
   }
 }
diff --git a/apps/server/src/modules/storage/backends/disk/legacy/node-tombstones.ts b/apps/server/src/modules/storage/backends/disk/legacy/node-tombstones.ts
index 940d757a6..060a50416 100644
--- a/apps/server/src/modules/storage/backends/disk/legacy/node-tombstones.ts
+++ b/apps/server/src/modules/storage/backends/disk/legacy/node-tombstones.ts
@@ -7,11 +7,11 @@
  * Tombstones cannot live on a {@link CanvasStore} instance: those instances
  * sit in a bounded LRU and may be evicted while an already-started writer is
  * still running. This registry is therefore shared by every instance, scoped
- * by both workspace and Space id, and expires entries after a short TTL.
+ * by Space id, and expires entries after a short TTL.
  *
  * A single unref'd timer removes expired entries even when no later storage
- * call happens, so old workspaces and node ids do not become a permanent,
- * ever-growing process map.
+ * call happens, so old node ids do not become a permanent, ever-growing
+ * process map.
  */
 
 export const NODE_TOMBSTONE_TTL_MS = 5 * 60_000;
@@ -24,11 +24,6 @@ export interface NodeTombstoneSnapshot {
   readonly expiresAtByNodeId: ReadonlyMap<string, number>;
 }
 
-function scopeKey(workspacePath: string, canvasId: string): string {
-  // NUL cannot occur in a filesystem path or id, so the pair is unambiguous.
-  return `${workspacePath}\0${canvasId}`;
-}
-
 function sweepExpired(now = Date.now()): void {
   for (const [scope, entries] of tombstones) {
     for (const [nodeId, expiresAt] of entries) {
@@ -62,69 +57,63 @@ function scheduleCleanup(): void {
   (cleanupTimer as { unref?: () => void }).unref?.();
 }
 
-export function markNodeDeleted(
-  workspacePath: string,
-  canvasId: string,
-  nodeId: string,
-): void {
+export function markNodeDeleted(canvasId: string, nodeId: string): void {
   sweepExpired();
-  const scope = scopeKey(workspacePath, canvasId);
-  let entries = tombstones.get(scope);
+  let entries = tombstones.get(canvasId);
   if (!entries) {
     entries = new Map();
-    tombstones.set(scope, entries);
+    tombstones.set(canvasId, entries);
   }
   entries.set(nodeId, Date.now() + NODE_TOMBSTONE_TTL_MS);
   scheduleCleanup();
 }
 
-export function clearNodeTombstone(
-  workspacePath: string,
-  canvasId: string,
-  nodeId: string,
-): void {
-  const scope = scopeKey(workspacePath, canvasId);
-  const entries = tombstones.get(scope);
+export function clearNodeTombstone(canvasId: string, nodeId: string): void {
+  const entries = tombstones.get(canvasId);
   if (!entries) return;
   if (!entries.delete(nodeId)) return;
-  if (entries.size === 0) tombstones.delete(scope);
+  if (entries.size === 0) tombstones.delete(canvasId);
   scheduleCleanup();
 }
 
-export function clearSpaceNodeTombstones(
-  workspacePath: string,
-  canvasId: string,
-): void {
-  tombstones.delete(scopeKey(workspacePath, canvasId));
+export function clearSpaceNodeTombstones(canvasId: string): void {
+  tombstones.delete(canvasId);
   scheduleCleanup();
 }
 
-export function isNodeTombstoned(
-  workspacePath: string,
-  canvasId: string,
-  nodeId: string,
-): boolean {
-  const scope = scopeKey(workspacePath, canvasId);
-  const entries = tombstones.get(scope);
+/**
+ * Drop every tombstone, for a process that is changing Workspace.
+ *
+ * A tombstone fences a sidecar path, so it means nothing once a different
+ * Workspace is active. Production commits one Workspace and never calls this;
+ * a test moving through several temporary ones would otherwise carry a fence
+ * from one into the next.
+ */
+export function clearAllNodeTombstones(): void {
+  tombstones.clear();
+  scheduleCleanup();
+}
+
+export function isNodeTombstoned(canvasId: string, nodeId: string): boolean {
+  const entries = tombstones.get(canvasId);
   const expiresAt = entries?.get(nodeId);
   if (expiresAt === undefined) return false;
   if (Date.now() < expiresAt) return true;
 
   entries?.delete(nodeId);
-  if (entries?.size === 0) tombstones.delete(scope);
+  if (entries?.size === 0) tombstones.delete(canvasId);
   scheduleCleanup();
   return false;
 }
 
 /** Capture exact process-local tombstone state for transaction rollback. */
 export function captureNodeTombstones(
-  workspacePath: string,
   canvasId: string,
   nodeIds: ReadonlySet<string>,
 ): NodeTombstoneSnapshot {
   sweepExpired();
   const ids = [...nodeIds];
-  const entries = tombstones.get(scopeKey(workspacePath, canvasId));
+  const entries = tombstones.get(canvasId);
   const expiresAtByNodeId = new Map<string, number>();
   for (const nodeId of ids) {
     const expiresAt = entries?.get(nodeId);
@@ -135,23 +124,21 @@ export function captureNodeTombstones(
 
 /** Restore only the ids captured by {@link captureNodeTombstones}. */
 export function restoreNodeTombstones(
-  workspacePath: string,
   canvasId: string,
   snapshot: NodeTombstoneSnapshot,
 ): void {
-  const scope = scopeKey(workspacePath, canvasId);
-  let entries = tombstones.get(scope);
+  let entries = tombstones.get(canvasId);
   for (const nodeId of snapshot.nodeIds) entries?.delete(nodeId);
 
   if (snapshot.expiresAtByNodeId.size > 0) {
     if (!entries) {
       entries = new Map();
-      tombstones.set(scope, entries);
+      tombstones.set(canvasId, entries);
     }
     for (const [nodeId, expiresAt] of snapshot.expiresAtByNodeId) {
       entries.set(nodeId, expiresAt);
     }
   }
-  if (entries?.size === 0) tombstones.delete(scope);
+  if (entries?.size === 0) tombstones.delete(canvasId);
   scheduleCleanup();
 }
diff --git a/apps/server/src/modules/storage/backends/disk/space-logs.ts b/apps/server/src/modules/storage/backends/disk/space-logs.ts
index e1d9f4354..4239a3286 100644
--- a/apps/server/src/modules/storage/backends/disk/space-logs.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-logs.ts
@@ -18,8 +18,6 @@
  * by its own tests.
  */
 
-import path from 'node:path';
-
 import { canvasEventInputSchema, canvasEventRecordSchema } from '@huabu/shared';
 import {
   coalesceChanges,
@@ -33,7 +31,6 @@ import {
   readJsonLinesStrict,
   readJsonStrict,
 } from '../../../../utils/fs.js';
-import { getWorkspacePath } from '../../../workspace.js';
 import { assertSpaceMutationAllowed } from '../../space-lifecycle-admission.js';
 
 import type { CanvasStore } from './legacy/canvas-store.js';
@@ -99,20 +96,9 @@ export interface DiskSpaceLogs {
 
 class DiskSpaceLogCoordinator {
   readonly #store: CanvasStore;
-  readonly #workspacePath: string;
 
   constructor(store: CanvasStore) {
     this.#store = store;
-    this.#workspacePath = path.resolve(getWorkspacePath());
-  }
-
-  private assertActiveWorkspace(): void {
-    if (path.resolve(getWorkspacePath()) !== this.#workspacePath) {
-      throw new Error(
-        `Space logs(${this.#store.canvasId}) belong to an inactive workspace. ` +
-          'Resolve a fresh Space handle after workspace activation.',
-      );
-    }
   }
 
   private requireSpace(): void {
@@ -127,7 +113,6 @@ class DiskSpaceLogCoordinator {
   // ── Events ────────────────────────────────────────────────────────────────
 
   async appendEvents(events: readonly NewCanvasEvent[]): Promise<void> {
-    this.assertActiveWorkspace();
     if (events.length === 0) return;
     events.forEach(validateEventInput);
     this.requireSpace();
@@ -137,14 +122,12 @@ class DiskSpaceLogCoordinator {
   }
 
   async readEvents(limit?: number): Promise<CanvasEvent[]> {
-    this.assertActiveWorkspace();
     return readValidatedEvents(eventsPath(this.#store.canvasId), limit);
   }
 
   // ── Change-review records ─────────────────────────────────────────────────
 
   async readChanges(threadId: string): Promise<CanvasChangeRecord[]> {
-    this.assertActiveWorkspace();
     return coalesceChanges(
       readJsonArray<CanvasChangeRecord>(
         changesPath(this.#store.canvasId, threadId),
@@ -157,7 +140,6 @@ class DiskSpaceLogCoordinator {
     threadId: string,
     records: readonly CanvasChangeRecord[],
   ): Promise<CanvasChangeRecord[]> {
-    this.assertActiveWorkspace();
     this.requireSpace();
     const filePath = changesPath(this.#store.canvasId, threadId);
     const existing = coalesceChanges(
@@ -172,7 +154,6 @@ class DiskSpaceLogCoordinator {
     threadId: string,
     changeId: string,
   ): Promise<CanvasChangeRecord | null> {
-    this.assertActiveWorkspace();
     this.requireSpace();
     const filePath = changesPath(this.#store.canvasId, threadId);
     const existing = coalesceChanges(
diff --git a/apps/server/src/modules/storage/backends/disk/space-nodes.ts b/apps/server/src/modules/storage/backends/disk/space-nodes.ts
index 9fc2783f0..3ce9ab189 100644
--- a/apps/server/src/modules/storage/backends/disk/space-nodes.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-nodes.ts
@@ -4,9 +4,6 @@
 /** Disk implementation of the asynchronous node-record port. */
 
 import { createHash } from 'node:crypto';
-import path from 'node:path';
-
-import { getWorkspacePath } from '../../../workspace.js';
 
 import type { CanvasStore } from './legacy/canvas-store.js';
 import type { NodeContent } from '../../../canvas/persistence-types.js';
@@ -43,16 +40,13 @@ export class DiskSpaceNodes implements SpaceNodes {
   readonly canvasId: string;
 
   readonly #store: CanvasStore;
-  readonly #workspacePath: string;
 
   constructor(store: CanvasStore) {
     this.#store = store;
     this.canvasId = store.canvasId;
-    this.#workspacePath = path.resolve(getWorkspacePath());
   }
 
   async read(nodeId: string): Promise<NodeSnapshot | null> {
-    this.#assertActiveWorkspace();
     const record = this.#store.readNodeStrict(nodeId);
     return record === null ? null : snapshotOf(record);
   }
@@ -70,7 +64,6 @@ export class DiskSpaceNodes implements SpaceNodes {
   async readMany(
     nodeIds: readonly string[],
   ): Promise<Map<string, NodeSnapshot>> {
-    this.#assertActiveWorkspace();
     const out = new Map<string, NodeSnapshot>();
     for (const nodeId of new Set(nodeIds)) {
       const record = this.#store.readNodeStrict(nodeId);
@@ -80,7 +73,6 @@ export class DiskSpaceNodes implements SpaceNodes {
   }
 
   async list(): Promise<Map<string, NodeSnapshot>> {
-    this.#assertActiveWorkspace();
     return snapshotsOf(await this.#store.readAllNodes());
   }
 
@@ -88,7 +80,6 @@ export class DiskSpaceNodes implements SpaceNodes {
     onNode: (snapshot: NodeSnapshot) => void,
     options?: NodeStreamOptions,
   ): Promise<Map<string, NodeSnapshot>> {
-    this.#assertActiveWorkspace();
     const contents = await this.#store.streamAllNodes(
       (_id, content) => onNode(snapshotOf(content)),
       options?.signal,
@@ -97,7 +88,6 @@ export class DiskSpaceNodes implements SpaceNodes {
   }
 
   async put(input: NodePutInput): Promise<NodePutResult> {
-    this.#assertActiveWorkspace();
     if (input.record.nodeId !== input.nodeId) {
       throw new Error(
         `SpaceNodes(${this.canvasId}) nodeId mismatch: ` +
@@ -170,16 +160,6 @@ export class DiskSpaceNodes implements SpaceNodes {
   }
 
   async delete(nodeId: string): Promise<NodeDeleteResult> {
-    this.#assertActiveWorkspace();
     return this.#store.deleteNode(nodeId);
   }
-
-  #assertActiveWorkspace(): void {
-    if (path.resolve(getWorkspacePath()) !== this.#workspacePath) {
-      throw new Error(
-        `SpaceNodes(${this.canvasId}) belongs to an inactive workspace. ` +
-          'Resolve a fresh Space handle after workspace activation.',
-      );
-    }
-  }
 }
diff --git a/apps/server/src/modules/storage/backends/disk/space-record.ts b/apps/server/src/modules/storage/backends/disk/space-record.ts
index 3a1737129..66a10f1c7 100644
--- a/apps/server/src/modules/storage/backends/disk/space-record.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-record.ts
@@ -9,12 +9,9 @@
  * which owns the version check and the node/delta batch around it.
  */
 
-import path from 'node:path';
-
 import { refreshCanvasDirIndex } from './canvas-dirs.js';
 import { canvasJsonPath } from './layout.js';
 import { readValidCanvasFile } from './space-record-validation.js';
-import { getWorkspacePath } from '../../../workspace.js';
 
 import type { CanvasStore } from './legacy/canvas-store.js';
 import type { CanvasFile } from '../../../canvas/persistence-types.js';
@@ -23,21 +20,13 @@ import type { SpaceHandle } from '../../ports/structured.js';
 /**
  * Bind the record read for one Space handle.
  *
- * The workspace active at bind time is captured here, so a handle retained
- * across a workspace switch rejects rather than reading the newly active
- * workspace — the same guard the other Disk parts carry.
+ * Shared by the handle and its extension member, so the existence check that
+ * guards a substrate is the same read every other member answers to.
  */
 export function createDiskSpaceRecordReader(
   store: CanvasStore,
 ): SpaceHandle['read'] {
-  const workspacePath = path.resolve(getWorkspacePath());
   return async function readSpaceRecord(): Promise<CanvasFile | null> {
-    if (path.resolve(getWorkspacePath()) !== workspacePath) {
-      throw new Error(
-        `Space record(${store.canvasId}) belongs to an inactive workspace. ` +
-          'Resolve a fresh Space handle after workspace activation.',
-      );
-    }
     return readDiskSpaceRecord(store);
   };
 }
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
index 250a61022..4413b374d 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.test.ts
@@ -266,16 +266,13 @@ describe('DiskSpaceRepository membership', () => {
     await expect(spaces.worldId()).rejects.toBeInstanceOf(SyntaxError);
   });
 
-  it('rejects a retained handle after the active Workspace changes', async () => {
-    const firstRoot = makeWorkspace('huabu-space-membership-stale-a-');
+  it('reads the Workspace that is active when it is resolved', async () => {
+    const firstRoot = makeWorkspace('huabu-space-membership-a-');
     seedWorld(firstRoot, 'world-a');
-    const held = new DiskSpaceRepository();
-    await expect(held.worldId()).resolves.toBe('world-a');
+    await expect(new DiskSpaceRepository().worldId()).resolves.toBe('world-a');
 
-    const secondRoot = makeWorkspace('huabu-space-membership-stale-b-');
+    const secondRoot = makeWorkspace('huabu-space-membership-b-');
     seedWorld(secondRoot, 'world-b');
-    await expect(held.list()).rejects.toThrow(/inactive workspace/i);
-    await expect(held.worldId()).rejects.toThrow(/inactive workspace/i);
     await expect(new DiskSpaceRepository().worldId()).resolves.toBe('world-b');
   });
 });
diff --git a/apps/server/src/modules/storage/backends/disk/space-repository.ts b/apps/server/src/modules/storage/backends/disk/space-repository.ts
index 4fe1e245a..5b0588bb4 100644
--- a/apps/server/src/modules/storage/backends/disk/space-repository.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-repository.ts
@@ -73,7 +73,6 @@ export class DiskSpaceRepository implements SpaceRepository {
   }
 
   async list(): Promise<CanvasSummary[]> {
-    this.#assertActiveWorkspace();
     refreshCanvasDirIndex();
 
     return listCanvasDirEntries().map((entry) => {
@@ -88,7 +87,6 @@ export class DiskSpaceRepository implements SpaceRepository {
   }
 
   async worldId(): Promise<string> {
-    this.#assertActiveWorkspace();
     return this.#requireWorld();
   }
 
@@ -107,7 +105,6 @@ export class DiskSpaceRepository implements SpaceRepository {
    * World is a new member of the collection every later read resolves through.
    */
   async ensureWorld(): Promise<string> {
-    this.#assertActiveWorkspace();
     const canvasId = ensureWorldCanvasOnDisk(this.#workspacePath);
     // A freshly created World is a new member of the collection every later
     // read resolves through.
@@ -116,7 +113,6 @@ export class DiskSpaceRepository implements SpaceRepository {
   }
 
   async create(input: SpaceCreateInput): Promise<SpaceCreateResult> {
-    this.#assertActiveWorkspace();
     const canvasId = sanitizeId(input.canvasId, 'canvasId');
     assertSpaceMutationAllowed(canvasId);
     // Creation owns membership allocation. Refresh here rather than relying
@@ -154,7 +150,6 @@ export class DiskSpaceRepository implements SpaceRepository {
   }
 
   async beginDelete(input: SpaceDeleteInput): Promise<SpaceBeginDeleteResult> {
-    this.#assertActiveWorkspace();
     const canvasId = sanitizeId(input.canvasId, 'canvasId');
     // Revalidate the protected World identity before a destructive session,
     // as the old composition path did before touching blobs.
@@ -201,7 +196,6 @@ export class DiskSpaceRepository implements SpaceRepository {
   }
 
   async rename(input: SpaceRenameInput): Promise<SpaceRenameResult> {
-    this.#assertActiveWorkspace();
     const canvasId = sanitizeId(input.canvasId, 'canvasId');
     assertSpaceMutationAllowed(canvasId);
     if (this.#isWorld(canvasId)) {
@@ -271,15 +265,6 @@ export class DiskSpaceRepository implements SpaceRepository {
     return requireWorldCanvasId();
   }
 
-  #assertActiveWorkspace(): void {
-    if (path.resolve(getWorkspacePath()) !== this.#workspacePath) {
-      throw new Error(
-        'Space repository belongs to an inactive workspace. ' +
-          'Resolve a fresh Space repository after workspace activation.',
-      );
-    }
-  }
-
   #conflictingTitle(directoryName: string): string | null {
     const entry = listAllCanvasDirEntries().find(
       (candidate) =>
diff --git a/apps/server/src/modules/storage/backends/disk/space-tasks.ts b/apps/server/src/modules/storage/backends/disk/space-tasks.ts
index bcc8d8728..3ae779d1f 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tasks.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tasks.ts
@@ -1,8 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import path from 'node:path';
-
 import {
   taskRecordSchema,
   taskRunCompletionSchema,
@@ -17,7 +15,6 @@ import {
 import { tasksPath } from './layout.js';
 import { readDiskSpaceRecord } from './space-record.js';
 import { atomicWriteJson, readJsonStrict } from '../../../../utils/fs.js';
-import { getWorkspacePath } from '../../../workspace.js';
 import { assertSpaceMutationAllowed } from '../../space-lifecycle-admission.js';
 
 import type { CanvasStore } from './legacy/canvas-store.js';
@@ -28,6 +25,7 @@ import type {
   TaskRunUpdate,
 } from '../../ports/structured.js';
 
+/** In-flight Task mutations, one chain per Space. */
 const taskMutationChains = new Map<string, Promise<unknown>>();
 
 async function withTaskMutationMutex<T>(
@@ -103,11 +101,9 @@ export class DiskSpaceTasks implements SpaceTasks {
   readonly runs: SpaceTaskRuns;
 
   readonly #store: CanvasStore;
-  readonly #workspacePath: string;
 
   constructor(store: CanvasStore) {
     this.#store = store;
-    this.#workspacePath = path.resolve(getWorkspacePath());
     this.runs = Object.freeze({
       create: (run: TaskRunRecord) => this.#createRun(run),
       update: (runId: string, update: TaskRunUpdate) =>
@@ -120,14 +116,6 @@ export class DiskSpaceTasks implements SpaceTasks {
     });
   }
 
-  #assertActiveWorkspace(): void {
-    if (path.resolve(getWorkspacePath()) !== this.#workspacePath) {
-      throw new Error(
-        `Space Tasks(${this.#store.canvasId}) belong to an inactive workspace`,
-      );
-    }
-  }
-
   #requireSpace(): void {
     assertSpaceMutationAllowed(this.#store.canvasId);
     if (!readDiskSpaceRecord(this.#store)) {
@@ -138,7 +126,6 @@ export class DiskSpaceTasks implements SpaceTasks {
   }
 
   async read(): Promise<TaskStoreSnapshot> {
-    this.#assertActiveWorkspace();
     return readTaskStore(this.#store.canvasId);
   }
 
@@ -248,10 +235,7 @@ export class DiskSpaceTasks implements SpaceTasks {
   }
 
   async #mutate<T>(apply: (snapshot: TaskStoreSnapshot) => T): Promise<T> {
-    this.#assertActiveWorkspace();
-    const key = `${this.#workspacePath}\0${this.#store.canvasId}`;
-    return withTaskMutationMutex(key, () => {
-      this.#assertActiveWorkspace();
+    return withTaskMutationMutex(this.#store.canvasId, () => {
       this.#requireSpace();
       const current = readTaskStore(this.#store.canvasId);
       const next: TaskStoreSnapshot = {
diff --git a/apps/server/src/modules/storage/backends/disk/space-write.ts b/apps/server/src/modules/storage/backends/disk/space-write.ts
index 577eed916..913071946 100644
--- a/apps/server/src/modules/storage/backends/disk/space-write.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-write.ts
@@ -24,12 +24,9 @@
  * lock. A comment is not a mechanism.
  */
 
-import path from 'node:path';
-
 import { runCanvasPersistenceTransaction } from './canvas-persistence-transaction.js';
 import { canvasFileShapeError } from './space-record-validation.js';
 import { readDiskSpaceRecord } from './space-record.js';
-import { getWorkspacePath } from '../../../workspace.js';
 
 import type { CanvasStore } from './legacy/canvas-store.js';
 import type {
@@ -53,21 +50,9 @@ function nodeMutationError(mutation: SpaceNodeMutation, detail: string): Error {
  * Bind the ordered write to one Space.
  *
  * A closure rather than a class: this is the Space's write action, so the only
- * thing it needs to own is the store it writes through and the Workspace it
- * was resolved in.
+ * thing it needs to own is the store it writes through.
  */
 export function createDiskSpaceWrite(store: CanvasStore): SpaceHandle['write'] {
-  const boundWorkspacePath = path.resolve(getWorkspacePath());
-
-  function assertActiveWorkspace(): void {
-    if (path.resolve(getWorkspacePath()) !== boundWorkspacePath) {
-      throw new Error(
-        `SpaceWrite(${store.canvasId}) belongs to an inactive workspace. ` +
-          'Resolve a fresh Space handle after workspace activation.',
-      );
-    }
-  }
-
   function validateInput(input: SpaceWriteInput): void {
     if (!Number.isFinite(input.expectedVersion)) {
       throw new TypeError('expectedVersion must be a finite number');
@@ -146,7 +131,6 @@ export function createDiskSpaceWrite(store: CanvasStore): SpaceHandle['write'] {
   return async function write(
     input: SpaceWriteInput,
   ): Promise<SpaceWriteResult> {
-    assertActiveWorkspace();
     validateInput(input);
 
     const current = readDiskSpaceRecord(store);
diff --git a/apps/server/src/modules/storage/backends/disk/structured-store.test.ts b/apps/server/src/modules/storage/backends/disk/structured-store.test.ts
index 72278d483..a86d7e152 100644
--- a/apps/server/src/modules/storage/backends/disk/structured-store.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/structured-store.test.ts
@@ -288,17 +288,6 @@ describe('Disk Space Tasks', () => {
       /references missing Task/,
     );
   });
-
-  it('rejects a retained handle after the active Workspace changes', async () => {
-    const retained = store.space('canvas-empty').tasks;
-    const replacement = freshWorkspace('huabu-task-repo-next-');
-
-    await expect(retained.read()).rejects.toThrow(/inactive workspace/);
-
-    workspaceState.path = root;
-    resetStorageCache();
-    rmSync(replacement, { recursive: true, force: true });
-  });
 });
 
 /**
diff --git a/apps/server/src/modules/storage/backends/disk/structured-store.ts b/apps/server/src/modules/storage/backends/disk/structured-store.ts
index af4f133cc..93d262bb1 100644
--- a/apps/server/src/modules/storage/backends/disk/structured-store.ts
+++ b/apps/server/src/modules/storage/backends/disk/structured-store.ts
@@ -7,11 +7,8 @@
  * Builds a composite {@link SpaceHandle} on demand over the legacy per-Space
  * object that `getCanvasStore` already caches. It adds **no cache of its
  * own**: a second cache would have to be invalidated in lockstep with the
- * first, and `resetStorageCache()` — called on workspace switch — clears only
- * the legacy map, so a separately cached composite would survive a workspace
- * change still wrapping the previous workspace's object. The handle is a few
- * field assignments over an object the existing cache returns, so there is
- * nothing to gain by caching it twice.
+ * first, and the handle is a few field assignments over an object the existing
+ * cache returns, so there is nothing to gain by caching it twice.
  *
  * Because the record, log-backed, and node adapters all wrap the *same* legacy
  * object the compatibility facade resolves, a write through either view is
diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts
index 30bb27295..616d9e558 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -26,6 +26,8 @@
 
 import { isWorkspaceConfigured } from '../workspace.js';
 import { DiskBlobStore } from './backends/disk/blob-store.js';
+import { resetStorageCache } from './backends/disk/legacy/canvas-store-cache.js';
+import { clearAllNodeTombstones } from './backends/disk/legacy/node-tombstones.js';
 import { stageDiskSpaceImport } from './backends/disk/space-import.js';
 import { diskSpaceTree } from './backends/disk/space-tree.js';
 import { DiskStructuredStore } from './backends/disk/structured-store.js';
@@ -302,16 +304,23 @@ export async function mountStorage(
 }
 
 /**
- * Drop the mount without closing it.
+ * Drop the process's storage state without closing it.
  *
  * The synchronous counterpart to {@link closeStorage}, for a caller that
  * cannot await — {@link commitWorkspacePath} publishing a Workspace, and the
  * tests that move between temporary ones. A backend whose `close()` matters is
  * one {@link ensure} refuses to rebuild here anyway, so nothing that holds a
  * connection is reachable through this path.
+ *
+ * The mount, the Disk adapter's instance cache, and its node fences go
+ * together: all three describe whichever Workspace was active, and none of
+ * them carries an answer to *which* one, because a process only ever has the
+ * one.
  */
 export function resetStorage(): void {
   current = null;
+  resetStorageCache();
+  clearAllNodeTombstones();
 }
 
 /** Close the active mount. Called on graceful Server shutdown. */
diff --git a/apps/server/src/modules/workspace.route.ts b/apps/server/src/modules/workspace.route.ts
index 75035c243..a74bdd513 100644
--- a/apps/server/src/modules/workspace.route.ts
+++ b/apps/server/src/modules/workspace.route.ts
@@ -9,7 +9,7 @@ import path from 'node:path';
 import { validatePathSchema, workspacePathSchema } from '@huabu/shared';
 
 import { resetPreprocessDispatcher } from './preprocessing/index.js';
-import { getStructuredStore, resetStorageCache } from './storage/index.js';
+import { getStructuredStore } from './storage/index.js';
 import {
   activateWorkspacePath,
   WorkspaceActivationInProgressError,
@@ -265,8 +265,8 @@ const workspaceRoutes: FastifyPluginAsync = async (app) => {
     }
     try {
       await activateWorkspacePath(parsed.data.path);
-      // Reset singletons that cache filesystem handles for the old workspace.
-      resetStorageCache();
+      // The dispatcher holds workspace-scoped state of its own; storage drops
+      // its caches as part of committing the path.
       resetPreprocessDispatcher();
       return await buildWorkspaceState();
     } catch (e) {
diff --git a/docs/architecture/canvas-storage.md b/docs/architecture/canvas-storage.md
index 3e076305d..98ff41bce 100644
--- a/docs/architecture/canvas-storage.md
+++ b/docs/architecture/canvas-storage.md
@@ -139,7 +139,7 @@ Key points:
 | `ports/namespace.ts`           | The `<owner>.<name>` grammar for an extension namespace — the only thing storage validates about an extension.                                                                                                                                        |
 | `ports/contracts/`             | Reusable Space-collection, node, Space-write, log, blob, extension, and store suites; guarantees are the minimum every adapter implements.                                                                                                            |
 | `backends/disk/`               | Disk implementations plus before-image restoration for rejected in-process ordered batches; no journal or startup recovery. `space-tree.ts` and `space-import.ts` hold the Disk-only Space directory and bundle-publication capabilities — not ports. |
-| `backends/disk/legacy/`        | The legacy `CanvasStore` and its synchronous adapter primitives, bounded Workspace-qualified cache, and process-local node tombstones.                                                                                                                |
+| `backends/disk/legacy/`        | The legacy `CanvasStore` and its synchronous adapter primitives, its bounded instance cache, and process-local node tombstones.                                                                                                                       |
 | `compatibility/canvas.ts`      | Residual Disk reads plus direct-module create/delete test fixtures; lifecycle writers are not exported from the public storage barrel.                                                                                                                |
 | `space-lifecycle-admission.ts` | Backend-neutral, writer-preferring single-process coordinator shared by structured mutations and blob puts during a delete session.                                                                                                                   |
 | `profile.ts` and `storage.ts`  | Backend selection, cross-axis validation, the process-wide mount, the `space(canvasId)` facade, blob areas, and the blob-first deletion saga.                                                                                                         |
@@ -154,7 +154,7 @@ Canvas persistence DTOs and the write coordinator live under `modules/canvas/`;
 
 Space deletion is serialized against composed blob puts by a writer-preferring admission coordinator keyed on the Space. `beginDelete()` acquires the exclusive session before blob I/O; `finish()` removes structured state, while `abort()` releases the fence without doing so. Blobs are swept before structure so a failed sweep can be retried while the Space record still names them. Puts already admitted may finish; a put queued behind a successful deletion rechecks existence and fails without recreating blobs, while a failed blob sweep leaves the record available for retry. Mutations through existing Space handles and repositories reject while deletion is active or queued; reads remain available for cleanup. Residual direct-filesystem features — bundle import/export, reveal, the built-in file tools, external-note claim, and Windows handle coordination — are outside this repository fence; they are declared Disk-only in the capability matrix rather than treated as blockers, and off Disk they are unavailable rather than emulated.
 
-Retained Disk Space repository and handle instances, blob scopes, and legacy `CanvasStore` instances reject use after the active Workspace changes — a state production no longer reaches, and the guard that keeps a test moving between temporary Workspaces from reading a stale one. Each `spaces()` call returns a fresh Workspace-bound handle and each read rescans current Disk state. The Workspace-qualified LRU is cleared and rebuilt on the next lookup. The delete-session contract covers overlapping operations through one configured backend instance. Disk realizes it with the shared process-local coordinator; it is not a multi-process transaction or distributed lock, and a SQL adapter must supply an equivalent backend-instance fence using its own mechanisms.
+No Disk handle, repository, blob scope, instance cache, or node fence records _which_ Workspace it belongs to, because a process only ever serves one. Committing a Workspace drops all of them together (`resetStorage()`), so the next handle is new — which is what keeps a test moving between temporary Workspaces from reading a stale one. Each `spaces()` call returns a fresh handle and each read rescans current Disk state. The delete-session contract covers overlapping operations through one configured backend instance. Disk realizes it with the shared process-local coordinator; it is not a multi-process transaction or distributed lock, and a SQL adapter must supply an equivalent backend-instance fence using its own mechanisms.
 
 The `chat_v2/` two-tier log and `threads.json` remain owned by Agenetes L2 (`FileEventLogStore`, `FileTurnStore`, and `FileThreadStore`), wired in [agenetes/drivers.ts](../../apps/server/src/modules/agent/agenetes/drivers.ts); see [agent-architecture.md](./agent-architecture.md) §5. Workspace activation is coordinated by `apps/server/src/modules/workspace-activation.ts`; the isolated child entry is `workspace-prepare.worker.ts`, and the ordered migration sequence is centralized in `workspace-prepare.ts` with migration implementations under `modules/workspace/migrations/`.
 
diff --git a/docs/proposals/multi-backend-storage.md b/docs/proposals/multi-backend-storage.md
index ed73e76bf..f1f99a710 100644
--- a/docs/proposals/multi-backend-storage.md
+++ b/docs/proposals/multi-backend-storage.md
@@ -1093,9 +1093,9 @@ The post-implementation adversarial pass hardened the existing Disk behavior
 without widening the portable contract. Disk reads now distinguish ENOENT
 from corrupt or unreadable durable state; JSONL readers tolerate only a final
 unterminated crash fragment and validate event/delta row shapes; cache entries
-and retained handles are Workspace-qualified; and Space deletion has a
-process-local admission gate plus an active-Workspace lease spanning blob and
-structured cleanup. The executor's multi-file rollback remains a
+and retained handles were Workspace-qualified (§12.6.5 later removed both,
+once a process could only ever serve one Workspace); and Space deletion has a
+process-local admission gate spanning blob and structured cleanup. The executor's multi-file rollback remains a
 Disk/application implementation detail, not a new generic transaction API.
 External-note watcher recovery is owned by a separate watcher-recovery PR and
 is not part of Phase 2. Coordination across multiple server processes and a
@@ -2286,7 +2286,10 @@ than by reading:
   live process between two Workspaces. Issue #126 established that this is not
   a product requirement; §12.6.5 below is the lifecycle that replaced it, and
   the leak, the leases, the stale-mount check, and `Storage.workspacePath` all
-  went with the staging.
+  went with the staging. So did every "which Workspace am I?" check underneath:
+  the Disk handles, repositories, blob scopes, instance cache, and node fences
+  no longer record one, because committing a Workspace drops all of them
+  together and a process never has a second.
 - **A blob scope for the Space root cannot be a directory scope.** Its area is
   shared with `space.json` and every node directory, so `list()` would claim
   storage's own records and `deleteAll()` would remove the Space. The `guide`

From 4a67c36baf3e4a11b9c99f0ee78f294eeca296e5 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Fri, 21 Aug 2026 09:45:26 +0800
Subject: [PATCH 20/20] fix(workspace): do not retry a startup workspace the
 server already failed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The server reports why it could not open the workspace it was started on, and
the client showed that reason — then fell straight through to activating the
same path again, because an unconfigured free-mode server has always meant
"try the remembered folder". On an unavailable drive that is a second 70-second
wait after the first one already failed, and it ends by dropping the saved path
so a drive that comes back is no longer remembered.

A reported startup failure is the answer to that question, so stop asking it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ufq2A7GReTSpRdtApkpdNZ
---
 apps/desktop/src/main.ts             | 18 +++++++++---------
 apps/web/src/store/workspaceStore.ts | 10 ++++++++++
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index afcd7d480..2e6998a88 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -468,6 +468,15 @@ function buildServerEnv(port: number): NodeJS.ProcessEnv {
     );
   }
 
+  // External-agent (ACP) integration: the server embeds an `agentlet`
+  // daemon supervisor (`DaemonSupervisor`) which fork()s the daemon
+  // entry point itself. In packaged builds the entry resolves to
+  // `<resources>/server/agentlet/index.js` (copied by tsup + bundled
+  // by electron-builder, see ./electron-builder.yml extraResources);
+  // in dev it falls back to `external/agentlet/packages/local/dist/index.js`.
+  // No env var injection is needed here \u2014 the resolver in
+  // `daemon-supervisor.ts` covers both layouts.
+
   // The workspace the user last chose, handed to the server at fork.
   //
   // A server process serves one workspace for its lifetime, so this is where
@@ -479,15 +488,6 @@ function buildServerEnv(port: number): NodeJS.ProcessEnv {
   // the picker remains available and a folder that has gone missing lands the
   // user back on it instead of killing the app. Absent on first launch, which
   // is what shows the picker then.
-  //
-  // External-agent (ACP) integration: the server embeds an `agentlet`
-  // daemon supervisor (`DaemonSupervisor`) which fork()s the daemon
-  // entry point itself. In packaged builds the entry resolves to
-  // `<resources>/server/agentlet/index.js` (copied by tsup + bundled
-  // by electron-builder, see ./electron-builder.yml extraResources);
-  // in dev it falls back to `external/agentlet/packages/local/dist/index.js`.
-  // No env var injection is needed here \u2014 the resolver in
-  // `daemon-supervisor.ts` covers both layouts.
   const savedWorkspace = readWorkspaceStore().path;
 
   return {
diff --git a/apps/web/src/store/workspaceStore.ts b/apps/web/src/store/workspaceStore.ts
index f79f23959..e868f1292 100644
--- a/apps/web/src/store/workspaceStore.ts
+++ b/apps/web/src/store/workspaceStore.ts
@@ -378,6 +378,16 @@ export const useWorkspaceStore = create<WorkspaceState>()((set, get) => ({
       return true;
     }
 
+    // The server was handed a remembered folder and could not open it. It has
+    // already paid for that attempt — up to 70 seconds when the drive is
+    // unavailable — so do not spend it again on the same path. Show the
+    // picker with the reason set above, and leave the saved path alone so a
+    // drive that comes back is still remembered.
+    if (info.startupError) {
+      set({ isSyncing: false });
+      return false;
+    }
+
     // Try to auto-activate using the remembered absolute path.
     const savedPath = persisted.path;
     if (savedPath) {