pyric 0.0.1 → 0.1.0-alpha.7

package/dist/rules/simulator/wrappers/float.js

@@ -0,0 +1,88 @@
+/**
+ * RULES-B5 — int/float type distinction in the rules value model.
+ *
+ * Firestore Security Rules (CEL) has two distinct numeric types, `int`
+ * (INT64) and `float` (FLOAT64). The JS host has only one `number`, so
+ * `1` and `1.0` are indistinguishable at the host level — which is why
+ * the pre-fix evaluator reported `1.5 is int` → true and `1 is float` →
+ * true, and did float division for `10 / 4` (→ 2.5, where prod truncates
+ * int÷int to 2). See findings-ledger RULES-B5.
+ *
+ * The fix tags FLOAT values with this lightweight wrapper while bare JS
+ * `number` continues to mean `int`. Why wrap floats (not ints): integers
+ * are overwhelmingly the common case in rules data (counts, sizes, list
+ * indices, `request.time` millis), and every existing `typeof x ===
+ * 'number'` site already treats a bare number as an int — so wrapping the
+ * rarer float keeps the blast radius small. The evaluator unwraps floats
+ * at arithmetic/comparison boundaries via `numericValue()` and re-tags
+ * the result when either operand was a float.
+ *
+ * `is float` ↔ `value instanceof RulesFloat`; `is int` ↔ bare number.
+ * `string()` of a float keeps its decimal (`string(1.0)` → "1.0").
+ *
+ * Doc/oracle: https://firebase.google.com/docs/reference/rules/rules.Float
+ * (distinct Float type) + the CEL int/float division spec (int÷int
+ * truncates, int÷0 errors, float÷0 → NaN).
+ */
+import { RulesValue, NO_OP } from './base.js';
+export class RulesFloat extends RulesValue {
+    typeName = 'float';
+    value;
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+    /** Numeric coercion — float arithmetic unwraps to this raw double. */
+    valueOf() {
+        return this.value;
+    }
+    /**
+     * `string()` of a float keeps a decimal point so the int/float
+     * distinction survives the cast: `string(1.0)` → "1.0", not "1".
+     * Non-integral floats stringify naturally (`string(1.5)` → "1.5").
+     */
+    toString() {
+        return Number.isInteger(this.value) ? `${this.value}.0` : String(this.value);
+    }
+    toJSON() {
+        return { __type: 'float', value: this.value };
+    }
+    equals(other) {
+        // CEL compares int and float by numeric value (`1 == 1.0` → true), so
+        // equality unwraps both sides rather than gating on `instanceof`.
+        if (other instanceof RulesFloat)
+            return this.value === other.value;
+        if (typeof other === 'number')
+            return this.value === other;
+        return false;
+    }
+    /**
+     * Float participates in arithmetic/comparison against bare-number ints
+     * and other floats. A float operand always yields a float result (CEL
+     * has no int÷float→int narrowing); division by zero is FLOAT division so
+     * it produces NaN (caller decides storeability) rather than erroring the
+     * way int÷0 does. NO_OP for any non-numeric operand so the evaluator's
+     * type-mismatch guard surfaces e.g. `1.5 + 'a'` as a real error.
+     */
+    binaryOp(op, other) {
+        const r = other instanceof RulesFloat ? other.value
+            : typeof other === 'number' ? other
+                : undefined;
+        if (r === undefined)
+            return NO_OP;
+        const l = this.value;
+        switch (op) {
+            case '+': return new RulesFloat(l + r);
+            case '-': return new RulesFloat(l - r);
+            case '*': return new RulesFloat(l * r);
+            case '/': return new RulesFloat(l / r); // float ÷ 0 → ±Infinity / NaN
+            case '%': return new RulesFloat(l % r);
+            case '<': return l < r;
+            case '<=': return l <= r;
+            case '>': return l > r;
+            case '>=': return l >= r;
+            default: return NO_OP;
+        }
+    }
+}
+//# sourceMappingURL=float.js.map

