@abloatai/ablo 0.6.0 → 0.8.0

package/dist/sync/BootstrapHelper.js

@@ -3,7 +3,7 @@
  * Removed problematic caching that was serving stale data
  */
 import { getContext } from '../context.js';
-import { SyncSessionError, AbloConnectionError, translateHttpError } from '../errors.js';
+import { SyncSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../errors.js';
 // SyncObservability replaced by getContext().observability
 import { parseBootstrapResponse } from './schemas.js';
 export class BootstrapHelper {
@@ -60,7 +60,9 @@ export class BootstrapHelper {
     createTimeoutPromise(ms, operation) {
         return new Promise((_, reject) => {
             setTimeout(() => {
-                reject(new Error(`Bootstrap ${operation} timed out after ${ms}ms`));
+                reject(new AbloConnectionError(`Bootstrap ${operation} timed out after ${ms}ms`, {
+                    code: 'bootstrap_fetch_timeout',
+                }));
             }, ms);
         });
     }
@@ -138,6 +140,17 @@ export class BootstrapHelper {
                     });
                     throw error;
                 }
+                // Don't retry NON-retryable errors. A 401/403/4xx auth or client error
+                // (api_key_required, jwt_issuer_untrusted, …) will NOT succeed by
+                // repeating the same request with the same credential — retrying just
+                // hammers the server and floods the console with doomed requests. Only
+                // transient failures (5xx, 429, timeouts, network blips, or an
+                // unclassified error with no code) flow through to the retry/backoff.
+                const ablo = toAbloError(error);
+                if (ablo.code && !isRetryableCode(ablo.code)) {
+                    getContext().observability.breadcrumb('Bootstrap non-retryable error — failing fast', 'sync.bootstrap', 'warning', { code: ablo.code, httpStatus: ablo.httpStatus });
+                    throw ablo;
+                }
                 lastError = error;
                 getContext().observability.breadcrumb('Bootstrap fetch failed', 'sync.bootstrap', 'warning', {
                     attempt: attempt + 1,
@@ -157,7 +170,11 @@ export class BootstrapHelper {
             });
             return cached;
         }
-        throw lastError || new Error('Failed to fetch bootstrap data');
+        throw lastError
+            ? toAbloError(lastError)
+            : new AbloConnectionError('Failed to fetch bootstrap data', {
+                code: 'bootstrap_fetch_timeout',
+            });
     }
     /**
      * Fetch bootstrap with ETag, returning 304 hints
@@ -198,17 +215,6 @@ export class BootstrapHelper {
             return { notModified: true, etag };
         }
         if (!res.ok) {
-            // Check for session/auth errors - these should redirect to login
-            if (SyncSessionError.isSessionErrorResponse(res.status)) {
-                let body = '';
-                try {
-                    body = await res.text();
-                }
-                catch {
-                    // Ignore body parsing errors
-                }
-                throw new SyncSessionError(body || `Session expired or invalid: ${res.status}`, res.status);
-            }
             const bodyText = await res.text().catch(() => '');
             let parsed = bodyText;
             if (bodyText) {
@@ -219,7 +225,21 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            // Translate the canonical envelope FIRST so the server's specific code +
+            // message survive (e.g. `api_key_required`, `jwt_issuer_untrusted`).
+            const translated = translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            // Only a genuine session/JWT EXPIRY — or a bare auth failure carrying no
+            // structured code — should drive the sign-in redirect. A specific auth
+            // code like `api_key_required` is NOT an expired session: re-logging-in
+            // mints the same credential and loops. Surface it as its real typed error
+            // instead of a `session_expired` wrapping the stringified body.
+            if (translated.code === 'session_expired' ||
+                translated.code === 'jwt_expired' ||
+                ((res.status === 401 || res.status === 403) &&
+                    translated.code === undefined)) {
+                throw new SyncSessionError(translated.message, res.status);
+            }
+            throw translated;
         }
         const rawJson = await res.json();
         const data = parseBootstrapResponse(rawJson);
@@ -275,17 +295,6 @@ export class BootstrapHelper {
         }
         clearTimeout(timeoutId);
         if (!response.ok) {
-            // Check for session/auth errors - these should redirect to login
-            if (SyncSessionError.isSessionErrorResponse(response.status)) {
-                let body = '';
-                try {
-                    body = await response.text();
-                }
-                catch {
-                    // Ignore body parsing errors
-                }
-                throw new SyncSessionError(body || `Session expired or invalid: ${response.status}`, response.status);
-            }
             const bodyText = await response.text().catch(() => '');
             let parsed = bodyText;
             if (bodyText) {
@@ -296,7 +305,17 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            // Same code-aware handling as the primary bootstrap fetch: preserve the
+            // server's specific code/message; only a genuine expiry (or a bare,
+            // code-less auth failure) drives the sign-in redirect.
+            const translated = translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            if (translated.code === 'session_expired' ||
+                translated.code === 'jwt_expired' ||
+                ((response.status === 401 || response.status === 403) &&
+                    translated.code === undefined)) {
+                throw new SyncSessionError(translated.message, response.status);
+            }
+            throw translated;
         }
         const rawJson = await response.json();
         const data = parseBootstrapResponse(rawJson);

package/dist/sync/ConnectionManager.d.ts

@@ -34,7 +34,7 @@
  *      instead of hard-reloading an already-offline browser.
  */
 import { type ProbeResult } from './NetworkProbe.js';
