@pyric/cli 0.1.0-alpha.9

package/dist/serve/worker/entry.js

@@ -0,0 +1,144 @@
+/**
+ * SharedWorker entry point — the actual SharedWorker script.
+ *
+ * WHY A SEPARATE ENTRY
+ * --------------------
+ * `host.ts` is pure-ish: it accepts an injected `{ db, sandbox }` and
+ * fake ports, so tests can drive it without a real SharedWorker runtime.
+ * This file is the integration shell: it creates the ONE real sandbox,
+ * attaches IDB persistence, deploys permissive starter rules, and wires
+ * every connecting port to `handleMessage`.
+ *
+ * Do NOT import this file in tests — import `host.ts` directly.
+ *
+ * LIFECYCLE
+ * ---------
+ * The SharedWorker lives while at least one tab holds a port. When all
+ * tabs close or navigate away, the worker is GC'd. IDB persistence means
+ * data survives full close → reopen cycles: on the next connect the sandbox
+ * restores from IDB, and the tab reconnects to a warm state.
+ *
+ * PERSISTENCE KEY
+ * ---------------
+ * Using `'pyric-shared-worker'` as the IDB persistence key. This is a
+ * package-level default; serve integration (Phase 3) may want to scope
+ * it per-project or per-port. Phase 1 keeps it simple.
+ *
+ * RULES
+ * -----
+ * We deploy a permissive starter ruleset on first init. Callers change
+ * rules at runtime via `{ t:'op', method:'setRules', source }` messages.
+ *
+ * SINGLE SANDBOX GUARANTEE
+ * ------------------------
+ * `_ctx` is module-level. The first `connect` event lazily creates it;
+ * all subsequent ports reuse the same ctx — one sandbox, one Firestore
+ * backend for all tabs. This is the architectural invariant the whole
+ * SharedWorker approach depends on.
+ */
+import { createIndexedDBBackend } from 'pyric/sandbox';
+import { handleMessage, cleanupPort, } from './host.js';
+import { buildWorkerCtx } from './serve-init.js';
+import { SERVICE_WORKER_CHANNEL, } from './service-worker-channel.js';
+import { createServiceWorkerRelay } from './service-worker-relay.js';
+// ─── Singleton context ────────────────────────────────────────────────────
+// `_ctx` is the RESOLVED context, kept for the synchronous `close` handler.
+// The build is memoized as a PROMISE (`_ctxPromise`) — NOT as the resolved
+// value — because init is async (it awaits `/__pyric/init.json` + persistence
+// restore). The first messages arrive in a BURST (the authState sub, the first
+// firestore sub, an op — possibly across two tabs at once); if each re-checked
+// only the resolved `_ctx` they would every one start a fresh init and build a
+// SEPARATE sandbox, so a listener and a write could bind to different
+// instances and never see each other. The promise memo guarantees ONE init.
+let _ctx = null;
+let _ctxPromise = null;
+/**
+ * Return the shared context, memoizing the in-flight init promise so
+ * concurrent first messages await ONE build (see `_ctxPromise` above).
+ */
+function getCtx() {
+    return (_ctxPromise ??= buildCtx());
+}
+/**
+ * Build the ONE shared sandbox + Firestore handle. Invoked exactly once per
+ * worker lifetime via the `getCtx` memo — never concurrently. The real boot
+ * logic lives in `buildWorkerCtx` (serve-init.ts) so it is testable without
+ * a SharedWorker runtime; this shell only supplies the real ambients.
+ *
+ * NOTE (#754): no worker-side session restore. Sessions are per-port; each
+ * PAGE re-establishes its own session from web storage via
+ * `auth.restorePortSession` (runtime.ts). The user DB itself is restored
+ * from the persisted snapshot inside buildWorkerCtx (#629).
+ */
+async function buildCtx() {
+    // ONE IDB backend for the whole worker. createIndexedDBBackend's guard
+    // checks `typeof indexedDB === 'undefined'` — SharedWorkers have full
+    // IndexedDB access, so this succeeds. The persistence controller's
+    // window.addEventListener('beforeunload', ...) is guarded by
+    // `typeof window !== 'undefined'`, so enablePersistence is worker-safe.
+    const ctx = await buildWorkerCtx({
+        fetch,
+        idb: createIndexedDBBackend(),
+        // EventSource is available in workers; guard anyway for exotic hosts.
+        makeEventSource: typeof EventSource !== 'undefined'
+            ? (url) => new EventSource(url)
+            : null,
+    });
+    _ctx = ctx; // publish the resolved ctx for the synchronous close handler
+    return ctx;
+}
+// ─── SharedWorker connect handler ─────────────────────────────────────────
+/**
+ * `self` in a SharedWorker is `SharedWorkerGlobalScope`, not `Window`.
+ * Each tab that opens the SharedWorker fires one `connect` event.
+ * Each tab gets its own `MessagePort`; we start() it (required for
+ * classic-mode workers to un-pause the message queue) and wire onmessage.
+ */
+self.onconnect = (e) => {
+    const port = e.ports[0];
+    port.start();
+    let messageQueue = Promise.resolve();
+    port.onmessage = (ev) => {
+        // Serialize each port's frames. A disconnect acknowledgement therefore
+        // cannot overtake an already-posted mutation, and later frames see the
+        // disconnected-port tombstone instead of touching the shared backend.
+        messageQueue = messageQueue.then(async () => {
+            try {
+                const ctx = await getCtx();
+                await handleMessage(ctx, port, ev.data);
+            }
+            catch (e) {
+                // eslint-disable-next-line no-console
+                console.error('[pyric worker] message handler error:', e?.stack ?? e, 'msg:', ev.data);
+            }
+        });
+    };
+    // Best-effort port cleanup on tab close/navigation.
+    // Chrome doesn't reliably fire 'close' on MessagePort — handled as
+    // best-effort; subscriptions also GC when the worker itself dies.
+    port.addEventListener('close', () => {
+        if (_ctx)
+            cleanupPort(_ctx, port);
+    });
+};
+// ServiceWorkerGlobalScope cannot construct a SharedWorker, but both worker
+// kinds share BroadcastChannel. Adapt each SW app connection to the host's
+// existing PortLike seam so it reaches this exact context/broker instead of
+// constructing a second in-Service-Worker sandbox.
+if (typeof BroadcastChannel !== 'undefined') {
+    const channel = new BroadcastChannel(SERVICE_WORKER_CHANNEL);
+    const relay = createServiceWorkerRelay({
+        getCtx,
+        send(message) { channel.postMessage(message); },
+        onError(error, envelope) {
+            console.error('[pyric worker] service-worker relay error:', error?.stack ?? error, 'msg:', envelope);
+        },
+    });
+    channel.onmessage = (event) => {
+        const envelope = event.data;
+        if (envelope.direction !== 'host')
+            return;
+        void relay.handle(envelope);
+    };
+}
+//# sourceMappingURL=entry.js.map

