@abloatai/ablo 0.8.0 → 0.9.0

package/dist/client/validateAbloOptions.js

@@ -16,7 +16,7 @@ export function validateAbloOptions(input) {
     const kind = options.kind ?? 'user';
     if (!url) {
         return new AbloValidationError('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
-            `Ablo({ baseURL: 'wss://sync.abloatai.com', schema, user })`, { code: 'base_url_missing' });
+            `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(...)

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-29";
+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
@@ -92,6 +140,7 @@ export declare const ERROR_CODES: {
     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;
@@ -167,11 +216,13 @@ 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;
@@ -211,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;
@@ -284,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;

package/dist/errorCodes.js

@@ -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,8 +37,45 @@
  * 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 const ERROR_CONTRACT_VERSION = '2026-05-29';
-const wire = (category, httpStatus, retryable, message) => ({ category, surface: 'wire', httpStatus, retryable, message });
+export const ERROR_CONTRACT_VERSION = '2026-06-02';
+/**
+ * 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 const RECOVERY_CLASSES = [
+    '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 const recoveryClassSchema = z.enum(RECOVERY_CLASSES);
+const wire = (category, httpStatus, retryable, message, recovery) => ({ category, surface: 'wire', httpStatus, retryable, message, recovery });
 const client = (category, message) => ({ category, surface: 'client', retryable: false, message });
 /**
  * The closed set of stable error codes. Add a code here BEFORE throwing it
@@ -47,7 +85,13 @@ export const ERROR_CODES = {
     // ── auth (401) ─────────────────────────────────────────────────────
     apikey_invalid: wire('auth', 401, false, 'API key is unknown or malformed.'),
     apikey_revoked: wire('auth', 401, false, 'API key has been revoked.'),
-    apikey_expired: wire('auth', 401, false, 'API key has expired.'),
+    // THE sync-engine access credential — the Stripe-style ephemeral key
+    // (`ek_` for users, `rk_` for agents) minted server-side from the login and
+    // presented as a Bearer. Its expiry is routine and re-mintable: get a fresh
+    // key from the still-valid session and retry — NEVER a sign-out. (An agent's
+    // expired `rk_` must not log a human out either.) This is the ONLY code on
+    // the silent re-mint path; see RecoveryClass `access_credential_expiry`.
+    apikey_expired: wire('auth', 401, false, 'API key has expired.', 'access_credential_expiry'),
     apikey_missing: wire('auth', 401, false, 'No API key was supplied on the request.'),
     api_key_required: wire('auth', 401, false, 'This operation requires an API key.'),
     capability_id_missing: wire('auth', 401, false, 'A capability id was expected but not provided.'),
@@ -55,7 +99,8 @@ export const ERROR_CODES = {
     identity_resolve_failed: wire('auth', 401, false, 'Identity resolution was rejected.'),
     auth_no_credentials: wire('auth', 401, false, 'No recognized authentication credential was presented — no API key and no bearer JWT. Send `Authorization: Bearer <token>`.'),
     identity_missing_organization: wire('auth', 401, false, 'Authentication succeeded but resolved to no organization context.'),
-    session_expired: wire('auth', 401, false, 'The session is invalid or expired; re-authenticate.'),
+    // The long-lived login is gone — terminal, drives sign-out + re-auth.
+    session_expired: wire('auth', 401, false, 'The session is invalid or expired; re-authenticate.', 'session_expiry'),
     // `jwt_invalid` is the residual fallback; the codes below split out the
     // specific failure modes so an integrating customer can tell "I registered
     // the wrong JWKS" from "my token has no org claim" from "wrong audience"
@@ -68,19 +113,25 @@ export const ERROR_CODES = {
     jwt_audience_mismatch: wire('auth', 401, false, "The bearer JWT's `aud` (audience) claim does not match the audience this issuer is registered with."),
     jwt_missing_subject: wire('auth', 401, false, 'The bearer JWT has no `sub` (subject) claim to identify the user.'),
     jwt_missing_organization: wire('auth', 401, false, 'The bearer JWT carries no organization context — neither a fixed org for the issuer nor the configured organization claim.'),
-    jwt_expired: wire('auth', 401, false, 'The bearer JWT has expired; obtain a fresh token.'),
+    // Trusted-issuer / BYO-IdP path only — Ablo's own sync-engine no longer
+    // authenticates with JWTs (it uses the Stripe-style ephemeral key, below).
+    // When a customer DOES present an external-IdP JWT, its expiry means
+    // re-authenticate against that IdP, so it classifies as a session expiry
+    // (which also keeps `isSessionErrorResponse` behaviour unchanged).
+    jwt_expired: wire('auth', 401, false, 'The bearer JWT has expired; obtain a fresh token.', 'session_expiry'),
     jwt_org_membership_denied: wire('auth', 403, false, "The bearer JWT's subject is not an active member of the organization in its `org_id` claim (removed, suspended, or the claim does not match a membership)."),
     file_upload_auth_required: wire('auth', 401, false, 'File upload requires an authenticated session.'),
     browser_apikey_blocked: client('auth', 'Raw API keys must not be used from a browser context.'),
     browser_database_url_blocked: client('auth', 'A database connection string must not be used from a browser context — it carries DB credentials.'),
-    datasource_registration_failed: client('auth', 'Failed to register the provided databaseUrl as this project data source.'),
+    datasource_registration_failed: client('auth', 'Failed to register the provided databaseUrl for the direct Postgres connector.'),
     // ── permission / capability (403) ──────────────────────────────────
     capability_scope_denied: wire('capability', 403, false, "The connection's resolved scope does not cover the attempted action."),
     issuer_register_forbidden: wire('permission', 403, false, 'Registering a trusted issuer requires a secret (sk_) API key.'),
     capability_invalid: wire('capability', 403, false, 'The capability is unknown, revoked, or expired.'),
-    byo_role_cannot_enforce_rls: wire('permission', 403, false, 'The bring-your-own DB role cannot enforce row-level security.'),
-    byo_role_unreadable: wire('permission', 403, false, 'The bring-your-own DB role could not be introspected.'),
-    byo_tenant_tables_unforced_rls: wire('permission', 403, false, 'Tenant tables do not have RLS forced under the BYO role.'),
+    byo_role_cannot_enforce_rls: wire('permission', 403, false, 'The direct Postgres connector role cannot enforce row-level security.'),
+    byo_role_unreadable: wire('permission', 403, false, 'The direct Postgres connector role could not be introspected.'),
+    byo_tenant_tables_unforced_rls: wire('permission', 403, false, 'Tenant tables do not have RLS forced under the direct Postgres connector role.'),
+    byo_host_not_allowed: wire('permission', 403, false, 'The direct Postgres connector host resolves to a private, loopback, or link-local address and cannot be used.'),
     // ── claim / intent conflict (409) ──────────────────────────────────
     claim_conflict: wire('claim', 409, true, 'The target entity is claimed by another participant.'),
     claim_lost: wire('claim', 409, true, 'A previously held claim was lost before the write applied.'),
@@ -172,12 +223,14 @@ export const ERROR_CODES = {
     queue_too_deep: wire('transport', 503, true, 'The transaction queue exceeded its depth limit.'),
     flush_timeout: wire('transport', 504, true, 'Timed out flushing the transaction queue.'),
     wait_for_timeout: wire('transport', 504, true, 'A wait-for condition timed out.'),
+    instance_at_capacity: wire('transport', 503, true, 'The server is at connection capacity. Retry shortly — transient and not specific to your credentials.'),
     fetch_unavailable: client('transport', 'No fetch implementation is available in this environment.'),
     base_url_missing: client('transport', 'No base URL was configured for the client.'),
     sync_not_ready: client('transport', 'A sync operation was attempted before the client was ready.'),
     ws_not_ready: client('transport', 'A frame was sent before the WebSocket was connected.'),
     // ── quota / rate limit (429) ──────────────────────────────────────
     quota_exceeded: wire('rate_limit', 429, true, 'The organization exceeded its configured usage quota.'),
+    connection_limit_exceeded: wire('rate_limit', 429, true, 'Too many concurrent WebSocket connections for this principal or organization. Close idle connections, or retry once others drain.'),
     // ── server (5xx) ───────────────────────────────────────────────────
     internal_error: wire('server', 500, true, 'An unexpected server error occurred.'),
     quota_lookup_failed: wire('server', 503, true, 'The quota decision could not be loaded.'),
@@ -219,6 +272,7 @@ export const ERROR_CODES = {
     mutator_registry_unnamed_def: client('client', 'A mutator definition was registered without a name.'),
     mutators_schema_missing: client('client', 'Mutators were registered without a schema.'),
     undo_scope_schema_missing: client('client', 'An undo scope was opened without a schema.'),
+    undo_entry_invalid: client('client', 'An undo entry failed inverse-op schema validation.'),
     mock_mutation_failed: client('client', 'A mock mutation adapter was configured to fail.'),
     mock_unsupported_operation: client('client', 'A mock adapter received an unsupported operation.'),
     // ── HTTP route edge codes (egress through app.onError) ─────────────
@@ -282,3 +336,48 @@ export function errorCodeSpec(code) {
 export function isRetryableCode(code) {
     return errorCodeSpec(code)?.retryable ?? false;
 }
+/**
+ * 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 function classifyRecovery(code) {
+    const spec = errorCodeSpec(code);
+    if (!spec)
+        return 'none';
+    if (spec.recovery)
+        return spec.recovery;
+    if (spec.retryable)
+        return 'transient';
+    if (spec.httpStatus === 403)
+        return 'permission';
+    if (spec.category === 'auth')
+        return 'auth_blocked';
+    return 'none';
+}
+/**
+ * Compile-time exhaustiveness guard: forces every {@link RecoveryClass} to be
+ * acknowledged here, so adding a class to {@link RECOVERY_CLASSES} without
+ * deciding its meaning is a type error rather than a silent gap. (Mirrors the
+ * closed-union discipline `ERROR_CODES` itself uses via `satisfies`.)
+ */
+const _RECOVERY_CLASS_EXHAUSTIVE = {
+    access_credential_expiry: true,
+    session_expiry: true,
+    auth_blocked: true,
+    permission: true,
+    transient: true,
+    none: true,
+};
+void _RECOVERY_CLASS_EXHAUSTIVE;

package/dist/errors.d.ts

@@ -19,8 +19,8 @@
  * Both work on every subclass.
  */
 import type { ErrorCode } from './errorCodes.js';
-export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec } from './errorCodes.js';
-export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode } from './errorCodes.js';
+export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errorCodes.js';
+export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errorCodes.js';
 /** Common shape for all errors thrown by this SDK. */
 export declare class AbloError extends Error {
     /** Discriminator string — matches the class name. Lets consumers