@abloatai/ablo 0.34.1 → 0.35.0

package/dist/{wire → transaction/wire}/commit.d.ts

@@ -18,7 +18,6 @@
  */
 import { z } from 'zod';
 import type { ErrorCode } from '../errorCodes.js';
-import type { RequiredCapability } from '../errors.js';
 /** Matches the permanent source/idempotency-key ceiling. */
 export declare const COMMIT_CORRELATION_ID_MAX_LENGTH = 255;
 /** Opaque server-authored identity shared by a queued receipt and its authoritative source delta. */
@@ -29,6 +28,24 @@ export declare const commitStatusSchema: z.ZodEnum<{
     confirmed: "confirmed";
 }>;
 export type CommitStatus = z.infer<typeof commitStatusSchema>;
+/**
+ * The settlement states a write may block on — extracted from the reported
+ * vocabulary above, never restated beside it. `commitStatusSchema` is every
+ * state a server can report; this is the subset a caller can usefully wait for,
+ * and the two are not the same question: one describes an outcome, the other a
+ * request.
+ *
+ * `.extract` keeps the relationship mechanical in both directions. Renaming a
+ * settlement state breaks this line at build time, and adding one that nobody
+ * can block on — a commit parked for a human, say — does not become a legal
+ * `wait` merely by being added above. Both the `wait` option's runtime
+ * validator and its interface derive from here, so they cannot disagree.
+ */
+export declare const commitWaitSchema: z.ZodEnum<{
+    queued: "queued";
+    confirmed: "confirmed";
+}>;
+export type CommitWait = z.infer<typeof commitWaitSchema>;
 /** The one settlement discriminant shared by every commit boundary. */
 export declare const commitSettlementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     status: z.ZodLiteral<"queued">;
@@ -104,72 +121,6 @@ export declare const commitReceiptSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     missingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>], "status">;
 export type CommitReceiptWire = z.infer<typeof commitReceiptSchema>;
-/**
- * Compatibility decoder for pre-contract WebSocket acknowledgements. It
- * supplies fields old servers omitted and normalizes their string sync ids,
- * then hands the result to the exact same canonical receipt schema. It never
- * invents a source correlation: an old/malformed queued receipt still fails
- * closed.
- */
-export declare const legacyCompatibleCommitReceiptSchema: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
-    status: z.ZodLiteral<"queued">;
-    correlationId: z.ZodString;
-    object: z.ZodLiteral<"commit_receipt">;
-    id: z.ZodOptional<z.ZodString>;
-    clientTxId: z.ZodString;
-    serverTxId: z.ZodString;
-    success: z.ZodLiteral<true>;
-    lastSyncId: z.ZodNumber;
-    ops: z.ZodNumber;
-    notifications: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        object: z.ZodOptional<z.ZodLiteral<"stale_notification">>;
-        model: z.ZodString;
-        id: z.ZodString;
-        readAt: z.ZodNumber;
-        observedSyncId: z.ZodNumber;
-        conflictingFields: z.ZodArray<z.ZodString>;
-        currentValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        writtenBy: z.ZodObject<{
-            kind: z.ZodEnum<{
-                user: "user";
-                agent: "agent";
-                system: "system";
-            }>;
-            id: z.ZodString;
-        }, z.core.$strip>;
-        group: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-    missingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>, z.ZodObject<{
-    status: z.ZodLiteral<"confirmed">;
-    correlationId: z.ZodOptional<z.ZodString>;
-    object: z.ZodLiteral<"commit_receipt">;
-    id: z.ZodOptional<z.ZodString>;
-    clientTxId: z.ZodString;
-    serverTxId: z.ZodString;
-    success: z.ZodLiteral<true>;
-    lastSyncId: z.ZodNumber;
-    ops: z.ZodNumber;
-    notifications: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        object: z.ZodOptional<z.ZodLiteral<"stale_notification">>;
-        model: z.ZodString;
-        id: z.ZodString;
-        readAt: z.ZodNumber;
-        observedSyncId: z.ZodNumber;
-        conflictingFields: z.ZodArray<z.ZodString>;
-        currentValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        writtenBy: z.ZodObject<{
-            kind: z.ZodEnum<{
-                user: "user";
-                agent: "agent";
-                system: "system";
-            }>;
-            id: z.ZodString;
-        }, z.core.$strip>;
-        group: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-    missingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>], "status">>;
 /** The failure arm is separate: queued/confirmed always imply `success:true`. */
 export declare const rejectedCommitReceiptSchema: z.ZodObject<{
     object: z.ZodLiteral<"commit_receipt">;
@@ -183,7 +134,13 @@ export declare const rejectedCommitReceiptSchema: z.ZodObject<{
         code: z.ZodCustom<ErrorCode, ErrorCode>;
         message: z.ZodString;
         field: z.ZodOptional<z.ZodString>;
-        requiredCapability: z.ZodOptional<z.ZodCustom<RequiredCapability, RequiredCapability>>;
+        requiredCapability: z.ZodOptional<z.ZodObject<{
+            scope: z.ZodString;
+            constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>>;
+            issuer: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+            ttlSeconds: z.ZodPreprocess<z.ZodOptional<z.ZodNumber>>;
+            nonce: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+        }, z.core.$loose>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type RejectedCommitReceiptWire = z.infer<typeof rejectedCommitReceiptSchema>;
@@ -257,7 +214,13 @@ export declare const mutationResultPayloadSchema: z.ZodUnion<readonly [z.ZodDisc
         code: z.ZodCustom<ErrorCode, ErrorCode>;
         message: z.ZodString;
         field: z.ZodOptional<z.ZodString>;
-        requiredCapability: z.ZodOptional<z.ZodCustom<RequiredCapability, RequiredCapability>>;
+        requiredCapability: z.ZodOptional<z.ZodObject<{
+            scope: z.ZodString;
+            constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>>;
+            issuer: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+            ttlSeconds: z.ZodPreprocess<z.ZodOptional<z.ZodNumber>>;
+            nonce: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+        }, z.core.$loose>>;
     }, z.core.$strip>;
 }, z.core.$strip>]>;
 export type MutationResultPayload = z.infer<typeof mutationResultPayloadSchema>;
