@abloatai/ablo 0.5.1 → 0.7.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;
@@ -111,21 +156,21 @@ export declare class AbloStaleContextError extends AbloError {
     });
 }
 /**
- * The target entity currently has an active intent held by another
- * participant and the caller asked the SDK not to return immediately.
+ * The target entity is currently claimed by another participant and the caller
+ * asked the SDK not to read/write through that claim.
  *
- * Use `ifBusy: 'wait'` to wait for the intent stream to clear, or
- * `ifBusy: 'return'` to inspect the active intents yourself.
+ * Use `ifClaimed: 'wait'` to wait for the claim to clear, or
+ * `ifClaimed: 'return'` to inspect active claims yourself.
  */
-export declare class AbloBusyError extends AbloError {
-    readonly type: "AbloBusyError";
-    readonly intents?: ReadonlyArray<unknown>;
+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;
-        intents?: ReadonlyArray<unknown>;
+        claims?: ReadonlyArray<unknown>;
     });
 }
 /**

package/dist/errors.js

@@ -18,6 +18,7 @@
  *
  * Both work on every subclass.
  */
+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 +26,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 +61,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 {
@@ -109,19 +159,19 @@ export class AbloStaleContextError extends AbloError {
     }
 }
 /**
- * The target entity currently has an active intent held by another
- * participant and the caller asked the SDK not to return immediately.
+ * The target entity is currently claimed by another participant and the caller
+ * asked the SDK not to read/write through that claim.
  *
- * Use `ifBusy: 'wait'` to wait for the intent stream to clear, or
- * `ifBusy: 'return'` to inspect the active intents yourself.
+ * Use `ifClaimed: 'wait'` to wait for the claim to clear, or
+ * `ifClaimed: 'return'` to inspect active claims yourself.
  */
-export class AbloBusyError extends AbloError {
-    type = 'AbloBusyError';
-    intents;
+export class AbloClaimedError extends AbloError {
+    type = 'AbloClaimedError';
+    claims;
     constructor(message, options) {
         super(message, options);
-        if (options?.intents !== undefined)
-            this.intents = options.intents;
+        if (options?.claims !== undefined)
+            this.claims = options.claims;
     }
 }
 /**
@@ -224,7 +274,11 @@ export function translateHttpError(status, body, requestId) {
         flatError ??
         (typeof body === 'string' ? body : `HTTP ${status}`);
     const requiredCapability = nested?.requiredCapability ?? parsed.requiredCapability;
-    const baseOpts = { code, httpStatus: status, requestId };
+    // 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: status, requestId };
     if (status === 401)
         return new AbloAuthenticationError(message, baseOpts);
     if (status === 403 || code === 'capability_scope_denied' || code === 'capability_invalid') {
@@ -233,6 +287,13 @@ export function translateHttpError(status, body, requestId) {
         }
         return new AbloPermissionError(message, baseOpts);
     }
+    // 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);
+    }
     if (status === 409)
         return new AbloIdempotencyError(message, baseOpts);
     if (status === 422 || status === 400)

package/dist/index.d.ts

@@ -5,17 +5,17 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * await ablo.tasks.load({ where: { id: 'task_123' } });
- * await ablo.tasks.update('task_123', { title: 'Fix bug' });
+ * await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+ * await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
  *
  * type Entry = Ablo.Peer;
  * ```
  *
- * `Ablo({ schema, apiKey })` gives typed model resources. `Ablo({ apiKey })`
- * gives the lower-level Resource / Intent / Commit client for agents,
- * MCP routes, and custom runtimes.
+ * `Ablo({ schema, apiKey })` gives typed model clients. `Ablo({ apiKey })`
+ * gives the HTTP model/commit client for agents, MCP routes, and custom
+ * runtimes.
  *
- * Stripe / Anthropic / OpenAI all do this: one import, resources
+ * Stripe / Anthropic / OpenAI all do this: one import, model clients
  * reached via dot-access on the engine, types via namespace dots.
  *
  * Public subpaths:
@@ -42,14 +42,16 @@
  * If you don't recognize one, you don't need it — the default path covers you.
  */
 export { Ablo } from './client/Ablo.js';
-export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelIntentHandle, ModelIntentAcquireOptions, ModelOperations, } from './client/Ablo.js';
+export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ClaimOptions, ClaimedRow, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
 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, AbloBusyError, 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, 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,17 +5,17 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * await ablo.tasks.load({ where: { id: 'task_123' } });
