pyric 0.0.1 → 0.1.0-alpha.7

package/dist/sandbox/firestore/transaction-merge.js

@@ -0,0 +1,107 @@
+/**
+ * Thrown when the queue contains a `delete` followed by another write
+ * at the same path. The combination is unprobed; v1 errors instead of
+ * guessing. The wrapper in the commit path (Item 2) translates this
+ * to a `FirestoreSimError { code: 'failed-precondition' }` with a
+ * message naming the unprobed combo.
+ */
+export class AmbiguousPostDeleteWriteError extends Error {
+    path;
+    secondMethod;
+    constructor(path, secondMethod) {
+        super(`Queued ${secondMethod} on '${path}' after a delete in the same ` +
+            `transaction. This combination is unprobed against production ` +
+            `Firestore; refusing to guess. Either drop the delete or split ` +
+            `into two transactions.`);
+        this.name = 'AmbiguousPostDeleteWriteError';
+        this.path = path;
+        this.secondMethod = secondMethod;
+    }
+}
+/**
+ * Collapse the per-path queue into one `BatchOperation` per path.
+ *
+ * - Iterates writes in queue order.
+ * - For each path, maintains the "effective op" (method + accumulated
+ *   data) and folds in subsequent writes per the table above.
+ * - Throws `AmbiguousPostDeleteWriteError` on `delete + anything`.
+ */
+export function mergeQueuedWrites(writes) {
+    // Insertion-ordered map keeps the output stable for callers that
+    // care about ordering across paths (none today, but cheap to preserve).
+    const byPath = new Map();
+    for (const w of writes) {
+        const prior = byPath.get(w.path);
+        if (prior === undefined) {
+            byPath.set(w.path, toBatchOp(w));
+            continue;
+        }
+        if (prior.method === 'delete') {
+            throw new AmbiguousPostDeleteWriteError(w.path, w.method);
+        }
+        byPath.set(w.path, fold(prior, w));
+    }
+    return Array.from(byPath.values());
+}
+/** Convert a single queued write to its initial `BatchOperation` shape. */
+function toBatchOp(w) {
+    if (w.method === 'delete') {
+        return { method: 'delete', path: w.path };
+    }
+    // set / create / update all carry data; queue invariant.
+    if (w.data === undefined) {
+        throw new Error(`internal: queued ${w.method} on ${w.path} has no data — ` +
+            `Transaction class invariant violated`);
+    }
+    return { method: w.method, path: w.path, data: w.data };
+}
+/**
+ * Fold a new queued write into an existing same-path effective op.
+ * Pre: `prior.method !== 'delete'` (caller checked).
+ */
+function fold(prior, next) {
+    switch (next.method) {
+        case 'delete':
+            // Anything-then-delete: final state is gone.
+            return { method: 'delete', path: next.path };
+        case 'set': {
+            // Anything-then-set: set replaces entirely. The earlier op is
+            // semantically erased (Admin's set is overwrite).
+            const data = requireData(next);
+            return { method: 'set', path: next.path, data };
+        }
+        case 'update': {
+            // Merge update fields onto the prior payload. Last-wins per
+            // field; earlier non-overlapping fields preserved (probe 0.D).
+            const updateData = requireData(next);
+            const priorData = prior.data ?? {};
+            const merged = { ...priorData, ...updateData };
+            // Method stays the same as prior — set+update keeps `set`,
+            // create+update keeps `create`, update+update stays `update`.
+            // This preserves the "structural failure" semantics: a `create`
+            // that's later updated still throws `already-exists` if the doc
+            // exists at commit, which is what production would do.
+            return { method: prior.method, path: next.path, data: merged };
+        }
+        case 'create': {
+            // create-after-anything-non-delete is unusual but well-defined:
+            // the prior op already established intent, then create adds a
+            // fail-on-exists guard. We honor the most recent intent — if
+            // someone queued `update` then `create`, the final intent is
+            // create-with-merged-data. This is consistent with the
+            // update-after-create case and avoids a third "ambiguous" throw.
+            const createData = requireData(next);
+            const priorData = prior.data ?? {};
+            const merged = { ...priorData, ...createData };
+            return { method: 'create', path: next.path, data: merged };
+        }
+    }
+}
+function requireData(w) {
+    if (w.data === undefined) {
+        throw new Error(`internal: queued ${w.method} on ${w.path} has no data — ` +
+            `Transaction class invariant violated`);
+    }
+    return w.data;
+}
+//# sourceMappingURL=transaction-merge.js.map

