pyric 0.0.1 → 0.1.0-alpha.7

package/dist/rules/simulator/mapdiff.js

@@ -0,0 +1,72 @@
+/**
+ * MapDiff implementation for Firestore rules simulation.
+ *
+ * Implements request.resource.data.diff(resource.data) which returns
+ * a MapDiff object with methods for comparing two document states.
+ *
+ * Semantics derived from production Firestore behavior:
+ * - Only compares top-level keys (nested map diff is unreliable in production)
+ * - Values are compared with Firestore Rules value equality
+ * - Returns Set-like objects with hasOnly(), hasAll(), hasAny(), size()
+ */
+import { FirestoreSet } from './firestore-set.js';
+import { rulesValuesEqual } from './value-equality.js';
+export { FirestoreSet } from './firestore-set.js';
+export class MapDiff {
+    before;
+    after;
+    constructor(before, after) {
+        this.before = before;
+        this.after = after;
+    }
+    /** Keys present in `after` but not in `before`. */
+    addedKeys() {
+        const added = [];
+        for (const key of Object.keys(this.after)) {
+            if (!(key in this.before))
+                added.push(key);
+        }
+        return new FirestoreSet(added);
+    }
+    /** Keys present in `before` but not in `after`. */
+    removedKeys() {
+        const removed = [];
+        for (const key of Object.keys(this.before)) {
+            if (!(key in this.after))
+                removed.push(key);
+        }
+        return new FirestoreSet(removed);
+    }
+    /** Keys present in both but with different values. */
+    changedKeys() {
+        const changed = [];
+        for (const key of Object.keys(this.after)) {
+            if (key in this.before && !rulesValuesEqual(this.before[key], this.after[key])) {
+                changed.push(key);
+            }
+        }
+        return new FirestoreSet(changed);
+    }
+    /** Keys that were added, removed, or changed. Union of added + removed + changed. */
+    affectedKeys() {
+        const affected = [];
+        const allKeys = new Set([...Object.keys(this.before), ...Object.keys(this.after)]);
+        for (const key of allKeys) {
+            if (!(key in this.before) || !(key in this.after) || !rulesValuesEqual(this.before[key], this.after[key])) {
+                affected.push(key);
+            }
+        }
+        return new FirestoreSet(affected);
+    }
+    /** Keys present in both with identical values. */
+    unchangedKeys() {
+        const unchanged = [];
+        for (const key of Object.keys(this.before)) {
+            if (key in this.after && rulesValuesEqual(this.before[key], this.after[key])) {
+                unchanged.push(key);
+            }
+        }
+        return new FirestoreSet(unchanged);
+    }
+}
+//# sourceMappingURL=mapdiff.js.map

package/dist/rules/simulator/mapdiff.js.map

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

package/dist/rules/simulator/project-after-state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Item 0.D / Item 7 — single source of truth for the post-write document
+ * state under each WriteMode.
+ *
+ * Both `request.resource.data` (the data the rule sees) and
+ * `getAfter(path)` (the projected post-write doc) MUST agree. Routing
+ * everything through one function is the only way to make sure they
+ * never diverge as the merge semantics evolve.
+ *
+ * Per-mode semantics (matches admin SDK):
+ *   create               → after = payload (pre-state irrelevant; create
+ *                           fails if doc exists, but that's enforced by
+ *                           the test runner, not by this projection)
+ *   set { merge: false } → after = payload (full replace)
+ *   set { merge: true }  → after = recursive merge of pre and payload
+ *   update               → for each top-level key in payload:
+ *                           - if key contains '.', treat as field path:
+ *                             setNested(result, key.split('.'), value)
+ *                           - else: result[key] = value (entire replacement
+ *                             at that key, NOT recursive merge — this is
+ *                             the trap the 0.D hindsight describes)
+ *   delete               → after = null (doc is gone)
+ */
+import type { WriteMode } from '../test/spec.js';
+export type DocState = Record<string, unknown>;
+/**
+ * Project the after-state of a write. Returns null for `delete`.
+ *
+ * `existing` is the pre-write document state (typically `tc.resource`).
+ * `payload` is the write payload (typically `tc.data`).
+ */
+export declare function projectAfterState(mode: WriteMode, existing: DocState | null, payload: DocState): DocState | null;
+//# sourceMappingURL=project-after-state.d.ts.map

