@abloatai/humans 0.48.0 → 0.49.0

package/src/local/client/storeCluster.ts

@@ -38,6 +38,10 @@ import { registerModelsFromSchema } from './modelRegistration.js';
 import { deriveConfigFromSchema } from './schemaConfig.js';
 import { createDefaultMutationExecutor } from './wsMutationExecutor.js';
 import type { InternalAbloOptions } from './options.js';
+import {
+  createReadSetContext,
+  type ReadSetContext,
+} from '@abloatai/transaction/internal/read-set';
 export type { InternalAbloOptions } from './options.js';
 
 /**
@@ -55,6 +59,8 @@ export interface StoreCluster {
   readonly components: InternalComponents;
   /** The store orchestrating the graph, holding the host-built connection. */
   readonly store: BaseSyncedStore;
+  /** Client-local opaque evidence registry; never an ambient execution scope. */
+  readonly readSetContext: ReadSetContext;
 }
 
 /**
@@ -99,6 +105,7 @@ export function buildStoreCluster(
     return null;
   }
   const schema = options.schema;
+  const readSetContext = createReadSetContext();
 
   // Config derives from the schema; caller-supplied overrides layer on top,
   // caller winning per key.
@@ -112,7 +119,10 @@ export function buildStoreCluster(
   // error and the MutationQueue owns the retry. A caller-supplied executor
   // still wins (test mocks, alternative transports).
   const executor: MutationExecutor =
-    options.mutationExecutor ?? createDefaultMutationExecutor(() => transport);
+    options.mutationExecutor ?? createDefaultMutationExecutor(
+      () => transport,
+      readSetContext,
+    );
 
   // This client's runtime — the instance the whole graph is constructed
   // with, so two clients in one process never read each other's logger,
@@ -168,5 +178,5 @@ export function buildStoreCluster(
     { collaborationEvents: options.collaborationEvents ?? [] },
   );
 
-  return { runtime, components, store };
+  return { runtime, components, store, readSetContext };
 }

package/src/local/client/storeLifecycle.ts

@@ -11,6 +11,7 @@
 
 import type { SchemaRecord, Schema } from '@abloatai/transaction/schema/schema';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { EffectiveAuthority } from '@abloatai/transaction/auth';
 import type { Logger } from '@abloatai/transaction/logger';
 import type { AuthCredentialSource } from '@abloatai/transaction/auth/credentialSource';
 import type { RefreshScheduler } from '@abloatai/transaction/auth';
@@ -32,6 +33,7 @@ export interface IdentitySeed {
   /** The resolved account scope; null until known. */
   readonly accountScope: string | null;
   readonly syncGroups: readonly string[];
