@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/serve/worker/durable-persistence.ts

@@ -0,0 +1,137 @@
+import { sandbox as authOps } from 'pyric/auth';
+import {
+  bundleRecords,
+  parseBundle,
+  serializeToBuckets,
+  type PersistenceBackend,
+} from 'pyric/sandbox';
+import type { InitPayload } from '../namespace.js';
+import { ensureAuth, type HostCtx } from './host.js';
+
+export interface DurablePersistenceEnv {
+  fetch: typeof fetch;
+  captureDebounceMs?: number;
+}
+
+const WORKER_WRITER_ID = 'pyric-shared-worker';
+
+const stateSection = (name: 'firestore' | 'auth'): string => `/__pyric/state?section=${name}`;
+
+/** Add the committable server-file or seed-fixture tier to the worker's IDB store. */
+export function createWorkerDurableBackend(
+  idb: PersistenceBackend,
+  payload: InitPayload,
+  env: DurablePersistenceEnv,
+): PersistenceBackend {
+  const persist = Boolean(payload.persist);
+  const seed = (payload.seedState ?? null) as {
+    firestore?: Record<string, Record<string, unknown>>;
+    services?: Record<string, unknown>;
+  } | null;
+  const fixtureRecords = !persist && seed != null
+    ? serializeToBuckets(seed.firestore ?? {}, seed.services ?? {}, 0)
+    : null;
+
+  if (!persist && fixtureRecords === null) return idb;
+
+  let primed = false;
+  const primeOnce = async (key: string): Promise<void> => {
+    if (primed) return;
+    primed = true;
+    if ((await idb.listRecords(key)).length > 0) return;
+    if (persist) {
+      const res = await env.fetch(stateSection('firestore'));
+      if (res.status === 200) {
+        const records = parseBundle(await res.text());
+        if (records.size > 0) await idb.putRecords(key, records);
+      }
+    } else if (fixtureRecords !== null) {
+      await idb.putRecords(key, fixtureRecords);
+    }
+  };
+
+  const mirror = async (key: string): Promise<void> => {
+    if (!persist) return;
+    try {
+      const ids = await idb.listRecords(key);
+      const all = new Map<string, unknown>();
+      for (const id of ids) {
+        const record = await idb.getRecord(key, id);
+        if (record != null) all.set(id, record);
+      }
+      const res = await env.fetch(stateSection('firestore'), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-pyric-writer': WORKER_WRITER_ID },
+        body: bundleRecords(all),
+      });
+      if (res.status === 423) {
+        console.warn('[pyric worker] --persist: server file is held by another writer; export skipped.');
+      }
+    } catch {
+      /* export sink offline; local IDB is unaffected. */
+    }
+  };
+
+  return {
+    async getRecord(key, recordId) {
+      await primeOnce(key);
+      return idb.getRecord(key, recordId);
+    },
+    async listRecords(key) {
+      await primeOnce(key);
+      return idb.listRecords(key);
+    },
+    async putRecords(key, records) {
+      await idb.putRecords(key, records);
+      await mirror(key);
+    },
+    async deleteRecords(key, recordIds) {
+      await idb.deleteRecords(key, recordIds);
+      await mirror(key);
+    },
+    async clear(key) {
+      await idb.clear(key);
+      if (!persist) return;
+      try {
+        await env.fetch(stateSection('firestore'), {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'x-pyric-writer': WORKER_WRITER_ID },
+          body: 'null',
+        });
+      } catch {
+        /* export sink offline; local IDB is unaffected. */
+      }
+    },
+  };
+}
+
+/** Mirror the auth user DB to the committable server file when persistence is enabled. */
+export function setupServerAuthFlush(
+  ctx: HostCtx,
+  payload: InitPayload,
+  env: DurablePersistenceEnv,
+): () => void {
+  if (!payload.persist) return () => {};
+  const auth = ensureAuth(ctx);
+  const debounceMs = env.captureDebounceMs ?? 400;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const flush = (): void => {
+    const body = JSON.stringify({ users: authOps.exportUsers(auth) });
+    env.fetch(stateSection('auth'), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-pyric-writer': WORKER_WRITER_ID },
+      body,
+    }).catch(() => {});
+  };
+
+  const unsubscribe = authOps.subscribeUsers(auth, () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(flush, debounceMs);
+  });
+
+  return () => {
+    if (timer) clearTimeout(timer);
+    unsubscribe();
+  };
+}