package/dist/rules/simulator/project-after-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-after-state.d.ts","sourceRoot":"","sources":["../../../src/rules/simulator/project-after-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA8E/C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,QAAQ,GAAG,IAAI,EACzB,OAAO,EAAE,QAAQ,GAChB,QAAQ,GAAG,IAAI,CAWjB"}

package/dist/rules/simulator/project-after-state.js

@@ -0,0 +1,88 @@
+/** Field-path segments that must never be walked or written. Because the
+ *  projected doc is a plain JS object, a segment named `__proto__` (or, as
+ *  defence-in-depth, `constructor`/`prototype`) would reach the shared
+ *  `Object.prototype` and let a rule-permitted `update`/`set` payload
+ *  pollute it process-wide (a field name arrives via JSON transports that
+ *  preserve `__proto__` as a genuine own key). These are never valid
+ *  Firestore-map segments in this projection, so rejecting them is a
+ *  sandbox-only safety constraint, not a parity regression. */
+const UNSAFE_SEGMENTS = new Set(['__proto__', 'prototype', 'constructor']);
+function assertSafeSegment(seg) {
+    if (UNSAFE_SEGMENTS.has(seg)) {
+        throw new Error(`Invalid field-path segment '${seg}': the keys __proto__, prototype, ` +
+            'and constructor are reserved and cannot appear in a field path.');
+    }
+}
+/** Recursive merge for set({merge: true}) — payload wins on leaf collisions. */
+function recursiveMerge(existing, payload) {
+    const out = { ...existing };
+    for (const [k, v] of Object.entries(payload)) {
+        assertSafeSegment(k);
+        const cur = Object.hasOwn(out, k) ? out[k] : undefined;
+        if (v !== null && typeof v === 'object' && !Array.isArray(v) &&
+            cur !== null && typeof cur === 'object' && !Array.isArray(cur)) {
+            out[k] = recursiveMerge(cur, v);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/** Set a value at a nested path (mutates `obj`). Used by update dot-paths.
+ *
+ *  A field path that traverses a non-map intermediate REPLACES that prefix with
+ *  a fresh map — this matches Firestore's updateDoc field-path semantics, where
+ *  `updateDoc(ref, {'a.b': 1})` on a string `a` overwrites `a` with `{b:1}`
+ *  (last-write-wins on the path prefix). (We intentionally do NOT throw here;
+ *  the RULES-B10 fix is the update *merge* in handler.ts, not this projection.) */
+function setNested(obj, path, value) {
+    let cur = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const seg = path[i];
+        assertSafeSegment(seg);
+        // Own-property read only: bare `cur[seg]` would resolve an unvalidated
+        // segment to the shared object prototype.
+        const next = Object.hasOwn(cur, seg) ? cur[seg] : undefined;
+        if (next === null || typeof next !== 'object' || Array.isArray(next)) {
+            cur[seg] = {};
+        }
+        cur = cur[seg];
+    }
+    const leaf = path[path.length - 1];
+    assertSafeSegment(leaf);
+    cur[leaf] = value;
+}
+/** Update mode: top-level keys replace; dot-paths patch nested maps. */
+function updateMerge(existing, payload) {
+    const out = { ...existing };
+    for (const [k, v] of Object.entries(payload)) {
+        if (k.includes('.')) {
+            setNested(out, k.split('.'), v);
+        }
+        else {
+            assertSafeSegment(k);
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/**
+ * Project the after-state of a write. Returns null for `delete`.
+ *
+ * `existing` is the pre-write document state (typically `tc.resource`).
+ * `payload` is the write payload (typically `tc.data`).
+ */
+export function projectAfterState(mode, existing, payload) {
+    switch (mode.kind) {
+        case 'create':
+            return payload;
+        case 'set':
+            return mode.merge ? recursiveMerge(existing ?? {}, payload) : payload;
+        case 'update':
+            return updateMerge(existing ?? {}, payload);
+        case 'delete':
+            return null;
+    }
+}
+//# sourceMappingURL=project-after-state.js.map

package/dist/rules/simulator/project-after-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-after-state.js","sourceRoot":"","sources":["../../../src/rules/simulator/project-after-state.ts"],"names":[],"mappings":"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"}

package/dist/rules/simulator/query-proof.d.ts

@@ -0,0 +1,80 @@
+/**
+ * RULES-B11 (rules-side) — query-proof evaluation for `list` operations.
+ *
+ * Production Firestore enforces "rules are NOT filters." For a query (`list`),
+ * the engine does not run the rule per-document and silently drop the docs that
+ * fail — it evaluates the rule ONCE against the query itself, and rejects the
+ * WHOLE query unless the rules can PROVE that every document the query could
+ * return is readable. A query the rules can't prove safe is denied outright (a
+ * `permission-denied` error), never silently truncated.
+ *
+ *   docs: https://firebase.google.com/docs/firestore/security/rules-query
+ *   "Rules are not filters … the query must be guaranteed to return only
+ *    documents that the rules allow the client to read. Otherwise the request
+ *    fails — even if the actual result set would have been allowed."
+ *
+ * THIS MODULE is the pure rules-side decision: given a collection's `list`
+ * allow-rule condition and the query's constraints, decide PROVABLE or REJECT.
+ * It is the function the firestore-track listener/read path
+ * (`sandbox/firestore/local-environment.ts:silentReadCollection`) should call
+ * INSTEAD of the current per-doc "rules-as-filters" loop — wiring that lives in
+ * T2's carve-out and is STOP-documented for hand-off (see the round-2 step doc).
+ *
+ * Scope of the proof here (the well-documented, decidable core):
+ *  - A `list` rule that does NOT depend on per-document data
+ *    (`resource.data.*`) — only `request.auth`, `request.query`, constants,
+ *    path variables — is doc-independent: if it evaluates ALLOW, EVERY doc is
+ *    equally allowed, so any query shape is provable.
+ *  - A rule that REQUIRES a per-document predicate (`resource.data.<field> ==
+ *    <const>`, conjoined into the condition) is provable ONLY IF the query
+ *    carries a `where(<field>, <op>, <const>)` constraint that guarantees the
+ *    same predicate. Otherwise the query could return a non-matching doc, so
+ *    prod rejects it — we return `provable: false`.
+ *
+ * Out of scope (documented as conservative REJECT, never a false ALLOW): rules
+ * with disjunctions over doc data, inequality/range proofs, function-inlined
+ * data predicates. When the rule's doc-dependence can't be discharged by a
+ * direct `where` equality match, we reject — the safe direction (prod also
+ * rejects an unprovable query).
+ */
+import type { Expression, FunctionDef } from '../grammar/FirestoreAST.js';
+/** A single `where(field, op, value)` constraint carried by the query. */
+export interface QueryWhereConstraint {
+    field: string;
+    op: string;
+    value: string | number | boolean | null;
+}
+/** The query constraints relevant to the proof. `where` is the load-bearing
+ *  one; limit/offset/orderBy are carried for completeness + future range
+ *  proofs (and already populate `request.query`). */
+export interface QueryConstraints {
+    where?: QueryWhereConstraint[];
+    limit?: number | null;
+    offset?: number | null;
+    orderBy?: string | null;
+}
+export type QueryProofResult = {
+    provable: true;
+    reason: string;
+} | {
+    provable: false;
+    reason: string;
+};
+/**
+ * Decide whether `listCondition` is PROVABLE for every doc the query could
+ * return, given its `constraints`. Pure — no evaluation context, no I/O.
+ *
+ * @param listCondition the `allow list/read` rule's condition AST (already the
+ *   specific list rule; OR-of-rules is the caller's concern — it asks per rule).
+ * @param constraints   the query's where/limit/offset/orderBy.
+ * @param fnMap         user-defined functions, for inlining doc-dependence checks.
+ */
+export declare function evaluateQueryProof(listCondition: Expression, constraints: QueryConstraints, fnMap?: Map<string, FunctionDef>): QueryProofResult;
+/**
+ * True if the expression depends on `resource.data` (the per-document data of
+ * the candidate doc) — directly or via an inlined user function. Mirrors the
+ * shape of `referencesRequestTime` in linter/ast-utils. `request.resource.data`
+ * (the WRITE payload) is NOT per-doc-read data, so it's intentionally excluded.
+ */
+export declare function referencesResourceData(expr: Expression, fnMap?: Map<string, FunctionDef>, visited?: Set<string>): boolean;
+//# sourceMappingURL=query-proof.d.ts.map

package/dist/rules/simulator/query-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-proof.d.ts","sourceRoot":"","sources":["../../../src/rules/simulator/query-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE1E,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACzC;AAED;;qDAEqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,UAAU,EACzB,WAAW,EAAE,gBAAgB,EAC7B,KAAK,GAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAa,GAC1C,gBAAgB,CA6ClB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,UAAU,EAChB,KAAK,GAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAa,EAC3C,OAAO,cAAoB,GAC1B,OAAO,CA+BT"}

package/dist/rules/simulator/query-proof.js

@@ -0,0 +1,142 @@
+/**
+ * Decide whether `listCondition` is PROVABLE for every doc the query could
+ * return, given its `constraints`. Pure — no evaluation context, no I/O.
+ *
+ * @param listCondition the `allow list/read` rule's condition AST (already the
+ *   specific list rule; OR-of-rules is the caller's concern — it asks per rule).
+ * @param constraints   the query's where/limit/offset/orderBy.
+ * @param fnMap         user-defined functions, for inlining doc-dependence checks.
+ */
+export function evaluateQueryProof(listCondition, constraints, fnMap = new Map()) {
+    // 1. Doc-independent rule → any query is provable. This is the common
+    //    `allow list: if request.auth != null` / `if true` case.
+    if (!referencesResourceData(listCondition, fnMap)) {
+        return {
+            provable: true,
+            reason: 'list rule does not depend on per-document data; every doc is equally readable',
+        };
+    }
+    // 2. Doc-dependent rule. Extract the per-doc equality predicates the rule
+    //    REQUIRES (top-level `&&` conjuncts of the form `resource.data.F == V`),
+    //    and check each is guaranteed by a matching `where` equality constraint.
+    const required = extractRequiredDataEqualities(listCondition);
+    if (required.length === 0) {
+        // The rule touches resource.data but not via a discharge-able top-level
+        // equality (e.g. inequality, disjunction, function-wrapped). Conservatively
+        // reject — prod also rejects a query it can't prove.
+        return {
+            provable: false,
+            reason: 'list rule depends on per-document data through a predicate the query cannot discharge ' +
+                '(only top-level `resource.data.field == value` conjunctions are provable here) — ' +
+                'prod rejects the whole query rather than filtering',
+        };
+    }
+    const wheres = constraints.where ?? [];
+    const unproven = required.filter(req => !wheres.some(w => w.field === req.field && w.op === '==' && valuesEqual(w.value, req.value)));
+    if (unproven.length > 0) {
+        const list = unproven.map(r => `resource.data.${r.field} == ${JSON.stringify(r.value)}`).join(', ');
+        return {
+            provable: false,
+            reason: `list rule requires [${list}] but the query has no matching where(...) ` +
+                `equality to guarantee it — prod rejects the query ("rules are not filters")`,
+        };
+    }
+    return {
+        provable: true,
+        reason: 'every per-document predicate the rule requires is guaranteed by a query where(...) constraint',
+    };
+}
+/**
+ * True if the expression depends on `resource.data` (the per-document data of
+ * the candidate doc) — directly or via an inlined user function. Mirrors the
+ * shape of `referencesRequestTime` in linter/ast-utils. `request.resource.data`
+ * (the WRITE payload) is NOT per-doc-read data, so it's intentionally excluded.
+ */
+export function referencesResourceData(expr, fnMap = new Map(), visited = new Set()) {
+    const check = (e) => {
+        switch (e.type) {
+            case 'memberAccess':
+                // `resource.data` (the bare `resource` identifier, not `request.resource`).
+                if (e.property === 'data' && e.object.type === 'identifier' && e.object.name === 'resource') {
+                    return true;
+                }
+                return check(e.object);
+            case 'bracketAccess':
+                return check(e.object) || check(e.index);
+            case 'functionCall':
+                if (fnMap.has(e.name) && !visited.has(e.name)) {
+                    visited.add(e.name);
+                    const fn = fnMap.get(e.name);
+                    if (referencesResourceData(fn.body, fnMap, visited))
+                        return true;
+                    if (fn.lets.some(b => referencesResourceData(b.value, fnMap, visited)))
+                        return true;
+                }
+                return e.args.some(check);
+            case 'binaryOp': return check(e.left) || check(e.right);
+            case 'unaryOp': return check(e.operand);
+            case 'methodCall': return check(e.object) || e.args.some(check);
+            case 'ternary': return check(e.condition) || check(e.consequent) || check(e.alternate);
+            case 'inExpr': return check(e.element) || check(e.collection);
+            case 'isExpr': return check(e.value);
+            case 'listLiteral': return e.elements.some(check);
+            case 'mapLiteral': return e.entries.some(en => check(en.key) || check(en.value));
+            default: return false;
+        }
+    };
+    return check(expr);
+}
+/**
+ * Pull out the per-doc EQUALITY predicates the rule requires: top-level `&&`
+ * conjuncts shaped `resource.data.<field> == <literal>` (either operand order).
+ * Only the conjunctive (AND) spine is walked — a disjunction (`||`) anywhere
+ * means the predicate isn't unconditionally required, so we don't extract from
+ * under it (the caller then conservatively rejects).
+ */
+function extractRequiredDataEqualities(expr) {
+    const out = [];
+    const walkAnd = (e) => {
+        if (e.type === 'binaryOp' && e.op === '&&') {
+            walkAnd(e.left);
+            walkAnd(e.right);
+            return;
+        }
+        const eq = asDataEquality(e);
+        if (eq)
+            out.push(eq);
+    };
+    walkAnd(expr);
+    return out;
+}
+/** Match `resource.data.<field> == <literal>` (either operand order) → constraint. */
+function asDataEquality(e) {
+    if (e.type !== 'binaryOp' || e.op !== '==')
+        return null;
+    const fromSide = (data, lit) => {
+        const field = dataFieldPath(data);
+        if (field !== null && lit.type === 'literal') {
+            return { field, op: '==', value: lit.value };
+        }
+        return null;
+    };
+    return fromSide(e.left, e.right) ?? fromSide(e.right, e.left);
+}
+/**
+ * If `e` is a single-segment `resource.data.<field>` access, return `<field>`;
+ * otherwise null. Nested paths (`resource.data.a.b`) aren't dischargeable by a
+ * flat `where('a.b', ...)` equality here, so they return null → reject.
+ */
+function dataFieldPath(e) {
+    if (e.type === 'memberAccess' &&
+        e.object.type === 'memberAccess' &&
+        e.object.property === 'data' &&
+        e.object.object.type === 'identifier' &&
+        e.object.object.name === 'resource') {
+        return e.property;
+    }
+    return null;
+}
+function valuesEqual(a, b) {
+    return a === b;
+}
+//# sourceMappingURL=query-proof.js.map

package/dist/rules/simulator/query-proof.js.map

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

package/dist/rules/simulator/value-equality.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Firestore Rules value equality.
+ *
+ * Rules wrappers and FirestoreSet own equality; lists and maps compare
+ * structurally, with map key order ignored.
+ */
+export declare function rulesValuesEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=value-equality.d.ts.map

package/dist/rules/simulator/value-equality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-equality.d.ts","sourceRoot":"","sources":["../../../src/rules/simulator/value-equality.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAiBhE"}

package/dist/rules/simulator/value-equality.js

@@ -0,0 +1,40 @@
+import { FirestoreSet } from './firestore-set.js';
+import { RulesValue } from './wrappers/base.js';
+/**
+ * Firestore Rules value equality.
+ *
+ * Rules wrappers and FirestoreSet own equality; lists and maps compare
+ * structurally, with map key order ignored.
+ */
+export function rulesValuesEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a instanceof RulesValue)
+        return a.equals(b);
+    if (b instanceof RulesValue)
+        return b.equals(a);
+    if (a instanceof FirestoreSet || b instanceof FirestoreSet) {
+        return a instanceof FirestoreSet && a.equals(b);
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((value, index) => rulesValuesEqual(value, b[index]));
+    }
+    if (!isRulesMapValue(a) || !isRulesMapValue(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => key in b && rulesValuesEqual(a[key], b[key]));
+}
+function isRulesMapValue(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=value-equality.js.map

package/dist/rules/simulator/value-equality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-equality.js","sourceRoot":"","sources":["../../../src/rules/simulator/value-equality.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAU,EAAE,CAAU;IACrD,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,YAAY,UAAU;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,YAAY,UAAU;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,YAAY,YAAY,IAAI,CAAC,YAAY,YAAY,EAAE,CAAC;QAC3D,OAAO,CAAC,YAAY,YAAY,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACzD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC"}

package/dist/rules/simulator/wrappers/base.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Wrapper class contract for Firestore Rules value types — see
+ * REBUILD_PLAN.md Item 0.B + Item 1.
+ *
+ * Why an abstract base instead of duck typing: the evaluator dispatches
+ * through six different code paths (rulesValuesEqual, memberAccess,
+ * bracketAccess, evaluateMethodCall, evaluateBinaryOp, isExpr, inExpr).
+ * Without a single base class, every new wrapper would have to be
+ * registered at six sites — and forgetting one is the exact failure mode
+ * 0.B is designed to prevent ("two `Timestamp` instances wrapping the
+ * same millis weren't `===`, so `request.time == otherTime` always
+ * denied in sim"). With this base class, every wrapper inherits all six
+ * dispatch hooks for free.
+ *
+ * Concrete subclasses (Timestamp, Duration, Bytes, LatLng) land in
+ * Item 1.1–1.4. Path lands in Item 5. This file is intentionally
+ * dead code until 1.1 — landing it first makes each wrapper sub-task
+ * a "fill in the blanks" exercise instead of a structural change.
+ */
+/**
+ * Sentinel returned by `binaryOp` / `callMethod` when the wrapper does
+ * not handle the requested operation/method. The evaluator interprets
+ * NO_OP as "fall through" — for `binaryOp` that means try the generic
+ * numeric path; for `callMethod` it means throw `UnsupportedError`.
+ *
+ * `Symbol.for` (registered symbol) survives module duplication that
+ * can happen across bun + esbuild + node test runners — `===` checks
+ * stay reliable even if `base.ts` is loaded under two different module
+ * specifiers.
+ */
+export declare const NO_OP: unique symbol;
+export type NoOp = typeof NO_OP;
+export declare abstract class RulesValue {
+    /**
+     * Stable type tag for `isExpr` dispatch — must match the names emitted
+     * by the parser for `is timestamp`, `is duration`, `is bytes`,
+     * `is latlng`, `is path`. Lowercase, single token.
+     */
+    abstract readonly typeName: string;
+    /**
+     * Numeric coercion for any code path that bypasses `binaryOp` and
+     * casts to number (legacy `as number` sites in evaluator.ts and any
+     * future `String(x)` / `Number(x)` calls). The 0.B per-wrapper table
+     * documents what each type returns:
+     *   Timestamp / Duration → seconds*1000 + Math.round(nanos/1e6) (millis)
+     *   Bytes                → data.length (byte count)
+     *   LatLng / Path        → NaN (no meaningful numeric coercion)
+     *
+     * Returning NaN for LatLng/Path is intentional — any rule that does
+     * arithmetic on them is buggy, and NaN propagation makes the failure
+     * loud rather than silent. The binary op hook (`binaryOp`) catches
+     * the supported cases above this fallback.
+     */
+    abstract valueOf(): number;
+    /**
+     * String coercion for map keys, regex args, path segments, the
+     * `string()` builtin, and template-style concatenation. Must
+     * round-trip through value-equality where the wrapper has a literal
+     * form: `parseRules(toString(x)).equals(x)` for Timestamp/Duration/
+     * LatLng/Path. Bytes is exempt (literal form is the base64 string,
+     * but the parser side will land with hashing.* in Item 5).
+     */
+    abstract toString(): string;
+    /**
+     * JSON-serializable form for debug output and any consumer that
+     * runs `JSON.stringify` on a TestResult. Returns a plain object with
+     * a `__type` discriminator so the serialized form is stable across
+     * releases — crucial for the parity stress harness's debugMessages.
+     */
+    abstract toJSON(): unknown;
+    /**
+     * Value equality. THE single source of truth for `==` / `!=` /
+     * `rulesValuesEqual`. `===` reference equality is intentionally
+     * insufficient (the 0.B failure: two `timestamp.value(1234)` calls
+     * produce two distinct instances; `===` is false; rule denies).
+     */
+    abstract equals(other: unknown): boolean;
+    /**
+     * Property access for `x.field` and `x[field]`. Default returns null
+     * (no such field) — the same shape Firestore rules use for missing
+     * map keys, so denial behavior is consistent.
+     *
+     * Wrappers override only for named properties they expose. Methods
+     * are NOT exposed via `field` — `x.size` evaluates the property to
+     * `null`, and `x.size()` goes through `callMethod` instead.
+     */
+    field(_name: string): unknown;
+    /**
+     * Method dispatch for `x.method(args)`. Default returns NO_OP — the
+     * evaluator turns NO_OP into `UnsupportedError`, which the handler
+     * maps to TestResult.state = 'UNSUPPORTED' (Item 0.A). That gives
+     * agents a clear "sim gap" signal rather than a silent DENY when a
+     * wrapper hasn't implemented a method yet.
+     *
+     * Wrappers override with a switch on `method` and dispatch to their
+     * own private methods. The dispatch table is intentionally not a
+     * `Record<string, Function>` — keeping it as a switch lets each
+     * wrapper apply its own arg validation and return-type promises
+     * inline rather than forcing a uniform signature.
+     */
+    callMethod(_method: string, _args: unknown[]): unknown | NoOp;
+    /**
+     * Cross-type binary operator dispatch. Default returns NO_OP — the
+     * evaluator falls through to generic numeric ops via `valueOf()`.
+     *
+     * Wrappers override for the operators they support. The 0.B
+     * "Required dispatch changes" table specifies the cross-type
+     * arithmetic each wrapper claims:
+     *   Timestamp + Duration → Timestamp
+     *   Timestamp - Timestamp → Duration
+     *   Timestamp - Duration → Timestamp
+     *   Duration ± Duration → Duration
+     *   Bytes < <= > >= Bytes → lexicographic byte compare
+     *
+     * `==` and `!=` do NOT route through this hook — they go through
+     * `rulesValuesEqual` which calls `equals()`. This split keeps the
+     * "is this the same value?" question separate from "what does
+     * `lhs OP rhs` evaluate to?".
+     *
+     * Dispatch is left-operand-only. For commutative ops where the
+     * right operand is a wrapper but the left isn't (e.g. `1 + duration`),
+     * the wrapper is responsible for handling reversed arguments via
+     * its own `binaryOp` when called from the right — the evaluator
+     * detects this by re-dispatching when `lv` isn't a wrapper but
+     * `rv` is, for the symmetric ops `==`, `!=`, `+`, `*`.
+     */
+    binaryOp(_op: string, _other: unknown): unknown | NoOp;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/rules/simulator/wrappers/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../src/rules/simulator/wrappers/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,EAAE,OAAO,MAAsD,CAAC;AAClF,MAAM,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC;AAEhC,8BAAsB,UAAU;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAEnC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,IAAI,MAAM;IAE1B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,IAAI,MAAM;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO;IAE1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAExC;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI7B;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,IAAI;IAI7D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;CAGvD"}