package/dist/sandbox/firestore/transaction-merge.js.map

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

package/dist/sandbox/firestore/transaction-types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Item 1.1 — Transaction type surface.
+ *
+ * Locked decisions live in the design rationale's
+ * Decisions Log. Re-stated here only as inline anchors:
+ *
+ *   - 0.B: `tx.get` of a missing doc returns `{ exists: false, data: () =>
+ *     undefined }`. Never throws. Mirrors Admin SDK shape.
+ *   - 0.C: `tx.getAll(...paths)` returns snapshots in input order.
+ *   - 0.A + 0.J: read-before-write ordering is GLOBAL — any write method
+ *     flips a per-tx flag; subsequent reads throw `failed-precondition`.
+ *   - 0.D: same-path multi-write merges on commit (last-wins per field).
+ *     The merge happens at commit time in `transaction-merge.ts`; the
+ *     queue here is append-only.
+ *   - 0.G: callback exceptions propagate unchanged. The result types
+ *     here only describe the *successful* (or rule-denied) path; thrown
+ *     errors don't construct a `TransactionResult`.
+ *   - 0.H: no `retries` field. Single-threaded simulator can't trigger
+ *     conflicts. Documented as a known limitation.
+ */
+import type { DocumentData } from './local-state.js';
+import type { AgentEvent } from './event-log.js';
+import type { FirestoreSimError } from './errors.js';
+/**
+ * Snapshot shape returned by `tx.get` / `tx.getAll`. Matches the Admin
+ * SDK's `DocumentSnapshot` surface narrowly enough for the rules-eval
+ * use case — `exists` discriminates and `data()` is lazy because it
+ * mirrors the Admin SDK signature even though our impl is eager.
+ *
+ * Probe 0.B: Admin returns `snap.exists === false` and `snap.data() ===
+ * undefined` for a missing doc; never throws. Our shape matches.
+ */
+export interface TransactionSnapshot {
+    readonly path: string;
+    readonly exists: boolean;
+    data(): DocumentData | undefined;
+}
+/**
+ * Internal — a single read captured during the callback. Surfaced on
+ * `TransactionResult.reads` for diagnostic value (production doesn't
+ * expose this, but agents debugging "why did my tx commit nothing"
+ * benefit from seeing what the callback saw).
+ */
+export interface CapturedRead {
+    path: string;
+    data: DocumentData | null;
+}
+/**
+ * Internal — a queued write before merge/commit. Carries the original
+ * call method so `transaction-merge.ts` can collapse same-path entries
+ * with the right semantics (`update + update` merges; `set + update`
+ * applies update on top of set; etc.).
+ */
+export interface QueuedWrite {
+    method: 'set' | 'create' | 'update' | 'delete';
+    path: string;
+    data?: DocumentData;
+}
+/**
+ * Caller surface for `Transaction`. Implementation lives in
+ * `transaction.ts`; this interface is what callbacks see.
+ *
+ * `set` is included even though `BatchOperationInput` doesn't expose
+ * it — the Admin SDK's transaction does, and the merge layer collapses
+ * `set` into the appropriate `BatchOperation` at commit.
+ */
+export interface Transaction {
+    /** Admin-mode read; never evaluates rules. */
+    get(path: string): TransactionSnapshot;
+    /** Admin-mode batched read; preserves input order. */
+    getAll(...paths: string[]): TransactionSnapshot[];
+    /** Queue a `set` (overwrite-or-create). Flips writeStarted. */
+    set(path: string, data: DocumentData): void;
+    /** Queue a `create` (fail-on-exists at commit). Flips writeStarted. */
+    create(path: string, data: DocumentData): void;
+    /** Queue an `update` (fail-if-missing at commit). Flips writeStarted. */
+    update(path: string, data: DocumentData): void;
+    /** Queue a `delete`. Flips writeStarted. */
+    delete(path: string): void;
+}
+/**
+ * Options accepted by `LocalEnvironment.transaction(fn, options)`.
+ *
+ * `auth` is required (matches `Operation.auth` shape elsewhere in the
+ * simulator); rules eval needs it on every queued write.
+ *
+ * `readOnly` is the side-finding from probe 0.H — Admin's
+ * `runTransaction(fn, { readOnly })` accepts it. v1 simulator records
+ * a `readOnlyViolation: true` on the result if a write was queued
+ * inside a read-only tx, but does NOT throw. Provisional; v2 may flip
+ * to strict.
+ */
+export interface TransactionOptions {
+    auth: {
+        uid: string;
+        token?: Record<string, unknown>;
+    } | null;
+    readOnly?: boolean;
+    /**
+     * Studio admin lens (Pyric Studio Gap #2). When `true`, per-write rule
+     * evaluation at commit is skipped — every queued write is treated as
+     * ALLOW. Storage preconditions (create-already-exists, etc.) and the
+     * normal commit/event/listener path still apply, so an admin transaction
+     * behaves like a rule-allowed one minus the rule gate. Transaction reads
+     * (`tx.get`) already bypass rules in the sandbox model, so this flag only
+     * affects the write commit. Default (absent/false) enforces rules.
+     */
+    bypassRules?: boolean;
+}
+/**
+ * Result returned from `LocalEnvironment.transaction(...)` on success
+ * or rule-denial. Thrown errors (callback throw, read-after-write
+ * violation) do NOT produce a `TransactionResult` — they propagate.
+ *
+ * `reads` is included for diagnostic value (production doesn't surface
+ * this; we do). `writes` is one entry per *queued* write at the time
+ * of commit, post-merge — so two `update` calls to the same path
+ * produce one `writes[]` entry, not two.
+ */
+export interface TransactionResult<R = unknown> {
+    /** True iff every queued write passed rules and applied. */
+    allowed: boolean;
+    reads: CapturedRead[];
+    writes: {
+        path: string;
+        method: 'create' | 'update' | 'delete';
+        allowed: boolean;
+        debugMessages: string[];
+        error?: FirestoreSimError;
+    }[];
+    /** Whatever the callback returned; `undefined` if it returned nothing. */
+    returnValue: R | undefined;
+    event: AgentEvent;
+    /** Top-level error (atomic-rollback case). Absent when `allowed: true`. */
+    error?: FirestoreSimError;
+    /**
+     * Provisional 0.H side-finding: true iff a write method was called
+     * inside a `readOnly: true` transaction. v1 still queues + commits
+     * the write; v2 may flip to strict (throw at the call site).
+     */
+    readOnlyViolation?: boolean;
+}
+/**
+ * Locked Admin SDK message for read-after-write violations. Matched
+ * exactly so `error.message` parity is preserved for callers that
+ * stringify and grep — agents porting tests from prod expect the
+ * same wording.
+ *
+ * Source: probe 0.A run 2026-05-05 against firebase-admin 12.x.
+ */
+export declare const READ_AFTER_WRITE_MESSAGE = "Firestore transactions require all reads to be executed before all writes.";
+//# sourceMappingURL=transaction-types.d.ts.map

