@abloatai/humans 0.48.0 → 0.50.0

package/dist/local/client/storeLifecycle.d.ts

@@ -10,6 +10,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 { CredentialProvider } from '@abloatai/transaction/auth/apiKey';
@@ -23,6 +24,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 {
     /**

package/dist/local/client/storeLifecycle.js

@@ -169,6 +169,7 @@ export function startStoreLifecycle(deps) {
                     participantKind,
                     accountScope,
                     syncGroups: resolvedSyncGroups,
+                    authority: resolved.authority,
                 });
                 if (resolved.refreshScheduler) {
                     _refreshScheduler = resolved.refreshScheduler;

package/dist/local/client/wsMutationExecutor.d.ts

@@ -7,6 +7,8 @@
 import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
 import type { MutationExecutor, MutationOperation } from '../interfaces/index.js';
 import type { CommitAck } from '../sync/commitFrames.js';
+import type { CommitReceiptWire } from '@abloatai/transaction/wire/commit';
+import { type ReadSetContext } from '@abloatai/transaction/internal/read-set';
 /**
  * Creates the default mutation executor, which sends each change as a `commit`
  * frame over the sync engine's own WebSocket. The engine owns its socket, so
@@ -23,5 +25,6 @@ import type { CommitAck } from '../sync/commitFrames.js';
  * generation below exists only for direct, one-shot executor consumers.
  */
 export declare 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, timeoutMs?: number, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null) => Promise<CommitAck>;
-} | null): MutationExecutor;
+} | null, readSetContext?: ReadSetContext): MutationExecutor;

package/dist/local/client/wsMutationExecutor.js

@@ -4,6 +4,8 @@
  * commit time because it does not exist yet when the executor is created. A
  * client wires this up automatically unless you supply your own executor.
  */
+import { recordWebSocketCommitReceipt, } 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) ──────
 /**
@@ -21,10 +23,10 @@ import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
  * this key before its first attempt and owns reuse across retries. The fallback
  * generation below exists only for direct, one-shot executor consumers.
  */
