@abloatai/ablo 0.26.0 → 0.28.0

package/dist/transactions/commitEnvelope.js

@@ -0,0 +1,139 @@
+/**
+ * Runtime contracts for retry-safe commits.
+ *
+ * `commitEnvelopeMemberSchema` is the compact pointer stored on an in-memory
+ * transaction. `durableCommitEnvelopeSchema` is the actual outbox record: one
+ * atomic IndexedDB value containing the stable request key, exact ordered wire
+ * operations, and the source mutations it supersedes.
+ */
+import { z } from 'zod';
+import { idempotencyKeySchema } from '../commit/contract.js';
+import { readDependencySchema } from '../coordination/schema.js';
+import { commitOperationSchema } from '../wire/frames.js';
+export const COMMIT_ENVELOPE_VERSION = 1;
+export const COMMIT_ENVELOPE_RECORD_PREFIX = 'commit-envelope:';
+/** One transaction's position in a commit; this is not the envelope itself. */
+export const commitEnvelopeMemberSchema = z
+    .strictObject({
+    idempotencyKey: idempotencyKeySchema,
+    operationIndex: z.number().int().nonnegative(),
+    operationCount: z.number().int().positive(),
+    sealedAt: z.number().int().nonnegative().optional(),
+    sequence: z.number().int().nonnegative().optional(),
+})
+    .refine(({ operationIndex, operationCount }) => operationIndex < operationCount, { message: 'operationIndex must be smaller than operationCount' });
+/** The legacy mutation operation shape sent by the current commit transport. */
+export const durableCommitOperationSchema = commitOperationSchema
+    .pick({
+    type: true,
+    model: true,
+    id: true,
+    input: true,
+    transactionId: true,
+    readAt: true,
+    onStale: true,
+})
+    .extend({
+    model: z.string().min(1),
+    id: z.string().min(1),
+    input: z.record(z.string(), z.unknown()).optional(),
+    transactionId: z.string().min(1).optional(),
+    options: z
+        .strictObject({
+        idempotencyKey: z.string().min(1).max(255).nullable().optional(),
+        label: z.string().min(1).max(255).optional(),
+    })
+        .optional(),
+});
+const durableCommitOptionsSchema = z.strictObject({
+    causedByTaskId: z.string().min(1).nullable().optional(),
+    reads: z.array(readDependencySchema).nullable().optional(),
+});
+export const commitOutboxScopeSchema = z.strictObject({
+    organizationId: z.string().min(1),
+    participantId: z.string().min(1),
+    namespace: z.string().min(1),
+});
+/**
+ * One crash-durable logical commit. Keeping every operation in one record makes
+ * membership and order atomic: recovery can observe the old record or the new
+ * record, never half an envelope.
+ */
+export const durableCommitEnvelopeSchema = z
+    .strictObject({
+    id: z.string().startsWith(COMMIT_ENVELOPE_RECORD_PREFIX),
+    type: z.literal('commit_envelope'),
+    storageVersion: z.literal(COMMIT_ENVELOPE_VERSION),
+    origin: z.enum(['model_batch', 'atomic_commit']),
+    idempotencyKey: idempotencyKeySchema,
+    operations: z.array(durableCommitOperationSchema).min(1).max(500),
+    // Bookkeeping cardinality is independent of the 500 wire-operation cap:
+    // hundreds of same-row offline patches may coalesce into one operation.
+    sourceMutationIds: z.array(z.string().min(1)).default([]),
+    commitOptions: durableCommitOptionsSchema.default({}),
+    scope: commitOutboxScopeSchema.optional(),
+    createdAt: z.number().int().nonnegative(),
+    sealedAt: z.number().int().nonnegative(),
+    /** Monotonic within one client; disambiguates writes sealed in the same ms. */
+    sequence: z.number().int().nonnegative().optional(),
+    timestamp: z.number().int().nonnegative(),
+})
+    .superRefine((envelope, context) => {
+    if (envelope.id !== commitEnvelopeRecordId(envelope.idempotencyKey)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['id'],
+            message: 'Envelope record id must be derived from its idempotency key',
+        });
+    }
+    if (new Set(envelope.sourceMutationIds).size !== envelope.sourceMutationIds.length) {
+        context.addIssue({
+            code: 'custom',
+            path: ['sourceMutationIds'],
+            message: 'Source mutation ids must be unique',
+        });
+    }
+    if (envelope.origin === 'model_batch') {
+        const transactionIds = envelope.operations.map((operation) => operation.transactionId);
+        if (transactionIds.some((id) => typeof id !== 'string' || id.length === 0)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['operations'],
+                message: 'Every model-batch operation must carry a transactionId',
+            });
+        }
+        else if (new Set(transactionIds).size !== transactionIds.length) {
+            context.addIssue({
+                code: 'custom',
+                path: ['operations'],
+                message: 'Model-batch transactionIds must be unique',
+            });
+        }
+    }
+});
+export function commitEnvelopeRecordId(idempotencyKey) {
+    return `${COMMIT_ENVELOPE_RECORD_PREFIX}${idempotencyKey}`;
+}
+/** Constructs validated member metadata when an in-memory batch is formed. */
+export function createCommitEnvelopeMember(value) {
+    return commitEnvelopeMemberSchema.parse(value);
+}
+/**
+ * Freezes the exact JSON request that will be persisted and sent. The JSON
+ * round-trip deliberately applies the same Date/undefined semantics as the
+ * WebSocket transport before the request fingerprint becomes durable.
+ */
+export function createDurableCommitEnvelope(value) {
+    const candidate = {
+        ...value,
+        id: commitEnvelopeRecordId(value.idempotencyKey),
+        type: 'commit_envelope',
+        storageVersion: COMMIT_ENVELOPE_VERSION,
+        timestamp: value.sealedAt,
+    };
+    const serialized = JSON.stringify(candidate);
+    if (serialized === undefined) {
+        throw new TypeError('Commit envelope is not JSON serializable');
+    }
+    return durableCommitEnvelopeSchema.parse(JSON.parse(serialized));
+}

