sh3-core 0.7.5 → 0.8.1

package/dist/documents/sync/tombstones.js

@@ -0,0 +1,58 @@
+/*
+ * Tombstone store — records deletion metadata so sync connectors can
+ * distinguish "never existed" from "was deleted." Backed by JSON docs
+ * under the reserved sync shardId. GC is driven by the engine, not here.
+ */
+import { readJson, writeJson, deletePath, listJsonPaths } from './serialization';
+const PREFIX = 'tombstones/';
+function key(shardId, path) {
+    return `${PREFIX}${shardId}__${encodeURIComponent(path)}.json`;
+}
+export class TombstoneStore {
+    constructor(backend, tenantId) {
+        this.backend = backend;
+        this.tenantId = tenantId;
+    }
+    async record(shardId, path, lastHash, deletedAt) {
+        await writeJson(this.backend, this.tenantId, key(shardId, path), {
+            deletedAt,
+            lastHash,
+        });
+    }
+    async get(shardId, path) {
+        return readJson(this.backend, this.tenantId, key(shardId, path));
+    }
+    async clear(shardId, path) {
+        await deletePath(this.backend, this.tenantId, key(shardId, path));
+    }
+    async listByShard(shardId) {
+        const prefix = `${PREFIX}${shardId}__`;
+        const paths = await listJsonPaths(this.backend, this.tenantId, prefix);
+        const out = [];
+        for (const p of paths) {
+            const rec = await readJson(this.backend, this.tenantId, p);
+            if (!rec)
+                continue;
+            const originalPath = decodeURIComponent(p.slice(prefix.length, -'.json'.length));
+            out.push(Object.assign({ shardId, path: originalPath }, rec));
+        }
+        return out;
+    }
+    async listAll() {
+        const paths = await listJsonPaths(this.backend, this.tenantId, PREFIX);
+        const out = [];
+        for (const p of paths) {
+            const rec = await readJson(this.backend, this.tenantId, p);
+            if (!rec)
+                continue;
+            const rest = p.slice(PREFIX.length, -'.json'.length);
+            const sep = rest.indexOf('__');
+            if (sep < 0)
+                continue;
+            const shardId = rest.slice(0, sep);
+            const path = decodeURIComponent(rest.slice(sep + 2));
+            out.push(Object.assign({ shardId, path }, rec));
+        }
+        return out;
+    }
+}

package/dist/documents/sync/tombstones.test.d.ts

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

package/dist/documents/sync/tombstones.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../backends';
+import { TombstoneStore } from './tombstones';
+describe('TombstoneStore', () => {
+    let backend;
+    let store;
+    beforeEach(() => {
+        backend = new MemoryDocumentBackend();
+        store = new TombstoneStore(backend, 'tenant-a');
+    });
+    it('records and retrieves a tombstone', async () => {
+        await store.record('shard-x', 'dir/file.md', 'hash123', 1000);
+        const t = await store.get('shard-x', 'dir/file.md');
+        expect(t).toEqual({ deletedAt: 1000, lastHash: 'hash123' });
+    });
+    it('returns null for non-tombstoned paths', async () => {
+        expect(await store.get('shard-x', 'absent.md')).toBeNull();
+    });
+    it('clears a tombstone (on upsert of same path)', async () => {
+        await store.record('shard-x', 'a.md', 'h', 1);
+        await store.clear('shard-x', 'a.md');
+        expect(await store.get('shard-x', 'a.md')).toBeNull();
+    });
+    it('lists tombstones within a shard', async () => {
+        await store.record('shard-x', 'a.md', 'h1', 1);
+        await store.record('shard-x', 'b.md', 'h2', 2);
+        await store.record('shard-y', 'c.md', 'h3', 3);
+        const list = await store.listByShard('shard-x');
+        expect(list.map((t) => t.path).sort()).toEqual(['a.md', 'b.md']);
+    });
+    it('lists all tombstones across shards', async () => {
+        await store.record('shard-x', 'a.md', 'h1', 1);
+        await store.record('shard-y', 'c.md', 'h3', 3);
+        const all = await store.listAll();
+        expect(all.length).toBe(2);
+    });
+});

package/dist/documents/sync/types.d.ts

