@abloatai/ablo 0.7.0 → 0.9.0

package/dist/client/index.d.ts

@@ -30,6 +30,7 @@
  * ```
  */
 export { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type ClaimedOptions, type IfClaimedPolicy, type IntentWaitOptions, type ModelCountOptions, type ModelListOptions, type ModelListScope, type ModelLoadOptions, type ModelOperations, type ModelReadOptions, } from './Ablo.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './auth.js';
 export type { AbloPersistence } from './persistence.js';
 export type { AbloApi, AbloApiClientOptions, AbloApiIntents, Agent, AgentIntentInput, AgentIntentOptions, AgentOptions, AgentModelClient, AgentModelReadOptions, AgentModelMutationOptions, AgentRunContext, AgentRunDone, AgentRunFailed, AgentRunCancelled, AgentRunOptions, AgentRunResult, AgentRunStatus, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, Task, TaskCloseOptions, TaskCloseResult, TaskCreateOptions, TaskResource, } from './ApiClient.js';
 export type { EngineParticipant, JoinedParticipant, ParticipantJoinOptions, ParticipantManager, ParticipantScope, ParticipantStatus, ScopedIntents, ScopedPresence, } from '../sync/participants.js';

package/dist/client/index.js

@@ -30,3 +30,4 @@
  * ```
  */
 export { Ablo, computeFKDepthPriority, } from './Ablo.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './auth.js';

package/dist/client/registerDataSource.d.ts

