pyric 0.1.0-alpha.20 → 0.1.0-alpha.21

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);

package/src/rules/simulator/handler.ts

@@ -24,6 +24,8 @@ import { evaluate, UnsupportedError, TraceRecorder, type SimulationContext } fro
 
 import { Timestamp } from './wrappers/timestamp.js';
 import { Path } from './wrappers/path.js';
+import { LookupBudget } from './lookup-budget.js';
+import { ResourceLimitError } from './eval-error.js';
 import { projectAfterState } from './project-after-state.js';
 import {
   requestQuery,
@@ -75,12 +77,27 @@ function methodToOperations(method: string): string[] {
 
 // ═══ Rule evaluation ═══
 
+/**
+ * One match block's contribution to the request verdict. `resourceLimit`
+ * carries a per-request resource limit (the document access budget) that
+ * the block ran into: it is not this block's private failure, so the caller
+ * stops evaluating siblings and denies the whole request.
+ */
+interface RuleBlockOutcome {
+  decision: Decision;
+  trace: RuleEvaluation[];
+  notes: string[];
+  resourceLimit?: string;
+}
+
 /**
  * Evaluate all allow rules in a match block for a given operation.
  * Uses OR semantics — if any matching rule allows, access is granted.
  *
  * Decision logic:
  *   - any rule ALLOW → ALLOW (short-circuit)
+ *   - else if any rule hit a per-request resource limit → DENY, and the
+ *     caller stops: the limit ends the request, not just this block
  *   - else if any rule threw UnsupportedError → UNSUPPORTED (sim abstains)
  *   - else → DENY
  *
@@ -93,7 +110,7 @@ function evaluateRules(
   operation: string,
   ctx: SimulationContext,
   source?: string,
-): { decision: Decision; trace: RuleEvaluation[]; notes: string[] } {
+): RuleBlockOutcome {
   const ops = methodToOperations(operation);
   const trace: RuleEvaluation[] = [];
   const notes: string[] = [];
@@ -140,6 +157,27 @@ function evaluateRules(
       trace.push(entry);
     } catch (e) {
       entry.expressionTrace = recorder.entries;
+      // A per-request resource limit (the document access budget) is not a
+      // failure of THIS rule: production stops the whole request there, so
+      // no sibling allow rule and no other match block gets a chance to
+      // grant. Abandon the loop and report the limit up to the caller.
+      const isResourceLimit = e instanceof ResourceLimitError;
+      if (isResourceLimit) {
+        entry.verdict = 'ERROR';
+        entry.message = (e as ResourceLimitError).message;
+        trace.push(entry);
+        ctx.trace = priorRecorder;
+        notes.push(
+          `Request denied by a rules resource limit: ${(e as ResourceLimitError).message}. `
+          + 'The limit is per request, so no other allow rule or match block was evaluated.',
+        );
+        return {
+          decision: 'DENY',
+          trace,
+          notes,
+          resourceLimit: (e as ResourceLimitError).message,
+        };
+      }
       const isUnsupported = e instanceof UnsupportedError;
       if (isUnsupported) {
         sawUnsupported = true;
@@ -220,6 +258,7 @@ function buildContext(
   pathVariables: Record<string, string>,
   getDoc?: (path: string) => Record<string, unknown> | null,
   batchProjection?: Map<string, Record<string, unknown> | null>,
+  lookupBudget?: LookupBudget,
 ): SimulationContext {
   const fnMap = new Map<string, FunctionDef>();
   for (const fn of functions) fnMap.set(fn.name, fn);
@@ -366,6 +405,12 @@ function buildContext(
     // getafter-batch fix — shared batch/transaction projection, when the
     // caller supplied one. Absent for single-op evaluation.
     ...(batchProjection ? { batchProjection } : {}),
+    // Per-request document access budget (10 distinct lookups). The SAME
+    // instance is threaded into every match block's context for one test
+    // case, because production's budget spans overlapping match blocks and
+    // OR'd allow rules within one request evaluation. An absent budget and
+    // an `undefined` one mean the same thing here: no budget is enforced.
+    lookupBudget,
   };
 }
 
@@ -538,9 +583,18 @@ export class SimulateFirestoreRulesHandler {
       const notes: string[] = [];
       let sawUnsupported = false;
       let grantingBlockPath: string | undefined;
+      let hitResourceLimit = false;
+      // One lookup budget per test case (one request evaluation), shared
+      // across every matching block below and reset here between requests.
+      // Production's single-request budget is 10 distinct document
+      // accesses; transactions and batched writes additionally get a
+      // 20-access aggregate that is NOT modeled, because each per-op
+      // simulate() call in a batch (see WriteRuntime.buildBatchProjection)
+      // gets its own fresh per-op budget of 10.
+      const lookupBudget = new LookupBudget();
       for (const match of matches) {
         const pathVars = { ...rootBindings, ...match.pathVariables };
-        const ctx = buildContext(tc, match.functions, pathVars, opts?.getDoc, opts?.batchProjection);
+        const ctx = buildContext(tc, match.functions, pathVars, opts?.getDoc, opts?.batchProjection, lookupBudget);
 
         const blockPath = renderMatchBlockPath(match.block);
         const res = evaluateRules(match.block, tc.method, ctx, source);
@@ -550,6 +604,14 @@ export class SimulateFirestoreRulesHandler {
         trace.push(...res.trace);
         notes.push(...res.notes);
 
+        // A per-request resource limit ends the request: production stops
+        // the whole evaluation, so a later match block cannot grant.
+        const isResourceLimit = res.resourceLimit !== undefined;
+        if (isResourceLimit) {
+          decision = 'DENY';
+          hitResourceLimit = true;
+          break;
+        }
         const isResAllow = res.decision === 'ALLOW';
         if (isResAllow) {
           decision = 'ALLOW';
@@ -561,8 +623,10 @@ export class SimulateFirestoreRulesHandler {
           sawUnsupported = true;
         }
       }
-      const isNotAllow = decision !== 'ALLOW';
-      if (isNotAllow) {
+      // A resource limit is a definite production DENY, so it outranks an
+      // UNSUPPORTED abstention recorded by an earlier block.
+      const isEscalatable = decision !== 'ALLOW' && !hitResourceLimit;
+      if (isEscalatable) {
         if (sawUnsupported) {
           decision = 'UNSUPPORTED';
         }

package/src/rules/simulator/lookup-budget.ts

@@ -0,0 +1,101 @@
+import type { SimulationContext } from './evaluation-context.js';
+import { ResourceLimitError } from './eval-error.js';
+import { isDocumentPath, normalizeDocumentPath } from './document-lookups.js';
+
+// ═══ Per-request document-lookup budget ═══
+//
+// Production hard-limits security-rule document access calls, get(),
+// exists(), getAfter() and existsAfter(), to 10 per single-document request
+// or query evaluation. Multi-document transactions and batched writes get
+// an AGGREGATE budget of 20 on top of a per-operation 10; only the per-
+// operation 10 is modeled here (each batched op's simulate() call gets its
+// own fresh LookupBudget, mirroring how WriteRuntime.buildBatchProjection
+// shares one projection map across per-op simulate() calls but each op is
+// its own rules evaluation).
+//
+// Counting semantics: distinct accesses, not raw calls. In-repo production
+// evidence:
+//   - site-docs secure/firestore-rules-limits.md ("More than 10 document
+//     access calls"): "Repeated reads of the same path are cached; reads of
+//     different paths are not."
+//   - rules/stdlib-modules.ts spaces guidance: "get() is cached per request,
+//     so all rules on the request share a single read of the 10-get budget."
+//   - The Storage sibling limit (storage/sandbox/rules-methods.ts) uses a
+//     per-request distinct-path set, verified by real-resource capture.
+//
+// What is implemented, exactly: the budget keys on (kind, path), where kind
+// is 'doc' for pre-write reads (get/exists) and 'after' for post-write
+// projections (getAfter/existsAfter). So get() and exists() on one path
+// share a slot, getAfter() and existsAfter() on one path share a slot, and
+// a path read by BOTH a pre-write and a post-write call charges TWO slots.
+// The two calls read different snapshots, so charging them separately is the
+// fail-closed direction while production's cache granularity is uncaptured.
+//
+// TODO(unverified): a credentialed production capture is needed to pin
+// (a) whether get() and exists() on one path really share one cache slot,
+// (b) whether getAfter() on a path already read by get() charges a second
+// slot or reuses the first, and (c) whether exhausting the budget is
+// absorbable by a determining CEL operand (modeled: not absorbable). The
+// capture is a ruleset whose condition performs 10 lookups and then an
+// 11th, deployed and probed against a live project. The Rules Test API does
+// not enforce the budget, so it cannot produce this evidence.
+
+/** Production's per-evaluation document access budget (single request). */
+const DOCUMENT_LOOKUP_LIMIT = 10;
+
+/**
+ * Budget exhaustion. A {@link ResourceLimitError}, not a plain EvalError,
+ * because it fails the WHOLE request closed: CEL error absorption
+ * (`error || true`, `error && false`) must not swallow it into an ALLOW,
+ * and a sibling allow rule or match block must not evaluate past it.
+ */
+export class LookupBudgetError extends ResourceLimitError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'LookupBudgetError';
+  }
+}
+
+/**
+ * Per-request lookup counter. The handler creates ONE per test case
+ * (request evaluation) and every match block and allow rule evaluated for
+ * that request shares it: production's budget spans OR'd rules and
+ * overlapping match blocks alike (the linter's SHARED_GATE "cross-rule
+ * budget exhaustion" hazard).
+ */
+export class LookupBudget {
+  private readonly accessed = new Set<string>();
+
+  /**
+   * Charge one document access. `kind` is 'doc' for pre-write reads
+   * (get/exists) and 'after' for post-write projections (getAfter/
+   * existsAfter). A repeat access to the same (kind, path) is cached and
+   * free; the 11th DISTINCT access throws {@link LookupBudgetError}, which
+   * fails the request closed.
+   */
+  charge(kind: 'doc' | 'after', normalizedPath: string): void {
+    const key = `${kind}:${normalizedPath}`;
+    if (this.accessed.has(key)) return; // cached, does not count against the budget
+    if (this.accessed.size >= DOCUMENT_LOOKUP_LIMIT) {
+      throw new LookupBudgetError(
+        `document access limit exceeded: this request already read ${DOCUMENT_LOOKUP_LIMIT} distinct documents `
+        + `via get()/exists()/getAfter()/existsAfter() (production allows 10 per request; `
+        + `the 11th distinct access fails the evaluation)`,
+      );
+    }
+    this.accessed.add(key);
+  }
+}
+
+/**
+ * The single charging seam for all four document access builtins. Charges
+ * the budget for a raw (unnormalized) lookup path. Malformed paths charge
+ * nothing: no document read happens, and the caller's own validation
+ * produces the error or false result.
+ */
+export function chargeLookup(ctx: SimulationContext, kind: 'doc' | 'after', rawPath: string): void {
+  if (!ctx.lookupBudget) return;
+  const normalized = normalizeDocumentPath(rawPath);
+  if (!isDocumentPath(normalized)) return;
+  ctx.lookupBudget.charge(kind, normalized);
+}

