pyric 0.0.1 → 0.1.0-alpha.10

package/dist/sandbox/admin-firestore/remote/query.js

@@ -0,0 +1,186 @@
+/**
+ * Chainable `Query` for the remote arm — accumulates `where`/`orderBy`/
+ * cursor/`limit` state immutably (mirroring the local arm's `QueryImpl`)
+ * and flattens it into the wire's constraint list on execution.
+ *
+ * KNOWN CURSOR LIMITS: the wire has no document-key cursor, so snapshot
+ * cursors require explicit non-`__name__` orderBy fields and lose the
+ * implicit `__name__` tie-break — see {@link cursorValuesFromSnapshot}.
+ */
+import { SandboxError } from 'pyric/sandbox';
+import { armOp } from './channel.js';
+import { invalidArgument } from './errors.js';
+import { encodeValue } from './value-codec.js';
+import { makeQuerySnapshot } from './snapshots.js';
+import { chainableOnSnapshot, REMOTE_SNAPSHOT_REGISTRAR, registerRemoteListener, } from './listeners.js';
+/** Brand for `Transaction.get`'s doc-vs-query runtime dispatch and the
+ *  descriptor recovery it needs. */
+const QUERY_STATE = Symbol('pyric/sandbox/admin-firestore/remoteQueryState');
+export function queryStateOf(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    return value[QUERY_STATE];
+}
+function encodeFilter(filter) {
+    if (filter.kind === 'where') {
+        validateWhereOp(filter.op);
+        return { kind: 'where', field: filter.field, op: filter.op, value: encodeValue(filter.value) };
+    }
+    return { kind: filter.kind, filters: filter.filters.map(encodeFilter) };
+}
+const WHERE_OPS = new Set([
+    '<', '<=', '==', '!=', '>=', '>',
+    'in', 'not-in', 'array-contains', 'array-contains-any',
+]);
+function validateWhereOp(op) {
+    if (!WHERE_OPS.has(op)) {
+        throw invalidArgument(`invalid where operator: ${String(op)}`);
+    }
+}
+/** Flatten the accumulated state into the wire's constraint list. */
+export function buildDescriptor(state) {
+    const constraints = [...state.filters];
+    for (const o of state.orders) {
+        constraints.push({ kind: 'orderBy', field: o.field, direction: o.direction });
+    }
+    if (state.start) {
+        constraints.push({
+            kind: state.start.inclusive ? 'startAt' : 'startAfter',
+            values: state.start.values.map(encodeValue),
+        });
+    }
+    if (state.end) {
+        constraints.push({
+            kind: state.end.inclusive ? 'endAt' : 'endBefore',
+            values: state.end.values.map(encodeValue),
+        });
+    }
+    if (state.limitCount !== undefined) {
+        constraints.push(state.limitFromEnd
+            ? { kind: 'limitToLast', n: state.limitCount }
+            : { kind: 'limit', n: state.limitCount });
+    }
+    if (constraints.length === 0)
+        return state.source;
+    return { __ref: 'query', source: state.source, constraints };
+}
+/**
+ * Pull cursor values off a `DocumentSnapshot` at the query's EXPLICIT
+ * orderBy fields — the remote mirror of the local
+ * `cursorValuesFromSnapshot`.
+ *
+ * HONEST FIDELITY LIMITS (the relay's value-cursor constraints cannot
+ * express a document-key cursor; extending the wire with one is filed
+ * for later — no protocol change here):
+ *
+ *   1. Zero explicit orderBy → THROW. The local arm positions on the
+ *      implicit `__name__` key; the wire cannot.
+ *   2. An explicit `orderBy('__name__')` → THROW. `__name__` is not a
+ *      data field — reading `data()['__name__']` would yield `undefined`
+ *      and the cursor would silently match NOTHING/EVERYTHING.
+ *   3. TIE-BREAK GAP (documented, not thrown — it is only detectable at
+ *      the data level): the local arm's snapshot cursors also carry the
+ *      implicit `__name__` tie-break value, so `orderBy('v')
+ *      .startAfter(snapOfB)` with ties on `v` still positions PAST the
+ *      exact document. The remote cursor carries only the explicit
+ *      field values, so under EQUAL orderBy values the boundary is the
+ *      VALUE, not the document: `startAfter(snap)` skips every doc tied
+ *      with `snap` (deterministically — the whole tie group), where the
+ *      local arm keeps the tied docs that sort after it by key. Break
+ *      ties with an explicit second orderBy field to paginate exactly.
+ */
+function cursorValuesFromSnapshot(snapshot, orders, method) {
+    if (orders.length === 0) {
+        throw invalidArgument(`${method}(snapshot) on a remote sandbox requires at least one explicit orderBy() ` +
+            'clause — the relay protocol has no document-key cursor.');
+    }
+    if (orders.some((o) => o.field === '__name__')) {
+        throw invalidArgument(`${method}(snapshot) on a remote sandbox does not support orderBy('__name__') — ` +
+            'the relay protocol has no document-key cursor, and __name__ is not a data ' +
+            'field a value cursor can carry. Order by a real document field instead.');
+    }
+    const data = snapshot.data();
+    if (data === undefined) {
+        throw new SandboxError('not-found', 'Snapshot-based cursors require an existing document — got an empty ' +
+            `snapshot for ${snapshot.id ?? '<unknown>'}.`);
+    }
+    return orders.map((o) => data[o.field]);
+}
+export function makeQuery(arm, state) {
+    const clone = (patch) => makeQuery(arm, { ...state, ...patch });
+    const query = {
+        [QUERY_STATE]: state,
+        where(field, op, value) {
+            validateWhereOp(op);
+            return clone({
+                filters: [...state.filters, { kind: 'where', field, op, value: encodeValue(value) }],
+            });
+        },
+        applyFilter(filter) {
+            return clone({ filters: [...state.filters, encodeFilter(filter)] });
+        },
+        orderBy(field, direction = 'asc') {
+            return clone({ orders: [...state.orders, { field, direction }] });
+        },
+        limit(n) {
+            return clone({ limitCount: n, limitFromEnd: false });
+        },
+        limitToLast(n) {
+            return clone({ limitCount: n, limitFromEnd: true });
+        },
+        startCursor(values, inclusive) {
+            return clone({ start: { values: [...values], inclusive } });
+        },
+        endCursor(values, inclusive) {
+            return clone({ end: { values: [...values], inclusive } });
+        },
+        startCursorFromSnapshot(snapshot, inclusive) {
+            return clone({
+                start: {
+                    values: cursorValuesFromSnapshot(snapshot, state.orders, inclusive ? 'startAt' : 'startAfter'),
+                    inclusive,
+                },
+            });
+        },
+        endCursorFromSnapshot(snapshot, inclusive) {
+            return clone({
+                end: {
+                    values: cursorValuesFromSnapshot(snapshot, state.orders, inclusive ? 'endAt' : 'endBefore'),
+                    inclusive,
+                },
+            });
+        },
+        async get(_opts) {
+            validateExecutable(state);
+            const wire = (await armOp(arm, {
+                method: 'getDocs',
+                source: buildDescriptor(state),
+            }));
+            return makeQuerySnapshot(arm, wire);
+        },
+        async aggregate(spec) {
+            validateExecutable(state);
+            const wire = (await armOp(arm, {
+                method: 'aggregate',
+                source: buildDescriptor(state),
+                spec,
+            }));
+            return { data: () => wire.data };
+        },
+        [REMOTE_SNAPSHOT_REGISTRAR]: (options, onNext, onError) => {
+            validateExecutable(state);
+            return registerRemoteListener(arm, buildDescriptor(state), options, onNext, onError);
+        },
+        onSnapshot: chainableOnSnapshot,
+    };
+    return query;
+}
+/** Client-side runtime checks matching the local arm's execution-time
+ *  contract, so the failure surfaces with the same code + guidance
+ *  instead of a worker round-trip. */
+export function validateExecutable(state) {
+    if (state.limitFromEnd && state.orders.length === 0) {
+        throw invalidArgument('limitToLast() queries require at least one orderBy clause.');
+    }
+}
+//# sourceMappingURL=query.js.map

