@abloatai/transaction 0.48.0 → 0.50.0

package/src/resources/functionalUpdate.ts

@@ -28,6 +28,7 @@ import {
   AbloClaimedError,
   AbloContentionError,
 } from '../errors.js';
+import type { ReadDependency } from '../coordination/schema.js';
 
 /**
  * The functional form of an update: given the freshly-read row, return the
@@ -38,8 +39,8 @@ export type ModelUpdater<T> = (
   current: T,
 ) => Partial<T> | null | undefined | Promise<Partial<T> | null | undefined>;
 
-/** Tuning for the functional update's internal reconcile loop. */
-export interface ContentionOptions {
+/** Options for the functional `update(id, reducer, options)` form. */
+export interface FunctionalUpdateOptions<Dependency = ReadDependency> {
   /**
    * Max reconcile rounds under contention before throwing
    * {@link AbloContentionError}. Each round re-reads the latest row and re-runs
@@ -48,8 +49,19 @@ export interface ContentionOptions {
   readonly retries?: number;
   /** Abort the reconcile loop (e.g. the request was cancelled). */
   readonly signal?: AbortSignal;
+  /**
+   * Cross-target state this reducer decision depends on. Captured point rows
+   * are resolved by the public client; canonical dependencies remain the
+   * low-level escape hatch. Dependencies survive reconcilable CAS failures and
+   * are consumed only with the successful attempt.
+   */
+  readonly reads?: readonly Dependency[] | null;
 }
 
+/** @deprecated Use {@link FunctionalUpdateOptions}. */
+export type ContentionOptions<Dependency = ReadDependency> =
+  FunctionalUpdateOptions<Dependency>;
+
 /** Reconcile rounds before a hot row is declared permanently contended. */
 export const DEFAULT_CONTENTION_RETRIES = 16;
 
@@ -104,9 +116,9 @@ export interface ReconcileTransport<T, R> {
  * both transports so the guarantee is provably identical. Returns the write's
  * result, or `undefined` when the updater opted out of writing.
  */
-export async function reconcileFunctionalUpdate<T, R>(
+export async function reconcileFunctionalUpdate<T, R, Read = ReadDependency>(
   updater: ModelUpdater<T>,
-  options: ContentionOptions | undefined,
+  options: FunctionalUpdateOptions<Read> | undefined,
   transport: ReconcileTransport<T, R>,
 ): Promise<R | undefined> {
   const retries = options?.retries ?? DEFAULT_CONTENTION_RETRIES;

package/src/resources/httpResources.ts

@@ -15,14 +15,19 @@ import type { ClaimHeartbeatReply, ClaimState } from '../wire/claims.js';
 import type {
   ClientCommitReceipt,
   CommitWait,
+  CommitRecord,
+  CommitRecordList,
+  CommitRecordListOptions,
+  CommitRecordWhere,
 } from '../wire/commit.js';
 import type { LogListResponse, LogQuery } from '../wire/feedEvent.js';
-// Re-exported, not redeclared. `wire/commit.ts` owns the settlement vocabulary
+import type { ModelListEvidence } from '../wire/modelResponses.js';
+// Re-exported, not redeclared. `wire/commit.ts` owns the commit-status vocabulary
 // and derives the waitable subset from it; this module serves that name to SDK
 // consumers. Restating the subset here as its own union produced a type that
 // matched the canonical one only by both happening to list the same two
 // strings — and would have silently disagreed with the runtime `wait`
-// validator the moment a third settlement state existed.
+// validator the moment a third commit status existed.
 export type { CommitWait };
 // `ModelTarget` (the `model` and `id` locator) and `ModelClaim` (the resolved
 // claim view) are defined in `../coordination/schema`, derived from a single
@@ -39,7 +44,7 @@ import type { SyncGroupInput } from '../schema/roles.js';
 import type {
   CapabilityCan,
   CapabilityOperation,
-  CapabilityScope,
+  EffectiveAuthority,
 } from '../auth/capability.js';
 import type {
   Claim,
@@ -48,7 +53,7 @@ import type {
   Duration,
   HeldClaim,
 } from '../types/streams.js';
-import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
+import type { ModelUpdater, FunctionalUpdateOptions } from './functionalUpdate.js';
 import type {
   ClaimOptions,
   ClaimAttemptEvent,
@@ -93,6 +98,12 @@ export interface HttpTransportRead<T = Record<string, unknown>> {
   readonly claims: readonly ModelClaim[];
 }
 
+/** @internal Exact collection envelope retained until the typed facade captures evidence. */
+export interface HttpTransportList<T = Record<string, unknown>> {
+  readonly data: readonly T[];
+  readonly evidence?: readonly ModelListEvidence[];
+}
+
 export type IfClaimedPolicy = 'return' | 'fail';
 
 export interface ClaimedOptions {
@@ -160,6 +171,8 @@ export interface CommitOperationInput {
   readonly id?: string | null;
   readonly data?: Record<string, unknown> | null;
   readonly transactionId?: string | null;
+  /** Claim identity derived from a held claim; not an application id. */
+  readonly claimId?: string | null;
   readonly readAt?: number | null;
   readonly onStale?: OnStaleMode | null;
   /** Fencing token (Option B) from the batch's claim handle; server-validated. */
@@ -207,6 +220,8 @@ export type CommitReceipt = ClientCommitReceipt;
 
 export interface CommitResource {
   create(options: CommitCreateOptions): Promise<CommitReceipt>;
+  get(options: { readonly id: string }): Promise<CommitRecord | null>;
+  list(options?: CommitRecordListOptions): Promise<CommitRecordList>;
 }
 
 export interface HttpLogListOptions
@@ -276,6 +291,10 @@ export interface ModelMutationOptions extends ClaimedOptions {
   readonly idempotencyKey?: string | null;
   readonly readAt?: number | null;
   readonly onStale?: OnStaleMode | null;
+  /** Commit-lifetime read dependencies checked before this mutation lands. */
+  readonly reads?: readonly ReadDependency[] | null;
+  /** Persisted read dependencies registered by this mutation. */
+  readonly track?: readonly TrackDependency[] | null;
   readonly claim?: Claim | ClaimOptions | null;
   /** Fencing token (Option B) from the claim; server-validated at commit. */
   readonly fenceToken?: number | null;
@@ -332,7 +351,7 @@ export interface HttpTransportModel<
    * and `limit`. The typed public client always exposes `ablo.<model>.list`;
    * this protocol shape is private transport machinery.
    */
-  list(options?: ServerReadOptions<T>): Promise<T[]>;
+  list(options?: ServerReadOptions<T>): Promise<HttpTransportList<T>>;
   /**
    * Creates a row and returns the confirmed server row, including framework
    * defaults such as `createdAt` and `createdBy`. Matches the stateful client's
@@ -354,7 +373,7 @@ export interface HttpTransportModel<
   update(
     id: string,
     updater: ModelUpdater<T>,
-    options?: ContentionOptions,
+    options?: FunctionalUpdateOptions,
   ): Promise<CommitReceipt | undefined>;
   delete(params: ModelMutationOptions & { readonly id: string }): Promise<CommitReceipt>;
   /**
@@ -475,7 +494,7 @@ export interface AbloSession {
   organizationId: string;
   /** The grant this token carries, on both axes — the same shape the key row
    *  stores and the gates enforce. */
-  scope: CapabilityScope;
+  scope: EffectiveAuthority;
   userMeta: Record<string, unknown>;
 }
 
@@ -492,7 +511,7 @@ export interface SessionRotation {
   token: string;
   expiresAt: string | null;
   organizationId: string;
-  scope: CapabilityScope;
+  scope: EffectiveAuthority;
   rotatedFrom: {
     id: string;
     expiresAt: string;

package/src/resources/modelOperations.ts

@@ -3,7 +3,7 @@
  * caller passes to a read, a write, or a claim.
  *
  * These types describe the *change or the query being requested*, never a local
- * copy of the rows it touches, so they sit in the settlement core and are shared
+ * copy of the rows it touches, so they sit in the commit core and are shared
  * by every transport and every caller (ADR 0013 §4, ADR 0016). The factory that
  * binds them to reactive model instances — `createModelProxy` — stays with the
  * reactive consumer, along with `ModelOperations` and `ModelCollaboration`,
@@ -562,7 +562,7 @@ export interface ModelRetrieveParams extends ServerRetrieveOptions {
  * Options shared by schema model writes.
  *
  * Reactive clients apply the row change optimistically before returning from
- * the call. The returned promise has one stable settlement contract across
+ * the call. The returned promise has one stable confirmation contract across
  * reactive and stateless clients: it resolves only after authoritative
  * confirmation. Callers that need an earlier queued receipt use the lower-level
  * `commits.create` resource instead.

package/src/resources/mutationOptions.ts

@@ -3,7 +3,7 @@
  *
  * Every field here defines, orders, settles, or authorises *the change itself*
  * — request identity, commit disposition, fencing, and the premise it rests on.
- * None of it touches a local copy of rows, so it belongs with the settlement
+ * None of it touches a local copy of rows, so it belongs with the commit
  * core rather than the reactive consumer (ADR 0013 §4, ADR 0016).
  */
 

package/src/resources/where.ts

@@ -10,7 +10,7 @@
  * key — for example, fetching every block whose `sectionId` falls in a set of ids.
  *
  * These types describe the *request*, not any local copy of the rows it returns,
- * so they live with the settlement core rather than the reactive consumer.
+ * so they live with the commit core rather than the reactive consumer.
  */
 
 import { z } from 'zod';

package/src/resources/writeOptionsSchema.ts

@@ -20,7 +20,15 @@ import { z } from 'zod';
 import type { MutationOptions } from '../resources/mutationOptions.js';
 import { AbloValidationError } from '../errors.js';
 import { commitWaitSchema } from '../wire/commit.js';
-import { onStaleModeSchema } from '../coordination/schema.js';
+import {
+  onStaleModeSchema,
+  MAX_READ_SET_ENTRIES,
+  readDependencyListSchema,
+  readSetWatermarkSchema,
+  readSetProjectionEntryCount,
+  trackDependencyListSchema,
+} from '../coordination/schema.js';
+import type { AssertExact } from '../types/assertExact.js';
 
 // Re-exported, not redeclared. `coordination/schema.ts` owns this enum — it is
 // what the wire schemas and the server validate against — while the published
@@ -38,7 +46,7 @@ export const writeOptionsSchema = z.object({
   /** Resolve when queued locally (default) or once the server confirms. */
   wait: commitWaitSchema.optional(),
   /** Stale guard: the sync watermark the caller's reasoning was based on. */
-  readAt: z.number().int().nonnegative().nullish(),
+  readAt: readSetWatermarkSchema.nullish(),
   /** What the server does when the target moved past `readAt`. */
   onStale: onStaleModeSchema.nullish(),
   /** The held claim's fencing token (Option B), sourced from the claim handle
@@ -49,6 +57,15 @@ export const writeOptionsSchema = z.object({
   /** The claim this write belongs to — either a claim id, or a live claim
    *  handle whose `release`/`revoke` functions are preserved untouched. */
   claim: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
+  /** Low-level claim identity carried after a live handle is normalized. */
+  claimRef: z.union([z.string(), z.object({ id: z.string() })]).nullish(),
+  /** Commit-lifetime entries in the write's ReadSet. */
+  reads: readDependencyListSchema.nullish(),
+  /** Persisted entries projected from the write's ReadSet. */
+  track: trackDependencyListSchema.nullish(),
+}).refine((value) => readSetProjectionEntryCount(value) <= MAX_READ_SET_ENTRIES, {
+  path: ['reads'],
+  message: `reads and track may contain at most ${MAX_READ_SET_ENTRIES} entries combined`,
 });
 
 export type WriteOptionsInput = z.infer<typeof writeOptionsSchema>;
@@ -78,14 +95,15 @@ export function assertWriteOptions(value: unknown, context?: string): void {
 }
 
 // ── Drift guard ──────────────────────────────────────────────────────────────
-// Compile-time proof that `writeOptionsSchema` stays assignment-compatible
-// with the canonical `MutationOptions` interface. If either side changes
-// shape, this stops compiling — the schema and the interface can never
-// silently diverge.
-type _AssertOptionsMatchSchema = MutationOptions extends WriteOptionsInput ? true : never;
-type _AssertSchemaMatchesOptions = WriteOptionsInput extends MutationOptions ? true : never;
-const _writeOptionsContractInSync: [_AssertOptionsMatchSchema, _AssertSchemaMatchesOptions] = [
-  true,
-  true,
-];
+// `claim` is the one high-level handle normalized before MutationOptions. Every
+// other key is the canonical interface itself. Compare keys exactly: mutual
+// assignment between all-optional objects is vacuous and failed to catch three
+// missing members in this schema.
+type WriteOptionsContract = MutationOptions & {
+  readonly claim?: string | { readonly id: string } | null;
+};
+const _writeOptionsContractInSync: AssertExact<
+  keyof WriteOptionsInput,
+  keyof WriteOptionsContract
+> = true;
 void _writeOptionsContractInSync;

package/src/schema/index.ts

@@ -275,6 +275,6 @@ export {
 
 // The OpenAPI generator describes the language-agnostic `/v1` surface — the
 // primitive itself, which a Python or Go caller consumes with no TypeScript
-// anywhere — so it lives in the settlement core (ADR 0016). Re-exported here so
+// anywhere — so it lives in the confirmation core (ADR 0016). Re-exported here so
 // the `@abloatai/ablo/schema` import path keeps resolving.
 export { abloOpenApi, schemaToOpenApi, type SchemaToOpenApiOptions } from './openapi.js';

package/src/schema/openapi.ts

@@ -29,7 +29,13 @@ import { ABLO_HOSTED_HTTP_BASE_URL } from '../auth/hostedEndpoints.js';
 // one definition site, so the documented surface cannot drift from the
 // enforced one.
 import { z } from 'zod';
-import { commitRequestSchema, commitReceiptSchema } from '../wire/commit.js';
+import {
+  commitRequestSchema,
+  commitReceiptSchema,
+  commitRecordSchema,
+  commitRecordListSchema,
+  commitRecordWhereSchema,
+} from '../wire/commit.js';
 import {
   claimRequestSchema,
   claimHeartbeatRequestSchema,
@@ -154,7 +160,9 @@ const ABLO_OPERATION_IDS: Readonly<Record<string, string>> = {
   'POST /v1/capabilities/{id}/rotate': 'rotateCapability',
   'GET /v1/schema': 'getSchema',
   'GET /v1/logs': 'listLogEntries',
+  'GET /v1/commits': 'listCommits',
   'POST /v1/commits': 'commit',
+  'GET /v1/commits/{id}': 'getCommit',
 };
 
 function fieldSchema(f: FieldMeta): Json {
@@ -317,6 +325,11 @@ function queryParams(schema: z.ZodType): Json[] {
   }));
 }
 
+const commitRecordListQuerySchema = commitRecordWhereSchema.safeExtend({
+  cursor: z.string().min(1).optional(),
+  limit: z.number().int().min(1).max(100).optional(),
+});
+
 /**
  * Both release routes answer in one shape. `released` distinguishes "this call
  * ended your lease" from "there was nothing of yours to end" — both success,
@@ -736,11 +749,9 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         tags: ['claims'],
         summary: 'Heartbeat a claim by id — held or queued',
         description:
-          'The beat a waiter needs: a queued caller holds nothing but the ' +
-          '`claimId` it was handed at enqueue, and an entry that stops beating ' +
-          'drops out of the line on TTL. The reply doubles as the wait poll — ' +
-          '`queued` means still in line, `held` means the grant landed, at which ' +
-          'point `GET /v1/claims/{claimId}` carries the fence token.',
+          'Keep a held or queued claim active. Branch on the returned status: ' +
+          '`queued` is still waiting and `held` has been granted. Retrieve the ' +
+          'claim after a grant before writing.',
         parameters: [claimIdParam()],
         requestBody: optionalJsonBody(derive(claimHeartbeatRequestSchema, 'input')),
         responses: {
@@ -849,6 +860,12 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
       },
     },
     '/v1/commits': {
+      get: {
+        tags: ['commits'],
+        summary: 'List commit records',
+        parameters: queryParams(commitRecordListQuerySchema),
+        responses: { '200': jsonResp('Tenant-scoped commit records', derive(commitRecordListSchema, 'output')) },
+      },
       post: {
         tags: ['commits'],
         summary: 'Commit a batch of operations atomically, and/or register durable premises',
@@ -857,6 +874,14 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         responses: { '200': commitReceipt() },
       },
     },
+    '/v1/commits/{id}': {
+      get: {
+        tags: ['commits'],
+        summary: 'Retrieve a commit record',
+        parameters: [idParam()],
+        responses: { '200': jsonResp('The commit record, or null when absent', derive(commitRecordSchema.nullable(), 'output')) },
+      },
+    },
   };
 
   applyOperationIds(paths, ABLO_OPERATION_IDS);
@@ -864,7 +889,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
 
   return envelope(
     options,
-    'The Ablo transaction layer: commit, read, and claim. `{model}` is any model ' +
+    'Ablo collaboration infrastructure: commit, read, and claim. `{model}` is any model ' +
       'from your pushed schema — the routes are the same whichever it is. ' +
       'Authenticate every request with your API key as a Bearer token.',
     paths,
@@ -962,6 +987,12 @@ export function schemaToOpenApi<S extends SchemaRecord>(
   }
 
   paths['/v1/commits'] = {
+    get: {
+      tags: ['commits'],
+      summary: 'List commit records',
+      parameters: queryParams(commitRecordListQuerySchema),
+      responses: { '200': jsonResp('Tenant-scoped commit records', derive(commitRecordListSchema, 'output')) },
+    },
     post: {
       tags: ['commits'],
       summary: 'Commit a batch of operations atomically, and/or register durable premises',
@@ -970,7 +1001,17 @@ export function schemaToOpenApi<S extends SchemaRecord>(
       responses: { '200': commitReceipt() },
     },
   };
+  paths['/v1/commits/{id}'] = {
+    get: {
+      tags: ['commits'],
+      summary: 'Retrieve a commit record',
+      parameters: [idParam()],
+      responses: { '200': jsonResp('The commit record, or null when absent', derive(commitRecordSchema.nullable(), 'output')) },
+    },
+  };
+  operationIds['GET /v1/commits'] = 'listCommits';
   operationIds['POST /v1/commits'] = 'commit';
+  operationIds['GET /v1/commits/{id}'] = 'getCommit';
   applyOperationIds(paths, operationIds);
   attachCanonicalErrors(paths);
 

package/src/server/commit.ts

@@ -17,6 +17,7 @@ import type { ParticipantKind, ConfirmationState } from '../log/syncDeltaRow.js'
 import type { ParticipantRef } from '../wire/delta.js';
 import type { CommitExecutionResultInput } from '../wire/commit.js';
 import type { ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { EffectiveAuthority } from '../auth/capability.js';
 
 export interface CommitContext {
   participantId: string;
@@ -25,6 +26,11 @@ export interface CommitContext {
    * structured attribution rather than a string-prefix convention.
    */
   participantKind: ParticipantKind;
+  /** Effective data grant resolved from the authenticated identity at commit time. */
+  authority?: EffectiveAuthority;
+  /** Server request identity and ingress used for physical-attempt evidence. */
+  requestId?: string;
+  transport?: 'http' | 'websocket' | 'internal';
   organizationId: string;
   /** Immutable branch selected by the authenticated credential. */
   branchId: string;
@@ -90,7 +96,7 @@ export interface CommitContext {
 
 /**
  * The server execution receipt persisted in `mutation_log`. Its runtime schema
- * lives with the HTTP/WS settlement contract so queued correlation cannot drift
+ * lives with the HTTP/WS confirmation contract so queued correlation cannot drift
  * between cache, transport, and client.
  */
 export type CommitExecutionResult = CommitExecutionResultInput;

package/src/server/index.ts

@@ -21,6 +21,10 @@ export type {
   AdapterResolver,
 } from './adapter.js';
 export type { CommitContext, CommitExecutionResult } from './commit.js';
-export { commitExecutionResultSchema } from '../wire/commit.js';
+export {
+  commitExecutionResultSchema,
+  commitRecordSchema,
+  type CommitRecord,
+} from '../wire/commit.js';
 export { storageModeSchema, type StorageMode } from './storageMode.js';
 export type { ColumnOverride, BootstrapModel } from './readConfig.js';

package/src/source/adapters/kysely.ts

@@ -338,15 +338,23 @@ export function kyselyDirectMutation<S extends SchemaRecord>(
   db: KyselyLike,
   schema: Schema<S>,
 ): MutationAdapter {
+  const markerModels = new Map<string, string>();
+  for (const [key, definition] of Object.entries(schema.models)) {
+    const typename = definition.typename || key;
+    markerModels.set(key, typename);
+    markerModels.set(key.toLowerCase(), typename);
+    markerModels.set(typename, typename);
+    markerModels.set(typename.toLowerCase(), typename);
+  }
   return createKyselyMutationAdapter(
     db,
     createKyselyMutationCore(db, schema),
     'direct',
     {
-      markerModelFor: (operationModel) => {
-        const typename = schema.models[operationModel]?.typename;
-        return typename && typename.length > 0 ? typename : operationModel;
-      },
+      markerModelFor: (operationModel) =>
+        markerModels.get(operationModel) ??
+        markerModels.get(operationModel.toLowerCase()) ??
+        operationModel,
     },
   );
 }

package/src/source/adapters/kyselyMutationCore.ts

@@ -100,11 +100,23 @@ function buildColumnMaps(schema: Schema): ReadonlyMap<string, ModelColumns> {
     }
     const orgColumn = tenancyColumn(model.tenancy);
     if (orgColumn) register('organizationId', orgColumn);
-    out.set(key, {
+    const columns = {
       table: model.tableName ?? key,
       fieldToColumn,
       columnToField,
-    });
+    };
+    // The public clients normalize operation model names to lowercase before
+    // they cross the wire. Preserve the authored key for direct adapter users,
+    // but resolve the same lowercase key/typename aliases as the server's
+    // schema-derived ModelMap. Without these aliases, a camelCase schema key
+    // such as `collaborationWorkItems` validates at the server boundary and
+    // then fails here as an unknown customer model.
+    out.set(key, columns);
+    out.set(key.toLowerCase(), columns);
+    if (model.typename) {
+      out.set(model.typename, columns);
+      out.set(model.typename.toLowerCase(), columns);
+    }
   }
   return out;
 }
@@ -191,7 +203,13 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
           .where('id', '=', id)
           .returningAll()
           .execute();
-        return deleted[0] ? toFields(columns, deleted[0]) : { id };
+        if (!deleted[0]) {
+          throw new AbloValidationError(
+            `${operation.type} on "${operation.model}/${id}" matched no source row`,
+            { code: 'entity_not_found' },
+          );
+        }
+        return toFields(columns, deleted[0]);
       }
 
       if (operation.type === 'CREATE') {
@@ -214,7 +232,13 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
         .where('id', '=', id)
         .returningAll()
         .execute();
-      return updated[0] ? toFields(columns, updated[0]) : { id, ...input };
+      if (!updated[0]) {
+        throw new AbloValidationError(
+          `${operation.type} on "${operation.model}/${id}" matched no source row`,
+          { code: 'mutate_update_entity_not_found' },
+        );
+      }
+      return toFields(columns, updated[0]);
     },
   };
 }

package/src/source/types.ts

@@ -152,7 +152,7 @@ export interface SourceEvent {
    */
   readonly organizationId?: string;
   /**
-   * @deprecated Legacy echo identity. It is not trusted for queued settlement;
+   * @deprecated Legacy echo identity. It is not trusted for queued confirmation;
    * use `correlationId` and `transactionId` for mediated endpoint writes.
    */
   readonly clientTxId?: string;

package/src/testing/fixtures/httpResponses.ts

@@ -17,6 +17,8 @@
 
 import { listEnvelope } from '@abloatai/transaction/wire';
 import type {
+  CommitAck,
+  CommitReceiptWire,
   ModelReadResponse,
   ModelListResponse,
   ClaimAcquiredResponse,
@@ -25,6 +27,55 @@ import type {
   ClaimHeartbeatReply,
 } from '@abloatai/transaction/wire';
 import type { ModelClaim } from '@abloatai/transaction/coordination';
+import type { EffectiveAuthority } from '@abloatai/transaction/auth';
+
+/** Stable server-authored times shared by commit boundary fixtures. */
+export const COMMIT_FIXTURE_TIMES = {
+  createdAt: '2026-08-05T10:00:00.000Z',
+  statusAt: '2026-08-05T10:00:00.058Z',
+} as const;
+
+/** Canonical authenticated authority for transport-boundary test responses. */
+export const EFFECTIVE_AUTHORITY_FIXTURE = {
+  organizationId: 'org-1',
+  projectId: 'project-1',
+  branchId: 'branch-1',
+  syncGroups: ['org:org-1'],
+  operations: [],
+  participantKind: 'agent',
+  participantId: 'agent-1',
+  deliveryPartition: null,
+} satisfies EffectiveAuthority;
+
+/** A canonical hosted confirmation returned by HTTP or WebSocket. */
+export function confirmedCommitReceiptResponse(args: {
+  clientTxId: string;
+  lastSyncId?: number;
+  serverTxId?: string;
+  ops?: number;
+}): CommitReceiptWire {
+  const lastSyncId = args.lastSyncId ?? 0;
+  return {
+    object: 'commit_receipt',
+    clientTxId: args.clientTxId,
+    serverTxId: args.serverTxId ?? String(lastSyncId),
+    ...COMMIT_FIXTURE_TIMES,
+    success: true,
+    authority: EFFECTIVE_AUTHORITY_FIXTURE,
+    status: 'confirmed',
+    lastSyncId,
+    ops: args.ops ?? 1,
+  } satisfies CommitReceiptWire;
+}
+
+/** Canonical normalized acknowledgement for mutation-executor test doubles. */
+export function confirmedCommitAck(lastSyncId = 0): CommitAck {
+  return {
+    status: 'confirmed',
+    statusAt: COMMIT_FIXTURE_TIMES.statusAt,
+    lastSyncId,
+  } satisfies CommitAck;
+}
 
 /** `GET /v1/models/{model}/{id}`. Pass `data: null` for a miss. */
 export function modelReadResponse(args: {
@@ -51,14 +102,22 @@ export function modelListResponse(args: {
   hasMore?: boolean;
   nextCursor?: string | null;
   stamp?: number;
+  evidence?: readonly { id: string; stamp: number }[];
 }): ModelListResponse {
+  const stamp = args.stamp ?? 0;
+  const inferredEvidence = args.data.flatMap((row): { id: string; stamp: number }[] => {
+    if (typeof row !== 'object' || row === null) return [];
+    const id = (row as { id?: unknown }).id;
+    return typeof id === 'string' ? [{ id, stamp }] : [];
+  });
   return {
     object: 'list',
     model: args.model,
     data: [...args.data],
     has_more: args.hasMore ?? false,
     next_cursor: args.nextCursor ?? null,
-    stamp: args.stamp ?? 0,
+    stamp,
+    evidence: [...(args.evidence ?? inferredEvidence)],
   } satisfies ModelListResponse;
 }
 

package/src/transactionLayer.ts

@@ -30,7 +30,7 @@ import type { ModelScope } from './types/index.js';
 
 /**
  * A commit's durable acceptance — `{ status: 'queued' }` with the correlation
- * the settlement feed later confirms. The wire layer owns the receipt fields;
+ * the confirmation feed later confirms. The wire layer owns the receipt fields;
  * the seam adds the client idempotency identity needed for a safe wait/retry.
  */
 export type CommitReceipt = ClientCommitReceipt & {