@abloatai/ablo 0.25.0 → 0.27.0

package/dist/transactions/commitPayload.js

@@ -0,0 +1,143 @@
+/**
+ * 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';
+import { MutationOperationType } from '../types/index.js';
+/**
+ * Framework-internal keys added by `Model.toJSON()` that must never
+ * reach the wire. The server treats each top-level key as a target
+ * column, so shipping these would blow up the INSERT/UPDATE.
+ */
+const FRAMEWORK_KEYS = new Set(['__class', '__typename', 'clientId', 'syncStatus']);
+/**
+ * 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. Drops framework-internal keys (`__class`, `__typename`, `clientId`,
+ *      `syncStatus`) and anything not declared on the model's schema.
+ *   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 removed so
+ * they are not written as `SET column = NULL` on the server.
+ *
+ * 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);
+    const fields = metadata?.fields;
+    const out = {};
+    if (!fields) {
+        // Unknown registration — strip framework keys and ship the rest.
+        for (const [k, v] of Object.entries(source)) {
+            if (FRAMEWORK_KEYS.has(k))
+                continue;
+            if (opts.dropUndefined && v === undefined)
+                continue;
+            out[k] = v;
+        }
+        return out;
+    }
+    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 (stored as jsonb on the server) are sent as objects,
+        // not pre-serialized strings. Pre-stringifying here corrupts a round trip:
+        //
+        //   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 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;
+}
+export const normalizeModelKey = (modelName) => modelName.replace('Model', '').toLowerCase();
+export const stripModelSuffix = (modelName) => modelName.replace('Model', '');
+/**
+ * Returns the priority score used to order create operations by foreign-key
+ * depth, so a parent row commits before its children.
+ *
+ * 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 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;
+    if (type !== 'create')
+        return defaultNonCreatePriority;
+    return modelCreatePriority.get(modelName) ?? defaultCreatePriority;
+};
+export const TX_TYPE_TO_MUTATION_OP = {
+    create: MutationOperationType.CREATE,
+    update: MutationOperationType.UPDATE,
+    delete: MutationOperationType.DELETE,
+    archive: MutationOperationType.ARCHIVE,
+    unarchive: MutationOperationType.UNARCHIVE,
+};
+export function hasStaleWriteOptions(options) {
+    return (options?.readAt !== undefined ||
+        options?.onStale !== undefined);
+}
+/**
+ * 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;
+    const writeOptions = transaction.writeOptions;
+    if (!writeOptions)
+        return operation;
+    if (writeOptions.readAt !== undefined) {
+        operation.readAt = writeOptions.readAt;
+    }
+    if (writeOptions.onStale !== undefined) {
+        operation.onStale = writeOptions.onStale;
+    }
+    if (writeOptions.idempotencyKey != null || writeOptions.label !== undefined) {
+        operation.options = {
+            ...(writeOptions.idempotencyKey != null
+                ? { idempotencyKey: writeOptions.idempotencyKey }
+                : {}),
+            ...(writeOptions.label !== undefined ? { label: writeOptions.label } : {}),
+        };
+    }
+    return operation;
+}
+export function asTransportError(value) {
+    return (value && typeof value === 'object' ? value : {});
+}
+export function extractStatusCode(error) {
+    return asTransportError(error).response?.status;
+}

package/dist/transactions/deltaConfirmation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 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: {
+        get(id: string): Transaction | undefined;
+        getByStatus(status: Transaction['status']): Transaction[];
+        updateStatus(id: string, status: Transaction['status']): void;
+    };
+    optimisticUpdates: {
+        delete(id: string): boolean;
+    };
+    emit(event: string, payload?: unknown): void;
+    isConnected(): boolean;
+    position: SyncPosition;
+}
+export declare class DeltaConfirmationTracker {
+    private readonly ctx;
+    private static readonly DELTA_MAX_RETRIES;
+    private static readonly DELTA_MAX_TIMEOUT_MS;
+    private deltaConfirmationTimeouts;
+    private deltaConfirmationRetries;
+    constructor(ctx: DeltaConfirmationContext);
+    /** Applied-cursor alias, kept so the read sites below stay legible. */
+    private get lastSeenSyncId();
+    noteAck(lastSyncId: number | undefined): void;
+    /**
+     * 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;
+    /**
+     * 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

@@ -0,0 +1,215 @@
+/**
+ * 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;
+    // Retry configuration for delta confirmation, using exponential backoff.
+    // Maximum retries before requesting a full reconciliation.
+    static DELTA_MAX_RETRIES = 5;
+    // Upper bound on the backoff timeout.
+    static DELTA_MAX_TIMEOUT_MS = 120_000;
+    // 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();
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Applied-cursor alias, kept so the read sites below stay legible. */
+    get lastSeenSyncId() {
+        return this.ctx.position.applied;
+    }
+    noteAck(lastSyncId) {
+        this.ctx.position.noteAck(lastSyncId);
+    }
+    /**
+     * Confirms every awaiting transaction whose sync-id threshold this delta
+     * meets or exceeds.
+     * @param syncId - The sync id of the received delta.
+     */
+    onDeltaReceived(syncId) {
+        // 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');
+        const executingTxs = this.ctx.store.getByStatus('executing');
+        // Debug: Show state when delta arrives
+        if (awaitingTxs.length > 0 || executingTxs.length > 0) {
+            getContext().logger.debug('tx:delta_received', {
+                syncId,
+                lastSeenSyncId: this.lastSeenSyncId,
+                awaitingCount: awaitingTxs.length,
+                executingCount: executingTxs.length,
+                awaitingThresholds: awaitingTxs.map((tx) => ({
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    needed: tx.syncIdNeededForCompletion,
+                    willConfirm: tx.syncIdNeededForCompletion !== undefined && syncId >= tx.syncIdNeededForCompletion,
+                })),
+            });
+        }
+        // Fast path: no awaiting transactions
+        if (awaitingTxs.length === 0)
+            return;
+        let confirmedCount = 0;
+        for (const tx of awaitingTxs) {
+            // Confirm if this delta's ID meets or exceeds the threshold
+            if (tx.syncIdNeededForCompletion !== undefined && syncId >= tx.syncIdNeededForCompletion) {
+                this.cancelDeltaConfirmationTimeout(tx.id);
+                this.ctx.store.updateStatus(tx.id, 'completed');
+                this.ctx.emit('transaction:completed', tx);
+                this.ctx.emit(`transaction:completed:${tx.id}`, tx);
+                this.ctx.optimisticUpdates.delete(tx.id);
+                confirmedCount++;
+                getContext().logger.debug('tx:confirm_via_delta', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    neededSyncId: tx.syncIdNeededForCompletion,
+                    receivedSyncId: syncId,
+                });
+            }
+        }
+        // Log batch summary only if we confirmed something
+        if (confirmedCount > 0) {
+            // Leave a breadcrumb when transactions confirm.
+            getContext().observability.breadcrumb('Transactions confirmed via delta', 'sync.transaction', 'info', {
+                count: confirmedCount,
+                syncId,
+                remainingAwaiting: awaitingTxs.length - confirmedCount,
+            });
+        }
+    }
+    // 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);
+        // 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);
+            if (!currentTx || currentTx.status !== 'awaiting_delta') {
+                this.deltaConfirmationRetries.delete(tx.id);
+                return; // Already confirmed or failed
+            }
+            // If disconnected, re-schedule with same timeout (no backoff while offline)
+            if (!this.ctx.isConnected()) {
+                // Self-healing: re-schedule the confirmation wait while offline, no
+                // consumer action needed → debug.
+                getContext().logger.debug('[TransactionQueue] Timeout fired while disconnected - re-scheduling', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                });
+                this.deltaConfirmationTimeouts.delete(tx.id);
+                this.scheduleDeltaConfirmationTimeout(tx, timeoutMs);
+                return;
+            }
+            const retryCount = this.deltaConfirmationRetries.get(tx.id) ?? 0;
+            getContext().observability.captureReconciliation({
+                reason: 'delta_timeout',
+                model: tx.modelName,
+                modelId: tx.modelId,
+                syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                lastSeenSyncId: this.lastSeenSyncId,
+                retryCount,
+                connectionState: this.ctx.isConnected() ? 'connected' : 'disconnected',
+            });
+            if (retryCount < DeltaConfirmationTracker.DELTA_MAX_RETRIES) {
+                // 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);
+                // 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,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                    lastSeenSyncId: this.lastSeenSyncId,
+                    retryCount: retryCount + 1,
+                });
+                // Self-healing retry with backoff — the server already committed; we're
+                // just waiting on the delta. No consumer action → debug.
+                getContext().logger.debug('[TransactionQueue] Re-scheduling with backoff', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    nextTimeoutMs: nextTimeout,
+                    retry: retryCount + 1,
+                });
+                this.scheduleDeltaConfirmationTimeout(tx, nextTimeout);
+            }
+            else {
+                // 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({
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    retryCount: DeltaConfirmationTracker.DELTA_MAX_RETRIES,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                });
+                // Emit the persist event; the client performs the write to local storage.
+                this.ctx.emit('transaction:persist_awaiting', {
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    operationType: tx.type,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                });
+                // Also request one final reconciliation cycle
+                this.ctx.emit('reconciliation:needed', {
+                    reason: 'delta_retries_exhausted',
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                    lastSeenSyncId: this.lastSeenSyncId,
+                    retryCount: DeltaConfirmationTracker.DELTA_MAX_RETRIES,
+                });
+            }
+        }, timeoutMs);
+        this.deltaConfirmationTimeouts.set(tx.id, timeoutHandle);
+    }
+    // Cancel a pending delta confirmation timeout and clean up retry tracking
+    cancelDeltaConfirmationTimeout(id) {
+        const timeoutHandle = this.deltaConfirmationTimeouts.get(id);
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+            this.deltaConfirmationTimeouts.delete(id);
+        }
+        this.deltaConfirmationRetries.delete(id);
+    }
+    /**
+     * 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()) {
+            clearTimeout(timeoutHandle);
+        }
+        this.deltaConfirmationTimeouts.clear();
+        this.deltaConfirmationRetries.clear();
+    }
+}

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/replayValidation.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The validation boundary for replaying persisted transactions after a restart.
+ *
+ * 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 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';
+/**
+ * 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;
+    type: z.ZodEnum<{
+        update: "update";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+        unarchive: "unarchive";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    modelKey: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    context: z.ZodObject<{
+        userId: z.ZodString;
+        organizationId: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        teamIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    createdAt: z.ZodOptional<z.ZodNumber>;
+    batchId: z.ZodOptional<z.ZodString>;
+    writeOptions: z.ZodOptional<z.ZodObject<{
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    localOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type PersistedReplayableTransaction = z.infer<typeof persistedTransactionSchema>;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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<{
+        update: "update";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+    }>;
+    modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    modelName: z.ZodString;
+    timestamp: z.ZodString;
+    writeOptions: z.ZodOptional<z.ZodObject<{
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type PersistedQueuedMutation = z.infer<typeof persistedMutationSchema>;