sh3-core 0.9.0 → 0.10.1

package/dist/app/store/storeShard.svelte.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { diffPermissions } from './storeShard.svelte';
+describe('diffPermissions', () => {
+    it('returns empty added and removed when the sets are identical', () => {
+        expect(diffPermissions(['a', 'b'], ['a', 'b'])).toEqual({
+            added: [],
+            removed: [],
+        });
+    });
+    it('detects permissions added by the new version', () => {
+        expect(diffPermissions(['a'], ['a', 'b'])).toEqual({
+            added: ['b'],
+            removed: [],
+        });
+    });
+    it('detects permissions removed by the new version', () => {
+        expect(diffPermissions(['a', 'b'], ['a'])).toEqual({
+            added: [],
+            removed: ['b'],
+        });
+    });
+    it('reports both added and removed when the set changes in both directions', () => {
+        expect(diffPermissions(['a', 'b'], ['b', 'c'])).toEqual({
+            added: ['c'],
+            removed: ['a'],
+        });
+    });
+    it('treats an empty old set as "everything is new"', () => {
+        expect(diffPermissions([], ['a', 'b'])).toEqual({
+            added: ['a', 'b'],
+            removed: [],
+        });
+    });
+});

package/dist/contributions/index.d.ts

@@ -0,0 +1,2 @@
+export type { ContributionsApi } from './types';
+export { register, list, listPoints, onChange, __resetContributionsForTest } from './registry';

package/dist/contributions/index.js

@@ -0,0 +1,8 @@
+/*
+ * Contribution-points barrel — internal re-exports.
+ *
+ * The public type (ContributionsApi) reaches shards via api.ts; this
+ * file is internal-only, re-exporting the registry for activate.svelte.ts
+ * and for tests.
+ */
+export { register, list, listPoints, onChange, __resetContributionsForTest } from './registry';

package/dist/contributions/registry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Register a descriptor under the given point. Returns an unregister
+ * function; calling it more than once is a safe no-op.
+ */
+export declare function register<T = unknown>(pointId: string, descriptor: T): () => void;
+/** Enumerate descriptors at the named point in registration order. */
+export declare function list<T = unknown>(pointId: string): T[];
+/** Enumerate every point id with at least one registration. */
+export declare function listPoints(): string[];
+/**
+ * Subscribe to registration changes at the named point. The callback
+ * receives no arguments — subscribers call `list` themselves to read
+ * the current state. Returns an unsubscribe; double-unsubscribe is a
+ * safe no-op.
+ */
+export declare function onChange(pointId: string, cb: () => void): () => void;
+/**
+ * Test-only reset. Not exported from the barrel; tests import it
+ * directly from this module.
+ */
+export declare function __resetContributionsForTest(): void;

package/dist/contributions/registry.js

@@ -0,0 +1,89 @@
+/*
+ * Contribution point registry — shard-to-shard runtime collaboration.
+ *
+ * One module-level map holds every point's descriptors. Handles are
+ * Symbols so two registrations with identical content stay distinct.
+ * Emitters are a Set of zero-arg callbacks; subscribers re-read `list`
+ * themselves when notified.
+ *
+ * No tenant partitioning: the shell is single-tenant per session; a
+ * future multi-tenant client would add a tenant dimension to the
+ * outer map (see direction spec §5.2).
+ */
+const points = new Map();
+const listeners = new Map();
+function emit(pointId) {
+    const set = listeners.get(pointId);
+    if (!set)
+        return;
+    for (const cb of set)
+        cb();
+}
+/**
+ * Register a descriptor under the given point. Returns an unregister
+ * function; calling it more than once is a safe no-op.
+ */
+export function register(pointId, descriptor) {
+    const handle = Symbol();
+    let map = points.get(pointId);
+    if (!map) {
+        map = new Map();
+        points.set(pointId, map);
+    }
+    map.set(handle, descriptor);
+    emit(pointId);
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        const m = points.get(pointId);
+        if (!m)
+            return;
+        if (m.delete(handle)) {
+            if (m.size === 0)
+                points.delete(pointId);
+            emit(pointId);
+        }
+    };
+}
+/** Enumerate descriptors at the named point in registration order. */
+export function list(pointId) {
+    const m = points.get(pointId);
+    return m ? Array.from(m.values()) : [];
+}
+/** Enumerate every point id with at least one registration. */
+export function listPoints() {
+    return Array.from(points.keys());
+}
+/**
+ * Subscribe to registration changes at the named point. The callback
+ * receives no arguments — subscribers call `list` themselves to read
+ * the current state. Returns an unsubscribe; double-unsubscribe is a
+ * safe no-op.
+ */
+export function onChange(pointId, cb) {
+    let set = listeners.get(pointId);
+    if (!set) {
+        set = new Set();
+        listeners.set(pointId, set);
+    }
+    set.add(cb);
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        set.delete(cb);
+        if (set.size === 0)
+            listeners.delete(pointId);
+    };
+}
+/**
+ * Test-only reset. Not exported from the barrel; tests import it
+ * directly from this module.
+ */
+export function __resetContributionsForTest() {
+    points.clear();
+    listeners.clear();
+}

