@abloatai/ablo 0.27.0 → 0.28.0

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/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 CommitOutboxStore 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 { CommitOutboxStore } from './commitOutboxStore.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: CommitOutboxStore): 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