@abloatai/ablo 0.27.0 → 0.29.0

package/dist/stores/ObjectStore.d.ts

@@ -4,6 +4,15 @@
  */
 import type { ModelMetadata } from '../types/index.js';
 import type { ObjectStoreContract } from './ObjectStoreContract.js';
+/**
+ * IDB transaction options type (TypeScript's lib.dom.d.ts may be outdated)
+ * durability: 'relaxed' provides ~16x write performance improvement
+ * by not requiring fsync on each transaction commit.
+ * Safe for optimistic sync engines that can recover from server state.
+ */
+interface IDBTransactionOptionsWithDurability {
+    durability?: 'default' | 'relaxed' | 'strict';
+}
 /**
  * An IndexedDB-backed store holding the records of a single model.
  *
@@ -21,8 +30,11 @@ export declare class ObjectStore implements ObjectStoreContract {
     protected modelName: string;
     protected storeName: string;
     protected metadata: ModelMetadata;
+    private readonly writeDurability;
     private isClosing;
-    constructor(db: IDBDatabase, modelName: string, storeName: string, metadata: ModelMetadata);
+    constructor(db: IDBDatabase, modelName: string, storeName: string, metadata: ModelMetadata, writeDurability?: NonNullable<IDBTransactionOptionsWithDurability['durability']>);
+    /** Insert without replacing an existing key (used by the commit outbox). */
+    add(data: Record<string, unknown>): Promise<void>;
     /**
      * Mark this store as closing to prevent new operations
      */
@@ -100,3 +112,4 @@ export declare class ObjectStore implements ObjectStoreContract {
      */
     performMaintenance(): Promise<void>;
 }
+export {};

package/dist/stores/ObjectStore.js