package/dist/sandbox/firestore/transaction-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-types.d.ts","sourceRoot":"","sources":["../../../src/sandbox/firestore/transaction-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,IAAI,IAAI,YAAY,GAAG,SAAS,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACvC,sDAAsD;IACtD,MAAM,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,mBAAmB,EAAE,CAAC;IAElD,+DAA+D;IAC/D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5C,uEAAuE;IACvE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/C,yEAAyE;IACzE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/C,4CAA4C;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;QACvC,OAAO,EAAE,OAAO,CAAC;QACjB,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;KAC3B,EAAE,CAAC;IACJ,0EAA0E;IAC1E,WAAW,EAAE,CAAC,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,+EACyC,CAAC"}

package/dist/sandbox/firestore/transaction-types.js

@@ -0,0 +1,10 @@
+/**
+ * Locked Admin SDK message for read-after-write violations. Matched
+ * exactly so `error.message` parity is preserved for callers that
+ * stringify and grep — agents porting tests from prod expect the
+ * same wording.
+ *
+ * Source: probe 0.A run 2026-05-05 against firebase-admin 12.x.
+ */
+export const READ_AFTER_WRITE_MESSAGE = 'Firestore transactions require all reads to be executed before all writes.';
+//# sourceMappingURL=transaction-types.js.map

