@abloatai/ablo 0.26.0 → 0.27.0

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;
@@ -117,11 +108,11 @@ export function hasStaleWriteOptions(options) {
         options?.onStale !== undefined);
 }
 /**
- * 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;
 }

package/dist/transactions/deltaConfirmation.js

@@ -1,25 +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 { getContext } from '../context.js';
 export class DeltaConfirmationTracker {
     ctx;
-    // Delta confirmation retry config (Replicache-style exponential backoff)
-    // Max retries before requesting full reconciliation
+    // Retry configuration for delta confirmation, using exponential backoff.
+    // Maximum retries before requesting a full reconciliation.
     static DELTA_MAX_RETRIES = 5;
-    // Initial timeout (first attempt)
-    static DELTA_INITIAL_TIMEOUT_MS = 30_000;
-    // Max timeout cap (like Replicache's maxDelayMs of 60s)
+    // Upper bound on the backoff timeout.
     static DELTA_MAX_TIMEOUT_MS = 120_000;
-    // LINEAR PATTERN: Track delta confirmation timeouts for awaiting_delta transactions
-    // Following Replicache/PowerSync pattern: retry with backoff instead of rolling back
+    // Pending confirmation timeouts for transactions awaiting their delta. On
+    // timeout the tracker retries with backoff rather than rolling back.
     deltaConfirmationTimeouts = new Map();
     // Track retry attempts per transaction for exponential backoff
     deltaConfirmationRetries = new Map();
@@ -34,12 +31,12 @@ export class DeltaConfirmationTracker {
         this.ctx.position.noteAck(lastSyncId);
     }
     /**
-     * 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) {
-        // Cursor advancing happens where the delta is APPLIED (the store calls
+        // The cursor advances where the delta is applied (the store calls
         // position.advanceApplied / advancePersisted); this hook only resolves
         // confirmation thresholds against the incoming id.
         const awaitingTxs = this.ctx.store.getByStatus('awaiting_delta');
@@ -82,7 +79,7 @@ export class DeltaConfirmationTracker {
         }
         // Log batch summary only if we confirmed something
         if (confirmedCount > 0) {
-            // Use warn for staging visibility when transactions confirm
+            // Leave a breadcrumb when transactions confirm.
             getContext().observability.breadcrumb('Transactions confirmed via delta', 'sync.transaction', 'info', {
                 count: confirmedCount,
                 syncId,
@@ -90,15 +87,16 @@ export class DeltaConfirmationTracker {
             });
         }
     }
-    // REPLICACHE/POWERSYNC PATTERN: Schedule delta confirmation with retry + reconciliation
-    // Instead of rolling back on timeout (which destroys confirmed server state),
-    // retry with exponential backoff and request reconciliation to catch up on missed deltas.
-    // Only rollback on explicit server rejection, never on timeout.
+    // Schedule the confirmation wait for a transaction. On timeout the tracker
+    // retries with exponential backoff and requests reconciliation to catch up on
+    // missed deltas, rather than rolling back, which would discard state the
+    // server has already confirmed. A rollback happens only on an explicit server
+    // rejection, never on a timeout.
     scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
         // Cancel any existing timeout for this transaction
         this.cancelDeltaConfirmationTimeout(tx.id);
-        // NB: deliberately NOT an async callback — the body is fully synchronous,
-        // and `setTimeout(async …)` turns any throw into an unhandled promise
+        // Deliberately not an async callback: the body is fully synchronous, and
+        // `setTimeout(async …)` would turn any throw into an unhandled promise
         // rejection instead of a catchable synchronous error.
         const timeoutHandle = setTimeout(() => {
             const currentTx = this.ctx.store.get(tx.id);
@@ -119,12 +117,6 @@ export class DeltaConfirmationTracker {
                 return;
             }
             const retryCount = this.deltaConfirmationRetries.get(tx.id) ?? 0;
-            const diagnosis = this.lastSeenSyncId === 0
-                ? 'No deltas received - delta pipeline may be broken'
-                : currentTx.syncIdNeededForCompletion &&
-                    this.lastSeenSyncId < currentTx.syncIdNeededForCompletion
-                    ? 'Delta not yet received - may be lost or delayed'
-                    : 'Delta should have confirmed - possible race condition';
             getContext().observability.captureReconciliation({
                 reason: 'delta_timeout',
                 model: tx.modelName,
@@ -135,14 +127,15 @@ export class DeltaConfirmationTracker {
                 connectionState: this.ctx.isConnected() ? 'connected' : 'disconnected',
             });
             if (retryCount < DeltaConfirmationTracker.DELTA_MAX_RETRIES) {
-                // RETRY: Request reconciliation and re-schedule with exponential backoff
-                // The server already committed this mutation — we just need the delta to arrive
+                // Retry: request reconciliation and re-schedule with exponential
+                // backoff. The server has already committed the mutation; only the
+                // delta is outstanding.
                 this.deltaConfirmationRetries.set(tx.id, retryCount + 1);
                 this.deltaConfirmationTimeouts.delete(tx.id);
                 // Exponential backoff: 30s → 60s → 120s → 120s → 120s (capped)
                 const nextTimeout = Math.min(timeoutMs * 2, DeltaConfirmationTracker.DELTA_MAX_TIMEOUT_MS);
-                // Emit reconciliation request so SyncedStore can cycle the WebSocket
-                // to trigger delta catch-up from the server
+                // Request reconciliation so the client can cycle the connection and
+                // catch up on missed deltas from the server.
                 this.ctx.emit('reconciliation:needed', {
                     reason: 'delta_confirmation_timeout',
                     txId: tx.id,
@@ -163,10 +156,10 @@ export class DeltaConfirmationTracker {
                 this.scheduleDeltaConfirmationTimeout(tx, nextTimeout);
             }
             else {
-                // LINEAR PATTERN: Retries exhausted — persist to IndexedDB instead of rolling back.
-                // The transaction succeeded on the server (HTTP 200), so the data exists server-side.
-                // Persist the awaiting state so it survives tab close. On next session, the WebSocket
-                // reconnect + delta catch-up will naturally confirm it (like Linear's IndexedDB caching).
+                // Retries exhausted: persist the awaiting state instead of rolling back.
+                // The commit succeeded on the server, so the data exists there. Saving
+                // the awaiting state lets it survive the page closing; on the next
+                // session, reconnecting and catching up on deltas will confirm it.
                 this.deltaConfirmationRetries.delete(tx.id);
                 this.deltaConfirmationTimeouts.delete(tx.id);
                 getContext().observability.captureDeltaRetryExhausted({
@@ -176,7 +169,7 @@ export class DeltaConfirmationTracker {
                     retryCount: DeltaConfirmationTracker.DELTA_MAX_RETRIES,
                     syncIdNeeded: currentTx.syncIdNeededForCompletion,
                 });
-                // Emit persist event — SyncClient handles the IDB write
+                // Emit the persist event; the client performs the write to local storage.
                 this.ctx.emit('transaction:persist_awaiting', {
                     txId: tx.id,
                     model: tx.modelName,
@@ -208,10 +201,9 @@ export class DeltaConfirmationTracker {
         this.deltaConfirmationRetries.delete(id);
     }
     /**
-     * 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() {
         for (const timeoutHandle of this.deltaConfirmationTimeouts.values()) {

package/dist/transactions/optimisticApply.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Local-first apply and rollback bookkeeping for pending mutations.
+ *
+ * When a change is written before the server confirms it, these functions
+ * record it in a ledger and emit an `optimistic:*` event; separate listeners
+ * apply the change to the in-memory data and, on rollback, restore the value
+ * it replaced. Each function takes the ledger and a small event emitter rather
+ * than any larger object, so the rules have no dependencies of their own and
+ * can be tested in isolation.
+ */
+import type { Model } from '../Model.js';
+import type { MutationInput, Transaction } from './commitPayload.js';
+/**
+ * One tracked optimistic mutation: the live model plus the value it held
+ * before the change, kept so a rollback can restore it.
+ */
+export interface OptimisticUpdateEntry {
+    model: Model;
+    previousState: MutationInput | null | undefined;
+    transaction: Transaction;
+}
+/**
+ * The event emitter these functions use to announce each optimistic change and
+ * its rollback. You supply the implementation.
+ */
+export interface OptimisticEmitter {
+    emit(event: string, payload: unknown): void;
+}
+/**
+ * Record an optimistic create and announce it. There is no prior value to
+ * restore, so the rollback pre-image is `null`.
+ */
+export declare function applyOptimisticCreate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+/**
+ * Record an optimistic update and announce it, keeping the row's prior value so
+ * a rollback can put it back.
+ */
+export declare function applyOptimisticUpdate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+/**
+ * Record an optimistic delete and announce it, keeping the deleted row so a
+ * rollback can restore it.
+ */
+export declare function applyOptimisticDelete(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+/**
+ * Undo an optimistic mutation by its transaction id: emit `optimistic:rollback`
+ * with the saved pre-image so listeners can restore the prior value, then drop
+ * the ledger entry. Does nothing if the transaction was never tracked.
+ */
+export declare function rollbackOptimistic(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, transaction: Transaction, reason?: string, error?: Error): Promise<void>;

package/dist/transactions/optimisticApply.js

@@ -0,0 +1,65 @@
+/**
+ * Local-first apply and rollback bookkeeping for pending mutations.
+ *
+ * When a change is written before the server confirms it, these functions
+ * record it in a ledger and emit an `optimistic:*` event; separate listeners
+ * apply the change to the in-memory data and, on rollback, restore the value
+ * it replaced. Each function takes the ledger and a small event emitter rather
+ * than any larger object, so the rules have no dependencies of their own and
+ * can be tested in isolation.
+ */
+/**
+ * Record an optimistic create and announce it. There is no prior value to
+ * restore, so the rollback pre-image is `null`.
+ */
+export function applyOptimisticCreate(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: null,
+        transaction,
+    });
+    emitter.emit('optimistic:create', { model, transaction });
+}
+/**
+ * Record an optimistic update and announce it, keeping the row's prior value so
+ * a rollback can put it back.
+ */
+export function applyOptimisticUpdate(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: transaction.previousData,
+        transaction,
+    });
+    emitter.emit('optimistic:update', { model, transaction });
+}
+/**
+ * Record an optimistic delete and announce it, keeping the deleted row so a
+ * rollback can restore it.
+ */
+export function applyOptimisticDelete(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: transaction.previousData,
+        transaction,
+    });
+    emitter.emit('optimistic:delete', { model, transaction });
+}
+/**
+ * Undo an optimistic mutation by its transaction id: emit `optimistic:rollback`
+ * with the saved pre-image so listeners can restore the prior value, then drop
+ * the ledger entry. Does nothing if the transaction was never tracked.
+ */
+export function rollbackOptimistic(optimisticUpdates, emitter, transaction, reason, error) {
+    const optimistic = optimisticUpdates.get(transaction.id);
+    if (!optimistic)
+        return Promise.resolve();
+    emitter.emit('optimistic:rollback', {
+        model: optimistic.model,
+        previousState: optimistic.previousState,
+        transaction,
+        reason: reason ?? 'unknown',
+        error,
+    });
+    optimisticUpdates.delete(transaction.id);
+    return Promise.resolve();
+}

