pyric-tools 0.1.0-alpha.7

package/dist/serve/worker/host.js

@@ -0,0 +1,1605 @@
+/**
+ * SharedWorker host — op handlers and subscription registry.
+ *
+ * WHY INJECTED DEPS
+ * -----------------
+ * The host is deliberately decoupled from `SharedWorkerGlobalScope` so
+ * unit tests can drive it with a REAL pyric sandbox + fake MessagePort
+ * objects — no browser or SharedWorker runtime required. The entry point
+ * (`entry.ts`) creates the real sandbox + db and wires the connecting ports
+ * to this module.
+ *
+ * ARCHITECTURE
+ * ------------
+ * One `HostCtx` is shared across ALL connected ports. It holds:
+ *   - `db` — the single modular Firestore handle (from pyric/firestore's
+ *     `getFirestore(sandbox)` — sandbox-live mode so auth changes propagate).
+ *   - `sandbox` — the underlying Sandbox, needed for `setRules` and for
+ *     constructing sentinels via FieldValue.
+ *   - `subs` — per-port subscription registry: Map<PortLike, Map<subId, unsub>>
+ *
+ * Each connecting port calls `handleMessage(ctx, port, msg)`. The function
+ * is exported so tests can call it directly.
+ *
+ * SENTINEL RESOLUTION
+ * -------------------
+ * Write data crossing the port may contain `SentinelMarker` objects
+ * (`{ __sentinel: 'serverTimestamp' }` etc.). Before passing data to the
+ * sandbox we walk the payload and replace each marker with the real
+ * FieldValue object from `pyric/firestore`'s sentinel factories. The
+ * sandbox's value-resolver then executes them as usual.
+ *
+ * SUBSCRIPTION FAN-OUT
+ * --------------------
+ * Because all ports share ONE sandbox, an onSnapshot listener registered
+ * via the sandbox automatically fires for writes from ANY port. We just
+ * need to forward the snapshot to the correct originating port(s).
+ *
+ * TRANSACTIONS + READ-SET VALIDATION
+ * ------------------------------------
+ * `runTransaction` on the worker is the full-fidelity path: the host calls
+ * the sandbox's `runTransaction`, which runs the update function, handles
+ * optimistic-concurrency retries, and commits atomically. The client now
+ * sends a `reads` array alongside `writes`; the worker re-reads each doc
+ * inside the sandbox transaction and validates that no concurrent write
+ * changed any of them between the client's read and this commit. A mismatch
+ * signals `{ code: 'aborted' }` on the wire so the client can re-run
+ * `updateFn` — see `txnCommit` handler for full details.
+ */
+import { getFirestore as pyricGetFirestore, getAdminFirestore as pyricGetAdminFirestore, doc as pyricDoc, collection as pyricCollection, collectionGroup as pyricCollectionGroup, query as pyricQuery, where as pyricWhere, and as pyricAnd, or as pyricOr, orderBy as pyricOrderBy, limit as pyricLimit, limitToLast as pyricLimitToLast, startAt as pyricStartAt, startAfter as pyricStartAfter, endAt as pyricEndAt, endBefore as pyricEndBefore, getDoc, getDocs, setDoc, updateDoc, deleteDoc, addDoc, onSnapshot, getCountFromServer, getAggregateFromServer, runTransaction, writeBatch, serverTimestamp, increment, arrayUnion, arrayRemove, deleteField, } from 'pyric/firestore';
+// The canonical value codec (same module the protocol's read path uses) —
+// write payloads rehydrate host-side so marker-shaped scalars from the JSON
+// relay legs are STORED as real wrapper instances (see prepareWriteData).
+import { rehydrateDocValue } from 'pyric/firestore-values';
+import { serializeToBuckets, bundleRecords, parseBundle, deserializeFromBuckets } from 'pyric/sandbox';
+import { sandbox as sandboxOps } from 'pyric/firestore';
+import { getInternalEnv } from 'pyric/sandbox/internal';
+import { initializeApp } from 'pyric/app';
+import { getStorage, getStorageSandbox, ref as storageRef, listAll as storageListAll, getMetadata as storageGetMetadata, getBlob as storageGetBlob, getBytes as storageGetBytes, uploadBytes as storageUploadBytes, deleteObject as storageDeleteObject, } from 'pyric/storage';
+// Host-only rules-bypass admin plane — the storage mirror of
+// `getAdminFirestore`/`getAdminDatabase`, resolved for `actAs: { mode: 'admin' }`.
+import { getAdminStorageSandbox } from 'pyric/storage/internal';
+import { getDatabase as pyricGetDatabase, getAdminDatabase as pyricGetAdminDatabase, ref as rtdbRef, get as rtdbGet, set as rtdbSet, update as rtdbUpdate, remove as rtdbRemove, onValue as rtdbOnValue, serverTimestamp as rtdbServerTimestamp, sandbox as rtdbSandbox, } from 'pyric/database/modular';
+import { serializeError, serializeDocData, isSentinelMarker, isAuthSub, isEventSub, isRtdbSub, bytesToBase64, base64ToBytes, storagePayloadTooLarge, MAX_STORAGE_OP_BYTES, MAX_STORAGE_OP_B64_LENGTH, } from './protocol.js';
+// The canonical agent tool dispatcher — reused on the worker so a bridged agent
+// executes against THIS sandbox (one backend for app + Studio + agent), instead
+// of a separate in-page sandbox.
+import { buildSandboxDispatcher } from '../../bridge/client/dispatch.js';
+import { post, ok, fail, bestEffortFlush } from './host-context.js';
+import { authSubsFor, isAuthOp, handleAuthOp, handleAuthSub, handleAuthUnsub, portSession, cleanupPortSession, } from './host-auth.js';
+import { eventSubsFor, handleEventSub, handleEventUnsub, } from './host-events.js';
+// Re-export so host.ts's public surface is unchanged after the decomposition.
+export { ensureAuth, portSession } from './host-auth.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 }]]));
+}
+// ─── Descriptor → live ref resolution ───────────────────────────────────
+/**
+ * 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.
+ */
+function resolveTarget(db, target) {
+    if (target.__ref === 'doc') {
+        return pyricDoc(db, target.path);
+    }
+    if (target.__ref === 'collection') {
+        return pyricCollection(db, target.path);
+    }
+    if (target.__ref === 'group') {
+        return pyricCollectionGroup(db, target.collectionId);
+    }
+    // query descriptor
+    const source = resolveTarget(db, target.source);
+    const constraints = target.constraints.map((c) => resolveConstraint(c));
+    return pyricQuery(source, ...constraints);
+}
+function resolveConstraint(c) {
+    switch (c.kind) {
+        case 'where':
+            // Rehydrate the comparison value (same rationale as prepareWriteData,
+            // spike gap 4, applied to READ inputs): over the JSON relay legs a
+            // Node-side Timestamp/Bytes/GeoPoint arrives as its marker shape;
+            // without rehydration the comparison would see a plain map and the
+            // filter would silently mismatch typed stored values.
+            return pyricWhere(c.field, c.op, rehydrateDocValue(c.value));
+        // Composite filters rebuild through the modular `and`/`or` factories,
+        // which validate operands: an empty composite or a nested non-filter
+        // throws the same TypeError the in-page SDK raises (surfaces as an
+        // error res / snap-error, never a crash).
+        case 'and':
+            return pyricAnd(...c.filters.map(resolveConstraint));
+        case 'or':
+            return pyricOr(...c.filters.map(resolveConstraint));
+        case 'orderBy':
+            return pyricOrderBy(c.field, c.direction);
+        case 'limit':
+            return pyricLimit(c.n);
+        case 'limitToLast':
+            return pyricLimitToLast(c.n);
+        // Cursor values rehydrate for the same reason as `where` values —
+        // `startAfter(<timestamp>)` must position against real Timestamps.
+        case 'startAt':
+            return pyricStartAt(...c.values.map(rehydrateDocValue));
+        case 'startAfter':
+            return pyricStartAfter(...c.values.map(rehydrateDocValue));
+        case 'endAt':
+            return pyricEndAt(...c.values.map(rehydrateDocValue));
+        case 'endBefore':
+            return pyricEndBefore(...c.values.map(rehydrateDocValue));
+    }
+}
+// ─── Sentinel resolution ──────────────────────────────────────────────────
+/**
+ * Walk a write payload and replace every `SentinelMarker` with the
+ * corresponding pyric/firestore FieldValue sentinel object.
+ *
+ * WHY: FieldValue class instances don't survive structured clone — they
+ * arrive as plain objects and lose their prototype, breaking sandbox
+ * sentinel detection. The client sends `{ __sentinel: 'serverTimestamp' }`
+ * etc. and we reconstruct the real FieldValue here before the sandbox sees
+ * the data.
+ *
+ * The sandbox's sentinel-capture code (sentinel-capture.ts) recognizes
+ * FieldValue objects by their internal `__type` property, which the
+ * factories produce correctly.
+ */
+function resolveSentinels(value) {
+    if (isSentinelMarker(value)) {
+        return resolveSentinel(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(resolveSentinels);
+    }
+    if (value !== null && typeof value === 'object') {
+        // Leave CLASS instances intact (Timestamp/Bytes/LatLng rehydrated by
+        // prepareWriteData below, or FieldValue objects): walking their entries
+        // into a plain object would strip the prototype the sandbox keys on.
+        // Sentinel markers only ever live in plain JSON containers.
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            return value;
+        }
+        const obj = value;
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            out[k] = resolveSentinels(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Prepare an incoming WRITE payload for the sandbox: rehydrate marker-shaped
+ * scalars into REAL wrapper instances, then rebuild FieldValue sentinels.
+ *
+ * WHY REHYDRATE WRITES (spike gap 4): over the JSON relay legs a Node-side
+ * `Timestamp`/`Bytes`/`GeoPoint` arrives as its `toJSON()` marker
+ * (`{ type: 'firestore/timestamp/1.0', … }` or `{ __type: 'timestamp', … }`).
+ * Without rehydration the worker STORES the marker as a plain map — reads
+ * mask the bug (the read path rehydrates), but in-worker rules comparisons
+ * and `orderBy` over that field see a map, not a timestamp. `rehydrateDocValue`
+ * is the same canonical codec the read path / persistence uses, so the wire,
+ * store, and IDB formats stay one format.
+ *
+ * Order matters: rehydration first (it passes `__sentinel` markers through
+ * as plain objects, rehydrating any marker-shaped values nested inside
+ * arrayUnion/arrayRemove), then sentinel resolution (which now skips the
+ * freshly rehydrated class instances — see resolveSentinels).
+ */
+function prepareWriteData(value) {
+    return resolveSentinels(rehydrateDocValue(value));
+}
+function resolveRtdbSentinels(value) {
+    if (value && typeof value === 'object') {
+        const marker = value;
+        if (marker.__rtdbSentinel === 'serverTimestamp')
+            return rtdbServerTimestamp();
+        if (Array.isArray(value))
+            return value.map(resolveRtdbSentinels);
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = resolveRtdbSentinels(v);
+        return out;
+    }
+    return value;
+}
+function resolveSentinel(marker) {
+    switch (marker.__sentinel) {
+        case 'serverTimestamp': return serverTimestamp();
+        case 'increment': return increment(marker.n);
+        case 'arrayUnion': return arrayUnion(...marker.values);
+        case 'arrayRemove': return arrayRemove(...marker.values);
+        case 'deleteField': return deleteField();
+    }
+}
+// ─── Snapshot serialization ───────────────────────────────────────────────
+/**
+ * Rebuild a JSON-flattened `Uint8Array` (an index-keyed `{ "0": n, … }`
+ * map) and encode it as base64url without padding — the exact form
+ * `pyric/rules`' `Bytes.toBase64()` emits. Backs the transaction read-set
+ * canonicalizer's handling of prototype-stripped `Bytes` clones.
+ */
+/** Timestamp/Duration stripped-clone key set (they share field names). */
+const TS_CLONE_KEYS = ['typeName', 'seconds', 'nanos'];
+/** Does `o` carry EXACTLY these own enumerable keys (no more, no fewer)?
+ *  Backs the transaction canonicalizer's strict clone-shape matching. */
+function hasExactKeys(o, keys) {
+    const own = Object.keys(o);
+    return own.length === keys.length && keys.every((k) => k in o);
+}
+function indexMapToBase64Url(data) {
+    const map = (data ?? {});
+    const keys = Object.keys(map);
+    const bytes = new Uint8Array(keys.length);
+    for (let i = 0; i < keys.length; i++)
+        bytes[i] = map[String(i)] ?? 0;
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * Serialize a document snapshot to cross-port form.
+ * Uses JSON-via-serializeDocData so Timestamp/Bytes/LatLng survive.
+ */
+function serializeDocSnap(snap) {
+    const existsBool = typeof snap.exists === 'function' ? snap.exists() : snap.exists;
+    const data = existsBool ? snap.data() : undefined;
+    return {
+        id: snap.id,
+        // Doc snapshots carry a top-level `path`; QUERY doc snapshots carry it on
+        // `.ref.path`. Read both so query rows serialize their FULL path (Studio's
+        // browse resolves the document detail from it).
+        path: snap.path ?? snap.ref?.path,
+        exists: existsBool,
+        data: data ? serializeDocData(data) : undefined,
+    };
+}
+// ─── Auth lens (Pyric Studio) ─────────────────────────────────────────────
+/**
+ * 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.
+ */
+function lensDb(ctx, actAs) {
+    // Absent / app-session → the app's live session handle.
+    if (!actAs || actAs.mode === 'app-session') {
+        return ctx.db;
+    }
+    // { mode: 'admin' } → a modular rules-bypass handle (cached per ctx).
+    if (actAs.mode === 'admin') {
+        return (ctx.adminDb ??= pyricGetAdminFirestore(ctx.sandbox));
+    }
+    // { mode: 'anon' } → a genuinely UNAUTHENTICATED handle
+    // (`withAuth(null)` — `request.auth == null` in rules). NOT the same as an
+    // absent lens, which resolves to the PORT'S SESSION: a relayed op that
+    // means "no auth" must pin this lens or it silently runs as whoever the
+    // browser tab is signed in as.
+    if (actAs.mode === 'anon') {
+        return (ctx.anonDb ??= pyricGetFirestore(ctx.sandbox.withAuth(null)));
+    }
+    // { mode: 'as', uid } → a frozen-identity handle; rules evaluate as `uid`.
+    const handles = (ctx.lensHandles ??= new Map());
+    const key = lensCacheKey(actAs);
+    let handle = handles.get(key);
+    if (!handle) {
+        handle = pyricGetFirestore(ctx.sandbox.withAuth(authStateForLens(actAs)));
+        handles.set(key, handle);
+    }
+    return handle;
+}
+function authStateForLens(actAs) {
+    return actAs.token === undefined
+        ? { uid: actAs.uid }
+        : { uid: actAs.uid, token: actAs.token };
+}
+function lensCacheKey(actAs) {
+    return actAs.token === undefined
+        ? actAs.uid
+        : `${actAs.uid}:${JSON.stringify(actAs.token)}`;
+}
+/**
+ * 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.
+ */
+function lensProvenance(actAs) {
+    return actAs ?? { mode: 'app-session' };
+}
+/**
+ * Resolve the data handle for an op/sub carrying NO explicit lens: the
+ * PORT'S SESSION (#754). A signed-in port gets a per-uid 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.
+ *
+ * Known staleness (same class as `lensHandles`): a claims change via
+ * `auth.adminUpdateUser` is not reflected in an existing session's handle
+ * until that user session is re-established (real Firebase behaves the same
+ * until token refresh).
+ */
+function sessionDb(ctx, port) {
+    const session = portSession(ctx, port);
+    if (!session)
+        return ctx.db;
+    const cache = (ctx.sessionDbs ??= new Map());
+    let handle = cache.get(session.user.uid);
+    if (!handle) {
+        handle = pyricGetFirestore(ctx.sandbox.withAuth(session.state));
+        cache.set(session.user.uid, handle);
+    }
+    return handle;
+}
+function sessionRtdb(ctx, port) {
+    const session = portSession(ctx, port);
+    if (!session)
+        return ensureRtdb(ctx);
+    const cache = (ctx.sessionRtdbs ??= new Map());
+    let handle = cache.get(session.user.uid);
+    if (!handle) {
+        handle = pyricGetDatabase(ctx.sandbox.withAuth(session.state));
+        cache.set(session.user.uid, handle);
+    }
+    return handle;
+}
+function lensRtdb(ctx, actAs, port) {
+    if (!actAs || actAs.mode === 'app-session') {
+        return sessionRtdb(ctx, port);
+    }
+    if (actAs.mode === 'admin') {
+        return (ctx.adminRtdb ??= pyricGetAdminDatabase(ctx.sandbox));
+    }
+    // Genuinely unauthenticated — see the `anon` note on lensDb.
+    if (actAs.mode === 'anon') {
+        return (ctx.anonRtdb ??= pyricGetDatabase(ctx.sandbox.withAuth(null)));
+    }
+    const handles = (ctx.lensRtdbs ??= new Map());
+    const key = lensCacheKey(actAs);
+    let handle = handles.get(key);
+    if (!handle) {
+        handle = pyricGetDatabase(ctx.sandbox.withAuth(authStateForLens(actAs)));
+        handles.set(key, handle);
+    }
+    return handle;
+}
+// ─── Op handlers ──────────────────────────────────────────────────────────
+/** The shared Storage handle, lazily created (Pyric Studio data browse): one per
+ *  worker, over an app bound to the shared sandbox. The high-level
+ *  `pyric/storage` ops enforce rules, so the host reads through them. */
+function ensureStorage(ctx) {
+    return (ctx.storage ??= getStorage(initializeApp({ sandbox: ctx.sandbox })));
+}
+/**
+ * Resolve the Storage handle a storage op runs against, given its `actAs`
+ * lens — the storage mirror of {@link lensRtdb}:
+ *
+ *   - absent / `app-session` → the shared anonymous page handle
+ *     ({@link ensureStorage}). Storage rules apply only when the HOST
+ *     configured them on this sandbox's storage service (first call per
+ *     sandbox wins) — the SERVED worker currently configures none
+ *     (`setRules`/`setDatabaseRules` cover Firestore/RTDB only), so
+ *     worker-mode storage is effectively open today and all lenses behave
+ *     alike there. The lens split matters for embedding/test hosts that
+ *     pre-open the service with rules. (Storage also has no per-port
+ *     session plumbing — reads always ran anonymous; writes keep that.)
+ *   - `{ 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 lensStorage(ctx, actAs) {
+    if (!actAs || actAs.mode === 'app-session') {
+        return ensureStorage(ctx);
+    }
+    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) {
+    const md = msg.metadata ?? {};
+    const str = (key) => typeof md[key] === 'string' ? md[key] : undefined;
+    const customSource = md['customMetadata'] ?? md['metadata'];
+    let customMetadata;
+    if (customSource !== null && typeof customSource === 'object' && !Array.isArray(customSource)) {
+        customMetadata = {};
+        for (const [k, v] of Object.entries(customSource)) {
+            customMetadata[k] = String(v);
+        }
+    }
+    const settable = {};
+    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;
+}
+function ensureRtdb(ctx) {
+    return (ctx.rtdb ??= pyricGetDatabase(ctx.sandbox));
+}
+function rtdbSnapToWire(snap) {
+    return {
+        key: snap.key,
+        exists: snap.exists(),
+        value: snap.val(),
+        size: snap.size,
+    };
+}
+function normalizeDatabaseRules(source) {
+    if (source === null)
+        return null;
+    if (typeof source === 'string') {
+        return JSON.parse(source);
+    }
+    if (typeof source === 'object' && source !== null) {
+        return source;
+    }
+    throw new Error('RTDB rules must be a rules JSON object or JSON string.');
+}
+function firestoreRuleMessages(result) {
+    const messages = [];
+    if (result.parseError) {
+        messages.push({
+            severity: 'error',
+            text: `PARSE ERROR: expected ${String(result.parseError.expected ?? 'valid rules')}`,
+            line: result.parseError.line,
+            column: result.parseError.column,
+        });
+    }
+    for (const warning of result.warnings ?? []) {
+        messages.push({
+            severity: warning.severity === 'error' ? 'error' : warning.severity === 'warning' ? 'warn' : 'info',
+            text: String(warning.message ?? warning),
+        });
+    }
+    return messages;
+}
+async function handleOp(ctx, port, msg) {
+    const { sandbox } = ctx;
+    // Explicit lens (Studio admin / as / app-session) → lensDb; no lens → the
+    // PORT'S SESSION (#754), so app ops run as whoever this tab signed in as.
+    const db = msg.actAs ? lensDb(ctx, msg.actAs) : sessionDb(ctx, port);
+    // Provenance the op runs under. Stamped onto the unified event stream's
+    // `authLens` by the emit path (C1 field / T1 emit). For `{ mode: 'as', uid }`
+    // the resolved `db` already carries `auth: { uid }`, so a rules eval emits
+    // under that identity; `lens` is the canonical normalised value the host
+    // hands forward when the explicit emit-time stamp seam exists (see lensProvenance).
+    const lens = lensProvenance(msg.actAs);
+    void lens;
+    switch (msg.method) {
+        case 'getDoc': {
+            try {
+                const ref = pyricDoc(db, msg.path);
+                const snap = await getDoc(ref);
+                ok(port, msg.id, serializeDocSnap(snap));
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'getDocs': {
+            try {
+                const source = resolveTarget(db, msg.source);
+                // CollectionReference is always also queryable — getDocs accepts Query<T>
+                // and CollectionReference is structurally compatible at runtime even though
+                // the type system doesn't know that (CollectionReference has no `_isQuery`
+                // brand). Cast through Query to satisfy the type checker.
+                const snap = await getDocs(source);
+                const docs = snap.docs.map((d) => serializeDocSnap(d));
+                ok(port, msg.id, { docs });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'setDoc': {
+            try {
+                const ref = pyricDoc(db, msg.path);
+                const data = prepareWriteData(msg.data);
+                await setDoc(ref, data, msg.options);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'updateDoc': {
+            try {
+                const ref = pyricDoc(db, msg.path);
+                const data = prepareWriteData(msg.data);
+                await updateDoc(ref, data);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'deleteDoc': {
+            try {
+                const ref = pyricDoc(db, msg.path);
+                await deleteDoc(ref);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'addDoc': {
+            try {
+                const coll = pyricCollection(db, msg.collectionPath);
+                const data = prepareWriteData(msg.data);
+                const ref = await addDoc(coll, data);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, { id: ref.id, path: ref.path });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'count': {
+            try {
+                const source = resolveTarget(db, msg.source);
+                const snap = await getCountFromServer(source);
+                ok(port, msg.id, { count: snap.data().count });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'aggregate': {
+            // Multi-field aggregates (count/sum/average). The wire spec is
+            // structurally pyric/firestore's AggregateSpec, so it passes straight
+            // through; the reply data is plain numbers / null (empty-input average).
+            try {
+                const source = resolveTarget(db, msg.source);
+                const snap = await getAggregateFromServer(source, msg.spec);
+                ok(port, msg.id, { data: snap.data() });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'listRootCollections': {
+            // Keyspace enumeration (Pyric Studio data browse). Lens-independent: it
+            // lists the collection ids present, not rule-gated reads.
+            try {
+                ok(port, msg.id, { ids: getInternalEnv(sandbox).listRootCollections() });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'listSubcollections': {
+            try {
+                ok(port, msg.id, { ids: getInternalEnv(sandbox).listSubcollections(msg.docPath) });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'batchCommit': {
+            /**
+             * WHY: writeBatch in pyric/firestore buffers set/update/delete calls
+             * and commits them as one unit through the sandbox backend. We
+             * reconstruct the batch here from the wire write descriptors.
+             * Atomicity guarantee: the sandbox backend applies all writes or none
+             * (per-collection lock semantics of LocalEnvironment.batch()).
+             */
+            try {
+                const batch = writeBatch(db);
+                for (const w of msg.writes) {
+                    applyWriteToBatch(db, batch, w);
+                }
+                await batch.commit();
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'txnCommit': {
+            /**
+             * READ-SET VALIDATION FOR MULTI-TAB CORRECTNESS
+             * -----------------------------------------------
+             * The client sends `{ method: 'txnCommit', reads, writes }` after its
+             * `updateFn` callback has resolved. `reads` is the set of docs the
+             * client read during `updateFn` (each entry is `{ path, data }` where
+             * `data` is the serialized snapshot the client saw, or null if the doc
+             * was missing).
+             *
+             * WHY READ-SET VALIDATION IS NECESSARY
+             * -------------------------------------
+             * A transaction spans two messages: the client's `txn.get` RPC (sent
+             * during `updateFn`) and this `txnCommit` RPC. Between those messages
+             * the event loop is free — another tab's write to any of the read docs
+             * can land in that gap via a separate `setDoc` message. Without
+             * validation that would be a silent lost update: the client computed
+             * its writes using stale data, committed them, and the other tab's
+             * changes were silently overwritten.
+             *
+             * HOW WE VALIDATE (no per-doc version/updateTime in the sandbox)
+             * ---------------------------------------------------------------
+             * Inside a real `runTransaction(db, callback)`, the callback re-reads
+             * every doc from the read-set via `tx.get(ref)`, serializes its current
+             * data to the same JSON form the client produced (using `serializeDocData`
+             * on both sides), and compares the JSON strings. If any doc's current
+             * serialized form differs from what the client recorded, another tab
+             * wrote it between the client's read and this commit — we throw an abort
+             * sentinel so the sandbox rolls back the transaction, and we return
+             * `{ ok: false, error: { code: 'aborted' } }` on the wire. The client's
+             * retry loop then re-runs `updateFn` with fresh reads.
+             *
+             * SERIALIZED-FORM EQUALITY — VIA THE CANONICAL CODEC
+             * ---------------------------------------------------
+             * Both JSON strings are CANONICALIZED before comparison:
+             * `JSON.stringify(rehydrateDocValue(JSON.parse(json)))`. Raw string
+             * equality is NOT safe here even within one process, because the two
+             * read paths yield DIFFERENT wrapper classes for the same stored
+             * value: `getDoc` (what the client's read-set echoes) returns
+             * `firebase/firestore` classes whose `Timestamp.toJSON()` emits
+             * `{ seconds, nanoseconds, type }`, while the transaction's
+             * validation re-read comes through the admin-compat wrapper whose
+             * `Timestamp.toJSON()` emits `{ type, seconds, nanoseconds }` — same
+             * value, different key order, different string. Rehydrating both
+             * sides through the ONE shared codec (`pyric/firestore-values`)
+             * collapses every marker family into the same wrapper classes with
+             * deterministic `toJSON()` key order, so string equality ↔ value
+             * equality again — an unmodified doc can never phantom-abort (which
+             * would livelock the client's retry loop), while a real concurrent
+             * write still mismatches. Plain-map key order is preserved by both
+             * paths from the same stored object, so it stays comparable.
+             *
+             * NOTE ON tx.set/update/delete SIGNATURE
+             * ---------------------------------------
+             * The modular pyric/firestore Transaction (wrapping the admin-compat
+             * TransactionWrapper) takes `tx.set(docRef, data)` where `docRef` is a
+             * real `DocumentReference` — NOT a path string. We build refs via
+             * `pyricDoc(db, path)` for each write.
+             */
+            /** Sentinel thrown inside the transaction callback to signal an abort. */
+            const TXN_ABORT = Symbol('txn-abort');
+            /**
+             * Canonicalize a serialized doc-data JSON string (see
+             * SERIALIZED-FORM EQUALITY above). Two normalization passes:
+             *
+             *   1. `rehydrateDocValue` collapses the marker families (`__type`
+             *      persistence markers and `firebase/firestore` `toJSON()`
+             *      markers) into the one set of wrapper classes, whose
+             *      `toJSON()` re-emits a single deterministic form.
+             *   2. The stringify replacer additionally normalizes PROTOTYPE-
+             *      STRIPPED wrapper clones — the sandbox transaction's
+             *      capture-by-value `structuredClone` turns a stored rules
+             *      wrapper into a plain `{ typeName, … }` object that neither
+             *      marker family matches, so without this pass an unmodified
+             *      typed doc would never compare equal to the client's getDoc
+             *      echo (a guaranteed phantom abort → retry livelock).
+             */
+            const canonicalDocJson = (json) => JSON.stringify(rehydrateDocValue(JSON.parse(json)), (_key, v) => {
+                if (v === null || typeof v !== 'object' || Array.isArray(v))
+                    return v;
+                const o = v;
+                if (typeof o.typeName !== 'string' || o.__type !== undefined)
+                    return v;
+                // Re-shape a stripped rules-wrapper clone into the wrapper's own
+                // canonical toJSON marker form (kept in sync with pyric/rules'
+                // simulator/wrappers/* instance fields + toJSON()) — but ONLY
+                // when the key set EXACTLY matches that wrapper's own-field
+                // shape. A looser match would silently DROP extra keys from
+                // user data that merely resembles a clone, collapsing two
+                // genuinely different docs into one canonical form and letting
+                // a concurrent write commit undetected (false equality). A
+                // near-miss map passes through unchanged — worst case is a
+                // spurious abort + retry, never a lost update.
+                switch (o.typeName) {
+                    case 'timestamp':
+                        return hasExactKeys(o, TS_CLONE_KEYS)
+                            ? { __type: 'timestamp', seconds: o.seconds, nanos: o.nanos }
+                            : v;
+                    case 'duration':
+                        return hasExactKeys(o, TS_CLONE_KEYS)
+                            ? { __type: 'duration', seconds: o.seconds, nanos: o.nanos }
+                            : v;
+                    case 'latlng':
+                        return hasExactKeys(o, ['typeName', 'lat', 'lng'])
+                            ? { __type: 'latlng', lat: o.lat, lng: o.lng }
+                            : v;
+                    case 'reference':
+                        return hasExactKeys(o, ['typeName', 'path'])
+                            ? { __type: 'reference', path: o.path }
+                            : v;
+                    case 'path':
+                        return hasExactKeys(o, ['typeName', 'segments', 'bindings'])
+                            ? { __type: 'path', segments: o.segments }
+                            : v;
+                    case 'bytes':
+                        // The Uint8Array field serialized as an index-keyed map;
+                        // rebuild and emit Bytes.toJSON()'s base64url form.
+                        return hasExactKeys(o, ['typeName', 'data'])
+                            ? { __type: 'bytes', base64: indexMapToBase64Url(o.data) }
+                            : v;
+                    default:
+                        return v;
+                }
+            });
+            try {
+                await runTransaction(db, async (tx) => {
+                    // ── Step 1: validate the read-set ──────────────────────────────
+                    // Re-read each doc the client touched and compare its current
+                    // serialized form against what the client recorded at read time.
+                    const modularTx = tx;
+                    for (const r of msg.reads) {
+                        const ref = pyricDoc(db, r.path);
+                        const currentSnap = await modularTx.get(ref);
+                        const existsBool = typeof currentSnap.exists === 'function'
+                            ? currentSnap.exists()
+                            : currentSnap.exists;
+                        // Compute the serialized form of the current doc state.
+                        const currentSerialized = existsBool && currentSnap.data()
+                            ? serializeDocData(currentSnap.data())
+                            : null;
+                        // Compare against what the client recorded:
+                        //   both null → ok (doc still doesn't exist)
+                        //   both present + same JSON → ok
+                        //   anything else → conflict
+                        const clientHadNull = r.data === null;
+                        const workerHasNull = currentSerialized === null;
+                        if (clientHadNull !== workerHasNull) {
+                            // Existence changed (created or deleted by another tab).
+                            throw TXN_ABORT;
+                        }
+                        if (!clientHadNull &&
+                            !workerHasNull &&
+                            canonicalDocJson(r.data.json) !== canonicalDocJson(currentSerialized.json)) {
+                            // Data changed by another tab.
+                            throw TXN_ABORT;
+                        }
+                    }
+                    // ── Step 2: apply the queued writes ────────────────────────────
+                    for (const w of msg.writes) {
+                        const ref = pyricDoc(db, w.path);
+                        if (w.method === 'set') {
+                            const data = prepareWriteData(w.data);
+                            modularTx.set(ref, data, w.options);
+                        }
+                        else if (w.method === 'update') {
+                            const data = prepareWriteData(w.data);
+                            modularTx.update(ref, data);
+                        }
+                        else if (w.method === 'delete') {
+                            modularTx.delete(ref);
+                        }
+                    }
+                });
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                if (e === TXN_ABORT) {
+                    // Read-set conflict — signal the client to retry its updateFn.
+                    const abortErr = { code: 'aborted', message: 'Transaction read-set conflict: a concurrent write invalidated the read snapshot.' };
+                    post(port, { t: 'res', id: msg.id, ok: false, error: abortErr });
+                }
+                else {
+                    fail(port, msg.id, e);
+                }
+            }
+            break;
+        }
+        case 'setRules':
+        case 'setFirestoreRules': {
+            try {
+                const result = sandboxOps.setRules(db, msg.source);
+                const messages = firestoreRuleMessages(result);
+                const okDeploy = !messages.some((m) => m.severity === 'error');
+                ctx.activeRules ??= {};
+                const previous = ctx.activeRules.firestore?.status === 'active'
+                    ? ctx.activeRules.firestore.source
+                    : ctx.activeRules.firestore?.lastKnownGood;
+                ctx.activeRules.firestore = {
+                    source: okDeploy ? msg.source : ctx.activeRules.firestore?.source ?? msg.source,
+                    updatedAt: Date.now(),
+                    status: okDeploy ? 'active' : 'error',
+                    messages,
+                    ...(previous ? { lastKnownGood: previous } : {}),
+                };
+                ok(port, msg.id, { warnings: result.warnings, messages, ok: okDeploy });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'setDatabaseRules': {
+            try {
+                const db = ensureRtdb(ctx);
+                const rules = normalizeDatabaseRules(msg.source);
+                const previous = ctx.activeRules?.database?.status === 'active'
+                    ? ctx.activeRules.database.source
+                    : ctx.activeRules?.database?.lastKnownGood;
+                rtdbSandbox.setRules(db, rules);
+                ctx.activeRules ??= {};
+                ctx.activeRules.database = {
+                    source: rules,
+                    updatedAt: Date.now(),
+                    status: 'active',
+                    messages: [],
+                    ...(previous ? { lastKnownGood: previous } : {}),
+                };
+                ok(port, msg.id, { ok: true, messages: [] });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'getActiveRules': {
+            ok(port, msg.id, msg.service ? ctx.activeRules?.[msg.service] ?? null : ctx.activeRules ?? {});
+            break;
+        }
+        case 'getRulesStatus': {
+            ok(port, msg.id, msg.service ? ctx.activeRules?.[msg.service] ?? null : ctx.activeRules ?? {});
+            break;
+        }
+        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 = sandboxOps.snapshotState(ctx.adminDb ?? lensDb(ctx, { mode: 'admin' }));
+                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;
+        }
+        case 'rtdb.get': {
+            try {
+                const db = lensRtdb(ctx, msg.actAs, port);
+                ok(port, msg.id, rtdbSnapToWire(await rtdbGet(rtdbRef(db, msg.path))));
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'rtdb.set': {
+            try {
+                const db = lensRtdb(ctx, msg.actAs, port);
+                const value = resolveRtdbSentinels(msg.value);
+                await rtdbSet(rtdbRef(db, msg.path), value);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'rtdb.update': {
+            try {
+                const db = lensRtdb(ctx, msg.actAs, port);
+                await rtdbUpdate(rtdbRef(db, msg.path), resolveRtdbSentinels(msg.values));
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'rtdb.remove': {
+            try {
+                const db = lensRtdb(ctx, msg.actAs, port);
+                await rtdbRemove(rtdbRef(db, msg.path));
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'rtdb.push': {
+            try {
+                const db = lensRtdb(ctx, msg.actAs, port);
+                const childPath = `${msg.path}/${msg.key}`;
+                if (msg.value !== undefined) {
+                    await rtdbSet(rtdbRef(db, childPath), resolveRtdbSentinels(msg.value));
+                    await bestEffortFlush(ctx);
+                }
+                const normalizedPath = `/${childPath.split('/').filter(Boolean).join('/')}`;
+                ok(port, msg.id, { key: msg.key, path: normalizedPath });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'rtdb.adminSnapshot': {
+            try {
+                ok(port, msg.id, rtdbSandbox.snapshotState(lensRtdb(ctx, { mode: 'admin' }, port)));
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        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;
+        }
+        case 'setPolicy': {
+            // Store the dial's PolicyRequest as the worker-side runtime governance
+            // (Pyric Studio F3). This is the source of truth Studio reflects + a
+            // future in-worker agent runtime consults. It does NOT push into a
+            // running bridge process — see the limitation note on `ctx.policy` /
+            // `PolicyRequest`. Additive + idempotent: last write wins.
+            ctx.policy = msg.policy;
+            ok(port, msg.id, null);
+            break;
+        }
+        case 'getPolicy': {
+            // Read back the active runtime policy (null until the dial set one), so
+            // Studio can reflect persisted state across reconnects within a worker
+            // lifetime and a freshly-connecting port can hydrate the dial.
+            ok(port, msg.id, ctx.policy ?? null);
+            break;
+        }
+        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 '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 = lensStorage(ctx, msg.actAs);
+                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 = lensStorage(ctx, msg.actAs);
+                // 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 = lensStorage(ctx, msg.actAs);
+                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, so server writes get Studio
+            // provenance for free.
+            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 = lensStorage(ctx, msg.actAs);
+                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 = lensStorage(ctx, msg.actAs);
+                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.
+            try {
+                const storage = lensStorage(ctx, msg.actAs);
+                await storageDeleteObject(storageRef(storage, msg.path));
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        default: {
+            // Auth ops (`auth.*`) are routed to handleAuthOp by handleMessage before
+            // reaching here, so any method landing in this default is genuinely
+            // unknown. (We can't use a `never` exhaustiveness check anymore because
+            // OpMessage now includes the auth variants this switch deliberately skips.)
+            fail(port, msg.id, new Error(`Unknown method: ${String(msg.method)}`));
+        }
+    }
+}
+function applyWriteToBatch(db, batch, w) {
+    const b = batch;
+    const ref = pyricDoc(db, w.path);
+    if (w.method === 'set') {
+        const data = prepareWriteData(w.data);
+        b.set(ref, data, w.options);
+    }
+    else if (w.method === 'update') {
+        const data = prepareWriteData(w.data);
+        b.update(ref, data);
+    }
+    else if (w.method === 'delete') {
+        b.delete(ref);
+    }
+}
+const _sessionSubs = new WeakMap();
+function sessionSubsFor(ctx, port) {
+    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;
+}
+/**
+ * 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, port) {
+    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 (unsub)
+            unsub();
+        portSubs?.delete(subId);
+        bound.delete(subId); // handleSub/handleRtdbSub re-records it
+        if (isRtdbSub(msg)) {
+            handleRtdbSub(ctx, port, msg);
+        }
+        else {
+            handleSub(ctx, port, msg);
+        }
+    }
+}
+function handleSub(ctx, port, msg) {
+    // 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;
+    let unsub;
+    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);
+}
+function handleRtdbSub(ctx, port, msg) {
+    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, (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, port, msg, target) {
+    return onSnapshot(target, (snap) => {
+        // Detect doc vs query snapshot by shape.
+        const snapAny = snap;
+        if (Array.isArray(snapAny.docs)) {
+            // Query snapshot
+            const docs = snapAny.docs.map((d) => serializeDocSnap(d));
+            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),
+            });
+        }
+    }, (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) } });
+    });
+}
+function handleUnsub(ctx, port, msg) {
+    // 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);
+}
+// ─── Main dispatch ────────────────────────────────────────────────────────
+/**
+ * Handle one inbound message from a port.
+ *
+ * This is the primary unit-testable seam. Tests create a real `HostCtx`
+ * backed by an in-memory pyric sandbox and call this function directly
+ * with fake port objects, exercising the full op+subscription lifecycle
+ * without a real SharedWorker.
+ */
+/**
+ * Agent tool-call dispatch. The bridge peer forwards `tool` messages so the
+ * agent runs the canonical sandbox tool set against THIS worker's sandbox (the
+ * same instance the app + Studio use) instead of a separate in-page backend.
+ * Replies with a `res` whose value is the `{ ok, summary, data }` result.
+ */
+async function handleTool(ctx, port, msg) {
+    try {
+        ctx.toolDispatch ??= buildSandboxDispatcher(ctx.sandbox);
+        const result = await ctx.toolDispatch(msg.name, msg.args ?? {});
+        // Pre-serialize via JSON BEFORE the structured-clone hop over the port. Read
+        // results carry real firebase wrapper instances (Timestamp/GeoPoint/Bytes/
+        // VectorValue) whose toJSON() produces the canonical agent-facing shapes.
+        // structuredClone would strip those prototypes (losing toJSON) and post
+        // mangled internals, and would throw DataCloneError on any non-cloneable
+        // field. JSON.stringify here runs toJSON() while the instances are intact and
+        // yields a plain, clone-safe object — matching the in-page path, which
+        // JSON-stringified at the bridge. A serialization error lands in the catch
+        // below, never in postMessage.
+        ok(port, msg.id, JSON.parse(JSON.stringify(result)));
+    }
+    catch (e) {
+        fail(port, msg.id, e);
+    }
+}
+export async function handleMessage(ctx, port, msg) {
+    // Op provenance, stamped MECHANICALLY at dispatch:
+    //   - `actor`: a client that DECLARED itself the issuer (`issuer: 'studio'`,
+    //     stamped by Studio's worker client — see `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`) is stamped whenever
+    //     present — independent of issuer declaration, because admin is admin
+    //     regardless of who asked (an agent tool relay's admin op must classify
+    //     as a rules BYPASS in Traffic, not as a rules allow). Without this,
+    //     Firestore admin-lens ops carried no lens on their events and
+    //     `verdictFor` mislabeled the bypass as ALLOW (the RTDB/Firestore
+    //     asymmetry the traffic-metrics work flagged).
+    // Events an emitter already stamped win over the window (stampProvenance
+    // semantics: the event's own field always beats the ambient default).
+    const issuer = msg.issuer;
+    const actAs = msg.actAs;
+    if ((issuer === 'studio' || actAs) && ctx.sandbox.runWithProvenance) {
+        return ctx.sandbox.runWithProvenance({
+            ...(issuer === 'studio' ? { actor: { kind: 'studio' } } : {}),
+            ...(actAs ? { authLens: actAs } : {}),
+        }, () => dispatchMessage(ctx, port, msg));
+    }
+    return dispatchMessage(ctx, port, msg);
+}
+async function dispatchMessage(ctx, port, msg) {
+    if (msg.t === 'op') {
+        if (isAuthOp(msg.method)) {
+            await handleAuthOp(ctx, port, msg);
+        }
+        else {
+            await handleOp(ctx, port, msg);
+        }
+    }
+    else if (msg.t === 'sub') {
+        if (isAuthSub(msg)) {
+            handleAuthSub(ctx, port, msg);
+        }
+        else if (isEventSub(msg)) {
+            handleEventSub(ctx, port, msg);
+        }
+        else if (isRtdbSub(msg)) {
+            handleRtdbSub(ctx, port, msg);
+        }
+        else {
+            handleSub(ctx, port, msg);
+        }
+    }
+    else if (msg.t === 'unsub') {
+        // An unsub may target an auth sub, an event-stream sub, or a Firestore
+        // listener — try the cheap routing registries first, then fall through to
+        // the Firestore listener teardown.
+        if (!handleAuthUnsub(ctx, port, msg.subId) &&
+            !handleEventUnsub(ctx, port, msg.subId)) {
+            handleUnsub(ctx, port, msg);
+        }
+    }
+    else if (msg.t === 'tool') {
+        await handleTool(ctx, port, msg);
+    }
+}
+// ─── Port cleanup ─────────────────────────────────────────────────────────
+/**
+ * Tear down all subscriptions for a disconnected port.
+ * Called when a port's `close` event fires (browser best-effort) or
+ * when the entry point explicitly cleans up a port.
+ */
+export function cleanupPort(ctx, port) {
+    // Drop the port's auth subscriptions (routing entries — no real listener
+    // to tear down), its per-port session, and its session-bound sub records
+    // (#754).
+    authSubsFor(ctx).delete(port);
+    cleanupPortSession(ctx, port);
+    _sessionSubs.get(ctx)?.delete(port);
+    // Drop the port's event-stream subscriptions too (also routing entries off
+    // the single shared `sandbox.onEvent` subscription — nothing to unsubscribe,
+    // just stop fanning out to a dead port).
+    eventSubsFor(ctx).delete(port);
+    const portSubs = ctx.subs.get(port);
+    if (!portSubs)
+        return;
+    for (const unsub of portSubs.values()) {
+        unsub();
+    }
+    ctx.subs.delete(port);
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────
+function ensurePortSubs(ctx, port) {
+    if (!ctx.subs.has(port)) {
+        ctx.subs.set(port, new Map());
+    }
+}
+//# sourceMappingURL=host.js.map