package/dist/sandbox/admin-firestore/remote/query.js.map

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

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

@@ -0,0 +1,55 @@
+/**
+ * Remote arm of the admin-shaped Firestore surface (remote sandbox,
+ * slice 2 / checkpoint 2).
+ *
+ * A PARALLEL channel-backed implementation of `pyric/sandbox/admin-compat`'s
+ * type surface (`Firestore` / `DocumentReference` / `Query` / `WriteBatch` /
+ * `Transaction`), per the remote-Firestore spike verdict: the local
+ * admin-compat layer is welded to `LocalEnvironment`'s SYNCHRONOUS engine
+ * seam and cannot run over a WebSocket, so the remote arm re-implements the
+ * SHAPE over `RemoteSandboxChannel.op`/`subscribe` worker-relay frames —
+ * exactly the fork `pyric-admin/database` took for RTDB. The two arms share
+ * the type surface and the conformance assertions, not the implementation.
+ *
+ * This module is the facade — `createRemoteFirestore` wires the collaborator
+ * files in this directory (`channel.ts` for the op dispatcher, `doc-ref.ts` /
+ * `query.ts` for refs, `batch.ts` for `WriteBatch`, `transaction.ts` for
+ * `Transaction`, `value-codec.ts` / `errors.ts` / `wire-types.ts` for the
+ * shared wire plumbing, `listeners.ts` for `onSnapshot`, `snapshots.ts` for
+ * one-shot reads) into the `SandboxFirestore` surface `../get-firestore.ts`
+ * and `../get-admin-firestore.ts` dispatch to for a remote sandbox context.
+ *
+ * DEPENDENCY DIRECTION: this module lives in `pyric` and may only consume
+ * the STRUCTURAL channel contract from `pyric/sandbox`'s remote seam
+ * (`RemoteSandboxChannel` — one loose `op`, one loose `subscribe`). The
+ * concrete worker-protocol unions live in `@pyric/cli`, which `pyric`
+ * cannot import; ops are spelled loosely (`{ method: 'getDoc', path,
+ * actAs }`) and kept structurally identical to
+ * `packages/cli/src/serve/worker/protocol.ts`.
+ *
+ * IDENTITY: every op and every subscription pins an EXPLICIT `actAs` lens.
+ * An ABSENT lens resolves worker-side to the browser tab's PORT SESSION —
+ * whoever happens to be signed in in the tab — which is never what a
+ * server-side handle means. `getAdminFirestore` pins `{ mode: 'admin' }`
+ * (rules bypass); `getFirestore(ctx)` pins `{ mode: 'as', uid, token? }`
+ * for a signed identity or `{ mode: 'anon' }` for `withAuth(null)`. The
+ * `as` lens carries the FULL `AuthState` (uid + custom-claims token): the
+ * worker host resolves it via `sandbox.withAuth({ uid, token })`, so there
+ * is no identity-fidelity loss versus the local arm.
+ *
+ * See `value-codec.ts` for the write/read value codec (including the
+ * accepted marker-lookalike divergence), `query.ts` for the cursor
+ * fidelity limits, and `transaction.ts` for the optimistic-transaction
+ * protocol.
+ */
+import { type AuthLens, type RemoteSandbox } from 'pyric/sandbox';
+import type { SandboxFirestore } from '../types.js';
+/**
+ * Build the channel-backed `SandboxFirestore` for a remote sandbox handle.
+ * `lens` is pinned on EVERY op and subscription (see the module header for
+ * the identity mapping); path-shape validation matches the local arm so
+ * `invalid-argument` failures surface at the call site without a
+ * round-trip.
+ */
+export declare function createRemoteFirestore(sandbox: RemoteSandbox, lens: AuthLens): SandboxFirestore;
+//# sourceMappingURL=remote-firestore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-firestore.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/remote-firestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAahF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAkBpD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,QAAQ,GACb,gBAAgB,CA6DlB"}

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

