@abloatai/transaction 0.51.0 → 0.53.0

package/src/transport/httpTransport.ts

@@ -84,6 +84,7 @@ import type {
   ModelMutationOptions,
   ModelReadOptions,
   HttpTransportRead,
+  HttpTransportList,
   HttpLogsResource,
   ModelTarget,
   CreateSessionParams,
@@ -151,6 +152,7 @@ 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';
 import {
   createDurableHttpCommitEnvelope,
   canonicalHttpCommitBody,
@@ -203,6 +205,7 @@ const DEFAULT_CLAIM_TTL_MS = 60_000;
 export interface HttpTransport {
   ready(): Promise<void>;
   waitForFlush(): Promise<void>;
+  /** Drains scheduled commits and active requests. */
   dispose(): Promise<void>;
   purge(): Promise<void>;
   readonly commits: CommitResource;
@@ -361,6 +364,26 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
   let readyPromise: Promise<void> | null = null;
   let effectiveAuthority: EffectiveAuthority | null = null;
   let httpCommitLane: Promise<void> = Promise.resolve();
+  let activeRequests = 0;
+  let requestIdleWaiters: Array<() => void> = [];
+  let disposePromise: Promise<void> | null = null;
+
+  function requestStarted(): void {
+    activeRequests += 1;
+  }
+
+  function requestFinished(): void {
+    activeRequests -= 1;
+    if (activeRequests !== 0) return;
+    const waiters = requestIdleWaiters;
+    requestIdleWaiters = [];
+    for (const resolve of waiters) resolve();
+  }
+
+  function waitForRequestIdle(): Promise<void> {
+    if (activeRequests === 0) return Promise.resolve();
+    return new Promise((resolve) => requestIdleWaiters.push(resolve));
+  }
 
   function runInHttpCommitLane<T>(work: () => Promise<T>): Promise<T> {
     const result = httpCommitLane.then(work);
@@ -475,7 +498,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
    * the commit paths do with their receipt schema. Everywhere else, go through
    * {@link requestJson}, which will not let a response past unvalidated.
    */
-  async function requestRaw(
+  async function performRequest(
     path: string,
     init: RequestInit & {
       readonly idempotencyKey?: string | null;
@@ -557,6 +580,22 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     return body;
   }
 
+  async function requestRaw(
+    path: string,
+    init: RequestInit & {
+      readonly idempotencyKey?: string | null;
+      readonly sealedProtocolVersion?: number;
+    },
+    skipReady = false
+  ): Promise<unknown> {
+    requestStarted();
+    try {
+      return await performRequest(path, init, skipReady);
+    } finally {
+      requestFinished();
+    }
+  }
+
   /**
    * Issues one request and validates its body against the route's schema.
    *
@@ -729,6 +768,11 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     initial: CommitResponse
   ): Promise<CommitResponse> {
     let current = initial;
+    const operationResults = initial.operationResults;
+    const withOperationResults = (receipt: CommitResponse): CommitResponse =>
+      operationResults?.length
+        ? { ...receipt, operationResults }
+        : receipt;
     const correlationId = initial.correlationId;
     const deadlineAt = requestTimeoutMs > 0 ? Date.now() + requestTimeoutMs : null;
 
@@ -780,7 +824,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         if (confirmationDeadline) clearTimeout(confirmationDeadline);
       }
 
-      if (current.status === 'confirmed') return current;
+      if (current.status === 'confirmed') return withOperationResults(current);
       const delayMs =
         deadlineAt === null
           ? HTTP_CONFIRMATION_POLL_INTERVAL_MS
@@ -791,7 +835,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         });
       }
     }
-    return current;
+    return withOperationResults(current);
   }
 
   async function replayHttpCommitOutbox(): Promise<Map<string, ReplayedHttpCommit>> {
@@ -1111,6 +1155,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       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),
@@ -1392,6 +1437,9 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           ? { notifications: body.notifications }
           : {}),
         ...(body.missingIds && body.missingIds.length > 0 ? { missingIds: body.missingIds } : {}),
+        ...(body.operationResults && body.operationResults.length > 0
+          ? { operationResults: body.operationResults }
+          : {}),
       };
     },
     get({ id }) {
@@ -1447,9 +1495,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
   async function listModel<T>(
     modelName: string,
     options?: ServerReadOptions<T>,
-  ): Promise<{ readonly data: readonly T[]; readonly evidence?: readonly { id: string; stamp: number }[] }> {
+  ): Promise<HttpTransportList<T>> {
     const params = new URLSearchParams();
     if (options?.limit !== undefined) params.set('limit', String(options.limit));
+    if (options?.cursor !== undefined) {
+      params.set('cursor', options.cursor);
+    }
     if (options?.orderBy) {
       const [col, dir] = Object.entries(options.orderBy)[0] ?? [];
       if (col) {
@@ -1457,12 +1508,27 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         if (dir === 'desc') params.set('order', 'desc');
       }
     }
-    // The collection route turns any non-reserved query param into an equality
-    // filter (`?status=todo`). The wire is AND-only equality — matches what a
-    // stateless reactor needs; richer predicates stay on the stateful path.
-    if (options?.where && typeof options.where === 'object') {
-      for (const [k, v] of Object.entries(options.where as Record<string, unknown>)) {
-        if (v !== undefined && v !== null && typeof v !== 'object') params.set(k, String(v));
+    // The whole filter travels as the canonical clause list, so every operator
+    // the grammar declares survives the trip. The previous encoding walked the
+    // object's own entries and skipped any value that was an object, which
+    // silently discarded `IN` filters and every tuple-form clause: the request
+    // went out unfiltered and the caller read the result as a filtered one.
+    const clauses = normalizeWhere(options?.where);
+    if (clauses.length > 0) {
+      params.set('where', JSON.stringify(clauses));
+      // Plain equality also goes out in the older `?column=value` shorthand.
+      // A server that predates the `where` parameter does not reserve the name
+      // and does not declare it as a column, so it skips it — and a dropped
+      // filter is not an error there, it is a wider answer than the caller
+      // asked for. Sending both means a version skew loses only the operator
+      // filters, which that server could not have honoured anyway. A current
+      // server ignores a shorthand key the clause list already carries.
+      for (const clause of clauses) {
+        const [column] = clause;
+        const value = clause.length === 2 ? clause[1] : clause[2];
+        if (clause.length === 3 && clause[1] !== '=') continue;
+        if (value === null || typeof value === 'object') continue;
+        params.set(column, String(value));
       }
     }
     const qs = params.toString();
@@ -1477,6 +1543,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     // the typed facade above, which holds the model's schema.
     return {
       data: res.data as T[],
+      hasMore: res.has_more,
+      nextCursor: res.next_cursor,
       ...(res.evidence ? { evidence: res.evidence } : {}),
     };
   }
@@ -2053,7 +2121,16 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         const replayed = await replayHttpCommitOutbox();
         await confirmReplayedHttpCommits(replayed);
       }),
-    async dispose() {},
+    dispose() {
+      if (!disposePromise) {
+        const scheduledCommits = httpCommitLane;
+        disposePromise = (async () => {
+          await scheduledCommits;
+          await waitForRequestIdle();
+        })();
+      }
+      return disposePromise;
+    },
     async purge() {},
     commits,
     claims,

package/src/transport/wsFrameHandlers.ts

@@ -222,6 +222,9 @@ const handleMutationResult: WsFrameHandler = (session, message) => {
         ...(receipt.missingIds && receipt.missingIds.length > 0
           ? { missingIds: receipt.missingIds }
           : {}),
+        ...(receipt.operationResults && receipt.operationResults.length > 0
+          ? { operationResults: receipt.operationResults }
+          : {}),
           }),
     );
   } else {

package/src/types/global.ts

@@ -51,7 +51,7 @@ export interface DefaultSyncShape {
   // `models` is a `SchemaRecord` (not `Record<string, unknown>`) so that
   // `ResolveSchema['models']` still satisfies the `R extends SchemaRecord`
   // bound on the SDK hooks when no `Register` is present — e.g. a shared
-  // package (`@ablo/documents`, `@ablo/teams`) typechecked standalone, with no
+  // package (`feature packages`) typechecked standalone, with no
   // app registration in scope. Without this the fallback wouldn't type-check
   // against `useAblo<R>()`/`AbloProvider<R>` and every such package would need
   // its own ambient registration.

package/src/types/streams.ts

@@ -629,12 +629,12 @@ export interface Claim<T = Record<string, unknown>, M = ResolveClaimMeta> {
   revoke?: () => void;
   /**
    * Extend the lease past the liveness window — the "still working" signal
-   * for long-running tasks. Resolving means the lease is still yours, now
+   * for long-running items. Resolving means the lease is still yours, now
    * good until the returned `expiresAt`; a lease that lapsed (and may have
    * been granted to the next in line) rejects with an
    * {@link ../errors.js AbloClaimedError} carrying code `claim_lost`, so the
    * failed beat doubles as the loss notification. Each beat's extension is
-   * clamped server-side — hold a long task by beating on a cadence (pass
+   * clamped server-side — hold a long item by beating on a cadence (pass
    * `heartbeat` when claiming to have the SDK do this for you), not by
    * asking once for a huge window. Present only on a claim you hold.
    */

package/src/wire/accountResponses.ts

@@ -14,6 +14,7 @@
  */
 
 import { z } from 'zod';
+import { listEnvelopeSchema } from './listEnvelope.js';
 // Composed, never restated: these are the artifact's own shapes, and a
 // hand-written mirror here would be a second copy of the exact record this
 // response exists to stop withholding.
@@ -45,16 +46,9 @@ export type ProjectResponse = z.infer<typeof projectResponseSchema>;
 /**
  * `GET /v1/projects`.
  *
- * Note what this is NOT: the canonical {@link ListEnvelope}. An org's projects
- * are returned whole, so the route emits `data` with no `has_more`/`next_cursor`
- * beside it. That divergence is real and this schema states it rather than
- * describing a pagination the endpoint does not implement — adding the two
- * fields is an API change, not a documentation fix.
+ * Uses the canonical paginated list envelope shared by every collection.
  */
-export const projectListResponseSchema = z.object({
-  object: z.literal('list'),
-  data: z.array(projectResponseSchema).readonly(),
-});
+export const projectListResponseSchema = listEnvelopeSchema(projectResponseSchema);
 export type ProjectListResponse = z.infer<typeof projectListResponseSchema>;
 
 /** One minted key, returned exactly once — the plaintext is never readable again. */
@@ -101,7 +95,7 @@ export const conflictAxisWireSchema = z.object({
 
 /** One model in the deployed schema, as the schema read reports it. */
 export const schemaModelResponseSchema = z.object({
-  /** The key local code addresses (`ablo.documents`). */
+  /** The key local code addresses (`ablo.records`). */
   key: z.string(),
   /** The wire typename the engine routes and gates on. */
   typename: z.string(),
@@ -122,7 +116,7 @@ export const schemaModelResponseSchema = z.object({
    *
    * The schema artifact has always carried these and this response dropped
    * them, so a caller with no local schema declaration — which is every caller
-   * that is not TypeScript — had no way to learn that `task.title` is a
+   * that is not TypeScript — had no way to learn that `item.title` is a
    * required string. It found out from a 400 at the end of a round trip.
    *
    * For an agent that is not merely slow, it is a reasoning detour: a typo

package/src/wire/claims.ts

@@ -121,7 +121,13 @@ export const listQuerySchema = z.object({
   limit: z.string().optional(),
   order_by: z.string().optional(),
   order: z.enum(['asc', 'desc']).optional(),
-  /** Keyset cursor: the id of the last row from the previous page. */
+  /**
+   * Keyset cursor: the opaque `next_cursor` the previous page returned. It
+   * encodes the sort position it was issued for, so it is not a row id and is
+   * refused against a different `order_by`/`order`.
+   */
+  cursor: z.string().optional(),
+  /** @deprecated The pre-0.53.0 spelling of `cursor`. Send `cursor`. */
   starting_after: z.string().optional(),
 });
 export type ListQuery = z.infer<typeof listQuerySchema>;

package/src/wire/commit.ts

@@ -102,6 +102,31 @@ export type CommitWait = z.infer<typeof commitWaitSchema>;
 const missingIdsSchema = z.array(z.string().min(1));
 const notificationsSchema = z.array(staleNotificationSchema);
 
+export const commitOperationOutcomeSchema = z.enum([
+  'created',
+  'updated',
+  'deleted',
+  'archived',
+  'unarchived',
+]);
+
+export const commitOperationResultSchema = z.strictObject({
+  transactionId: z.string().min(1),
+  outcome: commitOperationOutcomeSchema,
+  row: z.record(z.string(), z.unknown()),
+});
+export type CommitOperationResult<
+  Row extends Record<string, unknown> = Record<string, unknown>,
+> = Omit<z.infer<typeof commitOperationResultSchema>, 'row'> & { readonly row: Row };
+
+const operationResultsSchema = z
+  .array(commitOperationResultSchema)
+  .min(1)
+  .refine(
+    (results) => new Set(results.map((result) => result.transactionId)).size === results.length,
+    'operation result transactionIds must be unique',
+  );
+
 export const commitActorSchema = z.strictObject({
   kind: participantKindSchema,
   id: z.string().min(1),
@@ -155,6 +180,8 @@ const successfulReceiptCommonShape = {
   authority: effectiveAuthoritySchema,
   notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
+  /** Exact rows returned by the writing transaction; absent on durable replay. */
+  operationResults: operationResultsSchema.optional(),
 } as const;
 
 const queuedCommitReceiptSchema = queuedCommitStatusSchema.safeExtend(
@@ -316,6 +343,7 @@ export type CommitExecutionResult = z.infer<typeof commitExecutionResultSchema>;
 const ackCommonShape = {
   notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
+  operationResults: operationResultsSchema.optional(),
 } as const;
 
 /** Normalized acknowledgement handed from a mutation transport to the queue. */
@@ -350,6 +378,7 @@ export const clientCommitReceiptSchema = z.strictObject({
   lastSyncId: readSetWatermarkSchema.optional(),
   notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
+  operationResults: operationResultsSchema.optional(),
 });
 export type ClientCommitReceipt = z.infer<typeof clientCommitReceiptSchema>;
 
@@ -382,13 +411,14 @@ export const commitOperationBodySchema = z.object({
   action: z.string(),
   model: z.string(),
   data: z.record(z.string(), z.unknown()).nullish(),
+  where: z.record(z.string().min(1), z.unknown()).nullish(),
 });
 export type CommitOperationBody = z.infer<typeof commitOperationBodySchema>;
 
 /** Commit records retain intent metadata but never copy customer mutation data. */
 export const COMMIT_OPERATION_DATA_RETENTION = 'redacted' as const;
 export const commitRecordOperationSchema = commitOperationBodySchema
-  .omit({ data: true })
+  .omit({ data: true, where: true })
   .safeExtend({ data: z.strictObject({ retention: z.literal(COMMIT_OPERATION_DATA_RETENTION) }) });
 export type CommitRecordOperation = z.infer<typeof commitRecordOperationSchema>;
 

package/src/wire/index.ts

@@ -22,7 +22,13 @@ export {
   INTERNAL_ERROR_PUBLIC_MESSAGE,
 } from './errorEnvelope.js';
 export type { ErrorEnvelope } from './errorEnvelope.js';
-export { listEnvelopeSchema, listEnvelope } from './listEnvelope.js';
+export {
+  listEnvelopeSchema,
+  listEnvelope,
+  CURSOR_PARAM,
+  CURSOR_PARAM_ALIAS,
+  CURSOR_PARAM_NAMES,
+} from './listEnvelope.js';
 export type { ListEnvelope } from './listEnvelope.js';
 
 // The `GET /v1/logs` feed — the two arms, their envelope, and the cursor that
@@ -99,6 +105,8 @@ export {
   commitStatusSchema,
   commitWaitSchema,
   commitReceiptSchema,
+  commitOperationOutcomeSchema,
+  commitOperationResultSchema,
   rejectedCommitReceiptSchema,
   mutationResultPayloadSchema,
   mutationResultMessageSchema,
@@ -121,6 +129,7 @@ export {
 } from './commit.js';
 export type {
   CommitOperationBody,
+  CommitOperationResult,
   CommitActor,
   CommitAttempt,
   CommitClaimReference,

package/src/wire/listEnvelope.ts

@@ -10,6 +10,29 @@
  */
 import { z } from 'zod';
 
+/**
+ * The query parameter a caller resumes a collection with, and the single alias
+ * retained for it.
+ *
+ * Declared beside the envelope that issues `next_cursor`, because the parameter
+ * and the field it consumes are one contract and both planes read them: the
+ * server to know which names are taken, the spec generator to document them,
+ * the client to send one. When the name lived in each of those separately, this
+ * spec described `starting_after` for a model list and `cursor` for a commit
+ * record list — the same concept under two names, in one document.
+ *
+ * `starting_after` is the spelling used through 0.52.0. It borrowed a name whose
+ * established meaning elsewhere is a row id, while this value has always been an
+ * opaque token bound to the sort it was issued for.
+ */
+export const CURSOR_PARAM = 'cursor';
+
+/** @deprecated The pre-0.53.0 spelling of {@link CURSOR_PARAM}. */
+export const CURSOR_PARAM_ALIAS = 'starting_after';
+
+/** Both names a cursor may arrive under, for reserving them in a query string. */
+export const CURSOR_PARAM_NAMES: readonly string[] = [CURSOR_PARAM, CURSOR_PARAM_ALIAS];
+
 /**
  * Builds the authoritative list-envelope schema for a row schema. Keeping the
  * item validator generic lets every endpoint share the same envelope contract

package/src/wire/protocol.ts

@@ -16,7 +16,7 @@
  * The lease is three ping intervals long and is renewed on every ping, so a
  * live holder always has at least two intervals of runway and a silent one
  * lapses about two missed pings after it stops renewing. The window measures
- * liveness, not how long a task may run: widening the lease without also
+ * liveness, not how long a item may run: widening the lease without also
  * widening the ping makes holders flap, and neither value should be redefined
  * anywhere else.
  */