@@ -0,0 +1,19 @@
+export interface RegisterDataSourceInput {
+    /** HTTP API base, e.g. `https://api.abloatai.com/api` (from resolveBootstrapBaseUrl). */
+    readonly baseUrl: string;
+    /** Secret key (`sk_…`) used to authenticate + derive the org. */
+    readonly apiKey: string | null;
+    /** Postgres connection string for the direct connector. */
+    readonly databaseUrl: string;
+    /** Optional Postgres schema (defaults server-side to `public`). */
+    readonly schema?: string;
+    /** Custom fetch (tests/proxies/odd runtimes). */
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * POST the connection string to the self-serve direct connector route. Resolves
+ * on success (the org is now a dedicated tenant pointed at this DB); throws an
+ * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
+ * surfaces it instead of silently bootstrapping against the wrong store.
+ */
+export declare function registerDataSource(input: RegisterDataSourceInput): Promise<void>;

package/dist/client/registerDataSource.js

@@ -0,0 +1,59 @@
+/**
+ * Self-serve direct-Postgres connector registration.
+ *
+ * Historical note: this module name says "DataSource", but this path registers
+ * a direct database URL. It is not the signed `dataSource(...)` endpoint path.
+ *
+ * When a client is constructed with `databaseUrl`, the SDK registers that
+ * connection string BEFORE bootstrap so the server resolves the org's data plane
+ * to that direct connector.
+ *
+ * The org is derived server-side from the API key — the caller never sends an
+ * organization id. The connection string is sent once over TLS and is never
+ * echoed back (the server stores it as a secret and returns only a safe
+ * `datasource` projection: host, database, schema).
+ */
+import { AbloError } from '../errors.js';
+/**
+ * POST the connection string to the self-serve direct connector route. Resolves
+ * on success (the org is now a dedicated tenant pointed at this DB); throws an
+ * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
+ * surfaces it instead of silently bootstrapping against the wrong store.
+ */
+export async function registerDataSource(input) {
+    if (!input.apiKey) {
+        throw new AbloError('databaseUrl requires an apiKey to register the direct Postgres connector (the org is derived from the key).', { code: 'datasource_registration_failed' });
+    }
+    const doFetch = input.fetchImpl ?? fetch;
+    const endpoint = `${input.baseUrl.replace(/\/+$/, '')}/v1/datasource`;
+    let response;
+    try {
+        response = await doFetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${input.apiKey}`,
+            },
+            body: JSON.stringify({
+                connectionString: input.databaseUrl,
+                ...(input.schema ? { schema: input.schema } : {}),
+            }),
+        });
+    }
+    catch (cause) {
+        throw new AbloError('Could not reach the Ablo API to register the direct Postgres connector.', {
+            code: 'datasource_registration_failed',
+            cause,
+        });
+    }
+    if (!response.ok) {
+        let detail = '';
+        try {
+            detail = (await response.text()).slice(0, 500);
+        }
+        catch {
+            // ignore body read failures — the status alone is enough to fail loud
+        }
+        throw new AbloError(`Direct Postgres connector registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
+    }
+}

package/dist/client/validateAbloOptions.d.ts

@@ -10,6 +10,7 @@
  * because the error messages reference URLs and would mislead if a
  * URL was actually present.
  */
+import { AbloError } from '../errors.js';
 /**
  * Minimal subset of `AbloOptions` the validator actually inspects.
  * Defined here as its own interface so the validator doesn't pull
@@ -39,4 +40,4 @@ export interface ValidateAbloOptionsInput {
     readonly configuredApiKey: unknown;
     readonly configuredAuthToken: unknown;
 }
-export declare function validateAbloOptions(input: ValidateAbloOptionsInput): Error | null;
+export declare function validateAbloOptions(input: ValidateAbloOptionsInput): AbloError | null;

package/dist/client/validateAbloOptions.js

@@ -10,12 +10,13 @@
  * because the error messages reference URLs and would mislead if a
  * URL was actually present.
  */
+import { AbloValidationError } from '../errors.js';
 export function validateAbloOptions(input) {
     const { options, url, configuredApiKey, configuredAuthToken } = input;
     const kind = options.kind ?? 'user';
     if (!url) {
-        return new Error('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
-            `Ablo({ baseURL: 'wss://sync.abloatai.com', schema, user })`);
+        return new AbloValidationError('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
+            `Ablo({ baseURL: 'wss://api.abloatai.com', schema, user })`, { code: 'base_url_missing' });
     }
     // Schema is optional for the model-first API:
     //   Ablo({ apiKey }).model('clauses').retrieve(...)
@@ -26,18 +27,18 @@ export function validateAbloOptions(input) {
         kind === 'user' &&
         options.user &&
         !options.user.id) {
-        return new Error('Ablo: `user.id` must be a non-empty string when `user` is provided.');
+        return new AbloValidationError('Ablo: `user.id` must be a non-empty string when `user` is provided.', { code: 'invalid_options', param: 'user.id' });
     }
     if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.agentId) {
-        return new Error('Ablo: provide either `apiKey` or `agentId` for `kind: "agent"`. ' +
+        return new AbloValidationError('Ablo: provide either `apiKey` or `agentId` for `kind: "agent"`. ' +
             'Hosted-cloud consumers pass `apiKey` and the server derives the ' +
             'agent identity from its scope; self-hosted passes `agentId` + ' +
-            '`capabilityToken` directly.');
+            '`capabilityToken` directly.', { code: 'invalid_options', param: 'agentId' });
     }
     if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.capabilityToken) {
-        return new Error('Ablo: provide either `apiKey` (hosted cloud — SDK exchanges internally) ' +
+        return new AbloValidationError('Ablo: provide either `apiKey` (hosted cloud — SDK exchanges internally) ' +
             'or `capabilityToken` (self-hosted — your auth layer mints + hands in). ' +
-            'See https://abloatai.com/docs/api-keys for the full pattern.');
+            'See https://abloatai.com/docs/api-keys for the full pattern.', { code: 'invalid_options', param: 'capabilityToken' });
     }
     return null;
 }

package/dist/core/DatabaseManager.js

@@ -8,7 +8,7 @@
  * Follows Ablo's architecture for database management.
  */
 import { getContext } from '../context.js';
