pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/rules/simulator/query-proof-residual.ts

@@ -0,0 +1,209 @@
+/** Reduce query-guaranteed facts to a candidate-independent residual condition.
+ * Every finite alternative must pass. Unknown predicates are never evaluated
+ * against a fabricated partial document; only positive OR branches can omit them.
+ */
+import type { Expression, FunctionDef } from "../grammar/FirestoreAST.js";
+import {
+  isProvablyDocIndependent,
+  substituteIdentifiers,
+  type QueryConstraints,
+} from "./query-proof.js";
+type Scalar = string | number | boolean | null;
+const scalar = (value: unknown): value is Scalar =>
+  value === null ||
+  typeof value === "string" ||
+  typeof value === "boolean" ||
+  (typeof value === "number" && Number.isFinite(value));
+const literal = (value: Scalar): Expression => ({
+  type: "literal",
+  value,
+  raw: JSON.stringify(value),
+});
+function field(expr: Expression): string | undefined {
+  if (
+    expr.type === "memberAccess" &&
+    expr.object.type === "memberAccess" &&
+    expr.object.property === "data" &&
+    expr.object.object.type === "identifier" &&
+    expr.object.object.name === "resource"
+  )
+    return expr.property;
+  return undefined;
+}
+function join(left: Expression, right: Expression, op: string): Expression {
+  return { type: "binaryOp", op, left, right };
+}
+
+export function queryResidual(
+  condition: Expression,
+  constraints: QueryConstraints,
+  functions: Map<string, FunctionDef>,
+  authUid?: string,
+): { condition: Expression; partial: boolean } | undefined {
+  let partial = false;
+  const domains = new Map<string, Scalar[]>();
+  for (const filter of constraints.where ?? []) {
+    if (domains.has(filter.field)) continue;
+    if (filter.op === "==" && scalar(filter.value))
+      domains.set(filter.field, [filter.value]);
+    if (
+      filter.op === "in" &&
+      Array.isArray(filter.value) &&
+      filter.value.length > 0 &&
+      filter.value.length <= 30 &&
+      filter.value.every(scalar)
+    )
+      domains.set(filter.field, filter.value);
+  }
+  let variants: Map<string, Scalar>[] = [new Map()];
+  for (const [name, values] of domains) {
+    if (variants.length * values.length > 30) return undefined;
+    variants = variants.flatMap((variant) =>
+      values.map((value) => new Map([...variant, [name, value]])),
+    );
+  }
+  const residuals: Expression[] = [];
+  for (const pins of variants) {
+    let budget = 2000;
+    function rewrite(
+      expr: Expression,
+      visiting = new Set<string>(),
+    ): Expression {
+      if (--budget < 0) throw new Error("proof expansion budget");
+      const key = field(expr);
+      if (key !== undefined && pins.has(key)) return literal(pins.get(key)!);
+      if (expr.type === "functionCall" && functions.has(expr.name)) {
+        // Leave already-independent helpers intact to preserve evaluator scoping/budgets.
+        if (isProvablyDocIndependent(expr, functions)) return expr;
+        if (visiting.has(expr.name)) throw new Error("recursive proof helper");
+        const fn = functions.get(expr.name)!;
+        if (fn.parameters.length !== expr.args.length)
+          throw new Error("proof arity");
+        const bindings = new Map(
+          fn.parameters.map((name, i) => [name, expr.args[i]!]),
+        );
+        for (const binding of fn.lets)
+          bindings.set(
+            binding.name,
+            substituteIdentifiers(binding.value, bindings),
+          );
+        return rewrite(
+          substituteIdentifiers(fn.body, bindings),
+          new Set([...visiting, expr.name]),
+        );
+      }
+      if (expr.type === "inExpr") {
+        const arrayField = field(expr.collection);
+        const element = rewrite(expr.element, visiting);
+        let value: Scalar | undefined;
+        if (element.type === "literal") value = element.value;
+        if (
+          element.type === "memberAccess" &&
+          element.property === "uid" &&
+          element.object.type === "memberAccess" &&
+          element.object.property === "auth" &&
+          element.object.object.type === "identifier" &&
+          element.object.object.name === "request"
+        )
+          value = authUid;
+        if (
+          arrayField !== undefined &&
+          value !== undefined &&
+          (constraints.where ?? []).some(
+            (filter) =>
+              filter.field === arrayField &&
+              filter.op === "array-contains" &&
+              filter.value === value,
+          )
+        )
+          return literal(true);
+        return {
+          ...expr,
+          element,
+          collection: rewrite(expr.collection, visiting),
+        };
+      }
+      const sub = (value: Expression) => rewrite(value, visiting);
+      switch (expr.type) {
+        case "literal":
+        case "identifier":
+          return expr;
+        case "memberAccess":
+          return { ...expr, object: sub(expr.object) };
+        case "bracketAccess":
+          return { ...expr, object: sub(expr.object), index: sub(expr.index) };
+        case "sliceAccess":
+          return {
+            ...expr,
+            object: sub(expr.object),
+            start: sub(expr.start),
+            end: sub(expr.end),
+          };
+        case "binaryOp":
+          return { ...expr, left: sub(expr.left), right: sub(expr.right) };
+        case "unaryOp":
+          return { ...expr, operand: sub(expr.operand) };
+        case "ternary":
+          return {
+            ...expr,
+            condition: sub(expr.condition),
+            consequent: sub(expr.consequent),
+            alternate: sub(expr.alternate),
+          };
+        case "isExpr":
+          return { ...expr, value: sub(expr.value) };
+        case "methodCall":
+          return {
+            ...expr,
+            object: sub(expr.object),
+            args: expr.args.map(sub),
+          };
+        case "functionCall":
+          return { ...expr, args: expr.args.map(sub) };
+        case "listLiteral":
+          return { ...expr, elements: expr.elements.map(sub) };
+        case "mapLiteral":
+          return {
+            ...expr,
+            entries: expr.entries.map((entry) => ({
+              key: sub(entry.key),
+              value: sub(entry.value),
+            })),
+          };
+        case "pathLiteral":
+          return {
+            ...expr,
+            segments: expr.segments.map((segment) =>
+              typeof segment === "string" ? segment : sub(segment),
+            ),
+          };
+      }
+    }
+    // A sufficient condition, never a guessed representative. Unknown branches
+    // may be discarded only in monotone positive OR, never under NOT/ternary.
+    function sufficient(expr: Expression): Expression | undefined {
+      if (isProvablyDocIndependent(expr, functions)) return expr;
+      if (expr.type !== "binaryOp" || (expr.op !== "&&" && expr.op !== "||"))
+        return undefined;
+      const left = sufficient(expr.left),
+        right = sufficient(expr.right);
+      if (left && right) return join(left, right, expr.op);
+      if (expr.op === "||") {
+        partial = true;
+        return left ?? right;
+      }
+      return undefined;
+    }
+    try {
+      const residual = sufficient(rewrite(condition));
+      if (!residual) return undefined;
+      residuals.push(residual);
+    } catch {
+      return undefined;
+    }
+  }
+  return {
+    condition: residuals.reduce((left, right) => join(left, right, "&&")),
+    partial,
+  };
+}