+  readonly authority: EffectiveAuthority;
 }
 
 export interface StoreLifecycle {
@@ -282,6 +284,7 @@ export function startStoreLifecycle<S extends SchemaRecord>(
           participantKind,
           accountScope,
           syncGroups: resolvedSyncGroups,
+          authority: resolved.authority,
         });
 
         if (resolved.refreshScheduler) {

package/src/local/client/wsMutationExecutor.ts

@@ -12,6 +12,12 @@ import type {
   MutationOptions,
 } from '../interfaces/index.js';
 import type { CommitAck } from '../sync/commitFrames.js';
+import type { CommitReceiptWire } from '@abloatai/transaction/wire/commit';
+import {
+  recordWebSocketCommitReceipt,
+  type ReadSetContext,
+} from '@abloatai/transaction/internal/read-set';
+import { commitAckSchema } from '@abloatai/transaction/wire/commit';
 import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
 
 // ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
@@ -33,6 +39,13 @@ import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
  */
 	export function createDefaultMutationExecutor(
 	  getWs: () => {
+	    sendCommitReceipt?: (
+	      operations: readonly MutationOperation[],
+	      clientTxId: string,
+	      timeoutMs?: number,
+	      reads?: readonly ReadDependency[] | null,
+	      track?: readonly TrackDependency[] | null,
+	    ) => Promise<CommitReceiptWire>;
 	    sendCommit?: (
 	      operations: readonly MutationOperation[],
 	      clientTxId: string,
@@ -41,13 +54,14 @@ import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
 	      track?: readonly TrackDependency[] | null,
 	    ) => Promise<CommitAck>;
 	  } | null,
+	  readSetContext?: ReadSetContext,
 	): MutationExecutor {
 	  async function commit(
 	    operations: MutationOperation[],
 	    options?: MutationOptions,
 	  ) {
     const ws = getWs();
-    if (!ws?.sendCommit) {
+    if (!ws || (!ws.sendCommit && !ws.sendCommitReceipt)) {
       throw new AbloConnectionError(
         'SyncWebSocket not ready for commit. The engine must finish bootstrap ' +
           'before mutations can be sent.',
@@ -60,6 +74,34 @@ import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
 	        ? crypto.randomUUID()
 	        : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`);
 	    try {
+	      if (ws.sendCommitReceipt) {
+	        const receipt = await ws.sendCommitReceipt(
+	          operations,
+	          clientTxId,
+	          undefined,
+	          options?.reads,
+	          options?.track,
+	        );
+	        recordWebSocketCommitReceipt(readSetContext, {
+	          receipt,
+	          operations,
+	          reads: options?.reads,
+	          track: options?.track,
+	        });
+	        return commitAckSchema.parse({
+	          status: receipt.status,
+	          statusAt: receipt.statusAt,
+	          lastSyncId: receipt.lastSyncId,
+	          ...(receipt.correlationId ? { correlationId: receipt.correlationId } : {}),
+	          ...(receipt.notifications ? { notifications: receipt.notifications } : {}),
+	          ...(receipt.missingIds ? { missingIds: receipt.missingIds } : {}),
+	        });
+	      }
+	      if (!ws.sendCommit) {
+	        throw new AbloConnectionError('SyncWebSocket commit transport is unavailable.', {
+	          code: 'ws_not_ready',
+	        });
+	      }
 	      return await ws.sendCommit(
 	        operations,
 	        clientTxId,

package/src/local/context.ts

@@ -86,7 +86,11 @@ const _fallback: RuntimeContext = {
   config: emptyConfig,
   getModelMetadata: () => undefined,
   mutationExecutor: {
-    commit: () => Promise.resolve({ lastSyncId: 0, status: 'confirmed' as const }),
+    commit: () => Promise.resolve({
+      status: 'confirmed' as const,
+      statusAt: '1970-01-01T00:00:00.000Z',
+      lastSyncId: 0,
+    }),
     executeCreate: () => Promise.resolve(),
     executeUpdate: () => Promise.resolve(null),
     executeDelete: () => Promise.resolve(),

package/src/local/interfaces/index.ts

@@ -18,7 +18,7 @@ export type { CoordinationObservability } from '@abloatai/transaction/observabil
 // ─────────────────────────────────────────────
 
 // The logging port carries no framework and no local state, so it lives in the
-// settlement core (ADR 0016). Re-exported here so `interfaces` stays the single
+// confirmation core (ADR 0016). Re-exported here so `interfaces` stays the single
 // place a consumer looks for the contracts it implements. The `import type` is
 // load-bearing: `SyncLogger = Logger` below needs the name bound in this module.
 export type { Logger } from '@abloatai/transaction/logger';
@@ -29,7 +29,7 @@ import type { Logger } from '@abloatai/transaction/logger';
 // ─────────────────────────────────────────────
 
 // The transport-facing slice — breadcrumbs and socket errors — moved to the
-// settlement core with the duplex transport (ADR 0016): a socket held for
+// confirmation core with the duplex transport (ADR 0016): a socket held for
 // claim push must report its lifecycle with no store present. Re-exported
 // here so `interfaces` stays the single place a consumer looks; the `import
 // type` is load-bearing for `ObservabilityProvider extends` below.
@@ -143,7 +143,7 @@ export interface ObservabilityProvider
   captureSelfHealing(details: SelfHealingDetails): void;
 
   // `captureClaim` and `captureConflict` are inherited from
-  // `CoordinationObservability` in the core — the settlement layer reports those
+  // `CoordinationObservability` in the core — the confirmation layer reports those
   // two on its own behalf, with no store present.
 
   /** Capture commit returning lastSyncId: 0 */
@@ -225,7 +225,7 @@ export type MutationCommitResult = MutationCommitResultInput;
 // `MutationOptions` describes how a write is issued — request identity, commit
 // disposition, and the premise it rests on (optimistic via `readAt`/`reads`, or
 // claim-protected via `claimRef`/`fenceToken`) — and holds no local row state,
-// so it lives in the settlement core (ADR 0016). Re-exported here so the
+// so it lives in the confirmation core (ADR 0016). Re-exported here so the
 // existing `interfaces` import path keeps resolving.
 // The `import type` is load-bearing, not redundant: `export type { X } from`
 // re-exports without binding X in this module's scope, and `Pick<X, K>` on an
@@ -243,7 +243,7 @@ import type { MutationOptions } from '@abloatai/transaction/resources/mutationOp
  */
 export type WriteOptions = Pick<
   MutationOptions,
-  'readAt' | 'onStale' | 'idempotencyKey' | 'label' | 'fenceToken'
+  'readAt' | 'onStale' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'
 >;
 
 /** A single mutation within a batch. Its `options` travel with it so the server
@@ -265,6 +265,8 @@ export interface MutationOperation {
    * the wire at once.
    */
   transactionId?: string;
+  /** Server-issued claim identity the operation is attributed to. */
+  claimId?: string | null;
   readAt?: number | null;
   onStale?: OnStaleMode | null;
   /**

package/src/local/mutators/UndoManager.ts

@@ -365,7 +365,7 @@ export class UndoScope<S extends Schema> {
    * Run `work` after every previously-enqueued scope operation has settled,
    * in invocation order. The internal `tail` always resolves (failures are
    * swallowed *for the chain only*) so one rejected mutator can't wedge the
-   * queue; the original settlement is still surfaced to this call's caller.
+   * queue; the original confirmation is still surfaced to this call's caller.
    */
   private enqueue<T>(work: () => Promise<T>): Promise<T> {
     const result = this.tail.then(work, work);

package/src/local/query/client.ts

@@ -13,6 +13,7 @@
  */
 
 import { z } from 'zod';
+import { modelListEvidenceSchema } from '@abloatai/transaction/wire';
 import type { QueryBatch, QueryBatchResult } from './types.js';
 import { translateHttpError } from '@abloatai/transaction/errors';
 import { classifyRecovery, type RecoveryClass } from '@abloatai/transaction/errorCodes';
@@ -37,6 +38,16 @@ const QueryResultSchema = z
 const QueryBatchResultSchema = z
   .object({
     results: z.array(QueryResultSchema),
+    evidence: z.array(z.array(modelListEvidenceSchema)).optional(),
+    errors: z.array(z.object({
+      index: z.number().int().nonnegative(),
+      model: z.string(),
+      type: z.string(),
+      code: z.string(),
+      message: z.string(),
+      request_id: z.string().optional(),
+      event_id: z.string(),
+    })).optional(),
   })
   .loose();
 
@@ -189,6 +200,12 @@ export async function postQuery(
         });
         return { results: batch.queries.map(() => []) };
       }
+      for (const failure of parsed.data.errors ?? []) {
+        runtime.logger.warn(
+          `Could not load ${failure.model} — ${failure.message} (code: ${failure.code}, ref: ${failure.request_id ?? failure.event_id}). No results were returned for slot ${failure.index}.`,
+        );
+        runtime.logger.debug('[postQuery.error] query slot failure', failure);
+      }
       return parsed.data;
     } finally {
       clearTimeout(timer);

package/src/local/query/types.ts

@@ -15,7 +15,7 @@
  */
 
 // The where grammar describes the *request*, not any local copy of the rows it
-// returns, so it lives in the settlement core (ADR 0016). Re-exported here so
+// returns, so it lives in the confirmation core (ADR 0016). Re-exported here so
 // the existing `query/types` import path keeps resolving.
 export type {
   WherePrimitive,
@@ -24,6 +24,7 @@ export type {
   LoadWhere,
 } from '@abloatai/transaction/resources/where';
 import type { WhereClause } from '@abloatai/transaction/resources/where';
+import type { ModelListEvidence } from '@abloatai/transaction/wire';
 
 /** A single structured fetch request. */
 export interface Query {
@@ -93,6 +94,18 @@ export interface QueryBatchResult {
    * before use.
    */
   results: unknown[];
+  /** Per-result-slot evidence for the primary rows in that slot. */
+  evidence?: readonly (readonly QueryReadEvidence[])[];
+  /** Per-slot failures that previously looked identical to an empty result. */
+  errors?: readonly {
+    index: number;
+    model: string;
+    type: string;
+    code: string;
+    message: string;
+    request_id?: string;
+    event_id: string;
+  }[];
   /**
    * The server watermark observed after the batch ran. Model reads expose this
    * as `stamp`, and callers thread it into `commits.create({ readAt })` so the
@@ -100,3 +113,5 @@ export interface QueryBatchResult {
    */
   lastSyncId?: number;
 }
+
+export type QueryReadEvidence = ModelListEvidence;

package/src/local/stores/syncAction.ts

@@ -1,7 +1,7 @@
 /**
  * The persisted local action record consumed by `SyncActionStore`. It is a
  * client materialization artifact, not a transaction-layer wire shape: the
- * authoritative broadcast vocabulary is the settlement core's delta wire
+ * authoritative broadcast vocabulary is the confirmation core's delta wire
  * schema, while this one adds the local `__class` discriminator IndexedDB uses.
  */
 

package/src/local/sync/ConnectionManager.ts

@@ -1,5 +1,5 @@
 /**
- * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * Moved to the confirmation core with the duplex transport (ADR 0016): the
  * connection state machine is plain, mobx-free plumbing an agent needs as much
  * as a browser does. This path re-exports it so existing importers stay
  * unchanged; the reactive store mirrors its transitions through

package/src/local/sync/OnDemandLoader.ts

@@ -121,6 +121,7 @@ function snapshotDoesNotAdvanceModel(data: Record<string, unknown>, model: Model
 }
 
 export class OnDemandLoader {
+  private readonly readEvidence = new WeakMap<object, number>();
   private readonly inFlight = new Map<string, Promise<Model[]>>();
   /**
    * Query keys with a background confirm currently in flight. Distinct from
@@ -224,6 +225,11 @@ export class OnDemandLoader {
     return work;
   }
 
+  /** Exact evidence retained for a row returned by a server-confirmed fetch. */
+  getReadEvidence(row: object): number | undefined {
+    return this.readEvidence.get(row);
+  }
+
   private async runFetch(
     modelName: string,
     typename: string,
@@ -337,7 +343,8 @@ export class OnDemandLoader {
     clauses: readonly WhereClause[],
     options: FetchOptions<unknown> | undefined,
   ): Promise<Model[]> {
-    const networkRows = await this.queryNetwork(modelName, clauses, options);
+    const network = await this.queryNetwork(modelName, clauses, options);
+    const networkRows = network.rows;
     const networkModels = networkRows
       // Strict: a row the server returned whose type name this client never
       // registered is a genuine schema collision (the pushed schema differs
@@ -346,6 +353,12 @@ export class OnDemandLoader {
       .map((raw) => this.hydrateOne(raw, typename, { strict: true }))
       .filter((m): m is Model => m !== null);
 
+    const evidenceById = new Map(network.evidence.map((entry) => [entry.id, entry.stamp]));
+    for (const model of networkModels) {
+      const stamp = evidenceById.get(model.id);
+      if (stamp !== undefined) this.readEvidence.set(model, stamp);
+    }
+
     if (networkModels.length > 0) {
       this.opts.objectPool.addBatch(networkModels, ModelScope.live);
       // Background IDB write — don't block the caller. Expanded children are
@@ -558,7 +571,10 @@ export class OnDemandLoader {
     modelName: string,
     clauses: readonly WhereClause[],
     options: FetchOptions<unknown> | undefined,
-  ): Promise<unknown[]> {
+  ): Promise<{
+    rows: unknown[];
+    evidence: readonly { id: string; stamp: number }[];
+  }> {
     const typename = this.resolveTypename(modelName);
     const orderEntries = options?.orderBy ? Object.entries(options.orderBy) : [];
     const firstOrder = orderEntries[0];
@@ -586,6 +602,7 @@ export class OnDemandLoader {
       { queries: [query] },
     );
     const rows: unknown[] = Array.isArray(result.results[0]) ? result.results[0] : [];
+    const evidence = result.evidence?.[0] ?? [];
     // Normalize: wire rows lack `__typename` when the server elides it.
     const normalized = rows.map((row) => {
       if (row && typeof row === 'object' && !('__typename' in row)) {
@@ -605,7 +622,7 @@ export class OnDemandLoader {
     if (options?.expand && options.expand.length > 0) {
       this.hydrateExpanded(modelName, normalized, options.expand);
     }
-    return normalized;
+    return { rows: normalized, evidence };
   }
 
   /**

package/src/local/sync/SyncWebSocket.ts

@@ -1,5 +1,5 @@
 /**
- * The reactive engine's connection to the sync server: the settlement core's
+ * The reactive engine's connection to the sync server: the confirmation core's
  * duplex transport ({@link WsTransport}, ADR 0016) plus everything that turns
  * the stream into a local, watchable copy — wire-delta validation, the resume
  * cursor and its persistence-gated ack discipline, incremental sync and

package/src/local/sync/commitFrames.ts

@@ -1,5 +1,5 @@
 /**
- * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * Moved to the confirmation core with the duplex transport (ADR 0016): the
  * commit-path frame builders are stateless wire helpers. This path re-exports
  * them so existing importers stay unchanged. The core's `buildCommitFrame`
  * takes the structural `CommitFrameOperation` slice, which this package's

package/src/local/sync/contextPorts.ts

@@ -1,5 +1,5 @@
 /**
- * The runtime context, sliced into the ports the settlement core's transport
+ * The runtime context, sliced into the ports the confirmation core's transport
  * takes. The core is injected, never service-located (ADR 0016), while this
  * package resolves its shared dependencies through `getContext()` — so these
  * adapters bridge the two: each method reads the context at call time, which

package/src/local/sync/credentialLifecycle.ts

@@ -1,5 +1,5 @@
 /**
- * Moved to the settlement core with the duplex transport (ADR 0016): keeping
+ * Moved to the confirmation core with the duplex transport (ADR 0016): keeping
  * a long-lived socket's credential fresh is connection plumbing an agent needs
  * as much as a browser does. This path re-exports it so existing importers
  * stay unchanged.

package/src/local/sync/wsFrameHandlers.ts

@@ -1,5 +1,5 @@
 /**
- * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * Moved to the confirmation core with the duplex transport (ADR 0016): the
  * inbound frame dispatch is the receiving half of the wire protocol, and the
  * handlers already worked against the minimal `WsSession` port rather than
  * the transport object. This path re-exports it so existing importers stay

package/src/local/transactions/databaseCommitOutbox.ts

@@ -1,7 +1,7 @@
 import type {
   DurableWriteStore,
 } from '@abloatai/transaction/durableWrites';
-import type { PendingWrite } from '@abloatai/transaction/transactions/settlement/pendingWrite';
+import type { PendingWrite } from '@abloatai/transaction/transactions/confirmation/pendingWrite';
 
 export interface CommitOutboxDatabase {
   sealTransactionRecord(

package/src/local/transactions/localMutation.ts

@@ -10,7 +10,7 @@ type EmitLocalMutation = (event: string, payload: unknown) => void;
 /**
  * Human-side optimistic-write adapter.
  *
- * Settlement retains ordering and receipts; this adapter owns the local
+ * Confirmation retains ordering and receipts; this adapter owns the local
  * pre-image ledger and announces apply/rollback work to the materialiser.
  */
 export function createLocalMutationPort(

package/src/local/transactions/mutations/MutationQueue.ts

@@ -87,7 +87,7 @@ import {
   type DurableCommitOperation,
   type DurableCommitOperationInput,
   type CommitOutboxScope,
-} from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+} from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { DurableWriteStore } from './durableWriteStore.js';
 import { stableStringify } from '@abloatai/transaction/utils/json';
 import {
@@ -126,7 +126,7 @@ import { handleConflict as resolveConflict, isPermanentError as classifyPermanen
 import { takeNextExecutionBatch as selectExecutionBatch, takePendingDrainBatch as selectPendingDrainBatch } from './executionSelection.js';
 import { scheduleProcessing as scheduleProcessingExternal, type ProcessingSchedulerContext } from './processingScheduler.js';
 import {
-  drainPendingSettlements,
+  drainPendingConfirmations,
   type PendingDrainContext,
 } from './pendingDrain.js';
 import { restoreDurableCommits as restoreDurableCommitsExternal, type DurableCommitRestoreContext } from './durableCommitRestore.js';
@@ -286,7 +286,7 @@ export class MutationQueue extends EventEmitter {
   /**
    * Small race buffer for authoritative echoes that arrive before the queued
    * mutation receipt. The forward and WAL stream are independent channels, so
-   * either can win without changing the settlement result.
+   * either can win without changing the confirmation result.
    */
   private recentDeltaCorrelations = new Map<string, number>();
   /**
@@ -1472,7 +1472,7 @@ export class MutationQueue extends EventEmitter {
     if (this.isProcessing) return;
     this.isProcessing = true;
     try {
-      await drainPendingSettlements(this.pendingDrainContext);
+      await drainPendingConfirmations(this.pendingDrainContext);
     } finally {
       this.isProcessing = false;
       if (this.executionQueue.length > 0) this.scheduleProcessing(true);

package/src/local/transactions/mutations/batchProcessing.ts

@@ -6,7 +6,7 @@ import type { OptimisticUpdateEntry } from './localMutation.js';
 import type { StaleNotification } from '@abloatai/transaction/coordination/schema';
 import type { DeltaConfirmationTracker } from './deltaConfirmation.js';
 import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
-import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import { AbloError, AbloNotFoundError } from '@abloatai/transaction/errors';
 import { applyWriteOptions, normalizeModelKey, TX_TYPE_TO_MUTATION_OP, type WriteOperationFields } from './commitPayload.js';
 import type { MutationOperationType } from '@abloatai/transaction/types';

package/src/local/transactions/mutations/commitApi.ts

@@ -1,7 +1,7 @@
 import { AbloIdempotencyError } from '@abloatai/transaction/errors';
 import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
 import { stableStringify } from '@abloatai/transaction/utils/json';
-import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { CommitTransaction } from './commitLane.js';
 import type { SealDurableCommitInput } from './commitTransport.js';
 

package/src/local/transactions/mutations/commitLane.ts

@@ -4,7 +4,7 @@ import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
 import type {
   DurableCommitEnvelope,
   DurableCommitOperation,
-} from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+} from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { SealDurableCommitInput } from './commitTransport.js';
 import { transientRetryDelayMs } from './failureHandling.js';
 

package/src/local/transactions/mutations/commitPayload.ts

@@ -15,7 +15,7 @@ import { MutationOperationType } from '@abloatai/transaction/types';
 import { snapshotJsonValue } from '@abloatai/transaction/utils/json';
 import type { OnStaleMode } from '@abloatai/transaction/coordination/schema';
 import type { MutationOptions, WriteOptions } from '../../interfaces/index.js';
-import type { CommitEnvelopeMember } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { CommitEnvelopeMember } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 
 export interface UserContext {
   userId: string;
@@ -208,6 +208,8 @@ export function hasStaleWriteOptions(options?: WriteOptions): boolean {
 export function hasCommitCoalescingBarrier(options?: WriteOptions): boolean {
   return (
     hasStaleWriteOptions(options) ||
+    options?.claimRef != null ||
+    options?.fenceToken != null ||
     typeof options?.idempotencyKey === 'string' ||
     typeof options?.label === 'string'
   );
@@ -217,6 +219,7 @@ export interface WriteOperationFields {
   readAt?: number | null;
   onStale?: OnStaleMode | null;
   fenceToken?: number | null;
+  claimId?: string;
   options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
 }
 
@@ -243,6 +246,12 @@ export function applyWriteOptions<T extends object>(
   if (writeOptions.fenceToken !== undefined) {
     operation.fenceToken = writeOptions.fenceToken;
   }
+  if (writeOptions.claimRef != null) {
+    operation.claimId =
+      typeof writeOptions.claimRef === 'string'
+        ? writeOptions.claimRef
+        : writeOptions.claimRef.id;
+  }
   if (writeOptions.idempotencyKey != null || writeOptions.label !== undefined) {
     operation.options = {
       ...(writeOptions.idempotencyKey != null

package/src/local/transactions/mutations/commitTransport.ts

@@ -17,7 +17,7 @@ import {
   type CommitOutboxScope,
   type DurableCommitEnvelope,
   type DurableCommitOperation,
-} from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+} from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { DurableWriteStore } from './durableWriteStore.js';
 
 export interface CommitTransportContext {

package/src/local/transactions/mutations/durableCommitRestore.ts

@@ -1,9 +1,9 @@
 import { AbloIdempotencyError, AbloValidationError } from '@abloatai/transaction/errors';
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { CommitTransaction } from './commitLane.js';
-import type { DurableCommitEnvelope, CommitOutboxScope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { DurableCommitEnvelope, CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { DurableWriteStore } from './durableWriteStore.js';
-import { durableCommitEnvelopeSchema } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import { durableCommitEnvelopeSchema } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 
 export interface DurableCommitRestoreContext {
   readonly config: { enablePersistence: boolean };

package/src/local/transactions/mutations/durableWriteStore.ts

@@ -1,12 +1,12 @@
 /**
- * The durable-write port moved to the settlement core (ADR 0016): it is a
+ * The durable-write port moved to the confirmation core (ADR 0016): it is a
  * contract over commit envelopes and holds no local rows. Re-exported here so
  * the existing `transactions/mutations/durableWriteStore` import path keeps
  * resolving for the queue, the outbox, and the client options.
  *
  * The port and its config live in the core's `durableWrites` module (a behavior
  * contract, not a persisted shape); the records that cross it are owned by
- * `transactions/settlement/pendingWrite`.
+ * `transactions/confirmation/pendingWrite`.
  */
 
 export {
@@ -17,5 +17,5 @@ export type {
   DurableWriteStore,
   DurableWritesConfig,
 } from '@abloatai/transaction/durableWrites';
-export { pendingWriteSchema } from '@abloatai/transaction/transactions/settlement/pendingWrite';
-export type { PendingWrite } from '@abloatai/transaction/transactions/settlement/pendingWrite';
+export { pendingWriteSchema } from '@abloatai/transaction/transactions/confirmation/pendingWrite';
+export type { PendingWrite } from '@abloatai/transaction/transactions/confirmation/pendingWrite';

package/src/local/transactions/mutations/localMutation.ts

@@ -30,7 +30,7 @@ export interface OptimisticEmitter {
   emit(event: string, payload: unknown): void;
 }
 
-/** Materializer capability consumed by settlement; implementation belongs to the local layer. */
+/** Materializer capability consumed by confirmation; implementation belongs to the local layer. */
 export interface LocalMutationPort {
   readonly updates: Map<string, OptimisticUpdateEntry>;
   applyCreate(model: Model, transaction: QueuedMutation): void;

package/src/local/transactions/mutations/mutationPersistence.ts

@@ -1,7 +1,7 @@
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { MutationPersistencePort } from '../../mutationPersistence.js';
 import type { MutationQueueConfig } from './MutationQueue.js';
-import type { CommitOutboxScope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { QueuedMutation } from './commitPayload.js';
 import { MutationStore } from './MutationStore.js';
 import { normalizeModelKey } from './commitPayload.js';

package/src/local/transactions/mutations/pendingDrain.ts

@@ -3,7 +3,7 @@ import type { QueuedMutation } from './commitPayload.js';
 import type { MutationStore } from './MutationStore.js';
 import type { OptimisticUpdateEntry } from './localMutation.js';
 import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
-import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import { applyWriteOptions, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 
 export interface PendingDrainContext {
@@ -31,7 +31,7 @@ export interface PendingDrainContext {
   readonly emit: (event: string, payload: object) => boolean;
 }
 
-export async function drainPendingSettlements(ctx: PendingDrainContext): Promise<void> {
+export async function drainPendingConfirmations(ctx: PendingDrainContext): Promise<void> {
     ctx.assertDurableReplayOpen();
     // Kick the commit lane too: atomic envelopes from `commits.create()` may
     // have been left at the head of the lane while the connection was down.