package/dist/serve/worker/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../src/serve/worker/entry.ts"],"names":[],"mappings":"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"}

package/dist/serve/worker/host/admin-firestore.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SharedWorker host — admin-lens Firestore document ops (rules bypass).
+ *
+ * The `admin.*` surface used by the pyric-admin remote arm + Pyric Studio's
+ * "edit anything as admin": direct document get/list/set/delete against the
+ * sandbox admin plane, plus `admin.readState` (a prefix/depth-scoped snapshot
+ * of the whole store through the cached admin handle).
+ *
+ * Routed here by the host dispatcher. These ops act on `ctx.sandbox.admin` /
+ * the admin handle directly, so they take no resolved `db`. Never imports the
+ * dispatcher.
+ */
+import type { OpMessage } from '../protocol.js';
+import { type HostCtx, type PortLike } from '../host-context.js';
+export declare function isAdminFirestoreOp(method: OpMessage['method']): boolean;
+export declare function handleAdminFirestoreOp(ctx: HostCtx, port: PortLike, msg: OpMessage): Promise<void>;
+//# sourceMappingURL=admin-firestore.d.ts.map

package/dist/serve/worker/host/admin-firestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-firestore.d.ts","sourceRoot":"","sources":["../../../../src/serve/worker/host/admin-firestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAA6B,MAAM,oBAAoB,CAAC;AAW5F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,OAAO,CAEvE;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,IAAI,CAAC,CAqDf"}

