@abloatai/transaction 0.47.0 → 0.49.0

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,
@@ -644,7 +657,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
     '/v1/branches/{id}/status': {
       get: {
         tags: ['branches'],
-        summary: 'Diagnose one branch plane',
+        summary: 'Diagnose one branch',
         description:
           'Returns branch lifecycle, active schema, compatibility with the parent schema, safe datasource coordinates, and readiness blockers.',
         parameters: [idParam()],
@@ -699,7 +712,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         description:
           'One round trip per cadence for a worker holding many rows, instead of ' +
           'one per row. Takes only `ttl`; the leases are whichever ones your ' +
-          'credential holds on this plane.',
+          'credential holds on this branch.',
         requestBody: optionalJsonBody(derive(claimHeartbeatRequestSchema, 'input')),
         responses: {
           '200': namedResp(
@@ -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: {
@@ -812,7 +823,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         tags: ['schema'],
         summary: 'What the models look like',
         description:
-          "The schema deployed on your credential's plane: every model with its " +
+          "The schema deployed on your credential's branch: every model with its " +
           'fields, their types, and its relations. Read this when you have no ' +
           'local schema declaration to read types from — it is what makes a ' +
           'field typo a local check rather than a rejected write. Each model ' +
@@ -835,7 +846,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
           'How a caller without a socket learns what its peers did. Omit ' +
           '`after` for the most recent entries, then copy each page\'s ' +
           '`next_cursor` back as `after` to walk forward. Scope is taken from ' +
-          'your key — organization, plane and sync groups — so a caller cannot ' +
+          'your key — organization, branch and sync groups — so a caller cannot ' +
           'widen what it sees by asking.',
         parameters: queryParams(logQuerySchema),
         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;
 }

package/src/source/index.ts

@@ -192,5 +192,5 @@ export {
   type FootprintArtifact,
   type FootprintKind,
   type FootprintNames,
-  type FootprintPlane,
+  type DataSourceIdentity,
 } from '../footprint.js';

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 & {

package/src/transactions/{settlement → confirmation}/commitEnvelope.ts

@@ -8,7 +8,12 @@
  */
 
 import { z } from 'zod';
-import { readDependencySchema, trackDependencySchema } from '../../coordination/schema.js';
+import {
+  MAX_READ_SET_ENTRIES,
+  readDependencyListSchema,
+  readSetProjectionEntryCount,
+  trackDependencyListSchema,
+} from '../../coordination/schema.js';
 import { wireCommitOperationSchema } from '../../wire/frames.js';
 import { correlationIdSchema } from '../../wire/commit.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
@@ -41,6 +46,7 @@ export const durableCommitOperationSchema = wireCommitOperationSchema
     id: true,
     input: true,
     transactionId: true,
+    claimId: true,
     readAt: true,
     onStale: true,
     fenceToken: true,
@@ -50,6 +56,7 @@ export const durableCommitOperationSchema = wireCommitOperationSchema
     id: z.string().min(1),
     input: z.record(z.string(), z.unknown()).optional(),
     transactionId: z.string().min(1).optional(),
+    claimId: z.string().min(1).optional(),
     options: z
       .strictObject({
         idempotencyKey: z.string().min(1).max(255).nullable().optional(),
@@ -62,8 +69,11 @@ export type DurableCommitOperation = z.infer<typeof durableCommitOperationSchema
 export type DurableCommitOperationInput = z.input<typeof durableCommitOperationSchema>;
 
 const durableCommitOptionsSchema = z.strictObject({
-  reads: z.array(readDependencySchema).nullable().optional(),
-  track: z.array(trackDependencySchema).nullable().optional(),
+  reads: readDependencyListSchema.nullable().optional(),
+  track: trackDependencyListSchema.nullable().optional(),
+}).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 const commitOutboxScopeSchema = z.strictObject({

package/src/transport/commitFrames.ts

@@ -53,6 +53,7 @@ export interface CommitFrameOperation {
   readonly id: string;
   readonly input?: Record<string, unknown>;
   readonly transactionId?: string;
+  readonly claimId?: string | null;
   readonly readAt?: number | null;
   readonly onStale?: OnStaleMode | null;
   readonly fenceToken?: number | null;
@@ -80,17 +81,18 @@ export function buildCommitFrame(
       id: op.id,
       input: op.input,
       transactionId: op.transactionId,
+      claimId: op.claimId,
       readAt: op.readAt,
       onStale: op.onStale,
       fenceToken: op.fenceToken,
     })),
     clientTxId,
   };
-  // The batch premise: the rows or groups the writer read before committing.
-  if (reads && reads.length > 0) payload.reads = [...reads];
-  // Durable premises the writer is registering: the rows or groups it
-  // wants to keep hearing about after this commit, delivered on a future receipt.
-  if (track && track.length > 0) payload.track = [...track];
+  // Preserve declaration at the wire boundary. `null`, an explicit empty list,
+  // and omission are distinct inputs even when today's server treats each as
+  // "none"; the WebSocket path must not silently erase a field the caller set.
+  if (reads !== undefined) payload.reads = reads === null ? null : [...reads];
+  if (track !== undefined) payload.track = track === null ? null : [...track];
   return { type: 'commit', payload };
 }
 

package/src/transport/connectionManager.ts

@@ -15,7 +15,7 @@
  * first successful connect and disposed on teardown.
  *
  * This is a plain state machine, not a reactive object: it lives in the
- * settlement core, which carries no reactivity runtime (ADR 0016). A consumer
+ * confirmation core, which carries no reactivity runtime (ADR 0016). A consumer
  * that wants to render recovery progress mirrors the transitions through
  * {@link ConnectionCallbacks.onStateChange} into its own observable state —
  * which is what the reactive engine's store does.