package/dist/contributions/registry.test.d.ts

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

package/dist/contributions/registry.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { register, list, listPoints, onChange, __resetContributionsForTest, } from './registry';
+describe('contributions registry', () => {
+    beforeEach(() => {
+        __resetContributionsForTest();
+    });
+    describe('register / list', () => {
+        it('returns an unregister function', () => {
+            const unreg = register('p', { id: 'a' });
+            expect(typeof unreg).toBe('function');
+        });
+        it('register then list returns the descriptor', () => {
+            register('p', { id: 'a' });
+            expect(list('p')).toEqual([{ id: 'a' }]);
+        });
+        it('lists multiple descriptors in registration order', () => {
+            register('p', { id: 'a' });
+            register('p', { id: 'b' });
+            register('p', { id: 'c' });
+            expect(list('p').map((d) => d.id)).toEqual(['a', 'b', 'c']);
+        });
+        it('separates descriptors by pointId', () => {
+            register('p1', { id: 'a' });
+            register('p2', { id: 'b' });
+            expect(list('p1')).toEqual([{ id: 'a' }]);
+            expect(list('p2')).toEqual([{ id: 'b' }]);
+        });
+        it('returns an empty array for an unknown pointId', () => {
+            expect(list('nope')).toEqual([]);
+        });
+        it('unregister removes the descriptor', () => {
+            const unreg = register('p', { id: 'a' });
+            unreg();
+            expect(list('p')).toEqual([]);
+        });
+        it('double-unregister is a no-op', () => {
+            const unreg = register('p', { id: 'a' });
+            unreg();
+            unreg();
+            expect(list('p')).toEqual([]);
+        });
+        it('allows duplicate descriptors (framework does not inspect content)', () => {
+            register('p', { id: 'a' });
+            register('p', { id: 'a' });
+            expect(list('p')).toHaveLength(2);
+        });
+    });
+    describe('listPoints', () => {
+        it('returns empty when nothing is registered', () => {
+            expect(listPoints()).toEqual([]);
+        });
+        it('returns every pointId with at least one registration', () => {
+            register('p1', { id: 'a' });
+            register('p2', { id: 'b' });
+            expect(listPoints().sort()).toEqual(['p1', 'p2']);
+        });
+        it('excludes pointIds whose last registration was unregistered', () => {
+            const u1 = register('p1', { id: 'a' });
+            register('p2', { id: 'b' });
+            u1();
+            expect(listPoints()).toEqual(['p2']);
+        });
+    });
+    describe('onChange', () => {
+        it('fires on register', () => {
+            const cb = vi.fn();
+            onChange('p', cb);
+            register('p', { id: 'a' });
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+        it('fires on unregister', () => {
+            const cb = vi.fn();
+            const unreg = register('p', { id: 'a' });
+            onChange('p', cb);
+            unreg();
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+        it('does not fire for other pointIds', () => {
+            const cb = vi.fn();
+            onChange('p1', cb);
+            register('p2', { id: 'a' });
+            expect(cb).not.toHaveBeenCalled();
+        });
+        it('supports multiple subscribers', () => {
+            const a = vi.fn();
+            const b = vi.fn();
+            onChange('p', a);
+            onChange('p', b);
+            register('p', { id: 'x' });
+            expect(a).toHaveBeenCalledTimes(1);
+            expect(b).toHaveBeenCalledTimes(1);
+        });
+        it('unsubscribe stops callbacks', () => {
+            const cb = vi.fn();
+            const off = onChange('p', cb);
+            off();
+            register('p', { id: 'x' });
+            expect(cb).not.toHaveBeenCalled();
+        });
+        it('double-unsubscribe is a no-op', () => {
+            const cb = vi.fn();
+            const off = onChange('p', cb);
+            off();
+            off();
+            register('p', { id: 'x' });
+            expect(cb).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/contributions/types.d.ts

@@ -0,0 +1,24 @@
+export interface ContributionsApi {
+    /**
+     * Register `descriptor` under `pointId`. Descriptors are freeform;
+     * the framework does not inspect them. The type parameter exists
+     * for ergonomics — provider and contributor agree on the shape via
+     * a type-only import of the provider's public types.
+     *
+     * Returns an unregister function. Calling it is optional (the
+     * framework auto-unregisters on shard deactivate) and safe to call
+     * more than once.
+     */
+    register<T = unknown>(pointId: string, descriptor: T): () => void;
+    /** Enumerate descriptors at `pointId` in registration order. */
+    list<T = unknown>(pointId: string): T[];
+    /** Enumerate every point id with at least one registration. */
+    listPoints(): string[];
+    /**
+     * Subscribe to registration changes at `pointId`. The callback
+     * receives no arguments — call `list` from inside to read the
+     * current state. Returns an unsubscribe; auto-unsubscribed on
+     * shard deactivate.
+     */
+    onChange(pointId: string, cb: () => void): () => void;
+}

package/dist/contributions/types.js

@@ -0,0 +1,10 @@
+/*
+ * ContributionsApi — the per-shard surface exposed on ShardContext.
+ *
+ * See docs/sh3-rfcs/2026-04-20-shard-contribution-points.md for
+ * motivation and semantics. Every registration and every onChange
+ * subscription made through this API is auto-cleaned when the owning
+ * shard deactivates; callers should not need to call the returned
+ * disposer unless they want to release early.
+ */
+export {};

package/dist/documents/browse.d.ts

@@ -8,5 +8,35 @@ export interface BrowseCapability {
     watchDocuments(callback: (change: DocumentChange) => void): () => void;
     /** Enumerate shard ids with at least one document in the tenant. */
     listShards(): Promise<string[]>;
+    /**
+     * Read content from any shard's document namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:read`. Returns the content string
+     * (text-format docs), ArrayBuffer (binary-format docs), or null if the
+     * document does not exist. Tenant-scoped — cannot cross tenants.
+     *
+     * Absent (undefined) on the capability object when `documents:read`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.readFrom === 'function'`.
+     */
+    readFrom?(shardId: string, path: string): Promise<string | ArrayBuffer | null>;
+    /**
+     * Write content into any shard's document namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:write`. Emits a normal
+     * `DocumentChange` so other shards and the file-explorer pick up the
+     * new or updated document. Tenant-scoped — cannot cross tenants.
+     *
+     * Absent (undefined) on the capability object when `documents:write`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.writeTo === 'function'`.
+     */
+    writeTo?(shardId: string, path: string, content: string | ArrayBuffer): Promise<void>;
 }
-export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend): BrowseCapability;
+export interface BrowseCapabilityOptions {
+    /** When true, the returned capability exposes `readFrom`. */
+    canRead: boolean;
+    /** When true, the returned capability exposes `writeTo`. */
+    canWrite: boolean;
+}
+export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend, options?: BrowseCapabilityOptions): BrowseCapability;

package/dist/documents/browse.js

@@ -6,8 +6,8 @@
  * the owning shard's own ctx.documents() handle.
  */
 import { documentChanges } from './notifications';
-export function createBrowseCapability(tenantId, backend) {
-    return {
+export function createBrowseCapability(tenantId, backend, options = { canRead: false, canWrite: false }) {
+    const capability = {
         listDocuments: () => backend.listAllDocuments(tenantId),
         listShards: () => backend.listAllShards(tenantId),
         watchDocuments: (callback) => documentChanges.subscribe((change) => {
@@ -16,4 +16,20 @@ export function createBrowseCapability(tenantId, backend) {
             callback(change);
         }),
     };
+    if (options.canRead) {
+        capability.readFrom = (shardId, path) => backend.read(tenantId, shardId, path);
+    }
+    if (options.canWrite) {
+        capability.writeTo = async (shardId, path, content) => {
+            const existed = await backend.exists(tenantId, shardId, path);
+            await backend.write(tenantId, shardId, path, content);
+            documentChanges.emit({
+                type: existed ? 'update' : 'create',
+                path,
+                tenantId,
+                shardId,
+            });
+        };
+    }
+    return capability;
 }

package/dist/documents/browse.test.js

@@ -38,4 +38,85 @@ describe('BrowseCapability', () => {
         documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
         expect(cb).not.toHaveBeenCalled();
     });
+    describe('readFrom (documents:read gate)', () => {
+        it('is absent when canRead is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            expect(browse.readFrom).toBeUndefined();
+        });
+        it('is present when canRead is true', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(typeof browse.readFrom).toBe('function');
+        });
+        it('reads content from a foreign shard namespace', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'other', 'notes/ideas.md', 'hello');
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('other', 'notes/ideas.md')).toBe('hello');
+        });
+        it('returns null when the foreign document does not exist', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('other', 'nope.txt')).toBeNull();
+        });
+        it('never crosses tenants: a t1 capability cannot read t2 docs', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t2', 's', 'secret.txt', 'hidden');
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('s', 'secret.txt')).toBeNull();
+        });
+    });
+    describe('writeTo (documents:write gate)', () => {
+        it('is absent when canWrite is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            expect(browse.writeTo).toBeUndefined();
+        });
+        it('is present when canWrite is true', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            expect(typeof browse.writeTo).toBe('function');
+        });
+        it('writes into the target shard namespace and emits a create change', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.writeTo('target-shard', 'notes/ideas.md', 'hello');
+            expect(await be.read('t1', 'target-shard', 'notes/ideas.md')).toBe('hello');
+            expect(events).toEqual([
+                { type: 'create', path: 'notes/ideas.md', tenantId: 't1', shardId: 'target-shard' },
+            ]);
+            unsub();
+        });
+        it('emits update (not create) when overwriting an existing document', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'target-shard', 'a.txt', 'v1');
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.writeTo('target-shard', 'a.txt', 'v2');
+            expect(await be.read('t1', 'target-shard', 'a.txt')).toBe('v2');
+            expect(events).toEqual([
+                { type: 'update', path: 'a.txt', tenantId: 't1', shardId: 'target-shard' },
+            ]);
+            unsub();
+        });
+        it('never crosses tenants: cannot be tricked into writing into tenant b', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            await browse.writeTo('s', 'a.txt', 'x');
+            expect(await be.read('t1', 's', 'a.txt')).toBe('x');
+            expect(await be.read('t2', 's', 'a.txt')).toBeNull();
+        });
+    });
+    describe('read + write combined', () => {
+        it('round-trips content through readFrom after writeTo', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: true });
+            await browse.writeTo('shard-x', 'doc.txt', 'roundtrip');
+            expect(await browse.readFrom('shard-x', 'doc.txt')).toBe('roundtrip');
+        });
+    });
 });

