@abloatai/transaction 0.55.0 → 0.57.0

package/src/transport/httpTransport.ts

@@ -17,7 +17,6 @@ import {
   claimedError,
   translateHttpError,
 } from '../errors.js';
-import { v5 as uuidv5 } from 'uuid';
 import { z } from 'zod';
 import {
   reconcileFunctionalUpdate,
@@ -37,7 +36,6 @@ import {
 } from '../auth/apiKey.js';
 import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
 import {
-  commitReceiptSchema,
   commitRecordSchema,
   commitRecordListSchema,
   commitRecordListOptionsSchema,
@@ -99,25 +97,11 @@ import {
 import { parseIdentityResolveResponse } from '../auth/schemas.js';
 import type { EffectiveAuthority } from '../auth/capability.js';
 
-/**
- * Interpret a heartbeat reply for a lease this handle HOLDS: anything other
- * than `held` means the lease is no longer ours (a holder cannot be `queued`;
- * `lost` rides a 409 that the wire error mapping already surfaces as
- * AbloClaimedError before reaching here). The thrown loss is the definitive
- * signal that stops the auto-heartbeat loop.
- */
-function heldHeartbeatReply(reply: ClaimHeartbeatReply, label: string): ClaimHeartbeat {
-  if (reply.status === 'held' && typeof reply.expiresAt === 'number') {
-    return {
-      expiresAt: reply.expiresAt,
-      ...(reply.queueDepth !== undefined ? { queueDepth: reply.queueDepth } : {}),
-    };
-  }
-  throw new AbloClaimedError(
-    `The lease behind ${label} is no longer held — it expired or was granted onward. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`,
-    { code: 'claim_lost' }
-  );
-}
+import {
+  claimFromModelClaim,
+  heldHeartbeatReply,
+  parseSuccessfulCommitResponse,
+} from './httpTransportHelpers.js';
 import type { SchemaRecord } from '../schema/schema.js';
 import type {
   ClaimLookupParams,
@@ -127,6 +111,7 @@ import type {
   ClaimReorderParams,
   ModelTrackParams,
   ModelTrackResult,
+  ModelCreateManyParams,
   ServerReadOptions,
   ResolvedClaimContentionOptions,
   ClaimQueueView,
@@ -151,7 +136,15 @@ import {
 import { declaredMeta, wireMeta } from '../coordination/claimMeta.js';
 import type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim } from '../types/streams.js';
 import type { CoordinationObservability } from '../observability.js';
-import { assertWriteOptions } from '../resources/writeOptionsSchema.js';
+import {
+  assertWriteOptions,
+  assertWriteTarget,
+} from '../resources/writeOptionsSchema.js';
+import {
+  createModelId,
+  resolveCreatedRows,
+  resolveCreateId,
+} from '../resources/modelCreate.js';
 import { normalizeWhere } from '../resources/where.js';
 import {
   createDurableHttpCommitEnvelope,
@@ -163,6 +156,12 @@ import {
   type DurableHttpCommitMethod,
 } from '../transactions/confirmation/httpCommitEnvelope.js';
 import type { CommitOutboxScope } from '../transactions/confirmation/commitEnvelope.js';
+import {
+  createClientTxId,
+  normalizeCommitOperations,
+  replicationLagTimeout,
+  type ExactHttpCommitRequest,
+} from './httpCommitRequest.js';
 import { resolveDurableWrites } from '../durableWrites.js';
 
 /** @internal Private options for the schema-agnostic HTTP protocol transport. */
@@ -239,46 +238,6 @@ export interface HttpTransport {
 
 type CommitResponse = CommitReceiptWire;
 
-function parseSuccessfulCommitResponse(value: unknown, idempotencyKey: string): CommitResponse {
-  const parsed = commitReceiptSchema.safeParse(value);
-  if (!parsed.success || parsed.data.clientTxId !== idempotencyKey) {
-    throw new AbloConnectionError(
-      'The commit endpoint returned an invalid success receipt; its outcome remains pending and is safe to retry.',
-      {
-        code: 'commit_no_result',
-        cause: parsed.success
-          ? new Error('Commit receipt clientTxId did not match its idempotency key')
-          : parsed.error,
-      }
-    );
-  }
-  return parsed.data;
-}
-
-/** Decode the HTTP claim DTO into the one public Claim shape. */
-function claimFromModelClaim(claim: ModelClaim): Claim {
-  // The handle a caller reads back is a public claim, so its `meta` is the
-  // declared shape; the rest of the sub-entity locator crosses whole rather
-  // than member by member, which is how `fields` used to die on this hop.
-  const { meta, ...details } = subTarget(claim.target);
-  return {
-    object: 'claim',
-    id: claim.id,
-    ...(claim.status ? { status: claim.status } : {}),
-    // The server always stamps a description; default only for total safety.
-    description: claim.description ?? 'editing',
-    heldBy: claim.actor,
-    participantKind: claim.participantKind,
-    expiresAt: claim.expiresAt,
-    ...(claim.position !== undefined ? { position: claim.position } : {}),
-    target: {
-      ...streamTarget(claim.target),
-      ...details,
-      ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
-    },
-  };
-}
-
 /** @internal Constructed only by the typed HTTP facade. */
 export function createHttpTransport(options: HttpTransportOptions): HttpTransport {
   const env = readProcessEnv();
@@ -703,14 +662,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     readonly response: CommitResponse;
   }
 
-  interface ExactHttpCommitRequest {
-    readonly idempotencyKey: string;
-    readonly method: DurableHttpCommitMethod;
-    readonly path: string;
-    readonly body: string;
-    readonly sealedProtocolVersion?: number;
-  }
-
   function observeCommitReceipt(
     request: ExactHttpCommitRequest,
     receipt: CommitResponse,
@@ -738,25 +689,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     }
   }
 
-  function replicationLagTimeout(
-    request: ExactHttpCommitRequest,
-    response: CommitResponse
-  ): AbloConnectionError {
-    return new AbloConnectionError(
-      `The source accepted commit ${request.idempotencyKey}, but its replication echo did not arrive within ${requestTimeoutMs}ms.`,
-      {
-        code: 'replication_lag_timeout',
-        httpStatus: 504,
-        details: {
-          clientTxId: request.idempotencyKey,
-          ...(response.correlationId ? { correlationId: response.correlationId } : {}),
-          timeoutMs: requestTimeoutMs,
-          accepted: true,
-        },
-      }
-    );
-  }
-
   /**
    * Replays one byte-identical, idempotent HTTP commit until mutation-log
    * replay reports the source echo as confirmed. `queued` is acceptance only:
@@ -779,7 +711,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     while (current.status === 'queued') {
       const remaining = deadlineAt === null ? null : deadlineAt - Date.now();
       if (remaining !== null && remaining <= 0) {
-        throw replicationLagTimeout(request, current);
+        throw replicationLagTimeout(request, current, requestTimeoutMs);
       }
 
       const confirmationController = new AbortController();
@@ -817,7 +749,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           confirmationController.signal.aborted ||
           (deadlineAt !== null && Date.now() >= deadlineAt)
         ) {
-          throw replicationLagTimeout(request, current);
+          throw replicationLagTimeout(request, current, requestTimeoutMs);
         }
         throw error;
       } finally {
@@ -1128,57 +1060,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     });
   }
 
-  function createClientTxId(idempotencyKey?: string | null): string {
-    if (idempotencyKey && idempotencyKey.length > 0) return idempotencyKey;
-    return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-      ? crypto.randomUUID()
-      : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-  }
-
-  function createModelId(modelName: string, idempotencyKey?: string | null): string {
-    if (idempotencyKey) {
-      return uuidv5(`${modelName}:${idempotencyKey}`, 'aa4ba6d4-bf0b-5b38-9c45-116f79a6e548');
-    }
-    return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-      ? crypto.randomUUID()
-      : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-  }
-
-  function normalizeCommitOperation(
-    op: CommitOperationInput,
-    defaults: Pick<CommitCreateOptions, 'readAt' | 'onStale'>,
-    fence: BatchFence | null,
-    claim: Claim | null,
-  ): CommitOperationInput {
-    return {
-      action: op.action,
-      model: op.model,
-      id: op.id ?? null,
-      data: op.data ?? null,
-      where: op.where ?? null,
-      transactionId: op.transactionId ?? null,
-      claimId:
-        op.claimId ?? claimIdFor(claim?.target, claim?.id, op.model, op.id ?? null),
-      readAt: op.readAt ?? defaults.readAt ?? null,
-      onStale: op.onStale ?? defaults.onStale ?? null,
-      fenceToken: op.fenceToken ?? fenceTokenFor(fence, op.model, op.id ?? null),
-    };
-  }
-
-  function normalizeCommitOperations(
-    commitOptions: CommitCreateOptions,
-    fence: BatchFence | null
-  ): readonly CommitOperationInput[] {
-    if (commitOptions.operations.length === 0) {
-      throw new AbloValidationError('Commit requires a non-empty `operations` array.', {
-        code: 'commit_operation_required',
-      });
-    }
-    return commitOptions.operations.map((op) =>
-      normalizeCommitOperation(op, commitOptions, fence, commitOptions.claim ?? null)
-    );
-  }
-
   async function listClaimState(
     target?: Partial<ModelTarget>
   ): Promise<{ active: readonly ModelClaim[]; queue: readonly ModelClaim[] }> {
@@ -1607,6 +1488,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       },
       `${modelName} ${action}`
     );
+    if (action !== 'create') assertWriteTarget(action, modelName, id);
     const clientTxId = createClientTxId(options?.idempotencyKey);
     const encModel = encodeURIComponent(modelName);
     const path =
@@ -1945,12 +1827,26 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       if (!claimInput) return run(input);
 
       if (isClaimHandle(claimInput)) {
+        // The lease's watermark travels with it. Unwrapping the handle to a
+        // `claimRef` is what put this here: `mutateModel` reads `readAt` off a
+        // handle on `claim`, and this sets `claim: undefined` before it looks,
+        // so the stale guard was silently dropped on every write that named a
+        // handle. The result was mutual exclusion without lost-update
+        // detection, on the transport agents run, under code that reads as
+        // though it had both. The reactive client binds the same three values
+        // from the claim it holds; a caller's own `readAt`/`onStale` win.
         return run({
           ...input,
           claimRef: { id: claimInput.id },
           ...(claimInput.fenceToken !== undefined
             ? { fenceToken: claimInput.fenceToken }
             : {}),
+          ...(input?.readAt === undefined && claimInput.readAt !== undefined
+            ? { readAt: claimInput.readAt }
+            : {}),
+          ...(input?.onStale === undefined && claimInput.readAt !== undefined
+            ? { onStale: 'reject' as const }
+            : {}),
           claim: undefined,
         });
       }
@@ -2079,6 +1975,60 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           return created;
         });
       },
+      /**
+       * Creates many rows as ONE commit, and returns them.
+       *
+       * Atomic on purpose: a batch that half-lands leaves the caller to work
+       * out which half, and every other write door here declines whole. One
+       * rejected row declines the batch.
+       *
+       * A fresh receipt returns the authoritative rows directly from the
+       * writing transaction. A durable idempotency replay deliberately redacts
+       * those rows, so that path verifies every deterministic id with a point
+       * read and fails loudly if policy prevents a complete answer. Neither
+       * path can report a partial collection as success.
+       *
+       * Ids are resolved here rather than left to the server, so the results
+       * can be returned in the caller's own order rather than the order the
+       * transaction happened to settle them.
+       */
+      async createMany(
+        params: ModelCreateManyParams<Record<string, unknown>>
+      ): Promise<T[]> {
+        if (params.data.length === 0) return [];
+
+        // A claim/stale guard addresses one existing row, so the canonical
+        // batch-create options do not admit those fields at all.
+        const { data, ...options } = params;
+        const ids = data.map(
+          (row, index) =>
+            resolveCreateId(undefined, row) ??
+            createModelId(
+              name,
+              params.idempotencyKey ? `${params.idempotencyKey}:${index}` : null
+            )
+        );
+        const receipt = await commits.create({
+          ...options,
+          operations: data.map((row, index) => ({
+            action: 'create' as const,
+            model: name,
+            id: ids[index] ?? null,
+            data: row,
+          })),
+          wait: 'confirmed',
+        });
+
+        return resolveCreatedRows<T>({
+          modelName: name,
+          ids,
+          operationResults: receipt.operationResults,
+          readRow: async (id) => {
+            const read = await retrieveModel<T>(name, { id });
+            return read.data;
+          },
+        });
+      },
       update: updateModel,
       async delete(params: ModelMutationOptions & { readonly id: string }): Promise<CommitReceipt> {
         return withMutationClaim(params.id, params, async (options) => {

package/src/transport/httpTransportHelpers.ts

@@ -0,0 +1,63 @@
+import { AbloClaimedError, AbloConnectionError } from '../errors.js';
+import { commitReceiptSchema, type CommitReceiptWire } from '../wire/commit.js';
+import type { ClaimHeartbeatReply } from '../wire/claims.js';
+import type { ModelClaim } from '../resources/httpResources.js';
+import { subTarget, streamTarget } from '../coordination/locator.js';
+import { declaredMeta } from '../coordination/claimMeta.js';
+import type { Claim, ClaimHeartbeat } from '../types/streams.js';
+
+/** Interpret a heartbeat reply for a lease this handle currently holds. */
+export function heldHeartbeatReply(
+  reply: ClaimHeartbeatReply,
+  label: string,
+): ClaimHeartbeat {
+  if (reply.status === 'held' && typeof reply.expiresAt === 'number') {
+    return {
+      expiresAt: reply.expiresAt,
+      ...(reply.queueDepth !== undefined ? { queueDepth: reply.queueDepth } : {}),
+    };
+  }
+  throw new AbloClaimedError(
+    `The lease behind ${label} is no longer held — it expired or was granted onward. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`,
+    { code: 'claim_lost' },
+  );
+}
+
+export function parseSuccessfulCommitResponse(
+  value: unknown,
+  idempotencyKey: string,
+): CommitReceiptWire {
+  const parsed = commitReceiptSchema.safeParse(value);
+  if (!parsed.success || parsed.data.clientTxId !== idempotencyKey) {
+    throw new AbloConnectionError(
+      'The commit endpoint returned an invalid success receipt; its outcome remains pending and is safe to retry.',
+      {
+        code: 'commit_no_result',
+        cause: parsed.success
+          ? new Error('Commit receipt clientTxId did not match its idempotency key')
+          : parsed.error,
+      },
+    );
+  }
+  return parsed.data;
+}
+
+/** Decode the HTTP claim DTO into the public Claim shape. */
+export function claimFromModelClaim(claim: ModelClaim): Claim {
+  const { meta, ...details } = subTarget(claim.target);
+  return {
+    object: 'claim',
+    id: claim.id,
+    ...(claim.status ? { status: claim.status } : {}),
+    description: claim.description ?? 'editing',
+    heldBy: claim.actor,
+    participantKind: claim.participantKind,
+    expiresAt: claim.expiresAt,
+    ...(claim.position !== undefined ? { position: claim.position } : {}),
+    target: {
+      ...streamTarget(claim.target),
+      ...details,
+      ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
+    },
+  };
+}

package/src/wire/apiLifecycle.ts

@@ -0,0 +1,94 @@
+/**
+ * What a caller can rely on about the HTTP surface not moving under it: where
+ * the version is written, what a removal looks like before it happens, and how
+ * much warning it comes with.
+ *
+ * An agent decides whether to integrate against an API partly on whether the
+ * API can change without telling it. That decision needs facts, not a promise,
+ * so each of these is a value some other surface derives from — the path
+ * segment every route is mounted under, the header every response carries, and
+ * the two standard fields a withdrawal is announced on. {@link API_LIFECYCLE}
+ * is the same set written as prose, and it is what the published OpenAPI
+ * document's description carries: the policy and the routes it governs are then
+ * one artifact, and a reader who has the spec has the policy.
+ *
+ * Two axes, deliberately separate:
+ *
+ *   - The PATH version ({@link API_PATH_VERSION}) is the breaking axis. It
+ *     changes only when a shape a caller sends or reads changes incompatibly,
+ *     and the old segment keeps serving through the notice window.
+ *   - The CONTRACT date on {@link API_VERSION_HEADER} is the additive axis. It
+ *     moves when something observable is added — a new error code, a new field
+ *     — and a caller pinned to an older reading keeps working. Its value is
+ *     `ERROR_CONTRACT_VERSION`, stamped by the server on every response.
+ */
+
+/**
+ * The path segment every route is mounted under: `/api/v1/...`. Callers address
+ * this literally, and the OpenAPI document's paths are written from it, so the
+ * spec cannot advertise a version the server does not serve.
+ */
+export const API_PATH_VERSION = 'v1';
+
+/**
+ * Carries the date-stamped contract version on every response. A client that
+ * records the value it was built against can tell that the server has moved
+ * without waiting for a field it does not recognize to break something.
+ */
+export const API_VERSION_HEADER = 'Ablo-Version';
+
+/**
+ * Announces that a route will be withdrawn, as an sf-Date of the moment the
+ * deprecation took effect (RFC 9745): `Deprecation: @1774483200`. It appears
+ * while the route still works — a deprecated route answers normally.
+ */
+export const API_DEPRECATION_HEADER = 'Deprecation';
+
+/**
+ * The moment the route stops answering, as an HTTP-date (RFC 8594):
+ * `Sunset: Tue, 08 Sep 2026 00:00:00 GMT`. Paired with
+ * {@link API_DEPRECATION_HEADER}, the two bound the window a caller has.
+ */
+export const API_SUNSET_HEADER = 'Sunset';
+
+/**
+ * The minimum gap between the two headers above. A number rather than a
+ * sentence because it is the part a caller plans against, and because the
+ * published policy renders it rather than restating it.
+ */
+export const API_DEPRECATION_NOTICE_DAYS = 180;
+
+/**
+ * The policy, in the words it is published in.
+ *
+ * Written here rather than in the document that shows it because two documents
+ * show it — the OpenAPI description and the site's API page — and a policy
+ * stated twice is a policy that will eventually say two things.
+ */
+export const API_LIFECYCLE = `## Versioning
+
+Every route is mounted under \`/${API_PATH_VERSION}\`, and that segment is part
+of the address you call. A change that would break a caller — a field removed, a
+type narrowed, a status changed — arrives as a new segment beside this one, never
+as a change to this one. Additive changes do land here: a new field on a
+response, a new optional parameter, a new error code. Ignore what you do not
+recognize and you will not be broken by them.
+
+Every response carries \`${API_VERSION_HEADER}\`, a date stamp for the contract
+the server is serving. Record the value your integration was built against and
+compare it if behavior surprises you.
+
+## Deprecation
+
+A route being withdrawn says so on itself, for at least
+${API_DEPRECATION_NOTICE_DAYS} days before it stops answering:
+
+- \`${API_DEPRECATION_HEADER}\` — an sf-Date of when the deprecation took effect
+  (RFC 9745). The route still answers normally while this is present.
+- \`${API_SUNSET_HEADER}\` — an HTTP-date of when it stops answering (RFC 8594).
+- \`Link\` with \`rel="deprecation"\` pointing at what to read, and
+  \`rel="successor-version"\` at what to call instead when there is one.
+
+The same operations are marked \`deprecated: true\` in this document. Treating
+either signal as a build failure is the intended use; nothing is removed without
+both.`;

package/src/wire/auth.ts

@@ -34,9 +34,12 @@ export const ephemeralKeyRequestSchema = z.object({
   /** The participant this session acts as. */
   user: ephemeralKeyUserSchema,
   /**
-   * Mint into this organization instead of the caller's own. Requires the
-   * `organization:act-as` scope — without it a secret key can never mint a
-   * session into another tenant.
+   * Open the session in a DIFFERENT organization, one the caller does not
+   * belong to. Requires the `organization:act-as` scope. This is the identity
+   * provider case, where each organization is an account in its own right.
+   *
+   * A platform serving its own customers does not use this: its customers are
+   * rows in its own schema, and a session reaches them through `syncGroups`.
    */
   organizationId: z.string().min(1).optional(),
   /**

package/src/wire/commit.ts

@@ -18,6 +18,7 @@
  */
 
 import { z } from 'zod';
+import { logPositionSchema } from '../syncLog/contract.js';
 import {
   onStaleModeSchema,
   MAX_READ_SET_ENTRIES,
@@ -25,7 +26,6 @@ import {
   readSetRowTargetSchema,
   readSetProjectionEntryCount,
   readSetSchema,
-  readSetWatermarkSchema,
   participantKindSchema,
   staleNotificationSchema,
   trackDependencyListSchema,
@@ -61,7 +61,7 @@ export const confirmedCommitStatusSchema = z
   .strictObject({
     status: confirmedStatusSchema,
     statusAt: commitTimestampSchema,
-    lastSyncId: readSetWatermarkSchema,
+    lastSyncId: logPositionSchema,
     correlationId: correlationIdSchema.optional(),
   })
   .refine(({ correlationId, lastSyncId }) => correlationId === undefined || lastSyncId > 0, {
@@ -375,7 +375,7 @@ export type MutationCommitResult = z.infer<typeof mutationCommitResultSchema>;
 export const clientCommitReceiptSchema = z.strictObject({
   id: z.string().min(1),
   status: z.union([queuedStatusSchema, confirmedStatusSchema]),
-  lastSyncId: readSetWatermarkSchema.optional(),
+  lastSyncId: logPositionSchema.optional(),
   notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   operationResults: operationResultsSchema.optional(),
@@ -400,15 +400,30 @@ export const commitOperationControlShape = {
   id: z.string().nullish(),
   transactionId: z.string().nullish(),
   claimId: z.string().min(1).nullish(),
-  readAt: readSetWatermarkSchema.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(),

package/src/wire/index.ts

@@ -120,6 +120,8 @@ export {
   // The request side of the same boundary — one definition, which the published
   // OpenAPI reference derives from rather than describing separately.
   commitOperationControlShape,
+  modelOperationActionSchema,
+  normalizeStorageOperationAction,
   commitOperationBodySchema,
   commitActorSchema,
   commitAttemptSchema,
@@ -133,6 +135,7 @@ export {
   commitRecordListSchema,
 } from './commit.js';
 export type {
+  ModelOperationAction,
   CommitOperationBody,
   CommitOperationResult,
   CommitActor,
@@ -408,3 +411,31 @@ export type {
   CapabilityRequest,
   CapabilityMintResponse,
 } from './auth.js';
+
+// How a rate limit is stated on a response, so a caller can pace itself rather
+// than discover the ceiling by hitting it. The field names and their Structured
+// Fields spellings live in one module because every producer — the engine's
+// per-key limiter and the public docs surfaces both — has to spell them the
+// same way for a client to read either.
+export {
+  RATE_LIMIT_HEADER,
+  RATE_LIMIT_POLICY_HEADER,
+  RETRY_AFTER_HEADER,
+  rateLimitField,
+  rateLimitPolicyField,
+  rateLimitHeaders,
+} from './rateLimit.js';
+export type { QuotaPolicy, ServiceLimit, RateLimitSignal } from './rateLimit.js';
+
+// What a caller can rely on about this surface not moving under it: the path
+// segment the routes live under, the header carrying the contract date, and the
+// two standard fields a withdrawal is announced on. The published OpenAPI
+// description renders `API_LIFECYCLE` rather than restating it.
+export {
+  API_PATH_VERSION,
+  API_VERSION_HEADER,
+  API_DEPRECATION_HEADER,
+  API_SUNSET_HEADER,
+  API_DEPRECATION_NOTICE_DAYS,
+  API_LIFECYCLE,
+} from './apiLifecycle.js';

package/src/wire/modelMutations.ts

@@ -16,12 +16,12 @@
  */
 
 import { z } from 'zod';
+import { logPositionSchema } from '../syncLog/contract.js';
 import {
   onStaleModeSchema,
   MAX_READ_SET_ENTRIES,
   readDependencyListSchema,
   readSetProjectionEntryCount,
-  readSetWatermarkSchema,
   trackDependencyListSchema,
 } from '../coordination/schema.js';
 
@@ -50,7 +50,7 @@ export const modelMutationRequestSchema = z.object({
    * the read. Ablo rejects the write if the row moved in between, which is
    * what makes read → decide → write safe without a lock across the deciding.
    */
-  readAt: readSetWatermarkSchema.nullish(),
+  readAt: logPositionSchema.nullish(),
   /** Commit-lifetime dependencies checked with the single model operation. */
   reads: readDependencyListSchema.nullish(),
   /** Durable dependencies registered with the single model operation. */