package/src/rules/simulator/query-proof.ts

@@ -1,3 +1,4 @@
+import { queryResidual } from './query-proof-residual.js';
 /**
  * RULES-B11 (rules-side) — query-proof evaluation for `list` operations.
  *
@@ -31,24 +32,22 @@
  *    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, membership/type
- * checks, and any predicate that can't be reduced to a top-level equality after
- * user functions are inlined (helpers ARE inlined — a helper whose body is an
- * equality spine is proven the same as if it were written inline). The proof
- * demands FULL accounting: a rule is provable only when its entire
- * doc-dependence reduces to equality conjuncts the query discharges — one
- * doc-dependent non-equality conjunct anywhere on the spine rejects the whole
- * query, even if every equality is discharged. That is the safe direction
- * (prod also rejects an unprovable query).
+ * Additional supported facts: scalar equality/finite `in` values substitute
+ * exact candidate fields, and `array-contains` proves the corresponding positive
+ * membership predicate only. Positive OR branches can supply a sufficient proof.
+ * Every finite combination is evaluated through a document-independent residual,
+ * including query-pinned lookup paths; unpinned reads are never fabricated.
+ * Unbounded ranges, dynamic document-dependent collections, candidate identities,
+ * and unsupported syntax still fail closed. The finite expansion is capped at 30.
  */
