@abloatai/ablo 0.7.0 → 0.9.0

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-28';
-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,21 +85,53 @@ 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.'),
     exchange_failed: wire('auth', 401, false, 'The API-key credential exchange was rejected.'),
     identity_resolve_failed: wire('auth', 401, false, 'Identity resolution was rejected.'),
-    session_expired: wire('auth', 401, false, 'The session is invalid or expired; re-authenticate.'),
+    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.'),
+    // 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"
+    // rather than getting one opaque code for all of them.
+    jwt_invalid: wire('auth', 401, false, 'The bearer JWT could not be validated (unclassified).'),
+    jwt_malformed: wire('auth', 401, false, 'The bearer JWT is not a well-formed JWT and could not be decoded.'),
+    jwt_missing_issuer: wire('auth', 401, false, 'The bearer JWT has no `iss` (issuer) claim, so it cannot be routed to a trusted issuer.'),
+    jwt_issuer_untrusted: wire('auth', 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Register it via POST /v1/trusted-issuers, or check the token's issuer claim."),
+    jwt_signature_invalid: wire('auth', 401, false, "The bearer JWT's signature could not be verified against the issuer's JWKS (wrong key, rotated key, or forged token)."),
+    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.'),
+    // 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 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.'),
@@ -80,6 +150,7 @@ export const ERROR_CODES = {
     commit_operation_required: wire('validation', 400, false, 'A commit must carry `operation` or `operations`.'),
     commit_operation_model_required: wire('validation', 400, false, 'A commit operation is missing its `model`.'),
     commit_operations_ambiguous: wire('validation', 400, false, 'A commit supplied both `operation` and `operations`.'),
+    commit_too_many_operations: wire('validation', 400, false, 'A commit exceeded the per-commit operation limit; split it into smaller batches.'),
     model_required_field_missing: wire('validation', 400, false, 'A required field was absent from the model payload.'),
     model_identifier_missing: wire('validation', 400, false, 'The model payload is missing its identifier.'),
     snapshot_reserved_key: wire('validation', 400, false, 'A snapshot used a reserved key name.'),
@@ -92,6 +163,18 @@ export const ERROR_CODES = {
     model_not_found: wire('not_found', 404, false, 'The referenced model row does not exist.'),
     mutate_update_entity_not_found: wire('not_found', 404, false, 'The entity targeted by an update does not exist.'),
     task_id_missing: wire('server', 502, true, 'The task-create response did not include an id.'),
+    // ── data integrity / DB constraints ────────────────────────────────
+    // Emitted when a write is rejected by a database integrity constraint
+    // (Postgres class-23). All NON-retryable: the same payload re-sent
+    // unchanged will fail identically, so the client must roll back, not
+    // retry. The server normalizer maps SQLSTATE → these codes and tucks the
+    // raw constraint/column/table detail into `details` rather than leaking
+    // the driver's message text onto the wire.
+    not_null_violation: wire('validation', 400, false, 'A required field was missing (database not-null constraint).'),
+    foreign_key_violation: wire('conflict', 409, false, 'A referenced entity does not exist, or is still referenced (database foreign-key constraint).'),
+    unique_violation: wire('conflict', 409, false, 'A value violates a uniqueness constraint.'),
+    check_violation: wire('validation', 400, false, 'A value violates a database check constraint.'),
+    constraint_violation: wire('validation', 400, false, 'A database integrity constraint was violated.'),
     // ── tenant / unknown model (400) ───────────────────────────────────
     server_execute_unknown_model: wire('tenant', 400, false, 'The server-execute request named a model not in the tenant schema.'),
     mutate_create_unknown_model: wire('tenant', 400, false, 'A create targeted a model not in the tenant schema.'),
@@ -140,18 +223,21 @@ 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.'),
     turn_open_failed: wire('server', 500, true, 'The agent turn failed to open.'),
     turn_close_failed: wire('server', 500, true, 'The agent turn failed to close cleanly.'),
     // ── client-only invariants (never serialized) ──────────────────────
+    invalid_options: client('client', 'The Ablo client was constructed with invalid or incomplete options.'),
     no_ablo_provider: client('client', 'An Ablo hook was used outside of an Ablo provider.'),
     no_sync_group_provider: client('client', 'A sync-group hook was used outside of its provider.'),
     sync_context_missing_provider: client('client', 'Sync context was read outside of its provider.'),
@@ -186,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) ─────────────
@@ -249,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
@@ -272,11 +272,62 @@ export declare class SyncSessionError extends AbloAuthenticationError {
      */
     static isSessionErrorResponse(status: number, body?: string): boolean;
 }
+/**
+ * Coerce ANY thrown value into an {@link AbloError} — the last-line guarantee
+ * that an SDK consumer never catches an untagged error. An already-typed
+ * AbloError passes through untouched (so `code`/`httpStatus`/subclass survive);
+ * a bare `Error` keeps its message and is preserved as `cause` (carrying any
+ * `.code` someone attached); a non-Error is stringified.
+ *
+ * This is the client mirror of the server's `normalizeError` — applied at the
+ * SDK's public async boundaries so `instanceof AbloError` / `e.type` always
+ * hold for whatever a consumer catches, regardless of which internal layer
+ * (transport, IndexedDB, bootstrap, a third-party throw) produced it.
+ */
+export declare function toAbloError(err: unknown): AbloError;
+/**
+ * Build the appropriate typed {@link AbloError} from a wire error — the
+ * single code→class mapping shared by every transport that can reject a
+ * request (HTTP responses via {@link translateHttpError}, WebSocket
+ * `mutation_result`/`claim_ack` frames, agent-job receipts).
+ *
+ * Code-first, then status-driven. A known {@link ErrorCode} carries its own
+ * canonical `httpStatus` in the registry, so frame transports that don't have
+ * an HTTP status (the WebSocket commit path) still produce the right subclass
+ * — instead of a hand-rolled `new Error(message)` that drops out of the typed
+ * hierarchy and loses `code`/`httpStatus`/retryability.
+ */
+export declare function errorFromWire(message: string, opts?: {
+    code?: string;
+    /** Explicit transport status (HTTP). When omitted, derived from the
+     *  registry spec for `code` so frame transports map correctly too. */
+    httpStatus?: number;
+    requestId?: string;
+    requiredCapability?: RequiredCapability;
+}): AbloError;
 /**
  * Translate an HTTP response into the appropriate typed error.
  *
  * Single source of truth for status-code → class mapping — every SDK
  * fetch path that sees a non-2xx response should route through here
- * so the customer-visible error is always the right subclass.
+ * so the customer-visible error is always the right subclass. Delegates
+ * the actual class selection to {@link errorFromWire} (shared with the
+ * frame transports) after extracting code/message from the HTTP body.
  */
 export declare function translateHttpError(status: number, body: unknown, requestId?: string): AbloError;
+/**
+ * Whether an HTTP error body carries a code {@link translateHttpError} can read
+ * — a top-level `code`, a nested `error.code`, or a string `error`. Callers that
+ * own a meaningful fallback code (e.g. `turn_open_failed`) use this to decide
+ * between routing through `translateHttpError` (structured envelope present) and
+ * throwing their own typed error with the fallback (bare/non-Ablo body), instead
+ * of emitting a code-less error.
+ */
+export declare function hasWireCode(body: unknown): boolean;
+/**
+ * Extract the canonical error `code` from a raw HTTP error body STRING — the
+ * top-level `code` or a nested `error.code`. Returns undefined for non-JSON or
+ * code-less bodies. Used by session-error detection to tell a genuine expiry
+ * (`session_expired`/`jwt_expired`) apart from other auth failures.
+ */
+export declare function extractWireCode(body?: string): string | undefined;

package/dist/errors.js

@@ -18,7 +18,9 @@
  *
  * Both work on every subclass.
  */
-export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode } from './errorCodes.js';
+import { z } from 'zod';
+import { errorCodeSpec, classifyRecovery } from './errorCodes.js';
+export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errorCodes.js';
 // ── AbloError hierarchy — the typed error surface ────────────────────
 /** Common shape for all errors thrown by this SDK. */
 export class AbloError extends Error {
@@ -237,32 +239,160 @@ export class SyncSessionError extends AbloAuthenticationError {
      * Check if an HTTP response status indicates a session error
      */
     static isSessionErrorResponse(status, body) {
-        if (status === 401)
-            return true;
-        if (status === 403) {
-            if (body) {
-                const lowerBody = body.toLowerCase();
-                if (lowerBody.includes('session') ||
-                    lowerBody.includes('unauthorized') ||
-                    lowerBody.includes('not authenticated') ||
-                    lowerBody.includes('token')) {
-                    return true;
-                }
-            }
-            return true;
+        // "Should this response sign the user out?" — TRUE only for a genuine
+        // expiry of the LONG-LIVED login (`recovery: 'session_expiry'`). Decided
+        // via the closed recovery taxonomy rather than a hardcoded code list, so
+        // the access-vs-session split lives in one place (errorCodes.ts). This is
+        // behaviourally identical to the old `session_expired || jwt_expired` list.
+        //
+        // Deliberately NOT true for `access_credential_expiry` (`apikey_expired` —
+        // the Stripe-style ephemeral key): an expired `ek_`/`rk_` is re-mintable
+        // from the still-valid login and must NOT log the user out — the connection
+        // layer silently re-mints instead. Likewise NOT true for `auth_blocked` /
+        // `permission` failures (api_key_required, jwt_issuer_untrusted, 403s):
+        // re-auth re-mints the same rejected credential and loops ("flash then
+        // bounce to /signin").
+        const code = extractWireCode(body);
+        if (code) {
+            return classifyRecovery(code) === 'session_expiry';
         }
-        return false;
+        // No structured code (bare body, non-Ablo proxy response): a 401 is taken as
+        // expiry — the historical default that drives re-auth — while a 403 is a
+        // permission failure, not a session error.
+        return status === 401;
     }
 }
+// ── HTTP → class mapping ──────────────────────────────────────────────
+const OptionalWireStringSchema = z.preprocess((value) => (typeof value === 'string' ? value : undefined), z.string().optional());
+const RequiredCapabilityWireSchema = z
+    .object({
+    scope: z.string(),
+    constraints: z
+        .record(z.string(), z.union([z.array(z.string()), z.string()]))
+        .optional(),
+    issuer: OptionalWireStringSchema,
+    ttlSeconds: z
+        .preprocess((value) => (typeof value === 'number' ? value : undefined), z.number().optional()),
+    nonce: OptionalWireStringSchema,
+})
+    .passthrough();
+const NestedErrorShapeSchema = z
+    .object({
+    code: OptionalWireStringSchema,
+    message: OptionalWireStringSchema,
+    field: OptionalWireStringSchema,
+    requiredCapability: RequiredCapabilityWireSchema.optional().catch(undefined),
+})
+    .passthrough();
+const ErrorFieldSchema = z
+    .preprocess((value) => typeof value === 'string' || (typeof value === 'object' && value !== null)
+    ? value
+    : undefined, z.union([z.string(), NestedErrorShapeSchema]).optional())
+    .catch(undefined);
+const ErrorBodyShapeSchema = z
+    .object({
+    /** Legacy: `error` was a flat code string on older endpoints. Newer
+     *  endpoints (CommitReceipt) carry `error` as a nested object. */
+    error: ErrorFieldSchema,
+    code: OptionalWireStringSchema,
+    reason: OptionalWireStringSchema,
+    message: OptionalWireStringSchema,
+    requiredCapability: RequiredCapabilityWireSchema.optional().catch(undefined),
+})
+    .passthrough();
+function parseErrorBodyShape(body) {
+    if (typeof body !== 'object' || body === null)
+        return {};
+    const parsed = ErrorBodyShapeSchema.safeParse(body);
+    return parsed.success ? parsed.data : {};
+}
+/**
+ * Coerce ANY thrown value into an {@link AbloError} — the last-line guarantee
+ * that an SDK consumer never catches an untagged error. An already-typed
+ * AbloError passes through untouched (so `code`/`httpStatus`/subclass survive);
+ * a bare `Error` keeps its message and is preserved as `cause` (carrying any
+ * `.code` someone attached); a non-Error is stringified.
+ *
+ * This is the client mirror of the server's `normalizeError` — applied at the
+ * SDK's public async boundaries so `instanceof AbloError` / `e.type` always
+ * hold for whatever a consumer catches, regardless of which internal layer
+ * (transport, IndexedDB, bootstrap, a third-party throw) produced it.
+ */
+export function toAbloError(err) {
+    if (err instanceof AbloError)
+        return err;
+    if (err instanceof Error) {
+        const rawCode = err.code;
+        const code = typeof rawCode === 'string' ? rawCode : undefined;
+        return new AbloError(err.message, { code, cause: err });
+    }
+    return new AbloError(String(err), { cause: err });
+}
+/**
+ * Build the appropriate typed {@link AbloError} from a wire error — the
+ * single code→class mapping shared by every transport that can reject a
+ * request (HTTP responses via {@link translateHttpError}, WebSocket
+ * `mutation_result`/`claim_ack` frames, agent-job receipts).
+ *
+ * Code-first, then status-driven. A known {@link ErrorCode} carries its own
+ * canonical `httpStatus` in the registry, so frame transports that don't have
+ * an HTTP status (the WebSocket commit path) still produce the right subclass
+ * — instead of a hand-rolled `new Error(message)` that drops out of the typed
+ * hierarchy and loses `code`/`httpStatus`/retryability.
+ */
+export function errorFromWire(message, opts = {}) {
+    const { code, requestId, requiredCapability } = opts;
+    // Effective status: an explicit HTTP status wins; otherwise fall back to
+    // the code's canonical status from the registry (undefined for unknown /
+    // forward-compat codes, which then map to the base AbloError).
+    const httpStatus = opts.httpStatus ?? (code ? errorCodeSpec(code)?.httpStatus : undefined);
+    // Wire boundary: an incoming code is an arbitrary string (a newer server
+    // may send a code this SDK predates). Cast to ErrorCode here — the one
+    // sanctioned crossing — so internal producers stay statically checked.
+    const publicCode = (code === 'intent_conflict' ? 'claim_conflict' : code);
+    const baseOpts = { code: publicCode, httpStatus, requestId };
+    // ── Code-first specials (transport-independent) ──────────────────────
+    // A scoped credential was denied — route through CapabilityError so callers
+    // can read `.requiredCapability` to attenuate-and-retry.
+    if (code === 'capability_scope_denied' || code === 'capability_invalid') {
+        return new CapabilityError(code, message, requiredCapability);
+    }
+    // Claim enforcement (rides 409): the target entity is held by another
+    // participant. Discriminate on code BEFORE the generic 409→idempotency
+    // mapping so a claim rejection surfaces as AbloClaimedError.
+    if (code === 'intent_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
+        return new AbloClaimedError(message, baseOpts);
+    }
+    // A write whose `readAt` watermark went stale — callers re-read and retry.
+    if (code === 'stale_context') {
+        return new AbloStaleContextError(message, baseOpts);
+    }
+    // ── Status-driven dispatch (HTTP parity) ─────────────────────────────
+    if (httpStatus === 401)
+        return new AbloAuthenticationError(message, baseOpts);
+    if (httpStatus === 403)
+        return new AbloPermissionError(message, baseOpts);
+    if (httpStatus === 409)
+        return new AbloIdempotencyError(message, baseOpts);
+    if (httpStatus === 422 || httpStatus === 400)
+        return new AbloValidationError(message, baseOpts);
+    if (httpStatus === 429)
+        return new AbloRateLimitError(message, baseOpts);
+    if (httpStatus !== undefined && httpStatus >= 500)
+        return new AbloServerError(message, baseOpts);
+    return new AbloError(message, baseOpts);
+}
 /**
  * Translate an HTTP response into the appropriate typed error.
  *
  * Single source of truth for status-code → class mapping — every SDK
  * fetch path that sees a non-2xx response should route through here
- * so the customer-visible error is always the right subclass.
+ * so the customer-visible error is always the right subclass. Delegates
+ * the actual class selection to {@link errorFromWire} (shared with the
+ * frame transports) after extracting code/message from the HTTP body.
  */
 export function translateHttpError(status, body, requestId) {
-    const parsed = typeof body === 'object' && body !== null ? body : {};
+    const parsed = parseErrorBodyShape(body);
     const nested = parsed.error != null && typeof parsed.error === 'object'
         ? parsed.error
         : undefined;
@@ -274,33 +404,51 @@ export function translateHttpError(status, body, requestId) {
         flatError ??
         (typeof body === 'string' ? body : `HTTP ${status}`);
     const requiredCapability = nested?.requiredCapability ?? parsed.requiredCapability;
-    // Wire boundary: an incoming code is an arbitrary string (a newer server
-    // may send a code this SDK predates). Cast to ErrorCode here — the one
-    // sanctioned crossing — so internal producers stay statically checked.
-    const publicCode = (code === 'intent_conflict' ? 'claim_conflict' : code);
-    const baseOpts = { code: publicCode, httpStatus: status, requestId };
-    if (status === 401)
-        return new AbloAuthenticationError(message, baseOpts);
-    if (status === 403 || code === 'capability_scope_denied' || code === 'capability_invalid') {
-        if (code === 'capability_scope_denied' || code === 'capability_invalid') {
-            return new CapabilityError(code, message, requiredCapability);
-        }
-        return new AbloPermissionError(message, baseOpts);
+    return errorFromWire(message, { code, httpStatus: status, requestId, requiredCapability });
+}
+/**
+ * Whether an HTTP error body carries a code {@link translateHttpError} can read
+ * — a top-level `code`, a nested `error.code`, or a string `error`. Callers that
+ * own a meaningful fallback code (e.g. `turn_open_failed`) use this to decide
+ * between routing through `translateHttpError` (structured envelope present) and
+ * throwing their own typed error with the fallback (bare/non-Ablo body), instead
+ * of emitting a code-less error.
+ */
+export function hasWireCode(body) {
+    const parsed = parseErrorBodyShape(body);
+    if (typeof parsed.code === 'string')
+        return true;
+    if (typeof parsed.error === 'string')
+        return true;
+    return (typeof parsed.error === 'object' &&
+        parsed.error !== null &&
+        typeof parsed.error.code === 'string');
+}
+/**
+ * Extract the canonical error `code` from a raw HTTP error body STRING — the
+ * top-level `code` or a nested `error.code`. Returns undefined for non-JSON or
+ * code-less bodies. Used by session-error detection to tell a genuine expiry
+ * (`session_expired`/`jwt_expired`) apart from other auth failures.
+ */
+export function extractWireCode(body) {
+    if (!body)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
     }
-    // Claim enforcement also rides 409 (a commit blocked by a foreign claim).
-    // Discriminate on the code BEFORE the generic idempotency mapping so a
-    // claim rejection surfaces as AbloClaimedError, not AbloIdempotencyError —
-    // same typed error the WebSocket commit path yields for these codes.
-    if (code === 'intent_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
-        return new AbloClaimedError(message, baseOpts);
+    catch {
+        return undefined;
     }
-    if (status === 409)
-        return new AbloIdempotencyError(message, baseOpts);
-    if (status === 422 || status === 400)
-        return new AbloValidationError(message, baseOpts);
-    if (status === 429)
-        return new AbloRateLimitError(message, baseOpts);
-    if (status >= 500)
-        return new AbloServerError(message, baseOpts);
-    return new AbloError(message, baseOpts);
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const b = parseErrorBodyShape(parsed);
+    if (typeof b.code === 'string')
+        return b.code;
+    if (typeof b.error === 'string')
+        return b.error;
+    if (typeof b.error === 'object' && b.error !== null && typeof b.error.code === 'string') {
+        return b.error.code;
+    }
+    return undefined;
 }

package/dist/index.d.ts

@@ -5,8 +5,11 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
- * await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
+ * const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+ * await ablo.weatherReports.update({
+ *   id: 'report_stockholm',
+ *   data: { status: 'ready' },
+ * });
  *
  * type Entry = Ablo.Peer;
  * ```
@@ -23,13 +26,17 @@
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
  *   @abloatai/ablo/testing  — test harnesses + mocks
  *
- * Consumer code should converge on `ablo.<model>.load(...)`, which routes
- * through the engine's `HydrationCoordinator` and dedupes single-flight
- * hydrations.
+ * Reads split by where the data comes from. `ablo.<model>.retrieve({ id })` and
+ * `.list({ where })` are the async **server** reads (pool → IDB → network via
+ * the `HydrationCoordinator`, single-flight deduped); they're the default and
+ * what hosted/stateless callers want, since their local graph starts empty.
+ * `ablo.<model>.get(id)` / `.getAll(...)` / `.getCount(...)` are synchronous
+ * **local-graph** snapshots with no network round-trip — for reactive React
+ * selectors (`useAblo((ablo) => ablo.<model>.get(id))`) once the graph is warm.
  *
  * ── What to import (read this first) ────────────────────────────────
  * Default path — this is all most apps and agents ever need:
- *   • `Ablo` (default export) + `AbloOptions` + the `Model*Options` bags
+ *   • `Ablo` (default export) + `AbloOptions` + the `Model*Params` bags
  *   • the `Ablo*Error` classes, to discriminate failures in catch blocks
  * That's it. If you're reaching past those, you're in advanced territory.
  *
@@ -42,16 +49,22 @@
  * If you don't recognize one, you don't need it — the default path covers you.
  */
 export { Ablo } from './client/Ablo.js';
-export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ClaimOptions, ClaimedRow, ModelOperations, } from './client/Ablo.js';
+export type { MutationExecutor } from './interfaces/index.js';
+export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
+export { createAbloHttpClient, type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
+export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
 export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
-export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
-export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec } from './errors.js';
+export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
+export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
+export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';