@abloatai/transaction 0.56.0 → 0.58.0

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

@@ -7,11 +7,9 @@
 
 import type {
   ClaimHeartbeatAckPayload,
-  OnStaleMode,
   ReadDependency,
-  TrackDependency,
-} from '../coordination/schema.js';
-import type { ClaimHeartbeatReply, ClaimState } from '../wire/claims.js';
+} from '../../coordination/schema.js';
+import type { ClaimHeartbeatReply, ClaimState } from '../../claims/contract.js';
 import type {
   ClientCommitReceipt,
   CommitWait,
@@ -19,10 +17,13 @@ import type {
   CommitRecordList,
   CommitRecordListOptions,
   CommitRecordWhere,
-} from '../wire/commit.js';
-import type { LogListResponse, LogQuery } from '../wire/feedEvent.js';
-import type { ModelListEvidence } from '../wire/modelResponses.js';
-// Re-exported, not redeclared. `wire/commit.ts` owns the commit-status vocabulary
+  CommitOperationBody,
+  ModelOperationAction,
+} from '../../commit/contract.js';
+import type { LogListResponse, LogQuery } from '../../observation/feedContract.js';
+import type { ModelListEvidence } from '../../wire/modelResponses.js';
+import { AbloValidationError } from '../../errors.js';
+// Re-exported, not redeclared. `commit/contract.ts` owns the commit-status vocabulary
 // and derives the waitable subset from it; this module serves that name to SDK
 // consumers. Restating the subset here as its own union produced a type that
 // matched the canonical one only by both happening to list the same two
@@ -33,36 +34,34 @@ export type { CommitWait };
 // claim view) are defined in `../coordination/schema`, derived from a single
 // schema so the client, the HTTP client, and the server share one definition.
 // They are re-exported here so the resource types live behind one import.
-import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
+import type { ModelTarget, ModelClaim } from '../../coordination/schema.js';
 export type { ModelTarget, ModelClaim };
-import type { ResolveClaimMeta } from '../types/global.js';
-import type { ParticipantKind } from '../types/participant.js';
-import type { SchemaRecord } from '../schema/schema.js';
-import type { SyncGroupInput } from '../schema/roles.js';
+import type { ResolveClaimMeta } from '../../types/global.js';
+import type { ParticipantKind } from '../../types/participant.js';
+import type { SchemaRecord } from '../../schema/schema.js';
+import type { SyncGroupInput } from '../../schema/roles.js';
 // The capability vocabulary — `auth/capability.ts` owns what a grant is on both
 // axes, and these params are the surface a developer declares it through.
 import type {
   CapabilityCan,
   CapabilityOperation,
   EffectiveAuthority,
-} from '../auth/capability.js';
+} from '../../auth/capability.js';
 import type {
   Claim,
   ClaimStream,
   ClaimWaitOptions,
   Duration,
   HeldClaim,
-} from '../types/streams.js';
+} from '../../types/streams.js';
 import type { ModelUpdater, FunctionalUpdateOptions } from './functionalUpdate.js';
 import type {
   ClaimOptions,
   ClaimAttemptEvent,
-  ClaimParams,
-  ClaimSkipParams,
+  ClaimCall,
   ClaimReadApi,
   AwaitedClaimMethod,
-  ModelTrackParams,
-  ModelTrackResult,
+  ModelCreateManyParams,
   ServerReadOptions,
 } from './modelOperations.js';
 