@@ -0,0 +1,111 @@
+/**
+ * Remote arm of the admin-shaped Firestore surface (remote sandbox,
+ * slice 2 / checkpoint 2).
+ *
+ * A PARALLEL channel-backed implementation of `pyric/sandbox/admin-compat`'s
+ * type surface (`Firestore` / `DocumentReference` / `Query` / `WriteBatch` /
+ * `Transaction`), per the remote-Firestore spike verdict: the local
+ * admin-compat layer is welded to `LocalEnvironment`'s SYNCHRONOUS engine
+ * seam and cannot run over a WebSocket, so the remote arm re-implements the
+ * SHAPE over `RemoteSandboxChannel.op`/`subscribe` worker-relay frames —
+ * exactly the fork `pyric-admin/database` took for RTDB. The two arms share
+ * the type surface and the conformance assertions, not the implementation.
+ *
+ * This module is the facade — `createRemoteFirestore` wires the collaborator
+ * files in this directory (`channel.ts` for the op dispatcher, `doc-ref.ts` /
+ * `query.ts` for refs, `batch.ts` for `WriteBatch`, `transaction.ts` for
+ * `Transaction`, `value-codec.ts` / `errors.ts` / `wire-types.ts` for the
+ * shared wire plumbing, `listeners.ts` for `onSnapshot`, `snapshots.ts` for
+ * one-shot reads) into the `SandboxFirestore` surface `../get-firestore.ts`
+ * and `../get-admin-firestore.ts` dispatch to for a remote sandbox context.
+ *
+ * DEPENDENCY DIRECTION: this module lives in `pyric` and may only consume
+ * the STRUCTURAL channel contract from `pyric/sandbox`'s remote seam
+ * (`RemoteSandboxChannel` — one loose `op`, one loose `subscribe`). The
+ * concrete worker-protocol unions live in `@pyric/cli`, which `pyric`
+ * cannot import; ops are spelled loosely (`{ method: 'getDoc', path,
+ * actAs }`) and kept structurally identical to
+ * `packages/cli/src/serve/worker/protocol.ts`.
+ *
+ * IDENTITY: every op and every subscription pins an EXPLICIT `actAs` lens.
+ * An ABSENT lens resolves worker-side to the browser tab's PORT SESSION —
+ * whoever happens to be signed in in the tab — which is never what a
+ * server-side handle means. `getAdminFirestore` pins `{ mode: 'admin' }`
+ * (rules bypass); `getFirestore(ctx)` pins `{ mode: 'as', uid, token? }`
+ * for a signed identity or `{ mode: 'anon' }` for `withAuth(null)`. The
+ * `as` lens carries the FULL `AuthState` (uid + custom-claims token): the
+ * worker host resolves it via `sandbox.withAuth({ uid, token })`, so there
+ * is no identity-fidelity loss versus the local arm.
+ *
+ * See `value-codec.ts` for the write/read value codec (including the
+ * accepted marker-lookalike divergence), `query.ts` for the cursor
+ * fidelity limits, and `transaction.ts` for the optimistic-transaction
+ * protocol.
+ */
+import { SandboxError } from 'pyric/sandbox';
+import { isCollectionPath, isDocumentPath, } from '../../firestore/admin-compat/paths.js';
+import { invalidArgument } from './errors.js';
+import { makeCollectionRef, makeDocRef } from './doc-ref.js';
+import { makeQuery } from './query.js';
+import { makeWriteBatch } from './batch.js';
+import { runRemoteTransaction } from './transaction.js';
+/** Canonical remediating throw for sync-only sandbox members that cannot
+ *  span the wire. Mirrors the slice-1 handle's error style. */
+function syncOnlyRemotely(member, remedy) {
+    return new SandboxError('unimplemented', `SandboxFirestore.${member} is not available on a remote sandbox — its return ` +
+        `value is synchronous and the data lives in the browser worker. ${remedy}`);
+}
+/**
+ * Build the channel-backed `SandboxFirestore` for a remote sandbox handle.
+ * `lens` is pinned on EVERY op and subscription (see the module header for
+ * the identity mapping); path-shape validation matches the local arm so
+ * `invalid-argument` failures surface at the call site without a
+ * round-trip.
+ */
+export function createRemoteFirestore(sandbox, lens) {
+    const arm = { sandbox, lens };
+    return {
+        // ── Production-shaped surface ────────────────────────────────────
+        collection(path) {
+            if (!isCollectionPath(path)) {
+                throw invalidArgument(`collection path must have an odd number of segments: ${path}`);
+            }
+            return makeCollectionRef(arm, path);
+        },
+        doc(path) {
+            if (!isDocumentPath(path)) {
+                throw invalidArgument(`document path must have an even number of segments: ${path}`);
+            }
+            return makeDocRef(arm, path);
+        },
+        collectionGroup(collectionId) {
+            if (collectionId.length === 0 || collectionId.includes('/')) {
+                throw invalidArgument(`collection group id must be a single non-empty segment with no '/': ${collectionId}`);
+            }
+            return makeQuery(arm, {
+                source: { __ref: 'group', collectionId },
+                filters: [],
+                orders: [],
+                limitFromEnd: false,
+            });
+        },
+        batch() {
+            return makeWriteBatch(arm);
+        },
+        runTransaction(fn, _opts) {
+            return runRemoteTransaction(arm, fn);
+        },
+        // ── Sandbox-only surface (sync contracts — remediating throws) ───
+        setRules() {
+            throw syncOnlyRemotely('setRules', "Deploy rules asynchronously through the relay instead: `await sandbox.channel.op({ method: 'setFirestoreRules', source })`.");
+        },
+        seed() {
+            throw syncOnlyRemotely('seed', 'The relay has no atomic seed op; write seed docs through this handle ' +
+                "(`db.doc(path).set(data)` / `db.batch()`), or drive `sandbox.channel.op({ method: 'admin.setDocument', path, data })` per document.");
+        },
+        snapshot() {
+            throw syncOnlyRemotely('snapshot', "Read the worker state asynchronously instead: `await sandbox.channel.op({ method: 'admin.readState' })`.");
+        },
+    };
+}
+//# sourceMappingURL=remote-firestore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-firestore.js","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/remote-firestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,YAAY,EAAqC,MAAM,eAAe,CAAC;AAShF,OAAO,EACL,gBAAgB,EAChB,cAAc,GACf,MAAM,uCAAuC,CAAC;AAG/C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD;+DAC+D;AAC/D,SAAS,gBAAgB,CAAC,MAAc,EAAE,MAAc;IACtD,OAAO,IAAI,YAAY,CACrB,eAAe,EACf,oBAAoB,MAAM,qDAAqD;QAC7E,kEAAkE,MAAM,EAAE,CAC7E,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAsB,EACtB,IAAc;IAEd,MAAM,GAAG,GAAc,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAEzC,OAAO;QACL,oEAAoE;QACpE,UAAU,CAAC,IAAY;YACrB,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5B,MAAM,eAAe,CAAC,wDAAwD,IAAI,EAAE,CAAC,CAAC;YACxF,CAAC;YACD,OAAO,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,GAAG,CAAC,IAAY;YACd,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,MAAM,eAAe,CAAC,uDAAuD,IAAI,EAAE,CAAC,CAAC;YACvF,CAAC;YACD,OAAO,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC/B,CAAC;QACD,eAAe,CAAC,YAAoB;YAClC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5D,MAAM,eAAe,CACnB,uEAAuE,YAAY,EAAE,CACtF,CAAC;YACJ,CAAC;YACD,OAAO,SAAS,CAAC,GAAG,EAAE;gBACpB,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE;gBACxC,OAAO,EAAE,EAAE;gBACX,MAAM,EAAE,EAAE;gBACV,YAAY,EAAE,KAAK;aACpB,CAAC,CAAC;QACL,CAAC;QACD,KAAK;YACH,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,cAAc,CACZ,EAAuC,EACvC,KAAwB;YAExB,OAAO,oBAAoB,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACvC,CAAC;QAED,oEAAoE;QACpE,QAAQ;YACN,MAAM,gBAAgB,CACpB,UAAU,EACV,6HAA6H,CAC9H,CAAC;QACJ,CAAC;QACD,IAAI;YACF,MAAM,gBAAgB,CACpB,MAAM,EACN,uEAAuE;gBACrE,qIAAqI,CACxI,CAAC;QACJ,CAAC;QACD,QAAQ;YACN,MAAM,gBAAgB,CACpB,UAAU,EACV,0GAA0G,CAC3G,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/sandbox/admin-firestore/remote/snapshots.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Admin-shaped one-shot snapshots for the remote arm — `getDoc`/`getDocs`
+ * results decoded from the wire into `DocumentSnapshot`/`QuerySnapshot`.
+ */
+import type { DocumentReference, DocumentSnapshot, QuerySnapshot } from 'pyric/sandbox/admin-compat';
+import type { RemoteArm } from './channel.js';
+import type { WireDocSnap, WireQuerySnap } from './wire-types.js';
+export declare function makeDocumentSnapshot(ref: DocumentReference, wire: WireDocSnap): DocumentSnapshot;
+export declare function makeQuerySnapshot(arm: RemoteArm, wire: WireQuerySnap): QuerySnapshot;
+//# sourceMappingURL=snapshots.d.ts.map

