pyric 0.0.1 → 0.1.0-alpha.10

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

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

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

@@ -0,0 +1,47 @@
+/**
+ * `FirestoreImpl` — top-level Admin-SDK-compat handle backed by a
+ * `LocalEnvironment`.
+ *
+ * Path-shape validation lives at the input boundary so a typo'd path
+ * surfaces as `'invalid-argument'` rather than a downstream
+ * `'unimplemented'`/`'permission-denied'` blur. Slice 4 wires the
+ * remaining method bodies (batch, runTransaction).
+ *
+ * `runTransaction` carries two locked translations:
+ *
+ *   - **Divergence #4-A:** the simulator throws `ReadAfterWriteError`
+ *     (a plain `Error` subclass carrying `.simError`) when a tx reads
+ *     after writing. Translate the throw into a typed
+ *     `FirestoreCompatError { code: 'failed-precondition' }` so
+ *     callers can `if (e.code === 'failed-precondition')` without
+ *     instanceof-checking against an SDK-internal class.
+ *
+ *   - **Divergence #4-B:** the simulator's `transaction()` returns
+ *     `TransactionResult.allowed === false` (with a typed `error`)
+ *     when a queued write fails at commit (e.g., `tx.create` on an
+ *     existing doc). Surface the typed error directly so the
+ *     `'already-exists'` code reaches the caller.
+ *
+ * The `await` on the env.transaction call is load-bearing: bench
+ * wrapper line 195 documents that without it, an async callback
+ * leaves `result` as a Promise object whose `.allowed` is undefined,
+ * which we'd then misread as a denial.
+ *
+ * See the design rationale for slice contracts.
+ */
+import type { LocalEnvironment } from 'pyric/sandbox/internal';
+import type { EventProvenance } from '../../types/events.js';
+import { type AuthContext, type CollectionReference, type DocumentReference, type Firestore, type OperationOptions, type Query, type Transaction, type WriteBatch } from './types.js';
+export declare class FirestoreImpl implements Firestore {
+    private readonly env;
+    private readonly auth;
+    private readonly bypassRules;
+    private readonly provenance?;
+    constructor(env: LocalEnvironment, auth: AuthContext, bypassRules?: boolean, provenance?: EventProvenance | undefined);
+    collection(path: string): CollectionReference;
+    doc(path: string): DocumentReference;
+    collectionGroup(collectionId: string): Query;
+    batch(): WriteBatch;
+    runTransaction<R>(fn: (tx: Transaction) => Promise<R> | R, opts?: OperationOptions): Promise<R>;
+}
+//# sourceMappingURL=firestore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"firestore.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/firestore/admin-compat/firestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAQ7D,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,qBAAa,aAAc,YAAW,SAAS;IAE3C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAKrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;gBAPX,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,WAAW,EAKjB,WAAW,GAAE,OAAe,EAC5B,UAAU,CAAC,EAAE,eAAe,YAAA;IAG/C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB;IAY7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB;IAYpC,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,KAAK;IAc5C,KAAK,IAAI,UAAU;IAIb,cAAc,CAAC,CAAC,EACpB,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACvC,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,CAAC,CAAC;CA2Cd"}

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

