@abloatai/ablo 0.7.0 → 0.8.0

package/dist/client/createModelProxy.d.ts

@@ -7,10 +7,12 @@
  * testable in isolation and the constructor doesn't carry it.
  *
  * Each schema model gets one `ModelOperations<T, CreateInput>` —
- * exposes `retrieve`, `list`, `count`, `create`, `update`, `delete`,
- * `claim`, `claimState`, `queue`, `release`, `subscribe`, and `load`.
- * The factory returns a plain object; the client assembles the
- * `ablo.<model>` lookup table from these.
+ * exposes the async server reads `retrieve` / `list`, the synchronous
+ * local-graph snapshots `get` / `getAll` / `getCount`, the writes
+ * `create` / `update` / `delete`, the coordination namespace `claim`
+ * (`claim(id, work)` plus `claim.state` / `claim.queue` / `claim.release` /
+ * `claim.reorder`), and `onChange`. The factory returns a plain object; the
+ * client assembles the `ablo.<model>` lookup table from these.
  */
 import type { MutationOptions } from '../interfaces/index.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
@@ -48,7 +50,7 @@ export interface ModelLoadOptions<T> {
      *   - tuple form: `[['name', 'ILIKE', '%Goldman%']]` for operators
      *
      * See `LoadWhere<T>` in `query/types.ts`. For OR semantics, run two
-     * `load()` calls and union — the wire protocol is AND-only.
+     * `list()` calls and union — the wire protocol is AND-only.
      */
     where?: LoadWhere<T>;
     orderBy?: {
@@ -68,6 +70,9 @@ export interface ModelLoadOptions<T> {
      */
     expand?: readonly string[];
 }
+/** Options for the single-row async server read `retrieve(id)`. A subset of
+ *  {@link ModelLoadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
+export type ModelRetrieveOptions = Pick<ModelLoadOptions<unknown>, 'type' | 'expand'>;
 export interface IntentLeaseHandle {
     readonly id: string;
     release(): Promise<void>;
@@ -173,62 +178,37 @@ export interface ClaimOptions {
  * verb — there is no method chaining on the claim.
  */
 export type ClaimedRow<T> = T & AsyncDisposable;
-export interface ModelOperations<T, CreateInput> {
-    /**
-     * Retrieve a single entity by id from the local pool. Synchronous.
-     * Returns `undefined` when the entity isn't loaded yet — use
-     * `load({where: {id}})` if you want to lazy-hydrate from storage/network.
-     *
-     * Mirrors `stripe.customers.retrieve(id)`.
-     */
-    retrieve(id: string): T | undefined;
-    /**
-     * List entities matching a filter from the local pool. Synchronous.
-     * No network round-trip — use `load()` for hydration.
-     *
-     * Mirrors `stripe.customers.list({...})`.
-     */
-    list(options?: ModelListOptions<T>): T[];
-    /** Count entities matching a filter (synchronous, from local pool). */
-    count(options?: ModelCountOptions<T>): number;
-    /**
-     * Create a new entity — **optimistic, offline-first**. Resolves once
-     * the mutation is queued locally, not when the server confirms.
-     * Server rejection rolls back automatically; watch `sync.syncStatus`.
-     */
-    create(data: CreateInput, options?: MutationOptions): Promise<T>;
-    /** Update an entity by id — optimistic, offline-first (see `create`). */
-    update(id: string, data: Partial<T>, options?: MutationOptions): Promise<T>;
-    /** Delete an entity by id — optimistic, offline-first (see `create`). */
-    delete(id: string, options?: MutationOptions): Promise<void>;
+/**
+ * The coordination surface for a model, exposed as a callable namespace.
+ *
+ * Calling it takes a claim — either the callback form (`claim(id, work)`, which
+ * releases when `work` settles) or the bare lease form (`claim(id)`). Its
+ * members read and steer the same coordination plane: `state` (current holder),
+ * `queue` (the wait line), `release` (drop a held claim), `reorder` (re-rank the
+ * line). All four stay on the ephemeral coordination plane — never persisted,
+ * never a `SyncDelta`.
+ */
+export interface ClaimApi<T> {
+    /** Take a claim and get the held row back (bare lease form). */
+    (id: string, options?: ClaimOptions): Promise<ClaimedRow<T>>;
     /**
-     * Claim a row so other writers wait or are rejected until you're done.
-     * Reads stay open by default. Prefer the callback form for ordinary held
-     * work; it releases when the callback returns or throws. The `await using`
-     * form is also available for wider lexical scopes.
-     *
-     * ```ts
-     * await ablo.weatherReports.claim('report_stockholm', async (report) => {
-     *   const weather = await getWeather(report.location);
-     *   await ablo.weatherReports.update(report.id, { forecast: weather });
-     * });
-     * ```
+     * Take a claim, run `work` with the held row, release when it settles. The
+     * preferred form for ordinary held work.
      */
-    claim(id: string, options?: ClaimOptions): Promise<ClaimedRow<T>>;
-    claim<R>(id: string, work: (row: ClaimedRow<T>) => Promise<R> | R, options?: ClaimOptions): Promise<R>;
+    <R>(id: string, work: (row: ClaimedRow<T>) => Promise<R> | R, options?: ClaimOptions): Promise<R>;
     /**
-     * Read who's coordinating on a row — the current holder (who, phase,
-     * until when), or `null` when free. Synchronous and reactive; for
-     * observers/UI. Never blocks.
+     * Who's coordinating on a row — the current holder (who, phase, until when),
+     * or `null` when free. Synchronous and reactive; for observers/UI. Never
+     * blocks.
      */
-    claimState(id: string): Intent | null;
+    state(id: string): Intent | null;
     /**
      * The wait queue on a row — who's lined up behind the holder and what each
      * intends. Reactive snapshot (synced from the server, like `activity`);
      * returns a Stripe-style list envelope, FIFO order, empty when no one waits.
      *
      * ```ts
-     * const { data } = ablo.decks.queue('deck_1');
+     * const { data } = ablo.decks.claim.queue('deck_1');
      * // → [{ heldBy: 'agent:summarizer', action: 'editing', position: 0 }, …]
      * ```
      */
@@ -237,28 +217,92 @@ export interface ModelOperations<T, CreateInput> {
         readonly data: readonly Intent[];
     };
     /**
-     * Re-rank the wait queue on a record — move waiters to the front in the
-     * given order. Pass the `Intent[]` from `queue(id).data`, reordered. A
+     * Re-rank the wait queue on a record — move waiters to the front in the given
+     * order. Pass the `Intent[]` from `claim.queue(id).data`, reordered. A
      * privileged operation: the server gates it (the caller needs the
      * `intent.reorder` capability), so it's fire-and-forget — the new order
-     * arrives reactively through `queue(id)`.
+     * arrives reactively through `claim.queue(id)`.
      *
      * ```ts
-     * const { data } = ablo.decks.queue('deck_1');
-     * ablo.decks.reorder('deck_1', [data[2], data[0], data[1]]); // promote #2
+     * const { data } = ablo.decks.claim.queue('deck_1');
+     * ablo.decks.claim.reorder('deck_1', [data[2], data[0], data[1]]); // promote #2
      * ```
      */
     reorder(id: string, order: readonly Intent[]): void;
     /** Release a claim you hold early. Usually implicit (scope exit). */
     release(id: string): Promise<void>;
-    /** Listen for changes (callback called on every change). */
-    onChange(callback: (entities: T[]) => void, options?: ModelListOptions<T>): () => void;
+}
+export interface ModelOperations<T, CreateInput> {
     /**
-     * Load matching rows into the local graph if they are not already
-     * present. Single-flight: concurrent calls with the same args share
-     * one in-flight request. Default `type: 'complete'` waits for the
-     * server; `type: 'unknown'` returns local + refreshes async.
+     * Read a single entity by id from the **server** — async. Resolves through
+     * the 3-tier lookup (local pool → IndexedDB → network `POST /sync/query`)
+     * and lands the row in the local graph. Resolves to `undefined` when no
+     * such row exists.
+     *
+     * This is the default "get me this entity" read and the one hosted /
+     * stateless callers want, since their local graph starts empty. For a
+     * synchronous read of an already-warm graph (a React selector) use
+     * `get(id)`.
+     *
+     * Mirrors `stripe.customers.retrieve(id)` — network-backed.
+     */
+    retrieve(id: string, options?: ModelRetrieveOptions): Promise<T | undefined>;
+    /**
+     * List entities matching a filter from the **server** — async. Same 3-tier
+     * lookup + graph hydration as `retrieve`; single-flight deduped. Returns the
+     * matched rows.
+     *
+     * Mirrors `stripe.customers.list({...})` — network-backed. For a synchronous
+     * read of the local graph use `getAll(...)`.
+     */
+    list(options?: ModelLoadOptions<T>): Promise<T[]>;
+    /**
+     * Synchronous snapshot of a single entity from the **local graph** — no
+     * network. Returns `undefined` when the row isn't resident (cold hosted
+     * client, or a `lazy` model not yet loaded). Pairs with reactive selectors:
+     * `useAblo((ablo) => ablo.<model>.get(id))`.
+     */
+    get(id: string): T | undefined;
+    /**
+     * Synchronous snapshot of a filtered collection from the **local graph** —
+     * no network round-trip. Empty until `retrieve`/`list`/bootstrap has warmed
+     * the graph.
      */
-    load(options?: ModelLoadOptions<T>): Promise<T[]>;
+    getAll(options?: ModelListOptions<T>): T[];
+    /** Count entities in the **local graph** (synchronous, no network). */
+    getCount(options?: ModelCountOptions<T>): number;
+    /**
+     * Create a new entity — **optimistic, offline-first**. Resolves once
+     * the mutation is queued locally, not when the server confirms.
+     * Server rejection rolls back automatically; watch `sync.syncStatus`.
+     */
+    create(data: CreateInput, options?: MutationOptions): Promise<T>;
+    /** Update an entity by id — optimistic, offline-first (see `create`). */
+    update(id: string, data: Partial<T>, options?: MutationOptions): Promise<T>;
+    /** Delete an entity by id — optimistic, offline-first (see `create`). */
+    delete(id: string, options?: MutationOptions): Promise<void>;
+    /**
+     * Claim a row so other writers wait or are rejected until you're done, and
+     * inspect or manage that coordination through the same namespace. Call it to
+     * take a claim (the callback form releases when the callback returns or
+     * throws); reach for its members to observe and steer the wait line:
+     *
+     * - `claim.state(id)` — who holds the row now, or `null` when free
+     * - `claim.queue(id)` — who's lined up behind the holder
+     * - `claim.release(id)` — drop a claim early (usually implicit on scope exit)
+     * - `claim.reorder(id, order)` — re-rank the wait line
+     *
+     * ```ts
+     * await ablo.weatherReports.claim('report_stockholm', async (report) => {
+     *   const weather = await getWeather(report.location);
+     *   await ablo.weatherReports.update(report.id, { forecast: weather });
+     * });
+     *
+     * const holder = ablo.weatherReports.claim.state('report_stockholm');
+     * ```
+     */
+    claim: ClaimApi<T>;
+    /** Listen for changes (callback called on every change). */
+    onChange(callback: (entities: T[]) => void, options?: ModelListOptions<T>): () => void;
 }
 export declare function createModelProxy<T, C>(schemaKey: string, registeredModelName: string, objectPool: ObjectPool, syncClient: SyncClient, registry: ModelRegistry, hydration: HydrationCoordinator, collaboration?: ModelCollaboration<T>): ModelOperations<T, C>;

package/dist/client/createModelProxy.js

@@ -7,13 +7,15 @@
  * testable in isolation and the constructor doesn't carry it.
  *
  * Each schema model gets one `ModelOperations<T, CreateInput>` —
- * exposes `retrieve`, `list`, `count`, `create`, `update`, `delete`,
- * `claim`, `claimState`, `queue`, `release`, `subscribe`, and `load`.
- * The factory returns a plain object; the client assembles the
- * `ablo.<model>` lookup table from these.
+ * exposes the async server reads `retrieve` / `list`, the synchronous
+ * local-graph snapshots `get` / `getAll` / `getCount`, the writes
+ * `create` / `update` / `delete`, the coordination namespace `claim`
+ * (`claim(id, work)` plus `claim.state` / `claim.queue` / `claim.release` /
+ * `claim.reorder`), and `onChange`. The factory returns a plain object; the
+ * client assembles the `ablo.<model>` lookup table from these.
  */
 import { autorun } from 'mobx';
-import { AbloClaimedError, AbloValidationError } from '../errors.js';
+import { AbloClaimedError, AbloValidationError, toAbloError, } from '../errors.js';
 import { Model, modelAsRow } from '../Model.js';
 import { ModelScope } from '../types/index.js';
 const modelClientMeta = new WeakMap();
@@ -28,6 +30,22 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         throw new AbloValidationError(`Ablo: schema model "${schemaKey}" resolved to "${registeredModelName}", ` +
             'but no matching constructor was registered.', { code: 'model_not_registered' });
     }
+    // Last-line guarantee for the public surface: any rejection from a lower
+    // layer (transport timeout, IndexedDB failure, a third-party throw) is
+    // coerced to an AbloError before it reaches the consumer. The SDK's
+    // contract is that callers only ever catch tagged errors — `instanceof
+    // AbloError` / `e.type` always hold. Internal helpers stay unwrapped; only
+    // the methods exposed on `operations` are guarded.
+    const guard = (fn) => {
+        return async (...args) => {
+            try {
+                return await fn(...args);
+            }
+            catch (err) {
+                throw toAbloError(err);
+            }
+        };
+    };
     const load = async (options) => {
         const rows = await hydration.fetch(schemaKey, options);
         // The coordinator returns Model instances. ModelOperations is
@@ -129,11 +147,39 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         }
         return takeClaim(id, a);
     }
+    // `claim` is a callable namespace: invoke it to take a claim, reach its
+    // members to read/steer the coordination plane. Attach the readers to the
+    // guarded callable so `ablo.<model>.claim(...)` and `ablo.<model>.claim.state(...)`
+    // are the same object.
+    const claimApi = Object.assign(guard(claim), {
+        state(id) {
+            return collaboration?.observe({ model: schemaKey, id }) ?? null;
+        },
+        queue(id) {
+            return {
+                object: 'list',
+                data: collaboration?.queue({ model: schemaKey, id }) ?? [],
+            };
+        },
+        reorder(id, order) {
+            collaboration?.reorder({ model: schemaKey, id }, order);
+        },
+        release: guard((id) => releaseClaim(id)),
+    });
     const operations = {
-        retrieve(id) {
+        retrieve: guard(async (id, options) => {
+            const rows = await load({
+                ...options,
+                where: { id },
+                limit: 1,
+            });
+            return rows[0];
+        }),
+        list: guard(load),
+        get(id) {
             return objectPool.get(id);
         },
-        list(options) {
+        getAll(options) {
             const all = objectPool.getByType(ModelClass, (options?.state ?? ModelScope.live));
             let result = all;
             if (options?.where) {
@@ -166,10 +212,10 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 result = result.slice(0, options.limit);
             return result;
         },
-        count(options) {
-            return this.list(options).length;
+        getCount(options) {
+            return this.getAll(options).length;
         },
-        async create(data, options) {
+        create: guard(async (data, options) => {
             // TODO(options-persistence): stash `options` alongside the
             // queued transaction so idempotencyKey survives offline flush.
             const model = new ModelClass({
@@ -181,8 +227,8 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             syncClient.add(model, options);
             await waitForMutation(model, options);
             return modelAsRow(model);
-        },
-        async update(id, data, options) {
+        }),
+        update: guard(async (id, data, options) => {
             const model = objectPool.get(id);
             if (!model)
                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
@@ -202,37 +248,23 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             syncClient.update(model, effective);
             await waitForMutation(model, effective);
             return modelAsRow(model);
-        },
-        async delete(id, options) {
+        }),
+        delete: guard(async (id, options) => {
             const model = objectPool.get(id);
             if (!model)
                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
             syncClient.delete(model, options);
             await waitForMutation(model, options);
-        },
-        claim,
-        claimState(id) {
-            return collaboration?.observe({ model: schemaKey, id }) ?? null;
-        },
-        queue(id) {
-            return {
-                object: 'list',
-                data: collaboration?.queue({ model: schemaKey, id }) ?? [],
-            };
-        },
-        reorder(id, order) {
-            collaboration?.reorder({ model: schemaKey, id }, order);
-        },
-        release(id) {
-            return releaseClaim(id);
-        },
+        }),
+        // `claim` is a callable namespace (take a claim) carrying the coordination
+        // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).
+        claim: claimApi,
         onChange(callback, options) {
             return autorun(() => {
-                const entities = this.list(options);
+                const entities = this.getAll(options);
                 callback(entities);
             });
         },
-        load,
     };
     modelClientMeta.set(operations, {
         key: schemaKey,

package/dist/client/identity.js

@@ -44,6 +44,20 @@ export async function resolveParticipantIdentity(input) {
     // Branch 2: self-derived (capability token present, identity unknown)
     if (!internalOptions.organizationId ||
         (kind === 'agent' ? !options.agentId : !options.user?.id)) {
+        // Fail fast on the missing-credential case. We're here because there's no
+        // apiKey (Branch 1) and the identity isn't caller-supplied (Branch 3), so
+        // `initialCapToken` is the only thing that can authenticate the
+        // `/auth/identity` call. When it's absent — the common cause being
+        // `getToken()` resolving to `null` (no/expired session, see
+        // `getSyncCapabilityToken`) — the request can only come back as the server's
+        // opaque `identity_resolve_failed: no_matching_provider`. Surface the real
+        // condition locally instead: `session_expired` is the registered,
+        // re-authenticate-able code, and we never make a doomed round-trip.
+        if (!initialCapToken) {
+            throw new AbloAuthenticationError('No auth token available to resolve identity — the session token is ' +
+                'missing or expired. Ensure `getToken()` returns a valid token, or ' +
+                'pass `apiKey` / `capabilityToken`.', { code: 'session_expired' });
+        }
         const baseUrl = options.bootstrapBaseUrl ?? `${url.replace(/^ws/, 'http')}/api`;
         const identity = await resolveIdentity({
             baseUrl,

package/dist/client/registerDataSource.d.ts

@@ -0,0 +1,19 @@
+export interface RegisterDataSourceInput {
+    /** HTTP API base, e.g. `https://api.abloatai.com/api` (from resolveBootstrapBaseUrl). */
+    readonly baseUrl: string;
+    /** Secret key (`sk_…`) used to authenticate + derive the org. */
+    readonly apiKey: string | null;
+    /** The customer's own Postgres connection string. */
+    readonly databaseUrl: string;
+    /** Optional Postgres schema (defaults server-side to `public`). */
+    readonly schema?: string;
+    /** Custom fetch (tests/proxies/odd runtimes). */
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * POST the connection string to the self-serve datasource route. Resolves on
+ * success (the org is now a dedicated tenant pointed at this DB); throws an
+ * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
+ * surfaces it instead of silently bootstrapping against the wrong store.
+ */
+export declare function registerDataSource(input: RegisterDataSourceInput): Promise<void>;

package/dist/client/registerDataSource.js

@@ -0,0 +1,57 @@
+/**
+ * Self-serve data-source registration.
+ *
+ * When a client is constructed with `databaseUrl`, the SDK registers that
+ * connection string as the project's own-Postgres data store BEFORE bootstrap,
+ * so the server resolves the org's data plane to the customer's DB and writes
+ * synced rows back into it (dedicated/BYO tenant).
+ *
+ * The org is derived server-side from the API key — the caller never sends an
+ * organization id. The connection string is sent once over TLS and is never
+ * echoed back (the server stores it as a secret and returns only a safe
+ * `datasource` projection: host, database, schema).
+ */
+import { AbloError } from '../errors.js';
+/**
+ * POST the connection string to the self-serve datasource route. Resolves on
+ * success (the org is now a dedicated tenant pointed at this DB); throws an
+ * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
+ * surfaces it instead of silently bootstrapping against the wrong store.
+ */
+export async function registerDataSource(input) {
+    if (!input.apiKey) {
+        throw new AbloError('databaseUrl requires an apiKey to register the data source (the org is derived from the key).', { code: 'datasource_registration_failed' });
+    }
+    const doFetch = input.fetchImpl ?? fetch;
+    const endpoint = `${input.baseUrl.replace(/\/+$/, '')}/v1/datasource`;
+    let response;
+    try {
+        response = await doFetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${input.apiKey}`,
+            },
+            body: JSON.stringify({
+                connectionString: input.databaseUrl,
+                ...(input.schema ? { schema: input.schema } : {}),
+            }),
+        });
+    }
+    catch (cause) {
+        throw new AbloError('Could not reach the Ablo API to register databaseUrl.', {
+            code: 'datasource_registration_failed',
+            cause,
+        });
+    }
+    if (!response.ok) {
+        let detail = '';
+        try {
+            detail = (await response.text()).slice(0, 500);
+        }
+        catch {
+            // ignore body read failures — the status alone is enough to fail loud
+        }
+        throw new AbloError(`databaseUrl registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
+    }
+}

package/dist/client/validateAbloOptions.d.ts

@@ -10,6 +10,7 @@
  * because the error messages reference URLs and would mislead if a
  * URL was actually present.
  */
+import { AbloError } from '../errors.js';
 /**
  * Minimal subset of `AbloOptions` the validator actually inspects.
  * Defined here as its own interface so the validator doesn't pull
@@ -39,4 +40,4 @@ export interface ValidateAbloOptionsInput {
     readonly configuredApiKey: unknown;
     readonly configuredAuthToken: unknown;
 }
-export declare function validateAbloOptions(input: ValidateAbloOptionsInput): Error | null;
+export declare function validateAbloOptions(input: ValidateAbloOptionsInput): AbloError | null;

package/dist/client/validateAbloOptions.js

@@ -10,12 +10,13 @@
  * because the error messages reference URLs and would mislead if a
  * URL was actually present.
  */
+import { AbloValidationError } from '../errors.js';
 export function validateAbloOptions(input) {
     const { options, url, configuredApiKey, configuredAuthToken } = input;
     const kind = options.kind ?? 'user';
     if (!url) {
-        return new Error('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
-            `Ablo({ baseURL: 'wss://sync.abloatai.com', schema, user })`);
+        return new AbloValidationError('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
+            `Ablo({ baseURL: 'wss://sync.abloatai.com', schema, user })`, { code: 'base_url_missing' });
     }
     // Schema is optional for the model-first API:
     //   Ablo({ apiKey }).model('clauses').retrieve(...)
@@ -26,18 +27,18 @@ export function validateAbloOptions(input) {
         kind === 'user' &&
         options.user &&
         !options.user.id) {
-        return new Error('Ablo: `user.id` must be a non-empty string when `user` is provided.');
+        return new AbloValidationError('Ablo: `user.id` must be a non-empty string when `user` is provided.', { code: 'invalid_options', param: 'user.id' });
     }
     if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.agentId) {
-        return new Error('Ablo: provide either `apiKey` or `agentId` for `kind: "agent"`. ' +
+        return new AbloValidationError('Ablo: provide either `apiKey` or `agentId` for `kind: "agent"`. ' +
             'Hosted-cloud consumers pass `apiKey` and the server derives the ' +
             'agent identity from its scope; self-hosted passes `agentId` + ' +
-            '`capabilityToken` directly.');
+            '`capabilityToken` directly.', { code: 'invalid_options', param: 'agentId' });
     }
     if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.capabilityToken) {
-        return new Error('Ablo: provide either `apiKey` (hosted cloud — SDK exchanges internally) ' +
+        return new AbloValidationError('Ablo: provide either `apiKey` (hosted cloud — SDK exchanges internally) ' +
             'or `capabilityToken` (self-hosted — your auth layer mints + hands in). ' +
-            'See https://abloatai.com/docs/api-keys for the full pattern.');
+            'See https://abloatai.com/docs/api-keys for the full pattern.', { code: 'invalid_options', param: 'capabilityToken' });
     }
     return null;
 }

package/dist/errorCodes.d.ts

@@ -36,7 +36,7 @@
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export declare const ERROR_CONTRACT_VERSION = "2026-05-28";
+export declare const ERROR_CONTRACT_VERSION = "2026-05-29";
 /** Coarse grouping for metrics dashboards and docs sectioning. */
 export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'intent' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
 /** One registry entry. `httpStatus` is present only for `surface: 'wire'`
@@ -69,10 +69,25 @@ export declare const ERROR_CODES: {
     readonly capability_id_missing: ErrorCodeSpec;
     readonly exchange_failed: ErrorCodeSpec;
     readonly identity_resolve_failed: ErrorCodeSpec;
+    readonly auth_no_credentials: ErrorCodeSpec;
+    readonly identity_missing_organization: ErrorCodeSpec;
     readonly session_expired: ErrorCodeSpec;
+    readonly jwt_invalid: ErrorCodeSpec;
+    readonly jwt_malformed: ErrorCodeSpec;
+    readonly jwt_missing_issuer: ErrorCodeSpec;
+    readonly jwt_issuer_untrusted: ErrorCodeSpec;
+    readonly jwt_signature_invalid: ErrorCodeSpec;
+    readonly jwt_audience_mismatch: ErrorCodeSpec;
+    readonly jwt_missing_subject: ErrorCodeSpec;
+    readonly jwt_missing_organization: ErrorCodeSpec;
+    readonly jwt_expired: ErrorCodeSpec;
+    readonly jwt_org_membership_denied: ErrorCodeSpec;
     readonly file_upload_auth_required: ErrorCodeSpec;
     readonly browser_apikey_blocked: ErrorCodeSpec;
+    readonly browser_database_url_blocked: ErrorCodeSpec;
+    readonly datasource_registration_failed: ErrorCodeSpec;
     readonly capability_scope_denied: ErrorCodeSpec;
+    readonly issuer_register_forbidden: ErrorCodeSpec;
     readonly capability_invalid: ErrorCodeSpec;
     readonly byo_role_cannot_enforce_rls: ErrorCodeSpec;
     readonly byo_role_unreadable: ErrorCodeSpec;
@@ -92,6 +107,7 @@ export declare const ERROR_CODES: {
     readonly commit_operation_required: ErrorCodeSpec;
     readonly commit_operation_model_required: ErrorCodeSpec;
     readonly commit_operations_ambiguous: ErrorCodeSpec;
+    readonly commit_too_many_operations: ErrorCodeSpec;
     readonly model_required_field_missing: ErrorCodeSpec;
     readonly model_identifier_missing: ErrorCodeSpec;
     readonly snapshot_reserved_key: ErrorCodeSpec;
@@ -103,6 +119,11 @@ export declare const ERROR_CODES: {
     readonly model_not_found: ErrorCodeSpec;
     readonly mutate_update_entity_not_found: ErrorCodeSpec;
     readonly task_id_missing: ErrorCodeSpec;
+    readonly not_null_violation: ErrorCodeSpec;
+    readonly foreign_key_violation: ErrorCodeSpec;
+    readonly unique_violation: ErrorCodeSpec;
+    readonly check_violation: ErrorCodeSpec;
+    readonly constraint_violation: ErrorCodeSpec;
     readonly server_execute_unknown_model: ErrorCodeSpec;
     readonly mutate_create_unknown_model: ErrorCodeSpec;
     readonly tenant_model_columns_unknown: ErrorCodeSpec;
@@ -155,6 +176,7 @@ export declare const ERROR_CODES: {
     readonly quota_lookup_failed: ErrorCodeSpec;
     readonly turn_open_failed: ErrorCodeSpec;
     readonly turn_close_failed: ErrorCodeSpec;
+    readonly invalid_options: ErrorCodeSpec;
     readonly no_ablo_provider: ErrorCodeSpec;
     readonly no_sync_group_provider: ErrorCodeSpec;
     readonly sync_context_missing_provider: ErrorCodeSpec;