pyric 0.0.1 → 0.1.0-alpha.8

package/dist/sandbox/firestore/local-state.js

@@ -0,0 +1,413 @@
+/**
+ * LocalState — in-memory Firestore document store.
+ *
+ * Manages a Map<string, Record<string, unknown>> with correct Firestore
+ * semantics for create, update (merge), delete, and set (overwrite).
+ *
+ * This is the "database" for the local environment. The simulator
+ * evaluates rules; this class manages the data those rules protect.
+ *
+ * Write-boundary resolver:
+ *   Every mutation (`create`, `update`, `set`, `applyBatch`, and the
+ *   constructor seed pass) routes through {@link resolveValueTree}
+ *   before the value lands in storage. The resolver is the single
+ *   chokepoint where Date → Timestamp coercion, FieldValue sentinel
+ *   resolution, DocumentReference wrapping, etc. happen (see
+ *   value-resolver.ts). Today the registry is empty (Item 0); Items 1+
+ *   plug in converters without touching this file.
+ *
+ *   Idempotency: callers higher up the stack (e.g.,
+ *   `LocalEnvironment.execute`) may resolve before us so rules see the
+ *   same shape storage will see. Double-resolution is intentional and
+ *   safe — every converter is required to no-op on its own output.
+ */
+import { resolveValueTree, partitionDeletes } from './value-resolver.js';
+import { applyUpdate, applyMerge } from './field-merge.js';
+/** Pick only `fields` from `data` (a shallow top-level projection). */
+function projectFields(data, fields) {
+    const out = {};
+    for (const f of fields) {
+        if (Object.prototype.hasOwnProperty.call(data, f))
+            out[f] = data[f];
+    }
+    return out;
+}
+export class LocalState {
+    documents;
+    constructor(seed = {}, backing) {
+        this.documents = backing ?? new Map();
+        for (const [path, data] of Object.entries(seed)) {
+            // Seed pass: no prior state, method='seed' so converters can branch.
+            const resolved = resolveValueTree({ ...data }, {
+                path,
+                method: 'seed',
+                prior: null,
+            });
+            // Item 2: drop any DELETE_FIELD sentinels in the seed (a rare but
+            // legal shape if the agent reuses payload objects). No prior to
+            // delete from on a seed; we just strip the markers.
+            const { writes } = partitionDeletes(resolved);
+            this.documents.set(path, writes);
+        }
+    }
+    // ═══ Read operations ═══
+    /** Get a single document. Returns null if not found. */
+    get(path) {
+        return this.documents.get(path) ?? null;
+    }
+    /** Check if a document exists. */
+    exists(path) {
+        return this.documents.has(path);
+    }
+    /**
+     * Scan the keyspace under `prefix`: the single iteration primitive `list`
+     * (and, later, the query engine) build on. With `directOnly`, returns only
+     * direct children of `prefix` (a collection scan); otherwise every descendant.
+     * With `phantoms`, synthesizes empty parent entries for paths whose parent has
+     * descendants but no stored doc of its own (mirrors live Firestore's
+     * `listDocuments`). An empty `prefix` scans the whole keyspace. Real stored
+     * docs come in keyspace (insertion) order; phantoms are appended after, so a
+     * real doc always wins over its phantom synthesis.
+     */
+    scan(prefix, opts = {}) {
+        const norm = prefix === '' || prefix.endsWith('/') ? prefix : prefix + '/';
+        const project = opts.projection
+            ? (d) => projectFields(d, opts.projection)
+            : (d) => d;
+        const results = [];
+        const seenIds = new Set();
+        const phantomIds = [];
+        for (const [path, data] of this.documents) {
+            if (norm !== '' && !path.startsWith(norm))
+                continue;
+            if (!opts.directOnly) {
+                results.push({ path, data: project(data) });
+                continue;
+            }
+            const remainder = path.slice(norm.length);
+            const slashIdx = remainder.indexOf('/');
+            if (slashIdx === -1) {
+                // Direct child — real stored doc.
+                results.push({ path, data: project(data) });
+                seenIds.add(remainder);
+            }
+            else if (opts.phantoms) {
+                // Deeper descendant — its top segment is a parent id under our
+                // collection. Record once; synthesize after the scan so real
+                // stored docs win over the phantom synthesis.
+                const parentId = remainder.slice(0, slashIdx);
+                if (parentId.length > 0 && !phantomIds.includes(parentId)) {
+                    phantomIds.push(parentId);
+                }
+            }
+        }
+        if (opts.directOnly && opts.phantoms) {
+            for (const id of phantomIds) {
+                if (seenIds.has(id))
+                    continue;
+                results.push({ path: norm + id, data: {}, phantom: true });
+            }
+        }
+        return results;
+    }
+    /**
+     * List all documents in a collection: real stored direct children plus
+     * phantom parents (synthesized empty docs for any parent with descendants).
+     * Mirrors live Firestore's `listDocuments`; `getDocument(path)` still returns
+     * `null` for a phantom; phantoms only surface via list traversal. This is
+     * `scan(collection, { directOnly, phantoms })`.
+     */
+    list(collection) {
+        return this.scan(collection, { directOnly: true, phantoms: true });
+    }
+    /**
+     * List all root collection IDs derived from the document keyspace.
+     * For seeded paths `users/u1`, `users/u1/posts/p1`, `articles/a1`, returns
+     * `['users', 'articles']` (deduped, insertion order).
+     *
+     * Note: a collection is "visible" if any document path lives under it.
+     * Phantom parents (e.g., a path `users/u1/posts/p1` with no `users/u1`
+     * stored doc) still surface their root collection here, mirroring how
+     * real Firestore exposes a collection whenever any descendant exists.
+     */
+    listRootCollections() {
+        const seen = new Set();
+        const out = [];
+        for (const path of this.documents.keys()) {
+            const first = path.split('/', 1)[0];
+            if (first.length === 0)
+                continue;
+            if (!seen.has(first)) {
+                seen.add(first);
+                out.push(first);
+            }
+        }
+        return out;
+    }
+    /**
+     * List subcollection IDs directly underneath the given document path.
+     * For docPath `users/u1` and stored paths `users/u1/posts/p1`,
+     * `users/u1/posts/p2`, `users/u1/sessions/s1`, returns `['posts', 'sessions']`.
+     *
+     * Like {@link listRootCollections}, a subcollection is visible whenever
+     * any descendant path exists — it does NOT require the parent doc to
+     * have stored data.
+     */
+    listSubcollections(docPath) {
+        const prefix = docPath.endsWith('/') ? docPath : docPath + '/';
+        const seen = new Set();
+        const out = [];
+        for (const path of this.documents.keys()) {
+            if (!path.startsWith(prefix))
+                continue;
+            const remainder = path.slice(prefix.length);
+            const next = remainder.split('/', 1)[0];
+            if (next.length === 0)
+                continue;
+            if (!seen.has(next)) {
+                seen.add(next);
+                out.push(next);
+            }
+        }
+        return out;
+    }
+    /** Get all documents as a plain object. */
+    snapshot() {
+        const snap = {};
+        for (const [path, data] of this.documents) {
+            snap[path] = { ...data };
+        }
+        return snap;
+    }
+    /** Total document count. */
+    size() {
+        return this.documents.size;
+    }
+    // ═══ Write operations ═══
+    /**
+     * Create a document. Fails if the document already exists.
+     * Sets the full document data (no merge).
+     */
+    create(path, data) {
+        if (this.documents.has(path)) {
+            return { success: false, error: `Document '${path}' already exists` };
+        }
+        let writes;
+        try {
+            const resolved = resolveValueTree({ ...data }, {
+                path,
+                method: 'create',
+                prior: null,
+            });
+            // Item 2: create has no prior, so deletedKeys are no-ops; we just
+            // strip the markers so they don't land in storage.
+            writes = partitionDeletes(resolved).writes;
+        }
+        catch (e) {
+            return { success: false, error: e.message };
+        }
+        this.documents.set(path, writes);
+        return { success: true };
+    }
+    /**
+     * Update a document. Fails if the document doesn't exist.
+     * MERGES fields — does not replace the entire document.
+     * Firestore update() semantics: existing fields not in the update are preserved.
+     */
+    update(path, data) {
+        const existing = this.documents.get(path);
+        if (!existing) {
+            return { success: false, error: `Document '${path}' does not exist` };
+        }
+        let merged;
+        try {
+            const resolved = resolveValueTree({ ...data }, {
+                path,
+                method: 'update',
+                prior: existing,
+            });
+            // FS-B5: top-level `updateDoc` keys are dot-separated FieldPaths.
+            // `applyUpdate` expands `{'a.b': v}` into a nested set (preserving
+            // `a.c`), replaces a whole map for a single-segment key, and removes
+            // DELETE_FIELD-marked leaves — matching prod's PatchMutation.
+            merged = applyUpdate(existing, resolved);
+        }
+        catch (e) {
+            return { success: false, error: e.message };
+        }
+        this.documents.set(path, merged);
+        return { success: true, priorData: { ...existing } };
+    }
+    /**
+     * Merge-set a document — `setDoc(data, {merge:true})` /
+     * `{mergeFields}`. Deep-merges nested maps into the existing doc
+     * (FS-B6): `setDoc({a:{b:2}}, {merge:true})` over `{a:{c:1}}` yields
+     * `{a:{b:2,c:1}}`. Creates the doc if absent. `mergeFields` restricts
+     * the write to the listed (dot-separated) field paths.
+     */
+    setMerge(path, data, mergeFields) {
+        const priorData = this.documents.has(path)
+            ? { ...this.documents.get(path) }
+            : null;
+        const resolved = resolveValueTree({ ...data }, {
+            path,
+            method: 'set',
+            prior: priorData,
+        });
+        const merged = applyMerge(priorData ?? {}, resolved, mergeFields);
+        this.documents.set(path, merged);
+        return { success: true, priorData, created: priorData === null };
+    }
+    /**
+     * Set a document. Creates or overwrites — always succeeds.
+     * Replaces the entire document (no merge).
+     */
+    set(path, data) {
+        const priorData = this.documents.has(path)
+            ? { ...this.documents.get(path) }
+            : null;
+        const resolved = resolveValueTree({ ...data }, {
+            path,
+            method: 'set',
+            prior: priorData,
+        });
+        // Item 2: set replaces the doc entirely, so deletedKeys have no
+        // existing field to remove — but we still strip the markers so
+        // they don't reach storage. Real Firestore rejects deleteField()
+        // inside a non-merge set; we accept-and-strip for now since merge
+        // mode isn't yet plumbed into the simulator's set path.
+        const { writes } = partitionDeletes(resolved);
+        this.documents.set(path, writes);
+        return { success: true, priorData, created: priorData === null };
+    }
+    /**
+     * Delete a document. Fails if the document doesn't exist.
+     * Returns the deleted data (for undo).
+     */
+    delete(path) {
+        const existing = this.documents.get(path);
+        if (!existing) {
+            return { success: false, error: `Document '${path}' does not exist` };
+        }
+        this.documents.delete(path);
+        return { success: true, priorData: { ...existing } };
+    }
+    // ═══ Batch operations ═══
+    /**
+     * Apply multiple writes atomically.
+     * Evaluates all operations against CURRENT state (no cross-visibility).
+     * If all succeed, applies all. If any fails, none apply.
+     *
+     * Note: This handles the DATA side only. Rules evaluation is the caller's
+     * responsibility (LocalEnvironment evaluates rules, then calls batch).
+     */
+    applyBatch(operations) {
+        // Validate all operations against current state first
+        const errors = [];
+        for (let i = 0; i < operations.length; i++) {
+            const op = operations[i];
+            switch (op.method) {
+                case 'create':
+                    if (this.documents.has(op.path)) {
+                        errors.push({ index: i, error: `Document '${op.path}' already exists` });
+                    }
+                    break;
+                case 'update':
+                    if (!this.documents.has(op.path)) {
+                        errors.push({ index: i, error: `Document '${op.path}' does not exist` });
+                    }
+                    break;
+                case 'delete':
+                    // Delete-missing is a no-op in production: `WriteBatch.delete`
+                    // and `Transaction.delete` on an absent doc resolve cleanly,
+                    // matching the single-op `deleteDoc` contract (matrix row
+                    // Firestore #39, oracle:
+                    // scripts/oracle/observations/firestore-deletedoc-missing.json).
+                    // Apply phase below tolerates the absence via `documents.delete`,
+                    // which is itself a no-op on a missing key.
+                    break;
+                // 'set' always succeeds
+            }
+        }
+        if (errors.length > 0) {
+            return { success: false, errors };
+        }
+        // Capture prior state for all affected documents (for undo)
+        const priorStates = new Map();
+        for (const op of operations) {
+            if (!priorStates.has(op.path)) {
+                priorStates.set(op.path, this.documents.has(op.path) ? { ...this.documents.get(op.path) } : null);
+            }
+        }
+        // Apply all operations. Each non-delete write routes through the
+        // resolver with the correct prior — captured above, so resolution
+        // order within the batch sees the same prior the rules saw. Item 2:
+        // every non-delete branch partitions DELETE_FIELD markers out via
+        // partitionDeletes so they don't leak into storage.
+        for (const op of operations) {
+            switch (op.method) {
+                case 'create': {
+                    const resolved = resolveValueTree({ ...op.data }, {
+                        path: op.path,
+                        method: 'create',
+                        prior: null,
+                    });
+                    const { writes } = partitionDeletes(resolved);
+                    this.documents.set(op.path, writes);
+                    break;
+                }
+                case 'update': {
+                    const existing = this.documents.get(op.path);
+                    const resolved = resolveValueTree({ ...op.data }, {
+                        path: op.path,
+                        method: 'update',
+                        prior: existing,
+                    });
+                    // FS-B5: dot-path FieldPath expansion + sibling-preserving merge.
+                    this.documents.set(op.path, applyUpdate(existing, resolved));
+                    break;
+                }
+                case 'set': {
+                    const priorForSet = priorStates.get(op.path) ?? null;
+                    const resolved = resolveValueTree({ ...op.data }, {
+                        path: op.path,
+                        method: 'set',
+                        prior: priorForSet,
+                    });
+                    const { writes } = partitionDeletes(resolved);
+                    this.documents.set(op.path, writes);
+                    break;
+                }
+                case 'delete':
+                    this.documents.delete(op.path);
+                    break;
+            }
+        }
+        return { success: true, priorStates };
+    }
+    /**
+     * Restore state from a WHOLE-keyspace snapshot (reset to seed, transaction
+     * undo). Replaces the entire keyspace.
+     */
+    restore(snapshot) {
+        this.documents.clear();
+        for (const [path, data] of Object.entries(snapshot)) {
+            this.documents.set(path, { ...data });
+        }
+    }
+    /**
+     * Restore only the given paths to their prior state (for single-write / batch
+     * undo). `null` means the doc did not exist before, so undo deletes it; any
+     * other path in the keyspace is left untouched. This is the affected-path
+     * counterpart to {@link restore} that keeps undo O(affected), not O(keyspace).
+     */
+    restorePaths(priorDocs) {
+        for (const [path, data] of Object.entries(priorDocs)) {
+            if (data === null)
+                this.documents.delete(path);
+            else
+                this.documents.set(path, { ...data });
+        }
+    }
+}
+//# sourceMappingURL=local-state.js.map