@@ -0,0 +1,117 @@
+/**
+ * `FirestoreImpl` — top-level Admin-SDK-compat handle backed by a
+ * `LocalEnvironment`.
+ *
+ * Path-shape validation lives at the input boundary so a typo'd path
+ * surfaces as `'invalid-argument'` rather than a downstream
+ * `'unimplemented'`/`'permission-denied'` blur. Slice 4 wires the
+ * remaining method bodies (batch, runTransaction).
+ *
+ * `runTransaction` carries two locked translations:
+ *
+ *   - **Divergence #4-A:** the simulator throws `ReadAfterWriteError`
+ *     (a plain `Error` subclass carrying `.simError`) when a tx reads
+ *     after writing. Translate the throw into a typed
+ *     `FirestoreCompatError { code: 'failed-precondition' }` so
+ *     callers can `if (e.code === 'failed-precondition')` without
+ *     instanceof-checking against an SDK-internal class.
+ *
+ *   - **Divergence #4-B:** the simulator's `transaction()` returns
+ *     `TransactionResult.allowed === false` (with a typed `error`)
+ *     when a queued write fails at commit (e.g., `tx.create` on an
+ *     existing doc). Surface the typed error directly so the
+ *     `'already-exists'` code reaches the caller.
+ *
+ * The `await` on the env.transaction call is load-bearing: bench
+ * wrapper line 195 documents that without it, an async callback
+ * leaves `result` as a Promise object whose `.allowed` is undefined,
+ * which we'd then misread as a denial.
+ *
+ * See the design rationale for slice contracts.
+ */
+import { makeError } from 'pyric/sandbox/internal';
+import { ReadAfterWriteError } from 'pyric/sandbox/internal';
+import { isCollectionPath, isDocumentPath } from './paths.js';
+import { CollectionGroupQueryImpl, CollectionRefImpl } from './query.js';
+import { DocumentRefImpl } from './doc-ref.js';
+import { WriteBatchImpl } from './batch.js';
+import { TransactionImpl } from './transaction.js';
+import { FirestoreCompatError, } from './types.js';
+export class FirestoreImpl {
+    env;
+    auth;
+    bypassRules;
+    provenance;
+    constructor(env, auth, 
+    // Studio admin lens (Gap #2): when true, every op produced by this
+    // handle (and the refs/batch/tx it spawns) carries `bypassRules`, so
+    // the LocalEnvironment skips rule evaluation. Threaded down to each
+    // child impl alongside `auth`. Default false → rules enforced.
+    bypassRules = false, provenance) {
+        this.env = env;
+        this.auth = auth;
+        this.bypassRules = bypassRules;
+        this.provenance = provenance;
+    }
+    collection(path) {
+        if (!isCollectionPath(path)) {
+            throw new FirestoreCompatError(makeError('invalid-argument', `collection path must have an odd number of segments: ${path}`));
+        }
+        return new CollectionRefImpl(this.env, this.auth, path, this.bypassRules);
+    }
+    doc(path) {
+        if (!isDocumentPath(path)) {
+            throw new FirestoreCompatError(makeError('invalid-argument', `document path must have an even number of segments: ${path}`));
+        }
+        return new DocumentRefImpl(this.env, this.auth, path, this.bypassRules);
+    }
+    collectionGroup(collectionId) {
+        if (collectionId.length === 0 || collectionId.includes('/')) {
+            throw new FirestoreCompatError(makeError('invalid-argument', `collection group id must be a single non-empty segment with no '/': ${collectionId}`));
+        }
+        return new CollectionGroupQueryImpl(this.env, this.auth, collectionId, [], [], undefined, false, undefined, undefined, this.bypassRules);
+    }
+    batch() {
+        return new WriteBatchImpl(this.env, this.auth, this.bypassRules);
+    }
+    async runTransaction(fn, opts) {
+        let result;
+        try {
+            // The await is load-bearing: see header for the bench-line-195
+            // note. Sync-callback path collapses through the same await with
+            // no functional difference.
+            result = await this.env.transaction((simTx) => {
+                const tx = new TransactionImpl(simTx);
+                return fn(tx);
+            }, {
+                auth: opts?.auth !== undefined ? opts.auth : this.auth,
+                bypassRules: this.bypassRules,
+                provenance: this.provenance,
+            });
+        }
+        catch (e) {
+            // Divergence #4-A: ReadAfterWriteError → typed
+            // 'failed-precondition'. Other throws (callback throws, sentinel
+            // resolution errors that escape to here) propagate untouched —
+            // they aren't wrapper-translatable.
+            if (e instanceof ReadAfterWriteError) {
+                throw new FirestoreCompatError(e.simError);
+            }
+            throw e;
+        }
+        if (!result.allowed) {
+            // Divergence #4-B (and the broader denial case): the simulator
+            // attaches a typed `error` to any non-allowed result. Surface
+            // it directly so codes like 'already-exists' reach the caller.
+            if (result.error) {
+                throw new FirestoreCompatError(result.error);
+            }
+            // Defensive — should be unreachable under Item 6 invariant.
+            const denied = result.writes.find((w) => !w.allowed);
+            const msg = denied?.debugMessages.join('; ') ?? 'transaction denied at commit';
+            throw new FirestoreCompatError(makeError('permission-denied', `transaction failed: ${msg}`));
+        }
+        return result.returnValue;
+    }
+}
+//# sourceMappingURL=firestore.js.map

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

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

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

