@syncular/client 0.30.16 → 0.31.0

package/dist/diagnostics.d.ts

@@ -113,7 +113,7 @@ export interface DiagnosticQueryFailure {
     readonly id: string;
     /** Distinct generated table names the query depends on, ascending. */
     readonly tables: readonly string[];
-    readonly code: 'client.storage_corrupt' | 'client.storage_full' | 'client.storage_io' | 'client.query_failed';
+    readonly code: 'client.storage_corrupt' | 'client.storage_full' | 'client.storage_io' | 'client.storage_busy' | 'sync.local_corrupt' | 'client.query_failed';
     /** SQLite extended result code, when the driver exposed one. */
     readonly sqliteCode?: number;
     /** First failure since this id's last successful read. */

package/dist/errors.d.ts

@@ -65,6 +65,6 @@ export declare class RealtimeUnavailableError extends ClientSyncError {
  */
 export declare function classifySqliteFailure(error: unknown): {
     readonly sqliteCode: number | undefined;
-    readonly code: typeof STORAGE_CORRUPT_CODE | typeof STORAGE_FULL_CODE | typeof STORAGE_IO_CODE | undefined;
+    readonly code: typeof STORAGE_CORRUPT_CODE | typeof STORAGE_FULL_CODE | typeof STORAGE_IO_CODE | typeof STORAGE_BUSY_CODE | undefined;
     readonly error: unknown;
 };

package/dist/errors.js

@@ -98,7 +98,8 @@ export function classifySqliteFailure(error) {
             sqliteCode: typeof sqliteCode === 'number' ? sqliteCode : undefined,
             code: error.code === STORAGE_FULL_CODE ||
                 error.code === STORAGE_IO_CODE ||
-                error.code === STORAGE_CORRUPT_CODE
+                error.code === STORAGE_CORRUPT_CODE ||
+                error.code === STORAGE_BUSY_CODE
                 ? error.code
                 : undefined,
             error: retained,
@@ -124,7 +125,9 @@ export function classifySqliteFailure(error) {
             ? STORAGE_IO_CODE
             : primary === 11 || primary === 26
                 ? STORAGE_CORRUPT_CODE
-                : undefined;
+                : primary === 5 || primary === 6
+                    ? STORAGE_BUSY_CODE
+                    : undefined;
     if (code === undefined)
         return { sqliteCode, code, error };
     const rollback = error instanceof Error && 'rollbackError' in error
@@ -134,7 +137,9 @@ export function classifySqliteFailure(error) {
         ? 'local SQLite storage is full'
         : primary === 10
             ? 'local SQLite storage I/O failed'
-            : 'local SQLite storage is corrupt', false, {
+            : code === STORAGE_BUSY_CODE
+                ? 'local SQLite storage is busy'
+                : 'local SQLite storage is corrupt', code === STORAGE_BUSY_CODE, {
         sqliteCode,
         sqliteMessage: error instanceof Error ? error.message : String(error),
         ...(rollback !== undefined

package/dist/failed-overlay.js

@@ -96,12 +96,6 @@ export function overlayScopePredicate(table, id) {
 function retainedRows(db, scope, acknowledged) {
     return db.query(`SELECT * FROM ${RETAINED_ROWS} WHERE (${overlayScopePredicate('tbl', 'id')})${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`, [scope ? JSON.stringify(scope) : null]);
 }
-function retainedTable(schema, name) {
-    const table = schema.tables.get(name);
-    if (!table)
-        throw new ClientSyncError('sync.unknown_table', 'retained table is unknown');
-    return table;
-}
 export function restoreFailedBases(db, schema, scope) {
     const seen = new Set();
     for (const row of retainedRows(db, scope)) {
@@ -109,7 +103,12 @@ export function restoreFailedBases(db, schema, scope) {
         if (seen.has(key))
             continue;
         seen.add(key);
-        const table = retainedTable(schema, row.tbl);
+        // §7.4.4: a retained row whose table the current schema removed has no
+        // mirror to project; its persisted intent and outcome stay available, only
+        // this projection is skipped.
+        const table = schema.tables.get(row.tbl);
+        if (table === undefined)
+            continue;
         if (row.base === null)
             deleteLocalRow(db, table, row.id, false);
         else {
@@ -125,7 +124,12 @@ export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
         const id = row.commit_id;
         let operation = JSON.parse(row.op);
         if (schema && operation.op === 'upsert') {
-            const table = retainedTable(schema, operation.table);
+            // §7.4.4: the table this retained row belongs to is gone; the persisted
+            // outcome and intent stay available, only the removed-table projection is
+            // skipped.
+            const table = schema.tables.get(operation.table);
+            if (table === undefined)
+                continue;
             if (acknowledged) {
                 if (!db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [operation.rowId]).length)
                     operation = {

package/dist/http.d.ts

@@ -1,8 +1,8 @@
 /**
  * Browser transport bindings (§1.1, §5.4/§5.5, §8.1): fetch-based sync
- * transport, segment download with signed-URL preference and direct-serve
- * fallback, and a WebSocket realtime connector. Core tests never use these
- * (the loopback doctrine); the browser fixture exercises them in a real browser.
+ * transport, descriptor-selected signed-URL or direct segment delivery, and
+ * WebSocket realtime connectors. Adapter tests inject fetch and socket surfaces;
+ * protocol core conformance uses loopback.
  */
 import type { BlobTransport } from './blob.js';
 import type { RealtimeConnector, RemoteOperationTransport, RemoteOperationRealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';

package/dist/http.js

@@ -1,23 +1,50 @@
 import { SSP2_CONTENT_TYPE } from './content-type.js';
 import { ClientSyncError } from './errors.js';
-async function throwHttpError(response, details) {
-    let code = 'sync.transport_failed';
+async function transfer(message, operation, httpStatus) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        // Classify only known exception kinds. Injected errors, including
+        // ClientSyncError, are untrusted and never become the returned cause.
+        const causeKind = error instanceof DOMException && error.name === 'TimeoutError'
+            ? 'timeout'
+            : error instanceof DOMException && error.name === 'AbortError'
+                ? 'aborted'
+                : httpStatus !== undefined
+                    ? 'body'
+                    : error instanceof TypeError
+                        ? 'network'
+                        : 'unknown';
+        throw new ClientSyncError('sync.transport_failed', message, true, {
+            causeKind,
+            ...(httpStatus !== undefined ? { httpStatus } : {}),
+        });
+    }
+}
+async function throwHttpError(response, defaultCode = 'sync.transport_failed') {
+    let code = defaultCode;
     let message = 'HTTP request failed';
-    let retryable = response.status >= 500 || response.status === 429;
+    let retryable = response.status >= 500 ||
+        response.status === 429 ||
+        defaultCode === 'sync.auth_required';
     try {
         const body = (await response.json());
-        if (typeof body.code === 'string')
-            code = body.code;
-        if (typeof body.message === 'string')
-            message = body.message;
-        if (typeof body.retryable === 'boolean')
-            retryable = body.retryable;
+        // Only the blob download endpoint can establish absence.
+        if (body.code !== 'blob.not_found' || defaultCode === 'blob.not_found') {
+            if (typeof body.code === 'string')
+                code = body.code;
+            if (typeof body.message === 'string')
+                message = body.message;
+            if (typeof body.retryable === 'boolean')
+                retryable = body.retryable;
+        }
     }
     catch {
         // non-JSON error body — keep the HTTP-status defaults
     }
     throw new ClientSyncError(code, message, retryable, {
-        ...details,
+        causeKind: 'status',
         httpStatus: response.status,
     });
 }
@@ -29,47 +56,57 @@ function hostHeaders(options) {
 export function httpSyncTransport(syncUrl, options) {
     const doFetch = options?.fetch ?? fetch;
     return async (request) => {
-        const response = await doFetch(syncUrl, {
+        const response = await transfer('sync request failed', () => doFetch(syncUrl, {
             method: 'POST',
             headers: {
                 'Content-Type': SSP2_CONTENT_TYPE,
                 ...hostHeaders(options),
             },
             body: request.slice().buffer,
-        });
+        }));
         if (!response.ok)
             await throwHttpError(response);
-        return new Uint8Array(await response.arrayBuffer());
+        return new Uint8Array(await transfer('response body read failed', () => response.arrayBuffer(), response.status));
     };
 }
 /** POST one registered authoritative operation to `<mount>/operations`. */
 export function httpRemoteOperationTransport(operationsUrl, options) {
     const doFetch = options?.fetch ?? fetch;
     return async (request) => {
-        const response = await doFetch(operationsUrl, {
+        const response = await transfer('remote operation request failed', () => doFetch(operationsUrl, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/vnd.syncular.operations.v1+json',
                 ...hostHeaders(options),
             },
             body: request.slice().buffer,
-        });
+        }));
         if (!response.ok)
             await throwHttpError(response);
-        return new Uint8Array(await response.arrayBuffer());
+        return new Uint8Array(await transfer('response body read failed', () => response.arrayBuffer(), response.status));
     };
 }
+function socketOperation(message, operation) {
+    try {
+        return operation();
+    }
+    catch {
+        throw new ClientSyncError('sync.transport_failed', message, true, {
+            causeKind: 'unknown',
+        });
+    }
+}
 /** WebSocket connector for registered query snapshots. */
 export function webSocketRemoteOperationConnector(realtimeUrl) {
     return (handlers) => new Promise((resolve, reject) => {
-        const socket = new WebSocket(realtimeUrl);
+        const socket = socketOperation('realtime socket failed to connect', () => new WebSocket(realtimeUrl));
         let opened = false;
         socket.binaryType = 'arraybuffer';
         socket.onopen = () => {
             opened = true;
             resolve({
-                send: (bytes) => socket.send(bytes.slice().buffer),
-                close: () => socket.close(),
+                send: (bytes) => socketOperation('realtime send failed', () => socket.send(bytes.slice().buffer)),
+                close: () => socketOperation('realtime close failed', () => socket.close()),
             });
         };
         socket.onmessage = (event) => {
@@ -140,29 +177,13 @@ async function readSegmentBody(response, onProgress) {
 export function httpSegmentDownloader(segmentsBaseUrl, options) {
     const doFetch = options?.fetch ?? fetch;
     const download = async (url, init, onProgress, signed = false) => {
-        // A capability's query/fragment and URL credentials never enter details.
-        const path = URL.canParse(url)
-            ? new URL(url).pathname
-            : url.split(/[?#]/)[0];
-        let response;
-        try {
-            response = await doFetch(url, init);
-            if (!response.ok) {
-                if (!signed)
-                    await throwHttpError(response, { path });
-                throw new ClientSyncError('sync.transport_failed', 'signed segment request failed; invalidate the descriptor and re-pull', true, { path, httpStatus: response.status });
-            }
-            return await readSegmentBody(response, onProgress);
-        }
-        catch (error) {
-            if (error instanceof ClientSyncError)
-                throw error;
-            throw new ClientSyncError('sync.transport_failed', 'segment transfer failed', true, {
-                path,
-                ...(response !== undefined ? { httpStatus: response.status } : {}),
-                causeMessage: error instanceof Error ? error.message : String(error),
-            });
+        const response = await transfer('segment transfer failed', () => doFetch(url, init));
+        if (!response.ok) {
+            if (!signed)
+                await throwHttpError(response);
+            throw new ClientSyncError('sync.transport_failed', 'signed segment request failed; invalidate the descriptor and re-pull', true, { causeKind: 'status', httpStatus: response.status });
         }
+        return transfer('segment transfer failed', () => readSegmentBody(response, onProgress), response.status);
     };
     const direct = (request) => download(`${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`, {
         headers: {
@@ -185,28 +206,34 @@ export function httpBlobTransport(blobsBaseUrl, options) {
     const blobUrl = (blobId) => `${blobsBaseUrl}/${encodeURIComponent(blobId)}`;
     return {
         upload: async (blobId, bytes, mediaType) => {
-            const response = await doFetch(blobUrl(blobId), {
+            const response = await transfer('blob upload failed', () => doFetch(blobUrl(blobId), {
                 method: 'PUT',
                 headers: {
                     'Content-Type': mediaType ?? 'application/octet-stream',
                     ...hostHeaders(options),
                 },
                 body: bytes.slice().buffer,
-            });
+            }));
             if (!response.ok)
                 await throwHttpError(response);
         },
         download: async (blobId) => {
-            const response = await doFetch(blobUrl(blobId), {
+            const response = await transfer('blob download failed', () => doFetch(blobUrl(blobId), {
                 headers: { ...hostHeaders(options) },
-            });
+            }));
             if (!response.ok)
-                await throwHttpError(response);
+                await throwHttpError(response, response.status === 404
+                    ? 'blob.not_found'
+                    : response.status === 403
+                        ? 'blob.forbidden'
+                        : response.status === 401
+                            ? 'sync.auth_required'
+                            : 'sync.transport_failed');
             // §5.9.5 always-issue: a JSON body with `url` means presigned delivery;
             // an octet-stream body is inline bytes.
             const contentType = response.headers.get('content-type') ?? '';
             if (contentType.includes('application/json')) {
-                const body = (await response.json());
+                const body = (await transfer('blob download body read failed', () => response.json(), response.status));
                 if (typeof body.url === 'string') {
                     return {
                         kind: 'url',
@@ -219,20 +246,20 @@ export function httpBlobTransport(blobsBaseUrl, options) {
             }
             return {
                 kind: 'bytes',
-                bytes: new Uint8Array(await response.arrayBuffer()),
+                bytes: new Uint8Array(await transfer('blob download body read failed', () => response.arrayBuffer(), response.status)),
             };
         },
         // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
         fetchUrl: async (url) => {
-            const response = await doFetch(url);
+            const response = await transfer('signed blob download failed', () => doFetch(url));
             if (!response.ok) {
-                throw new ClientSyncError('sync.transport_failed', `blob signed-URL fetch failed with HTTP ${response.status} (§5.9.5: re-request to recover)`, true);
+                throw new ClientSyncError('sync.transport_failed', 'signed blob download failed; re-request to recover', true, { causeKind: 'status', httpStatus: response.status });
             }
-            return new Uint8Array(await response.arrayBuffer());
+            return new Uint8Array(await transfer('response body read failed', () => response.arrayBuffer(), response.status));
         },
         // §5.9.3: presigned-upload grant.
         uploadGrant: async (blobId, byteLength, mediaType) => {
-            const response = await doFetch(`${blobUrl(blobId)}/upload-grant`, {
+            const response = await transfer('blob upload grant request failed', () => doFetch(`${blobUrl(blobId)}/upload-grant`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
@@ -242,10 +269,10 @@ export function httpBlobTransport(blobsBaseUrl, options) {
                     byteLength,
                     ...(mediaType !== undefined ? { mediaType } : {}),
                 }),
-            });
+            }));
             if (!response.ok)
                 await throwHttpError(response);
-            const body = (await response.json());
+            const body = (await transfer('blob upload grant body read failed', () => response.json(), response.status));
             if (typeof body.url === 'string') {
                 return {
                     kind: 'url',
@@ -261,15 +288,15 @@ export function httpBlobTransport(blobsBaseUrl, options) {
         },
         // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
         uploadToUrl: async (url, bytes, mediaType) => {
-            const response = await doFetch(url, {
+            const response = await transfer('signed blob upload failed', () => doFetch(url, {
                 method: 'PUT',
                 headers: {
                     'Content-Type': mediaType ?? 'application/octet-stream',
                 },
                 body: bytes.slice().buffer,
-            });
+            }));
             if (!response.ok) {
-                throw new ClientSyncError('sync.transport_failed', `blob presigned PUT failed with HTTP ${response.status} (§5.9.3: re-request a grant or stream direct)`, true);
+                throw new ClientSyncError('sync.transport_failed', 'signed blob upload failed; re-request a grant or stream direct', true, { causeKind: 'status', httpStatus: response.status });
             }
         },
     };
@@ -277,17 +304,17 @@ export function httpBlobTransport(blobsBaseUrl, options) {
 /** WebSocket realtime connector (§8.1): text = control, binary = deltas. */
 export function webSocketRealtimeConnector(realtimeUrl) {
     return (handlers) => new Promise((resolve, reject) => {
-        const socket = new WebSocket(realtimeUrl);
+        const socket = socketOperation('realtime socket failed to connect', () => new WebSocket(realtimeUrl));
         let opened = false;
         socket.binaryType = 'arraybuffer';
         socket.onopen = () => {
             opened = true;
             resolve({
-                send: (text) => socket.send(text),
+                send: (text) => socketOperation('realtime send failed', () => socket.send(text)),
                 sendBytes: (bytes) => {
-                    socket.send(bytes.slice().buffer);
+                    socketOperation('realtime send failed', () => socket.send(bytes.slice().buffer));
                 },
-                close: () => socket.close(),
+                close: () => socketOperation('realtime close failed', () => socket.close()),
             });
         };
         socket.onmessage = (event) => {

package/dist/outcomes.d.ts

@@ -7,7 +7,7 @@ export declare const OUTCOMES_TABLE = "_syncular_commit_outcomes";
  * restart can never turn "rejected" into an inferred success. Conflict payloads
  * deliberately stay local; retention never deletes an unresolved failure.
  */
-import type { RejectionDetails, RowValue } from '@syncular/core';
+import { type RejectionDetails, type RowValue } from '@syncular/core';
 import type { ClientDatabase } from './database.js';
 import type { OutboxOperation } from './outbox.js';
 export interface ConflictRecord {
@@ -97,8 +97,16 @@ export interface ResolveCommitOutcomeInput {
     readonly resolution: Exclude<CommitOutcomeResolution, 'active'>;
     readonly replacementClientCommitId?: string;
 }
+export declare function isStoredOperation(value: unknown): value is OutboxOperation;
 export declare function recordCommitOutcome(db: ClientDatabase, outcome: Omit<CommitOutcome, 'sequence' | 'resolution'>): CommitOutcome;
 export declare function commitOutcome(db: ClientDatabase, clientCommitId: string): CommitOutcome | undefined;
+/**
+ * §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 declare function persistedCommitOutcome(db: ClientDatabase, clientCommitId: string): CommitOutcome | undefined;
 export declare function listCommitOutcomes(db: ClientDatabase, query?: CommitOutcomeQuery): CommitOutcome[];
 export declare function persistCommitOutcomeResolution(db: ClientDatabase, input: ResolveCommitOutcomeInput, nowMs: number): CommitOutcome | undefined;
 /**