package/dist/sandbox/admin-firestore/remote/snapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/snapshots.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAEhB,aAAa,EACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAElE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,WAAW,GAAG,gBAAgB,CAQhG;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,aAAa,GAClB,aAAa,CAoBf"}

package/dist/sandbox/admin-firestore/remote/snapshots.js

@@ -0,0 +1,37 @@
+/**
+ * Admin-shaped one-shot snapshots for the remote arm — `getDoc`/`getDocs`
+ * results decoded from the wire into `DocumentSnapshot`/`QuerySnapshot`.
+ */
+import { decodeDocData } from './value-codec.js';
+import { makeDocRef } from './doc-ref.js';
+export function makeDocumentSnapshot(ref, wire) {
+    const data = wire.exists && wire.data ? decodeDocData(wire.data) : undefined;
+    return {
+        id: ref.id,
+        ref,
+        exists: wire.exists,
+        data: () => data,
+    };
+}
+export function makeQuerySnapshot(arm, wire) {
+    const docs = wire.docs.map((row) => {
+        const path = row.path ?? row.id;
+        const ref = makeDocRef(arm, path);
+        const data = row.data ? decodeDocData(row.data) : {};
+        return {
+            id: ref.id,
+            ref,
+            exists: true,
+            data: () => data,
+        };
+    });
+    return {
+        size: docs.length,
+        empty: docs.length === 0,
+        docs,
+        forEach(callback) {
+            docs.forEach((d) => callback(d));
+        },
+    };
+}
+//# sourceMappingURL=snapshots.js.map