package/dist/rules/simulator/wrappers/float.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"float.js","sourceRoot":"","sources":["../../../../src/rules/simulator/wrappers/float.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAa,MAAM,WAAW,CAAC;AAEzD,MAAM,OAAO,UAAW,SAAQ,UAAU;IAC/B,QAAQ,GAAG,OAAO,CAAC;IACnB,KAAK,CAAS;IAEvB,YAAY,KAAa;QACvB,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,sEAAsE;IACtE,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACN,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/E,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,KAAc;QACnB,sEAAsE;QACtE,kEAAkE;QAClE,IAAI,KAAK,YAAY,UAAU;YAAE,OAAO,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC;QACnE,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC;QAC3D,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAU,EAAE,KAAc;QACjC,MAAM,CAAC,GACL,KAAK,YAAY,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK;YACzC,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK;gBACnC,CAAC,CAAC,SAAS,CAAC;QACd,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAClC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;QACrB,QAAQ,EAAE,EAAE,CAAC;YACX,KAAK,GAAG,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACvC,KAAK,GAAG,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACvC,KAAK,GAAG,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACvC,KAAK,GAAG,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,8BAA8B;YACtE,KAAK,GAAG,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACvC,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACzB,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACzB,OAAO,CAAC,CAAC,OAAO,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,40 @@
+/**
+ * LatLng wrapper for Firestore Rules `latlng` type — Item 1.1.
+ *
+ * Closes the LatLng type gap from REBUILD_PLAN.md "Current Evaluator Gap
+ * Analysis" — instance methods + the `latlng.value(lat, lng)` namespace
+ * constructor (was the entire `latlng` namespace gap).
+ *
+ * Reference surface (from REBUILD_PLAN.md "Reference Inventory"):
+ *   - latitude() → Float, range [-90, 90]
+ *   - longitude() → Float, range [-180, 180]
+ *   - distance(other: LatLng) → Float, meters
+ *   - Operators: == != only (no arithmetic — see RulesValue.binaryOp note)
+ *
+ * Construction: `latlng.value(lat, lng)` only. Production also accepts
+ * stored LatLng values from Firestore documents, but that path requires
+ * test-data sentinels we haven't introduced yet — single-source
+ * construction in 1.1 keeps the wrapper testable end-to-end.
+ */
+import { RulesValue, type NoOp } from './base.js';
+export declare class LatLng extends RulesValue {
+    readonly typeName = "latlng";
+    readonly lat: number;
+    readonly lng: number;
+    constructor(lat: number, lng: number);
+    /**
+     * NaN — LatLng has no meaningful numeric coercion. The 0.B contract
+     * documents this explicitly: any rule that does arithmetic on a
+     * LatLng (e.g. `latlng + 1`) is buggy, and NaN propagation makes
+     * the failure loud rather than silent. The `binaryOp` override
+     * below also returns NO_OP for everything except `==`/`!=` (which
+     * route through `equals()` not `binaryOp`), so arithmetic falls
+     * through to the generic numeric path → NaN → comparison fails.
+     */
+    valueOf(): number;
+    toString(): string;
+    toJSON(): unknown;
+    equals(other: unknown): boolean;
+    callMethod(method: string, args: unknown[]): unknown | NoOp;
+}
+//# sourceMappingURL=latlng.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"latlng.d.ts","sourceRoot":"","sources":["../../../../src/rules/simulator/wrappers/latlng.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAS,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AA0BzD,qBAAa,MAAO,SAAQ,UAAU;IACpC,QAAQ,CAAC,QAAQ,YAAY;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;IAUpC;;;;;;;;OAQG;IACH,OAAO,IAAI,MAAM;IAIjB,QAAQ,IAAI,MAAM;IAIlB,MAAM,IAAI,OAAO;IAIjB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAQ/B,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,IAAI;CA2B5D"}

package/dist/rules/simulator/wrappers/latlng.js

@@ -0,0 +1,100 @@
+/**
+ * LatLng wrapper for Firestore Rules `latlng` type — Item 1.1.
+ *
+ * Closes the LatLng type gap from REBUILD_PLAN.md "Current Evaluator Gap
+ * Analysis" — instance methods + the `latlng.value(lat, lng)` namespace
+ * constructor (was the entire `latlng` namespace gap).
+ *
+ * Reference surface (from REBUILD_PLAN.md "Reference Inventory"):
+ *   - latitude() → Float, range [-90, 90]
+ *   - longitude() → Float, range [-180, 180]
+ *   - distance(other: LatLng) → Float, meters
+ *   - Operators: == != only (no arithmetic — see RulesValue.binaryOp note)
+ *
+ * Construction: `latlng.value(lat, lng)` only. Production also accepts
+ * stored LatLng values from Firestore documents, but that path requires
+ * test-data sentinels we haven't introduced yet — single-source
+ * construction in 1.1 keeps the wrapper testable end-to-end.
+ */
+import { RulesValue, NO_OP } from './base.js';
+/**
+ * Distance between two points on Earth, in meters, via the haversine
+ * formula. Production uses WGS-84 ellipsoid math which differs from
+ * haversine by up to ~0.5%. We accept that drift for Item 1 — the
+ * parity pack covers exact-equality and same-point cases (where
+ * haversine == ellipsoid == 0); long-distance precision parity is
+ * deferred until a real-world rule surfaces a discrepancy in the
+ * benchmark divergence log. If/when that happens, swap the
+ * implementation here without touching the wrapper's interface.
+ */
+function haversineMeters(latA, lngA, latB, lngB) {
+    const R = 6371000; // mean Earth radius in meters
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const φ1 = toRad(latA);
+    const φ2 = toRad(latB);
+    const Δφ = toRad(latB - latA);
+    const Δλ = toRad(lngB - lngA);
+    const a = Math.sin(Δφ / 2) ** 2 +
+        Math.cos(φ1) * Math.cos(φ2) * Math.sin(Δλ / 2) ** 2;
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+}
+export class LatLng extends RulesValue {
+    typeName = 'latlng';
+    lat;
+    lng;
+    constructor(lat, lng) {
+        super();
+        // Don't validate range here — production accepts out-of-range values
+        // via stored data and only the namespace constructor `latlng.value`
+        // would raise. Keeping the wrapper itself permissive lets storage
+        // and constructor paths share the same class without divergence.
+        this.lat = lat;
+        this.lng = lng;
+    }
+    /**
+     * NaN — LatLng has no meaningful numeric coercion. The 0.B contract
+     * documents this explicitly: any rule that does arithmetic on a
+     * LatLng (e.g. `latlng + 1`) is buggy, and NaN propagation makes
+     * the failure loud rather than silent. The `binaryOp` override
+     * below also returns NO_OP for everything except `==`/`!=` (which
+     * route through `equals()` not `binaryOp`), so arithmetic falls
+     * through to the generic numeric path → NaN → comparison fails.
+     */
+    valueOf() {
+        return NaN;
+    }
+    toString() {
+        return `${this.lat},${this.lng}`;
+    }
+    toJSON() {
+        return { __type: 'latlng', lat: this.lat, lng: this.lng };
+    }
+    equals(other) {
+        return (other instanceof LatLng &&
+            this.lat === other.lat &&
+            this.lng === other.lng);
+    }
+    callMethod(method, args) {
+        switch (method) {
+            case 'latitude':
+                return this.lat;
+            case 'longitude':
+                return this.lng;
+            case 'distance': {
+                const other = args[0];
+                if (!(other instanceof LatLng)) {
+                    // Real type error, not a sim gap — caller throws EvalError, not
+                    // UnsupportedError. Returning NO_OP would mask the type bug as
+                    // "method not implemented", which is wrong: we *did* implement
+                    // distance, the caller passed garbage.
+                    throw new TypeError(`latlng.distance() requires a LatLng argument, got ${typeof other}`);
+                }
+                return haversineMeters(this.lat, this.lng, other.lat, other.lng);
+            }
+            default:
+                return NO_OP;
+        }
+    }
+}
+//# sourceMappingURL=latlng.js.map

package/dist/rules/simulator/wrappers/latlng.js.map

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

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

@@ -0,0 +1,75 @@
+/**
+ * Path wrapper — Item 5.4 of REBUILD_PLAN.md.
+ *
+ * Reference surface (rules.Path):
+ *   bind(map: Map) → Path    substitutes {placeholder} segments; null vals reject
+ *   Operators: ==, dot x.f, numeric x[i], named x[name]
+ *   Constructed via literal `/path/to/resource` or `path("path/to/resource")`
+ *
+ * Per 0.B per-wrapper table:
+ *   typeName: 'path'
+ *   valueOf:  NaN          (no meaningful numeric coercion)
+ *   toString: '/seg1/seg2' (round-trips with literal form)
+ *   equals:   segment-by-segment string equality
+ *   binaryOp: NO_OP (== / != route through equals; no <,> on paths)
+ *
+ * Path was deferred from Item 1 because its only construction site is the
+ * `path()` builtin (Item 5) and the `/foo/$(x)/` literal form. Landing the
+ * wrapper now lets `pathLiteral` evaluation flip from "string" to "Path"
+ * so `is path` works correctly without breaking get/exists (which already
+ * String()-coerce their argument).
+ *
+ * Segments may include `{name}` placeholders. `bind()` replaces them in
+ * one shot, returning a fresh Path. The wrapper does NOT enforce that
+ * all placeholders are bound — leaving that to the consumer (get/exists)
+ * makes parity behavior obvious: an unbound path renders as "/users/{uid}"
+ * and the resolver returns null.
+ */
+import { RulesValue, type NoOp } from './base.js';
+export declare class Path extends RulesValue {
+    readonly typeName = "path";
+    /** Resolved-or-placeholder segments. A segment like '{uid}' is unbound. */
+    readonly segments: readonly string[];
+    /**
+     * Named-segment bindings — populated either by `bind()` (which records the
+     * name → value pair when substituting `{name}` placeholders) or by the
+     * handler when constructing `request.path` from a matched rule path
+     * (so `request.path.uid` returns the wildcard value from the matched
+     * `match /users/{uid}/...` block).
+     *
+     * Without this, `field('uid')` on a fully-bound Path returned null and
+     * any rule reading named segments off `request.path` silently denied.
+     */
+    readonly bindings: Readonly<Record<string, string>>;
+    constructor(segments: readonly string[], bindings?: Record<string, string>);
+    /** Construct from a string like '/users/alice' or 'users/{uid}/posts'. */
+    static fromString(s: string): Path;
+    /**
+     * Replace `{name}` placeholders with values from `bindings`. Returns
+     * a fresh Path. If a binding value is null/undefined, throws — matches
+     * the rules.Path.bind() contract that "values must not be null".
+     *
+     * Passing a binding whose placeholder doesn't exist in the path is
+     * silently allowed (consistent with how the spec says binding by extra
+     * keys has no effect).
+     */
+    bind(bindings: Record<string, unknown>): Path;
+    valueOf(): number;
+    toString(): string;
+    toJSON(): unknown;
+    equals(other: unknown): boolean;
+    /**
+     * Bracket / dot field dispatch.
+     *
+     * Numeric string ('0', '1', ...) → returns the segment at that index,
+     * null if out of bounds. The evaluator funnels both `p[0]` and `p[i]`
+     * here as `String(idx)`.
+     *
+     * Named ('uid', etc.) → returns the value from `bindings`, populated
+     * either by `bind()` or by the handler when constructing `request.path`
+     * from a matched-rule path. Returns null if the name was never bound.
+     */
+    field(name: string): unknown;
+    callMethod(method: string, args: unknown[]): unknown | NoOp;
+}
+//# sourceMappingURL=path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../../src/rules/simulator/wrappers/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,UAAU,EAAS,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAKzD,qBAAa,IAAK,SAAQ,UAAU;IAClC,QAAQ,CAAC,QAAQ,UAAU;IAE3B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;gBAExC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM;IAM9E,0EAA0E;IAC1E,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAOlC;;;;;;;;OAQG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA6B7C,OAAO,IAAI,MAAM;IAIjB,QAAQ,IAAI,MAAM;IAIlB,MAAM,IAAI,OAAO;IAIjB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAS/B;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAgB5B,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,IAAI;CAe5D"}

package/dist/rules/simulator/wrappers/path.js

@@ -0,0 +1,158 @@
+/**
+ * Path wrapper — Item 5.4 of REBUILD_PLAN.md.
+ *
+ * Reference surface (rules.Path):
+ *   bind(map: Map) → Path    substitutes {placeholder} segments; null vals reject
+ *   Operators: ==, dot x.f, numeric x[i], named x[name]
+ *   Constructed via literal `/path/to/resource` or `path("path/to/resource")`
+ *
+ * Per 0.B per-wrapper table:
+ *   typeName: 'path'
+ *   valueOf:  NaN          (no meaningful numeric coercion)
+ *   toString: '/seg1/seg2' (round-trips with literal form)
+ *   equals:   segment-by-segment string equality
+ *   binaryOp: NO_OP (== / != route through equals; no <,> on paths)
+ *
+ * Path was deferred from Item 1 because its only construction site is the
+ * `path()` builtin (Item 5) and the `/foo/$(x)/` literal form. Landing the
+ * wrapper now lets `pathLiteral` evaluation flip from "string" to "Path"
+ * so `is path` works correctly without breaking get/exists (which already
+ * String()-coerce their argument).
+ *
+ * Segments may include `{name}` placeholders. `bind()` replaces them in
+ * one shot, returning a fresh Path. The wrapper does NOT enforce that
+ * all placeholders are bound — leaving that to the consumer (get/exists)
+ * makes parity behavior obvious: an unbound path renders as "/users/{uid}"
+ * and the resolver returns null.
+ */
+import { RulesValue, NO_OP } from './base.js';
+/** Recognises {name} placeholders. Spec is restrictive: identifier chars only. */
+const PLACEHOLDER = /^\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+export class Path extends RulesValue {
+    typeName = 'path';
+    /** Resolved-or-placeholder segments. A segment like '{uid}' is unbound. */
+    segments;
+    /**
+     * Named-segment bindings — populated either by `bind()` (which records the
+     * name → value pair when substituting `{name}` placeholders) or by the
+     * handler when constructing `request.path` from a matched rule path
+     * (so `request.path.uid` returns the wildcard value from the matched
+     * `match /users/{uid}/...` block).
+     *
+     * Without this, `field('uid')` on a fully-bound Path returned null and
+     * any rule reading named segments off `request.path` silently denied.
+     */
+    bindings;
+    constructor(segments, bindings = {}) {
+        super();
+        this.segments = segments;
+        this.bindings = bindings;
+    }
+    /** Construct from a string like '/users/alice' or 'users/{uid}/posts'. */
+    static fromString(s) {
+        // Leading slash is conventional but optional; trim either way.
+        const trimmed = s.startsWith('/') ? s.slice(1) : s;
+        if (trimmed.length === 0)
+            return new Path([]);
+        return new Path(trimmed.split('/'));
+    }
+    /**
+     * Replace `{name}` placeholders with values from `bindings`. Returns
+     * a fresh Path. If a binding value is null/undefined, throws — matches
+     * the rules.Path.bind() contract that "values must not be null".
+     *
+     * Passing a binding whose placeholder doesn't exist in the path is
+     * silently allowed (consistent with how the spec says binding by extra
+     * keys has no effect).
+     */
+    bind(bindings) {
+        const next = [];
+        const nextBindings = { ...this.bindings };
+        for (const seg of this.segments) {
+            const m = seg.match(PLACEHOLDER);
+            if (!m) {
+                next.push(seg);
+                continue;
+            }
+            const name = m[1];
+            if (name in bindings) {
+                const v = bindings[name];
+                if (v === null || v === undefined) {
+                    throw new TypeError(`Path.bind(): binding '${name}' must not be null`);
+                }
+                const sv = String(v);
+                next.push(sv);
+                nextBindings[name] = sv;
+            }
+            else {
+                // Unbound — preserve the placeholder. get/exists will see the
+                // literal `{name}` and the resolver will return null.
+                next.push(seg);
+            }
+        }
+        return new Path(next, nextBindings);
+    }
+    // ─── RulesValue contract ─────────────────────────────────────────────
+    valueOf() {
+        return NaN; // No meaningful numeric coercion (matches LatLng).
+    }
+    toString() {
+        return '/' + this.segments.join('/');
+    }
+    toJSON() {
+        return { __type: 'path', segments: [...this.segments] };
+    }
+    equals(other) {
+        if (!(other instanceof Path))
+            return false;
+        if (this.segments.length !== other.segments.length)
+            return false;
+        for (let i = 0; i < this.segments.length; i++) {
+            if (this.segments[i] !== other.segments[i])
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Bracket / dot field dispatch.
+     *
+     * Numeric string ('0', '1', ...) → returns the segment at that index,
+     * null if out of bounds. The evaluator funnels both `p[0]` and `p[i]`
+     * here as `String(idx)`.
+     *
+     * Named ('uid', etc.) → returns the value from `bindings`, populated
+     * either by `bind()` or by the handler when constructing `request.path`
+     * from a matched-rule path. Returns null if the name was never bound.
+     */
+    field(name) {
+        // Numeric index path (works for strings like '0', '12', ...)
+        if (/^\d+$/.test(name)) {
+            const i = Number(name);
+            if (i < 0 || i >= this.segments.length)
+                return null;
+            return this.segments[i];
+        }
+        // Named binding lookup. Bindings are populated either by `bind()` or by
+        // the handler when constructing `request.path` from a matched-rule path
+        // (so wildcards from `match /users/{uid}/...` are exposed as
+        // `request.path.uid`). Returns null if the name was never bound — same
+        // shape as missing-map-key reads elsewhere in the evaluator.
+        if (name in this.bindings)
+            return this.bindings[name];
+        return null;
+    }
+    callMethod(method, args) {
+        switch (method) {
+            case 'bind': {
+                const m = args[0];
+                if (m === null || m === undefined || typeof m !== 'object' || Array.isArray(m) || m instanceof RulesValue) {
+                    throw new TypeError(`Path.bind() requires a Map argument, got ${m === null ? 'null' : typeof m}`);
+                }
+                return this.bind(m);
+            }
+            default:
+                return NO_OP;
+        }
+    }
+}
+//# sourceMappingURL=path.js.map

package/dist/rules/simulator/wrappers/path.js.map

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

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

@@ -0,0 +1,82 @@
+/**
+ * Reference wrapper — Item 3 of simulator-prod-parity.md.
+ *
+ * Reference surface (rules.Reference):
+ *   - `.path`   — relative document path string ('users/u1')
+ *   - `.id`     — last segment of the path ('u1')
+ *   - `.parent` — parent collection path string ('users')
+ *   - `is reference` — type test
+ *   - `==` / `!=` against another Reference
+ *
+ * Per 0.B per-wrapper table:
+ *   typeName: 'reference'
+ *   valueOf:  NaN          (no meaningful numeric coercion — like Path/LatLng)
+ *   toString: 'users/u1'   (relative path; round-trips with the admin SDK
+ *                          DocumentReference.path getter)
+ *   equals:   path-string equality (project/database not significant in
+ *             the simulator — every Reference lives in the same logical DB)
+ *   binaryOp: NO_OP (== / != route through equals)
+ *
+ * Why a relative-path-only wrapper rather than a full project/database/doc
+ * model: Firestore rules see references as opaque path values. The
+ * `referenceValue` wire encoding *does* need a fully-qualified
+ * `projects/<p>/databases/<d>/documents/<path>` string for round-trip
+ * with discover/wire.ts, but that's a write-out concern — the wire
+ * encoder synthesizes a default qualifier on the way out. Inside the
+ * simulator, two references are the same reference iff their relative
+ * paths match.
+ *
+ * The admin SDK DocumentReference exposes more (e.g., `.firestore`,
+ * `formattedName`); the rules language does not — we deliberately
+ * shrink to the rules-visible surface so accidental `ref.firestore`
+ * reads in a rule (which production would silently null out) match
+ * the simulator.
+ */
+import { RulesValue, type NoOp } from './base.js';
+export declare class Reference extends RulesValue {
+    readonly typeName = "reference";
+    /** Relative document path, e.g. 'users/u1' or 'users/u1/posts/p1'. */
+    readonly path: string;
+    constructor(path: string);
+    /**
+     * Construct from an admin-SDK-style fully-qualified resource name like
+     * `projects/p/databases/(default)/documents/users/u1`. The fully-
+     * qualified form is what `referenceValue` emits on the wire; using this
+     * helper at the decode boundary keeps the relative-path invariant.
+     */
+    static fromResourceName(resourceName: string): Reference;
+    /** Last path segment; '' for an empty path. */
+    get id(): string;
+    /**
+     * Parent collection path as a string. For `users/u1` returns `users`;
+     * for `users/u1/posts/p1` returns `users/u1/posts`. An empty string
+     * if there is no parent (a root-level reference is degenerate, but
+     * we don't throw to keep diagnostics-friendly).
+     *
+     * Returning a string (not a Reference) matches Firestore rules' lack of
+     * a CollectionReference type — collections aren't first-class values in
+     * rules. Agents that want to compare against a collection path do so by
+     * string equality, which this supports.
+     */
+    get parent(): string;
+    valueOf(): number;
+    toString(): string;
+    toJSON(): unknown;
+    equals(other: unknown): boolean;
+    /**
+     * Property dispatch. Mirrors the admin SDK read surface: `.path`,
+     * `.id`, `.parent`. Anything else returns null (Firestore rules
+     * "missing map key" shape, consistent with other wrappers).
+     */
+    field(name: string): unknown;
+    callMethod(_method: string, _args: unknown[]): unknown | NoOp;
+}
+/**
+ * Build the fully-qualified resource name used by Firestore's
+ * `referenceValue` wire field. The simulator doesn't carry a real
+ * project ID, so callers (the wire encoder) supply one — defaulting
+ * to `'sim'` and database `'(default)'` keeps the round-trip intact
+ * without inventing fake projects in the wrapper itself.
+ */
+export declare function referenceToResourceName(ref: Reference, projectId?: string, databaseId?: string): string;
+//# sourceMappingURL=reference.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../../src/rules/simulator/wrappers/reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,UAAU,EAAS,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAEzD,qBAAa,SAAU,SAAQ,UAAU;IACvC,QAAQ,CAAC,QAAQ,eAAe;IAEhC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;IAOxB;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS;IAIxD,+CAA+C;IAC/C,IAAI,EAAE,IAAI,MAAM,CAGf;IAED;;;;;;;;;;OAUG;IACH,IAAI,MAAM,IAAI,MAAM,CAGnB;IAID,OAAO,IAAI,MAAM;IAIjB,QAAQ,IAAI,MAAM;IAOlB,MAAM,IAAI,OAAO;IAIjB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAK/B;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAS5B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,IAAI;CAO9D;AAuBD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,EACd,SAAS,GAAE,MAAc,EACzB,UAAU,GAAE,MAAoB,GAC/B,MAAM,CAER"}