pyric 0.0.1 → 0.1.0-alpha.11

package/dist/firestore/sandbox/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 '../../../sandbox/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/firestore/sandbox/admin-compat/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/firestore/sandbox/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,kCAAkC,CAAC;AAExE,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/firestore/sandbox/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/firestore/sandbox/admin-compat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/firestore/sandbox/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/firestore/sandbox/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/firestore/sandbox/admin-compat/paths.d.ts.map

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

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

@@ -0,0 +1,269 @@
+/**
+ * `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;
+    /**
+     * Full executable identity for activity monitoring. The rules-proof
+     * projection above intentionally drops OR branches, rich operands, cursor
+     * detail, and most ordering, so it cannot safely identify repeated reads.
+     */
+    protected activityQuery(): unknown;
+    /** Distinguish direct-collection scans from collection-group scans. */
+    protected activityScope(): unknown;
+    /**
+     * 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. Bare collection listens retain a no-op applier so
+     * the activity monitor still receives their complete query identity.
+     *
+     * 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;
+    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;
+    protected activityScope(): unknown;
+}
+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/firestore/sandbox/admin-compat/query.d.ts.map

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