package/dist/documents/types.d.ts

@@ -5,6 +5,35 @@
  * through the owning shard's own `ctx.documents()` handle.
  */
 export declare const PERMISSION_DOCUMENTS_BROWSE = "documents:browse";
+/**
+ * Manifest permission string: grants the shard the ability to read
+ * document content from any shard's namespace within the active tenant
+ * via `ctx.browse.readFrom(shardId, path)`. Requires `documents:browse`
+ * in the same manifest — the read surface hangs off `ctx.browse`, which
+ * only exists when `browse` is granted.
+ *
+ * `documents:browse` alone is metadata-only (listDocuments, listShards,
+ * watchDocuments). `documents:read` is the separate content-read gate so
+ * observer shards granted `browse` today do not silently gain content
+ * access.
+ *
+ * Tenant-scoped: reads cannot cross tenants.
+ */
+export declare const PERMISSION_DOCUMENTS_READ = "documents:read";
+/**
+ * Manifest permission string: grants the shard the ability to write
+ * documents into any shard's namespace within the active tenant via
+ * `ctx.browse.writeTo(shardId, path, content)`. Requires
+ * `documents:browse` in the same manifest — the write surface hangs off
+ * `ctx.browse`, which only exists when `browse` is granted.
+ *
+ * Tenant-scoped: writes cannot cross tenants. A shard declaring
+ * `browse` + `write` can overwrite any document owned by any shard in
+ * the current tenant, which is why the install-time consent modal
+ * surfaces this as a distinct line item rather than folding it into
+ * `browse`.
+ */
+export declare const PERMISSION_DOCUMENTS_WRITE = "documents:write";
 /**
  * Format hint for document content. Determines whether reads return a string
  * (`text`) or an `ArrayBuffer` (`binary`).

package/dist/documents/types.js

@@ -16,3 +16,32 @@
  * through the owning shard's own `ctx.documents()` handle.
  */
 export const PERMISSION_DOCUMENTS_BROWSE = 'documents:browse';