@@ -333,7 +296,13 @@ export declare const mutationResultMessageSchema: z.ZodObject<{
             code: z.ZodCustom<ErrorCode, ErrorCode>;
             message: z.ZodString;
             field: z.ZodOptional<z.ZodString>;
-            requiredCapability: z.ZodOptional<z.ZodCustom<RequiredCapability, RequiredCapability>>;
+            requiredCapability: z.ZodOptional<z.ZodObject<{
+                scope: z.ZodString;
+                constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>>;
+                issuer: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+                ttlSeconds: z.ZodPreprocess<z.ZodOptional<z.ZodNumber>>;
+                nonce: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+            }, z.core.$loose>>;
         }, z.core.$strip>;
     }, z.core.$strip>]>;
 }, z.core.$strip>;
@@ -461,11 +430,12 @@ export declare const commitAckSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strict>], "status">;
 export type CommitAck = z.infer<typeof commitAckSchema>;
 /**
- * Compatibility boundary for injected/older mutation executors. New
- * transports return `commitAckSchema`; a legacy `{lastSyncId}` is normalized
- * to explicit confirmed settlement before queue code branches on it.
+ * The boundary an injected mutation executor returns through. It is the
+ * acknowledgement schema itself: settlement is declared, never inferred from
+ * an omission, so a transport cannot report a write as landed by staying
+ * silent about how it landed.
  */
-export declare const mutationCommitResultSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const mutationCommitResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     status: z.ZodLiteral<"queued">;
     correlationId: z.ZodString;
     lastSyncId: z.ZodNumber;
