pyric 0.0.1 → 0.1.0-alpha.10

package/dist/sandbox/admin-firestore/get-admin-firestore.js

@@ -0,0 +1,62 @@
+/**
+ * `getAdminFirestore(target)` — the rules-bypassing `SandboxFirestore`
+ * resolver (the Pyric Studio admin lens, Gap #2).
+ */
+import { isRemoteSandbox } from 'pyric/sandbox';
+import { bindOperationContext } from 'pyric/sandbox/internal';
+import { wrapWithErrorTranslation } from './error-translation.js';
+import { buildFirestoreHandle } from './local-handle.js';
+import { createRemoteFirestore } from './remote/remote-firestore.js';
+/**
+ * Idempotency cache for admin (rules-bypassing) handles. Keyed by ctx,
+ * SEPARATE from `getFirestore`'s handle cache so the same
+ * `SandboxContext` can vend both a rules-enforced handle (`getFirestore`)
+ * and a rules-bypassing one (`getAdminFirestore`) without one clobbering
+ * the other.
+ */
+const adminHandleCache = new WeakMap();
+export function getAdminFirestore(target) {
+    // Admin reads/writes are identity-agnostic (rules are off), so a bare
+    // `Sandbox` is accepted as well as a `SandboxContext`. A bare sandbox is
+    // normalised to an anonymous ctx — the captured auth is irrelevant since
+    // no rule reads `request.auth` on the bypass path.
+    const baseContext = isSandboxContext(target)
+        ? target
+        : target.withAuth(null);
+    const cached = adminHandleCache.get(baseContext);
+    if (cached)
+        return cached;
+    const ctx = baseContext.operationContext.authLens.mode === 'admin'
+        ? baseContext
+        : bindOperationContext(baseContext, {
+            source: baseContext.operationContext.source,
+            authLens: { mode: 'admin' },
+            ...(baseContext.operationContext.planId === undefined
+                ? {}
+                : { planId: baseContext.operationContext.planId }),
+        });
+    // REMOTE ARM: rules bypass rides the worker's `{ mode: 'admin' }` lens
+    // (the same lens Studio's admin surface uses) — identity-agnostic, so
+    // the normalised ctx's auth is irrelevant, exactly like the local path.
+    const fresh = isRemoteSandbox(ctx.sandbox)
+        ? createRemoteFirestore(ctx.sandbox, { mode: 'admin' })
+        : wrapWithErrorTranslation(buildFirestoreHandle(ctx, true), ctx, true);
+    // Cache against the caller-owned context. `bindOperationContext` creates a
+    // derived context to pin the admin lens, and keying by that fresh object
+    // would silently defeat the public per-context idempotency contract.
+    adminHandleCache.set(baseContext, fresh);
+    return fresh;
+}
+/**
+ * Brand test for the `SandboxContext` overload of {@link getAdminFirestore}.
+ * A `SandboxContext` carries `withAuth` + a `sandbox` back-reference; a bare
+ * `Sandbox` carries `withAuth` too but also `admin`/`currentUser`. We test
+ * for the `sandbox` property which only the context has.
+ */
+function isSandboxContext(target) {
+    return (target !== null &&
+        typeof target === 'object' &&
+        'sandbox' in target &&
+        typeof target.withAuth === 'function');
+}
+//# sourceMappingURL=get-admin-firestore.js.map

package/dist/sandbox/admin-firestore/get-admin-firestore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-admin-firestore.js","sourceRoot":"","sources":["../../../src/sandbox/admin-firestore/get-admin-firestore.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAqC,MAAM,eAAe,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAAoC,CAAC;AAuCzE,MAAM,UAAU,iBAAiB,CAAC,MAAgC;IAChE,sEAAsE;IACtE,yEAAyE;IACzE,yEAAyE;IACzE,mDAAmD;IACnD,MAAM,WAAW,GAAmB,gBAAgB,CAAC,MAAM,CAAC;QAC1D,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACjD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,GAAG,GAAmB,WAAW,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,KAAK,OAAO;QAChF,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,oBAAoB,CAAC,WAAW,EAAE;YAChC,MAAM,EAAE,WAAW,CAAC,gBAAgB,CAAC,MAAM;YAC3C,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;YAC3B,GAAG,CAAC,WAAW,CAAC,gBAAgB,CAAC,MAAM,KAAK,SAAS;gBACnD,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC;SACrD,CAAC,CAAC;IACP,uEAAuE;IACvE,sEAAsE;IACtE,wEAAwE;IACxE,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC;QACxC,CAAC,CAAC,qBAAqB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACvD,CAAC,CAAC,wBAAwB,CAAC,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACzE,2EAA2E;IAC3E,yEAAyE;IACzE,qEAAqE;IACrE,gBAAgB,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,MAAgC;IACxD,OAAO,CACL,MAAM,KAAK,IAAI;QACf,OAAO,MAAM,KAAK,QAAQ;QAC1B,SAAS,IAAI,MAAM;QACnB,OAAQ,MAAiC,CAAC,QAAQ,KAAK,UAAU,CAClE,CAAC;AACJ,CAAC"}