package/dist/serve/worker/host/admin-firestore.js

@@ -0,0 +1,92 @@
+/**
+ * SharedWorker host — admin-lens Firestore document ops (rules bypass).
+ *
+ * The `admin.*` surface used by the pyric-admin remote arm + Pyric Studio's
+ * "edit anything as admin": direct document get/list/set/delete against the
+ * sandbox admin plane, plus `admin.readState` (a prefix/depth-scoped snapshot
+ * of the whole store through the cached admin handle).
+ *
+ * Routed here by the host dispatcher. These ops act on `ctx.sandbox.admin` /
+ * the admin handle directly, so they take no resolved `db`. Never imports the
+ * dispatcher.
+ */
+import { snapshotDocuments } from 'pyric/sandbox/firestore';
+import { ok, fail, bestEffortFlush } from '../host-context.js';
+/** The admin-lens op methods routed to {@link handleAdminFirestoreOp}. */
+const ADMIN_METHODS = new Set([
+    'admin.getDocument',
+    'admin.listDocuments',
+    'admin.setDocument',
+    'admin.deleteDocument',
+    'admin.readState',
+]);
+export function isAdminFirestoreOp(method) {
+    return ADMIN_METHODS.has(method);
+}
+export async function handleAdminFirestoreOp(ctx, port, msg) {
+    switch (msg.method) {
+        case 'admin.getDocument': {
+            try {
+                ok(port, msg.id, ctx.sandbox.admin.getDocument(msg.path));
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'admin.listDocuments': {
+            try {
+                ok(port, msg.id, ctx.sandbox.admin.listDocuments(msg.path));
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'admin.setDocument': {
+            try {
+                ctx.sandbox.admin.setDocument(msg.path, msg.data);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'admin.deleteDocument': {
+            try {
+                const deleted = ctx.sandbox.admin.deleteDocument(msg.path);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, deleted);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'admin.readState': {
+            try {
+                const snap = snapshotDocuments(ctx.sandbox);
+                const out = {};
+                const prefix = msg.path ?? '';
+                for (const [path, data] of Object.entries(snap)) {
+                    if (prefix && !path.startsWith(prefix))
+                        continue;
+                    if (msg.maxDepth !== undefined && path.split('/').length > msg.maxDepth)
+                        continue;
+                    out[path] = data;
+                }
+                ok(port, msg.id, out);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        default: {
+            fail(port, msg.id, new Error(`Unknown method: ${String(msg.method)}`));
+        }
+    }
+}
+//# sourceMappingURL=admin-firestore.js.map

package/dist/serve/worker/host/admin-firestore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-firestore.js","sourceRoot":"","sources":["../../../../src/serve/worker/host/admin-firestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAA+B,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE5F,0EAA0E;AAC1E,MAAM,aAAa,GAAG,IAAI,GAAG,CAAS;IACpC,mBAAmB;IACnB,qBAAqB;IACrB,mBAAmB;IACnB,sBAAsB;IACtB,iBAAiB;CAClB,CAAC,CAAC;AAEH,MAAM,UAAU,kBAAkB,CAAC,MAA2B;IAC5D,OAAO,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,GAAY,EACZ,IAAc,EACd,GAAc;IAEd,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;QACnB,KAAK,mBAAmB,CAAC,CAAC,CAAC;YACzB,IAAI,CAAC;gBACH,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5D,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAAC,CAAC;YACtC,MAAM;QACR,CAAC;QAED,KAAK,qBAAqB,CAAC,CAAC,CAAC;YAC3B,IAAI,CAAC;gBACH,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9D,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAAC,CAAC;YACtC,MAAM;QACR,CAAC;QAED,KAAK,mBAAmB,CAAC,CAAC,CAAC;YACzB,IAAI,CAAC;gBACH,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,IAA+B,CAAC,CAAC;gBAC7E,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC;gBAC3B,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAAC,CAAC;YACtC,MAAM;QACR,CAAC;QAED,KAAK,sBAAsB,CAAC,CAAC,CAAC;YAC5B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAC3D,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC;gBAC3B,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;YAC5B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAAC,CAAC;YACtC,MAAM;QACR,CAAC;QAED,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAC5C,MAAM,GAAG,GAA4B,EAAE,CAAC;gBACxC,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;gBAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBAChD,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;wBAAE,SAAS;oBACjD,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,QAAQ;wBAAE,SAAS;oBAClF,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;gBACnB,CAAC;gBACD,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YACxB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAAC,CAAC;YACtC,MAAM;QACR,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YACR,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,KAAK,CAAC,mBAAmB,MAAM,CAAE,GAA2B,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/serve/worker/host/connection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SharedWorker host — connection / instance / state-transfer ops.
+ *
+ * The worker-lifecycle surface the client's `connection` family talks to:
+ *   - `getVersion` (build hash + per-worker instance id),
+ *   - full-state transfer (`exportState`/`importState`, the portable bundle),
+ *   - named branches (`saveBranch`/`listBranches`/`switchBranch`/`deleteBranch`,
+ *     saved-state bundles in the RAW idb).
+ *
+ * Owns the stable per-worker instance id (persisted to the raw idb) and the
+ * branch registry helpers. `getOrCreateInstanceId` is imported by serve-init;
+ * the instance-id + branch constants/helpers are part of the host's public
+ * surface (re-exported by the host barrel). Never imports the dispatcher.
+ */
+import type { PersistenceBackend } from 'pyric/sandbox';
+import type { OpMessage } from '../protocol.js';
+import { type HostCtx, type PortLike } from '../host-context.js';
+/**
+ * Per-SharedWorker instance id — generated once and persisted to the RAW idb
+ * (local-only, like the session record above; it must NEVER reach the
+ * committable server file). Because IndexedDB is per (origin + browser profile),
+ * two profiles on the same `localhost:<port>` get two distinct ids — which is
+ * exactly how the UI tells same-port-different-profile sandboxes apart.
+ */
+export declare const INSTANCE_ID_KEY = "pyric:worker:instance";
+/**
+ * `crypto.randomUUID()` is secure-context-only (https or localhost), so it is
+ * `undefined` over plain http on a non-localhost host (a Tailscale or LAN
+ * hostname). `crypto.getRandomValues` is NOT gated, so build a v4 UUID from it as
+ * the fallback. Without this the worker throws on init over Tailscale and the
+ * whole sandbox (auth, firestore, bridge) silently fails to come up.
+ */
+export declare function randomUuid(): string;
+export declare function getOrCreateInstanceId(idb: PersistenceBackend): Promise<string>;
+export declare const BRANCH_PREFIX = "pyric:worker:branch:";
+export declare const BRANCH_REGISTRY_KEY = "pyric:worker:branches";
+export declare function listBranchNames(idb?: PersistenceBackend): Promise<string[]>;
+export declare function isConnectionOp(method: OpMessage['method']): boolean;
+export declare function handleConnectionOp(ctx: HostCtx, port: PortLike, msg: OpMessage): Promise<void>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/serve/worker/host/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/serve/worker/host/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAY,MAAM,oBAAoB,CAAC;AAM3E;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,0BAA0B,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAOnC;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMpF;AAQD,eAAO,MAAM,aAAa,yBAAyB,CAAC;AACpD,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,wBAAsB,eAAe,CAAC,GAAG,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIjF;AAiBD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,OAAO,CAEnE;AAED,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,IAAI,CAAC,CAkFf"}

package/dist/serve/worker/host/connection.js

@@ -0,0 +1,153 @@
+/**
+ * SharedWorker host — connection / instance / state-transfer ops.
+ *
+ * The worker-lifecycle surface the client's `connection` family talks to:
+ *   - `getVersion` (build hash + per-worker instance id),
+ *   - full-state transfer (`exportState`/`importState`, the portable bundle),
+ *   - named branches (`saveBranch`/`listBranches`/`switchBranch`/`deleteBranch`,
+ *     saved-state bundles in the RAW idb).
+ *
+ * Owns the stable per-worker instance id (persisted to the raw idb) and the
+ * branch registry helpers. `getOrCreateInstanceId` is imported by serve-init;
+ * the instance-id + branch constants/helpers are part of the host's public
+ * surface (re-exported by the host barrel). Never imports the dispatcher.
+ */
+import { serializeToBuckets, bundleRecords, parseBundle, deserializeFromBuckets } from 'pyric/sandbox';
+import { ok, fail } from '../host-context.js';
+/**
+ * Per-SharedWorker instance id — generated once and persisted to the RAW idb
+ * (local-only, like the session record above; it must NEVER reach the
+ * committable server file). Because IndexedDB is per (origin + browser profile),
+ * two profiles on the same `localhost:<port>` get two distinct ids — which is
+ * exactly how the UI tells same-port-different-profile sandboxes apart.
+ */
+export const INSTANCE_ID_KEY = 'pyric:worker:instance';
+/**
+ * `crypto.randomUUID()` is secure-context-only (https or localhost), so it is
+ * `undefined` over plain http on a non-localhost host (a Tailscale or LAN
+ * hostname). `crypto.getRandomValues` is NOT gated, so build a v4 UUID from it as
+ * the fallback. Without this the worker throws on init over Tailscale and the
+ * whole sandbox (auth, firestore, bridge) silently fails to come up.
+ */
+export function randomUuid() {
+    if (typeof crypto.randomUUID === 'function')
+        return crypto.randomUUID();
+    const b = crypto.getRandomValues(new Uint8Array(16));
+    b[6] = (b[6] & 0x0f) | 0x40;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = Array.from(b, (x) => x.toString(16).padStart(2, '0'));
+    return `${h.slice(0, 4).join('')}-${h.slice(4, 6).join('')}-${h.slice(6, 8).join('')}-${h.slice(8, 10).join('')}-${h.slice(10, 16).join('')}`;
+}
+export async function getOrCreateInstanceId(idb) {
+    const rec = (await idb.getRecord(INSTANCE_ID_KEY, 'id'));
+    if (rec && typeof rec.value === 'string')
+        return rec.value;
+    const id = randomUuid();
+    await idb.putRecords(INSTANCE_ID_KEY, new Map([['id', { value: id }]]));
+    return id;
+}
+// ── Phase 3: named branches ─────────────────────────────────────────────────
+// A branch is a named saved state bundle in the RAW idb (local-only, like the
+// instance id + session; it must NEVER reach the committable server file). They
+// let one instance keep several named states it can switch between
+// (switchBranch = loadSnapshot the bundle, a clobber). A registry record holds
+// the ordered name list, since the backend lists records WITHIN a key, not keys.
+export const BRANCH_PREFIX = 'pyric:worker:branch:';
+export const BRANCH_REGISTRY_KEY = 'pyric:worker:branches';
+export async function listBranchNames(idb) {
+    if (!idb)
+        return [];
+    const rec = (await idb.getRecord(BRANCH_REGISTRY_KEY, 'names'));
+    return Array.isArray(rec?.value) ? rec.value : [];
+}
+async function writeBranchRegistry(idb, names) {
+    await idb.putRecords(BRANCH_REGISTRY_KEY, new Map([['names', { value: names }]]));
+}
+/** The connection/state/branch op methods routed to {@link handleConnectionOp}. */
+const CONNECTION_METHODS = new Set([
+    'getVersion',
+    'exportState',
+    'importState',
+    'saveBranch',
+    'listBranches',
+    'switchBranch',
+    'deleteBranch',
+]);
+export function isConnectionOp(method) {
+    return CONNECTION_METHODS.has(method);
+}
+export async function handleConnectionOp(ctx, port, msg) {
+    switch (msg.method) {
+        case 'getVersion': {
+            // The build hash is injected by the bundler (esbuild `define`). `typeof`
+            // guards the non-bundled path (tests import the compiled host directly,
+            // where the global is undefined) → reports 'dev'.
+            ok(port, msg.id, {
+                version: typeof __PYRIC_WORKER_VERSION__ !== 'undefined' ? __PYRIC_WORKER_VERSION__ : 'dev',
+                instanceId: ctx.instanceId,
+            });
+            break;
+        }
+        case 'exportState': {
+            // Phase 2 (transfer): serialize the FULL sandbox state to a portable bundle
+            // string using the SAME chunk format the persist layer uses, so wrapper
+            // types (Timestamp / Bytes / GeoPoint / VectorValue) round-trip. The string
+            // crosses the MessagePort cleanly (unlike the raw snapshot object).
+            const snap = ctx.sandbox.snapshot();
+            ok(port, msg.id, { bundle: bundleRecords(serializeToBuckets(snap.firestore, snap.services, 0)) });
+            break;
+        }
+        case 'importState': {
+            // Phase 2 (clobber): replace this sandbox's ENTIRE state with the imported
+            // bundle via the public loadSnapshot() (reset + rebuild firestore + restore
+            // services; listeners re-evaluate, persist re-flushes).
+            ctx.sandbox.loadSnapshot(deserializeFromBuckets(parseBundle(msg.bundle)));
+            ok(port, msg.id, { ok: true });
+            break;
+        }
+        case 'saveBranch': {
+            // Phase 3: snapshot the live sandbox into a named branch bundle (raw idb).
+            if (!ctx.sessionBackend) {
+                ok(port, msg.id, { ok: false, error: 'no persistence backend' });
+                break;
+            }
+            const snap = ctx.sandbox.snapshot();
+            const bundle = bundleRecords(serializeToBuckets(snap.firestore, snap.services, 0));
+            await ctx.sessionBackend.putRecords(BRANCH_PREFIX + msg.name, new Map([['bundle', { value: bundle }]]));
+            const names = await listBranchNames(ctx.sessionBackend);
+            if (!names.includes(msg.name))
+                await writeBranchRegistry(ctx.sessionBackend, [...names, msg.name]);
+            ok(port, msg.id, { ok: true });
+            break;
+        }
+        case 'listBranches': {
+            ok(port, msg.id, { branches: await listBranchNames(ctx.sessionBackend) });
+            break;
+        }
+        case 'switchBranch': {
+            // Phase 3: loadSnapshot the named branch bundle (a clobber).
+            const rec = ctx.sessionBackend
+                ? (await ctx.sessionBackend.getRecord(BRANCH_PREFIX + msg.name, 'bundle'))
+                : undefined;
+            if (!rec?.value) {
+                ok(port, msg.id, { ok: false, error: `no such branch: ${msg.name}` });
+                break;
+            }
+            ctx.sandbox.loadSnapshot(deserializeFromBuckets(parseBundle(rec.value)));
+            ok(port, msg.id, { ok: true });
+            break;
+        }
+        case 'deleteBranch': {
+            if (ctx.sessionBackend) {
+                await ctx.sessionBackend.clear(BRANCH_PREFIX + msg.name);
+                await writeBranchRegistry(ctx.sessionBackend, (await listBranchNames(ctx.sessionBackend)).filter((n) => n !== msg.name));
+            }
+            ok(port, msg.id, { ok: true });
+            break;
+        }
+        default: {
+            fail(port, msg.id, new Error(`Unknown method: ${String(msg.method)}`));
+        }
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/serve/worker/host/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../../src/serve/worker/host/connection.ts"],"names":[],"mappings":"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"}

package/dist/serve/worker/host/core.d.ts

@@ -0,0 +1,159 @@
+/**
+ * SharedWorker host — shared resolution layer (host/core.ts).
+ *
+ * The helpers every firestore-touching family module leans on:
+ *   - the auth-lens → live-handle resolvers (`lensDb`/`lensRtdb`/`sessionDb`/…),
+ *     the single place a per-op `actAs` lens or a port session becomes a live
+ *     Firestore/RTDB handle;
+ *   - descriptor → live ref/query resolution (`resolveTarget`/`resolveConstraint`),
+ *     used by both the read ops and the subscription handlers;
+ *   - cross-port snapshot serialization (`serializeDocSnap`);
+ *   - `opProvenance`, the issue-time provenance both the ambient-provenance
+ *     window (dispatch) and the storage ops (explicit thread) read.
+ *
+ * Genuinely-shared STATE lives on `HostCtx` (host-context.ts) — the dependency
+ * root. This module adds the shared FUNCTIONS that resolve against that state;
+ * it imports the pyric firestore/database engine, so it is deliberately kept
+ * out of host-context.ts (which stays engine-free).
+ */
+import { type Firestore, type DocumentReference, type CollectionReference, type Query } from 'pyric/firestore';
+import { type Database } from 'pyric/database';
+import type { AuthLens, EventProvenance } from 'pyric/sandbox';
+import type { MintedSession } from 'pyric/auth';
+import type { InboundMessage, TargetDescriptor } from '../protocol.js';
+import { type HostCtx, type PortLike } from '../host-context.js';
+/**
+ * Resolve a TargetDescriptor into a live pyric ref or query.
+ *
+ * WHY WE RESOLVE ON THE WORKER
+ * The client never holds live pyric refs — it holds plain `DocRef`/
+ * `CollRef`/`GroupRef`/`QueryDescriptor` objects that serialize cleanly
+ * across the MessagePort. On every op the worker rebuilds the live ref
+ * from these descriptors. This keeps the client completely stateless with
+ * respect to sandbox internals and makes retries trivially correct.
+ */
+export declare function resolveTarget(db: Firestore, target: TargetDescriptor): DocumentReference | CollectionReference | Query;
+/**
+ * Serialize a document snapshot to cross-port form.
+ * Uses JSON-via-serializeDocData so Timestamp/Bytes/LatLng survive.
+ */
+export declare function serializeDocSnap(snap: {
+    id: string;
+    path?: string;
+    ref?: {
+        path?: string;
+    };
+    exists: boolean | (() => boolean);
+    data(): Record<string, unknown> | undefined;
+}): {
+    id: string;
+    path?: string;
+    exists: boolean;
+    data?: {
+        json: string;
+    };
+};
+/**
+ * Resolve the Firestore handle an op runs against, given its `actAs` lens
+ * (Pyric Studio auth lens, T2 — implements the C2 protocol seam).
+ *
+ * Resolution by `actAs.mode` (absent ⇒ the app's session):
+ *
+ *   - `app-session` (and `actAs` absent): `ctx.db` — the shared sandbox-live
+ *     handle. Reads `sandbox.currentUser` per op, so rules evaluate under
+ *     whoever the served app is signed in as. This is the unchanged default
+ *     and the ONLY lens the app itself ever uses.
+ *
+ *   - `{ mode: 'as', uid }` (impersonation — the rules-debugging primitive):
+ *     a FROZEN-identity `getFirestore(sandbox.withAuth({ uid }))` handle.
+ *     Security rules APPLY and evaluate as that user — `request.auth.uid`
+ *     resolves to `uid`. This lets Studio "re-run this denied op as the user
+ *     who attempted it" (Wave-2 rules-debugging, F4). Handles are cached
+ *     per-uid on `ctx.lensHandles`.
+ *
+ *   - `{ mode: 'admin' }` (rule bypass): a modular `getAdminFirestore(sandbox)`
+ *     handle (pyric Gap #2) whose ops skip security-rule evaluation while still
+ *     reading/writing the same store and emitting events. This is Studio's
+ *     "edit anything as admin" surface (F2). Cached on `ctx.adminDb`.
+ *
+ *   - `{ mode: 'anon' }` (explicitly unauthenticated): a frozen
+ *     `getFirestore(sandbox.withAuth(null))` handle — rules apply with
+ *     `request.auth == null`. The remote arm's `withAuth(null)`; distinct from
+ *     an ABSENT lens, which resolves to the port's session. Cached on
+ *     `ctx.anonDb`.
+ *
+ * WRITE-IMPERSONATION GATING (open micro-decision #1, honoured): the resolver
+ * itself is symmetric — an `{ mode: 'as', uid }` lens applies to BOTH reads and
+ * writes (a write-as-user is denied/allowed exactly as that user's rules say).
+ * The POLICY decision — "read-as-user always; write-as-user only on an explicit
+ * reproduce path" — is enforced at the CALLER (the Studio client / UI chooses
+ * when to attach a write op's `actAs`), NOT here. Default behaviour stays admin/
+ * app-session unless a caller sets `actAs`; no UI is added by T2.
+ */
+export declare function lensDb(ctx: HostCtx, actAs?: AuthLens): Firestore;
+export declare function authStateForLens(actAs: Extract<AuthLens, {
+    mode: 'as';
+}>): {
+    uid: string;
+    token?: Record<string, unknown>;
+};
+export declare function lensCacheKey(actAs: Extract<AuthLens, {
+    mode: 'as';
+}>): string;
+/** Cache key for a real port session; claims are part of authorization identity. */
+export declare function sessionCacheKey(session: MintedSession): string;
+/**
+ * Normalise a per-op `actAs` lens to the {@link AuthLens} provenance shape that
+ * the unified sandbox event stream stamps on each event's `authLens` field.
+ *
+ * Absent ⇒ `{ mode: 'app-session' }` (the app's own session) — matching how
+ * `EventProvenance.authLens` reads when omitted. C1 added the field to events;
+ * T1 owns the EMIT path that actually writes it. T2's job is to thread the lens
+ * THROUGH the host so T1 has the value at emit time: see the call in `handleOp`
+ * where the resolved lens is passed to the sandbox via `withLens` when that
+ * emit seam exists. Today the sandbox event emitters infer `authLens` from the
+ * acting identity (the impersonation handle's frozen `auth` is `{ uid }`, so a
+ * rules eval already carries that uid); this helper exists so the host has a
+ * single canonical normaliser when the explicit emit-time stamp lands.
+ */
+export declare function lensProvenance(actAs?: AuthLens): AuthLens;
+/**
+ * Resolve the data handle for an op/sub carrying NO explicit lens: the
+ * PORT'S SESSION (#754). A signed-in port gets a per-session-token cached
+ * `getFirestore(sandbox.withAuth(session.state))` handle — rules evaluate
+ * under its uid + custom claims, exactly like a globally signed-in user. A
+ * signed-out port falls back to `ctx.db` (sandbox-live; `currentUser` is
+ * never set in served mode, so that is the unauthenticated view).
+ *
+ * This is NOT the impersonation lens: the session was minted by validated
+ * sign-in on this port (`sandbox.mintSession`), so both reads and writes
+ * legitimately run as that user — the write-impersonation gate on the
+ * Studio `as` lens does not apply to a port's own session.
+ *
+ * Claim changes become visible when the client forces an ID-token refresh;
+ * host-auth updates the port session, clears all session-bound service
+ * caches, and re-establishes that port's listeners under the new token.
+ */
+export declare function sessionDb(ctx: HostCtx, port: PortLike): Firestore;
+export declare function lensRtdb(ctx: HostCtx, actAs: AuthLens | undefined, port: PortLike): Database;
+export declare function ensureRtdb(ctx: HostCtx): Database;
+/**
+ * Op provenance from an inbound message, bound at ISSUE time. This is the
+ * source of truth for both the synchronous ambient window used by immediate
+ * emitters and the operation-scoped Storage handle used across awaits.
+ *
+ *   - `actor`: a client that DECLARED itself the issuer (`issuer: 'studio'`,
+ *     stamped by Studio's worker client — `setOpIssuer` in client.ts) gets
+ *     `actor: { kind: 'studio' }`. Bridge-relayed frames are forwarded
+ *     verbatim without the stamp (client.ts `relayWorkerOp`), so remote
+ *     admin/agent traffic is never mislabeled as Studio's.
+ *   - `authLens`: the op's EFFECTIVE lens (`msg.actAs`) whenever present —
+ *     independent of issuer, because admin is admin regardless of who asked
+ *     (an agent tool relay's admin op must classify as a rules BYPASS in
+ *     Traffic, not a rules allow).
+ *
+ * Returns `undefined` for a plain served-app op (no issuer, no lens); its
+ * app source and app-session lens come from the service handle itself.
+ */
+export declare function opProvenance(msg: InboundMessage): EventProvenance | undefined;
+//# sourceMappingURL=core.d.ts.map

package/dist/serve/worker/host/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/serve/worker/host/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAiBL,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,KAAK,EACX,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAEjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAKjE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,gBAAgB,GACvB,iBAAiB,GAAG,mBAAmB,GAAG,KAAK,CAcjD;AAwCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,MAAM,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IAClC,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC7C,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAY1E;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CA6BhE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAI3H;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,GAAG,MAAM,CAI7E;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAI9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAEzD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAWjE;AAeD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAoB5F;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAEjD;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,eAAe,GAAG,SAAS,CAQ7E"}