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

package/src/sandbox/sandbox-context.ts

@@ -27,32 +27,84 @@ import { SandboxError } from './types/errors.js';
 import type { Sandbox } from './types/service.js';
 import { immutableOperationContext } from './operation-record.js';
 
+/**
+ * Normalize AuthState during SandboxContextImpl context assembly.
+ * Automatically projects top-level `tenant` into `token.firebase.tenant`
+ * while preserving custom claims and explicit nested token overrides.
+ * Never mutates original input.
+ */
+export function normalizeAuthState(auth: AuthState): AuthState {
+  if (auth === null) return null;
+
+  if (auth.tenant === undefined) {
+    if (auth.token === undefined) {
+      return { uid: auth.uid };
+    }
+    return {
+      uid: auth.uid,
+      token: structuredClone(auth.token),
+    };
+  }
+
+  const token = auth.token !== undefined ? structuredClone(auth.token) : {};
+  const existingFirebase = token.firebase;
+
+  let normalizedFirebase: Record<string, unknown>;
+  if (
+    typeof existingFirebase === 'object' &&
+    existingFirebase !== null &&
+    !Array.isArray(existingFirebase)
+  ) {
+    const fbObj = existingFirebase as Record<string, unknown>;
+    normalizedFirebase = {
+      ...fbObj,
+      tenant: fbObj.tenant !== undefined ? fbObj.tenant : auth.tenant,
+    };
+  } else {
+    normalizedFirebase = { tenant: auth.tenant };
+  }
+
+  token.firebase = normalizedFirebase;
+
+  return {
+    uid: auth.uid,
+    tenant: auth.tenant,
+    token,
+  };
+}
+
 function authLensFor(auth: AuthState): AuthLens {
   if (auth === null) 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 class SandboxContextImpl implements SandboxContext {
+  public readonly auth: AuthState;
+  public readonly operationContext: OperationContext;
+
   constructor(
     public readonly sandbox: Sandbox,
-    public readonly auth: AuthState,
+    auth: AuthState,
     operationContext?: OperationContext,
   ) {
+    validateAuthState(auth);
+    const normalized = normalizeAuthState(auth);
+    this.auth = normalized;
     this.operationContext = immutableOperationContext(operationContext ?? {
       source: { kind: 'unattributed' },
-      authLens: authLensFor(auth),
+      authLens: authLensFor(normalized),
     });
   }
 
-  public readonly operationContext: OperationContext;
-
   withAuth(auth: AuthState): SandboxContext {
     validateAuthState(auth);
-    return new SandboxContextImpl(this.sandbox, auth, {
+    const normalized = normalizeAuthState(auth);
+    return new SandboxContextImpl(this.sandbox, normalized, {
       source: this.operationContext.source,
-      authLens: authLensFor(auth),
+      authLens: authLensFor(normalized),
       ...(this.operationContext.planId === undefined
         ? {}
         : { planId: this.operationContext.planId }),
@@ -106,6 +158,14 @@ export function validateAuthState(auth: unknown): asserts auth is AuthState {
       'withAuth() requires `uid` to be a non-empty string.',
     );
   }
+  if ('tenant' in obj && obj.tenant !== undefined) {
+    if (typeof obj.tenant !== 'string' || obj.tenant.length === 0) {
+      throw new SandboxError(
+        'invalid-argument',
+        'withAuth() requires `tenant` (when present) to be a non-empty string.',
+      );
+    }
+  }
   if ('token' in obj && obj.token !== undefined) {
     if (obj.token === null || typeof obj.token !== 'object' || Array.isArray(obj.token)) {
       throw new SandboxError(

package/src/sandbox/types/auth-state.ts

@@ -18,5 +18,5 @@
  * names should reflect that.
  */
 export type AuthState =
-  | { uid: string; token?: Record<string, unknown> }
+  | { uid: string; token?: Record<string, unknown>; tenant?: string }
   | null;

package/src/sandbox/types/events.ts

@@ -379,7 +379,8 @@ export interface ServiceMutationEvent {
    *   - storage: `object_put` | `object_delete` | `metadata_update`
    *   - rtdb:    `set` | `update` | `remove` | `transaction`
    *   - ai:      `generate_content` | `stream_generate_content` |
-   *              `count_tokens` | `request_rejected`
+   *              `count_tokens` | `request_rejected` | `response_blocked` |
+   *              `model_substituted`
    * New ops can be added without a breaking change (consumers switch with a
    * default branch).
    */

package/src/sandbox/types/operation.ts

@@ -15,7 +15,7 @@ export type EventActor =
 /** The identity/rules lens an operation actually ran under. */
 export type AuthLens =
   | { mode: 'admin' }
-  | { mode: 'as'; uid: string; token?: Record<string, unknown> }
+  | { mode: 'as'; uid: string; tenant?: string; token?: Record<string, unknown> }
   | { mode: 'app-session' }
   | { mode: 'anon' };
 

package/src/storage/enforce.ts

@@ -4,10 +4,9 @@
  * grow their own copy of the same dispatch.
  *
  * Behavior:
- *   - No rules configured → allow. The v1 scope's session-archive
- *     ruleset is opt-in; bare `getStorage` with no `rules` option
- *     keeps the open-by-default semantics consistent with the
- *     pre-Slice-8 surface.
+ *   - No rules configured → deny. Matches Firebase production fail-closed
+ *     security invariants: bare `getStorage` with no `rules` option
+ *     rejects client operations with `storage/unauthorized`.
  *   - Rules configured → call `evaluateStorageRules`. Throw
  *     `storage/unauthorized` with the evaluator's `reasons` joined
  *     into the message on denial.
@@ -16,9 +15,8 @@
  * permission governs both download and list, so `list.ts` enforces a
  * `read` check on the scanned prefix path. A previous v1 scope build
  * silently bypassed list — that contradicted the rules-enforcement
- * contract (a denied tree was still enumerable). With no rules
- * configured the check is a no-op (open-by-default), so the
- * session-archive demo is unaffected.
+ * contract (a denied tree was still enumerable). When no rules are
+ * configured the check fails closed (default-deny).
  *
  * Studio observability (storage-denial-events): every enforcement
  * decision — allow, deny, AND admin-plane bypass — lands on the
@@ -44,10 +42,12 @@ import { emitSandboxEvent, makeSandboxOperationEvent } from 'pyric/sandbox/inter
 import type { EventProvenance } from 'pyric/sandbox';
 import {
   storageOperationProvenance,
+  type CrossServiceIam,
   type StorageService,
   type Target,
 } from './service.js';
 import { evaluateStorageRules } from './sandbox/rules-evaluator.js';
+import { RuleEvalError } from './sandbox/rules-evaluation-error.js';
 import type { EvaluationInput, FirestoreLookup } from './sandbox/rules.js';
 import { unauthorized } from './errors.js';
 
@@ -71,18 +71,16 @@ export function enforceRules(
     return;
   }
   if (!service.rules) {
-    // Open-by-default: no rules configured, no evaluation happened.
-    // Still emit `allow` for parity — an unrestricted op is legitimately
-    // "allowed", just never evaluated.
-    emitOperation(target, input, 'allow', undefined, 'user', false, boundProvenance);
-    return;
+    const reasons = ['No Storage rules configured; default deny.'];
+    emitOperation(target, input, 'deny', reasons, 'user', false, boundProvenance);
+    throw unauthorized(input.request.method, input.request.path, ' — No Storage rules configured; default deny.');
   }
   const evaluationInput = target ? withCanonicalRulesPath(input, target.bucket) : input;
   const result = evaluateStorageRules(
     service.rules,
     evaluationInput,
     undefined,
-    firestoreLookupFor(target),
+    firestoreLookupFor(target, service.crossServiceIam),
   );
   if (!result.allowed) {
     emitOperation(target, input, 'deny', result.reasons, 'user', true, boundProvenance);
@@ -164,12 +162,53 @@ function emitOperation(
  *
  * Calls without a target get no lookup — a rule that reaches for
  * `firestore.*` there denies "unsupported" rather than false-allowing.
+ *
+ * `crossServiceIam: 'denied'` models the production project state WITHOUT
+ * `roles/firebaserules.firestoreServiceAgent` on the Storage service agent:
+ * the lookup capability is still injected (so path validation and laziness
+ * behave identically), but every EXECUTED get/exists fails. See
+ * {@link crossServiceIamDeniedLookup}.
  */
-function firestoreLookupFor(target?: Target): FirestoreLookup | undefined {
+function firestoreLookupFor(
+  target: Target | undefined,
+  crossServiceIam: CrossServiceIam,
+): FirestoreLookup | undefined {
   if (!target) return undefined;
+  if (crossServiceIam === 'denied') return crossServiceIamDeniedLookup();
   const admin = target.sandbox.admin;
   return {
     get: (path) => admin.getDocument(path) as Record<string, unknown> | null,
     exists: (path) => admin.getDocument(path) !== null,
   };
 }
+
+/**
+ * The `crossServiceIam: 'denied'` lookup: every executed
+ * `firestore.get()/exists()` throws a {@link RuleEvalError} naming the
+ * missing service-agent role, so the rule denies with that reason,
+ * mirroring production's IAM-disabled boundary captured by conformance
+ * observation `stdlib-realstorage-p3-lookup-budget` (row storage-rules#134):
+ * every lookup-executing family DENIES while a short-circuited lookup is
+ * never invoked and its rule still ALLOWS. The capture pins only that
+ * executed-lookup/short-circuit boundary; how an IAM failure interacts
+ * with CEL `&&`/`||` error absorption is NOT pinned by it (no absorption
+ * family ran IAM-disabled), so this uses the same absorbable
+ * {@link RuleEvalError} class as the existing no-capability deny path.
+ *
+ * Exported for the conformance replay test
+ * (`packages/conformance/test/src/storage-stdlib-real-replay.test.ts`),
+ * which runs the captured IAM-disabled matrix against the evaluator with
+ * THIS production lookup, not a hand-rolled twin.
+ */
+export function crossServiceIamDeniedLookup(): FirestoreLookup {
+  const fail = (method: 'get' | 'exists'): never => {
+    throw new RuleEvalError(
+      `firestore.${method}() failed: cross-service Firestore access is not authorized: ` +
+        "the Storage service agent lacks roles/firebaserules.firestoreServiceAgent (crossServiceIam: 'denied')",
+    );
+  };
+  return {
+    get: () => fail('get'),
+    exists: () => fail('exists'),
+  };
+}

package/src/storage/index.ts

@@ -22,7 +22,7 @@
  */
 
 export { getStorageSandbox, TARGET_SYMBOL } from './service.js';
-export type { FirebaseStorage, StorageOptions, Target, SandboxTarget } from './service.js';
+export type { CrossServiceIam, FirebaseStorage, StorageOptions, Target, SandboxTarget } from './service.js';
 export { getStorage, connectStorageEmulator } from './instances.js';
 
 export { StorageError } from './errors.js';

package/src/storage/list.ts

@@ -52,7 +52,7 @@ export async function listAll(refIn: StorageReference): Promise<ListResult> {
   // requires `read` on the scanned ref's path. Prefixes have no
   // backing object, so `resource` is null (a list of an unauthorized
   // tree throws `storage/unauthorized`, same as a denied read). When
-  // no rules are configured this is a no-op (open-by-default).
+  // no rules are configured, enforcement fails closed.
   enforceRules(service, {
     request: {
       auth: storageAuth(target),

package/src/storage/sandbox/rules-evaluation-error.ts

@@ -1,2 +1,34 @@
 /** Fatal evaluator misuse caught at the allow boundary and converted to a deny. */
 export class RuleEvalError extends Error {}
+
+/**
+ * A construct whose production verdict is unknowable locally: either
+ * production rejects the ruleset at deploy time (undefined function, wrong
+ * arity, unresolved import, unknown namespace method) or the simulator
+ * cannot model the construct at all. Its effect is EVALUATION-WIDE in
+ * production, where a determining `&&`/`||` operand cannot rescue it, so it is
+ * never absorbed and always fails closed.
+ */
+export class RuleUnsupportedError extends RuleEvalError {}
+
+/**
+ * A resource-limit exhaustion (the two-document Firestore lookup cap, the
+ * max call depth). Production fails the WHOLE evaluation closed on these:
+ * they are not CEL error values, so commutative `&&`/`||` absorption must
+ * not turn one into an allow (same posture as the Firestore simulator's
+ * LookupBudgetError precedent).
+ */
+export class RuleResourceLimitError extends RuleEvalError {}
+
+/**
+ * True for the errors that CEL `&&`/`||` absorption may treat as an error
+ * VALUE at an operand boundary: genuine rule-evaluation failures, excluding
+ * the unsupported/compile-reject and resource-limit classes above.
+ */
+export function isAbsorbableEvalError(err: unknown): err is RuleEvalError {
+  return (
+    err instanceof RuleEvalError
+    && !(err instanceof RuleUnsupportedError)
+    && !(err instanceof RuleResourceLimitError)
+  );
+}

package/src/storage/sandbox/rules-evaluator.ts

@@ -12,7 +12,12 @@ import {
 } from './rules.js';
 import { evalMethodCall } from './rules-methods.js';
 import { formatPath, matchSegments, splitPath } from './rules-path-match.js';
-import { RuleEvalError } from './rules-evaluation-error.js';
+import {
+  RuleEvalError,
+  RuleResourceLimitError,
+  RuleUnsupportedError,
+  isAbsorbableEvalError,
+} from './rules-evaluation-error.js';
 import {
   RuleError,
   describeRulesType as describeType,
@@ -92,6 +97,10 @@ export function evaluateStorageRules(
             );
             continue;
           }
+          // Unverified: production's behavior for a non-boolean allow
+          // condition (a CEL type error there, rather than this truthiness
+          // coercion) has not been captured. The coercion stays as written
+          // until a production capture settles it.
           result = truthy(value);
         } catch (err) {
           // Any function-evaluation failure (undefined function, wrong
@@ -186,12 +195,17 @@ export interface EvalCtx {
 /**
  * Walk an `Expr` against the bindings + path params. Missing bindings or
  * members and invalid operations produce `RuleError` values. They propagate
- * unless evaluation short-circuits around them or an explicitly modeled
- * boolean case absorbs them (for example, `<error> || true`). Any `RuleError`
- * that reaches an allow boundary denies with its production-shaped reason.
+ * unless a `&&`/`||` operand that uniquely determines the result absorbs
+ * them COMMUTATIVELY, CEL-style (`<error> || true` → true, and
+ * `<error> && false` → false, see the binary case). Any `RuleError` that
+ * reaches an allow boundary denies with its production-shaped reason.
  *
- * User-defined function failures throw `RuleEvalError`; the allow boundary
- * likewise catches them and denies instead of falling through to a
+ * Function-evaluation failures throw `RuleEvalError`; at a `&&`/`||`
+ * operand boundary the ABSORBABLE ones are converted to error values so
+ * they participate in the same absorption, while unsupported/compile-reject
+ * (`RuleUnsupportedError`) and resource-limit (`RuleResourceLimitError`)
+ * failures re-throw and fail the evaluation closed. The allow boundary
+ * catches whatever still throws and denies instead of falling through to a
  * potentially truthy value.
  */
 export function evalExpr(expr: Expr, ctx: EvalCtx): unknown {
@@ -236,25 +250,37 @@ export function evalExpr(expr: Expr, ctx: EvalCtx): unknown {
     case 'path':
       // A path literal is only meaningful as a `firestore.get()/exists()`
       // argument (handled directly there). Reaching it anywhere else means
-      // the rule used it out of position — deny rather than coerce.
-      throw new RuleEvalError('a Firestore path literal is only valid as an argument to firestore.get()/exists()');
+      // the rule used it out of position, a compile-reject-class failure
+      // (never absorbed): deny rather than coerce.
+      throw new RuleUnsupportedError('a Firestore path literal is only valid as an argument to firestore.get()/exists()');
     case 'unary': {
-      // An error survives negation (production: `!(resource.name == 'x')` with
-      // `name` absent DENIES). Propagate rather than flipping it to `true`.
       const a = evalExpr(expr.arg, ctx);
+      if (expr.op === '!') {
+        if (isErr(a)) {
+          throw new RuleEvalError(a.message);
+        }
+        if (typeof a !== 'boolean') {
+          throw new RuleEvalError(`Unary '!' expects a boolean, got ${describeType(a)}.`);
+        }
+        return !a;
+      }
       if (isErr(a)) return a;
       if (expr.op === '-') {
         if (a instanceof RulesFloat) return new RulesFloat(-a.value);
         if (typeof a !== 'number') return new RuleError(`Unary '-' applied to ${describeType(a)}.`);
         return -a;
       }
-      return !truthy(a);
+      return undefined;
     }
     case 'ternary': {
       const c = evalExpr(expr.cond, ctx);
       // An error condition denies the whole conditional; it must not fall
       // through to the alternate branch and potentially allow.
       if (isErr(c)) return c;
+      // Unverified: production's behavior for a non-boolean ternary
+      // condition (a CEL type error there, rather than this truthiness
+      // coercion) has not been captured. The coercion stays as written
+      // until a production capture settles it.
       return truthy(c) ? evalExpr(expr.then, ctx) : evalExpr(expr.else, ctx);
     }
     case 'in': {
@@ -318,23 +344,12 @@ export function evalExpr(expr: Expr, ctx: EvalCtx): unknown {
       return new RuleError(`Slice applied to ${describeType(t)} (expected a list or string).`);
     }
     case 'binary': {
-      // Short-circuit && / || so half-undefined chains don't trip
-      // (e.g. `request.auth != null && request.auth.uid == 'a'`).
-      if (expr.op === '&&') {
-        const l = evalExpr(expr.left, ctx);
-        if (isErr(l)) return l;
-        return truthy(l) ? evalExpr(expr.right, ctx) : l;
-      }
-      if (expr.op === '||') {
-        const l = evalExpr(expr.left, ctx);
-        if (isErr(l)) {
-          // Production: `<error> || true` ALLOWS — a true disjunct rescues the
-          // error; `<error> || false` stays an error.
-          const r = evalExpr(expr.right, ctx);
-          return truthy(r) ? r : l;
-        }
-        return truthy(l) ? l : evalExpr(expr.right, ctx);
-      }
+      // RULES-B3: && and || are COMMUTATIVE error-absorbing operators in
+      // CEL, not JS left-to-right short-circuit. The two operators differ
+      // only in which operand value uniquely determines the result: false
+      // for &&, true for ||. Both are evaluated by the one helper below.
+      if (expr.op === '&&') return evalAbsorbingOperator(expr.left, expr.right, false, ctx);
+      if (expr.op === '||') return evalAbsorbingOperator(expr.left, expr.right, true, ctx);
       const l = evalExpr(expr.left, ctx);
       if (isErr(l)) return l;
       const r = evalExpr(expr.right, ctx);
@@ -372,6 +387,64 @@ export function evalExpr(expr: Expr, ctx: EvalCtx): unknown {
   }
 }
 
+/**
+ * Evaluate one commutative error-absorbing operator, `&&` or `||`. The two
+ * differ only in `determining`, the operand value that fixes the result on
+ * its own: `false` for `&&`, `true` for `||`.
+ *
+ * If either operand evaluates to `determining`, that is the result and an
+ * error in the other operand is absorbed, whichever side it sits on. So
+ * `error && false` evaluates to false and `error || true` to true, while
+ * `error && true` and `error || false` propagate the error and deny.
+ * Laziness is preserved in the no-error path: a determining left operand
+ * skips the right one entirely.
+ */
+function evalAbsorbingOperator(
+  left: Expr,
+  right: Expr,
+  determining: boolean,
+  ctx: EvalCtx,
+): boolean | RuleError {
+  const l = evalLogicalOperand(left, ctx);
+  if (l === determining) return determining; // left determines; right unevaluated
+  const r = evalLogicalOperand(right, ctx);
+  if (r === determining) return determining; // right determines and absorbs any left error
+  if (isErr(l)) return l;                    // left errored and nothing determined
+  return r;                                  // left was non-determining; right decides
+}
+
+/**
+ * Evaluate one `&&`/`||` operand tri-state: `true`, `false`, or a
+ * {@link RuleError} value the operator may absorb commutatively.
+ *
+ *   - A thrown ABSORBABLE {@link RuleEvalError} (for example
+ *     `firestore.get()` without an injected capability, or `!` on an error)
+ *     is converted to an error VALUE here so a determining sibling operand
+ *     can absorb it: production evaluates these positions to a
+ *     position-local error.
+ *   - {@link RuleUnsupportedError} (compile-reject or unmodelable) and
+ *     {@link RuleResourceLimitError} (lookup cap, call depth) re-throw:
+ *     production fails those closed for the WHOLE evaluation, so no
+ *     determining operand may rescue them (the lookup-budget precedent).
+ *   - A non-boolean, non-error operand is a CEL TYPE error (RULES-B6,
+ *     captured by rules-firestore-strict-boolean-control-flow): it becomes
+ *     an absorbable error value, never a truthy/falsy coercion.
+ */
+function evalLogicalOperand(expr: Expr, ctx: EvalCtx): boolean | RuleError {
+  let v: unknown;
+  try {
+    v = evalExpr(expr, ctx);
+  } catch (err) {
+    if (isAbsorbableEvalError(err)) return new RuleError(err.message);
+    throw err;
+  }
+  if (isErr(v)) return v;
+  if (typeof v !== 'boolean') {
+    return new RuleError(`Expected a boolean '&&'/'||' operand, got ${describeType(v)}.`);
+  }
+  return v;
+}
+
 /**
  * Evaluate a user-defined function call. Arguments are evaluated in the
  * CALLER's context, then bound to the function's parameters; the body
@@ -382,22 +455,26 @@ export function evalExpr(expr: Expr, ctx: EvalCtx): unknown {
  */
 function evalCall(expr: Extract<Expr, { kind: 'call' }>, ctx: EvalCtx): unknown {
   const fn = ctx.funcs.get(expr.name);
+  // Undefined functions, unresolved imports, and arity mismatches are
+  // COMPILE-reject failures in production (the ruleset never deploys), so
+  // they are RuleUnsupportedError: unabsorbable by &&/||, always deny.
   if (!fn) {
-    throw new RuleEvalError(`undefined function ${expr.name}()`);
+    throw new RuleUnsupportedError(`undefined function ${expr.name}()`);
   }
   if (fn.unresolvedImport !== undefined) {
-    throw new RuleEvalError(
+    throw new RuleUnsupportedError(
       `function ${expr.name}() is imported from '${fn.unresolvedImport}', but import module resolution is not implemented`,
     );
   }
   if (fn.params.length !== expr.args.length) {
-    throw new RuleEvalError(
+    throw new RuleUnsupportedError(
       `function ${expr.name}() expects ${fn.params.length} argument(s), got ${expr.args.length}`,
     );
   }
   const depth = ctx.depth + 1;
   if (depth > MAX_CALL_DEPTH) {
-    throw new RuleEvalError(
+    // Resource-limit class: fails the evaluation closed, never absorbed.
+    throw new RuleResourceLimitError(
       `function ${expr.name}() exceeded max call depth ${MAX_CALL_DEPTH}`,
     );
   }

package/src/storage/sandbox/rules-methods.ts

@@ -1,7 +1,11 @@
 import { RulesFloat } from '../../rules/simulator/wrappers/float.js';
 import type { Expr } from './rules.js';
 import { evalExpr, type EvalCtx } from './rules-evaluator.js';
-import { RuleEvalError } from './rules-evaluation-error.js';
+import {
+  RuleEvalError,
+  RuleResourceLimitError,
+  RuleUnsupportedError,
+} from './rules-evaluation-error.js';
 import {
   RuleError,
   describeRulesType as describeType,
@@ -86,7 +90,10 @@ export function evalMethodCall(expr: Extract<Expr, { kind: 'methodcall' }>, ctx:
     return evalMapGet(expr, ctx);
   }
 
-  throw new RuleEvalError(`unsupported method .${expr.method}()`);
+  // An unknown method name is either unmodeled here or rejected by
+  // production's compiler. Its verdict is unknowable locally, so it is
+  // unabsorbable (fails closed even under a determining &&/|| operand).
+  throw new RuleUnsupportedError(`unsupported method .${expr.method}()`);
 }
 
 /**
@@ -111,7 +118,8 @@ function evalFirestoreBuiltin(
   ctx: EvalCtx,
 ): unknown {
   if (expr.method !== 'get' && expr.method !== 'exists') {
-    throw new RuleEvalError(`unsupported method firestore.${expr.method}()`);
+    // Unknown namespace method, compile-reject class, never absorbed.
+    throw new RuleUnsupportedError(`unsupported method firestore.${expr.method}()`);
   }
   if (!ctx.firestoreLookup) {
     // No sandbox-backed capability injected — keep the deny-with-reason
@@ -121,16 +129,20 @@ function evalFirestoreBuiltin(
     );
   }
   if (expr.args.length !== 1) {
-    throw new RuleEvalError(`firestore.${expr.method}() expects a single path argument`);
+    // Wrong call shape: production rejects at compile; never absorbed.
+    throw new RuleUnsupportedError(`firestore.${expr.method}() expects a single path argument`);
   }
   const arg = expr.args[0];
   if (arg.kind !== 'path') {
-    throw new RuleEvalError(`firestore.${expr.method}() requires a /databases/.../documents/... path literal`);
+    throw new RuleUnsupportedError(`firestore.${expr.method}() requires a /databases/.../documents/... path literal`);
   }
   const docPath = buildFirestoreDocPath(arg, ctx);
   if (!ctx.firestoreAccesses.has(docPath)) {
     if (ctx.firestoreAccesses.size >= 2) {
-      throw new RuleEvalError('firestore access limit exceeded: at most two distinct documents');
+      // Resource-limit class, the same posture as the Firestore lookup
+      // budget: production fails the whole evaluation closed, so a
+      // determining &&/|| operand must NOT absorb this into an allow.
+      throw new RuleResourceLimitError('firestore access limit exceeded: at most two distinct documents');
     }
     ctx.firestoreAccesses.add(docPath);
   }
@@ -140,7 +152,9 @@ function evalFirestoreBuiltin(
   const fields = ctx.firestoreLookup.get(docPath);
   if (fields === null) {
     // A missing get is a Rules error VALUE: it denies at the allow boundary,
-    // but participates in CEL error absorption (`error || true` allows).
+    // but participates in COMMUTATIVE CEL error absorption in `&&`/`||`
+    // (`error || true` allows, and `error && false` evaluates to false,
+    // see the tri-state operand handling in rules-evaluator.ts).
     return new RuleError(`firestore.get() targeted a nonexistent document: ${docPath}`);
   }
   return { data: fields };