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

package/src/firestore/sandbox/atomic-write-pipeline.ts

@@ -1,6 +1,6 @@
 import type { BatchOperation, DocumentData } from './local-state.js';
 import { resolveValueTree, type ResolveMethod } from './value-resolver.js';
-import { makeError, type FirestoreSimError } from './errors.js';
+import { makeError, type FirestoreEvalRequest, type FirestoreSimError } from './errors.js';
 import { renderLegacyDebugMessages, Timestamp, projectEvaluatedRule } from 'pyric/rules/internal';
 import {
 
@@ -11,6 +11,7 @@ import type { Operation } from './writes.js';
 import type { EventProvenance } from '../../sandbox/types/events.js';
 import type { EmitRequestInput } from './request-events.js';
 import { walkForSentinels } from './sentinel-capture.js';
+import { applyMerge } from './field-merge.js';
 import { WriteRuntime } from './write-runtime.js';
 
 export type AtomicRuleMethod = 'create' | 'update' | 'delete';
@@ -22,6 +23,7 @@ export interface AtomicWriteInput {
   path: string;
   data?: DocumentData;
   preData?: DocumentData;
+  merge?: Operation['merge'];
 }
 
 export interface AtomicWriteContext {
@@ -40,7 +42,7 @@ export interface AtomicPreparation {
   serverTime: Timestamp;
 }
 
-export interface AtomicResolutionFailure {
+export interface AtomicPreparationFailure {
   index: number;
   input: AtomicWriteInput;
   message: string;
@@ -73,42 +75,65 @@ export class AtomicWritePipeline {
   prepare(
     inputs: AtomicWriteInput[],
     context: AtomicWriteContext,
-  ): AtomicPreparation | AtomicResolutionFailure {
-    const serverTime = Timestamp.fromMillis(Date.now());
+  ): AtomicPreparation | AtomicPreparationFailure {
+    const serverTime = Timestamp.fromMillis(this.runtime.clock.now());
     const resolvedOps: BatchOperation[] = [];
-    for (let index = 0; index < inputs.length; index++) {
-      const input = inputs[index]!;
+    const projection = new Map<string, DocumentData | null>();
+    for (const [index, input] of inputs.entries()) {
       try {
-        const data = input.data
-          ? resolveValueTree({ ...input.data }, {
-              path: input.path,
-              method: input.method as ResolveMethod,
-              prior: this.runtime.state.get(input.path),
-              serverTime,
-            })
-          : input.data;
-        resolvedOps.push({ method: input.method, path: input.path, data });
+        const updatesDeletedDocument = input.method === 'update' && projection.get(input.path) === null;
+        if (updatesDeletedDocument) {
+          throw new Error(`Cannot delete then update document '${input.path}' in the same atomic write.`);
+        }
+        const hasData = input.data !== undefined;
+        let data = input.data;
+        if (hasData) {
+          const hasEarlierWrite = projection.has(input.path);
+          let prior: DocumentData | null;
+          if (hasEarlierWrite) {
+            prior = projection.get(input.path) ?? null;
+          } else {
+            prior = this.runtime.state.get(input.path);
+          }
+          data = resolveValueTree({ ...input.data }, {
+            path: input.path,
+            method: input.method as ResolveMethod,
+            prior,
+            serverTime,
+          });
+          const { merge } = input;
+          const hasMerge = merge !== undefined && merge !== false;
+          if (hasMerge) {
+            const mergesAllFields = merge === true;
+            const mergeFields = mergesAllFields ? undefined : merge.mergeFields;
+            data = applyMerge(prior ?? {}, data, mergeFields);
+          }
+        }
+        const resolved = { method: input.method, path: input.path, data };
+        resolvedOps.push(resolved);
+        this.runtime.buildBatchProjection([resolved], projection);
       } catch (error) {
         const message = (error as Error).message;
         const wrapped = makeError('invalid-argument', message);
         const prior = context.snapshot[input.path] ?? null;
         const request: EmitRequestInput = {
-          at: Date.now(),
+          at: this.runtime.clock.now(),
           evalMs: 0,
           method: input.ruleMethod,
           path: input.path,
           auth: context.auth,
           result: 'deny',
-          debugMessages: [`FieldValue resolve error: ${message}`],
-          ...(this.includesRequestData(context, input)
-            ? { resourceData: input.preData }
-            : {}),
+          debugMessages: [`Write preparation error: ${message}`],
           resourceBefore: { data: prior, exists: prior !== null },
           origin: context.origin,
           groupId: context.groupId,
-          ...(context.bypassRules ? { detail: { admin: true } } : {}),
-          ...(context.provenance ? { provenance: context.provenance } : {}),
         };
+        const includesData = this.includesRequestData(context, input);
+        if (includesData) request.resourceData = input.preData;
+        const bypassesRules = context.bypassRules === true;
+        if (bypassesRules) request.detail = { admin: true };
+        const hasProvenance = context.provenance !== undefined;
+        if (hasProvenance) request.provenance = context.provenance;
         return { index, input, message, error: wrapped, request };
       }
     }
@@ -116,34 +141,49 @@ export class AtomicWritePipeline {
   }
 
   evaluateAndApply(prepared: AtomicPreparation): AtomicDecision {
-    const { context, inputs, resolvedOps, serverTime } = prepared;
+    const { context, resolvedOps, serverTime } = prepared;
+    const projection = this.runtime.buildBatchProjection(resolvedOps);
+    const inputs = prepared.inputs.map((input) => {
+      const hasExplicitRuleMethod = input.method !== 'set';
+      if (hasExplicitRuleMethod) return input;
+      const deletesDocument = projection.get(input.path) === null;
+      let ruleMethod: AtomicRuleMethod;
+      if (deletesDocument) {
+        ruleMethod = 'delete';
+      } else {
+        const documentExists = this.runtime.state.get(input.path) !== null;
+        ruleMethod = documentExists ? 'update' : 'create';
+      }
+      return { ...input, ruleMethod };
+    });
     const testCases = resolvedOps.map((operation, index) => {
-      const input = inputs[index]!;
-      return this.runtime.buildTestCase({
-        method: input.ruleMethod,
+      const testCase = this.runtime.buildTestCase({
+        method: inputs[index].ruleMethod,
         path: operation.path,
         auth: context.auth,
         data: operation.data,
       }, serverTime);
+      // Atomic request.resource and getAfter both describe the final document.
+      testCase.data = projection.get(operation.path) ?? undefined;
+      return testCase;
     });
-    const projection = this.runtime.buildBatchProjection(testCases);
     const outcomes: AtomicWriteOutcome[] = [];
     let allowed = true;
 
-    for (let index = 0; index < resolvedOps.length; index++) {
-      const operation = resolvedOps[index]!;
-      const input = inputs[index]!;
+    for (const [index] of resolvedOps.entries()) {
+      const input = inputs[index];
       const prior = context.snapshot[input.path] ?? null;
-      const evalAt = Date.now();
+      const evalAt = this.runtime.clock.now();
       const evalStart = performance.now();
       const simulation = this.runtime.runSimulate(
-        [testCases[index]!],
+        [testCases[index]],
         context.bypassRules,
         projection,
       );
       const evalMs = performance.now() - evalStart;
 
-      if (!simulation.success) {
+      const simulationFailed = !simulation.success;
+      if (simulationFailed) {
         const error = makeError('invalid-argument', simulation.error.message);
         outcomes.push({
           path: input.path,
@@ -165,10 +205,11 @@ export class AtomicWritePipeline {
         continue;
       }
 
-      const evaluated = simulation.data.results[0]!;
+      const evaluated = simulation.data.results[0];
       const debugMessages = renderLegacyDebugMessages(evaluated);
-      if (evaluated.state === 'UNSUPPORTED') {
-        this.runtime.emitRequest(this.request(
+      const isUnsupported = evaluated.state === 'UNSUPPORTED';
+      if (isUnsupported) {
+        const unsupportedRequest = this.request(
           prepared,
           input,
           prior,
@@ -176,7 +217,9 @@ export class AtomicWritePipeline {
           evalMs,
           'unsupported',
           debugMessages,
-        ));
+        );
+        unsupportedRequest.rulesEvidence = this.runtime.captureEvidence(evaluated);
+        this.runtime.emitRequest(unsupportedRequest);
         throw new SimulatorUnsupportedError(
           unsupportedMessage(input.ruleMethod, input.path, debugMessages),
           input.ruleMethod,
@@ -205,18 +248,15 @@ export class AtomicWritePipeline {
           debugMessages,
         ),
       };
-      if (isAllowed === false) {
+      outcome.request.rulesEvidence = this.runtime.captureEvidence(evaluated);
+      const isDenied = !isAllowed;
+      if (isDenied) {
         const evalRule = projectEvaluatedRule(evaluated);
         const isPriorNotNull = prior !== null;
         const errExtras: {
-          request: {
-            method: AtomicRuleMethod;
-            path: string;
-            auth: any;
-            resourceData?: DocumentData;
-          };
+          request: FirestoreEvalRequest;
           resource: { data: DocumentData | null; exists: boolean };
-          rule?: any;
+          rule?: FirestoreSimError['rule'];
         } = {
           request: {
             method: input.ruleMethod,
@@ -236,7 +276,7 @@ export class AtomicWritePipeline {
         outcome.error = makeError(
           'permission-denied',
           `${input.ruleMethod} ${input.path} denied by rules`,
-          errExtras as any,
+          errExtras,
         );
         this.runtime.emitDenial(outcome.error);
         allowed = false;
@@ -247,17 +287,21 @@ export class AtomicWritePipeline {
     let structuralError: FirestoreSimError | null = null;
     if (allowed) {
       const applied = this.runtime.state.applyBatch(resolvedOps);
-      if (!applied.success) {
+      const applicationFailed = !applied.success;
+      if (applicationFailed) {
         allowed = false;
         const first = applied.errors?.[0];
-        if (first !== undefined) {
+        const hasFailure = first !== undefined;
+        if (hasFailure) {
           const failed = resolvedOps[first.index];
+          const failedCreate = failed?.method === 'create';
           structuralError = makeError(
-            failed?.method === 'create' ? 'already-exists' : 'not-found',
+            failedCreate ? 'already-exists' : 'not-found',
             first.error,
           );
           const outcome = outcomes[first.index];
-          if (outcome) {
+          const hasOutcome = outcome !== undefined;
+          if (hasOutcome) {
             outcome.allowed = false;
             outcome.error = structuralError;
           }
@@ -265,50 +309,56 @@ export class AtomicWritePipeline {
       }
     }
 
-    return { ...prepared, outcomes, allowed, structuralError };
+    return { ...prepared, inputs, outcomes, allowed, structuralError };
   }
 
   emitAndNotify(decision: AtomicDecision): void {
     const { context, inputs, outcomes, serverTime } = decision;
-    for (let index = 0; index < outcomes.length; index++) {
-      const outcome = outcomes[index]!;
-      const input = inputs[index]!;
+    for (const [index, outcome] of outcomes.entries()) {
+      const input = inputs[index];
       const committed = decision.allowed && outcome.allowed;
       const prior = context.snapshot[input.path] ?? null;
-      outcome.request.resourceAfter = committed
-        ? input.ruleMethod === 'delete'
+      if (committed) {
+        const isDelete = input.ruleMethod === 'delete';
+        outcome.request.resourceAfter = isDelete
           ? { data: null, exists: false }
           : {
               data: this.runtime.state.get(input.path),
               exists: this.runtime.state.get(input.path) !== null,
-            }
-        : { data: prior, exists: prior !== null };
+            };
+      } else {
+        outcome.request.resourceAfter = { data: prior, exists: prior !== null };
+      }
       this.runtime.emitRequest(outcome.request);
 
       if (committed) {
-        const sentinels = input.preData ? walkForSentinels(input.preData) : undefined;
-        this.runtime.emitWrite({
+        const hasPreData = input.preData !== undefined;
+        const sentinels = hasPreData ? walkForSentinels(input.preData) : undefined;
+        const isDelete = input.ruleMethod === 'delete';
+        const write: Parameters<WriteRuntime['emitWrite']>[0] = {
           method: input.ruleMethod,
           path: input.path,
           auth: context.auth,
-          ...(input.ruleMethod !== 'delete' && input.preData
-            ? { data: input.preData }
-            : {}),
           priorState: prior,
-          nextState: input.ruleMethod === 'delete'
-            ? null
-            : this.runtime.state.get(input.path),
+          nextState: isDelete ? null : this.runtime.state.get(input.path),
           groupId: context.groupId,
           groupKind: context.origin,
-          ...(sentinels && sentinels.length > 0 ? { sentinels } : {}),
           requestTime: serverTime,
-          ...(context.bypassRules ? { detail: { admin: true } } : {}),
-          ...(context.provenance ? { provenance: context.provenance } : {}),
-        });
+        };
+        const includesData = !isDelete && hasPreData;
+        if (includesData) write.data = input.preData;
+        const hasSentinels = sentinels !== undefined && sentinels.length > 0;
+        if (hasSentinels) write.sentinels = sentinels;
+        const bypassesRules = context.bypassRules === true;
+        if (bypassesRules) write.detail = { admin: true };
+        const hasProvenance = context.provenance !== undefined;
+        if (hasProvenance) write.provenance = context.provenance;
+        this.runtime.emitWrite(write);
       }
     }
 
-    if (decision.allowed) {
+    const { allowed } = decision;
+    if (allowed) {
       this.runtime.notify(
         context.origin,
         inputs[0]?.path ?? '',
@@ -327,7 +377,7 @@ export class AtomicWritePipeline {
     debugMessages: string[],
   ): EmitRequestInput {
     const { context } = prepared;
-    return {
+    const request: EmitRequestInput = {
       at,
       evalMs,
       method: input.ruleMethod,
@@ -335,15 +385,17 @@ export class AtomicWritePipeline {
       auth: context.auth,
       result,
       debugMessages,
-      ...(this.includesRequestData(context, input)
-        ? { resourceData: input.preData }
-        : {}),
       resourceBefore: { data: prior, exists: prior !== null },
       origin: context.origin,
       groupId: context.groupId,
-      ...(context.bypassRules ? { detail: { admin: true } } : {}),
-      ...(context.provenance ? { provenance: context.provenance } : {}),
     };
+    const includesData = this.includesRequestData(context, input);
+    if (includesData) request.resourceData = input.preData;
+    const bypassesRules = context.bypassRules === true;
+    if (bypassesRules) request.detail = { admin: true };
+    const hasProvenance = context.provenance !== undefined;
+    if (hasProvenance) request.provenance = context.provenance;
+    return request;
   }
 
   private includesRequestData(

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

@@ -4,7 +4,7 @@ import type {
   BatchResult,
   Operation,
 } from './writes.js';
-import { AtomicWritePipeline } from './atomic-write-pipeline.js';
+import { AtomicWritePipeline, type AtomicRuleMethod } from './atomic-write-pipeline.js';
 import { WriteRuntime } from './write-runtime.js';
 
 /** Adapts batch inputs and result history to the shared atomic-write pipeline. */
@@ -22,11 +22,18 @@ export class BatchWriteExecutor {
   ): BatchResult {
     const snapshot = this.runtime.capturePriors(operations.map((operation) => operation.path));
     const groupId = `batch-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-    const inputs = operations.map((operation) => ({
-      ...operation,
-      ruleMethod: operation.method,
-      preData: operation.data,
-    }));
+    const inputs = operations.map((operation) => {
+      const { method } = operation;
+      const isReplacement = method === 'set';
+      let ruleMethod: AtomicRuleMethod;
+      if (isReplacement) {
+        const documentExists = snapshot[operation.path] !== null;
+        ruleMethod = documentExists ? 'update' : 'create';
+      } else {
+        ruleMethod = method;
+      }
+      return { ...operation, ruleMethod, preData: operation.data };
+    });
     const prepared = this.pipeline.prepare(inputs, {
       origin: 'batch',
       groupId,
@@ -35,12 +42,15 @@ export class BatchWriteExecutor {
       snapshot,
     });
 
-    if (!('resolvedOps' in prepared)) {
+    const hasAuth = auth !== null;
+    const eventAuth = hasAuth ? { uid: auth.uid } : null;
+    const preparationFailed = !('resolvedOps' in prepared);
+    if (preparationFailed) {
       const event = this.runtime.eventLog.append({
         type: 'batch',
         method: 'batch',
         path: '',
-        auth: auth ? { uid: auth.uid } : null,
+        auth: eventAuth,
         allowed: false,
         operations: operations.map((operation) => ({
           method: operation.method,
@@ -49,61 +59,73 @@ export class BatchWriteExecutor {
           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,
-        results: operations.map((operation) => ({
-          path: operation.path,
-          allowed: false,
-          debugMessages: [prepared.message],
-          ...(operation.path === prepared.input.path ? { error: prepared.error } : {}),
-        })),
+        results: operations.map((operation) => {
+          const result: BatchResult['results'][number] = {
+            path: operation.path,
+            allowed: false,
+            debugMessages: [prepared.message],
+          };
+          const isFailedPath = operation.path === prepared.input.path;
+          if (isFailedPath) result.error = prepared.error;
+          return result;
+        }),
         event,
         error: prepared.error,
       };
     }
 
     const decision = this.pipeline.evaluateAndApply(prepared);
-    const results: BatchResult['results'] = decision.outcomes.map((outcome) => ({
-      path: outcome.path,
-      allowed: outcome.allowed,
-      debugMessages: outcome.debugMessages,
-      ...(outcome.error ? { error: outcome.error } : {}),
-    }));
+    const results = decision.outcomes.map((outcome) => {
+      const result: BatchResult['results'][number] = {
+        path: outcome.path,
+        allowed: outcome.allowed,
+        debugMessages: outcome.debugMessages,
+      };
+      const hasError = outcome.error !== undefined;
+      if (hasError) result.error = outcome.error;
+      return result;
+    });
+    const { allowed } = decision;
     const event = this.runtime.eventLog.append({
       type: 'batch',
       method: 'batch',
       path: '',
-      auth: auth ? { uid: auth.uid } : null,
-      allowed: decision.allowed,
-      priorDocs: decision.allowed ? snapshot : undefined,
+      auth: eventAuth,
+      allowed,
+      priorDocs: allowed ? snapshot : undefined,
       operations: decision.resolvedOps.map((operation, index) => ({
         method: operation.method,
         path: operation.path,
         data: operation.data,
         allowed: results[index]?.allowed ?? false,
       })),
-      debugMessages: decision.allowed
+      debugMessages: allowed
         ? ['Batch committed']
         : ['Batch 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 ??
         results.find((result) => result.error)?.error ??
         makeError('permission-denied', 'Batch denied');
     }
-    return {
-      allowed: decision.allowed,
+    const result: BatchResult = {
+      allowed,
       results,
       event,
-      ...(topError ? { error: topError } : {}),
     };
+    const hasTopError = topError !== undefined;
+    if (hasTopError) result.error = topError;
+    return result;
   }
 }

package/src/firestore/sandbox/converters/user-timestamp.ts

@@ -1,45 +1,11 @@
 /**
- * User-Timestamp write-boundary converter (FS-B4).
+ * Normalize SDK and decoded Timestamp values at the Firestore write boundary.
+ * Firestore stores microsecond precision; rules must inspect that same value
+ * before deciding whether a write is allowed. Preserve the caller's object.
  *
- * Unifies Timestamp storage. The simulator stores resolved timestamps as
- * rules-internal {@link Timestamp} (`pyric/rules`, `{seconds, nanos}`,
- * carrying evaluator hooks). The `serverTimestamp()` sentinel and `Date`
- * inputs already resolve to that internal class (see `timestamp.ts`). But
- * a timestamp the user *writes directly* — via the modular SDK's
- * `Timestamp` (the admin-compat `{seconds, nanoseconds}` class re-exported
- * as `Timestamp` from `pyric/firestore`) or a raw `firebase/firestore`
- * `Timestamp` — has no converter, so it lands in storage as the compat
- * class instance. Two problems with that split storage:
- *
- *   1. The rules evaluator detects timestamps via `value instanceof
- *      RulesValue && typeName === 'timestamp'`. A compat `Timestamp` is
- *      neither, so `data.createdAt is timestamp` returns false — a user
- *      `Timestamp` is rejected by the very `is timestamp` rule that a
- *      `serverTimestamp()` write passes.
- *   2. Range filters / cursors / `orderBy` compare against stored values.
- *      The FS-B3 comparator was taught both timestamp shapes, so ordering
- *      mostly works — but the read-path translator only rewrites the
- *      internal class to compat shape, so a user-written compat Timestamp
- *      never gets the `nanos`→`nanoseconds` normalization round-trip and
- *      `serverTimestamp()`-written and user-written timestamps live as two
- *      different classes in the same collection. Normalizing both to the
- *      internal class at the write boundary collapses the split.
- *
- * Detection strategy — duck typing on the compat / `firebase/firestore`
- * Timestamp shape, exactly like {@link bytesConverter} /
- * {@link geoPointConverter}:
- *   - numeric `seconds`
- *   - numeric `nanoseconds`  (the compat / fb field name — distinct from
- *     the internal class's `nanos`, which is how we reject our own output)
- *   - method `toMillis`
- *
- * We deliberately don't `instanceof fb.Timestamp` — the simulator package
- * must not take a hard dependency on `firebase/firestore`, and multiple
- * `firebase` copies in a workspace would defeat `instanceof` anyway.
- *
- * Idempotency: the internal {@link Timestamp} has `nanos`, not
- * `nanoseconds`, and `value instanceof RulesTimestamp` short-circuits
- * first — so a second resolver pass over our own output is a no-op.
+ * Decoded rules wrappers already at storage precision are left alone, making
+ * repeated write preparation idempotent. The SDK shape is recognized without
+ * a Firebase dependency, including instances from a separately installed SDK.
  */
 import { KEEP, type ValueConverter } from '../value-resolver.js';
 import { Timestamp as RulesTimestamp } from 'pyric/rules/internal';
@@ -66,7 +32,18 @@ function isUserTimestamp(v: unknown): v is UserTimestampLike {
 export const userTimestampConverter: ValueConverter = {
   name: 'user-timestamp-to-rules-timestamp',
   convert(value) {
-    if (!isUserTimestamp(value)) return KEEP;
-    return new RulesTimestamp(value.seconds, value.nanoseconds);
+    const isRulesTimestamp = value instanceof RulesTimestamp;
+    if (isRulesTimestamp) {
+      const nanoseconds = Math.floor(value.nanos / 1_000) * 1_000;
+      const hasMicrosecondPrecision = nanoseconds === value.nanos;
+      if (hasMicrosecondPrecision) return KEEP;
+      return new RulesTimestamp(value.seconds, nanoseconds);
+    }
+    const isSdkTimestamp = isUserTimestamp(value);
+    if (isSdkTimestamp) {
+      const nanoseconds = Math.floor(value.nanoseconds / 1_000) * 1_000;
+      return new RulesTimestamp(value.seconds, nanoseconds);
+    }
+    return KEEP;
   },
 };

package/src/firestore/sandbox/document-copy.ts

@@ -0,0 +1,27 @@
+import type { DocumentData } from './document-store.js';
+import { isPlainObject } from './value-resolver.js';
+import { Timestamp } from '../timestamp.js';
+import { registeredReferenceQueryValuePath } from './query-value-registry.js';
+
+/** Copy document inputs, validating Dates without resolving write transforms. */
+export function cloneDoc(data: DocumentData): DocumentData {
+  const copy: DocumentData = {};
+  for (const [field, value] of Object.entries(data)) {
+    copy[field] = cloneValue(value);
+  }
+  return copy;
+}
+
+function cloneValue(value: unknown): unknown {
+  const isDate = value instanceof Date;
+  if (isDate) return Timestamp.fromDate(value).toDate();
+  const isArray = Array.isArray(value);
+  if (isArray) return value.map(cloneValue);
+  const isMap = isPlainObject(value);
+  if (isMap) {
+    const isReference = registeredReferenceQueryValuePath(value) !== undefined;
+    if (isReference) return value;
+    return cloneDoc(value);
+  }
+  return value;
+}