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

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;

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