pyric 0.0.1 → 0.1.0-alpha.7

package/dist/sandbox/firestore/sentinel-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel-capture.js","sourceRoot":"","sources":["../../../src/sandbox/firestore/sentinel-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,MAAM,UAAU,gBAAgB,CAAC,KAAc,EAAE,MAAM,GAAG,EAAE;IAC1D,MAAM,IAAI,GAAkB,EAAE,CAAC;IAC/B,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACrB,OAAO,IAAI,CAAC;IAEZ,SAAS,KAAK,CAAC,CAAU,EAAE,CAAS;QAClC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO;QACnE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,MAAM,GAAG,GAAG,CAA4B,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9B,OAAO;QACT,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,GAA4B;IAC1C,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;IACrB,IAAI,CAAC,KAAK,iBAAiB;QAAE,OAAO,iBAAiB,CAAC;IACtD,IAAI,CAAC,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IAC1C,IAAI,CAAC,KAAK,YAAY;QAAE,OAAO,YAAY,CAAC;IAC5C,IAAI,CAAC,KAAK,aAAa;QAAE,OAAO,aAAa,CAAC;IAC9C,IAAI,CAAC,KAAK,aAAa;QAAE,OAAO,QAAQ,CAAC;IACzC,OAAO,IAAI,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,284 @@
+/**
+ * Snapshot-listener types — Slices 1–3 of `onSnapshot`.
+ *
+ * Slice 1 added the registry; Slice 2 added Web-SDK-shaped snapshot
+ * types and the initial-fire wiring (in local-environment.ts); Slice 3
+ * adds change detection — recompute on writes, diff against the prior
+ * snapshot, suppress no-ops, fire surviving callbacks. See
+ * the design rationale for the slice plan and
+ * the design rationale for the production
+ * patterns these types are adapted from (firebase-js-sdk 4.14.1, section 3,
+ * section 4, section 5).
+ */
+import type { DocumentData } from './local-state.js';
+import type { Operation } from './local-environment.js';
+import type { QueryConstraints } from '../../rules/simulator/query-proof.js';
+/**
+ * A query's `where` / `orderBy` / cursor / `limit` constraints as a
+ * pure row transformer (FS-B2). `addSnapshotListener` threads this in
+ * from the chainable `QueryImpl.snapshotConstraints()` so a filtered
+ * `onSnapshot(query(...))` delivers the same membership as a one-shot
+ * `getDocs(query(...))`. `undefined` means a bare collection listen
+ * (no constraints) — the whole rule-allowed collection is delivered.
+ *
+ * RULES-B11 — the applier also carries `structured`, the query's
+ * `where`/`limit`/`orderBy` as data (not just an opaque transformer), so
+ * `silentReadCollection` can run `evaluateQueryProof` against the matched
+ * `list` rule: an unprovable query is DENIED whole ("rules are not
+ * filters"), never silently filtered. Carried on the function object so
+ * existing call sites that just thread the applier through stay unchanged.
+ */
+export interface QueryConstraintApplier {
+    (rows: {
+        path: string;
+        data: DocumentData;
+    }[]): {
+        path: string;
+        data: DocumentData;
+    }[];
+    /** Structured constraints for the query-proof gate (RULES-B11). Absent on
+     *  appliers built before the query carries any provable constraints. */
+    structured?: QueryConstraints;
+}
+/**
+ * What a listener is watching. Query targets carry their `where` /
+ * `orderBy` / `limit` constraints via {@link SnapshotTarget.constraints}
+ * (FS-B2) so the listener delivers a filtered/ordered/limited view
+ * rather than the whole collection.
+ */
+export type SnapshotTarget = {
+    kind: 'doc';
+    path: string;
+} | {
+    kind: 'query';
+    collection: string;
+    constraints?: QueryConstraintApplier;
+};
+/**
+ * Mirrors `SnapshotListenOptions` from the Web SDK. `source: 'cache'` has
+ * no analog in the sandbox (no offline cache) — accepted but treated as
+ * `'default'`.
+ *
+ * `includeMetadataChanges` is now observable (item 3 / COMPAT firestore#85):
+ * a local write echoes to every listener with `hasPendingWrites: true`, and
+ * `includeMetadataChanges` listeners additionally receive the server-ack
+ * fire (`hasPendingWrites: false`) that default listeners never see. See
+ * `LocalEnvironment.notifyDocListener` / `notifyQueryListener`. `fromCache`
+ * remains constant `false` — the sandbox has no offline cache to serve from.
+ */
+export interface SnapshotListenerOptions {
+    includeMetadataChanges?: boolean;
+    source?: 'default' | 'cache';
+}
+/**
+ * Callback shape is a placeholder until Slice 2 introduces the public
+ * `QuerySnapshot` / `DocumentSnapshot` types. Typed as `unknown` here so
+ * Slice 1 does not lock in a snapshot shape that survey item section 4 says
+ * needs careful construction (lazy `docs`, cached `docChanges()`).
+ */
+export type SnapshotCallback = (snapshot: unknown) => void;
+/**
+ * Stream errors. Per findings section 9, listener errors are stream-level —
+ * once delivered, the listener is silently terminated (no further
+ * snapshots). Slice 7 wires this end-to-end; the field exists in the
+ * record now so Slice 1 doesn't have to re-shape it later.
+ */
+export type SnapshotErrorCallback = (error: unknown) => void;
+/**
+ * The fork's auth context at registration time — captured per
+ * `addSnapshotListener` call rather than re-read at notification time.
+ *
+ * Why per-listener capture (write-time filtering): when a write by bob
+ * triggers a fan-out, alice's listener must re-read under ALICE's auth,
+ * not bob's. Re-reading "whatever auth is current" would let one user's
+ * write leak through another user's listener. So each listener pins the
+ * auth it subscribed with for write-driven re-evaluation. KEEP THIS.
+ *
+ * Why it ALSO re-captures (live listeners only): production doesn't just
+ * read auth once at listen-establishment — it RE-ESTABLISHES the listen
+ * stream when the session's own auth changes (sign-out/sign-in), so an
+ * auth-gated listener gets a permission-denied on sign-out. Capturing
+ * once was therefore INCOMPLETE. Live (`followsCurrentUser`) listeners
+ * re-capture their `auth` when the sandbox's `currentUser` changes (see
+ * {@link followsCurrentUser} + `LocalEnvironment.reevaluateLiveListeners`),
+ * matching that re-establishment. Frozen-ctx listeners
+ * (`followsCurrentUser === false`) stay pinned by design — that's the
+ * admin/testing use case where identity is chosen explicitly per handle.
+ */
+export type ListenerAuth = Operation['auth'];
+export interface ListenerRecord {
+    /** Stable id used to look up the record on unsubscribe. */
+    id: string;
+    target: SnapshotTarget;
+    callback: SnapshotCallback;
+    errorCallback?: SnapshotErrorCallback;
+    /** Captured at registration; see {@link ListenerAuth}. */
+    auth: ListenerAuth;
+    /**
+     * `true` when this listener was registered through a `sandbox-live`
+     * Firestore handle (`getFirestore(sandbox)`), whose identity follows
+     * `sandbox.currentUser`. Such listeners re-capture their `auth` and
+     * re-evaluate when `currentUser` changes — matching production, which
+     * re-establishes the listen stream on a session auth change (an
+     * auth-gated listener loses access on sign-out). `false` for
+     * frozen-ctx listeners (`getFirestore(ctx)`), which stay pinned to the
+     * identity chosen at handle-construction time (admin/testing path).
+     */
+    followsCurrentUser: boolean;
+    options: SnapshotListenerOptions;
+    /**
+     * Last snapshot delivered to the callback. Slice 2 populates this on
+     * the initial fire; Slice 3 uses {@link currentDocData} /
+     * {@link currentDocs} as the diff baseline (raw data is cheaper than
+     * unwrapping the snapshot accessor on every write).
+     */
+    currentSnapshot: unknown;
+    /**
+     * Diff baseline for `kind: 'doc'` listeners. `null` means the doc
+     * does not exist; `undefined` means no snapshot has fired yet.
+     * Slice 3 reads this to detect modified-vs-no-op fires.
+     */
+    currentDocData?: DocumentData | null;
+    /**
+     * Diff baseline for `kind: 'query'` listeners. The previous list of
+     * docs the listener saw, in the same order Slice 2's
+     * `silentReadCollection` returns them (path-ordered). Slice 3 passes
+     * this to `buildQuerySnapshot` so `oldIndex` and the `removed`
+     * change list are computed against the right baseline.
+     */
+    currentDocs?: {
+        path: string;
+        data: DocumentData;
+    }[];
+    /**
+     * Set when an error has been delivered. Per findings section 9 — once true,
+     * the dispatch loop must skip this record. Slice 7 wires the flip.
+     */
+    errored: boolean;
+}
+/**
+ * Mirrors `firebase/firestore`'s `SnapshotMetadata`. `fromCache` is always
+ * `false` (the sandbox has no offline cache). `hasPendingWrites` transitions
+ * (item 3): a local write's optimistic echo carries `true`, and the server
+ * ack carries `false` — so `includeMetadataChanges` has an observable effect
+ * matching prod (COMPAT firestore#85).
+ */
+export interface SnapshotMetadata {
+    readonly hasPendingWrites: boolean;
+    readonly fromCache: false;
+}
+/**
+ * Minimal `DocumentReference` shape exposed on snapshots — `id` and
+ * `path` are all the production type guarantees for read-side use. The
+ * Web SDK adapter (Slice 4) supplies a richer ref to its own callers;
+ * this interface is the contract this module promises.
+ */
+export interface SnapshotDocRef {
+    readonly id: string;
+    readonly path: string;
+}
+/**
+ * Minimal `Query` shape exposed on `QuerySnapshot.query` — production
+ * exposes the original `Query` object. For our purposes the listener's
+ * `SnapshotTarget` is enough handle for round-tripping.
+ */
+export interface SnapshotQueryRef {
+    readonly path: string;
+}
+export type DocumentChangeType = 'added' | 'modified' | 'removed';
+export interface DocumentSnapshot {
+    readonly id: string;
+    readonly ref: SnapshotDocRef;
+    readonly metadata: SnapshotMetadata;
+    exists(): boolean;
+    data(): DocumentData | undefined;
+    /**
+     * Field accessor mirroring `firebase/firestore`'s `DocumentSnapshot.get(fieldPath)`.
+     * Dotted paths supported. Missing intermediate keys yield `undefined`
+     * — production behavior; agents commonly chain optional reads.
+     */
+    get(fieldPath: string): unknown;
+}
+/**
+ * Production narrows `data()` to non-undefined here. We follow suit so
+ * that agent code calling `snap.data().foo` doesn't need a guard for
+ * the items inside a `QuerySnapshot.docs` array.
+ */
+export interface QueryDocumentSnapshot extends DocumentSnapshot {
+    data(): DocumentData;
+}
+export interface DocumentChange {
+    readonly type: DocumentChangeType;
+    readonly doc: QueryDocumentSnapshot;
+    /** -1 for `added`. */
+    readonly oldIndex: number;
+    /** -1 for `removed`. */
+    readonly newIndex: number;
+}
+/** Options for `QuerySnapshot.docChanges`. Mirrors Web SDK shape. */
+export interface DocChangesOptions {
+    includeMetadataChanges?: boolean;
+}
+export interface QuerySnapshot {
+    readonly query: SnapshotQueryRef;
+    readonly metadata: SnapshotMetadata;
+    readonly size: number;
+    readonly empty: boolean;
+    readonly docs: QueryDocumentSnapshot[];
+    forEach(callback: (snap: QueryDocumentSnapshot) => void): void;
+    /**
+     * Per findings section 4: cached by `includeMetadataChanges` value; throws if
+     * called with `true` when the listener did not subscribe with
+     * `includeMetadataChanges: true`. The Slice 2 implementation produces
+     * "all docs added" on the first fire — Slice 3 supplies real diffs.
+     */
+    docChanges(options?: DocChangesOptions): DocumentChange[];
+}
+/**
+ * Settled metadata — `hasPendingWrites: false`. Used for the initial fire,
+ * the server-ack fire (item 3), and every re-eval that reflects a durable
+ * server read (rules redeploy, live-listener auth change). Shared frozen
+ * instance to save allocations on the common settled path.
+ */
+export declare const SANDBOX_METADATA: SnapshotMetadata;
+/**
+ * Pending metadata — `hasPendingWrites: true`. Stamped on the local write
+ * echo (item 3): the optimistic fire a write produces before the (sandbox-
+ * synchronous) server ack. Mirrors prod, where a `setDoc` echoes locally
+ * with `hasPendingWrites: true`. COMPAT firestore#85.
+ */
+export declare const SANDBOX_METADATA_PENDING: SnapshotMetadata;
+/**
+ * Build a Web-SDK-shaped `DocumentSnapshot` for a single doc path.
+ * `data === null` indicates the doc does not exist (`exists() === false`,
+ * `data() === undefined`).
+ */
+export declare function buildDocumentSnapshot(path: string, data: DocumentData | null, metadata?: SnapshotMetadata): DocumentSnapshot;
+/**
+ * Build a Web-SDK-shaped `QuerySnapshot`.
+ *
+ * `docList` carries the docs in their query-order (the caller is
+ * responsible for ordering — for Slice 2 the order is whatever
+ * `LocalState.list` returns, which is a path-ordered scan).
+ *
+ * `prevDocs` is the previous snapshot's docs, used to compute
+ * `oldIndex`. Pass `undefined` for an initial snapshot — every doc
+ * surfaces as `added` with `oldIndex === -1`. Slice 3 will pass the
+ * previous list to compute `modified` / `removed` entries.
+ *
+ * The returned `docChanges()` is cached by `includeMetadataChanges`
+ * and throws on flag-mismatch when the listener didn't subscribe with
+ * the option (per findings section 4) — that throw is wired by passing
+ * `excludesMetadataChanges: !options.includeMetadataChanges` from the
+ * listener record, which Slice 3 hooks into the dispatch path.
+ */
+export declare function buildQuerySnapshot(query: SnapshotQueryRef, docList: {
+    path: string;
+    data: DocumentData;
+}[], options: {
+    excludesMetadataChanges: boolean;
+}, prevDocs?: {
+    path: string;
+    data: DocumentData;
+}[], metadata?: SnapshotMetadata): QuerySnapshot;
+//# sourceMappingURL=snapshot-listeners.d.ts.map

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

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

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

