@abloatai/ablo 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 0.8.0
+
+A callable `claim` coordination namespace and bring-your-own-database support
+via a new `databaseUrl` option.
+
+### Minor Changes
+
+- **Callable `claim` coordination namespace.** Taking a claim and inspecting its
+  state now live under one accessor: `claim(id, work)` acquires a claim and runs
+  `work` while it's held, and `claim.state(id)`, `claim.queue(id)`,
+  `claim.release(id)`, and `claim.reorder(id, order)` cover the surrounding
+  lifecycle. The README leads with the problem (who is allowed to act, and in
+  what order) and the Quick Start now demonstrates `claim` directly.
+
+- **Bring-your-own-database via `databaseUrl`.** Point a project at your own
+  Postgres with `Ablo({ schema, apiKey, databaseUrl })`. Ablo writes synced rows
+  back into your database, so your data stays canonical. Server-side only;
+  defaults to `process.env.DATABASE_URL`. See the data-sources guide for setup
+  and role requirements.
+
+### Breaking
+
+- The flat coordination methods `claimState`, `queue`, `release`, and `reorder`
+  are removed in favor of the `claim` namespace above.
+
+  ```diff
+  - await ablo.task.claimState(id)
+  - await ablo.task.release(id)
+  + await ablo.task.claim.state(id)
+  + await ablo.task.claim.release(id)
+  ```
+
+## 0.7.0
+
+### Minor Changes
+
+- Structured error contract, schema/migration engine, and a full `ablo` CLI.
+  - **Structured error contract across HTTP + WS planes.** A closed, canonical
+    error-code registry is now the `code` tier of a Stripe-style error model. A
+    single HTTP egress funnel converts every throw to a canonical
+    `{ type, code, message, doc_url, request_id, ...details }` envelope; the WS
+    plane narrows mutation/claim error codes to the same union.
+  - **Versioned contract + drift guard.** `ERROR_CONTRACT_VERSION` (date-based)
+    ships in `errors.json` and on the `Ablo-Version` response header, so consumers
+    detect contract changes without diffing docs. Generated `errors.mdx` /
+    `errors.json` plus a CI drift guard keep the docs, OpenAPI spec, and SDK from
+    silently diverging from the registry.
+  - **Always-on request correlation.** Every response carries a `req_…` request id
+    (honoring an inbound `x-request-id`), stamped into the envelope's `request_id`.
+  - **OpenAPI parity.** The stale `{ error, reason }` schema is replaced by the
+    canonical envelope plus a generated `ErrorCode` enum.
+
+  CLI + schema:
+  - **Schema diff + migration planning engine** (`generateProvisionPlan` /
+    `generateMigrationPlan` in `@abloatai/ablo/schema`) — pure diff, classify,
+    apply, and constant-value backfill for required-field migrations.
+  - **`ablo generate`** — emit TypeScript types from the pushed schema.
+  - **Full `ablo` CLI suite**, Stripe-CLI-shaped: `init`, `login` / `logout` /
+    `status`, `mode [test|live]`, `dev` (push schema to the test sandbox + watch),
+    `logs` (tail your scope's commit activity), and the data-source commands below.
+    Authentication is the OAuth 2.0 device flow; `login` provisions and stores a
+    test and a live key, and `mode` switches the active one.
+  - **Database-URL structure (bring-your-own-database).** The CLI is split by where
+    it writes:
+    - `ablo pull` / `ablo check` / `ablo migrate` operate on **your own
+      `DATABASE_URL`** — `pull` introspects it to emit `defineSchema(...)` from
+      existing tables (read-only, like `prisma db pull`), `check` verifies tables
+      fit the schema with no DDL, and `migrate` applies DDL to `DATABASE_URL`.
+    - `ablo schema push` / `ablo dev` target the **hosted** test/live sandbox; the
+      server diffs, migrates, and activates the uploaded schema. `dev` never
+      touches live data.
+
+  **BREAKING** — removed the legacy React hooks `useQuery` / `useOne` / `useMutate`
+  / `useReader`. Use `useAblo()` + `ablo.<model>.*` instead. The `MutateActions`,
+  `ReaderActions`, and `ReaderFindOptions` types are still re-exported for callers
+  that referenced them.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -1,39 +1,66 @@
 # Ablo
 
-Ablo is a typed sync engine for shared app state — the kind that humans,
-server code, and AI agents all edit at once.
+[![npm](https://img.shields.io/npm/v/@abloatai/ablo.svg)](https://www.npmjs.com/package/@abloatai/ablo)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
+[![types](https://img.shields.io/badge/types-included-blue.svg)](#)
+[![runtime](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](#keys--runtime)
 
-Reach for it when those edits need to show up everywhere in real time, not
-silently overwrite each other, expose who's working on what, and leave a record
-of who changed what.
+**Let people and AI agents work on the same data without overwriting each other.**
+
+When an agent and a person change the same thing at once, work gets lost: one
+edit silently clobbers another, or the agent acts on data that already moved.
+Ablo gives them one shared, typed write path so people, server actions, and
+agents can all work on the same rows without working blind.
+
+The core idea is a **claim**. An agent's work is rarely one instant write; it
+reads something, thinks, calls an LLM or tool, then writes back. While that is
+happening, the row can change underneath it. So before slow work starts, the
+agent claims the row. If someone else is already working on it, `claim` waits,
+re-reads the fresh row, then hands it over. No stale overwrite, no separate
+agent mutation path.
+
+Under the hood, you define a Zod schema once and get typed model clients for
+every actor:
 
 ```txt
 schema -> ablo.<model>.create/retrieve/update/claim(...)
 ```
 
+The schema is the public contract. It gives you typed model methods, realtime
+fanout, React selectors, agent writes, and the HTTP/Data Source shape for
+non-JavaScript services. Every confirmed change shows up everywhere, and active
+claims are visible while the work is still in progress.
+
+[Get started ↓](#quick-start) · point your coding agent at the shipped `llms.txt`
+
+It works with the auth and database you already have: realtime data is scoped to
+*sync groups* from your own identity, and your database can stay the source of
+truth via a Data Source.
+
+**Built for** collaborative editors, AI agent workflows, and internal tools —
+anywhere people and agents change shared state and everyone has to see it live.
+
 ## Set up
 
 ```bash
 npm install @abloatai/ablo
 ```
 
-The package ships an `llms.txt` — a precise map of the API — so a coding agent
-integrates from the real surface instead of guessing it. Point Claude Code or
-Cursor at it:
+**Keys & runtime.** Ablo needs Node 22+ and TypeScript 5+. Grab an `sk_test_*`
+key for a sandbox
+(`export ABLO_API_KEY=sk_test_...`); keep keys in trusted server runtimes only.
+In the browser, `<AbloProvider>` authenticates with the signed-in user's
+session — never the raw key.
 
-> Read `node_modules/@abloatai/ablo/llms.txt`, then add an Ablo schema and
-> `<AbloProvider>`, wire my first create / retrieve / update, and use `claim`
-> for anything an agent edits across a slow step (read → LLM → write).
-
-Or wire it by hand — the [Quick Start](#quick-start) below is the shape it
-produces. For production (React, an existing backend, Data Source, agents), the
+Then wire it by hand — the [Quick Start](#quick-start) below is the shape to
+copy. For production (React, an existing backend, Data Source, agents), the
 [Integration Guide](./docs/integration-guide.md) is the deeper map.
 
-**Keys & runtime.** Ablo is ESM-only (`import`, not `require`) and needs Node
-22+ and TypeScript 5+. Grab an `sk_test_*` key
-for a sandbox (`export ABLO_API_KEY=sk_test_...`); keep keys in trusted server
-runtimes only. In the browser, `<AbloProvider>` authenticates with the signed-in
-user's session — never the raw key.
+**Prefer to let an agent wire it?** The package ships an `llms.txt` — a precise
+map of the API — so Claude Code or Cursor integrates from the real surface
+instead of guessing:
+
+> Read `node_modules/@abloatai/ablo/llms.txt`, then add an Ablo schema, a `<AbloProvider>`, and my first create / retrieve / update.
 
 ## Quick Start
 
@@ -61,12 +88,16 @@ const created = await ablo.weatherReports.create({
   status: 'pending',
 });
 
-const updated = await ablo.weatherReports.update(created.id, {
-  status: 'ready',
-  forecast: 'Light rain, 13C',
+// An agent claims the row, does its slow work, then writes back. While the
+// claim is held nobody else can overwrite it; anyone else who tries waits in
+// line and re-reads the result. This is the whole point of Ablo.
+await ablo.weatherReports.claim(created.id, async (report) => {
+  const forecast = await fetchForecast(report.location); // slow: API or LLM call
+  await ablo.weatherReports.update(report.id, { status: 'ready', forecast });
 });
 
-console.log({ id: updated.id, status: updated.status });
+const ready = ablo.weatherReports.get(created.id);
+console.log({ id: ready.id, status: ready.status });
 
 await ablo.dispose();
 ```
@@ -77,33 +108,32 @@ Expected output:
 { id: '...', status: 'ready' }
 ```
 
-Pass `schema` to get typed models like `ablo.weatherReports.update(...)`.
-
 ## Reading
 
-`retrieve(id)` returns one row from the local cache — synchronous, no round-trip.
-`list(...)` filters and sorts what's already synced; it's also synchronous, and
-reactive under `useAblo`/`subscribe`. `load(...)` fetches from the server when a
-row may not be local yet.
+Two ways to read, depending on whether you can wait. `get(id)` / `getAll({ where })`
+/ `getCount({ where })` are instant — they read what's already local and re-render
+on their own when it changes, so they're what your UI uses. `retrieve(id)` /
+`list({ where })` go ask the server and return a `Promise`, for when you need the
+authoritative answer right now.
 
 ```ts
-ablo.weatherReports.retrieve('report_stockholm'); // → row | undefined
+ablo.weatherReports.get('report_stockholm');
 
-// Synchronous, from the local cache → row[]
-const pending = ablo.weatherReports.list({
-  where: { status: 'pending' },   // equality filter (an array value means IN)
+const pending = ablo.weatherReports.getAll({
+  where: { status: 'pending' },
   orderBy: { location: 'asc' },
   limit: 20,
 });
 
-// Server fetch → Promise<row[]>. 'complete' waits for the server; 'unknown'
-// returns what's local now and refreshes in the background.
-const ready = await ablo.weatherReports.load({
+const ready = await ablo.weatherReports.list({
   where: { status: 'ready' },
   type: 'complete',
 });
 ```
 
+An array value in `where` means `IN`. On `list`, `type: 'complete'` waits for
+the server; `'unknown'` returns what's local now and refreshes in the background.
+
 ## Writing
 
 `create` / `update` apply optimistically and resolve to the row. Two options
@@ -128,30 +158,35 @@ meanwhile, or worse, acts on stale state. `claim` holds the row across that gap:
 
 ```ts
 await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  // If someone else holds it, claim() WAITS in a fair queue, then re-reads —
-  // so `report` is the current row, never a stale snapshot. Reads stay open by
-  // default; only acting-on-the-row serializes.
-
-  const forecast = await weatherAgent.getWeather(report.location); // slow LLM gap
+  const forecast = await weatherAgent.getWeather(report.location);
   await ablo.weatherReports.update(report.id, { forecast, status: 'ready' });
-}); // claim released here, whether the callback returns or throws
+});
 ```
 
+If someone else holds the row, `claim()` waits in a fair queue, then re-reads —
+so `report` is the current row, never a stale snapshot. Reads stay open by
+default; only acting on the row serializes. The claim releases when the callback
+returns or throws.
+
 See who's mid-edit before you act — decide to wait, or skip:
 
 ```ts
-ablo.weatherReports.claimState('report_stockholm'); // → the holder, or null
-ablo.weatherReports.queue('report_stockholm');    // → { data: [{ heldBy, action, position }, …] }
+ablo.weatherReports.claim.state('report_stockholm');
+ablo.weatherReports.claim.queue('report_stockholm');
 
 await ablo.weatherReports.claim(id, async (report) => {
   /* do the held work */
-}, { wait: false });      // held? skip (dedup) — throws instead of waiting
+}, { wait: false });
 
 await ablo.weatherReports.claim(id, async (report) => {
   /* do the held work */
-}, { maxQueueDepth: 2 }); // 2+ already ahead? bail
+}, { maxQueueDepth: 2 });
 ```
 
+`claim.state` returns the holder (or `null`); `claim.queue` returns the line waiting
+behind it. `wait: false` skips rather than waiting when the row is held;
+`maxQueueDepth: 2` bails when two or more are already ahead.
+
 Default reads keep working while a row is claimed. Server reads that need claimed
 semantics can opt in with `ifClaimed: 'return' | 'wait' | 'fail'`.
 
@@ -168,8 +203,8 @@ try {
 > Prefer the callback form for ordinary held work. Manual scoped claims are
 > available for wider lifetimes, but callback claims are the docs default.
 
-See [Coordination](./docs/coordination.md) for the full `claim` / `claimState` /
-`queue` / `release` reference.
+See [Coordination](./docs/coordination.md) for the full `claim` / `claim.state` /
+`claim.queue` / `claim.release` reference.
 
 ## React
 
@@ -179,7 +214,7 @@ everything inside is live.
 
 ```tsx
 import { AbloProvider, useAblo } from '@abloatai/ablo/react';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 function App() {
   return (
@@ -190,14 +225,11 @@ function App() {
 }
 
 function Report({ id }: { id: string }) {
-  // Reactive read: this re-renders whenever the row changes — whether you,
-  // a teammate, or an agent changed it.
-  const report = useAblo((ablo) => ablo.weatherReports.retrieve(id));
+  const report = useAblo((ablo) => ablo.weatherReports.get(id));
   const ablo = useAblo();
 
   if (!report) return null;
 
-  // Write: same method as the server example above. Optimistic; fans out.
   return (
     <button onClick={() => ablo?.weatherReports.update(id, { status: 'ready' })}>
       {report.status}
@@ -206,6 +238,10 @@ function Report({ id }: { id: string }) {
 }
 ```
 
+The `useAblo(selector)` read re-renders whenever the row changes — whether you,
+a teammate, or an agent changed it. The write is the same optimistic, fan-out
+method as the server example above.
+
 `<AbloProvider>` owns the connection — no API key in the browser. That's the
 whole loop: read with `useAblo(selector)`, write with `ablo.<model>`, and every
 other client (human or agent) on that row sees it in real time. See
@@ -226,8 +262,9 @@ the browser connects as an already-scoped participant — it never holds the key
 and can't widen its own scope. Your schema's `identityRoles` map that identity
 to sync-group strings.
 
+`userId` / `teamIds` come from your auth, resolved server-side:
+
 ```tsx
-// userId / teamIds come from YOUR auth, resolved server-side
 <AbloProvider schema={schema} userId={user.id} teamIds={user.teamIds}>
   <App />
 </AbloProvider>
@@ -248,7 +285,7 @@ each other's changes in real time — that's the default, not a feature you turn
 
 - `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
 - `useAblo(...)` gives React clients the live row, kept current automatically.
-- `ablo.<model>.claim(id)` / `claimState(id)` / `queue(id)` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
+- `ablo.<model>.claim(id)` / `claim.state(id)` / `queue(id)` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
 
 Always write through Ablo — either the SDK model methods
 (`ablo.<model>.create/update/delete`) or the HTTP write endpoint below. If you
@@ -262,7 +299,7 @@ HTTP endpoint when a server-to-server caller needs to write without opening a
 WebSocket:
 
 ```bash
-curl https://api.ablo.dev/v1/commits \
+curl https://api.abloatai.com/v1/commits \
   -H "Authorization: Bearer sk_test_..." \
   -H "Content-Type: application/json" \
   -d '{ "operations": [
@@ -343,10 +380,11 @@ contract; there are no retry or timeout knobs to tune.
 ## Production Reference
 
 - [Identity & Sync Groups](./docs/identity.md) — bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
+- [Schema Contract](./docs/schema-contract.md) — one schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
-- [Coordination](./docs/coordination.md) — `claim` / `claimState` / `queue` / `release` reference: hold a row across slow agent work, and observe the line waiting behind it.
+- [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
 - [Connect Your Database](./docs/data-sources.md) — keep canonical rows in your app database without giving Ablo database credentials.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.

package/dist/BaseSyncedStore.d.ts

@@ -662,7 +662,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     queryByClass(modelClass: ModelConstructor<Model>, options?: {
         predicate?: (model: Model) => boolean;
-        scope?: ModelScope;
+        state?: ModelScope;
         orderBy?: keyof Model;
         order?: 'asc' | 'desc';
         limit?: number;

package/dist/BaseSyncedStore.js

@@ -12,7 +12,7 @@
  * pull generic methods into this base class.
  */
 import { makeObservable, observable, computed, runInAction } from 'mobx';
-import { AbloConnectionError, AbloValidationError } from './errors.js';
+import { AbloConnectionError, AbloValidationError, toAbloError } from './errors.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
 import { PropertyType } from './types/index.js';
 import { SyncWebSocket, } from './sync/SyncWebSocket.js';
@@ -447,14 +447,18 @@ export class BaseSyncedStore {
                 }
             }
         }
-        throw lastError || new Error('Bootstrap failed after all retry attempts');
+        throw lastError
+            ? toAbloError(lastError)
+            : new AbloConnectionError('Bootstrap failed after all retry attempts', {
+                code: 'bootstrap_fetch_timeout',
+            });
     }
     /** Create a timeout promise for bootstrap attempts */
     createBootstrapTimeout(attempt) {
         const timeoutMs = BOOTSTRAP_CONFIG.OVERALL_TIMEOUT_MS + (attempt - 1) * 3_000;
         return new Promise((_, reject) => {
             setTimeout(() => {
-                reject(new Error(`Bootstrap timed out after ${timeoutMs}ms (attempt ${attempt})`));
+                reject(new AbloConnectionError(`Bootstrap timed out after ${timeoutMs}ms (attempt ${attempt})`, { code: 'bootstrap_fetch_timeout' }));
             }, timeoutMs);
         });
     }
@@ -1688,7 +1692,7 @@ export class BaseSyncedStore {
         const modelName = this.objectPool.registry.getModelNameFromConstructor(modelClass);
         if (!modelName)
             return { data: [], total: 0, hasMore: false };
-        let allModels = this.objectPool.getByType(modelClass, options?.scope ?? ModelScope.live);
+        let allModels = this.objectPool.getByType(modelClass, options?.state ?? ModelScope.live);
         // Filter out pending deletes
         allModels = allModels.filter((m) => !this.pendingDeletes.has(m.id));
         // Apply predicate

package/dist/SyncEngineContext.d.ts

@@ -33,7 +33,8 @@ export declare const noopObservability: SyncObservabilityProvider;
 export declare const noopAnalytics: SyncAnalytics;
 /** Browser-native online status provider */
 export declare const browserOnlineStatus: OnlineStatusProvider;
-/** Permissive session error detector — treats 401/403 as session errors */
+/** Session error detector — delegates to SyncSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
 export declare const defaultSessionErrorDetector: SessionErrorDetector;
 /**
  * Fallback config used when the context is read before

package/dist/SyncEngineContext.js

@@ -4,6 +4,7 @@
  * All SDK classes receive this context at construction time.
  * It bundles every injectable dependency so constructors stay clean.
  */
+import { SyncSessionError } from './errors.js';
 // ─────────────────────────────────────────────
 // No-op defaults for optional dependencies
 // ─────────────────────────────────────────────
@@ -45,7 +46,8 @@ export const browserOnlineStatus = {
         return typeof navigator !== 'undefined' ? navigator.onLine : true;
     },
 };
-/** Permissive session error detector — treats 401/403 as session errors */
+/** Session error detector — delegates to SyncSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
 export const defaultSessionErrorDetector = {
     isSessionError(error) {
         if (error && typeof error === 'object' && 'isSessionError' in error) {
@@ -53,8 +55,8 @@ export const defaultSessionErrorDetector = {
         }
         return false;
     },
-    isSessionErrorResponse(status) {
-        return status === 401 || status === 403;
+    isSessionErrorResponse(status, body) {
+        return SyncSessionError.isSessionErrorResponse(status, body);
     },
 };
 /**

package/dist/agent/session.js

@@ -20,6 +20,7 @@
  * The helper itself imports nothing app-specific. Open-source-clean.
  */
 import { Ablo } from '../client/Ablo.js';
+import { AbloConnectionError } from '../errors.js';
 /**
  * Returns a session whose `getAgent` method handles cache, mint,
  * sync_groups alignment, and lifecycle. Call `disposeAll()` from
@@ -113,8 +114,8 @@ export function createAgentSession(options) {
                 causeMsg,
                 err,
             });
-            throw new Error(`ws bootstrap ${wsUrl} failed: ${e.message ?? 'bootstrap failed'}` +
-                (code ? ` (${code})` : ''));
+            throw new AbloConnectionError(`ws bootstrap ${wsUrl} failed: ${e.message ?? 'bootstrap failed'}` +
+                (code ? ` (${code})` : ''), { code: 'bootstrap_fetch_timeout', cause: err });
         }
         cacheByKey.set(key, { agent, expiresAtMs: minted.expiresAtMs });
         return agent;

package/dist/auth/index.js

@@ -11,7 +11,25 @@
  * SDKs hide their internal auth-handshake — the apiKey is the only
  * credential the consumer touches.
  */
-import { AbloAuthenticationError } from '../errors.js';
+import { AbloAuthenticationError, translateHttpError } from '../errors.js';
+/**
+ * Whether an HTTP error body carries a code `translateHttpError` can read —
+ * a top-level `code`, a nested `error.code`, or a string `error`. When it
+ * doesn't (empty body, non-JSON, or a non-Ablo proxy 401), the caller falls
+ * back to its own default code rather than emitting a code-less error.
+ */
+function hasWireCode(body) {
+    if (typeof body !== 'object' || body === null)
+        return false;
+    const b = body;
+    if (typeof b.code === 'string')
+        return true;
+    if (typeof b.error === 'string')
+        return true;
+    return (typeof b.error === 'object' &&
+        b.error !== null &&
+        typeof b.error.code === 'string');
+}
 export async function exchangeApiKey(options) {
     if (!options.apiKey) {
         throw new AbloAuthenticationError('apiKey is required for capability exchange', { code: 'apikey_missing' });
@@ -59,11 +77,16 @@ export async function exchangeApiKey(options) {
         catch {
             // ignore — server returned non-JSON error
         }
-        const errBody = body;
-        throw new AbloAuthenticationError(`apiKey exchange rejected (${response.status}): ${errBody?.reason ?? response.statusText}`, {
-            code: errBody?.error ?? 'exchange_failed',
-            httpStatus: response.status,
-        });
+        // Route through the canonical wire-error translator so the server's
+        // envelope (`code` + `message` + `doc_url`) propagates verbatim and maps to
+        // the right AbloError subclass — instead of the legacy `error`/`reason`
+        // shape this used to read (which the server no longer emits, collapsing
+        // every failure to a generic code with an empty message). Fall back to
+        // `exchange_failed` only when the body carried no recognizable code.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`apiKey exchange rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
     }
     const raw = (await response.json());
     if (!isCapabilityExchangeResponse(raw)) {
@@ -130,11 +153,16 @@ export async function resolveIdentity(options) {
         catch {
             // ignore non-JSON auth errors
         }
-        const errBody = body;
-        throw new AbloAuthenticationError(`identity resolve rejected (${response.status}): ${errBody?.reason ?? response.statusText}`, {
-            code: errBody?.error ?? 'identity_resolve_failed',
-            httpStatus: response.status,
-        });
+        // Canonical envelope translation (see `exchangeApiKey` above). This is what
+        // surfaces the sync-server's precise auth diagnosis — e.g.
+        // `jwt_issuer_untrusted` with its full message — to the SDK consumer,
+        // instead of collapsing every 401 to `identity_resolve_failed` with an
+        // empty reason because the old parser looked for `error`/`reason` keys the
+        // server doesn't emit.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`identity resolve rejected (${response.status})`, { code: 'identity_resolve_failed', httpStatus: response.status });
     }
     return (await response.json());
 }