@abloatai/ablo 0.25.0 → 0.27.0

package/dist/errorCodes.js

@@ -1,68 +1,70 @@
 /**
- * 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 const ERROR_CONTRACT_VERSION = '2026-06-20';
+export const ERROR_CONTRACT_VERSION = '2026-07-03';
 /**
- * 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 const RECOVERY_CLASSES = [
     'access_credential_expiry',
@@ -72,214 +74,220 @@ export const RECOVERY_CLASSES = [
     '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 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
- * — 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 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.'),
-    // 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.'),
+    apikey_invalid: wire('auth', 401, false, "This API key isn't one Ablo recognizes — it may be mistyped, truncated, or belong to a different environment. Check the key and try again."),
+    apikey_revoked: wire('auth', 401, false, 'This API key has been revoked and can no longer be used. Mint a new key from the dashboard.'),
+    // The short-lived access credential — the ephemeral key (`ek_` for users,
+    // `rk_` for agents) minted from the login and presented as a bearer token.
+    // Its expiry is routine and re-mintable: get a fresh key from the still-valid
+    // session and retry, rather than signing out. An agent's expired `rk_` must
+    // not sign a human out either. This is the one code on the silent re-mint
+    // path; see the `access_credential_expiry` recovery class.
+    apikey_expired: wire('auth', 401, false, 'This ephemeral API key has expired. Mint a fresh key from your still-valid session and retry the request.', 'access_credential_expiry'),
+    apikey_missing: wire('auth', 401, false, 'The request arrived without an API key. Send one as `Authorization: Bearer <key>`.'),
+    api_key_required: wire('auth', 401, false, 'This operation requires an API key, and none was presented. Send one as `Authorization: Bearer <key>`.'),
+    capability_id_missing: wire('auth', 401, false, 'This request must name a capability id, but none was provided.'),
+    exchange_failed: wire('auth', 401, false, 'The API key could not be exchanged for a working credential — the exchange was rejected. Check that the key is still valid.'),
+    identity_resolve_failed: wire('auth', 401, false, 'The server could not resolve an identity for this credential — the identity lookup was rejected. Check that the credential is still valid.'),
     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.'),
+    identity_missing_organization: wire('auth', 401, false, 'Authentication succeeded, but the credential resolves to no organization, so requests cannot be scoped. Check that the key or token carries an organization.'),
+    // The long-lived login is gone; this is terminal and drives sign-out and
+    // re-authentication.
+    session_expired: wire('auth', 401, false, 'Your session has expired or is no longer valid. Sign in again to continue.', 'session_expiry'),
+    // `jwt_invalid` is the general fallback; the codes below it split out specific
+    // failure modes, so an integrator can tell a wrong JWKS registration from a
+    // token with no organization claim from a wrong audience, instead of getting
+    // one opaque code for all of them.
+    jwt_invalid: wire('auth', 401, false, "The bearer JWT failed validation for a reason the server could not classify further. Check the token's issuer, signature, audience, and expiry."),
+    jwt_malformed: wire('auth', 401, false, 'The bearer token is not a well-formed JWT and could not be decoded. Check that the full, unmodified token was sent.'),
     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'),
+    // Applies only to the trusted-issuer path, where a customer authenticates with
+    // a JWT from their own identity provider. When such a token expires, the
+    // remedy is to re-authenticate against that provider, so it classifies as a
+    // session expiry.
+    jwt_expired: wire('auth', 401, false, 'The bearer JWT has expired. Obtain a fresh token from your identity provider and retry.', '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 a datasource.'),
-    datasource_connection_unsupported: wire('validation', 400, false, 'This deployment cannot register a direct (connection string) datasource — use the signed endpoint kind.'),
+    file_upload_auth_required: wire('auth', 401, false, 'File uploads require an authenticated session. Sign in and retry.'),
+    browser_apikey_blocked: client('auth', 'A raw API key was used from a browser, where anyone can read it. Keep secret keys server-side and hand the browser a short-lived ephemeral key instead.'),
+    browser_database_url_blocked: client('auth', 'A database connection string was used from a browser context. It carries database credentials, so it must stay server-side.'),
+    datasource_registration_failed: client('auth', 'The provided `databaseUrl` could not be registered as a data source. Check that the connection string is valid and the database is reachable.'),
+    datasource_connection_unsupported: wire('validation', 400, false, 'This deployment does not accept direct connection-string data sources. Register a signed Data Source endpoint instead.'),
     datasource_direct_deprecated: wire('validation', 410, false, 'The direct (connection string) datasource is deprecated. Register a signed Data Source endpoint instead — your app owns the write and your credentials never leave it.'),
     // ── 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.'),
+    capability_scope_denied: wire('capability', 403, false, 'This action falls outside the scope granted to the connection, so it was denied.'),
+    issuer_register_forbidden: wire('permission', 403, false, 'Registering a trusted issuer requires a secret (`sk_`) API key. The key presented is not a secret key.'),
+    capability_invalid: wire('capability', 403, false, 'This capability cannot be used — it is unknown, revoked, or expired. Request a fresh grant.'),
     test_database_not_registered: wire('permission', 403, false, 'Test mode requires a registered dev database for this org — run `npx ablo init`, or construct the client with `databaseUrl` using your test key.'),
     tenant_routing_failed: wire('server', 500, true, "The org's registered database could not be resolved or dialed. Ablo never falls back to shared storage for a dedicated tenant — retry, and check the datasource status if it persists."),
-    database_role_cannot_enforce_rls: wire('permission', 403, false, 'The connected database role cannot enforce row-level security (superuser or BYPASSRLS).'),
-    database_role_unreadable: wire('permission', 403, false, 'The connected database role could not be introspected.'),
-    database_tables_unforced_rls: wire('permission', 403, false, 'Synced tables in the connected database do not have FORCE ROW LEVEL SECURITY applied.'),
-    database_host_not_allowed: wire('permission', 403, false, 'The connected database host resolves to a private, loopback, or link-local address and cannot be used.'),
-    // Deprecated spellings of the `database_*` codes above — still emitted by
-    // older servers; kept so they classify identically. Do not use in new code.
+    database_role_cannot_enforce_rls: wire('permission', 403, false, 'The database role Ablo connects with is a superuser or has `BYPASSRLS`, so Postgres will not enforce row-level security for it. Connect with a role that is subject to RLS.'),
+    database_role_unreadable: wire('permission', 403, false, 'Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced.'),
+    database_tables_unforced_rls: wire('permission', 403, false, 'Some synced tables do not have `FORCE ROW LEVEL SECURITY` applied, so the table owner can bypass row isolation. Run `ALTER TABLE ... FORCE ROW LEVEL SECURITY` on each synced table.'),
+    database_host_not_allowed: wire('permission', 403, false, "The database host resolves to a private, loopback, or link-local address, which Ablo's servers will not connect to. Use a publicly resolvable host."),
+    // Older spellings of the `database_*` codes above, still sent by some servers
+    // and kept so they classify identically. Prefer the `database_*` codes.
     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 / claim conflict (409) ──────────────────────────────────
-    // Held-claim rejections are NOT queue-retryable (gRPC FAILED_PRECONDITION /
-    // ABORTED semantics; Replicache/Zero SETTLE a rejected mutation — reject the
-    // caller, roll back the optimistic effect — instead of resending it).
-    // Blindly re-sending the same payload cannot succeed while the lease is
-    // held, and a lease can outlive any sane retry budget. The correct recovery
-    // lives at the CALLER: take a claim (`ablo.<model>.claim` queues fairly
-    // behind the holder) or re-read and rebase. `retryable: true` here turned
-    // every cross-client claim conflict into an infinite client resend loop
-    // (~150ms storm — found by the claims journey, 2026-06-10).
-    claim_conflict: wire('claim', 409, false, 'The target entity is claimed by another participant.'),
-    claim_lost: wire('claim', 409, false, 'A previously held claim was lost before the write applied.'),
-    entity_claimed: wire('claim', 409, false, 'The target entity is currently claimed; write was blocked.'),
-    malformed_claim: wire('claim', 400, false, 'The claim payload was malformed.'),
-    malformed_subscription: wire('validation', 400, false, 'The update_subscription payload was malformed; expected { syncGroups: string[] }.'),
-    model_claimed: wire('claim', 409, false, 'The model instance is claimed by another participant.'),
-    model_claimed_timeout: wire('claim', 409, false, 'Timed out waiting for a model claim to clear.'),
+    // A rejection because another participant holds a claim is not retryable.
+    // Re-sending the same write cannot succeed while the claim is held, and a
+    // claim can outlive any reasonable retry budget, so an automatic retry would
+    // only loop. Recovery belongs to the caller: take a claim, which queues fairly
+    // behind the holder (`ablo.<model>.claim`), or re-read and rebase.
+    claim_conflict: wire('claim', 409, false, 'Another participant holds a claim on this row, so the write was rejected. Take a claim with `ablo.<model>.claim` to queue fairly behind the holder, or re-read and rebase.'),
+    claim_lost: wire('claim', 409, false, 'The claim held on this row was lost before the write could apply. Re-acquire the claim and retry.'),
+    entity_claimed: wire('claim', 409, false, 'This row is currently claimed by another participant, so the write was blocked. Queue behind the holder with `ablo.<model>.claim`, or wait for the claim to clear.'),
+    malformed_claim: wire('claim', 400, false, 'The claim payload could not be parsed. A claim must name the model and the entity it targets; check the payload shape and resend.'),
+    malformed_subscription: wire('validation', 400, false, 'The `update_subscription` payload was malformed; expected `{ syncGroups: string[] }`.'),
+    model_claimed: wire('claim', 409, false, 'Another participant holds a claim on this row. Read `claim.state` to see who holds it, or queue behind them with a claim of your own.'),
+    model_claimed_timeout: wire('claim', 409, false, 'Another participant held a claim on this row and did not release it in time. Retry, or read `claim.state` to see who holds it.'),
     model_claim_not_configured: client('claim', 'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'),
     model_watch_not_configured: client('claim', 'watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
     // ── stale context / idempotency (409) ──────────────────────────────
-    stale_context: wire('conflict', 409, true, 'The write carried a readAt watermark that is now stale; re-read and retry.'),
+    stale_context: wire('conflict', 409, true, "The row changed after you read it — the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
     // Raised by the functional `update(id, current => next)` form once its
-    // internal reconcile budget is exhausted — the row stayed continuously
-    // contended. Client-side: the SDK already retried; the caller decides whether
-    // to back off, raise `retries`, or move the row to the WebSocket transport.
-    contention_exhausted: client('conflict', 'A functional update could not land after exhausting its reconcile budget; the row stayed continuously contended.'),
-    update_aborted: client('conflict', 'The functional update reconcile loop was aborted via its AbortSignal before the write landed.'),
-    idempotency_conflict: wire('conflict', 409, false, 'The same Idempotency-Key was reused with a different request body.'),
-    idempotency_key_too_long: wire('validation', 400, false, 'The supplied Idempotency-Key exceeds the maximum length.'),
+    // internal reconcile budget is exhausted, because the row stayed continuously
+    // contended. The SDK has already retried; the caller decides whether to back
+    // off, raise `retries`, or move the row to the WebSocket transport.
+    contention_exhausted: client('conflict', 'A functional update kept losing to concurrent writes and exhausted its reconcile budget. Back off and retry, raise `retries`, or move the row to the WebSocket transport.'),
+    update_aborted: client('conflict', 'The functional update was aborted via its `AbortSignal` before the write landed; nothing was written.'),
+    idempotency_conflict: wire('conflict', 409, false, 'This `Idempotency-Key` was already used with a different request body. Reuse a key only to retry an identical request; otherwise generate a new one.'),
+    idempotency_key_too_long: wire('validation', 400, false, 'The supplied `Idempotency-Key` exceeds the maximum length. Use a shorter key — a UUID works well.'),
     // ── validation (400 / 422) ─────────────────────────────────────────
     write_options_invalid: client('validation', 'The write options (`idempotencyKey` / `label` / `wait` / `readAt` / `onStale` / `claim`) failed validation against the write-options schema.'),
     source_operation_id_required: client('validation', 'A data-source operation arrived without the entity `id` it targets.'),
-    source_adapter_misconfigured: client('validation', 'The data-source ORM adapter could not map a schema model onto the backing client (missing delegate or model).'),
-    source_event_invalid: client('validation', 'A data-source outbox event could not be built — the operation carries no entity id and none was supplied.'),
+    source_adapter_misconfigured: client('validation', 'The data-source ORM adapter could not map a schema model onto the backing client — the client exposes no matching delegate or model. Check that the adapter and schema agree on model names.'),
+    // The server validates every incoming data-source event before appending it
+    // to the log and rejects the whole batch with this code; `param` names the
+    // offending index and field path, such as `events[3].entityId`. It is also
+    // raised on the client when an outbound source event cannot be built.
+    source_event_invalid: wire('validation', 400, false, 'A data-source event was malformed — missing or invalid id, model, entityId, type, or field value. The whole event batch was rejected and nothing was ingested; fix the offending outbox row and re-send.'),
     duration_invalid: client('validation', 'A duration value was not a number of seconds or a "500ms" | "30s" | "3m" | "24h" string.'),
     schema_definition_invalid: client('validation', 'A schema definition value was invalid (bad column identifier, non-finite backfill, or unsupported schema-JSON version).'),
     cli_invalid_arguments: client('validation', 'The CLI was invoked with an unknown flag or a malformed flag value.'),
-    turn_validation_failed: wire('validation', 422, false, 'The agent turn failed server-side validation.'),
+    turn_validation_failed: wire('validation', 422, false, 'The agent turn payload failed server-side validation and was not applied.'),
     commit_operation_required: wire('validation', 400, false, 'A commit must carry `operation` or `operations`.'),
+    // Both commit transports — the WebSocket `commit` frame and the HTTP
+    // `/v1/commits` endpoint — validate every operation and reject the whole batch
+    // with this code. `param` names the offending index and field path, such as
+    // `operations[3].readAt`.
+    commit_operation_invalid: wire('validation', 400, false, 'A commit operation failed validation against the wire commit-operation schema — wrong field type (e.g. a string `readAt`), unknown `type`, or missing `model`. The whole batch was rejected; the error names the offending operation index and field path.'),
     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_operations_ambiguous: wire('validation', 400, false, 'A commit supplied both `operation` and `operations`. Send one or the other, not both.'),
     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.'),
-    mesh_message_invalid_input: wire('validation', 400, false, 'The mesh message failed input validation.'),
-    mesh_message_from_id_spoof: wire('validation', 403, false, 'The mesh message `from` id does not match the authenticated sender.'),
-    mesh_message_from_kind_mismatch: wire('validation', 403, false, 'The mesh message `from` kind does not match the sender.'),
-    agent_perception_missing_context: wire('validation', 422, false, 'The agent perception request lacked required context.'),
+    model_required_field_missing: wire('validation', 400, false, 'The write is missing a field the model marks as required. Include the field and retry.'),
+    model_identifier_missing: wire('validation', 400, false, "The payload is missing the model's identifier, so the target row cannot be determined. Include the `id` field."),
+    snapshot_reserved_key: wire('validation', 400, false, 'The snapshot uses a key name that is reserved by the runtime. Rename the key and retry.'),
+    mesh_message_invalid_input: wire('validation', 400, false, 'The mesh message payload failed input validation and was not delivered.'),
+    mesh_message_from_id_spoof: wire('validation', 403, false, "The mesh message's `from` id does not match the authenticated sender, so it was rejected — participants may only send as themselves."),
+    mesh_message_from_kind_mismatch: wire('validation', 403, false, "The mesh message's `from` kind does not match the kind of the authenticated sender, so it was rejected."),
+    agent_perception_missing_context: wire('validation', 422, false, 'The agent perception request is missing context it needs to run. Include the required context fields and retry.'),
     // ── not found (404) ────────────────────────────────────────────────
-    entity_not_found: wire('not_found', 404, false, 'The referenced entity does not exist.'),
-    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.'),
+    entity_not_found: wire('not_found', 404, false, 'No row exists with the requested id. It may have been deleted, or the id may belong to a different environment.'),
+    model_not_found: wire('not_found', 404, false, 'No row of this model exists with the requested id. It may have been deleted, or the id may belong to a different environment.'),
+    mutate_update_entity_not_found: wire('not_found', 404, false, 'The row targeted by this update does not exist — it may have been deleted since you read it. Re-read before retrying.'),
+    task_id_missing: wire('server', 502, true, 'The task-create response arrived without a task id, so the result cannot be used. Retry the request.'),
+    // ── data integrity / database constraints ──────────────────────────
+    // Emitted when a database integrity constraint rejects a write. None are
+    // retryable: the same payload re-sent unchanged fails identically, so the
+    // client must roll back rather than retry. The server maps the underlying SQL
+    // constraint to one of these codes and places the raw constraint, column, and
+    // table detail in `details` instead of exposing the driver's message text.
+    not_null_violation: wire('validation', 400, false, 'The database rejected the write because a required column was left empty — a not-null constraint. The error details name the column; supply a value and retry.'),
+    foreign_key_violation: wire('conflict', 409, false, 'The database rejected the write on a foreign-key constraint: a referenced row does not exist, or the row being deleted is still referenced by others. The error details name the constraint.'),
+    unique_violation: wire('conflict', 409, false, 'The write duplicates a value that must be unique — another row already holds it. Choose a different value, or update the existing row.'),
+    check_violation: wire('validation', 400, false, 'The database rejected a value that fails one of its check constraints. The error details name the constraint; adjust the value and retry.'),
+    constraint_violation: wire('validation', 400, false, 'The database rejected the write on an integrity constraint. The error details identify the specific constraint.'),
     column_type_mismatch: wire('validation', 400, false, 'A structured (JSON) value was written to a column whose database type cannot hold it. Ablo adapts a json field to either a jsonb column (native) or a text column (serialized) — but a scalar column (integer, boolean, uuid, timestamp, …) cannot store a JSON object or array. Use a jsonb or text column for this field. Ablo adapts to your column; it does not alter your schema.'),
     // ── tenant / unknown model (400) ───────────────────────────────────
     server_execute_unknown_model: wire('tenant', 400, false, 'Wrote to a model the server does not know. The server keeps its own copy of the schema — run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models.'),
     mutate_create_unknown_model: wire('tenant', 400, false, 'Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first — the server keeps its own copy of the schema.'),
-    tenant_model_columns_unknown: wire('tenant', 400, false, "The tenant model's columns could not be resolved."),
-    tenant_model_missing_organization_id: wire('tenant', 400, false, 'The tenant model is missing the organization_id column required for isolation.'),
+    tenant_model_columns_unknown: wire('tenant', 400, false, 'The columns for this model could not be resolved in the tenant database, so the operation cannot be mapped onto its table.'),
+    tenant_model_missing_organization_id: wire('tenant', 400, false, "This model's table has no `organization_id` column, which Ablo requires to isolate rows by organization. Add the column before syncing this model."),
     // ── schema migration / declaration (validation) ────────────────────
-    schema_mutable_missing_meta: wire('schema', 400, false, 'A mutable schema is missing its required meta block.'),
-    schema_scope_kind_invalid: wire('schema', 400, false, 'A scope kind in the schema is invalid.'),
-    schema_field_not_camelcase: wire('schema', 400, false, 'A schema field name is not camelCase.'),
-    schema_field_consecutive_caps: wire('schema', 400, false, 'A schema field name has consecutive capital letters.'),
+    schema_mutable_missing_meta: wire('schema', 400, false, 'The schema is declared mutable but is missing its required `meta` block.'),
+    schema_scope_kind_invalid: wire('schema', 400, false, 'A scope declaration in the schema uses a kind the engine does not recognize.'),
+    schema_field_not_camelcase: wire('schema', 400, false, 'A schema field name is not camelCase. Rename the field (for example `dueDate`) — Ablo derives column names from camelCase field names.'),
+    schema_field_consecutive_caps: wire('schema', 400, false, 'A schema field name contains consecutive capital letters, which cannot be mapped to a column name unambiguously. Write acronyms in lower case (`apiKey`, not `APIKey`).'),
     schema_reserved_field: client('schema', 'A model redeclared a reserved base field (id, createdAt, updatedAt, organizationId, createdBy) that the SDK provides automatically.'),
-    schema_grants_shape_invalid: wire('schema', 400, false, 'A grants declaration has an invalid shape.'),
-    schema_grants_identifier_unsafe: wire('schema', 400, false, 'A grants declaration referenced an unsafe identifier.'),
-    schema_grants_relation_kind: wire('schema', 400, false, 'A grants relation referenced an invalid kind.'),
-    schema_grants_relation_missing: wire('schema', 400, false, 'A grants declaration referenced a missing relation.'),
-    schema_grants_target_not_scope_root: wire('schema', 400, false, 'A grants target is not a scope root.'),
-    drop_field: client('schema', 'Migration would drop a field (destructive classification).'),
-    drop_model: client('schema', 'Migration would drop a model (destructive classification).'),
-    lossy_recreate: client('schema', 'Migration would require a lossy table recreate.'),
-    made_required: client('schema', 'Migration would make an existing field required.'),
-    required_field_added: client('schema', 'Migration adds a new required field.'),
-    enum_value_removed: client('schema', 'Migration removes an enum value (destructive classification).'),
-    risky_cast: client('schema', 'Migration would perform a risky column type cast.'),
+    schema_grants_shape_invalid: wire('schema', 400, false, 'A `grants` declaration in the schema has an invalid shape and could not be parsed.'),
+    schema_grants_identifier_unsafe: wire('schema', 400, false, 'A `grants` declaration references an identifier that is not safe to use in SQL. Use plain column and relation names.'),
+    schema_grants_relation_kind: wire('schema', 400, false, 'A `grants` declaration references a relation of a kind it cannot traverse.'),
+    schema_grants_relation_missing: wire('schema', 400, false, 'A `grants` declaration references a relation the model does not define. Check the relation name against the model.'),
+    schema_grants_target_not_scope_root: wire('schema', 400, false, 'A `grants` declaration targets a model that is not a scope root, so access cannot be derived from it.'),
+    drop_field: client('schema', 'This migration would drop an existing field, destroying the data stored in it.'),
+    drop_model: client('schema', 'This migration would drop an entire model and its table, destroying the rows stored in it.'),
+    lossy_recreate: client('schema', 'This migration can only apply by recreating the table, which would not preserve its existing rows.'),
+    made_required: client('schema', 'This migration makes an existing optional field required, which rows without a value for it would violate.'),
+    required_field_added: client('schema', 'This migration adds a new required field that existing rows have no value for.'),
+    enum_value_removed: client('schema', 'This migration removes an enum value that existing rows may still hold.'),
+    risky_cast: client('schema', 'This migration changes a column to a type its current values may not convert to cleanly.'),
     // ── claim / lease (409 / transport) ───────────────────────────────
-    claim_lease_unavailable: wire('claim', 503, true, 'The claim-lease coordination subsystem is unavailable; retry.'),
-    claim_not_wired: client('claim', 'Claim support was used but is not wired in this runtime.'),
-    claim_queued: wire('claim', 409, true, 'The claim was queued behind an active lease holder.'),
-    claim_wait_aborted: wire('claim', 409, true, 'Waiting for the claim lease was aborted.'),
-    claim_wait_poll_interval_required: client('claim', 'A poll interval is required when waiting on an claim.'),
-    grant_timeout: wire('claim', 504, true, 'Timed out waiting for a capability grant.'),
-    slide_intent_missing_deck_id: wire('claim', 400, false, 'A slide claim was missing its deck id.'),
-    slide_intent_unknown_sibling: wire('claim', 400, false, 'A slide claim referenced an unknown sibling slide.'),
+    claim_lease_unavailable: wire('claim', 503, true, 'The claim-lease coordination subsystem is temporarily unavailable, so the claim could not be processed. Retry shortly.'),
+    claim_not_wired: client('claim', 'Claims were used, but this runtime has no claim support wired in. The standard `Ablo({ schema, apiKey })` client wires it up automatically.'),
+    claim_queued: wire('claim', 409, true, 'The claim was queued behind the current lease holder and will be granted in turn. Wait, or read `claim.queue` to see your position.'),
+    claim_wait_aborted: wire('claim', 409, true, 'The wait for this claim lease was aborted before the lease was granted.'),
+    claim_wait_poll_interval_required: client('claim', 'Waiting on a claim requires a poll interval, and none was provided.'),
+    grant_timeout: wire('claim', 504, true, 'The wait for a capability grant timed out before one arrived. Retry the request.'),
+    slide_intent_missing_deck_id: wire('claim', 400, false, 'This slide claim is missing the id of the deck it belongs to.'),
+    slide_intent_unknown_sibling: wire('claim', 400, false, 'This slide claim references a sibling slide that does not exist in the deck.'),
     // ── bootstrap (transport) ──────────────────────────────────────────
-    bootstrap_fetch_timeout: wire('bootstrap', 504, true, 'The bootstrap fetch timed out.'),
-    bootstrap_offline: wire('bootstrap', 503, true, 'Bootstrap could not run because the client is offline.'),
-    bootstrap_offline_no_cache: wire('bootstrap', 503, false, 'Bootstrap is offline and no cached snapshot is available.'),
-    bootstrap_response_invalid: wire('bootstrap', 502, true, 'The bootstrap response was malformed.'),
-    bootstrap_response_schema_invalid: wire('bootstrap', 502, true, 'The bootstrap response failed schema validation.'),
+    bootstrap_fetch_timeout: wire('bootstrap', 504, true, 'The initial bootstrap fetch timed out before the server responded. Retry shortly.'),
+    bootstrap_offline: wire('bootstrap', 503, true, 'Bootstrap could not run because the client is offline. It can proceed once the network returns.'),
+    bootstrap_offline_no_cache: wire('bootstrap', 503, false, 'The client is offline and no cached snapshot is available to start from, so there is no data to load until the network returns.'),
+    bootstrap_response_invalid: wire('bootstrap', 502, true, 'The bootstrap response could not be parsed. Retrying may succeed.'),
+    bootstrap_response_schema_invalid: wire('bootstrap', 502, true, 'The bootstrap response parsed but failed schema validation, so it was not applied. Retrying may succeed.'),
     // ── transport / connection ─────────────────────────────────────────
-    exchange_malformed_response: wire('transport', 502, true, 'The credential exchange returned a malformed response.'),
-    exchange_network_error: wire('transport', 503, true, 'A network error occurred during credential exchange.'),
-    source_network_error: wire('transport', 503, true, 'A network error occurred talking to the source.'),
-    identity_network_error: wire('transport', 503, true, 'A network error occurred resolving identity.'),
-    commit_no_result: wire('transport', 504, true, 'The commit was sent but no result frame arrived.'),
-    commit_failed: wire('transport', 500, true, 'The commit failed to apply.'),
-    commit_offline_grace_expired: wire('transport', 503, false, "The offline grace window expired before the commit could be sent."),
-    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.'),
+    exchange_malformed_response: wire('transport', 502, true, 'The credential exchange returned a response that could not be parsed. Retrying may succeed.'),
+    exchange_network_error: wire('transport', 503, true, 'A network error interrupted the credential exchange. Check connectivity and retry.'),
+    source_network_error: wire('transport', 503, true, 'A network error occurred while talking to the data source. Check connectivity and retry.'),
+    identity_network_error: wire('transport', 503, true, 'A network error occurred while resolving your identity. Check connectivity and retry.'),
+    commit_no_result: wire('transport', 504, true, 'The commit was sent, but no result frame arrived, so its outcome is unknown. It is safe to retry.'),
+    commit_failed: wire('transport', 500, true, 'The commit reached the server but failed to apply. Retrying may succeed.'),
+    commit_offline_grace_expired: wire('transport', 503, false, 'The offline grace window expired before this commit could be sent, so it was not applied. Re-apply the change once the connection returns.'),
+    queue_too_deep: wire('transport', 503, true, 'The transaction queue is over its depth limit, so new writes are being rejected until it drains. Retry shortly.'),
+    flush_timeout: wire('transport', 504, true, 'Flushing the transaction queue timed out before every pending write was sent. Retry once connectivity stabilizes.'),
+    wait_for_timeout: wire('transport', 504, true, 'A wait-for condition timed out before it was satisfied. Retry, or extend the timeout.'),
     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.'),
+    fetch_unavailable: client('transport', 'This environment provides no `fetch` implementation, so HTTP requests cannot be made. Run on a platform with `fetch` (Node 18+, modern browsers) or supply a polyfill.'),
+    base_url_missing: client('transport', 'The client has no base URL configured, so it cannot address the server. Set the base URL when constructing the client.'),
+    sync_not_ready: client('transport', 'A sync operation ran before the client finished initializing. Wait for the client to be ready before syncing.'),
+    ws_not_ready: client('transport', 'A frame was sent before the WebSocket connection was established. Wait for the connection to open before sending.'),
     // ── quota / rate limit (429) ──────────────────────────────────────
-    quota_exceeded: wire('rate_limit', 429, true, 'The organization exceeded its configured usage quota.'),
+    quota_exceeded: wire('rate_limit', 429, true, 'Your organization has used up its configured usage quota. Requests will succeed again once the quota resets or the limit is raised.'),
     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.'),
-    // Per-CREDENTIAL request-rate limit — the fast (RPS/burst) axis, distinct from
-    // the slow-axis `quota_exceeded` (org daily/monthly usage). Keyed per API key,
-    // so one noisy key backs off without affecting the rest of the org. The
-    // `Retry-After` header carries the bucket-refill delay.
-    rate_limit_exceeded: wire('rate_limit', 429, true, 'This API key is sending requests too quickly; slow down and retry after the indicated delay.'),
+    // A per-key request-rate limit — the fast, requests-per-second axis, as
+    // opposed to `quota_exceeded`, which is the slower organization-wide usage
+    // limit. It is keyed per API key, so one noisy key backs off without affecting
+    // the rest of the organization. The `Retry-After` header carries the delay
+    // before the next request is allowed.
+    rate_limit_exceeded: wire('rate_limit', 429, true, 'This API key is sending requests faster than its rate limit allows. Slow down and retry after the delay in the `Retry-After` header.'),
     // ── 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.'),
-    // The per-key rate-limiter backend (Redis) was unreachable and the API is
-    // configured to FAIL CLOSED on that path, so the request was rejected rather
-    // than admitted unchecked. Retryable: the next attempt re-probes the backend.
+    internal_error: wire('server', 500, true, "Something went wrong on Ablo's side — an unexpected server error. It is safe to retry."),
+    quota_lookup_failed: wire('server', 503, true, "The server could not load this organization's quota state, so the request was rejected rather than admitted unchecked. Retry shortly."),
+    // The rate-limiter backend was unreachable and this endpoint is configured to
+    // fail closed, so the request was rejected rather than admitted unchecked. It
+    // is retryable: the next attempt re-probes the backend.
     rate_limiter_unavailable: wire('server', 503, true, 'The rate-limiter backend is unavailable and this endpoint is configured to fail closed; retry shortly.'),
-    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.'),
+    turn_open_failed: wire('server', 500, true, 'The agent turn could not be opened on the server. It is safe to retry.'),
+    turn_close_failed: wire('server', 500, true, 'The agent turn could not be closed cleanly on the server. It is safe to retry the close.'),
     // ── 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.'),
@@ -319,85 +327,95 @@ export const ERROR_CODES = {
     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) ─────────────
+    // ── HTTP route edge codes ──────────────────────────────────────────
     invalid_body: wire('validation', 400, false, 'The request body was missing, unparseable, or the wrong shape.'),
     invalid_json: wire('validation', 400, false, 'The request body was not valid JSON.'),
     capability_id_required: wire('validation', 400, false, 'A capability id is required for this request.'),
     organization_mismatch: wire('permission', 403, false, 'The request targeted an organization the caller is not scoped to.'),
     project_scope_denied: wire('permission', 403, false, "The request targeted a project the caller's key is not scoped to."),
-    project_slug_taken: wire('validation', 409, false, 'A project with this slug already exists in the organization.'),
+    project_slug_taken: wire('validation', 409, false, 'A project with this slug already exists in the organization. Choose a different slug.'),
     forbidden: wire('permission', 403, false, 'The caller lacks permission for this operation.'),
-    source_api_key_unresolved: wire('auth', 401, false, 'The source API key could not be resolved.'),
+    source_api_key_unresolved: wire('auth', 401, false, 'The API key presented for this data source could not be resolved to a known key. Check the key and its environment.'),
     capability_auth_disabled: wire('server', 503, false, 'Capability authentication is disabled on this server.'),
-    provisioner_unavailable: wire('server', 503, false, 'No database provisioner is configured.'),
-    invalid_model: wire('validation', 400, false, 'The request named an invalid model.'),
-    invalid_id: wire('validation', 400, false, 'The request carried an invalid id.'),
+    provisioner_unavailable: wire('server', 503, false, 'This deployment has no database provisioner configured, so tables cannot be created here.'),
+    invalid_model: wire('validation', 400, false, 'The model name in the request is not a valid model identifier.'),
+    invalid_id: wire('validation', 400, false, 'The id in the request is not a valid identifier.'),
     unknown_model: wire('tenant', 400, false, 'Named a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` — the server keeps its own copy of the schema.'),
-    model_not_tenant_scoped: wire('tenant', 400, false, 'The model is not tenant-scoped and cannot be queried this way.'),
+    model_not_tenant_scoped: wire('tenant', 400, false, 'This model is not tenant-scoped, so it cannot be queried through the tenant-scoped read path.'),
     schema_table_invalid: wire('schema', 500, false, "The model's table identifier is invalid."),
     schema_scope_invalid: wire('schema', 500, false, "The model's scope predicate could not be built."),
-    entity_fetch_failed: wire('server', 500, true, 'The entity fetch failed.'),
-    events_required: wire('validation', 400, false, 'The request must include a non-empty events array.'),
-    ingest_failed: wire('validation', 400, false, 'The source-event ingest failed.'),
-    migration_failed: wire('server', 500, false, 'The schema migration failed to apply.'),
-    model_query_failed: wire('validation', 400, false, 'The model query failed.'),
-    queries_required: wire('validation', 400, false, 'The request must include a non-empty queries array.'),
+    entity_fetch_failed: wire('server', 500, true, 'The server failed to fetch the requested entity. It is safe to retry.'),
+    events_required: wire('validation', 400, false, 'The request must include a non-empty `events` array.'),
+    ingest_failed: wire('validation', 400, false, 'The source-event batch was rejected during ingest and nothing was appended. Check the events against the expected shape and re-send.'),
+    migration_failed: wire('server', 500, false, 'The schema migration failed while applying and did not complete.'),
+    schema_provisioning_forbidden: wire('permission', 403, false, 'Schema registration could not create tables in the target database: the engine is not permitted to run DDL there.'),
+    model_query_failed: wire('validation', 400, false, 'The model query failed to execute. Check the query filters and operators.'),
+    queries_required: wire('validation', 400, false, 'The request must include a non-empty `queries` array.'),
     query_unsupported_operator: wire('validation', 400, false, 'The query used an unsupported operator.'),
-    query_unknown_relation: wire('validation', 400, false, 'The query referenced an unknown relation.'),
-    query_relation_target_unknown: wire('schema', 500, false, 'A relation targets a model the schema does not define.'),
+    query_invalid_like_pattern: wire('validation', 400, false, 'The `LIKE` pattern must not end with an escape character.'),
+    query_invalid_boolean: wire('validation', 400, false, 'The query compared a boolean column against an invalid boolean literal.'),
+    protocol_version_unsupported: wire('transport', 426, false, 'The client sync-protocol version is outside the range this server supports — upgrade the SDK (or the server was rolled back mid-fleet).'),
+    database_unreachable: wire('validation', 400, false, "Ablo could not reach this database to check that it can stream replication. The connection string may be wrong, the host may not be reachable from Ablo's servers, or the credentials may not be accepted."),
+    database_not_replication_ready: wire('validation', 400, false, 'This database is not set up for logical replication yet. Every failing item — wal_level, the publication, the replication grant, a replica identity — is listed in the error details with its exact fix. `ablo connect` prints the one-time setup; `ablo connect --check` verifies it.'),
+    replication_publication_drift: wire('validation', 400, false, 'Your schema maps to tables that are not members of the replication publication, so their changes silently never stream and the source looks frozen. The missing tables and the exact `ALTER PUBLICATION … ADD TABLE …` to add them are in the error details — Ablo never alters your database for you.'),
+    query_unknown_relation: wire('validation', 400, false, 'The query references a relation the model does not define. Check the relation name against the schema.'),
+    query_relation_target_unknown: wire('schema', 500, false, 'A relation in the query targets a model the schema does not define.'),
     query_invalid_identifier: wire('validation', 400, false, 'The query contained an invalid identifier.'),
     org_id_required: wire('validation', 400, false, 'An organization id is required for this request.'),
-    presence_identity_required: wire('validation', 400, false, 'Both userId and organizationId are required.'),
-    upload_fields_required: wire('validation', 400, false, 'A required upload field was missing.'),
-    upload_items_required: wire('validation', 400, false, 'The request must include a non-empty items array.'),
-    presigned_url_failed: wire('server', 500, true, 'Failed to generate a presigned upload URL.'),
+    presence_identity_required: wire('validation', 400, false, 'Presence requests must carry both `userId` and `organizationId`.'),
+    upload_fields_required: wire('validation', 400, false, 'The upload request is missing a required field.'),
+    upload_items_required: wire('validation', 400, false, 'The request must include a non-empty `items` array.'),
+    presigned_url_failed: wire('server', 500, true, 'The server could not generate a presigned upload URL. It is safe to retry.'),
+    upload_not_configured: wire('server', 503, false, 'Uploads are not configured on this deployment: the upload storage bucket and CDN domain are unset.'),
     task_id_required: wire('validation', 400, false, 'A task id is required for this request.'),
-    claim_id_required: wire('validation', 400, false, 'An claim id is required for this request.'),
+    claim_id_required: wire('validation', 400, false, 'A claim id is required for this request.'),
     commit_operation_action_required: wire('validation', 400, false, 'A commit operation is missing its `action`.'),
     commit_operation_unsupported: wire('validation', 400, false, 'A commit operation used an unsupported `action`.'),
     usage_invalid: wire('validation', 400, false, 'The usage request was invalid.'),
     invalid_request: wire('validation', 400, false, 'The request parameters were invalid.'),
     capability_not_found: wire('not_found', 404, false, 'No capability exists with the given id.'),
-    invalid_participant_kind: wire('validation', 400, false, 'The participant kind is invalid.'),
-    invalid_sync_group: wire('validation', 400, false, 'Sync groups must be "default" or "<namespace>:<id>".'),
-    narrow_scope_required: wire('validation', 400, false, 'A narrowed scope is required for this request.'),
-    wide_scope_forbidden: wire('permission', 403, false, 'A wide scope is not permitted for this caller.'),
-    capability_required: wire('auth', 401, false, 'This operation requires a capability.'),
+    invalid_participant_kind: wire('validation', 400, false, 'The participant kind is not one the server recognizes.'),
+    invalid_sync_group: wire('validation', 400, false, 'Sync groups must be `default` or `<namespace>:<id>`.'),
+    narrow_scope_required: wire('validation', 400, false, 'This request requires a scope narrowed to specific resources; the presented scope is too broad.'),
+    wide_scope_forbidden: wire('permission', 403, false, 'This caller may not use a wide scope. Request a scope narrowed to the resources you need.'),
+    capability_required: wire('auth', 401, false, 'This operation requires a capability, and none was presented.'),
     parent_turn_not_found: wire('not_found', 404, false, 'The referenced parent turn does not exist.'),
-    parent_turn_foreign_agent: wire('permission', 403, false, 'The parent turn belongs to a different agent.'),
+    parent_turn_foreign_agent: wire('permission', 403, false, 'The referenced parent turn belongs to a different agent, so it cannot be used here.'),
     turn_not_found: wire('not_found', 404, false, 'The referenced turn does not exist.'),
-    turn_foreign_agent: wire('permission', 403, false, 'The turn belongs to a different agent.'),
-    invalid_intent: wire('validation', 400, false, 'The claim request was invalid.'),
+    turn_foreign_agent: wire('permission', 403, false, 'This turn belongs to a different agent, so the caller cannot act on it.'),
+    invalid_intent: wire('validation', 400, false, 'The claim request was malformed and could not be processed.'),
     schema_too_large: wire('validation', 413, false, 'The submitted schema exceeds the maximum size.'),
+    request_too_large: wire('validation', 413, false, 'The request body exceeds the maximum size.'),
     invalid_schema: wire('validation', 400, false, 'The submitted schema could not be parsed.'),
-    incompatible_change: wire('conflict', 409, false, 'The schema change is incompatible with the current schema.'),
+    incompatible_change: wire('conflict', 409, false, 'The schema change is incompatible with the schema currently deployed and cannot be applied as-is.'),
 };
-/** 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 function errorCodeSpec(code) {
     return ERROR_CODES[code];
 }
-/** 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 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.
+ * 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 function classifyRecovery(code) {
     const spec = errorCodeSpec(code);
@@ -414,10 +432,9 @@ export function classifyRecovery(code) {
     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`.)
+ * A compile-time exhaustiveness guard: it forces every {@link RecoveryClass} to
+ * be listed here, so adding a class to {@link RECOVERY_CLASSES} without deciding
+ * its meaning is a type error rather than a silent gap.
  */
 const _RECOVERY_CLASS_EXHAUSTIVE = {
     access_credential_expiry: true,