package/dist/sandbox/firestore/transaction-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-types.js","sourceRoot":"","sources":["../../../src/sandbox/firestore/transaction-types.ts"],"names":[],"mappings":"AAmJA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,4EAA4E,CAAC"}

package/dist/sandbox/firestore/transaction.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Item 1.2 — `Transaction` callback class.
+ *
+ * The class agents see inside their `runTransaction` callback. Its job
+ * is narrow:
+ *
+ *   1. Capture reads (admin-mode, no rules) via an injected reader
+ *      callback. This decouples the class from `LocalEnvironment` for
+ *      testability — Item 2 binds the reader to `this.getDocument`.
+ *   2. Queue writes append-only. The merge / atomic-apply / rules-eval
+ *      all happen *after* the callback returns, in `LocalEnvironment.
+ *      transaction()` (Item 2.1).
+ *   3. Enforce global read-before-write ordering — once any write
+ *      method runs, every subsequent `get` / `getAll` throws. This is
+ *      the locked Admin SDK behavior (probes 0.A + 0.J).
+ *
+ * The class is single-use: a fresh instance is constructed per call to
+ * `LocalEnvironment.transaction(...)`. After the callback returns,
+ * `consume()` hands the captured reads + queued writes to the commit
+ * path and the instance is discarded.
+ */
+import type { DocumentData } from './local-state.js';
+import { type FirestoreSimError } from './errors.js';
+import { type CapturedRead, type QueuedWrite, type Transaction, type TransactionSnapshot } from './transaction-types.js';
+/**
+ * Reader signature. Returns the document at `path` or `null` if it
+ * doesn't exist. Bound at construction time; the class itself doesn't
+ * know whether the reader hits `LocalState`, a stub, or a remote.
+ */
+export type TransactionReader = (path: string) => DocumentData | null;
+/**
+ * Thrown synchronously by `tx.get` / `tx.getAll` when called after
+ * any write method. Maps cleanly to the simulator's typed-error
+ * surface — callers in Item 2 catch this, translate to
+ * `FirestoreSimError { code: 'failed-precondition' }`, and re-raise.
+ *
+ * Carrying a typed error class (rather than a plain `Error`) lets the
+ * commit path discriminate from arbitrary user throws (probe 0.G:
+ * those propagate unchanged) without instanceof-checking message
+ * strings.
+ */
+export declare class ReadAfterWriteError extends Error {
+    readonly simError: FirestoreSimError;
+    constructor();
+}
+/**
+ * Single-use transaction context. See file header for design notes.
+ */
+export declare class TransactionContext implements Transaction {
+    private readonly reader;
+    private readonly reads;
+    private readonly writes;
+    private writeStarted;
+    constructor(reader: TransactionReader);
+    get(path: string): TransactionSnapshot;
+    getAll(...paths: string[]): TransactionSnapshot[];
+    set(path: string, data: DocumentData): void;
+    create(path: string, data: DocumentData): void;
+    update(path: string, data: DocumentData): void;
+    delete(path: string): void;
+    /**
+     * Hand reads + queued writes to the commit path. After this is
+     * called the instance is dead — further calls would corrupt the
+     * commit. Item 2 calls this exactly once after the callback returns.
+     */
+    consume(): {
+        reads: readonly CapturedRead[];
+        writes: readonly QueuedWrite[];
+    };
+    /**
+     * True iff any write method has been called. Item 2.3 checks this
+     * after the callback returns to populate `readOnlyViolation` when
+     * the tx was started with `readOnly: true`.
+     */
+    hadWrites(): boolean;
+    private queue;
+    private assertReadsAllowed;
+}
+//# sourceMappingURL=transaction.d.ts.map