@@ -511,125 +481,7 @@ export declare const mutationCommitResultSchema: z.ZodPipe<z.ZodUnion<readonly [
         group: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     missingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>], "status">, z.ZodObject<{
-    status: z.ZodOptional<z.ZodUndefined>;
-    correlationId: z.ZodOptional<z.ZodUndefined>;
-    lastSyncId: z.ZodNumber;
-    notifications: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        object: z.ZodOptional<z.ZodLiteral<"stale_notification">>;
-        model: z.ZodString;
-        id: z.ZodString;
-        readAt: z.ZodNumber;
-        observedSyncId: z.ZodNumber;
-        conflictingFields: z.ZodArray<z.ZodString>;
-        currentValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        writtenBy: z.ZodObject<{
-            kind: z.ZodEnum<{
-                user: "user";
-                agent: "agent";
-                system: "system";
-            }>;
-            id: z.ZodString;
-        }, z.core.$strip>;
-        group: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-    missingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>]>, z.ZodTransform<{
-    status: "queued";
-    correlationId: string;
-    lastSyncId: number;
-    notifications?: {
-        model: string;
-        id: string;
-        readAt: number;
-        observedSyncId: number;
-        conflictingFields: string[];
-        currentValues: Record<string, unknown>;
-        writtenBy: {
-            kind: "user" | "agent" | "system";
-            id: string;
-        };
-        object?: "stale_notification" | undefined;
-        group?: string | undefined;
-    }[] | undefined;
-    missingIds?: string[] | undefined;
-} | {
-    status: "confirmed";
-    lastSyncId: number;
-    correlationId?: string | undefined;
-    notifications?: {
-        model: string;
-        id: string;
-        readAt: number;
-        observedSyncId: number;
-        conflictingFields: string[];
-        currentValues: Record<string, unknown>;
-        writtenBy: {
-            kind: "user" | "agent" | "system";
-            id: string;
-        };
-        object?: "stale_notification" | undefined;
-        group?: string | undefined;
-    }[] | undefined;
-    missingIds?: string[] | undefined;
-}, {
-    status: "queued";
-    correlationId: string;
-    lastSyncId: number;
-    notifications?: {
-        model: string;
-        id: string;
-        readAt: number;
-        observedSyncId: number;
-        conflictingFields: string[];
-        currentValues: Record<string, unknown>;
-        writtenBy: {
-            kind: "user" | "agent" | "system";
-            id: string;
-        };
-        object?: "stale_notification" | undefined;
-        group?: string | undefined;
-    }[] | undefined;
-    missingIds?: string[] | undefined;
-} | {
-    status: "confirmed";
-    lastSyncId: number;
-    correlationId?: string | undefined;
-    notifications?: {
-        model: string;
-        id: string;
-        readAt: number;
-        observedSyncId: number;
-        conflictingFields: string[];
-        currentValues: Record<string, unknown>;
-        writtenBy: {
-            kind: "user" | "agent" | "system";
-            id: string;
-        };
-        object?: "stale_notification" | undefined;
-        group?: string | undefined;
-    }[] | undefined;
-    missingIds?: string[] | undefined;
-} | {
-    lastSyncId: number;
-    status?: undefined;
-    correlationId?: undefined;
-    notifications?: {
-        model: string;
-        id: string;
-        readAt: number;
-        observedSyncId: number;
-        conflictingFields: string[];
-        currentValues: Record<string, unknown>;
-        writtenBy: {
-            kind: "user" | "agent" | "system";
-            id: string;
-        };
-        object?: "stale_notification" | undefined;
-        group?: string | undefined;
-    }[] | undefined;
-    missingIds?: string[] | undefined;
-}>>;
+}, z.core.$strict>], "status">;
 export type MutationCommitResultInput = z.input<typeof mutationCommitResultSchema>;
 export type MutationCommitResult = z.infer<typeof mutationCommitResultSchema>;
 /**
@@ -669,3 +521,83 @@ export declare const clientCommitReceiptSchema: z.ZodObject<{
     missingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type ClientCommitReceipt = z.infer<typeof clientCommitReceiptSchema>;
+/** Control fields any operation in a commit may carry. */
+export declare const commitOperationControlShape: {
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>>;
+    fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+};
+/** One write inside a commit, in the canonical spelling. */
+export declare const commitOperationBodySchema: z.ZodObject<{
+    action: z.ZodString;
+    model: z.ZodString;
+    data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>>;
+    fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export type CommitOperationBody = z.infer<typeof commitOperationBodySchema>;
+/**
+ * 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.
+ */
+export declare const commitRequestSchema: z.ZodObject<{
+    operations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        action: z.ZodString;
+        model: z.ZodString;
+        data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>>;
+    reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        model: z.ZodString;
+        id: z.ZodString;
+        readAt: z.ZodNumber;
+        fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        onStale: z.ZodOptional<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        group: z.ZodString;
+        readAt: z.ZodNumber;
+        onStale: z.ZodOptional<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>;
+    }, z.core.$strip>]>>>>;
+    track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        model: z.ZodString;
+        id: z.ZodString;
+        readAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        group: z.ZodString;
+        readAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>>>;
+}, z.core.$strip>;
+export type CommitRequest = z.infer<typeof commitRequestSchema>;

