From 90ad1968ead12a569a05785572fa167f3bf353bd Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 17:14:15 +0800
Subject: [PATCH 1/9] 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.test.ts  |  3 ++
 .../storage/backends/disk/space-tree.ts       | 44 ++++++++++++++++---
 .../modules/storage/module-boundaries.test.ts |  3 ++
 12 files changed, 148 insertions(+), 87 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 b9c9a3520..b31a5724b 100644
--- a/apps/server/src/modules/remote_fs/rfs.route.test.ts
+++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts
@@ -1324,7 +1324,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({
@@ -1422,7 +1422,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')
@@ -1485,7 +1487,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,
@@ -1532,7 +1536,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 {
@@ -1564,7 +1568,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) => ({
@@ -1613,7 +1619,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 {
@@ -1633,7 +1639,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,
@@ -1680,7 +1686,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'),
     );
@@ -1710,7 +1718,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,
@@ -1749,7 +1759,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.test.ts b/apps/server/src/modules/storage/backends/disk/space-tree.test.ts
index 9172483e9..fb51e74f5 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tree.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.test.ts
@@ -52,6 +52,9 @@ describe('diskSpaceTree', () => {
     // *other* Workspace's files under the id it asked about — the file tools'
     // sandbox root and bundle export both resolve real paths from it.
     expect(() => retained.directory()).toThrow(/inactive workspace/);
+    expect(() => retained.nodeIdForPath('nodes/Note.md')).toThrow(
+      /inactive workspace/,
+    );
     expect(diskSpaceTree('space-a').directory()).toBe(
       path.join(second, 'space-a'),
     );
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 d42ed44b4..f83fcb68b 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tree.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.ts
@@ -22,8 +22,12 @@
 import path from 'node:path';
 
 import { canvasRoot } from './layout.js';
+import { getCanvasStore } from './legacy/canvas-store-cache.js';
 import { getWorkspacePath } from '../../../workspace.js';
 
+/** A node sidecar, as RFS and the file tools address one. */
+const NODE_SIDECAR_RE = /^nodes\/([^/]+\.md)$/;
+
 export interface DiskSpaceTree {
   readonly canvasId: string;
   /**
@@ -45,22 +49,50 @@ export interface DiskSpaceTree {
    * handle instead.
    */
   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 {
   // Bound at resolution, exactly as `DiskSpaceNodes` binds its own: one Space
   // handle answers about one Workspace, on every member.
   const workspacePath = path.resolve(getWorkspacePath());
+  const assertActiveWorkspace = (): void => {
+    if (path.resolve(getWorkspacePath()) !== workspacePath) {
+      throw new Error(
+        `DiskSpaceTree(${canvasId}) belongs to an inactive workspace. ` +
+          'Resolve a fresh Space handle after workspace activation.',
+      );
+    }
+  };
   return {
     canvasId,
     directory: () => {
-      if (path.resolve(getWorkspacePath()) !== workspacePath) {
-        throw new Error(
-          `DiskSpaceTree(${canvasId}) belongs to an inactive workspace. ` +
-            'Resolve a fresh Space handle after workspace activation.',
-        );
-      }
+      assertActiveWorkspace();
       return canvasRoot(canvasId);
     },
+    nodeIdForPath: (relativePath: string) => {
+      assertActiveWorkspace();
+      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 d1f91ba03..81c4dfc12 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 dd077a812994fd985c12eeac8c7e8be9b2f3a2bc Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 17:24:40 +0800
Subject: [PATCH 2/9] 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       |  35 ++---
 .../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, 310 insertions(+), 275 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 575d533a0..c536b79c4 100644
--- a/apps/server/src/modules/canvas/world-portals.ts
+++ b/apps/server/src/modules/canvas/world-portals.ts
@@ -10,11 +10,7 @@ import {
 import { getNodeDefaultSize } 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 PREVIEW_SIZE = getNodeDefaultSize('spacePreview');
 const PORTAL_WIDTH = PREVIEW_SIZE.width ?? 480;
@@ -111,9 +107,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');
   }
@@ -142,10 +142,13 @@ function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
     targetMap.set(targetCanvasId, node);
   }
 
-  const spaces = listCanvasDirEntries().sort((a, b) =>
-    a.id.localeCompare(b.id),
+  // `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.
+  const members = (await spaces.list()).sort((a, b) =>
+    a.canvasId.localeCompare(b.canvasId),
   );
-  const liveCanvasIds = new Set(spaces.map((space) => space.id));
+  const liveCanvasIds = new Set(members.map((member) => member.canvasId));
   const byId = new Map(nodes.map((node) => [node.id, node]));
   const occupied: Rect[] = nodes.map((node) => {
     const position = absolutePosition(node, byId);
@@ -167,9 +170,9 @@ function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
     )
     .map((node) => node.id as CanvasNodeId);
 
-  const inputs: CanvasNodeCreateInput[] = spaces.flatMap((space) => {
-    if (previewByTarget.has(space.id)) return [];
-    const legacy = legacyPortalByTarget.get(space.id);
+  const inputs: CanvasNodeCreateInput[] = members.flatMap((member) => {
+    if (previewByTarget.has(member.canvasId)) return [];
+    const legacy = legacyPortalByTarget.get(member.canvasId);
     const position = legacy?.position ?? findOpenPortalSlot(occupied);
     const size = {
       width: dimension(legacy?.style?.width, PORTAL_WIDTH),
@@ -186,7 +189,7 @@ function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
         position,
         size,
         data: {
-          targetCanvasId: space.id,
+          targetCanvasId: member.canvasId,
         },
         selectOnCreate: false,
       },
@@ -198,7 +201,7 @@ function planWorldPortalReconciliation(): WorldPortalReconciliationPlan {
 
 async function reconcileWorldPortalsOnce(): Promise<void> {
   const { worldCanvasId, deleteNodeIds, inputs } =
-    planWorldPortalReconciliation();
+    await planWorldPortalReconciliation();
   if (inputs.length === 0 && deleteNodeIds.length === 0) return;
 
   const commands: 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 81c4dfc12..871c07323 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -426,12 +426,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',
@@ -442,10 +437,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': [
@@ -453,7 +445,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 8bc79ccfb11e9ad0c2b7d0a3148914d83a9669f4 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 17:35:33 +0800
Subject: [PATCH 3/9] 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 871c07323..5c23f8af3 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -431,7 +431,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 de73a9431e1c0c86c5bb28d87ea3473d2d3b5f0a Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Wed, 19 Aug 2026 17:40:57 +0800
Subject: [PATCH 4/9] 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 de99b02de..af3b33211 100644
--- a/apps/server/src/modules/canvas/canvas.route.ts
+++ b/apps/server/src/modules/canvas/canvas.route.ts
@@ -61,16 +61,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,
@@ -361,10 +361,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;
@@ -379,17 +379,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;
@@ -411,9 +400,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'];
@@ -512,13 +501,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 : '';
@@ -531,16 +524,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) ?? [],
     );
   });
 }
@@ -886,20 +879,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
@@ -909,9 +894,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;
     }
@@ -938,13 +926,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>;
 
@@ -1014,9 +1003,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,
@@ -1102,8 +1092,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' });
@@ -1112,7 +1102,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,
@@ -1588,8 +1578,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);
@@ -1622,8 +1611,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' });
     }
@@ -1862,9 +1850,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' });
       }
 
@@ -1902,7 +1889,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 f83fcb68b..c95231e9f 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tree.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.ts
@@ -68,6 +68,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 {
@@ -94,5 +106,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 5c23f8af3..bf7a17705 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',
@@ -401,11 +400,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)
@@ -423,11 +418,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 1be0366589ad7bf850cdd1fafd4698cc19200059 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Mon, 24 Aug 2026 19:11:44 +0800
Subject: [PATCH 5/9] 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

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. Its refusal
off Disk is phrased inline until the capability matrix owns that wording
(§12.8).

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 neutrality guard is now writable as specified: import-level, repo-wide,
migrations and tests exempt.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EKZXxEWwZvAZo8YMaLv4m
---
 .../server/src/modules/canvas/canvas.route.ts |  95 +++++---------
 .../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.test.ts  |   4 +
 .../storage/backends/disk/space-tree.ts       |  17 ++-
 apps/server/src/modules/storage/index.ts      |   2 +
 .../modules/storage/module-boundaries.test.ts |  89 ++++++++++++-
 apps/server/src/modules/storage/storage.ts    |  15 +++
 9 files changed, 298 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 af3b33211..94d542c9c 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';
 
@@ -47,20 +47,15 @@ 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,
   getStructuredStore,
   type CanvasFile,
   type NodeContent,
@@ -68,8 +63,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 {
@@ -1581,8 +1574,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
@@ -1681,13 +1676,20 @@ 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) {
+        // Phrased here only until the capability matrix owns the wording
+        // (§12.8), so a Disk-only refusal reads the same everywhere.
+        return reply.code(400).send({
+          message:
+            'Space bundle import is not available on this storage backend.',
+        });
+      }
+      const stagingDir = staged.stagingDirectory;
       let stagingCleanedUp = false;
       try {
         await new Promise<void>((resolve, reject) => {
@@ -1753,64 +1755,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.test.ts b/apps/server/src/modules/storage/backends/disk/space-tree.test.ts
index fb51e74f5..7aaa6b681 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tree.test.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.test.ts
@@ -55,6 +55,10 @@ describe('diskSpaceTree', () => {
     expect(() => retained.nodeIdForPath('nodes/Note.md')).toThrow(
       /inactive workspace/,
     );
+    expect(() => retained.nodesDirectory()).toThrow(/inactive workspace/);
+    expect(() => retained.duplicateSidecars('node-a')).toThrow(
+      /inactive workspace/,
+    );
     expect(diskSpaceTree('space-a').directory()).toBe(
       path.join(second, 'space-a'),
     );
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 c95231e9f..d50a76601 100644
--- a/apps/server/src/modules/storage/backends/disk/space-tree.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-tree.ts
@@ -21,7 +21,7 @@
 
 import path from 'node:path';
 
-import { canvasRoot } from './layout.js';
+import { canvasRoot, nodesDir } from './layout.js';
 import { getCanvasStore } from './legacy/canvas-store-cache.js';
 import { getWorkspacePath } from '../../../workspace.js';
 
@@ -68,6 +68,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.
@@ -100,6 +110,10 @@ export function diskSpaceTree(canvasId: string): DiskSpaceTree {
       assertActiveWorkspace();
       return canvasRoot(canvasId);
     },
+    nodesDirectory: () => {
+      assertActiveWorkspace();
+      return nodesDir(canvasId);
+    },
     nodeIdForPath: (relativePath: string) => {
       assertActiveWorkspace();
       const filename = NODE_SIDECAR_RE.exec(relativePath)?.[1];
@@ -107,6 +121,7 @@ export function diskSpaceTree(canvasId: string): DiskSpaceTree {
       return getCanvasStore(canvasId).nodeIdForFilename(filename);
     },
     duplicateSidecars: (nodeId: string) => {
+      assertActiveWorkspace();
       const store = getCanvasStore(canvasId);
       return store.isDuplicateNode(nodeId)
         ? store.duplicateNodeFiles(nodeId)
diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts
index 991cc2a7e..a43b0cb2f 100644
--- a/apps/server/src/modules/storage/index.ts
+++ b/apps/server/src/modules/storage/index.ts
@@ -84,12 +84,14 @@ export {
   initStorage,
   setStorageForTesting,
   space,
+  stageSpaceImport,
   storageHealth,
   workspaceAtDirectory,
   workspaceDirectory,
 } 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 {
   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 bf7a17705..96b6c8f51 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -346,6 +346,91 @@ describe('Disk Space tree capability', () => {
   });
 });
 
+/**
+ * The neutrality half of the exit criterion, at the import level (proposal
+ * §12.7, §12.8).
+ *
+ * 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',
+    '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(
@@ -432,8 +517,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 4d5bab65e..7363c44e7 100644
--- a/apps/server/src/modules/storage/storage.ts
+++ b/apps/server/src/modules/storage/storage.ts
@@ -31,6 +31,7 @@ import {
   getWorkspacePath,
 } 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 {
@@ -46,6 +47,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,
@@ -515,6 +517,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 915b52ff0532f8948ee6dd3a913bd3670ab8dba6 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Mon, 24 Aug 2026 19:17:46 +0800
Subject: [PATCH 6/9] refactor(canvas): read the Space preview projection
 through the ports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The preview scene was the one production reader the migration missed, because
it reaches the legacy Disk store by name through the barrel rather than by
path — which the import guard resolved to `storage/index` and let through. It
now reads topology through `space(canvasId).read()` and node records through
`nodes.list()`, and the guard checks the symbol as well as the path, so the
barrel stops being a way around it.

`resetStorageCache` stays off that symbol list deliberately. It is on the
barrel too and the Workspace routes still call it, but it reads nothing: it is
activation dropping an adapter's caches, which is a composition concern with
its own home to find, not a module learning how a Space is stored.

One behaviour moves, stated rather than absorbed. The route used to read node
sidecars strictly and answer 422 when one failed to parse; the port defines a
single lenient read for the collection — a record it cannot produce is
omitted, a record broken by hand recovers — and the projection already fell
back to topology data for an absent record. A damaged sidecar now renders the
way it does when its own Space is opened, instead of failing the whole
preview. The 422 stays for a malformed Space *record*, which is the damage
that makes the projection meaningless, and now covers a record the port
refuses to produce as well as topology that is not the expected shape.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EKZXxEWwZvAZo8YMaLv4m
---
 .../src/modules/canvas/space-preview-scene.ts | 30 +++++++++-----
 .../modules/storage/module-boundaries.test.ts | 41 +++++++++++++++++++
 docs/architecture/space-preview.md            |  2 +-
 3 files changed, 62 insertions(+), 11 deletions(-)

diff --git a/apps/server/src/modules/canvas/space-preview-scene.ts b/apps/server/src/modules/canvas/space-preview-scene.ts
index 4fed867d7..508d631f1 100644
--- a/apps/server/src/modules/canvas/space-preview-scene.ts
+++ b/apps/server/src/modules/canvas/space-preview-scene.ts
@@ -18,7 +18,7 @@ import {
   stripMarkdown,
 } from '@huabu/shared/canvas-engine';
 
-import { getCanvasStore, getStructuredStore } from '../storage/index.js';
+import { getStructuredStore, space } from '../storage/index.js';
 
 type StoredNode = NestableNode & {
   type?: string;
@@ -146,18 +146,28 @@ export async function getSpacePreviewScene(
     throw new SpacePreviewSceneError(404, 'Target Space was not found');
   }
 
-  const store = getCanvasStore(canvasId);
-  const canvas = store.read();
+  const target = space(canvasId);
+  let canvas;
+  try {
+    canvas = await target.read();
+  } catch {
+    // A record the port refuses to produce is a malformed target, which is
+    // the same 422 the shape checks below raise. Reading it as a file used to
+    // put that judgement here; the port makes it once for every reader, and
+    // this route still owns what the caller is told.
+    throw new SpacePreviewSceneError(422, 'Target Space is malformed');
+  }
   if (!canvas) {
     throw new SpacePreviewSceneError(404, 'Target Space was not found');
   }
 
-  let contentByNodeId;
-  try {
-    contentByNodeId = await store.readAllNodes({ strict: true });
-  } catch {
-    throw new SpacePreviewSceneError(422, 'Target Space content is malformed');
-  }
+  // Node records are read the one lenient way the port defines, which is also
+  // how the Space's own view renders it: a record that cannot be produced is
+  // omitted and the projection falls back to topology data below, and a
+  // record a user broke by hand recovers the same way it does when its Space
+  // is opened. The 422 stays for a malformed *Space record*, which is the
+  // damage that makes the whole projection meaningless.
+  const contentByNodeId = await target.nodes.list();
 
   if (
     !Array.isArray(canvas.state?.nodes) ||
@@ -175,7 +185,7 @@ export async function getSpacePreviewScene(
     const position = absolutePosition(node.id);
     if (!position || !node.type) continue;
     const defaults = getNodeDefaultSize(node.type);
-    const content = contentByNodeId.get(node.id);
+    const content = contentByNodeId.get(node.id)?.record;
     const previewText =
       node.type === 'note' || node.type === 'text'
         ? boundedPreviewText(content?.content ?? node.data?.content)
diff --git a/apps/server/src/modules/storage/module-boundaries.test.ts b/apps/server/src/modules/storage/module-boundaries.test.ts
index 96b6c8f51..5f7b90d94 100644
--- a/apps/server/src/modules/storage/module-boundaries.test.ts
+++ b/apps/server/src/modules/storage/module-boundaries.test.ts
@@ -429,6 +429,47 @@ describe('no production module outside storage names a Disk layout', () => {
     // importers left and was deleted; this keeps the path closed.
     expect(violations).toEqual([]);
   });
+
+  /**
+   * The path check above only sees a direct import. The barrel still
+   * re-exports the legacy store for the compatibility layer and the Disk
+   * suites, so a production file can reach the same object by name without
+   * ever naming its file — which is how one reader survived the migration.
+   */
+  it('rejects a production import of a legacy CanvasStore symbol', () => {
+    // Readers only. `resetStorageCache` is on the barrel too and the
+    // Workspace routes still call it, but it reads nothing — it is the
+    // activation lifecycle dropping an adapter's caches, which is a
+    // composition concern with its own home to find (§12.8), not a
+    // production module learning how a Space is stored.
+    const LEGACY_STORE_SYMBOLS = [
+      'CanvasStore',
+      'getCanvasStore',
+      'forgetCanvasStore',
+    ];
+    const violations: string[] = [];
+    for (const file of sourceFiles) {
+      if (file.startsWith('modules/storage/')) continue;
+      if (file.endsWith('.test.ts')) continue;
+
+      const source = read(file);
+      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]
+            .trim();
+          if (LEGACY_STORE_SYMBOLS.includes(name)) {
+            violations.push(`${file} → ${name}`);
+          }
+        }
+      }
+    }
+    expect(violations).toEqual([]);
+  });
 });
 
 describe('structured write authority', () => {
diff --git a/docs/architecture/space-preview.md b/docs/architecture/space-preview.md
index cba278dec..bb055af76 100644
--- a/docs/architecture/space-preview.md
+++ b/docs/architecture/space-preview.md
@@ -13,7 +13,7 @@ Legacy `canvasRef`, `frameRef`, `nodeRef`, and Pin data remain readable for comp
 
 ## 2. Scene projection boundary
 
-`GET /api/canvas/:canvasId/preview-scene` accepts only an ordinary Space in the active workspace. The server converts topology and node sidecars into the shared zod contract in `packages/shared/src/types/api/space-preview.ts`; missing targets return `404` and malformed target records return `422`.
+`GET /api/canvas/:canvasId/preview-scene` accepts only an ordinary Space in the active workspace. The server reads the target through the storage ports — `space(canvasId).read()` for topology, `nodes.list()` for node records — and converts the result into the shared zod contract in `packages/shared/src/types/api/space-preview.ts`. Missing targets return `404`; a target whose Space record cannot be produced, or whose topology is not the expected shape, returns `422`. Node records are read the one lenient way the port defines: a record that cannot be produced is omitted and the projection falls back to topology data, and a record broken by hand recovers the same way it does when its own Space is opened. A single damaged sidecar therefore renders leniently rather than failing the whole preview, which is the behaviour of the Space's own view.
 
 The response contains identity, title, Canvas version, absolute node geometry, safe visual kinds, whitespace-normalized labels, bounded plain-text excerpts for Note and Text nodes, bounded Image source references, eligible edges, scene bounds, and explicit truncation flags. Markdown is flattened before projection; inline `data:` and renderer-local `blob:` image sources are excluded. The response never includes complete rich-editor state, prompts, chat and Agent state, Interactive View state, artifact bytes, handles, selection, or mutation metadata.
 

From 50ec4b598aa07841b057bcfa91a968b7e2556787 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Mon, 24 Aug 2026 19:19:08 +0800
Subject: [PATCH 7/9] docs(storage): record the backend-agnostic read surface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§12.7 was written as a plan before the work started; it now records what
landed, including the two findings that only appeared while building — that
`node-prompt` could not stay store-aware, and that the barrel let one reader
around a path-level import guard — and the two behaviours that moved on
purpose rather than as side effects.

The architecture doc's list of "remaining compatibility consumers" described
reads that no longer exist. What is left outside the ports is a set of
Disk-shaped capabilities, not a set of readers, which is a different claim and
the one §12.8 acts on.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EKZXxEWwZvAZo8YMaLv4m
---
 docs/architecture/canvas-storage.md     |   4 +-
 docs/proposals/multi-backend-storage.md | 107 +++++++++++++++++++-----
 2 files changed, 89 insertions(+), 22 deletions(-)

diff --git a/docs/architecture/canvas-storage.md b/docs/architecture/canvas-storage.md
index 87e3e5964..3c1162d78 100644
--- a/docs/architecture/canvas-storage.md
+++ b/docs/architecture/canvas-storage.md
@@ -4,7 +4,7 @@
 
 ## 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`. `SpaceNodes` reads one node by id, a named selection through `readMany()`, and the whole Space through `list()` / `stream()`; all four return the same records and the same opaque revisions. The application reaches all of it through one `space(canvasId)` handle on the composition root, which joins the structured handle with the Space's blob scope and, on Disk, its `diskTree`. 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.
+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`. `SpaceNodes` reads one node by id, a named selection through `readMany()`, and the whole Space through `list()` / `stream()`; all four return the same records and the same opaque revisions. The application reaches all of it through one `space(canvasId)` handle on the composition root, which joins the structured handle with the Space's blob scope and, on Disk, its `diskTree`. Space creation and deletion, standalone node writes, executor and revert batches, preprocessing persistence, and event/change mutations enter these ports. Every production structured read now enters these ports too; `CanvasStore` lives inside the Disk adapter and its own suites, and no production module outside `storage/` imports it or a Disk layout symbol. What is left outside the ports are Disk-shaped _capabilities_ rather than reads: bundle export and import, reveal-in-file-manager, the built-in file tools, external-note observation and claim, RFS upload/delete, and boot migrations. Each mutates or names physical files, so they keep non-Disk profiles unselectable until they are declared as unavailable there rather than merely undesigned.
 
 Runtime Home-folder activation reserves the namespace switch before preparing and migrating the selected directory in a disposable child process. An in-flight Workspace operation therefore refuses the switch before the target is touched, and no new operation can enter the old Workspace while preparation is pending. 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.
 
@@ -96,7 +96,7 @@ Key points:
 
 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/`; Workspace identity, durable membership, and Disk locators live under `modules/storage/`, while active-Workspace lifecycle and boot migrations remain 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.
+Canvas persistence DTOs and the write coordinator live under `modules/canvas/`; Workspace identity, durable membership, and Disk locators live under `modules/storage/`, while active-Workspace lifecycle and boot migrations remain 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, prevents new consumers of the forwarding shims, and holds the neutrality guard: no production file outside `storage/` may import a Disk layout symbol or a legacy `CanvasStore` symbol. The check is import-level and symbol-level — a local variable that happens to be called `artifactPath` is not a violation, while importing `canvasRoot`, or reaching `getCanvasStore` through the barrel, is. Migrations are exempt because they rewrite frozen historical on-disk shapes; tests are exempt for the same reason they may name an adapter.
 
 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.
 
diff --git a/docs/proposals/multi-backend-storage.md b/docs/proposals/multi-backend-storage.md
index c6dcdb08e..20906ee10 100644
--- a/docs/proposals/multi-backend-storage.md
+++ b/docs/proposals/multi-backend-storage.md
@@ -55,8 +55,9 @@ Last updated: 2026-08-24
 > PR #93. What remains between the portable contracts and a second structured
 > adapter is specified in §6.4 and built by three change sets rather than one
 > phase: §12.6 (one Space handle and the portable read surface,
-> **implemented**), §12.7 (backend-agnostic application reads), and §12.8 (the
-> dispositions and the product-level harness). §12 is the authoritative plan;
+> **implemented**), §12.7 (backend-agnostic application reads,
+> **implemented**), and §12.8 (the dispositions and the product-level
+> harness). §12 is the authoritative plan;
 > the decision table in §2 marks what each step has actually settled.
 
 ---
@@ -2302,24 +2303,90 @@ Out, and owned by the two change sets that follow: retiring production
 symmetry, the extension substrate, the Disk-only capability matrix, and the
 product-level backend harness (§12.8).
 
-### 12.7 Backend-agnostic application reads — **planned**
-
-Production reads still reach the legacy Disk store directly. This change set
-moves Canvas, agent, web, RFS, interactive-view, and Task reads onto
-`SpaceHandle.read()` and the §12.6.1 node shapes, leaves `CanvasStore` inside
-the Disk adapter and compatibility tests, and widens the module-boundary guard
-to reject production `CanvasStore` imports and Disk-layout imports from every
-production module outside `storage/` — not merely the workspace module.
-
-Pure Canvas context builders take already-read `CanvasFile` / node-record
-values instead of reaching into storage themselves; their async adapters own
-repository access once per request. Search keeps its progressive metadata
-delivery without naming a filesystem scan.
-
-One behavioural hardening rides along: 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.
+### 12.7 Backend-agnostic application reads — **implemented**
+
+The second change set. Every production structured read now 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()`. Search keeps its progressive
+metadata delivery without naming a filesystem scan.
+
+`CanvasStore` remains inside the Disk adapter and the compatibility tests. It
+is not an application service: `storage/canvas-store.ts` had no importers left
+and is deleted — the first of the three Phase-4.5 forwarding shims to go.
+
+Two findings, each 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.
+
+**The barrel was a way around the import guard.** The Space preview
+projection reached the legacy store by name through `storage/index.js`, which
+the path-level check resolved to the barrel and let through. The guard now
+checks the imported symbol as well as the path. `resetStorageCache` is
+deliberately not on that symbol list: it is on the barrel too and the
+Workspace routes still call it, but it reads nothing — it is activation
+dropping an adapter's caches, a composition concern with its own home to find
+(§12.8).
+
+#### 12.7.1 The last Disk-layout imports
+
+The neutrality half of 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.
+
+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 is import-level, repo-wide, migrations and tests exempt: a local
+variable that happens to be called `artifactPath` is not a violation while
+importing `canvasRoot` is.
+
+#### 12.7.2 Two behaviours that moved, deliberately
+
+Neither is implied by the read migration, and both are hardenings rather than
+side effects.
+
+**Duplicate `canvasId` directories raise.** Two Space directories carrying the
+same id resolved last-wins; the directory scan now rejects. That makes a
+Finder-side duplication a loud failure of every catalogue read rather than a
+Space that silently resolves to an arbitrary copy.
+
+**The Space preview reads node records leniently.** The route read sidecars
+strictly and answered 422 when one failed to parse. The port defines a single
+lenient read for the collection — a record it cannot produce is omitted, a
+record broken by hand recovers — and the projection already fell back to
+topology data for an absent record, so a damaged sidecar now renders the way
+it does when its own Space is opened instead of failing the whole preview. The
+422 stays for a malformed Space _record_, and now covers a record the port
+refuses to produce as well as topology that is not the expected shape. The
+alternative was a `strict` flag on `list()`, which the port had just finished
+arguing against: one caller's all-or-nothing preference is not a second read
+semantics every backend has to carry.
 
 ### 12.8 The dispositions, and a harness that proves them — **planned**
 

From b66cdb170008493ef0364a316962e7e69dcfae6b Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 27 Aug 2026 18:24:43 +0800
Subject: [PATCH 8/9] test(storage): cover the portable read surface end to end
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The unit suites beside each reader prove it calls the port. None of them
shows that a request still answers the same way now that every read goes
through `space(canvasId)`, so this adds one suite that drives a real temp
Workspace, the Disk adapters, and the Canvas routes with nothing mocked —
34 scenarios over the four node-read shapes, the Space GET, the preview
projection, duplicate Space directories, World references, search, bundle
export/import, the per-node content routes, executor batches, and Workspace
switching. Both behaviours this branch moved on purpose are pinned there:
a duplicated Space directory fails loudly naming both, and a hand-damaged
sidecar renders instead of 422'ing a preview.

Writing it surfaced two things.

**The bundle record filename could be `undefined`.** `space-import.ts`
captured `[SPACE_JSON_FILENAME, 'canvas.json']` at module scope, and
`layout.ts` → `workspace.ts` → the storage barrel → the composition root →
`space-import.ts` is an import cycle. Entered through a Disk module, this
file evaluates while `layout.ts` is still initializing and the array freezes
that constant to `undefined` for the life of the process — every Space
bundle import then answers 500 with nothing in the message to explain it.
The production entry point's own order happens to be safe, which is why
nothing caught it and why no static import in a test can express the failing
case; the regression test resets the module registry and re-enters the cycle
deliberately. Assembling the list per call is the fix.

**`SpaceNodes.list()` documented the opposite of what it does.** The port
said a record the scan cannot retrieve is omitted; #132 made the scan strict
about reachability and the adapter has said so since, and the adapter is what
runs. The rule the two collection shapes actually keep — strict about
retrievability, lenient about content — is now stated once on the interface
and both shapes are held to it by test, because a caller that could pick the
scan which hides an environmental failure cannot tell a Space that lost a
node from one it merely cannot read.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EFDPiFypeiho39r8Q7Z9uC
---
 .../modules/canvas/portable-reads.e2e.test.ts | 1169 +++++++++++++++++
 .../storage/backends/disk/space-import.ts     |   17 +-
 .../src/modules/storage/ports/structured.ts   |   27 +-
 3 files changed, 1201 insertions(+), 12 deletions(-)
 create mode 100644 apps/server/src/modules/canvas/portable-reads.e2e.test.ts

diff --git a/apps/server/src/modules/canvas/portable-reads.e2e.test.ts b/apps/server/src/modules/canvas/portable-reads.e2e.test.ts
new file mode 100644
index 000000000..1c779e568
--- /dev/null
+++ b/apps/server/src/modules/canvas/portable-reads.e2e.test.ts
@@ -0,0 +1,1169 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * End-to-end coverage for the backend-agnostic read surface.
+ *
+ * Every scenario here drives a **real** stack: a temp Workspace on disk, the
+ * Disk adapters behind the storage ports, and the Canvas routes registered on
+ * a real Fastify instance. Nothing is mocked. The unit suites beside each
+ * module already prove that a given reader calls the port; what they cannot
+ * show is that the whole request path still answers the same way once every
+ * read goes through `space(canvasId)` — including the two behaviours this
+ * change set moved on purpose (a duplicated Space directory now fails loudly,
+ * and a hand-damaged node sidecar renders instead of 422'ing a preview).
+ *
+ * Scenarios are grouped by the surface a user reaches:
+ *
+ *   1. the four node-read shapes agreeing with each other
+ *   2. `GET /canvas/:id` — the Space a client opens
+ *   3. `GET /canvas/:id/preview-scene` — the Portal projection
+ *   4. duplicate Space directories — the catalogue's integrity failure
+ *   5. `GET /canvas/:id/references` — World reference resolution
+ *   6. `POST /canvas/:id/search` — the sidecar scan
+ *   7. `GET /canvas/:id/export` + `POST /canvas/import` — the bundle format
+ *   8. Workspace switching — a retained handle must not read the new one
+ */
+
+import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import multipart from '@fastify/multipart';
+import archiver from 'archiver';
+import fastify from 'fastify';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import canvasRoutes from './canvas.route.js';
+import { refreshCanvasDirIndex } from '../storage/backends/disk/canvas-dirs.js';
+import {
+  createSpace,
+  getStructuredStore,
+  resetStorageCache,
+  space,
+} from '../storage/index.js';
+import { setWorkspacePath } from '../workspace.js';
+
+import type { CanvasFile, NodeContent } from '../storage/index.js';
+import type { FastifyInstance } from 'fastify';
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+interface SeedNode {
+  readonly id: string;
+  readonly type: string;
+  readonly label: string | null;
+  readonly content?: string;
+  readonly position?: { x: number; y: number };
+  /** Extra topology `data` fields — Portal targets, question state, … */
+  readonly data?: Record<string, unknown>;
+  /** Omit the sidecar entirely; the node exists in topology only. */
+  readonly sidecar?: false;
+}
+
+interface SeedEdge {
+  readonly id: string;
+  readonly source: string;
+  readonly target: string;
+  readonly label?: string;
+}
+
+let workspacePath: string;
+let app: FastifyInstance;
+
+function freshWorkspace(): string {
+  const root = mkdtempSync(path.join(tmpdir(), 'huabu-portable-reads-'));
+  setWorkspacePath(root);
+  resetStorageCache();
+  return root;
+}
+
+async function buildApp(): Promise<FastifyInstance> {
+  const instance = fastify();
+  await instance.register(multipart);
+  await instance.register(canvasRoutes, { prefix: '/canvas' });
+  await instance.ready();
+  return instance;
+}
+
+function topologyNode(node: SeedNode): Record<string, unknown> {
+  return {
+    id: node.id,
+    type: node.type,
+    position: node.position ?? { x: 0, y: 0 },
+    data: { label: node.label, ...(node.data ?? {}) },
+  };
+}
+
+function nodeRecord(node: SeedNode): NodeContent {
+  return {
+    nodeId: node.id,
+    type: node.type,
+    label: node.label,
+    content: node.content ?? '',
+  };
+}
+
+/** Create a Space and install one topology + sidecar generation through the port. */
+async function seedSpace(
+  canvasId: string,
+  title: string | null,
+  nodes: readonly SeedNode[] = [],
+  edges: readonly SeedEdge[] = [],
+): Promise<CanvasFile> {
+  const created = await createSpace(canvasId, title);
+  if (!created.ok) throw new Error(`seed failed for ${canvasId}`);
+  return writeTopology(canvasId, nodes, edges);
+}
+
+/** Replace a Space's topology and sidecars, whatever its current version. */
+async function writeTopology(
+  canvasId: string,
+  nodes: readonly SeedNode[],
+  edges: readonly SeedEdge[] = [],
+): Promise<CanvasFile> {
+  const handle = space(canvasId);
+  const current = await handle.read();
+  if (!current) throw new Error(`no Space record for ${canvasId}`);
+  const nextRecord: CanvasFile = {
+    ...current,
+    version: current.version + 1,
+    updatedAt: Date.now(),
+    state: {
+      ...current.state,
+      nodes: nodes.map(topologyNode),
+      edges: edges.map((edge) => ({
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        ...(edge.label === undefined ? {} : { data: { label: edge.label } }),
+      })),
+    },
+  };
+  const result = await handle.write({
+    expectedVersion: current.version,
+    nextRecord,
+    nodeMutations: nodes
+      .filter((node) => node.sidecar !== false)
+      .map((node) => ({
+        kind: 'put' as const,
+        nodeId: node.id,
+        record: nodeRecord(node),
+      })),
+  });
+  if (!result.ok) throw new Error(`seed write failed: ${result.reason}`);
+  return nextRecord;
+}
+
+/**
+ * Disk's own directory for a Space.
+ *
+ * The tests reach for it to damage a Space the way a user with a file manager
+ * would — which is exactly the capability `diskTree` exists to name, and the
+ * only reason a test may know a Space is a folder.
+ */
+function spaceDirectory(canvasId: string): string {
+  const tree = space(canvasId).diskTree;
+  if (!tree) throw new Error('expected a Disk-backed Space');
+  return tree.directory();
+}
+
+function spaceNodesDirectory(canvasId: string): string {
+  const tree = space(canvasId).diskTree;
+  if (!tree) throw new Error('expected a Disk-backed Space');
+  return tree.nodesDirectory();
+}
+
+/** Hand-write a sidecar the way a user editing files outside the app would. */
+function writeSidecarByHand(
+  canvasId: string,
+  filename: string,
+  body: string,
+): void {
+  const dir = spaceNodesDirectory(canvasId);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, filename), body, 'utf8');
+  resetStorageCache();
+}
+
+/** Overwrite a Space record on disk, bypassing the port's version check. */
+function writeRecordByHand(canvasId: string, record: unknown): void {
+  writeFileSync(
+    path.join(spaceDirectory(canvasId), 'space.json'),
+    JSON.stringify(record, null, 2),
+    'utf8',
+  );
+  resetStorageCache();
+}
+
+function multipartBody(
+  filename: string,
+  body: Buffer,
+): { payload: Buffer; headers: Record<string, string> } {
+  const boundary = '----huabu-portable-reads';
+  const head = Buffer.from(
+    `--${boundary}\r\n` +
+      `Content-Disposition: form-data; name="file"; filename="${filename}"\r\n` +
+      `Content-Type: application/zip\r\n\r\n`,
+  );
+  const tail = Buffer.from(`\r\n--${boundary}--\r\n`);
+  return {
+    payload: Buffer.concat([head, body, tail]),
+    headers: { 'content-type': `multipart/form-data; boundary=${boundary}` },
+  };
+}
+
+/** Build a Space bundle by hand, so an older on-the-wire shape can be replayed. */
+async function makeBundle(entries: Record<string, string>): Promise<Buffer> {
+  const archive = archiver('zip', { zlib: { level: 0 } });
+  const chunks: Buffer[] = [];
+  archive.on('data', (chunk: Buffer) => chunks.push(chunk));
+  const finished = new Promise<void>((resolve, reject) => {
+    archive.on('end', () => resolve());
+    archive.on('error', reject);
+  });
+  for (const [name, content] of Object.entries(entries)) {
+    archive.append(content, { name });
+  }
+  await archive.finalize();
+  await finished;
+  return Buffer.concat(chunks);
+}
+
+/** Read an NDJSON search response back into its events. */
+function ndjson(payload: string): Record<string, unknown>[] {
+  return payload
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+}
+
+beforeEach(async () => {
+  workspacePath = freshWorkspace();
+  await getStructuredStore().spaces().ensureWorld();
+  app = await buildApp();
+});
+
+afterEach(async () => {
+  await app.close();
+  resetStorageCache();
+  rmSync(workspacePath, { recursive: true, force: true });
+});
+
+// ─── 1. The four node-read shapes ───────────────────────────────────────────
+
+describe('node reads through the port', () => {
+  it('serves the same records and revisions through read, readMany, list, and stream', async () => {
+    await seedSpace('canvas-shapes', 'Shapes', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'alpha body' },
+      { id: 'node-b', type: 'note', label: 'Beta', content: 'beta body' },
+      { id: 'node-c', type: 'text', label: 'Gamma', content: 'gamma body' },
+    ]);
+    const nodes = space('canvas-shapes').nodes;
+
+    const listed = await nodes.list();
+    const streamed = new Map<string, unknown>();
+    const settled = await nodes.stream((snapshot) => {
+      streamed.set(snapshot.record.nodeId, snapshot);
+    });
+    const selected = await nodes.readMany(['node-a', 'node-c']);
+    const single = await nodes.read('node-a');
+
+    expect([...listed.keys()].sort()).toEqual(['node-a', 'node-b', 'node-c']);
+    expect(settled).toEqual(listed);
+    expect(streamed.size).toBe(3);
+    expect(single).toEqual(listed.get('node-a'));
+    expect(selected.get('node-a')).toEqual(listed.get('node-a'));
+    expect(selected.get('node-c')).toEqual(listed.get('node-c'));
+    // The revision is the port's own opaque token; the same record must not
+    // produce two of them depending on which shape asked for it.
+    expect(single?.revision).toBe(listed.get('node-a')?.revision);
+  });
+
+  it('treats an absent id in readMany as a missing key and collapses repeats', async () => {
+    await seedSpace('canvas-select', 'Select', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'a' },
+    ]);
+
+    const selected = await space('canvas-select').nodes.readMany([
+      'node-a',
+      'node-a',
+      'node-missing',
+    ]);
+
+    expect(selected.size).toBe(1);
+    expect(selected.has('node-missing')).toBe(false);
+    expect(await space('canvas-select').nodes.read('node-missing')).toBeNull();
+  });
+
+  it('stops a streamed scan early when the caller aborts, and still settles', async () => {
+    // More nodes than the adapter's read concurrency, so aborting on the first
+    // delivery still leaves work the scan can decline to do.
+    const total = 128;
+    await seedSpace(
+      'canvas-abort',
+      'Abort',
+      Array.from({ length: total }, (_, i) => ({
+        id: `node-${i}`,
+        type: 'note',
+        label: `Node ${i}`,
+        content: `body ${i}`,
+      })),
+    );
+
+    const signal = { aborted: false };
+    const seen: string[] = [];
+    const settled = await space('canvas-abort').nodes.stream(
+      (snapshot) => {
+        seen.push(snapshot.record.nodeId);
+        signal.aborted = true;
+      },
+      { signal },
+    );
+
+    // The promise still settles — an aborted scan must not leak a pending
+    // read — but its map is partial by definition.
+    expect(seen.length).toBeGreaterThan(0);
+    expect(settled.size).toBeLessThan(total);
+    expect(settled.size).toBe(seen.length);
+  });
+
+  it('recovers a hand-broken sidecar identically through read and list', async () => {
+    await seedSpace('canvas-broken', 'Broken', [
+      { id: 'node-ok', type: 'note', label: 'Fine', content: 'fine' },
+    ]);
+    writeSidecarByHand(
+      'canvas-broken',
+      'node-damaged.md',
+      '---\nlabel: [unterminated\n---\nthe body survives\n',
+    );
+
+    const nodes = space('canvas-broken').nodes;
+    const single = await nodes.read('node-damaged');
+    const listed = await nodes.list();
+
+    // Broken YAML is dropped, the markdown body is kept, and both shapes
+    // report the node the same way.
+    expect(single?.record.content.trim()).toBe('the body survives');
+    expect(single?.record.label).toBeNull();
+    expect(listed.get('node-damaged')).toEqual(single);
+  });
+
+  it('rejects both collection scans when a record cannot be retrieved at all', async () => {
+    await seedSpace('canvas-unreadable', 'Unreadable', [
+      { id: 'node-ok', type: 'note', label: 'Fine', content: 'fine' },
+    ]);
+    // A directory where a sidecar should be: reachable-but-unreadable, which
+    // is the environmental failure the port says must never look like absence.
+    mkdirSync(
+      path.join(spaceNodesDirectory('canvas-unreadable'), 'node-blocked.md'),
+      { recursive: true },
+    );
+    resetStorageCache();
+
+    const nodes = space('canvas-unreadable').nodes;
+    await expect(nodes.list()).rejects.toThrow();
+    // The streamed shape answers the same way, so a caller cannot pick the
+    // scan that hides the failure.
+    await expect(nodes.stream(() => {})).rejects.toThrow();
+  });
+});
+
+// ─── 2. GET /canvas/:id ─────────────────────────────────────────────────────
+
+describe('GET /canvas/:canvasId', () => {
+  it('hydrates node bodies that live only in the sidecars', async () => {
+    await seedSpace('canvas-get', 'Get', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'sidecar body' },
+    ]);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-get',
+    });
+
+    expect(response.statusCode).toBe(200);
+    const node = response.json().state.nodes[0];
+    expect(node.data.content).toBe('sidecar body');
+    // The body must not have been round-tripped into the topology record.
+    const record = await space('canvas-get').read();
+    expect(JSON.stringify(record?.state.nodes)).not.toContain('sidecar body');
+  });
+
+  it('still serves a Space whose sidecar frontmatter a user broke', async () => {
+    await seedSpace('canvas-get-broken', 'Get broken', [
+      { id: 'node-damaged', type: 'note', label: 'Damaged', sidecar: false },
+    ]);
+    writeSidecarByHand(
+      'canvas-get-broken',
+      'node-damaged.md',
+      '---\nlabel: [unterminated\n---\nstill readable\n',
+    );
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-get-broken',
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json().state.nodes[0].data.content).toContain(
+      'still readable',
+    );
+  });
+
+  it('answers 404 for a Space that does not exist', async () => {
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-absent',
+    });
+
+    expect(response.statusCode).toBe(404);
+  });
+});
+
+// ─── 3. GET /canvas/:id/preview-scene ───────────────────────────────────────
+
+describe('GET /canvas/:canvasId/preview-scene', () => {
+  it('projects records and topology into one bounded scene', async () => {
+    await seedSpace(
+      'canvas-preview',
+      'Preview',
+      [
+        {
+          id: 'node-a',
+          type: 'note',
+          label: 'Alpha',
+          content: '# Heading\n\nSome **preview** text.',
+          position: { x: 10, y: 20 },
+        },
+        {
+          id: 'node-b',
+          type: 'note',
+          label: 'Beta',
+          content: 'beta body',
+          position: { x: 300, y: 20 },
+        },
+      ],
+      [{ id: 'edge-1', source: 'node-a', target: 'node-b', label: 'links' }],
+    );
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-preview/preview-scene',
+    });
+
+    expect(response.statusCode).toBe(200);
+    const scene = response.json();
+    expect(scene.nodes).toHaveLength(2);
+    expect(scene.nodes[0]).toMatchObject({
+      id: 'node-a',
+      kind: 'content',
+      x: 10,
+      y: 20,
+    });
+    // Markdown is stripped for the preview text, and it comes from the record.
+    expect(scene.nodes[0].previewText).toContain('Some preview text');
+    expect(scene.edges).toEqual([
+      expect.objectContaining({ id: 'edge-1', label: 'links' }),
+    ]);
+    expect(scene.truncated).toEqual({ nodes: false, edges: false });
+  });
+
+  it('renders a damaged sidecar instead of refusing the whole projection', async () => {
+    // The behaviour this change set moved on purpose: the preview used to read
+    // sidecars strictly and answer 422 when one failed to parse. It now reads
+    // the same lenient collection the Space's own view does.
+    await seedSpace('canvas-preview-damaged', 'Damaged preview', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'alpha' },
+      { id: 'node-damaged', type: 'note', label: 'Damaged', sidecar: false },
+    ]);
+    writeSidecarByHand(
+      'canvas-preview-damaged',
+      'node-damaged.md',
+      '---\nkeywords: [oops\n---\nrecovered body\n',
+    );
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-preview-damaged/preview-scene',
+    });
+
+    expect(response.statusCode).toBe(200);
+    const ids = response.json().nodes.map((node: { id: string }) => node.id);
+    expect(ids).toEqual(['node-a', 'node-damaged']);
+  });
+
+  it('falls back to topology data for a node with no sidecar at all', async () => {
+    await seedSpace('canvas-preview-bare', 'Bare preview', [
+      {
+        id: 'node-bare',
+        type: 'note',
+        label: 'Bare',
+        sidecar: false,
+        data: { content: 'topology fallback' },
+      },
+    ]);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-preview-bare/preview-scene',
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json().nodes[0]).toMatchObject({
+      id: 'node-bare',
+      label: 'Bare',
+      previewText: 'topology fallback',
+    });
+  });
+
+  it('keeps 422 for a malformed Space record', async () => {
+    await seedSpace('canvas-preview-malformed', 'Malformed', []);
+    writeRecordByHand('canvas-preview-malformed', {
+      canvasId: 'canvas-preview-malformed',
+      title: 'Malformed',
+      version: 1,
+      createdAt: 1,
+      updatedAt: 1,
+      state: { nodes: 'not an array', edges: [] },
+    });
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-preview-malformed/preview-scene',
+    });
+
+    expect(response.statusCode).toBe(422);
+    expect(response.json().message).toContain('malformed');
+  });
+
+  it('answers 404 for an absent Space and for the World Space', async () => {
+    const worldId = await getStructuredStore().spaces().worldId();
+
+    const absent = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-absent/preview-scene',
+    });
+    const world = await app.inject({
+      method: 'GET',
+      url: `/canvas/${worldId}/preview-scene`,
+    });
+
+    expect(absent.statusCode).toBe(404);
+    expect(world.statusCode).toBe(404);
+  });
+});
+
+// ─── 4. Duplicate Space directories ─────────────────────────────────────────
+
+describe('two directories claiming one Space', () => {
+  it('fails every catalogue read loudly and names both directories', async () => {
+    await seedSpace('canvas-dupe', 'Duplicated', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'a' },
+    ]);
+    cpSync(
+      spaceDirectory('canvas-dupe'),
+      path.join(workspacePath, 'Duplicated copy'),
+      { recursive: true },
+    );
+    refreshCanvasDirIndex();
+
+    const listed = await app.inject({ method: 'GET', url: '/canvas' });
+
+    expect(listed.statusCode).toBe(500);
+    await expect(getStructuredStore().spaces().list()).rejects.toThrow(
+      /duplicate directories.*Duplicated.*Duplicated copy/s,
+    );
+  });
+
+  it('recovers as soon as one of the two directories is removed', async () => {
+    await seedSpace('canvas-dupe-fix', 'Fixable', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'a' },
+    ]);
+    const copy = path.join(workspacePath, 'Fixable copy');
+    cpSync(spaceDirectory('canvas-dupe-fix'), copy, { recursive: true });
+    refreshCanvasDirIndex();
+    await expect(getStructuredStore().spaces().list()).rejects.toThrow();
+
+    rmSync(copy, { recursive: true, force: true });
+    refreshCanvasDirIndex();
+
+    const listed = await app.inject({ method: 'GET', url: '/canvas' });
+    expect(listed.statusCode).toBe(200);
+    expect(
+      listed
+        .json()
+        .canvases.map((entry: { canvasId: string }) => entry.canvasId),
+    ).toContain('canvas-dupe-fix');
+  });
+});
+
+// ─── 5. GET /canvas/:id/references ──────────────────────────────────────────
+
+describe('GET /canvas/:canvasId/references', () => {
+  async function seedWorld(nodes: readonly SeedNode[]): Promise<string> {
+    const worldId = await getStructuredStore().spaces().worldId();
+    await writeTopology(worldId, nodes);
+    return worldId;
+  }
+
+  it('resolves Portal and node references through the ports', async () => {
+    await seedSpace('canvas-src', 'Source', [
+      {
+        id: 'node-target',
+        type: 'note',
+        label: 'Target',
+        content: 'target body',
+      },
+    ]);
+    const worldId = await seedWorld([
+      {
+        id: 'node-portal',
+        type: 'canvasRef',
+        label: null,
+        sidecar: false,
+        data: { targetCanvasId: 'canvas-src' },
+      },
+      {
+        id: 'node-ref',
+        type: 'nodeRef',
+        label: null,
+        sidecar: false,
+        data: { target: { canvasId: 'canvas-src', nodeId: 'node-target' } },
+      },
+    ]);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/canvas/${worldId}/references`,
+    });
+
+    expect(response.statusCode).toBe(200);
+    const { references } = response.json();
+    expect(references).toEqual([
+      expect.objectContaining({
+        kind: 'canvasRef',
+        targetCanvasId: 'canvas-src',
+        status: 'ok',
+        title: 'Source',
+      }),
+      expect.objectContaining({
+        kind: 'nodeRef',
+        status: 'ok',
+        source: expect.objectContaining({ type: 'note', label: 'Target' }),
+      }),
+    ]);
+  });
+
+  it('reports a missing Space and a missing node distinctly', async () => {
+    await seedSpace('canvas-partial', 'Partial', [
+      { id: 'node-present', type: 'note', label: 'Present', content: 'here' },
+    ]);
+    const worldId = await seedWorld([
+      {
+        id: 'node-portal',
+        type: 'canvasRef',
+        label: null,
+        sidecar: false,
+        data: { targetCanvasId: 'canvas-gone' },
+      },
+      {
+        id: 'node-ref',
+        type: 'nodeRef',
+        label: null,
+        sidecar: false,
+        data: { target: { canvasId: 'canvas-partial', nodeId: 'node-gone' } },
+      },
+    ]);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/canvas/${worldId}/references`,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(
+      response.json().references.map((ref: { status: string }) => ref.status),
+    ).toEqual(['canvas-missing', 'node-missing']);
+  });
+
+  it('refuses to resolve references for an ordinary Space', async () => {
+    await seedSpace('canvas-ordinary', 'Ordinary', []);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-ordinary/references',
+    });
+
+    expect(response.statusCode).toBe(400);
+  });
+});
+
+// ─── 6. POST /canvas/:id/search ─────────────────────────────────────────────
+
+describe('POST /canvas/:canvasId/search', () => {
+  it('finds text that exists only in a node sidecar', async () => {
+    await seedSpace('canvas-search', 'Search', [
+      {
+        id: 'node-a',
+        type: 'note',
+        label: 'Alpha',
+        content: 'the needle is in the body',
+      },
+      { id: 'node-b', type: 'note', label: 'Beta', content: 'unrelated' },
+    ]);
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/canvas/canvas-search/search',
+      payload: { query: 'needle' },
+    });
+
+    expect(response.statusCode).toBe(200);
+    const events = ndjson(response.payload);
+    const matches = events.filter((event) => event.type === 'match');
+    expect(matches).toHaveLength(1);
+    expect(matches[0]).toMatchObject({
+      tier: 'content',
+      match: {
+        nodeId: 'node-a',
+        field: 'content',
+        snippet: expect.stringContaining('needle'),
+      },
+    });
+    expect(events.at(-1)).toMatchObject({ type: 'done' });
+  });
+
+  it('answers 404 before opening a stream for an absent Space', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/canvas/canvas-absent/search',
+      payload: { query: 'needle' },
+    });
+
+    expect(response.statusCode).toBe(404);
+  });
+});
+
+// ─── 7. Bundle export and import ────────────────────────────────────────────
+
+describe('Space bundle round trip', () => {
+  it('re-imports an exported bundle as a new Space with its node records', async () => {
+    await seedSpace('canvas-export', 'Exported', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'exported body' },
+    ]);
+
+    const exported = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-export/export',
+    });
+    expect(exported.statusCode).toBe(200);
+    expect(exported.headers['content-disposition']).toContain('.huabu.zip');
+
+    const body = multipartBody('Exported.huabu.zip', exported.rawPayload);
+    const imported = await app.inject({
+      method: 'POST',
+      url: '/canvas/import',
+      payload: body.payload,
+      headers: body.headers,
+    });
+
+    expect(imported.statusCode).toBe(200);
+    const newCanvasId = imported.json().canvasId;
+    expect(newCanvasId).not.toBe('canvas-export');
+
+    const record = await space(newCanvasId).read();
+    expect(record?.canvasId).toBe(newCanvasId);
+    const nodes = await space(newCanvasId).nodes.list();
+    expect(nodes.get('node-a')?.record.content).toContain('exported body');
+  });
+
+  it('accepts a bundle that still carries the frozen canvas.json record name', async () => {
+    const bundle = await makeBundle({
+      'manifest.json': JSON.stringify({ version: '2', title: 'Legacy bundle' }),
+      'canvas.json': JSON.stringify({
+        canvasId: 'canvas-legacy-source',
+        title: 'Legacy bundle',
+        version: 3,
+        createdAt: 1,
+        updatedAt: 2,
+        state: {
+          nodes: [
+            {
+              id: 'node-legacy',
+              type: 'note',
+              position: { x: 0, y: 0 },
+              data: { label: 'Legacy' },
+            },
+          ],
+          edges: [],
+        },
+      }),
+      'nodes/Legacy.md':
+        '---\nid: node-legacy\ntype: note\nlabel: Legacy\n---\nlegacy body\n',
+    });
+
+    const body = multipartBody('legacy.huabu.zip', bundle);
+    const imported = await app.inject({
+      method: 'POST',
+      url: '/canvas/import',
+      payload: body.payload,
+      headers: body.headers,
+    });
+
+    expect(imported.statusCode).toBe(200);
+    const canvasId = imported.json().canvasId;
+    const record = await space(canvasId).read();
+    expect(record?.title).toBe('Legacy bundle');
+    const nodes = await space(canvasId).nodes.list();
+    expect(nodes.get('node-legacy')?.record.content).toContain('legacy body');
+  });
+
+  it('de-duplicates the title when the imported name is already taken', async () => {
+    await seedSpace('canvas-taken', 'Shared name', []);
+    const bundle = await makeBundle({
+      'manifest.json': JSON.stringify({ version: '2', title: 'Shared name' }),
+      'space.json': JSON.stringify({
+        canvasId: 'canvas-other-source',
+        title: 'Shared name',
+        version: 0,
+        createdAt: 1,
+        updatedAt: 1,
+        state: { nodes: [], edges: [] },
+      }),
+    });
+
+    const body = multipartBody('shared.huabu.zip', bundle);
+    const imported = await app.inject({
+      method: 'POST',
+      url: '/canvas/import',
+      payload: body.payload,
+      headers: body.headers,
+    });
+
+    expect(imported.statusCode).toBe(200);
+    const record = await space(imported.json().canvasId).read();
+    expect(record?.title).not.toBe('Shared name');
+    expect(record?.title).toContain('Shared name');
+  });
+
+  it('refuses a bundle with no Space record and leaves no staging directory', async () => {
+    const bundle = await makeBundle({
+      'manifest.json': JSON.stringify({ version: '2' }),
+      'nodes/Orphan.md': '---\nid: node-orphan\n---\nno record\n',
+    });
+
+    const body = multipartBody('broken.huabu.zip', bundle);
+    const imported = await app.inject({
+      method: 'POST',
+      url: '/canvas/import',
+      payload: body.payload,
+      headers: body.headers,
+    });
+
+    expect(imported.statusCode).toBe(400);
+    const listed = await app.inject({ method: 'GET', url: '/canvas' });
+    expect(listed.json().canvases).toHaveLength(0);
+  });
+
+  it('resolves the record filename however the module graph was entered', async () => {
+    // `space-import.ts` reads the record filename from `layout.ts`, and the
+    // two sit in one import cycle: layout → workspace → the storage barrel →
+    // the composition root → space-import. Whichever module the process
+    // happens to load first decides whether `layout.ts` has finished
+    // initializing by the time this file evaluates, so a module-scope capture
+    // of that constant is `undefined` for the life of the process under some
+    // orders and correct under others — and every bundle import then answers
+    // 500 with no clue why.
+    //
+    // A static import cannot express that: the order this file's own imports
+    // produce is the safe one. Reset the registry and re-enter the cycle
+    // through a Disk module, which is the order that breaks it.
+    vi.resetModules();
+    await import('../storage/backends/disk/canvas-dirs.js');
+    const reloadedStorage = await import('../storage/index.js');
+    const reloadedWorkspace = await import('../workspace.js');
+
+    const staging = mkdtempSync(path.join(tmpdir(), 'huabu-portable-reads-4-'));
+    try {
+      reloadedWorkspace.setWorkspacePath(staging);
+      const staged = reloadedStorage.stageSpaceImport('canvas-staged');
+      expect(staged).not.toBeNull();
+      if (!staged) return;
+      mkdirSync(staged.stagingDirectory, { recursive: true });
+      writeFileSync(
+        path.join(staged.stagingDirectory, 'space.json'),
+        JSON.stringify({
+          canvasId: 'canvas-staged-source',
+          title: 'Staged',
+          version: 0,
+          createdAt: 1,
+          updatedAt: 1,
+          state: { nodes: [], edges: [] },
+        }),
+        'utf8',
+      );
+
+      await expect(staged.readRecord()).resolves.toMatchObject({
+        canvasId: 'canvas-staged-source',
+      });
+    } finally {
+      rmSync(staging, { recursive: true, force: true });
+      // The reloaded copy of `workspace.ts` holds its own module state; put
+      // the one this file uses back where the shared setup left it.
+      setWorkspacePath(workspacePath);
+      resetStorageCache();
+    }
+  });
+
+  it('answers 404 when exporting a Space that does not exist', async () => {
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-absent/export',
+    });
+
+    expect(response.statusCode).toBe(404);
+  });
+});
+
+// ─── 8. Per-node content routes ─────────────────────────────────────────────
+
+describe('per-node content routes', () => {
+  it('serves one node record and round-trips an edit back through it', async () => {
+    await seedSpace('canvas-content', 'Content', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'first body' },
+    ]);
+
+    const before = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-content/nodes/node-a/content',
+    });
+    expect(before.statusCode).toBe(200);
+    expect(before.json()).toMatchObject({
+      nodeId: 'node-a',
+      type: 'note',
+      label: 'Alpha',
+      content: 'first body',
+    });
+
+    const written = await app.inject({
+      method: 'PUT',
+      url: '/canvas/canvas-content/nodes/node-a/content',
+      payload: { nodeType: 'note', content: 'second body' },
+    });
+    expect(written.statusCode).toBe(200);
+
+    const after = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-content/nodes/node-a/content',
+    });
+    expect(after.json().content).toBe('second body');
+    // Sidecar writes are outside the Space record's version counter.
+    expect((await space('canvas-content').read())?.version).toBe(1);
+  });
+
+  it('returns a placeholder rather than 404 for a node with no sidecar', async () => {
+    await seedSpace('canvas-content-bare', 'Bare content', [
+      { id: 'node-bare', type: 'note', label: 'Bare', sidecar: false },
+    ]);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-content-bare/nodes/node-bare/content',
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toMatchObject({
+      nodeId: 'node-bare',
+      contentMissing: true,
+      content: '',
+    });
+  });
+
+  it('keeps a node whose frontmatter a user broke editable and deletable', async () => {
+    // The reason the port's single-node read is strict about reachability but
+    // lenient about content: refusing the read would make a hand-broken node
+    // unreachable through exactly the two routes that could repair it.
+    await seedSpace('canvas-content-broken', 'Broken content', [
+      { id: 'node-broken', type: 'note', label: 'Broken', sidecar: false },
+    ]);
+    writeSidecarByHand(
+      'canvas-content-broken',
+      'node-broken.md',
+      '---\nkeywords: [oops\n---\nsalvageable\n',
+    );
+
+    const read = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-content-broken/nodes/node-broken/content',
+    });
+    expect(read.statusCode).toBe(200);
+    expect(read.json().content).toContain('salvageable');
+
+    const repaired = await app.inject({
+      method: 'PUT',
+      url: '/canvas/canvas-content-broken/nodes/node-broken/content',
+      payload: { nodeType: 'note', content: 'repaired', label: 'Broken' },
+    });
+    expect(repaired.statusCode).toBe(200);
+    expect(
+      (await space('canvas-content-broken').nodes.read('node-broken'))?.record
+        .content,
+    ).toContain('repaired');
+
+    const deleted = await app.inject({
+      method: 'DELETE',
+      url: '/canvas/canvas-content-broken/nodes/node-broken',
+    });
+    expect(deleted.statusCode).toBe(200);
+    expect(
+      await space('canvas-content-broken').nodes.read('node-broken'),
+    ).toBeNull();
+  });
+
+  it('renders a node two sidecars claim, and refuses to overwrite either', async () => {
+    // Only a filesystem can produce this, so only Disk answers it: the read
+    // path keeps the node visible with a duplicate hint so a user can fix it,
+    // while the write path hard-fails rather than picking a file.
+    await seedSpace('canvas-dupe-node', 'Duplicate node', [
+      { id: 'node-a', type: 'note', label: 'Alpha', content: 'original' },
+    ]);
+    writeSidecarByHand(
+      'canvas-dupe-node',
+      'Alpha copy.md',
+      '---\nid: node-a\ntype: note\nlabel: Alpha\n---\nsecond claim\n',
+    );
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/canvas/canvas-dupe-node/nodes/node-a/content',
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toMatchObject({
+      nodeId: 'node-a',
+      contentDuplicate: true,
+    });
+    expect(response.json().duplicateFiles).toHaveLength(2);
+
+    const put = await space('canvas-dupe-node').nodes.put({
+      nodeId: 'node-a',
+      record: {
+        nodeId: 'node-a',
+        type: 'note',
+        label: 'Alpha',
+        content: 'overwrite attempt',
+      },
+    });
+    expect(put).toMatchObject({ ok: false, reason: 'duplicate-node' });
+  });
+});
+
+// ─── 9. Executor batches ────────────────────────────────────────────────────
+
+describe('POST /canvas/:canvasId/execute', () => {
+  it('hydrates prestate through the ports and lands nodes plus sidecars', async () => {
+    await seedSpace('canvas-exec', 'Exec', [
+      { id: 'node-existing', type: 'note', label: 'Existing', content: 'kept' },
+    ]);
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/canvas/canvas-exec/execute',
+      payload: {
+        originator: { source: 'ui' },
+        commands: [
+          {
+            type: 'CREATE_NODES',
+            nodes: [
+              {
+                id: 'node-new',
+                nodeType: 'note',
+                position: { x: 40, y: 40 },
+                data: { label: 'New', content: 'created by the executor' },
+              },
+            ],
+          },
+        ],
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toMatchObject({
+      canvasId: 'canvas-exec',
+      fromVersion: 1,
+      toVersion: 2,
+    });
+
+    const nodes = await space('canvas-exec').nodes.list();
+    expect([...nodes.keys()].sort()).toEqual(['node-existing', 'node-new']);
+    expect(nodes.get('node-new')?.record.content).toContain(
+      'created by the executor',
+    );
+    // The prestate the batch read from is still there afterwards.
+    expect(nodes.get('node-existing')?.record.content).toBe('kept');
+  });
+
+  it('answers 404 for a batch addressed to a Space that does not exist', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/canvas/canvas-absent/execute',
+      payload: { originator: { source: 'ui' }, commands: [] },
+    });
+
+    expect(response.statusCode).toBe(404);
+  });
+});
+
+// ─── 10. Workspace switching ────────────────────────────────────────────────
+
+describe('a handle bound to one Workspace', () => {
+  it('refuses to read a newly activated Workspace instead of resolving into it', async () => {
+    await seedSpace('canvas-bound', 'Bound', [
+      {
+        id: 'node-a',
+        type: 'note',
+        label: 'Alpha',
+        content: 'first workspace',
+      },
+    ]);
+    const retained = space('canvas-bound');
+    const retainedNodes = retained.nodes;
+    const retainedTree = retained.diskTree;
+    expect(retainedTree).not.toBeNull();
+
+    const second = mkdtempSync(path.join(tmpdir(), 'huabu-portable-reads-2-'));
+    try {
+      setWorkspacePath(second);
+      resetStorageCache();
+
+      await expect(retainedNodes.list()).rejects.toThrow(/inactive workspace/i);
+      await expect(retainedNodes.read('node-a')).rejects.toThrow(
+        /inactive workspace/i,
+      );
+      expect(() => retainedTree?.directory()).toThrow(/inactive workspace/i);
+    } finally {
+      rmSync(second, { recursive: true, force: true });
+      setWorkspacePath(workspacePath);
+      resetStorageCache();
+    }
+  });
+
+  it('serves the new Workspace through a freshly resolved handle', async () => {
+    await seedSpace('canvas-bound-2', 'Bound two', []);
+
+    const second = mkdtempSync(path.join(tmpdir(), 'huabu-portable-reads-3-'));
+    try {
+      setWorkspacePath(second);
+      resetStorageCache();
+      await getStructuredStore().spaces().ensureWorld();
+
+      expect(await space('canvas-bound-2').read()).toBeNull();
+      expect(await getStructuredStore().spaces().list()).toEqual([]);
+    } finally {
+      rmSync(second, { recursive: true, force: true });
+      setWorkspacePath(workspacePath);
+      resetStorageCache();
+    }
+  });
+});
diff --git a/apps/server/src/modules/storage/backends/disk/space-import.ts b/apps/server/src/modules/storage/backends/disk/space-import.ts
index b9bdf181f..5b70b651c 100644
--- a/apps/server/src/modules/storage/backends/disk/space-import.ts
+++ b/apps/server/src/modules/storage/backends/disk/space-import.ts
@@ -33,15 +33,24 @@ import { getWorkspacePath } from '../../../workspace.js';
 import type { CanvasFile } from '../../../canvas/persistence-types.js';
 
 /**
- * The filename a bundle carries its record under, before this backend
+ * The filenames a bundle may carry 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.
+ *
+ * Assembled per call rather than captured at module scope. `layout.ts` and
+ * this file sit in one import cycle — layout imports `getWorkspacePath`,
+ * `workspace.ts` imports the storage barrel, and the composition root imports
+ * this module — so a graph entered through a Disk module evaluates this file
+ * while `layout.ts` is still initializing. A module-level array would freeze
+ * `undefined` in place of the record filename for the life of the process.
  */
-const BUNDLE_RECORD_FILENAMES = [SPACE_JSON_FILENAME, 'canvas.json'] as const;
+function bundleRecordFilenames(): readonly string[] {
+  return [SPACE_JSON_FILENAME, 'canvas.json'];
+}
 
 export interface DiskSpaceImport {
   /** Where the bundle's entries should be written. */
@@ -72,7 +81,7 @@ export function stageDiskSpaceImport(canvasId: string): DiskSpaceImport {
     stagingDirectory,
 
     async readRecord(): Promise<CanvasFile | null> {
-      for (const name of BUNDLE_RECORD_FILENAMES) {
+      for (const name of bundleRecordFilenames()) {
         const candidate = path.join(stagingDirectory, name);
         if (!existsSync(candidate)) continue;
         return JSON.parse(await readFile(candidate, 'utf8')) as CanvasFile;
@@ -102,7 +111,7 @@ export function stageDiskSpaceImport(canvasId: string): DiskSpaceImport {
         path.join(stagingDirectory, SPACE_JSON_FILENAME),
         JSON.stringify({ ...record, canvasId, title }),
       );
-      for (const name of BUNDLE_RECORD_FILENAMES) {
+      for (const name of bundleRecordFilenames()) {
         if (name === SPACE_JSON_FILENAME) continue;
         await rm(path.join(stagingDirectory, name), { force: true });
       }
diff --git a/apps/server/src/modules/storage/ports/structured.ts b/apps/server/src/modules/storage/ports/structured.ts
index 099988725..905715473 100644
--- a/apps/server/src/modules/storage/ports/structured.ts
+++ b/apps/server/src/modules/storage/ports/structured.ts
@@ -461,7 +461,17 @@ export type NodeDeleteResult = 'deleted' | 'absent';
  * content revision. Label allocation is a domain behavior: a non-strict put
  * may return a de-duplicated persisted label, while a strict put reports a
  * `label-conflict`. The contract intentionally says nothing about filenames
- * or physical layout. Environmental and malformed-record failures reject.
+ * or physical layout.
+ *
+ * Every read is **strict about retrievability and lenient about content**. A
+ * record that exists but cannot be produced is an environmental failure and
+ * rejects — never absence, and never a silently shorter collection. A record
+ * whose stored content is malformed is recovered rather than refused, because
+ * on a backend that keeps records in files a user can damage one by hand, and
+ * a record no read will produce cannot be repaired through the routes that
+ * exist to repair it. The two rules hold identically on {@link SpaceNodes.read},
+ * {@link SpaceNodes.readMany}, {@link SpaceNodes.list}, and
+ * {@link SpaceNodes.stream}.
  *
  * Two mutation outcomes are **adapter-shaped** and optional:
  *
@@ -508,13 +518,14 @@ export interface SpaceNodes {
    * 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.
+   * Answers about exactly the nodes {@link read} would, under the same two
+   * rules the interface states: a record that cannot be retrieved rejects the
+   * scan, and a record whose content is malformed is recovered. Dropping the
+   * unretrievable member instead — serving the rest of the collection — was
+   * considered and rejected: it would leave this port promising that
+   * environmental failures reject while its two collection shapes reported
+   * absence, and no caller could then tell a Space that lost a node from one
+   * it merely cannot read right now.
    */
   list(): Promise<Map<string, NodeSnapshot>>;
   /**

From a997544a41b0bbf112a2f8b8b4d79b35b5632903 Mon Sep 17 00:00:00 2001
From: Yuge Zhang <scottyugochang@gmail.com>
Date: Thu, 27 Aug 2026 18:27:00 +0800
Subject: [PATCH 9/9] fix(server): correct backend-agnostic read regressions

---
 .../agent/conversation/envelope.test.ts       |  80 +++++
 .../modules/agent/conversation/envelope.ts    |  15 +-
 .../src/modules/agent/tools/executor.ts       |  59 +++-
 .../agent/tools/world-target-read.test.ts     |  86 +++++-
 .../server/src/modules/canvas/canvas.route.ts |  10 +-
 .../modules/canvas/import-node-src.test.ts    |  56 +++-
 .../src/modules/canvas/import-node-src.ts     |  23 +-
 .../canvas/world-reference-resolver.test.ts   | 110 ++++++-
 .../canvas/world-reference-resolver.ts        | 275 +++++++++---------
 .../interactive-view.route.ts                 |   3 +-
 10 files changed, 539 insertions(+), 178 deletions(-)
 create mode 100644 apps/server/src/modules/agent/conversation/envelope.test.ts

diff --git a/apps/server/src/modules/agent/conversation/envelope.test.ts b/apps/server/src/modules/agent/conversation/envelope.test.ts
new file mode 100644
index 000000000..e13946f6b
--- /dev/null
+++ b/apps/server/src/modules/agent/conversation/envelope.test.ts
@@ -0,0 +1,80 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const readMany = vi.hoisted(() => vi.fn());
+
+vi.mock('../../storage/index.js', () => ({
+  space: () => ({
+    nodes: {
+      readMany,
+      read: vi.fn(),
+    },
+  }),
+}));
+
+import { buildChatEnvelope } from './envelope.js';
+
+import type { NodeContent, NodeSnapshot } from '../../storage/index.js';
+import type { FastifyBaseLogger } from 'fastify';
+
+const logger = {
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+} as unknown as FastifyBaseLogger;
+
+function snapshot(nodeId: string, content: string): NodeSnapshot {
+  return {
+    record: {
+      nodeId,
+      type: 'note',
+      label: `Label ${nodeId}`,
+      content,
+    } as NodeContent,
+    revision: `revision-${nodeId}`,
+  };
+}
+
+describe('buildChatEnvelope selection records', () => {
+  beforeEach(() => {
+    readMany.mockReset();
+    readMany.mockImplementation(async (nodeIds: readonly string[]) => {
+      const available = new Map<string, NodeSnapshot>([
+        ['frame-1', snapshot('frame-1', 'Frame body')],
+        ['child-1', snapshot('child-1', 'Child body')],
+      ]);
+      return new Map(
+        nodeIds.flatMap((nodeId) => {
+          const record = available.get(nodeId);
+          return record ? [[nodeId, record] as const] : [];
+        }),
+      );
+    });
+  });
+
+  it('enriches recursively included frame children from their records', async () => {
+    const envelope = await buildChatEnvelope({
+      content: 'Review this frame',
+      attachments: [],
+      selectedNodes: [
+        {
+          id: 'frame-1',
+          type: 'frame',
+          children: [{ id: 'child-1', type: 'note' }],
+        },
+      ],
+      canvasId: 'canvas-1',
+      logger,
+    });
+
+    expect(readMany).toHaveBeenCalledWith(['frame-1', 'child-1']);
+    expect(envelope.focus.selection.refs).toEqual([
+      expect.objectContaining({ id: 'frame-1', preview: 'Frame body' }),
+      expect.objectContaining({ id: 'child-1', preview: 'Child body' }),
+    ]);
+    expect(envelope.focus.selection.selectedIds).toEqual(['frame-1']);
+  });
+});
diff --git a/apps/server/src/modules/agent/conversation/envelope.ts b/apps/server/src/modules/agent/conversation/envelope.ts
index be7242aeb..f0bc00841 100644
--- a/apps/server/src/modules/agent/conversation/envelope.ts
+++ b/apps/server/src/modules/agent/conversation/envelope.ts
@@ -217,7 +217,7 @@ async function collectSelectedNodeRefs(
   if (canvasId) {
     try {
       records = await space(canvasId).nodes.readMany(
-        collectSelectedNodeIds(nodes),
+        collectSelectionNodeIds(nodes),
       );
     } catch {
       /* Space unreadable — refs stay bare. */
@@ -249,6 +249,19 @@ async function collectSelectedNodeRefs(
   return refs;
 }
 
+/** Collect every node represented by the recursive selection wire. */
+function collectSelectionNodeIds(nodes: WireSelectionNode[]): string[] {
+  const seen = new Set<string>();
+  const walk = (list: WireSelectionNode[]) => {
+    for (const node of list) {
+      seen.add(node.id);
+      if (node.children) walk(node.children);
+    }
+  };
+  walk(nodes);
+  return [...seen];
+}
+
 /**
  * Collect the ids the user **explicitly selected** (top-level only —
  * frame children are intentionally skipped).
diff --git a/apps/server/src/modules/agent/tools/executor.ts b/apps/server/src/modules/agent/tools/executor.ts
index f63d6c75e..95c1d0e60 100644
--- a/apps/server/src/modules/agent/tools/executor.ts
+++ b/apps/server/src/modules/agent/tools/executor.ts
@@ -65,6 +65,7 @@ import {
 } from './handlers/task.js';
 import { handleWebSearch, type WebSearchArgs } from './handlers/web-search.js';
 import { resolveWorldReadCanvasId } from '../../canvas/world-target-access.js';
+import { acquireWorkspaceOperationLease } from '../../workspace.js';
 
 import type { AgentToolResult } from '@earendil-works/pi-agent-core';
 import type { NodeOrigin } from '@huabu/shared';
@@ -134,42 +135,72 @@ export async function executeTool(
       canvasId: await resolveWorldReadCanvasId(ownerCanvasId, requested),
     } as unknown as T;
   };
+  const withStableWorkspace = async <T>(
+    operation: () => T | Promise<T>,
+  ): Promise<T> => {
+    // Cross-Space read authorization and the handler that consumes it are one
+    // operation. The resolver cannot release the Workspace before the handler
+    // runs without reopening a switch window between the check and the read.
+    const lease = acquireWorkspaceOperationLease();
+    try {
+      return await operation();
+    } finally {
+      lease.release();
+    }
+  };
 
   switch (name) {
     case 'web_search':
       return handleWebSearch(args as WebSearchArgs);
 
     case 'get_space_outline':
-      return handleGetCanvasOutline(
-        await withReadCanvasId<GetCanvasOutlineArgs>(args, 'get_space_outline'),
+      return withStableWorkspace(async () =>
+        handleGetCanvasOutline(
+          await withReadCanvasId<GetCanvasOutlineArgs>(
+            args,
+            'get_space_outline',
+          ),
+        ),
       );
 
     case 'inspect_nodes':
-      return handleInspectNodes(
-        await withReadCanvasId<InspectNodesArgs>(args, 'inspect_nodes'),
+      return withStableWorkspace(async () =>
+        handleInspectNodes(
+          await withReadCanvasId<InspectNodesArgs>(args, 'inspect_nodes'),
+        ),
       );
 
     case 'inspect_edges':
-      return handleInspectEdges(
-        await withReadCanvasId<InspectEdgesArgs>(args, 'inspect_edges'),
+      return withStableWorkspace(async () =>
+        handleInspectEdges(
+          await withReadCanvasId<InspectEdgesArgs>(args, 'inspect_edges'),
+        ),
       );
 
     case 'grep':
-      return handleGrep(await withReadCanvasId<GrepArgs>(args, 'grep'));
+      return withStableWorkspace(async () =>
+        handleGrep(await withReadCanvasId<GrepArgs>(args, 'grep')),
+      );
 
     case 'find':
-      return handleFind(await withReadCanvasId<FindArgs>(args, 'find'));
+      return withStableWorkspace(async () =>
+        handleFind(await withReadCanvasId<FindArgs>(args, 'find')),
+      );
 
     case 'ls':
-      return handleLs(await withReadCanvasId<LsArgs>(args, 'ls'));
+      return withStableWorkspace(async () =>
+        handleLs(await withReadCanvasId<LsArgs>(args, 'ls')),
+      );
 
     case 'read': {
       const ownerCanvasId = requireCanvasId('read');
-      const readArgs = await withReadCanvasId<ReadArgs>(args, 'read');
-      return handleRead(
-        readArgs,
-        readArgs.canvasId === ownerCanvasId ? context?.readSet : undefined,
-      );
+      return withStableWorkspace(async () => {
+        const readArgs = await withReadCanvasId<ReadArgs>(args, 'read');
+        return handleRead(
+          readArgs,
+          readArgs.canvasId === ownerCanvasId ? context?.readSet : undefined,
+        );
+      });
     }
 
     case 'space_commands':
diff --git a/apps/server/src/modules/agent/tools/world-target-read.test.ts b/apps/server/src/modules/agent/tools/world-target-read.test.ts
index ce4995afc..bd7a6eff7 100644
--- a/apps/server/src/modules/agent/tools/world-target-read.test.ts
+++ b/apps/server/src/modules/agent/tools/world-target-read.test.ts
@@ -7,21 +7,35 @@ import path from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-const workspaceState = vi.hoisted(() => ({ path: '' }));
+const workspaceState = vi.hoisted(() => ({ path: '', leases: 0 }));
 
 vi.mock('../../workspace.js', () => ({
   getWorkspacePath: () => workspaceState.path,
+  acquireWorkspaceOperationLease: () => {
+    const workspacePath = workspaceState.path;
+    workspaceState.leases += 1;
+    let released = false;
+    return {
+      workspacePath,
+      release: () => {
+        if (released) return;
+        released = true;
+        workspaceState.leases -= 1;
+      },
+    };
+  },
 }));
 
 import { executeTool } from './executor.js';
 import { refreshCanvasDirIndex } from '../../storage/canvas-dirs.js';
 
-function writeCanvas(
+function writeCanvasAt(
+  workspacePath: string,
   directory: string,
   canvasId: string,
   nodes: unknown[],
 ): void {
-  const root = path.join(workspaceState.path, directory);
+  const root = path.join(workspacePath, directory);
   mkdirSync(root, { recursive: true });
   writeFileSync(
     path.join(root, 'space.json'),
@@ -37,10 +51,27 @@ function writeCanvas(
   );
 }
 
+function writeCanvas(
+  directory: string,
+  canvasId: string,
+  nodes: unknown[],
+): void {
+  writeCanvasAt(workspaceState.path, directory, canvasId, nodes);
+}
+
+function switchWorkspace(nextPath: string): void {
+  if (workspaceState.leases > 0) {
+    throw new Error('Workspace operation in progress');
+  }
+  workspaceState.path = nextPath;
+  refreshCanvasDirIndex();
+}
+
 beforeEach(() => {
   workspaceState.path = mkdtempSync(
     path.join(tmpdir(), 'huabu-world-target-read-'),
   );
+  workspaceState.leases = 0;
   writeCanvas('.world', 'canvas-world', [
     {
       id: 'node-portal',
@@ -126,4 +157,53 @@ describe('World target reads', () => {
       ),
     ).rejects.toThrow();
   });
+
+  it('keeps portal authorization and the target read in one Workspace', async () => {
+    const originalWorkspace = workspaceState.path;
+    const otherWorkspace = mkdtempSync(
+      path.join(tmpdir(), 'huabu-world-target-read-other-'),
+    );
+    writeCanvasAt(otherWorkspace, '.world', 'canvas-world', [
+      {
+        id: 'node-portal',
+        type: 'canvasRef',
+        position: { x: 0, y: 0 },
+        data: { targetCanvasId: 'canvas-a' },
+      },
+    ]);
+    writeCanvasAt(otherWorkspace, 'Other Project', 'canvas-a', [
+      {
+        id: 'node-other',
+        type: 'note',
+        position: { x: 0, y: 0 },
+        data: {},
+      },
+    ]);
+
+    let switchError: unknown;
+    queueMicrotask(() => {
+      try {
+        switchWorkspace(otherWorkspace);
+      } catch (error) {
+        switchError = error;
+      }
+    });
+
+    try {
+      const result = JSON.parse(
+        (await executeTool(
+          'get_space_outline',
+          { targetCanvasId: 'canvas-a' },
+          { canvasId: 'canvas-world' },
+        )) as string,
+      ) as { nodes: Array<{ id: string }> };
+
+      expect(switchError).toBeInstanceOf(Error);
+      expect(workspaceState.path).toBe(originalWorkspace);
+      expect(result.nodes.map((node) => node.id)).toEqual(['node-source']);
+    } finally {
+      workspaceState.path = originalWorkspace;
+      rmSync(otherWorkspace, { recursive: true, force: true });
+    }
+  });
 });
diff --git a/apps/server/src/modules/canvas/canvas.route.ts b/apps/server/src/modules/canvas/canvas.route.ts
index 94d542c9c..4dd1b1324 100644
--- a/apps/server/src/modules/canvas/canvas.route.ts
+++ b/apps/server/src/modules/canvas/canvas.route.ts
@@ -1571,12 +1571,13 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     Reply: ApiResult<RevealNodesFolderResponse>;
   }>('/:canvasId/reveal-nodes', async function (request, reply) {
     const { canvasId } = request.params;
-    if (!(await space(canvasId).read())) {
+    const handle = space(canvasId);
+    if (!(await handle.read())) {
       return reply.code(404).send({ message: 'Canvas not found' });
     }
     // 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();
+    const dir = handle.diskTree?.nodesDirectory();
     if (dir === undefined || !existsSync(dir)) {
       return reply.code(404).send({ message: 'Nodes folder not found' });
     }
@@ -1606,7 +1607,8 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     }
     const includeHistory = parsedQuery.data.includeHistory !== 'false';
 
-    const canvas = await space(canvasId).read();
+    const handle = space(canvasId);
+    const canvas = await handle.read();
     if (!canvas) {
       return reply.code(404).send({ message: 'Canvas not found' });
     }
@@ -1614,7 +1616,7 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => {
     // 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 tree = handle.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/import-node-src.test.ts b/apps/server/src/modules/canvas/import-node-src.test.ts
index 5df3b819b..5dc22e475 100644
--- a/apps/server/src/modules/canvas/import-node-src.test.ts
+++ b/apps/server/src/modules/canvas/import-node-src.test.ts
@@ -43,6 +43,7 @@ beforeEach(() => {
     'c-web-remote',
     'c-web-data',
     'c-web-merge-local',
+    'c-web-merge-multiple',
     'c-web-merge-remote',
     'c-image-local',
     'c-image-reentered',
@@ -82,19 +83,25 @@ function firstPatchedSrc(commands: CanvasCommand[]): string | undefined {
 
 /** Seed a Space with one existing web node for merge-path tests. */
 function seedWebNode(canvasId: string, nodeId: string, src: string): void {
+  seedWebNodes(canvasId, [{ nodeId, src }]);
+}
+
+/** Seed a Space with existing web nodes for merge-path tests. */
+function seedWebNodes(
+  canvasId: string,
+  nodes: readonly { nodeId: string; src: string }[],
+): void {
   getCanvasStore(canvasId).write({
     canvasId,
     title: null,
     version: 1,
     state: {
-      nodes: [
-        {
-          id: nodeId,
-          type: 'web',
-          position: { x: 0, y: 0 },
-          data: { label: 'Existing page', src },
-        },
-      ],
+      nodes: nodes.map(({ nodeId, src }) => ({
+        id: nodeId,
+        type: 'web',
+        position: { x: 0, y: 0 },
+        data: { label: 'Existing page', src },
+      })),
       edges: [],
     },
     createdAt: Date.now(),
@@ -244,6 +251,39 @@ describe('importForeignNodeSources — web nodes', () => {
 
     expect(firstPatchedSrc(out)).toBe(remote);
   });
+
+  it('normalizes every entry in a multi-node MERGE_NODE_DATA command', async () => {
+    const canvasId = 'c-web-merge-multiple';
+    const firstNodeId = 'node-web-merge-first';
+    const secondNodeId = 'node-web-merge-second';
+    seedWebNodes(canvasId, [
+      { nodeId: firstNodeId, src: 'https://example.com/first' },
+      { nodeId: secondNodeId, src: 'https://example.com/second' },
+    ]);
+    const firstUpload = stageUpload(canvasId, 'first.html', '<p>first</p>');
+    const secondUpload = stageUpload(canvasId, 'second.html', '<p>second</p>');
+
+    const out = await importForeignNodeSources(canvasId, [
+      {
+        type: 'MERGE_NODE_DATA',
+        patches: [
+          { nodeId: firstNodeId, patch: { src: 'upload/first.html' } },
+          { nodeId: secondNodeId, patch: { src: 'upload/second.html' } },
+        ],
+      },
+    ]);
+    const command = out[0];
+    if (command?.type !== 'MERGE_NODE_DATA') {
+      throw new Error('Expected MERGE_NODE_DATA output');
+    }
+
+    expect(command.patches.map((entry) => entry.patch.src)).toEqual([
+      expect.stringMatching(/^artifact-[^/]+\.html$/),
+      expect.stringMatching(/^artifact-[^/]+\.html$/),
+    ]);
+    expect(existsSync(firstUpload)).toBe(false);
+    expect(existsSync(secondUpload)).toBe(false);
+  });
 });
 
 describe('importForeignNodeSources — media nodes (regression)', () => {
diff --git a/apps/server/src/modules/canvas/import-node-src.ts b/apps/server/src/modules/canvas/import-node-src.ts
index 9a33d14f9..b51faebaa 100644
--- a/apps/server/src/modules/canvas/import-node-src.ts
+++ b/apps/server/src/modules/canvas/import-node-src.ts
@@ -141,19 +141,22 @@ export async function importForeignNodeSources(
   // Lazily built nodeId → nodeType map, needed only to gate MERGE_NODE_DATA
   // 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;
+  let typeByIdPromise: Promise<Map<string, string>> | null = null;
   const nodeType = async (nodeId: string): Promise<string> => {
-    if (!typeById) {
-      typeById = new Map();
-      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') {
-          typeById.set(n.id, n.type);
+    if (!typeByIdPromise) {
+      typeByIdPromise = (async () => {
+        const byId = new Map<string, string>();
+        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') {
+            byId.set(n.id, n.type);
+          }
         }
-      }
+        return byId;
+      })();
     }
-    return typeById.get(nodeId) ?? '';
+    return (await typeByIdPromise).get(nodeId) ?? '';
   };
 
   const out: 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 10ce2b9c5..277f0b86e 100644
--- a/apps/server/src/modules/canvas/world-reference-resolver.test.ts
+++ b/apps/server/src/modules/canvas/world-reference-resolver.test.ts
@@ -7,10 +7,23 @@ import path from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-const workspaceState = vi.hoisted(() => ({ path: '' }));
+const workspaceState = vi.hoisted(() => ({ path: '', leases: 0 }));
 
 vi.mock('../workspace.js', () => ({
   getWorkspacePath: () => workspaceState.path,
+  acquireWorkspaceOperationLease: () => {
+    const workspacePath = workspaceState.path;
+    workspaceState.leases += 1;
+    let released = false;
+    return {
+      workspacePath,
+      release: () => {
+        if (released) return;
+        released = true;
+        workspaceState.leases -= 1;
+      },
+    };
+  },
 }));
 
 import {
@@ -19,12 +32,13 @@ import {
 } from './world-reference-resolver.js';
 import { refreshCanvasDirIndex } from '../storage/canvas-dirs.js';
 
-function writeCanvas(
+function writeCanvasAt(
+  workspacePath: string,
   directory: string,
   canvasId: string,
   nodes: unknown[],
 ): string {
-  const root = path.join(workspaceState.path, directory);
+  const root = path.join(workspacePath, directory);
   mkdirSync(root, { recursive: true });
   writeFileSync(
     path.join(root, 'space.json'),
@@ -41,10 +55,27 @@ function writeCanvas(
   return root;
 }
 
+function writeCanvas(
+  directory: string,
+  canvasId: string,
+  nodes: unknown[],
+): string {
+  return writeCanvasAt(workspaceState.path, directory, canvasId, nodes);
+}
+
+function switchWorkspace(nextPath: string): void {
+  if (workspaceState.leases > 0) {
+    throw new Error('Workspace operation in progress');
+  }
+  workspaceState.path = nextPath;
+  refreshCanvasDirIndex();
+}
+
 beforeEach(() => {
   workspaceState.path = mkdtempSync(
     path.join(tmpdir(), 'huabu-world-references-'),
   );
+  workspaceState.leases = 0;
   writeCanvas('.world', 'canvas-world', [
     {
       id: 'node-portal-a',
@@ -255,4 +286,77 @@ describe('World reference resolution', () => {
     );
     expect(resolved?.status).toBe('ok');
   });
+
+  it('keeps World authorization and referenced records in one Workspace', async () => {
+    const originalWorkspace = workspaceState.path;
+    const otherWorkspace = mkdtempSync(
+      path.join(tmpdir(), 'huabu-world-references-other-'),
+    );
+    writeCanvasAt(otherWorkspace, '.world', 'canvas-world', [
+      {
+        id: 'node-portal-a',
+        type: 'canvasRef',
+        position: { x: 0, y: 0 },
+        data: { targetCanvasId: 'canvas-a' },
+      },
+      {
+        id: 'node-ref-ok',
+        type: 'nodeRef',
+        position: { x: 0, y: 0 },
+        data: { target: { canvasId: 'canvas-a', nodeId: 'node-source' } },
+      },
+    ]);
+    const otherSource = writeCanvasAt(
+      otherWorkspace,
+      'Other Project',
+      'canvas-a',
+      [
+        {
+          id: 'node-source',
+          type: 'note',
+          position: { x: 0, y: 0 },
+          data: {},
+        },
+      ],
+    );
+    mkdirSync(path.join(otherSource, 'nodes'));
+    writeFileSync(
+      path.join(otherSource, 'nodes', 'Other note.md'),
+      [
+        '---',
+        'id: node-source',
+        'type: note',
+        'label: Other note',
+        '---',
+        'Other body',
+      ].join('\n'),
+      'utf8',
+    );
+
+    let switchError: unknown;
+    queueMicrotask(() => {
+      try {
+        switchWorkspace(otherWorkspace);
+      } catch (error) {
+        switchError = error;
+      }
+    });
+
+    try {
+      const response = await resolveWorldReferences('canvas-world');
+      const resolved = response.references.find(
+        (reference) => reference.referenceNodeId === 'node-ref-ok',
+      );
+
+      expect(switchError).toBeInstanceOf(Error);
+      expect(workspaceState.path).toBe(originalWorkspace);
+      expect(resolved).toMatchObject({
+        status: 'ok',
+        source: { label: 'Source note', preview: 'Source body' },
+      });
+    } finally {
+      workspaceState.path = originalWorkspace;
+      rmSync(otherWorkspace, { recursive: true, force: true });
+    }
+  });
 });
diff --git a/apps/server/src/modules/canvas/world-reference-resolver.ts b/apps/server/src/modules/canvas/world-reference-resolver.ts
index 75d9b86d7..0b33ba510 100644
--- a/apps/server/src/modules/canvas/world-reference-resolver.ts
+++ b/apps/server/src/modules/canvas/world-reference-resolver.ts
@@ -6,6 +6,7 @@ import { agentBindingSchema, getQuestionNodeStatus } from '@huabu/shared';
 import { describeNode } from './node-prompt.js';
 import { readWorldTargetCanvasesStrict } from './world-target-access.js';
 import { getStructuredStore, space } from '../storage/index.js';
+import { acquireWorkspaceOperationLease } from '../workspace.js';
 
 import type { CanvasFile, NodeContent } from '../storage/index.js';
 import type {
@@ -36,98 +37,126 @@ interface SourceCanvas {
 export async function resolveWorldReferences(
   worldCanvasId: string,
 ): Promise<GetWorldReferencesResponse> {
-  if (worldCanvasId !== (await getStructuredStore().spaces().worldId())) {
-    throw new WorldReferenceResolutionError(
-      'References can be resolved only for the World Canvas',
-    );
-  }
-  const world = await space(worldCanvasId).read();
-  if (!world) {
-    throw new WorldReferenceResolutionError('World Canvas is not readable');
-  }
+  const workspaceLease = acquireWorkspaceOperationLease();
+  try {
+    if (worldCanvasId !== (await getStructuredStore().spaces().worldId())) {
+      throw new WorldReferenceResolutionError(
+        'References can be resolved only for the World Canvas',
+      );
+    }
+    const world = await space(worldCanvasId).read();
+    if (!world) {
+      throw new WorldReferenceResolutionError('World Canvas is not readable');
+    }
 
-  const nodes = world.state.nodes as StoredNode[];
-  const sourceCanvasIds = new Set<string>();
-  for (const node of nodes) {
-    if (node.type === 'canvasRef') {
-      const targetCanvasId = node.data?.targetCanvasId;
-      if (typeof targetCanvasId !== 'string') {
-        throw new WorldReferenceResolutionError(
-          `Portal ${node.id} has no valid targetCanvasId`,
-        );
-      }
-      sourceCanvasIds.add(targetCanvasId);
-    } else if (node.type === 'nodeRef' || node.type === 'frameRef') {
-      const target = node.data?.target as Record<string, unknown> | undefined;
-      if (
-        typeof target?.canvasId !== 'string' ||
-        typeof target.nodeId !== 'string'
-      ) {
-        throw new WorldReferenceResolutionError(
-          `Node reference ${node.id} has no valid target`,
-        );
+    const nodes = world.state.nodes as StoredNode[];
+    const sourceCanvasIds = new Set<string>();
+    for (const node of nodes) {
+      if (node.type === 'canvasRef') {
+        const targetCanvasId = node.data?.targetCanvasId;
+        if (typeof targetCanvasId !== 'string') {
+          throw new WorldReferenceResolutionError(
+            `Portal ${node.id} has no valid targetCanvasId`,
+          );
+        }
+        sourceCanvasIds.add(targetCanvasId);
+      } else if (node.type === 'nodeRef' || node.type === 'frameRef') {
+        const target = node.data?.target as Record<string, unknown> | undefined;
+        if (
+          typeof target?.canvasId !== 'string' ||
+          typeof target.nodeId !== 'string'
+        ) {
+          throw new WorldReferenceResolutionError(
+            `Node reference ${node.id} has no valid target`,
+          );
+        }
+        sourceCanvasIds.add(target.canvasId);
       }
-      sourceCanvasIds.add(target.canvasId);
     }
-  }
 
-  const sources = new Map<string, SourceCanvas>();
-  const sourceCanvases = await readWorldTargetCanvasesStrict(sourceCanvasIds);
-  await Promise.all(
-    [...sourceCanvasIds].map(async (canvasId) => {
-      const canvas = sourceCanvases.get(canvasId) ?? null;
-      if (!canvas) {
-        sources.set(canvasId, { canvas: null });
-        return;
+    const sources = new Map<string, SourceCanvas>();
+    const sourceCanvases = await readWorldTargetCanvasesStrict(sourceCanvasIds);
+    await Promise.all(
+      [...sourceCanvasIds].map(async (canvasId) => {
+        const canvas = sourceCanvases.get(canvasId) ?? null;
+        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 });
+      }),
+    );
+
+    const references: ResolvedWorldReference[] = [];
+    for (const node of nodes) {
+      if (node.type === 'canvasRef') {
+        const targetCanvasId = node.data?.targetCanvasId as string;
+        const canvas = sources.get(targetCanvasId)?.canvas;
+        references.push({
+          kind: 'canvasRef',
+          referenceNodeId: node.id as `node-${string}`,
+          targetCanvasId: targetCanvasId as `canvas-${string}`,
+          status: canvas ? 'ok' : 'canvas-missing',
+          ...(canvas ? { title: canvas.title } : {}),
+        });
+        continue;
       }
-      // 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);
+      if (node.type !== 'nodeRef' && node.type !== 'frameRef') continue;
+
+      const target = node.data?.target as { canvasId: string; nodeId: string };
+      const kind = node.type;
+      const source = sources.get(target.canvasId);
+      if (!source?.canvas) {
+        references.push({
+          kind,
+          referenceNodeId: node.id as `node-${string}`,
+          target: {
+            canvasId: target.canvasId as `canvas-${string}`,
+            nodeId: target.nodeId as `node-${string}`,
+          },
+          status: 'canvas-missing',
+        });
+        continue;
       }
-      sources.set(canvasId, { canvas, content });
-    }),
-  );
 
-  const references: ResolvedWorldReference[] = [];
-  for (const node of nodes) {
-    if (node.type === 'canvasRef') {
-      const targetCanvasId = node.data?.targetCanvasId as string;
-      const canvas = sources.get(targetCanvasId)?.canvas;
-      references.push({
-        kind: 'canvasRef',
-        referenceNodeId: node.id as `node-${string}`,
-        targetCanvasId: targetCanvasId as `canvas-${string}`,
-        status: canvas ? 'ok' : 'canvas-missing',
-        ...(canvas ? { title: canvas.title } : {}),
-      });
-      continue;
-    }
-    if (node.type !== 'nodeRef' && node.type !== 'frameRef') continue;
+      const sourceNode = (source.canvas.state.nodes as StoredNode[]).find(
+        (candidate) => candidate.id === target.nodeId,
+      );
+      if (!sourceNode) {
+        references.push({
+          kind,
+          referenceNodeId: node.id as `node-${string}`,
+          target: {
+            canvasId: target.canvasId as `canvas-${string}`,
+            nodeId: target.nodeId as `node-${string}`,
+          },
+          status: 'node-missing',
+        });
+        continue;
+      }
 
-    const target = node.data?.target as { canvasId: string; nodeId: string };
-    const kind = node.type;
-    const source = sources.get(target.canvasId);
-    if (!source?.canvas) {
-      references.push({
-        kind,
-        referenceNodeId: node.id as `node-${string}`,
-        target: {
-          canvasId: target.canvasId as `canvas-${string}`,
-          nodeId: target.nodeId as `node-${string}`,
+      const sourceContent = source.content?.get(target.nodeId) ?? null;
+      const resolved = describeNode(
+        {
+          id: target.nodeId,
+          type: sourceNode.type as CanvasNodeType,
         },
-        status: 'canvas-missing',
-      });
-      continue;
-    }
-
-    const sourceNode = (source.canvas.state.nodes as StoredNode[]).find(
-      (candidate) => candidate.id === target.nodeId,
-    );
-    if (!sourceNode) {
+        'preview',
+        sourceContent,
+      );
+      const sourceData = sourceNode.data ?? {};
+      const agentBinding =
+        sourceNode.type === 'question'
+          ? agentBindingSchema.safeParse(sourceData.agentBinding)
+          : null;
       references.push({
         kind,
         referenceNodeId: node.id as `node-${string}`,
@@ -135,59 +164,37 @@ export async function resolveWorldReferences(
           canvasId: target.canvasId as `canvas-${string}`,
           nodeId: target.nodeId as `node-${string}`,
         },
-        status: 'node-missing',
+        status: 'ok',
+        source: {
+          type: resolved.type,
+          ...(resolved.label ? { label: resolved.label } : {}),
+          ...(resolved.summary ? { summary: resolved.summary } : {}),
+          ...(resolved.preview ? { preview: resolved.preview } : {}),
+          ...(resolved.rev ? { rev: resolved.rev } : {}),
+          ...(sourceNode.type === 'question'
+            ? {
+                ...(typeof sourceData.threadId === 'string' &&
+                sourceData.threadId.length > 0
+                  ? { threadId: sourceData.threadId }
+                  : {}),
+                status: getQuestionNodeStatus(sourceData),
+                viewed: sourceData.viewed === true,
+                agentMode:
+                  sourceData.agentMode === 'operate' ? 'operate' : 'ask',
+                agentBinding: agentBinding?.success
+                  ? agentBinding.data
+                  : { kind: 'internal' },
+                hasAuthoredContent:
+                  typeof sourceContent?.content === 'string' &&
+                  sourceContent.content.trim().length > 0,
+              }
+            : {}),
+        },
       });
-      continue;
     }
 
-    const sourceContent = source.content?.get(target.nodeId) ?? null;
-    const resolved = describeNode(
-      {
-        id: target.nodeId,
-        type: sourceNode.type as CanvasNodeType,
-      },
-      'preview',
-      sourceContent,
-    );
-    const sourceData = sourceNode.data ?? {};
-    const agentBinding =
-      sourceNode.type === 'question'
-        ? agentBindingSchema.safeParse(sourceData.agentBinding)
-        : null;
-    references.push({
-      kind,
-      referenceNodeId: node.id as `node-${string}`,
-      target: {
-        canvasId: target.canvasId as `canvas-${string}`,
-        nodeId: target.nodeId as `node-${string}`,
-      },
-      status: 'ok',
-      source: {
-        type: resolved.type,
-        ...(resolved.label ? { label: resolved.label } : {}),
-        ...(resolved.summary ? { summary: resolved.summary } : {}),
-        ...(resolved.preview ? { preview: resolved.preview } : {}),
-        ...(resolved.rev ? { rev: resolved.rev } : {}),
-        ...(sourceNode.type === 'question'
-          ? {
-              ...(typeof sourceData.threadId === 'string' &&
-              sourceData.threadId.length > 0
-                ? { threadId: sourceData.threadId }
-                : {}),
-              status: getQuestionNodeStatus(sourceData),
-              viewed: sourceData.viewed === true,
-              agentMode: sourceData.agentMode === 'operate' ? 'operate' : 'ask',
-              agentBinding: agentBinding?.success
-                ? agentBinding.data
-                : { kind: 'internal' },
-              hasAuthoredContent:
-                typeof sourceContent?.content === 'string' &&
-                sourceContent.content.trim().length > 0,
-            }
-          : {}),
-      },
-    });
+    return { references };
+  } finally {
+    workspaceLease.release();
   }
-
-  return { references };
 }
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..470daaf72 100644
--- a/apps/server/src/modules/interactive-view/interactive-view.route.ts
+++ b/apps/server/src/modules/interactive-view/interactive-view.route.ts
@@ -58,6 +58,7 @@ const interactiveViewRoutes: FastifyPluginAsync = async (app) => {
       });
     }
     try {
+      const blobs = space(params.data.canvasId).blobs;
       const resource = await interactiveViewService.get(
         params.data.canvasId,
         params.data.nodeId,
@@ -84,7 +85,7 @@ const interactiveViewRoutes: FastifyPluginAsync = async (app) => {
       const sent = await sendBlob(
         request,
         reply,
-        space(params.data.canvasId).blobs,
+        blobs,
         resource.rendererArtifact,
       );
       if (!sent) {