-import { openIDBWithTimeout } from './openIDBWithTimeout.js';
+import { openIDBWithTimeout, deleteIDBWithTimeout, IDBOpenTimeoutError, } from './openIDBWithTimeout.js';
 import { AbloConnectionError } from '../errors.js';
 import { getActiveRegistry, hasActiveRegistry } from '../ModelRegistry.js';
 /**
@@ -30,7 +30,7 @@ export class DatabaseManager {
      * Initialize the meta database (ablo_databases)
      */
     async initializeMetaDatabase() {
-        this.metaDb = await openIDBWithTimeout(this.metaDbName, 1, {
+        const open = () => openIDBWithTimeout(this.metaDbName, 1, {
             onUpgrade: (request) => {
                 const db = request.result;
                 if (!db.objectStoreNames.contains('databases')) {
@@ -42,6 +42,34 @@ export class DatabaseManager {
                 }
             },
         });
+        try {
+            this.metaDb = await open();
+        }
+        catch (error) {
+            // Self-heal a wedged meta DB. When `ablo_databases`'s backing store gets
+            // stuck (a corrupted store, or a leaked connection from a prior
+            // timed-out open), every open of that name hangs with no event and the
+            // app is permanently bricked until the user manually clears site data —
+            // the "open did not resolve within 10000ms" dead end. The registry this
+            // DB holds is rebuildable from the server on the next bootstrap, so it is
+            // safe to delete and re-create. Try exactly once: delete, then re-open.
+            if (!(error instanceof IDBOpenTimeoutError))
+                throw error;
+            getContext().logger.warn('[sync-engine] meta DB open timed out — attempting self-heal (delete + retry)', { db: this.metaDbName, reason: error.reason });
+            getContext().observability.captureBootstrapFailure(error, {
+                type: 'meta-db-open-timeout',
+            });
+            const deleted = await deleteIDBWithTimeout(this.metaDbName);
+            if (!deleted) {
+                // The delete itself was blocked/stuck — a live connection in another
+                // window or a deadlocked backing store. We cannot recover in-page;
+                // rethrow so the provider surfaces the real (now actionable) error.
+                throw error;
+            }
+            // Fresh store — this open creates `ablo_databases` from scratch.
+            this.metaDb = await open();
+            getContext().logger.info('[sync-engine] meta DB self-heal succeeded');
+        }
     }
     /**
      * Calculate database info for a user/workspace combination

package/dist/core/openIDBWithTimeout.d.ts

@@ -16,12 +16,48 @@
 export declare class IDBOpenTimeoutError extends Error {
     readonly dbName: string;
     readonly reason: 'blocked' | 'timeout';
+    /**
+     * Stable, transport-independent code. `toAbloError` preserves a string
+     * `.code`, so this survives the wrap into `AbloError` and reaches the
+     * provider's `onError` intact — letting the app distinguish a wedged-storage
+     * failure (show a recovery screen) from any other bootstrap error without a
+     * brittle message match.
+     */
+    readonly code = "storage_open_timeout";
     constructor(dbName: string, reason: 'blocked' | 'timeout', message: string);
 }
+/** True for the wedged-IndexedDB failure, after it has been wrapped anywhere. */
+export declare function isStorageOpenTimeout(err: unknown): boolean;
 export interface OpenIDBOptions {
     /** Called inside `onupgradeneeded` — mirrors `IDBOpenDBRequest.onupgradeneeded`. */
     onUpgrade?: (request: IDBOpenDBRequest, event: IDBVersionChangeEvent) => void;
     /** Max milliseconds to wait for the open request to resolve. Default 10_000. */
     timeoutMs?: number;
+    /**
+     * Called when another context (a new tab, a fresh deploy, or our own
+     * `deleteIDBWithTimeout` self-heal) fires `versionchange` on this connection.
+     * By default the connection is `close()`d immediately — the W3C/MDN-mandated
+     * behavior that lets the other context's upgrade/delete proceed instead of
+     * blocking forever. Provide this to ALSO react (e.g. prompt a reload) AFTER
+     * the close. Throwing here is swallowed.
+     */
+    onVersionChange?: () => void;
 }
 export declare function openIDBWithTimeout(name: string, version: number | undefined, options?: OpenIDBOptions): Promise<IDBDatabase>;
+/**
+ * Bounded `indexedDB.deleteDatabase()` — the delete counterpart of
+ * `openIDBWithTimeout`. Used by the meta-DB self-heal: when opening
+ * `ablo_databases` times out (a wedged backing store), we attempt to delete it
+ * and re-create from scratch. The registry it holds is rebuildable from the
+ * server on the next bootstrap, so dropping it is safe.
+ *
+ * Like `open`, `deleteDatabase` can hang indefinitely: if another live
+ * connection holds the DB it fires `onblocked` and waits, and on a truly stuck
+ * store it fires *no* event at all. Both become a bounded rejection here so the
+ * caller can fall through to surfacing a real error instead of spinning.
+ *
+ * Resolves `true` on a clean delete, `false` if it was blocked or timed out
+ * (caller decides whether to retry the open regardless — a no-op delete still
+ * leaves us no worse off).
+ */
+export declare function deleteIDBWithTimeout(name: string, timeoutMs?: number): Promise<boolean>;

package/dist/core/openIDBWithTimeout.js

@@ -16,6 +16,14 @@
 export class IDBOpenTimeoutError extends Error {
     dbName;
     reason;
+    /**
+     * Stable, transport-independent code. `toAbloError` preserves a string
+     * `.code`, so this survives the wrap into `AbloError` and reaches the
+     * provider's `onError` intact — letting the app distinguish a wedged-storage
+     * failure (show a recovery screen) from any other bootstrap error without a
+     * brittle message match.
+     */
+    code = 'storage_open_timeout';
     constructor(dbName, reason, message) {
         super(message);
         this.dbName = dbName;
@@ -23,6 +31,12 @@ export class IDBOpenTimeoutError extends Error {
         this.name = 'IDBOpenTimeoutError';
     }
 }
+/** True for the wedged-IndexedDB failure, after it has been wrapped anywhere. */
+export function isStorageOpenTimeout(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        err.code === 'storage_open_timeout');
+}
 export function openIDBWithTimeout(name, version, options = {}) {
     const timeoutMs = options.timeoutMs ?? 10_000;
     return new Promise((resolve, reject) => {
@@ -42,7 +56,47 @@ export function openIDBWithTimeout(name, version, options = {}) {
                 options.onUpgrade(request, event);
             };
         }
-        request.onsuccess = () => settle(() => resolve(request.result));
+        request.onsuccess = () => {
+            // If we ALREADY timed out (or blocked) and rejected, this is a late
+            // success: the native open eventually completed after we gave up. The
+            // resulting connection is orphaned — nobody up the stack holds it, so
+            // nobody will `.close()` it. A leaked open connection holds an IndexedDB
+            // lock that wedges every subsequent open/delete of this DB name (the
+            // exact "ablo_databases open/delete hangs forever with no event" failure
+            // mode). Close it here so a timed-out attempt can't poison the store.
+            if (settled) {
+                try {
+                    request.result.close();
+                }
+                catch {
+                    // Best-effort — a half-open connection may already be unusable.
+                }
+                return;
+            }
+            const db = request.result;
+            // MANDATORY resilience handler (W3C IndexedDB / MDN): close this
+            // connection the instant any other context wants to upgrade or delete the
+            // DB. Without it, an open connection that ignores `versionchange` blocks
+            // the other context's request indefinitely — the root cause of a wedged
+            // `ablo_databases` that survives reloads (an interrupted transaction's
+            // connection never closes, so every later open/delete hangs with no
+            // event). Auto-closing here makes the store self-releasing.
+            db.onversionchange = () => {
+                try {
+                    db.close();
+                }
+                catch {
+                    // Already closing/closed — nothing to do.
+                }
+                try {
+                    options.onVersionChange?.();
+                }
+                catch {
+                    // A consumer reaction must never break the close.
+                }
+            };
+            settle(() => resolve(db));
+        };
         request.onerror = () => settle(() => reject(request.error));
         // The critical handler: another tab is blocking us. Native API leaves
         // the request pending indefinitely; we fail fast with a clear error so
@@ -61,3 +115,36 @@ export function openIDBWithTimeout(name, version, options = {}) {
         }, timeoutMs);
     });
 }
