pyric 0.0.1 → 0.1.0-alpha.10

package/dist/sandbox/branches/index.js

@@ -0,0 +1,327 @@
+/**
+ * Branches — a fork / apply / diff / promote / discard primitive built
+ * **on top of** the existing `snapshot()` + `replay()` surface. Nothing
+ * here re-implements those; a branch is an in-memory sandbox seeded from
+ * a {@link SandboxSnapshot}, with `apply` delegating to `replay()` and
+ * `diff` reusing the replay engine's structural divergence classifier.
+ *
+ * Mental model (the Pyric Studio "experiment" primitive — see
+ * the design rationale):
+ *
+ *   const branch = fork(live.snapshot(), rules);   // isolated copy
+ *   apply(branch, agentPlanEvents);                // re-issue writes
+ *   const changes = diff(branch, live);            // what changed vs live
+ *   promote(branch, live);   // land the branch's mutations on live
+ *   // ...or...
+ *   discard(branch);         // drop it; live is untouched
+ *
+ * This is the substrate for Studio's agent dry-run → accept/reject
+ * (A1), rules-failure "re-run against an edited ruleset" (F4), and
+ * time-travel (A2). Each of those wants: an isolated copy of current
+ * state, a way to play hypothetical writes against it, a structural
+ * diff, and a commit/rollback gate.
+ *
+ * Granularity / honesty notes:
+ *   - `fork` rehydrates **Firestore** state from the snapshot (the
+ *     `firestore` key) plus rules. Per-service state in
+ *     `snapshot.services` (auth users, etc.) is NOT rehydrated here —
+ *     a fresh fork has no registered persistable services to restore
+ *     into, mirroring how persistence skips unregistered services. If a
+ *     consumer needs auth-in-a-branch it can register services on the
+ *     branch sandbox and restore them; that's out of scope for v1.
+ *   - `diff` reuses the replay engine's doc-level + field-level walk
+ *     (`Divergence`). Without captured write metadata it can't license
+ *     sentinel/auto-id drift, so every field difference surfaces as
+ *     `real-divergence` — which is the correct, honest classification
+ *     for "branch state vs live state" (there are no replayed sentinels
+ *     to reconcile). Doc add/remove surface as presence divergences.
+ *   - `promote` re-issues the branch's accumulated write events onto the
+ *     target via `replay`'s machinery, then copies the resulting docs
+ *     onto the target through the admin plane. It applies *mutations*
+ *     (added/changed/removed docs), not a blind whole-snapshot replace —
+ *     docs the branch never touched are left alone on the target.
+ */
+import { initializeSandbox, } from '../index.js';
+import { getInternalEnv } from '../internal/sandbox-impl.js';
+import { Timestamp } from 'pyric/rules/internal';
+/**
+ * Fork a new branch from a snapshot.
+ *
+ * Seeds a fresh sandbox with `rules` and the snapshot's Firestore docs
+ * (the same `seed({ rules, documents })` path replay uses to stand up a
+ * clean environment). The branch is fully isolated: writes on it never
+ * touch the source sandbox.
+ *
+ * @param snapshot Baseline state — typically `liveSandbox.snapshot()`.
+ * @param rules    Rules source for the branch. Pass the live rules to
+ *                 reproduce production behaviour, or an *edited* ruleset
+ *                 to test a rules change in isolation (Studio F4).
+ */
+export function fork(snapshot, rules = '') {
+    const sandbox = initializeSandbox();
+    const env = getInternalEnv(sandbox);
+    // Copy-on-write fork: the branch reads `snapshot.firestore` as an immutable
+    // base (no clone, O(1)) and lands its own writes in an overlay. The snapshot
+    // is a stable, branch-owned object the live sandbox never mutates, so the
+    // branch stays isolated from later live writes.
+    env.seed({ rules, baseDocuments: snapshot.firestore });
+    return {
+        sandbox,
+        rules,
+        base: snapshot,
+        events: [],
+        discarded: false,
+    };
+}
+/**
+ * Apply a stream of events to a branch by re-issuing their writes against
+ * the branch's CURRENT state.
+ *
+ * This is the same per-write re-issue logic `replay()` runs (filter to
+ * `kind: 'write'`, honour `autoId` / pinned `requestTime`, prefer the
+ * pre-resolution `request.resourceData` so sentinels re-resolve), but
+ * applied *incrementally* on the branch's existing env rather than on a
+ * fresh empty sandbox — so it composes over base docs (e.g. an `update`
+ * lands on a doc the snapshot seeded) and accumulates across multiple
+ * `apply` calls. The applied events are folded into `branch.events` so
+ * {@link promote} can reproduce the same sequence on the target.
+ *
+ * @returns the same branch (mutated in place) for chaining.
+ */
+export function apply(branch, events) {
+    assertLive(branch);
+    const env = getInternalEnv(branch.sandbox);
+    const writes = events.filter((e) => e.kind === 'write');
+    for (const wEv of writes) {
+        // Prefer the paired request event's pre-resolution payload (sentinels
+        // intact); fall back to the write's post-resolution `data`.
+        const data = preResolutionDataFor(wEv, events) ?? wEv.data;
+        const requestTime = new Timestamp(wEv.requestTime.seconds, wEv.requestTime.nanoseconds);
+        if (wEv.autoId) {
+            const collection = wEv.path.slice(0, wEv.path.lastIndexOf('/'));
+            env.createWithAutoId(collection, (data ?? {}), wEv.auth);
+            continue;
+        }
+        try {
+            env.execute({
+                method: wEv.method,
+                path: wEv.path,
+                auth: wEv.auth,
+                ...(data !== undefined ? { data: data } : {}),
+                requestTime,
+            });
+        }
+        catch {
+            // A denied/failed re-issue surfaces later as state divergence in
+            // diff(); keep going so one bad write doesn't abort the rest.
+        }
+    }
+    branch.events.push(...events);
+    return branch;
+}
+/**
+ * Best-effort pre-resolution payload for a write — the `request` event at
+ * or before it (same path) carries `request.resourceData` with sentinels
+ * intact. Mirrors the replay engine's `preResolutionDataFor`.
+ */
+function preResolutionDataFor(wEv, allEvents) {
+    const wIdx = allEvents.indexOf(wEv);
+    if (wIdx < 0)
+        return undefined;
+    for (let i = wIdx; i >= 0; i--) {
+        const e = allEvents[i];
+        if (!e || e.kind !== 'request')
+            continue;
+        if (e.path !== wEv.path)
+            continue;
+        return e.request?.resourceData;
+    }
+    return undefined;
+}
+/**
+ * Structural diff of a branch's current state against a reference.
+ *
+ * Reuses the replay engine's `Divergence` result type and mirrors its
+ * doc-level + field-level walk (see {@link diffDocSets}). With no captured
+ * write metadata in play, differences surface as `real-divergence`
+ * (field/doc changed) — the honest classification for "branch vs live".
+ * Added/removed docs surface as presence divergences (one side
+ * `undefined`).
+ *
+ * @param branch The experiment.
+ * @param target Live sandbox or a snapshot to compare against.
+ */
+export function diff(branch, target) {
+    assertLive(branch);
+    const branchDocs = getInternalEnv(branch.sandbox).snapshot();
+    const targetDocs = firestoreSnapshotOf(target);
+    return diffDocSets(targetDocs, branchDocs);
+}
+/**
+ * Promote a branch's mutations onto a target (live) sandbox.
+ *
+ * "Honest promote": it computes the doc-level delta between the branch's
+ * BASE snapshot and its current state — i.e. exactly what the applied
+ * events changed — and lands only those mutations on the target through
+ * the admin plane:
+ *   - docs added/changed on the branch → `admin.setDocument`
+ *   - docs deleted on the branch       → `admin.deleteDocument`
+ *   - docs the branch never touched    → left untouched on the target
+ *
+ * Admin-plane application fires the target's listeners (matching how
+ * persistence restore lands docs), so live UI/handles see the promotion.
+ *
+ * The branch is marked discarded afterward — a promoted branch is spent.
+ *
+ * @param branch The experiment to land.
+ * @param target The live sandbox to land it on.
+ */
+export function promote(branch, target) {
+    assertLive(branch);
+    const baseDocs = branch.base.firestore;
+    const finalDocs = getInternalEnv(branch.sandbox).snapshot();
+    const paths = new Set([...Object.keys(baseDocs), ...Object.keys(finalDocs)]);
+    for (const path of paths) {
+        const before = baseDocs[path];
+        const after = finalDocs[path];
+        if (after === undefined) {
+            // Branch deleted this doc relative to its base.
+            target.admin.deleteDocument(path);
+            continue;
+        }
+        if (before === undefined || !sandboxDocumentsEqual(before, after)) {
+            // Branch added or changed this doc.
+            target.admin.setDocument(path, after);
+        }
+        // else: unchanged on the branch — leave the target's copy alone.
+    }
+    branch.discarded = true;
+    branch.sandbox.dispose();
+}
+/**
+ * Discard a branch: drop its sandbox and mark it spent. The target is
+ * never touched (nothing was promoted). Idempotent.
+ */
+export function discard(branch) {
+    if (branch.discarded)
+        return;
+    branch.discarded = true;
+    branch.sandbox.dispose();
+}
+// ---------------------------------------------------------------------------
+// internals
+// ---------------------------------------------------------------------------
+function assertLive(branch) {
+    if (branch.discarded) {
+        throw new Error('Branch has been discarded or promoted; create a new fork.');
+    }
+}
+/** Resolve only Firestore documents without traversing registered services. */
+function firestoreSnapshotOf(target) {
+    if (isSandbox(target))
+        return getInternalEnv(target).snapshot();
+    return target.firestore;
+}
+function isSandbox(target) {
+    return typeof target.snapshot === 'function';
+}
+/**
+ * Doc-set structural diff. Mirrors the replay engine's doc-level + field-
+ * level walk and reuses its `Divergence` result type. The replay engine's
+ * own classifier is bound to captured write metadata (sentinels / auto-id
+ * aliases) which a branch-vs-live comparison doesn't have, so this is the
+ * "focused doc-level diff" the spec calls for when that machinery doesn't
+ * fit: every leaf difference is `real-divergence`, and doc add/remove
+ * surface as presence divergences (one side `undefined`).
+ */
+function diffDocSets(beforeDocs, afterDocs) {
+    const out = [];
+    const allPaths = new Set([...Object.keys(beforeDocs), ...Object.keys(afterDocs)]);
+    for (const path of allPaths) {
+        const before = beforeDocs[path];
+        const after = afterDocs[path];
+        if (before === undefined && after !== undefined) {
+            out.push({ kind: 'real-divergence', path, before: undefined, after });
+            continue;
+        }
+        if (before !== undefined && after === undefined) {
+            out.push({ kind: 'real-divergence', path, before, after: undefined });
+            continue;
+        }
+        if (before === undefined || after === undefined)
+            continue;
+        walkDoc(path, before, after, out);
+    }
+    return out;
+}
+/**
+ * Field-level walk producing dotted/bracket leaf paths — mirrors the
+ * replay engine's `diffDoc` walk (same path syntax: `profile.lastSeen`,
+ * `tags[0]`). Every leaf difference is `real-divergence`; there is no
+ * captured sentinel metadata in a branch-vs-live diff to license drift.
+ */
+function walkDoc(path, before, after, out) {
+    walk(before, after, '');
+    function walk(a, b, fieldPath) {
+        if (a === b)
+            return;
+        const aIsObj = a !== null && typeof a === 'object' && !Array.isArray(a);
+        const bIsObj = b !== null && typeof b === 'object' && !Array.isArray(b);
+        if (aIsObj && bIsObj) {
+            const ao = a;
+            const bo = b;
+            const keys = new Set([...Object.keys(ao), ...Object.keys(bo)]);
+            for (const k of keys) {
+                const next = fieldPath ? `${fieldPath}.${k}` : k;
+                walk(ao[k], bo[k], next);
+            }
+            return;
+        }
+        if (Array.isArray(a) && Array.isArray(b)) {
+            const len = Math.max(a.length, b.length);
+            for (let i = 0; i < len; i++) {
+                walk(a[i], b[i], `${fieldPath}[${i}]`);
+            }
+            return;
+        }
+        if (sandboxDocumentsEqual(a, b))
+            return;
+        out.push({ kind: 'real-divergence', path, field: fieldPath || undefined, before: a, after: b });
+    }
+}
+/** Structural equality on sandbox document snapshots. */
+function sandboxDocumentsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    const aArr = Array.isArray(a);
+    const bArr = Array.isArray(b);
+    if (aArr !== bArr)
+        return false;
+    if (aArr && bArr) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!sandboxDocumentsEqual(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao);
+    const bk = Object.keys(bo);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k))
+            return false;
+        if (!sandboxDocumentsEqual(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=index.js.map

package/dist/sandbox/branches/index.js.map

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

package/dist/sandbox/firestore/admin-compat/batch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `WriteBatchImpl` — Admin-SDK-compat `WriteBatch` backed by
+ * `LocalEnvironment.batch(...)`.
+ *
+ * Ported from bench's `pilot/src/firestore-wrapper.ts:360-391`.
+ *
+ * Set semantics: `WriteBatch.set(ref, data)` translates to either
+ * `'create'` (doc absent) or `'update'` (doc present) at queue time —
+ * the simulator's `BatchOperationInput` accepts only
+ * `'create' | 'update' | 'delete'`. The peek runs in the wrapper
+ * thread (single-threaded; the simulator is synchronous), so no other
+ * write can interleave between peek and queue.
+ *
+ * Error translation: `LocalEnvironment.batch(...)` returns a
+ * `BatchResult` whose `.error` carries a typed `FirestoreSimError`
+ * for any failed batch (atomic rollback). Surface that directly as
+ * `FirestoreCompatError` — same field-shape as Admin SDK's
+ * `FirestoreError.code` so `try { } catch (e) { if (e.code ===
+ * 'already-exists') }` works unchanged.
+ */
+import type { LocalEnvironment } from 'pyric/sandbox/internal';
+import { type AuthContext, type DocumentData, type DocumentReference, type OperationOptions, type WriteBatch } from './types.js';
+export declare class WriteBatchImpl implements WriteBatch {
+    private readonly env;
+    private readonly auth;
+    private readonly bypassRules;
+    private readonly ops;
+    constructor(env: LocalEnvironment, auth: AuthContext, bypassRules?: boolean);
+    set(ref: DocumentReference, data: DocumentData): WriteBatch;
+    update(ref: DocumentReference, data: DocumentData): WriteBatch;
+    delete(ref: DocumentReference): WriteBatch;
+    commit(opts?: OperationOptions): Promise<void>;
+}
+//# sourceMappingURL=batch.d.ts.map

package/dist/sandbox/firestore/admin-compat/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/firestore/admin-compat/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,qBAAa,cAAe,YAAW,UAAU;IAI7C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAGrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAP9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;gBAG9B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,WAAW,EAGjB,WAAW,GAAE,OAAe;IAG/C,GAAG,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,YAAY,GAAG,UAAU;IAU3D,MAAM,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,YAAY,GAAG,UAAU;IAK9D,MAAM,CAAC,GAAG,EAAE,iBAAiB,GAAG,UAAU;IAKpC,MAAM,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBrD"}

package/dist/sandbox/firestore/admin-compat/batch.js

@@ -0,0 +1,73 @@
+/**
+ * `WriteBatchImpl` — Admin-SDK-compat `WriteBatch` backed by
+ * `LocalEnvironment.batch(...)`.
+ *
+ * Ported from bench's `pilot/src/firestore-wrapper.ts:360-391`.
+ *
+ * Set semantics: `WriteBatch.set(ref, data)` translates to either
+ * `'create'` (doc absent) or `'update'` (doc present) at queue time —
+ * the simulator's `BatchOperationInput` accepts only
+ * `'create' | 'update' | 'delete'`. The peek runs in the wrapper
+ * thread (single-threaded; the simulator is synchronous), so no other
+ * write can interleave between peek and queue.
+ *
+ * Error translation: `LocalEnvironment.batch(...)` returns a
+ * `BatchResult` whose `.error` carries a typed `FirestoreSimError`
+ * for any failed batch (atomic rollback). Surface that directly as
+ * `FirestoreCompatError` — same field-shape as Admin SDK's
+ * `FirestoreError.code` so `try { } catch (e) { if (e.code ===
+ * 'already-exists') }` works unchanged.
+ */
+import { makeError } from 'pyric/sandbox/internal';
+import { FirestoreCompatError, } from './types.js';
+export class WriteBatchImpl {
+    env;
+    auth;
+    bypassRules;
+    ops = [];
+    constructor(env, auth, 
+    // Studio admin lens (Gap #2) — when true, the committed batch bypasses
+    // rules. Forwarded to LocalEnvironment.batch(). Default false.
+    bypassRules = false) {
+        this.env = env;
+        this.auth = auth;
+        this.bypassRules = bypassRules;
+    }
+    set(ref, data) {
+        // Dispatch to create-or-update at queue time — same logic as
+        // DocumentRefImpl.set, kept here rather than shared because the
+        // batch path has no async wrapping.
+        const existing = this.env.getDocument(ref.path);
+        const method = existing === null ? 'create' : 'update';
+        this.ops.push({ method, path: ref.path, data });
+        return this;
+    }
+    update(ref, data) {
+        this.ops.push({ method: 'update', path: ref.path, data });
+        return this;
+    }
+    delete(ref) {
+        this.ops.push({ method: 'delete', path: ref.path });
+        return this;
+    }
+    async commit(opts) {
+        // Empty batch is a no-op — match Admin SDK behavior (commit() of an
+        // empty WriteBatch resolves cleanly without a network round-trip).
+        if (this.ops.length === 0)
+            return;
+        const result = this.env.batch(this.ops, opts?.auth !== undefined ? opts.auth : this.auth, this.bypassRules);
+        if (result.allowed)
+            return;
+        // Surface the structured error if present (always present per
+        // Item 6 — see errors.ts; first per-op error mirrored to top-level).
+        if (result.error) {
+            throw new FirestoreCompatError(result.error);
+        }
+        // Defensive fallback — should be unreachable given Item 6's
+        // invariant that every denial carries an error.
+        const denied = result.results.find((r) => !r.allowed);
+        const msg = denied?.debugMessages.join('; ') ?? 'batch denied';
+        throw new FirestoreCompatError(makeError('permission-denied', `batch failed: ${msg}`));
+    }
+}
+//# sourceMappingURL=batch.js.map

package/dist/sandbox/firestore/admin-compat/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../../../src/sandbox/firestore/admin-compat/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EACL,oBAAoB,GAMrB,MAAM,YAAY,CAAC;AAEpB,MAAM,OAAO,cAAc;IAIN;IACA;IAGA;IAPF,GAAG,GAA0B,EAAE,CAAC;IAEjD,YACmB,GAAqB,EACrB,IAAiB;IAClC,uEAAuE;IACvE,+DAA+D;IAC9C,cAAuB,KAAK;QAJ5B,QAAG,GAAH,GAAG,CAAkB;QACrB,SAAI,GAAJ,IAAI,CAAa;QAGjB,gBAAW,GAAX,WAAW,CAAiB;IAC5C,CAAC;IAEJ,GAAG,CAAC,GAAsB,EAAE,IAAkB;QAC5C,6DAA6D;QAC7D,gEAAgE;QAChE,oCAAoC;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,MAAM,GAAwB,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC5E,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,GAAsB,EAAE,IAAkB;QAC/C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,GAAsB;QAC3B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAuB;QAClC,oEAAoE;QACpE,mEAAmE;QACnE,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAC3B,IAAI,CAAC,GAAG,EACR,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAChD,IAAI,CAAC,WAAW,CACjB,CAAC;QACF,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO;QAC3B,8DAA8D;QAC9D,qEAAqE;QACrE,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C,CAAC;QACD,4DAA4D;QAC5D,gDAAgD;QAChD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC;QAC/D,MAAM,IAAI,oBAAoB,CAAC,SAAS,CAAC,mBAAmB,EAAE,iBAAiB,GAAG,EAAE,CAAC,CAAC,CAAC;IACzF,CAAC;CACF"}

package/dist/sandbox/firestore/admin-compat/doc-ref.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `DocumentRefImpl` — Admin-SDK-compat `DocumentReference` backed by
+ * `LocalEnvironment`.
+ *
+ * Ported from bench's `pilot/src/firestore-wrapper.ts:213-270`. The
+ * behavioral nuance worth a comment is `set()`: the simulator's
+ * evaluator wants distinct `'create'` / `'update'` rule clauses (no
+ * `allow set:` syntax). So `set()` peeks at `getDocument(path)`,
+ * dispatches to `create` if absent / `update` if present.
+ *
+ * Differences from the bench source:
+ *   - Plain `Error` throws → `FirestoreCompatError` with the typed
+ *     `FirestoreErrorCode` from the SDK's `OperationResult.error`.
+ *     Falls back to `'permission-denied'` if the simulator returned a
+ *     denial without a structured error (defense-in-depth — slice-1
+ *     review locked that every denial carries `error`, but the
+ *     fallback keeps the wrapper honest if that invariant ever slips).
+ *   - The `update`-as-partial vs Firestore-`set`-as-replace divergence
+ *     is documented (and locked) at the design-doc level — see
+ *     the design rationale.
+ */
+import type { LocalEnvironment } from 'pyric/sandbox/internal';
+import { type AuthContext, type CollectionReference, type DocumentData, type DocumentReference, type DocumentSnapshot, type OperationOptions, type SetOptions } from './types.js';
+export declare class DocumentRefImpl implements DocumentReference {
+    private readonly env;
+    private readonly auth;
+    private readonly bypassRules;
+    readonly id: string;
+    readonly path: string;
+    constructor(env: LocalEnvironment, auth: AuthContext, path: string, bypassRules?: boolean);
+    get parent(): CollectionReference;
+    collection(name: string): CollectionReference;
+    get(opts?: OperationOptions): Promise<DocumentSnapshot>;
+    set(data: DocumentData, options?: SetOptions): Promise<void>;
+    update(data: DocumentData, opts?: OperationOptions): Promise<void>;
+    delete(opts?: OperationOptions): Promise<void>;
+}
+//# sourceMappingURL=doc-ref.d.ts.map

package/dist/sandbox/firestore/admin-compat/doc-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-ref.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/firestore/admin-compat/doc-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM/D,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAsBpB,qBAAa,eAAgB,YAAW,iBAAiB;IAKrD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAIrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAT9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGH,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,WAAW,EAClC,IAAI,EAAE,MAAM,EAGK,WAAW,GAAE,OAAe;IAM/C,IAAI,MAAM,IAAI,mBAAmB,CAOhC;IAED,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB;IAIvC,GAAG,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkBvD,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAoD5D,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlE,MAAM,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CASrD"}

package/dist/sandbox/firestore/admin-compat/doc-ref.js

@@ -0,0 +1,154 @@
+/**
+ * `DocumentRefImpl` — Admin-SDK-compat `DocumentReference` backed by
+ * `LocalEnvironment`.
+ *
+ * Ported from bench's `pilot/src/firestore-wrapper.ts:213-270`. The
+ * behavioral nuance worth a comment is `set()`: the simulator's
+ * evaluator wants distinct `'create'` / `'update'` rule clauses (no
+ * `allow set:` syntax). So `set()` peeks at `getDocument(path)`,
+ * dispatches to `create` if absent / `update` if present.
+ *
+ * Differences from the bench source:
+ *   - Plain `Error` throws → `FirestoreCompatError` with the typed
+ *     `FirestoreErrorCode` from the SDK's `OperationResult.error`.
+ *     Falls back to `'permission-denied'` if the simulator returned a
+ *     denial without a structured error (defense-in-depth — slice-1
+ *     review locked that every denial carries `error`, but the
+ *     fallback keeps the wrapper honest if that invariant ever slips).
+ *   - The `update`-as-partial vs Firestore-`set`-as-replace divergence
+ *     is documented (and locked) at the design-doc level — see
+ *     the design rationale.
+ */
+import { makeError } from 'pyric/sandbox/internal';
+import { lastSegment, parentCollectionPath } from './paths.js';
+import { makeDocSnapshot } from './snapshots.js';
+import { CollectionRefImpl } from './query.js';
+import { FirestoreCompatError, } from './types.js';
+/**
+ * Convert a denied `OperationResult` into a typed throwable. Prefers
+ * the result's structured error; falls back to `'permission-denied'`
+ * with a stitched-together message from `debugMessages`.
+ */
+function throwFromDenial(result, contextLabel) {
+    if (result.error) {
+        throw new FirestoreCompatError(result.error);
+    }
+    const msg = result.debugMessages.length > 0
+        ? result.debugMessages.join('; ')
+        : '(no debug message)';
+    throw new FirestoreCompatError(makeError('permission-denied', `${contextLabel}: ${msg}`));
+}
+export class DocumentRefImpl {
+    env;
+    auth;
+    bypassRules;
+    id;
+    path;
+    constructor(env, auth, path, 
+    // Studio admin lens (Gap #2) — stamped onto every Operation this ref
+    // issues. Inherited by child collection refs. Default false.
+    bypassRules = false) {
+        this.env = env;
+        this.auth = auth;
+        this.bypassRules = bypassRules;
+        this.path = path;
+        this.id = lastSegment(path);
+    }
+    get parent() {
+        return new CollectionRefImpl(this.env, this.auth, parentCollectionPath(this.path), this.bypassRules);
+    }
+    collection(name) {
+        return new CollectionRefImpl(this.env, this.auth, `${this.path}/${name}`, this.bypassRules);
+    }
+    async get(opts) {
+        const result = this.env.execute({
+            method: 'get',
+            path: this.path,
+            auth: opts?.auth !== undefined ? opts.auth : this.auth,
+            bypassRules: this.bypassRules,
+        });
+        if (!result.allowed)
+            throwFromDenial(result, 'get denied');
+        // execute() returns `data: undefined` for "denied" and `data: null`
+        // for "doc absent (rule allowed)". makeDocSnapshot treats both as
+        // "not exists", which matches Admin SDK's `snap.exists === false`
+        // for a get of a missing doc.
+        const data = result.data === undefined || result.data === null
+            ? undefined
+            : result.data;
+        return makeDocSnapshot(this, data);
+    }
+    async set(data, options) {
+        // Three branches — each rides on the same execute() pipeline but
+        // chooses a different combination of (rule clause, storage mode):
+        //
+        //   - default: rule clause picked by execute() (create / update),
+        //     storage REPLACES via the `'set'` method. Matches Firestore
+        //     `set(data)` semantics.
+        //   - { merge: true }: shallow-merge every top-level field via the
+        //     `'update'` rule clause + storage update (which merges).
+        //     Falls back to `'create'` when the doc is absent.
+        //   - { mergeFields: [...] }: project `data` to just the listed
+        //     top-level fields, then dispatch the same way as merge:true.
+        const auth = options?.auth !== undefined ? options.auth : this.auth;
+        if (options?.mergeFields !== undefined) {
+            // FS-B6: pass the full data + the field-path mask to the merge
+            // engine. It deep-merges only the listed (dot-separated) paths into
+            // the existing doc — dropping the old shallow top-level projection.
+            const mergeFields = options.mergeFields.map((f) => String(f));
+            const existing = this.env.getDocument(this.path);
+            const method = existing === null ? 'create' : 'update';
+            const result = this.env.execute({
+                method, path: this.path, data, auth, merge: { mergeFields },
+                bypassRules: this.bypassRules,
+            });
+            if (!result.allowed)
+                throwFromDenial(result, `set denied (as ${method})`);
+            return;
+        }
+        if (options?.merge === true) {
+            // FS-B6: deep-merge nested maps into the existing doc instead of the
+            // old shallow top-level spread.
+            const existing = this.env.getDocument(this.path);
+            const method = existing === null ? 'create' : 'update';
+            const result = this.env.execute({
+                method, path: this.path, data, auth, merge: true,
+                bypassRules: this.bypassRules,
+            });
+            if (!result.allowed)
+                throwFromDenial(result, `set denied (as ${method})`);
+            return;
+        }
+        // Default — replace semantics. The simulator's `'set'` method
+        // translates to `create` / `update` for rules eval but routes to
+        // `state.set` (replace) for storage.
+        const result = this.env.execute({
+            method: 'set', path: this.path, data, auth,
+            bypassRules: this.bypassRules,
+        });
+        if (!result.allowed)
+            throwFromDenial(result, 'set denied');
+    }
+    async update(data, opts) {
+        const result = this.env.execute({
+            method: 'update',
+            path: this.path,
+            data,
+            auth: opts?.auth !== undefined ? opts.auth : this.auth,
+            bypassRules: this.bypassRules,
+        });
+        if (!result.allowed)
+            throwFromDenial(result, 'update denied');
+    }
+    async delete(opts) {
+        const result = this.env.execute({
+            method: 'delete',
+            path: this.path,
+            auth: opts?.auth !== undefined ? opts.auth : this.auth,
+            bypassRules: this.bypassRules,
+        });
+        if (!result.allowed)
+            throwFromDenial(result, 'delete denied');
+    }
+}
+//# sourceMappingURL=doc-ref.js.map