@abloatai/ablo 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.28.0
+
+### Minor Changes
+
+- **Commits are now crash-durable — a sealed envelope replays the exact request after a restart, on both transports.** Before a batch reaches the wire, the WebSocket client seals it into one atomic outbox record: the stable idempotency key, the exact JSON-normalized ordered operations, and the source mutations it supersedes. Recovery replays the sealed request as it was sent — never re-projected from model state in the new process — and a multi-operation commit is only ever replayed whole, so an atomic A+B can't come back later as A and B separately.
+
+- **The stateless HTTP client replays its outbox on startup.** It persists the exact request (method, path, body, idempotency key) and re-sends unacknowledged envelopes before its first new request. A definitive rejection (a 4xx other than 429) settles the envelope instead of retrying it.
+
+- **New `commitOutbox` client option + `CommitOutboxStore` interface.** Browsers default to strict IndexedDB storage when persistence is on; Node agents and workers can inject workflow-, SQLite-, or filesystem-backed storage so commits survive process restarts. The client's transaction journal now writes with strict durability, so an acknowledged outbox record means disk-backed.
+
+- **Replay is fenced and fails closed.** Reusing an idempotency key with a different request is rejected on both transports; replay is scoped to the actor and server that sealed the envelope and bounded to the server's idempotency retention, so a stale envelope is held for review instead of re-sent; a write queued behind an ambiguous predecessor waits for it to settle rather than overtaking it; and a persistence adapter that cannot guarantee durability reports failure instead of phantom success. Generated create ids are sealed with the request, so a crash mid-create recovers the same row.
+
+- **`@abloatai/ablo/commit` publishes the transport-independent v2 commit contract.** Branded identifiers, ordered operations, explicit write preconditions (`unchanged_since`, `version_matches`, `claim_fence`), and a discriminated `CommitReceipt` — `committed`, `conflicted` (carrying the smallest current state needed to reconcile), or `rejected` (a typed error plus the capability a retry would need). This release publishes the contract so tooling and tests can validate against it today; the engine's live commit path still speaks the current protocol, and the cutover to v2 ships server-side.
+
+- **New wire exports.** `@abloatai/ablo/wire` gains the matching `CommitRequestMessage` / `CommitResultMessage` frames, re-exports the current transport's operation schemas under `legacyCommit*` names, and exports `BootstrapReason` — the machine-readable reasons a live delta stream must resume via catch-up (`too_far_behind`, `too_many_deltas`, `missing_entities`, `stream_gap`).
+
+- **Reactive reads are typed as what they actually return: snapshot rows, not model instances.** `useAblo` selectors now receive `AbloReads<Schema>` — model reads typed as the row's data fields plus schema computeds, without relation accessors or model methods. Reading `row.layers` inside a selector is a compile error instead of a silent `undefined` at runtime; compose relations through a dedicated hook or selector instead. The new `Row<'slides'>` / `InferRow` types are the snapshot-row companion to `Model<'slides'>`, mirroring what `toReactiveSnapshot()` produces. This is a type-level change only: selectors that compiled against relation accessors now fail to compile, and each of those reads was already returning `undefined` — the new errors point at real bugs. Runtime behavior is unchanged.
+
+### Patch Changes
+
+- **The resume cursor advances only through the contiguous durable prefix of a delta frame.** A frame spanning several local stores commits per store, and those transactions can fail independently — taking the maximum id from any successful store could permanently skip an earlier failed delta on every later catch-up.
+
+- **Conflicting undo-scope options warn instead of being silently ignored.** A scope keeps the options it was created with; the silent version of that rule could leave a surface believing it enabled stream recording when it hadn't.
+
+- **Docs and error copy name the real HTTP mount.** REST paths are documented as `/api/v1/...` — the OpenAPI server URLs carry the `/api` mount — and the `jwt_issuer_untrusted` message no longer points at an endpoint that doesn't exist.
+
 ## 0.27.0
 
 ### Minor Changes
@@ -8,7 +34,7 @@
 
 - **Beats carry progress and pressure.** `heartbeat({ details })` stores lightweight progress as the claim's peer-visible `meta.progress` (last beat wins, via `claim.state`); every beat's answer reports `queueDepth` — how many participants wait in line behind the lease — observable per auto-beat with the new `onHeartbeat` claim option.
 
-- **`ablo.claims.heartbeatAll({ ttl })`** extends every lease the credential holds in one request (`POST /v1/claims/heartbeat`) — the stateless twin of the WebSocket keepalive, for workers holding many rows.
+- **`ablo.claims.heartbeatAll({ ttl })`** extends every lease the credential holds in one request (`POST /api/v1/claims/heartbeat`) — the stateless twin of the WebSocket keepalive, for workers holding many rows.
 
 - **Keepalive renewals extend but never shorten a lease**, so an explicit work-duration `ttl` now survives pings and brief reconnects instead of collapsing to the liveness window.
 