package/dist/sandbox/admin-firestore/get-firestore.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `getFirestore(ctx)` — the rules-enforced `SandboxFirestore` resolver.
+ * Dispatches to the local engine handle or the channel-backed remote arm
+ * depending on the context's sandbox brand.
+ */
+import { type AuthLens, type AuthState, type SandboxContext } from 'pyric/sandbox';
+import type { SandboxFirestore } from './types.js';
+/**
+ * Resolve the Firestore service handle for a context. Idempotent —
+ * subsequent calls with the same context return the same wrapper.
+ *
+ * Requires a `SandboxContext`, never a bare `Sandbox`. Anonymous is
+ * `sandbox.withAuth(null)`, written explicitly — every call site
+ * states identity.
+ *
+ * @example
+ * ```ts
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { getFirestore } from 'pyric-admin/firestore';
+ *
+ * const sandbox = initializeSandbox();
+ * const db = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+ * db.setRules(MY_RULES);
+ * db.seed({ documents: { 'tickets/T-1': { ... } } });
+ *
+ * // Different identity? Different context, same data.
+ * const dbAsBob = getFirestore(sandbox.withAuth({ uid: 'bob' }));
+ * ```
+ */
+export declare function getFirestore(ctx: SandboxContext): SandboxFirestore;
+/** Map a context's frozen `AuthState` to the worker-relay lens the remote
+ *  arm pins on every op/sub. Never absent — see {@link getFirestore}. */
+export declare function lensForAuth(auth: AuthState): AuthLens;
+//# sourceMappingURL=get-firestore.d.ts.map

package/dist/sandbox/admin-firestore/get-firestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-firestore.d.ts","sourceRoot":"","sources":["../../../src/sandbox/admin-firestore/get-firestore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAmB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AASnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,gBAAgB,CAsBlE;AAED;yEACyE;AACzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAKrD"}

package/dist/sandbox/admin-firestore/get-firestore.js

@@ -0,0 +1,71 @@
+/**
+ * `getFirestore(ctx)` — the rules-enforced `SandboxFirestore` resolver.
+ * Dispatches to the local engine handle or the channel-backed remote arm
+ * depending on the context's sandbox brand.
+ */
+import { isRemoteSandbox } from 'pyric/sandbox';
+import { wrapWithErrorTranslation } from './error-translation.js';
+import { buildFirestoreHandle } from './local-handle.js';
+import { createRemoteFirestore } from './remote/remote-firestore.js';
+/**
+ * Idempotency cache. Each `SandboxContext` gets its own handle because
+ * each context carries its own auth identity. Cached by reference,
+ * garbage-collected with the context.
+ */
+const handleCache = new WeakMap();
+/**
+ * Resolve the Firestore service handle for a context. Idempotent —
+ * subsequent calls with the same context return the same wrapper.
+ *
+ * Requires a `SandboxContext`, never a bare `Sandbox`. Anonymous is
+ * `sandbox.withAuth(null)`, written explicitly — every call site
+ * states identity.
+ *
+ * @example
+ * ```ts
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { getFirestore } from 'pyric-admin/firestore';
+ *
+ * const sandbox = initializeSandbox();
+ * const db = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+ * db.setRules(MY_RULES);
+ * db.seed({ documents: { 'tickets/T-1': { ... } } });
+ *
+ * // Different identity? Different context, same data.
+ * const dbAsBob = getFirestore(sandbox.withAuth({ uid: 'bob' }));
+ * ```
+ */
+export function getFirestore(ctx) {
+    const cached = handleCache.get(ctx);
+    if (cached)
+        return cached;
+    // REMOTE ARM (remote sandbox, slice 2): a remote-branded sandbox has no
+    // in-process engine — return the channel-backed parallel implementation
+    // instead of building the local compat handle. Identity mapping: the
+    // context's frozen auth pins the per-op lens — `withAuth(null)` means
+    // `{ mode: 'anon' }` (an ABSENT lens would silently resolve to the
+    // browser tab's port session), and a signed identity pins
+    // `{ mode: 'as', uid, token? }` with the FULL claims token (the worker
+    // resolves it via `sandbox.withAuth({ uid, token })`, so custom claims
+    // evaluate in rules exactly as on the local arm).
+    const fresh = isRemoteSandbox(ctx.sandbox)
+        ? createRemoteFirestore(ctx.sandbox, lensForAuth(ctx.auth))
+        : // Wrap the raw handle so every operation (and every object returned
+            // from it: `DocumentReference`, `Query`, `WriteBatch`, `Transaction`)
+            // re-throws compat errors as `SandboxError` with structured
+            // `denialContext`. The wrapper also stashes `ctx` on every wrapped
+            // value via CONTEXT_SYMBOL so `onSnapshot` can recover it.
+            wrapWithErrorTranslation(buildFirestoreHandle(ctx), ctx);
+    handleCache.set(ctx, fresh);
+    return fresh;
+}
+/** Map a context's frozen `AuthState` to the worker-relay lens the remote
+ *  arm pins on every op/sub. Never absent — see {@link getFirestore}. */
+export function lensForAuth(auth) {
+    if (auth === null || auth === undefined)
+        return { mode: 'anon' };
+    return auth.token === undefined
+        ? { mode: 'as', uid: auth.uid }
+        : { mode: 'as', uid: auth.uid, token: auth.token };
+}
+//# sourceMappingURL=get-firestore.js.map

