@abloatai/transaction 0.56.0 → 0.58.0

package/src/{resources → client/resources}/modelOperations.ts

@@ -5,19 +5,18 @@
  * These types describe the *change or the query being requested*, never a local
  * 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
+ * binds them to reactive model instances — `createModelOperations` — stays with the
  * reactive consumer, along with `ModelOperations` and `ModelCollaboration`,
  * which reference the live participant handle.
  */
 
-import type { ModelScope } from '../types/index.js';
-import type { ResolveClaimMeta } from '../types/global.js';
-import type { AbloError } from '../errors.js';
-import type { StaleNotification, TrackDependency } from '../coordination/schema.js';
-import type { FieldRef, FieldSelector } from '../schema/fieldRef.js';
-import type { BaseModelFields } from '../schema/schema.js';
-import type { ClaimHeartbeatPlan } from '../coordination/claimHeartbeatLoop.js';
-import type { Duration } from '../utils/duration.js';
+import type { ModelScope } from '../../types/index.js';
+import type { ResolveClaimMeta } from '../../types/global.js';
+import type { AbloError } from '../../errors.js';
+import type { FieldRef, FieldSelector } from '../../schema/fieldRef.js';
+import type { BaseModelFields, Clearable } from '../../schema/schema.js';
+import type { ClaimHeartbeatPlan } from '../../claims/heartbeat.js';
+import type { Duration } from '../../utils/duration.js';
 import type {
   Claim,
   ClaimHeartbeat,
@@ -25,7 +24,7 @@ import type {
   HeldClaim,
   HeldLease,
   Peer,
-} from '../types/streams.js';
+} from '../../types/streams.js';
 import type { MutationOptions } from './mutationOptions.js';
 import type { LoadWhere } from './where.js';
 
