pyric 0.0.1 → 0.1.0-alpha.7

package/dist/firestore/index.js

@@ -0,0 +1,1536 @@
+/**
+ * `pyric/firestore` — modular Web-SDK Firestore adapter for the
+ * Pyric sandbox.
+ *
+ * Mirrors `firebase/firestore`'s tree-shakable free-function shape:
+ * `getDoc`, `setDoc`, `addDoc`, `query`, `where`, `orderBy`, `limit`,
+ * `onSnapshot`, `runTransaction`, etc. All operations route to one of
+ * two backends, picked at init time:
+ *
+ *   - **Sandbox target** — wraps `pyric-admin`'s chainable adapter,
+ *     which sits on `pyric/sandbox`'s `LocalEnvironment`. No
+ *     network. Identity comes from a `SandboxContext`.
+ *   - **Prod target** — wraps `firebase/firestore` against a real
+ *     Firebase project. Identity comes from `firebase/auth`'s
+ *     current user.
+ *
+ * Same call surface across both. Agent code that writes against the
+ * sandbox during iteration runs unmodified against prod at deploy.
+ *
+ * The dual-target machinery lives in two pieces:
+ *   - {@link TARGET_SYMBOL} — hidden brand on every {@link Firestore}
+ *     handle that names the active backend.
+ *   - {@link refToTarget} — WeakMap from refs/queries back to their
+ *     owning target, so chained calls (`query(coll, where(...))`,
+ *     `getDocs(q)`) recover routing without re-tagging at every step.
+ *
+ * Every public function has a `target.kind` switch with explicit
+ * branches — the structure is parallel and grep-friendly.
+ */
+import { getFirestore as getChainableFirestore, getAdminFirestore as getChainableAdminFirestore, Timestamp as ChainTimestamp, FieldValue as ChainFieldValue, FOLLOWS_CURRENT_USER, SandboxError, } from 'pyric/sandbox/admin-firestore';
+import { SandboxContextImpl } from 'pyric/sandbox';
+import { getInternalEnv } from 'pyric/sandbox/internal';
+import { Bytes as RulesBytes, LatLng as RulesLatLng, Vector as RulesVector, lintFirestoreRules, } from 'pyric/rules';
+import * as fb from 'firebase/firestore';
+// Phase 3 unified app handle. Adapter dispatch reads `APP_TARGET` and
+// routes to the existing direct-handle path (sandbox vs prod).
+import { APP_TARGET } from 'pyric/app';
+// ─── Branding + routing ───────────────────────────────────────────────
+/**
+ * Hidden property on every {@link Firestore} handle. Discriminates
+ * between sandbox and prod backends so free functions can route
+ * without consumer-visible API differences.
+ */
+export const TARGET_SYMBOL = Symbol('pyric/firestore/target');
+/** True for both sandbox variants — used at dispatch sites that share a
+ *  branch (every sandbox op routes the same way once we've resolved the
+ *  chainable handle). The prod branch is the complement. */
+function isSandboxKind(target) {
+    return target.kind === 'sandbox' || target.kind === 'sandbox-live';
+}
+/**
+ * Resolve a sandbox-flavored target to its chainable Firestore handle.
+ *
+ * `sandbox` targets carry a frozen handle from `getFirestore(ctx)` time;
+ * `sandbox-live` targets build a fresh handle bound to the sandbox's
+ * current `currentUser` at every call. Callers that issue multiple ops
+ * in a row should cache the result into a local — every `getDb()` call
+ * rebuilds the chainable, which is correct but wasteful when the auth
+ * state hasn't moved between adjacent ops.
+ */
+function sandboxDb(target) {
+    return target.kind === 'sandbox' ? target.db : target.getDb();
+}
+/**
+ * Map from refs / queries to their owning target. Populated by every
+ * factory + chaining operation; consulted by every free function.
+ *
+ * WeakMap keys let entries GC alongside the refs that produced them.
+ */
+const refToTarget = new WeakMap();
+function tag(obj, target) {
+    refToTarget.set(obj, target);
+    return obj;
+}
+/**
+ * For `sandbox-live` refs/queries, record a closure that rebuilds the
+ * chainable ref against a fresh `SandboxFirestore` handle. Used by
+ * every dispatch site to re-resolve the ref under the sandbox's
+ * *current* `currentUser` rather than the auth that was active when
+ * the ref was first built.
+ *
+ * Necessary because `pyric-admin`'s chainable refs capture auth at
+ * construction time — calling `chainRef.get()` on a held ref runs
+ * under the auth from when the ref was built, not from when the op
+ * fires. For sandbox-live, every op must construct a fresh chainable
+ * ref bound to the current ctx before issuing the op.
+ *
+ * The closure form supports the full chain: `doc(coll, id)` rebuilds
+ * via `rebuild(coll)(db).doc(id)`; `query(coll, where(...))` rebuilds
+ * via `apply(constraints)` over the rebuilt source. Stored only for
+ * sandbox-live refs — the `sandbox` (frozen-ctx) and `prod` paths
+ * keep their existing held-ref semantics.
+ */
+const sandboxLiveRebuild = new WeakMap();
+function tagLive(obj, target, rebuild) {
+    refToTarget.set(obj, target);
+    sandboxLiveRebuild.set(obj, rebuild);
+    return obj;
+}
+/** Resolve the chainable doc ref to use for an op against `ref`. For
+ *  `sandbox`, returns the held chainable; for `sandbox-live`, runs
+ *  the recorded rebuild closure against a fresh handle. */
+function chainDocFor(target, ref) {
+    const underlying = underlyingOf(ref);
+    if (target.kind === 'sandbox')
+        return underlying;
+    const rebuild = sandboxLiveRebuild.get(underlying);
+    if (!rebuild) {
+        throw new TypeError('pyric/firestore: live ref missing rebuild closure — was it produced by a factory in this package?');
+    }
+    return rebuild(sandboxDb(target));
+}
+/** Same as {@link chainDocFor} but typed for collection refs. */
+function chainCollFor(target, ref) {
+    const underlying = underlyingOf(ref);
+    if (target.kind === 'sandbox')
+        return underlying;
+    const rebuild = sandboxLiveRebuild.get(underlying);
+    if (!rebuild) {
+        throw new TypeError('pyric/firestore: live collection ref missing rebuild closure.');
+    }
+    return rebuild(sandboxDb(target));
+}
+/** Same as {@link chainDocFor} but typed for queries. */
+function chainQueryFor(target, q) {
+    const underlying = underlyingOf(q);
+    if (target.kind === 'sandbox')
+        return underlying;
+    const rebuild = sandboxLiveRebuild.get(underlying);
+    if (!rebuild) {
+        throw new TypeError('pyric/firestore: live query missing rebuild closure.');
+    }
+    return rebuild(sandboxDb(target));
+}
+/**
+ * Tag a sandbox-flavored ref + (optionally) record its rebuild
+ * closure. Routes to {@link tag} for frozen-ctx targets and
+ * {@link tagLive} for live targets. Centralizes the per-factory
+ * "record rebuild on live, plain tag on frozen" decision.
+ */
+function tagSandboxRef(obj, target, rebuild) {
+    if (target.kind === 'sandbox-live') {
+        return tagLive(obj, target, rebuild);
+    }
+    return tag(obj, target);
+}
+/** Resolve a sandbox-flavored parent's rebuild closure. For
+ *  sandbox-live, the parent must have been tagged via
+ *  {@link tagSandboxRef}; for sandbox, returns a no-op stand-in
+ *  since the held chainable is the only ref the dispatch sites use.
+ *
+ *  Used by chaining factories (`doc(coll, …)`, `collection(doc, …)`,
+ *  `query(coll, …)`) to derive a rebuild that reads the parent's
+ *  rebuild and applies one more step. */
+function parentRebuild(parent) {
+    const underlying = underlyingOf(parent);
+    const fn = sandboxLiveRebuild.get(underlying);
+    if (fn)
+        return fn;
+    // Frozen-ctx target. The chainable parent ref is bound to the same
+    // ctx for life; returning it as-is is correct because frozen-ctx
+    // chaining is what `pyric-admin`'s adapter already supports.
+    return () => underlying;
+}
+function targetOf(refOrDb) {
+    if (TARGET_SYMBOL in refOrDb) {
+        return refOrDb[TARGET_SYMBOL];
+    }
+    const t = refToTarget.get(refOrDb);
+    if (!t) {
+        throw new TypeError('pyric/firestore: unrecognized reference — was it produced by a factory in this package?');
+    }
+    return t;
+}
+const refToConverter = new WeakMap();
+const refToUnderlying = new WeakMap();
+function converterOf(obj) {
+    return refToConverter.get(obj);
+}
+/** Resolve to the plain chain / fb ref. `withConverter` shells point
+ *  at the underlying; everything else is its own underlying. */
+function underlyingOf(obj) {
+    return refToUnderlying.get(obj) ?? obj;
+}
+/** Build a new sandbox shell that points at `underlying` and carries
+ *  `converter`. Inherits routing + identity (id/path) from underlying.
+ *
+ *  Accepts both `SandboxTarget` and `SandboxLiveTarget`: the shell
+ *  exists at the modular layer (above the chainable), so it only
+ *  needs to record routing for `targetOf` and the underlying pointer
+ *  for `underlyingOf`. The chain re-resolution (under current auth)
+ *  happens at op time via {@link chainDocFor} / {@link chainCollFor}
+ *  / {@link chainQueryFor} on the underlying. */
+function buildSandboxShell(underlying, target, converter) {
+    const shell = {
+        id: underlying.id ?? '',
+        path: underlying.path ?? '',
+    };
+    refToConverter.set(shell, converter);
+    refToUnderlying.set(shell, underlying);
+    refToTarget.set(shell, target);
+    return shell;
+}
+export function getFirestore(target) {
+    // PyricApp dispatch: inspect the brand and forward to the existing
+    // direct-handle path. Kept ABOVE the legacy probes so a sandbox-app
+    // handle (which structurally carries `sandbox` + the brand symbol)
+    // routes through the unified path, not the structural sandbox sniff.
+    if (isPyricApp(target)) {
+        return target[APP_TARGET] === 'sandbox'
+            ? getFirestore(target.sandbox)
+            : getFirestore(target.firebaseApp);
+    }
+    if (isSandboxContext(target)) {
+        const chainable = getChainableFirestore(target);
+        const t = { kind: 'sandbox', db: chainable, sandbox: target.sandbox };
+        return { [TARGET_SYMBOL]: t };
+    }
+    if (isSandbox(target)) {
+        const t = {
+            kind: 'sandbox-live',
+            sandbox: target,
+            getDb: makeGetDb(target),
+        };
+        return { [TARGET_SYMBOL]: t };
+    }
+    const fbDb = fb.getFirestore(target);
+    const t = { kind: 'prod', db: fbDb };
+    return { [TARGET_SYMBOL]: t };
+}
+/**
+ * A Firestore handle scoped to a specific identity, for multi-user testing.
+ *
+ * `actingAs(sandbox, { uid })` returns a `Firestore` whose ops evaluate security
+ * rules as that user (`request.auth.uid === uid`; custom claims via `token`);
+ * `actingAs(sandbox, null)` is the anonymous (signed-out) path. Multiple
+ * identities over ONE sandbox share the same store, so a write by one is
+ * delivered to another's `onSnapshot`: the basis for multi-user sync testing.
+ *
+ * @example
+ * ```ts
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { actingAs, doc, setDoc, onSnapshot } from 'pyric/firestore';
+ * const sandbox = initializeSandbox();
+ * const alice = actingAs(sandbox, { uid: 'alice' });
+ * const bob   = actingAs(sandbox, { uid: 'bob', token: { role: 'member' } });
+ * onSnapshot(doc(bob, 'rooms/r1'), () => {
+ *   // fires when alice writes (same store; rules evaluated as bob)
+ * });
+ * await setDoc(doc(alice, 'rooms/r1'), { owner: 'alice' });
+ * ```
+ *
+ * Thin sugar over `getFirestore(sandbox.withAuth(identity))`; the value is a
+ * named, discoverable seam for multi-user scenarios. See
+ * the design rationale.
+ */
+export function actingAs(sandbox, identity) {
+    return getFirestore(sandbox.withAuth(identity));
+}
+export function getAdminFirestore(target) {
+    // Sandbox-backed PyricApp → unwrap to its Sandbox. A prod-backed app has
+    // no admin-bypass analog, so reject it loudly rather than silently
+    // returning a rules-enforced prod handle.
+    if (isPyricApp(target)) {
+        if (target[APP_TARGET] !== 'sandbox') {
+            throw new TypeError('getAdminFirestore: the admin (rules-bypass) lens is sandbox-only — ' +
+                'a prod-backed app has no way to bypass deployed security rules.');
+        }
+        return getAdminFirestore(target.sandbox);
+    }
+    const sandbox = isSandboxContext(target) ? target.sandbox : target;
+    const chainable = getChainableAdminFirestore(sandbox);
+    const t = { kind: 'sandbox', db: chainable, sandbox };
+    return { [TARGET_SYMBOL]: t };
+}
+/**
+ * Brand-based test for the {@link PyricApp} overload. Reads the
+ * `APP_TARGET` symbol that `pyric/app`'s `initializeApp` stamps on
+ * every handle. Cheap + collision-free: a `Sandbox` / `FirebaseApp`
+ * / `SandboxContext` will never carry this symbol.
+ */
+function isPyricApp(target) {
+    return (target !== null
+        && typeof target === 'object'
+        && APP_TARGET in target);
+}
+/**
+ * Brand-based test for the SandboxContext overload. Uses
+ * `instanceof SandboxContextImpl` for robustness — structural
+ * dispatch would silently break if `SandboxContext`'s shape ever
+ * changed, or if a future `FirebaseApp` grew a `withAuth` method.
+ *
+ * Internal — consumers always call `getFirestore` and let the
+ * dispatch figure it out.
+ */
+function isSandboxContext(target) {
+    return target instanceof SandboxContextImpl;
+}
+/**
+ * Structural test for the `Sandbox` overload. The class is internal
+ * to `pyric/sandbox` (not exported), so we recognize it by the
+ * presence of `currentUser` + `onCurrentUserChanged` + `withAuth` +
+ * `admin` — the four members that distinguish `Sandbox` from
+ * `SandboxContext` (which has `withAuth` only) and `FirebaseApp`
+ * (which has none). Tightening to a brand symbol would require an
+ * `pyric/sandbox` change; structural recognition is safe here
+ * because every member of this set has been on `Sandbox` since v0
+ * and `FirebaseApp` would have to grow all four to collide.
+ */
+function isSandbox(target) {
+    if (target === null || typeof target !== 'object')
+        return false;
+    const o = target;
+    return (typeof o.withAuth === 'function'
+        && typeof o.onCurrentUserChanged === 'function'
+        && 'currentUser' in o
+        && 'admin' in o);
+}
+/**
+ * Build the per-call ctx-resolver for a `sandbox-live` target. Each
+ * call reads `sandbox.currentUser` (the source of truth that
+ * `pyric/auth` writes through to), constructs a fresh
+ * `SandboxContext`, and returns the chainable Firestore handle bound
+ * to it. Constructing per-call is cheap — `SandboxContext` is a tiny
+ * object — and `pyric-admin`'s `getFirestore(ctx)` caches by ctx
+ * identity via WeakMap, so the chainable is collected once the ctx
+ * is.
+ *
+ * `withAuth(null)` is the anonymous path; rules evaluate with
+ * `request.auth == null`, matching production Firebase Auth's
+ * "signed out" state.
+ */
+function makeGetDb(sandbox) {
+    return () => {
+        const ctx = sandbox.withAuth(sandbox.currentUser);
+        return getChainableFirestore(ctx);
+    };
+}
+export { SandboxError };
+// ─── Tier 1: scalar types + sentinels re-exported from firebase ──────
+//
+// These types are class shapes (or sentinels) the `firebase/firestore`
+// modular SDK exposes. They're shared across both targets in the
+// sense that:
+//
+//   - **Prod target** uses them natively (round-trips through the
+//     wire encoder, server stores them as proper Firestore values).
+//   - **Sandbox target** rides `Bytes`, `GeoPoint`, and `VectorValue`
+//     through their converters at `sandbox/firestore/converters/` on
+//     write, then finalizes the read back to `fb.Bytes` / `fb.GeoPoint`
+//     / `fb.VectorValue` in {@link finalizeSandboxValue} so consumer
+//     code's `instanceof` checks match prod. `vector()` / `VectorValue`
+//     are re-exported from `firebase/firestore` like the others.
+//
+// `documentId()` and `FieldPath` ARE supported on both sides today —
+// `documentId()` returns a `FieldPath` sentinel that the chainable
+// adapter recognizes as "by document id" when passed to `where()`.
+export { Bytes, GeoPoint, documentId, FieldPath, vector, VectorValue, } from 'firebase/firestore';
+// ─── Tier 1: equality helpers (target-aware) ─────────────────────────
+/**
+ * Structural equality for two refs / queries / snapshots. The
+ * native helpers (`fb.refEqual` etc.) only handle prod-shape values;
+ * for sandbox-shape values we fall back to a fullPath / toString
+ * comparison that matches the JS SDK's semantics. Throws when the
+ * pair routes to different targets — that's a programming error.
+ */
+/**
+ * Routing match for equality helpers. Sandbox and sandbox-live are
+ * compatible at the equality layer — two refs that name the same
+ * path are equal regardless of whether their owning Firestore
+ * handle was built from a frozen `SandboxContext` or a live
+ * `Sandbox`. The structural comparison falls back to `fullPath` /
+ * `toString` per the JS SDK's semantics, which works uniformly
+ * across both shapes.
+ *
+ * Crossing sandbox vs prod is still a programming error and throws.
+ */
+function targetMatch(a, b) {
+    const ta = targetOf(a);
+    const tb = targetOf(b);
+    const aSandbox = isSandboxKind(ta);
+    const bSandbox = isSandboxKind(tb);
+    if (aSandbox !== bSandbox) {
+        throw new TypeError('pyric/firestore: cannot compare references / queries / snapshots across different targets.');
+    }
+    return ta;
+}
+/** True when two `DocumentReference`s point at the same path under
+ *  the same target. */
+export function refEqual(a, b) {
+    const t = targetMatch(a, b);
+    if (t.kind === 'prod')
+        return fb.refEqual(asFbDoc(a), asFbDoc(b));
+    // Sandbox + sandbox-live both compare by path — `underlyingOf` peels
+    // any `withConverter` shell so a typed ref equals its underlying.
+    return underlyingOf(a).path
+        === underlyingOf(b).path;
+}
+/** True when two `Query`s are structurally identical (same source +
+ *  same constraint chain). */
+export function queryEqual(a, b) {
+    const t = targetMatch(a, b);
+    if (t.kind === 'prod')
+        return fb.queryEqual(asFbQuery(a), asFbQuery(b));
+    // Sandbox-target queries don't expose a deep-equality contract;
+    // fall back to identity. Most consumer code that asks `queryEqual`
+    // is comparing the same returned object against a cached one,
+    // which identity handles.
+    return a === b;
+}
+/** True when two `DocumentSnapshot` / `QuerySnapshot` pairs describe
+ *  the same underlying data + path. */
+export function snapshotEqual(a, b) {
+    const t = targetMatch(a, b);
+    if (t.kind === 'prod') {
+        return fb.snapshotEqual(a, b);
+    }
+    return a === b;
+}
+// ─── Tier 1: emulator connect (prod-target only) ─────────────────────
+/**
+ * Point the prod-target Firestore handle at the Firestore emulator.
+ * Must be called BEFORE any operation runs against `db`. No-op on
+ * sandbox-target handles (the sandbox IS a local emulator).
+ *
+ * `options` mirrors `firebase/firestore`'s shape — pass
+ * `{ mockUserToken: '…' }` to bypass auth checks under the emulator,
+ * matching how the JS SDK lets tests skip Firebase Auth.
+ */
+export function connectFirestoreEmulator(db, host, port, options) {
+    const target = targetOf(db);
+    if (isSandboxKind(target)) {
+        // The sandbox already runs locally; pointing it at an emulator
+        // host is a no-op rather than an error so consumer code that
+        // does the wiring unconditionally compiles against both targets.
+        return;
+    }
+    fb.connectFirestoreEmulator(target.db, host, port, options);
+}
+// Shorthand: cast helpers used inside route arms. The runtime objects
+// match these shapes precisely; the casts let the routing keep its
+// single-typed public surface.
+function asChainDoc(r) { return r; }
+function asChainColl(r) { return r; }
+function asChainQuery(r) { return r; }
+function asFbDoc(r) { return r; }
+function asFbColl(r) { return r; }
+function asFbQuery(r) { return r; }
+// ─── Path constructors ────────────────────────────────────────────────
+export function doc(parent, ...pathSegments) {
+    const target = targetOf(parent);
+    const isHandle = TARGET_SYMBOL in parent;
+    // Propagate any converter from a typed collection to the resulting
+    // doc — `doc(coll<User>, 'u1')` returns `DocumentReference<User>`.
+    // For prod, fb's `.doc()` chain inherits the converter natively, so
+    // this only needs to fire on the sandbox side.
+    const conv = isHandle ? undefined : converterOf(parent);
+    if (isSandboxKind(target)) {
+        const db = sandboxDb(target);
+        if (isHandle) {
+            if (pathSegments.length === 0) {
+                throw new TypeError('doc(db, path) requires at least one path segment.');
+            }
+            const path = pathSegments.join('/');
+            const built = db.doc(path);
+            const tagged = tagSandboxRef(built, target, (fresh) => fresh.doc(path));
+            return tagged;
+        }
+        const coll = asChainColl(underlyingOf(parent));
+        const ref = pathSegments.length === 0
+            ? coll.doc()
+            : coll.doc(pathSegments.join('/'));
+        // The path is now known (either the explicit segments under the
+        // parent's path, or the auto-minted id appended). Rebuild from
+        // the absolute path so the live ref re-resolves under whatever
+        // auth the next op picks up.
+        const absPath = ref.path;
+        const tagged = tagSandboxRef(ref, target, (fresh) => fresh.doc(absPath));
+        if (conv) {
+            return buildSandboxShell(tagged, target, conv);
+        }
+        return tagged;
+    }
+    // prod
+    if (isHandle) {
+        if (pathSegments.length === 0) {
+            throw new TypeError('doc(db, path) requires at least one path segment.');
+        }
+        return tag(fb.doc(target.db, pathSegments.join('/')), target);
+    }
+    const coll = asFbColl(parent);
+    const ref = pathSegments.length === 0
+        ? fb.doc(coll)
+        : fb.doc(coll, pathSegments.join('/'));
+    return tag(ref, target);
+}
+/**
+ * Cross-collection query — scans every document under every
+ * collection whose final segment matches `collectionId`. Mirrors
+ * `firebase/firestore`'s `collectionGroup(db, id)` shape.
+ *
+ * Returned `Query` accepts the same `where` / `orderBy` / `limit`
+ * constraints as any other query.
+ */
+export function collectionGroup(db, collectionId) {
+    const target = targetOf(db);
+    if (isSandboxKind(target)) {
+        const q = sandboxDb(target).collectionGroup(collectionId);
+        return tagSandboxRef(q, target, (fresh) => fresh.collectionGroup(collectionId));
+    }
+    const q = fb.collectionGroup(target.db, collectionId);
+    return tag(q, target);
+}
+export function collection(parent, ...pathSegments) {
+    const target = targetOf(parent);
+    const isHandle = TARGET_SYMBOL in parent;
+    if (pathSegments.length === 0) {
+        throw new TypeError('collection() requires at least one path segment.');
+    }
+    // Note: any converter on `parent` (typed DocumentReference<T>) does
+    // NOT propagate to the sub-collection — matches `firebase/firestore`'s
+    // `collection(typedDoc, path)` returning `CollectionReference<DocumentData>`.
+    // A parent doc's T describes its own data, not its subcollections'.
+    if (isSandboxKind(target)) {
+        if (isHandle) {
+            const path = pathSegments.join('/');
+            const built = sandboxDb(target).collection(path);
+            return tagSandboxRef(built, target, (fresh) => fresh.collection(path));
+        }
+        const docRef = asChainDoc(underlyingOf(parent));
+        const subPath = pathSegments.join('/');
+        const built = docRef.collection(subPath);
+        const absPath = built.path;
+        return tagSandboxRef(built, target, (fresh) => fresh.collection(absPath));
+    }
+    // prod
+    if (isHandle) {
+        return tag(fb.collection(target.db, pathSegments.join('/')), target);
+    }
+    const docRef = asFbDoc(parent);
+    return tag(fb.collection(docRef, pathSegments.join('/')), target);
+}
+// ─── Reads ────────────────────────────────────────────────────────────
+function isNumberArray(a) {
+    return Array.isArray(a) && a.every((n) => typeof n === 'number');
+}
+/**
+ * A vector read from the sandbox may arrive as a live `Vector` wrapper, a
+ * prototype-stripped plain object (`{typeName:'vector', value}`), or the wire
+ * sentinel (`{__type__:'__vector__', value}`). Duck-type all three; `instanceof`
+ * alone misses the stripped form the read path hands back. Returns the
+ * components, or null if `value` isn't a vector.
+ */
+function vectorValuesOf(value) {
+    if (value instanceof RulesVector)
+        return Array.from(value.value);
+    if (value === null || typeof value !== 'object')
+        return null;
+    const o = value;
+    if (o.typeName === 'vector' && isNumberArray(o.value))
+        return o.value;
+    if (o.__type__ === '__vector__' && isNumberArray(o.value))
+        return o.value;
+    return null;
+}
+/**
+ * Final read-path translation for sandbox-target snapshots.
+ *
+ * The admin-compat read-path walker (in `pyric/sandbox`'s admin-compat
+ * `snapshots.ts`) leaves `pyric/rules` wrappers (`Bytes`,
+ * `LatLng`) as identity — it can't translate them to
+ * `firebase/firestore`'s `Bytes` / `GeoPoint` because the admin-compat
+ * layer doesn't depend on `firebase/firestore`.
+ *
+ * This package does, so we do the final hop here: walk the value tree
+ * and convert any rules-wrapper instance into its `firebase/firestore`
+ * counterpart so consumer code can rely on
+ * `data.b instanceof fb.Bytes === true` and
+ * `data.g instanceof fb.GeoPoint === true` against sandbox reads —
+ * matching the prod-target invariant.
+ *
+ * Closes firestore COMPAT rows #109 (`Bytes`) and #110 (`GeoPoint`).
+ * Vectors (#111, `VectorValue` / `vector()`) round-trip the same way as of
+ * Phase 0-F; the formal COMPAT ✓ + oracle observation land with the
+ * conformance phase (Phase 5b). Vector SEARCH (`findNearest`) is separate.
+ */
+function finalizeSandboxValue(value) {
+    if (value instanceof RulesBytes) {
+        return fb.Bytes.fromUint8Array(value.data);
+    }
+    if (value instanceof RulesLatLng) {
+        return new fb.GeoPoint(value.lat, value.lng);
+    }
+    const vectorValues = vectorValuesOf(value);
+    if (vectorValues) {
+        return fb.vector(vectorValues);
+    }
+    if (Array.isArray(value)) {
+        return value.map(finalizeSandboxValue);
+    }
+    // Only walk plain objects (`{...}` literals + `Object.create(null)`).
+    // Class instances we don't recognize pass through as identity so we
+    // don't accidentally destructure their private state (the same gap
+    // that motivated #109/#110 in the first place).
+    if (value !== null && typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        if (proto === Object.prototype || proto === null) {
+            const out = {};
+            for (const [k, v] of Object.entries(value)) {
+                out[k] = finalizeSandboxValue(v);
+            }
+            return out;
+        }
+    }
+    return value;
+}
+function finalizeSandboxData(data) {
+    if (data === undefined)
+        return undefined;
+    return finalizeSandboxValue(data);
+}
+/**
+ * Wrap a raw sandbox `DocumentSnapshot` so `.data()` runs the final
+ * value translation (rules wrappers → `firebase/firestore` types).
+ * Other surface (id / ref / exists) passes through unchanged so
+ * `tagSnapshotRefs` still operates on the original snap object.
+ */
+function wrapSandboxDocSnap(snap) {
+    const s = snap;
+    const original = s.data.bind(snap);
+    Object.defineProperty(s, 'data', {
+        value: () => finalizeSandboxData(original()),
+        configurable: true,
+        writable: true,
+    });
+    return snap;
+}
+/**
+ * Wrap a plain sandbox `DocumentSnapshot` so `.data()` runs the
+ * converter's `fromFirestore`. Identity / `exists` pass through.
+ */
+function applyConverterToDocSnap(snap, conv) {
+    return {
+        id: snap.id,
+        exists: snap.exists,
+        data: () => {
+            // Sandbox snaps expose `exists` as a property (Admin shape).
+            const exists = typeof snap.exists === 'function'
+                ? snap.exists()
+                : snap.exists;
+            if (!exists)
+                return undefined;
+            const raw = finalizeSandboxData(snap.data());
+            // fromFirestore receives a QueryDocumentSnapshot-narrowed view —
+            // doc is known to exist at this branch, so `data()` returns the
+            // raw value (never undefined).
+            const queryDocSnap = {
+                id: snap.id,
+                exists: true,
+                data: () => raw,
+            };
+            return conv.fromFirestore(queryDocSnap);
+        },
+    };
+}
+export async function getDoc(ref) {
+    const target = targetOf(ref);
+    if (isSandboxKind(target)) {
+        const conv = converterOf(ref);
+        const snap = await chainDocFor(target, ref).get();
+        if (conv) {
+            return applyConverterToDocSnap(snap, conv);
+        }
+        // Normalize `.exists` to method form + tag the snap's ref so
+        // consumers get Firebase-modular-SDK shape uniformly.
+        tagSnapshotRefs(snap, target);
+        // Wrap .data() to translate `pyric/rules` wrappers
+        // (Bytes / LatLng) into `firebase/firestore` types so reads match
+        // prod's instanceof semantics. Closes firestore #109 + #110.
+        return wrapSandboxDocSnap(snap);
+    }
+    return fb.getDoc(asFbDoc(ref));
+}
+export async function getDocs(query) {
+    const target = targetOf(query);
+    if (isSandboxKind(target)) {
+        const conv = converterOf(query);
+        const snap = await chainQueryFor(target, query).get();
+        if (conv) {
+            const c = conv;
+            const wrappedDocs = snap.docs.map((d) => applyConverterToDocSnap(d, c));
+            return {
+                size: wrappedDocs.length,
+                empty: wrappedDocs.length === 0,
+                docs: wrappedDocs,
+            };
+        }
+        // Normalize each doc's `.exists` + tag the doc refs so consumer
+        // code targeting Firebase's modular SDK works uniformly.
+        tagSnapshotRefs(snap, target);
+        // Wrap each doc snap's .data() to translate rules-wrappers to
+        // `firebase/firestore` types — same parity hop as `getDoc` above.
+        const docs = snap.docs;
+        for (const d of docs)
+            wrapSandboxDocSnap(d);
+        return snap;
+    }
+    return fb.getDocs(asFbQuery(query));
+}
+export async function setDoc(ref, data, options) {
+    const target = targetOf(ref);
+    if (isSandboxKind(target)) {
+        const conv = converterOf(ref);
+        const payload = conv
+            ? conv.toFirestore(data)
+            : data;
+        // Pass `options` through verbatim — `ChainSetOptions` is structurally
+        // the same shape as our public `SetOptions` (sandbox layer adds an
+        // optional `auth` field we don't expose at the modular layer).
+        return chainDocFor(target, ref).set(payload, options);
+    }
+    // Prod refs that came through `withConverter` carry their converter
+    // on the fb ref itself — `fb.setDoc` invokes `toFirestore` natively.
+    if (options === undefined)
+        return fb.setDoc(asFbDoc(ref), data);
+    return fb.setDoc(asFbDoc(ref), data, options);
+}
+/**
+ * `updateDoc` does NOT run the converter. Matches `firebase/firestore`'s
+ * Web SDK shape — partial updates can target any subset of fields, so
+ * a translator built around a full `AppModelType` would be a type-shape
+ * mismatch. Use the underlying `DocumentData` view (`withConverter(ref,
+ * null)`) for typed-and-untyped mixed access if you need both styles
+ * against the same path.
+ */
+export async function updateDoc(ref, data) {
+    const target = targetOf(ref);
+    if (isSandboxKind(target))
+        return chainDocFor(target, ref).update(data);
+    return fb.updateDoc(asFbDoc(ref), data);
+}
+export async function deleteDoc(ref) {
+    const target = targetOf(ref);
+    if (isSandboxKind(target))
+        return chainDocFor(target, ref).delete();
+    return fb.deleteDoc(asFbDoc(ref));
+}
+export async function addDoc(coll, data) {
+    const target = targetOf(coll);
+    if (isSandboxKind(target)) {
+        const conv = converterOf(coll);
+        const payload = conv
+            ? conv.toFirestore(data)
+            : data;
+        const ref = await chainCollFor(target, coll).add(payload);
+        // The freshly-minted doc has its auto-id path baked in. Record a
+        // rebuild closure for sandbox-live so subsequent ops on `ref`
+        // re-resolve against the current user (matches the doc()-factory
+        // semantics for explicitly-pathed refs).
+        const absPath = ref.path;
+        const tagged = tagSandboxRef(ref, target, (fresh) => fresh.doc(absPath));
+        // Propagate the collection's converter onto the freshly-created
+        // doc ref so `getDoc(addDocResult)` round-trips through the same
+        // typing without an extra `withConverter` call. Matches fb's
+        // native behavior.
+        if (conv) {
+            return buildSandboxShell(tagged, target, conv);
+        }
+        return tagged;
+    }
+    const ref = await fb.addDoc(asFbColl(coll), data);
+    return tag(ref, target);
+}
+export function withConverter(source, converter) {
+    const target = targetOf(source);
+    if (target.kind === 'prod') {
+        // fb's native withConverter is on every ref / query — applies the
+        // converter to all subsequent reads / writes through fb's own API.
+        const native = source;
+        const out = native.withConverter(converter);
+        return tag(out, target);
+    }
+    // Sandbox.
+    if (converter === null) {
+        // Strip — return the underlying plain ref. Falls back to `source`
+        // itself if it was never wrapped (no-op).
+        return underlyingOf(source);
+    }
+    const underlying = underlyingOf(source);
+    return buildSandboxShell(underlying, target, converter);
+}
+export function query(source, ...constraints) {
+    const target = targetOf(source);
+    const conv = converterOf(source);
+    if (isSandboxKind(target)) {
+        // Apply constraints to the source's chainable query. For
+        // sandbox-live we rebuild via the parent's rebuild closure under
+        // a transient handle so the resulting tagged query has a known
+        // shape; the rebuild closure we record below applies the same
+        // constraint chain against a *fresh* handle at op time.
+        const sourceRebuild = parentRebuild(source);
+        const buildAt = (db) => {
+            let q = sourceRebuild(db);
+            for (const c of constraints)
+                q = c.applySandbox(q);
+            return q;
+        };
+        const q = buildAt(sandboxDb(target));
+        const tagged = tagSandboxRef(q, target, (fresh) => buildAt(fresh));
+        // Propagate any converter from a typed source through the new query.
+        if (conv) {
+            return buildSandboxShell(tagged, target, conv);
+        }
+        return tagged;
+    }
+    let q = asFbQuery(source);
+    for (const c of constraints)
+        q = c.applyProd(q);
+    return tag(q, target);
+}
+export function where(field, op, value) {
+    const sandboxFilter = { kind: 'where', field, op, value };
+    const fbFilter = fb.where(field, op, value);
+    return {
+        applySandbox: (q) => q.where(field, op, value),
+        applyProd: (q) => fb.query(q, fbFilter),
+        _sandboxFilter: sandboxFilter,
+        _fbFilter: fbFilter,
+    };
+}
+/**
+ * OR composite — at least one of the inner constraints must match.
+ * Each argument must itself be a filter constraint (`where()`, or
+ * nested `or()` / `and()`); passing `orderBy()` or `limit()` here is
+ * a type error at runtime.
+ *
+ * Mirrors `firebase/firestore`'s `or(...filters)` shape.
+ */
+export function or(...filters) {
+    return composite('or', filters);
+}
+/**
+ * AND composite. Same shape as `or()` but every inner constraint
+ * must match. Useful inside an `or()` to combine constraints that
+ * would otherwise be at the top level.
+ */
+export function and(...filters) {
+    return composite('and', filters);
+}
+/**
+ * Build a composite QueryConstraint. Extracts each sub-constraint's
+ * sandbox + fb filter representations; throws when any input is a
+ * non-filter (`orderBy` / `limit`).
+ */
+function composite(kind, filters) {
+    if (filters.length === 0) {
+        throw new TypeError(`pyric/firestore: ${kind}() requires at least one filter argument.`);
+    }
+    const sandboxSubs = [];
+    const fbSubs = [];
+    for (const c of filters) {
+        if (c._sandboxFilter === undefined || c._fbFilter === undefined) {
+            throw new TypeError(`pyric/firestore: ${kind}() received a non-filter constraint (orderBy / limit are not valid here).`);
+        }
+        sandboxSubs.push(c._sandboxFilter);
+        fbSubs.push(c._fbFilter);
+    }
+    const sandboxFilter = { kind, filters: sandboxSubs };
+    const fbFilter = kind === 'or' ? fb.or(...fbSubs) : fb.and(...fbSubs);
+    return {
+        applySandbox: (q) => q.applyFilter(sandboxFilter),
+        applyProd: (q) => fb.query(q, fbFilter),
+        _sandboxFilter: sandboxFilter,
+        _fbFilter: fbFilter,
+    };
+}
+export function orderBy(field, direction) {
+    return {
+        applySandbox: (q) => q.orderBy(field, direction),
+        applyProd: (q) => fb.query(q, fb.orderBy(field, direction)),
+    };
+}
+export function limit(n) {
+    return {
+        applySandbox: (q) => q.limit(n),
+        applyProd: (q) => fb.query(q, fb.limit(n)),
+    };
+}
+// ─── Cursor pagination + limitToLast (Tier 3) ────────────────────────
+//
+// Modular Web-SDK shape:
+//
+//   query(coll,
+//     orderBy('priority'),
+//     startAfter(prevPagePriority),
+//     limit(10),
+//   );
+//
+// Each cursor factory accepts a positional values list (one per
+// orderBy clause). For sandbox-target, the values pass straight into
+// the chainable Query.startCursor / endCursor methods; for prod, we
+// spread into `fb.startAt(...values)` etc. The DocumentSnapshot
+// overload (`startAt(snapshot)`) lands in a follow-up commit.
+/**
+ * Limit the query to the LAST `n` documents in the ordered result.
+ * Requires at least one `orderBy` on the query (production-aligned —
+ * the simulator throws at execute time without one).
+ */
+export function limitToLast(n) {
+    return {
+        applySandbox: (q) => q.limitToLast(n),
+        applyProd: (q) => fb.query(q, fb.limitToLast(n)),
+    };
+}
+/**
+ * Heuristic for the snapshot overload: a single argument whose
+ * `.data` is a function. Both the chainable adapter's
+ * `AdminDocumentSnapshot` and `firebase/firestore`'s
+ * `DocumentSnapshot` expose `.data()` so this catches both targets
+ * cleanly. Falls back to the values-spread variant for everything
+ * else (including a single non-snapshot scalar arg, which is
+ * legitimate when the orderBy is on one field).
+ */
+function isDocumentSnapshot(args) {
+    if (args.length !== 1)
+        return false;
+    const a = args[0];
+    return (a !== null &&
+        typeof a === 'object' &&
+        'data' in a &&
+        typeof a.data === 'function');
+}
+export function startAt(...args) {
+    if (isDocumentSnapshot(args)) {
+        const snap = args[0];
+        return {
+            applySandbox: (q) => q.startCursorFromSnapshot(snap, true),
+            applyProd: (q) => fb.query(q, fb.startAt(snap)),
+        };
+    }
+    return {
+        applySandbox: (q) => q.startCursor(args, true),
+        applyProd: (q) => fb.query(q, fb.startAt(...args)),
+    };
+}
+export function startAfter(...args) {
+    if (isDocumentSnapshot(args)) {
+        const snap = args[0];
+        return {
+            applySandbox: (q) => q.startCursorFromSnapshot(snap, false),
+            applyProd: (q) => fb.query(q, fb.startAfter(snap)),
+        };
+    }
+    return {
+        applySandbox: (q) => q.startCursor(args, false),
+        applyProd: (q) => fb.query(q, fb.startAfter(...args)),
+    };
+}
+export function endAt(...args) {
+    if (isDocumentSnapshot(args)) {
+        const snap = args[0];
+        return {
+            applySandbox: (q) => q.endCursorFromSnapshot(snap, true),
+            applyProd: (q) => fb.query(q, fb.endAt(snap)),
+        };
+    }
+    return {
+        applySandbox: (q) => q.endCursor(args, true),
+        applyProd: (q) => fb.query(q, fb.endAt(...args)),
+    };
+}
+export function endBefore(...args) {
+    if (isDocumentSnapshot(args)) {
+        const snap = args[0];
+        return {
+            applySandbox: (q) => q.endCursorFromSnapshot(snap, false),
+            applyProd: (q) => fb.query(q, fb.endBefore(snap)),
+        };
+    }
+    return {
+        applySandbox: (q) => q.endCursor(args, false),
+        applyProd: (q) => fb.query(q, fb.endBefore(...args)),
+    };
+}
+/** Factory: count() aggregate. */
+export function count() {
+    return { kind: 'count' };
+}
+/** Factory: sum-of-`field` aggregate. */
+export function sum(field) {
+    return { kind: 'sum', field };
+}
+/** Factory: average-of-`field` aggregate. */
+export function average(field) {
+    return { kind: 'average', field };
+}
+/**
+ * Count documents matching the query. Returns a snapshot whose
+ * `.data()` yields `{ count: N }` — same shape `firebase/firestore`'s
+ * `getCountFromServer` produces.
+ */
+export async function getCountFromServer(source) {
+    const target = targetOf(source);
+    if (isSandboxKind(target)) {
+        const snap = await chainQueryFor(target, source).aggregate({ count: { kind: 'count' } });
+        const data = snap.data();
+        return { data: () => ({ count: (data.count ?? 0) }) };
+    }
+    const snap = await fb.getCountFromServer(asFbQuery(source));
+    return { data: () => ({ count: snap.data().count }) };
+}
+/**
+ * Run a multi-field aggregate against the query. Spec entries are
+ * keyed by caller-chosen aliases; the returned snapshot's `.data()`
+ * uses the same keys.
+ *
+ * Sandbox target dispatches straight into the chainable adapter.
+ * Prod target translates pyric's `AggregateField` shapes into
+ * `firebase/firestore` AggregateField instances (`fb.count()`,
+ * `fb.sum(...)`, `fb.average(...)`) before delegating.
+ */
+export async function getAggregateFromServer(source, spec) {
+    const target = targetOf(source);
+    if (isSandboxKind(target)) {
+        // The sandbox spec shape is structurally identical to ours, but
+        // we re-construct so the type system sees `ChainAggregateSpec`
+        // explicitly (avoids a chained cast at the call site).
+        const chainSpec = {};
+        for (const alias of Object.keys(spec))
+            chainSpec[alias] = spec[alias];
+        const snap = await chainQueryFor(target, source).aggregate(chainSpec);
+        return { data: () => snap.data() };
+    }
+    // Prod — translate spec to firebase/firestore AggregateField objects.
+    const fbSpec = {};
+    for (const alias of Object.keys(spec)) {
+        const f = spec[alias];
+        if (f.kind === 'count')
+            fbSpec[alias] = fb.count();
+        else if (f.kind === 'sum')
+            fbSpec[alias] = fb.sum(f.field);
+        else
+            fbSpec[alias] = fb.average(f.field);
+    }
+    const snap = await fb.getAggregateFromServer(asFbQuery(source), fbSpec);
+    return { data: () => snap.data() };
+}
+export function onSnapshot(ref, arg2, arg3, arg4) {
+    const target = targetOf(ref);
+    if (isSandboxKind(target)) {
+        // Resolve the chainable ref. For frozen sandbox, this is the held
+        // chainable; for sandbox-live, build a fresh chainable bound to the
+        // *current* `sandbox.currentUser` — the listener captures that
+        // identity as its initial auth. For sandbox-live the listener also
+        // FOLLOWS `currentUser`: a later sign-out / sign-in re-evaluates it
+        // under the new auth (an auth-gated listener loses access on
+        // sign-out, regains under a different signed-in user). This matches
+        // production, which re-establishes the listen stream on a session
+        // auth change. Frozen-ctx (`getFirestore(ctx)`) listeners stay
+        // pinned to their chosen identity (admin/testing path).
+        const r = resolveSandboxListenable(target, ref);
+        // Wrap the next callback so any ref the snapshot carries (the
+        // document's `.ref` for a doc snapshot; each doc's `.ref` for a
+        // query snapshot) gets tagged in `refToTarget` before the consumer
+        // ever sees it. Without this, `snap.ref` / `snap.docs[i].ref`
+        // come back from the chainable adapter untagged, and the next
+        // `onSnapshot(ref, …)` / `setDoc(ref, …)` throws
+        // "pyric/firestore: unrecognized reference."
+        const wrappedArgs = tagSandboxSnapshotArgs(arg2, arg3, arg4, target);
+        // Thread the live-vs-frozen marker down to the chainable adapter so
+        // it can set `addSnapshotListener`'s `followsCurrentUser` flag. The
+        // adapter sees only a `SandboxContext` and can't recover the
+        // distinction on its own; we stamp an internal symbol onto the
+        // forwarded options object (prepending one when the call used the
+        // callback-first form). The adapter reads + strips it.
+        const finalArgs = markSandboxLiveSnapshotArgs(wrappedArgs, target);
+        return finalArgs.length === 3
+            ? r.onSnapshot(finalArgs[0], finalArgs[1], finalArgs[2])
+            : finalArgs.length === 2
+                ? r.onSnapshot(finalArgs[0], finalArgs[1])
+                : r.onSnapshot(finalArgs[0]);
+    }
+    // prod — `firebase/firestore`'s onSnapshot takes the same arg shapes.
+    // fb's modular SDK already returns refs that route through `targetOf`'s
+    // `TARGET_SYMBOL` path (we set the symbol on each ref the package
+    // exposes), so no wrapping is needed on the prod side.
+    const fbRef = ref;
+    // The fb overload set is wide — cast through `any` for the arg
+    // forwarding; the types match at runtime.
+    return arg4 !== undefined
+        ? fb.onSnapshot(fbRef, arg2, arg3, arg4)
+        : arg3 !== undefined
+            ? fb.onSnapshot(fbRef, arg2, arg3)
+            : fb.onSnapshot(fbRef, arg2);
+}
+/**
+ * Pick the chainable object whose `.onSnapshot` we attach to. For
+ * `sandbox`, this is just the underlying held chainable (existing
+ * behavior). For `sandbox-live`, this is a fresh chainable rebuilt
+ * against the current `sandbox.currentUser` — the listener captures
+ * that identity as its initial auth. Unlike before, the live listener
+ * then FOLLOWS `currentUser`: a later sign-out / sign-in re-evaluates
+ * it under the new identity (wired via `FOLLOWS_CURRENT_USER` →
+ * `LocalEnvironment.reevaluateLiveListeners`), so an auth-gated
+ * listener loses access on sign-out without the caller having to
+ * unsubscribe — matching production's listener re-establishment.
+ */
+function resolveSandboxListenable(target, ref) {
+    const underlying = underlyingOf(ref);
+    if (target.kind === 'sandbox') {
+        return underlying;
+    }
+    const rebuild = sandboxLiveRebuild.get(underlying);
+    if (!rebuild) {
+        throw new TypeError('pyric/firestore: live ref missing rebuild closure for onSnapshot.');
+    }
+    return rebuild(sandboxDb(target));
+}
+/**
+ * Wrap the `next` callback in an `onSnapshot(…)` call so every ref the
+ * snapshot carries is tagged into `refToTarget` before delivery. Returns
+ * the rewritten arg tuple ready to forward to the underlying chainable
+ * adapter. Only used for the sandbox target — prod refs from
+ * `firebase/firestore` already carry `TARGET_SYMBOL`.
+ */
+/**
+ * FS-B14 — `true` when `obj` is a partial `onSnapshot` observer (an object
+ * carrying at least one of `next` / `error` / `complete` as a function).
+ * Mirrors `isPartialObserver` in `clones/.../api/observer.ts`. Used to keep
+ * an `{ error: fn }` / `{ complete: fn }` observer from being misrouted as a
+ * `SnapshotListenOptions` object.
+ */
+function isPartialObserver(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const o = obj;
+    return (typeof o.next === 'function' ||
+        typeof o.error === 'function' ||
+        typeof o.complete === 'function');
+}
+function tagSandboxSnapshotArgs(arg2, arg3, arg4, target) {
+    // Detect whether arg2 is the SnapshotListenOptions form. FS-B14 — an
+    // observer is any object carrying at least one of `next` / `error` /
+    // `complete` as a function (mirrors `isPartialObserver` in
+    // `clones/.../api/observer.ts`). The old `!('next' in arg2)` test
+    // misrouted an `{ error: fn }` observer as options, dropping it and
+    // surfacing "missing next handler". A SnapshotListenOptions object has
+    // none of those function-valued keys.
+    const isOptions = typeof arg2 === 'object' && arg2 !== null && !isPartialObserver(arg2);
+    if (isOptions) {
+        // (options, next | observer, error?)
+        const next = arg3;
+        if (typeof next === 'function') {
+            return [arg2, wrapNext(next, target), arg4 ?? defaultSnapshotErrorHandler];
+        }
+        if (next && typeof next === 'object') {
+            return [arg2, wrapObserver(next, target)];
+        }
+        return [arg2];
+    }
+    // (next | observer, error?)
+    if (typeof arg2 === 'function') {
+        return [
+            wrapNext(arg2, target),
+            arg3 ?? defaultSnapshotErrorHandler,
+        ];
+    }
+    if (arg2 && typeof arg2 === 'object') {
+        return [wrapObserver(arg2, target)];
+    }
+    return [arg2];
+}
+/**
+ * Stamp the internal `FOLLOWS_CURRENT_USER` marker onto the options
+ * object of a forwarded `onSnapshot` arg tuple, so the chainable adapter
+ * can set `addSnapshotListener`'s `followsCurrentUser` flag. Only applies
+ * to `sandbox-live` targets — frozen-ctx (`sandbox`) and prod listeners
+ * keep their pinned identity and are returned unchanged.
+ *
+ * `args` is the post-`tagSandboxSnapshotArgs` tuple, which is one of:
+ *   - `[options, next|observer, error?]` — options-first form
+ *   - `[next|observer, error?]`          — callback-first form
+ *   - `[observer]`                       — observer-only form
+ *
+ * For the options-first form we clone the options and add the symbol.
+ * For the other forms we PREPEND a fresh options object carrying only
+ * the symbol — safe because the chainable adapter's normalizer
+ * discriminates `(options, …)` from `(callback, …)` by inspecting the
+ * first arg, and a marker-only object has no `next`/`error`/`complete`
+ * handler so it reads as options.
+ */
+function markSandboxLiveSnapshotArgs(args, target) {
+    if (target.kind !== 'sandbox-live')
+        return args;
+    const first = args[0];
+    const firstIsOptions = typeof first === 'object' && first !== null && !isPartialObserver(first);
+    if (firstIsOptions) {
+        const opts = { ...first, [FOLLOWS_CURRENT_USER]: true };
+        return [opts, ...args.slice(1)];
+    }
+    return [{ [FOLLOWS_CURRENT_USER]: true }, ...args];
+}
+function finalizeSandboxSnapshot(snap, target) {
+    if (!isSandboxKind(target) || !snap || typeof snap !== 'object')
+        return snap;
+    const s = snap;
+    if (typeof s.data === 'function') {
+        wrapSandboxDocSnap(snap);
+    }
+    if (Array.isArray(s.docs)) {
+        for (const d of s.docs)
+            wrapSandboxDocSnap(d);
+    }
+    return snap;
+}
+/**
+ * Default error handler for a sandbox `onSnapshot` listener whose caller
+ * supplied none. Mirrors the Firebase Web SDK, which logs an uncaught listener
+ * error to the console rather than swallowing it — WITHOUT this, a denied
+ * listener (a rules change, or a sign-out that revokes read access) fails
+ * INVISIBLY: the last snapshot stays on screen and the app gets no signal that
+ * its read was rejected. (Prod listeners go through the real SDK, which applies
+ * its own default; this only fires on the sandbox path.)
+ */
+function defaultSnapshotErrorHandler(error) {
+    // eslint-disable-next-line no-console
+    console.error('pyric/firestore: Uncaught Error in snapshot listener:', error);
+}
+function wrapNext(next, target) {
+    return (snap) => next(finalizeSandboxSnapshot(tagSnapshotRefs(snap, target), target));
+}
+function wrapObserver(obs, target) {
+    return {
+        ...obs,
+        next: obs.next
+            ? (snap) => obs.next(finalizeSandboxSnapshot(tagSnapshotRefs(snap, target), target))
+            : undefined,
+        // Surface an unobserved listener error instead of swallowing it.
+        error: obs.error ?? defaultSnapshotErrorHandler,
+    };
+}
+/**
+ * Walk a snapshot and tag every ref-shaped field in `refToTarget`,
+ * AND normalize `.exists` to method form so consumer code targeting
+ * Firebase's modular SDK (`if (snap.exists())`) works uniformly.
+ *
+ * The chainable adapter exposes `exists` as a property (Admin SDK
+ * shape — `if (snap.exists)`). Firebase's modular SDK exposes it as
+ * a method (`if (snap.exists())`). Without this normalization, user
+ * code written against the documented Firebase API crashes against
+ * the sandbox with "snap.exists is not a function" — a parity bug
+ * agents and developers all rediscover by hand.
+ *
+ * Both forms remain readable on the returned object — the function
+ * branch in any "did the existing FirestoreTab handle both shapes"
+ * code still works.
+ *
+ * Idempotent — tagging an already-tagged object is a no-op, and the
+ * `exists` getter we install is a no-op when one already exists.
+ */
+function tagSnapshotRefs(snap, target) {
+    if (!snap || typeof snap !== 'object')
+        return snap;
+    const s = snap;
+    if (s.ref) {
+        tag(s.ref, target);
+        wireSnapshotRefToUnderlying(s.ref, target);
+    }
+    normalizeExists(s);
+    if (Array.isArray(s.docs)) {
+        for (const doc of s.docs) {
+            if (doc?.ref) {
+                tag(doc.ref, target);
+                wireSnapshotRefToUnderlying(doc.ref, target);
+            }
+            if (doc)
+                normalizeExists(doc);
+        }
+    }
+    return snap;
+}
+/**
+ * Snapshot `.ref` objects from the sandbox carry only `{ id, path }`
+ * — no `.onSnapshot`, `.get`, `.set`, etc. — so a follow-up
+ * `onSnapshot(snap.ref)` would crash with "ref.onSnapshot is not a
+ * function." Bind the snapshot ref to a full chainable doc ref via
+ * `refToUnderlying`; `underlyingOf(snap.ref)` then returns the real
+ * ref the chainable adapter exposes its op methods on. No-op for
+ * prod (their refs are already operative) and for refs that already
+ * have a registered underlying.
+ */
+function wireSnapshotRefToUnderlying(snapRef, target) {
+    if (!isSandboxKind(target))
+        return;
+    if (typeof snapRef.path !== 'string' || snapRef.path.length === 0)
+        return;
+    if (refToUnderlying.has(snapRef))
+        return;
+    const path = snapRef.path;
+    try {
+        // Build a concrete chainable doc to back the snap-ref via
+        // `refToUnderlying`. For sandbox-live, also record a rebuild
+        // closure so subsequent ops on the snap ref re-resolve against
+        // the *current* `sandbox.currentUser` (rather than re-using the
+        // listener-time auth that was frozen into the chainable).
+        const full = sandboxDb(target).doc(path);
+        refToUnderlying.set(snapRef, full);
+        if (target.kind === 'sandbox-live') {
+            sandboxLiveRebuild.set(full, (fresh) => fresh.doc(path));
+        }
+    }
+    catch {
+        // path → doc resolution can throw if the path is malformed
+        // (odd segment count, etc.). Best-effort — leave the snap ref
+        // pointing at itself; the next op call will surface a clear
+        // "ref.onSnapshot is not a function" instead of mangling state.
+    }
+}
+/**
+ * If `obj.exists` is a boolean property, replace it with a function
+ * that returns that value — so consumer code can do `snap.exists()`
+ * uniformly across the sandbox + Firebase backends. Idempotent: if
+ * `exists` is already a function, leave it alone.
+ *
+ * `configurable: true` so a later normalize (over a re-yielded
+ * snapshot from the same listener) can re-install cleanly.
+ */
+function normalizeExists(obj) {
+    const current = obj.exists;
+    if (typeof current === 'function')
+        return;
+    const value = current === true;
+    try {
+        Object.defineProperty(obj, 'exists', {
+            value: () => value,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+    }
+    catch {
+        // Some snapshot impls might freeze the object. Best-effort —
+        // a frozen snap already provides the property reading the user
+        // can do `if (snap.exists)` against; the call-site failure is
+        // surfaced via the error boundary.
+    }
+}
+// ─── Transactions + batches ───────────────────────────────────────────
+export async function runTransaction(db, fn) {
+    const target = targetOf(db);
+    if (isSandboxKind(target)) {
+        // For sandbox-live, the transaction (and every op inside the
+        // callback) runs under the auth captured at `runTransaction`
+        // start. Mutating `sandbox.currentUser` mid-transaction does
+        // not retro-actively re-auth in-flight reads (matches
+        // production: a transaction is identity-stable by design).
+        return sandboxDb(target).runTransaction(fn);
+    }
+    return fb.runTransaction(target.db, fn);
+}
+export function writeBatch(db) {
+    const target = targetOf(db);
+    if (isSandboxKind(target)) {
+        // Each batch is constructed under a fresh chainable bound to
+        // the current user. The batch holds that identity for every
+        // op queued through it (matches transactions — once a batch is
+        // opened, identity is frozen until `.commit()`).
+        const batch = sandboxDb(target).batch();
+        return tag(batch, target);
+    }
+    const batch = fb.writeBatch(target.db);
+    return tag(batch, target);
+}
+// ─── Sandbox-only operations ──────────────────────────────────────────
+//
+// Grouped as a named-object export per the v4 plan. These have no
+// `firebase/firestore` analog — keeping them under a `sandbox`
+// namespace at the import site documents the sandbox-only
+// constraint better than the runtime throw could. Calling them on
+// a prod-target Firestore still throws `SandboxError` defensively.
+/**
+ * Sandbox lifecycle operations. Only meaningful against a
+ * sandbox-target `Firestore` (built via `getFirestore(ctx)` with a
+ * `SandboxContext`). Each function throws `SandboxError` when
+ * handed a prod-target handle.
+ *
+ * **Naming note**: the `sandbox` export name conflicts with the
+ * common local variable from `initializeSandbox()` (which also
+ * returns a `Sandbox` typically held as `const sandbox = …`).
+ * When both are in scope, alias the import:
+ *
+ * ```ts
+ * import { sandbox as sandboxOps } from 'pyric/firestore';
+ * import { initializeSandbox } from 'pyric/sandbox';
+ *
+ * const sandbox = initializeSandbox();      // local var
+ * const db = getFirestore(sandbox.withAuth(…));
+ * sandboxOps.setRules(db, RULES);            // SDK ops
+ * ```
+ *
+ * The `sandbox` name was kept because it accurately describes the
+ * surface (sandbox-only lifecycle). The renaming alternatives —
+ * `sbx`, `firestoreSandbox`, `localOps` — all read worse than the
+ * import-time alias.
+ */
+export const sandbox = {
+    /** Load a rules source into the underlying `LocalEnvironment`. */
+    setRules(db, rules) {
+        const target = targetOf(db);
+        if (!isSandboxKind(target)) {
+            throw new SandboxError('failed-precondition', 'sandbox.setRules is sandbox-only; use firestore.rules.deploy from pyric-tools/deploy for prod targets.');
+        }
+        return sandboxDb(target).setRules(rules);
+    },
+    /** Bulk-load documents bypassing rules. */
+    seedDocuments(db, documents) {
+        const target = targetOf(db);
+        if (!isSandboxKind(target)) {
+            throw new SandboxError('failed-precondition', 'sandbox.seedDocuments is sandbox-only; populate prod data via writes.');
+        }
+        return sandboxDb(target).seed({ documents });
+    },
+    /** Dump every document the underlying `LocalEnvironment` has stored. */
+    snapshotState(db) {
+        const target = targetOf(db);
+        if (!isSandboxKind(target)) {
+            throw new SandboxError('failed-precondition', 'sandbox.snapshotState is sandbox-only.');
+        }
+        return sandboxDb(target).snapshot();
+    },
+    /**
+     * Single-call diagnostic an agent uses to answer "what state is the
+     * sandbox in?" without grepping internal modules. Born out of
+     * CLAUDE_DEBUG_SESSION.md: a real agent took 51 tool calls + 72k
+     * tokens to figure out that the scaffold's rules weren't loaded.
+     *
+     * Returns: current rules source, lint summary, doc count by
+     * collection, recent denials, recent requests. Stable JSON shape —
+     * marshalled over MCP by `sandbox_inspect`.
+     */
+    inspect(db, opts) {
+        const target = targetOf(db);
+        if (!isSandboxKind(target)) {
+            throw new SandboxError('failed-precondition', 'sandbox.inspect is sandbox-only.');
+        }
+        return inspectSandbox(target.sandbox, opts?.recentEventLimit ?? 10);
+    },
+};
+function inspectSandbox(sandbox, recentLimit) {
+    const env = getInternalEnv(sandbox);
+    const rulesSource = env.getRules();
+    const lint = rulesSource ? lintFirestoreRules(rulesSource) : { warnings: [] };
+    const findings = lint.warnings.map((w) => ({
+        rule: w.rule,
+        severity: w.severity,
+        message: w.message,
+    }));
+    const counts = { errors: 0, warnings: 0, info: 0 };
+    for (const w of lint.warnings) {
+        if (w.severity === 'error')
+            counts.errors++;
+        else if (w.severity === 'warning')
+            counts.warnings++;
+        else
+            counts.info++;
+    }
+    const docs = env.snapshot();
+    const byCollection = {};
+    for (const path of Object.keys(docs)) {
+        const top = path.split('/')[0] ?? '';
+        if (!top)
+            continue;
+        byCollection[top] = (byCollection[top] ?? 0) + 1;
+    }
+    const history = sandbox.history();
+    const requests = history.filter((e) => e.kind === 'request');
+    const denials = requests.filter((e) => e.result === 'deny');
+    const recentRequests = requests.slice(-recentLimit).map((e) => ({
+        path: String(e.path ?? ''),
+        method: String(e.method ?? ''),
+        result: String(e.result ?? ''),
+        auth: e.auth ?? null,
+    }));
+    const recentDenials = denials.slice(-recentLimit).map((e) => ({
+        path: String(e.path ?? ''),
+        method: String(e.method ?? ''),
+        auth: e.auth ?? null,
+        debugMessage: typeof e.debugMessage === 'string' ? e.debugMessage : undefined,
+    }));
+    return {
+        rules: {
+            source: rulesSource,
+            sizeBytes: new TextEncoder().encode(rulesSource).byteLength,
+            isEmpty: rulesSource.trim().length === 0,
+            lint: { ...counts, findings },
+        },
+        documents: {
+            totalCount: Object.keys(docs).length,
+            byCollection,
+        },
+        events: {
+            totalCount: history.length,
+            recentDenials,
+            recentRequests,
+        },
+    };
+}
+// ─── Sentinels + scalar types ─────────────────────────────────────────
+//
+// Sentinels in pyric ride on `pyric-admin`'s sentinel objects, which
+// are structurally identical to `firebase/firestore`'s — the simulator
+// recognizes them by `__type` discriminator, and so does production
+// Firestore (their wire format normalizes through the same path). One
+// `FieldValue.increment(1)` works in both targets.
+//
+// `Timestamp` is similar — admin-shape `{seconds, nanoseconds}` matches
+// the modular SDK's `Timestamp` shape.
+export { ChainFieldValue as FieldValue, ChainTimestamp as Timestamp };
+export function serverTimestamp() {
+    return ChainFieldValue.serverTimestamp();
+}
+export function increment(n) {
+    return ChainFieldValue.increment(n);
+}
+export function arrayUnion(...values) {
+    return ChainFieldValue.arrayUnion(...values);
+}
+export function arrayRemove(...values) {
+    return ChainFieldValue.arrayRemove(...values);
+}
+export function deleteField() {
+    return ChainFieldValue.delete();
+}
+// ─── Tool factories (Slice 10) ────────────────────────────────────────
+export { createFirestoreDataTools, createFirestoreInspectTools } from './tools.js';
+//# sourceMappingURL=index.js.map