@abloatai/ablo 0.26.0 → 0.28.0

package/dist/Database.js

@@ -1,6 +1,9 @@
 /**
- * Database - Simplified persistence layer
- * Fixed bootstrap triggering and data flow
+ * The local persistence layer for synced models. It stores rows in the
+ * browser's IndexedDB (or in-memory maps when run headlessly), applies inbound
+ * deltas to that store, and fetches the bootstrap snapshot from your sync
+ * server. {@link BaseSyncedStore} drives it, and {@link InstanceCache} holds the
+ * in-memory mirror of what this class persists.
  */
 import { DatabaseManager } from './core/DatabaseManager.js';
 import { StoreManager } from './core/StoreManager.js';
@@ -10,6 +13,43 @@ import { getContext } from './context.js';
 import { AbloConnectionError, AbloValidationError } from './errors.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
 import { syncPositionSchema } from './sync/syncPosition.js';
+import { highestPersistedPrefixSyncId } from './sync/persistedPrefix.js';
+/**
+ * Request identity excludes local timing metadata for re-entrant seals: a
+ * retry rebuilds its envelope with a fresh `sequence`/seal clock, so comparing
+ * those volatile fields would reject every legitimate same-request re-seal as
+ * an idempotency conflict. Only the fields that define the wire request count.
+ */
+function isSameOutboxRecord(existing, candidate) {
+    if (existing.type === 'http_commit_envelope' &&
+        candidate.type === 'http_commit_envelope') {
+        const identity = (record) => ({
+            id: record.id,
+            type: record.type,
+            storageVersion: record.storageVersion,
+            idempotencyKey: record.idempotencyKey,
+            request: record.request,
+            scopeNamespace: record.scopeNamespace,
+        });
+        return JSON.stringify(identity(existing)) === JSON.stringify(identity(candidate));
+    }
+    if (existing.type === 'commit_envelope' &&
+        candidate.type === 'commit_envelope') {
+        const identity = (record) => ({
+            id: record.id,
+            type: record.type,
+            storageVersion: record.storageVersion,
+            origin: record.origin,
+            idempotencyKey: record.idempotencyKey,
+            operations: record.operations,
+            sourceMutationIds: record.sourceMutationIds,
+            commitOptions: record.commitOptions,
+            scope: record.scope,
+        });
+        return JSON.stringify(identity(existing)) === JSON.stringify(identity(candidate));
+    }
+    return JSON.stringify(existing) === JSON.stringify(candidate);
+}
 export class Database {
     // Core database components
     databaseManager;
@@ -22,11 +62,11 @@ export class Database {
         return this.bootstrapHelper;
     }
     /**
-     * PURE scoped snapshot fetch for hydrate-on-enter (P4). Returns the FULL
-     * current rows of the given sync groups, with NO side effects — unlike
+     * Fetch the current rows of the given sync groups as a side-effect-free
+     * snapshot, used to hydrate a scope as the user enters it. Unlike
      * {@link bootstrapFromServer}, it does not persist to IndexedDB and does not
-     * touch the connection's `subscribedSyncGroups` (which the shrinkage check
-     * owns). The caller applies the result to the pool via the SCOPED apply path.
+     * change the connection's subscribed sync groups. The caller applies the
+     * result to the pool through the scoped apply path.
      */
     async fetchScopedBootstrapData(syncGroups) {
         // No lastSyncId → a full snapshot of exactly these groups.
@@ -156,17 +196,14 @@ export class Database {
         getContext().logger.info(`Database opened: ${this.currentDbInfo.name} (${readiness.readyStores.length}/${readiness.totalStores} stores ready)`);
     }
     /**
-     * Compact a record before persisting to IndexedDB
-     * - Removes null/undefined fields
-     * - Removes empty arrays and empty objects
-     * - Drops redundant fields: __typename, __class, clientId, syncStatus
-     *
-     * ARCHITECTURE: By design, this method receives plain objects, not MobX observables:
-     * - WebSocket deltas: Already JSON-parsed (SyncedStore.ts:889)
-     * - Optimistic updates: Models call toJSON() which uses toJS() (SlideLayer.ts:224)
-     * - Bootstrap data: Plain JSON from server
+     * Shrink a record before persisting it. Drops `undefined` fields, empty
+     * arrays, empty objects, and the redundant markers `__typename`, `__class`,
+     * `clientId`, and `syncStatus`. Explicit `null` values are preserved, since
+     * a null is a meaningful "clear this field" in a nullable column.
      *
-     * Note: We do NOT drop required defaults; server provides them.
+     * By design this receives plain objects, never live observables: WebSocket
+     * deltas arrive already parsed, optimistic updates come through `toJSON()`,
+     * and bootstrap data is plain JSON from the server.
      */
     compactRecord(_modelName, data) {
         if (!data || typeof data !== 'object')
@@ -177,8 +214,8 @@ export class Database {
             if (key === '__typename' || key === '__class' || key === 'clientId' || key === 'syncStatus') {
                 continue;
             }
-            // FIXED: Only skip undefined, preserve explicit null values
-            // Null is semantically meaningful in Prisma schemas (nullable fields)
+            // Skip only `undefined`; preserve explicit `null`, which is a
+            // meaningful value for a nullable column.
             if (value === undefined) {
                 continue;
             }
@@ -272,26 +309,24 @@ export class Database {
         // point). Invalid → 0 → full bootstrap, the safe degradation.
         const metadataLastSyncId = syncPositionSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
         const dataAge = metadata?.updatedAt ? Date.now() - metadata.updatedAt.getTime() : Infinity;
-        // ── Zero-style cache-validity check ──────────────────────────
+        // ── Cache-validity check ─────────────────────────────────────
         //
         // The cursor (lastSyncId) is only valid if the data it refers to
-        // actually exists in the stores. If IDB was cleared (or this is a
-        // fresh in-memory session), the metadata's lastSyncId is stale —
-        // sending it to the server would trigger a partial bootstrap that
-        // returns zero deltas because the gap is 0, leaving the client
-        // with an empty ObjectPool.
+        // actually exists in the stores. If the local store was cleared (or
+        // this is a fresh in-memory session), the metadata's lastSyncId is
+        // stale — sending it to the server would trigger a partial bootstrap
+        // that returns zero deltas because the gap is 0, leaving the client
+        // with an empty InstanceCache.
         //
-        // Zero solves this by co-locating the cursor with the cached data:
-        // if the data is gone, the cursor is gone. We achieve the same
-        // property by sampling the actual stores — if they're empty, the
-        // cursor is meaningless regardless of what metadata claims.
+        // The fix is to sample the actual stores: if they hold no rows, the
+        // cursor is meaningless regardless of what the metadata claims.
         const dataExists = this.inMemory
             ? false // In-memory mode: no persistent data across sessions
             : await this.storeManager.hasAnyData();
         // The effective lastSyncId: only trust the metadata cursor when
         // we've confirmed the data it refers to actually exists in the stores.
         const lastSyncId = dataExists ? metadataLastSyncId : 0;
-        // 🔍 DIAGNOSTIC: Log database state
+        // Log the resolved database state for diagnostics.
         getContext().logger.debug('[Database.requiredBootstrap] State check', {
             readinessReady: readiness.ready,
             hasMetadata: !!metadata,
@@ -312,7 +347,8 @@ export class Database {
             getContext().logger.info('Offline detected with local data - using local bootstrap');
         }
         else {
-            // SERVER-AUTHORITATIVE: Always use full bootstrap when online.
+            // The server is the source of truth: always use a full bootstrap
+            // when online.
             type = 'full';
             getContext().logger.info('Full bootstrap - server is source of truth', {
                 reason: offline ? 'offline_no_data' : 'server_authoritative',
@@ -329,7 +365,9 @@ export class Database {
         };
     }
     /**
-     * Bootstrap database with data from Go server
+     * Fetch a bootstrap snapshot (or delta batch) from the sync server and load
+     * it into the local store, then return a {@link BootstrapResult} the caller
+     * applies to the {@link InstanceCache}.
      */
     async bootstrapFromServer(requirements, 
     /** Full sync-group subscription list — what the WS subscribes to
@@ -348,8 +386,8 @@ export class Database {
             modelsToLoad: requirements.modelsToLoad,
         });
         try {
-            // ✅ FETCH FIRST (before any destructive operations)
-            // This prevents data loss if the network request fails
+            // Fetch before any destructive operation, so a failed network
+            // request can't leave the local store empty.
             const startTime = typeof performance !== 'undefined' ? performance.now() : Date.now();
             getContext().logger.info('Fetching bootstrap data from server (before clearing local data)', {
                 type: requirements.type,
@@ -363,8 +401,9 @@ export class Database {
                 hasDeltas: !!bootstrapData.deltas,
                 deltaCount: bootstrapData.deltaCount ?? 0,
             });
-            // ✅ Only clear AFTER successful fetch (transactional safety)
-            // IMPORTANT: Clear if the SERVER says it's a full snapshot, regardless of what we asked.
+            // Clear only after a successful fetch, for transactional safety.
+            // Clear when the server says the response is a full snapshot,
+            // regardless of what type was requested.
             if (bootstrapData.type === 'full') {
                 await this.clear();
             }
@@ -379,7 +418,7 @@ export class Database {
                 // Apply deltas to IndexedDB using processDeltaBatch for better performance.
                 // Capture the return value so the pool can be updated by the caller —
                 // without this, partial-bootstrap DELETEs persist to IDB but don't
-                // evict entities from the in-memory ObjectPool, leaving ghost rows
+                // evict entities from the in-memory InstanceCache, leaving ghost rows
                 // visible on the canvas until a full reload rebuilds the pool.
                 let deltasApplied = 0;
                 let deltaResults;
@@ -501,17 +540,16 @@ export class Database {
     }
     // bootstrapSpecificModels removed per request
     /**
-     * Process incoming delta from WebSocket - simplified
+     * Apply a single inbound delta from the WebSocket to the local store.
      *
-     * ⚠️ PERFORMANCE NOTE: This method is called for each individual delta.
-     * For batch processing, use processDeltaBatch() instead to avoid
-     * transaction overhead (2x transactions per delta = major bottleneck).
+     * This handles one delta at a time. To apply several, prefer
+     * {@link processDeltaBatch}, which commits them in one IndexedDB transaction
+     * rather than two transactions per delta.
      *
-     * 📝 PARTIAL DELTA PATTERN:
-     * - Server sends only changed fields: {id, position: {...}, updatedAt}
-     * - UPDATE deltas are MERGED with existing records: {...existing, ...delta}
-     * - This preserves fields not included in the delta (e.g., deckId, title)
-     * - Explicit null values ARE preserved: {position: null} clears the field
+     * Update deltas carry only the changed fields, so they are merged onto the
+     * existing record rather than replacing it. That preserves fields the delta
+     * omits (such as deckId or title), and an explicit null is kept as a value,
+     * clearing that field.
      */
     async processDelta(delta) {
         const { actionType, modelName, modelId, data, syncId } = delta;
@@ -519,7 +557,7 @@ export class Database {
         if (!store) {
             return { action: 'verify', modelName, modelId };
         }
-        // Best-practice gating: ignore already-applied deltas by comparing with persisted lastSyncId
+        // Idempotency gate: ignore already-applied deltas by comparing with the persisted lastSyncId
         try {
             const lastApplied = await this.getLastSyncId();
             const incomingId = typeof syncId === 'number' ? syncId : undefined;
@@ -572,11 +610,12 @@ export class Database {
                 return { action: 'add', modelName, modelId, data: compacted };
             }
             case 'U': {
-                // ✅ UPDATE: MUST merge with existing record (partial delta pattern)
-                // Read existing record first
+                // Update: merge onto the existing record (partial-delta pattern).
+                // Read the existing record first.
                 const existing = await store.get(modelId);
-                // CRITICAL FIX: Skip UPDATE if there's no existing record to merge with
-                // Creating a record from partial UPDATE data causes corruption (missing deckId, etc.)
+                // Skip the update when there's no existing record to merge with:
+                // building a record from partial update data would corrupt it
+                // (missing deckId, and so on).
                 if (!existing) {
                     getContext().observability.breadcrumb('Skipping UPDATE delta - no existing record to merge with', 'sync.database', 'warning', {
                         modelName,
@@ -619,7 +658,7 @@ export class Database {
                     getContext().observability.breadcrumb(`IndexedDB delete failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
                         error: err instanceof Error ? err.message : String(err),
                     });
-                    // Surface failure so caller does not mutate ObjectPool inconsistently
+                    // Surface failure so caller does not mutate InstanceCache inconsistently
                     throw err;
                 }
                 return { action: 'remove', modelName, modelId };
@@ -659,27 +698,20 @@ export class Database {
         }
     }
     /**
-     * ✅ PERFORMANCE FIX: Process multiple deltas in a single IndexedDB transaction
+     * Apply many deltas to the local store in as few IndexedDB transactions as
+     * possible. Deltas are grouped by store, and each store's writes commit in a
+     * single transaction, so a batch of 186 deltas becomes roughly one
+     * transaction per store instead of two per delta.
      *
-     * This method dramatically improves sync performance by:
-     * 1. Batch-reading all existing records for UPDATEs (outside transaction for speed)
-     * 2. Opening a single transaction per store for all writes
-     * 3. Merging UPDATE deltas with existing data to preserve unmodified fields
-     * 4. Updating metadata only once at the end with highest syncId
+     * The method reads the existing records for update deltas up front, then
+     * merges each update onto its existing record so fields the delta omits are
+     * preserved and an explicit null still clears its field. It advances the
+     * persisted sync cursor once, to the highest committed sync id.
      *
-     * Performance impact: 186 deltas goes from ~372 transactions to just 1 transaction
-     *
-     * 📝 PARTIAL DELTA MERGE PATTERN:
-     * - UPDATE deltas contain only changed fields
-     * - We merge with existing: {...existing, ...delta}
-     * - Preserves deckId, title, settings etc. when updating just position
-     * - Handles explicit null: {field: null} clears the field correctly
-     *
-     * 🔄 LINEAR-STYLE CONFLICT RESOLUTION:
-     * - Builds a map of DELETE deltas with their syncIds
-     * - Before processing UPDATE/INSERT, checks for DELETE with higher syncId
-     * - Skips stale updates for entities that will be/were deleted
-     * - Prevents 404 errors from fetching already-deleted entities
+     * Conflict resolution follows a delete-wins rule: it first indexes the
+     * delete deltas by entity, then skips any insert or update whose sync id is
+     * at or below a delete for the same entity. This avoids resurrecting a
+     * deleted entity and avoids fetching one that no longer exists.
      */
     async processDeltaBatch(deltas) {
         if ((!this.workspaceDb && !this.inMemory) || this.isClosing || deltas.length === 0) {
@@ -722,14 +754,11 @@ export class Database {
         }
         // Prepare results aligned with input order
         const results = new Array(deltas.length);
-        // ========================================================================
-        // LINEAR-STYLE CONFLICT RESOLUTION: Build DELETE syncId index
-        // ========================================================================
-        // Per Linear's architecture: "If the syncId of the deleting action is larger,
-        // the model will not be created." This prevents processing stale UPDATE deltas
-        // for entities that have been cascade-deleted (where DELETE delta exists).
-        // ========================================================================
-        const deleteSyncIds = new Map(); // key: "ModelName:modelId" -> DELETE syncId
+        // Build a delete index for conflict resolution. When a delete has a sync
+        // id at or above a later insert or update for the same entity, that entity
+        // is not (re)created — which drops stale updates for cascade-deleted
+        // entities.
+        const deleteSyncIds = new Map(); // key: "ModelName:modelId" -> delete syncId
         for (const delta of deltas) {
             if (delta.actionType === 'D' && delta.syncId) {
                 const key = `${delta.modelName}:${delta.modelId}`;
@@ -749,21 +778,20 @@ export class Database {
         }
         // Group deltas by store for efficient transaction management.
         //
-        // We intentionally track TWO highwater marks: `highestSyncId` for the
-        // total range seen, and `highestPersistedSyncId` accumulated only from
-        // deltas whose store transaction actually succeeded. The cursor
-        // advance (at `updateWorkspaceMetadata`) uses ONLY the persisted one.
+        // The method tracks the total range seen plus the exact input indexes whose
+        // store transaction committed. The cursor is derived from their ordered
+        // prefix after every store finishes; a maximum alone is unsafe because a
+        // later store can succeed after an earlier store failed.
         //
-        // Without this split, a single store-level IDB failure (e.g. compact
-        // record missing required field, validation abort) silently advances
-        // the cursor past deltas that never wrote to IDB. Next partial
-        // bootstrap asks "what's new since {advanced cursor}?" and the
-        // skipped rows fall into the already-seen range forever — the
-        // observed "postgres has the deck, IDB doesn't, full reload can't
-        // recover it" failure mode.
+        // Without this split, a single store-level failure (a compacted record
+        // missing a required field, a validation abort) would advance the cursor
+        // past deltas that never wrote to IndexedDB. The next partial bootstrap
+        // would ask "what's new since {advanced cursor}?", the skipped rows would
+        // fall into the already-seen range forever, and the local store would stay
+        // permanently behind the server with no way to recover on reload.
         const deltasByStore = new Map();
         let highestSyncId = 0;
-        let highestPersistedSyncId = 0;
+        const persistedIndexes = new Set();
         let skippedDueToConflict = 0;
         deltas.forEach((delta, idx) => {
             // Normalize to number — postgres sends bigint syncIds as strings.
@@ -773,9 +801,8 @@ export class Database {
             if (typeof deltaSyncIdNum === 'number' && !isNaN(deltaSyncIdNum) && deltaSyncIdNum > highestSyncId) {
                 highestSyncId = deltaSyncIdNum;
             }
-            // ========================================================================
-            // CONFLICT CHECK: Skip UPDATE/INSERT if DELETE exists with higher syncId
-            // ========================================================================
+            // Conflict check: skip an insert or update when a delete for the same
+            // entity has an equal or higher sync id.
             if (delta.actionType === 'U' ||
                 delta.actionType === 'I' ||
                 delta.actionType === 'C' ||
@@ -795,6 +822,9 @@ export class Database {
                             deleteSyncId,
                         });
                         results[idx] = { action: 'verify', modelName: delta.modelName, modelId: delta.modelId };
+                        // The later delete in this same ordered frame supersedes this
+                        // value, so the stale predecessor requires no separate write.
+                        persistedIndexes.add(idx);
                         skippedDueToConflict++;
                         return; // Skip this delta
                     }
@@ -823,8 +853,8 @@ export class Database {
             if (!store)
                 continue;
             try {
-                // ✅ BEST PRACTICE: Batch read-modify-write pattern
-                // Step 1: Identify which deltas need existing data (UPDATEs)
+                // Batch read-modify-write.
+                // Step 1: Identify which deltas need existing data (updates)
                 const updateDeltas = storeDeltas.filter(({ delta }) => delta.actionType === 'U');
                 const updateIds = updateDeltas.map(({ delta }) => delta.modelId);
                 // Step 2: Batch read all existing records in a SINGLE IDB transaction
@@ -849,8 +879,9 @@ export class Database {
                         }
                     }
                 }
-                // ✅ SELF-HEALING: Fetch missing records for UPDATE deltas
-                // Track IDs that failed to fetch (404 = entity deleted, skip the delta)
+                // Self-heal by fetching missing records for update deltas.
+                // Track ids that failed to fetch (a 404 means the entity was deleted,
+                // so its delta is skipped).
                 const failedToFetch = new Set();
                 if (missingIds.size > 0) {
                     getContext().logger.info(`[Database.processDeltaBatch] Found ${missingIds.size} missing records for ${modelName}, fetching from server...`);
@@ -924,13 +955,11 @@ export class Database {
                             });
                             break;
                         case 'U': {
-                            // ✅ UPDATE: Merge delta with existing record (already fetched)
+                            // Update: merge the delta onto the existing record (already fetched).
                             const existing = existingRecords.get(modelId);
-                            // ========================================================================
-                            // SKIP STALE DELTAS: If entity doesn't exist locally AND failed to fetch
-                            // from server (404), this is a stale UPDATE for a deleted entity.
-                            // Per Linear's architecture, skip it instead of creating incomplete data.
-                            // ========================================================================
+                            // Skip a stale update: if the entity is neither in the local
+                            // store nor fetchable from the server (a 404), it was deleted,
+                            // so skip it rather than create an incomplete record.
                             if (!existing && failedToFetch.has(modelId)) {
                                 getContext().logger.debug('[Database.processDeltaBatch] Skipping UPDATE for deleted entity', {
                                     modelName,
@@ -939,8 +968,9 @@ export class Database {
                                 stagedResults.push({ action: 'verify', modelName, modelId, idx });
                                 break; // Skip this delta
                             }
-                            // CRITICAL FIX: Skip UPDATE if there's no existing record to merge with
-                            // Creating a record from partial UPDATE data causes corruption (missing deckId, etc.)
+                            // Skip the update when there's no existing record to merge with:
+                            // building a record from partial update data would corrupt it
+                            // (missing deckId, and so on).
                             if (!existing) {
                                 getContext().observability.breadcrumb('Batch: Skipping UPDATE delta - no existing record', 'sync.database', 'warning', {
                                     modelName,
@@ -993,14 +1023,14 @@ export class Database {
                     tx.oncomplete = () => { resolve(); };
                     tx.onerror = () => { reject(tx.error); };
                 });
-                // Only commit staged results to the global results if the transaction succeeded.
-                // Also advance `highestPersistedSyncId` ONLY for deltas in this successful tx
-                // — so the cursor can't advance past rows that never wrote to IDB.
+                // Only commit staged results to the global results if the transaction
+                // succeeded. Record input indexes rather than a maximum sync id; the
+                // durable cursor is the prefix through these indexes.
                 for (const r of stagedResults) {
                     // Resolve the originating delta so we can carry its
                     // transactionId through to the result. Echo detection in
                     // `SyncClient.applyDeltaBatchToPool` reads it.
-                    const sourceDelta = storeDeltas.find(({ idx }) => idx === r.idx)?.delta;
+                    const sourceDelta = deltas[r.idx];
                     results[r.idx] = {
                         action: r.action,
                         modelName: r.modelName,
@@ -1008,13 +1038,7 @@ export class Database {
                         data: r.data,
                         transactionId: sourceDelta?.transactionId,
                     };
-                    const rawSyncId = storeDeltas[storeDeltas.findIndex(({ idx }) => idx === r.idx)]?.delta.syncId;
-                    // SyncDelta.syncId is typed as number but postgres serializes
-                    // bigint to string on the wire — coerce before compare.
-                    const syncId = typeof rawSyncId === 'string' ? Number(rawSyncId) : rawSyncId;
-                    if (typeof syncId === 'number' && !isNaN(syncId) && syncId > highestPersistedSyncId) {
-                        highestPersistedSyncId = syncId;
-                    }
+                    persistedIndexes.add(r.idx);
                 }
             }
             catch (err) {
@@ -1048,11 +1072,12 @@ export class Database {
                 }
             }
         }
-        // Update metadata only to the highest syncId whose store transaction
-        // actually committed. Using `highestSyncId` (the range-seen max) would
-        // advance the cursor past deltas that failed to persist — the "cursor
-        // ahead of IDB" divergence that makes subsequent partial bootstraps
-        // skip the missing rows forever.
+        // Advance only through the durable INPUT PREFIX. IDs need not be
+        // numerically contiguous because other tenants and filtered sync groups
+        // occupy gaps; the server-delivered order is the relevant sequence.
+        const highestPersistedSyncId = highestPersistedPrefixSyncId(deltas, persistedIndexes);
+        // Using `highestSyncId` (the range-seen max) would advance past an earlier
+        // failed store transaction and permanently skip its delta.
         //
         // If `highestPersistedSyncId === 0` (every store tx failed), we leave
         // the metadata alone. Next partial bootstrap will re-deliver the
@@ -1104,13 +1129,7 @@ export class Database {
         const store = this.getRequiredStore(modelName);
         return await store.getAllFromIndex(indexName, value);
     }
-    /**
-     * Update workspace metadata
-     */
-    /**
-     * Get the last sync ID from workspace metadata
-     */
-    /** Read workspace metadata from IDB (returns null if db not open). */
+    /** Read workspace metadata from IndexedDB. Returns null when the database is not open. */
     async getWorkspaceMetadata() {
         if (this.inMemory)
             return this.inMemoryMetadata;
@@ -1167,16 +1186,51 @@ export class Database {
      *  delete/getAll/getAllFromIndex surface, so callers don't need to
      *  branch on which one they got back. */
     get transactionStore() {
-        return this.getStore('__transactions');
+        return this.getRequiredStore('__transactions');
     }
     async saveTransaction(transaction) {
-        await this.transactionStore?.put(transaction);
+        await this.transactionStore.put(transaction);
+    }
+    /** Persist one burst of journal rows in a single strict durability group. */
+    async saveTransactions(transactions) {
+        if (transactions.length === 0)
+            return;
+        if (this.inMemory) {
+            await Promise.all(transactions.map((transaction) => this.transactionStore.put(transaction)));
+            return;
+        }
+        const db = this.workspaceDb;
+        if (!db || this.isClosing) {
+            throw new AbloConnectionError('Database not opened for mutation journal', {
+                code: 'db_not_opened',
+            });
+        }
+        await new Promise((resolve, reject) => {
+            try {
+                const tx = db.transaction(['__transactions'], 'readwrite', {
+                    durability: 'strict',
+                });
+                const store = tx.objectStore('__transactions');
+                for (const transaction of transactions)
+                    store.put(transaction);
+                tx.oncomplete = () => { resolve(); };
+                tx.onabort = () => {
+                    reject(tx.error ?? new Error('Mutation journal transaction aborted'));
+                };
+                tx.onerror = () => {
+                    // onabort owns rejection.
+                };
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
     }
     async removeTransaction(id) {
-        await this.transactionStore?.delete(id);
+        await this.transactionStore.delete(id);
     }
     async getPersistedTransactions() {
-        const rows = (await this.transactionStore?.getAll()) ?? [];
+        const rows = await this.transactionStore.getAll();
         // Storage layer returns the centralized `Record<string, unknown>`
         // shape from `ObjectStoreContract`. PersistedTransaction adds an
         // index signature so each row already structurally satisfies the
@@ -1184,14 +1238,138 @@ export class Database {
         // here, and it only accepts PersistedTransaction.
         return rows;
     }
+    async getPersistedTransaction(id) {
+        return (await this.transactionStore.get(id));
+    }
+    /**
+     * Atomically seal one exact commit request and consume the staged mutation
+     * records it replaces. The read, optional add, and deletes share one strict
+     * IndexedDB transaction, so a crash can expose the staged records or the
+     * sealed envelope, never a missing handoff. Returns the pre-existing record
+     * when the envelope id was already sealed (retry/re-entrant call).
+     */
+    async sealTransactionRecord(record, consumedRecordIds) {
+        const recordId = record.id;
+        if (!recordId) {
+            throw new AbloValidationError('A sealed transaction record must carry an id', {
+                code: 'invalid_body',
+            });
+        }
+        if (this.inMemory) {
+            const store = this.transactionStore;
+            const existing = (await store.get(recordId));
+            if (existing && !isSameOutboxRecord(existing, record)) {
+                throw new AbloValidationError('Commit outbox key already identifies a different request', {
+                    code: 'idempotency_conflict',
+                });
+            }
+            if (!existing) {
+                const sources = await Promise.all(consumedRecordIds.map((id) => store.get(id)));
+                if (sources.some((source) => source === undefined)) {
+                    throw new AbloValidationError('Commit outbox source mutations were already claimed by another envelope', { code: 'idempotency_conflict' });
+                }
+                await store.add(record);
+            }
+            for (const id of consumedRecordIds) {
+                if (id !== recordId)
+                    await store.delete(id);
+            }
+            return existing;
+        }
+        const db = this.workspaceDb;
+        if (!db || this.isClosing) {
+            throw new AbloConnectionError('Database not opened for commit outbox', {
+                code: 'db_not_opened',
+            });
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = db.transaction(['__transactions'], 'readwrite', {
+                    durability: 'strict',
+                });
+                const store = tx.objectStore('__transactions');
+                const getRequest = store.get(recordId);
+                const sourceIds = [...new Set(consumedRecordIds)].filter((id) => id !== recordId);
+                const sourceRequests = sourceIds.map((id) => store.get(id));
+                const sourceExists = new Array(sourceRequests.length).fill(false);
+                let existing;
+                let collisionError;
+                let envelopeRead = false;
+                let sourcesRead = 0;
+                let promotionStarted = false;
+                const promote = () => {
+                    if (promotionStarted ||
+                        !envelopeRead ||
+                        sourcesRead !== sourceRequests.length)
+                        return;
+                    promotionStarted = true;
+                    if (existing && !isSameOutboxRecord(existing, record)) {
+                        collisionError = new AbloValidationError('Commit outbox key already identifies a different request', { code: 'idempotency_conflict' });
+                        tx.abort();
+                        return;
+                    }
+                    // A new envelope owns promotion only while every source row still
+                    // exists. This is the fleet/tab execution claim: a second tab that
+                    // restored the same journal entries under another key loses here and
+                    // cannot dispatch. An identical existing envelope is an idempotent
+                    // retry, so its already-consumed sources may be absent.
+                    if (!existing && sourceExists.some((exists) => !exists)) {
+                        collisionError = new AbloValidationError('Commit outbox source mutations were already claimed by another envelope', { code: 'idempotency_conflict' });
+                        tx.abort();
+                        return;
+                    }
+                    if (!existing)
+                        store.add(record);
+                    for (const id of sourceIds)
+                        store.delete(id);
+                };
+                getRequest.onsuccess = () => {
+                    existing = getRequest.result;
+                    envelopeRead = true;
+                    promote();
+                };
+                getRequest.onerror = () => {
+                    tx.abort();
+                };
+                sourceRequests.forEach((request, index) => {
+                    request.onsuccess = () => {
+                        sourceExists[index] = request.result !== undefined;
+                        sourcesRead += 1;
+                        promote();
+                    };
+                    request.onerror = () => {
+                        tx.abort();
+                    };
+                });
+                tx.oncomplete = () => { resolve(existing); };
+                tx.onabort = () => {
+                    reject(collisionError ??
+                        tx.error ??
+                        getRequest.error ??
+                        new Error('Commit outbox transaction aborted'));
+                };
+                tx.onerror = () => {
+                    // onabort owns rejection so the promise settles exactly once.
+                };
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
     async cleanupOldTransactions(maxAge) {
         const store = this.transactionStore;
-        if (!store)
-            return 0;
         const rows = (await store.getAll());
         const cutoff = Date.now() - maxAge;
         let cleaned = 0;
         for (const tx of rows) {
+            // Live write intent has no safe age-based expiry. In particular, server
+            // idempotency retention may already have elapsed, so silently deleting or
+            // blindly replaying an old envelope would both be unsafe. Restoration
+            // owns quarantine/reconciliation for these records.
+            if (tx.type === 'commit_envelope' || tx.type === 'pending_mutation') {
+                continue;
+            }
             if (typeof tx.timestamp === 'number' && tx.timestamp < cutoff) {
                 await store.delete(tx.id);
                 cleaned++;
@@ -1267,8 +1445,11 @@ export class Database {
         this.currentDbInfo = null;
         getContext().logger.debug('Database closed');
     }
-    async clear() {
+    async clear(options = {}) {
         await this.storeManager.clearAllStores();
+        if (options.includeWriteJournal) {
+            await this.transactionStore.clear();
+        }
         getContext().logger.info('All stores cleared');
     }
 }