@abloatai/ablo 0.6.0 → 0.8.0

package/dist/errors.d.ts

@@ -18,27 +18,71 @@
  *
  * Both work on every subclass.
  */
+import type { ErrorCode } from './errorCodes.js';
+export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec } from './errorCodes.js';
+export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode } from './errorCodes.js';
 /** Common shape for all errors thrown by this SDK. */
 export declare class AbloError extends Error {
     /** Discriminator string — matches the class name. Lets consumers
      *  switch on `e.type` without `instanceof` checks across package
      *  boundaries (matches Stripe's `err.type` pattern). */
     readonly type: string;
-    /** Stable short identifier for logs + metrics.
-     *  E.g. `'apikey_invalid'`, `'capability_scope_denied'`. */
+    /** Stable short identifier for logs + metrics, drawn from the closed
+     *  {@link ErrorCode} registry — e.g. `'apikey_invalid'`,
+     *  `'capability_scope_denied'`. Stored as a plain `string` (not
+     *  `ErrorCode`) so an older SDK still surfaces a newer server's code it
+     *  doesn't recognise yet; producers are constrained at the constructor
+     *  param instead. */
     readonly code?: string;
     /** HTTP status code when the error originated from an HTTP response. */
     readonly httpStatus?: number;
     /** Correlation id for ops — present when the server sent one on
      *  `x-request-id`. Include in support tickets. */
     readonly requestId?: string;
+    /** Which input caused the error — a model/field path like
+     *  `'dataroomMember.grants.subject'`. Mirrors Stripe's `error.param`;
+     *  lets tooling point at the exact offending declaration. */
+    readonly param?: string;
+    /** Link to the docs for this `code`. Mirrors Stripe's `error.doc_url`.
+     *  Defaults from `code` via {@link docUrlForCode} when omitted. */
+    readonly docUrl?: string;
+    /** Domain-specific structured payload merged into the wire envelope —
+     *  e.g. a schema push's `{ warnings, unexecutable }`, a stale write's
+     *  conflicting rows. Mirrors how Stripe attaches type-specific fields
+     *  (`decline_code`, `payment_intent`) alongside the standard ones, so a
+     *  structured error keeps its detail through `toJSON` instead of being
+     *  flattened to a bare message. */
+    readonly details?: Readonly<Record<string, unknown>>;
     constructor(message: string, options?: {
-        code?: string;
+        code?: ErrorCode;
         httpStatus?: number;
         requestId?: string;
         cause?: unknown;
+        param?: string;
+        docUrl?: string;
+        details?: Readonly<Record<string, unknown>>;
     });
+    /**
+     * Serialize to Stripe's error-object shape: `{ type, code, param, message,
+     * doc_url, request_id }`. One JSON shape across HTTP bodies, WS frames, and
+     * logs — so consumers parse Ablo errors the way they already parse Stripe's.
+     */
+    toJSON(): {
+        type: string;
+        code?: string;
+        param?: string;
+        message: string;
+        doc_url?: string;
+        request_id?: string;
+        [key: string]: unknown;
+    };
 }