- * await ablo.tasks.update('task_123', { title: 'Fix bug' });
+ * await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+ * await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
  *
  * type Entry = Ablo.Peer;
  * ```
  *
- * `Ablo({ schema, apiKey })` gives typed model resources. `Ablo({ apiKey })`
- * gives the lower-level Resource / Intent / Commit client for agents,
- * MCP routes, and custom runtimes.
+ * `Ablo({ schema, apiKey })` gives typed model clients. `Ablo({ apiKey })`
+ * gives the HTTP model/commit client for agents, MCP routes, and custom
+ * runtimes.
  *
- * Stripe / Anthropic / OpenAI all do this: one import, resources
+ * Stripe / Anthropic / OpenAI all do this: one import, model clients
  * reached via dot-access on the engine, types via namespace dots.
  *
  * Public subpaths:
@@ -74,15 +74,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, AbloBusyError, CapabilityError, translateHttpError, } from './errors.js';
-// Typed-global augmentation point. Consumers declare their Schema/Presence/
-// Intents/UserMeta once in a `.d.ts` via `declare global { interface AbloSync
-// { ... } }`. Resolver types live under the `Ablo` namespace —
-// `Ablo.ResolveSchema`, `Ablo.ResolvePresence`, etc. — pure type-level.
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, 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/interfaces/index.d.ts

@@ -151,18 +151,11 @@ export interface CommitResult {
  *   When omitted, the SDK auto-generates a UUIDv4 per mutation so every
  *   call is retry-safe by default. Opt out with `{ idempotencyKey: null }`
  *   if you genuinely want retry-unsafe writes (rare).
- * - `timeout` — abort the request if it takes longer than this many ms.
- *   No default (uses underlying transport's timeout).
- * - `maxNetworkRetries` — retry with exponential backoff on 5xx / 429 /
- *   network errors. The same `idempotencyKey` is reused across retries
- *   so the server dedupes correctly. Default: 0.
  * - `label` — human-readable audit tag. Flows to `mutation_log.label`
  *   server-side for operator debugging ("nightly cleanup", "user click").
  */
 export interface MutationOptions {
     idempotencyKey?: string | null;
-    timeout?: number;
-    maxNetworkRetries?: number;
     label?: string;
     wait?: 'queued' | 'confirmed';
     readAt?: number | null;
@@ -205,9 +198,8 @@ export interface MutationOperation {
     /**
      * Per-op idempotency + audit metadata. `idempotencyKey` doubles as
      * the `mutation_log.client_tx_id` cache key; `label` is persisted to
-     * `mutation_log.label` for debugging. Client-only fields (`timeout`,
-     * `maxNetworkRetries`) are handled at the transport layer and are
-     * NOT sent over the wire.
+     * `mutation_log.label` for debugging. These are the only `MutationOptions`
+     * fields carried over the wire.
      */
     options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
 }

package/dist/mutators/Transaction.d.ts

@@ -21,8 +21,8 @@
  */
 import type { Schema } from '../schema/schema.js';
 import type { SyncStoreContract } from '../react/context.js';
-import { type MutateActions } from '../react/useMutate.js';
-import { type ReaderActions, type ReaderFindOptions } from '../react/useReader.js';
+import { type MutateActions } from './mutateActions.js';
+import { type ReaderActions, type ReaderFindOptions } from './readerActions.js';
 /**
  * The full transaction surface. `tx.mutations.<key>.*` for writes,
  * `tx.read.<key>.*` for imperative reads. Re-exports the base read options

package/dist/mutators/Transaction.js

@@ -19,8 +19,8 @@
  * microtask coalescer in `TransactionQueue` collapses N pushes into one
  * wire commit. Same shape Zero uses: no `insertMany`, just an array map.
  */
-import { createMutateActions } from '../react/useMutate.js';
-import { createReaderActions } from '../react/useReader.js';
+import { createMutateActions } from './mutateActions.js';
+import { createReaderActions } from './readerActions.js';
 import { AbloValidationError } from '../errors.js';
 /**
  * Build a Transaction for a single mutator invocation. The returned object

package/dist/mutators/mutateActions.d.ts

@@ -0,0 +1,44 @@
+import type { Schema, InferModel, InferCreate } from '../schema/schema.js';
+import type { SyncStoreContract } from '../react/context.js';
+/**
+ * `create` / `update` / `delete` are overloaded: pass one row or an array
+ * (Drizzle/Prisma `values(rowOrRows)` shape). Every entry in an array call
+ * lands in the same synchronous tick (`Promise.all`), so the microtask
+ * coalescer in `TransactionQueue` collapses N pushes into one wire commit.
+ *
+ * This module is the React-free core of CRUD staging. The transaction system
+ * (`Transaction` / `RecordingTransaction`) and `BaseSyncedStore` build on it;
+ * there is no React hook here (the legacy `useMutate` hook was removed —
+ * callers use `ablo.<model>.create/update/delete`).
+ */
+type UpdatePatch<S extends Schema, K extends keyof S['models'] & string> = {
+    id: string;
+} & Partial<InferModel<S, K>>;
+export interface MutateActions<S extends Schema, K extends keyof S['models'] & string> {
+    /**
+     * Create one entity, or an array of entities in a single tick. ID,
+     * createdAt, updatedAt, organizationId default automatically per row.
+     */
+    create(data: InferCreate<S, K>): Promise<InferModel<S, K>>;
+    create(data: InferCreate<S, K>[]): Promise<InferModel<S, K>[]>;
+    /**
+     * Update one row, or an array of rows in a single tick. Each patch is
+     * `{ id, ...changes }` — missing ids throw. Schema-generated models are
+     * MobX-observable, so direct assignment fires reactivity.
+     */
+    update(patch: UpdatePatch<S, K>): Promise<InferModel<S, K>>;
+    update(patches: UpdatePatch<S, K>[]): Promise<InferModel<S, K>[]>;
+    /**
+     * Delete one row by id, or an array of ids in a single tick. Missing ids
+     * are silently ignored.
+     */
+    delete(id: string): Promise<void>;
+    delete(ids: string[]): Promise<void>;
+    /** Soft-archive by ID. */
+    archive: (id: string) => Promise<void>;
+    /** Restore an archived entity by ID. */
+    unarchive: (id: string) => Promise<void>;
+}
+/** Pure factory — builds CRUD actions over a store for one model. React-free. */
+export declare function createMutateActions<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, store: SyncStoreContract, organizationId: string): MutateActions<S, K>;
+export {};

package/dist/{react/useMutate.js → mutators/mutateActions.js}

@@ -1,12 +1,6 @@
-'use client';
-import { useMemo } from 'react';
 import { Model, modelAsRow } from '../Model.js';
 import { AbloValidationError } from '../errors.js';
-import { useSyncContext } from './context.js';
-/**
- * Pure factory — testable without React. The hook just wraps this in
- * useMemo with the React context.
- */
+/** Pure factory — builds CRUD actions over a store for one model. React-free. */
 export function createMutateActions(schema, modelKey, store, organizationId) {
     const modelDef = schema.models[modelKey];
     const typename = modelDef?.typename ?? modelKey;
@@ -25,7 +19,7 @@ export function createMutateActions(schema, modelKey, store, organizationId) {
         };
         const model = store.pool.createFromData(fullData);
         if (!model) {
-            throw new AbloValidationError(`useMutate: failed to create ${typename} — no constructor in registry`, { code: 'mutate_create_unknown_model' });
+            throw new AbloValidationError(`createMutateActions: failed to create ${typename} — no constructor in registry`, { code: 'mutate_create_unknown_model' });
         }
         return model;
     };
@@ -34,14 +28,13 @@ export function createMutateActions(schema, modelKey, store, organizationId) {
         const { id, ...changes } = patch;
         const model = store.pool.get(id);
         if (!model) {
-            throw new AbloValidationError(`useMutate: ${typename} with id "${id}" not found in pool`, { code: 'mutate_update_entity_not_found' });
+            throw new AbloValidationError(`createMutateActions: ${typename} with id "${id}" not found in pool`, { code: 'mutate_update_entity_not_found' });
         }
-        // Schema-derived patch keys are validated at the call-site type
-        // signature (`UpdatePatch<S, K>`); writes here are dynamic-class
-        // field assignments. `Reflect.set` is the typed bridge — Model
-        // doesn't carry an index signature for arbitrary string keys, but
-        // the dynamic field installation in `createDynamicModelClass`
-        // guarantees these keys resolve at runtime.
+        // Schema-derived patch keys are validated at the call-site type signature
+        // (`UpdatePatch<S, K>`); writes here are dynamic-class field assignments.
+        // `Reflect.set` is the typed bridge — Model carries no index signature, but
+        // the dynamic field installation in `createDynamicModelClass` guarantees
+        // these keys resolve at runtime.
         for (const [fieldName, value] of Object.entries(changes)) {
             Reflect.set(model, fieldName, value);
         }
@@ -49,9 +42,9 @@ export function createMutateActions(schema, modelKey, store, organizationId) {
         return model;
     };
     return {
-        // Overloaded — runtime check on `Array.isArray` decides shape. Both
-        // branches stage via `Promise.all` so the microtask coalescer in
-        // `TransactionQueue` collapses N pushes into one wire commit.
+        // Overloaded — runtime `Array.isArray` decides shape. Both branches stage
+        // via `Promise.all` so the microtask coalescer collapses N pushes into one
+        // wire commit.
         create: (async (data) => {
             const now = new Date();
             if (Array.isArray(data)) {
@@ -110,13 +103,3 @@ export function createMutateActions(schema, modelKey, store, organizationId) {
         },
     };
 }
-export function useMutate(schemaOrKey, maybeKey) {
-    const { store, organizationId, schema: ctxSchema } = useSyncContext();
-    const resolvedSchema = typeof schemaOrKey === 'string' ? ctxSchema : schemaOrKey;
-    const resolvedKey = typeof schemaOrKey === 'string' ? schemaOrKey : maybeKey;
-    if (!resolvedSchema) {
-        throw new AbloValidationError('useMutate: no schema available. Pass the schema as the first arg ' +
-            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'mutate_schema_missing' });
-    }
-    return useMemo(() => createMutateActions(resolvedSchema, resolvedKey, store, organizationId), [store, organizationId, resolvedSchema, resolvedKey]);
-}

package/dist/mutators/readerActions.d.ts

@@ -0,0 +1,32 @@
+import type { Schema, InferModel } from '../schema/schema.js';
+import type { SyncStoreContract } from '../react/context.js';
+/**
+ * React-free imperative reads over a store: one-off `retrieve`/`list`/`count`
+ * snapshots that do NOT subscribe to changes. Used by the transaction system
+ * and `BaseSyncedStore`. For reactive reads in components use
+ * `useAblo((ablo) => ablo.<model>.retrieve(id) / .list(opts))`.
+ */
+export interface ReaderFindOptions<T> {
+    /** Equality filter — uses FK index when the field is registered. */
+    where?: Partial<T>;
+    /** Predicate applied AFTER `where` filtering. */
+    filter?: (entity: T) => boolean;
+    /** Sort field. */
+    orderBy?: keyof T & string;
+    /** Sort direction. Default: 'asc'. */
+    order?: 'asc' | 'desc';
+    /** Max results. */
+    limit?: number;
+    /** Skip N results. */
+    offset?: number;
+}
+export interface ReaderActions<S extends Schema, K extends keyof S['models'] & string> {
+    /** Get a single entity by id. Returns undefined if not in pool. */
+    retrieve: (id: string) => InferModel<S, K> | undefined;
+    /** Read a collection with optional filters. Snapshot — not reactive. */
+    list: (options?: ReaderFindOptions<InferModel<S, K>>) => InferModel<S, K>[];
+    /** Count entities matching the options. */
+    count: (options?: ReaderFindOptions<InferModel<S, K>>) => number;
+}
+/** Pure factory — builds imperative read actions over a store for one model. */
+export declare function createReaderActions<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, store: SyncStoreContract): ReaderActions<S, K>;

package/dist/{react/useReader.js → mutators/readerActions.js}

@@ -1,15 +1,9 @@
-'use client';
-import { useMemo } from 'react';
-import { useSyncContext } from './context.js';
-import { AbloValidationError } from '../errors.js';
-/**
- * Pure factory — testable without React. `useReader` wraps this in useMemo.
- */
+/** Pure factory — builds imperative read actions over a store for one model. */
 export function createReaderActions(schema, modelKey, store) {
     const modelDef = schema.models[modelKey];
     const typename = modelDef?.typename ?? modelKey;
     function read(options) {
-        // FK index fast path: single-field `where` on a registered FK index → O(1) lookup.
+        // FK index fast path: single-field `where` on a registered FK index → O(1).
         let candidates;
         const whereEntries = options?.where ? Object.entries(options.where) : [];
         const singleWhere = whereEntries.length === 1 ? whereEntries[0] : undefined;
@@ -61,13 +55,3 @@ export function createReaderActions(schema, modelKey, store) {
         count: (options) => read(options).length,
     };
 }
-export function useReader(schemaOrKey, maybeKey) {
-    const { store, schema: ctxSchema } = useSyncContext();
-    const resolvedSchema = typeof schemaOrKey === 'string' ? ctxSchema : schemaOrKey;
-    const resolvedKey = typeof schemaOrKey === 'string' ? schemaOrKey : maybeKey;
-    if (!resolvedSchema) {
-        throw new AbloValidationError('useReader: no schema available. Pass the schema as the first arg ' +
-            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'reader_schema_missing' });
-    }
-    return useMemo(() => createReaderActions(resolvedSchema, resolvedKey, store), [store, resolvedSchema, resolvedKey]);
-}

package/dist/policy/index.d.ts

@@ -16,4 +16,4 @@
  * ```
  */
 export type { Conflict, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, IntentHeldConflict, } from './types.js';
-export { defaultPolicy } from './types.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './types.js';

package/dist/policy/index.js

@@ -15,4 +15,4 @@
  * };
  * ```
  */
-export { defaultPolicy } from './types.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './types.js';