+/**
+ * Manifest permission string: grants the shard the ability to read
+ * document content from any shard's namespace within the active tenant
+ * via `ctx.browse.readFrom(shardId, path)`. Requires `documents:browse`
+ * in the same manifest — the read surface hangs off `ctx.browse`, which
+ * only exists when `browse` is granted.
+ *
+ * `documents:browse` alone is metadata-only (listDocuments, listShards,
+ * watchDocuments). `documents:read` is the separate content-read gate so
+ * observer shards granted `browse` today do not silently gain content
+ * access.
+ *
+ * Tenant-scoped: reads cannot cross tenants.
+ */
+export const PERMISSION_DOCUMENTS_READ = 'documents:read';
+/**
+ * Manifest permission string: grants the shard the ability to write
+ * documents into any shard's namespace within the active tenant via
+ * `ctx.browse.writeTo(shardId, path, content)`. Requires
+ * `documents:browse` in the same manifest — the write surface hangs off
+ * `ctx.browse`, which only exists when `browse` is granted.
+ *
+ * Tenant-scoped: writes cannot cross tenants. A shard declaring
+ * `browse` + `write` can overwrite any document owned by any shard in
+ * the current tenant, which is why the install-time consent modal
+ * surfaces this as a distinct line item rather than folding it into
+ * `browse`.
+ */
+export const PERMISSION_DOCUMENTS_WRITE = 'documents:write';

