@abloatai/ablo 0.25.0 → 0.27.0

package/dist/core/storeContract.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The framework-neutral store contract. {@link SyncStoreContract} is the minimal
+ * store interface the SDK's hooks and mutators are written against, and
+ * {@link BaseSyncedStore} is the concrete class that implements it. Framework
+ * integrations, such as the React bindings, re-export these types, so a hook can
+ * accept any store that satisfies the contract without depending on a particular
+ * UI framework.
+ *
+ * This module is type-only: it has no runtime imports and contributes nothing to
+ * the runtime bundle beyond the erased interface declarations.
+ */
+import type { Model } from '../Model.js';
+import type { ModelScope } from '../types/index.js';
+import type { QueryView, QueryViewOptions } from './QueryView.js';
+import type { ViewRegistry } from './ViewRegistry.js';
+import type { ParticipantScope } from '../sync/participants.js';
+/**
+ * A snapshot of the client's synchronization state, shaped for binding to UI.
+ * {@link SyncStoreContract.syncStatus} exposes a reactive instance of this, and
+ * the `useSyncStatus()` hook reads its fields to render connection and progress
+ * indicators.
+ */
+export interface SyncStatus {
+    state: 'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting';
+    progress: number;
+    error?: Error;
+    /** When true, the error is a session/auth error requiring re-authentication. */
+    isSessionError: boolean;
+    lastSyncAt?: Date;
+    pendingChanges: number;
+    offlineSince?: Date;
+}
+/**
+ * A single locally-originated mutation, observed as it flows through the commit
+ * stream. The undo system records these to build its inverse operations: one is
+ * emitted per local create, update, delete, or archive. Changes arriving from
+ * other participants do not appear here — they apply through a separate path
+ * that does not queue mutations. Because `previousData` captures the field
+ * values as they were before the edit, each event carries everything needed to
+ * derive its inverse, with no separate snapshot step. A store exposes this
+ * stream through {@link SyncStoreContract.subscribeLocalMutations}.
+ */
+export interface LocalMutation {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+    /** The registered name of the mutated model, for example `'SlideLayer'`. */
+    modelName: string;
+    modelId: string;
+    /** The new field values, for a create or an update. */
+    data?: Record<string, unknown> | null;
+    /** The field values as they were before the edit. For an update these form
+     *  the inverse patch; for a delete they hold the full row needed to recreate
+     *  it. */
+    previousData?: Record<string, unknown> | null;
+}
+/**
+ * The minimal store interface the SDK's hooks and mutators depend on. Provide a
+ * concrete store that implements it — {@link BaseSyncedStore} is the built-in
+ * implementation — and the hooks work against your store without knowing its
+ * exact type. Optional members exist so lightweight test doubles can implement
+ * only the parts they exercise.
+ */
+export interface SyncStoreContract {
+    /**
+     * Subscribes to the stream of local mutations for undo recording, delivering
+     * each optimistic write before it is acknowledged by the server. See
+     * {@link LocalMutation}. Returns a function that removes the subscription.
+     * This is optional: when a store does not implement it, undo scopes simply
+     * record nothing.
+     */
+    subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
+    retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
+    queryByClass(modelClass: abstract new (...args: never[]) => Model, options?: {
+        predicate?: (model: Model) => boolean;
+        scope?: ModelScope;
+        orderBy?: keyof Model;
+        order?: 'asc' | 'desc';
+        limit?: number;
+        offset?: number;
+    }): {
+        data: Model[];
+    };
+    /**
+     * Saves one entity, creating it if new or updating it if it already exists.
+     * Calling `save` repeatedly within the same tick is efficient: the writes are
+     * coalesced and persisted, then sent to the server, as a single commit. There
+     * is deliberately no bulk method — issue one `save` per row and let the tick
+     * boundary batch them.
+     *
+     * Pass `skipValidation` on trusted, high-volume paths — bulk import or
+     * hydration, where the data has already been validated — to skip the per-row
+     * schema check, which is a measurable cost at that volume.
+     */
+    save(model: Model, options?: {
+        skipValidation?: boolean;
+    }): Promise<void>;
+    delete(model: Model): Promise<void>;
+    archive(model: Model): Promise<void>;
+    unarchive(model: Model): Promise<void>;
+    /** The in-memory object pool: look up individual entities or collections by
+     *  id or model name, create views, and resolve foreign-key relationships. */
+    pool: {
+        get(id: string): Model | undefined;
+        getByTypeName(typename: string, scope?: ModelScope): Model[];
+        getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
+        createFromData(data: Record<string, unknown>): Model | null;
+        hasForeignKeyIndex(typename: string, fieldName: string): boolean;
+        createView<T extends Record<string, unknown>>(typename: string, options?: QueryViewOptions<T>): QueryView<T>;
+        viewRegistry: ViewRegistry;
+    };
+    /**
+     * Reactive getters for the current sync state. In the built-in store these
+     * are backed by observable computeds, so reading them inside a reactive
+     * context — an observer component or a reaction — re-runs that context when
+     * the state changes. Code that prefers not to work with the reactivity system
+     * directly can read the same values through the `useSyncStatus()` hook.
+     */
+    readonly isReady: boolean;
+    readonly isSyncing: boolean;
+    readonly isOffline: boolean;
+    readonly isReconnecting: boolean;
+    readonly isError: boolean;
+    readonly hasUnsyncedChanges: boolean;
+    /**
+     * Manages the connection's area of interest — the dynamic set of data it
+     * subscribes to. Call `enterScope` and `leaveScope` to move that interest as
+     * the user navigates between documents, and `pinScope` and `unpinScope` to
+     * keep a scope subscribed while it stays important, such as while a claim is
+     * held. Every scope resolves through the same resolver the claim path uses, so
+     * read subscriptions and write claims always agree on which group they refer
+     * to. These are optional and do nothing until the connection is open.
+     */
+    enterScope?(scope: ParticipantScope, opts?: {
+        hydrate?: boolean;
+    }): Promise<void>;
+    leaveScope?(scope: ParticipantScope): Promise<void>;
+    pinScope?(scope: ParticipantScope): Promise<void>;
+    unpinScope?(scope: ParticipantScope): Promise<void>;
+    /**
+     * The full reactive {@link SyncStatus} record. The `useSyncStatus()` hook
+     * reads its fields — `state`, `progress`, `pendingChanges`, `isSessionError`,
+     * and `error` — to present the current sync state. It is part of the contract
+     * so hooks and test doubles can read or set it directly.
+     */
+    readonly syncStatus: SyncStatus;
+}