package/src/rules/stdlib-modules.ts

@@ -46,6 +46,13 @@ export type RulesService = 'firestore' | 'storage';
 export interface StdlibEntry {
   /** Surface signature, e.g. `math.ceil(x: number): int`. */
   signature: string;
+  /**
+   * Whether production accepts a ruleset that calls this entry. Omitted
+   * means accepted. `'rejected'` documents a name that Firebase reference
+   * material lists but production's compiler refuses, so the catalog can
+   * carry the correction while the signature field stays a signature.
+   */
+  acceptance?: 'rejected';
   /** One-line summary the agent reads first. */
   description: string;
   /** ~1–3 lines of real rule fragments. Optional. */
@@ -85,9 +92,9 @@ const BUILTINS_MODULE: StdlibModuleDefinition = {
   key: 'builtins',
   kind: 'language-namespace',
   description:
-    'Top-level functions always in scope inside rules — get, exists, getAfter, debug. Called bare, no namespace prefix.',
+    'Top-level functions always in scope inside rules: get, exists, getAfter. Called bare, no namespace prefix. (debug() is docs-only: production rejects it at compile.)',
   purpose:
-    'The four built-in functions Firestore Rules ships with at the top level. They are NOT inside a namespace — call `get(path)`, not `firestore.get(path)`. Used to read other documents (cross-document gates), check existence, peek at post-write state, and print debug values.',
+    'The built-in functions Firestore Rules ships with at the top level. They are NOT inside a namespace: call `get(path)`, not `firestore.get(path)`. Used to read other documents (cross-document gates), check existence, and peek at post-write state.',
   whenToUse:
     'Reach for `builtins` any time a rule needs information that isn\'t already on `request` or `resource`. Most common: `get(path)` to read another document\'s fields inside a predicate.',
   entries: [
@@ -117,10 +124,11 @@ const BUILTINS_MODULE: StdlibModuleDefinition = {
     },
     {
       signature: 'debug(value: any): bool',
+      acceptance: 'rejected',
       description:
-        'Print `value` to the Firestore emulator/test runner log and return true. No-op in production. Useful for narrowing why a rule denies during local development.',
+        'DO NOT USE. Although Firebase reference docs list `debug()`, production Firestore REJECTS rulesets that call it at compile time (`Function not found error: Name: [debug]`). The linter and local simulator reject it for the same reason.',
       notes:
-        'Always returns true — wrapping it in a predicate (`if debug(resource.data.x) && otherCondition`) shows the value without changing rule outcome.',
+        'Remove any debug() wrapper before deploying and evaluate the inner expression directly. There is no deployable logging primitive in rules.',
     },
   ],
   relatedKeys: ['request', 'resource', 'path'],
@@ -132,11 +140,11 @@ const MATH: StdlibModuleDefinition = {
   key: 'math',
   kind: 'language-namespace',
   description:
-    'Numeric helpers — abs, ceil, floor, round, sqrt, pow, isInfinite, isNaN. Use when rules need to coerce or bound numbers.',
+    'Numeric helpers: abs, ceil, floor, round, sqrt, pow, isNaN. Use when rules need to coerce or bound numbers.',
   purpose:
     'The `math` namespace exposes a small set of numeric utilities for use inside rule predicates. Functions are called as `math.<fn>(...)`. Always in scope; no import needed.',
   whenToUse:
-    'Reach for `math` whenever a rule needs to round, bound, or guard against non-finite numbers in a user-supplied field.',
+    'Reach for `math` whenever a rule needs to round, bound, or guard against NaN in a user-supplied field.',
   entries: [
     { signature: 'math.abs(n: number): number', description: 'Absolute value of `n`.' },
     { signature: 'math.ceil(n: number): int', description: 'Smallest integer >= `n`.' },
@@ -145,15 +153,15 @@ const MATH: StdlibModuleDefinition = {
     { signature: 'math.sqrt(n: number): number', description: 'Square root of `n`. Negative input returns NaN.' },
     { signature: 'math.pow(base: number, exp: number): number', description: '`base` raised to `exp`.' },
     {
-      signature: 'math.isInfinite(n: number): bool',
-      description: 'True if `n` is +Infinity or -Infinity.',
-      notes: 'Pairs with `math.isNaN` for safe numeric guards before arithmetic.',
+      signature: 'math.isNaN(n: number): bool',
+      description: 'True if `n` is NaN.',
+      notes:
+        'There is NO isInfinite function in the math namespace. Production Firestore rejects it at compile time (`Function not found error: Name: [math.isInfinite]`), despite it appearing in some Firebase reference material.',
     },
-    { signature: 'math.isNaN(n: number): bool', description: 'True if `n` is NaN.' },
   ],
   examples: [
     `allow update: if math.ceil(request.resource.data.score) <= 100;`,
-    `allow create: if !math.isNaN(request.resource.data.lat) && !math.isInfinite(request.resource.data.lat);`,
+    `allow create: if !math.isNaN(request.resource.data.lat);`,
   ],
   relatedKeys: ['hashing'],
 };

package/src/sandbox/admin-firestore/get-firestore.ts

@@ -67,7 +67,23 @@ export function getFirestore(ctx: SandboxContext): SandboxFirestore {
  *  arm pins on every op/sub. Never absent — see {@link getFirestore}. */
 export function lensForAuth(auth: AuthState): AuthLens {
   if (auth === null || auth === undefined) return { mode: 'anon' };
-  return auth.token === undefined
-    ? { mode: 'as', uid: auth.uid }
-    : { mode: 'as', uid: auth.uid, token: auth.token };
+  const lens: Extract<AuthLens, { mode: 'as' }> = { mode: 'as', uid: auth.uid };
+  if (auth.token !== undefined) lens.token = auth.token;
+  if (auth.tenant !== undefined) lens.tenant = auth.tenant;
+  return lens;
 }
+
+export function authStateForLens(actAs: Extract<AuthLens, { mode: 'as' }>): AuthState {
+  const state: Extract<AuthState, { uid: string }> = { uid: actAs.uid };
+  if (actAs.token !== undefined) state.token = actAs.token;
+  if (actAs.tenant !== undefined) state.tenant = actAs.tenant;
+  return state;
+}
+
+export function lensCacheKey(actAs: Extract<AuthLens, { mode: 'as' }>): string {
+  const parts = [actAs.uid];
+  if (actAs.tenant !== undefined) parts.push(`tenant:${actAs.tenant}`);
+  if (actAs.token !== undefined) parts.push(JSON.stringify(actAs.token));
+  return parts.join(':');
+}
+

package/src/sandbox/index.ts

@@ -51,7 +51,11 @@ export type {
   WriteSandboxEvent,
 } from './types/index.js';
 export { SandboxError } from './types/index.js';
-export { SandboxContextImpl } from './sandbox-context.js';
+export {
+  SandboxContextImpl,
+  normalizeAuthState,
+  validateAuthState,
+} from './sandbox-context.js';
 export {
   isOperationEvent,
   operationContextFor,

package/src/sandbox/persistence/types.ts

@@ -15,7 +15,7 @@
 /**
  * Minimal web-storage-like contract the session persistence controller
  * reads/writes. Matches the `localStorage` / `sessionStorage` browser
- * API subset that `pyric dev`'s `SessionStore` already uses, so
+ * API subset that `pyric sandbox`'s `SessionStore` already uses, so
  * browsers pass real storages and tests pass in-memory Map-backed fakes.
  *
  * Why the minimal subset (get/set/remove) instead of the full

package/src/sandbox/remote.ts

@@ -78,7 +78,7 @@ export interface RemoteSandboxChannel {
  */
 export interface RemoteSandbox extends Sandbox {
   readonly [REMOTE_SANDBOX]: true;
-  /** Base URL of the `pyric dev` this handle is attached to (used in
+  /** Base URL of the `pyric sandbox` this handle is attached to (used in
    *  error guidance: "open <serveUrl> in a browser and retry"). */
   readonly serveUrl: string;
   /** The raw worker op/sub relay channel. */
@@ -100,7 +100,7 @@ export const REMOTE_SANDBOX_FACTORY = Symbol.for('pyric.remote.sandboxFactory');
 
 /** Options accepted by the ambient remote-sandbox factory. */
 export interface RemoteSandboxFactoryOptions {
-  /** Explicit `pyric dev` base URL (from `PYRIC_SANDBOX=remote:<url>`).
+  /** Explicit `pyric sandbox` base URL (from `PYRIC_SANDBOX=remote:<url>`).
    *  When omitted the factory discovers the running host itself (the
    *  `.pyric/serve.json` locator protocol). */
   url?: string;