package/dist/sandbox/admin-firestore/remote/snapshots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshots.js","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/snapshots.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,MAAM,UAAU,oBAAoB,CAAC,GAAsB,EAAE,IAAiB;IAC5E,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7E,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,GAAG;QACH,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI;KACjB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,GAAc,EACd,IAAmB;IAEnB,MAAM,IAAI,GAA4B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAC1D,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,OAAO;YACL,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,GAAG;YACH,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI;SACjB,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,MAAM;QACjB,KAAK,EAAE,IAAI,CAAC,MAAM,KAAK,CAAC;QACxB,IAAI;QACJ,OAAO,CAAC,QAA+C;YACrD,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/sandbox/admin-firestore/remote/transaction.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `Transaction` for the remote arm.
+ *
+ * TRANSACTIONS: the worker exposes no interactive transaction session; the
+ * protocol is optimistic — every `tx.get` is an ordinary `getDoc`/`getDocs`
+ * op recorded into a client-held read-set, and ONE `txnCommit` op ships
+ * `{ reads, writes }`. The worker re-reads each path inside a real sandbox
+ * transaction and compares SERIALIZED JSON STRINGS. The read-set therefore
+ * echoes the worker's ORIGINAL `SerializedDocData.json` strings verbatim —
+ * re-serializing rehydrated data on this side would risk cross-process
+ * key-order/format drift and phantom aborts (livelock under retry). On
+ * `{ code: 'aborted' }` the update function is re-run with a fresh
+ * transaction, up to {@link TXN_MAX_ATTEMPTS} attempts (the worker client's
+ * model, which itself matches the Firestore SDK default).
+ */
+import type { Transaction } from 'pyric/sandbox/admin-compat';
+import { type RemoteArm } from './channel.js';
+export declare function runRemoteTransaction<R>(arm: RemoteArm, fn: (tx: Transaction) => Promise<R> | R): Promise<R>;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/sandbox/admin-firestore/remote/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAMV,WAAW,EACZ,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AASrD,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,GAAG,EAAE,SAAS,EACd,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,CAAC,CAAC,CAyFZ"}

