pyric 0.0.1 → 0.1.0-alpha.7

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAe/D,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,KAAK,EAEV,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAYpB,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,cAAc,CAAC;CAC3B;AAuQD;;;;GAIG;AACH,UAAU,MAAM;IACd,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;OAOG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,SAAU,YAAW,KAAK;IAEnC,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,gBAAgB;IACxC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW;IACpC,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM;IACzC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE;IAC7C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE;IACjD,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM;IACtC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO;IACxC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM;IACjC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM;IAK/B,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,OAAO;gBApBpB,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,WAAW,EACjB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,SAAS,MAAM,EAAO,EAC/B,MAAM,GAAE,SAAS,WAAW,EAAO,EACnC,UAAU,CAAC,EAAE,MAAM,YAAA;IACtC;;;;;;OAMG;IACgB,YAAY,GAAE,OAAe,EAC7B,KAAK,CAAC,EAAE,MAAM,YAAA,EACd,GAAG,CAAC,EAAE,MAAM,YAAA,EAKZ,WAAW,GAAE,OAAe;IAGjD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK;IAI9D,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK;IAIlC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,cAAsB,GAAG,KAAK;IAIhE,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,KAAK;IAIvB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,KAAK;IAI7B,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,GAAG,KAAK;IAIzD,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,GAAG,KAAK;IAIvD,uBAAuB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,SAAS,EAAE,OAAO,GAAG,KAAK;IAU9E,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,SAAS,EAAE,OAAO,GAAG,KAAK;IAU5E;;;;;OAKG;IACH,SAAS,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC;QACjC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3B,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;QAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,YAAY,EAAE,OAAO,CAAC;QACtB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;KACzB,CAAC,GAAG,SAAS;IAed;;;;;OAKG;IACH,SAAS,CAAC,gBAAgB,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE;IAQpE;;;;;OAKG;IACH,SAAS,CAAC,YAAY,IAAI,MAAM;IAIhC;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE;IAazF;;;;;;;;;;OAUG;IACH,SAAS,CAAC,qBAAqB,IAAI,gBAAgB;IAsBnD;;;;OAIG;IACH,SAAS,CAAC,gBAAgB,CACxB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,GAC3C;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE;IA+EzC;;;;;;;;;OASG;IACH,SAAS,CAAC,gBAAgB,IAAI,WAAW,EAAE;IAoB3C;;;;;;;;;;;;;OAaG;IACH,mBAAmB,IAAI,sBAAsB,GAAG,SAAS;IAenD,GAAG,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC;IAkCpD,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,sBAAsB,CAAC;CAU/F;AA4BD;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGpC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,SAAS,MAAM,EAAO,EAC/B,MAAM,GAAE,SAAS,WAAW,EAAO,EACnC,UAAU,CAAC,EAAE,MAAM,EACnB,YAAY,GAAE,OAAe,EAC7B,KAAK,CAAC,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,WAAW,GAAE,OAAe;IAQ9B;;;;;;OAMG;cACgB,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC;QAC1C,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3B,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;QAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,YAAY,EAAE,OAAO,CAAC;QACtB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;KACzB,CAAC,GAAG,SAAS;IAed;;;;;OAKG;cACgB,gBAAgB,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE;IAW7E;;;;;;OAMG;cACgB,YAAY,IAAI,MAAM;CAG1C;AAcD,qBAAa,iBAAkB,SAAQ,SAAU,YAAW,mBAAmB;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,GAAE,OAAe;IAMhG,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,iBAAiB;IAK7B,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAKnF"}