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

package/src/messaging/sw.ts

@@ -12,6 +12,7 @@
  * routing between the two planes is a single visibility decision.
  */
 import type { FirebaseApp } from '../app/types.js';
+import type { Sandbox, SandboxContext } from '../sandbox/index.js';
 import {
   defaultRegistration,
   deliverToMessaging,
@@ -50,8 +51,8 @@ export type {
  * service-worker plane (upstream: `getMessagingInSw`, component name
  * `messaging-sw`).
  */
-export function getMessaging(app?: FirebaseApp): Messaging {
-  return resolveMessaging('sw', app);
+export function getMessaging(target?: FirebaseApp | Sandbox | SandboxContext): Messaging {
+  return resolveMessaging('sw', target);
 }
 
 /**

package/src/performance/index.ts

@@ -0,0 +1,31 @@
+/**
+ * `pyric/performance` — a DEFERRED mirror of `firebase/performance`.
+ *
+ * Performance Monitoring instruments real network and render timings and
+ * ships them to Google. Nothing about it is locally observable, so it is
+ * deferred.
+ *
+ * Every symbol below resolves and links so an app that swaps `firebase` for
+ * `pyric` still loads; touching one throws `PyricDeferredApiError` naming this
+ * subpath. See `../deferred/entry.ts` for the full rationale.
+ *
+ * The value list is the exact public runtime surface of `firebase/performance`
+ * (Firebase Web SDK 12.13.0). Keep it in sync when this entry graduates to a
+ * real mirror.
+ */
+import { deferredEntry, type DeferredApi } from '../deferred/entry.js';
+
+export { PyricDeferredApiError } from '../deferred/entry.js';
+
+export const {
+  getPerformance, initializePerformance, trace,
+} = deferredEntry('performance');
+
+// Type declarations. Aliased to the deferred placeholder so a consumer's own
+// annotations keep type-checking: every deferred call returns `never`, which is
+// assignable to any of these. Names that Firebase exports as a CLASS appear both
+// here and above — a class is a value and a type, and both meanings must survive
+// the swap.
+export type FirebasePerformance = DeferredApi;
+export type PerformanceSettings = DeferredApi;
+export type PerformanceTrace = DeferredApi;

package/src/remote-config/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `pyric/remote-config` — a DEFERRED mirror of `firebase/remote-config`.
+ *
+ * Remote Config serves server-side parameter values with fetch/activate
+ * caching semantics. Mirroring it needs a sandbox-side config store and a
+ * model of the fetch throttle — buildable, not yet built.
+ *
+ * Every symbol below resolves and links so an app that swaps `firebase` for
+ * `pyric` still loads; touching one throws `PyricDeferredApiError` naming this
+ * subpath. See `../deferred/entry.ts` for the full rationale.
+ *
+ * The value list is the exact public runtime surface of `firebase/remote-config`
+ * (Firebase Web SDK 12.13.0). Keep it in sync when this entry graduates to a
+ * real mirror.
+ */
+import { deferredEntry, type DeferredApi } from '../deferred/entry.js';
+
+export { PyricDeferredApiError } from '../deferred/entry.js';
+
+export const {
+  activate, ensureInitialized, fetchAndActivate, fetchConfig, getAll, getBoolean, getNumber,
+  getRemoteConfig, getString, getValue, onConfigUpdate, setCustomSignals,
+  setLogLevel,
+} = deferredEntry('remote-config');
+
+/**
+ * The one deferred symbol that answers instead of throwing: the real SDK
+ * resolves a boolean, and a deferred entry IS unsupported, so the standard
+ * `isSupported().then(ok => ok && get…(app))` guard must run — not crash.
+ */
+export const isSupported = async (): Promise<boolean> => false;
+
+
+// Type declarations. Aliased to the deferred placeholder so a consumer's own
+// annotations keep type-checking: every deferred call returns `never`, which is
+// assignable to any of these. Names that Firebase exports as a CLASS appear both
+// here and above — a class is a value and a type, and both meanings must survive
+// the swap.
+export type ConfigUpdate = DeferredApi;
+export type ConfigUpdateObserver = DeferredApi;
+export type CustomSignals = DeferredApi;
+export type FetchResponse = DeferredApi;
+export type FetchStatus = DeferredApi;
+export type FetchType = DeferredApi;
+export type FirebaseExperimentDescription = DeferredApi;
+export type FirebaseRemoteConfigObject = DeferredApi;
+export type LogLevel = DeferredApi;
+export type RemoteConfig = DeferredApi;
+export type RemoteConfigOptions = DeferredApi;
+export type RemoteConfigSettings = DeferredApi;
+export type Unsubscribe = DeferredApi;
+export type Value = DeferredApi;
+export type ValueSource = DeferredApi;

package/src/rules/grammar/FirestoreValidator.ts

@@ -2,6 +2,7 @@ import type {
   FirestoreRules, MatchBlock, AllowRule, FunctionDef, Expression, Operation,
 } from './FirestoreAST.js';
 import { RULES_BUILTIN_FUNCTIONS } from './builtin-functions.js';
+import { countDocumentAccessCalls } from './document-access-count.js';
 
 export interface ValidationFinding {
   code: string;
@@ -26,8 +27,9 @@ export function validateFirestoreRules(ast: FirestoreRules): ValidationFinding[]
   // SEC-4: Check for default deny
   checkDefaultDeny(rootMatch, findings);
 
-  // QUA-3: Duplicate function names
-  checkDuplicateFunctions(rootMatch, findings);
+  // QUA-3: Duplicate function names in one scope (production compile
+  // rejection, so critical). Nested shadowing is legal and is not flagged.
+  checkDuplicateFunctions(ast, findings);
 
   // QUA-4: Unused functions
   checkUnusedFunctions(rootMatch, allCalls, findings);
@@ -124,12 +126,15 @@ function walkMatch(
       });
     }
 
-    // SEM-3: get()/exists() budget exceeded
-    const docReads = countDocReads(cond, new Map(localScope.map(f => [f.name, f])));
+    // SEM-3: document access budget exceeded. Production allows exactly 10
+    // get/exists/getAfter/existsAfter reads per request evaluation; the
+    // 11th fails, so the finding fires only ABOVE 10 (same boundary as the
+    // linter's GET_COUNT error and the simulator's runtime LookupBudget).
+    const docReads = countDocumentAccessCalls(cond, fnMap);
     if (docReads > 10) {
       findings.push({
         code: 'SEM-3', severity: 'high', path: pathStr, operation: opStr,
-        message: `Rule at ${pathStr} has ${docReads} document reads (get/exists) — exceeds the 10-call budget`,
+        message: `Rule at ${pathStr} may perform ${docReads} document access calls (get/exists/getAfter/existsAfter), which exceeds the 10-call budget`,
       });
     }
 
@@ -323,21 +328,6 @@ function referencesResourceData(expr: Expression): boolean {
   );
 }
 
-function countDocReads(expr: Expression, functions: Map<string, FunctionDef>, visited = new Set<string>()): number {
-  let count = 0;
-  walkExpr(expr, e => {
-    if (e.type === 'functionCall' && (e.name === 'get' || e.name === 'exists' || e.name === 'getAfter')) {
-      count++;
-    }
-    // Follow user-defined function calls
-    if (e.type === 'functionCall' && functions.has(e.name) && !visited.has(e.name)) {
-      visited.add(e.name);
-      count += countDocReads(functions.get(e.name)!.body, functions, visited);
-    }
-  });
-  return count;
-}
-
 function collectFunctionCalls(expr: Expression): string[] {
   const calls: string[] = [];
   walkExpr(expr, e => {
@@ -357,22 +347,48 @@ function collectAllFunctions(match: MatchBlock): Set<string> {
 }
 
 // ---- QUA-3: Duplicate functions ----
+//
+// Production REJECTS two declarations of one function name in the SAME
+// scope at compile time, so this is severity 'critical': the write gate
+// (`write/handler.ts`) blocks only critical validator findings, and
+// 'medium' folded to a mere warning that deployed anyway.
+//
+// A scope is one declaration list: the global list above `service`, the
+// list directly inside `service`, or one match block's own list. A nested
+// match block that redeclares a name from an enclosing scope SHADOWS it and
+// is legal: the simulator implements shadowing in
+// `simulator/match-resolution.ts`, and the production capture in
+// `conformance/rules-corpus/storage/function-scopes-and-shadowing.ts` pins
+// inner-shadows-outer as accepted. Flagging that would block a ruleset
+// production deploys.
+//
+// The code stays QUA-3 (already registered and asserted by consumers);
+// `DUPLICATE_FUNCTION` was considered and rejected, because the module
+// resolver already uses that name for its own error code
+// (`modules/resolver-core.ts`), and colliding would make mixed issue
+// lists ambiguous.
+
+function checkDuplicateFunctions(ast: FirestoreRules, findings: ValidationFinding[]) {
+  checkDupsInScope(ast.functions ?? [], 'global scope', findings);
+  checkDupsInScope(ast.service.functions ?? [], `service ${ast.service.name}`, findings);
+  checkDupsInMatchScopes(ast.service.match, findings);
+}
 
-function checkDuplicateFunctions(match: MatchBlock, findings: ValidationFinding[]) {
+function checkDupsInMatchScopes(match: MatchBlock, findings: ValidationFinding[]) {
   checkDupsInScope(match.functions, match.path.raw, findings);
-  for (const child of match.children) checkDuplicateFunctions(child, findings);
+  for (const child of match.children) checkDupsInMatchScopes(child, findings);
 }
 
-function checkDupsInScope(fns: FunctionDef[], path: string, findings: ValidationFinding[]) {
-  const seen = new Set<string>();
+function checkDupsInScope(fns: readonly FunctionDef[], scope: string, findings: ValidationFinding[]) {
+  const declared = new Set<string>();
   for (const fn of fns) {
-    if (seen.has(fn.name)) {
+    if (declared.has(fn.name)) {
       findings.push({
-        code: 'QUA-3', severity: 'medium', path,
-        message: `Duplicate function '${fn.name}' in scope at ${path}`,
+        code: 'QUA-3', severity: 'critical', path: scope,
+        message: `Duplicate function '${fn.name}' declared twice in ${scope}. Production rejects duplicate function declarations in one scope at compile time`,
       });
     }
-    seen.add(fn.name);
+    declared.add(fn.name);
   }
 }
 

package/src/rules/grammar/document-access-count.ts

@@ -0,0 +1,75 @@
+import type { Expression, FunctionDef } from './FirestoreAST.js';
+
+/**
+ * The four built-in document access calls production counts against a
+ * request's 10-read budget.
+ */
+const DOCUMENT_ACCESS_BUILTINS = new Set(['get', 'exists', 'getAfter', 'existsAfter']);
+
+/**
+ * Count the document access calls (get/exists/getAfter/existsAfter)
+ * reachable from a rule condition, expanding each user-defined function
+ * once PER CALL SITE. `isOwner(a) && isOwner(b) && isOwner(c)` with three
+ * gets inside `isOwner` costs nine, matching production where each call
+ * performs its own reads (different arguments mean different paths).
+ * A function's `let` bindings evaluate on every call, so their reads count
+ * too. The call stack guards recursion only, and entries unwind on return,
+ * so sibling call sites each pay full price.
+ *
+ * This is a static over-approximation: production caches repeated reads of
+ * the SAME path within a request (see site-docs
+ * secure/firestore-rules-limits.md), but path identity is not decidable
+ * statically, so every call site is charged. The cache-aware, distinct-path
+ * count is the runtime concern of LookupBudget in
+ * simulator/lookup-budget.ts, which counts what an evaluation actually
+ * reads rather than what a condition could reach.
+ *
+ * This is the single walker behind both static consumers: the validator's
+ * SEM-3 finding and the linter's GET_COUNT warning.
+ */
+export function countDocumentAccessCalls(
+  expr: Expression,
+  functions: Map<string, FunctionDef>,
+  callStack: Set<string> = new Set<string>(),
+): number {
+  let count = 0;
+
+  const visit = (e: Expression): void => {
+    switch (e.type) {
+      case 'functionCall':
+        if (DOCUMENT_ACCESS_BUILTINS.has(e.name)) {
+          count++;
+        } else {
+          const fn = functions.get(e.name);
+          const isExpandable = fn !== undefined && !callStack.has(e.name);
+          if (isExpandable) {
+            callStack.add(e.name);
+            for (const binding of fn!.lets) visit(binding.value);
+            visit(fn!.body);
+            callStack.delete(e.name); // unwind: count once per call site, not once per rule
+          }
+        }
+        e.args.forEach(visit);
+        break;
+      case 'binaryOp': visit(e.left); visit(e.right); break;
+      case 'unaryOp': visit(e.operand); break;
+      case 'ternary': visit(e.condition); visit(e.consequent); visit(e.alternate); break;
+      case 'methodCall': visit(e.object); e.args.forEach(visit); break;
+      case 'memberAccess': visit(e.object); break;
+      case 'bracketAccess': visit(e.object); visit(e.index); break;
+      case 'sliceAccess': visit(e.object); visit(e.start); visit(e.end); break;
+      case 'inExpr': visit(e.element); visit(e.collection); break;
+      case 'isExpr': visit(e.value); break;
+      case 'listLiteral': e.elements.forEach(visit); break;
+      case 'mapLiteral': e.entries.forEach((entry) => { visit(entry.key); visit(entry.value); }); break;
+      case 'pathLiteral':
+        for (const segment of e.segments) {
+          if (typeof segment !== 'string') visit(segment);
+        }
+        break;
+    }
+  };
+
+  visit(expr);
+  return count;
+}

package/src/rules/linter/ast-utils.ts

@@ -218,44 +218,10 @@ export function maxCallDepth(start: string, graph: Map<string, string[]>, visite
   return 1 + max;
 }
 
-/**
- * Count get() and exists() calls reachable from an expression,
- * following function calls transitively.
- */
-export function countGetCalls(expr: Expression, functions: Map<string, FunctionDef>, visited = new Set<string>()): number {
-  let count = 0;
-  const walk = (e: Expression) => {
-    switch (e.type) {
-      case 'functionCall':
-        if (e.name === 'get' || e.name === 'exists') {
-          count++;
-        } else if (functions.has(e.name) && !visited.has(e.name)) {
-          visited.add(e.name);
-          const fn = functions.get(e.name)!;
-          walk(fn.body);
-          for (const b of fn.lets) walk(b.value);
-        }
-        e.args.forEach(walk);
-        break;
-      case 'binaryOp': walk(e.left); walk(e.right); break;
-      case 'unaryOp': walk(e.operand); break;
-      case 'methodCall': walk(e.object); e.args.forEach(walk); break;
-      case 'memberAccess': walk(e.object); break;
-      case 'bracketAccess': walk(e.object); walk(e.index); break;
-      case 'ternary': walk(e.condition); walk(e.consequent); walk(e.alternate); break;
-      case 'inExpr': walk(e.element); walk(e.collection); break;
-      case 'isExpr': walk(e.value); break;
-      case 'listLiteral': e.elements.forEach(walk); break;
-      case 'mapLiteral': e.entries.forEach(en => { walk(en.key); walk(en.value); }); break;
-    }
-  };
-  walk(expr);
-  return count;
-}
-
 /**
  * Count how many times each user-defined function is called in an expression.
- * Unlike countGetCalls (which deduplicates), this counts raw call-site occurrences.
+ * Counts raw call-site occurrences at the top level only: it does not expand
+ * nested user-function bodies the way countDocumentAccessCalls does.
  */
 export function countFunctionCallSites(expr: Expression, fnNames: Set<string>): Map<string, number> {
   const counts = new Map<string, number>();

package/src/rules/linter/hallucinations.ts

@@ -95,7 +95,14 @@ const HALLUCINATED_GLOBALS: Record<string, string> = {
   undefined:  '`undefined` does not exist in rules — use `null`',
 };
 
-const VALID_MATH_METHODS = new Set(['abs', 'ceil', 'floor', 'round', 'sqrt', 'pow', 'isNaN']);
+/**
+ * The math-namespace functions production Firestore actually compiles.
+ * Notably ABSENT: `isInfinite`. Reference docs list it, but production
+ * rejects it at compile (`Function not found error: Name: [math.isInfinite]`).
+ * Exported so the stdlib-modules drift test can assert the documented
+ * catalog never re-grows a name this validator rejects.
+ */
+export const VALID_MATH_METHODS = new Set(['abs', 'ceil', 'floor', 'round', 'sqrt', 'pow', 'isNaN']);
 
 
 /**
@@ -122,6 +129,21 @@ const WRONG_CONTEXT_PATHS: WrongPath[] = [
     suggestion: '`resource.id` is not available — capture the document id with `/{docId}` in the match path' },
 ];
 
+/**
+ * Auth-token claims that are typed BOOL in production. Comparing one
+ * against a STRING literal compiles fine (CEL is dynamically typed) but
+ * the comparison is cross-type, so `== "true"` is always false and
+ * `!= "true"` is always true, and the latter silently opens the rule.
+ * WRONG_CONTEXT_PATHS can't express this: it matches `receiver.property`
+ * at depth 2, while token claims live at `request.auth.token.<claim>`
+ * and the bug is in the *comparison*, not the path itself.
+ *
+ * Only claims verifiably typed bool belong here. `email_verified` is the
+ * documented one (`request.auth.token.email_verified: bool`).
+ * `firebase.sign_in_provider` is a string, so it is deliberately NOT listed.
+ */
+const BOOL_TOKEN_CLAIMS = new Set(['email_verified']);
+
 /**
  * Built-in CEL methods that, when accessed without parentheses, are
  * almost certainly a missing-call mistake. Restricted to a small
@@ -186,40 +208,51 @@ interface Loc {
   ruleIndex?: number;
 }
 
+/**
+ * Visit every expression in the match tree, carrying the set of
+ * user-defined function names visible where the expression sits. Scope
+ * accumulates outward-in: a block sees its own declarations plus every
+ * enclosing scope's, which is the resolution order the simulator
+ * implements in `simulator/match-resolution.ts`.
+ */
 function walkAllExpressions(
   match: MatchBlock,
-  visit: (expr: Expression, loc: Loc) => void,
+  inheritedScope: ReadonlySet<string>,
+  visit: (expr: Expression, loc: Loc, scope: ReadonlySet<string>) => void,
 ) {
   const path = match.path.raw;
+  const scope = new Set(inheritedScope);
+  for (const fn of match.functions) scope.add(fn.name);
   for (const fn of match.functions) {
     const loc: Loc = { matchPath: path, functionName: fn.name };
-    walkExpr(fn.body, loc, visit);
-    for (const b of fn.lets) walkExpr(b.value, loc, visit);
+    walkExpr(fn.body, loc, scope, visit);
+    for (const b of fn.lets) walkExpr(b.value, loc, scope, visit);
   }
   for (let i = 0; i < match.allows.length; i++) {
-    walkExpr(match.allows[i].condition, { matchPath: path, ruleIndex: i }, visit);
+    walkExpr(match.allows[i].condition, { matchPath: path, ruleIndex: i }, scope, visit);
   }
-  for (const child of match.children) walkAllExpressions(child, visit);
+  for (const child of match.children) walkAllExpressions(child, scope, visit);
 }
 
 function walkExpr(
   expr: Expression,
   loc: Loc,
-  visit: (expr: Expression, loc: Loc) => void,
+  scope: ReadonlySet<string>,
+  visit: (expr: Expression, loc: Loc, scope: ReadonlySet<string>) => void,
 ) {
-  visit(expr, loc);
+  visit(expr, loc, scope);
   switch (expr.type) {
-    case 'binaryOp': walkExpr(expr.left, loc, visit); walkExpr(expr.right, loc, visit); break;
-    case 'unaryOp': walkExpr(expr.operand, loc, visit); break;
-    case 'methodCall': walkExpr(expr.object, loc, visit); expr.args.forEach(a => walkExpr(a, loc, visit)); break;
-    case 'memberAccess': walkExpr(expr.object, loc, visit); break;
-    case 'bracketAccess': walkExpr(expr.object, loc, visit); walkExpr(expr.index, loc, visit); break;
-    case 'ternary': walkExpr(expr.condition, loc, visit); walkExpr(expr.consequent, loc, visit); walkExpr(expr.alternate, loc, visit); break;
-    case 'inExpr': walkExpr(expr.element, loc, visit); walkExpr(expr.collection, loc, visit); break;
-    case 'isExpr': walkExpr(expr.value, loc, visit); break;
-    case 'listLiteral': expr.elements.forEach(e => walkExpr(e, loc, visit)); break;
-    case 'mapLiteral': expr.entries.forEach(en => { walkExpr(en.key, loc, visit); walkExpr(en.value, loc, visit); }); break;
-    case 'functionCall': expr.args.forEach(a => walkExpr(a, loc, visit)); break;
+    case 'binaryOp': walkExpr(expr.left, loc, scope, visit); walkExpr(expr.right, loc, scope, visit); break;
+    case 'unaryOp': walkExpr(expr.operand, loc, scope, visit); break;
+    case 'methodCall': walkExpr(expr.object, loc, scope, visit); expr.args.forEach(a => walkExpr(a, loc, scope, visit)); break;
+    case 'memberAccess': walkExpr(expr.object, loc, scope, visit); break;
+    case 'bracketAccess': walkExpr(expr.object, loc, scope, visit); walkExpr(expr.index, loc, scope, visit); break;
+    case 'ternary': walkExpr(expr.condition, loc, scope, visit); walkExpr(expr.consequent, loc, scope, visit); walkExpr(expr.alternate, loc, scope, visit); break;
+    case 'inExpr': walkExpr(expr.element, loc, scope, visit); walkExpr(expr.collection, loc, scope, visit); break;
+    case 'isExpr': walkExpr(expr.value, loc, scope, visit); break;
+    case 'listLiteral': expr.elements.forEach(e => walkExpr(e, loc, scope, visit)); break;
+    case 'mapLiteral': expr.entries.forEach(en => { walkExpr(en.key, loc, scope, visit); walkExpr(en.value, loc, scope, visit); }); break;
+    case 'functionCall': expr.args.forEach(a => walkExpr(a, loc, scope, visit)); break;
   }
 }
 
@@ -231,9 +264,19 @@ function walkExpr(
  * distinct (rule, key, location) tuple — duplicate identical patterns
  * within the same rule are de-duplicated.
  */
-function isUnsupportedDebugCall(expr: Expression, allowDebug?: boolean): boolean {
+/**
+ * A `debug(...)` call that resolves to NOTHING. Production has no built-in
+ * `debug`, but a ruleset is free to declare `function debug(v) { ... }`, and
+ * that call resolves and evaluates like any other user function, so only an
+ * unresolved call is a finding.
+ */
+function isUnresolvedDebugCall(
+  expr: Expression,
+  scope: ReadonlySet<string>,
+  allowDebug?: boolean,
+): boolean {
   if (allowDebug) return false;
-  return expr.type === 'functionCall' && expr.name === 'debug';
+  return expr.type === 'functionCall' && expr.name === 'debug' && !scope.has('debug');
 }
 
 function isHallucinatedMethodCall(expr: Expression): boolean {
@@ -275,6 +318,37 @@ function isWrongContextPath(expr: Expression): { suggestion: string } | undefine
   return WRONG_CONTEXT_PATHS.find(p => p.receiver === recv && p.property === prop);
 }
 
+/** Is `expr` a member access spelling exactly `request.auth.token.<claim>`
+ *  for a claim in BOOL_TOKEN_CLAIMS? */
+function boolTokenClaimName(expr: Expression): string | undefined {
+  if (expr.type !== 'memberAccess' || !BOOL_TOKEN_CLAIMS.has(expr.property)) return undefined;
+  const token = expr.object;
+  if (token.type !== 'memberAccess' || token.property !== 'token') return undefined;
+  const auth = token.object;
+  if (auth.type !== 'memberAccess' || auth.property !== 'auth') return undefined;
+  return auth.object.type === 'identifier' && auth.object.name === 'request'
+    ? expr.property
+    : undefined;
+}
+
+/**
+ * `request.auth.token.email_verified == "true"` (or `!=`, either operand
+ * order). The claim is a bool; a string literal can never equal it, so the
+ * comparison is a constant: `==` always denies, `!=` always allows.
+ */
+function boolTokenClaimStringComparison(
+  expr: Expression,
+): { claim: string; op: string; literal: string } | undefined {
+  if (expr.type !== 'binaryOp' || (expr.op !== '==' && expr.op !== '!=')) return undefined;
+  for (const [side, other] of [[expr.left, expr.right], [expr.right, expr.left]] as const) {
+    const claim = boolTokenClaimName(side);
+    if (claim && other.type === 'literal' && typeof other.value === 'string') {
+      return { claim, op: expr.op, literal: other.value };
+    }
+  }
+  return undefined;
+}
+
 function isLengthPropertyAccessOnMethod(expr: Expression): boolean {
   return expr.type === 'memberAccess' && expr.property === 'length' && expr.object.type === 'methodCall';
 }
@@ -301,14 +375,23 @@ export function checkHallucinations(ast: FirestoreRules, options: { allowDebug?:
     warnings.push(w);
   }
 
-  walkAllExpressions(ast.service.match, (expr, loc) => {
-    if (isUnsupportedDebugCall(expr, options.allowDebug)) {
+  // Functions declared above `service` and directly inside it are visible
+  // everywhere below, so they seed the scope the walk carries down.
+  const outerScope = new Set<string>();
+  for (const fn of ast.functions ?? []) outerScope.add(fn.name);
+  for (const fn of ast.service.functions ?? []) outerScope.add(fn.name);
+
+  walkAllExpressions(ast.service.match, outerScope, (expr, loc, scope) => {
+    if (isUnresolvedDebugCall(expr, scope, options.allowDebug)) {
       emit('HALLUCINATED_GLOBAL', 'debug', loc, {
         rule: 'HALLUCINATED_GLOBAL',
         severity: 'error',
-        message: '`debug()` helper is only permitted in local testing environments; remove it before deployment.',
+        message:
+          '`debug()` is not a Firestore rules function and no function named `debug` is declared in scope. '
+          + 'Production rejects the whole ruleset at compile time with '
+          + '`Function not found error: Name: [debug]`, so nothing in the file deploys.',
         location: loc,
-        fix: 'Remove debug() wrapper around the expression.',
+        fix: 'Remove the debug() call and evaluate the inner expression directly.',
       });
     }
 
@@ -400,6 +483,21 @@ export function checkHallucinations(ast: FirestoreRules, options: { allowDebug?:
       }
     }
 
+    const boolClaim = boolTokenClaimStringComparison(expr);
+    if (boolClaim) {
+      const { claim, op, literal } = boolClaim;
+      emit('BOOL_TOKEN_CLAIM', `${claim}|${op}|${literal}`, loc, {
+        rule: 'BOOL_TOKEN_CLAIM',
+        severity: 'error',
+        message:
+          `\`request.auth.token.${claim}\` is a bool, but it is compared against the string ` +
+          `"${literal}", a cross-type comparison that is always ${op === '==' ? 'false (rule always denies)' : 'true (rule silently allows)'}. ` +
+          `Compare against the boolean literal instead: \`request.auth.token.${claim} ${op} true\`.`,
+        location: loc,
+        fix: `Drop the quotes: \`request.auth.token.${claim} ${op} ${literal === 'false' ? 'false' : 'true'}\`.`,
+      });
+    }
+
     if (isLengthPropertyAccessOnMethod(expr)) {
       emit('LENGTH_PROPERTY', '', loc, {
         rule: 'LENGTH_PROPERTY',

package/src/rules/linter/linter.ts

@@ -18,7 +18,6 @@ import {
   extractFirstExpression,
   buildCallGraph,
   maxCallDepth,
-  countGetCalls,
   countFunctionCallSites,
   functionContainsGet,
   referencesRequestTime,
@@ -26,6 +25,7 @@ import {
   collectAllRules,
 } from './ast-utils.js';
 import { checkSyntaxHints, checkHallucinations } from './hallucinations.js';
+import { countDocumentAccessCalls } from '../grammar/document-access-count.js';
 
 // ═══ Types ═══
 
@@ -93,7 +93,11 @@ const THRESHOLDS = {
   CALL_DEPTH_WARN: 6,
   CALL_DEPTH_ERROR: 10,
   GET_COUNT_WARN: 5,
-  GET_COUNT_ERROR: 10,               // documented by Google
+  // Production allows EXACTLY 10 document access calls per request
+  // evaluation; the 11th fails (site-docs secure/firestore-rules-limits.md).
+  // Error fires strictly ABOVE this value, the same boundary as SEM-3 and
+  // the simulator's runtime LookupBudget.
+  GET_COUNT_ERROR: 10,
 };
 
 // ═══ Lint Rules ═══
@@ -350,12 +354,14 @@ function checkGetCount(
   for (const fn of allFunctions) fnMap.set(fn.name, fn);
 
   for (let i = 0; i < rules.length; i++) {
-    const count = countGetCalls(rules[i].rule.condition, fnMap);
-    if (count >= THRESHOLDS.GET_COUNT_ERROR) {
+    const count = countDocumentAccessCalls(rules[i].rule.condition, fnMap);
+    // Error only ABOVE the limit: production allows exactly 10 and fails
+    // the 11th, so a rule at exactly 10 is legal (still worth the WARN).
+    if (count > THRESHOLDS.GET_COUNT_ERROR) {
       warnings.push({
         rule: 'GET_COUNT',
         severity: 'error',
-        message: `Rule #${i} may invoke ${count} get()/exists() calls. Limit is ${THRESHOLDS.GET_COUNT_ERROR}.`,
+        message: `Rule #${i} may invoke ${count} get()/exists()/getAfter()/existsAfter() calls. Limit is ${THRESHOLDS.GET_COUNT_ERROR}.`,
         location: { ruleIndex: i },
         fix: 'Cache get() results via a config() wrapper function. Same-path calls are cached by Firestore.',
       });
@@ -363,7 +369,7 @@ function checkGetCount(
       warnings.push({
         rule: 'GET_COUNT',
         severity: 'warning',
-        message: `Rule #${i} invokes ${count} get()/exists() calls. Limit is ${THRESHOLDS.GET_COUNT_ERROR}.`,
+        message: `Rule #${i} invokes ${count} get()/exists()/getAfter()/existsAfter() calls. Limit is ${THRESHOLDS.GET_COUNT_ERROR}.`,
         location: { ruleIndex: i },
       });
     }
@@ -767,7 +773,16 @@ export interface LintOptions {
    * block linting of a valid current ruleset.
    */
   previousSource?: string;
-  /** Set to true when validating in a local emulator or testing environment where debug() is permitted. */
+  /**
+   * Set to true ONLY when linting a scratch ruleset that will never be
+   * deployed and an unresolved `debug()` call should be tolerated.
+   * Production Firestore rejects a ruleset that calls `debug()` at compile
+   * time (`Function not found error: Name: [debug]`), so the linter rejects
+   * it by default, including when `testCases` is supplied. A ruleset that
+   * declares its own `function debug(...)` is never flagged, with or
+   * without this flag. This flag is an explicit caller choice; it is never
+   * inferred from other options.
+   */
   allowDebug?: boolean;
 }
 
@@ -836,8 +851,15 @@ export function lintFirestoreRules(source: string, options: LintOptions = {}): L
   // Rule 8: Get duplication (same get()-containing function called multiple times)
   checkGetDuplication(allRules, allFunctions, warnings);
 
-  // Rule 9: Hallucinations — JS-style code that parses but fails at runtime
-  warnings.push(...checkHallucinations(ast, { allowDebug: options.allowDebug || Boolean(options.testCases && options.testCases.length > 0) }));
+  // Rule 9: Hallucinations, JS-style code that parses but fails at runtime.
+  // `allowDebug` is an EXPLICIT caller opt-in only. It used to be implied by
+  // a non-empty `testCases` array, which silently disabled the debug()
+  // rejection in any lint run that also carried a test suite, exactly the
+  // authoring path that feeds the write gate. Production rejects debug() at
+  // compile time (`Function not found error: Name: [debug]`), so the default
+  // must reject; a caller linting a ruleset that will never deploy can still
+  // pass `allowDebug: true`.
+  warnings.push(...checkHallucinations(ast, { allowDebug: options.allowDebug }));
 
   // Rule 9.5: Always-true predicates and recursive-wildcard open rules.
   // Severity: error so deployRules refuses to swap. The agent's #1
@@ -884,7 +906,7 @@ export function lintFirestoreRules(source: string, options: LintOptions = {}): L
   let maxExprs = 0;
   let maxGets = 0;
   for (const r of allRules) {
-    const gets = countGetCalls(r.rule.condition, fnMap);
+    const gets = countDocumentAccessCalls(r.rule.condition, fnMap);
     if (gets > maxGets) maxGets = gets;
   }