+/**
+ * Map a stable error `code` to its docs URL — the one place the convention
+ * lives, so every error carrying a code gets a `doc_url` for free (Stripe
+ * ships a link on every error).
+ */
+export declare function docUrlForCode(code: ErrorCode): string;
 /** 401 — invalid/missing/expired credentials. */
 export declare class AbloAuthenticationError extends AbloError {
     readonly type: "AbloAuthenticationError";
@@ -53,11 +97,12 @@ export declare class AbloRateLimitError extends AbloError {
     readonly type: "AbloRateLimitError";
     readonly retryAfterSeconds?: number;
     constructor(message: string, options?: {
-        code?: string;
+        code?: ErrorCode;
         httpStatus?: number;
         requestId?: string;
         cause?: unknown;
         retryAfterSeconds?: number;
+        details?: Readonly<Record<string, unknown>>;
     });
 }
 /** 409 — same `Idempotency-Key` reused with a different request body. */
@@ -98,7 +143,7 @@ export declare class AbloStaleContextError extends AbloError {
         readonly observedSyncId: number;
     }>;
     constructor(message: string, options?: {
-        code?: string;
+        code?: ErrorCode;
         httpStatus?: number;
         requestId?: string;
         cause?: unknown;
@@ -121,7 +166,7 @@ export declare class AbloClaimedError extends AbloError {
     readonly type: "AbloClaimedError";
     readonly claims?: ReadonlyArray<unknown>;
     constructor(message: string, options?: {
-        code?: string;
+        code?: ErrorCode;
         httpStatus?: number;
         requestId?: string;
         cause?: unknown;
@@ -227,11 +272,62 @@ export declare class SyncSessionError extends AbloAuthenticationError {
      */
     static isSessionErrorResponse(status: number, body?: string): boolean;
 }
+/**
+ * Coerce ANY thrown value into an {@link AbloError} — the last-line guarantee
+ * that an SDK consumer never catches an untagged error. An already-typed
+ * AbloError passes through untouched (so `code`/`httpStatus`/subclass survive);
+ * a bare `Error` keeps its message and is preserved as `cause` (carrying any
+ * `.code` someone attached); a non-Error is stringified.
+ *
+ * This is the client mirror of the server's `normalizeError` — applied at the
+ * SDK's public async boundaries so `instanceof AbloError` / `e.type` always
+ * hold for whatever a consumer catches, regardless of which internal layer
+ * (transport, IndexedDB, bootstrap, a third-party throw) produced it.
+ */
+export declare function toAbloError(err: unknown): AbloError;
+/**
+ * Build the appropriate typed {@link AbloError} from a wire error — the
+ * single code→class mapping shared by every transport that can reject a
+ * request (HTTP responses via {@link translateHttpError}, WebSocket
+ * `mutation_result`/`claim_ack` frames, agent-job receipts).
+ *
+ * Code-first, then status-driven. A known {@link ErrorCode} carries its own
+ * canonical `httpStatus` in the registry, so frame transports that don't have
+ * an HTTP status (the WebSocket commit path) still produce the right subclass
+ * — instead of a hand-rolled `new Error(message)` that drops out of the typed
+ * hierarchy and loses `code`/`httpStatus`/retryability.
+ */
+export declare function errorFromWire(message: string, opts?: {
+    code?: string;
+    /** Explicit transport status (HTTP). When omitted, derived from the
+     *  registry spec for `code` so frame transports map correctly too. */
+    httpStatus?: number;
+    requestId?: string;
+    requiredCapability?: RequiredCapability;
+}): AbloError;
 /**
  * Translate an HTTP response into the appropriate typed error.
  *
  * Single source of truth for status-code → class mapping — every SDK
  * fetch path that sees a non-2xx response should route through here
- * so the customer-visible error is always the right subclass.
+ * so the customer-visible error is always the right subclass. Delegates
+ * the actual class selection to {@link errorFromWire} (shared with the
+ * frame transports) after extracting code/message from the HTTP body.
  */
 export declare function translateHttpError(status: number, body: unknown, requestId?: string): AbloError;
+/**
+ * Whether an HTTP error body carries a code {@link translateHttpError} can read
+ * — a top-level `code`, a nested `error.code`, or a string `error`. Callers that
+ * own a meaningful fallback code (e.g. `turn_open_failed`) use this to decide
+ * between routing through `translateHttpError` (structured envelope present) and
+ * throwing their own typed error with the fallback (bare/non-Ablo body), instead
+ * of emitting a code-less error.
+ */
+export declare function hasWireCode(body: unknown): boolean;
+/**
+ * Extract the canonical error `code` from a raw HTTP error body STRING — the
+ * top-level `code` or a nested `error.code`. Returns undefined for non-JSON or
+ * code-less bodies. Used by session-error detection to tell a genuine expiry
+ * (`session_expired`/`jwt_expired`) apart from other auth failures.
+ */
+export declare function extractWireCode(body?: string): string | undefined;

package/dist/errors.js

@@ -18,6 +18,8 @@
  *
  * Both work on every subclass.
  */
+import { errorCodeSpec } from './errorCodes.js';
+export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode } from './errorCodes.js';
 // ── AbloError hierarchy — the typed error surface ────────────────────
 /** Common shape for all errors thrown by this SDK. */
 export class AbloError extends Error {
@@ -25,14 +27,32 @@ export class AbloError extends Error {
      *  switch on `e.type` without `instanceof` checks across package
      *  boundaries (matches Stripe's `err.type` pattern). */
     type = 'AbloError';
-    /** Stable short identifier for logs + metrics.
-     *  E.g. `'apikey_invalid'`, `'capability_scope_denied'`. */
+    /** Stable short identifier for logs + metrics, drawn from the closed
+     *  {@link ErrorCode} registry — e.g. `'apikey_invalid'`,
+     *  `'capability_scope_denied'`. Stored as a plain `string` (not
+     *  `ErrorCode`) so an older SDK still surfaces a newer server's code it
+     *  doesn't recognise yet; producers are constrained at the constructor
+     *  param instead. */
     code;
     /** HTTP status code when the error originated from an HTTP response. */
     httpStatus;
     /** Correlation id for ops — present when the server sent one on
      *  `x-request-id`. Include in support tickets. */
     requestId;
+    /** Which input caused the error — a model/field path like
+     *  `'dataroomMember.grants.subject'`. Mirrors Stripe's `error.param`;
+     *  lets tooling point at the exact offending declaration. */
+    param;
+    /** Link to the docs for this `code`. Mirrors Stripe's `error.doc_url`.
+     *  Defaults from `code` via {@link docUrlForCode} when omitted. */
+    docUrl;
+    /** Domain-specific structured payload merged into the wire envelope —
+     *  e.g. a schema push's `{ warnings, unexecutable }`, a stale write's
+     *  conflicting rows. Mirrors how Stripe attaches type-specific fields
+     *  (`decline_code`, `payment_intent`) alongside the standard ones, so a
+     *  structured error keeps its detail through `toJSON` instead of being
+     *  flattened to a bare message. */
+    details;
     constructor(message, options) {
         super(message);
         this.name = this.constructor.name;
@@ -42,10 +62,41 @@ export class AbloError extends Error {
             this.httpStatus = options.httpStatus;
         if (options?.requestId !== undefined)
             this.requestId = options.requestId;
+        if (options?.param !== undefined)
+            this.param = options.param;
+        if (options?.details !== undefined)
+            this.details = options.details;
+        const docUrl = options?.docUrl ?? (options?.code ? docUrlForCode(options.code) : undefined);
+        if (docUrl !== undefined)
+            this.docUrl = docUrl;
         if (options?.cause !== undefined) {
             Object.defineProperty(this, 'cause', { value: options.cause, enumerable: false });
         }
     }
+    /**
+     * Serialize to Stripe's error-object shape: `{ type, code, param, message,
+     * doc_url, request_id }`. One JSON shape across HTTP bodies, WS frames, and
+     * logs — so consumers parse Ablo errors the way they already parse Stripe's.
+     */
+    toJSON() {
+        return {
+            type: this.type,
+            ...(this.code !== undefined ? { code: this.code } : {}),
+            ...(this.param !== undefined ? { param: this.param } : {}),
+            message: this.message,
+            ...(this.docUrl !== undefined ? { doc_url: this.docUrl } : {}),
+            ...(this.requestId !== undefined ? { request_id: this.requestId } : {}),
+            ...(this.details ?? {}),
+        };
+    }
+}
+/**
+ * Map a stable error `code` to its docs URL — the one place the convention
+ * lives, so every error carrying a code gets a `doc_url` for free (Stripe
+ * ships a link on every error).
+ */
+export function docUrlForCode(code) {
+    return `https://docs.abloatai.com/errors#${code}`;
 }
 /** 401 — invalid/missing/expired credentials. */
 export class AbloAuthenticationError extends AbloError {
@@ -187,29 +238,106 @@ export class SyncSessionError extends AbloAuthenticationError {
      * Check if an HTTP response status indicates a session error
      */
     static isSessionErrorResponse(status, body) {
-        if (status === 401)
-            return true;
-        if (status === 403) {
-            if (body) {
-                const lowerBody = body.toLowerCase();
-                if (lowerBody.includes('session') ||
-                    lowerBody.includes('unauthorized') ||
-                    lowerBody.includes('not authenticated') ||
-                    lowerBody.includes('token')) {
-                    return true;
-                }
-            }
-            return true;
+        // Prefer the structured error code: ONLY a genuine session / JWT EXPIRY
+        // should drive sign-out + re-auth. A non-expiry auth failure
+        // (api_key_required, jwt_issuer_untrusted, a 403 permission denial, …) must
+        // NOT — re-authenticating re-mints the same credential and loops, which is
+        // exactly the "flash then bounce to /signin" symptom. This mirrors the
+        // canonical wire mapping (401 → Authentication, 403 → Permission).
+        const code = extractWireCode(body);
+        if (code) {
+            return code === 'session_expired' || code === 'jwt_expired';
         }
-        return false;
+        // No structured code (bare body, non-Ablo proxy response): a 401 is taken as
+        // expiry — the historical default that drives re-auth — while a 403 is a
+        // permission failure, not a session error.
+        return status === 401;
+    }
+}
+/**
+ * Coerce ANY thrown value into an {@link AbloError} — the last-line guarantee
+ * that an SDK consumer never catches an untagged error. An already-typed
+ * AbloError passes through untouched (so `code`/`httpStatus`/subclass survive);
+ * a bare `Error` keeps its message and is preserved as `cause` (carrying any
+ * `.code` someone attached); a non-Error is stringified.
+ *
+ * This is the client mirror of the server's `normalizeError` — applied at the
+ * SDK's public async boundaries so `instanceof AbloError` / `e.type` always
+ * hold for whatever a consumer catches, regardless of which internal layer
+ * (transport, IndexedDB, bootstrap, a third-party throw) produced it.
+ */
+export function toAbloError(err) {
+    if (err instanceof AbloError)
+        return err;
+    if (err instanceof Error) {
+        const rawCode = err.code;
+        const code = typeof rawCode === 'string' ? rawCode : undefined;
+        return new AbloError(err.message, { code, cause: err });
+    }
+    return new AbloError(String(err), { cause: err });
+}
+/**
+ * Build the appropriate typed {@link AbloError} from a wire error — the
+ * single code→class mapping shared by every transport that can reject a
+ * request (HTTP responses via {@link translateHttpError}, WebSocket
+ * `mutation_result`/`claim_ack` frames, agent-job receipts).
+ *
+ * Code-first, then status-driven. A known {@link ErrorCode} carries its own
+ * canonical `httpStatus` in the registry, so frame transports that don't have
+ * an HTTP status (the WebSocket commit path) still produce the right subclass
+ * — instead of a hand-rolled `new Error(message)` that drops out of the typed
+ * hierarchy and loses `code`/`httpStatus`/retryability.
+ */
+export function errorFromWire(message, opts = {}) {
+    const { code, requestId, requiredCapability } = opts;
+    // Effective status: an explicit HTTP status wins; otherwise fall back to
+    // the code's canonical status from the registry (undefined for unknown /
+    // forward-compat codes, which then map to the base AbloError).
+    const httpStatus = opts.httpStatus ?? (code ? errorCodeSpec(code)?.httpStatus : undefined);
+    // Wire boundary: an incoming code is an arbitrary string (a newer server
+    // may send a code this SDK predates). Cast to ErrorCode here — the one
+    // sanctioned crossing — so internal producers stay statically checked.
+    const publicCode = (code === 'intent_conflict' ? 'claim_conflict' : code);
+    const baseOpts = { code: publicCode, httpStatus, requestId };
+    // ── Code-first specials (transport-independent) ──────────────────────
+    // A scoped credential was denied — route through CapabilityError so callers
+    // can read `.requiredCapability` to attenuate-and-retry.
+    if (code === 'capability_scope_denied' || code === 'capability_invalid') {
+        return new CapabilityError(code, message, requiredCapability);
+    }
+    // Claim enforcement (rides 409): the target entity is held by another
+    // participant. Discriminate on code BEFORE the generic 409→idempotency
+    // mapping so a claim rejection surfaces as AbloClaimedError.
+    if (code === 'intent_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
+        return new AbloClaimedError(message, baseOpts);
+    }
+    // A write whose `readAt` watermark went stale — callers re-read and retry.
+    if (code === 'stale_context') {
+        return new AbloStaleContextError(message, baseOpts);
     }
+    // ── Status-driven dispatch (HTTP parity) ─────────────────────────────
+    if (httpStatus === 401)
+        return new AbloAuthenticationError(message, baseOpts);
+    if (httpStatus === 403)
+        return new AbloPermissionError(message, baseOpts);
+    if (httpStatus === 409)
+        return new AbloIdempotencyError(message, baseOpts);
+    if (httpStatus === 422 || httpStatus === 400)
+        return new AbloValidationError(message, baseOpts);
+    if (httpStatus === 429)
+        return new AbloRateLimitError(message, baseOpts);
+    if (httpStatus !== undefined && httpStatus >= 500)
+        return new AbloServerError(message, baseOpts);
+    return new AbloError(message, baseOpts);
 }
 /**
  * Translate an HTTP response into the appropriate typed error.
  *
  * Single source of truth for status-code → class mapping — every SDK
  * fetch path that sees a non-2xx response should route through here
- * so the customer-visible error is always the right subclass.
+ * so the customer-visible error is always the right subclass. Delegates
+ * the actual class selection to {@link errorFromWire} (shared with the
+ * frame transports) after extracting code/message from the HTTP body.
  */
 export function translateHttpError(status, body, requestId) {
     const parsed = typeof body === 'object' && body !== null ? body : {};
@@ -224,30 +352,53 @@ export function translateHttpError(status, body, requestId) {
         flatError ??
         (typeof body === 'string' ? body : `HTTP ${status}`);
     const requiredCapability = nested?.requiredCapability ?? parsed.requiredCapability;
-    const publicCode = code === 'intent_conflict' ? 'claim_conflict' : code;
-    const baseOpts = { code: publicCode, httpStatus: status, requestId };
-    if (status === 401)
-        return new AbloAuthenticationError(message, baseOpts);
-    if (status === 403 || code === 'capability_scope_denied' || code === 'capability_invalid') {
-        if (code === 'capability_scope_denied' || code === 'capability_invalid') {
-            return new CapabilityError(code, message, requiredCapability);
-        }
-        return new AbloPermissionError(message, baseOpts);
+    return errorFromWire(message, { code, httpStatus: status, requestId, requiredCapability });
+}
+/**
+ * Whether an HTTP error body carries a code {@link translateHttpError} can read
+ * — a top-level `code`, a nested `error.code`, or a string `error`. Callers that
+ * own a meaningful fallback code (e.g. `turn_open_failed`) use this to decide
+ * between routing through `translateHttpError` (structured envelope present) and
+ * throwing their own typed error with the fallback (bare/non-Ablo body), instead
+ * of emitting a code-less error.
+ */
+export 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');
+}
+/**
+ * Extract the canonical error `code` from a raw HTTP error body STRING — the
+ * top-level `code` or a nested `error.code`. Returns undefined for non-JSON or
+ * code-less bodies. Used by session-error detection to tell a genuine expiry
+ * (`session_expired`/`jwt_expired`) apart from other auth failures.
+ */
+export function extractWireCode(body) {
+    if (!body)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
     }
-    // Claim enforcement also rides 409 (a commit blocked by a foreign claim).
-    // Discriminate on the code BEFORE the generic idempotency mapping so a
-    // claim rejection surfaces as AbloClaimedError, not AbloIdempotencyError —
-    // same typed error the WebSocket commit path yields for these codes.
-    if (code === 'intent_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
-        return new AbloClaimedError(message, baseOpts);
+    catch {
+        return undefined;
     }
-    if (status === 409)
-        return new AbloIdempotencyError(message, baseOpts);
-    if (status === 422 || status === 400)
-        return new AbloValidationError(message, baseOpts);
-    if (status === 429)
-        return new AbloRateLimitError(message, baseOpts);
-    if (status >= 500)
-        return new AbloServerError(message, baseOpts);
-    return new AbloError(message, baseOpts);
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const b = parsed;
+    if (typeof b.code === 'string')
+        return b.code;
+    if (typeof b.error === 'object' &&
+        b.error !== null &&
+        typeof b.error.code === 'string') {
+        return b.error.code;
+    }
+    return undefined;
 }

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+ * const report = await ablo.weatherReports.retrieve('report_stockholm');
  * await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
  *
  * type Entry = Ablo.Peer;
@@ -23,9 +23,13 @@
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
  *   @abloatai/ablo/testing  — test harnesses + mocks
  *
- * Consumer code should converge on `ablo.<model>.load(...)`, which routes
- * through the engine's `HydrationCoordinator` and dedupes single-flight
- * hydrations.
+ * Reads split by where the data comes from. `ablo.<model>.retrieve(id)` and
+ * `.list({ where })` are the async **server** reads (pool → IDB → network via
+ * the `HydrationCoordinator`, single-flight deduped); they're the default and
+ * what hosted/stateless callers want, since their local graph starts empty.
+ * `ablo.<model>.get(id)` / `.getAll(...)` / `.getCount(...)` are synchronous
+ * **local-graph** snapshots with no network round-trip — for reactive React
+ * selectors (`useAblo((ablo) => ablo.<model>.get(id))`) once the graph is warm.
  *
  * ── What to import (read this first) ────────────────────────────────
  * Default path — this is all most apps and agents ever need:
@@ -48,9 +52,10 @@ export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
-export { defaultPolicy } from './policy/index.js';
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, } from './errors.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
+export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec } from './errors.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';

package/dist/index.js

@@ -5,7 +5,7 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+ * const report = await ablo.weatherReports.retrieve('report_stockholm');
  * await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
  *
  * type Entry = Ablo.Peer;
@@ -23,9 +23,13 @@
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
  *   @abloatai/ablo/testing  — test harnesses + mocks
  *
- * Consumer code should converge on `ablo.<model>.load(...)`, which routes
- * through the engine's `HydrationCoordinator` and dedupes single-flight
- * hydrations.
+ * Reads split by where the data comes from. `ablo.<model>.retrieve(id)` and
+ * `.list({ where })` are the async **server** reads (pool → IDB → network via
+ * the `HydrationCoordinator`, single-flight deduped); they're the default and
+ * what hosted/stateless callers want, since their local graph starts empty.
+ * `ablo.<model>.get(id)` / `.getAll(...)` / `.getCount(...)` are synchronous
+ * **local-graph** snapshots with no network round-trip — for reactive React
+ * selectors (`useAblo((ablo) => ablo.<model>.get(id))`) once the graph is warm.
  *
  * ── What to import (read this first) ────────────────────────────────
  * Default path — this is all most apps and agents ever need:
@@ -74,11 +78,11 @@ export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest,
 // (reject-on-stale) is already applied server-side, so you only import it
 // to COMPOSE a custom policy. Leave it alone and stale writes are rejected
 // safely by default. Type counterparts live under `Ablo.Conflict.*`.
-export { defaultPolicy } from './policy/index.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 // Typed error hierarchy — Stripe-style. One import gets every class
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
 // Advanced — most apps never import this. Custom (Zero-style) mutators:
 // `ablo.<model>.create/update/delete` already covers normal writes. Reach
 // for `defineMutators` only when you need a named, multi-step mutation with

package/dist/keys/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical Ablo API-key format — the single source of truth for how keys
+ * are minted, hashed, and validated. Both the sync-server (`apiKeyStore`)
+ * and the web control-plane (`generate-key.ts`) consume THIS module, so the
+ * format can no longer drift between the two mint sites (it used to live as
+ * a hand-copied twin kept in sync by a comment).
+ *
+ * Node-only — uses `node:crypto`. Exposed via the `@abloatai/ablo/keys`
+ * subpath and NEVER re-exported from the browser-facing `.` entry, so the
+ * client bundle never pulls in `node:crypto`.
+ *
+ * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
+ * base62 CRC32 checksum>`. The identifiable prefix + CRC32 checksum let
+ * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
+ * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
+ * still validate by hash — they parse here as `checksummed: false`.
+ */
+import { z } from 'zod';
+export declare const API_KEY_KINDS: readonly ["secret", "restricted", "ephemeral"];
+export type ApiKeyKind = (typeof API_KEY_KINDS)[number];
+export declare const API_KEY_ENVS: readonly ["live", "test"];
+export type ApiKeyEnv = (typeof API_KEY_ENVS)[number];
+/** A structurally-valid Ablo API key, parsed into its parts. */
+export interface ParsedApiKey {
+    /** The original plaintext. */
+    raw: string;
+    kind: ApiKeyKind;
+    env: ApiKeyEnv;
+    /** The chars after `<prefix>_<env>_` (body + checksum for new keys). */
+    body: string;
+    /** True when this is the new checksummed format (36-char base62 body). */
+    checksummed: boolean;
+}
+/**
+ * Canonical schema for an Ablo API key. `parse`/`safeParse` returns a typed
+ * {@link ParsedApiKey}; a new checksummed-format key with a BAD checksum is
+ * rejected (the offline-reject), while a legacy key parses as
+ * `checksummed: false` and passes (the server still hash-validates it).
+ */
+export declare const apiKeySchema: z.ZodPipe<z.ZodString, z.ZodTransform<ParsedApiKey, string>>;
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export declare function parseApiKey(raw: string): ParsedApiKey | null;
+/** True when the key uses the new checksummed format (regardless of validity). */
+export declare function isChecksummedKey(raw: string): boolean;
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export declare function keyChecksumMatches(raw: string): boolean;
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export declare function generateApiKey(env?: ApiKeyEnv, kind?: ApiKeyKind): {
+    plaintext: string;
+    hash: string;
+    prefix: string;
+};
+/**
+ * Stable SHA-256 hex of a plaintext key. A fast hash is CORRECT here (not
+ * bcrypt) — API keys are high-entropy random, so there's no dictionary to
+ * defend against. Used at both write (mint) and lookup.
+ */
+export declare function hashApiKey(plaintext: string): string;