@syncular/client 0.30.16 → 0.32.0

package/dist/outcomes.js

@@ -1,8 +1,17 @@
 export const OUTCOMES_TABLE = '_syncular_commit_outcomes';
 const SELECT_OUTCOME = `SELECT * FROM ${OUTCOMES_TABLE}`;
 import { RETAINED_ROWS } from './failed-overlay.js';
+/**
+ * Durable per-client commit outcomes.
+ *
+ * The journal is client-local protected database state. A final push result is
+ * written in the same SQLite transaction that drains its outbox commit, so a
+ * restart can never turn "rejected" into an inferred success. Conflict payloads
+ * deliberately stay local; retention never deletes an unresolved failure.
+ */
+import { normalizeRejectionDetails, } from '@syncular/core';
 import { ClientSyncError } from './errors.js';
-import { mapRowValues, jsonToRowValue, rowValueToJson, } from './schema.js';
+import { isBytesEnvelope, mapRowValues, jsonToRowValue, rowValueToJson, } from './schema.js';
 function encodeResults(results) {
     const stored = results.map((result) => {
         if (result.status !== 'conflict')
@@ -17,45 +26,132 @@ function encodeResults(results) {
     });
     return JSON.stringify(stored);
 }
+/** A JSON object that is neither null nor an array. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStoredRow(value) {
+    return (isRecord(value) &&
+        Object.values(value).every((cell) => cell === null ||
+            typeof cell === 'string' ||
+            typeof cell === 'boolean' ||
+            (typeof cell === 'number' && Number.isFinite(cell)) ||
+            isBytesEnvelope(cell)));
+}
+export function isStoredOperation(value) {
+    return (isRecord(value) &&
+        typeof value.table === 'string' &&
+        typeof value.rowId === 'string' &&
+        (value.baseVersion === undefined ||
+            Number.isSafeInteger(value.baseVersion)) &&
+        ((value.op === 'upsert' && isStoredRow(value.values)) ||
+            (value.op === 'delete' && value.values === undefined)));
+}
 function decodeResults(raw) {
+    function corrupt() {
+        throw new ClientSyncError('sync.local_corrupt', 'persisted commit outcome is invalid');
+    }
     const stored = JSON.parse(raw);
+    if (!Array.isArray(stored))
+        corrupt();
     return stored.map((result) => {
-        if (result.status !== 'conflict')
+        if (!isRecord(result))
+            corrupt();
+        if (result.status === 'applied') {
+            if (!Number.isInteger(result.opIndex) ||
+                result.opIndex < -2147483648 ||
+                result.opIndex > 2147483647)
+                corrupt();
             return result;
-        return {
-            status: 'conflict',
-            conflict: {
-                ...result.conflict,
-                // Pre-column-version journal entries carry no conflictColumns.
-                conflictColumns: result.conflict.conflictColumns ?? [],
-                serverRow: mapRowValues(result.conflict.serverRow, jsonToRowValue),
-            },
-        };
+        }
+        if (result.status === 'conflict') {
+            const conflict = result.conflict;
+            if (!isRecord(conflict) ||
+                !isStoredRow(conflict.serverRow) ||
+                typeof conflict.clientCommitId !== 'string' ||
+                !Number.isInteger(conflict.opIndex) ||
+                conflict.opIndex < -2147483648 ||
+                conflict.opIndex > 2147483647 ||
+                typeof conflict.table !== 'string' ||
+                typeof conflict.rowId !== 'string' ||
+                typeof conflict.code !== 'string' ||
+                typeof conflict.message !== 'string' ||
+                (conflict.operation !== undefined &&
+                    !isStoredOperation(conflict.operation)) ||
+                !Number.isSafeInteger(conflict.serverVersion) ||
+                (conflict.conflictColumns !== undefined &&
+                    (!Array.isArray(conflict.conflictColumns) ||
+                        !conflict.conflictColumns.every((column) => typeof column === 'string')))) {
+                corrupt();
+            }
+            return {
+                status: 'conflict',
+                conflict: {
+                    ...conflict,
+                    // Pre-column-version journal entries carry no conflictColumns.
+                    conflictColumns: conflict.conflictColumns ?? [],
+                    serverRow: mapRowValues(conflict.serverRow, jsonToRowValue),
+                },
+            };
+        }
+        if (result.status === 'error') {
+            const rejection = result.rejection;
+            if (!isRecord(rejection) ||
+                typeof rejection.clientCommitId !== 'string' ||
+                !Number.isInteger(rejection.opIndex) ||
+                rejection.opIndex < -2147483648 ||
+                rejection.opIndex > 2147483647 ||
+                typeof rejection.code !== 'string' ||
+                typeof rejection.message !== 'string' ||
+                typeof rejection.retryable !== 'boolean' ||
+                (rejection.operation !== undefined &&
+                    !isStoredOperation(rejection.operation))) {
+                corrupt();
+            }
+            try {
+                const { details, ...fields } = rejection;
+                return {
+                    status: 'error',
+                    rejection: {
+                        ...fields,
+                        ...(details == null
+                            ? {}
+                            : { details: normalizeRejectionDetails(details) }),
+                    },
+                };
+            }
+            catch {
+                corrupt();
+            }
+        }
+        corrupt();
     });
 }
-function parseOutcome(db, row) {
-    const retainedRows = db
-        .query(`SELECT tbl,id,intent,base,version,unique_conflicts FROM ${RETAINED_ROWS} WHERE commit_seq IS NULL AND commit_id=? ORDER BY idx`, [row.client_commit_id])
-        .map((retained) => {
-        const decode = (value) => value === null
-            ? null
-            : Object.fromEntries(Object.entries(JSON.parse(String(value))).map(([key, value]) => [key, jsonToRowValue(value)]));
-        return {
-            table: retained.tbl,
-            rowId: retained.id,
-            localRow: decode(retained.intent),
-            ...(retained.unique_conflicts === null
-                ? {}
-                : {
-                    uniqueConflicts: JSON.parse(retained.unique_conflicts).map((conflict) => ({
-                        ...conflict,
-                        serverRow: decode(JSON.stringify(conflict.serverRow)),
-                    })),
-                }),
-            serverRow: decode(retained.base),
-            serverVersion: retained.version === null ? null : retained.version,
-        };
-    });
+function parseOutcome(db, row, attachRetainedRows = true) {
+    const retainedRows = attachRetainedRows
+        ? db
+            .query(`SELECT tbl,id,intent,base,version,unique_conflicts FROM ${RETAINED_ROWS} WHERE commit_seq IS NULL AND commit_id=? ORDER BY idx`, [row.client_commit_id])
+            .map((retained) => {
+            const decode = (value) => value === null
+                ? null
+                : Object.fromEntries(Object.entries(JSON.parse(String(value))).map(([key, value]) => [key, jsonToRowValue(value)]));
+            return {
+                table: retained.tbl,
+                rowId: retained.id,
+                localRow: decode(retained.intent),
+                ...(retained.unique_conflicts === null
+                    ? {}
+                    : {
+                        uniqueConflicts: JSON.parse(retained.unique_conflicts).map((conflict) => ({
+                            ...conflict,
+                            serverRow: decode(JSON.stringify(conflict.serverRow)),
+                        })),
+                    }),
+                serverRow: decode(retained.base),
+                serverVersion: retained.version === null ? null : retained.version,
+            };
+        })
+        : [];
     return {
         sequence: row.seq,
         clientCommitId: row.client_commit_id,
@@ -93,6 +189,62 @@ export function commitOutcome(db, clientCommitId) {
     ])[0];
     return row === undefined ? undefined : parseOutcome(db, row);
 }
+/**
+ * §7.5 persisted-journal view: the stored outcome WITHOUT the owner-derived
+ * `retainedRows` images. A malformed journal row (invalid status, resolution,
+ * results, or operations JSON) raises the same static `sync.local_corrupt` the
+ * native sidecar reports, never a raw `SyntaxError`.
+ */
+export function persistedCommitOutcome(db, clientCommitId) {
+    const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
+        clientCommitId,
+    ])[0];
+    if (row === undefined)
+        return undefined;
+    function corrupt() {
+        throw new ClientSyncError('sync.local_corrupt', 'persisted commit outcome is invalid');
+    }
+    const status = row.status;
+    const resolution = row.resolution;
+    if ((status !== 'applied' &&
+        status !== 'cached' &&
+        status !== 'conflict' &&
+        status !== 'rejected') ||
+        (resolution !== 'active' &&
+            resolution !== 'resolved_keep_server' &&
+            resolution !== 'superseded' &&
+            resolution !== 'dismissed') ||
+        !Number.isSafeInteger(row.seq) ||
+        typeof row.client_commit_id !== 'string' ||
+        !Number.isSafeInteger(row.recorded_at_ms) ||
+        typeof row.results !== 'string' ||
+        (row.operations !== null && typeof row.operations !== 'string') ||
+        (row.resolved_at_ms !== null &&
+            !Number.isSafeInteger(row.resolved_at_ms)) ||
+        (row.replacement_client_commit_id !== null &&
+            typeof row.replacement_client_commit_id !== 'string')) {
+        corrupt();
+    }
+    try {
+        const outcome = parseOutcome(db, row, false);
+        const hasConflict = outcome.results.some((result) => result.status === 'conflict');
+        const hasError = outcome.results.some((result) => result.status === 'error');
+        const redacted = outcome.results.length === 0 && outcome.operations === undefined;
+        if (((status === 'applied' || status === 'cached') &&
+            (hasConflict || hasError)) ||
+            (status === 'conflict' && !(hasConflict || redacted)) ||
+            (status === 'rejected' && (hasConflict || !(hasError || redacted))))
+            corrupt();
+        if (outcome.operations !== undefined &&
+            (!Array.isArray(outcome.operations) ||
+                !outcome.operations.every(isStoredOperation)))
+            corrupt();
+        return outcome;
+    }
+    catch {
+        corrupt();
+    }
+}
 export function listCommitOutcomes(db, query = {}) {
     const limit = query.limit;
     if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1)) {

package/dist/schema.d.ts

@@ -159,6 +159,14 @@ export declare function recordToRowValues(table: CompiledClientTable, record: Re
 export type JsonRowValue = string | number | boolean | null | {
     readonly $bytes: string;
 };
+/**
+ * The canonical §7.1 byte envelope: exactly one `$bytes` key holding a string
+ * of hexadecimal digit pairs. Uppercase digits are accepted; encoders emit
+ * lowercase. A malformed envelope is a caller error, never a value to coerce.
+ */
+export declare function isBytesEnvelope(value: unknown): value is {
+    readonly $bytes: string;
+};
 export declare function hexToBytes(hex: string): Uint8Array;
 export declare function rowValueToJson(value: RowValue): JsonRowValue;
 export declare function jsonToRowValue(value: JsonRowValue): RowValue;

package/dist/schema.js

@@ -20,6 +20,15 @@ function invalidSchema(message) {
     throw new Error(message);
 }
 export function compileClientSchema(schema) {
+    // §7.4.2: the persisted marker is a canonical positive i32 and a replica
+    // refuses any requested version outside that range before it touches
+    // storage, so a client can never persist a marker it would reject on the
+    // next open.
+    if (!Number.isInteger(schema.version) ||
+        schema.version < 1 ||
+        schema.version > 2147483647) {
+        throw invalidRequest('generated schema version must be an integer in 1..=2147483647');
+    }
     const tables = new Map();
     const schemaObjectNames = new Set();
     for (const table of schema.tables) {
@@ -496,7 +505,13 @@ export function coerceSqlRepresentation(column, value) {
     switch (localColumnType(column)) {
         case 'boolean':
             return value === 0 ? false : value === 1 ? true : value;
-        case 'integer':
+        case 'integer': {
+            const integer = typeof value === 'bigint' ? Number(value) : value;
+            if (typeof integer === 'number' && !Number.isSafeInteger(integer)) {
+                throw invalidRequest('integer value is outside the safe-integer range');
+            }
+            return integer;
+        }
         case 'float':
             return typeof value === 'bigint' ? Number(value) : value;
         default:
@@ -527,6 +542,19 @@ function bytesToHex(bytes) {
         out += byte.toString(16).padStart(2, '0');
     return out;
 }
+/**
+ * The canonical §7.1 byte envelope: exactly one `$bytes` key holding a string
+ * of hexadecimal digit pairs. Uppercase digits are accepted; encoders emit
+ * lowercase. A malformed envelope is a caller error, never a value to coerce.
+ */
+export function isBytesEnvelope(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return (Object.keys(record).length === 1 &&
+        typeof record.$bytes === 'string' &&
+        /^(?:[0-9a-fA-F]{2})*$/.test(record.$bytes));
+}
 export function hexToBytes(hex) {
     const out = new Uint8Array(hex.length / 2);
     for (let i = 0; i < out.length; i++) {
@@ -541,6 +569,8 @@ export function rowValueToJson(value) {
 }
 export function jsonToRowValue(value) {
     if (typeof value === 'object' && value !== null) {
+        if (!isBytesEnvelope(value))
+            throw invalidRequest('an object value must be one $bytes key holding an even-length hexadecimal string');
         return hexToBytes(value.$bytes);
     }
     return value;

package/dist/state.js

@@ -2,6 +2,7 @@ export const META_TABLE = '_syncular_meta';
 import { PENDING_EVICTIONS } from './window.js';
 import { WINDOWS_TABLE } from './window.js';
 export const SUBSCRIPTIONS_TABLE = '_syncular_subscriptions';
+import { ClientSyncError } from './errors.js';
 export const LOCAL_REVISION_KEY = 'localRevision';
 const MAX_U64 = 18446744073709551615n;
 function rowToRecord(row) {
@@ -145,12 +146,12 @@ export function getLocalRevision(db) {
     const raw = getMeta(db, LOCAL_REVISION_KEY);
     if (raw === undefined)
         return 0n;
-    if (!/^(0|[1-9][0-9]*)$/.test(raw)) {
-        throw new Error(`invalid persisted local revision ${JSON.stringify(raw)}`);
+    if (typeof raw !== 'string' || !/^(0|[1-9][0-9]*)$/.test(raw)) {
+        throw new ClientSyncError('sync.local_corrupt', 'persisted local revision is invalid');
     }
     const revision = BigInt(raw);
     if (revision > MAX_U64) {
-        throw new Error(`persisted local revision exceeds u64: ${raw}`);
+        throw new ClientSyncError('sync.local_corrupt', 'persisted local revision is invalid');
     }
     return revision;
 }
@@ -161,7 +162,7 @@ export function getLocalRevision(db) {
 export function bumpLocalRevision(db) {
     const current = getLocalRevision(db);
     if (current === MAX_U64) {
-        throw new Error('local revision exhausted u64');
+        throw new ClientSyncError('sync.local_corrupt', 'local revision exhausted u64');
     }
     const next = current + 1n;
     setMeta(db, LOCAL_REVISION_KEY, next.toString());

package/dist/sync-scheduler.js

@@ -55,6 +55,14 @@ export function installSyncScheduler(client, options = {}) {
         backgroundReady = false;
         void client
             .syncUntilIdle(options.maxRounds)
+            .then((result) => {
+            if (result !== null &&
+                typeof result === 'object' &&
+                'budgetExhausted' in result &&
+                result.budgetExhausted === true) {
+                queueImmediate();
+            }
+        })
             .catch((error) => {
             if (!stopped)
                 report(error);

package/dist/worker-entry.js

@@ -88,6 +88,8 @@ export function startSyncWorker(overrides = {}) {
             .then((summary) => {
             if (!closed)
                 post({ t: 'event', event: { kind: 'synced', summary } });
+            if (summary.budgetExhausted)
+                consumeSyncIntent({ kind: 'interactive' });
         })
             .catch((error) => {
             if (!closed) {
@@ -302,6 +304,7 @@ export function startSyncWorker(overrides = {}) {
         'query',
         'authoritySnapshot',
         'querySnapshot',
+        'snapshotRead',
         'statusSnapshot',
         'conflicts',
         'rejections',

package/dist/worker-host.d.ts

@@ -25,7 +25,7 @@ import type { PromiseMethods } from './client.js';
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleResult, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
@@ -244,10 +244,11 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
         discarded: boolean;
     }>;
     sync(): Promise<SyncSummary>;
-    syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
+    syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
     authoritySnapshot(): Promise<import('./authority.js').AuthoritySnapshot>;
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
+    snapshotRead<Row = SqlRow>(spec: SnapshotReadRequest): Promise<SnapshotRead<Row>>;
     localRevision(): Promise<LocalRevision>;
     statusSnapshot(): Promise<SyncStatusSnapshot>;
     diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;

package/dist/worker-host.js

@@ -340,6 +340,9 @@ export class SyncClientHandle {
     querySnapshot(spec) {
         return this.#call('querySnapshot', [spec]);
     }
+    snapshotRead(spec) {
+        return this.#call('snapshotRead', [spec]);
+    }
     localRevision() {
         return this.#call('localRevision', []);
     }

package/dist/worker-protocol.d.ts

@@ -19,7 +19,7 @@ import type { SyncProgress } from './progress.js';
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleResult, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import type { ClientDiagnosticsSnapshot, RealtimePolicy } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
@@ -137,7 +137,7 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
         discarded: boolean;
     };
     sync(): Promise<SyncSummary>;
-    syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
+    syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     authoritySnapshot(): import('./authority.js').AuthoritySnapshot;
     querySnapshot(spec: QueryReadSpec): QuerySnapshot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.30.16",
+  "version": "0.32.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -97,10 +97,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.30.16"
+    "@syncular/core": "0.32.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.30.16",
+    "@syncular/server": "0.32.0",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }