@abloatai/transaction 0.50.0 → 0.52.0

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

package/src/wire/auth.ts

@@ -40,9 +40,10 @@ export const ephemeralKeyRequestSchema = z.object({
    */
   organizationId: z.string().min(1).optional(),
   /**
-   * Resolve this session's schema from a shared project rather than from the
-   * target organization, while its data stays scoped to that organization.
-   * Both fields are set together, and both require `ephemeral:mint-any-org`.
+   * Override the shared project used to resolve this session's schema while
+   * its data stays scoped to the target organization. A cross-organization
+   * mint defaults both coordinates to the caller key's own project. Both
+   * fields are set together, and both require `ephemeral:mint-any-org`.
    */
   schemaProjectId: z.string().min(1).optional(),
   schemaOwnerOrgId: z.string().min(1).optional(),

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

@@ -99,6 +99,8 @@ export {
   commitStatusSchema,
   commitWaitSchema,
   commitReceiptSchema,
+  commitOperationOutcomeSchema,
+  commitOperationResultSchema,
   rejectedCommitReceiptSchema,
   mutationResultPayloadSchema,
   mutationResultMessageSchema,
@@ -121,6 +123,7 @@ export {
 } from './commit.js';
 export type {
   CommitOperationBody,
+  CommitOperationResult,
   CommitActor,
   CommitAttempt,
   CommitClaimReference,

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.
  */