pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/database/sandbox/operation-events.ts

@@ -1,11 +1,6 @@
 import type { AuthState, Sandbox, SandboxOperationEvent } from 'pyric/sandbox';
-import {
-  emitSandboxEvent,
-  makeSandboxCommitEvent,
-  makeSandboxListenerEvent,
-  makeSandboxOperationEvent,
-  makeServiceMutationEvent,
-} from 'pyric/sandbox/internal';
+import type { ListenerOwner } from '../../sandbox/types/events.js';
+import { emitSandboxEvent, getClock, makeSandboxCommitEvent, makeSandboxListenerEvent, makeSandboxOperationEvent, makeServiceMutationEvent } from 'pyric/sandbox/internal';
 import { joinPath, pathSegments } from './data-tree.js';
 import type { ChildListener, ValueListener } from './listener-types.js';
 import type { RuleCheck, RuleEvaluationDetails } from './rules-eval.js';
@@ -45,6 +40,7 @@ export class OperationEvents {
     if (!this.sandbox) return;
     try {
       emitSandboxEvent(this.sandbox, makeServiceMutationEvent({
+        at: getClock(this.sandbox).now(),
         service: 'rtdb', op, path, auth,
         before: fields.before, after: fields.after, detail: fields.detail,
       }), { service: 'rtdb' });
@@ -87,6 +83,13 @@ export class OperationEvents {
       if (fields.origin) {
         originVal = fields.origin;
       }
+      // A caller that already resolved the operation's instant passes it, so the
+      // event and the write it describes agree exactly. A caller that did not
+      // reads the same clock here rather than falling back to the wall clock.
+      let at = fields.at;
+      if (at === undefined) {
+        at = getClock(this.sandbox).now();
+      }
       emitSandboxEvent(this.sandbox, makeSandboxOperationEvent({
         service: 'rtdb', method, path: canonicalPath(path), auth, result,
         origin: originVal, durationMs: fields.durationMs,
@@ -95,7 +98,7 @@ export class OperationEvents {
         request: fields.request, resourceBefore: fields.resourceBefore,
         resourceAfter: fields.resourceAfter, groupId: fields.groupId,
         groupKind: fields.groupKind, triggeredBy: fields.triggeredBy,
-        detail: fields.detail, at: fields.at,
+        detail: fields.detail, at,
       }), { service: 'rtdb' });
     } catch { /* telemetry is observational */ }
   }
@@ -117,6 +120,7 @@ export class OperationEvents {
     if (!this.sandbox) return;
     try {
       emitSandboxEvent(this.sandbox, makeSandboxCommitEvent({
+        at: getClock(this.sandbox).now(),
         service: 'rtdb', method, path: canonicalPath(path), auth,
         data: fields.data, priorState: fields.priorState, nextState: fields.nextState,
         groupId: fields.groupId, groupKind: fields.groupKind,
@@ -131,6 +135,9 @@ export class OperationEvents {
     auth: AuthState,
     fields: {
       event?: ChildListener['event'] | 'value';
+      /** The query the ref carried, for a listener attached to a query.
+       *  Diagnostic only: no verdict or delivery reads it. */
+      query?: unknown;
       result?: 'allow' | 'deny' | 'unsupported' | 'error';
       size?: number;
       sample?: unknown;
@@ -140,6 +147,7 @@ export class OperationEvents {
       detail?: Record<string, unknown>;
       reasons?: string[];
       rules?: SandboxOperationEvent['rules'];
+      owners?: ListenerOwner[];
     } = {},
   ): void {
     if (!this.sandbox) return;
@@ -149,11 +157,17 @@ export class OperationEvents {
         kindVal = fields.event;
       }
       emitSandboxEvent(this.sandbox, makeSandboxListenerEvent({
+        at: getClock(this.sandbox).now(),
         service: 'rtdb', phase, listenerId: listener.id,
-        target: { kind: kindVal, path: canonicalPath(listener.path) },
+        target: {
+          kind: kindVal,
+          path: canonicalPath(listener.path),
+          ...(fields.query === undefined ? {} : { query: fields.query }),
+        },
         auth, result: fields.result, size: fields.size, sample: fields.sample,
         reason: fields.reason, error: fields.error, triggeredBy: fields.triggeredBy,
         detail: fields.detail, reasons: fields.reasons, rules: fields.rules,
+        owners: fields.owners,
       }), { service: 'rtdb' });
     } catch { /* telemetry is observational */ }
   }

package/src/database/sandbox/persistence-state.ts

@@ -156,12 +156,12 @@ export class PersistenceState {
     const state: Record<string, JsonValue> = {
       '.pyricRtdbPersistence': 1,
       data: this.state.tree.snapshot(),
-      priorities: Object.fromEntries(this.state.priorities.entries()) as JsonValue,
+      priorities: Object.fromEntries(this.state.priorities.entries()),
     };
     if (hasActiveRules) {
-      state.rules = structuredClone(this.state.activeRules) as unknown as JsonValue;
+      state.rules = structuredClone(this.state.activeRules) as JsonValue;
     }
-    return state as unknown as JsonValue;
+    return state;
   }
 
   restore(root: JsonValue): void {
@@ -169,14 +169,7 @@ export class PersistenceState {
     const persisted = decode(root);
 
     let dataToRestore: JsonValue = {};
-    const isPersistedDataNull = persisted.data === null;
-    const isPersistedDataUndefined = persisted.data === undefined;
-    let hasPersistedData = false;
-    if (!isPersistedDataNull) {
-      if (!isPersistedDataUndefined) {
-        hasPersistedData = true;
-      }
-    }
+    const hasPersistedData = persisted.data !== null && persisted.data !== undefined;
     if (hasPersistedData) {
       dataToRestore = persisted.data;
     }

package/src/database/sandbox/priority-writes.ts

@@ -31,7 +31,7 @@ export class PriorityWrites {
   set(auth: AuthState, path: string, priority: Priority): void {
     validatePriority(priority);
     const current = this.state.tree.read(path);
-    const at = Date.now();
+    const at = this.state.clock.now();
     const evaluation = this.state.rules.evaluate('write', path === '/' ? '/' : path, {
       auth,
       mockData: this.state.tree.snapshot() as Record<string, unknown>,
@@ -39,7 +39,7 @@ export class PriorityWrites {
     });
     const priorPriority = this.state.priorities.get(path);
     const common = {
-      at, durationMs: Date.now() - at, request: { data: priority },
+      at, durationMs: this.state.clock.now() - at, request: { data: priority },
       resourceBefore: { data: current, exists: current !== null },
       resourceAfter: { data: current, exists: current !== null },
       detail: { priority, priorPriority },

package/src/database/sandbox/query.ts

@@ -46,47 +46,7 @@
  * enforcement is a deferred follow-up (would naturally hang off
  * `RulesEvaluator` not here).
  */
-import type { JsonValue } from './data-tree.js';
-
-/** Ordering selector. Stored as a discriminated union so the executor
- *  can switch on the kind without re-parsing. */
-export type OrderBy =
-  | { kind: 'child'; path: string }
-  | { kind: 'key' }
-  | { kind: 'priority' }
-  | { kind: 'value' };
-
-export type Priority = string | number | null;
-
-/** Cursor or filter bound. `startAt`/`endAt` are inclusive; the
- *  `*Exclusive` variants drop the boundary value. `equalTo` collapses
- *  start + end onto the same value (and is sugar for `startAt(v) +
- *  endAt(v)` per the SDK docs). */
-export type Bound =
-  | { kind: 'startAt'; value: JsonValue; key?: string }
-  | { kind: 'startAfter'; value: JsonValue; key?: string }
-  | { kind: 'endAt'; value: JsonValue; key?: string }
-  | { kind: 'endBefore'; value: JsonValue; key?: string }
-  | { kind: 'equalTo'; value: JsonValue; key?: string };
-
-/** Window-size constraint. Mutually exclusive with each other (prod
- *  rejects setting both — we don't reject here but the executor
- *  prioritises the last one set, matching `firebase/database`). */
-export type LimitKind = 'limitToFirst' | 'limitToLast';
-
-/**
- * A {@link Query} is a ref + a chain of constraints. The chain is
- * order-independent in terms of declared shape — the executor groups
- * constraints into {order, bounds, limit} during apply.
- */
-export interface QuerySpec {
-  /** Active ordering. `null` means Firebase's default priority index. */
-  orderBy: OrderBy | null;
-  /** Range/equality filters. Multiple bounds compose. */
-  bounds: Bound[];
-  /** Optional limit. Last-wins if set more than once. */
-  limit: { kind: LimitKind; n: number } | null;
-}
+import type { Bound, LimitKind, OrderBy, QuerySpec } from '../internal/query-projection.js';
 
 /** Empty spec — equivalent to "no constraints" (a plain ref query). */
 export function emptySpec(): QuerySpec {
@@ -166,230 +126,15 @@ export type Constraint =
   | { kind: 'bound'; bound: Bound }
   | { kind: 'limit'; limitKind: LimitKind; n: number };
 
-/**
- * Compare two `JsonValue`s under RTDB's documented type-order rules.
- * Locked by the upstream contract (Firebase docs: null < false < true
- * < number < string < object). The sandbox's ordering only needs to
- * match against same-type-or-null/undefined.
- *
- * Returns -1 / 0 / 1.
- */
-export function compareValues(a: JsonValue, b: JsonValue): number {
-  if (a === b) return 0;
-  // null sorts first.
-  if (a === null) return -1;
-  if (b === null) return 1;
-  const ta = typeofRank(a);
-  const tb = typeofRank(b);
-  if (ta !== tb) return ta - tb;
-  // Same type — value comparison.
-  if (typeof a === 'number' && typeof b === 'number') return a < b ? -1 : a > b ? 1 : 0;
-  if (typeof a === 'boolean' && typeof b === 'boolean') return a === b ? 0 : a ? 1 : -1;
-  if (typeof a === 'string' && typeof b === 'string') return a < b ? -1 : a > b ? 1 : 0;
-  // Objects/arrays are "greater" than primitives, but two object-valued
-  // children are ORDER-EQUAL under RTDB's model — the tie is broken by
-  // key, NOT by an invented JSON-string ordering (DB-B11; mirrors
-  // `ChildrenNode.ts:386-400` where ChildrenNodes compare equal). Return
-  // 0 so the caller's key tie-break takes over.
-  return 0;
-}
-
-function typeofRank(v: JsonValue): number {
-  // null = 0; boolean = 1; number = 2; string = 3; object/array = 4.
-  if (v === null) return 0;
-  if (typeof v === 'boolean') return 1;
-  if (typeof v === 'number') return 2;
-  if (typeof v === 'string') return 3;
-  return 4;
-}
-
-/** Used to test for integer-looking strings. Mirrors `INTEGER_REGEXP_`
- *  (`core/util/util.ts:496`). */
-const INTEGER_REGEXP = /^-?(0*)\d{1,10}$/;
-const INTEGER_32_MIN = -2147483648;
-const INTEGER_32_MAX = 2147483647;
-
-/** If the string is a 32-bit integer, return it; else `null`. Mirrors
- *  `tryParseInt` (`core/util/util.ts:511-520`). */
-function tryParseInt(str: string): number | null {
-  if (INTEGER_REGEXP.test(str)) {
-    const intVal = Number(str);
-    if (intVal >= INTEGER_32_MIN && intVal <= INTEGER_32_MAX) {
-      return intVal;
-    }
-  }
-  return null;
-}
-
-/**
- * Compare two Firebase key names under RTDB's `nameCompare` ordering:
- * integer-looking keys sort FIRST (numerically; ties broken by string
- * length so `"01"` follows `"1"`), then non-integer keys sort
- * lexicographically. Mirrors `nameCompare` (`core/util/util.ts:253-276`).
- *
- * This is RTDB's universal key order — it drives `orderByKey()`, the
- * tie-break for `orderByChild`/`orderByValue`, and the `key` argument of
- * `startAt(value, key)` / `endAt(value, key)` cursors. Plain
- * lexicographic compare (DB-B4) put `"10"` before `"2"`.
- */
-export function nameCompare(a: string, b: string): number {
-  if (a === b) return 0;
-  const aAsInt = tryParseInt(a);
-  const bAsInt = tryParseInt(b);
-  if (aAsInt !== null) {
-    if (bAsInt !== null) {
-      return aAsInt - bAsInt === 0 ? a.length - b.length : aAsInt - bAsInt;
-    }
-    // Integer keys sort before non-integer keys.
-    return -1;
-  } else if (bAsInt !== null) {
-    return 1;
-  }
-  return a < b ? -1 : 1;
-}
-
-/**
- * Extract the value the ordering uses to compare a child. For
- * `orderByKey()` it's the key string; for `orderByValue()` the child's
- * raw value; for `orderByChild(path)` the nested field at `path`
- * (which may itself be missing → `null`).
- */
-export function extractOrderValue(
-  spec: OrderBy | null,
-  key: string,
-  value: JsonValue,
-  priority: Priority = null,
-): JsonValue {
-  const o = spec ?? { kind: 'priority' as const };
-  switch (o.kind) {
-    case 'key':
-      return key;
-    case 'value':
-      return value;
-    case 'priority':
-      return priority;
-    case 'child': {
-      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        return null;
-      }
-      // Path may be a slash-separated dotted path (`'profile/name'`).
-      const segs = o.path.split('/').filter((s) => s.length > 0);
-      let cur: JsonValue = value;
-      for (const s of segs) {
-        if (cur === null || typeof cur !== 'object' || Array.isArray(cur)) return null;
-        cur = (cur as Record<string, JsonValue>)[s] ?? null;
-      }
-      return cur;
-    }
-  }
-}
-
-/** Result row — kept minimal so the snap-builder can render it cheaply. */
-export interface QueryRow {
-  key: string;
-  value: JsonValue;
-  priority: Priority;
-}
-
-/**
- * Run a {@link QuerySpec} against the data at a path. The caller passes
- * the raw value at the path (a `Record<string, JsonValue>` if it's a
- * collection, anything else → empty result).
- *
- * Returns an ordered, filtered, limited list of rows.
- */
-export function executeQuery(
-  pathData: JsonValue,
-  spec: QuerySpec,
-  priorityForKey: (key: string) => Priority = () => null,
-): QueryRow[] {
-  // Non-collection input → no rows. RTDB's `query()` on a primitive
-  // path returns an empty snapshot.
-  if (pathData === null || typeof pathData !== 'object' || Array.isArray(pathData)) {
-    return [];
-  }
-  const obj = pathData as Record<string, JsonValue>;
-  // Enumerate immediate children only — RTDB's query model is one-level.
-  let rows: QueryRow[] = Object.entries(obj).map(([key, value]) => ({
-    key,
-    value,
-    priority: priorityForKey(key),
-  }));
-
-  // ─── 1. Order ─────────────────────────────────────────────────────
-  const orderingByKey = spec.orderBy?.kind === 'key';
-  rows.sort((a, b) => {
-    if (orderingByKey) {
-      // `orderByKey` compares keys under RTDB's nameCompare directly
-      // (numeric-keys-first) — there's no separate tie-break.
-      return nameCompare(a.key, b.key);
-    }
-    const va = extractOrderValue(spec.orderBy, a.key, a.value, a.priority);
-    const vb = extractOrderValue(spec.orderBy, b.key, b.value, b.priority);
-    const cmp = compareValues(va, vb);
-    if (cmp !== 0) return cmp;
-    // Tie-break by key under nameCompare (RTDB's documented behavior —
-    // orderByChild / orderByValue ties break by key, numeric-first).
-    return nameCompare(a.key, b.key);
-  });
-
-  // ─── 2. Bounds ────────────────────────────────────────────────────
-  for (const b of spec.bounds) {
-    rows = rows.filter((row) => boundMatches(b, row, spec.orderBy));
-  }
-
-  // ─── 3. Limit ─────────────────────────────────────────────────────
-  if (spec.limit) {
-    const n = spec.limit.n;
-    if (spec.limit.kind === 'limitToFirst') {
-      rows = rows.slice(0, n);
-    } else {
-      rows = n >= rows.length ? rows : rows.slice(rows.length - n);
-    }
-  }
-
-  return rows;
-}
-
-/**
- * Does `row` pass the bound `b` under the active ordering?
- *
- * The bound's `value` is compared against the row's `extractOrderValue`.
- * The optional `key` arg (for `startAt(value, key)`) is a tie-breaker
- * for matching rows whose ordered-value equals `value` — the row passes
- * only if its key is also at-or-past the supplied key.
- */
-function boundMatches(b: Bound, row: QueryRow, orderBy: OrderBy | null): boolean {
-  const orderingByKey = orderBy?.kind === 'key';
-  // Under `orderByKey`, the bound's `value` IS the comparison key and is
-  // compared with nameCompare (numeric-first), NOT the value type-order.
-  // Under value/child ordering, compare the ordered value, then break
-  // ties on the key with nameCompare.
-  const cmp = orderingByKey
-    ? nameCompare(row.key, String(b.value))
-    : compareValues(extractOrderValue(orderBy, row.key, row.value, row.priority), b.value);
-  const keyCmp = (other: string): number => nameCompare(row.key, other);
-  switch (b.kind) {
-    case 'startAt':
-      if (cmp > 0) return true;
-      if (cmp < 0) return false;
-      // Equal: defer to optional key tie-breaker.
-      return b.key === undefined || keyCmp(b.key) >= 0;
-    case 'startAfter':
-      if (cmp > 0) return true;
-      if (cmp < 0) return false;
-      // Equal: row passes only if key strictly past the tie-breaker.
-      return b.key === undefined ? false : keyCmp(b.key) > 0;
-    case 'endAt':
-      if (cmp < 0) return true;
-      if (cmp > 0) return false;
-      return b.key === undefined || keyCmp(b.key) <= 0;
-    case 'endBefore':
-      if (cmp < 0) return true;
-      if (cmp > 0) return false;
-      return b.key === undefined ? false : keyCmp(b.key) < 0;
-    case 'equalTo':
-      if (cmp !== 0) return false;
-      return b.key === undefined || keyCmp(b.key) === 0;
-  }
-}
+export {
+  compareValues,
+  nameCompare,
+  extractOrderValue,
+  executeQuery,
+  type QueryRow,
+  type OrderBy,
+  type Priority,
+  type Bound,
+  type LimitKind,
+  type QuerySpec,
+} from '../internal/query-projection.js';

package/src/database/sandbox/rules-eval.ts

@@ -25,7 +25,79 @@ import {
   simulateRtdbRules,
   type CompiledRtdbRules,
 } from '../../rules/rtdb/compiled-rules.js';
+import type { SimulationInput } from '../../rules/rtdb/simulation/spec.js';
 import type { AuthState } from 'pyric/sandbox';
+import { SandboxClock } from 'pyric/sandbox';
+import type { QuerySpec } from './query.js';
+
+function toPrimitiveBoundValue(value: unknown): string | number | boolean | null {
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+  return null;
+}
+
+function resolveRequiredIndexKey(
+  orderBy: { kind: 'child'; path: string } | { kind: 'value' },
+): string {
+  if (orderBy.kind === 'value') {
+    return '.value';
+  }
+  return orderBy.path.split('/').filter(Boolean).join('/');
+}
+
+/**
+ * Convert a sandbox `QuerySpec` to the `SimulationInput['query']` shape
+ * consumed by the RTDB rules simulator.
+ */
+export function querySpecToSimulationQuery(spec: QuerySpec): SimulationInput['query'] {
+  const q: NonNullable<SimulationInput['query']> = {};
+  if (spec.orderBy?.kind === 'child') {
+    q.orderByChild = spec.orderBy.path;
+  } else if (spec.orderBy?.kind === 'key') {
+    q.orderByKey = true;
+  } else if (spec.orderBy?.kind === 'value') {
+    q.orderByValue = true;
+  }
+  for (const bound of spec.bounds) {
+    const val = toPrimitiveBoundValue(bound.value);
+    if (bound.kind === 'equalTo') {
+      q.equalTo = val;
+      q.startAt = val;
+      q.endAt = val;
+    } else if (bound.kind === 'startAt' || bound.kind === 'startAfter') {
+      q.startAt = val;
+    } else if (bound.kind === 'endAt' || bound.kind === 'endBefore') {
+      q.endAt = val;
+    }
+  }
+  if (spec.limit?.kind === 'limitToFirst') {
+    q.limitToFirst = spec.limit.n;
+  } else if (spec.limit?.kind === 'limitToLast') {
+    q.limitToLast = spec.limit.n;
+  }
+  return q;
+}
+
+function findMatchingNodesAtPath(root: CompiledRtdbRules, segments: string[]): CompiledRtdbRules[] {
+  let currentNodes: CompiledRtdbRules[] = [root];
+  for (const seg of segments) {
+    const nextNodes: CompiledRtdbRules[] = [];
+    for (const node of currentNodes) {
+      for (const child of node.children) {
+        const childSegs = child.path.split('/').filter(Boolean);
+        const lastSeg = childSegs[childSegs.length - 1];
+        if (!lastSeg) continue;
+        if (lastSeg === seg || lastSeg.startsWith('$')) {
+          nextNodes.push(child);
+        }
+      }
+    }
+    currentNodes = nextNodes;
+    if (currentNodes.length === 0) break;
+  }
+  return currentNodes;
+}
 
 /**
  * Plain-Error denial constructor. Matches the oracle observation: the
@@ -93,6 +165,11 @@ export interface EvalContext {
    * same update. Omit for single-path writes.
    */
   updates?: { path: string; value: unknown }[];
+  /** Optional query constraints for read rule evaluation. */
+  query?: SimulationInput['query'];
+  /** Optional query spec from sandbox query execution; automatically converts to `query` and validates `.indexOn`. */
+  querySpec?: QuerySpec;
+  indexMethod?: 'get' | 'listen';
 }
 
 export type RtdbDefaultPolicy = 'allow' | 'deny';
@@ -101,6 +178,15 @@ export class RulesEvaluator {
   private compiled: CompiledRtdbRules | null = null;
   private defaultPolicy: RtdbDefaultPolicy = 'deny';
 
+  /**
+   * @param clock The sandbox's clock, read for the rules engine's `now`. A
+   * standalone evaluator keeps its own wall clock.
+   */
+  constructor(
+    private readonly clock: SandboxClock = new SandboxClock(),
+    private readonly missingIndex?: (path: string, spec: QuerySpec, ctx: EvalContext) => void,
+  ) {}
+
   /** Set default access policy when no rules are loaded ('allow' or 'deny'). */
   setDefaultPolicy(policy: RtdbDefaultPolicy): void {
     this.defaultPolicy = policy;
@@ -121,6 +207,37 @@ export class RulesEvaluator {
     return this.compiled !== null;
   }
 
+  /**
+   * Enforce `.indexOn` rules for queries when security rules are active.
+   *
+   * Built-in orderings (`orderByKey`, `orderByPriority`, or default priority)
+   * and queries when no security rules are loaded (`this.compiled === null`)
+   * are exempt.
+   */
+  assertQueryIndex(path: string, spec: QuerySpec): void {
+    if (this.compiled === null) return;
+    if (spec.orderBy === null) return;
+    if (spec.orderBy.kind === 'key' || spec.orderBy.kind === 'priority') return;
+
+    const requiredIndex = resolveRequiredIndexKey(spec.orderBy);
+
+    const segments = path.split('/').filter(Boolean);
+    const normalizedPath = '/' + segments.join('/');
+
+    const matchingNodes = findMatchingNodesAtPath(this.compiled, segments);
+    const hasIndex = matchingNodes.some((node) =>
+      node.indexOn?.some(
+        (idx) => idx === requiredIndex || idx.split('/').filter(Boolean).join('/') === requiredIndex,
+      ),
+    );
+
+    if (!hasIndex) {
+      throw new Error(
+        `Index not defined, add ".indexOn": "${requiredIndex}", for path "${normalizedPath}", to the rules`,
+      );
+    }
+  }
+
   /**
    * Evaluate one op. Default-deny when no rules are loaded.
    *
@@ -182,16 +299,24 @@ export class RulesEvaluator {
         reasons: ['No RTDB rules loaded; default allow.'],
       };
     }
-    // The simulator's SimulationInputSchema requires `auth` to be
-    // either `null` or `{ uid: string, token: Record<string, unknown> }` —
-    // `token` is mandatory, not optional. `AuthState` from
-    // `pyric/sandbox` makes `token` optional. Normalise here so an
-    // auth identity without custom claims (`{ uid: 'alice' }`) still
-    // satisfies the schema and the rule sees `auth.token = {}`.
-    const normalisedAuth =
-      ctx.auth === null
-        ? null
-        : { uid: ctx.auth.uid, token: ctx.auth.token ?? {} };
+    // The simulator's SimulationInputSchema accepts `auth` as
+    // either `null` or `{ uid: string, tenant?: string, token?: Record<string, unknown> }`.
+    // Preserve tenant and optional token from AuthState so tenant claim
+    // normalization and custom claims reach the simulator.
+    let normalisedAuth: SimulationInput['auth'] = null;
+    if (ctx.auth !== null) {
+      normalisedAuth = {
+        uid: ctx.auth.uid,
+        token: ctx.auth.token ?? {},
+      };
+      if (ctx.auth.tenant !== undefined) {
+        normalisedAuth.tenant = ctx.auth.tenant;
+      }
+    }
+    let simulatedQuery = ctx.query;
+    if (simulatedQuery === undefined && ctx.querySpec !== undefined) {
+      simulatedQuery = querySpecToSimulationQuery(ctx.querySpec);
+    }
     const result = simulateRtdbRules(this.compiled, {
       operation,
       path: path === '/' ? '/' : path,
@@ -199,6 +324,8 @@ export class RulesEvaluator {
       mockData: ctx.mockData,
       newData: ctx.newData,
       updates: ctx.updates,
+      query: simulatedQuery,
+      now: this.clock.now(),
     });
     if (!result.success) {
       if (result.error.code === 'NO_MATCHING_RULE') {
@@ -228,6 +355,13 @@ export class RulesEvaluator {
         pathVariableBindings: result.data.pathVariableBindings,
       };
     }
+    if (result.data.allowed && isReadOperation && ctx.querySpec) {
+      try { this.assertQueryIndex(path, ctx.querySpec); }
+      catch (error) {
+        try { this.missingIndex?.(path, ctx.querySpec, ctx); } catch { /* diagnostics do not change the SDK failure */ }
+        throw error;
+      }
+    }
     return {
       check: result.data.allowed ? 'allow' : 'deny',
       reasons: [