package/dist/sandbox/admin-firestore/get-firestore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-firestore.js","sourceRoot":"","sources":["../../../src/sandbox/admin-firestore/get-firestore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAsD,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE;;;;GAIG;AACH,MAAM,WAAW,GAAG,IAAI,OAAO,EAAoC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,GAAmB;IAC9C,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,wEAAwE;IACxE,wEAAwE;IACxE,qEAAqE;IACrE,sEAAsE;IACtE,mEAAmE;IACnE,0DAA0D;IAC1D,uEAAuE;IACvE,uEAAuE;IACvE,kDAAkD;IAClD,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC;QACxC,CAAC,CAAC,qBAAqB,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3D,CAAC,CAAC,oEAAoE;YACpE,sEAAsE;YACtE,4DAA4D;YAC5D,mEAAmE;YACnE,2DAA2D;YAC3D,wBAAwB,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7D,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;yEACyE;AACzE,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACjE,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS;QAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;QAC/B,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;AACvD,CAAC"}

package/dist/sandbox/admin-firestore/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `pyric-admin` — Admin-SDK-shaped chainable Firestore adapter for
+ * the Pyric sandbox.
+ *
+ * `getFirestore(ctx)` returns a `SandboxFirestore` whose operations
+ * run under the context's auth identity and against the underlying
+ * `LocalEnvironment` of the context's sandbox. Idempotent — a second
+ * call with the same `SandboxContext` returns the same wrapper.
+ *
+ * Wraps the `pyric/sandbox/admin-compat` implementation.
+ * Per-operation methods construct a fresh delegate so a
+ * `sandbox.reset()` (which swaps the underlying environment) is
+ * picked up on the next operation. Refs returned from the wrapper
+ * (`DocumentReference`, `Query`) are bound to whichever environment
+ * was live when they were obtained — re-acquire them after reset to
+ * avoid stale-state confusion.
+ *
+ * This file is the package export barrel only — re-exports from the
+ * concept files in this directory (`get-firestore.ts`,
+ * `get-admin-firestore.ts`, `listeners.ts`, `types.ts`,
+ * `local-handle.ts`, `error-translation.ts`, `remote/`). No
+ * implementation lives here.
+ */
+export type { AuthState, Sandbox, SandboxContext, } from 'pyric/sandbox';
+export { SandboxError } from 'pyric/sandbox';
+export type { AggregateField, AggregateQuerySnapshot, AggregateSpec, Filter, CollectionReference, DocumentData, DocumentReference, DocumentSnapshot as AdminDocumentSnapshot, FieldValueSentinel, Firestore, OrderDirection, Query, QueryDocumentSnapshot as AdminQueryDocumentSnapshot, QuerySnapshot as AdminQuerySnapshot, SetOptions, Transaction, WhereFilterOp, WriteBatch, } from 'pyric/sandbox/admin-compat';
+export type { LintResult, LintWarning, RulesMetrics } from 'pyric/rules/internal';
+export { FieldValue, Timestamp } from 'pyric/sandbox/admin-compat';
+export type { LiveDocumentSnapshot as DocumentSnapshot, LiveQueryDocumentSnapshot as QueryDocumentSnapshot, LiveQuerySnapshot as QuerySnapshot, DocumentChange, DocumentChangeType, DocChangesOptions, SnapshotMetadata, } from 'pyric/sandbox/admin-compat';
+export type { SandboxFirestore } from './types.js';
+export type { SnapshotObserver, Unsubscribe } from './types.js';
+export { getFirestore } from './get-firestore.js';
+export { getAdminFirestore } from './get-admin-firestore.js';
+export { onSnapshot } from './listeners.js';
+export type { SnapshotListenOptions } from './listeners.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/admin-firestore/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sandbox/admin-firestore/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,YAAY,EACV,SAAS,EACT,OAAO,EACP,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAY7C,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,aAAa,EACb,MAAM,EACN,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,IAAI,qBAAqB,EACzC,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,KAAK,EACL,qBAAqB,IAAI,0BAA0B,EACnD,aAAa,IAAI,kBAAkB,EACnC,UAAU,EACV,WAAW,EACX,aAAa,EACb,UAAU,GACX,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAQnE,YAAY,EACV,oBAAoB,IAAI,gBAAgB,EACxC,yBAAyB,IAAI,qBAAqB,EAClD,iBAAiB,IAAI,aAAa,EAClC,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AAGpC,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGhE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAK7D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/sandbox/admin-firestore/index.js

