@abloatai/transaction 0.51.0 → 0.52.0

package/src/source/adapters/kyselyMutationCore.ts

@@ -1,7 +1,7 @@
 /**
  * Reusable Kysely row-mutation core.
  *
- * This is the single schema-field ↔ physical-column translation used by both
+ * This is the single schema-field ↔ database-column translation used by both
  * Kysely transports. It deliberately knows nothing about outboxes, logical
  * markers, or idempotency: wrappers compose those transaction policies around
  * the same `applyOperation` implementation, so direct and endpoint DML cannot
@@ -133,6 +133,11 @@ export function kyselyOperationRowId(operation: Operation): string {
   return id;
 }
 
+function suppliedOperationRowId(operation: Operation): string | undefined {
+  const id = operation.id ?? operation.input?.id;
+  return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+
 /** The transport-independent Kysely field/column mutation boundary. */
 export interface KyselyMutationCore {
   read(request: AdapterReadRequest): Promise<readonly Row[]>;
@@ -159,16 +164,23 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
     columns.fieldToColumn.get(field) ?? camelToSnake(field);
   const fieldFor = (columns: ModelColumns, column: string): string =>
     columns.columnToField.get(column) ?? snakeToCamel(column);
-
   const toColumns = (columns: ModelColumns, row: Row): Row => {
     const out: Row = {};
-    for (const key of Object.keys(row)) out[columnFor(columns, key)] = row[key];
+    for (const key of Object.keys(row)) {
+      out[columnFor(columns, key)] = row[key];
+    }
     return out;
   };
 
   const toFields = (columns: ModelColumns, row: Row): Row => {
     const out: Row = {};
-    for (const key of Object.keys(row)) out[fieldFor(columns, key)] = row[key];
+    for (const key of Object.keys(row)) {
+      const field = fieldFor(columns, key);
+      const value = row[key];
+      out[field] = field === 'id' && value !== null && value !== undefined
+        ? String(value)
+        : value;
+    }
     return out;
   };
 
@@ -179,7 +191,7 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
         const rows = await db
           .selectFrom(columns.table)
           .selectAll()
-          .where('id', '=', request.id)
+          .where(columnFor(columns, 'id'), '=', request.id)
           .limit(1)
           .execute();
         return rows.map((row) => toFields(columns, row));
@@ -194,13 +206,53 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
 
     async applyOperation(transaction, operation): Promise<Row> {
       const columns = modelColumns(operation.model);
-      const id = kyselyOperationRowId(operation);
       const input = operation.input ?? {};
+      if (operation.where && operation.type !== 'UPDATE') {
+        throw new AbloValidationError('where is supported only for UPDATE operations', {
+          code: 'commit_operation_invalid',
+          param: 'where',
+        });
+      }
+
+      if (operation.type === 'CREATE') {
+        const suppliedId = suppliedOperationRowId(operation);
+        const createInput = operation.id == null
+          ? Object.fromEntries(Object.entries(input).filter(([field]) => field !== 'id'))
+          : input;
+        const inserted = await transaction
+          .insertInto(columns.table)
+          .values(toColumns(columns, {
+            ...createInput,
+            ...(operation.id == null
+              ? {}
+              : suppliedId
+                ? { id: suppliedId }
+                : {}),
+          }))
+          .returningAll()
+          .execute();
+        if (!inserted[0]) {
+          throw new AbloValidationError(
+            `${operation.type} on "${operation.model}" returned no source row`,
+            { code: 'source_adapter_misconfigured' },
+          );
+        }
+        const row = toFields(columns, inserted[0]);
+        if (typeof row.id !== 'string' || row.id.length === 0) {
+          throw new AbloValidationError(
+            `${operation.type} on "${operation.model}" did not return a canonical id`,
+            { code: 'source_adapter_misconfigured' },
+          );
+        }
+        return row;
+      }
+
+      const id = kyselyOperationRowId(operation);
 
       if (operation.type === 'DELETE') {
         const deleted = await transaction
           .deleteFrom(columns.table)
-          .where('id', '=', id)
+          .where(columnFor(columns, 'id'), '=', id)
           .returningAll()
           .execute();
         if (!deleted[0]) {
@@ -212,30 +264,25 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
         return toFields(columns, deleted[0]);
       }
 
-      if (operation.type === 'CREATE') {
-        const inserted = await transaction
-          .insertInto(columns.table)
-          .values(toColumns(columns, { id, ...input }))
-          .returningAll()
-          .execute();
-        return inserted[0] ? toFields(columns, inserted[0]) : { id, ...input };
-      }
-
       const patch = toColumns(columns, {
         ...input,
         ...(operation.type === 'ARCHIVE' ? { archivedAt: new Date() } : {}),
         ...(operation.type === 'UNARCHIVE' ? { archivedAt: null } : {}),
       });
-      const updated = await transaction
+      let update = transaction
         .updateTable(columns.table)
         .set(patch)
-        .where('id', '=', id)
-        .returningAll()
-        .execute();
+        .where(columnFor(columns, 'id'), '=', id);
+      for (const [column, value] of Object.entries(toColumns(columns, operation.where ?? {}))) {
+        update = update.where(column, '=', value);
+      }
+      const updated = await update.returningAll().execute();
       if (!updated[0]) {
         throw new AbloValidationError(
-          `${operation.type} on "${operation.model}/${id}" matched no source row`,
-          { code: 'mutate_update_entity_not_found' },
+          operation.where
+            ? `The conditional ${operation.type} on "${operation.model}/${id}" did not match`
+            : `${operation.type} on "${operation.model}/${id}" matched no source row`,
+          { code: operation.where ? 'precondition_failed' : 'mutate_update_entity_not_found' },
         );
       }
       return toFields(columns, updated[0]);

package/src/source/adapters/memory.ts

@@ -54,6 +54,11 @@ export function memoryDataSource(): DataSourceAdapter {
   };
 
   const applyOperation = (op: Operation): Row => {
+    if (op.where) {
+      throw new AbloValidationError('The memory adapter does not support conditional operations', {
+        code: 'source_adapter_misconfigured',
+      });
+    }
     const m = modelStore(op.model);
     const id = rowId(op);
     switch (op.type) {

package/src/source/adapters/prisma.ts

@@ -80,7 +80,7 @@ const lowerFirst = (s: string): string => (s ? s.charAt(0).toLowerCase() + s.sli
  * the adapter, and it reflects a real limit of the type system rather than a
  * shortcut. Writes inside `prisma.$transaction(tx => …)` must go through the
  * transactional client `tx`, and the model is known only as a runtime string.
- * Prisma keys its client by fixed property names (`{ task: TaskDelegate; … }`), so
+ * Prisma keys its client by fixed property names (`{ item: ItemDelegate; … }`), so
  * a dynamic `tx[name]` lookup is `unknown` to the compiler: there is no static key
  * to infer from a string. The cast is checked at runtime immediately afterward by
  * confirming that `findMany` is a function on the resolved delegate.
@@ -149,6 +149,11 @@ export function prismaDataSource<S extends SchemaRecord>(
   void schema; // held for typed reads and model validation
 
   const applyOperation = async (tx: PrismaRaw, op: Operation): Promise<Row> => {
+    if (op.where) {
+      throw new AbloValidationError('The Prisma adapter does not support conditional operations', {
+        code: 'source_adapter_misconfigured',
+      });
+    }
     const delegate = delegateFor(tx, delegateName(op.model));
     const id = rowId(op);
     switch (op.type) {

package/src/source/conformance.ts

@@ -75,7 +75,7 @@ export function mutationConformanceChecks(
         const adapter = await make();
         const result = await adapter.commit(
           request('corr_create', [
-            { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+            { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
           ]),
         );
         assert.equal(result.rows.length, 1, 'one row returned');
@@ -90,12 +90,12 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         await adapter.commit(request('corr_load', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+          { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
         ]));
-        const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
+        const found = await adapter.read({ kind: 'load', model: 'item', id: 't1' });
         assert.equal(found.length, 1);
         assert.equal(found[0]?.title, 'A');
-        const missing = await adapter.read({ kind: 'load', model: 'task', id: 'nope' });
+        const missing = await adapter.read({ kind: 'load', model: 'item', id: 'nope' });
         assert.equal(missing.length, 0, 'unknown id reads empty');
       },
     },
@@ -104,10 +104,10 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         await adapter.commit(request('corr_list', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
-          { type: 'CREATE', model: 'task', id: 't2', input: { title: 'B' } },
+          { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
+          { type: 'CREATE', model: 'item', id: 't2', input: { title: 'B' } },
         ]));
-        const rows = await adapter.read({ kind: 'list', model: 'task' });
+        const rows = await adapter.read({ kind: 'list', model: 'item' });
         assert.deepEqual(rows.map((row) => row.id).sort(), ['t1', 't2']);
       },
     },
@@ -116,12 +116,12 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         const commitRequest = request('corr_replay', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A', n: 1 } },
+          { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A', n: 1 } },
         ]);
         const first = await adapter.commit(commitRequest);
         const second = await adapter.commit(commitRequest);
         assert.deepEqual(second.rows, first.rows, 'replay returns the original rows');
-        const rows = await adapter.read({ kind: 'list', model: 'task' });
+        const rows = await adapter.read({ kind: 'list', model: 'item' });
         assert.equal(rows.length, 1, 'no duplicate row');
       },
     },
@@ -131,13 +131,13 @@ export function mutationConformanceChecks(
         const adapter = await make();
         await adapter.commit(request(
           'corr_conflict',
-          [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }],
+          [{ type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } }],
           'a'.repeat(64),
         ));
         await assert.rejects(
           adapter.commit(request(
             'corr_conflict',
-            [{ type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } }],
+            [{ type: 'UPDATE', model: 'item', id: 't1', input: { title: 'B' } }],
             'b'.repeat(64),
           )),
           (error: unknown) =>
@@ -153,14 +153,14 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         const commitRequest = request('corr_concurrent', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+          { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
         ]);
         const [first, second] = await Promise.all([
           adapter.commit(commitRequest),
           adapter.commit(commitRequest),
         ]);
         assert.deepEqual(second.rows, first.rows);
-        const rows = await adapter.read({ kind: 'list', model: 'task' });
+        const rows = await adapter.read({ kind: 'list', model: 'item' });
         assert.equal(rows.length, 1, 'concurrent retries produced one row');
       },
     },
@@ -169,12 +169,12 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         await adapter.commit(request('corr_create_2', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+          { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
         ]));
         await adapter.commit(request('corr_update_2', [
-          { type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } },
+          { type: 'UPDATE', model: 'item', id: 't1', input: { title: 'B' } },
         ]));
-        const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
+        const found = await adapter.read({ kind: 'load', model: 'item', id: 't1' });
         assert.equal(found[0]?.title, 'B', 'update applied');
       },
     },
