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

package/src/firestore/sandbox/write-runtime.ts

@@ -1,5 +1,5 @@
-import type { DocStore, DocumentData } from './local-state.js';
-import { applyMerge } from './field-merge.js';
+import type { BatchOperation, DocStore, DocumentData } from './local-state.js';
+import { applyMerge, applyUpdate } from './field-merge.js';
 import type {
   SimulateFirestoreRulesHandler,
   TestCase,
@@ -12,12 +12,13 @@ import type { FirestoreEventBus } from './event-bus.js';
 import type { TriggerScope } from './trigger-scope.js';
 import type { FirestoreSimError } from './errors.js';
 import type { Operation } from './writes.js';
-import type { EventProvenance } from '../../sandbox/types/events.js';
+import type { EventProvenance, WriteSandboxEvent } from '../../sandbox/types/events.js';
 import { buildRequestEvent, nextRequestEventId, type EmitRequestInput } from './request-events.js';
 import type { SentinelHit } from './sentinel-capture.js';
 import { buildRulesTestCase } from './rules-test-case.js';
 import { simulateRules } from './rules-simulator.js';
-import { registerDefaultConverters } from './value-resolver.js';
+import { partitionDeletes, registerDefaultConverters } from './value-resolver.js';
+import { SandboxClock } from '../../sandbox/clock.js';
 
 registerDefaultConverters();
 
@@ -35,6 +36,9 @@ export class WriteRuntime {
     readonly eventLog: EventLog,
     private readonly events: FirestoreEventBus,
     private readonly triggerScope: TriggerScope,
+    /** The sandbox's clock, read for every server-set time this produces.
+     *  Defaults to a private wall clock for a standalone construction. */
+    readonly clock: SandboxClock = new SandboxClock(),
   ) {}
 
   get state(): DocStore {
@@ -46,7 +50,8 @@ export class WriteRuntime {
   }
 
   emitRequest(input: EmitRequestInput): void {
-    if (!this.events.request.hasSubscribers) return;
+    const hasNoSubscribers = !this.events.request.hasSubscribers;
+    if (hasNoSubscribers) return;
     this.events.request.emit(buildRequestEvent(input));
   }
 
@@ -65,38 +70,55 @@ export class WriteRuntime {
     detail?: { admin?: boolean } & Record<string, unknown>;
     provenance?: EventProvenance;
   }): void {
-    if (!this.events.write.hasSubscribers) return;
-    this.events.write.emit({
+    const hasNoSubscribers = !this.events.write.hasSubscribers;
+    if (hasNoSubscribers) return;
+    const event: WriteSandboxEvent = {
       kind: 'write',
       id: nextRequestEventId().replace(/^req-/, 'wr-'),
-      at: Date.now(),
+      at: this.clock.now(),
       method: input.method,
       path: input.path,
-      auth: input.auth
-        ? { uid: input.auth.uid, ...(input.auth.token ? { token: input.auth.token } : {}) }
-        : null,
-      ...(input.data !== undefined ? { data: input.data } : {}),
+      auth: null,
       priorState: input.priorState,
       nextState: input.nextState,
-      ...(input.groupId !== undefined ? { groupId: input.groupId } : {}),
-      ...(input.groupKind !== undefined ? { groupKind: input.groupKind } : {}),
-      ...(input.sentinels && input.sentinels.length > 0 ? { sentinels: input.sentinels } : {}),
-      ...(input.autoId !== undefined ? { autoId: input.autoId } : {}),
       requestTime: { seconds: input.requestTime.seconds, nanoseconds: input.requestTime.nanos },
-      ...(input.detail !== undefined ? { detail: input.detail } : {}),
-      ...(input.provenance ?? {}),
-    });
+    };
+    const { auth } = input;
+    const hasAuth = auth !== null;
+    if (hasAuth) {
+      event.auth = { uid: auth.uid };
+      const hasToken = Boolean(auth.token);
+      if (hasToken) event.auth.token = auth.token;
+    }
+    const hasData = input.data !== undefined;
+    if (hasData) event.data = input.data;
+    const hasGroupId = input.groupId !== undefined;
+    if (hasGroupId) event.groupId = input.groupId;
+    const hasGroupKind = input.groupKind !== undefined;
+    if (hasGroupKind) event.groupKind = input.groupKind;
+    const hasSentinels = input.sentinels !== undefined && input.sentinels.length > 0;
+    if (hasSentinels) event.sentinels = input.sentinels;
+    const hasAutoId = input.autoId !== undefined;
+    if (hasAutoId) event.autoId = input.autoId;
+    const hasDetail = input.detail !== undefined;
+    if (hasDetail) event.detail = input.detail;
+    this.events.write.emit({ ...event, ...input.provenance });
   }
 
   capturePriors(paths: readonly string[]): Record<string, DocumentData | null> {
     const priors: Record<string, DocumentData | null> = {};
     for (const path of paths) {
       const prior = this.state.get(path);
-      priors[path] = prior ? { ...prior } : null;
+      const documentExists = prior !== null;
+      priors[path] = documentExists ? { ...prior } : null;
     }
     return priors;
   }
 
+  captureEvidence(result: import('pyric/rules/internal').TestResult) {
+    return this.rules.captureEvidence(result);
+  }
+
   runSimulate(
     testCases: TestCase[],
     bypassRules: boolean | undefined,
@@ -112,20 +134,18 @@ export class WriteRuntime {
     );
   }
 
-  private isReadOnlyMethod(method: string): boolean {
-    return method === 'get' || method === 'list';
-  }
-
   private resolvePriorDocumentState(
     path: string,
     projection: Map<string, DocumentData | null>,
     databaseState: DocStore,
   ): DocumentData | null {
-    if (projection.has(path)) {
+    const hasProjection = projection.has(path);
+    if (hasProjection) {
       const projectedState = projection.get(path);
       return projectedState ?? null;
     }
-    if (databaseState.exists(path)) {
+    const documentExists = databaseState.exists(path);
+    if (documentExists) {
       const existingDatabaseState = databaseState.get(path);
       return existingDatabaseState ?? null;
     }
@@ -136,11 +156,12 @@ export class WriteRuntime {
     priorState: DocumentData | null,
     incomingData: DocumentData | undefined,
   ): DocumentData | null {
-    if (priorState === null) {
+    const documentMissing = priorState === null;
+    if (documentMissing) {
       return null;
     }
     const effectiveIncomingData = incomingData ?? {};
-    return applyMerge(priorState, effectiveIncomingData);
+    return applyUpdate(priorState, effectiveIncomingData);
   }
 
   private computeProjectedOverwrite(
@@ -152,23 +173,30 @@ export class WriteRuntime {
     return applyMerge(baseState, effectiveIncomingData);
   }
 
-  buildBatchProjection(testCases: TestCase[]): Map<string, DocumentData | null> {
-    const projection = new Map<string, DocumentData | null>();
-    for (const testCase of testCases) {
-      if (this.isReadOnlyMethod(testCase.method)) {
+  /** Project write intent before the rules vocabulary reduces set to create/update. */
+  buildBatchProjection(
+    operations: BatchOperation[],
+    projection = new Map<string, DocumentData | null>(),
+  ): Map<string, DocumentData | null> {
+    for (const operation of operations) {
+      const isReplacement = operation.method === 'set';
+      if (isReplacement) {
+        projection.set(operation.path, partitionDeletes(operation.data ?? {}).writes);
         continue;
       }
-      if (testCase.method === 'delete') {
-        projection.set(testCase.path, null);
+      const isDelete = operation.method === 'delete';
+      if (isDelete) {
+        projection.set(operation.path, null);
         continue;
       }
-      const priorState = this.resolvePriorDocumentState(testCase.path, projection, this.state);
-      if (testCase.method === 'update') {
-        const updatedDocument = this.computeProjectedUpdate(priorState, testCase.data);
-        projection.set(testCase.path, updatedDocument);
+      const priorState = this.resolvePriorDocumentState(operation.path, projection, this.state);
+      const isUpdate = operation.method === 'update';
+      if (isUpdate) {
+        const updatedDocument = this.computeProjectedUpdate(priorState, operation.data);
+        projection.set(operation.path, updatedDocument);
       } else {
-        const overwrittenDocument = this.computeProjectedOverwrite(priorState, testCase.data);
-        projection.set(testCase.path, overwrittenDocument);
+        const overwrittenDocument = this.computeProjectedOverwrite(priorState, operation.data);
+        projection.set(operation.path, overwrittenDocument);
       }
     }
     return projection;

package/src/firestore/sandbox/writes.ts

@@ -72,9 +72,11 @@ export interface OperationResult {
 }
 
 export interface BatchOperationInput {
-  method: 'create' | 'update' | 'delete';
+  /** `set` replaces data; its create/update rule is selected at commit. */
+  method: 'create' | 'update' | 'set' | 'delete';
   path: string;
   data?: DocumentData;
+  merge?: Operation['merge'];
 }
 
 export interface BatchResult {

package/src/firestore/sdk-activity.ts

@@ -0,0 +1,31 @@
+import { sdkActivity, type SdkActivityRecord, type SdkActivityHandle } from '../sandbox/internal/sdk-activity.js';
+import { listenerAttachOwners, type ListenerAttribution } from '../sandbox/attribution/listener-owners.js';
+import { underlyingOf, type Target } from './state.js';
+import type { QueryImpl } from './sandbox/admin-compat/query.js';
+
+/** One public invocation, independent of backend reads and listener reauthorization. */
+export function beginFirestoreActivity(
+  target: Target,
+  ref: object,
+  method: string,
+  kind: SdkActivityRecord['kind'],
+  attribution?: ListenerAttribution,
+): SdkActivityHandle {
+  const raw = underlyingOf(ref) as QueryImpl & { path?: string };
+  const source = typeof raw.sdkActivitySource === 'function'
+    ? raw.sdkActivitySource()
+    : { service: 'firestore' as const, target: raw.path!, key: `doc:${raw.path}` };
+  return sdkActivity.begin({
+    app: target.activityApp ?? target,
+    source,
+    method,
+    kind,
+    owners: listenerAttachOwners(attribution?.owner, attribution?.owners),
+  });
+}
+
+/** Batch/transaction identity is the app database, not an arbitrary first document. */
+export function beginFirestoreGroupActivity(target: Target, method: string): SdkActivityHandle {
+  return sdkActivity.begin({ app: target.activityApp ?? target, method, kind: 'operation',
+    source: { service: 'firestore', target: '/', key: 'database' } });
+}

package/src/firestore/snapshots.ts

@@ -14,6 +14,7 @@ import type { AdminDocumentSnapshot as ChainDocSnap, DocumentData } from 'pyric/
 
 import {
   tag,
+  TARGET_SYMBOL,
   sandboxDb,
   sandboxLiveRebuild,
   refToUnderlying,
@@ -22,6 +23,8 @@ import {
   underlyingOf,
   type Target,
 } from './state.js';
+import { doc } from './refs.js';
+import type { ReferenceDecoder } from './internal/value-codec.js';
 import { firestoreValuesEqual } from './sandbox/value-equality.js';
 import { registerReferenceQueryValue } from './sandbox/query-value-registry.js';
 import { clientStateFor } from './client-state.js';
@@ -238,24 +241,35 @@ export function recordQuerySnapshot(
  * Other surface (id / ref / exists) passes through unchanged so
  * `tagSnapshotRefs` still operates on the original snap object.
  */
-export function wrapSandboxDocSnap<T>(snap: object, target?: Target): DocumentSnapshot<T> {
+export function wrapSandboxDocSnap<T>(snap: object, target?: Target): DocumentSnapshot<T> & { exists(): boolean } {
   const s = snap as {
     data: () => DocumentData | undefined;
     ref?: { path?: string };
+    exists?: boolean | (() => boolean);
   };
+  normalizeExists(s);
   const original = s.data.bind(snap);
+  const hasTarget = target !== undefined;
+  let references: ReferenceDecoder | undefined;
+  if (hasTarget) {
+    references = { create: (path) => doc({ [TARGET_SYMBOL]: target }, path) };
+  }
   Object.defineProperty(s, 'data', {
-    value: () => finalizeSandboxData(original()),
+    value: () => finalizeSandboxData(original(), references),
     configurable: true,
     writable: true,
   });
-  if (target && s.ref?.path) {
-    Object.defineProperty(s, 'metadata', {
-      value: clientStateFor(target).snapshotMetadata(s.ref.path),
-      configurable: true,
-    });
+  if (hasTarget) {
+    const path = s.ref?.path;
+    const hasPath = path !== undefined && path.length > 0;
+    if (hasPath) {
+      Object.defineProperty(s, 'metadata', {
+        value: clientStateFor(target).snapshotMetadata(path),
+        configurable: true,
+      });
+    }
   }
-  return snap as DocumentSnapshot<T>;
+  return snap as DocumentSnapshot<T> & { exists(): boolean };
 }
 
 /**
@@ -267,26 +281,27 @@ export function applyConverterToDocSnap<AppModel>(
   conv: FirestoreDataConverter<AppModel>,
   target: Target,
   kind: 'document' | 'query-child',
-): DocumentSnapshot<AppModel> {
+): DocumentSnapshot<AppModel> & { exists(): boolean } {
+  const rawReference = doc({ [TARGET_SYMBOL]: target }, snap.ref.path);
+  const reference = rawReference.withConverter(conv);
+  const references: ReferenceDecoder = { create: (path) => doc({ [TARGET_SYMBOL]: target }, path) };
   const wrapped = {
     id: snap.id,
-    ref: snap.ref,
-    exists: snap.exists,
+    ref: reference,
+    exists: () => snapshotExists(snap),
     metadata: clientStateFor(target).snapshotMetadata(snap.ref.path),
     data: () => {
       // Sandbox snaps expose `exists` as a property (Admin shape).
-      const exists = typeof snap.exists === 'function'
-        ? (snap.exists as () => boolean)()
-        : snap.exists;
-      if (!exists) return undefined;
-      const raw = finalizeSandboxData(snap.data() as DocumentData) as DocumentData;
+      const isMissing = !snapshotExists(snap);
+      if (isMissing) return undefined;
+      const raw = finalizeSandboxData(snap.data() as DocumentData, references) as DocumentData;
       // fromFirestore receives a QueryDocumentSnapshot-narrowed view —
       // doc is known to exist at this branch, so `data()` returns the
       // raw value (never undefined).
       const queryDocSnap: QueryDocumentSnapshot = {
         id: snap.id,
-        ref: snap.ref as unknown as QueryDocumentSnapshot['ref'],
-        exists: true,
+        ref: rawReference,
+        exists: () => true,
         metadata: clientStateFor(target).snapshotMetadata(snap.ref.path),
         data: () => raw,
       };
@@ -306,6 +321,57 @@ export function applyConverterToDocSnap<AppModel>(
   return wrapped;
 }
 
+/**
+ * Run a converter over a snapshot a listener is about to deliver, in place.
+ *
+ * The sandbox builds one snapshot object per document and hands that same
+ * object to both `docs` and `docChanges()`, so converting the object covers
+ * both views. `data()` is re-read through the converter and `ref` gains the
+ * converter, matching what the read path returns.
+ *
+ * Call after {@link wrapSandboxDocSnap}: the captured accessor already yields
+ * finalized values, which is what `fromFirestore` expects to receive.
+ */
+export function applyConverterToDeliveredSnap(
+  snapshot: object,
+  conv: FirestoreDataConverter<unknown>,
+  target: Target,
+  kind: 'document' | 'query-child',
+): void {
+  const s = snapshot as {
+    id: string;
+    ref?: { path?: string };
+    exists?: boolean | (() => boolean);
+    data: () => DocumentData | undefined;
+  };
+  const path = s.ref?.path ?? '';
+  const readRaw = s.data.bind(snapshot);
+  const rawReference = doc({ [TARGET_SYMBOL]: target }, path);
+  const converted = rawReference.withConverter(conv as FirestoreDataConverter<unknown, DocumentData>);
+  Object.defineProperty(s, 'ref', { value: converted, configurable: true, writable: true });
+  Object.defineProperty(s, 'data', {
+    value: () => {
+      const raw = readRaw();
+      const isMissing = raw === undefined;
+      if (isMissing) return undefined;
+      const queryDocSnap: QueryDocumentSnapshot = {
+        id: s.id,
+        ref: rawReference,
+        exists: () => true,
+        metadata: clientStateFor(target).snapshotMetadata(path),
+        data: () => raw,
+      };
+      return conv.fromFirestore(queryDocSnap);
+    },
+    configurable: true,
+    writable: true,
+  });
+  // Equality compares the stored representation, never the consumer model, so
+  // the recorded raw view keeps the pre-converter accessor.
+  const rawView = { ref: { path }, exists: s.exists, data: readRaw } as unknown as ChainDocSnap;
+  recordDocumentSnapshot(snapshot, rawView, target, conv, kind);
+}
+
 /**
  * Walk a snapshot and tag every ref-shaped field in `refToTarget`,
  * AND normalize `.exists` to method form so consumer code targeting

package/src/firestore/state.ts

@@ -25,8 +25,10 @@ import {
   Bytes as RulesBytes,
   LatLng as RulesLatLng,
   Vector as RulesVector,
+  Reference as RulesReference,
 } from 'pyric/rules/internal';
 import type { FirestoreDataConverter } from './types.js';
+import type { ReferenceDecoder } from './internal/value-codec.js';
 import { Bytes, GeoPoint, vector } from './field-values.js';
 
 // ─── Branding + routing ───────────────────────────────────────────────
@@ -38,6 +40,7 @@ import { Bytes, GeoPoint, vector } from './field-values.js';
 export const TARGET_SYMBOL: unique symbol = Symbol('pyric/firestore/target');
 
 interface FirestoreTargetLifecycle {
+  activityApp?: object;
   own?: (cleanup: () => void) => () => void;
   assertUsable?: () => void;
   terminate?: () => void;
@@ -241,6 +244,9 @@ function resolveTarget(refOrDb: object): Target {
   return target;
 }
 
+/** Shared with the admin error-translation proxy; see `buildSandboxShell`. */
+const MODULAR_VALUE_SYMBOL = Symbol.for('pyric.firestore.modular-value');
+
 export const refToConverter = new WeakMap<object, FirestoreDataConverter<unknown> | null>();
 export const refToUnderlying = new WeakMap<object, object>();
 
@@ -266,12 +272,17 @@ export function underlyingOf<T extends object>(obj: T): object {
 export function buildSandboxShell(
   underlying: { id?: string; path?: string },
   target: SandboxTarget | SandboxLiveTarget,
-  converter: FirestoreDataConverter<unknown>,
-): object {
+  converter: FirestoreDataConverter<unknown> | null,
+) {
   const shell = {
     id: underlying.id ?? '',
     path: underlying.path ?? '',
   };
+  // A shell handed back from a method call on a chainable ref (a collection's
+  // `withConverter`) passes through the admin error-translation proxy on its
+  // way out. The marker tells that proxy to return the shell itself rather
+  // than a fresh wrapper, which would not be the key these WeakMaps hold.
+  Object.defineProperty(shell, MODULAR_VALUE_SYMBOL, { value: true });
   refToConverter.set(shell, converter);
   refToUnderlying.set(shell, underlying);
   refToTarget.set(shell, target);
@@ -310,30 +321,38 @@ export function vectorValuesOf(value: unknown): number[] | null {
  * Phase 0-F; the formal COMPAT ✓ + oracle observation land with the
  * conformance phase (Phase 5b). Vector SEARCH (`findNearest`) is separate.
  */
-export function finalizeSandboxValue(value: unknown): unknown {
-  if (value instanceof RulesBytes) {
+export function finalizeSandboxValue(value: unknown, references?: ReferenceDecoder): unknown {
+  const isReference = value instanceof RulesReference;
+  if (isReference) return references?.create(value.path) ?? value;
+  const isBytes = value instanceof RulesBytes;
+  if (isBytes) {
     return Bytes.fromUint8Array(value.data);
   }
-  if (value instanceof RulesLatLng) {
+  const isGeoPoint = value instanceof RulesLatLng;
+  if (isGeoPoint) {
     return new GeoPoint(value.lat, value.lng);
   }
   const vectorValues = vectorValuesOf(value);
-  if (vectorValues) {
+  const isVector = vectorValues !== null;
+  if (isVector) {
     return vector(vectorValues);
   }
-  if (Array.isArray(value)) {
-    return value.map(finalizeSandboxValue);
+  const isArray = Array.isArray(value);
+  if (isArray) {
+    return value.map((item) => finalizeSandboxValue(item, references));
   }
   // Only walk plain objects (`{...}` literals + `Object.create(null)`).
   // Class instances we don't recognize pass through as identity so we
   // don't accidentally destructure their private state (the same gap
   // that motivated #109/#110 in the first place).
-  if (value !== null && typeof value === 'object') {
+  const isObject = value !== null && typeof value === 'object';
+  if (isObject) {
     const proto = Object.getPrototypeOf(value);
-    if (proto === Object.prototype || proto === null) {
+    const isPlainMap = proto === Object.prototype || proto === null;
+    if (isPlainMap) {
       const out: Record<string, unknown> = {};
       for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-        out[k] = finalizeSandboxValue(v);
+        out[k] = finalizeSandboxValue(v, references);
       }
       return out;
     }
@@ -341,7 +360,8 @@ export function finalizeSandboxValue(value: unknown): unknown {
   return value;
 }
 
-export function finalizeSandboxData(data: DocumentData | undefined): DocumentData | undefined {
-  if (data === undefined) return undefined;
-  return finalizeSandboxValue(data) as DocumentData;
+export function finalizeSandboxData(data: DocumentData | undefined, references?: ReferenceDecoder): DocumentData | undefined {
+  const isMissing = data === undefined;
+  if (isMissing) return undefined;
+  return finalizeSandboxValue(data, references) as DocumentData;
 }

package/src/firestore/timestamp.ts

@@ -0,0 +1,86 @@
+import {
+  boundedActivityIdentity,
+  registerActivityValue,
+} from './sandbox/activity-value-registry.js';
+import { registerQueryValue } from './sandbox/query-value-registry.js';
+import { FirebaseError } from '../sandbox/internal/firebase-error.js';
+
+const MIN_SECONDS = -62_135_596_800;
+const MAX_SECONDS_EXCLUSIVE = 253_402_300_800;
+
+export class Timestamp {
+  constructor(
+    public readonly seconds: number,
+    public readonly nanoseconds: number,
+  ) {
+    const nanosecondsOutOfRange = nanoseconds < 0 || nanoseconds >= 1_000_000_000;
+    if (nanosecondsOutOfRange) {
+      throw new FirebaseError('invalid-argument', `Timestamp nanoseconds out of range: ${nanoseconds}`);
+    }
+    const secondsOutOfRange = seconds < MIN_SECONDS || seconds >= MAX_SECONDS_EXCLUSIVE;
+    if (secondsOutOfRange) {
+      throw new FirebaseError('invalid-argument', `Timestamp seconds out of range: ${seconds}`);
+    }
+    registerActivityValue(
+      this,
+      boundedActivityIdentity('timestamp', String(seconds), '\0', String(nanoseconds)),
+    );
+    registerQueryValue(this, Object.freeze({
+      type: 'timestamp',
+      seconds,
+      nanoseconds,
+    }), () => new Timestamp(seconds, nanoseconds));
+  }
+  static now(): Timestamp {
+    return Timestamp.fromMillis(Date.now());
+  }
+  static fromDate(d: Date): Timestamp {
+    return Timestamp.fromMillis(d.getTime());
+  }
+  static fromMillis(ms: number): Timestamp {
+    // FS-B12 — derive nanoseconds as `floor((ms - seconds*1000) * 1e6)` so
+    // the value is ALWAYS non-negative (matching `fb.Timestamp.fromMillis`).
+    // The old `(ms % 1000) * 1e6` produced negative nanos for negative
+    // millis, so `fromMillis(-500)` round-tripped to -1500 via toMillis().
+    const seconds = Math.floor(ms / 1000);
+    const nanoseconds = Math.floor((ms - seconds * 1000) * 1_000_000);
+    return new Timestamp(seconds, nanoseconds);
+  }
+  toDate(): Date {
+    return new Date(this.toMillis());
+  }
+  toMillis(): number {
+    // FS-B12 — `nanoseconds / 1e6` (matching `fb.Timestamp.toMillis`), not
+    // `floor(nanoseconds / 1e6)`; the floor dropped sub-millisecond nanos
+    // and broke the negative-millis round-trip.
+    return this.seconds * 1000 + this.nanoseconds / 1_000_000;
+  }
+  /** FS-B12 — value equality, mirroring `fb.Timestamp.isEqual`. */
+  isEqual(other: Timestamp): boolean {
+    return other.seconds === this.seconds && other.nanoseconds === this.nanoseconds;
+  }
+  /** FS-B12 — textual form, mirroring `fb.Timestamp.toString`. */
+  toString(): string {
+    return `Timestamp(seconds=${this.seconds}, nanoseconds=${this.nanoseconds})`;
+  }
+  /** FS-B12 — JSON form, mirroring `fb.Timestamp.toJSON`. */
+  toJSON(): { type: string; seconds: number; nanoseconds: number } {
+    return {
+      type: 'firestore/timestamp/1.0',
+      seconds: this.seconds,
+      nanoseconds: this.nanoseconds,
+    };
+  }
+  /**
+   * FS-B12 — primitive coercion for `<`/`<=`/`>=`/`>` comparisons, mirroring
+   * `fb.Timestamp.valueOf`: a zero-padded `<seconds>.<nanoseconds>` string
+   * (seconds offset by MIN_SECONDS so it stays non-negative and lexically
+   * ordered).
+   */
+  valueOf(): string {
+    const adjustedSeconds = this.seconds - MIN_SECONDS;
+    const formattedSeconds = String(adjustedSeconds).padStart(12, '0');
+    const formattedNanoseconds = String(this.nanoseconds).padStart(9, '0');
+    return `${formattedSeconds}.${formattedNanoseconds}`;
+  }
+}

package/src/firestore/tools.ts

@@ -13,6 +13,7 @@
  */
 
 import type { ToolHandler } from '@inbrowser/agent';
+import { QUERY_WHERE_OPERATORS } from './sandbox/query-operators.js';
 import type { LocalSandbox } from 'pyric/sandbox';
 import { inspect } from './sandbox-controls.js';
 import type { Firestore } from './index.js';
@@ -64,8 +65,7 @@ const AS_SCHEMA = {
 
 /** Pre-mortem M9 — constrain where-op to the WhereFilterOp union
  *  at the schema level so agents can't pass `==` typos. */
-const WHERE_OPS = ['<', '<=', '==', '!=', '>=', '>', 'in', 'not-in', 'array-contains', 'array-contains-any'] as const;
-type WhereOp = typeof WHERE_OPS[number];
+type WhereOp = typeof QUERY_WHERE_OPERATORS[number];
 
 interface WhereClause {
   field: string;
@@ -77,7 +77,7 @@ const WHERE_CLAUSE_SCHEMA = {
   type: 'object' as const,
   properties: {
     field: { type: 'string' as const },
-    op: { type: 'string' as const, enum: [...WHERE_OPS] },
+    op: { type: 'string' as const, enum: [...QUERY_WHERE_OPERATORS] },
     value: {},
   },
   required: ['field', 'op', 'value'],