@@ -70,19 +69,15 @@ import type {
 
 /**
  * The operations available on each model in the sync engine:
- *   `get({ id })` — an async single-row server read
+ *   `get({ id })` — an observational async single-row server read
+ *   `read({ id })` — an async single-row server read that may guard a write
  *   `list({ where })` — an async collection server read
  *   `local.get(id)` / `local.list(...)` / `local.count(...)` — synchronous local reads
  *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
  *   `claim({ id })` — a durable claim handle for coordinated writes
  */
 
-export type ModelOperationAction =
-  | 'create'
-  | 'update'
-  | 'delete'
-  | 'archive'
-  | 'unarchive';
+export type { ModelOperationAction };
 
 
 /** @internal Transport envelope; the public typed client returns the row. */
@@ -130,20 +125,119 @@ export interface HttpTransportList<T = Record<string, unknown>> {
  * and a complete one the same value, so the caller with 500 matching rows got
  * 20 and no way to find out.
  */
-export type ModelList<T> = T[] & Pick<HttpTransportList<T>, 'hasMore' | 'nextCursor'>;
+export type ModelList<T> = T[] & Pick<HttpTransportList<T>, 'hasMore' | 'nextCursor'> &
+  AsyncIterable<T>;
 
 /**
- * Attach the page state to the rows. Non-enumerable so the result stays
- * indistinguishable from a plain array everywhere the properties aren't read.
+ * How far a `for await` over a list will walk before it gives up.
+ *
+ * A cursor that stops advancing would otherwise spin forever. The bound is
+ * high enough that no real collection reaches it and low enough that a broken
+ * server is a failed read rather than a hung process.
+ */
+const AUTO_PAGE_LIMIT = 10_000;
+const LIST_ALL_PAGE_LIMIT = 100;
+
+const nextPageFor = new WeakMap<object, (cursor: string) => Promise<ModelList<unknown>>>();
+
+export interface ModelListWalkOptions {
+  readonly maxPages?: number;
+  readonly signal?: AbortSignal;
+}
+
+async function* walkModelList<T>(
+  first: ModelList<T>,
+  options: ModelListWalkOptions = {},
+): AsyncGenerator<T> {
+  const maxPages = options.maxPages ?? AUTO_PAGE_LIMIT;
+  if (!Number.isInteger(maxPages) || maxPages < 1) {
+    throw new AbloValidationError('maxPages must be a positive integer.', {
+      code: 'invalid_options',
+      param: 'maxPages',
+    });
+  }
+
+  let current = first;
+  for (let visited = 0; visited < maxPages; visited += 1) {
+    options.signal?.throwIfAborted();
+    for (let i = 0; i < current.length; i += 1) {
+      options.signal?.throwIfAborted();
+      yield current[i] as T;
+    }
+    const cursor = current.nextCursor;
+    const fetchNext = nextPageFor.get(current) as
+      | ((nextCursor: string) => Promise<ModelList<T>>)
+      | undefined;
+    if (!current.hasMore || cursor === null || fetchNext === undefined) return;
+    const next = await fetchNext(cursor);
+    if (next.nextCursor === cursor) {
+      throw new AbloValidationError(
+        `Walking this list received the same continuation cursor twice (${JSON.stringify(cursor)}). ` +
+          'The collection may be incomplete, so traversal stopped with an error.',
+        { code: 'malformed_response', param: 'nextCursor' },
+      );
+    }
+    current = next;
+  }
+  throw new AbloValidationError(
+    `Walking this list passed ${maxPages} pages without reaching the end. ` +
+      `Narrow the read with \`where\` or raise \`maxPages\` deliberately.`,
+    { code: 'invalid_options', param: 'maxPages' },
+  );
+}
+
+/** Collect a complete list through the same guarded cursor loop as async iteration. */
+export async function collectModelList<T>(
+  first: ModelList<T>,
+  options: ModelListWalkOptions = {},
+): Promise<T[]> {
+  const rows: T[] = [];
+  for await (const row of walkModelList(first, {
+    maxPages: options.maxPages ?? LIST_ALL_PAGE_LIMIT,
+    signal: options.signal,
+  })) rows.push(row);
+  return rows;
+}
+
+/**
+ * Attach the page state to the rows, and make the list walk its own pages.
+ *
+ * `hasMore` and `nextCursor` are non-enumerable, so the result stays
+ * indistinguishable from a plain array everywhere they are not read: it maps,
+ * filters, spreads, and `JSON.stringify`s exactly as the rows always did.
+ *
+ * The async iterator is the answer to the question that shape raises. A list
+ * read is a page — the server applies a default size and caps the largest —
+ * and a page of 20 looks precisely like a complete answer of 20, so every
+ * caller either checked `hasMore` or, far more often, reasoned about a
+ * truncated set without knowing it. Hand-rolled page walkers were the common
+ * result, and each one re-derived the same cursor loop and the same
+ * non-advancing-cursor guard.
+ *
+ * So iterate the value to get the page, and `for await` it to get the
+ * collection:
+ *
+ * ```ts
+ * const page = await ablo.issue.list({ where: { teamId } });
+ * for (const issue of page) …            // the 20 rows that came back
+ * for await (const issue of page) …      // every issue, paged as it goes
+ * ```
  */
 export function modelList<T>(
   rows: readonly T[],
   page: Pick<HttpTransportList<unknown>, 'hasMore' | 'nextCursor'>,
+  /** Reads the page after `cursor`. Omitted where no transport can follow. */
+  fetchNext?: (cursor: string) => Promise<ModelList<T>>,
 ): ModelList<T> {
-  return Object.defineProperties([...rows], {
+  const list = Object.defineProperties([...rows], {
     hasMore: { value: page.hasMore, enumerable: false },
     nextCursor: { value: page.nextCursor, enumerable: false },
+    [Symbol.asyncIterator]: { value: () => walkModelList(list), enumerable: false },
   }) as ModelList<T>;
+  if (fetchNext) {
+    nextPageFor.set(list, fetchNext as (cursor: string) => Promise<ModelList<unknown>>);
+  }
+  return list;
 }
 
 export type IfClaimedPolicy = 'return' | 'fail';
@@ -158,7 +252,7 @@ export interface ClaimedOptions {
   readonly ifClaimed?: IfClaimedPolicy;
 }
 
-export type { ClaimWaitOptions } from '../types/streams.js';
+export type { ClaimWaitOptions } from '../../types/streams.js';
 
 export interface ModelReadOptions extends ClaimedOptions {}
 
@@ -206,35 +300,22 @@ export interface ClaimCreateOptions {
   readonly onStatus?: (event: ClaimAttemptEvent) => void;
 }
 
-export interface CommitOperationInput {
-  readonly action: ModelOperationAction;
-  /** The model name — matches `ablo.<model>` and the schema's `model()`. */
-  readonly model: string;
-  readonly id?: string | null;
-  readonly data?: Record<string, unknown> | null;
-  readonly where?: Record<string, unknown> | null;
-  readonly transactionId?: string | null;
-  /** Claim identity derived from a held claim; not an application id. */
-  readonly claimId?: string | null;
-  readonly readAt?: number | null;
-  readonly onStale?: OnStaleMode | null;
-  /** Fencing token (Option B) from the batch's claim handle; server-validated. */
-  readonly fenceToken?: number | null;
-}
+/** Public commit operation inferred from the canonical request-body schema. */
+export type CommitOperationInput = CommitOperationBody;
+
+export type CommitClaim = Omit<Claim<unknown>, 'data'>;
 
-export interface CommitCreateOptions {
+export interface CommitCreateOptions<Read = ReadDependency> {
   readonly idempotencyKey?: string | null;
   readonly readAt?: number | null;
-  readonly onStale?: OnStaleMode | null;
   /**
    * A claim handle from `ablo.<model>.claim({ id })` (or the HTTP claim
    * surface). Same vocabulary as the per-model writes: the handle's
-   * snapshot watermark becomes the batch `readAt` default and `onStale`
-   * defaults to `'reject'`, so a commit that follows a claim is guarded
+   * snapshot watermark becomes the batch `readAt` default, so a commit that follows a claim is guarded
    * against concurrent edits without re-stating the watermark by hand.
-   * Explicit `readAt`/`onStale` on the options win.
+   * An explicit `readAt` on the options wins.
    */
-  readonly claim?: Claim | null;
+  readonly claim?: CommitClaim | null;
   /** One atomic batch. Use a one-element array for a single operation. */
   readonly operations: readonly CommitOperationInput[];
   readonly wait?: CommitWait;
@@ -242,27 +323,17 @@ export interface CommitCreateOptions {
    * The batch premise — the "did anything I looked at change?" guard.
    * Declare the rows (`{ model, id, readAt, fields? }`) or sync groups
    * (`{ group, readAt }`, for example `report:abc`) this batch was premised on; the
-   * server checks that none moved since `readAt` and fires the entry's `onStale`
-   * over the batch. This is distinct from the write-target `readAt`: it guards what
+   * server rejects the batch if any moved since `readAt`. This is distinct from the write-target `readAt`: it guards what
    * you read, not what you write.
    */
-  readonly reads?: readonly ReadDependency[] | null;
-  /**
-   * Durable premises to register as part of this batch — the persisted
-   * sibling of `reads`. Where `reads` guards only this commit, a `track` entry
-   * (`{ model, id, readAt? }` for a row or `{ group, readAt? }` for a sync group)
-   * lives on past it: a later matching change rides back on a future receipt's
-   * `notifications`. A track-only batch (just `track`, an empty `operations`) is
-   * the batch form of `ablo.<model>.track()`.
-   */
-  readonly track?: readonly TrackDependency[] | null;
+  readonly reads?: readonly Read[] | null;
 }
 
 /** Public projection inferred from the canonical runtime schema. */
 export type CommitReceipt = ClientCommitReceipt;
 
-export interface CommitResource {
-  create(options: CommitCreateOptions): Promise<CommitReceipt>;
+export interface CommitResource<Read = ReadDependency> {
+  create(options: CommitCreateOptions<Read>): Promise<CommitReceipt>;
   get(options: { readonly id: string }): Promise<CommitRecord | null>;
   list(options?: CommitRecordListOptions): Promise<CommitRecordList>;
 }
@@ -330,15 +401,16 @@ export interface HttpClaimsResource {
 }
 
 export interface ModelMutationOptions extends ClaimedOptions {
-  readonly claimRef?: string | { readonly id: string } | null;
   readonly idempotencyKey?: string | null;
-  readonly readAt?: number | null;
-  readonly onStale?: OnStaleMode | null;
   /** Commit-lifetime read dependencies checked before this mutation lands. */
   readonly reads?: readonly ReadDependency[] | null;
-  /** Persisted read dependencies registered by this mutation. */
-  readonly track?: readonly TrackDependency[] | null;
   readonly claim?: Claim | ClaimOptions | null;
+}
+
+/** Internal fields derived from a claim or functional update, never authored on a model write. */
+export interface InternalModelMutationOptions extends ModelMutationOptions {
+  readonly claimRef?: string | { readonly id: string } | null;
+  readonly readAt?: number | null;
   /** Fencing token (Option B) from the claim; server-validated at commit. */
   readonly fenceToken?: number | null;
 }
@@ -349,7 +421,7 @@ export interface ModelMutationOptions extends ClaimedOptions {
  * namespace for multi-step handles and coordination screens.
  *
  * It is the same surface as the reactive claim API, but because every read is a
- * server round-trip, `state`, `queue`, and `reorder` are awaited here. The
+ * server round-trip, `state`, `list`, `queue`, and `reorder` are awaited here. The
  * WebSocket client resolves those synchronously from its local cache, which is what
  * lets it read a claim's state inside a React render; a stateless client has no
  * cache to read, so the promise is unavoidable.
@@ -357,19 +429,14 @@ export interface ModelMutationOptions extends ClaimedOptions {
  * It is derived from `ClaimReadApi` through {@link AwaitedClaimMethod} so the two
  * transports cannot drift: the only difference is the promise wrapper that
  * statelessness forces. `claim({ id })` is identical on both (already async);
- * `state`, `queue`, `reorder`, and `release` are the awaited form.
+ * `state`, `list`, `queue`, `reorder`, and `release` are the awaited form.
  */
 export type HttpClaimApi<
   T = Record<string, unknown>,
   Fields = T,
-> =
-  // The try-claim first: `queue: false` resolves `null` on a held target —
-  // an expected outcome, not an error — while the queued default always
-  // resolves a held claim or rejects with a queue error.
-  ((params: ClaimSkipParams<Fields>) => Promise<HeldClaim<T> | null>) &
-  ((params: ClaimParams<Fields>) => Promise<HeldClaim<T>>) & {
-    [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
-  };
+> = ClaimCall<T, Fields> & {
+  [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
+};
 
 /** @internal String-keyed model routing owned by the private HTTP transport. */
 export interface HttpTransportModel<
@@ -385,10 +452,7 @@ export interface HttpTransportModel<
    *
    * Public callers never see this shape; `createAbloHttpClient` unwraps it.
    */
-  /** Canonical point lookup for the schema-agnostic transport. */
-  get(params: ModelReadOptions & { readonly id: string }): Promise<HttpTransportRead<T>>;
-  /** @deprecated Use `get({ id })`; retained for the private transport compatibility seam. */
-  retrieve(params: ModelReadOptions & { readonly id: string }): Promise<HttpTransportRead<T>>;
+  read(params: ModelReadOptions & { readonly id: string }): Promise<HttpTransportRead<T>>;
   /**
    * Collection read over HTTP (server round-trip). Equality `where`, `orderBy`,
    * and `limit`. The typed public client always exposes `ablo.<model>.list`;
@@ -402,6 +466,12 @@ export interface HttpTransportModel<
    * returned, not the input.
    */
   create(params: ModelMutationOptions & { readonly data: Record<string, unknown>; readonly id?: string | null }): Promise<T>;
+  /**
+   * Creates many rows as one atomic commit and returns them, in the caller's
+   * order. One rejected row declines the batch. The rows are the server's own,
+   * carried back on the commit rather than read again afterwards.
+   */
+  createMany(params: ModelCreateManyParams<Record<string, unknown>>): Promise<T[]>;
   update(params: ModelMutationOptions & { readonly id: string; readonly data: Record<string, unknown> }): Promise<CommitReceipt>;
   /**
    * Update under contention with a function of the latest state —
@@ -425,13 +495,6 @@ export interface HttpTransportModel<
    * schema-agnostic shape stays inside the HTTP transport.
    */
   claim: HttpClaimApi<T, Fields>;
-  /**
-   * Registers a durable premise on a row — request/response, no socket. A track
-   * declares what a caller is watching; it keeps no local copy of the row, so it
-   * belongs to every transport rather than to the reactive client (ADR 0013 §4).
-   * The typed public clients expose it as `ablo.<model>.track`.
-   */
-  track(params: ModelTrackParams): Promise<ModelTrackResult>;
 }
 
 /** A single data operation a scoped **agent** session may perform on a model.
@@ -480,6 +543,11 @@ export interface CreateUserSessionParams<S extends SchemaRecord> {
 export interface CreateAgentSessionParams<S extends SchemaRecord> {
   /** Your agent. `id` becomes the token's `participantId`. */
   agent: { id: string };
+  /** The authenticated person who started this agent run. The backend holding
+   *  the secret key attests this identity, and every resulting delta records
+   *  the agent as actor plus this user as `onBehalfOf`. Persist the user id on
+   *  durable work before enqueueing it so a later worker can supply it here. */
+  onBehalfOf?: { readonly user: { readonly id: string } };
   /** Per-model operation allowlist, typed against the schema's model names. */
   can: CapabilityCan<S>;
   /** Sync groups this session may subscribe to — typed (`'default'` or
@@ -512,6 +580,9 @@ export interface CreateAgentClientParams<S extends SchemaRecord> {
    *  Pass a stable string only when one logical agent must re-attach to its own
    *  held claims across reconnects or restarts. */
   id?: string;
+  /** The authenticated person who started this run. Preserving it on durable
+   *  work and supplying it here gives every write dual-principal attribution. */
+  onBehalfOf?: { readonly user: { readonly id: string } };
   /** A human-readable label for logs and attribution (carried in `userMeta.name`).
    *  It is independent of `id`: two agents that share a `name` still receive
    *  distinct ids and coordinate as separate participants — `name` never derives or

package/src/client/resources/modelCreate.ts

@@ -0,0 +1,73 @@
+/** Canonical create identity and result correlation shared by every client. */
+
+import { v5 as uuidv5 } from 'uuid';
+import { AbloConnectionError } from '../../errors.js';
+import type { CommitOperationResult } from '../../commit/contract.js';
+
+/** Resolve the two supported single-create id spellings. The sibling wins. */
+export function resolveCreateId(
+  explicitId: string | null | undefined,
+  data: unknown,
+): string | undefined {
+  if (typeof explicitId === 'string' && explicitId.length > 0) return explicitId;
+  const inData =
+    typeof data === 'object' && data !== null
+      ? (data as { readonly id?: unknown }).id
+      : undefined;
+  return typeof inData === 'string' && inData.length > 0 ? inData : undefined;
+}
+
+/** Stable across transports and client instances when an idempotency key is supplied. */
+export 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)}`;
+}
+
+/**
+ * Return server-authored create rows in input order.
+ *
+ * Fresh receipts carry operationResults. Durable idempotency replays redact
+ * row data, so that path verifies every expected id with a point read. It may
+ * fail under a write-only policy, but it can never report a partial collection
+ * as success.
+ */
+export async function resolveCreatedRows<T>(input: {
+  readonly modelName: string;
+  readonly ids: readonly string[];
+  readonly operationResults?: readonly CommitOperationResult[];
+  readonly readRow: (id: string) => Promise<T | undefined>;
+}): Promise<T[]> {
+  if (input.operationResults?.length === input.ids.length) {
+    const byId = new Map(
+      input.operationResults.map((result) => [
+        (result.row as { readonly id?: unknown }).id,
+        result.row,
+      ]),
+    );
+    const ordered = input.ids.map((id) => byId.get(id));
+    if (ordered.every((row): row is Record<string, unknown> => row !== undefined)) {
+      return ordered as T[];
+    }
+  }
+
+  const rows = await Promise.all(input.ids.map((id) => input.readRow(id)));
+  const missing = input.ids.filter((_id, index) => rows[index] === undefined);
+  if (missing.length > 0) {
+    throw new AbloConnectionError(
+      `${input.modelName} create confirmed, but ${missing.length} of ${input.ids.length} ` +
+        'server rows could not be recovered from its receipt or verified by id.',
+      { code: 'commit_no_result', details: { missingIds: missing } },
+    );
+  }
+  return rows as T[];
+}