@@ -0,0 +1,49 @@
+/**
+ * Admin-SDK-compat Firestore wrapper for `LocalEnvironment`.
+ *
+ * Lets agent code written against the firebase-admin Firestore surface
+ * run unchanged against the SDK's local simulator. Design rationale +
+ * locked divergences live in the design rationale;
+ * implementation slicing in the design rationale.
+ *
+ * Slice 1: shipped public types + a stub `createCompatFirestore`.
+ * Slice 2 (this commit): real `FirestoreImpl` with path-shape validation
+ * on `collection`/`doc`. The collection/doc/batch/runTransaction bodies
+ * still throw `'unimplemented'` until slices 3 + 4 land — but the class
+ * shape is final and the path-validation errors users hit first are
+ * already typed correctly (`invalid-argument`, not `unimplemented`).
+ */
+import type { LocalEnvironment } from 'pyric/sandbox/internal';
+import type { EventProvenance } from '../../types/events.js';
+import { type AuthContext, type Firestore } from './types.js';
+export { FirestoreCompatError, FieldValue, Timestamp, } from './types.js';
+export type { AggregateField, AggregateQuerySnapshot, AggregateSpec, Filter, AuthContext, CollectionReference, DocumentData, DocumentReference, DocumentSnapshot, FieldValueSentinel, Firestore, FirestoreErrorCode, FirestoreEvalRequest, FirestoreEvalResource, FirestoreSimError, OperationOptions, OrderDirection, Query, QueryDocumentSnapshot, QuerySnapshot, SetOptions, Transaction, WhereFilterOp, WriteBatch, } from './types.js';
+export interface CreateCompatFirestoreOptions {
+    /**
+     * Default auth context applied to every operation. Per-op overrides
+     * land in slice 3 (constructor-default + per-op override pattern from
+     * divergence #6).
+     */
+    auth?: AuthContext;
+    /**
+     * Studio admin lens (Pyric Studio Gap #2). When `true`, the returned
+     * handle's operations BYPASS security rules — every read/write is
+     * treated as ALLOW (the modular-shaped equivalent of `sandbox.admin.*`).
+     * Storage preconditions and the event/listener path are unchanged; only
+     * rule evaluation is skipped. Default `false` → rules enforced under
+     * `auth`. Used by `getAdminFirestore` (see `pyric-admin` and
+     * `pyric/firestore`).
+     */
+    bypassRules?: boolean;
+    /** Adapter-bound operation identity. Internal constructor concern; never a
+     * Firebase operation option. */
+    provenance?: EventProvenance;
+}
+/**
+ * Construct an Admin-SDK-compat Firestore handle backed by a
+ * `LocalEnvironment`. Slice 2 returns a real `FirestoreImpl` with
+ * working path-shape validation; the per-method bodies still throw
+ * `'unimplemented'` until slices 3 + 4 land.
+ */
+export declare function createCompatFirestore(env: LocalEnvironment, opts?: CreateCompatFirestoreOptions): Firestore;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/firestore/admin-compat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,aAAa,EACb,MAAM,EACN,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,KAAK,EACL,qBAAqB,EACrB,aAAa,EACb,UAAU,EACV,WAAW,EACX,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;oCACgC;IAChC,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,gBAAgB,EACrB,IAAI,CAAC,EAAE,4BAA4B,GAClC,SAAS,CAOX"}

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

