@abloatai/ablo 0.6.0 → 0.8.0

package/dist/client/auth.js

@@ -27,6 +27,15 @@ export function resolveApiKey(input) {
 export function resolveAuthToken(input) {
     return input.options.authToken ?? null;
 }
+/**
+ * Resolve the customer's own-Postgres connection string for write-back
+ * (dedicated/BYO tenant). Falls back to `DATABASE_URL` — the Prisma-style
+ * convention — so a server-side app that already exports it needs no extra
+ * config. Returns null for Ablo-managed storage (the hosted default).
+ */
+export function resolveDatabaseUrl(input) {
+    return input.options.databaseUrl ?? input.env.DATABASE_URL ?? null;
+}
 export const ABLO_DEFAULT_BASE_URL = 'wss://mesh.ablo.finance';
 export function resolveBaseURL(input) {
     return input.options.baseURL ?? ABLO_DEFAULT_BASE_URL;
@@ -35,11 +44,13 @@ export function resolveBaseURL(input) {
  * Browser guard — apiKey is server-side-only by default. Same check
  * Anthropic, OpenAI, and Stripe ship: shipping `sk_live_...` to a
  * browser exposes it in every visitor's network tab. Consumers opt
- * in explicitly when they have a publishable key or a server proxy.
+ * in explicitly when the browser holds a minted session token
+ * (`ek_`/`rk_`) or routes through a server proxy.
  */
 export function assertBrowserSafety(input) {
+    const inBrowser = typeof window !== 'undefined';
     if (!input.dangerouslyAllowBrowser &&
-        typeof window !== 'undefined' &&
+        inBrowser &&
         typeof input.apiKey === 'string' &&
         input.apiKey.startsWith('sk_')) {
         throw new AbloAuthenticationError("It looks like you're running in a browser-like environment.\n\n" +
@@ -49,6 +60,14 @@ export function assertBrowserSafety(input) {
             '`dangerouslyAllowBrowser` option to `true`, e.g.,\n\n' +
             '    Ablo({ schema, apiKey, dangerouslyAllowBrowser: true });\n', { code: 'browser_apikey_blocked' });
     }
+    // `databaseUrl` carries DB credentials and is NEVER browser-safe, so
+    // `dangerouslyAllowBrowser` does not override it. Register your database from
+    // a server-side runtime.
+    if (inBrowser && typeof input.databaseUrl === 'string' && input.databaseUrl.length > 0) {
+        throw new AbloAuthenticationError('Ablo `databaseUrl` cannot be used in a browser-like environment — it ' +
+            'carries your database credentials. Initialize the client with ' +
+            '`databaseUrl` from a server-side runtime only.', { code: 'browser_database_url_blocked' });
+    }
 }
 /**
  * Resolve an `ApiKeySetter` callable to its current string value.

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';
@@ -35,10 +37,12 @@ export interface ModelListOptions<T> {
     };
     limit?: number;
     offset?: number;
-    /** Lifecycle scope. Defaults to live rows. */
-    scope?: ModelListScope;
+    /** Lifecycle filter — `live` (default), `archived`, or `all`. Named `state`
+     *  (GitHub's open/closed/all precedent) so it doesn't collide with the
+     *  sync-group `scope`. */
+    state?: ModelListScope;
 }
-export type ModelCountOptions<T> = Pick<ModelListOptions<T>, 'where' | 'filter' | 'scope'>;
+export type ModelCountOptions<T> = Pick<ModelListOptions<T>, 'where' | 'filter' | 'state'>;
 export interface ModelLoadOptions<T> {
     /**
      * Filter for the lookup. Accepts:
@@ -46,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?: {
@@ -66,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>;
@@ -109,6 +116,14 @@ export interface ModelCollaboration<T> {
         model: string;
         id: string;
     }): readonly Intent[];
+    /**
+     * Re-rank the wait queue on a target (privileged — server-gated). `order` is
+     * the desired front-of-line ordering, taken from `queue(target)`.
+     */
+    reorder(target: {
+        model: string;
+        id: string;
+    }, order: readonly Intent[]): void;
     /**
      * Resolve once no participant holds an active intent on the target.
      * The contender's "wait until it's free" — delegates to the intent
@@ -163,24 +178,99 @@ export interface ClaimOptions {
  * verb — there is no method chaining on the claim.
  */
 export type ClaimedRow<T> = T & AsyncDisposable;
+/**
+ * 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>>;
+    /**
+     * Take a claim, run `work` with the held row, release when it settles. The
+     * preferred form for ordinary held work.
+     */
+    <R>(id: string, work: (row: ClaimedRow<T>) => Promise<R> | R, options?: ClaimOptions): Promise<R>;
+    /**
+     * 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.
+     */
+    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.claim.queue('deck_1');
+     * // → [{ heldBy: 'agent:summarizer', action: 'editing', position: 0 }, …]
+     * ```
+     */
+    queue(id: string): {
+        readonly object: 'list';
+        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 `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 `claim.queue(id)`.
+     *
+     * ```ts
+     * 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>;
+}
 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.
+     * 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.
      *
-     * Mirrors `stripe.customers.retrieve(id)`.
+     * 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): T | undefined;
+    retrieve(id: string, options?: ModelRetrieveOptions): Promise<T | undefined>;
     /**
-     * List entities matching a filter from the local pool. Synchronous.
-     * No network round-trip — use `load()` for hydration.
+     * 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({...})`.
+     * 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))`.
      */
-    list(options?: ModelListOptions<T>): T[];
-    /** Count entities matching a filter (synchronous, from local pool). */
-    count(options?: ModelCountOptions<T>): number;
+    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.
+     */
+    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.
@@ -192,50 +282,27 @@ export interface ModelOperations<T, CreateInput> {
     /** 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.
-     * 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.
+     * 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 });
      * });
-     * ```
-     */
-    claim(id: string, options?: ClaimOptions): Promise<ClaimedRow<T>>;
-    claim<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.
-     */
-    claimState(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');
-     * // → [{ heldBy: 'agent:summarizer', action: 'editing', position: 0 }, …]
+     * const holder = ablo.weatherReports.claim.state('report_stockholm');
      * ```
      */
-    queue(id: string): {
-        readonly object: 'list';
-        readonly data: readonly Intent[];
-    };
-    /** Release a claim you hold early. Usually implicit (scope exit). */
-    release(id: string): Promise<void>;
+    claim: ClaimApi<T>;
     /** Listen for changes (callback called on every change). */
     onChange(callback: (entities: T[]) => void, options?: ModelListOptions<T>): () => void;
-    /**
-     * 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.
-     */
-    load(options?: ModelLoadOptions<T>): Promise<T[]>;
 }
 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,12 +147,40 @@ 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) {
-            const all = objectPool.getByType(ModelClass, (options?.scope ?? ModelScope.live));
+        getAll(options) {
+            const all = objectPool.getByType(ModelClass, (options?.state ?? ModelScope.live));
             let result = all;
             if (options?.where) {
                 const where = 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,34 +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 }) ?? [],
-            };
-        },
-        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.ablo.dev', 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://ablo.dev/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/coordination/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@abloatai/ablo/coordination` — the canonical wire schema for the three
+ * coordination layers (presence, pessimistic claims, optimistic stale-context).
+ * See `./schema.ts` for the model and the per-layer schemas.
+ */
+export * from './schema.js';

package/dist/coordination/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@abloatai/ablo/coordination` — the canonical wire schema for the three
+ * coordination layers (presence, pessimistic claims, optimistic stale-context).
+ * See `./schema.ts` for the model and the per-layer schemas.
+ */
+export * from './schema.js';