@@ -200,7 +200,7 @@ export function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[]
         const request = change('corr_outbox_replay', [
           {
             type: 'CREATE',
-            model: 'task',
+            model: 'item',
             id: 't1',
             input: { title: 'A' },
             transactionId: 'op_outbox_replay',
@@ -223,7 +223,7 @@ export function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[]
         await adapter.commit(change('corr_event', [
           {
             type: 'CREATE',
-            model: 'task',
+            model: 'item',
             id: 't1',
             input: { title: 'A' },
             transactionId: 'op_event',
@@ -232,7 +232,7 @@ export function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[]
         const page = await adapter.events(null, 100);
         const event = page.events.find((candidate) => candidate.entityId === 't1');
         assert.ok(event, 'event for the committed row');
-        assert.equal(event.model, 'task');
+        assert.equal(event.model, 'item');
         assert.equal(event.type, 'CREATE');
         assert.equal(event.correlationId, 'corr_event');
         assert.equal(event.transactionId, 'op_event');
@@ -244,10 +244,10 @@ export function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[]
       run: async () => {
         const adapter = await make();
         await adapter.commit(change('corr_page_a', [
-          { type: 'CREATE', model: 'task', id: 't1', input: {} },
+          { type: 'CREATE', model: 'item', id: 't1', input: {} },
         ]));
         await adapter.commit(change('corr_page_b', [
-          { type: 'CREATE', model: 'task', id: 't2', input: {} },
+          { type: 'CREATE', model: 'item', id: 't2', input: {} },
         ]));
 
         const first = await adapter.events(null, 1);

package/src/source/contract.ts

@@ -79,6 +79,40 @@ export const sourceCommitEchoOperationSchema = z.strictObject({
   transactionId: z.string().min(1).max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH),
 });
 
+/**
+ * Pre-write correlation evidence. A database-generated CREATE has no row id
+ * until its INSERT returns, so the adapter receives the same operation shape
+ * with that one value absent and finalizes it inside the writing transaction.
+ */
+const sourceCommitEchoIntentOperationSchema = sourceCommitEchoOperationSchema.extend({
+  id: z.string().min(1).nullish(),
+});
+
+export const sourceCommitEchoIntentSchema = z
+  .strictObject({
+    version: z.literal(1),
+    correlationId: correlationIdSchema,
+    operations: z
+      .array(sourceCommitEchoIntentOperationSchema)
+      .min(1)
+      .max(ABLO_SOURCE_ECHO_MAX_OPERATIONS)
+      .readonly(),
+  })
+  .superRefine(({ operations }, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, operation] of operations.entries()) {
+      if (seen.has(operation.transactionId)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['operations', index, 'transactionId'],
+          message: 'WAL echo operation transactionIds must be unique',
+        });
+      }
+      seen.add(operation.transactionId);
+    }
+  });
+export type SourceCommitEchoIntent = z.infer<typeof sourceCommitEchoIntentSchema>;
+
 export const sourceCommitEchoMarkerSchema = z
   .strictObject({
     version: z.literal(1),

package/src/source/index.ts

@@ -129,6 +129,7 @@ export {
   sourceCommitEchoSchema,
   sourceCommitEchoOperationSchema,
   sourceCommitEchoMarkerSchema,
+  sourceCommitEchoIntentSchema,
   changeSetSchema,
   outboxEventSchema,
   eventsPageSchema,
@@ -141,6 +142,7 @@ export {
   type Migration,
   type AdapterCapabilities,
   type SourceCommitEchoMarkerWire,
+  type SourceCommitEchoIntent,
 } from './contract.js';
 export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';
 export {

package/src/source/types.ts

@@ -105,6 +105,7 @@ export interface SourceOperation {
   readonly model: string;
   readonly id?: string | null;
   readonly input?: Record<string, unknown> | null;
+  readonly where?: Record<string, unknown> | null;
   readonly transactionId?: string | null;
   readonly readAt?: number | null;
   readonly onStale?: OnStaleMode | null;

package/src/transactionLayer.ts

@@ -17,9 +17,9 @@
  * over a socket, and it joins the seam when its core carrier type exists —
  * see docs/plans/transaction-core-language.md, Tier 3.
  *
- * This is the contract, not a runtime: nothing in this package implements it
- * yet. The first explicit implementation (a headless client, a test harness)
- * gains a compile-time conformance pin against this interface.
+ * This is the contract, not a runtime. The headless HTTP client implements it
+ * as a proxy to the hosted authority; other compositions gain the same
+ * compile-time conformance pin against this interface.
  */
 
 import type { CommitMessage } from './wire/frames.js';

package/src/transport/httpClient.ts

@@ -166,10 +166,10 @@ export interface HttpModelClient<T, C = T> {
    * duplicated.
    *
    * ```ts
-   * await ablo.tasks.track({ id: 'task_42' });
+   * 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 task_42 moved in the meantime
+   * res.notifications; // populated if item_42 moved in the meantime
    * ```
    *
    * The returned `notifications` are only the tracks that had ALREADY fired at
@@ -209,6 +209,10 @@ export type AbloHttpClient<S extends SchemaRecord> = {
   readonly logs: HttpLogsResource;
   /** Server-confirmed authority of the credential, populated by `ready()`. */
   readonly identity: EffectiveAuthority | null;
+  /**
+   * Waits for requests already using this client and commits already scheduled
+   * on its commit lane. Stop accepting application work before calling it.
+   */
   dispose(): Promise<void>;
   /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
   getAuthToken(): Promise<string | null>;

package/src/transport/httpTransport.ts

@@ -203,6 +203,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 +362,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 +496,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 +578,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 +766,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 +822,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 +833,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         });
       }
     }
-    return current;
+    return withOperationResults(current);
   }
 
   async function replayHttpCommitOutbox(): Promise<Map<string, ReplayedHttpCommit>> {
@@ -1111,6 +1153,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 +1435,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 }) {
@@ -2053,7 +2099,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

@@ -101,7 +101,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 +122,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