package/dist/transactions/commitOutboxStore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Narrow persistence port for crash-durable commit envelopes.
+ *
+ * Browser clients use {@link DatabaseCommitOutboxStore}. Agent/Node hosts can
+ * inject a workflow-, SQLite-, or filesystem-backed implementation without
+ * coupling TransactionQueue to the browser database/cache implementation.
+ */
+import type { Database } from '../Database.js';
+import type { DurableCommitEnvelope } from './commitEnvelope.js';
+import type { DurableHttpCommitEnvelope } from './httpCommitEnvelope.js';
+export type CommitOutboxRecord = DurableCommitEnvelope | DurableHttpCommitEnvelope;
+export interface CommitOutboxStore {
+    /**
+     * Atomically reserve an envelope and consume the staged records it owns.
+     * Implementations must be scoped to one logical participant + server plane,
+     * reject same-id/different-request seals, and let only one envelope claim a
+     * staged record.
+     */
+    seal(envelope: CommitOutboxRecord, consumedRecordIds: readonly string[]): Promise<void>;
+    /** Load unacknowledged records. Implementations may return untrusted data. */
+    list(): Promise<readonly unknown[]>;
+    /** Remove one definitively settled envelope. */
+    remove(envelopeRecordId: string): Promise<void>;
+}
+/** Strict IndexedDB adapter backed by Database's `__transactions` store. */
+export declare class DatabaseCommitOutboxStore implements CommitOutboxStore {
+    private readonly database;
+    constructor(database: Database);
+    seal(envelope: CommitOutboxRecord, consumedRecordIds: readonly string[]): Promise<void>;
+    list(): Promise<readonly unknown[]>;
+    remove(envelopeRecordId: string): Promise<void>;
+}

package/dist/transactions/commitOutboxStore.js

@@ -0,0 +1,26 @@
+/**
+ * Narrow persistence port for crash-durable commit envelopes.
+ *
+ * Browser clients use {@link DatabaseCommitOutboxStore}. Agent/Node hosts can
+ * inject a workflow-, SQLite-, or filesystem-backed implementation without
+ * coupling TransactionQueue to the browser database/cache implementation.
+ */
+/** Strict IndexedDB adapter backed by Database's `__transactions` store. */
+export class DatabaseCommitOutboxStore {
+    database;
+    constructor(database) {
+        this.database = database;
+    }
+    async seal(envelope, consumedRecordIds) {
+        // This adapter deliberately has no duck-typed fallback. Reporting a
+        // successful seal after a no-op or a non-atomic save/delete handoff would
+        // authorize network dispatch without the durability this port promises.
+        await this.database.sealTransactionRecord(envelope, consumedRecordIds);
+    }
+    async list() {
+        return this.database.getPersistedTransactions();
+    }
+    async remove(envelopeRecordId) {
+        await this.database.removeTransaction(envelopeRecordId);
+    }
+}