package/dist/core/storeContract.js

@@ -0,0 +1,12 @@
+/**
+ * The framework-neutral store contract. {@link SyncStoreContract} is the minimal
+ * store interface the SDK's hooks and mutators are written against, and
+ * {@link BaseSyncedStore} is the concrete class that implements it. Framework
+ * integrations, such as the React bindings, re-export these types, so a hook can
+ * accept any store that satisfies the contract without depending on a particular
+ * UI framework.
+ *
+ * This module is type-only: it has no runtime imports and contributes nothing to
+ * the runtime bundle beyond the erased interface declarations.
+ */
+export {};

package/dist/environment.d.ts

@@ -1,12 +1,40 @@
 import { z } from 'zod';
+/**
+ * The two environments an Ablo project runs in: `production` for live data and
+ * `sandbox` for isolated test data. Every credential and every stored row
+ * belongs to exactly one of them.
+ */
 export declare const ENVIRONMENTS: readonly ["production", "sandbox"];
+/**
+ * How an environment is spelled inside an API-key prefix: a `live` key acts on
+ * the production environment and a `test` key acts on the sandbox. Convert
+ * between this spelling and {@link Environment} with
+ * {@link environmentFromKeyPrefix} and {@link environmentToKeyPrefix}.
+ */
 export type KeyPrefixEnvironment = 'live' | 'test';
+/** A Zod schema that validates a value as one of the {@link ENVIRONMENTS}. */
 export declare const environmentSchema: z.ZodEnum<{
     production: "production";
     sandbox: "sandbox";
 }>;
+/** One of the {@link ENVIRONMENTS} — either `'production'` or `'sandbox'`. */
 export type Environment = z.infer<typeof environmentSchema>;