package/dist/sandbox/firestore/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/sandbox/firestore/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAa,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAC;AAEhC;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,GAAG,IAAI,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;;CAMtC;AAED;;GAEG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,iBAAiB;IAMrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB;IAetC,MAAM,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,mBAAmB,EAAE;IASjD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAG3C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAG9C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAG9C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM1B;;;;OAIG;IACH,OAAO,IAAI;QAAE,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;QAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;KAAE;IAI7E;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAMpB,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,kBAAkB;CAK3B"}

package/dist/sandbox/firestore/transaction.js

@@ -0,0 +1,95 @@
+import { makeError } from './errors.js';
+import { READ_AFTER_WRITE_MESSAGE, } from './transaction-types.js';
+/**
+ * Thrown synchronously by `tx.get` / `tx.getAll` when called after
+ * any write method. Maps cleanly to the simulator's typed-error
+ * surface — callers in Item 2 catch this, translate to
+ * `FirestoreSimError { code: 'failed-precondition' }`, and re-raise.
+ *
+ * Carrying a typed error class (rather than a plain `Error`) lets the
+ * commit path discriminate from arbitrary user throws (probe 0.G:
+ * those propagate unchanged) without instanceof-checking message
+ * strings.
+ */
+export class ReadAfterWriteError extends Error {
+    simError;
+    constructor() {
+        super(READ_AFTER_WRITE_MESSAGE);
+        this.name = 'ReadAfterWriteError';
+        this.simError = makeError('failed-precondition', READ_AFTER_WRITE_MESSAGE);
+    }
+}
+/**
+ * Single-use transaction context. See file header for design notes.
+ */
+export class TransactionContext {
+    reader;
+    reads = [];
+    writes = [];
+    writeStarted = false;
+    constructor(reader) {
+        this.reader = reader;
+    }
+    // ─── Reads ────────────────────────────────────────────────────────
+    get(path) {
+        this.assertReadsAllowed();
+        const data = this.reader(path);
+        this.reads.push({ path, data });
+        // Capture-by-value: callbacks that mutate `data()` later don't
+        // poison the captured read set. Cheap (small docs) and matches
+        // production semantics where the snapshot is immutable.
+        const captured = data === null ? null : structuredClone(data);
+        return {
+            path,
+            exists: captured !== null,
+            data: () => (captured === null ? undefined : captured),
+        };
+    }
+    getAll(...paths) {
+        this.assertReadsAllowed();
+        // Order-preserving: probe 0.C confirmed Admin returns snapshots
+        // in input order. We mirror that by mapping in place.
+        return paths.map(p => this.get(p));
+    }
+    // ─── Writes ───────────────────────────────────────────────────────
+    set(path, data) {
+        this.queue({ method: 'set', path, data });
+    }
+    create(path, data) {
+        this.queue({ method: 'create', path, data });
+    }
+    update(path, data) {
+        this.queue({ method: 'update', path, data });
+    }
+    delete(path) {
+        this.queue({ method: 'delete', path });
+    }
+    // ─── Internal — used by Item 2's commit path ──────────────────────
+    /**
+     * Hand reads + queued writes to the commit path. After this is
+     * called the instance is dead — further calls would corrupt the
+     * commit. Item 2 calls this exactly once after the callback returns.
+     */
+    consume() {
+        return { reads: this.reads, writes: this.writes };
+    }
+    /**
+     * True iff any write method has been called. Item 2.3 checks this
+     * after the callback returns to populate `readOnlyViolation` when
+     * the tx was started with `readOnly: true`.
+     */
+    hadWrites() {
+        return this.writeStarted;
+    }
+    // ─── Private ──────────────────────────────────────────────────────
+    queue(write) {
+        this.writeStarted = true;
+        this.writes.push(write);
+    }
+    assertReadsAllowed() {
+        if (this.writeStarted) {
+            throw new ReadAfterWriteError();
+        }
+    }
+}
+//# sourceMappingURL=transaction.js.map

