@syncular/client 0.10.0 → 0.12.0

package/README.md

@@ -117,6 +117,11 @@ the same SQLite transaction that drains their outbox commit. Conflict entries
 retain the losing operation plus `serverVersion`/`serverRow`; active failures
 restore after restart and are never removed by retention. Configure the
 history cap with `limits.outcomeRetentionMaxEntries` (default 1,000).
+Failed outcomes additionally retain the complete ordered local commit envelope
+as `outcome.operations`, so a domain recovery flow can reconstruct siblings
+that rolled back with the terminating operation. It stays in the protected
+client database and is never added to the wire protocol, preferences, or
+telemetry; successful and historical outcomes may omit it.
 
 Use `patch(table, rowId, partial, { baseVersion? })` for editor-style partial
 updates. The wire still carries a full row, but the durable local operation

package/dist/client.js

@@ -1154,6 +1154,7 @@ export class SyncClient {
                 status: 'rejected',
                 recordedAtMs: this.#now(),
                 results: [{ status: 'error', rejection }],
+                operations: commit.operations,
             });
             pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
             batch.status();
@@ -1806,6 +1807,7 @@ export class SyncClient {
                 : 'rejected',
             recordedAtMs: this.#now(),
             results: outcomeResults,
+            operations: commit.operations,
         });
         pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
         batch.outcomes();
@@ -2083,6 +2085,7 @@ export class SyncClient {
                                 status: 'rejected',
                                 recordedAtMs: this.#now(),
                                 results,
+                                operations: commit.operations,
                             });
                         }
                         pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);

package/dist/outcomes.d.ts