package/src/serve/worker/entry.ts

@@ -0,0 +1,223 @@
+/**
+ * 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
+ * ---------------
+ * Project-scoped: `'pyric-shared-worker:<projectKey>'`, derived inside
+ * `buildWorkerCtx` from the init payload's `projectKey` (issue #359 family —
+ * IndexedDB is origin-scoped, so the old fixed key shared one sandbox
+ * snapshot database across every project on a localhost port). The legacy
+ * `'pyric-shared-worker'` key applies only when no project identity exists
+ * (older servers, standalone workers); see `workerPersistenceKey` in
+ * serve-init.ts for the orphan-don't-delete migration decision.
+ *
+ * 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.
+ */
+
+// SharedWorkerGlobalScope is not in the default TypeScript lib (it's in
+// lib.webworker.d.ts which conflicts with lib.dom.d.ts). This entry file is
+// browser-only and only bundled with esbuild (never compiled by tsc for
+// production). We declare the minimal interface we need so tsc can type-check
+// without enabling the full webworker lib.
+interface SharedWorkerGlobalScope {
+  onconnect: ((e: MessageEvent) => void) | null;
+  close(): void;
+}
+
+import { createIndexedDBBackend } from 'pyric/sandbox';
+
+import {
+  handleMessage,
+  cleanupPort,
+  type HostCtx,
+  type PortLike,
+} from './host.js';
+import { buildWorkerCtx, type EventSourceLike } from './serve-init.js';
+import type { InboundMessage } from './protocol.js';
+import {
+  SERVICE_WORKER_CHANNEL,
+  type ServiceWorkerChannelMessage,
+} from './service-worker-channel.js';
+import { createServiceWorkerRelay } from './service-worker-relay.js';
+import { createWorkerRetirement } from './retirement.js';
+
+declare const __PYRIC_WORKER_VERSION__: string;
+const workerEpoch = typeof __PYRIC_WORKER_VERSION__ !== 'undefined'
+  ? __PYRIC_WORKER_VERSION__
+  : 'dev';
+const workerScope = self as unknown as SharedWorkerGlobalScope;
+const retirement = createWorkerRetirement({
+  closeWorker: () => workerScope.close(),
+  beforeAnnounce: async () => { await _ctx?.captureFlush?.(); },
+});
+
+// ─── 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: HostCtx | null = null;
+let _ctxPromise: Promise<HostCtx> | null = null;
+
+/**
+ * Return the shared context, memoizing the in-flight init promise so
+ * concurrent first messages await ONE build (see `_ctxPromise` above).
+ */
+function getCtx(): Promise<HostCtx> {
+  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(): Promise<HostCtx> {
+  // 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) as unknown as EventSourceLike
+        : 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.
+ */
+workerScope.onconnect = (e: MessageEvent) => {
+  const port = e.ports[0];
+  port.start();
+  retirement.connect(port);
+
+  let messageQueue = Promise.resolve();
+  port.onmessage = (ev: MessageEvent<InboundMessage>) => {
+    if (ev.data.t === 'op' && ev.data.method === 'getRuntimeEpoch') {
+      port.postMessage({
+        t: 'res',
+        id: ev.data.id,
+        ok: true,
+        value: {
+          version: workerEpoch,
+        },
+      });
+      return;
+    }
+    if (ev.data.t === 'op' && ev.data.method === 'retireRuntime') {
+      void retirement.retire(port, ev.data.id, ev.data.targetEpoch);
+      return;
+    }
+    if (!retirement.accepting()) {
+      if ('id' in ev.data) {
+        port.postMessage({
+          t: 'res', id: ev.data.id, ok: false,
+          error: { code: 'pyric/worker-retiring', message: 'The Pyric worker is restarting.' },
+        });
+      }
+      return;
+    }
+    // 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 as unknown as PortLike, ev.data);
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        console.error('[pyric worker] message handler error:', (e as Error)?.stack ?? e, 'msg:', ev.data);
+      }
+    });
+    retirement.track(port, messageQueue);
+  };
+
+  // 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', () => {
+    retirement.disconnect(port);
+    if (_ctx) cleanupPort(_ctx, port as unknown as PortLike);
+  });
+};
+
+// 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 as Error)?.stack ?? error,
+        'msg:',
+        envelope,
+      );
+    },
+  });
+  channel.onmessage = (event: MessageEvent<ServiceWorkerChannelMessage>) => {
+    const envelope = event.data;
+    if (envelope.direction !== 'host') return;
+    // A generation-targeted replacement can briefly overlap this old worker
+    // with its successor. Only the accepting generation may answer the shared
+    // service-worker relay channel, otherwise both workers would reply.
+    if (!retirement.accepting()) return;
+    const work = relay.handle(envelope);
+    retirement.trackDetached(work);
+  };
+}

