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

package/src/firestore/sandbox/rules-list-authorizer.ts

@@ -1,3 +1,6 @@
+import { queryExecutionDiagnostic, type QueryExecutionSpec } from './query-execution.js';
+import type { EvaluatedRuleInfo } from 'pyric/rules/internal';
+import type { QueryProofDiagnostic } from '../../sandbox/types/query-proof.js';
 import type {
   SimulateFirestoreRulesHandler,
   TestCase,
@@ -23,6 +26,7 @@ import type { RulesState } from './rules-state.js';
 import { buildRulesTestCase } from './rules-test-case.js';
 import type { TriggerInfo } from './trigger-scope.js';
 import type { Operation } from './writes.js';
+import { SandboxClock } from '../../sandbox/clock.js';
 
 export interface RulesListAuthorizerHost {
   readonly state: DocStore;
@@ -37,6 +41,7 @@ export interface ListAuthorizationRequest {
   origin: 'listener' | 'user';
   bypassRules?: boolean;
   activityQuery?: unknown;
+  execution?: QueryExecutionSpec;
   triggeredBy?: TriggerInfo;
   /** Preserve the established request.time → event.at capture order. */
   timing?: { requestTime?: Timestamp; at: number };
@@ -56,6 +61,9 @@ export class RulesListAuthorizer {
     private readonly rules: RulesState,
     private readonly simulator: SimulateFirestoreRulesHandler,
     private readonly host: RulesListAuthorizerHost,
+    /** The sandbox's clock, read for every server-set time this produces.
+     *  Defaults to a private wall clock for a standalone construction. */
+    private readonly clock: SandboxClock = new SandboxClock(),
   ) {}
 
   authorize(request: ListAuthorizationRequest): ListAuthorizationResult {
@@ -68,9 +76,9 @@ export class RulesListAuthorizer {
     };
     const detail = Object.keys(requestDetail).length > 0 ? requestDetail : undefined;
     const requestTime = request.timing?.requestTime ?? (
-      request.bypassRules ? undefined : Timestamp.fromMillis(Date.now())
+      request.bypassRules ? undefined : Timestamp.fromMillis(this.clock.now())
     );
-    const evalAt = request.timing?.at ?? Date.now();
+    const evalAt = request.timing?.at ?? this.clock.now();
 
     if (request.bypassRules) {
       this.emitRequest({
@@ -123,64 +131,7 @@ export class RulesListAuthorizer {
     const proof = proveListQuery(evaluationAst, placeholderPath, auth, constraints, this.rules.source);
     const isUnprovable = proof.kind === 'unprovable';
     if (isUnprovable) {
-      const message =
-        `list ${path} denied: the query is statically unprovable for every possible ` +
-        `result (rules are not filters), so the whole query is rejected — ${proof.reason}`;
-      const remediation = renderQueryRemediation(proof.residual);
-      const reqEvent: {
-        at: number;
-        evalMs: number;
-        method: 'list';
-        path: string;
-        auth: any;
-        result: 'deny';
-        debugMessages: string[];
-        origin: any;
-        detail?: unknown;
-        triggeredBy?: unknown;
-      } = {
-        at: evalAt,
-        evalMs: performance.now() - evalStart,
-        method: 'list',
-        path,
-        auth,
-        result: 'deny',
-        debugMessages: [message],
-        origin,
-      };
-      const hasDetail = detail !== undefined;
-      if (hasDetail) {
-        reqEvent.detail = detail;
-      }
-      const hasTriggeredBy = triggeredBy !== undefined;
-      if (hasTriggeredBy) {
-        reqEvent.triggeredBy = triggeredBy;
-      }
-      this.emitRequest(reqEvent as any);
-
-      const errExtras: {
-        request: { method: 'list'; path: string; auth: any };
-        query: any;
-        remediation?: string;
-        rule?: any;
-      } = {
-        request: { method: 'list', path, auth },
-        query: constraints,
-      };
-      const isRemediationDefined = remediation !== undefined;
-      if (isRemediationDefined) {
-        const isRemediationNotEmpty = remediation !== '';
-        if (isRemediationNotEmpty) {
-          errExtras.remediation = remediation;
-        }
-      }
-      const hasProofRule = proof.rule !== undefined;
-      if (hasProofRule) {
-        errExtras.rule = proof.rule;
-      }
-      const error = makeError('permission-denied', message, errExtras as any);
-      this.emitUserDenial(origin, error);
-      return { allowed: false, error };
+      return this.denyQuery(request, proof, evalAt, performance.now() - evalStart, detail);
     }
 
     const evaluationSource = proof.kind === 'provable'
@@ -221,6 +172,7 @@ export class RulesListAuthorizer {
     }
 
     const result = simulation.data.results[0]!;
+    const rulesEvidence = this.rules.captureEvidence(result, 'query-residual');
     const debugMessages = renderLegacyDebugMessages(result);
     if (result.state === 'UNSUPPORTED') {
       this.emitRequest({
@@ -230,6 +182,7 @@ export class RulesListAuthorizer {
         path,
         auth,
         result: 'unsupported',
+        rulesEvidence,
         debugMessages,
         origin,
         ...(detail ? { detail } : {}),
@@ -245,53 +198,8 @@ export class RulesListAuthorizer {
 
     const isNotPassed = result.state !== 'PASSED';
     if (isNotPassed) {
-      const evalRule = projectEvaluatedRule(result);
-      const reqEvent: {
-        at: number;
-        evalMs: number;
-        method: 'list';
-        path: string;
-        auth: any;
-        result: 'deny';
-        debugMessages: string[];
-        evaluatedRule?: unknown;
-        origin: any;
-        detail?: unknown;
-        triggeredBy?: unknown;
-      } = {
-        at: evalAt,
-        evalMs,
-        method: 'list',
-        path,
-        auth,
-        result: 'deny',
-        debugMessages,
-        evaluatedRule: evalRule,
-        origin,
-      };
-      const hasDetail = detail !== undefined;
-      if (hasDetail) {
-        reqEvent.detail = detail;
-      }
-      const hasTriggeredBy = triggeredBy !== undefined;
-      if (hasTriggeredBy) {
-        reqEvent.triggeredBy = triggeredBy;
-      }
-      this.emitRequest(reqEvent as any);
-
-      const errExtras: {
-        request: { method: 'list'; path: string; auth: any };
-        rule?: unknown;
-      } = {
-        request: { method: 'list', path, auth },
-      };
-      const hasRule = evalRule !== undefined;
-      if (hasRule) {
-        errExtras.rule = evalRule;
-      }
-      const error = makeError('permission-denied', `list ${path} denied by rules`, errExtras as any);
-      this.emitUserDenial(origin, error);
-      return { allowed: false, error };
+      return this.denyQuery(request, proof, evalAt, evalMs, detail,
+         { reasons: debugMessages, rule: projectEvaluatedRule(result), evidence: rulesEvidence });
     }
 
     this.emitRequest({
@@ -303,6 +211,7 @@ export class RulesListAuthorizer {
       result: 'allow',
       debugMessages,
       evaluatedRule: projectEvaluatedRule(result),
+      rulesEvidence,
       origin,
       ...(detail ? { detail } : {}),
       ...(triggeredBy ? { triggeredBy } : {}),
@@ -310,6 +219,52 @@ export class RulesListAuthorizer {
     return { allowed: true };
   }
 
+  /** Combine local proof failures with actual residual evaluation, without
+   * ever putting rejected rules back into the authorization AST. */
+  private denyQuery(
+    request: ListAuthorizationRequest,
+    proof: ListProofVerdict,
+    at: number,
+    evalMs: number,
+    detail: EmitRequestInput['detail'],
+    residual: { reasons: string[]; rule?: EvaluatedRuleInfo; evidence?: EmitRequestInput['rulesEvidence'] } = { reasons: [] },
+  ): ListAuthorizationResult {
+    const { reasons: residualReasons, rule: evaluatedRule } = residual;
+    const failures = proof.kind === 'no-rule' ? [] : proof.failures;
+    const primary = failures.find(failure => failure.kind !== 'constraints-not-satisfied') ?? failures[0];
+    const queryProof: QueryProofDiagnostic = {
+      kind: primary?.kind ?? (proof.kind === 'no-rule' ? 'no-rule' : 'residual-denied'),
+      failures,
+      query: request.activityQuery ?? (request.execution ? queryExecutionDiagnostic(request.execution) : undefined),
+    };
+    const message = primary
+      ? `list ${request.path} denied: Pyric found the query statically unprovable — ${primary.reason}`
+      : `list ${request.path} denied by rules`;
+    // The projected AST can have empty match blocks. Its no-allow summary
+    // does not describe the deployed ruleset when proof rejected siblings.
+    const reasons = primary
+      ? [message, ...residualReasons.filter(reason => !reason.startsWith('No allow rules found'))]
+      : residualReasons;
+    const remediation = primary ? renderQueryRemediation(primary.residual) : undefined;
+    const error = makeError('permission-denied', message, {
+      request: { method: 'list', path: request.path, auth: request.auth },
+      query: request.constraints,
+      queryProof,
+      ...(remediation ? { remediation } : {}),
+      ...(primary?.rule || evaluatedRule ? { rule: primary?.rule ?? evaluatedRule } : {}),
+    });
+    this.emitRequest({
+      at, evalMs, method: 'list', path: request.path, auth: request.auth,
+      result: 'deny', debugMessages: reasons, queryProof, rulesEvidence: this.rules.captureQueryEvidence(queryProof, residual.evidence),
+      ...(evaluatedRule ? { evaluatedRule } : {}),
+      origin: request.origin,
+      ...(detail ? { detail } : {}),
+      ...(request.triggeredBy ? { triggeredBy: request.triggeredBy } : {}),
+    });
+    this.emitUserDenial(request.origin, error);
+    return { allowed: false, error };
+  }
+
   private applyProof(
     testCase: TestCase,
     proof: Exclude<ListProofVerdict, { kind: 'unprovable' }>,

package/src/firestore/sandbox/rules-operation-reader.ts

@@ -17,6 +17,7 @@ import {
 import { buildRulesTestCase } from './rules-test-case.js';
 import { EventLog } from './event-log.js';
 import { simulateRules } from './rules-simulator.js';
+import { SandboxClock } from '../../sandbox/clock.js';
 
 interface RulesOperationReaderHost {
   readonly state: DocStore;
@@ -30,6 +31,9 @@ export class RulesOperationReader {
     private readonly simulator: SimulateFirestoreRulesHandler,
     private readonly host: RulesOperationReaderHost,
     private readonly eventLog: EventLog,
+    /** The sandbox's clock, read for every server-set time this produces.
+     *  Defaults to a private wall clock for a standalone construction. */
+    private readonly clock: SandboxClock = new SandboxClock(),
   ) {}
 
   private get state(): DocStore {
@@ -55,10 +59,10 @@ export class RulesOperationReader {
     // No data to resolve on reads, but still pin a serverTime so the
     // handler's `request.time` is deterministic relative to anything
     // observed by debug messages (Item 1).
-    const readServerTime = Timestamp.fromMillis(Date.now());
+    const readServerTime = Timestamp.fromMillis(this.clock.now());
     const testCase = buildRulesTestCase(this.state, operation, readServerTime);
-    // Issue #307 — time the simulate call for RequestEvent.evalMs.
-    const evalAt = Date.now();
+    // Time the simulate call for RequestEvent.evalMs.
+    const evalAt = this.clock.now();
     const evalStart = performance.now();
     const simResult = simulateRules(
       this.state,
@@ -99,13 +103,14 @@ export class RulesOperationReader {
     }
 
     const result = simResult.data.results[0];
+    const rulesEvidence = this.rules.captureEvidence(result);
     const isUnsupported = result.state === 'UNSUPPORTED';
     if (isUnsupported) {
       // Issue #307 — surface the eval-time event BEFORE throwing so
       // subscribers see the unsupported request alongside everything else.
       const unsupReqEvent: any = {
         at: evalAt, evalMs, method, path, auth, result: 'unsupported',
-        debugMessages: renderLegacyDebugMessages(result), origin: 'user',
+        rulesEvidence, debugMessages: renderLegacyDebugMessages(result), origin: 'user',
       };
       const hasDetail = detail !== undefined;
       if (hasDetail) {
@@ -192,6 +197,7 @@ export class RulesOperationReader {
       result: 'allow' | 'deny';
       debugMessages: string[];
       evaluatedRule?: unknown;
+      rulesEvidence: import('../../sandbox/types/rules-evidence.js').RulesEvidence;
       origin: 'user';
       resourceBefore?: { data: DocumentData | null; exists: boolean };
       detail?: unknown;
@@ -200,6 +206,7 @@ export class RulesOperationReader {
       result: resultStr,
       debugMessages: renderLegacyDebugMessages(result),
       evaluatedRule: evalRule,
+      rulesEvidence,
       origin: 'user',
     };
     const isEventGet = method === 'get';

package/src/firestore/sandbox/rules-read-engine.ts

@@ -48,6 +48,7 @@ import {
   type RunQueryRequest,
   type RunQueryResult,
 } from './query-execution.js';
+import { SandboxClock } from '../../sandbox/clock.js';
 
 /**
  * The engine capability read paths need from the facade. `state` is a live
@@ -68,6 +69,9 @@ export class RulesReadEngine implements ListenerDispatchHost {
     private readonly simulator: SimulateFirestoreRulesHandler,
     private readonly host: RulesReadHost,
     eventLog: EventLog,
+    /** The sandbox's clock, read for every server-set time this produces.
+     *  Defaults to a private wall clock for a standalone construction. */
+    private readonly clock: SandboxClock = new SandboxClock(),
   ) {
     this.operationReader = new RulesOperationReader(
       events,
@@ -75,8 +79,9 @@ export class RulesReadEngine implements ListenerDispatchHost {
       simulator,
       host,
       eventLog,
+      clock,
     );
-    this.listAuthorizer = new RulesListAuthorizer(events, rules, simulator, host);
+    this.listAuthorizer = new RulesListAuthorizer(events, rules, simulator, host, clock);
   }
 
   private get state(): DocStore {
@@ -110,7 +115,7 @@ export class RulesReadEngine implements ListenerDispatchHost {
     if (bypassRules) {
       const data = this.state.get(path);
       this.emitRequest({
-        at: Date.now(),
+        at: this.clock.now(),
         evalMs: 0,
         method: 'get',
         path,
@@ -124,10 +129,10 @@ export class RulesReadEngine implements ListenerDispatchHost {
       });
       return { allowed: true, data };
     }
-    const readServerTime = Timestamp.fromMillis(Date.now());
+    const readServerTime = Timestamp.fromMillis(this.clock.now());
     const testCase = buildRulesTestCase(this.state, { method: 'get', path, auth }, readServerTime);
-    // Issue #307 — time the simulate call for listener-origin RequestEvents.
-    const evalAt = Date.now();
+    // Time the simulate call for listener-origin RequestEvents.
+    const evalAt = this.clock.now();
     const evalStart = performance.now();
     const simResult = this.simulator.simulate(this.rules.source, [testCase], {
       getDoc: (path) => this.state.get(path),
@@ -148,10 +153,11 @@ export class RulesReadEngine implements ListenerDispatchHost {
       };
     }
     const result = simResult.data.results[0]!;
+    const rulesEvidence = this.rules.captureEvidence(result);
     if (result.state === 'UNSUPPORTED') {
       this.emitRequest({
         at: evalAt, evalMs, method: 'get', path, auth, result: 'unsupported',
-        debugMessages: renderLegacyDebugMessages(result), origin: 'listener',
+        rulesEvidence, debugMessages: renderLegacyDebugMessages(result), origin: 'listener',
         ...(this.triggerScope.current() ? { triggeredBy: this.triggerScope.current() } : {}),
       });
       throw new SimulatorUnsupportedError(
@@ -176,6 +182,7 @@ export class RulesReadEngine implements ListenerDispatchHost {
       result: 'allow' | 'deny';
       debugMessages: string[];
       evaluatedRule?: unknown;
+      rulesEvidence: import('../../sandbox/types/rules-evidence.js').RulesEvidence;
       origin: 'listener';
       resourceBefore: { data: Record<string, unknown> | null; exists: boolean };
       triggeredBy?: unknown;
@@ -188,6 +195,7 @@ export class RulesReadEngine implements ListenerDispatchHost {
       result: resultStr,
       debugMessages: renderLegacyDebugMessages(result),
       evaluatedRule: evalRule,
+      rulesEvidence,
       origin: 'listener',
       resourceBefore: { data, exists: isDataNotNull },
     };
@@ -264,8 +272,8 @@ export class RulesReadEngine implements ListenerDispatchHost {
       ? queryConstraintsForProof(execution)
       : {};
     const timing = {
-      requestTime: Timestamp.fromMillis(Date.now()),
-      at: Date.now(),
+      requestTime: Timestamp.fromMillis(this.clock.now()),
+      at: this.clock.now(),
     };
     const triggeredBy = this.triggerScope.current();
     if (bypassRules) {
@@ -279,6 +287,7 @@ export class RulesReadEngine implements ListenerDispatchHost {
         constraints: structured,
         bypassRules,
         ...(constraints?.activityQuery ? { activityQuery: constraints.activityQuery } : {}),
+        execution,
         origin: 'listener',
         ...(triggeredBy ? { triggeredBy } : {}),
         timing,
@@ -291,6 +300,7 @@ export class RulesReadEngine implements ListenerDispatchHost {
       auth,
       constraints: structured,
       ...(constraints?.activityQuery ? { activityQuery: constraints.activityQuery } : {}),
+      execution,
       origin: 'listener',
       ...(triggeredBy ? { triggeredBy } : {}),
       timing,
@@ -350,6 +360,7 @@ export class RulesReadEngine implements ListenerDispatchHost {
       constraints: proof,
       bypassRules,
       ...(activityQuery !== undefined ? { activityQuery } : {}),
+      execution,
       origin: 'user',
     });
     if (!authorization.allowed) return authorization;

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

@@ -16,7 +16,27 @@
  */
 import { parseToAST, type FirestoreRules } from 'pyric/rules/internal';
 
+import type { TestResult } from 'pyric/rules/internal';
+import { captureRulesEvidence, captureQueryEvidence } from './rules-evidence.js';
+import type { RulesEvidence } from '../../sandbox/types/rules-evidence.js';
+
+// Diagnostic identity only; rules evaluation also works outside secure contexts.
+function rulesVersion(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  return `rules-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
 export class RulesState {
+  private version = rulesVersion();
+
+  captureEvidence(result: TestResult, scope: RulesEvidence['scope'] = 'request'): RulesEvidence {
+    return captureRulesEvidence(result, this.version, scope);
+  }
+
+  captureQueryEvidence(proof: import('../../sandbox/types/query-proof.js').QueryProofDiagnostic, residual?: RulesEvidence): RulesEvidence {
+    return captureQueryEvidence(proof, this.version, residual);
+  }
+
   private currentSource: string;
 
   /**
@@ -42,6 +62,7 @@ export class RulesState {
    * cached AST warm.
    */
   set(source: string): void {
+    if (this.currentSource !== source) this.version = rulesVersion();
     this.currentSource = source;
   }
 

package/src/firestore/sandbox/snapshot-listeners.ts

@@ -11,6 +11,10 @@
  * section 4, section 5).
  */
 import type { DocumentData } from './local-state.js';
+import type {
+  ListenerOwnerHint,
+  RecordedListenerOwners,
+} from '../../sandbox/attribution/listener-owners.js';
 import type { Operation } from './local-environment.js';
 // FS-B10 — translate the listener read path so `snap.data()` exposes the
 // SAME compat-shaped values (`Timestamp` `{seconds, nanoseconds}`, `Bytes`,
@@ -80,9 +84,16 @@ export type SnapshotTarget =
  * `LocalEnvironment.notifyDocListener` / `notifyQueryListener`. `fromCache`
  * remains constant `false` — the sandbox has no offline cache to serve from.
  */
-export interface SnapshotListenerOptions {
+export interface SnapshotListenerOptions extends RecordedListenerOwners {
   includeMetadataChanges?: boolean;
   source?: 'default' | 'cache';
+  /**
+   * Pyric's own extension, absent from the Firebase Web SDK: who owns this
+   * listener. A name, or the DOM element the listener feeds. Recorded as a
+   * `tag` owner on the `listener_attach` event and nowhere else. It changes
+   * nothing about what the listener delivers.
+   */
+  owner?: ListenerOwnerHint;
 }
 
 /**

package/src/firestore/sandbox/transaction-merge.ts

@@ -1,16 +1,17 @@
 /**
- * Item 1.3 — Same-path queued-write collapse.
+ * Legacy same-path queued-write collapse for sandbox/internal callers.
  *
- * `TransactionContext` queues writes append-only (Item 1.2). Before
- * commit, ops at the same path collapse into a single operation so the
- * existing `LocalState.applyBatch` can run rules-eval + apply atomically
- * without per-call divergence.
+ * Transaction execution no longer uses this reducer: the shared atomic
+ * pipeline resolves its append-only queue in order. This exported helper
+ * retains its earlier contract and does not implement general field-mask
+ * or transform composition.
  *
  * Probe 0.D verified `update + update` merges fields (last-wins per
  * field, earlier-but-non-overlapping fields preserved). The other
  * combinations are extrapolated from Admin SDK semantics:
  *
- *   set    + set        → second `set` wins (overwrite semantics).
+ *   set    + set        → second non-merge `set` wins (overwrite semantics).
+ *   set    + set(merge) → merge the next payload while retaining prior intent.
  *   set    + update     → `set` with `{ ...set.data, ...update.data }`.
  *   set    + delete     → `delete` wins (the set never observable).
  *   create + update     → `create` with `{ ...create.data, ...update.data }`.
@@ -24,13 +25,15 @@
  *                         than guess. Decisions Log: "delete + write
  *                         merge unprobed; v1 throws ambiguous".
  *
- * Output is `LocalState.BatchOperation[]` directly — that's what the
- * commit path (Item 2) feeds into `applyBatch`. Same-path entries
+ * Output retains `BatchOperationInput` intent for the atomic pipeline
+ * to resolve before storage. Same-path entries
  * collapse into one entry; different paths preserve order of first
  * appearance (insertion order in the path map).
  */
-import type { BatchOperation, DocumentData } from './local-state.js';
+import type { DocumentData } from './local-state.js';
+import type { BatchOperationInput } from './writes.js';
 import type { QueuedWrite } from './transaction-types.js';
+import { applyMerge } from './field-merge.js';
 
 /**
  * Thrown when the queue contains a `delete` followed by another write
@@ -63,19 +66,21 @@ export class AmbiguousPostDeleteWriteError extends Error {
  *   data) and folds in subsequent writes per the table above.
  * - Throws `AmbiguousPostDeleteWriteError` on `delete + anything`.
  */
-export function mergeQueuedWrites(writes: readonly QueuedWrite[]): BatchOperation[] {
+export function mergeQueuedWrites(writes: readonly QueuedWrite[]): BatchOperationInput[] {
   // Insertion-ordered map keeps the output stable for callers that
   // care about ordering across paths (none today, but cheap to preserve).
-  const byPath = new Map<string, BatchOperation>();
+  const byPath = new Map<string, BatchOperationInput>();
 
   for (const w of writes) {
     const prior = byPath.get(w.path);
-    if (prior === undefined) {
+    const isFirstWrite = prior === undefined;
+    if (isFirstWrite) {
       byPath.set(w.path, toBatchOp(w));
       continue;
     }
 
-    if (prior.method === 'delete') {
+    const followsDelete = prior.method === 'delete';
+    if (followsDelete) {
       throw new AmbiguousPostDeleteWriteError(w.path, w.method);
     }
 
@@ -86,34 +91,42 @@ export function mergeQueuedWrites(writes: readonly QueuedWrite[]): BatchOperatio
 }
 
 /** Convert a single queued write to its initial `BatchOperation` shape. */
-function toBatchOp(w: QueuedWrite): BatchOperation {
-  if (w.method === 'delete') {
+function toBatchOp(w: QueuedWrite): BatchOperationInput {
+  const isDelete = w.method === 'delete';
+  if (isDelete) {
     return { method: 'delete', path: w.path };
   }
   // set / create / update all carry data; queue invariant.
-  if (w.data === undefined) {
+  const hasNoData = w.data === undefined;
+  if (hasNoData) {
     throw new Error(
       `internal: queued ${w.method} on ${w.path} has no data — ` +
       `Transaction class invariant violated`,
     );
   }
-  return { method: w.method, path: w.path, data: w.data };
+  const operation: BatchOperationInput = { method: w.method, path: w.path, data: w.data };
+  const hasMerge = w.merge !== undefined;
+  if (hasMerge) operation.merge = w.merge;
+  return operation;
 }
 
 /**
  * Fold a new queued write into an existing same-path effective op.
  * Pre: `prior.method !== 'delete'` (caller checked).
  */
-function fold(prior: BatchOperation, next: QueuedWrite): BatchOperation {
+function fold(prior: BatchOperationInput, next: QueuedWrite): BatchOperationInput {
   switch (next.method) {
     case 'delete':
       // Anything-then-delete: final state is gone.
       return { method: 'delete', path: next.path };
 
     case 'set': {
-      // Anything-then-set: set replaces entirely. The earlier op is
-      // semantically erased (Admin's set is overwrite).
       const data = requireData(next);
+      const mergesFields = next.merge === true;
+      if (mergesFields) {
+        return { ...prior, data: applyMerge(prior.data ?? {}, data) };
+      }
+      // A set without merge replaces the earlier write entirely.
       return { method: 'set', path: next.path, data };
     }
 

package/src/firestore/sandbox/transaction-types.ts

@@ -9,19 +9,18 @@
  *   - 0.C: `tx.getAll(...paths)` returns snapshots in input order.
  *   - 0.A + 0.J: read-before-write ordering is GLOBAL — any write method
  *     flips a per-tx flag; subsequent reads throw `failed-precondition`.
- *   - 0.D: same-path multi-write merges on commit (last-wins per field).
- *     The merge happens at commit time in `transaction-merge.ts`; the
- *     queue here is append-only.
+ *   - 0.D: same-path writes resolve in queue order at commit. Results
+ *     summarize each path after execution; the queue is append-only.
  *   - 0.G: callback exceptions propagate unchanged. The result types
  *     here only describe the *successful* (or rule-denied) path; thrown
  *     errors don't construct a `TransactionResult`.
- *   - 0.H: no `retries` field. Single-threaded simulator can't trigger
- *     conflicts. Documented as a known limitation.
+ *   - Read conflicts retry the callback up to `maxAttempts`.
  */
 import type { DocumentData } from './local-state.js';
 import type { AgentEvent } from './event-log.js';
 import type { FirestoreSimError } from './errors.js';
 import type { EventProvenance } from '../../sandbox/types/events.js';
+import type { BatchOperationInput, Operation } from './writes.js';
 
 /**
  * Snapshot shape returned by `tx.get` / `tx.getAll`. Matches the Admin
@@ -50,24 +49,16 @@ export interface CapturedRead {
 }
 
 /**
- * Internal — a queued write before merge/commit. Carries the original
- * call method so `transaction-merge.ts` can collapse same-path entries
- * with the right semantics (`update + update` merges; `set + update`
- * applies update on top of set; etc.).
+ * Internal — a queued write before commit. Keeps the original method,
+ * data and mask until the shared atomic pipeline resolves it in order.
  */
-export interface QueuedWrite {
-  method: 'set' | 'create' | 'update' | 'delete';
-  path: string;
-  data?: DocumentData;
-}
+export type QueuedWrite = BatchOperationInput;
 
 /**
  * Caller surface for `Transaction`. Implementation lives in
  * `transaction.ts`; this interface is what callbacks see.
  *
- * `set` is included even though `BatchOperationInput` doesn't expose
- * it — the Admin SDK's transaction does, and the merge layer collapses
- * `set` into the appropriate `BatchOperation` at commit.
+ * The queued writes retain the same intent as batch inputs until commit.
  */
 export interface Transaction {
   /** Admin-mode read; never evaluates rules. */
@@ -76,7 +67,7 @@ export interface Transaction {
   getAll(...paths: string[]): TransactionSnapshot[];
 
   /** Queue a `set` (overwrite-or-create). Flips writeStarted. */
-  set(path: string, data: DocumentData): void;
+  set(path: string, data: DocumentData, merge?: Operation['merge']): void;
   /** Queue a `create` (fail-on-exists at commit). Flips writeStarted. */
   create(path: string, data: DocumentData): void;
   /** Queue an `update` (fail-if-missing at commit). Flips writeStarted. */
@@ -122,9 +113,8 @@ export interface TransactionOptions {
  * violation) do NOT produce a `TransactionResult` — they propagate.
  *
  * `reads` is included for diagnostic value (production doesn't surface
- * this; we do). `writes` is one entry per *queued* write at the time
- * of commit, post-merge — so two `update` calls to the same path
- * produce one `writes[]` entry, not two.
+ * this; we do). `writes` summarizes each path after execution, so two
+ * `update` calls to the same path produce one `writes[]` entry.
  */
 export interface TransactionResult<R = unknown> {
   /** True iff every queued write passed rules and applied. */