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

package/src/firestore/sandbox/transaction-write-executor.ts

@@ -1,4 +1,4 @@
-import type { BatchOperation, DocumentData } from './local-state.js';
+import type { DocumentData } from './local-state.js';
 import { makeError, type FirestoreSimError } from './errors.js';
 import {
   RetryableTransactionConflictError,
@@ -6,16 +6,15 @@ import {
   TransactionContext,
   type TransactionReader,
 } from './transaction.js';
-import { mergeQueuedWrites } from './transaction-merge.js';
 import type {
   Transaction,
   TransactionOptions,
   TransactionResult,
 } from './transaction-types.js';
-import { AtomicWritePipeline } from './atomic-write-pipeline.js';
+import { AtomicWritePipeline, type AtomicRuleMethod } from './atomic-write-pipeline.js';
 import { WriteRuntime } from './write-runtime.js';
 
-/** Adapts transaction callbacks, merge semantics, and results to the atomic pipeline. */
+/** Adapts transaction callbacks, ordered writes, and results to the atomic pipeline. */
 export class TransactionWriteExecutor {
   private readonly pipeline: AtomicWritePipeline;
 
@@ -51,9 +50,11 @@ export class TransactionWriteExecutor {
     const reader: TransactionReader = (path) => snapshot[path] ?? null;
     const context = new TransactionContext(reader, (path) => {
       const captured = versionsAtStart.get(path);
-      if (captured !== undefined) return captured;
+      const hasCapturedVersion = captured !== undefined;
+      if (hasCapturedVersion) return captured;
       const current = this.runtime.state.version(path);
-      return current <= attemptVersion ? current : -1;
+      const existedAtStart = current <= attemptVersion;
+      return existedAtStart ? current : -1;
     });
 
     let callbackResult: R | Promise<R>;
@@ -64,10 +65,10 @@ export class TransactionWriteExecutor {
       throw error;
     }
 
-    if (
+    const isAsyncCallback =
       callbackResult !== null &&
-      typeof (callbackResult as PromiseLike<R>)?.then === 'function'
-    ) {
+      typeof (callbackResult as PromiseLike<R>)?.then === 'function';
+    if (isAsyncCallback) {
       return (callbackResult as Promise<R>).then(
         (value) => {
           try {
@@ -95,9 +96,11 @@ export class TransactionWriteExecutor {
     options: TransactionOptions,
     attempt: number,
   ): TransactionResult<R> | Promise<TransactionResult<R>> {
-    if (!(error instanceof RetryableTransactionConflictError)) throw error;
+    const isNonConflictError = !(error instanceof RetryableTransactionConflictError);
+    if (isNonConflictError) throw error;
     const maxAttempts = options.maxAttempts ?? 5;
-    if (attempt >= maxAttempts) throw new TransactionAttemptsExhaustedError();
+    const attemptsExhausted = attempt >= maxAttempts;
+    if (attemptsExhausted) throw new TransactionAttemptsExhaustedError();
     return this.runAttempt(fn, options, attempt + 1);
   }
 
@@ -109,17 +112,20 @@ export class TransactionWriteExecutor {
   ): TransactionResult<R> {
     const { reads, writes, readVersions } = context.consume();
     for (const [path, version] of readVersions) {
-      if (this.runtime.state.version(path) !== version) {
+      const readChanged = this.runtime.state.version(path) !== version;
+      if (readChanged) {
         throw new RetryableTransactionConflictError();
       }
     }
     const auth = options.auth;
-    if (writes.length === 0) {
+    const hasNoWrites = writes.length === 0;
+    if (hasNoWrites) {
+      const hasAuth = auth !== null;
       const event = this.runtime.eventLog.append({
         type: 'transaction',
         method: 'transaction',
         path: '',
-        auth: auth ? { uid: auth.uid } : null,
+        auth: hasAuth ? { uid: auth.uid } : null,
         allowed: true,
         reads: reads.map((read) => ({ path: read.path, data: read.data })),
         operations: [],
@@ -129,34 +135,19 @@ export class TransactionWriteExecutor {
       return { allowed: true, reads: [...reads], writes: [], returnValue, event };
     }
 
-    let mergedOps: BatchOperation[];
-    try {
-      mergedOps = mergeQueuedWrites(writes);
-    } catch (error) {
-      const err = error as Error;
-      this.runtime.eventLog.append({
-        type: 'transaction',
-        method: 'transaction',
-        path: '',
-        auth: auth ? { uid: auth.uid } : null,
-        allowed: false,
-        aborted: true,
-        reads: reads.map((read) => ({ path: read.path, data: read.data })),
-        error: { name: err.name, message: err.message, code: 'failed-precondition' },
-        debugMessages: [`Transaction aborted at merge: ${err.message}`],
-      });
-      throw error;
-    }
-
     const priorDocs = Object.fromEntries(
-      mergedOps.map((operation) => [operation.path, snapshot[operation.path] ?? null]),
+      writes.map((operation) => [operation.path, snapshot[operation.path] ?? null]),
     );
-    const inputs = mergedOps.map((operation) => {
-      const ruleMethod = operation.method === 'set'
-        ? this.runtime.state.get(operation.path) !== null
-          ? 'update'
-          : 'create'
-        : operation.method;
+    const inputs = writes.map((operation) => {
+      const { method } = operation;
+      const isSet = method === 'set';
+      let ruleMethod: AtomicRuleMethod;
+      if (isSet) {
+        const documentExists = this.runtime.state.get(operation.path) !== null;
+        ruleMethod = documentExists ? 'update' : 'create';
+      } else {
+        ruleMethod = method;
+      }
       return {
         ...operation,
         ruleMethod,
@@ -173,34 +164,42 @@ export class TransactionWriteExecutor {
       snapshot: priorDocs,
     });
 
-    if (!('resolvedOps' in prepared)) {
+    const preparationFailed = !('resolvedOps' in prepared);
+    if (preparationFailed) {
+      const hasAuth = auth !== null;
       const event = this.runtime.eventLog.append({
         type: 'transaction',
         method: 'transaction',
         path: '',
-        auth: auth ? { uid: auth.uid } : null,
+        auth: hasAuth ? { uid: auth.uid } : null,
         allowed: false,
+        aborted: true,
+        error: { name: 'FirebaseError', message: prepared.message, code: prepared.error.code },
         reads: reads.map((read) => ({ path: read.path, data: read.data })),
-        operations: mergedOps.map((operation) => ({
+        operations: writes.map((operation) => ({
           method: operation.method,
           path: operation.path,
           data: operation.data,
           allowed: false,
         })),
         debugMessages: [
-          `FieldValue resolve error on '${prepared.input.path}': ${prepared.message}`,
+          `Write preparation error on '${prepared.input.path}': ${prepared.message}`,
         ],
       });
       this.runtime.emitRequest(prepared.request);
       return {
         allowed: false,
         reads: [...reads],
-        writes: inputs.map((input, index) => ({
-          path: input.path,
-          method: input.ruleMethod,
-          allowed: false,
-          debugMessages: index === prepared.index ? [prepared.message] : [],
-          ...(index === prepared.index ? { error: prepared.error } : {}),
+        writes: this.summarizeWrites(inputs.map((input, index) => {
+          const isFailedWrite = index === prepared.index;
+          const write: TransactionResult<R>['writes'][number] = {
+            path: input.path,
+            method: input.ruleMethod,
+            allowed: false,
+            debugMessages: isFailedWrite ? [prepared.message] : [],
+          };
+          if (isFailedWrite) write.error = prepared.error;
+          return write;
         })),
         returnValue,
         event,
@@ -209,20 +208,25 @@ export class TransactionWriteExecutor {
     }
 
     const decision = this.pipeline.evaluateAndApply(prepared);
-    const writeResults: TransactionResult<R>['writes'] =
-      decision.outcomes.map((outcome) => ({
+    const writeResults = decision.outcomes.map((outcome) => {
+      const write: TransactionResult<R>['writes'][number] = {
         path: outcome.path,
         method: outcome.method,
         allowed: outcome.allowed,
         debugMessages: outcome.debugMessages,
-        ...(outcome.error ? { error: outcome.error } : {}),
-      }));
+      };
+      const hasError = outcome.error !== undefined;
+      if (hasError) write.error = outcome.error;
+      return write;
+    });
+    const { allowed } = decision;
+    const hasAuth = auth !== null;
     const event = this.runtime.eventLog.append({
       type: 'transaction',
       method: 'transaction',
       path: '',
-      auth: auth ? { uid: auth.uid } : null,
-      allowed: decision.allowed,
+      auth: hasAuth ? { uid: auth.uid } : null,
+      allowed,
       reads: reads.map((read) => ({ path: read.path, data: read.data })),
       operations: decision.resolvedOps.map((operation, index) => ({
         method: operation.method,
@@ -230,32 +234,59 @@ export class TransactionWriteExecutor {
         data: operation.data,
         allowed: writeResults[index]?.allowed ?? false,
       })),
-      snapshot: decision.allowed ? snapshot : undefined,
-      debugMessages: decision.allowed
+      snapshot: allowed ? snapshot : undefined,
+      debugMessages: allowed
         ? ['Transaction committed']
         : ['Transaction rolled back — one or more operations denied'],
     });
 
     this.pipeline.emitAndNotify(decision);
     let topError: FirestoreSimError | undefined;
-    if (!decision.allowed) {
+    const wasDenied = !allowed;
+    if (wasDenied) {
       topError =
         decision.structuralError ??
         writeResults.find((write) => write.error)?.error ??
         makeError('permission-denied', 'Transaction denied');
     }
     const result: TransactionResult<R> = {
-      allowed: decision.allowed,
+      allowed,
       reads: [...reads],
-      writes: writeResults,
+      writes: this.summarizeWrites(writeResults),
       returnValue,
       event,
-      ...(topError ? { error: topError } : {}),
     };
-    if (options.readOnly && context.hadWrites()) result.readOnlyViolation = true;
+    const hasTopError = topError !== undefined;
+    if (hasTopError) result.error = topError;
+    const violatedReadOnly = options.readOnly === true && context.hadWrites();
+    if (violatedReadOnly) result.readOnlyViolation = true;
     return result;
   }
 
+  private summarizeWrites(writes: TransactionResult['writes']): TransactionResult['writes'] {
+    const byPath = new Map<string, TransactionResult['writes'][number]>();
+    for (const write of writes) {
+      const previous = byPath.get(write.path);
+      const isFirstWrite = previous === undefined;
+      if (isFirstWrite) {
+        byPath.set(write.path, write);
+        continue;
+      }
+      const allowed = previous.allowed && write.allowed;
+      const summary: TransactionResult['writes'][number] = {
+        path: write.path,
+        method: write.method,
+        allowed,
+        debugMessages: [...previous.debugMessages, ...write.debugMessages],
+      };
+      const error = previous.error ?? write.error;
+      const hasError = error !== undefined;
+      if (hasError) summary.error = error;
+      byPath.set(write.path, summary);
+    }
+    return [...byPath.values()];
+  }
+
   private logAbortedTransaction(
     context: TransactionContext,
     auth: TransactionOptions['auth'],
@@ -263,19 +294,22 @@ export class TransactionWriteExecutor {
   ): void {
     const withCode = error as Error & { code?: unknown };
     const { reads } = context.consume();
+    const hasAuth = auth !== null;
+    const errorDetails: { name: string; message: string; code?: string } = {
+      name: error.name,
+      message: error.message,
+    };
+    const hasCode = withCode.code !== undefined;
+    if (hasCode) errorDetails.code = String(withCode.code);
     this.runtime.eventLog.append({
       type: 'transaction',
       method: 'transaction',
       path: '',
-      auth: auth ? { uid: auth.uid } : null,
+      auth: hasAuth ? { uid: auth.uid } : null,
       allowed: false,
       aborted: true,
       reads: reads.map((read) => ({ path: read.path, data: read.data })),
-      error: {
-        name: error.name,
-        message: error.message,
-        ...(withCode.code !== undefined ? { code: String(withCode.code) } : {}),
-      },
+      error: errorDetails,
       debugMessages: [`Transaction aborted: ${error.message}`],
     });
   }

package/src/firestore/sandbox/transaction.ts

@@ -7,7 +7,7 @@
  *   1. Capture reads (admin-mode, no rules) via an injected reader
  *      callback. This decouples the class from `LocalEnvironment` for
  *      testability — Item 2 binds the reader to `this.getDocument`.
- *   2. Queue writes append-only. The merge / atomic-apply / rules-eval
+ *   2. Queue writes append-only. Ordered resolution / atomic-apply / rules-eval
  *      all happen *after* the callback returns, in `LocalEnvironment.
  *      transaction()` (Item 2.1).
  *   3. Enforce global read-before-write ordering — once any write
@@ -21,6 +21,8 @@
  */
 import type { DocumentData } from './local-state.js';
 import { makeError, type FirestoreSimError } from './errors.js';
+import type { Operation } from './writes.js';
+import { cloneDoc } from './document-copy.js';
 import {
   READ_AFTER_WRITE_MESSAGE,
   type CapturedRead,
@@ -97,18 +99,23 @@ export class TransactionContext implements Transaction {
   get(path: string): TransactionSnapshot {
     this.assertReadsAllowed();
     const data = this.reader(path);
-    if (!this.readVersions.has(path)) {
+    const isNewRead = !this.readVersions.has(path);
+    if (isNewRead) {
       this.readVersions.set(path, this.versionReader(path));
     }
     this.reads.push({ path, data });
     // Capture-by-value: callbacks that mutate `data()` later don't
     // poison the captured read set. Cheap (small docs) and matches
     // production semantics where the snapshot is immutable.
-    const captured = data === null ? null : structuredClone(data);
+    const documentMissing = data === null;
+    const captured = documentMissing ? null : cloneDoc(data);
     return {
       path,
       exists: captured !== null,
-      data: () => (captured === null ? undefined : captured),
+      data: () => {
+        const isMissing = captured === null;
+        return isMissing ? undefined : captured;
+      },
     };
   }
 
@@ -121,8 +128,14 @@ export class TransactionContext implements Transaction {
 
   // ─── Writes ───────────────────────────────────────────────────────
 
-  set(path: string, data: DocumentData): void {
-    this.queue({ method: 'set', path, data });
+  set(path: string, data: DocumentData, merge?: Operation['merge']): void {
+    const write: QueuedWrite = { method: 'set', path, data };
+    const hasMerge = merge !== undefined;
+    if (hasMerge) {
+      const hasFieldMask = typeof merge === 'object';
+      write.merge = hasFieldMask ? { mergeFields: [...merge.mergeFields] } : merge;
+    }
+    this.queue(write);
   }
   create(path: string, data: DocumentData): void {
     this.queue({ method: 'create', path, data });
@@ -161,12 +174,16 @@ export class TransactionContext implements Transaction {
   // ─── Private ──────────────────────────────────────────────────────
 
   private queue(write: QueuedWrite): void {
+    const { data } = write;
+    const hasData = data !== undefined;
+    if (hasData) write.data = cloneDoc(data);
     this.writeStarted = true;
     this.writes.push(write);
   }
 
   private assertReadsAllowed(): void {
-    if (this.writeStarted) {
+    const readsAreClosed = this.writeStarted;
+    if (readsAreClosed) {
       throw new ReadAfterWriteError();
     }
   }

package/src/firestore/sandbox/value-resolver.ts

@@ -47,6 +47,8 @@ import {
 import { documentReferenceConverter } from './converters/reference.js';
 import { vectorValueConverter } from './converters/vector.js';
 import { bytesConverter, geoPointConverter } from './converters/bytes-geopoint.js';
+import { isPlainObject } from '../plain-object.js';
+export { isPlainObject } from '../plain-object.js';
 
 export type DocumentData = Record<string, unknown>;
 
@@ -184,19 +186,6 @@ export function resolveValue(value: unknown, ctx: ResolveContext): unknown {
   return value;
 }
 
-/**
- * Plain-object detection: an object literal whose prototype chain is
- * `Object.prototype` (or null, for `Object.create(null)`). Class
- * instances like `Date`, `Timestamp`, `DocumentReference` deliberately
- * fall through to converter-or-identity handling — the resolver should
- * not silently strip their prototype by walking them as plain maps.
- */
-export function isPlainObject(value: unknown): value is DocumentData {
-  if (value === null || typeof value !== 'object') return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-}
-
 /**
  * Item 2 — split a resolved tree into "values to write" and "fields to
  * delete" by walking it for {@link DELETE_MARKER} sentinels.

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

@@ -36,6 +36,7 @@ import type {
 import { WriteRuntime } from './write-runtime.js';
 import { BatchWriteExecutor } from './batch-write-executor.js';
 import { TransactionWriteExecutor } from './transaction-write-executor.js';
+import { SandboxClock } from '../../sandbox/clock.js';
 
 interface WriteEngineHost {
   readonly state: DocStore;
@@ -55,6 +56,9 @@ export class WriteEngine {
     eventLog: EventLog,
     events: FirestoreEventBus,
     triggerScope: TriggerScope,
+    /** The sandbox's clock, read for every server-set time this produces.
+     *  Defaults to a private wall clock for a standalone construction. */
+    clock: SandboxClock = new SandboxClock(),
   ) {
     this.runtime = new WriteRuntime(
       host,
@@ -63,6 +67,7 @@ export class WriteEngine {
       eventLog,
       events,
       triggerScope,
+      clock,
     );
     this.batches = new BatchWriteExecutor(this.runtime);
     this.transactions = new TransactionWriteExecutor(this.runtime);
@@ -122,9 +127,9 @@ export class WriteEngine {
     // `request.time`) must see field-equal values, otherwise rules like
     // `data.createdAt == request.time` flake on sub-millisecond drift.
     // Replay engine: `operation.requestTime` (when provided) overrides
-    // Date.now() so the rule eval re-evaluates against the captured
-    // wall-clock instant, eliminating time-drift on replay.
-    const serverTime = pinnedRequestTime ?? Timestamp.fromMillis(Date.now());
+    // the sandbox clock so the rule eval re-evaluates against the captured
+    // instant, eliminating time-drift on replay.
+    const serverTime = pinnedRequestTime ?? Timestamp.fromMillis(this.runtime.clock.now());
 
     // Resolve the write payload BEFORE rule evaluation so rules see the
     // same shape storage will see (Item 0: write-boundary value-resolve).
@@ -164,7 +169,7 @@ export class WriteEngine {
       // engine but the user's op still produced a denial. evalMs is 0
       // because no simulate call happened.
       this.runtime.emitRequest({
-        at: Date.now(), evalMs: 0, method, path, auth, result: 'deny',
+        at: this.runtime.clock.now(), evalMs: 0, method, path, auth, result: 'deny',
         debugMessages: [`FieldValue resolve error: ${msg}`],
         ...(resolvedData ? { resourceData: resolvedData } : data ? { resourceData: data } : {}),
         resourceBefore: { data: snapshot[path] ?? null, exists: (snapshot[path] ?? null) !== null },
@@ -184,7 +189,7 @@ export class WriteEngine {
 
     const testCase = this.runtime.buildTestCase({ ...operation, data: resolvedData }, serverTime);
     // Issue #307 — time the simulate call for RequestEvent.evalMs.
-    const evalAt = Date.now();
+    const evalAt = this.runtime.clock.now();
     const evalStart = performance.now();
     const simResult = this.runtime.runSimulate([testCase], bypassRules);
     const evalMs = performance.now() - evalStart;
@@ -215,9 +220,11 @@ export class WriteEngine {
     }
 
     const result = simResult.data.results[0];
+    const rulesEvidence = this.runtime.captureEvidence(result);
     if (result.state === 'UNSUPPORTED') {
       this.runtime.emitRequest({
         at: evalAt, evalMs, method, path, auth, result: 'unsupported',
+        rulesEvidence,
         debugMessages: renderLegacyDebugMessages(result),
         ...(data ? { resourceData: data } : {}),
         resourceBefore: { data: snapshot[path] ?? null, exists: (snapshot[path] ?? null) !== null },
@@ -334,6 +341,7 @@ export class WriteEngine {
       result: isAllowed ? 'allow' : 'deny',
       debugMessages: renderLegacyDebugMessages(result),
       evaluatedRule: projectEvaluatedRule(result),
+      rulesEvidence,
       ...(data ? { resourceData: data } : {}),
       resourceBefore: { data: priorDoc, exists: priorDoc !== null },
       ...(method !== 'delete'