@@ -0,0 +1,33 @@
+/**
+ * `pyric-admin` — Admin-SDK-shaped chainable Firestore adapter for
+ * the Pyric sandbox.
+ *
+ * `getFirestore(ctx)` returns a `SandboxFirestore` whose operations
+ * run under the context's auth identity and against the underlying
+ * `LocalEnvironment` of the context's sandbox. Idempotent — a second
+ * call with the same `SandboxContext` returns the same wrapper.
+ *
+ * Wraps the `pyric/sandbox/admin-compat` implementation.
+ * Per-operation methods construct a fresh delegate so a
+ * `sandbox.reset()` (which swaps the underlying environment) is
+ * picked up on the next operation. Refs returned from the wrapper
+ * (`DocumentReference`, `Query`) are bound to whichever environment
+ * was live when they were obtained — re-acquire them after reset to
+ * avoid stale-state confusion.
+ *
+ * This file is the package export barrel only — re-exports from the
+ * concept files in this directory (`get-firestore.ts`,
+ * `get-admin-firestore.ts`, `listeners.ts`, `types.ts`,
+ * `local-handle.ts`, `error-translation.ts`, `remote/`). No
+ * implementation lives here.
+ */
+export { SandboxError } from 'pyric/sandbox';
+export { FieldValue, Timestamp } from 'pyric/sandbox/admin-compat';
+// Service resolvers.
+export { getFirestore } from './get-firestore.js';
+export { getAdminFirestore } from './get-admin-firestore.js';
+// `onSnapshot` — the free modular-shaped function, its options type, and
+// the live-vs-frozen marker the modular `pyric/firestore` layer stamps
+// onto listener options (see `listeners.ts`).
+export { onSnapshot } from './listeners.js';
+//# sourceMappingURL=index.js.map

package/dist/sandbox/admin-firestore/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sandbox/admin-firestore/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAUH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAiC7C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAsBnE,qBAAqB;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,yEAAyE;AACzE,uEAAuE;AACvE,8CAA8C;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/sandbox/admin-firestore/listeners.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `onSnapshot` — Web-SDK-shaped streaming reads over the chainable Admin
+ * surface. The four overloads mirror `firebase/firestore`'s `onSnapshot`
+ * so existing call sites copied from production code typecheck
+ * unchanged.
+ *
+ * Routing:
+ *   - `DocumentReference` → `LocalEnvironment.addSnapshotListener`
+ *      with `target = { kind: 'doc', path }`.
+ *   - `CollectionReference` (and any `Query` whose collection root is
+ *      reachable via `.path` or `.parent.path`) → `target = { kind: 'query', collection }`.
+ *   - Chained queries (`.where`/`.orderBy`/`.limit`) currently route as
+ *      whole-collection listeners; the simulator fires for any change in
+ *      the collection, and the callback receives every document. Slice 6
+ *      will add filter/order honoring at the listener layer.
+ *
+ * The registering context's `auth` is captured at register time and
+ * threaded through to `addSnapshotListener` so notifications evaluate
+ * rules under the auth that subscribed — not whatever auth happens to
+ * be active when a write triggers dispatch
+ * (`addSnapshotListener`'s auth-capture invariant).
+ *
+ * REMOTE ARM: refs minted by the channel-backed handle carry their own
+ * listener registrar (`getRemoteSnapshotRegistrar`) — dispatched before
+ * any local-engine resolution, since `getInternalEnv` rejects remote
+ * handles.
+ */
+import type { CollectionReference, DocumentReference, Query, SnapshotListenerOptions } from 'pyric/sandbox/admin-compat';
+import type { SnapshotObserver, Unsubscribe } from './types.js';
+/**
+ * Mirrors `firebase/firestore`'s `SnapshotListenOptions`. The
+ * `includeMetadataChanges` flag is accepted for API parity but has no
+ * observable effect in the sandbox: there's no offline cache and no
+ * pending-writes window, so `metadata.fromCache` and
+ * `metadata.hasPendingWrites` are always `false` (snapshot-listeners.ts section 6).
+ */
+export type SnapshotListenOptions = SnapshotListenerOptions;
+export declare function onSnapshot(reference: DocumentReference, observer: SnapshotObserver<import('pyric/sandbox/admin-compat').LiveDocumentSnapshot>): Unsubscribe;
+export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, observer: SnapshotObserver<import('pyric/sandbox/admin-compat').LiveDocumentSnapshot>): Unsubscribe;
+export declare function onSnapshot(reference: DocumentReference, onNext: (snapshot: import('pyric/sandbox/admin-compat').LiveDocumentSnapshot) => void, onError?: (error: unknown) => void, onCompletion?: () => void): Unsubscribe;
+export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, onNext: (snapshot: import('pyric/sandbox/admin-compat').LiveDocumentSnapshot) => void, onError?: (error: unknown) => void, onCompletion?: () => void): Unsubscribe;
+export declare function onSnapshot(reference: Query | CollectionReference, observer: SnapshotObserver<import('pyric/sandbox/admin-compat').LiveQuerySnapshot>): Unsubscribe;
+export declare function onSnapshot(reference: Query | CollectionReference, options: SnapshotListenOptions, observer: SnapshotObserver<import('pyric/sandbox/admin-compat').LiveQuerySnapshot>): Unsubscribe;
+export declare function onSnapshot(reference: Query | CollectionReference, onNext: (snapshot: import('pyric/sandbox/admin-compat').LiveQuerySnapshot) => void, onError?: (error: unknown) => void, onCompletion?: () => void): Unsubscribe;
+export declare function onSnapshot(reference: Query | CollectionReference, options: SnapshotListenOptions, onNext: (snapshot: import('pyric/sandbox/admin-compat').LiveQuerySnapshot) => void, onError?: (error: unknown) => void, onCompletion?: () => void): Unsubscribe;
+//# sourceMappingURL=listeners.d.ts.map