-export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'session_expired';
+export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'auth_blocked' | 'session_expired';
 export type ConnectionEvent = {
     type: 'NETWORK_LOST';
 } | {
@@ -52,6 +52,8 @@ export type ConnectionEvent = {
 } | {
     type: 'PROBE_SUCCESS';
     sessionValid: boolean;
+} | {
+    type: 'PROBE_AUTH_BLOCKED';
 } | {
     type: 'PROBE_FAILED';
 } | {

package/dist/sync/ConnectionManager.js

@@ -162,6 +162,8 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_AUTH_BLOCKED':
+                        return 'auth_blocked';
                     case 'PROBE_FAILED':
                         return 'waiting_for_network';
                     case 'NETWORK_LOST':
@@ -185,6 +187,8 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_AUTH_BLOCKED':
+                        return 'auth_blocked';
                     case 'NETWORK_LOST':
                         return 'offline';
                     default:
@@ -227,6 +231,25 @@ export class ConnectionManager {
                     default:
                         return null;
                 }
+            case 'auth_blocked':
+                // Reachable, but the data-plane rejected the credential (non-retryable,
+                // non-expiry — e.g. api_key_required, jwt_issuer_untrusted). Don't
+                // auto-reconnect and don't sign out. Allow a manual retry or a
+                // tab-focus / network-return re-probe (e.g. after a server deploy);
+                // a network drop parks offline; a genuine session error still expires.
+                switch (event.type) {
+                    case 'MANUAL_RETRY':
+                    case 'TAB_VISIBLE':
+                    case 'NETWORK_ONLINE':
+                        return 'probing_network';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    case 'WS_SESSION_ERROR':
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                        return 'session_expired';
+                    default:
+                        return null;
+                }
             case 'session_expired':
                 return null; // terminal
             default:
@@ -255,6 +278,16 @@ export class ConnectionManager {
             case 'backoff':
                 this.scheduleBackoff();
                 break;
+            case 'auth_blocked':
+                // Stop — reachable but the credential was rejected (e.g.
+                // api_key_required / jwt_issuer_untrusted from the data plane). Neither
+                // reconnecting nor re-auth fixes it. Drop the socket and wait for a
+                // manual retry / re-probe. Crucially NOT onSessionExpired (no sign-out)
+                // and NOT a reconnect — that's the whole point of this state.
+                this.clearBackoffTimer();
+                this.callbacks?.onDisconnectWebSocket();
+                getContext().observability.breadcrumb('Auth blocked — reachable but credential rejected; not reconnecting or signing out', 'sync.offline', 'error');
+                break;
             case 'session_expired':
                 this.clearBackoffTimer();
                 this.callbacks?.onDisconnectWebSocket();
@@ -270,7 +303,10 @@ export class ConnectionManager {
             runInAction(() => {
                 this.lastProbeResult = result;
             });
-            if (result.reachable) {
+            if (result.authBlocked) {
+                this.send({ type: 'PROBE_AUTH_BLOCKED' });
+            }
+            else if (result.reachable) {
                 this.send({ type: 'PROBE_SUCCESS', sessionValid: result.sessionValid ?? true });
             }
             else {

package/dist/sync/HydrationCoordinator.d.ts

@@ -113,6 +113,8 @@ export declare class HydrationCoordinator {
     private hydrateExpanded;
     private persistToIdb;
     private resolveTypename;
+    private columnizeField;
+    private columnizeClause;
 }
 /**
  * Normalize `LoadWhere<T>` input to the canonical `readonly WhereClause[]`

package/dist/sync/HydrationCoordinator.js

@@ -20,6 +20,7 @@
  * models accessed by id/where after the engine is ready.
  */
 import { ModelScope } from '../ObjectPool.js';
+import { AbloValidationError } from '../errors.js';
 import { postQuery } from '../query/client.js';
 export class HydrationCoordinator {
     opts;
@@ -53,8 +54,8 @@ export class HydrationCoordinator {
         const ModelClass = this.opts.registry.getModelByName(typename)
             ?? this.opts.registry.getModelByName(modelName);
         if (!ModelClass) {
-            throw new Error(`HydrationCoordinator.fetch: unknown model "${modelName}" — ` +
-                `not registered in the schema.`);
+            throw new AbloValidationError(`HydrationCoordinator.fetch: unknown model "${modelName}" — ` +
+                `not registered in the schema.`, { code: 'model_not_registered' });
         }
         const clauses = normalizeWhere(options?.where);
         const queryKey = stableKey(modelName, clauses, options?.orderBy, options?.limit);
@@ -161,10 +162,10 @@ export class HydrationCoordinator {
         const firstOrder = orderEntries[0];
         const query = {
             model: typename,
-            where: clauses.map((c) => columnizeClause(c)),
+            where: clauses.map((c) => this.columnizeClause(modelName, c)),
             ...(firstOrder
                 ? {
-                    orderBy: columnize(firstOrder[0]),
+                    orderBy: this.columnizeField(modelName, firstOrder[0]),
                     order: firstOrder[1] ?? 'asc',
                 }
                 : {}),
@@ -256,6 +257,27 @@ export class HydrationCoordinator {
             .models?.[modelName];
         return def?.typename ?? modelName;
     }
+    columnizeField(modelName, field) {
+        const fields = this.opts.schema.models?.[modelName]?.fields;
+        if (fields) {
+            const direct = fields[field]?.column;
+            if (direct)
+                return direct;
+            for (const [fieldName, meta] of Object.entries(fields)) {
+                const conventional = columnize(fieldName);
+                if (field === fieldName || field === conventional || field === meta.column) {
+                    return meta.column ?? conventional;
+                }
+            }
+        }
+        return /[A-Z]/.test(field) ? columnize(field) : field;
+    }
+    columnizeClause(modelName, clause) {
+        const finalCol = this.columnizeField(modelName, clause[0]);
+        if (clause.length === 2)
+            return [finalCol, clause[1]];
+        return [finalCol, clause[1], clause[2]];
+    }
 }
 // ── Helpers ────────────────────────────────────────────────────────────
 function stableKey(modelName, clauses, orderBy, limit) {
@@ -350,21 +372,6 @@ export function normalizeWhere(where) {
     }
     return [];
 }
-/**
- * Apply `columnize` to the column name of a wire-bound clause so the
- * server sees `slide_id` instead of `slideId`. Tuple-form clauses from
- * callers are passed through unchanged — they already supply the wire
- * column name (matches what existing `postQuery` consumers do).
- */
-function columnizeClause(clause) {
-    const col = clause[0];
-    // If the column already looks snake_case (no uppercase letters), assume
-    // the caller is already using server-side naming. Otherwise camelize→snake.
-    const finalCol = /[A-Z]/.test(col) ? columnize(col) : col;
-    if (clause.length === 2)
-        return [finalCol, clause[1]];
-    return [finalCol, clause[1], clause[2]];
-}
 /** Equality-only subset of clauses, keyed by column. Used by IDB fast paths. */
 function extractEqClauses(clauses) {
     const out = {};

package/dist/sync/NetworkProbe.d.ts

@@ -27,6 +27,14 @@ export interface ProbeResult {
     reachable: boolean;
     /** Whether the session cookie is still valid (null if server unreachable) */
     sessionValid: boolean | null;
+    /**
+     * Reachable, but a NON-retryable auth/config failure that is NOT a session
+     * expiry (e.g. `api_key_required`, `jwt_issuer_untrusted`). The session is
+     * fine — the data-plane rejected the credential TYPE — so neither
+     * reconnecting nor re-authenticating will help. The manager stops instead of
+     * looping. Distinct from `sessionValid: false` (genuine expiry → sign in).
+     */
+    authBlocked?: boolean;
     /** Round-trip time in ms (null if failed) */
     latencyMs: number | null;
 }

package/dist/sync/NetworkProbe.js

@@ -22,7 +22,7 @@
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
 import { getContext } from '../context.js';
-import { SyncSessionError } from '../errors.js';
+import { SyncSessionError, isRetryableCode } from '../errors.js';
 const PROBE_TIMEOUT_MS = 4000;
 /**
  * Derive the probe URL from a sync-server base URL. Accepts `ws://`,
@@ -72,7 +72,17 @@ export async function probeNetwork(baseUrl) {
             headers: { 'Cache-Control': 'no-cache' },
         });
         const latencyMs = Math.round(performance.now() - start);
-        if (SyncSessionError.isSessionErrorResponse(response.status)) {
+        // The probe is a HEAD (no body), but the sync-server sets `X-Auth-Failure:
+        // <code>` on every auth rejection — feed that to the code-aware detector so
+        // only a genuine session/JWT EXPIRY marks the session invalid. A non-expiry
+        // auth failure (e.g. api_key_required, jwt_issuer_untrusted) leaves
+        // sessionValid alone — the user IS logged in; signing them out wouldn't fix
+        // a credential-type/config problem and just bounces them to /signin.
+        const authFailure = response.headers.get('x-auth-failure');
+        const failureBody = authFailure
+            ? JSON.stringify({ code: authFailure })
+            : undefined;
+        if (SyncSessionError.isSessionErrorResponse(response.status, failureBody)) {
             // Server reachable but session expired/invalid
             getContext().logger.info('[NetworkProbe] Server reachable, session expired', {
                 status: response.status,
@@ -80,6 +90,18 @@ export async function probeNetwork(baseUrl) {
             });
             return { reachable: true, sessionValid: false, latencyMs };
         }
+        // Reachable, but a NON-retryable auth/config failure that is NOT a session
+        // expiry (api_key_required, jwt_issuer_untrusted, …). Re-auth won't fix it
+        // and retrying won't either — signal authBlocked so the manager STOPS
+        // rather than reconnect-looping or signing the user out.
+        if (authFailure && !isRetryableCode(authFailure)) {
+            getContext().logger.warn('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
+                status: response.status,
+                code: authFailure,
+                latencyMs,
+            });
+            return { reachable: true, sessionValid: true, authBlocked: true, latencyMs };
+        }
         // 2xx (including 204) means reachable + session valid.
         // 3xx/4xx (non-auth) still prove connectivity even though the probe
         // expected 204; log a warning so misconfigurations surface instead of

package/dist/sync/SyncWebSocket.d.ts

@@ -271,7 +271,7 @@ export interface CoreSyncEventMap {
     /**
      * Per-entity wait-queue snapshot: `{ target, queue: Intent[] }` with each
      * entry `status: 'queued'` + `position`. Broadcast to entity peers on every
-     * queue mutation — powers the reactive `ablo.<model>.queue(id)` read.
+     * queue mutation — powers the reactive `ablo.<model>.claim.queue(id)` read.
      */
     intent_queue: [Record<string, unknown>];
     intent_acquired: [Record<string, unknown>];

package/dist/sync/SyncWebSocket.js

@@ -10,7 +10,7 @@
 import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
-import { AbloClaimedError, CapabilityError, SyncSessionError, } from '../errors.js';
+import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
 // Consumers pass their own event types as TCollaboration generic parameter.
@@ -214,7 +214,7 @@ export class SyncWebSocket extends EventEmitter {
             const errorMessage = error instanceof Error ? error.message : 'Failed to create WebSocket';
             getContext().observability.captureWebSocketError({ context: 'create-websocket', error: errorMessage });
             this.isConnecting = false;
-            this.emit('error', new Error(errorMessage));
+            this.emit('error', new AbloConnectionError(errorMessage, { cause: error }));
             this.scheduleReconnect();
         }
     }
@@ -360,38 +360,19 @@ export class SyncWebSocket extends EventEmitter {
                             else {
                                 errorMessage = 'mutation failed on server';
                             }
-                            // Capability denials route through the typed CapabilityError
-                            // so callers can `instanceof CapabilityError` and read
-                            // `.requiredCapability` to attenuate-and-retry without
-                            // string-matching the error code.
-                            if (errorCode === 'capability_scope_denied' ||
-                                errorCode === 'capability_invalid') {
-                                pending.reject(new CapabilityError(errorCode, errorMessage, requiredCapability));
-                            }
-                            else if (errorCode === 'intent_conflict' ||
-                                errorCode === 'claim_conflict' ||
-                                errorCode === 'entity_claimed') {
-                                // Claim enforcement: another participant holds a live claim on
-                                // a targeted entity. Two server layers reject this — the Hub's
-                                // pre-commit lease check (`intent_conflict`, the code that
-                                // reaches clients in practice) and `executeCommit`'s deeper
-                                // guard (`entity_claimed`). Both mean "claimed", so both route
-                                // through the typed AbloClaimedError, letting callers
-                                // `instanceof AbloClaimedError` (or read `e.type` across worker
-                                // boundaries) and wait/bypass — symmetric with the
-                                // CapabilityError branch above, and with the HTTP commit path
-                                // (`translateHttpError`).
-                                pending.reject(new AbloClaimedError(errorMessage, {
-                                    code: errorCode === 'intent_conflict' ? 'claim_conflict' : errorCode,
-                                    httpStatus: 409,
-                                }));
-                            }
-                            else {
-                                const rejection = new Error(errorMessage);
-                                if (errorCode)
-                                    rejection.code = errorCode;
-                                pending.reject(rejection);
-                            }
+                            // Build the proper typed AbloError from the wire code via the
+                            // shared factory — the same code→class mapping the HTTP commit
+                            // path uses (`translateHttpError`). This keeps rejected commits
+                            // inside the typed hierarchy (capability denials →
+                            // CapabilityError with `.requiredCapability`; foreign-claim
+                            // conflicts → AbloClaimedError; everything else → the subclass
+                            // its registry `httpStatus` implies) instead of a hand-rolled
+                            // `new Error`, so callers can `instanceof`/`e.type` it and
+                            // downstream retry logic can read the contract's retryability.
+                            pending.reject(errorFromWire(errorMessage, {
+                                code: errorCode,
+                                requiredCapability,
+                            }));
                         }
                         break;
                     }
@@ -438,11 +419,10 @@ export class SyncWebSocket extends EventEmitter {
                                 pending.reject(new CapabilityError(code, msg, requiredCapability));
                             }
                             else {
-                                // Attach `code` as a property on the rejection so callers
-                                // can discriminate (`scope_conflict`, `malformed_claim`,
-                                // ...) without parsing the message.
-                                const rejection = Object.assign(new Error(`${code}: ${msg}`), { code });
-                                pending.reject(rejection);
+                                // Route through the shared factory so a failed claim_ack is a
+                                // typed AbloError (registry code → right subclass), symmetric
+                                // with the commit `mutation_result` path — never a bare Error.
+                                pending.reject(errorFromWire(msg, { code }));
                             }
                         }
                         break;
@@ -539,12 +519,12 @@ export class SyncWebSocket extends EventEmitter {
             // Check if we're offline first
             if (!getContext().onlineStatus.isOnline()) {
                 getContext().observability.breadcrumb('WebSocket error: Network is offline', 'sync.websocket', 'warning');
-                this.emit('error', new Error('Network is offline'));
+                this.emit('error', new AbloConnectionError('Network is offline', { code: 'bootstrap_offline' }));
                 return;
             }
             // After session error, suppress Sentry capture — the root cause is already reported.
             // Still emit so SyncedStore can update UI state.
-            const error = new Error(`WebSocket connection failed`);
+            const error = new AbloConnectionError(`WebSocket connection failed`);
             if (!this._sessionErrorDetected) {
                 getContext().observability.captureWebSocketError({
                     context: 'connection-error',
@@ -578,12 +558,16 @@ export class SyncWebSocket extends EventEmitter {
             if (this.pendingMutations.size > 0) {
                 for (const pending of this.pendingMutations.values()) {
                     clearTimeout(pending.timeout);
-                    pending.reject(Object.assign(new Error(`WebSocket closed while commit was in flight (code=${event.code}` +
+                    // AbloConnectionError → `isPermanentError` treats it as transient,
+                    // so TransactionQueue retries the commit on reconnect rather than
+                    // rolling it back. `diagnostics` is preserved as a property (the
+                    // queue's failure log walks the cause chain for it).
+                    pending.reject(Object.assign(new AbloConnectionError(`WebSocket closed while commit was in flight (code=${event.code}` +
                         (event.reason ? ` reason=${event.reason}` : '') +
                         (this.lastForceCloseReason
                             ? ` forceCloseReason=${this.lastForceCloseReason}`
                             : '') +
-                        ')'), { diagnostics: this.getConnectionDiagnostics() }));
+                        ')', { code: 'commit_no_result' }), { diagnostics: this.getConnectionDiagnostics() }));
                 }
                 this.pendingMutations.clear();
             }
@@ -594,7 +578,7 @@ export class SyncWebSocket extends EventEmitter {
             if (this.pendingClaims.size > 0) {
                 for (const pending of this.pendingClaims.values()) {
                     clearTimeout(pending.timeout);
-                    pending.reject(new Error(`WebSocket closed while claim was in flight (code=${event.code})`));
+                    pending.reject(new AbloConnectionError(`WebSocket closed while claim was in flight (code=${event.code})`));
                 }
                 this.pendingClaims.clear();
             }
@@ -762,7 +746,7 @@ export class SyncWebSocket extends EventEmitter {
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
                 this.pendingMutations.delete(clientTxId);
-                reject(new Error(`commit timed out after ${timeoutMs}ms (clientTxId=${clientTxId})`));
+                reject(new AbloConnectionError(`commit timed out after ${timeoutMs}ms (clientTxId=${clientTxId})`, { code: 'commit_no_result' }));
             }, timeoutMs);
             this.pendingMutations.set(clientTxId, { resolve, reject, timeout });
             try {
@@ -778,9 +762,7 @@ export class SyncWebSocket extends EventEmitter {
             catch (error) {
                 clearTimeout(timeout);
                 this.pendingMutations.delete(clientTxId);
-                reject(error instanceof Error
-                    ? error
-                    : new Error(String(error)));
+                reject(toAbloError(error));
             }
         });
     }
@@ -826,7 +808,9 @@ export class SyncWebSocket extends EventEmitter {
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
                 this.pendingClaims.delete(claimId);
-                reject(new Error(`claim timed out after ${timeoutMs}ms (claimId=${claimId})`));
+                reject(new AbloConnectionError(`claim timed out after ${timeoutMs}ms (claimId=${claimId})`, {
+                    code: 'wait_for_timeout',
+                }));
             }, timeoutMs);
             this.pendingClaims.set(claimId, { resolve, reject, timeout });
             try {
@@ -843,7 +827,7 @@ export class SyncWebSocket extends EventEmitter {
             catch (error) {
                 clearTimeout(timeout);
                 this.pendingClaims.delete(claimId);
-                reject(error instanceof Error ? error : new Error(String(error)));
+                reject(toAbloError(error));
             }
         });
     }
@@ -864,7 +848,10 @@ export class SyncWebSocket extends EventEmitter {
         if (pending) {
             clearTimeout(pending.timeout);
             this.pendingClaims.delete(claimId);
-            pending.reject(new Error(`claim ${claimId} released before ack`));
+            pending.reject(new AbloError(`claim ${claimId} released before ack`, {
+                code: 'intent_wait_aborted',
+                httpStatus: 409,
+            }));
         }
         if (this.ws?.readyState !== WebSocket.OPEN)
             return;
@@ -1172,8 +1159,11 @@ export class SyncWebSocket extends EventEmitter {
         else {
             detail = 'never_connected';
         }
-        const err = new Error(`SyncWebSocket not connected — cannot send ${action} (${detail})`);
-        err.diagnostics = d;
+        // Typed so it lands in the AbloError hierarchy AND `isPermanentError`
+        // sees a transient transport failure (retry on reconnect, don't roll
+        // back). `diagnostics` stays a property — the queue's failure log walks
+        // the cause chain for it.
+        const err = Object.assign(new AbloConnectionError(`SyncWebSocket not connected — cannot send ${action} (${detail})`, { code: 'ws_not_ready' }), { diagnostics: d });
         return err;
     }
     /** Returns the sync groups this connection is subscribed to. */

package/dist/sync/createIntentStream.d.ts

@@ -11,7 +11,8 @@
  * Wire contract (apps/sync-server/src/hub/types.ts):
  *   • Outbound: `{ type: 'intent_begin', payload: { intentId,
  *       entityType, entityId, action, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'intent_abandon', payload: { intentId } }`
+ *   • Outbound: `{ type: 'intent_abandon', payload: { intentId,
+ *       entityType?, entityId? } }`
  *   • Inbound (via presence): `event.activeIntents: IntentClaim[]`
  *     stamped with `declaredAt`, `expiresAt`.
  *   • Inbound: `intent_rejected` event with conflict metadata.