package/dist/sandbox/admin-firestore/remote/transaction.js

@@ -0,0 +1,105 @@
+/**
+ * `Transaction` for the remote arm.
+ *
+ * TRANSACTIONS: the worker exposes no interactive transaction session; the
+ * protocol is optimistic — every `tx.get` is an ordinary `getDoc`/`getDocs`
+ * op recorded into a client-held read-set, and ONE `txnCommit` op ships
+ * `{ reads, writes }`. The worker re-reads each path inside a real sandbox
+ * transaction and compares SERIALIZED JSON STRINGS. The read-set therefore
+ * echoes the worker's ORIGINAL `SerializedDocData.json` strings verbatim —
+ * re-serializing rehydrated data on this side would risk cross-process
+ * key-order/format drift and phantom aborts (livelock under retry). On
+ * `{ code: 'aborted' }` the update function is re-run with a fresh
+ * transaction, up to {@link TXN_MAX_ATTEMPTS} attempts (the worker client's
+ * model, which itself matches the Firestore SDK default).
+ */
+import { SandboxError } from 'pyric/sandbox';
+import { READ_AFTER_WRITE_MESSAGE } from '../../firestore/transaction-types.js';
+import { armOp } from './channel.js';
+import { encodeWriteData } from './value-codec.js';
+import { makeDocumentSnapshot, makeQuerySnapshot } from './snapshots.js';
+import { buildDescriptor, queryStateOf, validateExecutable } from './query.js';
+/** Matches the worker client's retry cap (and the Firestore SDK default). */
+const TXN_MAX_ATTEMPTS = 5;
+export async function runRemoteTransaction(arm, fn) {
+    for (let attempt = 0; attempt < TXN_MAX_ATTEMPTS; attempt++) {
+        // Fresh read-set + write buffer per attempt.
+        const reads = [];
+        const writes = [];
+        // READS-BEFORE-WRITES: the local arm's engine transaction throws
+        // `failed-precondition` (ReadAfterWriteError) when a read follows any
+        // write — the Admin SDK contract. The remote arm buffers writes
+        // client-side, so without this gate a `tx.get` after `tx.set` would
+        // issue a plain getDoc against PRE-transaction state and commit
+        // silently on stale data. Enforce the same contract, same message.
+        const assertReadsAllowed = () => {
+            if (writes.length > 0) {
+                throw new SandboxError('failed-precondition', READ_AFTER_WRITE_MESSAGE);
+            }
+        };
+        const tx = {
+            // Overloaded on the surface (doc ref vs query); runtime dispatch on
+            // the remote query brand — mirrors the local structural `isQuery`.
+            get(refOrQuery) {
+                assertReadsAllowed();
+                const state = queryStateOf(refOrQuery);
+                if (state !== undefined) {
+                    return txGetQuery(state);
+                }
+                return txGetDoc(refOrQuery);
+            },
+            set(ref, data) {
+                writes.push({ method: 'set', path: ref.path, data: encodeWriteData(data) });
+                return tx;
+            },
+            update(ref, data) {
+                writes.push({ method: 'update', path: ref.path, data: encodeWriteData(data) });
+                return tx;
+            },
+            delete(ref) {
+                writes.push({ method: 'delete', path: ref.path });
+                return tx;
+            },
+        };
+        async function txGetDoc(ref) {
+            const wire = (await armOp(arm, { method: 'getDoc', path: ref.path }));
+            // READ-SET INVARIANT: record the worker's ORIGINAL serialized
+            // envelope verbatim. The worker validates by re-serializing the
+            // current doc IN ITS OWN process and comparing JSON strings —
+            // echoing its bytes back is what keeps the comparison deterministic
+            // (re-serializing rehydrated data here would phantom-abort).
+            reads.push({
+                path: wire.path ?? ref.path,
+                data: wire.exists && wire.data ? wire.data : null,
+            });
+            return makeDocumentSnapshot(ref, wire);
+        }
+        async function txGetQuery(state) {
+            validateExecutable(state);
+            const wire = (await armOp(arm, {
+                method: 'getDocs',
+                source: buildDescriptor(state),
+            }));
+            // Register every returned doc in the read-set (the local arm's
+            // `simTx.getAll` registration) — again echoing the original bytes.
+            for (const row of wire.docs) {
+                reads.push({ path: row.path ?? row.id, data: row.data ?? null });
+            }
+            return makeQuerySnapshot(arm, wire);
+        }
+        const result = await fn(tx);
+        try {
+            await armOp(arm, { method: 'txnCommit', reads, writes });
+            return result;
+        }
+        catch (err) {
+            if (err instanceof SandboxError && err.code === 'aborted') {
+                continue; // read-set conflict — re-run fn with fresh reads
+            }
+            throw err;
+        }
+    }
+    throw new SandboxError('aborted', `Transaction failed after ${TXN_MAX_ATTEMPTS} attempts due to repeated conflicts. ` +
+        'Another writer is concurrently updating the same documents.');
+}
+//# sourceMappingURL=transaction.js.map