package/dist/sandbox/admin-firestore/listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../../src/sandbox/admin-firestore/listeners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,EACL,uBAAuB,EACxB,MAAM,4BAA4B,CAAC;AAQpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAMhE;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAiF5D,wBAAgB,UAAU,CACxB,SAAS,EAAE,iBAAiB,EAC5B,QAAQ,EAAE,gBAAgB,CAAC,OAAO,4BAA4B,EAAE,oBAAoB,CAAC,GACpF,WAAW,CAAC;AACf,wBAAgB,UAAU,CACxB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,gBAAgB,CAAC,OAAO,4BAA4B,EAAE,oBAAoB,CAAC,GACpF,WAAW,CAAC;AACf,wBAAgB,UAAU,CACxB,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,4BAA4B,EAAE,oBAAoB,KAAK,IAAI,EACrF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAClC,YAAY,CAAC,EAAE,MAAM,IAAI,GACxB,WAAW,CAAC;AACf,wBAAgB,UAAU,CACxB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,4BAA4B,EAAE,oBAAoB,KAAK,IAAI,EACrF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAClC,YAAY,CAAC,EAAE,MAAM,IAAI,GACxB,WAAW,CAAC;AACf,wBAAgB,UAAU,CACxB,SAAS,EAAE,KAAK,GAAG,mBAAmB,EACtC,QAAQ,EAAE,gBAAgB,CAAC,OAAO,4BAA4B,EAAE,iBAAiB,CAAC,GACjF,WAAW,CAAC;AACf,wBAAgB,UAAU,CACxB,SAAS,EAAE,KAAK,GAAG,mBAAmB,EACtC,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,gBAAgB,CAAC,OAAO,4BAA4B,EAAE,iBAAiB,CAAC,GACjF,WAAW,CAAC;AACf,wBAAgB,UAAU,CACxB,SAAS,EAAE,KAAK,GAAG,mBAAmB,EACtC,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,KAAK,IAAI,EAClF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAClC,YAAY,CAAC,EAAE,MAAM,IAAI,GACxB,WAAW,CAAC;AACf,wBAAgB,UAAU,CACxB,SAAS,EAAE,KAAK,GAAG,mBAAmB,EACtC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,KAAK,IAAI,EAClF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAClC,YAAY,CAAC,EAAE,MAAM,IAAI,GACxB,WAAW,CAAC"}

package/dist/sandbox/admin-firestore/listeners.js