package/dist/transactions/{persistedReplay.d.ts → replayValidation.d.ts}

@@ -1,26 +1,27 @@
 /**
- * persistedReplay — the Zod boundary for IDB → commit replay (T1.8).
+ * The validation boundary for replaying persisted transactions after a restart.
  *
- * Rows read back from the persisted-transaction store were written by a
- * PREVIOUS session — possibly by an older SDK version, possibly corrupted.
- * Spreading them straight into a `Transaction` re-entered the commit path
- * with zero validation. These schemas validate exactly the fields the queue
- * (and the offline mutation-queue restore) actually read on replay; rows
- * that don't parse are DROPPED (and surfaced through observability), never
- * replayed as garbage commits.
+ * Rows read back from the on-disk transaction store may have been written by an
+ * earlier run — possibly by an older version of this package, possibly
+ * corrupted. Rather than trust them, the schemas here validate exactly the
+ * fields the transaction queue and the offline-mutation restore read during
+ * replay. A row that fails to parse is dropped and reported, never replayed as
+ * a malformed commit.
  *
- * The same IDB store also holds two NON-replayable row kinds written by
- * other subsystems — the `'queue'` record (`SyncClient.persistMutationQueue`)
- * and `'awaiting_delta'` markers (`setupAwaitingTransactionPersistence`).
- * Those are recognized and skipped silently: they are expected neighbors,
- * not corruption.
+ * The same store also holds two kinds of rows that are not replayable
+ * transactions — the offline mutation queue (`type: 'queue'`) and delta-await
+ * markers (`type: 'awaiting_delta'`), each owned by another part of the client.
+ * {@link isNonReplayablePersistedRow} recognizes them so they are skipped
+ * quietly rather than flagged as corruption.
  */
 import { z } from 'zod';
 import type { Transaction } from './commitPayload.js';
 /**
- * A replayable persisted transaction — the fields `TransactionQueue`
- * actually reads when re-enqueueing (id/type/model addressing + payload +
- * identity context). Everything else is defaulted at rehydration time.
+ * The shape of a persisted transaction that can be replayed: the fields the
+ * transaction queue reads when it re-enqueues the row — its id, operation type,
+ * model addressing, payload, and identity context. Any remaining bookkeeping is
+ * filled in with defaults when the row is rehydrated by
+ * {@link deserializePersistedTransaction}.
  */
 export declare const persistedTransactionSchema: z.ZodObject<{
     id: z.ZodString;
@@ -57,17 +58,22 @@ export declare const persistedTransactionSchema: z.ZodObject<{
     localOnly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>;
 export type PersistedReplayableTransaction = z.infer<typeof persistedTransactionSchema>;
-/** Whether a persisted row belongs to another subsystem (skip, don't flag). */
+/**
+ * Reports whether a stored row is one of the non-transaction kinds, so callers
+ * skip it instead of treating it as a corrupt transaction.
+ */
 export declare function isNonReplayablePersistedRow(row: unknown): boolean;
 /**
- * Validate + rehydrate one persisted row into a replayable `Transaction`,
- * or `null` when the row doesn't parse. Missing bookkeeping fields are
- * re-derived exactly like a fresh staging would derive them.
+ * Validates one stored row and rehydrates it into a {@link Transaction} ready
+ * to replay, or returns `null` when the row fails validation. Bookkeeping
+ * fields the stored row lacks — status, attempts, priority, timestamp — are
+ * re-derived the same way a freshly staged transaction derives them.
  */
 export declare function deserializePersistedTransaction(row: unknown): Transaction | null;
 /**
- * One entry of the persisted offline mutation queue (the `'queue'` row's
- * `mutations` array) — the fields `SyncClient.restoreMutationQueue` reads.
+ * The shape of one entry in the persisted offline mutation queue — an item of
+ * the `'queue'` row's `mutations` array, carrying the fields read when the
+ * queue is restored on reconnect.
  */
 export declare const persistedMutationSchema: z.ZodObject<{
     type: z.ZodEnum<{