@@ -51,6 +51,12 @@ export interface CommitOutcome {
     readonly status: CommitOutcomeStatus;
     readonly recordedAtMs: number;
     readonly results: readonly CommitOperationOutcome[];
+    /**
+     * Complete local failed-commit envelope, retained after outbox drain so an
+     * authorized application can reconstruct atomic aggregate intent. Absent
+     * for successful and historical outcomes. Never sent over the wire.
+     */
+    readonly operations?: readonly OutboxOperation[];
     readonly resolution: CommitOutcomeResolution;
     readonly resolvedAtMs?: number;
     readonly replacementClientCommitId?: string;

package/dist/outcomes.js

@@ -41,6 +41,9 @@ function parseOutcome(row) {
         status: row.status,
         recordedAtMs: row.recorded_at_ms,
         results: decodeResults(row.results),
+        ...(typeof row.operations === 'string'
+            ? { operations: JSON.parse(row.operations) }
+            : {}),
         resolution: row.resolution,
         ...(typeof row.resolved_at_ms === 'number'
             ? { resolvedAtMs: row.resolved_at_ms }
@@ -52,17 +55,20 @@ function parseOutcome(row) {
 }
 export function recordCommitOutcome(db, outcome) {
     db.exec(`INSERT INTO _syncular_commit_outcomes(
-       client_commit_id, status, recorded_at_ms, results, resolution
-     ) VALUES (?, ?, ?, ?, 'active')`, [
+       client_commit_id, status, recorded_at_ms, results, operations, resolution
+     ) VALUES (?, ?, ?, ?, ?, 'active')`, [
         outcome.clientCommitId,
         outcome.status,
         outcome.recordedAtMs,
         encodeResults(outcome.results),
+        outcome.operations === undefined
+            ? null
+            : JSON.stringify(outcome.operations),
     ]);
     return commitOutcome(db, outcome.clientCommitId);
 }
 export function commitOutcome(db, clientCommitId) {
-    const row = db.query(`SELECT seq, client_commit_id, status, recorded_at_ms, results,
+    const row = db.query(`SELECT seq, client_commit_id, status, recorded_at_ms, results, operations,
             resolution, resolved_at_ms, replacement_client_commit_id
        FROM _syncular_commit_outcomes WHERE client_commit_id = ?`, [clientCommitId])[0];
     return row === undefined ? undefined : parseOutcome(row);
@@ -75,7 +81,7 @@ export function listCommitOutcomes(db, query = {}) {
     const where = query.activeOnly
         ? "WHERE resolution = 'active' AND status IN ('conflict', 'rejected')"
         : '';
-    const rows = db.query(`SELECT seq, client_commit_id, status, recorded_at_ms, results,
+    const rows = db.query(`SELECT seq, client_commit_id, status, recorded_at_ms, results, operations,
             resolution, resolved_at_ms, replacement_client_commit_id
        FROM _syncular_commit_outcomes ${where}
       ORDER BY seq DESC${limit === undefined ? '' : ' LIMIT ?'}`, limit === undefined ? [] : [limit]);

package/dist/schema.js

@@ -190,10 +190,19 @@ export function ensureLocalSchema(db, schema) {
       status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
       recorded_at_ms INTEGER NOT NULL,
       results TEXT NOT NULL,
+      operations TEXT,
       resolution TEXT NOT NULL DEFAULT 'active'
         CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
       resolved_at_ms INTEGER,
       replacement_client_commit_id TEXT)`);
+        // Outcomes created before durable aggregate recovery retain no commit
+        // envelope. New failed outcomes store it in the protected client DB.
+        try {
+            db.exec('ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations TEXT');
+        }
+        catch {
+            // column already exists — the CREATE above included it
+        }
         db.exec(`CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
       ON _syncular_commit_outcomes(resolution, seq)`);
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_subscriptions(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.10.0"
+    "@syncular/core": "0.12.0"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.10.0",
+    "@syncular/server": "0.12.0",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -1737,6 +1737,7 @@ export class SyncClient {
         status: 'rejected',
         recordedAtMs: this.#now(),
         results: [{ status: 'error', rejection }],
+        operations: commit.operations,
       });
       pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
       batch.status();
@@ -2543,6 +2544,7 @@ export class SyncClient {
         : 'rejected',
       recordedAtMs: this.#now(),
       results: outcomeResults,
+      operations: commit.operations,
     });
     pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
     batch.outcomes();
@@ -2900,6 +2902,7 @@ export class SyncClient {
                 status: 'rejected',
                 recordedAtMs: this.#now(),
                 results,
+                operations: commit.operations,
               });
             }
             pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);

package/src/outcomes.ts

@@ -70,6 +70,12 @@ export interface CommitOutcome {
   readonly status: CommitOutcomeStatus;
   readonly recordedAtMs: number;
   readonly results: readonly CommitOperationOutcome[];
+  /**
+   * Complete local failed-commit envelope, retained after outbox drain so an
+   * authorized application can reconstruct atomic aggregate intent. Absent
+   * for successful and historical outcomes. Never sent over the wire.
+   */
+  readonly operations?: readonly OutboxOperation[];
   readonly resolution: CommitOutcomeResolution;
   readonly resolvedAtMs?: number;
   readonly replacementClientCommitId?: string;
@@ -142,6 +148,9 @@ function parseOutcome(row: Readonly<Record<string, unknown>>): CommitOutcome {
     status: row.status as CommitOutcomeStatus,
     recordedAtMs: row.recorded_at_ms as number,
     results: decodeResults(row.results as string),
+    ...(typeof row.operations === 'string'
+      ? { operations: JSON.parse(row.operations) as OutboxOperation[] }
+      : {}),
     resolution: row.resolution as CommitOutcomeResolution,
     ...(typeof row.resolved_at_ms === 'number'
       ? { resolvedAtMs: row.resolved_at_ms }
@@ -158,13 +167,16 @@ export function recordCommitOutcome(
 ): CommitOutcome {
   db.exec(
     `INSERT INTO _syncular_commit_outcomes(
-       client_commit_id, status, recorded_at_ms, results, resolution
-     ) VALUES (?, ?, ?, ?, 'active')`,
+       client_commit_id, status, recorded_at_ms, results, operations, resolution
+     ) VALUES (?, ?, ?, ?, ?, 'active')`,
     [
       outcome.clientCommitId,
       outcome.status,
       outcome.recordedAtMs,
       encodeResults(outcome.results),
+      outcome.operations === undefined
+        ? null
+        : JSON.stringify(outcome.operations),
     ],
   );
   return commitOutcome(db, outcome.clientCommitId) as CommitOutcome;
@@ -175,7 +187,7 @@ export function commitOutcome(
   clientCommitId: string,
 ): CommitOutcome | undefined {
   const row = db.query(
-    `SELECT seq, client_commit_id, status, recorded_at_ms, results,
+    `SELECT seq, client_commit_id, status, recorded_at_ms, results, operations,
             resolution, resolved_at_ms, replacement_client_commit_id
        FROM _syncular_commit_outcomes WHERE client_commit_id = ?`,
     [clientCommitId],
@@ -198,7 +210,7 @@ export function listCommitOutcomes(
     ? "WHERE resolution = 'active' AND status IN ('conflict', 'rejected')"
     : '';
   const rows = db.query(
-    `SELECT seq, client_commit_id, status, recorded_at_ms, results,
+    `SELECT seq, client_commit_id, status, recorded_at_ms, results, operations,
             resolution, resolved_at_ms, replacement_client_commit_id
        FROM _syncular_commit_outcomes ${where}
       ORDER BY seq DESC${limit === undefined ? '' : ' LIMIT ?'}`,

package/src/schema.ts

@@ -294,10 +294,20 @@ export function ensureLocalSchema(
       status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
       recorded_at_ms INTEGER NOT NULL,
       results TEXT NOT NULL,
+      operations TEXT,
       resolution TEXT NOT NULL DEFAULT 'active'
         CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
       resolved_at_ms INTEGER,
       replacement_client_commit_id TEXT)`);
+    // Outcomes created before durable aggregate recovery retain no commit
+    // envelope. New failed outcomes store it in the protected client DB.
+    try {
+      db.exec(
+        'ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations TEXT',
+      );
+    } catch {
+      // column already exists — the CREATE above included it
+    }
     db.exec(`CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
       ON _syncular_commit_outcomes(resolution, seq)`);
     db.exec(`CREATE TABLE IF NOT EXISTS _syncular_subscriptions(