sh3-core 0.7.5 → 0.8.0

package/dist/documents/sync/serialization.js

@@ -0,0 +1,24 @@
+/*
+ * JSON storage helpers on top of DocumentBackend. All sync metadata
+ * lives under the reserved shardId SYNC_RESERVED_SHARD_ID, scoped per
+ * tenant by the backend. Callers pass tenantId explicitly; tenant
+ * scoping is enforced at the SyncHandle/engine layer.
+ */
+import { SYNC_RESERVED_SHARD_ID } from './types';
+export async function readJson(backend, tenantId, path) {
+    const raw = await backend.read(tenantId, SYNC_RESERVED_SHARD_ID, path);
+    if (raw === null)
+        return null;
+    const str = typeof raw === 'string' ? raw : new TextDecoder().decode(raw);
+    return JSON.parse(str);
+}
+export async function writeJson(backend, tenantId, path, value) {
+    await backend.write(tenantId, SYNC_RESERVED_SHARD_ID, path, JSON.stringify(value));
+}
+export async function deletePath(backend, tenantId, path) {
+    await backend.delete(tenantId, SYNC_RESERVED_SHARD_ID, path);
+}
+export async function listJsonPaths(backend, tenantId, prefix) {
+    const all = await backend.list(tenantId, SYNC_RESERVED_SHARD_ID);
+    return all.map((m) => m.path).filter((p) => p.startsWith(prefix));
+}

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

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

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

@@ -0,0 +1,26 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../backends';
+import { readJson, writeJson, listJsonPaths } from './serialization';
+import { SYNC_RESERVED_SHARD_ID } from './types';
+describe('sync serialization', () => {
+    let backend;
+    beforeEach(() => { backend = new MemoryDocumentBackend(); });
+    it('writes and reads JSON round-trip', async () => {
+        await writeJson(backend, 'tenant-a', 'foo/bar.json', { hello: 'world', n: 7 });
+        const out = await readJson(backend, 'tenant-a', 'foo/bar.json');
+        expect(out).toEqual({ hello: 'world', n: 7 });
+    });
+    it('returns null when a path is absent', async () => {
+        expect(await readJson(backend, 'tenant-a', 'missing.json')).toBeNull();
+    });
+    it('lists JSON paths under a prefix', async () => {
+        await writeJson(backend, 't', 'grants/a.json', { a: 1 });
+        await writeJson(backend, 't', 'grants/b.json', { b: 2 });
+        await writeJson(backend, 't', 'other/c.json', { c: 3 });
+        const paths = await listJsonPaths(backend, 't', 'grants/');
+        expect(paths.sort()).toEqual(['grants/a.json', 'grants/b.json']);
+    });
+    it('uses SYNC_RESERVED_SHARD_ID', () => {
+        expect(SYNC_RESERVED_SHARD_ID).toBe('__sync__');
+    });
+});

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

@@ -0,0 +1,11 @@
+import type { DocumentBackend } from '../types';
+import { SyncEngine } from './engine';
+import { type SyncRegistry } from './registry';
+interface Bundle {
+    engine: SyncEngine;
+    registry: SyncRegistry;
+}
+export declare function getSyncBundle(backend: DocumentBackend, tenantId: string): Promise<Bundle>;
+/** Test-only reset. */
+export declare function __resetSyncBundlesForTest(): void;
+export {};

package/dist/documents/sync/singleton.js

@@ -0,0 +1,26 @@
+/*
+ * Per-tenant SyncEngine singleton. Lazily initialised on first
+ * ctx.sync() call. The journal appender hook is registered once
+ * when the engine is first built so regular shard writes feed
+ * the journal for all future connectors.
+ */
+import { setJournalAppender } from '../journal-hook';
+import { SyncEngine } from './engine';
+import { createSyncRegistry } from './registry';
+const bundles = new Map();
+export async function getSyncBundle(backend, tenantId) {
+    const existing = bundles.get(tenantId);
+    if (existing)
+        return existing;
+    const engine = new SyncEngine(backend, tenantId);
+    await engine.init();
+    const registry = createSyncRegistry(backend, tenantId);
+    setJournalAppender(async (e) => { await engine.journal.append(e); });
+    const bundle = { engine, registry };
+    bundles.set(tenantId, bundle);
+    return bundle;
+}
+/** Test-only reset. */
+export function __resetSyncBundlesForTest() {
+    bundles.clear();
+}

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

@@ -0,0 +1,19 @@
+import type { DocumentBackend } from '../types';
+export interface TombstoneRecord {
+    deletedAt: number;
+    lastHash: string;
+}
+export interface TombstoneEntry extends TombstoneRecord {
+    shardId: string;
+    path: string;
+}
+export declare class TombstoneStore {
+    private backend;
+    private tenantId;
+    constructor(backend: DocumentBackend, tenantId: string);
+    record(shardId: string, path: string, lastHash: string, deletedAt: number): Promise<void>;
+    get(shardId: string, path: string): Promise<TombstoneRecord | null>;
+    clear(shardId: string, path: string): Promise<void>;
+    listByShard(shardId: string): Promise<TombstoneEntry[]>;
+    listAll(): Promise<TombstoneEntry[]>;
+}

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/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/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;

package/dist/registry/register.js

@@ -0,0 +1,22 @@
+/**
+ * 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 { registerShard } from '../shards/activate.svelte';
+import { registerApp } from '../apps/registry.svelte';
+export function registerLoadedBundle(loaded, meta) {
+    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);
+    }
+}