@@ -0,0 +1,116 @@
+/** Permission string required in a shard manifest to obtain ctx.sync(). */
+export declare const PERMISSION_DOCUMENTS_SYNC = "documents:sync";
+/** Reserved shardId used to persist sync metadata (journal, tombstones, cursors, grants). */
+export declare const SYNC_RESERVED_SHARD_ID = "__sync__";
+export type SyncScope = {
+    kind: 'shard';
+    shardId: string;
+} | {
+    kind: 'tenant';
+} | {
+    kind: 'path';
+    shardId: string;
+    prefix: string;
+};
+export interface ManifestEntry {
+    path: string;
+    shardId: string;
+    hash: string;
+    size: number;
+    lastModified: number;
+    tombstone?: {
+        deletedAt: number;
+    };
+}
+export interface ApplyEntry {
+    path: string;
+    shardId: string;
+    op: 'upsert' | 'delete';
+    content?: string | ArrayBuffer;
+    remoteHash: string;
+    remoteMtime: number;
+}
+export interface ApplyOpts {
+    onConflict?: ConflictPolicy;
+    expectedLocalHash?: string;
+}
+export type ApplyOutcome = {
+    status: 'applied';
+    newHash: string;
+} | {
+    status: 'skipped-identical';
+} | {
+    status: 'conflict';
+    resolution: ConflictResolution;
+};
+export interface ApplyBatchResult {
+    applied: Array<{
+        path: string;
+        shardId: string;
+        newHash: string;
+    }>;
+    skipped: Array<{
+        path: string;
+        shardId: string;
+        reason: 'identical';
+    }>;
+    conflicts: ConflictResolution[];
+}
+export interface ConflictResolution {
+    path: string;
+    shardId: string;
+    localHash: string;
+    remoteHash: string;
+    conflictArtifactPath: string;
+    base?: {
+        hash: string;
+    };
+}
+export interface ConflictContext {
+    path: string;
+    shardId: string;
+    localHash: string;
+    remoteHash: string;
+    baseHash?: string;
+}
+export type ConflictPolicy = 'default' | 'remote-wins' | 'local-wins' | 'keep-both' | ((ctx: ConflictContext) => Promise<'remote-wins' | 'local-wins' | 'keep-both'>);
+export interface JournalEntry {
+    seq: number;
+    ts: number;
+    shardId: string;
+    path: string;
+    op: 'upsert' | 'delete';
+    hash: string | null;
+}
+export interface ChangePage {
+    entries: JournalEntry[];
+    nextCursor: string;
+    hasMore: boolean;
+    truncated?: boolean;
+}
+export interface GrantRecord {
+    connectorId: string;
+    scope: SyncScope;
+    grantedAt: number;
+}
+export interface SyncHandle {
+    readonly connectorId: string;
+    grantedScopes(): Promise<SyncScope[]>;
+    getManifest(scope: SyncScope): Promise<ManifestEntry[]>;
+    changesSince(scope: SyncScope, cursor?: string): Promise<ChangePage>;
+    ack(scope: SyncScope, cursor: string): Promise<void>;
+    apply(scope: SyncScope, entry: ApplyEntry, opts?: ApplyOpts): Promise<ApplyOutcome>;
+    applyBatch(scope: SyncScope, manifest: ApplyEntry[], opts?: ApplyOpts): Promise<ApplyBatchResult>;
+    forget(scope: SyncScope, path: string): Promise<void>;
+}
+export declare class ScopeNotGrantedError extends Error {
+    readonly scope: SyncScope;
+    constructor(scope: SyncScope);
+}
+export declare class ScopeRevokedError extends Error {
+    readonly scope: SyncScope;
+    constructor(scope: SyncScope);
+}
+export declare class TenantMismatchError extends Error {
+    constructor();
+}

package/dist/documents/sync/types.js

@@ -0,0 +1,27 @@
+/*
+ * Document Sync API types. See docs/superpowers/specs/2026-04-14-document-sync-api-design.md.
+ */
+/** Permission string required in a shard manifest to obtain ctx.sync(). */
+export const PERMISSION_DOCUMENTS_SYNC = 'documents:sync';
+/** Reserved shardId used to persist sync metadata (journal, tombstones, cursors, grants). */
+export const SYNC_RESERVED_SHARD_ID = '__sync__';
+export class ScopeNotGrantedError extends Error {
+    constructor(scope) {
+        super(`Scope not granted: ${JSON.stringify(scope)}`);
+        this.scope = scope;
+        this.name = 'ScopeNotGrantedError';
+    }
+}
+export class ScopeRevokedError extends Error {
+    constructor(scope) {
+        super(`Scope revoked during operation: ${JSON.stringify(scope)}`);
+        this.scope = scope;
+        this.name = 'ScopeRevokedError';
+    }
+}
+export class TenantMismatchError extends Error {
+    constructor() {
+        super('Sync handle tenantId does not match current session');
+        this.name = 'TenantMismatchError';
+    }
+}