package/dist/sandbox/firestore/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../src/sandbox/firestore/transaction.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,SAAS,EAA0B,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,wBAAwB,GAKzB,MAAM,wBAAwB,CAAC;AAShC;;;;;;;;;;GAUG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,QAAQ,CAAoB;IACrC;QACE,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC,qBAAqB,EAAE,wBAAwB,CAAC,CAAC;IAC7E,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAkB;IACZ,MAAM,CAAoB;IAC1B,KAAK,GAAmB,EAAE,CAAC;IAC3B,MAAM,GAAkB,EAAE,CAAC;IACpC,YAAY,GAAG,KAAK,CAAC;IAE7B,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,qEAAqE;IAErE,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,+DAA+D;QAC/D,+DAA+D;QAC/D,wDAAwD;QACxD,MAAM,QAAQ,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAC9D,OAAO;YACL,IAAI;YACJ,MAAM,EAAE,QAAQ,KAAK,IAAI;YACzB,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;SACvD,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,GAAG,KAAe;QACvB,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,gEAAgE;QAChE,sDAAsD;QACtD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,qEAAqE;IAErE,GAAG,CAAC,IAAY,EAAE,IAAkB;QAClC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,CAAC,IAAY,EAAE,IAAkB;QACrC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,CAAC,IAAY,EAAE,IAAkB;QACrC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,CAAC,IAAY;QACjB,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,qEAAqE;IAErE;;;;OAIG;IACH,OAAO;QACL,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,qEAAqE;IAE7D,KAAK,CAAC,KAAkB;QAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAEO,kBAAkB;QACxB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,MAAM,IAAI,mBAAmB,EAAE,CAAC;QAClC,CAAC;IACH,CAAC;CACF"}

package/dist/sandbox/firestore/value-equality.d.ts

@@ -0,0 +1,2 @@
+export declare function firestoreValuesEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=value-equality.d.ts.map

package/dist/sandbox/firestore/value-equality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-equality.d.ts","sourceRoot":"","sources":["../../../src/sandbox/firestore/value-equality.ts"],"names":[],"mappings":"AAmBA,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAcpE"}

package/dist/sandbox/firestore/value-equality.js

@@ -0,0 +1,35 @@
+function hasFirestoreValueEquality(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'isEqual' in value &&
+        typeof value.isEqual === 'function');
+}
+function isFirestoreMapValue(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+export function firestoreValuesEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (hasFirestoreValueEquality(a))
+        return a.isEqual(b);
+    if (hasFirestoreValueEquality(b))
+        return b.isEqual(a);
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((value, index) => firestoreValuesEqual(value, b[index]));
+    }
+    if (!isFirestoreMapValue(a) || !isFirestoreMapValue(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => key in b && firestoreValuesEqual(a[key], b[key]));
+}
+//# sourceMappingURL=value-equality.js.map

package/dist/sandbox/firestore/value-equality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-equality.js","sourceRoot":"","sources":["../../../src/sandbox/firestore/value-equality.ts"],"names":[],"mappings":"AAIA,SAAS,yBAAyB,CAAC,KAAc;IAC/C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QAClB,OAAQ,KAA+B,CAAC,OAAO,KAAK,UAAU,CAC/D,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,CAAU,EAAE,CAAU;IACzD,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,yBAAyB,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,yBAAyB,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACzD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC"}