@@ -0,0 +1,194 @@
+// FS-B10 — translate the listener read path so `snap.data()` exposes the
+// SAME compat-shaped values (`Timestamp` `{seconds, nanoseconds}`, `Bytes`,
+// `GeoPoint`) a one-shot `getDoc`/`getDocs` returns. Without this the
+// listener leaked the rules-internal `Timestamp` (`{seconds, nanos}`, with a
+// `typeName` field and no `nanoseconds`). `read-translation.ts` carries no
+// admin-compat-surface dependency, so importing it here is cycle-free.
+import { translateReadData } from './admin-compat/read-translation.js';
+// ─── Snapshot constants ──────────────────────────────────────────────
+/**
+ * Settled metadata — `hasPendingWrites: false`. Used for the initial fire,
+ * the server-ack fire (item 3), and every re-eval that reflects a durable
+ * server read (rules redeploy, live-listener auth change). Shared frozen
+ * instance to save allocations on the common settled path.
+ */
+export const SANDBOX_METADATA = Object.freeze({
+    hasPendingWrites: false,
+    fromCache: false,
+});
+/**
+ * Pending metadata — `hasPendingWrites: true`. Stamped on the local write
+ * echo (item 3): the optimistic fire a write produces before the (sandbox-
+ * synchronous) server ack. Mirrors prod, where a `setDoc` echoes locally
+ * with `hasPendingWrites: true`. COMPAT firestore#85.
+ */
+export const SANDBOX_METADATA_PENDING = Object.freeze({
+    hasPendingWrites: true,
+    fromCache: false,
+});
+// ─── Snapshot construction helpers ───────────────────────────────────
+/**
+ * Walk a dotted path against a data tree. Returns `undefined` on any
+ * missing intermediate or non-object node — matching production's
+ * forgiving accessor (Web SDK `DocumentSnapshot.get`).
+ */
+function getByPath(data, fieldPath) {
+    if (data === undefined)
+        return undefined;
+    const parts = fieldPath.split('.');
+    let cur = data;
+    for (const p of parts) {
+        if (cur === null || cur === undefined || typeof cur !== 'object')
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+function lastSegment(path) {
+    const i = path.lastIndexOf('/');
+    return i === -1 ? path : path.slice(i + 1);
+}
+/**
+ * Build a Web-SDK-shaped `DocumentSnapshot` for a single doc path.
+ * `data === null` indicates the doc does not exist (`exists() === false`,
+ * `data() === undefined`).
+ */
+export function buildDocumentSnapshot(path, data, metadata = SANDBOX_METADATA) {
+    const ref = { id: lastSegment(path), path };
+    const exists = data !== null;
+    // FS-B10 — translate to the same compat shape `getDoc` returns, so a
+    // listener's `snap.data().createdAt` is a `{seconds, nanoseconds}`
+    // Timestamp, not the rules-internal `{seconds, nanos}` wrapper.
+    const translated = exists ? translateReadData(data) : undefined;
+    return {
+        id: ref.id,
+        ref,
+        metadata,
+        exists: () => exists,
+        data: () => translated,
+        get: (fieldPath) => getByPath(translated, fieldPath),
+    };
+}
+function buildQueryDocumentSnapshot(path, data, metadata = SANDBOX_METADATA) {
+    const ref = { id: lastSegment(path), path };
+    // FS-B10 — same read-path translation as the single-doc + getDocs paths.
+    const translated = translateReadData(data);
+    return {
+        id: ref.id,
+        ref,
+        metadata,
+        exists: () => true,
+        data: () => translated,
+        get: (fieldPath) => getByPath(translated, fieldPath),
+    };
+}
+/**
+ * Build a Web-SDK-shaped `QuerySnapshot`.
+ *
+ * `docList` carries the docs in their query-order (the caller is
+ * responsible for ordering — for Slice 2 the order is whatever
+ * `LocalState.list` returns, which is a path-ordered scan).
+ *
+ * `prevDocs` is the previous snapshot's docs, used to compute
+ * `oldIndex`. Pass `undefined` for an initial snapshot — every doc
+ * surfaces as `added` with `oldIndex === -1`. Slice 3 will pass the
+ * previous list to compute `modified` / `removed` entries.
+ *
+ * The returned `docChanges()` is cached by `includeMetadataChanges`
+ * and throws on flag-mismatch when the listener didn't subscribe with
+ * the option (per findings section 4) — that throw is wired by passing
+ * `excludesMetadataChanges: !options.includeMetadataChanges` from the
+ * listener record, which Slice 3 hooks into the dispatch path.
+ */
+export function buildQuerySnapshot(query, docList, options, prevDocs, metadata = SANDBOX_METADATA) {
+    const docs = docList.map((d) => buildQueryDocumentSnapshot(d.path, d.data, metadata));
+    // Pre-compute the no-metadata-change view (Slice 2 semantics):
+    // initial fire → every current doc is `added`. Slice 3 will replace
+    // this with proper diffing against `prevDocs`.
+    const baseChanges = prevDocs
+        ? computeChanges(prevDocs, docList, docs, metadata)
+        : docs.map((doc, newIndex) => ({ type: 'added', doc, oldIndex: -1, newIndex }));
+    let cachedNoMetaChanges = null;
+    let cachedWithMetaChanges = null;
+    return {
+        query,
+        metadata,
+        size: docs.length,
+        empty: docs.length === 0,
+        docs,
+        forEach(cb) {
+            for (const d of docs)
+                cb(d);
+        },
+        docChanges(opts) {
+            const wantMeta = !!opts?.includeMetadataChanges;
+            if (wantMeta && options.excludesMetadataChanges) {
+                // Production throws `FirestoreError(invalid-argument)` here. We
+                // throw a plain Error in the simulator core; the Web SDK adapter
+                // (Slice 4) re-tags this into a `FirestoreError` shape so agent
+                // code can pattern-match on `.code`.
+                throw new Error('To include metadata changes with your document changes, you must also pass ' +
+                    '{ includeMetadataChanges: true } to onSnapshot().');
+            }
+            // Sandbox metadata never transitions (findings section 6) so the two
+            // cached arrays are identical in practice — keeping the cache key
+            // separate matches production's contract verbatim and lets us add
+            // distinct semantics later without breaking call sites.
+            if (wantMeta) {
+                if (!cachedWithMetaChanges)
+                    cachedWithMetaChanges = baseChanges.slice();
+                return cachedWithMetaChanges;
+            }
+            if (!cachedNoMetaChanges)
+                cachedNoMetaChanges = baseChanges.slice();
+            return cachedNoMetaChanges;
+        },
+    };
+}
+/**
+ * Diff `prev` against `curr` to produce `DocumentChange[]`. Slice 3
+ * uses this from the notification path; Slice 2 only invokes it when
+ * `prevDocs` is supplied (i.e. never on the initial fire).
+ *
+ * `oldIndex`/`newIndex` follow production's contract (-1 for added /
+ * removed). Comparison uses path identity for membership and a shallow
+ * `JSON.stringify` for "modified" detection — good enough for the
+ * sandbox's data shapes (all `DocumentData` values are JSON-serialisable
+ * after sentinel resolution). A deep-equal helper can land in Slice 3
+ * if a probe surfaces a divergence.
+ */
+function computeChanges(prev, curr, currSnaps, metadata = SANDBOX_METADATA) {
+    const prevIndex = new Map();
+    prev.forEach((d, i) => prevIndex.set(d.path, i));
+    const currIndex = new Map();
+    curr.forEach((d, i) => currIndex.set(d.path, i));
+    const out = [];
+    // Removed (in prev, not in curr) — keep `oldIndex` from prev.
+    for (let i = 0; i < prev.length; i++) {
+        const p = prev[i];
+        if (!currIndex.has(p.path)) {
+            out.push({
+                type: 'removed',
+                doc: buildQueryDocumentSnapshot(p.path, p.data, metadata),
+                oldIndex: i,
+                newIndex: -1,
+            });
+        }
+    }
+    // Added or modified (every curr entry).
+    for (let i = 0; i < curr.length; i++) {
+        const c = curr[i];
+        const oldI = prevIndex.get(c.path);
+        if (oldI === undefined) {
+            out.push({ type: 'added', doc: currSnaps[i], oldIndex: -1, newIndex: i });
+        }
+        else {
+            const prevData = prev[oldI].data;
+            if (JSON.stringify(prevData) !== JSON.stringify(c.data)) {
+                out.push({ type: 'modified', doc: currSnaps[i], oldIndex: oldI, newIndex: i });
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=snapshot-listeners.js.map

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

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

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

@@ -0,0 +1,12 @@
+/**
+ * topK: the k smallest items by `cmp`, in ascending order, WITHOUT sorting the
+ * whole input. Equivalent to `[...items].sort(cmp).slice(0, k)` when `cmp` is a
+ * total order (no ties), which the query engine guarantees since its
+ * normalized orderBy ends with the unique `__name__` key. Used by `limit`
+ * queries (no full sort) and, later, by `findNearest`'s vector top-k.
+ *
+ * Maintains a bounded ascending buffer of size <= k via binary insertion: O(n
+ * log k) comparisons and O(k) extra space, vs the full sort's O(n log n) + O(n).
+ */
+export declare function topK<T>(items: Iterable<T>, k: number, cmp: (a: T, b: T) => number): T[];
+//# sourceMappingURL=topk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"topk.d.ts","sourceRoot":"","sources":["../../../src/sandbox/firestore/topk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,CAAC,EAAE,CAcvF"}

package/dist/sandbox/firestore/topk.js

@@ -0,0 +1,42 @@
+/**
+ * topK: the k smallest items by `cmp`, in ascending order, WITHOUT sorting the
+ * whole input. Equivalent to `[...items].sort(cmp).slice(0, k)` when `cmp` is a
+ * total order (no ties), which the query engine guarantees since its
+ * normalized orderBy ends with the unique `__name__` key. Used by `limit`
+ * queries (no full sort) and, later, by `findNearest`'s vector top-k.
+ *
+ * Maintains a bounded ascending buffer of size <= k via binary insertion: O(n
+ * log k) comparisons and O(k) extra space, vs the full sort's O(n log n) + O(n).
+ */
+export function topK(items, k, cmp) {
+    if (k <= 0)
+        return [];
+    const top = [];
+    for (const item of items) {
+        if (top.length < k) {
+            insertSorted(top, item, cmp);
+        }
+        else if (cmp(item, top[top.length - 1]) < 0) {
+            // `item` ranks ahead of the current k-th: evict the largest, insert this.
+            top.pop();
+            insertSorted(top, item, cmp);
+        }
+        // else: item is no smaller than the k-th best, so it cannot make the cut.
+    }
+    return top;
+}
+/** Insert `item` into the ascending array `arr` at its sorted position. Ties
+ *  (cmp === 0) land AFTER equal elements, preserving input order among equals. */
+function insertSorted(arr, item, cmp) {
+    let lo = 0;
+    let hi = arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (cmp(item, arr[mid]) < 0)
+            hi = mid;
+        else
+            lo = mid + 1;
+    }
+    arr.splice(lo, 0, item);
+}
+//# sourceMappingURL=topk.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"topk.js","sourceRoot":"","sources":["../../../src/sandbox/firestore/topk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,IAAI,CAAI,KAAkB,EAAE,CAAS,EAAE,GAA2B;IAChF,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnB,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,0EAA0E;YAC1E,GAAG,CAAC,GAAG,EAAE,CAAC;YACV,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,CAAC;QACD,0EAA0E;IAC5E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;kFACkF;AAClF,SAAS,YAAY,CAAI,GAAQ,EAAE,IAAO,EAAE,GAA2B;IACrE,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;IACpB,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAE,CAAC,GAAG,CAAC;YAAE,EAAE,GAAG,GAAG,CAAC;;YAClC,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;IACpB,CAAC;IACD,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;AAC1B,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * Item 1.3 — Same-path queued-write collapse.
+ *
+ * `TransactionContext` queues writes append-only (Item 1.2). Before
+ * commit, ops at the same path collapse into a single operation so the
+ * existing `LocalState.applyBatch` can run rules-eval + apply atomically
+ * without per-call divergence.
+ *
+ * Probe 0.D verified `update + update` merges fields (last-wins per
+ * field, earlier-but-non-overlapping fields preserved). The other
+ * combinations are extrapolated from Admin SDK semantics:
+ *
+ *   set    + set        → second `set` wins (overwrite semantics).
+ *   set    + update     → `set` with `{ ...set.data, ...update.data }`.
+ *   set    + delete     → `delete` wins (the set never observable).
+ *   create + update     → `create` with `{ ...create.data, ...update.data }`.
+ *   create + set        → `set` wins (set overwrites, semantically a
+ *                         fresh create-or-replace).
+ *   create + delete     → `delete` wins (final state is gone).
+ *   update + update     → ✅ probed: merged data.
+ *   update + set        → `set` wins (set replaces entirely).
+ *   update + delete     → `delete` wins.
+ *   delete + ANYTHING   → THROW. Probe didn't cover; safer to error
+ *                         than guess. Decisions Log: "delete + write
+ *                         merge unprobed; v1 throws ambiguous".
+ *
+ * Output is `LocalState.BatchOperation[]` directly — that's what the
+ * commit path (Item 2) feeds into `applyBatch`. Same-path entries
+ * collapse into one entry; different paths preserve order of first
+ * appearance (insertion order in the path map).
+ */
+import type { BatchOperation } from './local-state.js';
+import type { QueuedWrite } from './transaction-types.js';
+/**
+ * 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 declare class AmbiguousPostDeleteWriteError extends Error {
+    readonly path: string;
+    readonly secondMethod: string;
+    constructor(path: string, secondMethod: string);
+}
+/**
+ * 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 declare function mergeQueuedWrites(writes: readonly QueuedWrite[]): BatchOperation[];
+//# sourceMappingURL=transaction-merge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-merge.d.ts","sourceRoot":"","sources":["../../../src/sandbox/firestore/transaction-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;;;;GAMG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAClB,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAW/C;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,cAAc,EAAE,CAoBlF"}