package/dist/documents/sync/write-hook.test.d.ts

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

package/dist/documents/sync/write-hook.test.js

@@ -0,0 +1,36 @@
+// packages/sh3-core/src/documents/sync/write-hook.test.ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../backends';
+import { __setDocumentBackend, __setTenantId } from '../config';
+import { createDocumentHandle } from '../handle';
+import { SyncEngine } from './engine';
+import { setJournalAppender, clearJournalAppender } from '../journal-hook';
+describe('regular document writes feed the sync journal', () => {
+    let backend;
+    let engine;
+    beforeEach(async () => {
+        backend = new MemoryDocumentBackend();
+        __setDocumentBackend(backend);
+        __setTenantId('tenant-a');
+        engine = new SyncEngine(backend, 'tenant-a');
+        await engine.init();
+        setJournalAppender(async (e) => { await engine.journal.append(e); });
+    });
+    it('appends upsert to journal when shard writes via ctx.documents()', async () => {
+        const h = createDocumentHandle('tenant-a', 'shard-x', backend, { format: 'text' });
+        await h.write('a.md', 'hello');
+        const page = await engine.journal.changesSince({ kind: 'tenant' });
+        expect(page.entries.map((e) => `${e.shardId}:${e.path}:${e.op}`)).toEqual([
+            'shard-x:a.md:upsert',
+        ]);
+        clearJournalAppender();
+    });
+    it('appends delete to journal', async () => {
+        const h = createDocumentHandle('tenant-a', 'shard-x', backend, { format: 'text' });
+        await h.write('a.md', 'hello');
+        await h.delete('a.md');
+        const page = await engine.journal.changesSince({ kind: 'tenant' });
+        expect(page.entries.map((e) => e.op)).toEqual(['upsert', 'delete']);
+        clearJournalAppender();
+    });
+});

package/dist/documents/types.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Manifest permission string: grants tenant-wide document observation
+ * (`ctx.browse`) and sync registry visibility (`ctx.syncRegistry`).
+ * Read-only; writes still flow through the shard's own `ctx.documents()`.
+ */
+export declare const PERMISSION_DOCUMENTS_BROWSE = "documents:browse";
 /**
  * Format hint for document content. Determines whether reads return a string
  * (`text`) or an `ArrayBuffer` (`binary`).
@@ -50,6 +56,18 @@ export interface DocumentBackend {
     list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
     /** Return true if the document at `path` exists. */
     exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+    /**
+     * List every shard id that currently has at least one document stored
+     * for this tenant. Tenant-wide observation primitive.
+     */
+    listAllShards(tenantId: string): Promise<string[]>;
+    /**
+     * List every document in the tenant across all shards. Each entry
+     * carries the owning `shardId`. Tenant-wide observation primitive.
+     */
+    listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
 }
 /**
  * Shard-facing document handle returned by `ctx.documents()`. Binds

package/dist/documents/types.js

@@ -9,4 +9,9 @@
  * The document zone is a parallel subsystem — it does not extend
  * ZoneName or ZoneSchema. Shards access it via `ctx.documents()`.
  */
-export {};
+/**
+ * Manifest permission string: grants tenant-wide document observation
+ * (`ctx.browse`) and sync registry visibility (`ctx.syncRegistry`).
+ * Read-only; writes still flow through the shard's own `ctx.documents()`.
+ */
+export const PERMISSION_DOCUMENTS_BROWSE = 'documents:browse';

package/dist/env/client.d.ts

@@ -16,6 +16,15 @@ export declare function fetchEnvState(shardId: string): Promise<Record<string, u
  * Throws if not admin or if the server rejects the write.
  */
 export declare function putEnvState(shardId: string, state: Record<string, unknown>): Promise<void>;
+/** Result shape returned by {@link serverInstallPackage}. */
+export interface ServerInstallResult {
+    ok: boolean;
+    error?: string;
+    code?: string;
+    missing?: Array<{
+        id: string;
+    }>;
+}
 /**
  * Install a package on the server via multipart upload.
  * The client has already fetched and integrity-verified the client bundle
@@ -28,11 +37,7 @@ export declare function putEnvState(shardId: string, state: Record<string, unkno
  *   shard's routes. If the mount fails, the entire install is rolled
  *   back server-side.
  */