@@ -0,0 +1,290 @@
+/**
+ * `onSnapshot` — Web-SDK-shaped streaming reads over the chainable Admin
+ * surface. The four overloads mirror `firebase/firestore`'s `onSnapshot`
+ * so existing call sites copied from production code typecheck
+ * unchanged.
+ *
+ * Routing:
+ *   - `DocumentReference` → `LocalEnvironment.addSnapshotListener`
+ *      with `target = { kind: 'doc', path }`.
+ *   - `CollectionReference` (and any `Query` whose collection root is
+ *      reachable via `.path` or `.parent.path`) → `target = { kind: 'query', collection }`.
+ *   - Chained queries (`.where`/`.orderBy`/`.limit`) currently route as
+ *      whole-collection listeners; the simulator fires for any change in
+ *      the collection, and the callback receives every document. Slice 6
+ *      will add filter/order honoring at the listener layer.
+ *
+ * The registering context's `auth` is captured at register time and
+ * threaded through to `addSnapshotListener` so notifications evaluate
+ * rules under the auth that subscribed — not whatever auth happens to
+ * be active when a write triggers dispatch
+ * (`addSnapshotListener`'s auth-capture invariant).
+ *
+ * REMOTE ARM: refs minted by the channel-backed handle carry their own
+ * listener registrar (`getRemoteSnapshotRegistrar`) — dispatched before
+ * any local-engine resolution, since `getInternalEnv` rejects remote
+ * handles.
+ */
+import { SandboxError } from 'pyric/sandbox';
+import { getInternalEnv } from 'pyric/sandbox/internal';
+import { BYPASS_RULES_SYMBOL, CONTEXT_SYMBOL, registerOnSnapshotImpl, } from './error-translation.js';
+import { getRemoteSnapshotRegistrar, registerRemoteOnSnapshotImpl } from './remote/listeners.js';
+import { AUTH_SESSION_SCOPE, FOLLOWS_CURRENT_USER, } from 'pyric/firestore/internal';
+/**
+ * Internal channel for the modular `pyric/firestore` layer to mark a
+ * listener as live (identity follows `sandbox.currentUser`) vs frozen
+ * (`getFirestore(ctx)`, pinned identity). The chainable adapter sees only
+ * a `SandboxContext` per call and can't tell the two apart on its own — the
+ * live-vs-frozen distinction lives one layer up. The modular `onSnapshot`
+ * stamps this symbol onto the options object it forwards; {@link onSnapshot}
+ * here reads + strips it and threads the boolean into
+ * `LocalEnvironment.addSnapshotListener`'s `followsCurrentUser` parameter.
+ *
+ * Symbol-keyed (not a named field) so it never collides with a real
+ * `SnapshotListenOptions` field and never leaks to consumer code.
+ */
+/**
+ * Extract a `{ collectionPath }` for query-shaped refs. The compat
+ * `QueryImpl` keeps its `collectionPath` as a `protected` field, but
+ * `CollectionRefImpl` exposes it via the public `path` getter, and
+ * chained queries (the only thing `where`/`orderBy`/`limit` produces)
+ * inherit from `QueryImpl` — both expose the same internal field.
+ *
+ * Read it via a structural lookup rather than `instanceof` so this
+ * adapter never has to import the compat impl class (which would create
+ * a circular dependency through `pyric/sandbox/admin-compat`).
+ *
+ * Returns `null` for refs we cannot route (anonymous/foreign Query
+ * implementations); the caller throws a clear remediation error.
+ */
+function extractCollectionPath(ref) {
+    if (ref === null || typeof ref !== 'object')
+        return null;
+    const obj = ref;
+    // CollectionReference exposes `path` publicly.
+    if (typeof obj.path === 'string' && obj.path.length > 0)
+        return obj.path;
+    // QueryImpl keeps it on a protected field; protected is a TypeScript-
+    // only restriction at runtime, so this lookup succeeds for anything
+    // produced by `db.collection('x').where(...)` etc.
+    if (typeof obj.collectionPath === 'string' && obj.collectionPath.length > 0) {
+        return obj.collectionPath;
+    }
+    return null;
+}
+/**
+ * Pull the query's `where` / `orderBy` / cursor / `limit` constraints
+ * off a query-shaped ref as a pure row transformer (FS-B2), so a
+ * filtered `onSnapshot(query(...))` delivers the same membership as a
+ * one-shot `getDocs(query(...))`. `QueryImpl.snapshotConstraints()` is a
+ * public method on every query produced by `db.collection(...).where(...)`
+ * etc.; a bare `CollectionReference` returns `undefined` (no filtering).
+ * Structural lookup keeps this adapter from importing the compat class.
+ */
+function extractSnapshotConstraints(ref) {
+    if (ref !== null && typeof ref === 'object') {
+        const fn = ref.snapshotConstraints;
+        if (typeof fn === 'function') {
+            return fn.call(ref);
+        }
+    }
+    return undefined;
+}
+/**
+ * Discriminate a `DocumentReference` from a `Query`/`CollectionReference`.
+ * The Admin-shaped `DocumentReference` always has a `parent: CollectionReference`
+ * field; `Query` and `CollectionReference` do not have a `parent` field.
+ */
+function isDocumentReference(ref) {
+    if (ref === null || typeof ref !== 'object')
+        return false;
+    const obj = ref;
+    return (typeof obj.path === 'string' &&
+        obj.path.length > 0 &&
+        obj.parent !== undefined &&
+        obj.parent !== null);
+}
+/**
+ * Implementation. The argument shape is normalized into
+ * `{ options, onNext, onError, onCompletion }` here, then routed to
+ * `LocalEnvironment.addSnapshotListener`.
+ *
+ * `onCompletion` is accepted but never invoked: the local listener
+ * stream has no terminal state. Documented in the `SnapshotObserver`
+ * contract.
+ *
+ * Routing failures (Query without a discoverable collection path, or a
+ * ref that is neither doc nor query) throw immediately — they indicate
+ * a programming mistake the caller can fix. Per-call rule denials, by
+ * contrast, are routed through `onError` (or swallowed if no handler is
+ * supplied), matching production `onSnapshot` behavior.
+ */
+export function onSnapshot(reference, 
+// `any`-typed callback in the impl signature is intentional: each
+// overload narrows the callback to a specific snapshot shape, but
+// function parameter types are contravariant — a `(snap: LiveDoc) => void`
+// is *not* assignable to a `(snap: unknown) => void`. Using `any`
+// here keeps every overload assignable to the impl signature without
+// weakening the public surface (the overloads are what consumers see).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+arg2, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+arg3, arg4, arg5) {
+    // ── Normalize the (options, observer | callback set) variations. ──
+    let options = {};
+    let onNext;
+    let onError;
+    // Detect whether arg2 is the SnapshotListenOptions slot. The options
+    // object is the only plain-object value at arg2 that lacks both `next`
+    // and an `error` handler shaped like a function — the observer form
+    // always has at least one handler. This matches how the Web SDK
+    // discriminates.
+    const arg2IsOptions = typeof arg2 === 'object' &&
+        arg2 !== null &&
+        typeof arg2.next !== 'function' &&
+        typeof arg2.error !== 'function' &&
+        typeof arg2.complete !== 'function';
+    if (arg2IsOptions) {
+        options = arg2;
+        if (typeof arg3 === 'function') {
+            onNext = arg3;
+            onError = arg4;
+            // arg5 is onCompletion — accepted, never invoked (no terminal state).
+        }
+        else if (typeof arg3 === 'object' && arg3 !== null) {
+            const obs = arg3;
+            onNext = obs.next;
+            onError = obs.error;
+        }
+    }
+    else if (typeof arg2 === 'function') {
+        onNext = arg2;
+        onError = arg3;
+        // arg4 is onCompletion — accepted, never invoked.
+    }
+    else if (typeof arg2 === 'object' && arg2 !== null) {
+        const obs = arg2;
+        onNext = obs.next;
+        onError = obs.error;
+    }
+    if (!onNext && !onError) {
+        // FS-B14 — prod accepts an observer carrying only `error` (or
+        // `complete`); it registers and routes denials to the error handler.
+        // Only a fully-empty observer (no next AND no error) is a programming
+        // error. Pre-fix this required `next`, so an `{ error: fn }` observer
+        // threw "missing next handler".
+        throw new TypeError('onSnapshot: missing handler. Provide a callback, or an observer with a ' +
+            '`next` and/or `error` method.');
+    }
+    // The local listener stream has no terminal state, so a `next`-less
+    // observer registers purely to receive errors — `onNext` stays undefined
+    // and `addSnapshotListener` only fires the error path.
+    // ── REMOTE ARM: refs minted by the channel-backed handle carry their
+    // own listener registrar — dispatch on it BEFORE any local-engine
+    // resolution (`getInternalEnv` rejects remote handles). The registrar
+    // pins the handle's auth lens on the worker subscription; error
+    // callbacks receive `SandboxError`s with `denialContext` when the
+    // worker carried one.
+    const remoteRegistrar = getRemoteSnapshotRegistrar(reference);
+    if (remoteRegistrar) {
+        if (options[FOLLOWS_CURRENT_USER] === true) {
+            // The live-listener marker is stamped by the modular browser layer,
+            // which never runs against a remote handle — defensive throw so a
+            // future mis-wiring fails loudly instead of silently freezing.
+            throw new SandboxError('unimplemented', 'onSnapshot: live (follows-current-user) listeners are not supported on a ' +
+                'remote sandbox — remote listeners are frozen to the identity of the ' +
+                'context that created the ref.');
+        }
+        return remoteRegistrar(options, onNext, onError);
+    }
+    // ── Resolve the context + target from the ref. ──
+    const ctx = contextFromRef(reference);
+    const env = getInternalEnv(ctx.sandbox);
+    let target;
+    if (isDocumentReference(reference)) {
+        target = { kind: 'doc', path: reference.path };
+    }
+    else {
+        const collectionPath = extractCollectionPath(reference);
+        if (collectionPath === null) {
+            throw new TypeError('onSnapshot: could not determine the collection path for this Query. ' +
+                'Pass a CollectionReference or a Query produced by `.where`/`.orderBy`/`.limit` ' +
+                'on a CollectionReference obtained from `getFirestore(ctx)`.');
+        }
+        // FS-B2 — thread the query's where/orderBy/limit/cursor constraints
+        // into the target so the listener delivers a filtered/ordered/limited
+        // view (matching getDocs), not the whole collection.
+        const constraints = extractSnapshotConstraints(reference);
+        target = { kind: 'query', collection: collectionPath, constraints };
+    }
+    // Read the live-vs-frozen marker the modular layer stamped onto the
+    // options object (FOLLOWS_CURRENT_USER), then strip it so it never
+    // reaches the listener record's public `options`. Absent ⇒ frozen
+    // (the safe default for any direct chainable-adapter caller).
+    const followsCurrentUser = options[FOLLOWS_CURRENT_USER] === true;
+    const authScope = options[AUTH_SESSION_SCOPE];
+    const bypassRules = reference[BYPASS_RULES_SYMBOL] === true;
+    if (FOLLOWS_CURRENT_USER in options) {
+        const { [FOLLOWS_CURRENT_USER]: _omit, ...rest } = options;
+        options = rest;
+    }
+    if (AUTH_SESSION_SCOPE in options) {
+        const { [AUTH_SESSION_SCOPE]: _omit, ...rest } = options;
+        options = rest;
+    }
+    // A `next`-less (error-only) observer registers with a no-op data handler
+    // so the listener machinery stays on its non-optional callback contract;
+    // denials still route to `onError` (FS-B14).
+    return env.addSnapshotListener(target, onNext ?? (() => { }), options, ctx.auth, onError, followsCurrentUser, bypassRules, authScope);
+}
+/**
+ * Recover the {@link SandboxContext} that produced a ref. Refs returned
+ * from `db.doc(path)` / `db.collection(path)` are wrapped by
+ * `wrapWithErrorTranslation`, which stashes the owning context on the
+ * `CONTEXT_SYMBOL` property of every wrapped object. Reading that
+ * symbol gives us the auth + sandbox in one step — multiple contexts
+ * can share an env, and this lookup correctly picks the one that
+ * produced *this* ref.
+ */
+function contextFromRef(ref) {
+    if (ref === null || typeof ref !== 'object') {
+        throw new TypeError('onSnapshot: reference must be a DocumentReference or Query.');
+    }
+    const ctx = ref[CONTEXT_SYMBOL];
+    if (!ctx) {
+        throw new TypeError('onSnapshot: reference was not produced by a sandbox context — pass a ref obtained from `getFirestore(ctx)`.');
+    }
+    return ctx;
+}
+// ─── Chainable `.onSnapshot(...)` shim ─────────────────────────────────
+//
+// The free `onSnapshot(ref, observer)` function above mirrors
+// `firebase/firestore`'s modular shape. The rest of `pyric-admin` is
+// chainable-method-shaped, though, and agents reach for
+// `db.collection(path).where(...).onSnapshot(cb)` more often than the
+// free form. To eliminate the asymmetry without losing the modular
+// surface, we declare a chainable `.onSnapshot(...)` method on
+// DocumentReference/CollectionReference/Query via module augmentation
+// and synthesize the implementation in the error-translation Proxy.
+// Both forms route through the same listener registration.
+//
+// The free function stays exported — both styles are first-class.
+// Augmentation made the chainable `.onSnapshot()` method appear on
+// DocumentReference and Query. Under the consolidated layout (admin-compat
+// and admin-firestore in the same package), the augmentation strict-checks
+// every impl class against this signature, which breaks the impl classes
+// that don't define `.onSnapshot()` directly (the Proxy synthesizes it).
+//
+// Post-cutover behavior: use the free `onSnapshot(ref, observer)` function
+// exported above. The chainable `ref.onSnapshot()` continues to work at
+// runtime via the Proxy in error-translation.ts, but is no longer typed.
+// A future iteration can revive the typed chainable variant by moving the
+// augmentation into a separate consumer-facing declaration file that's
+// excluded from impl compilation.
+// Wire the synthesizer. Done at module init, after `onSnapshot` is
+// fully declared so the function reference is stable. The remote arm's
+// chainable `ref.onSnapshot(...)` late-binds through the same free
+// function (a static import back from remote/listeners.ts would be a cycle).
+registerOnSnapshotImpl(onSnapshot);
+registerRemoteOnSnapshotImpl(onSnapshot);
+//# sourceMappingURL=listeners.js.map

