sh3-core 0.24.0 → 0.25.1

package/dist/registry/installer.test.js

@@ -0,0 +1,146 @@
+import 'fake-indexeddb/auto';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { resetFramework } from '../__test__/reset';
+import { makeApp, makeAppManifest, makeShard, makeShardManifest } from '../__test__/fixtures';
+import { installPackage, loadInstalledPackages } from './installer';
+import { savePackage } from './storage';
+import { registeredApps } from '../apps/registry.svelte';
+import { registeredShards } from '../shards/lifecycle.svelte';
+// Mock the network for loadInstalledPackages tests.
+vi.mock('../env/client', () => ({
+    fetchServerPackages: vi.fn(),
+}));
+import { fetchServerPackages } from '../env/client';
+async function wipeIndexedDB() {
+    await new Promise((resolve) => {
+        const req = indexedDB.deleteDatabase('sh3-packages');
+        req.onsuccess = () => resolve();
+        req.onerror = () => resolve();
+        req.onblocked = () => resolve();
+    });
+}
+function makeLoaded(parts = {}) {
+    var _a, _b;
+    return {
+        shards: ((_a = parts.shards) !== null && _a !== void 0 ? _a : []).map((id) => makeShard({ manifest: makeShardManifest({ id }) })),
+        apps: ((_b = parts.apps) !== null && _b !== void 0 ? _b : []).map((id) => makeApp({ manifest: makeAppManifest({ id }) })),
+    };
+}
+function meta(id, type, version) {
+    return { id, type, version, sourceRegistry: '', contractVersion: '1' };
+}
+function installedRecord(id, type, version) {
+    return {
+        id,
+        type,
+        version,
+        sourceRegistry: '',
+        contractVersion: '1',
+        installedAt: '2026-01-01T00:00:00.000Z',
+        permissions: [],
+    };
+}
+// ---------------------------------------------------------------------------
+// Bug A — installPackage must drop apps/shards the new bundle no longer ships
+// ---------------------------------------------------------------------------
+describe('installPackage — diff-based unregistration (Bug A)', () => {
+    beforeEach(async () => {
+        resetFramework();
+        await wipeIndexedDB();
+    });
+    it('unregisters apps from the previous bundle that the new bundle no longer ships', async () => {
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.0.0'), {
+            loaded: makeLoaded({ apps: ['bar', 'baz'] }),
+        });
+        expect(registeredApps.has('bar')).toBe(true);
+        expect(registeredApps.has('baz')).toBe(true);
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.1.0'), {
+            loaded: makeLoaded({ apps: ['bar'] }),
+        });
+        expect(registeredApps.has('bar')).toBe(true);
+        expect(registeredApps.has('baz')).toBe(false);
+    });
+    it('unregisters shards from the previous bundle that the new bundle no longer ships', async () => {
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.0.0'), {
+            loaded: makeLoaded({ shards: ['shard-a', 'shard-b'] }),
+        });
+        expect(registeredShards.has('shard-a')).toBe(true);
+        expect(registeredShards.has('shard-b')).toBe(true);
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.1.0'), {
+            loaded: makeLoaded({ shards: ['shard-a'] }),
+        });
+        expect(registeredShards.has('shard-a')).toBe(true);
+        expect(registeredShards.has('shard-b')).toBe(false);
+    });
+    it('preserves entries present in both old and new bundles', async () => {
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.0.0'), {
+            loaded: makeLoaded({ shards: ['s1'], apps: ['a1'] }),
+        });
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.1.0'), {
+            loaded: makeLoaded({ shards: ['s1'], apps: ['a1'] }),
+        });
+        expect(registeredShards.has('s1')).toBe(true);
+        expect(registeredApps.has('a1')).toBe(true);
+    });
+    it('does not touch unrelated packages on first install of a new package', async () => {
+        await installPackage(new ArrayBuffer(0), meta('pkg-other', 'app', '1.0.0'), {
+            loaded: makeLoaded({ apps: ['other-app'] }),
+        });
+        await installPackage(new ArrayBuffer(0), meta('pkg-new', 'app', '1.0.0'), {
+            loaded: makeLoaded({ apps: ['new-app'] }),
+        });
+        expect(registeredApps.has('other-app')).toBe(true);
+        expect(registeredApps.has('new-app')).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// Bug B — loadInstalledPackages must refetch when local version != server
+// ---------------------------------------------------------------------------
+describe('loadInstalledPackages — version reconciliation (Bug B)', () => {
+    beforeEach(async () => {
+        resetFramework();
+        await wipeIndexedDB();
+        vi.resetAllMocks();
+        // Global fetch — used by _fetchAndCacheFromServer.
+        globalThis.fetch = vi.fn();
+        // Silence expected warnings: empty-byte bundles can't be dynamic-imported
+        // in node, so loadBundleModule throws and the installer warns. The
+        // routing decision under test happens before that, so the warnings are
+        // noise we don't want polluting test output.
+        vi.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    it('refetches from server when local cached version differs from server version', async () => {
+        await savePackage('foo', new ArrayBuffer(0), installedRecord('foo', 'app', '1.0.0'));
+        fetchServerPackages.mockResolvedValue([
+            {
+                id: 'foo',
+                type: 'app',
+                version: '1.1.0',
+                bundleUrl: 'http://server.test/packages/foo/client.js',
+                sourceRegistry: '',
+                contractVersion: '1',
+            },
+        ]);
+        globalThis.fetch.mockResolvedValue({
+            ok: true,
+            arrayBuffer: async () => new ArrayBuffer(0),
+        });
+        await loadInstalledPackages();
+        expect(globalThis.fetch).toHaveBeenCalledWith('http://server.test/packages/foo/client.js');
+    });
+    it('uses local cache when local version matches server version', async () => {
+        await savePackage('foo', new ArrayBuffer(0), installedRecord('foo', 'app', '1.0.0'));
+        fetchServerPackages.mockResolvedValue([
+            {
+                id: 'foo',
+                type: 'app',
+                version: '1.0.0',
+                bundleUrl: 'http://server.test/packages/foo/client.js',
+                sourceRegistry: '',
+                contractVersion: '1',
+            },
+        ]);
+        await loadInstalledPackages();
+        expect(globalThis.fetch).not.toHaveBeenCalled();
+    });
+});

package/dist/registry/types.d.ts

@@ -183,6 +183,25 @@ export interface InstalledPackage {
      * must treat a missing value as `[]`.
      */
     permissions: string[];
+    /**
+     * Shard ids this package contributed at install time. Populated from
+     * `LoadedBundle.shards[].manifest.id`. Used at reinstall to diff against
+     * the new bundle and unregister shards the new version no longer ships.
+     *
+     * Optional for backwards compatibility with records written before this
+     * field existed. Treat a missing value as "unknown" — diffing is skipped
+     * for that record and the field is populated on the next install.
+     */
+    contributedShards?: string[];
+    /**
+     * App ids this package contributed at install time. Populated from
+     * `LoadedBundle.apps[].manifest.id`. Same diff-and-unregister role as
+     * `contributedShards`.
+     *
+     * Optional for backwards compatibility with records written before this
+     * field existed.
+     */
+    contributedApps?: string[];
 }
 /**
  * Result of an install operation.

package/dist/runtime/runVerb.test.js

@@ -175,4 +175,91 @@ describe('runVerbProgrammatic', () => {
         await runVerbProgrammatic('docs-probe-2', 'docs-probe-2:peek', []);
         expect(seenDocs).toBeUndefined();
     });
+    it('surfaces the verb return value as result', async () => {
+        registerShard({
+            manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'returnObj',
+                    summary: 'returns an object',
+                    programmatic: true,
+                    async run() {
+                        return { answer: 'ok', count: 3 };
+                    },
+                });
+            },
+        });
+        await activateShard('tester');
+        const out = await runVerbProgrammatic('tester', 'tester:returnObj', []);
+        expect(out.result).toEqual({ answer: 'ok', count: 3 });
+    });
+    it('surfaces a primitive verb return value as result', async () => {
+        registerShard({
+            manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'returnNumber',
+                    summary: 'returns 42',
+                    programmatic: true,
+                    schema: {
+                        input: { type: 'object' },
+                        output: { type: 'integer' },
+                    },
+                    async run() {
+                        return 42;
+                    },
+                });
+            },
+        });
+        await activateShard('tester');
+        const out = await runVerbProgrammatic('tester', 'tester:returnNumber', []);
+        expect(out.result).toBe(42);
+    });
+    it('surfaces undefined as result for a verb that returns nothing', async () => {
+        registerShard({
+            manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'returnVoid',
+                    summary: 'returns nothing',
+                    programmatic: true,
+                    async run() {
+                        // no return
+                    },
+                });
+            },
+        });
+        await activateShard('tester');
+        const out = await runVerbProgrammatic('tester', 'tester:returnVoid', []);
+        expect(out.result).toBeUndefined();
+    });
+    it('round-trips an sh3-document handle through result', async () => {
+        registerShard({
+            manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'returnDoc',
+                    summary: 'returns a document handle',
+                    programmatic: true,
+                    schema: {
+                        input: { type: 'object' },
+                        output: {
+                            type: 'object',
+                            format: 'sh3-document',
+                            properties: {
+                                shardId: { type: 'string' },
+                                path: { type: 'string' },
+                            },
+                        },
+                    },
+                    async run() {
+                        return { shardId: 'notes', path: 'inbox/today.md' };
+                    },
+                });
+            },
+        });
+        await activateShard('tester');
+        const out = await runVerbProgrammatic('tester', 'tester:returnDoc', []);
+        expect(out.result).toEqual({ shardId: 'notes', path: 'inbox/today.md' });
+    });
 });

package/dist/sh3core-shard/folderActions.d.ts

@@ -0,0 +1,15 @@
+import type { ShardContext } from '../shards/types';
+/** Build the docs path for a user-or-project tenant id. Pure. */
+export declare function buildDocumentsPath(root: string, tenantId: string, join: (...parts: string[]) => string): string;
+export declare function disabledForApp(g: {
+    isLocal: boolean;
+}): boolean;
+export declare function disabledForUser(g: {
+    isLocal: boolean;
+    userId: string | null;
+}): boolean;
+export declare function disabledForProject(g: {
+    isLocal: boolean;
+    projectId: string | null;
+}): boolean;
+export declare function registerFolderActions(ctx: ShardContext): () => void;

package/dist/sh3core-shard/folderActions.js

@@ -0,0 +1,109 @@
+/*
+ * Palette-only "Open X folder" actions for the Tauri desktop sidecar.
+ * All three actions are registered unconditionally; visibility is gated
+ * by per-frame `disabled` predicates so changes in project scope or auth
+ * state take effect without re-registration.
+ *
+ * Targets:
+ *   sh3.openAppDataFolder           → appDataDir()
+ *   sh3.openUserDocumentsFolder     → appDataDir()/server/docs/<userId>
+ *   sh3.openProjectDocumentsFolder  → appDataDir()/server/docs/<activeProjectId>
+ *
+ * The `server/docs/<tenant>` layout matches sh3-server's doc-store on
+ * disk (see packages/sh3-server/src/doc-store/store.ts). The Tauri
+ * sidecar passes `appDataDir()/server` as sh3-server's --data arg.
+ *
+ * The runner uses dynamic `import()` for `@tauri-apps/api/path` and
+ * `@tauri-apps/plugin-opener` so Vite code-splits the Tauri deps into
+ * a separate chunk that only loads when the action runs. Mirrors the
+ * pattern used by `platform/index.ts` and `sh3Api/window.ts`.
+ */
+import { isLocalTauriDesktop } from '../platform/localSidecar';
+import { getUser } from '../auth/auth.svelte';
+import { sessionState } from '../projects/session-state.svelte';
+import { toastManager } from '../overlays/toast';
+/** Build the docs path for a user-or-project tenant id. Pure. */
+export function buildDocumentsPath(root, tenantId, join) {
+    return join(root, 'server', 'docs', tenantId);
+}
+export function disabledForApp(g) {
+    return !g.isLocal;
+}
+export function disabledForUser(g) {
+    return !g.isLocal || g.userId == null;
+}
+export function disabledForProject(g) {
+    return !g.isLocal || g.projectId == null;
+}
+async function openFolder(kind) {
+    try {
+        const [{ appDataDir, join }, { openPath }] = await Promise.all([
+            import('@tauri-apps/api/path'),
+            import('@tauri-apps/plugin-opener'),
+        ]);
+        const root = await appDataDir();
+        let target = root;
+        if (kind === 'user') {
+            const u = getUser();
+            if (!u)
+                return;
+            target = await join(root, 'server', 'docs', u.id);
+        }
+        else if (kind === 'project') {
+            const id = sessionState.activeProjectId;
+            if (!id)
+                return;
+            target = await join(root, 'server', 'docs', id);
+        }
+        await openPath(target);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        toastManager.notify(`Couldn't open folder: ${msg}`, { level: 'error', duration: 4000 });
+    }
+}
+export function registerFolderActions(ctx) {
+    const actions = [
+        {
+            id: 'sh3.openAppDataFolder',
+            label: 'Open SH3 data folder',
+            scope: ['home', 'app'],
+            contextItem: false,
+            paletteItem: true,
+            group: 'folders',
+            disabled: () => disabledForApp({ isLocal: isLocalTauriDesktop() }),
+            run: (_ctx) => openFolder('app'),
+        },
+        {
+            id: 'sh3.openUserDocumentsFolder',
+            label: 'Open user documents folder',
+            scope: ['home', 'app'],
+            contextItem: false,
+            paletteItem: true,
+            group: 'folders',
+            disabled: () => {
+                var _a, _b;
+                return disabledForUser({
+                    isLocal: isLocalTauriDesktop(),
+                    userId: (_b = (_a = getUser()) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : null,
+                });
+            },
+            run: (_ctx) => openFolder('user'),
+        },
+        {
+            id: 'sh3.openProjectDocumentsFolder',
+            label: 'Open project documents folder',
+            scope: ['home', 'app'],
+            contextItem: false,
+            paletteItem: true,
+            group: 'folders',
+            disabled: () => disabledForProject({
+                isLocal: isLocalTauriDesktop(),
+                projectId: sessionState.activeProjectId,
+            }),
+            run: (_ctx) => openFolder('project'),
+        },
+    ];
+    const disposers = actions.map((a) => ctx.actions.register(a));
+    return () => disposers.forEach((d) => d());
+}

package/dist/sh3core-shard/folderActions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sh3core-shard/folderActions.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { posix } from 'node:path';
+import { buildDocumentsPath, disabledForApp, disabledForUser, disabledForProject, } from './folderActions';
+const join = (...p) => posix.join(...p);
+describe('buildDocumentsPath', () => {
+    it('joins server/docs/<tenantId> under root', () => {
+        expect(buildDocumentsPath('/data', 'alice', join)).toBe('/data/server/docs/alice');
+    });
+    it('uses the supplied join, not posix hard-coding', () => {
+        const out = buildDocumentsPath('C:\\data', 'bob', (...p) => p.join('\\'));
+        expect(out).toBe('C:\\data\\server\\docs\\bob');
+    });
+});
+describe('disabledForApp', () => {
+    it('disabled when not local Tauri desktop', () => {
+        expect(disabledForApp({ isLocal: false })).toBe(true);
+    });
+    it('enabled when local Tauri desktop', () => {
+        expect(disabledForApp({ isLocal: true })).toBe(false);
+    });
+});
+describe('disabledForUser', () => {
+    it('disabled when not local Tauri desktop', () => {
+        expect(disabledForUser({ isLocal: false, userId: 'alice' })).toBe(true);
+    });
+    it('disabled when no signed-in user', () => {
+        expect(disabledForUser({ isLocal: true, userId: null })).toBe(true);
+    });
+    it('enabled when local + user present', () => {
+        expect(disabledForUser({ isLocal: true, userId: 'alice' })).toBe(false);
+    });
+});
+describe('disabledForProject', () => {
+    it('disabled when not local Tauri desktop', () => {
+        expect(disabledForProject({ isLocal: false, projectId: 'acme' })).toBe(true);
+    });
+    it('disabled when no active project', () => {
+        expect(disabledForProject({ isLocal: true, projectId: null })).toBe(true);
+    });
+    it('enabled when local + project active', () => {
+        expect(disabledForProject({ isLocal: true, projectId: 'acme' })).toBe(false);
+    });
+});

package/dist/sh3core-shard/sh3coreShard.svelte.js

@@ -33,6 +33,7 @@ import { resetActivePresetToDefault } from '../layout/store.svelte';
 import { modalManager } from '../overlays/modal';
 import { floatManager } from '../overlays/float';
 import { registerAppActions } from './appActions';
+import { registerFolderActions } from './folderActions';
 import { openPalette } from '../actions/listeners';
 /**
  * Build the palette-only float-maximize toggle action. Targets the topmost
@@ -122,6 +123,7 @@ export const sh3coreShard = {
         ctx.registerView('sh3core:home', factory);
         ctx.registerView('sh3:keys-and-peers', keysFactory);
         registerAppActions(ctx);
+        registerFolderActions(ctx);
         // Launcher parent — submenu drill host. No `run` needed: the
         // dispatcher's default behavior opens a sub-palette filtered to
         // `submenuOf === 'sh3.app.launch'`. The single parent replaces the

package/dist/shards/lifecycle.svelte.d.ts

@@ -112,3 +112,11 @@ export declare function activateShard(id: string): Promise<void>;
  * that explicitly want to verify cleanup paths).
  */
 export declare function deactivateShard(id: string): void;
+/**
+ * Remove a shard from the registry entirely. Deactivates it first if active,
+ * then drops it from `registeredShards` and clears any error record.
+ *
+ * Called by the package installer when a bundle update no longer ships a
+ * shard that the previous version contributed.
+ */
+export declare function unregisterShard(id: string): void;

package/dist/shards/lifecycle.svelte.js

@@ -607,3 +607,20 @@ export function deactivateShard(id) {
     shardEntries.delete(id);
     activeShards.delete(id);
 }
+/**
+ * Remove a shard from the registry entirely. Deactivates it first if active,
+ * then drops it from `registeredShards` and clears any error record.
+ *
+ * Called by the package installer when a bundle update no longer ships a
+ * shard that the previous version contributed.
+ */
+export function unregisterShard(id) {
+    if (!registeredShards.has(id))
+        return;
+    try {
+        deactivateShard(id);
+    }
+    catch ( /* not active */_a) { /* not active */ }
+    registeredShards.delete(id);
+    erroredShards.delete(id);
+}

package/dist/shell-shard/verbs/xfer.js

@@ -1,4 +1,38 @@
 import { parseScopePath, resolveScope } from './scope-parse';
+// ---------------------------------------------------------------------------
+// Path helpers
+//
+// xfer follows cp-style semantics for the destination:
+//   - dst path ending with `/` (or empty) is a directory; the file is placed
+//     inside with the source's filename (or, for -R, with the source-relative
+//     path rebased under the dst directory).
+//   - dst path without trailing slash is treated literally.
+// ---------------------------------------------------------------------------
+function basename(p) {
+    const i = p.lastIndexOf('/');
+    return i >= 0 ? p.slice(i + 1) : p;
+}
+/** Compose a final dst path from a (possibly-directory) dst dir plus a relative segment. */
+function joinDst(dstDir, relative) {
+    if (!dstDir)
+        return relative;
+    if (dstDir.endsWith('/'))
+        return dstDir + relative;
+    return `${dstDir}/${relative}`;
+}
+/**
+ * Strip a folder prefix off a doc path, returning the remainder. For the
+ * single-file case (doc.path equals prefix), returns the filename. The
+ * caller's filter guarantees doc.path is either exactly `prefix` or starts
+ * with `prefix + '/'`, so this never produces a stray leading slash.
+ */
+function rebaseFromPrefix(prefix, docPath) {
+    if (!prefix)
+        return docPath;
+    if (docPath === prefix)
+        return basename(docPath);
+    return docPath.slice(prefix.length + 1); // skip prefix and the separating '/'
+}
 export const xferVerb = {
     name: 'xfer',
     summary: [
@@ -7,6 +41,7 @@ export const xferVerb = {
         '  Either side may be @me or @project-<slug>; bare paths resolve to the active scope.',
         '  -R  recursive (src is a folder prefix)',
         '  -C  copy only, do not delete source',
+        '  Trailing `/` on dst means "into directory" (cp-style); without it dst is a literal path.',
     ].join('\n'),
     programmatic: true,
     async run(ctx, args) {
@@ -60,25 +95,52 @@ export const xferVerb = {
                 ctx.scrollback.push({ kind: 'status', text: 'xfer: path required (use -R for folder recursion)', level: 'error', ts });
                 return;
             }
-            if (srcTenant === dstTenant && srcParsed.shardId === dstParsed.shardId && srcParsed.path === dstParsed.path) {
+            // cp-style: trailing slash (or empty path) means "into this directory" —
+            // append the source filename so the file lands inside instead of trying
+            // to overwrite the directory itself.
+            const dstIsDir = !dstParsed.path || dstParsed.path.endsWith('/');
+            const dstFinalPath = dstIsDir
+                ? joinDst(dstParsed.path, basename(srcParsed.path))
+                : dstParsed.path;
+            if (srcTenant === dstTenant && srcParsed.shardId === dstParsed.shardId && srcParsed.path === dstFinalPath) {
                 ctx.scrollback.push({ kind: 'status', text: 'xfer: source and destination are the same', level: 'error', ts });
                 return;
             }
-            await ctx.sh3.docs.transferBetweenScopes(srcTenant, srcParsed.shardId, srcParsed.path, dstTenant, dstParsed.shardId, dstParsed.path, moveOpts);
+            await ctx.sh3.docs.transferBetweenScopes(srcTenant, srcParsed.shardId, srcParsed.path, dstTenant, dstParsed.shardId, dstFinalPath, moveOpts);
             const verb = copy ? 'copied' : 'moved';
             ctx.scrollback.push({ kind: 'status', text: `xfer: ${verb} ${positional[0]} → ${positional[1]}`, level: 'info', ts });
             return;
         }
         const prefix = srcParsed.path;
         const allDocs = await ctx.sh3.docs.listDocumentsIn(srcTenant);
-        const matching = allDocs.filter((d) => d.shardId === srcParsed.shardId && (!prefix || d.path.startsWith(prefix)));
+        // Folder-boundary filter: when `prefix` is set, a doc matches only if its
+        // path equals the prefix (single-file case) or sits inside the prefix
+        // folder (`prefix + '/'` ...). Plain `startsWith(prefix)` would also
+        // match sibling files whose names happen to share the prefix string
+        // (e.g. prefix `notes` matching `notesheet.md`).
+        const matching = allDocs.filter((d) => {
+            if (d.shardId !== srcParsed.shardId)
+                return false;
+            if (!prefix)
+                return true;
+            if (d.path === prefix)
+                return true;
+            return d.path.startsWith(`${prefix}/`);
+        });
         if (matching.length === 0) {
             ctx.scrollback.push({ kind: 'status', text: `xfer: no documents found under ${positional[0]}`, level: 'info', ts });
             return;
         }
         let count = 0;
         for (const doc of matching) {
-            await ctx.sh3.docs.transferBetweenScopes(srcTenant, doc.shardId, doc.path, dstTenant, dstParsed.shardId, doc.path, moveOpts);
+            // Per-doc dst: rebase the doc's path relative to the src prefix, then
+            // place it under the dst directory. Without this the dst directory is
+            // ignored and the file lands at its source path in dst shard, which
+            // (a) silently misplaces the file and (b) blows up on mounts where
+            // `mounts/<unknown-segment>/...` fails to resolve to a real mount.
+            const relative = rebaseFromPrefix(prefix, doc.path);
+            const dstFinalPath = joinDst(dstParsed.path, relative);
+            await ctx.sh3.docs.transferBetweenScopes(srcTenant, doc.shardId, doc.path, dstTenant, dstParsed.shardId, dstFinalPath, moveOpts);
             count++;
         }
         const verb = copy ? 'copied' : 'moved';