@@ -19,12 +19,35 @@ export class ObjectStore {
     modelName;
     storeName;
     metadata;
+    writeDurability;
     isClosing = false;
-    constructor(db, modelName, storeName, metadata) {
+    constructor(db, modelName, storeName, metadata, writeDurability = 'relaxed') {
         this.db = db;
         this.modelName = modelName;
         this.storeName = storeName;
         this.metadata = metadata;
+        this.writeDurability = writeDurability;
+    }
+    /** Insert without replacing an existing key (used by the commit outbox). */
+    async add(data) {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.reject(new Error('IndexedDB not available (closing or invalid)'));
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readwrite', {
+                    durability: this.writeDurability,
+                });
+                const store = tx.objectStore(this.storeName);
+                const request = store.add(data);
+                tx.oncomplete = () => { resolve(); };
+                tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
+                request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
     }
     /**
      * Mark this store as closing to prevent new operations
@@ -65,13 +88,13 @@ export class ObjectStore {
             try {
                 // Use relaxed durability for ~16x write performance (safe with optimistic sync)
                 const tx = this.db.transaction([this.storeName], 'readwrite', {
-                    durability: 'relaxed',
+                    durability: this.writeDurability,
                 });
                 const store = tx.objectStore(this.storeName);
                 const request = store.put(data);
                 tx.oncomplete = () => { resolve(); };
-                tx.onerror = () => { reject(tx.error || new Error('IndexedDB transaction error')); };
-                request.onerror = () => { reject(request.error || new Error('IndexedDB request error')); };
+                tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
+                request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
             }
             catch (error) {
                 // Propagate failure so callers do not continue with inconsistent state
@@ -169,13 +192,13 @@ export class ObjectStore {
             try {
                 // Use relaxed durability for ~16x write performance (safe with optimistic sync)
                 const tx = this.db.transaction([this.storeName], 'readwrite', {
-                    durability: 'relaxed',
+                    durability: this.writeDurability,
                 });
                 const store = tx.objectStore(this.storeName);
                 const request = store.delete(id);
                 tx.oncomplete = () => { resolve(); };
-                tx.onerror = () => { reject(tx.error || new Error('IndexedDB transaction error')); };
-                request.onerror = () => { reject(request.error || new Error('IndexedDB request error')); };
+                tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
+                request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
             }
             catch (error) {
                 reject(error instanceof Error ? error : new Error(String(error)));
@@ -205,13 +228,13 @@ export class ObjectStore {
             try {
                 // Use relaxed durability for ~16x write performance (safe with optimistic sync)
                 const tx = this.db.transaction([this.storeName], 'readwrite', {
-                    durability: 'relaxed',
+                    durability: this.writeDurability,
                 });
                 const store = tx.objectStore(this.storeName);
                 const request = store.clear();
                 tx.oncomplete = () => { resolve(); };
-                tx.onerror = () => { reject(tx.error || new Error('IndexedDB transaction error')); };
-                request.onerror = () => { reject(request.error || new Error('IndexedDB request error')); };
+                tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
+                request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
             }
             catch (error) {
                 reject(error instanceof Error ? error : new Error(String(error)));

package/dist/stores/ObjectStoreContract.d.ts

@@ -15,6 +15,8 @@
  * a silent failure in a caller.
  */
 export interface ObjectStoreContract {
+    /** Insert a record only when its key is absent. */
+    add(data: Record<string, unknown>): Promise<void>;
     /** Insert or update a record. The record must carry an `id` field. */
     put(data: Record<string, unknown>): Promise<void>;
     /** Look up a record by id. */

package/dist/surface.d.ts

@@ -30,7 +30,7 @@ export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orde
  * The keys of the client constructor options, {@link AbloOptions}. Only
  * `schema` is required; every other key is optional.
  */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "databaseUrl", "persistence", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "databaseUrl", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -58,6 +58,9 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
     'authEndpoint',
     'databaseUrl',
     'persistence',
+    'durableWrites',
+    'commitOutbox',
+    'commitOutboxScope',
     'transport',
     'debug',
     'logLevel',

package/dist/sync/BootstrapFetcher.d.ts

@@ -88,6 +88,16 @@ export declare class BootstrapFetcher {
      * means the app's schema and the deployed schema have diverged — reads/writes
      * relying on undeployed changes will later fail with an opaque DB constraint
      * error. Warn once, actionably; never throws or blocks the bootstrap.
+     *
+     * The message names the SERVER it connected to, and spans all three real
+     * causes rather than assuming "you forgot to push". Drift most often means the
+     * schema was pushed to a different server, project, or environment than this
+     * client points at (a bare `ablo push` targets the hosted default; a local app
+     * usually reads a local server) — so the first, load-bearing pointer is `ablo
+     * status`, which names the exact org/project/environment the key resolves to
+     * and the deployed hash, turning "which of these is it?" into one glance. The
+     * older "Run `ablo push`" copy sent everyone down one path and confused the
+     * common wrong-target and version-skew cases.
      */
     private warnOnSchemaDrift;
     constructor(options: BootstrapOptions);

package/dist/sync/BootstrapFetcher.js

@@ -25,6 +25,16 @@ export class BootstrapFetcher {
      * means the app's schema and the deployed schema have diverged — reads/writes
      * relying on undeployed changes will later fail with an opaque DB constraint
      * error. Warn once, actionably; never throws or blocks the bootstrap.
+     *
+     * The message names the SERVER it connected to, and spans all three real
+     * causes rather than assuming "you forgot to push". Drift most often means the
+     * schema was pushed to a different server, project, or environment than this
+     * client points at (a bare `ablo push` targets the hosted default; a local app
+     * usually reads a local server) — so the first, load-bearing pointer is `ablo
+     * status`, which names the exact org/project/environment the key resolves to
+     * and the deployed hash, turning "which of these is it?" into one glance. The
+     * older "Run `ablo push`" copy sent everyone down one path and confused the
+     * common wrong-target and version-skew cases.
      */
     warnOnSchemaDrift(serverHash) {
         if (this.schemaDriftWarned || !serverHash)
@@ -33,14 +43,27 @@ export class BootstrapFetcher {
         if (!clientHash || clientHash === serverHash)
             return;
         this.schemaDriftWarned = true;
+        const org = this.options.organizationId;
+        const where = org ? `${this.baseUrl} (org ${org})` : this.baseUrl;
         // Self-brand the message ("Ablo:") rather than rely on the default logger's
         // `[Ablo]` namespace — consumers wiring their own logger (pino, etc.) lose
         // that prefix, and a drift warning that reads like the app's own log is
         // worse than none. The brand tells them at a glance who is talking.
-        getContext().logger.warn(`Ablo: Schema drift detected — this app was built against schema ${clientHash}, ` +
-            `but the deployed schema is ${serverHash}. Operations that depend on schema ` +
-            `changes not yet deployed will fail later with an opaque database error. Run ` +
-            `\`ablo push\` to deploy your schema (or update this app to match the deployed one).`, { clientSchemaHash: clientHash, serverSchemaHash: serverHash });
+        getContext().logger.warn(`Ablo: Schema drift — the schema this client was built with (${clientHash}) is not the ` +
+            `one active on the server it connected to (${serverHash} at ${where}). Until they match, ` +
+            `operations that depend on the difference will fail later with an opaque database error. ` +
+            `This is usually one of three things. The schema may have been pushed to a different ` +
+            `server, project, or environment than this client points at — run \`ablo status\` to see ` +
+            `the exact org, project, and environment your key resolves to, alongside the deployed ` +
+            `hash, and confirm they match here. Your local schema may simply not be pushed to this ` +
+            `server yet — run \`ablo push\` against it. Or this client and the server may have been ` +
+            `built with different Ablo versions, which can hash an identical schema differently — ` +
+            `align the versions. This check is advisory and never blocks the connection.`, {
+            clientSchemaHash: clientHash,
+            serverSchemaHash: serverHash,
+            serverUrl: this.baseUrl,
+            ...(org ? { organizationId: org } : {}),
+        });
     }
     constructor(options) {
         // Defaults are spread first; the explicit `baseUrl` then takes precedence,

package/dist/sync/SyncWebSocket.d.ts

@@ -9,6 +9,7 @@
 import { EventEmitter } from 'events';
 import type { MutationOperation } from '../interfaces/index.js';
 import { type ClientSyncDelta } from '../wire/delta.js';
+import type { BootstrapReason } from '../wire/bootstrapReason.js';
 import type { ClaimError, ClaimRejection, StaleNotification, ReadDependency } from '../coordination/schema.js';
 import { type CommitAck } from './commitFrames.js';
 export type { CommitAck } from './commitFrames.js';
@@ -100,7 +101,7 @@ export interface SyncWebSocketOptions {
  */
 export interface BootstrapHint {
     tables?: string[];
-    reason?: 'too_far_behind' | 'too_many_deltas' | 'missing_entities';
+    reason?: BootstrapReason;
     staleTables?: string[];
     totalDeltaCount?: number;
 }

package/dist/sync/createClaimStream.d.ts

@@ -23,6 +23,15 @@
  */
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
+/**
+ * The wire capability the claim stream actually uses: subscribe to typed
+ * inbound frames, check liveness, and send outbound frames. `SyncWebSocket`
+ * satisfies it, so production wiring is unchanged — but depending on the port
+ * rather than the whole socket class lets a test drive it with a plain object,
+ * no cast. `Pick` carries the exact (generic, typed-payload) `subscribe`
+ * signature, so every handler stays fully typed.
+ */
+export type ClaimTransport = Pick<SyncWebSocket, 'subscribe' | 'isConnected' | 'send'>;
 export interface ClaimStreamConfig {
     /** Identity used to filter our own active claims out of `others`. */
     participantId: string;
@@ -36,7 +45,7 @@ export interface AttachableClaimStream extends ClaimStream {
      * `ablo.<model>.claim({ id })`, which is built on this.
      */
     claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
-    attach(transport: SyncWebSocket): void;
+    attach(transport: ClaimTransport): void;
     dispose(): void;
 }
-export declare function createClaimStream(config: ClaimStreamConfig, transport?: SyncWebSocket | null): AttachableClaimStream;
+export declare function createClaimStream(config: ClaimStreamConfig, transport?: ClaimTransport | null): AttachableClaimStream;

package/dist/sync/createClaimStream.js

@@ -23,7 +23,7 @@
  */
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { toMs } from '../utils/duration.js';
-import { claimHeartbeatAckPayloadSchema, descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+import { claimHeartbeatAckPayloadSchema, claimLostSchema, descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
 import { AbloClaimedError, AbloConnectionError } from '../errors.js';
 import { resolveHeartbeatOptions } from '../client/claimHeartbeatLoop.js';
 import { getContext } from '../context.js';
@@ -173,9 +173,10 @@ export function createClaimStream(config, transport = null) {
         //      (preempted or expired). Distinct from a rejection, which is a claim
         //      the server refused.
         unsubs.push(t.subscribe('claim_lost', (payload) => {
-            const lost = payload;
-            if (!lost.claimId)
+            const parsed = claimLostSchema.safeParse(payload);
+            if (!parsed.success)
                 return;
+            const lost = parsed.data;
             if (ownClaims.has(lost.claimId)) {
                 const c = ownClaims.get(lost.claimId);
                 getContext().logger.info(`claim: lost ${c ? claimLabel(c.entityType, c.entityId, c.field) : lost.claimId} (preempted or expired)`, { claimId: lost.claimId });

package/dist/sync/persistedPrefix.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns the highest sync id in the durable prefix of an ordered delta frame.
+ *
+ * A frame may span several IndexedDB stores, each committed in its own
+ * transaction. Those transactions can succeed and fail independently. The
+ * resume cursor may advance only through the first failed input: taking the
+ * maximum id from any successful store would skip an earlier failed delta on
+ * every later catch-up.
+ */
+export declare function highestPersistedPrefixSyncId(deltas: readonly {
+    readonly syncId?: number | string;
+}[], persistedIndexes: ReadonlySet<number>): number;

package/dist/sync/persistedPrefix.js

@@ -0,0 +1,22 @@
+/**
+ * Returns the highest sync id in the durable prefix of an ordered delta frame.
+ *
+ * A frame may span several IndexedDB stores, each committed in its own
+ * transaction. Those transactions can succeed and fail independently. The
+ * resume cursor may advance only through the first failed input: taking the
+ * maximum id from any successful store would skip an earlier failed delta on
+ * every later catch-up.
+ */
+export function highestPersistedPrefixSyncId(deltas, persistedIndexes) {
+    let through = 0;
+    for (let index = 0; index < deltas.length; index += 1) {
+        if (!persistedIndexes.has(index))
+            break;
+        const raw = deltas[index]?.syncId;
+        const syncId = typeof raw === 'string' ? Number(raw) : raw;
+        if (typeof syncId === 'number' && Number.isFinite(syncId) && syncId > through) {
+            through = syncId;
+        }
+    }
+    return through;
+}

package/dist/testing/index.d.ts

@@ -9,6 +9,8 @@ export type { CapturedMutation, MockMutationExecutorOptions } from './mocks/Mock
 export { MockNetworkMonitor } from './mocks/MockNetworkMonitor.js';
 export { MockWebSocket } from './mocks/MockWebSocket.js';
 export type { MockDelta, MockBootstrapHint } from './mocks/MockWebSocket.js';
+export { fakeDatabase } from './mocks/FakeDatabase.js';
+export type { FakeDatabaseOverrides } from './mocks/FakeDatabase.js';
 export { createTestContext, } from './mocks/MockSyncContext.js';
 export type { TestContextOptions, TestContextResult } from './mocks/MockSyncContext.js';
 export { TestProject, TestTask, TestComment, TestSlideDeck, TestSlide, TestSlideLayer, TEST_MODEL_PRIORITIES, registerTestModels, createTestConfig, resetFixtureCounter, createProjectFixture, createTaskFixture, createCommentFixture, createSlideDeckFixture, createSlideFixture, createSlideLayerFixture, } from './fixtures/models.js';

package/dist/testing/index.js

@@ -10,6 +10,7 @@
 export { MockMutationExecutor } from './mocks/MockMutationExecutor.js';
 export { MockNetworkMonitor } from './mocks/MockNetworkMonitor.js';
 export { MockWebSocket } from './mocks/MockWebSocket.js';
+export { fakeDatabase } from './mocks/FakeDatabase.js';
 export { createTestContext, } from './mocks/MockSyncContext.js';
 // ─────────────────────────────────────────────
 // Fixtures: Models

package/dist/testing/mocks/FakeDatabase.d.ts

@@ -0,0 +1,18 @@
+import type { Database } from '../../Database.js';
+/**
+ * Overrides for {@link fakeDatabase}. Everything is typechecked against
+ * Database's public surface except `getPersistedTransactions`, which widens to
+ * `unknown[]`: persisted rows are untrusted input (the DurableWriteStore port
+ * documents this), and restore-path tests feed deliberately corrupt rows.
+ */
+export type FakeDatabaseOverrides = Omit<Partial<Database>, 'getPersistedTransactions'> & {
+    getPersistedTransactions?: () => Promise<unknown[]>;
+};
+/**
+ * A Database double that implements ONLY the given members — no real
+ * prototype behind it, so a code path reaching for anything else fails
+ * loudly instead of silently running real IndexedDB logic. The bare `as`
+ * is a single narrowing assert (Database is assignable to the overrides
+ * type), so every override stays typechecked against the real surface.
+ */
+export declare function fakeDatabase(overrides: FakeDatabaseOverrides): Database;

package/dist/testing/mocks/FakeDatabase.js

@@ -0,0 +1,10 @@
+/**
+ * A Database double that implements ONLY the given members — no real
+ * prototype behind it, so a code path reaching for anything else fails
+ * loudly instead of silently running real IndexedDB logic. The bare `as`
+ * is a single narrowing assert (Database is assignable to the overrides
+ * type), so every override stays typechecked against the real surface.
+ */
+export function fakeDatabase(overrides) {
+    return overrides;
+}

package/dist/testing/mocks/MockWebSocket.d.ts

@@ -4,6 +4,7 @@
  * can drive connection changes, deltas, and bootstrap hints by hand.
  */
 import type { SyncActionType } from '../../types/index.js';
+import type { BootstrapReason } from '../../wire/bootstrapReason.js';
 /** The shape of a single delta — one change the server pushes to the client. */
 export interface MockDelta {
     id: number;
@@ -17,7 +18,7 @@ export interface MockDelta {
  * rebuild its data from scratch rather than catch up one delta at a time.
  */
 export interface MockBootstrapHint {
-    reason: 'too_far_behind' | 'too_many_deltas' | 'missing_entities';
+    reason: BootstrapReason;
     tables?: string[];
     staleTables?: string[];
 }

package/dist/transactions/TransactionQueue.d.ts

@@ -18,6 +18,8 @@ import { SyncPosition } from '../sync/syncPosition.js';
 import type { WriteOptions } from '../interfaces/index.js';
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 import { type MutationInput, type Transaction, type UserContext } from './commitPayload.js';
+import { type DurableCommitEnvelope, type DurableCommitOperation, type CommitOutboxScope } from './commitEnvelope.js';
+import type { DurableWriteStore } from './durableWriteStore.js';
 export type { Transaction, UserContext } from './commitPayload.js';
 /**
  * A pre-built, multi-operation commit submitted through
@@ -32,7 +34,7 @@ interface CommitTransaction {
     id: string;
     kind: 'commit';
     operations: {
-        type: string;
+        type: DurableCommitOperation['type'];
         model: string;
         id: string;
         input?: Record<string, unknown>;
@@ -48,6 +50,12 @@ interface CommitTransaction {
     attempts: number;
     lastSyncId?: number;
     error?: Error;
+    sealedAt: number;
+    sequence: number;
+    sealPromise?: Promise<void>;
+    durableEnvelope?: DurableCommitEnvelope;
+    /** Journal entries atomically consumed when this request was sealed. */
+    sourceMutationIds?: string[];
 }
 interface ConflictResolution {
     strategy: 'last-write-wins' | 'merge' | 'reject' | 'custom';
@@ -89,6 +97,7 @@ interface TransactionQueueConfig {
     commitOfflineGraceMs: number;
 }
 export declare class TransactionQueue extends EventEmitter {
+    private static readonly DURABLE_REPLAY_WINDOW_MS;
     private store;
     private lastPermanentErrorSig?;
     private _mutationExecutor;
@@ -105,6 +114,15 @@ export declare class TransactionQueue extends EventEmitter {
     private commitLane;
     private commitStore;
     private commitProcessing;
+    private lastCommitSequence;
+    private durableReplayBlock;
+    /** Browser-backed strict outbox; absent for standalone/in-memory consumers. */
+    private commitOutbox;
+    private commitOutboxScope;
+    private nextCommitSequence;
+    private emitCommitLifecycle;
+    private assertDurableReplayOpen;
+    private assertEnvelopeInsideReplayWindow;
     private computePriorityScore;
     private ensureDerivedFields;
     private entityKey;
@@ -134,6 +152,38 @@ export declare class TransactionQueue extends EventEmitter {
     private get lastSeenSyncId();
     private noteAck;
     private batchIndex;
+    /** Mints the request identity once; retry paths only read the stored value. */
+    private generateCommitIdempotencyKey;
+    /**
+     * Binds an ordered transaction batch to one wire-level idempotency key.
+     * Existing envelopes are validated and restored to their original order;
+     * they are never extended with newly queued work.
+     */
+    private ensureCommitEnvelope;
+    /** Bind the strict local outbox used before any mutation reaches the wire. */
+    setCommitOutbox(outbox: DurableWriteStore): void;
+    setCommitOutboxScope(scope: CommitOutboxScope): void;
+    private sourceMutationIdsFor;
+    /**
+     * Atomically replaces staged mutation journal rows with one exact request.
+     * The returned operations are the JSON-normalized values that must be sent;
+     * callers never send a separately reconstructed payload after sealing.
+     */
+    private sealDurableCommit;
+    /** Best-effort cleanup after a definitive result; replay is safe if it fails. */
+    private removeDurableCommit;
+    /**
+     * Takes either one complete retry envelope or a fresh batch. A retry waits
+     * until every original member has re-entered the queue, preventing an
+     * ambiguous A+B commit from being replayed later as A and B separately.
+     */
+    private takeNextExecutionBatch;
+    /**
+     * Selects one reconnect batch without changing the request identity of work
+     * that was already attempted. Explicit caller keys remain one-call batches;
+     * an existing envelope is replayed only with all of its original members.
+     */
+    private takeOfflineFlushBatch;
     /**
      * Resolvers for per-transaction `confirmation` promises. Populated in
      * `attachConfirmation` at staging time, consumed by the constructor-time
@@ -216,8 +266,8 @@ export declare class TransactionQueue extends EventEmitter {
     private commitCreatedTransactions;
     /**
      * Flushes every pending transaction in one commit, the fast path taken on
-     * reconnect. If the batch fails, each transaction falls back to normal,
-     * one-by-one processing.
+     * reconnect. If transport fails, the transactions retain this exact commit
+     * envelope when they fall back to normal queue processing.
      */
     flushOfflineQueue(): Promise<void>;
     /**
@@ -225,21 +275,21 @@ export declare class TransactionQueue extends EventEmitter {
      * batched commit. Returns the {@link Transaction}, whose `confirmation`
      * promise settles once the server confirms the write.
      */
-    create(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
+    create(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<Transaction>;
     /**
      * Records an update and applies it optimistically, then stages it for the next
      * batched commit. Rapid updates to the same entity coalesce into a single wire
      * operation.
      * @param precomputedChanges - Optional pre-captured changes, used instead of re-reading them from the model.
      */
-    update(model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: WriteOptions): Promise<Transaction>;
+    update(model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<Transaction>;
     /**
      * Records a delete and applies it optimistically. If the row's own create has
      * not yet been sent, both are cancelled locally rather than sending a create
      * followed by a delete; if the create is already in flight, the delete waits
      * until it settles so the server never sees a delete before the create.
      */
-    delete(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
+    delete(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<Transaction>;
     /**
      * Uploads a single attachment, delegating to the mutation executor.
      */
@@ -263,7 +313,7 @@ export declare class TransactionQueue extends EventEmitter {
      * Records an archive and applies it optimistically, then stages it for the
      * next batched commit.
      */
-    archive(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
+    archive(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<Transaction>;
     /**
      * Records an unarchive and applies it optimistically, then stages it for the
      * next batched commit.
@@ -309,7 +359,7 @@ export declare class TransactionQueue extends EventEmitter {
     enqueueCommit(clientTxId: string, operations: CommitTransaction['operations'], options?: {
         causedByTaskId?: string | null;
         reads?: ReadDependency[] | null;
-    }): void;
+    }): Promise<void>;
     /**
      * Drains the pending commit-lane envelopes one at a time. A transient
      * failure, such as a network error, leaves the envelope at the head of the
@@ -346,6 +396,8 @@ export declare class TransactionQueue extends EventEmitter {
      * - Any other business-logic error from the server.
      */
     private isPermanentError;
+    /** True only when the server definitively rejected before applying. */
+    private isDefinitiveRejection;
     /**
      * Handles a failed transaction: retries transient failures with backoff and
      * rolls back permanent ones, settling the transaction's confirmation promise
@@ -372,6 +424,12 @@ export declare class TransactionQueue extends EventEmitter {
      * persistence is disabled.
      */
     loadPersistedTransactions(database: Database): Promise<void>;
+    /**
+     * Restore exact sealed requests after the local database is open. Sealed
+     * envelopes replay through the atomic commit lane and are never re-projected
+     * through model/schema state from the new process.
+     */
+    restoreDurableCommits(): Promise<Set<string>>;
     /**
      * Validates and rehydrates one persisted row. Rows written to the same store
      * by other subsystems are skipped, and rows that fail the persisted