+/**
+ * Bounded `indexedDB.deleteDatabase()` — the delete counterpart of
+ * `openIDBWithTimeout`. Used by the meta-DB self-heal: when opening
+ * `ablo_databases` times out (a wedged backing store), we attempt to delete it
+ * and re-create from scratch. The registry it holds is rebuildable from the
+ * server on the next bootstrap, so dropping it is safe.
+ *
+ * Like `open`, `deleteDatabase` can hang indefinitely: if another live
+ * connection holds the DB it fires `onblocked` and waits, and on a truly stuck
+ * store it fires *no* event at all. Both become a bounded rejection here so the
+ * caller can fall through to surfacing a real error instead of spinning.
+ *
+ * Resolves `true` on a clean delete, `false` if it was blocked or timed out
+ * (caller decides whether to retry the open regardless — a no-op delete still
+ * leaves us no worse off).
+ */
+export function deleteIDBWithTimeout(name, timeoutMs = 5_000) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const request = indexedDB.deleteDatabase(name);
+        request.onsuccess = () => settle(true);
+        request.onerror = () => settle(false);
+        request.onblocked = () => settle(false);
+        const timer = setTimeout(() => settle(false), timeoutMs);
+    });
+}

package/dist/errorCodes.d.ts

@@ -29,6 +29,7 @@
  *      carry no `httpStatus`, exactly as Stripe omits client-side
  *      programmer errors from its published code list.
  */