package/dist/sandbox/admin-firestore/remote/transaction.js.map

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

package/dist/sandbox/admin-firestore/remote/value-codec.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Value codec for the remote arm's wire — write-data encoding (client →
+ * wire marker forms) and read-data decoding (wire → compat shapes).
+ *
+ * VALUE CODEC: write payloads are encoded CLIENT-side to the plain-JSON
+ * marker forms the worker host rehydrates (`prepareWriteData`): admin
+ * `FieldValue` sentinels (`{ __type: 'increment', value }`) become wire
+ * `SentinelMarker`s (`{ __sentinel: 'increment', n }`), and Timestamp /
+ * Date / rules-wrapper scalars become their `toJSON()` marker shapes — so
+ * the worker STORES real typed values (rules comparisons and `orderBy`
+ * see a Timestamp, not a map). Read payloads arrive as the
+ * `SerializedDocData` JSON envelope and are rehydrated with the ONE shared
+ * codec (`pyric/firestore-values`' `rehydrateDocValue`) then translated to
+ * the compat field shapes (`translateReadData`) — the same shapes the
+ * local arm's read path yields.
+ *
+ * KNOWN CODEC DIVERGENCE (accepted): user data that happens to be SHAPED
+ * like a codec marker — a plain map such as `{ __type: 'timestamp',
+ * seconds, nanos }` or `{ type: 'firestore/timestamp/1.0', … }` — is
+ * TRANSMUTED into the real typed value on the relayed path (the host's
+ * `prepareWriteData` / constraint rehydration cannot tell an intentional
+ * marker from a lookalike), while an in-page `setDoc` of the same map
+ * stores a plain map. This is the persistence codec's own behavior (an
+ * IndexedDB save/reload transmutes the same shapes), so the relay is
+ * consistent with the sandbox's durability semantics rather than with
+ * the in-page live path — marker-shaped user data is already reserved
+ * vocabulary in this system.
+ */
+import { type DocumentData } from 'pyric/sandbox/admin-compat';
+import type { WireDocData } from './wire-types.js';
+/**
+ * Encode ONE value for the wire: sentinels → markers, typed scalars →
+ * their `toJSON()` marker shapes, containers walked recursively.
+ *
+ * Typed scalars are encoded EXPLICITLY (not left for a JSON leg to
+ * flatten) so the wire form is transport-independent — the same frames
+ * work over structured clone and over the double-JSON WS relay. The
+ * host's `prepareWriteData` rehydrates every marker family back into
+ * real wrapper instances before the write, which is what makes the
+ * worker STORE typed values (the spike's gap-4 semantics).
+ */
+export declare function encodeValue(v: unknown): unknown;
+export declare function encodeWriteData(data: DocumentData): unknown;
+/** Parse the JSON envelope with the shared codec, but keep the values in
+ *  their RULES-INTERNAL wrapper form (what the local engine stores). Used
+ *  where a downstream helper does its own compat translation. */
+export declare function decodeInternal(serialized: WireDocData): DocumentData;
+/** Full read-path decode: shared codec rehydration + the same
+ *  internal→compat field-shape translation the local arm applies
+ *  (`Timestamp{seconds,nanoseconds}`, not the rules wrapper). */
+export declare function decodeDocData(serialized: WireDocData): DocumentData;
+//# sourceMappingURL=value-codec.d.ts.map

package/dist/sandbox/admin-firestore/remote/value-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-codec.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/value-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsCnD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CA0B/C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAE3D;AAID;;iEAEiE;AACjE,wBAAgB,cAAc,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAEpE;AAED;;iEAEiE;AACjE,wBAAgB,aAAa,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAEnE"}