-import type { Expression, FunctionDef } from '../grammar/FirestoreAST.js';
+import { assembleExpression } from '../grammar/FirestoreAssembler.js';
+import type { Expression, FunctionDef, SourceLoc } from '../grammar/FirestoreAST.js';
 
 /** A single `where(field, op, value)` constraint carried by the query. */
 export interface QueryWhereConstraint {
   readonly field: string;
   readonly op: string;
-  readonly value: string | number | boolean | null;
+  readonly value: string | number | boolean | null | readonly (string | number | boolean | null)[];
 }
 
 /** The query constraints relevant to the proof. `where` is the load-bearing
@@ -91,11 +90,14 @@ export interface QueryProofResidual {
   missing: QueryProofMissing[];
   mismatched: QueryProofMismatch[];
   outOfScope?: string;
+  /** Inlined predicate that stopped proof, not a runtime evaluation. */
+  predicate?: string;
+  predicateLoc?: SourceLoc;
 }
 
 export type QueryProofResult =
-  | { provable: true; reason: string }
-  | { provable: false; reason: string; residual: QueryProofResidual };
+  | { provable: true; reason: string; residualCondition?: Expression; proofFailure?: { kind: 'unsupported-predicate' | 'constraints-not-satisfied'; reason: string; residual: QueryProofResidual } }
+  | { provable: false; kind: 'unsupported-predicate' | 'constraints-not-satisfied'; reason: string; residual: QueryProofResidual };
 
 /**
  * Decide whether `listCondition` is PROVABLE for every doc the query could
@@ -112,6 +114,19 @@ export type QueryProofResult =
  *   `== request.auth.uid` predicate is not recognized as a required equality.
  */
 export function evaluateQueryProof(
+  condition: Expression, constraints: QueryConstraints,
+  functions: Map<string, FunctionDef> = new Map(), authUid?: string,
+): QueryProofResult {
+  const equality = evaluateEqualityQueryProof(condition, constraints, functions, authUid);
+  if (equality.provable || equality.kind === 'constraints-not-satisfied') return equality;
+  const residual = queryResidual(condition, constraints, functions, authUid);
+  if (residual) return {provable: true,
+    reason: 'query-guaranteed facts reduce every candidate alternative to a document-independent residual',
+    residualCondition: residual.condition, proofFailure: residual.partial ? equality : undefined};
+  return equality;
+}
+
+function evaluateEqualityQueryProof(
   listCondition: Expression,
   constraints: QueryConstraints,
   fnMap: Map<string, FunctionDef> = new Map(),
@@ -141,13 +156,14 @@ export function evaluateQueryProof(
   if (!extraction.ok || extraction.required.length === 0) {
     const outOfScope =
       'list rule depends on per-document data through a predicate the query cannot discharge ' +
-      '(a rule is provable only when its entire doc-dependence reduces to top-level ' +
-      '`resource.data.field == value` conjunctions, including through inlined helpers — ' +
-      'disjunctions, ranges, `in`, membership/type checks, and nested paths are not provable)';
+      '(unconstrained candidate fields or unsupported query facts remain after helper expansion)';
     return {
       provable: false,
-      reason: `${outOfScope} — prod rejects the whole query rather than filtering`,
-      residual: { missing: [], mismatched: [], outOfScope },
+      kind: 'unsupported-predicate',
+      reason: `${outOfScope} — Pyric cannot establish whether Firebase would allow this query`,
+      residual: { missing: [], mismatched: [], outOfScope,
+        ...(!extraction.ok ? { predicate: assembleExpression(extraction.predicate), predicateLoc: extraction.predicateLoc } : {}),
+      },
     };
   }
   const required = extraction.required;
@@ -179,6 +195,7 @@ export function evaluateQueryProof(
 
   return {
     provable: false,
+    kind: 'constraints-not-satisfied',
     reason: buildResidualReason(missing, mismatched),
     residual: { missing, mismatched },
   };
@@ -199,7 +216,7 @@ function buildResidualReason(missing: QueryProofMissing[], mismatched: QueryProo
       .join(', ');
     parts.push(`the query where(...) value does not match [${list}]`);
   }
-  return `${parts.join('; ')} — prod rejects the query ("rules are not filters")`;
+  return `${parts.join('; ')} — Pyric cannot prove the query safe ("rules are not filters")`;
 }
 
 /**
@@ -356,7 +373,7 @@ interface RequiredEquality {
  */
 type ExtractionResult =
   | { ok: true; required: RequiredEquality[] }
-  | { ok: false };
+  | { ok: false; predicate: Expression; predicateLoc?: SourceLoc };
 
 /**
  * Pull out the per-doc EQUALITY predicates the rule requires — top-level `&&`
@@ -382,9 +399,11 @@ function extractRequiredDataEqualities(
   authUid: string | undefined,
 ): ExtractionResult {
   const required: RequiredEquality[] = [];
-  const walkAnd = (e: Expression, visited: Set<string>): boolean => {
+  let predicate = expr;
+  let predicateLoc = expr.loc;
+  const walkAnd = (e: Expression, visited: Set<string>, enclosingLoc = expr.loc): boolean => {
     if (e.type === 'binaryOp' && e.op === '&&') {
-      return walkAnd(e.left, visited) && walkAnd(e.right, visited);
+      return walkAnd(e.left, visited, enclosingLoc) && walkAnd(e.right, visited, enclosingLoc);
     }
     if (e.type === 'functionCall' && fnMap.has(e.name) && !visited.has(e.name)) {
       const fn = fnMap.get(e.name)!;
@@ -398,7 +417,7 @@ function extractRequiredDataEqualities(
       for (const b of fn.lets) bindings.set(b.name, substituteIdentifiers(b.value, bindings));
       const inlined = substituteIdentifiers(fn.body, bindings);
       const nextVisited = new Set(visited).add(e.name);
-      return walkAnd(inlined, nextVisited);
+      return walkAnd(inlined, nextVisited, fn.loc ?? enclosingLoc);
     }
     const eq = asDataEquality(e, authUid);
     if (eq) {
@@ -410,9 +429,16 @@ function extractRequiredDataEqualities(
     // faithfully (auth / time / request.query). Anything else, including any
     // node shape the classifier doesn't positively recognize, fails the
     // extraction (fail closed).
-    return isProvablyDocIndependent(e, fnMap);
+    const independent = isProvablyDocIndependent(e, fnMap);
+    if (!independent) {
+      predicate = e;
+      // Older parsed expressions lack token locations; the enclosing helper
+      // definition still gives a useful authored citation.
+      predicateLoc = e.loc ?? enclosingLoc;
+    }
+    return independent;
   };
-  return walkAnd(expr, new Set()) ? { ok: true, required } : { ok: false };
+  return walkAnd(expr, new Set()) ? { ok: true, required } : { ok: false, predicate, predicateLoc };
 }
 
 /**
@@ -452,7 +478,7 @@ function isRequestAuthUid(e: Expression): boolean {
  * call's argument expressions for them. Pure structural map — the shared AST is
  * never mutated.
  */
-function substituteIdentifiers(expr: Expression, bindings: Map<string, Expression>): Expression {
+export function substituteIdentifiers(expr: Expression, bindings: Map<string, Expression>): Expression {
   const sub = (e: Expression): Expression => {
     switch (e.type) {
       case 'identifier':

package/src/rules/simulator/request-path.ts

@@ -0,0 +1,39 @@
+/**
+ * The form a request path takes before a match block is resolved against it.
+ *
+ * Rules match blocks hang off `match /databases/{database}/documents`, so a
+ * path is matched from the first segment after that root: `orders/o2`. The
+ * console, the SDK's `doc()` reference, and every error message Firestore
+ * itself prints use the full resource name instead, `/databases/(default)/
+ * documents/orders/o2`, and a caller that copies one of those in has always
+ * been answered with a confident DENY and the note that no block matched,
+ * which reads as a verdict rather than as a path that never reached the
+ * ruleset.
+ *
+ * Both forms mean the same request, so both are accepted here and the full
+ * form is reduced to the document-relative one before anything else looks at
+ * it. Only the exact `databases/<name>/documents` prefix is stripped, so a
+ * top-level collection that happens to be called `databases` still resolves as
+ * itself.
+ */
+
+/** The form a path takes, for a message that has to name it. */
+export const DOCUMENT_PATH_FORM =
+  'Paths are document-relative, from the first segment after /databases/<database>/documents, such as orders/o2.';
+
+/** The segment count the full resource-name prefix occupies. */
+const PREFIX_SEGMENTS = 3;
+
+/**
+ * The document-relative form of one request path. A path already in that form
+ * is returned with any leading separator removed and nothing else changed.
+ */
+export function documentRelativePath(path: string): string {
+  const segments = path.split('/').filter(Boolean);
+  const hasResourcePrefix =
+    segments.length > PREFIX_SEGMENTS &&
+    segments[0] === 'databases' &&
+    segments[2] === 'documents';
+  if (hasResourcePrefix) return segments.slice(PREFIX_SEGMENTS).join('/');
+  return segments.join('/');
+}

package/src/rules/simulator/trace-recorder.ts

@@ -6,6 +6,7 @@ export interface ExprTraceEntry {
   source: string;
   kind: Expression['type'];
   parent: number | null;
+  operator?: string;
   value?: unknown;
   skipped?: boolean;
   error?: string;
@@ -23,6 +24,7 @@ export class TraceRecorder {
     const index = this.entries.length;
     const parent = this.parents.length > 0 ? this.parents[this.parents.length - 1] : null;
     const entry: ExprTraceEntry = { source: assembleExpression(expr), kind: expr.type, parent };
+    if (expr.type === 'binaryOp') entry.operator = expr.op;
     this.stampFrame(entry);
     this.entries.push(entry);
     this.parents.push(index);
@@ -46,6 +48,7 @@ export class TraceRecorder {
       parent,
       skipped: true,
     };
+    if (expr.type === 'binaryOp') entry.operator = expr.op;
     this.stampFrame(entry);
     this.entries.push(entry);
   }

package/src/rules/simulator/wrappers/timestamp.ts

@@ -30,6 +30,7 @@ import { Duration } from './duration.js';
 const NANOS_PER_SECOND = 1_000_000_000;
 const MS_PER_DAY = 86_400_000;
 const SECONDS_PER_DAY = 86_400;
+const SECONDS_PER_MINUTE = 60;
 
 /**
  * Roll over-/under-flow nanos into seconds and force nanos non-negative.
@@ -127,11 +128,17 @@ export class Timestamp extends RulesValue {
    * field already encodes whole-seconds, so date math is exact even
    * when sub-ms nanos are present. `dayOfWeek` follows ISO 8601:
    * Monday = 1, Sunday = 7.
+   *
+   * `seconds()` and `nanos()` are time-of-day components like `hours()`
+   * and `minutes()`: the seconds of the minute and the nanoseconds of the
+   * second. The `seconds` field is epoch seconds; `toMillis()` is the epoch
+   * accessor rules see. Captured by rules-firestore-timestamp-component-accessors
+   * and rules-storage-stdlib-timestamp-duration.
    */
   callMethod(method: string, _args: unknown[]): unknown | NoOp {
     switch (method) {
       case 'seconds':
-        return this.seconds;
+        return ((this.seconds % SECONDS_PER_MINUTE) + SECONDS_PER_MINUTE) % SECONDS_PER_MINUTE;
       case 'nanos':
         return this.nanos;
       case 'toMillis':

package/src/rules/simulator-tools-impl.ts

@@ -316,7 +316,7 @@ export function createFirestoreSimulatorTools(
     {
       name: 'firestore_simulator_undo',
       description:
-        'Undo the last allowed write. Restores state to immediately before that op. Returns the undone event, or a `{ undone: false }` outcome when the log is empty.',
+        'Undo the last allowed write. Restores state to immediately before that op. Returns the undone event, or a `{ undone: false }` outcome when no retained write remains.',
       parameters: { type: 'object', properties: {} },
       async execute() {
         const env = await resolveSandbox();
@@ -361,14 +361,17 @@ export function createFirestoreSimulatorTools(
     {
       name: 'firestore_simulator_events',
       description:
-        'Return every event the sandbox has seen — allowed and denied — with timestamps, auth, and debug messages. Useful for audit / replay / "why did this rule deny?" investigations.',
+        'Return retained events — allowed and denied — with timestamps, auth, debug messages, and an omitted count when the bounded log was trimmed. Useful for audit / replay / "why did this rule deny?" investigations.',
       parameters: { type: 'object', properties: {} },
       async execute() {
         const env = await resolveSandbox();
+        const { omittedCount } = env.getEventRetention();
+        const wasTrimmed = omittedCount > 0;
         return {
           ok: true,
-          summary: 'Event log',
+          summary: wasTrimmed ? `Event log (${omittedCount} omitted)` : 'Event log',
           data: {
+            omittedCount,
             events: env.getEvents().map((e) => ({
               id: e.id,
               method: e.method,

package/src/rules/stdlib-tools.ts

@@ -124,7 +124,7 @@ export function createFirestoreRulesStdlibTools(): ToolHandler[] {
     {
       name: 'firestore_lint_rules',
       description:
-        "Lint a Firestore Security Rules source BEFORE writing it. Catches parse errors with line/col, JS-style hallucinations (.filter / .toLowerCase / optional chaining / arrow functions), expression-budget violations, binary-chain depth (cap 98), let-binding count (cap 11), get() count, source size (256KB), and shared-gate / public-write smells. Pure-local — no auth, no network. Call this on any candidate source the moment you're about to `writeRules` — fixing a flagged issue here is cheaper than letting `runOnce` surface it as a denial after a deploy round-trip.",
+        "Lint a Firestore Security Rules source BEFORE writing it. Catches parse errors with line/col, JS-style hallucinations (.filter / .toLowerCase / optional chaining / arrow functions), expression-budget violations, binary-chain depth (cap 98), let-binding count (cap 11), get() count, source size (256KB), and shared-gate / public-write smells. Pure-local, with no auth and no network. Call it on any candidate source before installing that source: fixing a flagged issue here is cheaper than letting a denial surface it after a deploy round-trip.",
       parameters: {
         type: 'object',
         properties: {
@@ -147,7 +147,7 @@ export function createFirestoreRulesStdlibTools(): ToolHandler[] {
           const { line, column, message } = result.parseError;
           return {
             ok: false,
-            summary: `Parse failed at line ${line}, col ${column} — fix syntax before writeRules`,
+            summary: `Parse failed at line ${line}, column ${column}. Fix the syntax before installing this source.`,
             data: result,
             message,
           };
@@ -160,7 +160,7 @@ export function createFirestoreRulesStdlibTools(): ToolHandler[] {
           ok: counts.errors === 0,
           summary:
             counts.errors === 0 && counts.warnings === 0
-              ? 'Lint clean — safe to writeRules'
+              ? 'Lint clean. This source is safe to install.'
               : `Lint found ${counts.errors} error${counts.errors === 1 ? '' : 's'}, ${counts.warnings} warning${counts.warnings === 1 ? '' : 's'}`,
           data: result,
         };
@@ -169,7 +169,7 @@ export function createFirestoreRulesStdlibTools(): ToolHandler[] {
     {
       name: 'firestore_resolve_modules',
       description:
-        "Resolve `2+modules` imports in a Firestore Rules source. Inlines the imported functions from the stdlib modules (`auth`, `validation`, `lobby`, etc. — see `firestore_rules_stdlib_list`) and rewrites the version line from `2+modules` to plain `2`. Call this BEFORE `writeRules` when the source you authored uses `2+modules` syntax — the playground's `runOnce` only understands plain v2 source. Pure-local; the stdlib modules are bundled into the package, no filesystem access required.",
+        "Resolve `2+modules` imports in a Firestore Rules source. Inlines the imported functions from the stdlib modules (`auth`, `validation`, `lobby`, and the rest of the catalogue) and rewrites the version line from `2+modules` to plain `2`. Call this before installing a source that uses `2+modules` syntax, because the playground's `runOnce` only understands plain v2 source. Pure-local; the stdlib modules are bundled into the package, no filesystem access required.",
       parameters: {
         type: 'object',
         properties: {