+import { z } from 'zod';
 /**
  * Version of the error contract — the envelope shape + the set of codes and
  * their semantics. Date-based, like Stripe's API versions. Bump it (and only
@@ -36,9 +37,48 @@
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export declare const ERROR_CONTRACT_VERSION = "2026-05-28";
+export declare const ERROR_CONTRACT_VERSION = "2026-06-02";
 /** Coarse grouping for metrics dashboards and docs sectioning. */
 export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'intent' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
+/**
+ * The closed taxonomy of *how a failure recovers* — one rung above the raw
+ * `code`. Where `code` says **what** went wrong, `RecoveryClass` says **what
+ * the client should do about it**, which is exactly the discriminant the sync
+ * FSM and the network probe need. It collapses what used to be three scattered
+ * booleans (`retryable`, `authBlocked`, `sessionValid`) into one exhaustive,
+ * Zod-validated enum so the connection layer branches on a single value with
+ * compile-time completeness instead of ad-hoc `if (!isRetryableCode(...))`
+ * chains.
+ *
+ *   - `access_credential_expiry` — the Stripe-style ephemeral key (`ek_`/`rk_`)
+ *     the sync-engine presents as its Bearer has expired. The long-lived login
+ *     is fine; the remedy is to silently RE-MINT a fresh key from the session
+ *     and retry the same request. This MUST NOT sign the user out (the whole
+ *     point of the wake-from-sleep fix: a 15-min `ek_` dying after a laptop nap
+ *     is routine, not a logout).
+ *   - `session_expiry` — the LONG-LIVED login itself is gone. Terminal:
+ *     sign out and route to re-authentication.
+ *   - `auth_blocked` — reachable, but the credential TYPE/config was rejected
+ *     (wrong key kind, untrusted issuer, no org). Re-auth re-mints the same
+ *     rejected credential and loops, so STOP — don't reconnect, don't sign out.
+ *   - `permission` — a 403 authorization denial (scope/role/membership).
+ *   - `transient` — retry the same request unchanged (5xx, lease contention…).
+ *   - `none` — not a recoverable-auth condition (validation, not-found, local
+ *     invariants, and any forward-compat code an older SDK doesn't know).
+ */
+export declare const RECOVERY_CLASSES: readonly ["access_credential_expiry", "session_expiry", "auth_blocked", "permission", "transient", "none"];
+/** Zod enum derived from {@link RECOVERY_CLASSES} — the runtime-validatable
+ *  form of the recovery taxonomy. */
+export declare const recoveryClassSchema: z.ZodEnum<{
+    permission: "permission";
+    access_credential_expiry: "access_credential_expiry";
+    session_expiry: "session_expiry";
+    auth_blocked: "auth_blocked";
+    transient: "transient";
+    none: "none";
+}>;
+/** How a failure recovers. See {@link RECOVERY_CLASSES}. */
+export type RecoveryClass = z.infer<typeof recoveryClassSchema>;
 /** One registry entry. `httpStatus` is present only for `surface: 'wire'`
  *  codes — status is a property of the wire boundary, never of a
  *  purely-local client invariant. */