+/**
+ * Coerces an untrusted value into a valid {@link Environment}, returning
+ * `fallback` (which defaults to `'production'`) when the value is not a
+ * recognized environment. Use it when reading an environment from configuration
+ * or off the wire.
+ */
 export declare function normalizeEnvironment(value: unknown, fallback?: Environment): Environment;
+/**
+ * Maps an API-key prefix spelling to its {@link Environment}: a `'test'` key
+ * operates on the sandbox, and anything else on production.
+ */
 export declare function environmentFromKeyPrefix(value: KeyPrefixEnvironment): Environment;
+/**
+ * Maps an {@link Environment} to the spelling used in an API-key prefix: the
+ * sandbox is `'test'` and production is `'live'`.
+ */
 export declare function environmentToKeyPrefix(value: Environment): KeyPrefixEnvironment;
+/** Returns true when the given environment is the sandbox. */
 export declare function isSandboxEnvironment(value: Environment): boolean;

package/dist/environment.js

@@ -1,16 +1,37 @@
 import { z } from 'zod';
+/**
+ * The two environments an Ablo project runs in: `production` for live data and
+ * `sandbox` for isolated test data. Every credential and every stored row
+ * belongs to exactly one of them.
+ */
 export const ENVIRONMENTS = ['production', 'sandbox'];
+/** A Zod schema that validates a value as one of the {@link ENVIRONMENTS}. */
 export const environmentSchema = z.enum(ENVIRONMENTS);
+/**
+ * Coerces an untrusted value into a valid {@link Environment}, returning
+ * `fallback` (which defaults to `'production'`) when the value is not a
+ * recognized environment. Use it when reading an environment from configuration
+ * or off the wire.
+ */
 export function normalizeEnvironment(value, fallback = 'production') {
     const parsed = environmentSchema.safeParse(value);
     return parsed.success ? parsed.data : fallback;
 }
+/**
+ * Maps an API-key prefix spelling to its {@link Environment}: a `'test'` key
+ * operates on the sandbox, and anything else on production.
+ */
 export function environmentFromKeyPrefix(value) {
     return value === 'test' ? 'sandbox' : 'production';
 }
+/**
+ * Maps an {@link Environment} to the spelling used in an API-key prefix: the
+ * sandbox is `'test'` and production is `'live'`.
+ */
 export function environmentToKeyPrefix(value) {
     return value === 'sandbox' ? 'test' : 'live';
 }
+/** Returns true when the given environment is the sandbox. */
 export function isSandboxEnvironment(value) {
     return value === 'sandbox';
 }

package/dist/errorCodes.d.ts