package/dist/{wire → transaction/wire}/commit.js

@@ -17,12 +17,27 @@
  * one giant object.
  */
 import { z } from 'zod';
-import { staleNotificationSchema } from '../coordination/schema.js';
+import { onStaleModeSchema, readDependencySchema, staleNotificationSchema, trackDependencySchema, } from '../coordination/schema.js';
+import { requiredCapabilityWireSchema } from '../errors.js';
 /** Matches the permanent source/idempotency-key ceiling. */
 export const COMMIT_CORRELATION_ID_MAX_LENGTH = 255;
 /** Opaque server-authored identity shared by a queued receipt and its authoritative source delta. */
 export const correlationIdSchema = z.string().min(1).max(COMMIT_CORRELATION_ID_MAX_LENGTH);
 export const commitStatusSchema = z.enum(['queued', 'confirmed']);
+/**
+ * The settlement states a write may block on — extracted from the reported
+ * vocabulary above, never restated beside it. `commitStatusSchema` is every
+ * state a server can report; this is the subset a caller can usefully wait for,
+ * and the two are not the same question: one describes an outcome, the other a
+ * request.
+ *
+ * `.extract` keeps the relationship mechanical in both directions. Renaming a
+ * settlement state breaks this line at build time, and adding one that nobody
+ * can block on — a commit parked for a human, say — does not become a legal
+ * `wait` merely by being added above. Both the `wait` option's runtime
+ * validator and its interface derive from here, so they cannot disagree.
+ */
+export const commitWaitSchema = commitStatusSchema.extract(['queued', 'confirmed']);
 const queuedSettlementShape = {
     status: z.literal('queued'),
     correlationId: correlationIdSchema,
@@ -91,41 +106,13 @@ export const commitReceiptSchema = z.discriminatedUnion('status', [
     confirmedCommitReceiptSchema,
 ]);
 /**
- * Compatibility decoder for pre-contract WebSocket acknowledgements. It
- * supplies fields old servers omitted and normalizes their string sync ids,
- * then hands the result to the exact same canonical receipt schema. It never
- * invents a source correlation: an old/malformed queued receipt still fails
- * closed.
+ * The rejection code is deliberately not narrowed to the {@link ErrorCode}
+ * registry. A newer server may reject a commit with a code this build predates,
+ * and failing the whole receipt over an unrecognized string would turn a
+ * readable rejection into an opaque parse error. `errorCodes.ts` sanctions this
+ * single boundary cast; every code *producer* is constrained at the
+ * `AbloError` constructor instead.
  */
-export const legacyCompatibleCommitReceiptSchema = z.preprocess((value) => {
-    if (typeof value !== 'object' || value === null)
-        return value;
-    const receipt = value;
-    if (receipt.success !== true)
-        return value;
-    const rawLastSyncId = receipt.lastSyncId;
-    const numericLastSyncId = typeof rawLastSyncId === 'string' && rawLastSyncId.trim().length > 0
-        ? Number(rawLastSyncId)
-        : rawLastSyncId;
-    const normalizedLastSyncId = typeof numericLastSyncId === 'number' &&
-        Number.isSafeInteger(numericLastSyncId) &&
-        numericLastSyncId >= 0
-        ? numericLastSyncId
-        : undefined;
-    return {
-        ...receipt,
-        object: receipt.object ?? 'commit_receipt',
-        status: receipt.status ?? 'confirmed',
-        serverTxId: typeof receipt.serverTxId === 'string'
-            ? receipt.serverTxId
-            : String(normalizedLastSyncId ?? 0),
-        ops: typeof receipt.ops === 'number' && Number.isSafeInteger(receipt.ops) ? receipt.ops : 0,
-        lastSyncId: normalizedLastSyncId ?? 0,
-    };
-}, commitReceiptSchema);
-const requiredCapabilitySchema = z.custom((value) => typeof value === 'object' &&
-    value !== null &&
-    typeof value.scope === 'string', { message: 'requiredCapability must contain a scope' });
 const errorCodeSchema = z.custom((value) => typeof value === 'string' && value.length > 0, { message: 'commit rejection code must be a non-empty string' });
 /** The failure arm is separate: queued/confirmed always imply `success:true`. */
 export const rejectedCommitReceiptSchema = z.object({
@@ -140,7 +127,7 @@ export const rejectedCommitReceiptSchema = z.object({
         code: errorCodeSchema,
         message: z.string(),
         field: z.string().optional(),
-        requiredCapability: requiredCapabilitySchema.optional(),
+        requiredCapability: requiredCapabilityWireSchema.optional(),
     }),
 });
 export const mutationResultPayloadSchema = z.union([
@@ -269,19 +256,13 @@ export const commitAckSchema = z.discriminatedUnion('status', [
         message: 'A source-confirmed acknowledgement requires a sync watermark',
     }),
 ]);
-const legacyMutationCommitResultSchema = z.strictObject({
-    ...ackCommonShape,
-    status: z.undefined().optional(),
-    correlationId: z.undefined().optional(),
-});
 /**
- * Compatibility boundary for injected/older mutation executors. New
- * transports return `commitAckSchema`; a legacy `{lastSyncId}` is normalized
- * to explicit confirmed settlement before queue code branches on it.
+ * The boundary an injected mutation executor returns through. It is the
+ * acknowledgement schema itself: settlement is declared, never inferred from
+ * an omission, so a transport cannot report a write as landed by staying
+ * silent about how it landed.
  */
-export const mutationCommitResultSchema = z
-    .union([commitAckSchema, legacyMutationCommitResultSchema])
-    .transform((result) => (result.status ? result : { ...result, status: 'confirmed' }));
+export const mutationCommitResultSchema = commitAckSchema;
 /**
  * Public SDK projection returned by `ablo.commits` and model mutations.
  *
@@ -298,3 +279,43 @@ export const clientCommitReceiptSchema = z.strictObject({
     notifications: notificationsSchema.optional(),
     missingIds: missingIdsSchema.optional(),
 });
+// ─────────────────────────────────────────────────────────────────────────
+//  The request side of the commit boundary
+// ─────────────────────────────────────────────────────────────────────────
+//
+// `POST /v1/commits` is the chokepoint every write passes through, so its
+// request shape is a boundary contract and belongs here beside the receipt it
+// answers with — not in a route handler. The published OpenAPI reference is
+// derived from these schemas rather than describing them separately, so the
+// documented surface cannot drift from the validated one.
+//
+// The server layers its own decoder-only compatibility spellings on top for
+// already-shipped clients; those are a rollout concern, not the contract.
+/** Control fields any operation in a commit may carry. */
+export const commitOperationControlShape = {
+    id: z.string().nullish(),
+    transactionId: z.string().nullish(),
+    readAt: z.number().nullish(),
+    onStale: onStaleModeSchema.nullish(),
+    fenceToken: z.number().nullish(),
+};
+/** One write inside a commit, in the canonical spelling. */
+export const commitOperationBodySchema = z.object({
+    ...commitOperationControlShape,
+    action: z.string(),
+    model: z.string(),
+    data: z.record(z.string(), z.unknown()).nullish(),
+});
+/**
+ * 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.
+ */
+export const commitRequestSchema = z.object({
+    operations: z.array(commitOperationBodySchema).min(1).optional(),
+    reads: z.array(readDependencySchema).nullish(),
+    track: z.array(trackDependencySchema).nullish(),
+});

package/dist/{wire → transaction/wire}/delta.d.ts

@@ -5,9 +5,9 @@
  * one definition and cannot drift apart. This is the delta's home in the wire
  * layer, alongside the other protocol shapes in `wire/`.
  *
- * The wire delta is a projection of the stored `sync_deltas` row (see
- * {@link import('../schema/syncDeltaRow.js').syncDeltaRowSchema}) and differs from
- * it in three ways: it omits `organizationId` (the tenant-isolation predicate is
+ * The wire delta is a projection of the stored `sync_deltas` row (the
+ * `syncDeltaRowSchema` in `../log/syncDeltaRow.ts`) and differs from it
+ * in three ways: it omits `organizationId` (the tenant-isolation predicate is
  * never broadcast), it uses the full action vocabulary (see
  * {@link syncDeltaActionSchema}) rather than plain create, update, and delete, and
  * it carries attribution as nested {@link ParticipantRef}s instead of flat columns.
@@ -18,19 +18,18 @@
  *   - {@link serverSyncDeltaSchema} — the core plus the audit attribution the server
  *     adds to each broadcast, which the client ignores.
  *
- * The two participant enums below (`participantKind`, `confirmationState`) are the
- * shared vocabulary of the protocol. They live here, at the wire layer, so the
- * stored-row schema can import them downward rather than the wire delta reaching
- * up into the schema DSL for them.
+ * The participant vocabulary the delta carries is declared once elsewhere and
+ * re-served here: the actor union lives in `types/participant.ts` and its
+ * runtime validator in `coordination/schema.ts`. Only `confirmationState` has
+ * its home in this module, since the approval stage of a committed change is
+ * delta attribution and nothing else. All three mirror Postgres enums.
  */
 import { z } from 'zod';
-/** `participant_kind` — who a delta is attributed to. */
-export declare const participantKindSchema: z.ZodEnum<{
-    user: "user";
-    agent: "agent";
-    system: "system";
-}>;
-export type ParticipantKind = z.infer<typeof participantKindSchema>;
+/** `participant_kind` — who a delta is attributed to. Declared in
+ *  `coordination/schema.ts`; re-exported so the wire subpath serves the
+ *  vocabulary its delta shapes carry. */
+export { participantKindSchema } from '../coordination/schema.js';
+export type { ParticipantKind } from '../types/participant.js';
 /** `confirmation_state` — the approval stage a committed change was in. */
 export declare const confirmationStateSchema: z.ZodEnum<{
     auto: "auto";
@@ -69,7 +68,9 @@ export type WireDeltaData = z.infer<typeof wireDeltaDataSchema>;
 /**
  * A participant reference as carried on a broadcast delta. The server expands the
  * flat `actor_id` and `actor_kind` stored columns into this nested `{ kind, id }`
- * shape.
+ * shape. The type is the canonical {@link ParticipantRef} from
+ * `types/participant.ts`; the pin below fails to compile if this schema and the
+ * canonical shape ever drift.
  */
 export declare const participantRefSchema: z.ZodObject<{
     kind: z.ZodEnum<{
@@ -79,7 +80,7 @@ export declare const participantRefSchema: z.ZodObject<{
     }>;
     id: z.ZodString;
 }, z.core.$strip>;
-export type ParticipantRef = z.infer<typeof participantRefSchema>;
+export type { ParticipantRef } from '../types/participant.js';
 /**
  * The fields the server and client agree on for a broadcast delta — the shared core
  * both projections extend. `transactionId` is typed as the client sees it (an
@@ -196,6 +197,54 @@ export declare const serverSyncDeltaSchema: z.ZodObject<{
         required_human_approval: "required_human_approval";
         auto_historical: "auto_historical";
     }>>;
-    causedByTaskId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type ServerSyncDelta = z.infer<typeof serverSyncDeltaSchema>;
+/**
+ * The transaction-layer seam's transport-neutral projection of a broadcast
+ * delta. It removes delivery plumbing (`syncGroups`, `transactionId`, and
+ * `correlationId`) while retaining the row change and optional audit
+ * attribution. `TransactionLayer.observe()` yields this shape.
+ */
+export declare const deltaSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    actionType: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+        A: "A";
+        V: "V";
+        C: "C";
+        G: "G";
+        S: "S";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    createdAt: z.ZodString;
+    actor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>>;
+    onBehalfOf: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>>;
+    capabilityId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    confirmationState: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        auto: "auto";
+        previewed: "previewed";
+        approved: "approved";
+        required_human_approval: "required_human_approval";
+        auto_historical: "auto_historical";
+    }>>>;
+}, z.core.$strip>;
+export type Delta = z.infer<typeof deltaSchema>;