-export function createDefaultMutationExecutor(getWs) {
+export function createDefaultMutationExecutor(getWs, readSetContext) {
     async function commit(operations, options) {
         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.', { code: 'ws_not_ready' });
         }
@@ -33,6 +35,28 @@ export function createDefaultMutationExecutor(getWs) {
                 ? 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, undefined, // use sendCommit's built-in 15s default; no per-call override
             options?.reads, options?.track);
         }

package/dist/local/context.js

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

package/dist/local/interfaces/index.d.ts

@@ -142,7 +142,7 @@ import type { MutationOptions } from '@abloatai/transaction/resources/mutationOp
  * `claim` are deliberately absent: both are resolved on the client before a write
  * is staged, so neither reaches this layer.
  */
-export type WriteOptions = Pick<MutationOptions, 'readAt' | 'onStale' | 'idempotencyKey' | 'label' | 'fenceToken'>;
+export type WriteOptions = Pick<MutationOptions, 'readAt' | 'onStale' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'>;
 /** A single mutation within a batch. Its `options` travel with it so the server
  *  can cache and replay the operation for idempotent retries. */
 export interface MutationOperation {
@@ -162,6 +162,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/dist/local/mutators/UndoManager.d.ts

@@ -168,7 +168,7 @@ export declare 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;
     /**

package/dist/local/mutators/UndoManager.js

@@ -315,7 +315,7 @@ export class UndoScope {
      * 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.
      */
     enqueue(work) {
         const result = this.tail.then(work, work);

package/dist/local/query/client.js

@@ -12,6 +12,7 @@
  * repeating the fetch and error-handling boilerplate.
  */
 import { z } from 'zod';
+import { modelListEvidenceSchema } from '@abloatai/transaction/wire';
 import { translateHttpError } from '@abloatai/transaction/errors';
 import { classifyRecovery } from '@abloatai/transaction/errorCodes';
 import { withAuthHeaders } from '@abloatai/transaction/auth/credentialSource';
@@ -33,6 +34,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();
 /**
@@ -129,6 +140,10 @@ export async function postQuery(options, batch) {
                 });
                 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 {

package/dist/local/query/types.d.ts

@@ -15,6 +15,7 @@
  */
 export type { WherePrimitive, WhereOp, WhereClause, 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 {
     /**
@@ -76,6 +77,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
@@ -83,3 +96,4 @@ export interface QueryBatchResult {
      */
     lastSyncId?: number;
 }
+export type QueryReadEvidence = ModelListEvidence;

package/dist/local/stores/syncAction.d.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.
  */
 import { z } from 'zod';

package/dist/local/stores/syncAction.js

@@ -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.
  */
 import { z } from 'zod';

package/dist/local/sync/ConnectionManager.d.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/dist/local/sync/ConnectionManager.js

@@ -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/dist/local/sync/OnDemandLoader.d.ts

@@ -78,6 +78,7 @@ export interface FetchOptions<T> {
 }
 export declare class OnDemandLoader {
     private readonly opts;
+    private readonly readEvidence;
     private readonly inFlight;
     /**
      * Query keys with a background confirm currently in flight. Distinct from
@@ -125,6 +126,8 @@ export declare class OnDemandLoader {
      * deduped on the (modelName, where, orderBy, limit) tuple.
      */
     fetch<T>(modelName: string, options?: FetchOptions<T>): Promise<Model[]>;
+    /** Exact evidence retained for a row returned by a server-confirmed fetch. */
+    getReadEvidence(row: object): number | undefined;
     private runFetch;
     /**
      * Read a query's rows from local storage only — pool first, then IndexedDB

package/dist/local/sync/OnDemandLoader.js

@@ -49,6 +49,7 @@ function snapshotDoesNotAdvanceModel(data, model) {
 }
 export class OnDemandLoader {
     opts;
+    readEvidence = new WeakMap();
     inFlight = new Map();
     /**
      * Query keys with a background confirm currently in flight. Distinct from
@@ -135,6 +136,10 @@ export class OnDemandLoader {
             .catch(() => undefined);
         return work;
     }
+    /** Exact evidence retained for a row returned by a server-confirmed fetch. */
+    getReadEvidence(row) {
+        return this.readEvidence.get(row);
+    }
     async runFetch(modelName, typename, ModelClass, clauses, options, queryKey) {
         // `{ type: 'complete' }` is the only way to force a server round-trip:
         // read-after-write certainty. Every other read is local-first.
@@ -217,7 +222,8 @@ export class OnDemandLoader {
      * revalidation kicked off after an `'unknown'` local hit.
      */
     async fetchFromNetwork(modelName, typename, clauses, options) {
-        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
@@ -225,6 +231,12 @@ export class OnDemandLoader {
             // dropping the row and failing downstream as `entity_not_found`.
             .map((raw) => this.hydrateOne(raw, typename, { strict: true }))
             .filter((m) => 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
@@ -435,6 +447,7 @@ export class OnDemandLoader {
             runtime: this.opts.runtime,
         }, { queries: [query] });
         const rows = 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)) {
@@ -453,7 +466,7 @@ export class OnDemandLoader {
         if (options?.expand && options.expand.length > 0) {
             this.hydrateExpanded(modelName, normalized, options.expand);
         }
-        return normalized;
+        return { rows: normalized, evidence };
     }
     /**
      * Hydrate nested expanded rows. Resolves each relation's target

package/dist/local/sync/SyncWebSocket.d.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/dist/local/sync/SyncWebSocket.js

@@ -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/dist/local/sync/commitFrames.d.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/dist/local/sync/commitFrames.js

@@ -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/dist/local/sync/contextPorts.d.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/dist/local/sync/contextPorts.js

@@ -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/dist/local/sync/credentialLifecycle.d.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/dist/local/sync/credentialLifecycle.js

@@ -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/dist/local/sync/wsFrameHandlers.d.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/dist/local/sync/wsFrameHandlers.js

@@ -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/dist/local/transactions/databaseCommitOutbox.d.ts

@@ -1,5 +1,5 @@
 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(record: PendingWrite, consumedRecordIds: readonly string[]): Promise<unknown>;
     getPersistedTransactions(): Promise<readonly unknown[]>;

package/dist/local/transactions/localMutation.d.ts

@@ -3,7 +3,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 declare function createLocalMutationPort(emit: EmitLocalMutation): LocalMutationPort;

package/dist/local/transactions/localMutation.js

@@ -1,7 +1,7 @@
 /**
  * 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(emit) {

package/dist/local/transactions/mutations/MutationQueue.d.ts

@@ -19,7 +19,7 @@ import { type LogPositionPort } from '../../logPosition.js';
 import type { WriteOptions } from '../../interfaces/index.js';
 import type { StaleNotification, ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
 import { type MutationInput, type QueuedMutation, type UserContext } from './commitPayload.js';
-import { type CommitOutboxScope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import { type CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { DurableWriteStore } from './durableWriteStore.js';
 import { type LocalMutationPort } from './localMutation.js';
 import { type CommitTransaction } from './commitLane.js';
@@ -124,7 +124,7 @@ export declare 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;
     /**

package/dist/local/transactions/mutations/MutationQueue.js

@@ -25,7 +25,7 @@ import { entityKey, mergeUpdateData, takeUnsentCreateForModel, findCreateBarrier
 import { DeltaConfirmationTracker } from './deltaConfirmation.js';
 import { deserializePersistedTransaction, isNonReplayablePersistedRow, pendingMutationRecordId, legacyPendingMutationRecordSchema, pendingMutationRecordSchema, persistedMutationSchema, } from './replayValidation.js';
 import { deserializeLegacyPendingMutation, loadPersistedTransactions, persistQueuedTransaction, removePersistedTransaction, settlePersistedFailure, } from './mutationPersistence.js';
-import { createCommitEnvelopeMember, createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import { createCommitEnvelopeMember, createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import { stableStringify } from '@abloatai/transaction/utils/json';
 import { createLocalMutationPort, } from './localMutation.js';
 import { dispatchCommitBounded, parseMutationCommitResult, persistDurableCommitAcceptance, removeDurableCommit, sealDurableCommit, } from './commitTransport.js';
@@ -38,7 +38,7 @@ import { handleFailure } from './failureHandling.js';
 import { handleConflict as resolveConflict, isPermanentError as classifyPermanentError, isDefinitiveRejection as classifyDefinitiveRejection } from './failurePolicy.js';
 import { takeNextExecutionBatch as selectExecutionBatch, takePendingDrainBatch as selectPendingDrainBatch } from './executionSelection.js';
 import { scheduleProcessing as scheduleProcessingExternal } from './processingScheduler.js';
-import { drainPendingSettlements, } from './pendingDrain.js';
+import { drainPendingConfirmations, } from './pendingDrain.js';
 import { restoreDurableCommits as restoreDurableCommitsExternal } from './durableCommitRestore.js';
 export class MutationQueue extends EventEmitter {
     // Keep one hour of clock/network margin inside the server's 24-hour ledger.
@@ -92,7 +92,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.
      */
     recentDeltaCorrelations = new Map();
     /**
@@ -1082,7 +1082,7 @@ export class MutationQueue extends EventEmitter {
             return;
         this.isProcessing = true;
         try {
-            await drainPendingSettlements(this.pendingDrainContext);
+            await drainPendingConfirmations(this.pendingDrainContext);
         }
         finally {
             this.isProcessing = false;

package/dist/local/transactions/mutations/batchProcessing.d.ts

@@ -5,7 +5,7 @@ import type { MutationStore } from './MutationStore.js';
 import type { OptimisticUpdateEntry } from './localMutation.js';
 import type { StaleNotification } from '@abloatai/transaction/coordination/schema';
 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';
 export interface BatchProcessingContext {
     readonly runtime: RuntimeContext;
     readonly config: MutationQueueConfig;

package/dist/local/transactions/mutations/commitApi.d.ts

@@ -1,5 +1,5 @@
 import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
-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';
 export interface CommitApiContext {

package/dist/local/transactions/mutations/commitLane.d.ts

@@ -1,7 +1,7 @@
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { ReadDependency, TrackDependency, OnStaleMode, StaleNotification } from '@abloatai/transaction/coordination/schema';
 import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
-import type { DurableCommitEnvelope, DurableCommitOperation } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { DurableCommitEnvelope, DurableCommitOperation } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { SealDurableCommitInput } from './commitTransport.js';
 export interface CommitTransaction {
     id: string;

package/dist/local/transactions/mutations/commitPayload.d.ts

@@ -12,7 +12,7 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 import { MutationOperationType } from '@abloatai/transaction/types';
 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;
     organizationId: string;
@@ -130,6 +130,7 @@ export interface WriteOperationFields {
     readAt?: number | null;
     onStale?: OnStaleMode | null;
     fenceToken?: number | null;
+    claimId?: string;
     options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
 }
 /**

package/dist/local/transactions/mutations/commitPayload.js

@@ -110,6 +110,8 @@ export function hasStaleWriteOptions(options) {
 /** Options whose identity/audit semantics forbid merging two caller writes. */
 export function hasCommitCoalescingBarrier(options) {
     return (hasStaleWriteOptions(options) ||
+        options?.claimRef != null ||
+        options?.fenceToken != null ||
         typeof options?.idempotencyKey === 'string' ||
         typeof options?.label === 'string');
 }
@@ -134,6 +136,12 @@ export function applyWriteOptions(op, transaction) {
     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/dist/local/transactions/mutations/commitTransport.d.ts

@@ -2,7 +2,7 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { MutationExecutor } from '../../interfaces/index.js';
 import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
 import { type MutationCommitResult } from '@abloatai/transaction/wire/commit';
-import { type CommitOutboxScope, type DurableCommitEnvelope, type DurableCommitOperation } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import { type CommitOutboxScope, type DurableCommitEnvelope, type DurableCommitOperation } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { DurableWriteStore } from './durableWriteStore.js';
 export interface CommitTransportContext {
     readonly runtime: RuntimeContext;

package/dist/local/transactions/mutations/commitTransport.js

@@ -1,6 +1,6 @@
 import { AbloConnectionError, AbloError, AbloIdempotencyError, } from '@abloatai/transaction/errors';
 import { mutationCommitResultSchema, } from '@abloatai/transaction/wire/commit';
-import { createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import { createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 export async function sealDurableCommit(ctx, input, pendingMutationRecordId) {
     const sourceMutationIds = [...new Set(input.sourceMutationIds ?? [])];
     const envelope = createDurableCommitEnvelope({

package/dist/local/transactions/mutations/durableCommitRestore.d.ts

@@ -1,6 +1,6 @@
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { CommitTransaction } from './commitLane.js';
-import type { CommitOutboxScope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { DurableWriteStore } from './durableWriteStore.js';
 export interface DurableCommitRestoreContext {
     readonly config: {

package/dist/local/transactions/mutations/durableCommitRestore.js

@@ -1,5 +1,5 @@
 import { AbloIdempotencyError, AbloValidationError } from '@abloatai/transaction/errors';
-import { durableCommitEnvelopeSchema } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import { durableCommitEnvelopeSchema } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 export async function restoreDurableCommits(ctx) {
     if (!ctx.config.enablePersistence)
         return new Set();

package/dist/local/transactions/mutations/durableWriteStore.d.ts

@@ -1,14 +1,14 @@
 /**
- * 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 { durableWriteStoreSchema, durableWritesConfigSchema, } from '@abloatai/transaction/durableWrites';
 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';