@@ -55,6 +95,14 @@ export interface ErrorCodeSpec {
     readonly retryable: boolean;
     /** One-line human description — the source text for the `doc_url` page. */
     readonly message: string;
+    /**
+     * Explicit recovery class. Set ONLY where it diverges from what `category` /
+     * `httpStatus` / `retryable` already imply — i.e. the handful of auth codes
+     * whose remedy (`session_expiry` vs `access_credential_expiry`) the bare
+     * status can't distinguish. Everything else is derived by
+     * {@link classifyRecovery}, so adding a normal code needs no `recovery`.
+     */
+    readonly recovery?: RecoveryClass;
 }
 /**
  * The closed set of stable error codes. Add a code here BEFORE throwing it
@@ -69,14 +117,30 @@ export declare const ERROR_CODES: {
     readonly capability_id_missing: ErrorCodeSpec;
     readonly exchange_failed: ErrorCodeSpec;
     readonly identity_resolve_failed: ErrorCodeSpec;
+    readonly auth_no_credentials: ErrorCodeSpec;
+    readonly identity_missing_organization: ErrorCodeSpec;
     readonly session_expired: ErrorCodeSpec;
+    readonly jwt_invalid: ErrorCodeSpec;
+    readonly jwt_malformed: ErrorCodeSpec;
+    readonly jwt_missing_issuer: ErrorCodeSpec;
+    readonly jwt_issuer_untrusted: ErrorCodeSpec;
+    readonly jwt_signature_invalid: ErrorCodeSpec;
+    readonly jwt_audience_mismatch: ErrorCodeSpec;
+    readonly jwt_missing_subject: ErrorCodeSpec;
+    readonly jwt_missing_organization: ErrorCodeSpec;
+    readonly jwt_expired: ErrorCodeSpec;
+    readonly jwt_org_membership_denied: ErrorCodeSpec;
     readonly file_upload_auth_required: ErrorCodeSpec;
     readonly browser_apikey_blocked: ErrorCodeSpec;
+    readonly browser_database_url_blocked: ErrorCodeSpec;
+    readonly datasource_registration_failed: ErrorCodeSpec;
     readonly capability_scope_denied: ErrorCodeSpec;
+    readonly issuer_register_forbidden: ErrorCodeSpec;
     readonly capability_invalid: ErrorCodeSpec;
     readonly byo_role_cannot_enforce_rls: ErrorCodeSpec;
     readonly byo_role_unreadable: ErrorCodeSpec;
     readonly byo_tenant_tables_unforced_rls: ErrorCodeSpec;
+    readonly byo_host_not_allowed: ErrorCodeSpec;
     readonly claim_conflict: ErrorCodeSpec;
     readonly claim_lost: ErrorCodeSpec;
     readonly entity_claimed: ErrorCodeSpec;
@@ -92,6 +156,7 @@ export declare const ERROR_CODES: {
     readonly commit_operation_required: ErrorCodeSpec;
     readonly commit_operation_model_required: ErrorCodeSpec;
     readonly commit_operations_ambiguous: ErrorCodeSpec;
+    readonly commit_too_many_operations: ErrorCodeSpec;
     readonly model_required_field_missing: ErrorCodeSpec;
     readonly model_identifier_missing: ErrorCodeSpec;
     readonly snapshot_reserved_key: ErrorCodeSpec;
@@ -103,6 +168,11 @@ export declare const ERROR_CODES: {
     readonly model_not_found: ErrorCodeSpec;
     readonly mutate_update_entity_not_found: ErrorCodeSpec;
     readonly task_id_missing: ErrorCodeSpec;
+    readonly not_null_violation: ErrorCodeSpec;
+    readonly foreign_key_violation: ErrorCodeSpec;
+    readonly unique_violation: ErrorCodeSpec;
+    readonly check_violation: ErrorCodeSpec;
+    readonly constraint_violation: ErrorCodeSpec;
     readonly server_execute_unknown_model: ErrorCodeSpec;
     readonly mutate_create_unknown_model: ErrorCodeSpec;
     readonly tenant_model_columns_unknown: ErrorCodeSpec;
@@ -146,15 +216,18 @@ export declare const ERROR_CODES: {
     readonly queue_too_deep: ErrorCodeSpec;
     readonly flush_timeout: ErrorCodeSpec;
     readonly wait_for_timeout: ErrorCodeSpec;
+    readonly instance_at_capacity: ErrorCodeSpec;
     readonly fetch_unavailable: ErrorCodeSpec;
     readonly base_url_missing: ErrorCodeSpec;
     readonly sync_not_ready: ErrorCodeSpec;
     readonly ws_not_ready: ErrorCodeSpec;
     readonly quota_exceeded: ErrorCodeSpec;
+    readonly connection_limit_exceeded: ErrorCodeSpec;
     readonly internal_error: ErrorCodeSpec;
     readonly quota_lookup_failed: ErrorCodeSpec;
     readonly turn_open_failed: ErrorCodeSpec;
     readonly turn_close_failed: ErrorCodeSpec;
+    readonly invalid_options: ErrorCodeSpec;
     readonly no_ablo_provider: ErrorCodeSpec;
     readonly no_sync_group_provider: ErrorCodeSpec;
     readonly sync_context_missing_provider: ErrorCodeSpec;
@@ -189,6 +262,7 @@ export declare const ERROR_CODES: {
     readonly mutator_registry_unnamed_def: ErrorCodeSpec;
     readonly mutators_schema_missing: ErrorCodeSpec;
     readonly undo_scope_schema_missing: ErrorCodeSpec;
+    readonly undo_entry_invalid: ErrorCodeSpec;
     readonly mock_mutation_failed: ErrorCodeSpec;
     readonly mock_unsupported_operation: ErrorCodeSpec;
     readonly invalid_body: ErrorCodeSpec;
@@ -262,3 +336,20 @@ export declare function errorCodeSpec(code: string): ErrorCodeSpec | undefined;
 /** Whether a code's spec marks it retryable. Unknown / dynamic codes
  *  default to non-retryable (safe default — don't auto-retry the unknown). */
 export declare function isRetryableCode(code: string): boolean;
+/**
+ * Classify a `code` into its {@link RecoveryClass} — the single discriminant
+ * the connection FSM and the network probe branch on.
+ *
+ * The registry stays the source of truth: an explicit `spec.recovery` wins
+ * (set only on the few auth codes whose remedy the status can't reveal), and
+ * everything else is DERIVED from the spec so the registry stays terse:
+ *   - retryable                → `transient`
+ *   - 403                      → `permission`
+ *   - residual `auth`-category → `auth_blocked` (the 401 credential-type codes)
+ *   - otherwise / unknown      → `none`
+ *
+ * Unknown / dynamic `policy:*` / forward-compat codes (`spec === undefined`)
+ * default to `none`, mirroring {@link isRetryableCode}'s safe default — never
+ * silently treat an unrecognised code as a credential expiry or a logout.
+ */
+export declare function classifyRecovery(code: string): RecoveryClass;