package/dist/transactions/commitPayload.d.ts

@@ -1,16 +1,16 @@
 /**
- * Commit-payload projection — the queue's wire vocabulary, lifted out of
- * `TransactionQueue.ts` as a pure leaf (no queue state, no timers).
- *
- * Owns the `Transaction` record shape plus every helper that turns a local
- * transaction into a wire-safe commit operation: schema-field projection
- * (`projectCommitPayload`), write-option projection (`applyWriteOptions`),
- * FK-aware priority scoring, and the transport-error duck-typing used to
- * classify server rejections. Because nothing here touches the queue's
- * runtime, the HTTP commit path can share this projection too.
+ * The vocabulary a local transaction uses on the wire. This module defines the
+ * {@link Transaction} record and the helpers that turn a transaction into a
+ * wire-safe commit operation: schema-field projection
+ * ({@link projectCommitPayload}), write-option projection
+ * ({@link applyWriteOptions}), foreign-key-aware priority scoring
+ * ({@link computePriorityScore}), and the structural checks used to classify
+ * transport errors. Nothing here holds queue state or timers, so the batched
+ * queue path and the HTTP commit path share the same projection.
  */
 import { MutationOperationType } from '../types/index.js';
 import type { MutationOptions, WriteOptions } from '../interfaces/index.js';