-export declare function serverInstallPackage(manifest: Record<string, unknown>, clientBundle: ArrayBuffer, serverBundle?: ArrayBuffer): Promise<{
-    ok: boolean;
-    id: string;
-    error?: string;
-}>;
+export declare function serverInstallPackage(manifest: Record<string, unknown>, clientBundle: ArrayBuffer, serverBundle?: ArrayBuffer): Promise<ServerInstallResult>;
 /**
  * Uninstall a package from the server.
  */

package/dist/env/client.js

@@ -61,7 +61,6 @@ export async function putEnvState(shardId, state) {
  *   back server-side.
  */
 export async function serverInstallPackage(manifest, clientBundle, serverBundle) {
-    var _a;
     if (!isAdmin())
         throw new Error('Cannot install: not elevated to admin');
     const auth = getAuthHeader();
@@ -79,11 +78,20 @@ export async function serverInstallPackage(manifest, clientBundle, serverBundle)
         headers,
         body: form,
     });
-    const body = await res.json();
     if (!res.ok) {
-        return { ok: false, id: String(manifest.id), error: (_a = body.error) !== null && _a !== void 0 ? _a : `HTTP ${res.status}` };
+        let body = {};
+        try {
+            body = await res.json();
+        }
+        catch ( /* non-JSON */_a) { /* non-JSON */ }
+        return {
+            ok: false,
+            error: typeof body.error === 'string' ? body.error : `HTTP ${res.status}`,
+            code: typeof body.code === 'string' ? body.code : undefined,
+            missing: Array.isArray(body.missing) ? body.missing : undefined,
+        };
     }
-    return { ok: true, id: String(manifest.id) };
+    return { ok: true };
 }
 /**
  * Uninstall a package from the server.

package/dist/layout/inspection.d.ts

@@ -50,6 +50,23 @@ export declare function expandChild(splitPath: number[], childIndex: number): bo
  * the sole authority on tree mutations.
  */
 export declare function closeTab(slotId: string): Promise<boolean>;
