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

package/src/firestore/sandbox/query-execution.ts

@@ -1,3 +1,6 @@
+import type { QueryWhereFilterOp } from './query-operators.js';
+import { activityValue } from './activity-query-value.js';
+import { isPlainObject } from './value-resolver.js';
 import { topK } from './topk.js';
 import { firestoreValuesEqual } from './value-equality.js';
 import { compareValues, typeOrderRank } from './query-value-order.js';
@@ -7,10 +10,7 @@ import type { QueryConstraints, QueryWhereConstraint } from './list-query-proof.
 import type { FirestoreSimError } from './errors.js';
 
 export type QueryDocumentData = Record<string, unknown>;
-export type QueryWhereFilterOp =
-  | '<' | '<=' | '==' | '!=' | '>=' | '>'
-  | 'in' | 'not-in'
-  | 'array-contains' | 'array-contains-any';
+export type { QueryWhereFilterOp } from './query-operators.js';
 export type QueryOrderDirection = 'asc' | 'desc';
 export type QueryFilter =
   | { readonly kind: 'where'; readonly field: string; readonly op: QueryWhereFilterOp; readonly value: unknown }
@@ -138,12 +138,15 @@ export function queryConstraintsForProof(execution: QueryExecutionSpec): QueryCo
       const value = filter.value;
       if (
         value === null || typeof value === 'string' ||
-        typeof value === 'number' || typeof value === 'boolean'
+        typeof value === 'number' || typeof value === 'boolean' ||
+        (filter.op === 'in' && Array.isArray(value) && value.length > 0 && value.length <= 30 && value.every(item =>
+          item === null || typeof item === 'string' || typeof item === 'boolean' ||
+          (typeof item === 'number' && Number.isFinite(item))))
       ) {
         where.push(Object.freeze({
           field: filter.field,
           op: filter.op,
-          value,
+          value: Array.isArray(value) ? Object.freeze([...value]) : value,
         }));
       }
       return;
@@ -160,6 +163,19 @@ export function queryConstraintsForProof(execution: QueryExecutionSpec): QueryCo
   });
 }
 