+import type { CommitEnvelopeMember } from './commitEnvelope.js';
 export interface UserContext {
     userId: string;
     organizationId: string;
@@ -20,24 +20,22 @@ export interface UserContext {
 /** Wire-format mutation payload (post-projection). */
 export type MutationInput = Record<string, unknown>;
 /**
- * Project a Model's serialized data onto its schema-declared fields
- * and return a wire-safe commit payload. Two jobs:
+ * Projects a model's serialized data onto the fields declared in its schema and
+ * returns a wire-safe commit payload. It does two things:
  *
- *   1. Drop framework internals (`__class`, `__typename`, `clientId`,
+ *   1. Drops framework-internal keys (`__class`, `__typename`, `clientId`,
  *      `syncStatus`) and anything not declared on the model's schema.
- *   2. JSON.stringify values typed as `field.json()` — TEXT columns
- *      storing JSON need explicit stringification; postgres.js won't
- *      auto-serialize for non-JSONB columns.
+ *   2. Passes each declared field's value through unchanged, including
+ *      JSON-typed fields, which are sent as objects rather than pre-serialized
+ *      strings (see the note in the body for why).
  *
- * For updates (`dropUndefined: true`), `undefined` values are also
- * stripped so they don't translate to `SET column = NULL` on the
- * server side.
+ * For updates (`dropUndefined: true`), `undefined` values are also removed so
+ * they are not written as `SET column = NULL` on the server.
  *
- * Fields are read from `ModelRegistry`, populated by
- * `registerModelsFromSchema` at SDK initialization. If the model
- * isn't registered with field metadata (edge case — e.g., tests or
- * manually registered models), projection falls back to identity and
- * the caller gets whatever the Model serialized.
+ * Field metadata comes from the model registry, populated when the schema is
+ * registered at initialization. If a model has no registered field metadata —
+ * for example a manually registered model — projection passes the serialized
+ * data through unchanged apart from dropping the framework keys.
  */
 export declare function projectCommitPayload(modelName: string, source: Record<string, unknown>, opts: {
     dropUndefined: boolean;
@@ -58,60 +56,73 @@ export interface Transaction {
     priorityScore: number;
     writeOptions?: WriteOptions;
     batchId?: string;
+    /**
+     * Stable identity of the wire commit that currently owns this operation.
+     *
+     * A transport failure is ambiguous: the server may have committed the
+     * batch even though the acknowledgement never reached this client. Keeping
+     * this envelope on every member lets the queue replay the exact same ordered
+     * batch with the exact same idempotency key instead of accidentally
+     * re-batching its operations under a fresh key.
+     */
+    commitEnvelope?: CommitEnvelopeMember;
+    /** Pending-mutation journal entries atomically consumed by this envelope. */
+    sourceMutationIds?: string[];
     /** Completed locally without a server operation; no sync echo will arrive. */
     localOnly?: boolean;
-    /** LINEAR PATTERN: syncId threshold - transaction confirms when delta.id >= this value */
+    /** Sync-id threshold: the transaction confirms once a delta with an id at least this value arrives. */
     syncIdNeededForCompletion?: number;
     /**
-     * Resolves when the server has confirmed this transaction (delta arrived
-     * or HTTP ack). Rejects with the originating error if the transaction is
-     * permanently rolled back. Name matches the queue's existing `'confirmed'`
-     * status vocabulary (`commits.create({wait:'confirmed'})`,
-     * `waitForConfirmation`) — gives call sites a single `await` point for
-     * "did my write land?", so failures surface at the source instead of
-     * leaking via silent pool rollback. The rejection error is the same
-     * `AbloError` recorded on the queue's `transaction:failed` event.
+     * Resolves once the server has confirmed this transaction, whether by a delta
+     * or an HTTP acknowledgement, and rejects with the originating error if the
+     * transaction is permanently rolled back. It gives a caller one place to await
+     * the answer to "did my write land?", matching the
+     * `commits.create({ wait: 'confirmed' })` and
+     * {@link TransactionQueue.waitForConfirmation} vocabulary, so a failure
+     * surfaces at the call site instead of only as a silent local rollback. The
+     * rejection value is the same {@link AbloError} carried on the queue's
+     * `transaction:failed` event.
      */
     confirmation?: Promise<void>;
 }
 export declare const normalizeModelKey: (modelName: string) => string;
 export declare const stripModelSuffix: (modelName: string) => string;
 /**
- * FK-ordered create priority.
+ * Returns the priority score used to order create operations by foreign-key
+ * depth, so a parent row commits before its children.
  *
- * Reads `config.modelCreatePriority` out of the runtime SyncEngineContext —
- * this map is populated once at `createSyncEngine(...)` time by walking the
- * schema's `belongsTo` graph (see `computeFKDepthPriority` in
- * `client/createSyncEngine.ts`). The queue stays schema-agnostic: no model
- * names appear here, and consumer applications can override specific
- * priorities via `configOverrides.modelCreatePriority` without touching the
- * SDK.
+ * The score comes from a priority map on the runtime configuration, built once
+ * at initialization by walking the schema's `belongsTo` graph. No model names
+ * are hard-coded here, and an application can override specific priorities
+ * through `configOverrides.modelCreatePriority`.
  *
- * Non-create ops (update/delete/archive/unarchive) don't need FK ordering
- * because the row already exists, so they all share
- * `config.defaultNonCreatePriority`.
+ * Non-create operations (update, delete, archive, unarchive) need no
+ * foreign-key ordering because the row already exists, so they all share the
+ * configured default non-create priority.
  */
 export declare const computePriorityScore: (type: Transaction["type"], modelName: string) => number;
 export declare const TX_TYPE_TO_MUTATION_OP: Record<Transaction['type'], MutationOperationType>;
 export declare function hasStaleWriteOptions(options?: WriteOptions): boolean;
+/** Options whose identity/audit semantics forbid merging two caller writes. */
+export declare function hasCommitCoalescingBarrier(options?: WriteOptions): boolean;
 export interface WriteOperationFields {
     readAt?: number | null;
     onStale?: 'reject' | 'overwrite' | 'notify' | null;
     options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
 }
 /**
- * Project a transaction's `writeOptions` onto the wire operation. Stale
- * guards (`readAt`/`onStale`) ride at the op root; `idempotencyKey`/`label`
- * ride in the op's `options` slot (`MutationOperation.options` — the
- * mutation_log cache key + audit tag). This is the single place the
- * caller-supplied write vocabulary crosses onto the wire.
+ * Copies a transaction's `writeOptions` onto the wire operation. The
+ * stale-context guards (`readAt` and `onStale`) sit at the operation's root,
+ * while `idempotencyKey` and `label` go in its `options` slot — the
+ * `mutation_log` cache key and audit tag. This is the one place caller-supplied
+ * write options cross onto the wire.
  */
 export declare function applyWriteOptions<T extends object>(op: T, transaction: Transaction): T & WriteOperationFields;
 /**
- * Structural shape we duck-type against for transport-layer errors.
- * Captures the union of GraphQL-style and HTTP-style error shapes the
- * mutation executor surfaces — kept narrow on purpose so we don't
- * pretend to know fields the runtime won't always supply.
+ * The structural shape used to inspect transport-layer errors. It covers the
+ * GraphQL-style and HTTP-style error shapes the mutation executor can surface,
+ * and is kept intentionally narrow so it does not claim fields the runtime may
+ * not supply.
  */
 export interface TransportError {
     message?: string;

package/dist/transactions/commitPayload.js

@@ -1,13 +1,12 @@
 /**
- * Commit-payload projection — the queue's wire vocabulary, lifted out of
- * `TransactionQueue.ts` as a pure leaf (no queue state, no timers).
- *
- * Owns the `Transaction` record shape plus every helper that turns a local
- * transaction into a wire-safe commit operation: schema-field projection
- * (`projectCommitPayload`), write-option projection (`applyWriteOptions`),
- * FK-aware priority scoring, and the transport-error duck-typing used to
- * classify server rejections. Because nothing here touches the queue's
- * runtime, the HTTP commit path can share this projection too.
+ * The vocabulary a local transaction uses on the wire. This module defines the
+ * {@link Transaction} record and the helpers that turn a transaction into a
+ * wire-safe commit operation: schema-field projection
+ * ({@link projectCommitPayload}), write-option projection
+ * ({@link applyWriteOptions}), foreign-key-aware priority scoring
+ * ({@link computePriorityScore}), and the structural checks used to classify
+ * transport errors. Nothing here holds queue state or timers, so the batched
+ * queue path and the HTTP commit path share the same projection.
  */
 import { getContext } from '../context.js';
 import { getActiveRegistry } from '../ModelRegistry.js';
@@ -19,24 +18,22 @@ import { MutationOperationType } from '../types/index.js';
  */
 const FRAMEWORK_KEYS = new Set(['__class', '__typename', 'clientId', 'syncStatus']);
 /**
- * Project a Model's serialized data onto its schema-declared fields
- * and return a wire-safe commit payload. Two jobs:
+ * Projects a model's serialized data onto the fields declared in its schema and
+ * returns a wire-safe commit payload. It does two things:
  *
- *   1. Drop framework internals (`__class`, `__typename`, `clientId`,
+ *   1. Drops framework-internal keys (`__class`, `__typename`, `clientId`,
  *      `syncStatus`) and anything not declared on the model's schema.
- *   2. JSON.stringify values typed as `field.json()` — TEXT columns
- *      storing JSON need explicit stringification; postgres.js won't
- *      auto-serialize for non-JSONB columns.
+ *   2. Passes each declared field's value through unchanged, including
+ *      JSON-typed fields, which are sent as objects rather than pre-serialized
+ *      strings (see the note in the body for why).
  *
- * For updates (`dropUndefined: true`), `undefined` values are also
- * stripped so they don't translate to `SET column = NULL` on the
- * server side.
+ * For updates (`dropUndefined: true`), `undefined` values are also removed so
+ * they are not written as `SET column = NULL` on the server.
  *
- * Fields are read from `ModelRegistry`, populated by
- * `registerModelsFromSchema` at SDK initialization. If the model
- * isn't registered with field metadata (edge case — e.g., tests or
- * manually registered models), projection falls back to identity and
- * the caller gets whatever the Model serialized.
+ * Field metadata comes from the model registry, populated when the schema is
+ * registered at initialization. If a model has no registered field metadata —
+ * for example a manually registered model — projection passes the serialized
+ * data through unchanged apart from dropping the framework keys.
  */
 export function projectCommitPayload(modelName, source, opts) {
     const metadata = getActiveRegistry().getMetadata(modelName);
@@ -53,31 +50,27 @@ export function projectCommitPayload(modelName, source, opts) {
         }
         return out;
     }
-    for (const [key, meta] of Object.entries(fields)) {
+    for (const key of Object.keys(fields)) {
         if (!(key in source))
             continue;
         const value = source[key];
         if (opts.dropUndefined && value === undefined)
             continue;
-        // JSON-typed fields (`jsonb` on the server): ship as OBJECTS over
-        // the wire, not pre-stringified strings. Previously we stringified
-        // here, which round-tripped incorrectly:
+        // JSON-typed fields (stored as jsonb on the server) are sent as objects,
+        // not pre-serialized strings. Pre-stringifying here corrupts a round trip:
         //
-        //   1. Client stringifies `position: {x, y}` → `'{"x":...}'`
-        //   2. Server writes to jsonb column (parses string → jsonb object, fine)
-        //   3. Server's delta echoes `data: JSON.stringify(op.input)` where
-        //      `op.input.position` is still the STRING from step 1
-        //   4. Client merges delta → `model.position = "{...}"` (STRING)
-        //   5. Next drag: `{ ...layer.position, x, y }` spreads the STRING
-        //      char-by-char, producing corrupted char-indexed objects like
-        //      `{"0":"{","1":"\"","2":"x",...,"x":null,"y":null,...}`
-        //   6. That corrupt object lands in the next commit, stored in jsonb.
+        //   1. The client stringifies `position: {x, y}` to `'{"x":...}'`.
+        //   2. The server writes it to the jsonb column, parsing the string, fine.
+        //   3. The server's delta echoes the input, where `position` is still the
+        //      string from step 1.
+        //   4. The client merges the delta and sets `model.position` to that string.
+        //   5. The next edit spreads the string character by character, producing a
+        //      corrupted, index-keyed object.
+        //   6. That corrupt object lands in the next commit and is stored in jsonb.
         //
-        // Sending objects avoids the round-trip mismatch: the wire carries
-        // the object through delta + commit unchanged, and `postgres-js`
-        // serializes JS objects to jsonb correctly via its own
-        // `json.serialize` (triggered by Postgres's ParameterDescription
-        // response identifying the column as type 3802 / jsonb).
+        // Sending objects avoids the mismatch: the value travels through the delta
+        // and the commit unchanged, and the Postgres driver serializes a JS object
+        // to jsonb correctly once the column is identified as jsonb.
         out[key] = value;
     }
     return out;
@@ -85,19 +78,17 @@ export function projectCommitPayload(modelName, source, opts) {
 export const normalizeModelKey = (modelName) => modelName.replace('Model', '').toLowerCase();
 export const stripModelSuffix = (modelName) => modelName.replace('Model', '');
 /**
- * FK-ordered create priority.
+ * Returns the priority score used to order create operations by foreign-key
+ * depth, so a parent row commits before its children.
  *
- * Reads `config.modelCreatePriority` out of the runtime SyncEngineContext —
- * this map is populated once at `createSyncEngine(...)` time by walking the
- * schema's `belongsTo` graph (see `computeFKDepthPriority` in
- * `client/createSyncEngine.ts`). The queue stays schema-agnostic: no model
- * names appear here, and consumer applications can override specific
- * priorities via `configOverrides.modelCreatePriority` without touching the
- * SDK.
+ * The score comes from a priority map on the runtime configuration, built once
+ * at initialization by walking the schema's `belongsTo` graph. No model names
+ * are hard-coded here, and an application can override specific priorities
+ * through `configOverrides.modelCreatePriority`.
  *
- * Non-create ops (update/delete/archive/unarchive) don't need FK ordering
- * because the row already exists, so they all share
- * `config.defaultNonCreatePriority`.
+ * Non-create operations (update, delete, archive, unarchive) need no
+ * foreign-key ordering because the row already exists, so they all share the
+ * configured default non-create priority.
  */
 export const computePriorityScore = (type, modelName) => {
     const { modelCreatePriority, defaultCreatePriority, defaultNonCreatePriority } = getContext().config;
@@ -116,12 +107,18 @@ export function hasStaleWriteOptions(options) {
     return (options?.readAt !== undefined ||
         options?.onStale !== undefined);
 }
+/** Options whose identity/audit semantics forbid merging two caller writes. */
+export function hasCommitCoalescingBarrier(options) {
+    return (hasStaleWriteOptions(options) ||
+        typeof options?.idempotencyKey === 'string' ||
+        typeof options?.label === 'string');
+}
 /**
- * Project a transaction's `writeOptions` onto the wire operation. Stale
- * guards (`readAt`/`onStale`) ride at the op root; `idempotencyKey`/`label`
- * ride in the op's `options` slot (`MutationOperation.options` — the
- * mutation_log cache key + audit tag). This is the single place the
- * caller-supplied write vocabulary crosses onto the wire.
+ * Copies a transaction's `writeOptions` onto the wire operation. The
+ * stale-context guards (`readAt` and `onStale`) sit at the operation's root,
+ * while `idempotencyKey` and `label` go in its `options` slot — the
+ * `mutation_log` cache key and audit tag. This is the one place caller-supplied
+ * write options cross onto the wire.
  */
 export function applyWriteOptions(op, transaction) {
     const operation = op;

package/dist/transactions/deltaConfirmation.d.ts

@@ -1,22 +1,22 @@
 /**
- * Delta-confirmation tracking — the queue's "did my write's echo arrive?"
- * machinery, lifted out of `TransactionQueue.ts` as a stateful leaf.
- *
- * Owns the ack watermark (via the shared `SyncPosition`), the per-transaction
- * confirmation timeout map, and the retry-with-backoff/reconciliation policy
- * for `awaiting_delta` transactions. Talks back to the queue through the
- * minimal `DeltaConfirmationContext` interface (never the host class type),
- * so the leaf stays cycle-free and testable in isolation.
+ * Tracks whether the confirming delta for a write has arrived. It holds the
+ * acknowledgement watermark (through the shared {@link SyncPosition}), the
+ * per-transaction confirmation timeouts, and the retry-with-backoff and
+ * reconciliation policy for transactions in the `awaiting_delta` status. It
+ * reaches back to {@link TransactionQueue} only through the small
+ * {@link DeltaConfirmationContext} interface, not the queue class itself, so it
+ * has no cyclic dependency and can be tested on its own.
  */
 import type { SyncPosition } from '../sync/syncPosition.js';
 import type { Transaction } from './commitPayload.js';
 /**
- * The slice of the queue a confirmation tracker needs: store lookups +
- * status flips, dropping optimistic entries on confirm, the host's event
- * surface (`transaction:completed`, `reconciliation:needed`, …), the
- * connection check (timeouts re-schedule instead of escalating while
- * offline), and the shared client position (`noteAck` advances `acked`;
- * diagnostics read `applied`).
+ * The subset of {@link TransactionQueue} that the confirmation tracker needs:
+ * store lookups and status changes, removing optimistic entries once a write
+ * confirms, the queue's event emitter (`transaction:completed`,
+ * `reconciliation:needed`, and so on), a connection check (so timeouts
+ * re-schedule instead of escalating while offline), and the shared client
+ * position (`noteAck` advances the acknowledgement cursor; diagnostics read the
+ * applied cursor).
  */
 export interface DeltaConfirmationContext {
     store: {
@@ -34,7 +34,6 @@ export interface DeltaConfirmationContext {
 export declare class DeltaConfirmationTracker {
     private readonly ctx;
     private static readonly DELTA_MAX_RETRIES;
-    private static readonly DELTA_INITIAL_TIMEOUT_MS;
     private static readonly DELTA_MAX_TIMEOUT_MS;
     private deltaConfirmationTimeouts;
     private deltaConfirmationRetries;
@@ -43,18 +42,17 @@ export declare class DeltaConfirmationTracker {
     private get lastSeenSyncId();
     noteAck(lastSyncId: number | undefined): void;
     /**
-     * LINEAR PATTERN: Confirm all awaiting transactions when delta with syncId >= threshold arrives.
-     * This replaces clientMutationId echoing - transactions are confirmed by sync ID threshold.
-     * @param syncId - The sync ID of the received delta
+     * Confirms every awaiting transaction whose sync-id threshold this delta
+     * meets or exceeds.
+     * @param syncId - The sync id of the received delta.
      */
     onDeltaReceived(syncId: number): void;
     scheduleDeltaConfirmationTimeout(tx: Transaction, timeoutMs: number): void;
     private cancelDeltaConfirmationTimeout;
     /**
-     * Tear down every armed confirmation timer (30–120s each, one per
-     * in-flight transaction). Called from `TransactionQueue.dispose()` —
-     * without it a disposed queue kept the Node process alive and fired
-     * callbacks against an already-cleared store (T1.19).
+     * Clears every armed confirmation timer, one per in-flight transaction.
+     * {@link TransactionQueue.dispose} calls this; without it a disposed queue
+     * would keep the process alive and fire callbacks against a cleared store.
      */
     dispose(): void;
 }