package/src/serve/worker/host/admin-firestore.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 { snapshotDocuments } from 'pyric/sandbox/firestore';
+import { type HostCtx, type PortLike, ok, fail, bestEffortFlush } from '../host-context.js';
+
+/** The admin-lens op methods routed to {@link handleAdminFirestoreOp}. */
+const ADMIN_METHODS = new Set<string>([
+  'admin.getDocument',
+  'admin.listDocuments',
+  'admin.setDocument',
+  'admin.deleteDocument',
+  'admin.readState',
+]);
+
+export function isAdminFirestoreOp(method: OpMessage['method']): boolean {
+  return ADMIN_METHODS.has(method);
+}
+
+export async function handleAdminFirestoreOp(
+  ctx: HostCtx,
+  port: PortLike,
+  msg: OpMessage,
+): Promise<void> {
+  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 as Record<string, unknown>);
+        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: Record<string, unknown> = {};
+        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 as { method: unknown }).method)}`));
+    }
+  }
+}

package/src/serve/worker/host/connection.ts

@@ -0,0 +1,179 @@
+/**
+ * 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 { serializeToBuckets, bundleRecords, parseBundle, deserializeFromBuckets } from 'pyric/sandbox';
+
+import type { OpMessage } from '../protocol.js';
+import { type HostCtx, type PortLike, ok, fail } from '../host-context.js';
+
+/** Build hash injected by the bundler's esbuild `define`. Undefined when the
+ *  compiled host is imported directly (tests) — guarded with `typeof`. */
+declare const __PYRIC_WORKER_VERSION__: string;
+
+/**
+ * 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(): string {
+  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: PersistenceBackend): Promise<string> {
+  const rec = (await idb.getRecord(INSTANCE_ID_KEY, 'id')) as { value?: string } | undefined;
+  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?: PersistenceBackend): Promise<string[]> {
+  if (!idb) return [];
+  const rec = (await idb.getRecord(BRANCH_REGISTRY_KEY, 'names')) as { value?: string[] } | undefined;
+  return Array.isArray(rec?.value) ? rec.value : [];
+}
+
+async function writeBranchRegistry(idb: PersistenceBackend, names: string[]): Promise<void> {
+  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<string>([
+  'getVersion',
+  'exportState',
+  'importState',
+  'saveBranch',
+  'listBranches',
+  'switchBranch',
+  'deleteBranch',
+]);
+
+export function isConnectionOp(method: OpMessage['method']): boolean {
+  return CONNECTION_METHODS.has(method);
+}
+
+export async function handleConnectionOp(
+  ctx: HostCtx,
+  port: PortLike,
+  msg: OpMessage,
+): Promise<void> {
+  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')) as { value?: string } | undefined)
+        : 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 as { method: unknown }).method)}`));
+    }
+  }
+}