+/** Describe every filter without traversing user-owned operands during diagnostics. */
+export function queryExecutionDiagnostic(execution: QueryExecutionSpec): unknown {
+  const filter = (entry: QueryFilter): unknown => entry.kind === 'where'
+    ? { kind: entry.kind, field: entry.field, op: entry.op, value: activityValue(entry.value) }
+    : { kind: entry.kind, filters: entry.filters.map(filter) };
+  return {
+    filters: execution.filters.map(filter), orders: execution.orders,
+    limitCount: execution.limitCount, limitFromEnd: execution.limitFromEnd,
+    ...(execution.start ? { start: { ...execution.start, values: execution.start.values.map(activityValue) } } : {}),
+    ...(execution.end ? { end: { ...execution.end, values: execution.end.values.map(activityValue) } } : {}),
+  };
+}
+
 export function gatherQueryRows(state: DocStore, scope: QueryScope): QueryRow[] {
   if (scope.kind === 'collection') {
     return state.scan(scope.path, { directOnly: true });
@@ -180,6 +196,16 @@ export function gatherQueryRows(state: DocStore, scope: QueryScope): QueryRow[]
 
 const KEY_FIELD = '__name__';
 
+/** String query field paths address nested maps, never literal dotted keys or prototypes. */
+function dataFieldValue(data: QueryDocumentData, path: string): unknown {
+  let value: unknown = data;
+  for (const segment of path.split('.')) {
+    if (!isPlainObject(value) || !Object.hasOwn(value, segment)) return undefined;
+    value = value[segment];
+  }
+  return value;
+}
+
 /** Operators that make a `where` clause an inequality filter — these imply
  *  an orderBy on the filtered field (mirrors `getInequalityFilterFields`). */
 const INEQUALITY_OPS: ReadonlySet<QueryWhereFilterOp> = new Set<QueryWhereFilterOp>([
@@ -190,7 +216,7 @@ const INEQUALITY_OPS: ReadonlySet<QueryWhereFilterOp> = new Set<QueryWhereFilter
  *  reference-like keyed on the document path so `compareValues` orders it
  *  via its reference branch; all other fields read from the doc data. */
 function orderValue(row: { path: string; data: QueryDocumentData }, field: string): unknown {
-  return field === KEY_FIELD ? { path: row.path } : row.data[field];
+  return field === KEY_FIELD ? { path: row.path } : dataFieldValue(row.data, field);
 }
 
 /** The set of fields a filter constrains with an inequality operator —
@@ -204,11 +230,6 @@ function inequalityFields(filter: QueryFilter): string[] {
   return filter.filters.flatMap(inequalityFields);
 }
 
-/** True when a filter (possibly composite) carries any inequality op. */
-function hasInequality(filter: QueryFilter): boolean {
-  return inequalityFields(filter).length > 0;
-}
-
 // ─────────────────────────────────────────────────────────────────────────
 // Range comparators (FS-B3) — canonical, type-order-aware.
 //
@@ -297,7 +318,7 @@ function filterFieldValue(row: QueryRow, field: string): unknown {
     const parts = row.path.split('/');
     return parts[parts.length - 1] ?? row.path;
   }
-  return row.data[field];
+  return dataFieldValue(row.data, field);
 }
 
 /**
@@ -393,7 +414,7 @@ function applyCursors(
 // key order never excludes a doc.
 function orderPresent(docs: QueryRow[], orders: QueryOrderClause[]): QueryRow[] {
   return docs.filter((d) =>
-    orders.every((o) => o.field === KEY_FIELD || d.data[o.field] !== undefined),
+    orders.every((o) => o.field === KEY_FIELD || dataFieldValue(d.data, o.field) !== undefined),
   );
 }
 
@@ -445,30 +466,26 @@ export function executeQuery(
 ): QueryRow[] {
   let filtered = applyQueryFilters(rows, [...spec.filters]);
   const normalized = normalizedQueryOrders(spec);
-  const needsOrder =
-    spec.orders.length > 0 ||
-    spec.start !== undefined ||
-    spec.end !== undefined ||
-    spec.filters.some(hasInequality);
-
-  if (
-    needsOrder &&
-    spec.limitCount !== undefined &&
+  const limitCount = spec.limitCount;
+  const canUseTopK =
+    limitCount !== undefined &&
     !spec.limitFromEnd &&
     spec.start === undefined &&
-    spec.end === undefined
-  ) {
+    spec.end === undefined;
+  if (canUseTopK) {
     return topK(
       orderPresent(filtered, normalized),
-      spec.limitCount,
+      limitCount,
       orderComparator(normalized),
     );
   }
-  if (needsOrder) filtered = applyOrder(filtered, normalized);
+  filtered = applyOrder(filtered, normalized);
 
-  if (spec.start || spec.end) {
+  const hasCursors = Boolean(spec.start || spec.end);
+  if (hasCursors) {
     for (const cursor of [spec.start, spec.end]) {
-      if (cursor && !cursor.fromSnapshot && cursor.values.length > spec.orders.length) {
+      const hasTooManyCursorValues = Boolean(cursor && !cursor.fromSnapshot && cursor.values.length > spec.orders.length);
+      if (hasTooManyCursorValues) {
         throw new FirestoreCompatError({
           code: 'invalid-argument',
           message:
@@ -481,17 +498,22 @@ export function executeQuery(
     filtered = applyCursors(filtered, normalized, spec.start, spec.end);
   }
 
-  if (spec.limitCount !== undefined) {
-    if (spec.limitFromEnd) {
-      if (spec.orders.length === 0) {
+  const finalLimit = spec.limitCount;
+  const hasLimit = finalLimit !== undefined;
+  if (hasLimit) {
+    const usesTailLimit = spec.limitFromEnd;
+    if (usesTailLimit) {
+      const hasNoExplicitOrder = spec.orders.length === 0;
+      if (hasNoExplicitOrder) {
         throw new FirestoreCompatError({
           code: 'unimplemented',
           message: 'limitToLast() queries require at least one orderBy clause.',
         });
       }
-      filtered = filtered.slice(-spec.limitCount);
+      const hasZeroLimit = finalLimit === 0;
+      filtered = hasZeroLimit ? [] : filtered.slice(-finalLimit);
     } else {
-      filtered = filtered.slice(0, spec.limitCount);
+      filtered = filtered.slice(0, finalLimit);
     }
   }
   return filtered;

package/src/firestore/sandbox/query-operand-equality.ts

@@ -8,6 +8,7 @@ import { firestoreValuesEqual } from './value-equality.js';
 import { FirestoreCompatError } from './firestore-compat-error.js';
 import { activityValue } from './activity-query-value.js';
 import { registerActivityValue } from './activity-value-registry.js';
+import { Timestamp } from '../timestamp.js';
 
 export type CapturedQueryOperand = {
   readonly kind: 'canonical';
@@ -20,6 +21,23 @@ interface CanonicalQueryValue {
   execution: unknown;
 }
 
+interface TimestampIdentity {
+  type: 'timestamp';
+  seconds: number;
+  nanoseconds: number;
+}
+
+function isTimestampIdentity(value: unknown): value is TimestampIdentity {
+  const isRecord = value !== null && typeof value === 'object';
+  if (isRecord) {
+    const hasTimestampMarker = 'type' in value && value.type === 'timestamp';
+    const hasSeconds = 'seconds' in value && typeof value.seconds === 'number';
+    const hasNanoseconds = 'nanoseconds' in value && typeof value.nanoseconds === 'number';
+    return hasTimestampMarker && hasSeconds && hasNanoseconds;
+  }
+  return false;
+}
+
 function invalidOperand(message: string): FirestoreCompatError {
   return new FirestoreCompatError({ code: 'invalid-argument', message });
 }
@@ -31,30 +49,50 @@ function canonicalize(
   allowNestedArrays = false,
   parentIsArray = false,
 ): CanonicalQueryValue {
-  if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+  const isSimpleScalar = value === null || typeof value === 'string' || typeof value === 'boolean';
+  if (isSimpleScalar) {
     return { comparison: value, execution: value };
   }
-  if (typeof value === 'number') return { comparison: value, execution: value };
-  if (typeof value === 'undefined' || typeof value === 'bigint'
-    || typeof value === 'function' || typeof value === 'symbol') {
+  const isNumber = typeof value === 'number';
+  if (isNumber) return { comparison: value, execution: value };
+  const isUnsupportedPrimitive = typeof value === 'undefined' || typeof value === 'bigint'
+    || typeof value === 'function' || typeof value === 'symbol';
+  if (isUnsupportedPrimitive) {
     throw invalidOperand(`Unsupported Firestore query value: ${typeof value}.`);
   }
-  if (typeof value !== 'object') throw invalidOperand('Unsupported Firestore query value.');
+  const isNotObject = typeof value !== 'object';
+  if (isNotObject) throw invalidOperand('Unsupported Firestore query value.');
 
   const registered = registeredQueryValue(value);
-  if (registered !== undefined) {
+  const isRegisteredValue = registered !== undefined;
+  if (isRegisteredValue) {
     const registeredOwner = registeredQueryValueOwner(value);
-    if (registeredOwner !== undefined && owner !== undefined && registeredOwner !== owner) {
+    const hasForeignOwner = registeredOwner !== undefined && owner !== undefined && registeredOwner !== owner;
+    if (hasForeignOwner) {
       throw invalidOperand('Document reference belongs to a different Firestore database.');
     }
+    const isTimestamp = isTimestampIdentity(registered);
+    if (isTimestamp) {
+      const nanoseconds = Math.floor(registered.nanoseconds / 1_000) * 1_000;
+      const timestamp = new Timestamp(registered.seconds, nanoseconds);
+      return {
+        comparison: {
+          type: 'registered-firestore-value',
+          value: Object.freeze({ type: 'timestamp', seconds: timestamp.seconds, nanoseconds }),
+        },
+        execution: timestamp,
+      };
+    }
     return {
       comparison: { type: 'registered-firestore-value', value: registered },
       execution: registeredQueryExecutionValue(value),
     };
   }
-  if (value instanceof Date) {
+  const isDate = value instanceof Date;
+  if (isDate) {
     const millis = value.getTime();
-    if (!Number.isFinite(millis)) throw invalidOperand('Invalid Date query value.');
+    const isInvalidDate = !Number.isFinite(millis);
+    if (isInvalidDate) throw invalidOperand('Invalid Date query value.');
     const seconds = Math.floor(millis / 1_000);
     const timestamp = Object.freeze({
       seconds,
@@ -74,24 +112,29 @@ function canonicalize(
       execution: timestamp,
     };
   }
-  if (value instanceof Uint8Array) {
+  const isByteArray = value instanceof Uint8Array;
+  if (isByteArray) {
     const copy = value.slice();
     return {
       comparison: { type: 'bytes', values: Array.from(copy) },
       execution: copy,
     };
   }
-  if (ancestors.has(value)) throw invalidOperand('Cyclic query operands are not Firestore values.');
+  const isCyclicValue = ancestors.has(value);
+  if (isCyclicValue) throw invalidOperand('Cyclic query operands are not Firestore values.');
 
   const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null && !Array.isArray(value)) {
+  const hasUnsupportedPrototype = prototype !== Object.prototype && prototype !== null && !Array.isArray(value);
+  if (hasUnsupportedPrototype) {
     throw invalidOperand('Firestore query maps must be plain objects.');
   }
 
   ancestors.add(value);
   try {
-    if (Array.isArray(value)) {
-      if (parentIsArray && !allowNestedArrays) {
+    const isArray = Array.isArray(value);
+    if (isArray) {
+      const isDisallowedNestedArray = parentIsArray && !allowNestedArrays;
+      if (isDisallowedNestedArray) {
         throw invalidOperand('Nested arrays are not supported.');
       }
       const entries = value.map((entry) => canonicalize(

package/src/firestore/sandbox/query-operators.ts

@@ -0,0 +1,20 @@
+import { FirestoreCompatError } from './firestore-compat-error.js';
+
+export const QUERY_WHERE_OPERATORS = [
+  '<', '<=', '==', '!=', '>=', '>', 'in', 'not-in', 'array-contains', 'array-contains-any',
+] as const;
+export type QueryWhereFilterOp = typeof QUERY_WHERE_OPERATORS[number];
+
+const whereOperators = new Set<unknown>(QUERY_WHERE_OPERATORS);
+
+export function assertQueryWhereFilter(operator: unknown, value: unknown): void {
+  const hasUnsupportedOperator = !whereOperators.has(operator);
+  if (hasUnsupportedOperator) {
+    throw new FirestoreCompatError({ code: 'invalid-argument', message: 'Unsupported Firestore filter operator.' });
+  }
+  const requiresArrayOperand = operator === 'in' || operator === 'not-in' || operator === 'array-contains-any';
+  const hasInvalidOperand = requiresArrayOperand && !Array.isArray(value);
+  if (hasInvalidOperand) {
+    throw new FirestoreCompatError({ code: 'invalid-argument', message: `Firestore ${operator} filter requires an array operand.` });
+  }
+}

package/src/firestore/sandbox/query-value-registry.ts

@@ -79,9 +79,10 @@ export function registeredReferenceQueryValuePath(value: object): string | undef
 export function registerReferenceQueryValue(
   value: object,
   path: string,
-  owner: object,
+  owner?: object,
   executionValue: object = value,
 ): void {
   registerQueryValue(value, new ReferenceQueryValue(path), () => executionValue);
-  owners.set(value, owner);
+  const hasOwner = owner !== undefined;
+  if (hasOwner) owners.set(value, owner);
 }

package/src/firestore/sandbox/request-events.ts

@@ -3,6 +3,7 @@
  * engine's traffic log (ADR-0007 mechanical extraction from
  * `local-environment.ts`).
  */
+import type { QueryProofDiagnostic } from '../../sandbox/types/query-proof.js';
 import type { EvaluatedRuleInfo } from 'pyric/rules/internal';
 import type { DocumentData } from './local-state.js';
 import type { EventProvenance } from '../../sandbox/types/events.js';
@@ -16,6 +17,8 @@ import type { Operation } from './writes.js';
  * `RequestEvent` shape consumers see.
  */
 export interface EmitRequestInput {
+  rulesEvidence?: import('../../sandbox/types/rules-evidence.js').RulesEvidence;
+  queryProof?: QueryProofDiagnostic;
   at: number;
   evalMs: number;
   method: Operation['method'];
@@ -96,6 +99,8 @@ export function buildRequestEvent(input: EmitRequestInput): import('../../sandbo
   if (input.resourceAfter !== undefined) {
     out.resourceAfter = input.resourceAfter;
   }
+  if (input.rulesEvidence !== undefined) out.rulesEvidence = input.rulesEvidence;
+  if (input.queryProof !== undefined) out.queryProof = input.queryProof;
   const matched = parseMatchedRule(input.debugMessages, input.result);
   if (matched) out.matchedRule = matched;
   // The structured deciding-rule projection (verdict + line + expression

package/src/firestore/sandbox/rules-evidence.ts

@@ -0,0 +1,94 @@
+import type { TestResult } from 'pyric/rules/internal';
+import type { RuleCheck, RulesEvidence } from '../../sandbox/types/rules-evidence.js';
+import type { QueryProofDiagnostic } from '../../sandbox/types/query-proof.js';
+
+type Evaluation = TestResult['trace'][number];
+type ExpressionEntry = NonNullable<Evaluation['expressionTrace']>[number];
+
+/** One budget per snapshot, shared across all rule and helper expressions. */
+class EvidenceBudget {
+  truncated = false;
+  remainingChecks = 128;
+
+  text(value: string): string {
+    if (value.length <= 256) return value;
+    this.truncated = true;
+    return `${value.slice(0, 256)}…`;
+  }
+
+  take<T>(values: readonly T[], limit: number): T[] {
+    if (values.length > limit) this.truncated = true;
+    return values.slice(0, limit);
+  }
+}
+
+function captureCheck(entry: ExpressionEntry, budget: EvidenceBudget): RuleCheck {
+  const location = {
+    expression: budget.text(entry.source), parent: entry.parent,
+    operator: entry.operator, kind: entry.kind,
+    helper: entry.inlinedFrom?.name,
+    binding: entry.letBinding?.name,
+  };
+  if (location.helper !== undefined) location.helper = budget.text(location.helper);
+  if (location.binding !== undefined) location.binding = budget.text(location.binding);
+  if (entry.skipped) return { ...location, state: 'skipped' };
+  if (entry.error !== undefined) return { ...location, state: 'error', error: budget.text(entry.error) };
+  const value = entry.value;
+  if (value === null || typeof value === 'boolean' || typeof value === 'number') {
+    return { ...location, state: 'value', value };
+  }
+  if (typeof value === 'string') return { ...location, state: 'value', value: budget.text(value) };
+  // Never retain document objects, token maps, or arbitrary runtime handles.
+  return { ...location, state: 'unavailable' };
+}
+
+function captureRule(rule: Evaluation, budget: EvidenceBudget): RulesEvidence['rules'][number] {
+  const entries = rule.expressionTrace ?? [];
+  const retained = budget.take(entries, budget.remainingChecks);
+  budget.remainingChecks -= retained.length;
+  const expression = rule.conditionText ?? '';
+  const captured: RulesEvidence['rules'][number] = {
+    expression: budget.text(expression), verdict: rule.verdict,
+    checks: retained.map(entry => captureCheck(entry, budget)),
+  };
+  if (rule.line !== undefined) captured.line = rule.line;
+  if (rule.matchPath !== undefined) captured.path = budget.text(rule.matchPath);
+  if (rule.message !== undefined) captured.error = budget.text(rule.message);
+  return captured;
+}
+
+export function captureRulesEvidence(
+  result: TestResult,
+  version: string,
+  scope: RulesEvidence['scope'] = 'request',
+): RulesEvidence {
+  const budget = new EvidenceBudget();
+  const rules = budget.take(result.trace, 32).map(rule => captureRule(rule, budget));
+  const attempts = result.pathResolution?.attempts ?? [];
+  const paths = budget.take(attempts, 32).map(entry => ({
+    path: budget.text(entry.blockPath), matched: entry.matched, line: entry.line,
+  }));
+  return { version, scope, decision: result.decision, rules, paths, truncated: budget.truncated };
+}
+
+/** Query proof may reject a request before any residual simulation occurs. */
+export function captureQueryEvidence(
+  proof: QueryProofDiagnostic,
+  version: string,
+  residual?: RulesEvidence,
+): RulesEvidence {
+  const budget = new EvidenceBudget();
+  const failures = budget.take(proof.failures, 32).map(failure => {
+    const captured: NonNullable<RulesEvidence['queryProof']>['failures'][number] = {
+      reason: budget.text(failure.reason),
+    };
+    if (failure.rule?.expression !== undefined) captured.expression = budget.text(failure.rule.expression);
+    if (failure.rule?.line !== undefined) captured.line = failure.rule.line;
+    return captured;
+  });
+  let decision: RulesEvidence['decision'] = 'DENY';
+  if (proof.kind === 'unsupported-path' || proof.kind === 'unsupported-predicate') decision = 'UNSUPPORTED';
+  const initial: RulesEvidence = { version, scope: 'query-residual', decision, truncated: false, rules: [], paths: [] };
+  const evidence = residual ?? initial;
+  return { ...evidence, queryProof: { kind: proof.kind, failures }, truncated: evidence.truncated || budget.truncated };
+}