+/**
+ * Pop a docked tab out into a new float. Locates the tab by `slotId` in
+ * the currently-rendered docked tree, removes it (preserving viewId +
+ * meta), and opens a float with the same view. Returns the new floatId
+ * on success, or null if the slot wasn't found in the docked tree.
+ *
+ * Guarded canClose() is NOT consulted — popout is not a close. The slot
+ * is recreated in the float with a fresh slotId, so the view is remounted.
+ */
+export declare function popoutView(slotId: string): string | null;
+/**
+ * Dock a float back into the currently-rendered layout. The float's
+ * active tab is appended to the first tabs group (same policy as
+ * `dockIntoActiveLayout`). Returns true on success. The float is closed
+ * after its content is transferred.
+ */
+export declare function dockFloat(floatId: string): boolean;
 /**
  * Dock a view into the currently-rendered layout without caring which
  * root it is. Used by the Ctrl+` shell hotkey and other "just put it

package/dist/layout/inspection.js

@@ -194,6 +194,59 @@ async function closeFloatTab(tree, slotId) {
     }
     return false;
 }
+/**
+ * Pop a docked tab out into a new float. Locates the tab by `slotId` in
+ * the currently-rendered docked tree, removes it (preserving viewId +
+ * meta), and opens a float with the same view. Returns the new floatId
+ * on success, or null if the slot wasn't found in the docked tree.
+ *
+ * Guarded canClose() is NOT consulted — popout is not a close. The slot
+ * is recreated in the float with a fresh slotId, so the view is remounted.
+ */
+export function popoutView(slotId) {
+    const tree = activeLayout();
+    const located = findTabBySlotId(tree.docked, slotId);
+    if (!located)
+        return null;
+    const entry = located.entry;
+    const viewId = entry.viewId;
+    if (!viewId)
+        return null;
+    const title = entry.label;
+    const meta = entry.meta;
+    removeTabBySlotId(tree.docked, slotId);
+    cleanupTree(tree.docked);
+    return floatManager.open(viewId, { title, meta });
+}
+/**
+ * Dock a float back into the currently-rendered layout. The float's
+ * active tab is appended to the first tabs group (same policy as
+ * `dockIntoActiveLayout`). Returns true on success. The float is closed
+ * after its content is transferred.
+ */
+export function dockFloat(floatId) {
+    var _a, _b;
+    const tree = activeLayout();
+    const floatEntry = tree.floats.find((f) => f.id === floatId);
+    if (!floatEntry)
+        return false;
+    const content = floatEntry.content;
+    const tabs = content.type === 'tabs' ? content : null;
+    if (!tabs || tabs.tabs.length === 0) {
+        floatManager.close(floatId);
+        return false;
+    }
+    const entry = (_b = tabs.tabs[(_a = tabs.activeTab) !== null && _a !== void 0 ? _a : 0]) !== null && _b !== void 0 ? _b : tabs.tabs[0];
+    const ok = dockIntoActiveLayout({
+        slotId: entry.slotId,
+        viewId: entry.viewId,
+        label: entry.label,
+        meta: entry.meta,
+    });
+    if (ok)
+        floatManager.close(floatId);
+    return ok;
+}
 function findFirstTabsNode(node) {
     if (node.type === 'tabs')
         return node;

package/dist/registry/installer.d.ts

@@ -7,9 +7,10 @@
  *
  * Flow:
  *   1. `installPackage(bundle, meta)` -- load module from bytes, verify
- *      declared type matches actual type, persist to IndexedDB, register
- *      with framework.
- *   2. `uninstallPackage(id)` -- deactivate if active, remove from storage.
+ *      declared type matches actual type, persist to IndexedDB, evict any
+ *      existing registration, then register via the shared helper.
+ *   2. `uninstallPackage(id)` -- deactivate if active, unregister app, remove
+ *      from storage.
  *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
  *      packages from IndexedDB and registers them.
  */
@@ -18,9 +19,10 @@ import type { InstalledPackage, InstallResult, PackageMeta } from './types';
  * Install a package from raw bundle bytes and metadata.
  *
  * Loads the ESM module, verifies the declared type matches the actual module
- * shape, persists to IndexedDB, and registers with the framework. If
- * registration fails (e.g. duplicate id from a shard that was already
- * glob-discovered), the package is still persisted but `hotLoaded` is false.
+ * shape, persists to IndexedDB, evicts any existing registration for the same
+ * id, and registers with the framework via the shared helper. If registration
+ * fails (e.g. a shard that was already glob-discovered), the package is still
+ * persisted but `hotLoaded` is false.
  *
  * @param bundle - Raw verified ESM bundle bytes.
  * @param meta - Provenance metadata for the install record.
@@ -31,7 +33,8 @@ export declare function installPackage(bundle: ArrayBuffer, meta: PackageMeta):
  * Uninstall a package by id.
  *
  * If the package is a shard and currently active, deactivates it first.
- * Removes both the bundle and metadata from IndexedDB.
+ * Unregisters any app entry for the id, then removes both the bundle and
+ * metadata from IndexedDB.
  *
  * @param id - The package id to uninstall.
  */

package/dist/registry/installer.js

@@ -7,24 +7,27 @@
  *
  * Flow:
  *   1. `installPackage(bundle, meta)` -- load module from bytes, verify
- *      declared type matches actual type, persist to IndexedDB, register
- *      with framework.
- *   2. `uninstallPackage(id)` -- deactivate if active, remove from storage.
+ *      declared type matches actual type, persist to IndexedDB, evict any
+ *      existing registration, then register via the shared helper.
+ *   2. `uninstallPackage(id)` -- deactivate if active, unregister app, remove
+ *      from storage.
  *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
  *      packages from IndexedDB and registers them.
  */
 import { loadBundleModule } from './loader';
 import { savePackage, loadBundle, listInstalled, removePackage } from './storage';
 import { verifyIntegrity } from './integrity';
-import { registerShard, deactivateShard } from '../shards/activate.svelte';
-import { registerApp } from '../apps/registry.svelte';
+import { deactivateShard } from '../shards/activate.svelte';
+import { unregisterApp } from '../apps/lifecycle';
+import { registerLoadedBundle } from './register';
 /**
  * Install a package from raw bundle bytes and metadata.
  *
  * Loads the ESM module, verifies the declared type matches the actual module
- * shape, persists to IndexedDB, and registers with the framework. If
- * registration fails (e.g. duplicate id from a shard that was already
- * glob-discovered), the package is still persisted but `hotLoaded` is false.
+ * shape, persists to IndexedDB, evicts any existing registration for the same
+ * id, and registers with the framework via the shared helper. If registration
+ * fails (e.g. a shard that was already glob-discovered), the package is still
+ * persisted but `hotLoaded` is false.
  *
  * @param bundle - Raw verified ESM bundle bytes.
  * @param meta - Provenance metadata for the install record.
@@ -88,20 +91,27 @@ export async function installPackage(bundle, meta) {
             error: `Failed to persist package: ${err instanceof Error ? err.message : String(err)}`,
         };
     }
-    // 5. Stamp loader-assigned version (ADR-013) then register all shards
-    //    and apps from the bundle. External package authors omit `version`
-    //    from their source manifests; the authoritative value is the
-    //    registry entry's `PackageVersion.version`, carried on `meta.version`.
+    // 5. Evict any existing registration for this id before re-registering.
+    //    Without this, reinstall at the same version leaks activation state
+    //    (shards stay active) or app entries (apps silently replace but the
+    //    old module instance's module-scope state is never torn down).
+    if (meta.type === 'shard' || meta.type === 'combo') {
+        try {
+            deactivateShard(meta.id);
+        }
+        catch ( /* not active or not a shard */_a) { /* not active or not a shard */ }
+    }
+    if (meta.type === 'app' || meta.type === 'combo') {
+        unregisterApp(meta.id);
+    }
+    // 6. Register all shards and apps from the bundle via the shared helper.
     let hotLoaded = true;
     try {
-        for (const shard of loaded.shards) {
-            shard.manifest = Object.assign(Object.assign({}, shard.manifest), { version: meta.version });
-            registerShard(shard);
-        }
-        for (const app of loaded.apps) {
-            app.manifest = Object.assign(Object.assign({}, app.manifest), { version: meta.version });
-            registerApp(app);
-        }
+        registerLoadedBundle(loaded, {
+            version: meta.version,
+            sourceRegistry: meta.sourceRegistry,
+            contractVersion: meta.contractVersion,
+        });
     }
     catch (err) {
         console.warn(`[sh3] Package "${meta.id}" installed but registration failed (will retry on next boot):`, err instanceof Error ? err.message : err);
@@ -113,18 +123,17 @@ export async function installPackage(bundle, meta) {
  * Uninstall a package by id.
  *
  * If the package is a shard and currently active, deactivates it first.
- * Removes both the bundle and metadata from IndexedDB.
+ * Unregisters any app entry for the id, then removes both the bundle and
+ * metadata from IndexedDB.
  *
  * @param id - The package id to uninstall.
  */
 export async function uninstallPackage(id) {
-    // Attempt deactivation (no-op if not active or not a shard).
     try {
         deactivateShard(id);
     }
-    catch (_a) {
-        // Ignore -- may not be a shard, or may not be active.
-    }
+    catch ( /* no-op */_a) { /* no-op */ }
+    unregisterApp(id);
     await removePackage(id);
 }
 /**
@@ -160,16 +169,11 @@ export async function loadInstalledPackages() {
                 continue;
             }
             const loaded = await loadBundleModule(bytes);
-            // Stamp loader-assigned version (ADR-013) from the persisted
-            // InstalledPackage record before registration.
-            for (const shard of loaded.shards) {
-                shard.manifest = Object.assign(Object.assign({}, shard.manifest), { version: pkg.version });
-                registerShard(shard);
-            }
-            for (const app of loaded.apps) {
-                app.manifest = Object.assign(Object.assign({}, app.manifest), { version: pkg.version });
-                registerApp(app);
-            }
+            registerLoadedBundle(loaded, {
+                version: pkg.version,
+                sourceRegistry: pkg.sourceRegistry,
+                contractVersion: pkg.contractVersion,
+            });
             if (loaded.shards.length === 0 && loaded.apps.length === 0) {
                 console.warn(`[sh3] Package "${pkg.id}" contains no valid shards or apps, skipping`);
             }

package/dist/registry/register.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Unified bundle registration — stamps loader-assigned metadata onto every
+ * shard/app manifest from a loaded bundle, then registers each. Shared by
+ * `installer.installPackage`, `installer.loadInstalledPackages`, and
+ * `createShell` discoveredPackages so the three boot paths stay in sync.
+ *
+ * Per ADR-013, external package authors omit `version` from their source
+ * manifests; the authoritative value comes from the persisted/server
+ * metadata and must be stamped here before any consumer reads the manifest.
+ */
+import type { LoadedBundle } from './loader';
+export interface BundleStampMeta {
+    version: string;
+    sourceRegistry: string;
+    contractVersion: string;
+}
+export declare function registerLoadedBundle(loaded: LoadedBundle, meta: BundleStampMeta): void;