@@ -142,34 +141,6 @@ export function claimAttemptFailure(
  */
 export type ModelListScope = ModelScope | `${ModelScope}`;
 
-/**
- * Options for `track({ id })` — register a durable premise on a row.
- *
- * Derived from the wire's row-form {@link TrackDependency} rather than restated
- * beside it: the caller names the row and, optionally, the watermark it is
- * premised on, while `model` comes from the proxy the call was made on. Adding
- * a field to the dependency therefore reaches this surface automatically, and
- * removing one stops the callers compiling.
- *
- * On `readAt`: omit it to baseline at the current head — "tell me about
- * anything from here on". Pass a known watermark (the one you read the row at)
- * to also catch a change that landed between that read and this call.
- */
-export type ModelTrackParams = Omit<
-  Extract<TrackDependency, { model: string }>,
-  'model'
->;
-
-/** The result of `track({ id })`. */
-export interface ModelTrackResult {
-  /**
-   * Tracks that had ALREADY fired at registration time — a change matching an
-   * open track that landed before this call. Present only when something was
-   * already stale; the ongoing signal arrives on the receipts of later commits.
-   */
-  notifications?: StaleNotification[];
-}
-
 /** Options for the synchronous local-graph reads `local.list` and `onChange` —
  *  a JavaScript `filter`, an equality `where`, and a lifecycle `state`. This is
  *  the local, reactive axis; contrast {@link ServerReadOptions}, the
@@ -191,7 +162,7 @@ export type LocalCountOptions<T> = Pick<
   'where' | 'filter' | 'state'
 >;
 
-/** Options for the asynchronous server reads `get` and `list` — the
+/** Options for the asynchronous server reads `read` and `list` — the
  *  operator `where` filter, `type`, and `expand`. This is the server axis;
  *  contrast {@link LocalReadOptions}, the local, reactive axis. */
 export interface ServerReadOptions<T> {
@@ -232,11 +203,17 @@ export interface ServerReadOptions<T> {
   expand?: readonly string[];
 }
 
-/** Options for the single-row async server read `get({ id })`. A subset of
+/** Options for an explicit complete collection traversal. */
+export interface ListAllOptions<T> extends Omit<ServerReadOptions<T>, 'cursor'> {
+  /** Maximum pages to read before refusing an unexpectedly broad traversal. @default 100 */
+  maxPages?: number;
+  /** Stops traversal between page requests and row yields. */
+  signal?: AbortSignal;
+}
+
+/** Options for the single-row async server `read({ id })`. A subset of
  *  {@link ServerReadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
-export type ServerRetrieveOptions = Pick<ServerReadOptions<unknown>, 'type' | 'expand'>;
-/** Canonical point-lookup options; retained separately for compatibility naming. */
-export type ServerGetOptions = ServerRetrieveOptions;
+export type ServerPointReadOptions = Pick<ServerReadOptions<unknown>, 'type' | 'expand'>;
 /**
  * A claimable part of a row is a field declared by that model's Zod shape.
  *
@@ -527,15 +504,26 @@ export interface ClaimReadApi<T = Record<string, unknown>> {
  * stateless HTTP claim surface from the reactive {@link ClaimReadApi}.
  */
 export type AwaitedClaimMethod<F> = F extends (...args: infer A) => infer R
-  ? R extends Promise<unknown>
+  // `[R]` keeps the check non-distributive. `state` returns `Claim | null`, and
+  // a bare `R extends …` split that into two function types, one per union
+  // member, so the HTTP `state` was typed as a union of functions rather than
+  // one function returning the union. The cast that hid it is gone.
+  ? [R] extends [Promise<unknown>]
     ? (...args: A) => R
     : (...args: A) => Promise<R>
   : F;
 
-export interface ClaimApi<
+/**
+ * The four ways to take a claim. Already async on every transport, so this is
+ * the ONE definition of the callable half of a claim namespace: the reactive
+ * {@link ClaimApi} and the stateless {@link HttpClaimApi} both extend it, and an
+ * overload added here reaches both. (The two used to restate these by hand, and
+ * the row-free pair below existed on one surface and not the other.)
+ */
+export interface ClaimCall<
   T,
   Fields = T,
-> extends ClaimReadApi<T> {
+> {
   /**
    * The try-claim: `contention: { mode: 'skip' }` (or `queue: false`)
    * treats a held target as an expected outcome, not an error — it resolves
@@ -550,23 +538,31 @@ export interface ClaimApi<
    * Takes a claim and returns an explicit held-work handle — a {@link HeldClaim}.
    * `data`, `release`, `revoke`, and the async disposer are always present (this
    * call re-reads the row under the lease), so callers can use `handle.data`
-   * directly and `await using` works without a guard.
+   * directly and `await using` works without a guard. A row that does not
+   * exist rejects with `AbloNotFoundError` after the lease is given back; to
+   * hold a key before its row exists, use the id-only form below.
    */
   (params: ClaimParams<Fields>): Promise<HeldClaim<T>>;
   /** The row-free try-claim — `null` when the key is already held. */
   (id: string, opts: ClaimSkipOptions<Fields>): Promise<HeldLease | null>;
   /**
    * Takes a claim by id alone, for a row that lives only in the customer's own
-   * database — Ablo has never seen it, so there is nothing to re-read. Returns a
-   * {@link HeldLease}: the same lease controls as {@link HeldClaim}
-   * (`release`, `revoke`, `heartbeat`, `await using`) but no `.data`. Locking a
-   * key you know by id is exactly this — serialize writers without first
-   * syncing the row into Ablo.
+   * database or does not exist yet — Ablo has nothing to re-read, so no read is
+   * made after the grant. Returns a {@link HeldLease}: the same lease controls
+   * as {@link HeldClaim} (`release`, `revoke`, `heartbeat`, `await using`) but
+   * no `.data`. Locking a key you know by id is exactly this — serialize
+   * writers without first syncing the row into Ablo, or claim an id before
+   * creating its row so two actors cannot both create it.
    */
   (id: string, opts?: ClaimOptions<Fields>): Promise<HeldLease>;
 }
 
-export interface ModelRetrieveParams extends ServerRetrieveOptions {
+export interface ClaimApi<
+  T,
+  Fields = T,
+> extends ClaimReadApi<T>, ClaimCall<T, Fields> {}
+
+export interface ModelReadParams extends ServerPointReadOptions {
   readonly id: string;
 }
 
@@ -579,7 +575,10 @@ export interface ModelRetrieveParams extends ServerRetrieveOptions {
  * confirmation. Callers that need an earlier queued receipt use the lower-level
  * `commits.create` resource instead.
  */
-export type ModelWriteOptions = Omit<MutationOptions, 'wait'>;
+export type ModelWriteOptions = Omit<
+  MutationOptions,
+  'wait' | 'readAt' | 'fenceToken' | 'claimRef'
+>;
 
 export interface ModelCreateParams<T, CreateInput>
   extends ModelWriteOptions {
@@ -588,6 +587,21 @@ export interface ModelCreateParams<T, CreateInput>
   readonly claim?: Claim<T> | ClaimTargetOptions<CreateInput> | null;
 }
 
+/**
+ * Creating many rows at once: the same verb, handed a list.
+ *
+ * One atomic commit, so the batch lands whole or not at all, and the rows come
+ * back in the order they were given. There is no `id` beside `data` here the
+ * way there is for a single create, since one id cannot address many rows;
+ * write it into each row instead, which the create input has always allowed.
+ */
+export type ModelCreateManyParams<CreateInput> = Pick<
+  ModelWriteOptions,
+  'idempotencyKey' | 'reads'
+> & {
+  readonly data: readonly CreateInput[];
+};
+
 export interface ModelUpdateParams<T, Fields = T>
   extends ModelWriteOptions {
   readonly id: string;
@@ -595,8 +609,12 @@ export interface ModelUpdateParams<T, Fields = T>
    * Patch only fields declared by the model's Zod input shape. Hydrated rows
    * also carry framework fields, relations, methods, and computed values; none
    * of those are writable data.
+   *
+   * Send a field to change it, omit it to leave it, send `null` to clear it —
+   * see {@link Clearable}. `undefined` is not a clear: it is dropped from the
+   * payload and the old value survives.
    */
-  readonly data: Partial<ClaimableFields<Fields>>;
+  readonly data: Clearable<ClaimableFields<Fields>>;
   readonly claim?: Claim<T> | ClaimTargetOptions<Fields> | null;
 }
 

package/src/{resources → client/resources}/mutationOptions.ts

@@ -7,8 +7,8 @@
  * core rather than the reactive consumer (ADR 0013 §4, ADR 0016).
  */
 
-import type { CommitWait } from '../wire/commit.js';
-import type { OnStaleMode, ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { CommitWait } from '../../commit/contract.js';
+import type { ReadDependency } from '../../coordination/schema.js';
 
 /**
  * Per-call options accepted by any mutation, passed as the last argument.
@@ -27,7 +27,6 @@ export interface MutationOptions {
   label?: string;
   wait?: CommitWait;
   readAt?: number | null;
-  onStale?: OnStaleMode | null;
   /**
    * The fencing token (Option B) of the held claim this write belongs to. The
    * server validates it against the entity's persisted high-water and rejects a
@@ -43,24 +42,12 @@ export interface MutationOptions {
    * The batch premise — the answer to "did anything I looked at change?" Each
    * entry is a row (`{ model, id, readAt, fields? }`) or a sync group
    * (`{ group, readAt }`) that this write was premised on. The server checks
-   * that none of them moved since their `readAt` and applies the entry's
-   * `onStale` behavior to the whole batch. This is distinct from the per-operation
+   * that none of them moved since their `readAt`; a stale dependency rejects the
+   * whole batch. This is distinct from the per-operation
    * `readAt`, which guards only the row being written.
    *
    * See `packages/ablo/docs/concurrency-convention.md` (§3 the two
    * premises, §4 the batch premise) for the governing convention.
    */
   reads?: ReadDependency[] | null;
-  /**
-   * Durable premises — what this write (or the record it produces) should
-   * keep watching. Unlike `reads`, which is checked once at commit and discarded,
-   * each `track` entry is persisted and re-checked against every future delta; a
-   * later matching change opens a `StaleNotification` for the tracking participant,
-   * delivered at their next commit or live to a held claim. Each entry is a row
-   * (`{ model, id }`) or a sync group (`{ group }`), optionally pinned to a `readAt`
-   * baseline (defaults to this commit's watermark).
-   *
-   * See `packages/ablo/docs/groups.md` for how `track` drives propagation.
-   */
-  track?: TrackDependency[] | null;
 }

package/src/{resources → client/resources}/where.ts

@@ -15,7 +15,7 @@
 
 import { z } from 'zod';
 
-import { AbloValidationError } from '../errors.js';
+import { AbloValidationError } from '../../errors.js';
 
 /** Primitive operand types allowed in a where clause. */
 export const wherePrimitiveSchema = z.union([

package/src/{resources → client/resources}/writeOptionsSchema.ts

@@ -2,7 +2,7 @@
  * The Zod schema for write options — the settings accepted by every write
  * entry point, including `ablo.<model>.create/update/delete`, `commits.create`,
  * and the HTTP write routes. Each of those boundaries validates against this
- * one schema, so a caller who passes, say, `onStale: 'rejct'` fails right away
+ * one schema, so a caller who passes a malformed option fails right away
  * with a typed {@link AbloValidationError} at the call site instead of silently
  * or with a 400 from the server.
  *
@@ -17,25 +17,12 @@
  */
 
 import { z } from 'zod';
-import { logPositionSchema } from '../syncLog/contract.js';
-import type { MutationOptions } from '../resources/mutationOptions.js';
-import { AbloValidationError } from '../errors.js';
-import { commitWaitSchema } from '../wire/commit.js';
-import {
-  onStaleModeSchema,
-  MAX_READ_SET_ENTRIES,
-  readDependencyListSchema,
-  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
-// SDK barrel exports the name from this module. Declaring it twice put a second
-// object behind the public export that agreed with the canonical one only by
-// both happening to list the same three strings.
-export { onStaleModeSchema };
+import { logPositionSchema } from '../../syncLog/contract.js';
+import type { MutationOptions } from './mutationOptions.js';
+import { AbloValidationError } from '../../errors.js';
+import { commitWaitSchema } from '../../commit/contract.js';
+import { readDependencyListSchema } from '../../coordination/schema.js';
+import type { AssertExact } from '../../types/assertExact.js';
 
 export const writeOptionsSchema = z.object({
   /** Idempotency key the server records in `mutation_log` to make retries
@@ -47,8 +34,6 @@ export const writeOptionsSchema = z.object({
   wait: commitWaitSchema.optional(),
   /** Stale guard: the sync watermark the caller's reasoning was based on. */
   readAt: logPositionSchema.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
    *  rather than set by hand; the server validates it against the entity's
    *  high-water. Kept in the schema so it stays aligned with `MutationOptions`
@@ -61,11 +46,6 @@ export const writeOptionsSchema = z.object({
   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>;
@@ -107,3 +87,31 @@ const _writeOptionsContractInSync: AssertExact<
   keyof WriteOptionsContract
 > = true;
 void _writeOptionsContractInSync;
+
+/**
+ * Refuse a per-model write that does not name its row.
+ *
+ * `update` and `delete` address the row through the URL, so an absent `id`
+ * used to be spelled into the path by `encodeURIComponent` as the literal
+ * string `"undefined"`. The request was well-formed, it matched no row, and it
+ * came back as an ordinary receipt: `delete({ where: { id } })` reported
+ * success and deleted nothing. `{ where }` is the shape the commit protocol
+ * takes one layer down, so reaching for it here is an easy and quiet mistake.
+ *
+ * The typed surface already rejects it at compile time. This is the same
+ * refusal for callers who reach the transport without those types.
+ */
+export function assertWriteTarget(
+  action: 'update' | 'delete',
+  modelName: string,
+  id: unknown,
+): void {
+  if (typeof id === 'string' && id.length > 0) return;
+  const namedAFilter =
+    typeof id === 'object' && id !== null && 'where' in (id as Record<string, unknown>);
+  throw new AbloValidationError(
+    `A ${modelName} ${action} has to name the row it acts on: ${action}({ id })` +
+      (namedAFilter ? ', not a `where` filter.' : '.'),
+    { code: 'invalid_body', param: 'id' },
+  );
+}

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

@@ -8,14 +8,9 @@
  */
 
 import { z } from 'zod';
-import {
-  MAX_READ_SET_ENTRIES,
-  readDependencyListSchema,
-  readSetProjectionEntryCount,
-  trackDependencyListSchema,
-} from '../../coordination/schema.js';
+import { readDependencyListSchema } from '../../coordination/schema.js';
 import { wireCommitOperationSchema } from '../../wire/frames.js';
-import { correlationIdSchema } from '../../wire/commit.js';
+import { correlationIdSchema } from '../contract.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
 import { snapshotJsonValue } from '../../utils/json.js';
 
@@ -48,7 +43,6 @@ export const durableCommitOperationSchema = wireCommitOperationSchema
     transactionId: true,
     claimId: true,
     readAt: true,
-    onStale: true,
     fenceToken: true,
   })
   .extend({
@@ -70,10 +64,6 @@ export type DurableCommitOperationInput = z.input<typeof durableCommitOperationS
 
 const durableCommitOptionsSchema = z.strictObject({
   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/{transactions → commit}/confirmation/httpCommitEnvelope.ts

@@ -3,7 +3,7 @@
 import { z } from 'zod';
 import { v5 as uuidv5 } from 'uuid';
 import { snapshotJsonValue, stableStringify } from '../../utils/json.js';
-import { correlationIdSchema } from '../../wire/commit.js';
+import { correlationIdSchema } from '../contract.js';
 import { PROTOCOL_VERSION } from '../../wire/protocolVersion.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
 

package/src/{transactions → commit}/confirmation/pendingWrite.ts

@@ -8,7 +8,7 @@
  * this module only unions them.
  *
  * The port that persists these records is a behavior contract, not a persisted
- * shape, so it lives outside this directory in `src/durableWrites.ts`.
+ * shape, so it lives outside this directory in `src/commit/durableWrites.ts`.
  */
 
 import { z } from 'zod';

package/src/{wire/commit.ts → commit/contract.ts}

@@ -20,15 +20,8 @@
 import { z } from 'zod';
 import { logPositionSchema } from '../syncLog/contract.js';
 import {
-  onStaleModeSchema,
-  MAX_READ_SET_ENTRIES,
   readDependencyListSchema,
-  readSetRowTargetSchema,
-  readSetProjectionEntryCount,
-  readSetSchema,
   participantKindSchema,
-  staleNotificationSchema,
-  trackDependencyListSchema,
 } from '../coordination/schema.js';
 import type { ErrorCode } from '../errorCodes.js';
 import { requiredCapabilityWireSchema } from '../errors.js';
@@ -100,7 +93,6 @@ export const commitWaitSchema = z.union([queuedStatusSchema, confirmedStatusSche
 export type CommitWait = z.infer<typeof commitWaitSchema>;
 
 const missingIdsSchema = z.array(z.string().min(1));
-const notificationsSchema = z.array(staleNotificationSchema);
 
 export const commitOperationOutcomeSchema = z.enum([
   'created',
@@ -143,7 +135,12 @@ export type CommitAttempt = z.infer<typeof commitAttemptSchema>;
 
 export const commitClaimReferenceSchema = z.strictObject({
   id: z.string().min(1),
-  target: readSetRowTargetSchema,
+  target: z.strictObject({
+    scope: z.literal('row'),
+    model: z.string(),
+    id: z.string(),
+    fields: z.array(z.string()).readonly().optional(),
+  }),
   fenceToken: z.number().int().nonnegative(),
 });
 export type CommitClaimReference = z.infer<typeof commitClaimReferenceSchema>;
@@ -178,7 +175,6 @@ const successfulReceiptCommonShape = {
   success: z.literal(true),
   ops: z.number().int().nonnegative(),
   authority: effectiveAuthoritySchema,
-  notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   /** Exact rows returned by the writing transaction; absent on durable replay. */
   operationResults: operationResultsSchema.optional(),
@@ -266,7 +262,6 @@ const executionEvidenceShape = {
     firstSyncId: z.number().int().nonnegative(),
     createdAt: commitTimestampSchema,
     confirmationTransactionIds: confirmationTransactionIdsSchema.optional(),
-    notifications: notificationsSchema.optional(),
     missingIds: missingIdsSchema.optional(),
 } as const;
 
@@ -341,7 +336,6 @@ export type CommitExecutionResultInput = z.input<typeof commitExecutionResultSch
 export type CommitExecutionResult = z.infer<typeof commitExecutionResultSchema>;
 
 const ackCommonShape = {
-  notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   operationResults: operationResultsSchema.optional(),
 } as const;
@@ -376,7 +370,6 @@ export const clientCommitReceiptSchema = z.strictObject({
   id: z.string().min(1),
   status: z.union([queuedStatusSchema, confirmedStatusSchema]),
   lastSyncId: logPositionSchema.optional(),
-  notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   operationResults: operationResultsSchema.optional(),
 });
@@ -401,14 +394,28 @@ export const commitOperationControlShape = {
   transactionId: z.string().nullish(),
   claimId: z.string().min(1).nullish(),
   readAt: logPositionSchema.nullish(),
-  onStale: onStaleModeSchema.nullish(),
   fenceToken: z.number().nullish(),
 };
 
+/** Canonical public spelling of a model operation. */
+export const modelOperationActionSchema = z.enum([
+  'create',
+  'update',
+  'delete',
+  'archive',
+  'unarchive',
+]);
+export type ModelOperationAction = z.infer<typeof modelOperationActionSchema>;
+
+/** Convert a storage operation verb into the canonical lowercase commit action. */
+export function normalizeStorageOperationAction(value: string): ModelOperationAction {
+  return modelOperationActionSchema.parse(value.toLowerCase());
+}
+
 /** One write inside a commit, in the canonical spelling. */
 export const commitOperationBodySchema = z.object({
   ...commitOperationControlShape,
-  action: z.string(),
+  action: modelOperationActionSchema,
   model: z.string(),
   data: z.record(z.string(), z.unknown()).nullish(),
   where: z.record(z.string().min(1), z.unknown()).nullish(),
@@ -427,7 +434,6 @@ export const commitReceiptEvidenceSchema = z.strictObject({
   clientTxId: z.string().min(1),
   serverTxId: z.string(),
   ops: z.number().int().nonnegative().optional(),
-  notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   error: commitErrorSchema.optional(),
 });
@@ -436,18 +442,13 @@ export type CommitReceiptEvidence = z.infer<typeof commitReceiptEvidenceSchema>;
 /**
  * The `POST /v1/commits` request body.
  *
- * `operations` carries the writes; `track` registers durable premises.
- * Neither is required on its own, because a body with `track` and no
- * `operations` is how a caller starts watching a row without writing to it.
- * Request identity travels in the `Idempotency-Key` header.
+ * `operations` carries the writes and `reads` carries the compact row evidence
+ * those writes were based on. Request identity travels in the
+ * `Idempotency-Key` header.
  */
 export const commitRequestSchema = z.strictObject({
-  operations: z.array(commitOperationBodySchema).min(1).optional(),
+  operations: z.array(commitOperationBodySchema).min(1),
   reads: readDependencyListSchema.nullish(),
-  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 CommitRequest = z.infer<typeof commitRequestSchema>;
 
@@ -459,7 +460,7 @@ const commitRecordEvidenceShape = {
     id: z.string().min(1),
     ...commitEvidenceShape,
     createdAt: commitTimestampSchema,
-    readSet: readSetSchema,
+    reads: readDependencyListSchema.readonly(),
     operations: z.array(commitRecordOperationSchema).readonly(),
     receipt: commitReceiptEvidenceSchema,
 } as const;

package/src/{durableWrites.ts → commit/durableWrites.ts}

@@ -2,18 +2,18 @@
  * The durable-write port and the option that installs it.
  *
  * Owns the persistence contract behind `Ablo({ durableWrites })` — a behavior
- * contract of methods, not a serialized shape, which is why it lives here
- * rather than in `transactions/confirmation/`. The records that cross this port
- * are owned by `pendingWriteSchema` there; this module never redescribes them.
+ * contract of methods, not a serialized shape, which is why it lives beside
+ * rather than inside `confirmation/`. The records that cross this port
+ * are owned by `confirmation/pendingWrite.ts`; this module never redescribes them.
  *
  * The engine consumes the port through `commitOutboxStore`, and the HTTP client
- * accepts the same option through `transport/httpOptions`.
+ * accepts the same option through `transport/http/options`.
  */
 
 import { z } from 'zod';
-import { AbloValidationError } from './errors.js';
-import type { CommitOutboxScope } from './transactions/confirmation/commitEnvelope.js';
-import type { PendingWrite } from './transactions/confirmation/pendingWrite.js';
+import { AbloValidationError } from '../errors.js';
+import type { CommitOutboxScope } from './confirmation/commitEnvelope.js';
+import type { PendingWrite } from './confirmation/pendingWrite.js';
 
 /**
  * Persistence port used by `Ablo({ durableWrites })`.