pyric 0.1.0-alpha.19 → 0.1.0-alpha.21

package/src/rules/rtdb/grammar/RtdbExpr.ohm

@@ -59,8 +59,11 @@ RtdbExpr {
     | null
 
   number
-    = digit+ "." digit+  -- float
-    | digit+              -- int
+    = digit+ "." digit+ exponent?  -- float
+    | digit+ exponent              -- exp
+    | digit+                       -- int
+
+  exponent = ("e" | "E") ("+" | "-")? digit+
 
   string
     = "\"" doubleStringChar* "\""  -- double

package/src/rules/rtdb/grammar/RtdbExpr.ohm.generated.ts

@@ -63,8 +63,11 @@ export const RTDB_EXPR_OHM_SOURCE = `RtdbExpr {
     | null
 
   number
-    = digit+ "." digit+  -- float
-    | digit+              -- int
+    = digit+ "." digit+ exponent?  -- float
+    | digit+ exponent              -- exp
+    | digit+                       -- int
+
+  exponent = ("e" | "E") ("+" | "-")? digit+
 
   string
     = "\\"" doubleStringChar* "\\""  -- double

package/src/rules/rtdb/grammar/simulator.ts

@@ -29,6 +29,32 @@ function safeMemberRead(recv: unknown, key: string): unknown {
   return (recv as Record<string, unknown>)[key] ?? null;
 }
 
+/** Process standard escape sequences in single-quoted string literals. */
+function processStringEscapes(raw: string): string {
+  let out = '';
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i];
+    if (c !== '\\' || i === raw.length - 1) {
+      out += c;
+      continue;
+    }
+    const next = raw[++i];
+    switch (next) {
+      case '\\': out += '\\'; break;
+      case '\'': out += '\''; break;
+      case '"':  out += '"';  break;
+      case 'n':  out += '\n'; break;
+      case 'r':  out += '\r'; break;
+      case 't':  out += '\t'; break;
+      case 'b':  out += '\b'; break;
+      case 'f':  out += '\f'; break;
+      case '/':  out += '/';  break;
+      default:   out += '\\' + next; break;
+    }
+  }
+  return out;
+}
+
 export interface EvalContext {
   auth: SimulatedAuth | null;
   data: DataSnapshot;
@@ -89,23 +115,21 @@ export class DataSnapshot {
 
   child(path: string): DataSnapshot {
     const parts = path.split('/').filter(p => p.length > 0);
-    let current: unknown = this._value;
-    let currentPath = this._path;
+    if (parts.length === 0) return this;
 
+    let current: unknown = this._value;
     for (const part of parts) {
-      if (current === null || current === undefined || typeof current !== 'object') {
+      if (current !== null && current !== undefined && typeof current === 'object') {
+        current = Object.hasOwn(current as object, part)
+          ? ((current as Record<string, unknown>)[part] ?? null)
+          : null;
+      } else {
         current = null;
-        currentPath = `${currentPath}/${part}`.replace(/\/+/g, '/');
-        break;
       }
-      // Own-property access only: a `__proto__`/`constructor` child must
-      // not resolve to the JS prototype chain.
-      current = Object.hasOwn(current as object, part)
-        ? ((current as Record<string, unknown>)[part] ?? null)
-        : null;
-      currentPath = `${currentPath === '/' ? '' : currentPath}/${part}`;
     }
 
+    const prefix = this._path === '/' ? '' : this._path;
+    const currentPath = `${prefix}/${parts.join('/')}`;
     return new DataSnapshot(current, currentPath, this._root);
   }
 
@@ -113,9 +137,10 @@ export class DataSnapshot {
     if (this._path === '/') return null;
     const parts = this._path.split('/').filter(p => p.length > 0);
     parts.pop();
-    const parentPath = '/' + parts.join('/');
+    if (parts.length === 0) {
+      return new DataSnapshot(this._root, '/');
+    }
     const rootSnap = new DataSnapshot(this._root, '/');
-    if (parentPath === '/') return rootSnap;
     return rootSnap.child(parts.join('/'));
   }
 
@@ -289,7 +314,8 @@ function getEvalSemantics(): Semantics {
 
     literal(node) { return (node as any).eval(); },
 
-    number_float(_int, _dot, _frac) { return parseFloat(this.sourceString); },
+    number_float(_int, _dot, _frac, _exp) { return parseFloat(this.sourceString); },
+    number_exp(_digits, _exp) { return parseFloat(this.sourceString); },
     number_int(_digits) { return parseInt(this.sourceString, 10); },
     number(node) { return (node as any).eval(); },
 
@@ -297,7 +323,7 @@ function getEvalSemantics(): Semantics {
       return JSON.parse(this.sourceString);
     },
     string_single(_open, chars, _close) {
-      return chars.children.map((c: any) => c.sourceString).join('');
+      return processStringEscapes(chars.sourceString);
     },
     string(node) { return (node as any).eval(); },
 

package/src/rules/rtdb/simulation/handler.ts

@@ -58,6 +58,23 @@ function snapshotChildKeys(snap: DataSnapshot): string[] {
  * the first unsupported node, else `null` when every applicable `.validate`
  * passes.
  */
+function hasValidateRule(n: RtdbNode): boolean {
+  if (n.validate) return true;
+  return n.children.some(hasValidateRule);
+}
+
+function shouldValidateSiblingSubtree(
+  currentSegments: readonly string[],
+  hasLocalDeletion: boolean,
+  allWritePaths: readonly string[][],
+): boolean {
+  return (
+    currentSegments.length > 0 ||
+    hasLocalDeletion ||
+    allWritePaths.some((wp) => wp.length === 1)
+  );
+}
+
 function findFailingValidate(
   node: RtdbNode,
   data: DataSnapshot,
@@ -65,31 +82,47 @@ function findFailingValidate(
   bindings: Record<string, string>,
   buildContext: ContextBuilder,
   pathToWrite: string[],
+  updates?: readonly { path: string; value?: unknown }[],
 ): ValidateFailure | null {
   let firstUnsupported: ValidateFailure | null = null;
 
+  const writePathStrings = new Set<string>();
+  if (updates && updates.length > 0) {
+    for (const u of updates) {
+      writePathStrings.add(u.path.split('/').filter(Boolean).join('/'));
+    }
+  }
+  writePathStrings.add(pathToWrite.filter(Boolean).join('/'));
+  const allWritePaths = Array.from(writePathStrings).map((p) => p.split('/').filter(Boolean));
+
   function walk(
     node: RtdbNode,
     data: DataSnapshot,
     newData: DataSnapshot,
     bindings: Record<string, string>,
-    remainingPath: string[],
+    currentSegments: string[],
+    isUnderModifiedSubtree: boolean,
   ): ValidateFailure | null {
-    // A null proposed value is a delete — RTDB does not validate deletes.
-    if (!newData.exists()) return null;
-
-    const rule = node.validate;
-    if (rule) {
-      if (!rule.parsed.valid) {
-        if (!firstUnsupported) {
-          firstUnsupported = { node, rule, bindings, unsupported: true };
+    if (newData.exists()) {
+      const rule = node.validate;
+      if (rule) {
+        if (!rule.parsed.valid) {
+          if (!firstUnsupported) {
+            firstUnsupported = { node, rule, bindings, unsupported: true };
+          }
+        } else {
+          const result = evaluateRtdbExpression(rule.raw, buildContext(data, newData, bindings));
+          if (!result) return { node, rule, bindings };
         }
-      } else {
-        const result = evaluateRtdbExpression(rule.raw, buildContext(data, newData, bindings));
-        if (!result) return { node, rule, bindings };
       }
     }
 
+    const isAtOrBelowWriteTarget = allWritePaths.some(
+      (wp) => wp.length <= currentSegments.length && wp.every((seg, idx) => seg === currentSegments[idx]),
+    );
+
+    const hasLocalDeletion = snapshotChildKeys(data).some((k) => !newData.child(k).exists());
+
     for (const child of node.children) {
       const childSegments = child.path.split('/').filter(Boolean);
       if (childSegments.length === 0) continue;
@@ -97,49 +130,118 @@ function findFailingValidate(
       const lastSegment = childSegments[childSegments.length - 1];
       const isPathVar = lastSegment.startsWith('$');
 
-      // Above the write location, validation follows only the operation path.
-      // Once the write location is reached, it fans out through every child
-      // present in the proposed value.
-      if (remainingPath.length > 0) {
-        if (!isPathVar && remainingPath[0] !== lastSegment) continue;
-        return walk(
-          child,
-          data.child(remainingPath[0]),
-          newData.child(remainingPath[0]),
-          isPathVar ? { ...bindings, [lastSegment]: remainingPath[0] } : bindings,
-          remainingPath.slice(1),
-        );
-      }
+      if (isAtOrBelowWriteTarget || isUnderModifiedSubtree) {
+        if (isPathVar) {
+          for (const key of snapshotChildKeys(newData)) {
+            const failure = walk(
+              child,
+              data.child(key),
+              newData.child(key),
+              { ...bindings, [lastSegment]: key },
+              [...currentSegments, key],
+              true,
+            );
+            if (failure) return failure;
+          }
+        } else {
+          if (newData.child(lastSegment).exists()) {
+            const failure = walk(
+              child,
+              data.child(lastSegment),
+              newData.child(lastSegment),
+              bindings,
+              [...currentSegments, lastSegment],
+              true,
+            );
+            if (failure) return failure;
+          }
+        }
+      } else {
+        // We are at an ancestor of write path(s)
+        if (isPathVar) {
+          const writeKeys = new Set<string>();
+          for (const wp of allWritePaths) {
+            if (
+              wp.length > currentSegments.length &&
+              currentSegments.every((seg, idx) => seg === wp[idx])
+            ) {
+              writeKeys.add(wp[currentSegments.length]);
+            }
+          }
+          for (const key of writeKeys) {
+            const failure = walk(
+              child,
+              data.child(key),
+              newData.child(key),
+              { ...bindings, [lastSegment]: key },
+              [...currentSegments, key],
+              false,
+            );
+            if (failure) return failure;
+          }
 
-      if (isPathVar) {
-        // Bind the path variable to each key actually present in the new
-        // data — a `$var` node validates every child of the written value.
-        for (const key of snapshotChildKeys(newData)) {
-          const failure = walk(
-            child,
-            data.child(key),
-            newData.child(key),
-            { ...bindings, [lastSegment]: key },
-            [],
+          if (
+            hasValidateRule(child) &&
+            shouldValidateSiblingSubtree(currentSegments, hasLocalDeletion, allWritePaths)
+          ) {
+            for (const key of snapshotChildKeys(newData)) {
+              if (writeKeys.has(key)) continue;
+              const failure = walk(
+                child,
+                data.child(key),
+                newData.child(key),
+                { ...bindings, [lastSegment]: key },
+                [...currentSegments, key],
+                true,
+              );
+              if (failure) return failure;
+            }
+          }
+        } else {
+          const key = lastSegment;
+          const isChildOnWritePath = allWritePaths.some(
+            (wp) =>
+              wp.length > currentSegments.length &&
+              wp[currentSegments.length] === key &&
+              currentSegments.every((seg, idx) => seg === wp[idx]),
           );
-          if (failure) return failure;
+
+          if (isChildOnWritePath) {
+            const failure = walk(
+              child,
+              data.child(key),
+              newData.child(key),
+              bindings,
+              [...currentSegments, key],
+              false,
+            );
+            if (failure) return failure;
+          } else {
+            // Sibling branch
+            if (
+              newData.child(key).exists() &&
+              hasValidateRule(child) &&
+              shouldValidateSiblingSubtree(currentSegments, hasLocalDeletion, allWritePaths)
+            ) {
+              const failure = walk(
+                child,
+                data.child(key),
+                newData.child(key),
+                bindings,
+                [...currentSegments, key],
+                true,
+              );
+              if (failure) return failure;
+            }
+          }
         }
-      } else {
-        const failure = walk(
-          child,
-          data.child(lastSegment),
-          newData.child(lastSegment),
-          bindings,
-          [],
-        );
-        if (failure) return failure;
       }
     }
 
     return null;
   }
 
-  const realFailure = walk(node, data, newData, bindings, pathToWrite);
+  const realFailure = walk(node, data, newData, bindings, [], false);
   return realFailure ?? firstUnsupported;
 }
 
@@ -343,6 +445,7 @@ export class SimulateHandler {
               {},
               buildContext,
               pathSegments,
+              updates,
             );
             if (failure) {
               return {

package/src/rules/simulator/document-lookups.ts

@@ -2,10 +2,43 @@ import type { SimulationContext, SimResource } from './evaluation-context.js';
 import { EvalError } from './eval-error.js';
 import { Path } from './wrappers/path.js';
 
+/**
+ * Check if a path or segment list points to a document (non-empty, even segment count).
+ */
+export function isDocumentPath(segmentsOrPath: string | readonly string[]): boolean {
+  const segments = typeof segmentsOrPath === 'string'
+    ? segmentsOrPath.split('/').filter(Boolean)
+    : segmentsOrPath;
+  return segments.length > 0 && segments.length % 2 === 0;
+}
+
 export function normalizeDocumentPath(rawPath: string): string {
-  return rawPath
-    .replace(/\$\(database\)/g, '(default)')
-    .replace(/^\/databases\/\(default\)\/documents\//, '');
+  let cleaned = rawPath.replace(/\$\(database\)/g, '(default)');
+  const dbPrefix = '/databases/(default)/documents/';
+  if (cleaned.startsWith(dbPrefix)) {
+    cleaned = cleaned.slice(dbPrefix.length);
+  } else if (cleaned.startsWith('/databases/(default)/documents')) {
+    cleaned = cleaned.slice('/databases/(default)/documents'.length);
+  }
+  if (cleaned.startsWith('/')) {
+    cleaned = cleaned.slice(1);
+  }
+
+  const rawSegments = cleaned.split('/').filter((s) => s.length > 0 && s !== '.');
+  const stack: string[] = [];
+
+  for (const seg of rawSegments) {
+    if (seg === '..') {
+      if (stack.length > 1) {
+        stack.pop();
+      }
+      // When stack.length <= 1, .. is clamped to prevent escaping collection or document root.
+    } else {
+      stack.push(seg);
+    }
+  }
+
+  return stack.join('/');
 }
 
 /** Build the identity-bearing value returned by a real document lookup. */
@@ -20,6 +53,12 @@ export function makeGetResource(relPath: string, data: Record<string, unknown>):
 
 export function resolveGet(rawPath: string, context: SimulationContext): SimResource {
   const path = normalizeDocumentPath(rawPath);
+  const segments = path.split('/').filter(Boolean);
+  if (!isDocumentPath(segments)) {
+    throw new EvalError(
+      `get() requires a path pointing to a document (even segment count), got '${path}'`,
+    );
+  }
   let document = context.mockDocuments.get(path);
   if (!document && context.getDoc) {
     const loaded = context.getDoc(path);
@@ -38,6 +77,10 @@ export function resolveGet(rawPath: string, context: SimulationContext): SimReso
 
 export function resolveExists(rawPath: string, context: SimulationContext): boolean {
   const path = normalizeDocumentPath(rawPath);
+  const segments = path.split('/').filter(Boolean);
+  if (!isDocumentPath(segments)) {
+    return false;
+  }
   if (context.mockDocuments.has(path)) return true;
   if (context.getDoc) {
     const loaded = context.getDoc(path);

package/src/rules/simulator/eval-error.ts

@@ -6,3 +6,19 @@ export class EvalError extends Error {
     this.name = 'EvalError';
   }
 }
+
+/**
+ * A resource limit the whole request ran into: the per-request document
+ * access budget today, and any future per-request cap. Production fails the
+ * entire request closed on these instead of producing a CEL error value, so
+ * they are never absorbed by a determining `&&`/`||` operand and never
+ * confined to the allow rule that raised them.
+ */
+export class ResourceLimitError extends EvalError {
+  constructor(message: string, expr?: Expression) {
+    super(message, expr);
+    this.name = 'ResourceLimitError';
+  }
+}
+
+export { EvalError as RuleEvalError };

package/src/rules/simulator/evaluation-builtins.ts

@@ -11,7 +11,8 @@ import { Path } from './wrappers/path.js';
 import { RulesFloat } from './wrappers/float.js';
 import { EvalError } from './eval-error.js';
 import { UnsupportedError } from './unsupported-error.js';
-import { makeGetResource, normalizeDocumentPath, resolveExists, resolveGet } from './document-lookups.js';
+import { isDocumentPath, makeGetResource, normalizeDocumentPath, resolveExists, resolveGet } from './document-lookups.js';
+import { chargeLookup } from './lookup-budget.js';
 import type { SimulationContext } from './evaluation-context.js';
 import { evaluate, isKnownGlobal, resolveIdentifier } from './evaluator.js';
 import { evaluateHashingMethod } from './hashing-builtins.js';
@@ -53,10 +54,14 @@ export function evaluateFunctionCall(
   switch (name) {
     case 'get': {
       const path = String(evaluate(args[0], ctx, scope));
+      // Charge the per-request lookup budget BEFORE resolving so the 11th
+      // distinct access fails closed even when the doc would resolve.
+      chargeLookup(ctx, 'doc', path);
       return resolveGet(path, ctx);
     }
     case 'exists': {
       const path = String(evaluate(args[0], ctx, scope));
+      chargeLookup(ctx, 'doc', path); // exists() shares get()'s per-path slot
       return resolveExists(path, ctx);
     }
     case 'getAfter': {
@@ -71,15 +76,27 @@ export function evaluateFunctionCall(
       // doesn't touch.
       const argVal = evaluate(args[0], ctx, scope);
       const pathStr = String(argVal);
+      const normalized = normalizeDocumentPath(pathStr);
+      const segments = normalized.split('/').filter(Boolean);
+      if (!isDocumentPath(segments)) {
+        throw new EvalError(
+          `getAfter() requires a path pointing to a document (even segment count), got '${normalized}'`,
+        );
+      }
+      // getAfter() is a document access call and counts against the
+      // per-request budget. 'after' keying: the post-write projection is a
+      // different snapshot than get()'s pre-write read, so a path read by
+      // both charges two slots. The fall-through resolveGet below does NOT
+      // re-charge, because charging lives only here.
+      chargeLookup(ctx, 'after', normalized);
       if (pathStr === ctx.afterStatePath.toString()) {
         // RULES-B8: getAfter() of a doc that won't exist post-write (delete,
         // or projected-null) ERRORS like get() — guard with existsAfter().
         if (ctx.afterState === null) {
           throw new EvalError(`getAfter() of non-existent document '${pathStr}' (guard with existsAfter() first)`);
         }
-        return makeGetResource(normalizeDocumentPath(pathStr), ctx.afterState);
+        return makeGetResource(normalized, ctx.afterState);
       }
-      const normalized = normalizeDocumentPath(pathStr);
       if (ctx.batchProjection?.has(normalized)) {
         const projected = ctx.batchProjection.get(normalized)!;
         if (projected === null) {
@@ -96,19 +113,29 @@ export function evaluateFunctionCall(
       // through to exists().
       const argVal = evaluate(args[0], ctx, scope);
       const pathStr = String(argVal);
+      const normalized = normalizeDocumentPath(pathStr);
+      const segments = normalized.split('/').filter(Boolean);
+      if (!isDocumentPath(segments)) {
+        return false;
+      }
+      // existsAfter() counts against the per-request lookup budget and
+      // shares getAfter()'s post-write slot for the same path.
+      chargeLookup(ctx, 'after', normalized);
       if (pathStr === ctx.afterStatePath.toString()) {
         return ctx.existsAfter;
       }
-      const normalized = normalizeDocumentPath(pathStr);
       if (ctx.batchProjection?.has(normalized)) {
         return ctx.batchProjection.get(normalized) !== null;
       }
       return resolveExists(pathStr, ctx);
     }
-    case 'debug': {
-      const val = evaluate(args[0], ctx, scope);
-      return val; // debug() returns its argument
-    }
+    // NOTE: `debug()` is deliberately NOT handled here. Production Firestore
+    // rejects it at compile ("Function not found error: Name: [debug]", the
+    // captured acceptance probe for firestore.function.debug), so the local
+    // evaluator must fail it the same way. Falling through to the
+    // user-defined lookup below yields `EvalError('Unknown function: debug')`,
+    // the exact message the conformance rejection-signature normalizer maps
+    // to `function-not-found:debug`.
     // RULES-B5 / RULES-B6: type-conversion builtins follow CEL's strict
     // semantics, not JS coercion. `String()` routes a RulesFloat through its
     // `.toString()` so `string(1.0)` → "1.0" (decimal preserved); bare ints

package/src/rules/simulator/evaluation-context.ts

@@ -1,4 +1,5 @@
 import type { FunctionDef } from '../grammar/FirestoreAST.js';
+import type { LookupBudget } from './lookup-budget.js';
 import type { TraceRecorder } from './trace-recorder.js';
 import { Path } from './wrappers/path.js';
 import { Timestamp } from './wrappers/timestamp.js';
@@ -108,6 +109,17 @@ export interface SimulationContext {
    * through to `get()` exactly as before.
    */
   batchProjection?: Map<string, Record<string, unknown> | null>;
+  /**
+   * Per-request document access budget (production: 10 distinct
+   * get/exists/getAfter/existsAfter reads per single-document request; the
+   * 11th fails the evaluation closed). The handler creates one per test
+   * case and shares it across every match block and allow rule evaluated
+   * for that request; a fresh budget per test case is the "resets between
+   * requests" semantics. Optional so non-handler evaluation paths are
+   * unaffected. See LookupBudget in lookup-budget.ts for the counting
+   * semantics and the in-repo production evidence.
+   */
+  lookupBudget?: LookupBudget;
   /** Optional per-rule expression-trace recorder. When set, the evaluator
    *  wraps every `evaluate()` call and records the sub-expression tree;
    *  when absent (the default), the evaluator is unchanged. The handler

package/src/rules/simulator/evaluator.ts

@@ -22,10 +22,10 @@ import { Timestamp } from './wrappers/timestamp.js';
 import { Bytes } from './wrappers/bytes.js';
 import { Path } from './wrappers/path.js';
 import { RulesFloat } from './wrappers/float.js';
-import { EvalError } from './eval-error.js';
+import { EvalError, ResourceLimitError } from './eval-error.js';
 import { UnsupportedError } from './unsupported-error.js';
 
-export { EvalError } from './eval-error.js';
+export { EvalError, EvalError as RuleEvalError } from './eval-error.js';
 export { UnsupportedError } from './unsupported-error.js';
 
 // ═══ Simulation Context ═══
@@ -71,7 +71,9 @@ function evaluateExpr(expr: Expression, ctx: SimulationContext, scope: Record<st
       return evaluateBinaryOp(expr.op, expr.left, expr.right, ctx, scope);
 
     case 'unaryOp': {
-      if (expr.op === '!') return !evaluate(expr.operand, ctx, scope);
+      if (expr.op === '!') {
+        return !requireBoolean(evaluate(expr.operand, ctx, scope), expr.operand);
+      }
       if (expr.op === '-') {
         const v = evaluate(expr.operand, ctx, scope);
         // RULES-B5: negating a float stays a float (`-1.5 is float`); negating
@@ -363,6 +365,13 @@ function evaluateBinaryOp(
   if (op === '&&') {
     let lv: unknown, lErr: unknown;
     try { lv = requireBoolean(evaluate(left, ctx, scope), left); } catch (e) { lErr = e; }
+    // A resource-limit failure (the document access budget) fails the WHOLE
+    // request, it is not a CEL error value: a determining RHS must not
+    // absorb it into an ALLOW. Fail closed immediately.
+    // TODO(unverified): confirm against a live production capture that the
+    // 11th-access error is not absorbable. The Rules Test API does not
+    // enforce the budget, so the capture has to be a deployed ruleset.
+    if (lErr instanceof ResourceLimitError) throw lErr;
     if (lErr === undefined && lv === false) {
       // LHS is false → determines the result; RHS need not be evaluated.
       ctx.trace?.skip(right);
@@ -380,6 +389,8 @@ function evaluateBinaryOp(
   if (op === '||') {
     let lv: unknown, lErr: unknown;
     try { lv = requireBoolean(evaluate(left, ctx, scope), left); } catch (e) { lErr = e; }
+    // See the `&&` branch: a resource-limit failure is not absorbable.
+    if (lErr instanceof ResourceLimitError) throw lErr;
     if (lErr === undefined && lv === true) {
       // LHS is true → determines the result; RHS need not be evaluated.
       ctx.trace?.skip(right);