@abloatai/transaction 0.56.0 → 0.58.0

package/src/transport/{httpClient.ts → http/client.ts}

@@ -20,9 +20,9 @@
 import {
   createHttpTransport,
   type HttpTransport,
-} from './httpTransport.js';
-import { modelWireNames } from '../auth/capability.js';
-import type { HttpClientConfig } from './httpOptions.js';
+} from './transport.js';
+import { modelWireNames } from '../../auth/capability.js';
+import type { HttpClientConfig } from './options.js';
 import type {
   CommitResource,
   CommitReceipt,
@@ -36,38 +36,37 @@ import type {
   CreateSessionParams,
   AbloSession,
   SessionResource,
-} from '../resources/httpResources.js';
-import { modelList } from '../resources/httpResources.js';
+} from '../../client/resources/httpResources.js';
+import { collectModelList, modelList } from '../../client/resources/httpResources.js';
+import { resolveCreateId } from '../../client/resources/modelCreate.js';
 import type {
   ModelCreateParams,
+  ModelCreateManyParams,
   ModelDeleteParams,
   ServerReadOptions,
-  ModelRetrieveParams,
-  ModelTrackParams,
-  ModelTrackResult,
+  ListAllOptions,
+  ModelReadParams,
   ModelUpdateParams,
-} from '../resources/modelOperations.js';
-import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
-import { omittedModelError } from '../schema/select.js';
+} from '../../client/resources/modelOperations.js';
+import type { Schema, SchemaRecord, InferModel, InferCreate } from '../../schema/schema.js';
+import { omittedModelError } from '../../schema/select.js';
 import {
   reconcileFunctionalUpdate,
   type ModelUpdater,
   type FunctionalUpdateOptions,
-} from '../resources/functionalUpdate.js';
-import type { HeldClaim } from '../types/streams.js';
-import { AbloConnectionError, AbloValidationError } from '../errors.js';
-import type { OnStaleMode, ReadDependency } from '../coordination/schema.js';
+} from '../../client/resources/functionalUpdate.js';
+import type { HeldClaim, HeldLease } from '../../types/streams.js';
+import { AbloConnectionError, AbloValidationError } from '../../errors.js';
+import type { ReadDependency } from '../../coordination/schema.js';
 import {
-  abortReadSetCommit,
   capturePointRead,
   createReadSetContext,
-  consumeReadSet,
   kReadEvidence,
   prepareReadSet,
   type ReadSetContext,
-} from '../readSetContext.js';
-import { recordHttpCommitReceipt } from '../commitRecordRuntime.js';
-import type { EffectiveAuthority } from '../auth/capability.js';
+} from '../../commit/readSetContext.js';
+import { recordHttpCommitReceipt } from '../../commit/recordRuntime.js';
+import type { EffectiveAuthority } from '../../auth/capability.js';
 
 export interface AbloHttpClientOptions<S extends SchemaRecord>
   extends HttpClientConfig<S> {
@@ -93,9 +92,10 @@ export type HttpModelMutationParams<P> = Omit<P, 'reads'> & {
 
 /**
  * The per-model surface of the stateless HTTP client — everything reachable over
- * request/response: reads (`get` and `list`), writes (`create`, `update`,
- * and `delete`), the durable-lease {@link HttpClaimApi | claim} plane for
- * coordinated writes, and `track`, which registers a durable premise on a row.
+ * request/response: observational reads (`get` and `list`), declared decision
+ * reads (`read`), writes (`create`, `update`,
+ * and `delete`), and the durable-lease {@link HttpClaimApi | claim} plane for
+ * coordinated writes.
  * It deliberately omits the stateful client's local-only
  * reads (the `local` namespace) and live subscriptions (`onChange`), which need
  * a resident graph and a persistent socket; those are absent from the type, so
@@ -105,37 +105,37 @@ export type HttpModelMutationParams<P> = Omit<P, 'reads'> & {
  * than a parallel list it happens to agree with — a verb added here arrives
  * there without a second edit.
  *
- * The typed model contract is transport-independent: `get` returns one row,
- * `list` returns rows, `create`/`update` return the resulting row, and `delete`
+ * The typed model contract is transport-independent: `get` and `read` return
+ * one row, `list` returns rows, `create`/`update` return the resulting row, and `delete`
  * returns nothing. The low-level protocol client keeps its read watermark and
  * commit receipt envelopes internally; callers should not have to change data
  * access syntax when they switch transport.
  */
 export interface HttpModelClient<T, C = T> {
+  /** Reads one current row without declaring it as input to a later decision. */
+  get(params: ModelReadParams & ModelReadOptions): Promise<T | undefined>;
   /**
    * Reads one row by id. Resolves to `undefined` when no such row exists — a
    * miss is data-absence, not an error.
    *
-   * This is the default "get me this row", and the one a stateless client
-   * wants, since it holds nothing locally. A client with a resident graph
-   * answers from it first and falls back to the network, which is why the
-   * synchronous `local.get` exists alongside this: same read, restricted
-   * to what is already here.
+   * Unlike `get`, the exact returned object privately carries model, id, and
+   * readAt evidence. Pass it in one mutation's `reads` array when that mutation
+   * was decided from this version.
    */
-  /** Canonical authoritative point lookup. A miss resolves to `undefined`. */
-  get(params: ModelRetrieveParams & ModelReadOptions): Promise<CapturedRow<T> | undefined>;
-  /** @deprecated Use `get({ id })` for an authoritative point lookup. */
-  retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<CapturedRow<T> | undefined>;
+  read(params: ModelReadParams & ModelReadOptions): Promise<CapturedRow<T> | undefined>;
   /**
-   * Reads the rows matching a filter. Same resolution as `get`, in bulk,
-   * and deduplicated so concurrent identical calls share one request.
+   * Observes the rows matching a filter, deduplicating concurrent identical
+   * calls. List rows are plain values; deliberately `read({ id })` any row a
+   * later mutation depends on.
    */
   /**
    * The rows are an array as before; `hasMore` and `nextCursor` on the result
    * say whether the collection continues past this page. Pass `nextCursor`
    * back as `cursor`, with the same `where` and `orderBy`, to walk it.
    */
-  list(options?: ServerReadOptions<T>): Promise<ModelList<CapturedRow<T>>>;
+  list(options?: ServerReadOptions<T>): Promise<ModelList<T>>;
+  /** Reads every matching row, following cursors with a bounded traversal. */
+  listAll(options?: ListAllOptions<T>): Promise<T[]>;
   /**
    * Creates a row and returns it, including any framework-applied defaults.
    * Passing an id that already exists is idempotent: the existing row is
@@ -148,6 +148,11 @@ export interface HttpModelClient<T, C = T> {
    * of `update` and `delete`.
    */
   create(params: HttpModelMutationParams<ModelCreateParams<T, C>>): Promise<T>;
+  /**
+   * Creates many rows as one atomic commit, and resolves to them in the order
+   * they were given. One rejected row declines the batch.
+   */
+  create(params: HttpModelMutationParams<ModelCreateManyParams<C>>): Promise<T[]>;
   update(params: HttpModelMutationParams<ModelUpdateParams<T, C>>): Promise<T>;
   /**
    * Updates a row with a function of its latest value — `update(id, current =>
@@ -165,24 +170,6 @@ export interface HttpModelClient<T, C = T> {
   ): Promise<T | undefined>;
   delete(params: HttpModelMutationParams<ModelDeleteParams<T, C>>): Promise<void>;
   claim: HttpClaimApi<T, C>;
-  /**
-   * Registers a durable premise on a row — "keep telling me about this one".
-   * Any change that lands on the tracked row rides back on the `notifications`
-   * of this client's next commit, so a long-running agent learns its context
-   * went stale without re-reading. A track it already holds is refreshed, not
-   * duplicated.
-   *
-   * ```ts
-   * await ablo.items.track({ id: 'item_42' });
-   * // …minutes of other work later, on the next write…
-   * const res = await ablo.commits.create({ operations: [ … ] });
-   * res.notifications; // populated if item_42 moved in the meantime
-   * ```
-   *
-   * The returned `notifications` are only the tracks that had ALREADY fired at
-   * registration time; the ongoing signal arrives on later receipts.
-   */
-  track(params: ModelTrackParams): Promise<ModelTrackResult>;
 }
 
 /**
@@ -203,7 +190,7 @@ export type AbloHttpClient<S extends SchemaRecord> = {
   ready(): Promise<void>;
   /** Replays every pending durable HTTP write in seal order and waits for confirmation. */
   waitForFlush(): Promise<void>;
-  readonly commits: CommitResource;
+  readonly commits: CommitResource<ReadDependency | CapturedRow>;
   /**
    * Claim-ticket operations keyed by `claimId`: `retrieve` polls a queued
    * ticket to its grant, `heartbeat` keeps one lease (held or queued) alive,
@@ -266,7 +253,7 @@ function createHttpModelClient<T, C = T>(
   readSetContext: ReadSetContext | undefined,
 ): HttpModelClient<T, C> {
   async function readRow(id: string): Promise<T | undefined> {
-    const read = await protocol.get({ id });
+    const read = await protocol.read({ id });
     capturePointRead(readSetContext, clientIdentity, modelName, id, read.data, read.stamp);
     return read.data;
   }
@@ -300,7 +287,6 @@ function createHttpModelClient<T, C = T>(
     readonly claim?: unknown;
     readonly idempotencyKey?: string | null;
     readonly readAt?: number | null;
-    readonly onStale?: OnStaleMode | null;
     readonly reads?: readonly unknown[] | null;
   }>(
     params: P,
@@ -309,22 +295,16 @@ function createHttpModelClient<T, C = T>(
       readSetContext,
       clientIdentity,
       params.readAt,
-      params.onStale,
       params.idempotencyKey,
       params.reads,
     );
     return {
-      options: {
-        ...mutationOptions(params),
-        ...(prepared.readAt !== undefined ? { readAt: prepared.readAt } : {}),
-        ...(prepared.onStale !== undefined ? { onStale: prepared.onStale } : {}),
-        ...(prepared.reads !== undefined ? { reads: prepared.reads } : {}),
-        ...(prepared.idempotencyKey !== undefined
-          ? { idempotencyKey: prepared.idempotencyKey }
-          : {}),
-      },
-      consumed: prepared.consumed,
-      automaticCommit: prepared.automaticCommit,
+      ...mutationOptions(params),
+      ...(prepared.readAt !== undefined ? { readAt: prepared.readAt } : {}),
+      ...(prepared.reads !== undefined ? { reads: prepared.reads } : {}),
+      ...(prepared.idempotencyKey !== undefined
+        ? { idempotencyKey: prepared.idempotencyKey }
+        : {}),
     };
   }
 
@@ -357,7 +337,7 @@ function createHttpModelClient<T, C = T>(
           model: modelName,
           id: arg,
           readFresh: async () => {
-            const read = await protocol.get({ id: arg });
+            const read = await protocol.read({ id: arg });
             capturePointRead(
               readSetContext,
               clientIdentity,
@@ -369,112 +349,117 @@ function createHttpModelClient<T, C = T>(
             return { data: read.data, stamp: read.stamp };
           },
           writeNext: async (patch, readAt) => {
-            const prepared = preparedMutation(
-              {
-                readAt,
-                onStale: 'reject' as const,
-                reads: options?.reads,
-              },
-            );
-            try {
-              const result = await protocol.update({
-                ...prepared.options,
-                id: arg,
-                data: patch,
-              });
-              consumeReadSet(
-                readSetContext,
-                clientIdentity,
-                prepared.consumed,
-                prepared.automaticCommit,
-              );
-              return result;
-            } catch (error) {
-              abortReadSetCommit(readSetContext, prepared.automaticCommit);
-              throw error;
-            }
+            const opts = preparedMutation({
+              readAt,
+              reads: options?.reads,
+            });
+            return await protocol.update({
+              ...opts,
+              id: arg,
+              data: patch,
+            });
           },
         },
       );
       return receipt === undefined ? undefined : requireUpdatedRow(arg);
     }
 
-    const prepared = preparedMutation(arg);
-    try {
-      await protocol.update({
-        ...prepared.options,
-        id: arg.id,
-        data: arg.data,
-      });
-    } catch (error) {
-      abortReadSetCommit(readSetContext, prepared.automaticCommit);
-      throw error;
-    }
-    consumeReadSet(
-      readSetContext,
-      clientIdentity,
-      prepared.consumed,
-      prepared.automaticCommit,
-    );
+    await protocol.update({
+      ...preparedMutation(arg),
+      id: arg.id,
+      data: arg.data,
+    });
     return requireUpdatedRow(arg.id);
   }
 
   const get = async (
-    params: ModelRetrieveParams & ModelReadOptions,
+    params: ModelReadParams & ModelReadOptions,
+  ): Promise<T | undefined> => {
+    const result = await protocol.read(params);
+    return result.data;
+  };
+
+  const read = async (
+    params: ModelReadParams & ModelReadOptions,
   ): Promise<CapturedRow<T> | undefined> => {
-    const read = await protocol.get(params);
+    const result = await protocol.read(params);
     capturePointRead(
       readSetContext,
       clientIdentity,
       modelName,
       params.id,
-      read.data,
-      read.stamp,
+      result.data,
+      result.stamp,
     );
-    return read.data as CapturedRow<T> | undefined;
+    return result.data as CapturedRow<T> | undefined;
   };
 
+  // `create` is overloaded: one row, or a list of them as one atomic commit.
+  // A real overloaded function rather than a property arrow, so both public
+  // signatures survive — the same reason `updateModel` is written this way.
+  function createModel(
+    params: HttpModelMutationParams<ModelCreateParams<T, C>>,
+  ): Promise<CapturedRow<T>>;
+  function createModel(
+    params: HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<CapturedRow<T>[]>;
+  async function createModel(
+    params:
+      | HttpModelMutationParams<ModelCreateParams<T, C>>
+      | HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<CapturedRow<T> | CapturedRow<T>[]> {
+    const opts = preparedMutation(params);
+    // The list form is one atomic commit through the protocol's batch door.
+    // Same verb because it is the same act; the argument says how many.
+    if (Array.isArray(params.data)) {
+      const rows = await protocol.createMany({
+        data: params.data as readonly Record<string, unknown>[],
+        ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+        ...(opts.reads ? { reads: [...opts.reads] } : {}),
+      });
+      return rows as CapturedRow<T>[];
+    }
+    const single = params as HttpModelMutationParams<ModelCreateParams<T, C>>;
+    const resolvedId = resolveCreateId(single.id, single.data);
+    const row = await protocol.create({
+      ...opts,
+      ...(resolvedId !== undefined ? { id: resolvedId } : {}),
+      data: single.data as Record<string, unknown>,
+    });
+    return row as CapturedRow<T>;
+  }
+
   const list = async (
     options?: ServerReadOptions<T>,
-  ): Promise<ModelList<CapturedRow<T>>> => {
+  ): Promise<ModelList<T>> => {
     const snapshot = await protocol.list(options);
-    const page = modelList<CapturedRow<T>>(
-      snapshot.data as readonly CapturedRow<T>[],
+    return modelList<T>(
+      snapshot.data,
       snapshot,
+      (cursor) => list({ ...options, cursor }),
     );
-    const registry = readSetContext?.getStore();
-    if (!registry) return page;
-    if (!snapshot.evidence) {
-      throw new AbloConnectionError(
-        `${modelName}.list did not return row evidence. Upgrade the Ablo server or use get({ id }).`,
-        { code: 'commit_no_result' },
-      );
-    }
-    const byId = new Map(snapshot.evidence.map((entry) => [entry.id, entry.stamp]));
-    for (const row of snapshot.data) {
-      const id = typeof row === 'object' && row !== null
-        ? Reflect.get(row as object, 'id')
-        : undefined;
-      const stamp = typeof id === 'string' ? byId.get(id) : undefined;
-      if (typeof id !== 'string' || stamp === undefined) {
-        throw new AbloConnectionError(
-          `${modelName}.list returned a row without matching evidence.`,
-          { code: 'commit_no_result' },
-        );
-      }
-      capturePointRead(readSetContext, clientIdentity, modelName, id, row, stamp);
-    }
-    return page;
+  };
+
+  const listAll = async (
+    options: ListAllOptions<T> = {},
+  ): Promise<T[]> => {
+    const { maxPages, signal, ...readOptions } = options;
+    signal?.throwIfAborted();
+    const first = await list(readOptions);
+    return collectModelList(first, { maxPages, signal });
   };
 
   // Claim acquisition performs its authoritative read only after the grant.
   // Preserve that exact post-grant watermark while retaining the callable
-  // namespace and all of its state/queue/release members through the proxy.
+  // namespace and all of its state/list/queue/release/reorder members through the proxy.
   const claim = new Proxy(protocol.claim, {
     apply(target, thisArg, argArray) {
-      const result = Reflect.apply(target, thisArg, argArray) as Promise<HeldClaim<T> | null>;
+      const result = Reflect.apply(target, thisArg, argArray) as Promise<
+        HeldClaim<T> | HeldLease | null
+      >;
       return result.then((held) => {
-        if (held && held.readAt !== undefined) {
+        // A row-free lease (`claim(id)`) carries no snapshot: nothing to capture.
+        if (held && 'data' in held && held.readAt !== undefined) {
           capturePointRead(
             readSetContext,
             clientIdentity,
@@ -491,48 +476,15 @@ function createHttpModelClient<T, C = T>(
 
   return {
     get,
-    retrieve: get,
+    read,
     list,
-    async create(params): Promise<T> {
-      const id = params.id ?? '';
-      const prepared = preparedMutation(params);
-      let row: T;
-      try {
-        row = await protocol.create({
-          ...prepared.options,
-          ...(params.id !== undefined ? { id: params.id } : {}),
-          data: params.data as Record<string, unknown>,
-        });
-      } catch (error) {
-        abortReadSetCommit(readSetContext, prepared.automaticCommit);
-        throw error;
-      }
-      consumeReadSet(
-        readSetContext,
-        clientIdentity,
-        prepared.consumed,
-        prepared.automaticCommit,
-      );
-      return row;
-    },
+    listAll,
+    create: createModel,
     update,
     async delete(params): Promise<void> {
-      const prepared = preparedMutation(params);
-      try {
-        await protocol.delete({ ...prepared.options, id: params.id });
-      } catch (error) {
-        abortReadSetCommit(readSetContext, prepared.automaticCommit);
-        throw error;
-      }
-      consumeReadSet(
-        readSetContext,
-        clientIdentity,
-        prepared.consumed,
-        prepared.automaticCommit,
-      );
+      await protocol.delete({ ...preparedMutation(params), id: params.id });
     },
     claim,
-    track: (params) => protocol.track(params),
   };
 }
 
@@ -581,12 +533,41 @@ export function createAbloHttpClient<S extends SchemaRecord>(
     return created;
   };
 
+  const commits: CommitResource<ReadDependency | CapturedRow> = {
+    async create(commitOptions) {
+      const prepared = prepareReadSet(
+        readSetContext,
+        clientIdentity,
+        commitOptions.readAt,
+        commitOptions.idempotencyKey,
+        commitOptions.reads,
+      );
+      return transport.commits.create({
+        operations: commitOptions.operations,
+        ...(commitOptions.claim !== undefined ? { claim: commitOptions.claim } : {}),
+        ...(commitOptions.wait !== undefined ? { wait: commitOptions.wait } : {}),
+        ...(prepared.readAt !== undefined ? { readAt: prepared.readAt } : {}),
+        ...(prepared.reads !== undefined ? { reads: prepared.reads } : {}),
+        ...(prepared.idempotencyKey !== undefined
+          ? { idempotencyKey: prepared.idempotencyKey }
+          : {}),
+      });
+    },
+    get: (options) => transport.commits.get(options),
+    list: (options) => transport.commits.list(options),
+  };
+
   const facade = new Proxy<Partial<AbloHttpClient<S>>>({}, {
     get(_target, prop) {
       if (prop === kReadEvidence) {
-        return { context: readSetContext, client: clientIdentity };
+        return {
+          context: readSetContext,
+          client: clientIdentity,
+          onChange: transport.onChange,
+        };
       }
       if (typeof prop !== 'string') return undefined;
+      if (prop === 'commits') return commits;
       // Real protocol members pass through unchanged.
       if (isProtocolMember(prop)) {
         return transport[prop];

package/src/transport/http/helpers.ts

@@ -0,0 +1,63 @@
+import { AbloClaimedError, AbloConnectionError } from '../../errors.js';
+import { commitReceiptSchema, type CommitReceiptWire } from '../../commit/contract.js';
+import type { ClaimHeartbeatReply } from '../../claims/contract.js';
+import type { ModelClaim } from '../../client/resources/httpResources.js';
+import { subTarget, streamTarget } from '../../claims/locator.js';
+import { declaredMeta } from '../../claims/meta.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/transport/http/index.ts

@@ -0,0 +1,5 @@
+/** Stateless HTTP transport boundary. */
+export * from './options.js';
+export * from './client.js';
+export * from './transport.js';
+export * from './helpers.js';

package/src/transport/{httpOptions.ts → http/options.ts}

@@ -10,15 +10,15 @@
  * without declaring `extends`; the composition root keeps owning its own type.
  */
 
-import type { Schema, SchemaRecord } from '../schema/schema.js';
-import type { AuthClientOptions } from '../auth/apiKey.js';
-import type { CoordinationObservability } from '../observability.js';
-import type { CommitOutboxScope } from '../transactions/confirmation/commitEnvelope.js';
-import type { CommitReceiptWire } from '../wire/commit.js';
+import type { Schema, SchemaRecord } from '../../schema/schema.js';
+import type { AuthClientOptions } from '../../auth/apiKey.js';
+import type { CoordinationObservability } from '../../observability.js';
+import type { CommitOutboxScope } from '../../commit/confirmation/commitEnvelope.js';
+import type { CommitReceiptWire } from '../../commit/contract.js';
 import type {
   DurableWriteStore,
   DurableWritesConfig,
-} from '../durableWrites.js';
+} from '../../commit/durableWrites.js';
 
 export interface HttpClientConfig<S extends SchemaRecord = SchemaRecord>
   // The credential fields come from the one place that defines them, so this