@abloatai/transaction 0.56.0 → 0.58.0

package/src/transport/{httpTransport.ts → http/transport.ts}

@@ -16,14 +16,13 @@ import {
   AbloNotFoundError,
   claimedError,
   translateHttpError,
-} from '../errors.js';
-import { v5 as uuidv5 } from 'uuid';
+} from '../../errors.js';
 import { z } from 'zod';
 import {
   reconcileFunctionalUpdate,
   type ModelUpdater,
   type FunctionalUpdateOptions,
-} from '../resources/functionalUpdate.js';
+} from '../../client/resources/functionalUpdate.js';
 import {
   assertBrowserSafety,
   readProcessEnv,
@@ -34,42 +33,42 @@ import {
   resolveBootstrapBaseUrl,
   rejectRemovedDatabaseUrlOption,
   warnIfCliKeyMismatch,
-} from '../auth/apiKey.js';
-import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
+} from '../../auth/apiKey.js';
+import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../../wire/protocolVersion.js';
 import {
-  commitReceiptSchema,
   commitRecordSchema,
   commitRecordListSchema,
   commitRecordListOptionsSchema,
   commitRecordWhereSchema,
   type CommitReceiptWire,
-} from '../wire/commit.js';
-import { logListResponseSchema } from '../wire/feedEvent.js';
+} from '../../commit/contract.js';
+import { logListResponseSchema } from '../../observation/feedContract.js';
 import {
   claimAcquireResponseSchema,
   claimHeartbeatBatchReplySchema,
   claimHeartbeatReplySchema,
   claimListResponseSchema,
   claimStateSchema,
+  DEFAULT_CLAIM_TTL_MS,
   type ClaimHeartbeatReply,
   type ClaimListResponse,
   type ClaimQueuedResponse,
   type ClaimRequest,
   type ClaimState,
   type ClaimTargetBody,
-} from '../wire/claims.js';
+} from '../../claims/contract.js';
 import {
   modelListResponseSchema,
   modelReadResponseSchema,
-} from '../wire/modelResponses.js';
-import { toMs } from '../utils/duration.js';
+} from '../../wire/modelResponses.js';
+import { toMs } from '../../utils/duration.js';
 import {
   heartbeatCadenceMs,
   resolveHeartbeatOptions,
   resolveHeartbeatPlan,
   startClaimHeartbeatLoop,
-} from '../coordination/claimHeartbeatLoop.js';
-import type { HttpClientConfig } from './httpOptions.js';
+} from '../../claims/heartbeat.js';
+import type { HttpClientConfig } from './options.js';
 import type {
   ClaimedOptions,
   CommitCreateOptions,
@@ -81,7 +80,7 @@ import type {
   HttpClaimsResource,
   HttpTransportModel,
   ModelClaim,
-  ModelMutationOptions,
+  InternalModelMutationOptions as ModelMutationOptions,
   ModelReadOptions,
   HttpTransportRead,
   HttpTransportList,
@@ -90,69 +89,68 @@ import type {
   CreateSessionParams,
   AbloSession,
   SessionResource,
-} from '../resources/httpResources.js';
-import { mintSession } from '../auth/sessionMint.js';
+} from '../../client/resources/httpResources.js';
+import { mintSession } from '../../auth/sessionMint.js';
 import {
   revokeCapability,
   rotateCapability,
-} from '../auth/capabilityLifecycle.js';
-import { parseIdentityResolveResponse } from '../auth/schemas.js';
-import type { EffectiveAuthority } from '../auth/capability.js';
+} from '../../auth/capabilityLifecycle.js';
+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 type { SchemaRecord } from '../schema/schema.js';
+import {
+  claimFromModelClaim,
+  heldHeartbeatReply,
+  parseSuccessfulCommitResponse,
+} from './helpers.js';
+import type { SchemaRecord } from '../../schema/schema.js';
 import type {
   ClaimLookupParams,
   ClaimOptions,
   ClaimParams,
   ClaimSkipParams,
+  ClaimSkipOptions,
   ClaimReorderParams,
-  ModelTrackParams,
-  ModelTrackResult,
+  ModelCreateManyParams,
   ServerReadOptions,
   ResolvedClaimContentionOptions,
   ClaimQueueView,
-} from '../resources/modelOperations.js';
+} from '../../client/resources/modelOperations.js';
 import {
   claimAttemptFailure,
   claimQueueView,
   emitClaimStatus,
   resolveClaimContentionOptions,
-} from '../resources/modelOperations.js';
-import type { Duration } from '../utils/duration.js';
-import type { TrackDependency } from '../coordination/schema.js';
-import { claimDescription, partName } from '../coordination/schema.js';
-import type { BatchFence } from '../coordination/locator.js';
+} from '../../client/resources/modelOperations.js';
+import type { Duration } from '../../utils/duration.js';
+import { claimDescription, partName } from '../../coordination/schema.js';
+import type { BatchFence } from '../../claims/locator.js';
 import {
   subTarget,
   streamTarget,
   batchFence,
   claimIdFor,
   fenceTokenFor,
-} from '../coordination/locator.js';
-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 { normalizeWhere } from '../resources/where.js';
+} from '../../claims/locator.js';
+import { declaredMeta, wireMeta } from '../../claims/meta.js';
+import type {
+  Claim,
+  ClaimHeartbeat,
+  ClaimHeartbeatOptions,
+  HeldClaim,
+  HeldLease,
+} from '../../types/streams.js';
+import type { CoordinationObservability } from '../../observability.js';
+import {
+  assertWriteOptions,
+  assertWriteTarget,
+} from '../../client/resources/writeOptionsSchema.js';
+import {
+  createModelId,
+  resolveCreatedRows,
+  resolveCreateId,
+} from '../../client/resources/modelCreate.js';
+import { normalizeWhere } from '../../client/resources/where.js';
 import {
   createDurableHttpCommitEnvelope,
   canonicalHttpCommitBody,
@@ -161,9 +159,16 @@ import {
   isHttpCommitReplayExpired,
   type DurableHttpCommitEnvelope,
   type DurableHttpCommitMethod,
-} from '../transactions/confirmation/httpCommitEnvelope.js';
-import type { CommitOutboxScope } from '../transactions/confirmation/commitEnvelope.js';
-import { resolveDurableWrites } from '../durableWrites.js';
+} from '../../commit/confirmation/httpCommitEnvelope.js';
+import type { CommitOutboxScope } from '../../commit/confirmation/commitEnvelope.js';
+import {
+  createClientTxId,
+  normalizeCommitOperations,
+  replicationLagTimeout,
+  type ExactHttpCommitRequest,
+} from '../../commit/httpRequest.js';
+import { resolveDurableWrites } from '../../commit/durableWrites.js';
+import { createHttpReadOnChange, type HttpReadOnChange } from './subscription.js';
 
 /** @internal Private options for the schema-agnostic HTTP protocol transport. */
 export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