package/dist/sandbox/firestore/local-state.js.map

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

package/dist/sandbox/firestore/overlay-backing.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OverlayBacking: copy-on-write storage over an immutable base, the engine
+ * behind CoW branches. Reads fall through to `base` unless shadowed by the
+ * overlay or hidden by a tombstone; writes land in the overlay; deletes
+ * tombstone a base path (or just drop an overlay-only doc). A fork is O(1) (an
+ * empty overlay over the shared base) instead of O(keyspace) (structuredClone).
+ *
+ * Isolation: the base (a `snapshot()` result) is only SHALLOW-cloned by
+ * snapshot(), so its nested objects are still shared with the live source and
+ * any sibling branch. Handing a base doc out by reference would let a caller
+ * mutate it in place and corrupt those. So base docs are deep-cloned on first
+ * read (memoized in `baseCache`, so repeated reads/scans don't re-clone), which
+ * restores the old clone-fork's full decoupling while keeping fork() O(1) and
+ * cloning only the docs a branch actually touches. The cache is NOT the overlay:
+ * a cached base read is not a write, so `diff` stays overlay-only.
+ *
+ * Iteration preserves base order: an updated base doc is emitted in its original
+ * position (overlay value), overlay-only docs are appended, and a base doc that
+ * was deleted then re-created stays in its original base position (which tracks
+ * prod's __name__ key order more closely than a Map clone's move-to-end would).
+ */
+import type { DocBacking, DocumentData } from './local-state.js';
+export declare class OverlayBacking implements DocBacking {
+    private readonly base;
+    private readonly overlay;
+    private readonly tombstones;
+    /** Deep-clone-on-first-read of base docs (see class doc). */
+    private readonly baseCache;
+    /** Set by clear(): the base is logically dropped, only the overlay counts. */
+    private cleared;
+    constructor(base: Record<string, DocumentData>);
+    private inBase;
+    /** A decoupled view of a base doc: deep clone, memoized. */
+    private baseDoc;
+    get(path: string): DocumentData | undefined;
+    set(path: string, data: DocumentData): void;
+    has(path: string): boolean;
+    delete(path: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    [Symbol.iterator](): IterableIterator<[string, DocumentData]>;
+}
+//# sourceMappingURL=overlay-backing.d.ts.map

package/dist/sandbox/firestore/overlay-backing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-backing.d.ts","sourceRoot":"","sources":["../../../src/sandbox/firestore/overlay-backing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEjE,qBAAa,cAAe,YAAW,UAAU;IAQnC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,8EAA8E;IAC9E,OAAO,CAAC,OAAO,CAAS;gBAEK,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAE/D,OAAO,CAAC,MAAM;IAId,4DAA4D;IAC5D,OAAO,CAAC,OAAO;IASf,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAM3C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAK3C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAM1B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAO7B,KAAK,IAAI,IAAI;IAOb,IAAI,IAAI,IAAI,MAAM,CAIjB;IAEA,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAIhC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAc/D"}

package/dist/sandbox/firestore/overlay-backing.js

@@ -0,0 +1,82 @@
+export class OverlayBacking {
+    base;
+    overlay = new Map();
+    tombstones = new Set();
+    /** Deep-clone-on-first-read of base docs (see class doc). */
+    baseCache = new Map();
+    /** Set by clear(): the base is logically dropped, only the overlay counts. */
+    cleared = false;
+    constructor(base) {
+        this.base = base;
+    }
+    inBase(path) {
+        return Object.prototype.hasOwnProperty.call(this.base, path);
+    }
+    /** A decoupled view of a base doc: deep clone, memoized. */
+    baseDoc(path) {
+        let cached = this.baseCache.get(path);
+        if (cached === undefined) {
+            cached = structuredClone(this.base[path]);
+            this.baseCache.set(path, cached);
+        }
+        return cached;
+    }
+    get(path) {
+        if (this.overlay.has(path))
+            return this.overlay.get(path);
+        if (this.cleared || this.tombstones.has(path))
+            return undefined;
+        return this.inBase(path) ? this.baseDoc(path) : undefined;
+    }
+    set(path, data) {
+        this.overlay.set(path, data);
+        this.tombstones.delete(path);
+    }
+    has(path) {
+        if (this.overlay.has(path))
+            return true;
+        if (this.cleared || this.tombstones.has(path))
+            return false;
+        return this.inBase(path);
+    }
+    delete(path) {
+        const existed = this.has(path);
+        this.overlay.delete(path);
+        if (!this.cleared && this.inBase(path))
+            this.tombstones.add(path);
+        return existed;
+    }
+    clear() {
+        this.overlay.clear();
+        this.tombstones.clear();
+        this.baseCache.clear();
+        this.cleared = true;
+    }
+    get size() {
+        let n = 0;
+        for (const _ of this)
+            void _, n++;
+        return n;
+    }
+    *keys() {
+        for (const [path] of this)
+            yield path;
+    }
+    *[Symbol.iterator]() {
+        const emitted = new Set();
+        if (!this.cleared) {
+            for (const path of Object.keys(this.base)) {
+                if (this.tombstones.has(path))
+                    continue;
+                emitted.add(path);
+                yield [path, this.overlay.has(path) ? this.overlay.get(path) : this.baseDoc(path)];
+            }
+        }
+        for (const [path, data] of this.overlay) {
+            if (emitted.has(path))
+                continue;
+            yield [path, data];
+        }
+    }
+}
+//# sourceMappingURL=overlay-backing.js.map

package/dist/sandbox/firestore/overlay-backing.js.map

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

package/dist/sandbox/firestore/sentinel-capture.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Walk a pre-resolution write payload and extract every sentinel hit
+ * keyed by its field path.
+ *
+ * Used by `LocalEnvironment.emitWrite` to populate
+ * `WriteSandboxEvent.sentinels` so the replay engine can re-issue the
+ * same sentinels at replay time (without consulting resolved values
+ * which would have drifted).
+ *
+ * Detection: every Firestore sentinel converter in
+ * `converters/{fieldvalue,timestamp}.ts` marks its payload with a
+ * `__type: '<name>'` discriminator. The walk matches that.
+ *
+ * Field-path syntax (locked in the decision doc, R1):
+ *   - object keys join with '.'
+ *   - in-array positions append '[<index>]'
+ *   - e.g., `tags[0]`, `profile.lastSeen`, `history[0].at`
+ *
+ * Short-circuit: when a sentinel is detected the walk does NOT recurse
+ * into its internals (e.g. `arrayUnion.values` may contain plain values
+ * that aren't replay-relevant). This is also what makes the walk cheap
+ * — probe R2 measured p99 ≤ 0.009ms across 0/1/16 sentinels per doc.
+ */
+export interface SentinelHit {
+    /** Dotted path with bracket-array-indices. */
+    field: string;
+    kind: 'serverTimestamp' | 'increment' | 'arrayUnion' | 'arrayRemove' | 'delete';
+}
+export declare function walkForSentinels(value: unknown, prefix?: string): SentinelHit[];
+//# sourceMappingURL=sentinel-capture.d.ts.map

package/dist/sandbox/firestore/sentinel-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel-capture.d.ts","sourceRoot":"","sources":["../../../src/sandbox/firestore/sentinel-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,iBAAiB,GAAG,WAAW,GAAG,YAAY,GAAG,aAAa,GAAG,QAAQ,CAAC;CACjF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,WAAW,EAAE,CAsB3E"}

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

@@ -0,0 +1,61 @@
+/**
+ * Walk a pre-resolution write payload and extract every sentinel hit
+ * keyed by its field path.
+ *
+ * Used by `LocalEnvironment.emitWrite` to populate
+ * `WriteSandboxEvent.sentinels` so the replay engine can re-issue the
+ * same sentinels at replay time (without consulting resolved values
+ * which would have drifted).
+ *
+ * Detection: every Firestore sentinel converter in
+ * `converters/{fieldvalue,timestamp}.ts` marks its payload with a
+ * `__type: '<name>'` discriminator. The walk matches that.
+ *
+ * Field-path syntax (locked in the decision doc, R1):
+ *   - object keys join with '.'
+ *   - in-array positions append '[<index>]'
+ *   - e.g., `tags[0]`, `profile.lastSeen`, `history[0].at`
+ *
+ * Short-circuit: when a sentinel is detected the walk does NOT recurse
+ * into its internals (e.g. `arrayUnion.values` may contain plain values
+ * that aren't replay-relevant). This is also what makes the walk cheap
+ * — probe R2 measured p99 ≤ 0.009ms across 0/1/16 sentinels per doc.
+ */
+export function walkForSentinels(value, prefix = '') {
+    const hits = [];
+    visit(value, prefix);
+    return hits;
+    function visit(v, p) {
+        if (v === null || v === undefined || typeof v !== 'object')
+            return;
+        if (Array.isArray(v)) {
+            v.forEach((el, i) => visit(el, `${p}[${i}]`));
+            return;
+        }
+        const obj = v;
+        const kind = detect(obj);
+        if (kind) {
+            hits.push({ field: p, kind });
+            return;
+        }
+        for (const [k, child] of Object.entries(obj)) {
+            const next = p ? `${p}.${k}` : k;
+            visit(child, next);
+        }
+    }
+}
+function detect(obj) {
+    const t = obj.__type;
+    if (t === 'serverTimestamp')
+        return 'serverTimestamp';
+    if (t === 'increment')
+        return 'increment';
+    if (t === 'arrayUnion')
+        return 'arrayUnion';
+    if (t === 'arrayRemove')
+        return 'arrayRemove';
+    if (t === 'deleteField')
+        return 'delete';
+    return null;
+}
+//# sourceMappingURL=sentinel-capture.js.map