@@ -39,7 +65,7 @@
 ### Minor Changes
 
 - ca30064: Logical replication is now the documented default storage path, with self-service data-source registration from the CLI.
-  - **`ablo connect --register`** — registers your database as an Ablo data source over logical replication in one step: it runs the same pre-flight replication probe `ablo connect` uses (server reachable, `REPLICATION` privilege, `wal_level=logical`, publication/slot creatable), and on success `POST`s the connection to the engine's `/v1/datasources`. The `ek_`-authed call scopes the source to your org automatically; the password is stored decomposed as a secret, never echoed back. This is the "registration is the enable" path — there is no separate tier or flag to pick.
+  - **`ablo connect --register`** — registers your database as an Ablo data source over logical replication in one step: it runs the same pre-flight replication probe `ablo connect` uses (server reachable, `REPLICATION` privilege, `wal_level=logical`, publication/slot creatable), and on success `POST`s the connection to the engine's `/api/v1/datasources`. The `ek_`-authed call scopes the source to your org automatically; the password is stored decomposed as a secret, never echoed back. This is the "registration is the enable" path — there is no separate tier or flag to pick.
   - **`ablo init` leads with logical replication** — the default storage mode is now `replication` (was `endpoint`); the generated env + next-steps point at `ablo connect` / `ablo connect --register`. The signed-endpoint and direct modes remain as the explicit fallback / legacy options.
   - **`ablo status`** — a data-plane diagnostic that probes whether your registered source is reachable and replicating (failure-only reporting, so it never falsely reports healthy).
   - **`ablo push`** — minor guard/UX refinements (deploy-target clarity).
@@ -594,7 +620,7 @@
 
 ### Patch Changes
 
-- `Model<'name'>` type helper via the `Register` binding — name your model in one parameter (`Model<'tasks'>`) instead of restating `typeof schema`; `Model<S, 'name'>` is also supported and `InferModel` is deprecated. CLI: retire the stale `dev` wording from the login outro and `push` header. Docs: cover the `Register` binding end-to-end and document the `pk_` publishable key + the `/v1/commits` HTTP path.
+- `Model<'name'>` type helper via the `Register` binding — name your model in one parameter (`Model<'tasks'>`) instead of restating `typeof schema`; `Model<S, 'name'>` is also supported and `InferModel` is deprecated. CLI: retire the stale `dev` wording from the login outro and `push` header. Docs: cover the `Register` binding end-to-end and document the `pk_` publishable key + the `/api/v1/commits` HTTP path.
 - 3024593: Fix `sessions.create({ user })` 403 — user sessions now mint via the sk\_-gated ephemeral-key door
   - `sessions.create({ user })` mints an `ek_` user session via `/auth/ephemeral-keys` (was wrongly routed through `/auth/capability`, which rejects human participants — writes were being attributed to agents).
   - Control-plane calls always present your original `sk_`, never the client's exchanged sync credential.

package/README.md

