@pyric/cli 0.1.0-alpha.10 → 0.1.0-alpha.12

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

@@ -0,0 +1,312 @@
+/**
+ * SharedWorker host — worker-backed Cloud Storage ops.
+ *
+ * Object browse (`storage.listAll`/`getMetadata`), the MessagePort-only
+ * `getBlob`, and the relay-safe base64 byte transfer (`putBytes`/`getBytes`)
+ * plus idempotent `deleteObject`. Owns the storage lens resolver
+ * (`lensStorage` — the storage mirror of the firestore/rtdb lens resolvers),
+ * the lazily-created shared handle, and the wire → `SettableMetadata` mapper.
+ *
+ * Routed here by the host dispatcher. Storage dispatch is async, so the
+ * mutating ops thread the op's provenance EXPLICITLY (their events escape the
+ * dispatcher's synchronous ambient-provenance window). Never imports the
+ * dispatcher.
+ */
+
+import {
+  getStorageSandbox,
+  ref as storageRef,
+  listAll as storageListAll,
+  getMetadata as storageGetMetadata,
+  getBlob as storageGetBlob,
+  getBytes as storageGetBytes,
+  uploadBytes as storageUploadBytes,
+  deleteObject as storageDeleteObject,
+  type FirebaseStorage,
+  type SettableMetadata,
+} from 'pyric/storage';
+// Host-only rules-bypass admin plane — the storage mirror of
+// `getAdminFirestore`/`getAdminDatabase`, resolved for `actAs: { mode: 'admin' }`.
+import {
+  bindStorageOperationContext,
+  getAdminStorageSandbox,
+} from 'pyric/storage/internal';
+import type { AuthLens } from 'pyric/sandbox';
+import { bindOperationContext } from 'pyric/sandbox/internal';
+
+import type { OpMessage } from '../protocol.js';
+import {
+  bytesToBase64,
+  base64ToBytes,
+  storagePayloadTooLarge,
+  MAX_STORAGE_OP_BYTES,
+  MAX_STORAGE_OP_B64_LENGTH,
+} from '../protocol.js';
+import { type HostCtx, type PortLike, ok, fail } from '../host-context.js';
+import { authStateForLens, lensCacheKey, opProvenance, sessionCacheKey } from './core.js';
+import { portSession } from '../host-auth.js';
+
+/** The shared Storage handle, lazily created (Pyric Studio data browse): one per
+ *  worker, directly over the shared sandbox. The high-level
+ *  `pyric/storage` ops enforce rules, so the host reads through them. */
+function ensureStorage(ctx: HostCtx): FirebaseStorage {
+  return (ctx.storage ??= getStorageSandbox(bindOperationContext(ctx.sandbox.withAuth(null), {
+    source: { kind: 'app' },
+    authLens: { mode: 'app-session' },
+  })));
+}
+
+/**
+ * Resolve the Storage handle a storage op runs against, given its `actAs`
+ * lens — the storage mirror of {@link lensRtdb}:
+ *
+ *   - absent / `app-session` → a handle carrying the initiating port's Auth
+ *     session, or the shared anonymous handle when that port is signed out.
+ *     Storage rules apply only when the HOST
+ *     configured them on this sandbox's storage service (first call per
+ *     sandbox wins) — the SERVED worker configures them via
+ *     `applyServeInit` (`serve-init.ts`), which opens the storage service
+ *     with `payload.storageRules` BEFORE any op can reach `ensureStorage`/
+ *     `lensStorage`, so every lens on a served worker enforces the
+ *     project's storage.rules (or runs open when the project has none,
+ *     matching Firestore/RTDB's no-rules posture). The lens split still
+ *     matters for embedding/test hosts that open the service directly.
+ *   - `{ mode: 'admin' }` → the rules-BYPASS handle from
+ *     `pyric/storage/internal`'s admin plane — same per-sandbox store +
+ *     ruleset, rule evaluation skipped (firebase-admin semantics for the
+ *     `pyric-admin` remote arm / Studio admin lens).
+ *   - `{ mode: 'as', uid }` → a frozen-identity `getStorageSandbox(
+ *     sandbox.withAuth({ uid, token? }))` handle; rules evaluate AS that
+ *     user. Cached per uid/token key on `ctx.lensStorages`.
+ */
+function sessionStorage(ctx: HostCtx, port: PortLike): FirebaseStorage {
+  const session = portSession(ctx, port);
+  if (!session) return ensureStorage(ctx);
+  const key = sessionCacheKey(session);
+  const handles = (ctx.sessionStorages ??= new Map());
+  let handle = handles.get(key);
+  if (!handle) {
+    handle = getStorageSandbox(ctx.sandbox.withAuth(session.state));
+    handles.set(key, handle);
+  }
+  return handle;
+}
+
+function lensStorage(ctx: HostCtx, actAs: AuthLens | undefined, port: PortLike): FirebaseStorage {
+  if (!actAs || actAs.mode === 'app-session') {
+    return sessionStorage(ctx, port);
+  }
+  if (actAs.mode === 'admin') {
+    return (ctx.adminStorage ??= getAdminStorageSandbox(ctx.sandbox));
+  }
+  // Genuinely unauthenticated — see the `anon` note on lensDb. Distinct from
+  // the shared page handle only when the host configured storage rules, but
+  // pinning it keeps remote `withAuth(null)` semantics uniform across services.
+  if (actAs.mode === 'anon') {
+    return (ctx.anonStorage ??= getStorageSandbox(ctx.sandbox.withAuth(null)));
+  }
+  const handles = (ctx.lensStorages ??= new Map());
+  const key = lensCacheKey(actAs);
+  let handle = handles.get(key);
+  if (!handle) {
+    handle = getStorageSandbox(ctx.sandbox.withAuth(authStateForLens(actAs)));
+    handles.set(key, handle);
+  }
+  return handle;
+}
+
+/**
+ * Map a wire `storage.putBytes` payload to `pyric/storage`'s
+ * `SettableMetadata`. The explicit `contentType` field wins; recognized
+ * settable fields are lifted from `metadata`; a GCS-style nested custom map
+ * (`metadata.metadata`, as `@google-cloud/storage`'s `save` spells it) or a
+ * pyric-style `metadata.customMetadata` becomes `customMetadata` with
+ * values coerced to strings (the storage-rules `metadata` model).
+ */
+function toSettableMetadata(msg: {
+  contentType?: string;
+  metadata?: Record<string, unknown>;
+}): SettableMetadata {
+  const md = msg.metadata ?? {};
+  const str = (key: string): string | undefined =>
+    typeof md[key] === 'string' ? (md[key] as string) : undefined;
+  const customSource = md['customMetadata'] ?? md['metadata'];
+  let customMetadata: Record<string, string> | undefined;
+  if (customSource !== null && typeof customSource === 'object' && !Array.isArray(customSource)) {
+    customMetadata = {};
+    for (const [k, v] of Object.entries(customSource as Record<string, unknown>)) {
+      customMetadata[k] = String(v);
+    }
+  }
+  const settable: SettableMetadata = {};
+  const contentType = msg.contentType ?? str('contentType');
+  if (contentType !== undefined) settable.contentType = contentType;
+  const cacheControl = str('cacheControl');
+  if (cacheControl !== undefined) settable.cacheControl = cacheControl;
+  const contentDisposition = str('contentDisposition');
+  if (contentDisposition !== undefined) settable.contentDisposition = contentDisposition;
+  const contentEncoding = str('contentEncoding');
+  if (contentEncoding !== undefined) settable.contentEncoding = contentEncoding;
+  const contentLanguage = str('contentLanguage');
+  if (contentLanguage !== undefined) settable.contentLanguage = contentLanguage;
+  if (customMetadata !== undefined) settable.customMetadata = customMetadata;
+  return settable;
+}
+
+/** The storage op methods routed to {@link handleStorageOp}. */
+const STORAGE_METHODS = new Set<string>([
+  'storage.listAll',
+  'storage.getMetadata',
+  'storage.getBlob',
+  'storage.putBytes',
+  'storage.getBytes',
+  'storage.deleteObject',
+]);
+
+export function isStorageOp(method: OpMessage['method']): boolean {
+  return STORAGE_METHODS.has(method);
+}
+
+export async function handleStorageOp(
+  ctx: HostCtx,
+  port: PortLike,
+  msg: OpMessage,
+): Promise<void> {
+  switch (msg.method) {
+    case 'storage.listAll': {
+      // Object browse. `listAll` enforces `read` rules on the scanned prefix
+      // under the op's lens (admin lens bypasses — see lensStorage).
+      try {
+        const storage = bindStorageOperationContext(
+          lensStorage(ctx, msg.actAs, port),
+          opProvenance(msg),
+        );
+        const result = await storageListAll(storageRef(storage, msg.path));
+        ok(port, msg.id, {
+          items: result.items.map((r) => ({ fullPath: r.fullPath, name: r.name })),
+          prefixes: result.prefixes.map((r) => ({ fullPath: r.fullPath, name: r.name })),
+        });
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'storage.getMetadata': {
+      try {
+        const storage = bindStorageOperationContext(
+          lensStorage(ctx, msg.actAs, port),
+          opProvenance(msg),
+        );
+        // FullMetadata is plain JSON (bucket/fullPath/name/size/contentType/...).
+        ok(
+          port,
+          msg.id,
+          await storageGetMetadata(storageRef(storage, msg.path)),
+        );
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'storage.getBlob': {
+      // MessagePort-ONLY: the Blob structured-clones to in-page callers
+      // (Studio previews) but silently corrupts under the JSON WS relay — the
+      // bridge client rejects relaying it (binary-payload guard). Remote
+      // callers use `storage.getBytes` (base64) instead.
+      try {
+        const storage = bindStorageOperationContext(
+          lensStorage(ctx, msg.actAs, port),
+          opProvenance(msg),
+        );
+        ok(
+          port,
+          msg.id,
+          await storageGetBlob(storageRef(storage, msg.path)),
+        );
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'storage.putBytes': {
+      // Byte upload (remote sandbox, slice 2). Decode-end size cap: reject an
+      // oversized base64 string BEFORE materializing its bytes, then re-check
+      // the exact decoded length. Rules enforce under the op's lens; the
+      // upload emits `service_mutation` events. Storage dispatch is async, so
+      // the event escapes the ambient-provenance window `handleMessage` opened;
+      // thread the op's provenance EXPLICITLY so a Studio-issued write is
+      // attributable end to end (issue #84 item 3).
+      try {
+        if (msg.dataB64.length > MAX_STORAGE_OP_B64_LENGTH) {
+          throw storagePayloadTooLarge(
+            Math.floor(msg.dataB64.length * 0.75),
+            `storage.putBytes payload for '${msg.path}'`,
+          );
+        }
+        const bytes = base64ToBytes(msg.dataB64);
+        if (bytes.byteLength > MAX_STORAGE_OP_BYTES) {
+          throw storagePayloadTooLarge(bytes.byteLength, `storage.putBytes payload for '${msg.path}'`);
+        }
+        const storage = bindStorageOperationContext(
+          lensStorage(ctx, msg.actAs, port),
+          opProvenance(msg),
+        );
+        const result = await storageUploadBytes(
+          storageRef(storage, msg.path),
+          bytes,
+          toSettableMetadata(msg),
+        );
+        // FullMetadata — plain JSON, relay-safe.
+        ok(port, msg.id, result.metadata);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'storage.getBytes': {
+      // JSON-safe byte download (remote sandbox, slice 2): base64 in the
+      // result. Encode-end size cap so a big browser-side object can't blow
+      // up the relay. Metadata is read alongside for contentType (both reads
+      // run under the same lens; rule-eval order keeps `unauthorized`
+      // superseding `not-found`, matching pyric/storage).
+      try {
+        const storage = bindStorageOperationContext(
+          lensStorage(ctx, msg.actAs, port),
+          opProvenance(msg),
+        );
+        const r = storageRef(storage, msg.path);
+        const meta = await storageGetMetadata(r);
+        if (meta.size > MAX_STORAGE_OP_BYTES) {
+          throw storagePayloadTooLarge(meta.size, `object '${msg.path}'`);
+        }
+        const buf = await storageGetBytes(r);
+        if (buf.byteLength > MAX_STORAGE_OP_BYTES) {
+          throw storagePayloadTooLarge(buf.byteLength, `object '${msg.path}'`);
+        }
+        ok(port, msg.id, {
+          dataB64: bytesToBase64(new Uint8Array(buf)),
+          contentType: meta.contentType,
+          size: buf.byteLength,
+        });
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'storage.deleteObject': {
+      // `pyric/storage`'s sandbox delete is idempotent (no-op on missing) —
+      // matching the pyric-admin local arm's delete semantics. Rules enforce
+      // `write` under the op's lens; deletes emit `service_mutation` events.
+      // Async dispatch escapes the ambient window — thread provenance
+      // explicitly (issue #84 item 3).
+      try {
+        const storage = bindStorageOperationContext(
+          lensStorage(ctx, msg.actAs, port),
+          opProvenance(msg),
+        );
+        await storageDeleteObject(storageRef(storage, msg.path));
+        ok(port, msg.id, null);
+      } 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/studio.ts

@@ -0,0 +1,75 @@
+/**
+ * SharedWorker host — Pyric Studio control ops.
+ *
+ * The sandbox-snapshot export Studio forks for rules re-run (`getSnapshot`).
+ * Kept as its own family to mirror the client's `studio` module.
+ *
+ * Routed here by the host dispatcher. Never imports the dispatcher.
+ */
+
+import { setRules } from 'pyric/sandbox/firestore';
+
+import type { OpMessage } from '../protocol.js';
+import { type HostCtx, type PortLike, ok, fail } from '../host-context.js';
+
+/** The Studio control op methods routed to {@link handleStudioOp}. */
+const STUDIO_METHODS = new Set<string>([
+  'getSnapshot',
+  'resetAll',
+]);
+
+export function isStudioOp(method: OpMessage['method']): boolean {
+  return STUDIO_METHODS.has(method);
+}
+
+export async function handleStudioOp(
+  ctx: HostCtx,
+  port: PortLike,
+  msg: OpMessage,
+): Promise<void> {
+  switch (msg.method) {
+    case 'getSnapshot': {
+      // Export the current sandbox snapshot (Pyric Studio rules re-run): Studio
+      // forks it locally to test edited rules / re-issue as the user on a branch.
+      ok(port, msg.id, ctx.sandbox.snapshot());
+      break;
+    }
+
+    case 'resetAll': {
+      // Sandbox-owned full reset (issue #359): the ONE wipe-everything path.
+      // `resetAll` iterates the worker sandbox's persistable-service registry,
+      // so auth users, the RTDB tree, AND storage objects clear along with the
+      // Firestore env — Studio can't forget a service the sandbox knows about.
+      // Awaited (storage clears IndexedDB stores) before the ack. Op-level
+      // failures reply as errors; per-service reset failures ride the reply
+      // payload's `errors` so Studio can surface a half-clear instead of
+      // reporting a clean reset.
+      try {
+        const { errors } = await ctx.sandbox.resetAll();
+        // `resetAll` swapped the env, wiping env-owned FIRESTORE rules (RTDB /
+        // storage rules live on their service objects and survive). Re-deploy
+        // the active project rules so a DATA reset never de-governs writes.
+        const firestoreRules = ctx.activeRules?.firestore;
+        const source =
+          firestoreRules?.status === 'active'
+            ? firestoreRules.source
+            : firestoreRules?.lastKnownGood;
+        if (typeof source === 'string') setRules(ctx.sandbox, source);
+        // The server capture (`.pyric/last-session.json`) persists the event
+        // history a rebooting worker re-primes into Traffic. Flush it NOW —
+        // reset just emptied `sandbox.history()`, and waiting out the
+        // capture debounce leaves a window where a worker death resurrects
+        // the wiped session's events on the next boot.
+        ctx.captureFlush?.();
+        ok(port, msg.id, { errors });
+      } catch (e) {
+        fail(port, msg.id, e instanceof Error ? e : new Error(String(e)));
+      }
+      break;
+    }
+
+    default: {
+      fail(port, msg.id, new Error(`Unknown method: ${String((msg as { method: unknown }).method)}`));
+    }
+  }
+}

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

@@ -0,0 +1,238 @@
+/**
+ * SharedWorker host — Firestore + RTDB value-subscription registry.
+ *
+ * `onSnapshot` / RTDB `onValue` listeners registered against the op's
+ * lens-resolved handle, with cross-port snapshot fan-out. Owns the
+ * session-bound sub registry (#754) that re-establishes a port's lens-less
+ * listeners under its NEW identity on every auth transition, mirroring prod's
+ * stream re-establishment (a sign-out re-evaluates live listeners so an
+ * auth-gated stream loses access instead of leaking the previous user's data).
+ *
+ * Routed here by the host dispatcher. Never imports the dispatcher.
+ */
+
+import {
+  onSnapshot,
+  type DocumentReference,
+  type CollectionReference,
+  type Query,
+} from 'pyric/firestore';
+import {
+  ref as rtdbRef,
+  onValue as rtdbOnValue,
+  type DatabaseReference,
+} from 'pyric/database';
+
+import type { FirestoreSubMessage, RtdbValueSubMessage, UnsubMessage } from '../protocol.js';
+import { serializeError, isRtdbSub } from '../protocol.js';
+import { activityJourneyId, type HostCtx, type PortLike, post } from '../host-context.js';
+import {
+  lensDb,
+  sessionDb,
+  lensRtdb,
+  opProvenance,
+  resolveTarget,
+  serializeDocSnap,
+} from './core.js';
+import { rtdbSnapToWire } from './rtdb.js';
+
+/**
+ * Session-bound sub registry (#754): the original sub message for every
+ * listener a port opened WITHOUT an explicit lens, so a port session change
+ * can re-establish it under the new identity (see resubscribeSessionSubs).
+ * Parallel to `ctx.subs` (which holds only the unsub fns).
+ */
+type SessionBoundSubMessage = FirestoreSubMessage | RtdbValueSubMessage;
+
+const _sessionSubs = new WeakMap<HostCtx, Map<PortLike, Map<string, SessionBoundSubMessage>>>();
+
+function sessionSubsFor(ctx: HostCtx, port: PortLike): Map<string, SessionBoundSubMessage> {
+  let byPort = _sessionSubs.get(ctx);
+  if (!byPort) {
+    byPort = new Map();
+    _sessionSubs.set(ctx, byPort);
+  }
+  let bySubId = byPort.get(port);
+  if (!bySubId) {
+    bySubId = new Map();
+    byPort.set(port, bySubId);
+  }
+  return bySubId;
+}
+
+/** Drop a port's session-bound sub records — invoked by the dispatcher's
+ *  `cleanupPort` on port disconnect. */
+export function dropPortSessionSubs(ctx: HostCtx, port: PortLike): void {
+  _sessionSubs.get(ctx)?.delete(port);
+}
+
+/**
+ * Re-establish a port's session-bound listeners under its CURRENT session —
+ * invoked (via the ctx hook) on every port session change. Mirrors prod's
+ * stream re-establishment on auth transitions: each listener is torn down and
+ * re-registered through `sessionDb`, so the fresh evaluation either delivers
+ * a snapshot (allowed) or a `permission-denied` snap-error (revoked). A
+ * signed-out page no longer keeps receiving auth-gated data.
+ */
+function resubscribeSessionSubs(ctx: HostCtx, port: PortLike): void {
+  const bound = _sessionSubs.get(ctx)?.get(port);
+  if (!bound || bound.size === 0) return;
+  const portSubs = ctx.subs.get(port);
+  for (const [subId, msg] of [...bound]) {
+    const unsub = portSubs?.get(subId);
+    if (isRtdbSub(msg)) {
+      if (unsub) unsub();
+      portSubs?.delete(subId);
+      bound.delete(subId); // handleRtdbSub re-records it
+      handleRtdbSub(ctx, port, msg);
+    } else {
+      // Auth transitions enter through host-auth rather than the dispatcher,
+      // so restore the original app/page provenance explicitly. The detach is
+      // correlated to the old accepted registration by listener id; this
+      // replacement attach must retain the same logical page attribution.
+      const provenance = {
+        ...opProvenance(msg, activityJourneyId(ctx, port)),
+        activity: { listenerId: subId, listenerLifecycle: 'reauthorize' as const },
+      };
+      const reauthorize = (): void => {
+        if (unsub) unsub();
+        portSubs?.delete(subId);
+        bound.delete(subId); // handleSub re-records it
+        handleSub(ctx, port, msg);
+      };
+      if (provenance && ctx.sandbox.runWithProvenance) {
+        ctx.sandbox.runWithProvenance(provenance, reauthorize);
+      } else {
+        reauthorize();
+      }
+    }
+  }
+}
+
+export function handleSub(ctx: HostCtx, port: PortLike, msg: FirestoreSubMessage): void {
+  // Resolve the listener's data handle through the SAME lens path ops use
+  // (Pyric Studio F4 "watch as user"): `{ mode: 'as', uid }` registers the
+  // listener as that user so its rule evals impersonate, `{ mode: 'admin' }`
+  // bypasses rules. Absent ⇒ the PORT'S SESSION (#754), so an app listener
+  // evaluates rules as whoever this tab signed in as.
+  const db = msg.actAs ? lensDb(ctx, msg.actAs) : sessionDb(ctx, port);
+  ensurePortSubs(ctx, port);
+  const portSubs = ctx.subs.get(port)!;
+
+  if (portSubs.has(msg.subId)) return; // idempotent
+
+  // Session-bound listeners re-establish on this port's auth transitions.
+  if (!msg.actAs) {
+    ctx.resubscribePortSubs ??= (p) => resubscribeSessionSubs(ctx, p);
+    sessionSubsFor(ctx, port).set(msg.subId, msg);
+  }
+
+  let target: DocumentReference | CollectionReference | Query;
+  let unsub: () => void;
+  try {
+    target = resolveTarget(db, msg.target);
+    unsub = registerListener(ctx, port, msg, target);
+  } catch (e) {
+    // resolveTarget / onSnapshot can throw synchronously (e.g. an invalid
+    // query or a rules-rejected target). Deliver it to the client's onSnapshot
+    // error callback as a snap-error instead of letting it escape handleMessage
+    // as an unhandled rejection (which would silently deliver NOTHING).
+    post(port, { t: 'snap', subId: msg.subId, value: { __error: serializeError(e) } });
+    return;
+  }
+
+  portSubs.set(msg.subId, unsub);
+}
+
+export function handleRtdbSub(ctx: HostCtx, port: PortLike, msg: RtdbValueSubMessage): void {
+  ensurePortSubs(ctx, port);
+  const portSubs = ctx.subs.get(port)!;
+  if (portSubs.has(msg.subId)) return;
+
+  if (!msg.actAs) {
+    ctx.resubscribePortSubs ??= (p) => resubscribeSessionSubs(ctx, p);
+    sessionSubsFor(ctx, port).set(msg.subId, msg);
+  }
+
+  try {
+    const ref = rtdbRef(lensRtdb(ctx, msg.actAs, port), msg.target.path);
+    const unsub = rtdbOnValue(
+      ref as DatabaseReference,
+      (snap) => post(port, { t: 'snap', subId: msg.subId, value: rtdbSnapToWire(snap) }),
+    );
+    portSubs.set(msg.subId, unsub);
+  } catch (e) {
+    post(port, { t: 'snap', subId: msg.subId, value: { __error: serializeError(e) } });
+  }
+}
+
+/** Register the real sandbox listener for a resolved target; returns its unsub.
+ *  Split out of handleSub so the throwing surface (resolveTarget + onSnapshot)
+ *  is inside handleSub's try/catch. */
+function registerListener(
+  _ctx: HostCtx,
+  port: PortLike,
+  msg: FirestoreSubMessage,
+  target: DocumentReference | CollectionReference | Query,
+): () => void {
+  return onSnapshot(
+    target as DocumentReference | Query,
+    (snap) => {
+      // Detect doc vs query snapshot by shape.
+      const snapAny = snap as {
+        id?: string;
+        path?: string;
+        exists?: boolean | (() => boolean);
+        data?: () => Record<string, unknown> | undefined;
+        docs?: Array<{
+          id: string;
+          path?: string;
+          exists: boolean | (() => boolean);
+          data(): Record<string, unknown>;
+        }>;
+      };
+
+      if (Array.isArray(snapAny.docs)) {
+        // Query snapshot
+        const docs = snapAny.docs.map((d) =>
+          serializeDocSnap(d as Parameters<typeof serializeDocSnap>[0]),
+        );
+        post(port, { t: 'snap', subId: msg.subId, value: { docs } });
+      } else if (snapAny.id !== undefined) {
+        // Doc snapshot
+        post(port, {
+          t: 'snap',
+          subId: msg.subId,
+          value: serializeDocSnap(snapAny as Parameters<typeof serializeDocSnap>[0]),
+        });
+      }
+    },
+    (err) => {
+      // Snapshot listener error (e.g. rules changed to deny).
+      // We forward as a snap with an __error field so the client can
+      // surface it to the original onSnapshot error callback.
+      post(port, { t: 'snap', subId: msg.subId, value: { __error: serializeError(err) } });
+    },
+  );
+}
+
+export function handleUnsub(ctx: HostCtx, port: PortLike, msg: UnsubMessage): void {
+  // Drop the session-bound record first — even when the live listener never
+  // registered (it errored at sub time), the record must not resurrect the
+  // sub on a later session change.
+  _sessionSubs.get(ctx)?.get(port)?.delete(msg.subId);
+  const portSubs = ctx.subs.get(port);
+  if (!portSubs) return;
+  const unsub = portSubs.get(msg.subId);
+  if (!unsub) return;
+  unsub();
+  portSubs.delete(msg.subId);
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────
+
+function ensurePortSubs(ctx: HostCtx, port: PortLike): void {
+  if (!ctx.subs.has(port)) {
+    ctx.subs.set(port, new Map());
+  }
+}