@@ -0,0 +1,27 @@
+/**
+ * Admin-SDK-compat Firestore wrapper for `LocalEnvironment`.
+ *
+ * Lets agent code written against the firebase-admin Firestore surface
+ * run unchanged against the SDK's local simulator. Design rationale +
+ * locked divergences live in the design rationale;
+ * implementation slicing in the design rationale.
+ *
+ * Slice 1: shipped public types + a stub `createCompatFirestore`.
+ * Slice 2 (this commit): real `FirestoreImpl` with path-shape validation
+ * on `collection`/`doc`. The collection/doc/batch/runTransaction bodies
+ * still throw `'unimplemented'` until slices 3 + 4 land — but the class
+ * shape is final and the path-validation errors users hit first are
+ * already typed correctly (`invalid-argument`, not `unimplemented`).
+ */
+import { FirestoreImpl } from './firestore.js';
+export { FirestoreCompatError, FieldValue, Timestamp, } from './types.js';
+/**
+ * Construct an Admin-SDK-compat Firestore handle backed by a
+ * `LocalEnvironment`. Slice 2 returns a real `FirestoreImpl` with
+ * working path-shape validation; the per-method bodies still throw
+ * `'unimplemented'` until slices 3 + 4 land.
+ */
+export function createCompatFirestore(env, opts) {
+    return new FirestoreImpl(env, opts?.auth ?? null, opts?.bypassRules ?? false, opts?.provenance);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/sandbox/firestore/admin-compat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAM/C,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAmDpB;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAqB,EACrB,IAAmC;IAEnC,OAAO,IAAI,aAAa,CACtB,GAAG,EACH,IAAI,EAAE,IAAI,IAAI,IAAI,EAClB,IAAI,EAAE,WAAW,IAAI,KAAK,EAC1B,IAAI,EAAE,UAAU,CACjB,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,37 @@
+/**
+ * Path helpers for the Admin-SDK-compat Firestore wrapper.
+ *
+ * Ported verbatim from bench's `pilot/src/firestore-wrapper.ts`
+ * (see the design rationale slice 2). Centralized
+ * here so `doc-ref.ts`, `query.ts`, and `firestore.ts` share one
+ * canonical segment-shape understanding — Admin SDK's even-segments-=-doc
+ * /odd-segments-=-collection convention is enforced at the wrapper's
+ * input boundary, before anything reaches `LocalEnvironment`.
+ */
+/**
+ * Split a Firestore path into segments, dropping leading/trailing
+ * slashes. Empty input yields `['']` (downstream callers treat that as
+ * an invalid path via the *Path predicates).
+ */
+export declare function pathSegments(path: string): string[];
+/**
+ * True iff `path` has an even, non-zero segment count — Admin SDK's
+ * shape rule for document paths (`collection/doc[/sub/doc]*`).
+ */
+export declare function isDocumentPath(path: string): boolean;
+/**
+ * True iff `path` has an odd segment count — Admin SDK's shape rule
+ * for collection paths (`collection[/doc/sub]*`).
+ */
+export declare function isCollectionPath(path: string): boolean;
+/**
+ * Last segment of `path`. Used to derive `DocumentReference.id` /
+ * `CollectionReference.id` from full paths.
+ */
+export declare function lastSegment(path: string): string;
+/**
+ * Drop the trailing segment of a document path to get the collection
+ * that contains it. Used by `DocumentReference.parent`.
+ */
+export declare function parentCollectionPath(docPath: string): string;
+//# sourceMappingURL=paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/firestore/admin-compat/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG5D"}

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

@@ -0,0 +1,49 @@
+/**
+ * Path helpers for the Admin-SDK-compat Firestore wrapper.
+ *
+ * Ported verbatim from bench's `pilot/src/firestore-wrapper.ts`
+ * (see the design rationale slice 2). Centralized
+ * here so `doc-ref.ts`, `query.ts`, and `firestore.ts` share one
+ * canonical segment-shape understanding — Admin SDK's even-segments-=-doc
+ * /odd-segments-=-collection convention is enforced at the wrapper's
+ * input boundary, before anything reaches `LocalEnvironment`.
+ */
+/**
+ * Split a Firestore path into segments, dropping leading/trailing
+ * slashes. Empty input yields `['']` (downstream callers treat that as
+ * an invalid path via the *Path predicates).
+ */
+export function pathSegments(path) {
+    return path.replace(/^\/+|\/+$/g, '').split('/');
+}
+/**
+ * True iff `path` has an even, non-zero segment count — Admin SDK's
+ * shape rule for document paths (`collection/doc[/sub/doc]*`).
+ */
+export function isDocumentPath(path) {
+    return pathSegments(path).length % 2 === 0 && pathSegments(path).length > 0;
+}
+/**
+ * True iff `path` has an odd segment count — Admin SDK's shape rule
+ * for collection paths (`collection[/doc/sub]*`).
+ */
+export function isCollectionPath(path) {
+    return pathSegments(path).length % 2 === 1;
+}
+/**
+ * Last segment of `path`. Used to derive `DocumentReference.id` /
+ * `CollectionReference.id` from full paths.
+ */
+export function lastSegment(path) {
+    const segs = pathSegments(path);
+    return segs[segs.length - 1] ?? '';
+}
+/**
+ * Drop the trailing segment of a document path to get the collection
+ * that contains it. Used by `DocumentReference.parent`.
+ */
+export function parentCollectionPath(docPath) {
+    const segs = pathSegments(docPath);
+    return segs.slice(0, -1).join('/');
+}
+//# sourceMappingURL=paths.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/sandbox/firestore/admin-compat/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrC,CAAC"}

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

@@ -0,0 +1,261 @@
+/**
+ * `QueryImpl` + `CollectionRefImpl` — Admin-SDK-compat query / collection
+ * surfaces backed by `LocalEnvironment.listDocuments(...)`.
+ *
+ * Ported from bench's `pilot/src/firestore-wrapper.ts:277-353`.
+ *
+ * Filtering is done JS-side because `listDocuments` returns the full
+ * collection unfiltered. That's the simulator's contract — it's a
+ * read-once snapshot, not a query engine — so the wrapper does the
+ * `where`/`orderBy`/`limit` work in memory before yielding snapshots.
+ *
+ * Differences from the bench source:
+ *   - Phantom parent docs (synthetic records the SDK injects for any
+ *     parent path that has descendants but no own data; see
+ *     `LocalEnvironment.listDocuments` JSDoc) are filtered OUT before
+ *     query results are returned. Phantom docs are a discover-crawler
+ *     affordance, not a query result — production Firestore would not
+ *     surface them in a `collection().get()` either.
+ *   - `compareValues` and `matchesWhere` use typed narrowing rather
+ *     than the bench's `as any` coercion. Same end result for
+ *     number/string/boolean/bigint fields (the only types the corpus
+ *     exercises today, per the design-doc inventory) and a deterministic
+ *     fallback (`String(...)` comparison) for cross-type cases.
+ *   - `firestoreValuesEqual` keeps query value matching aligned with
+ *     transform dedupe and Firestore value wrappers.
+ *
+ * Circular import note: `doc-ref.ts` imports `CollectionRefImpl` for
+ * `.parent` / `.collection(name)`; this file imports `DocumentRefImpl`
+ * for `CollectionRefImpl.doc()` and `QueryImpl.get()`. Both references
+ * sit inside method bodies (not class evaluation), so ESM's deferred
+ * binding resolves them correctly — no lazy-load machinery needed.
+ */
+import type { LocalEnvironment } from 'pyric/sandbox/internal';
+import type { QueryConstraints } from '../../../rules/simulator/query-proof.js';
+import type { QueryConstraintApplier } from '../snapshot-listeners.js';
+import { type AggregateQuerySnapshot, type AggregateSpec, type AuthContext, type CollectionReference, type DocumentData, type DocumentReference, type DocumentSnapshot, type Filter, type OperationOptions, type OrderDirection, type Query, type QuerySnapshot, type WhereFilterOp } from './types.js';
+interface OrderClause {
+    field: string;
+    direction: OrderDirection;
+}
+/**
+ * Cursor position along the orderBy fields. `values` is positional —
+ * `values[i]` compares against `orders[i].field`. `inclusive`
+ * distinguishes startAt/endAt (true) from startAfter/endBefore (false).
+ */
+interface Cursor {
+    values: readonly unknown[];
+    inclusive: boolean;
+    /**
+     * FS-B8 — whether this cursor was built from a `DocumentSnapshot`.
+     * Snapshot cursors position against the NORMALIZED orderBy (with the
+     * implicit `__name__` key), so they are legal without an explicit
+     * orderBy. VALUE cursors position against the EXPLICIT orderBy only and
+     * throw when they carry more values than explicit orderBy clauses
+     * (upstream `boundFromFields`: "Too many arguments").
+     */
+    fromSnapshot: boolean;
+}
+export declare class QueryImpl implements Query {
+    protected readonly env: LocalEnvironment;
+    protected readonly auth: AuthContext;
+    protected readonly collectionPath: string;
+    protected readonly clauses: readonly Filter[];
+    protected readonly orders: readonly OrderClause[];
+    protected readonly limitCount?: number | undefined;
+    /**
+     * When true, the query was built via `limitToLast(n)`. The
+     * `applyConstraints` pipeline reverses each orderBy direction
+     * before slicing and re-reverses afterwards. Requires at least
+     * one `orderBy` clause (the runtime check fires in `get()` /
+     * `aggregate()`).
+     */
+    protected readonly limitFromEnd: boolean;
+    protected readonly start?: Cursor | undefined;
+    protected readonly end?: Cursor | undefined;
+    protected readonly bypassRules: boolean;
+    constructor(env: LocalEnvironment, auth: AuthContext, collectionPath: string, clauses?: readonly Filter[], orders?: readonly OrderClause[], limitCount?: number | undefined, 
+    /**
+     * When true, the query was built via `limitToLast(n)`. The
+     * `applyConstraints` pipeline reverses each orderBy direction
+     * before slicing and re-reverses afterwards. Requires at least
+     * one `orderBy` clause (the runtime check fires in `get()` /
+     * `aggregate()`).
+     */
+    limitFromEnd?: boolean, start?: Cursor | undefined, end?: Cursor | undefined, bypassRules?: boolean);
+    where(field: string, op: WhereFilterOp, value: unknown): Query;
+    applyFilter(filter: Filter): Query;
+    orderBy(field: string, direction?: OrderDirection): Query;
+    limit(n: number): Query;
+    limitToLast(n: number): Query;
+    startCursor(values: unknown[], inclusive: boolean): Query;
+    endCursor(values: unknown[], inclusive: boolean): Query;
+    startCursorFromSnapshot(snapshot: DocumentSnapshot, inclusive: boolean): Query;
+    endCursorFromSnapshot(snapshot: DocumentSnapshot, inclusive: boolean): Query;
+    /**
+     * Build a fresh `QueryImpl` carrying the same identity (collectionPath,
+     * auth, env) plus the patches in `overrides`. Subclasses
+     * (`CollectionGroupQueryImpl`) override this to construct their own
+     * type so chained calls preserve the cross-collection semantics.
+     */
+    protected clone(overrides: Partial<{
+        clauses: readonly Filter[];
+        orders: readonly OrderClause[];
+        limitCount: number | undefined;
+        limitFromEnd: boolean;
+        start: Cursor | undefined;
+        end: Cursor | undefined;
+    }>): QueryImpl;
+    /**
+     * Hook subclasses (e.g. `CollectionGroupQueryImpl`) override to
+     * change WHERE docs come from. The default scans this query's
+     * `collectionPath` via `listDocuments`. Aggregations and `.get()`
+     * both run through this hook so they see the same candidate set.
+     */
+    protected gatherCandidates(): {
+        path: string;
+        data: DocumentData;
+    }[];
+    /**
+     * The collection path the `list` security rule evaluates against.
+     * Defaults to this query's `collectionPath`; `CollectionGroupQueryImpl`
+     * overrides it to the group-id match path so the group `list` rule
+     * fires. Used by {@link readCandidates}.
+     */
+    protected listRulePath(): string;
+    /**
+     * Gather candidates AND enforce security rules on the read (FS-B1 /
+     * RULES-B1). `get()` and `aggregate()` both run through this so query
+     * reads are rule-checked the same way `DocumentReference.get()` is — a
+     * deny-all rule set throws `permission-denied` instead of silently
+     * returning the whole collection.
+     *
+     * RULES-B11 — enforcement follows production's query-proof model
+     * ("rules are not filters"): the structured `where` constraints are
+     * threaded into {@link LocalEnvironment.readQueryCandidates} so a
+     * doc-data-dependent `list` rule the query's equalities discharge is
+     * ALLOWED, and an unprovable query is DENIED whole — never silently
+     * filtered to the readable subset.
+     *
+     * This is the auth-scoped read path. The raw, rules-bypassing
+     * {@link LocalEnvironment.listDocuments} stays reserved for explicit
+     * admin/crawler access (transaction read-sets, discover) — not exposed
+     * through the query surface.
+     */
+    protected readCandidates(opts?: OperationOptions): {
+        path: string;
+        data: DocumentData;
+    }[];
+    /**
+     * RULES-B11 — this query's constraints as DATA (vs. the opaque row
+     * transformer {@link applyConstraints} is). `where` carries every leaf
+     * equality/inequality reachable through top-level AND composition —
+     * the conjunctive spine, where each clause is unconditionally
+     * guaranteed for every returned doc. Clauses under an `or(...)` are
+     * NOT included (they guarantee nothing individually), and non-primitive
+     * operand values are skipped — both omissions are conservative: the
+     * proof can only fail to discharge a rule predicate (deny), never
+     * falsely discharge one.
+     */
+    protected structuredConstraints(): QueryConstraints;
+    /**
+     * Apply this query's clauses + orders + limit to a candidate set.
+     * Used by both `get()` and `aggregate()` so the filter logic
+     * stays single-sourced.
+     */
+    protected applyConstraints(rows: {
+        path: string;
+        data: DocumentData;
+    }[]): {
+        path: string;
+        data: DocumentData;
+    }[];
+    /**
+     * FS-B8 — the normalized sort order, mirroring upstream
+     * `core/query.ts:queryNormalizedOrderBy`:
+     *   1. explicit orderBy clauses as-is;
+     *   2. an implicit order on each inequality-filtered field not already
+     *      ordered (direction = last explicit direction, or asc);
+     *   3. a final `__name__` doc-key clause when the key is not explicitly
+     *      ordered, so equal-valued docs are deterministic and cursors can
+     *      disambiguate them.
+     */
+    protected normalizedOrders(): OrderClause[];
+    /**
+     * Public, side-effect-free view of this query's `where` / `orderBy` /
+     * cursor / `limit` constraints as a pure row transformer. The
+     * snapshot-listener path (FS-B2) threads this into the `SnapshotTarget`
+     * so a filtered/ordered/limited `onSnapshot(query(...))` delivers the
+     * same membership a one-shot `getDocs(query(...))` would — instead of
+     * the whole collection. Returns `undefined` when the query carries no
+     * constraints (a bare collection listen) so the listener path can skip
+     * the transform entirely.
+     *
+     * RULES-B11 — the applier also carries the structured constraints (see
+     * {@link structuredConstraints}) so the listener read path can run the
+     * query-proof gate against the matched `list` rule.
+     */
+    snapshotConstraints(): QueryConstraintApplier | undefined;
+    get(opts?: OperationOptions): Promise<QuerySnapshot>;
+    aggregate(spec: AggregateSpec, opts?: OperationOptions): Promise<AggregateQuerySnapshot>;
+}
+/**
+ * Cross-collection query — walks `env.snapshot()` (the in-memory
+ * keyspace) and returns every document whose immediate parent
+ * collection equals `collectionId`. Backs `Firestore.collectionGroup`.
+ *
+ * `collectionId` is matched on the second-to-last segment of each
+ * stored doc path. For doc `parents/X/items/Y`, segments are
+ * `[parents, X, items, Y]` so the parent collection is `items`.
+ *
+ * Inherits all `where` / `orderBy` / `limit` / `aggregate` plumbing
+ * from `QueryImpl`. Overrides only `gatherCandidates()` so the base
+ * class's get/aggregate machinery picks up the cross-collection scan
+ * automatically.
+ */
+export declare class CollectionGroupQueryImpl extends QueryImpl {
+    private readonly collectionId;
+    constructor(env: LocalEnvironment, auth: AuthContext, collectionId: string, clauses?: readonly Filter[], orders?: readonly OrderClause[], limitCount?: number, limitFromEnd?: boolean, start?: Cursor, end?: Cursor, bypassRules?: boolean);
+    /**
+     * Subclass clone: hand back a fresh `CollectionGroupQueryImpl`
+     * so chained calls (`where`, `applyFilter`, `orderBy`, `limit`,
+     * `limitToLast`, cursors) preserve the cross-collection
+     * identity. The base-class methods all dispatch through this
+     * hook — no per-method overrides needed.
+     */
+    protected clone(overrides: Partial<{
+        clauses: readonly Filter[];
+        orders: readonly OrderClause[];
+        limitCount: number | undefined;
+        limitFromEnd: boolean;
+        start: Cursor | undefined;
+        end: Cursor | undefined;
+    }>): QueryImpl;
+    /**
+     * Cross-collection candidate gathering. Walks the in-memory
+     * snapshot once and keeps docs whose immediate parent collection
+     * matches `collectionId`. Snapshot is a copy so iteration is safe
+     * even if writes interleave.
+     */
+    protected gatherCandidates(): {
+        path: string;
+        data: DocumentData;
+    }[];
+    /**
+     * Group reads span many parent collections, so there's no single
+     * concrete collection path to evaluate the `list` rule against. Use
+     * the group id as the representative match path — per-doc `get`
+     * enforcement (against each real candidate path) still runs, so a
+     * doc the caller can't read is dropped regardless of where it lives.
+     */
+    protected listRulePath(): string;
+}
+export declare class CollectionRefImpl extends QueryImpl implements CollectionReference {
+    readonly id: string;
+    readonly path: string;
+    constructor(env: LocalEnvironment, auth: AuthContext, path: string, bypassRules?: boolean);
+    doc(id?: string): DocumentReference;
+    add(data: DocumentData, opts?: OperationOptions): Promise<DocumentReference>;
+}
+export {};
+//# sourceMappingURL=query.d.ts.map

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

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