@@ -442,7 +442,7 @@ HTTP endpoint when a server-to-server caller needs to write without opening a
 WebSocket:
 
 ```bash
-curl https://api.abloatai.com/v1/commits \
+curl https://api.abloatai.com/api/v1/commits \
   -H "Authorization: Bearer sk_test_..." \
   -H "Content-Type: application/json" \
   -d '{ "operations": [

package/dist/BaseSyncedStore.js

@@ -602,7 +602,7 @@ export class BaseSyncedStore {
                 this.syncWebSocket?.disconnect();
                 this.updateSyncStatus({ state: 'error', error: error });
                 // SECURITY: Clear locally cached data when session is invalid
-                this.database.clear().catch(() => { });
+                this.database.clear({ includeWriteJournal: true }).catch(() => { });
                 this.objectPool.clear();
                 return 'session_error';
             }
@@ -779,16 +779,15 @@ export class BaseSyncedStore {
         if (this.initialized)
             return { success: true };
         this.userContext = context;
-        // Propagate identity to the SyncClient. Without this, every mutation
-        // silently drops in the mutation-staging path with a null userId and
-        // organizationId, because those guards early-return rather than throw.
-        // Setting it here, where the store receives the context, keeps identity
-        // in a single place.
-        yield this.syncClient.initialize(context.userId, context.organizationId);
         try {
             this.updateSyncStatus({ state: 'syncing', progress: 0 });
-            // Open database
+            // The commit outbox and offline mutation journal live in IndexedDB.
+            // Open it before SyncClient restores either one; reading first used to
+            // make persistence silently look empty on every cold start.
             yield this.database.open(context.userId, context.organizationId);
+            // Propagate identity only after storage is ready, then restore sealed
+            // requests before accepting fresh mutations.
+            yield this.syncClient.initialize(context.userId, context.organizationId);
             // Hydrate from IndexedDB (fast, cached data)
             let hasLocalData = false;
             try {
@@ -1202,7 +1201,7 @@ export class BaseSyncedStore {
             this.updateSyncStatus({ state: 'error', error, isSessionError: true });
             // SECURITY: Clear IndexedDB data on session expiry.
             // When auth is revoked, locally cached data must not persist on disk.
-            this.database.clear().catch((clearErr) => {
+            this.database.clear({ includeWriteJournal: true }).catch((clearErr) => {
                 // consumer register: session ended, but cached data may remain on disk
                 getContext().logger.error('Your session ended, but some locally cached data could not be cleared from this device.');
                 getContext().logger.debug('[BaseSyncedStore] Failed to clear database on session error', clearErr);

package/dist/Database.d.ts

@@ -286,8 +286,19 @@ export declare class Database {
      *  branch on which one they got back. */
     private get transactionStore();
     saveTransaction(transaction: PersistedTransaction): Promise<void>;
+    /** Persist one burst of journal rows in a single strict durability group. */
+    saveTransactions(transactions: readonly PersistedTransaction[]): Promise<void>;
     removeTransaction(id: string): Promise<void>;
     getPersistedTransactions(): Promise<PersistedTransaction[]>;
+    getPersistedTransaction(id: string): Promise<PersistedTransaction | undefined>;
+    /**
+     * 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).
+     */
+    sealTransactionRecord(record: PersistedTransaction, consumedRecordIds: readonly string[]): Promise<PersistedTransaction | undefined>;
     cleanupOldTransactions(maxAge: number): Promise<number>;
     /**
      * Store management
@@ -332,6 +343,8 @@ export declare class Database {
      */
     isOpen(): boolean;
     close(): Promise<void>;
-    clear(): Promise<void>;
+    clear(options?: {
+        includeWriteJournal?: boolean;
+    }): Promise<void>;
 }
 export {};

package/dist/Database.js

@@ -13,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;
@@ -741,10 +778,10 @@ export class Database {
         }
         // Group deltas by store for efficient transaction management.
         //
-        // The method tracks two high-water marks: `highestSyncId` for the total
-        // range seen, and `highestPersistedSyncId`, accumulated only from deltas
-        // whose store transaction actually committed. 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 failure (a compacted record
         // missing a required field, a validation abort) would advance the cursor
@@ -754,7 +791,7 @@ export class Database {
         // 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.
@@ -785,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
                     }
@@ -983,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.
-                // Advance `highestPersistedSyncId` only for deltas in this successful
-                // transaction, 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,
@@ -998,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) {
@@ -1038,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
@@ -1151,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
@@ -1168,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++;
@@ -1251,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');
     }
 }

package/dist/Model.d.ts

@@ -364,8 +364,25 @@ export declare abstract class Model {
      * the schema's `T` describes. Computed relations (`referenceModel`/
      * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
      * row projection; they're lazy/recursive and not part of the row's data.
+     *
+     * Schema-derived getters (`computed:` entries and `${field}Json` getters) ARE
+     * materialized, as non-enumerable own values. The schema's inferred row type
+     * includes them, so omitting them would make every snapshot read of a computed
+     * silently `undefined` — a type-level lie. They're evaluated here, inside the
+     * caller's tracked function, so the reaction subscribes to whatever fields the
+     * getter reads. Non-enumerable keeps write-path parity with model instances:
+     * an instance's getters sit on the prototype and never enter `{...model}`
+     * spreads or `JSON.stringify`, and materialized values must not either — a
+     * spread-into-update would otherwise send computed keys to the server.
      */
     toReactiveSnapshot<T = ModelData>(): T;
+    /**
+     * Names of schema-derived getters — `computed:` entries and `${field}Json`
+     * getters — that {@link toReactiveSnapshot} materializes onto snapshots.
+     * The dynamic model class built by `registerModelsFromSchema` overrides this;
+     * hand-written Model subclasses default to none.
+     */
+    getDerivedGetterNames(): readonly string[];
     /**
      * Get field changes for activity tracking
      */

package/dist/Model.js

@@ -23,6 +23,8 @@ export class ValidationError extends Error {
         this.name = 'ValidationError';
     }
 }
+/** Shared frozen default for {@link Model.getDerivedGetterNames}. */
+const EMPTY_DERIVED_GETTERS = Object.freeze([]);
 /**
  * The abstract base class every domain model extends. It holds the model's id
  * and timestamps, tracks in-place property changes for change detection and
@@ -734,6 +736,16 @@ export class Model {
      * the schema's `T` describes. Computed relations (`referenceModel`/
      * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
      * row projection; they're lazy/recursive and not part of the row's data.
+     *
+     * Schema-derived getters (`computed:` entries and `${field}Json` getters) ARE
+     * materialized, as non-enumerable own values. The schema's inferred row type
+     * includes them, so omitting them would make every snapshot read of a computed
+     * silently `undefined` — a type-level lie. They're evaluated here, inside the
+     * caller's tracked function, so the reaction subscribes to whatever fields the
+     * getter reads. Non-enumerable keeps write-path parity with model instances:
+     * an instance's getters sit on the prototype and never enter `{...model}`
+     * spreads or `JSON.stringify`, and materialized values must not either — a
+     * spread-into-update would otherwise send computed keys to the server.
      */
     toReactiveSnapshot() {
         const snapshot = {
@@ -744,8 +756,8 @@ export class Model {
         if (this.archivedAt !== undefined)
             snapshot.archivedAt = this.archivedAt;
         const properties = getActiveRegistry().getProperties(this.getModelName());
+        const self = this;
         if (properties) {
-            const self = this;
             for (const [propName, metadata] of properties) {
                 if (metadata.type === 'ephemeralProperty' ||
                     metadata.type === 'referenceModel' ||
@@ -757,8 +769,27 @@ export class Model {
                 snapshot[propName] = self[propName];
             }
         }
+        for (const name of this.getDerivedGetterNames()) {
+            Object.defineProperty(snapshot, name, {
+                // Evaluated on the model instance so `${field}Json` caches stay on it
+                // and the enclosing reaction tracks the fields the getter reads.
+                value: self[name],
+                enumerable: false,
+                configurable: true,
+                writable: false,
+            });
+        }
         return snapshot;
     }
+    /**
+     * Names of schema-derived getters — `computed:` entries and `${field}Json`
+     * getters — that {@link toReactiveSnapshot} materializes onto snapshots.
+     * The dynamic model class built by `registerModelsFromSchema` overrides this;
+     * hand-written Model subclasses default to none.
+     */
+    getDerivedGetterNames() {
+        return EMPTY_DERIVED_GETTERS;
+    }
     /**
      * Get field changes for activity tracking
      */

package/dist/SyncClient.d.ts

@@ -15,6 +15,7 @@ import { type UnconfirmedWritesMetrics } from './transactions/UnconfirmedWrites.
 import type { Database } from './Database.js';
 import type { WriteOptions } from './interfaces/index.js';
 import { SyncPosition } from './sync/syncPosition.js';
+import { type CommitOutboxStore } from './transactions/commitOutboxStore.js';
 interface SyncObserver {
     onSync?: (event: SyncEvent) => void;
 }
@@ -44,11 +45,14 @@ export declare class SyncClient extends EventEmitter {
     private database;
     private get mutationExecutor();
     private networkMonitor;
-    private transactionQueue;
     private observers;
     private userId;
     private organizationId;
     private pendingMutations;
+    private readonly stagedMutationIds;
+    private pendingJournalBatch;
+    private journalFlushScheduled;
+    private readonly commitOutboxNamespace;
     /**
      * Tracks the ids of transactions the client has applied optimistically but
      * the server has not yet confirmed. When a delta arrives, the receive path
@@ -72,7 +76,7 @@ export declare class SyncClient extends EventEmitter {
      * responses, and snapshots and claims read `readFloor`.
      */
     readonly position: SyncPosition;
-    constructor(objectPool: InstanceCache, database: Database);
+    constructor(objectPool: InstanceCache, database: Database, commitOutbox?: CommitOutboxStore, commitOutboxNamespace?: string);
     /**
      * Setup network monitoring handlers
      */
@@ -250,12 +254,12 @@ export declare class SyncClient extends EventEmitter {
      *   avoid re-reading a model after pool operations that might clear them.
      */
     private queueMutation;
+    private scheduleJournalFlush;
+    private flushPendingMutationJournal;
     private syncScheduled;
     private scheduleSync;
-    /**
-     * Persist mutation queue to IndexedDB
-     */
-    private persistMutationQueue;
+    private pendingMutationRecord;
+    private persistPendingMutation;
     /**
      * Restore the mutation queue from IndexedDB.
      *