@@ -1,74 +1,76 @@
 /**
- * The canonical Ablo error-code registry — the **`code` tier** of the
- * Stripe-style two-tier error model.
+ * The registry of every stable error code Ablo can produce. Error handling has
+ * two levels, and this file defines the finer one.
  *
- * ### The two tiers (mirrors Stripe)
+ *   - The `type` is the coarse category, and each one corresponds to an
+ *     {@link AbloError} subclass such as `AbloPermissionError` or
+ *     `AbloValidationError`. Catching by `instanceof` is equivalent to switching
+ *     on `error.type`.
+ *   - The `code` is the fine-grained, machine-readable identifier defined here,
+ *     written in `snake_case` (for example `entity_claimed` or `queue_too_deep`).
+ *     This is what you switch on to handle a specific situation, and what the
+ *     documentation link for an error is built from.
  *
- *   - **`type`** — coarse category, 1:1 with an {@link AbloError} subclass
- *     (`AbloPermissionError`, `AbloValidationError`, …). "Catch by
- *     `instanceof`" ≡ "switch on `e.type`". This tier lives in `errors.ts`.
- *   - **`code`** — the fine-grained, machine-readable identifier in this
- *     file. `snake_case`, ordered noun→state (`entity_claimed`) or
- *     condition→constraint (`queue_too_deep`). This is what callers
- *     `switch` on for specific handling, and what `doc_url` is derived from.
+ * The client, the server, and the tool-calling boundary all speak this same
+ * vocabulary, which makes the registry part of the API contract. Two things
+ * follow from that:
  *
- * Because sync-engine ↔ sync-server ↔ MCP all speak this code vocabulary,
- * the registry **is** the wire contract. Two consequences:
- *
- *   1. `ErrorCode` is a *closed* union (plus the `policy:${string}`
- *      dynamic family). Producing an unregistered code is a compile error
- *      — that's the whole point. {@link AbloError}'s constructor param is
- *      narrowed to `ErrorCode`; only the wire-parse boundary
- *      (`translateHttpError`, frame deserialization) casts an incoming
- *      string to `ErrorCode`, so an *older* SDK still tolerates a *newer*
- *      server's code (forward compat) while internal producers stay checked.
- *   2. The `surface: 'wire'` subset is what an HTTP/MCP boundary maps from
- *      and what the public error docs are generated from. `surface:
- *      'client'` codes are local SDK invariants (you forgot to open the DB,
- *      a model isn't registered) — never sent over the network, so they
- *      carry no `httpStatus`, exactly as Stripe omits client-side
- *      programmer errors from its published code list.
+ *   1. {@link ErrorCode} is a closed set — plus the dynamic `policy:${string}`
+ *      family — so producing a code that is not registered here is a
+ *      compile-time error. The {@link AbloError} constructor accepts only a
+ *      registered code. The one place an arbitrary string is accepted as a code
+ *      is where an incoming response is parsed, which lets an older client
+ *      tolerate a code from a newer server it does not yet recognize.
+ *   2. The codes marked `surface: 'wire'` are the ones that cross the network
+ *      and are mapped at the HTTP and tool-calling boundaries; the public error
+ *      documentation is generated from them. Codes marked `surface: 'client'`
+ *      describe local mistakes — accessing the database before opening it, or
+ *      writing to a model that was never registered — and are never sent over
+ *      the network, so they carry no HTTP status.
  */
 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
- * it) when the contract changes in a way consumers can observe: a new/removed
- * 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.
+ * The version of the error contract: the envelope shape together with the set of
+ * codes and their meanings. It is date-based, and changes only when the contract
+ * changes in a way a consumer can observe — a code added or removed, an HTTP
+ * status changed, or an envelope field changed. It is emitted in the generated
+ * error documentation and returned on the `Ablo-Version` response header, so a
+ * consumer can detect when its expected contract has drifted from the server's.
  */
-export declare const ERROR_CONTRACT_VERSION = "2026-06-20";
-/** Coarse grouping for metrics dashboards and docs sectioning. */
-export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'claim' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
+export declare const ERROR_CONTRACT_VERSION = "2026-07-03";
+/** A coarse grouping of error codes, used to organize metrics and documentation. */
+export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | '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.
+ * A closed classification of how a failure can be recovered from — a level above
+ * the raw {@link ErrorCode}. Where a code says what went wrong, a recovery class
+ * says what a client should do about it, which is exactly the distinction the
+ * connection layer needs to decide between retrying, re-minting a credential, and
+ * signing the user out. Every code maps to one of these, and the set is
+ * validated at runtime.
  *