package/dist/sandbox/admin-firestore/listeners.js.map

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

package/dist/sandbox/admin-firestore/local-handle.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Raw local-engine `SandboxFirestore` builder — wraps the
+ * `pyric/sandbox/admin-compat` implementation for one `SandboxContext`.
+ * Used by both `get-firestore.ts` (rules-enforced) and
+ * `get-admin-firestore.ts` (rules-bypassing); the `bypassRules` flag is
+ * the only difference between the two callers.
+ */
+import { type SandboxContext } from 'pyric/sandbox';
+import type { SandboxFirestore } from './types.js';
+/**
+ * Build a `SandboxFirestore` that delegates each operation to a freshly
+ * constructed compat impl. Constructing the delegate per-call is cheap
+ * (no allocation cost beyond the class instance) and ensures the
+ * operation reads from whatever environment the sandbox currently
+ * exposes — `reset()` propagates without explicit cache invalidation.
+ *
+ * The handle ignores any per-op `OperationOptions` it receives and
+ * always issues operations under `ctx.auth`. To test as a different
+ * user, derive a sibling context via `sandbox.withAuth(...)` and
+ * attach a service handle to that.
+ */
+export declare function buildFirestoreHandle(ctx: SandboxContext, bypassRules?: boolean): SandboxFirestore;
+//# sourceMappingURL=local-handle.d.ts.map