@@ -191,12 +196,6 @@ export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
 /** @internal Default per-request deadline for the private HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const HTTP_CONFIRMATION_POLL_INTERVAL_MS = 250;
-/**
- * The server's acquire window, mirrored here as the client-side default for a
- * claim that names no `ttl` — it sets the auto-heartbeat cadence.
- */
-const DEFAULT_CLAIM_TTL_MS = 60_000;
-
 // NOTE: end-user / agent session minting is `ablo.sessions.create(...)` (typed
 // against the schema, see Ablo.ts `CreateSessionParams`). There is no separate
 // `ephemeralKeys` resource — `sessions` is the one front door for both.
@@ -208,6 +207,8 @@ export interface HttpTransport {
   /** Drains scheduled commits and active requests. */
   dispose(): Promise<void>;
   purge(): Promise<void>;
+  /** @internal Live check used only by `context().onChange`. */
+  readonly onChange: HttpReadOnChange;
   readonly commits: CommitResource;
   /**
    * Claim-ticket operations keyed by `claimId` — the id a queued acquire
@@ -239,46 +240,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();
@@ -320,8 +281,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     const isConflict =
       code === 'stale_context' ||
       code === 'claim_conflict' ||
-      code === 'entity_claimed' ||
-      (typeof code === 'string' && code.startsWith('policy:'));
+      code === 'entity_claimed';
     if (!isConflict) return;
     const rawConflicts = errorRecord?.conflicts;
     const rows =
@@ -367,6 +327,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
   let activeRequests = 0;
   let requestIdleWaiters: Array<() => void> = [];
   let disposePromise: Promise<void> | null = null;
+  const readChangeControllers = new Set<AbortController>();
 
   function requestStarted(): void {
     activeRequests += 1;
@@ -488,7 +449,24 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     return target.toString();
   }
 
+  function subscriptionEndpoint(): string {
+    const target = new URL(endpoint('/v1/subscriptions'));
+    const partition = effectiveAuthority?.deliveryPartition;
+    if (partition) {
+      target.searchParams.set('deliveryPartition', `${partition.index}-${partition.count}`);
+    }
+    return target.toString();
+  }
+
   const requestTimeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const onChange = createHttpReadOnChange({
+    fetch: fetchImpl,
+    endpoint: subscriptionEndpoint,
+    authHeaders,
+    prepare: ready,
+    register: (controller) => readChangeControllers.add(controller),
+    unregister: (controller) => readChangeControllers.delete(controller),
+  });
 
   /**
    * Issues one request and returns its decoded body without a contract.
@@ -703,14 +681,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 +708,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 +730,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 +768,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 +1079,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[] }> {
@@ -1374,11 +1274,9 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         {
           idempotencyKey: commitOptions.idempotencyKey,
           readAt: commitOptions.readAt,
-          onStale: commitOptions.onStale,
           wait: commitOptions.wait,
           claim: commitOptions.claim,
           reads: commitOptions.reads,
-          track: commitOptions.track,
         },
         'commits.create'
       );
@@ -1390,14 +1288,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         {
           ...commitOptions,
           readAt: commitOptions.readAt ?? claim?.readAt ?? null,
-          onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
         },
         batchFence(claim?.target, claim?.fenceToken)
       );
       const requestBody = {
         operations,
         reads: commitOptions.reads,
-        track: commitOptions.track,
       };
       const wait = commitOptions.wait ?? 'confirmed';
       let body: CommitResponse;
@@ -1433,9 +1329,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         id: body.id ?? body.clientTxId,
         status: body.status,
         lastSyncId: body.lastSyncId,
-        ...(body.notifications && body.notifications.length > 0
-          ? { notifications: body.notifications }
-          : {}),
         ...(body.missingIds && body.missingIds.length > 0 ? { missingIds: body.missingIds } : {}),
         ...(body.operationResults && body.operationResults.length > 0
           ? { operationResults: body.operationResults }
@@ -1549,7 +1442,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     };
   }
 
-  async function retrieveModel<T>(
+  async function readModel<T>(
     modelName: string,
     params: ModelReadOptions & { readonly id: string }
   ): Promise<HttpTransportRead<T>> {
@@ -1562,7 +1455,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     );
 
     // A miss is `data: undefined`, not a thrown error. The WebSocket client's
-    // `retrieve` returns `T | undefined` for a missing row; throwing only here
+    // `read` returns `T | undefined` for a missing row; throwing only here
     // made the obvious read ("does this row exist?") a hard edge that an agent
     // had to wrap in try/catch. Both transports agree: an absent row means absent
     // data. Callers branch on `.data` (the documented `.data?.x` usage).
@@ -1598,15 +1491,14 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       options && {
         idempotencyKey: options.idempotencyKey,
         readAt: options.readAt,
-        onStale: options.onStale,
         claim: options.claim,
         claimRef: options.claimRef,
         fenceToken: options.fenceToken,
         reads: options.reads,
-        track: options.track,
       },
       `${modelName} ${action}`
     );
+    if (action !== 'create') assertWriteTarget(action, modelName, id);
     const clientTxId = createClientTxId(options?.idempotencyKey);
     const encModel = encodeURIComponent(modelName);
     const path =
@@ -1628,10 +1520,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     const readAt = options?.readAt ?? claimHandle?.readAt;
     const requestBody: Record<string, unknown> = {
       claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.id,
-      onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
       readAt,
       reads: options?.reads,
-      track: options?.track,
       // The claim's fencing token (Option B), so the per-model HTTP write door
       // fences the same as the WS proxy and `commits.create`.
       fenceToken: options?.fenceToken ?? claimHandle?.fenceToken,
@@ -1798,9 +1688,23 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       params: ClaimSkipParams<Fields>
     ): Promise<HeldClaim<T> | null>;
     function claimImpl(params: ClaimParams<Fields>): Promise<HeldClaim<T>>;
+    function claimImpl(
+      id: string,
+      opts: ClaimSkipOptions<Fields>
+    ): Promise<HeldLease | null>;
+    function claimImpl(id: string, opts?: ClaimOptions<Fields>): Promise<HeldLease>;
     async function claimImpl(
-      params: ClaimParams<Fields>,
-    ): Promise<HeldClaim<T> | null> {
+      idOrParams: string | ClaimParams<Fields>,
+      opts?: ClaimOptions<Fields>,
+    ): Promise<HeldClaim<T> | HeldLease | null> {
+      // The row-free form names a key by id alone. Ablo has never held that
+      // row, so there is no snapshot to take after the grant and no `data` on
+      // the handle: the lease is the whole answer. The object form re-reads
+      // the row under the lease and hands back a `HeldClaim`.
+      const rowFree = typeof idOrParams === 'string';
+      const params: ClaimParams<Fields> = rowFree
+        ? { ...(opts ?? {}), id: idOrParams }
+        : idOrParams;
       let acquired: { id: string; fenceToken?: number };
       try {
         acquired = await acquireClaim(params);
@@ -1827,16 +1731,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         id: params.id,
         description: claimDescription(params),
       });
-      const { data, stamp } = await retrieveModel<T>(name, { id: params.id });
-      // A held claim hands back a snapshot; the typed `HeldClaim.data` is `T`.
-      // `retrieve` now reports a miss as `undefined` rather than throwing, but a
-      // claim on a row that doesn't exist has nothing to hold — surface it.
-      if (data === undefined) {
-        throw new AbloNotFoundError(
-          `Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope).`,
-          [params.id]
-        );
-      }
       // One reading of the heartbeat options — cadence and callbacks from
       // whichever spelling the caller used (plan object, shorthand, or the
       // deprecated flat callbacks).
@@ -1876,10 +1770,9 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       // way. `subTarget` is wire-shaped by contract, including here, where the
       // value happens to have started out declared.
       const { meta, ...narrowed } = subTarget(params, name);
-      return {
+      const lease: HeldLease = {
         object: 'claim',
         id: claimId,
-        readAt: stamp,
         ...(fenceToken !== undefined ? { fenceToken } : {}),
         target: {
           ...streamTarget({ model: name, id: params.id }),
@@ -1887,7 +1780,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
         },
         description: claimDescription(params),
-        data,
         release,
         revoke: () => {
           void release().catch(() => {});
@@ -1895,6 +1787,24 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         heartbeat,
         [Symbol.asyncDispose]: release,
       };
+      if (rowFree) return lease;
+
+      const { data, stamp } = await readModel<T>(name, { id: params.id });
+      // A held claim hands back a snapshot; the typed `HeldClaim.data` is `T`.
+      // `retrieve` reports a miss as `undefined`, and a claim on a row that does
+      // not exist has nothing to hold. The grant came BEFORE this read, so the
+      // miss must give the lease back first: otherwise the key stays held under
+      // this credential until the TTL lapses, behind no handle anyone can
+      // release, and every other participant is refused for the duration.
+      if (data === undefined) {
+        await release().catch(() => undefined);
+        throw new AbloNotFoundError(
+          `Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope). ` +
+            `To hold a key before its row exists, claim it by id alone: claim('${params.id}') returns a lease without a snapshot.`,
+          [params.id]
+        );
+      }
+      return { ...lease, readAt: stamp, data };
     }
     const claimsForEntity = (
       params: ClaimLookupParams<T>
@@ -1906,7 +1816,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         { method: 'GET' },
         claimListResponseSchema
       );
-    const claim = Object.assign(claimImpl, {
+    const claim: HttpClaimApi<T, Fields> = Object.assign(claimImpl, {
       release: releaseClaim,
       state: async (params: ClaimLookupParams<T>): Promise<Claim | null> => {
         const res = await claimsForEntity(params);
@@ -1914,6 +1824,19 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         const first = res.data.find((row) => row.status !== 'queued');
         return first ? claimFromModelClaim(first) : null;
       },
+      // Every holder, from the same one read `state` takes its first entry
+      // from: the server lists holders before waiters, and the caller's own
+      // lease before its peers'. (This member was missing for as long as the
+      // namespace was cast to its type instead of typed as it.)
+      list: async (params: ClaimLookupParams<T>) => {
+        const res = await claimsForEntity(params);
+        return {
+          object: 'list' as const,
+          data: res.data
+            .filter((row) => row.status !== 'queued')
+            .map(claimFromModelClaim),
+        };
+      },
       queue: async (
         params: ClaimLookupParams<T>
       ): Promise<ClaimQueueView> => {
@@ -1934,7 +1857,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           }),
         });
       },
-    }) as HttpClaimApi<T, Fields>;
+    });
 
     const withMutationClaim = async <R>(
       id: string,
@@ -1945,12 +1868,23 @@ 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` wins.
         return run({
           ...input,
           claimRef: { id: claimInput.id },
           ...(claimInput.fenceToken !== undefined
             ? { fenceToken: claimInput.fenceToken }
             : {}),
+          ...(input?.readAt === undefined && claimInput.readAt !== undefined
+            ? { readAt: claimInput.readAt }
+            : {}),
           claim: undefined,
         });
       }
@@ -1996,7 +1930,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     ): Promise<CommitReceipt | undefined> {
       // Functional form: update(id, current => next). The SDK owns the
       // read-fresh → compute → compare-and-swap → reconcile loop; correctness
-      // rides on the row's watermark (readAt + onStale:'reject'), so no claim
+      // rides on the row's watermark (`readAt`), so no claim
       // or per-participant identity is needed and contention never clobbers.
       if (typeof arg === 'string') {
         const id = arg;
@@ -2011,13 +1945,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           model: name,
           id,
           readFresh: async () => {
-            const read = await retrieveModel<T>(name, { id });
+            const read = await readModel<T>(name, { id });
             return { data: read.data, stamp: read.stamp };
           },
           writeNext: (patch, readAt) =>
             mutateModel('update', name, id, patch, {
               readAt,
-              onStale: 'reject',
             }),
         });
       }
@@ -2030,11 +1963,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
 
     return {
       claim,
-      get(params: ModelReadOptions & { readonly id: string }): Promise<HttpTransportRead<T>> {
-        return retrieveModel<T>(name, params);
-      },
-      retrieve(params: ModelReadOptions & { readonly id: string }): Promise<HttpTransportRead<T>> {
-        return retrieveModel<T>(name, params);
+      read(params: ModelReadOptions & { readonly id: string }): Promise<HttpTransportRead<T>> {
+        return readModel<T>(name, params);
       },
       list(options?: ServerReadOptions<T>): ReturnType<typeof listModel<T>> {
         return listModel<T>(name, options);
@@ -2061,7 +1991,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
             params.data,
             options,
             async () => {
-              const read = await retrieveModel<T>(name, { id });
+              const read = await readModel<T>(name, { id });
               if (read.data === undefined) {
                 throw new AbloNotFoundError(
                   `create ${name}/${id} did not yield a readable row (the write did not confirm).`,
@@ -2079,6 +2009,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 readModel<T>(name, { id });
+            return read.data;
+          },
+        });
+      },
       update: updateModel,
       async delete(params: ModelMutationOptions & { readonly id: string }): Promise<CommitReceipt> {
         return withMutationClaim(params.id, params, async (options) => {
@@ -2086,29 +2070,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           return mutateModel('delete', name, params.id, undefined, options);
         });
       },
-      async track(params: ModelTrackParams): Promise<ModelTrackResult> {
-        const dependency: TrackDependency = {
-          model: name.toLowerCase(),
-          id: params.id,
-          ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
-        };
-        // A track carries no write, so it rides the commit lane as a
-        // zero-operation body — the shape `/v1/commits` accepts for registering
-        // a premise without one. Going through the same durable lane as every
-        // other commit means a disconnect replays the registration rather than
-        // dropping it, and a notification that had already fired is not lost to
-        // a retry.
-        const body = await dispatchHttpCommit({
-          path: '/v1/commits',
-          method: 'POST',
-          idempotencyKey: createClientTxId(),
-          body: { track: [dependency] },
-          wait: 'confirmed',
-        });
-        return body.notifications && body.notifications.length > 0
-          ? { notifications: body.notifications }
-          : {};
-      },
     };
   }
 
@@ -2123,6 +2084,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       }),
     dispose() {
       if (!disposePromise) {
+        for (const controller of readChangeControllers) controller.abort();
+        readChangeControllers.clear();
         const scheduledCommits = httpCommitLane;
         disposePromise = (async () => {
           await scheduledCommits;
@@ -2132,6 +2095,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       return disposePromise;
     },
     async purge() {},
+    onChange,
     commits,
     claims,
     logs,