- *   - `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:
+ *   - `access_credential_expiry` — the short-lived access credential the client
+ *     presents (its ephemeral `ek_` or `rk_` key) has expired, while the
+ *     underlying login is still valid. The remedy is to mint a fresh key from the
+ *     session and retry the same request. This does not sign the user out; a
+ *     short-lived key expiring — for example after a laptop resumes from sleep —
+ *     is routine.
+ *   - `session_expiry` — the long-lived login itself is gone. This is 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).
+ *   - `auth_blocked` — the server was reachable but rejected the kind or
+ *     configuration of the credential (wrong key type, untrusted issuer, no
+ *     organization). Re-authenticating would present the same rejected credential
+ *     and loop, so the client should stop rather than reconnect or sign out.
+ *   - `permission` — an authorization denial (403) based on scope, role, or
+ *     membership.
+ *   - `transient` — a temporary failure, such as a server error or lease
+ *     contention, that may succeed if the same request is retried unchanged.
+ *   - `none` — not a recoverable authentication condition: validation errors,
+ *     not-found, local invariants, and any code an older client does not
+ *     recognize.
  */
 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. */
+/** A Zod enum over {@link RECOVERY_CLASSES}, for validating a recovery class at
+ *  runtime. */
 export declare const recoveryClassSchema: z.ZodEnum<{
     permission: "permission";
     access_credential_expiry: "access_credential_expiry";
@@ -77,36 +79,40 @@ export declare const recoveryClassSchema: z.ZodEnum<{
     transient: "transient";
     none: "none";
 }>;
-/** How a failure recovers. See {@link RECOVERY_CLASSES}. */
+/** The recovery classification of a failure. 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. */
+/** One entry in the registry: everything known about a single error code.
+ *  `httpStatus` is present only for codes that cross the network, since an HTTP
+ *  status is a property of the wire boundary rather than of a purely local
+ *  error. */
 export interface ErrorCodeSpec {
     readonly category: ErrorCategory;
-    /** `'wire'` = crosses the network and is part of the API/MCP contract;
-     *  `'client'` = local SDK invariant, never serialized. */
+    /** `'wire'` for a code that crosses the network and is part of the API
+     *  contract; `'client'` for a local error that is never serialized. */
     readonly surface: 'wire' | 'client';
     /** Canonical HTTP status for the wire boundary. Omitted for client codes. */
     readonly httpStatus?: number;
-    /** Whether the same request can succeed on a later retry without the
-     *  caller changing anything. `false` for permission / validation /
-     *  not-found; `true` for transient transport / lease contention. */
+    /** Whether the same request can succeed on a later retry without the caller
+     *  changing anything. `false` for permission, validation, and not-found;
+     *  `true` for transient transport failures and lease contention. */
     readonly retryable: boolean;
-    /** One-line human description — the source text for the `doc_url` page. */
+    /** A one-line, human-readable description of the error — also the source text
+     *  for its documentation 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`.
+     * An explicit {@link RecoveryClass}, set only where it differs from what the
+     * category, HTTP status, and `retryable` flag already imply — mainly the few
+     * authentication codes whose remedy the status alone cannot reveal, such as
+     * telling a session expiry apart from an access-credential expiry. For every
+     * other code the recovery class is derived by {@link classifyRecovery}, so
+     * this field can be left unset.
      */
     readonly recovery?: RecoveryClass;
 }
 /**
- * The closed set of stable error codes. Add a code here BEFORE throwing it
- * — the narrowed {@link AbloError} constructor param enforces this.
+ * The complete set of stable error codes, keyed by code. A code must be added
+ * here before it can be thrown, since the {@link AbloError} constructor accepts
+ * only codes from this set.
  */
 export declare const ERROR_CODES: {
     readonly apikey_invalid: ErrorCodeSpec;
@@ -172,6 +178,7 @@ export declare const ERROR_CODES: {
     readonly cli_invalid_arguments: ErrorCodeSpec;
     readonly turn_validation_failed: ErrorCodeSpec;
     readonly commit_operation_required: ErrorCodeSpec;
+    readonly commit_operation_invalid: ErrorCodeSpec;
     readonly commit_operation_model_required: ErrorCodeSpec;
     readonly commit_operations_ambiguous: ErrorCodeSpec;
     readonly commit_too_many_operations: ErrorCodeSpec;
@@ -307,9 +314,16 @@ export declare const ERROR_CODES: {
     readonly events_required: ErrorCodeSpec;
     readonly ingest_failed: ErrorCodeSpec;
     readonly migration_failed: ErrorCodeSpec;
+    readonly schema_provisioning_forbidden: ErrorCodeSpec;
     readonly model_query_failed: ErrorCodeSpec;
     readonly queries_required: ErrorCodeSpec;
     readonly query_unsupported_operator: ErrorCodeSpec;
+    readonly query_invalid_like_pattern: ErrorCodeSpec;
+    readonly query_invalid_boolean: ErrorCodeSpec;
+    readonly protocol_version_unsupported: ErrorCodeSpec;
+    readonly database_unreachable: ErrorCodeSpec;
+    readonly database_not_replication_ready: ErrorCodeSpec;
+    readonly replication_publication_drift: ErrorCodeSpec;
     readonly query_unknown_relation: ErrorCodeSpec;
     readonly query_relation_target_unknown: ErrorCodeSpec;
     readonly query_invalid_identifier: ErrorCodeSpec;
@@ -318,6 +332,7 @@ export declare const ERROR_CODES: {
     readonly upload_fields_required: ErrorCodeSpec;
     readonly upload_items_required: ErrorCodeSpec;
     readonly presigned_url_failed: ErrorCodeSpec;
+    readonly upload_not_configured: ErrorCodeSpec;
     readonly task_id_required: ErrorCodeSpec;
     readonly claim_id_required: ErrorCodeSpec;
     readonly commit_operation_action_required: ErrorCodeSpec;
@@ -336,45 +351,47 @@ export declare const ERROR_CODES: {
     readonly turn_foreign_agent: ErrorCodeSpec;
     readonly invalid_intent: ErrorCodeSpec;
     readonly schema_too_large: ErrorCodeSpec;
+    readonly request_too_large: ErrorCodeSpec;
     readonly invalid_schema: ErrorCodeSpec;
     readonly incompatible_change: ErrorCodeSpec;
 };
 /**
- * The closed set of registered codes, plus the `policy:${reason}` dynamic
- * family (conflict-policy rejections name their reason inline, the same way
- * Stripe carries a `decline_code` sub-detail). The constructor of
- * {@link AbloError} narrows its `code` option to this type, so a typo or an
- * unregistered code is a compile error. The wire-parse boundary casts
- * incoming strings to this type to preserve forward compatibility.
+ * The type of a valid error code: any key registered in {@link ERROR_CODES},
+ * plus the dynamic `policy:${reason}` family, where a conflict-policy rejection
+ * names its reason inline. The {@link AbloError} constructor accepts only this
+ * type, so a typo or an unregistered code is a compile-time error. Only the
+ * boundary that parses an incoming response casts an arbitrary string to this
+ * type, which preserves forward compatibility with a newer server.
  */
 export type ErrorCode = keyof typeof ERROR_CODES | `policy:${string}`;
-/** The subset of codes that cross the network — the actual API/MCP wire
- *  contract. HTTP/MCP boundaries map from this set; docs are generated
- *  from it. */
+/** The subset of {@link ErrorCode} values that cross the network — the codes
+ *  that make up the API contract, from which the HTTP and tool-calling
+ *  boundaries map and the public documentation is generated. */
 export type WireErrorCode = {
     [K in keyof typeof ERROR_CODES]: (typeof ERROR_CODES)[K]['surface'] extends 'wire' ? K : never;
 }[keyof typeof ERROR_CODES];
-/** Look up an error code's spec. Returns `undefined` for the dynamic
- *  `policy:*` family and for any forward-compat code an older SDK doesn't
- *  yet know. */
+/** Looks up the {@link ErrorCodeSpec} for a code. Returns `undefined` for the
+ *  dynamic `policy:*` family and for any newer code this client does not yet
+ *  recognize. */
 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). */
+/** Reports whether a code is marked retryable. Unknown and dynamic codes
+ *  default to non-retryable, so an unrecognized failure is never retried
+ *  automatically. */
 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.
+ * Classifies a code into its {@link RecoveryClass} — the single value the
+ * connection layer and the network probe branch on to decide how to recover.
  *
- * 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`
+ * The registry is the source of truth. An explicit `recovery` on the code's spec
+ * wins; it is set only on the few authentication codes whose remedy the HTTP
+ * status cannot reveal. Every other code is derived from its spec:
+ *   - retryable                 → `transient`
+ *   - HTTP 403                  → `permission`
+ *   - remaining `auth` category → `auth_blocked` (the credential-type 401s)
+ *   - anything else, or 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.
+ * An unknown code, a dynamic `policy:*` code, or a code this client predates
+ * (no spec) defaults to `none`, the same safe default as {@link isRetryableCode}:
+ * an unrecognized code is never treated as a credential expiry or a sign-out.
  */
 export declare function classifyRecovery(code: string): RecoveryClass;