package/dist/registry/client.js

@@ -81,6 +81,9 @@ export async function fetchRegistries(urls) {
  * @throws If the fetch fails, the server returns a non-OK status, or the integrity check fails.
  */
 export async function fetchBundle(version, sourceRegistry) {
+    if (!version.bundleUrl || !version.integrity) {
+        throw new Error('fetchBundle called on a version with no client bundle');
+    }
     let url = version.bundleUrl;
     if (sourceRegistry && !/^https?:\/\//i.test(url)) {
         url = new URL(url, sourceRegistry).href;

package/dist/registry/installer.d.ts

@@ -14,6 +14,7 @@
  *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
  *      packages from IndexedDB and registers them.
  */
+import { type LoadedBundle } from './loader';
 import type { InstalledPackage, InstallResult, PackageMeta } from './types';
 /**
  * Install a package from raw bundle bytes and metadata.
@@ -28,7 +29,9 @@ import type { InstalledPackage, InstallResult, PackageMeta } from './types';
  * @param meta - Provenance metadata for the install record.
  * @returns Result object indicating success/failure and hot-load status.
  */
-export declare function installPackage(bundle: ArrayBuffer, meta: PackageMeta): Promise<InstallResult>;
+export declare function installPackage(bundle: ArrayBuffer, meta: PackageMeta, options?: {
+    loaded?: LoadedBundle;
+}): Promise<InstallResult>;
 /**
  * Uninstall a package by id.
  *

package/dist/registry/installer.js

@@ -20,6 +20,7 @@ import { verifyIntegrity } from './integrity';
 import { deactivateShard } from '../shards/activate.svelte';
 import { unregisterApp } from '../apps/lifecycle';
 import { registerLoadedBundle } from './register';
+import { extractBundlePermissions } from './permission-descriptions';
 /**
  * Install a package from raw bundle bytes and metadata.
  *
@@ -33,30 +34,42 @@ import { registerLoadedBundle } from './register';
  * @param meta - Provenance metadata for the install record.
  * @returns Result object indicating success/failure and hot-load status.
  */
-export async function installPackage(bundle, meta) {
+export async function installPackage(bundle, meta, options) {
     // 1. Verify bundle integrity before executing any code.
-    try {
-        await verifyIntegrity(bundle, meta.integrity);
-    }
-    catch (err) {
+    if (!meta.integrity) {
         return {
             success: false,
             hotLoaded: false,
-            error: `Integrity check failed: ${err instanceof Error ? err.message : String(err)}`,
+            error: 'Missing integrity hash — refusing to install unverified bundle',
         };
     }
-    // 2. Load the module from verified bytes.
-    let loaded;
     try {
-        loaded = await loadBundleModule(bundle);
+        await verifyIntegrity(bundle, meta.integrity);
     }
     catch (err) {
         return {
             success: false,
             hotLoaded: false,
-            error: `Failed to load bundle: ${err instanceof Error ? err.message : String(err)}`,
+            error: `Integrity check failed: ${err instanceof Error ? err.message : String(err)}`,
         };
     }
+    // 2. Load the module from verified bytes (or reuse the caller's copy).
+    let loaded;
+    if (options === null || options === void 0 ? void 0 : options.loaded) {
+        loaded = options.loaded;
+    }
+    else {
+        try {
+            loaded = await loadBundleModule(bundle);
+        }
+        catch (err) {
+            return {
+                success: false,
+                hotLoaded: false,
+                error: `Failed to load bundle: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
     // 3. Verify the bundle contains the declared type.
     if (meta.type === 'shard' && loaded.shards.length === 0) {
         return {
@@ -72,7 +85,7 @@ export async function installPackage(bundle, meta) {
             error: `Package "${meta.id}" declared type "app" but bundle contains no valid app`,
         };
     }
-    // 4. Persist to IndexedDB.
+    // 4. Persist to IndexedDB. Permissions captured from manifest(s).
     const record = {
         id: meta.id,
         type: meta.type,
@@ -80,6 +93,7 @@ export async function installPackage(bundle, meta) {
         sourceRegistry: meta.sourceRegistry,
         contractVersion: meta.contractVersion,
         installedAt: new Date().toISOString(),
+        permissions: extractBundlePermissions(loaded),
     };
     try {
         await savePackage(meta.id, bundle, record);

package/dist/registry/permission-descriptions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Human-friendly descriptions for manifest-declared permissions.
+ *
+ * The app store's install/update confirmation modal renders each permission
+ * via `describePermission`. Unknown permission IDs fall back to showing the
+ * raw ID with a generic placeholder so newer packages don't crash older
+ * cores.
+ */
+import type { LoadedBundle } from './loader';
+export interface PermissionDescription {
+    title: string;
+    description: string;
+}
+export declare const PERMISSION_DESCRIPTIONS: Record<string, PermissionDescription>;
+export declare function describePermission(id: string): PermissionDescription;
+/**
+ * Compute the deduped union of declared permissions across every shard
+ * and app exported by a bundle. For a plain shard or app bundle this is
+ * just that manifest's permissions; for combos it merges both halves.
+ */
+export declare function extractBundlePermissions(loaded: LoadedBundle): string[];