@abloatai/ablo 0.7.0 → 0.9.0

package/dist/client/createModelProxy.d.ts

@@ -7,10 +7,12 @@
  * testable in isolation and the constructor doesn't carry it.
  *
  * Each schema model gets one `ModelOperations<T, CreateInput>` —
- * exposes `retrieve`, `list`, `count`, `create`, `update`, `delete`,
- * `claim`, `claimState`, `queue`, `release`, `subscribe`, and `load`.
- * The factory returns a plain object; the client assembles the
- * `ablo.<model>` lookup table from these.
+ * exposes the async server reads `retrieve` / `list`, the synchronous
+ * local-graph snapshots `get` / `getAll` / `getCount`, the writes
+ * `create` / `update` / `delete`, the coordination namespace `claim`
+ * (`claim({ id })` 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';
@@ -19,7 +21,7 @@ import type { SyncClient } from '../SyncClient.js';
 import type { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
 import type { LoadWhere } from '../query/types.js';
 import { ModelScope } from '../types/index.js';
-import type { Duration, Intent, IntentWaitOptions, Snapshot } from '../types/streams.js';
+import type { Duration, Intent, IntentWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
 export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
@@ -48,7 +50,7 @@ export interface ModelLoadOptions<T> {
      *   - tuple form: `[['name', 'ILIKE', '%Goldman%']]` for operators
      *
      * See `LoadWhere<T>` in `query/types.ts`. For OR semantics, run two
-     * `load()` calls and union — the wire protocol is AND-only.
+     * `list()` calls and union — the wire protocol is AND-only.
      */
     where?: LoadWhere<T>;
     orderBy?: {
@@ -68,6 +70,9 @@ export interface ModelLoadOptions<T> {
      */
     expand?: readonly string[];
 }
+/** Options for the single-row async server read `retrieve({ id })`. A subset of
+ *  {@link ModelLoadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
+export type ModelRetrieveOptions = Pick<ModelLoadOptions<unknown>, 'type' | 'expand'>;
 export interface IntentLeaseHandle {
     readonly id: string;
     release(): Promise<void>;
@@ -79,6 +84,9 @@ export interface ModelCollaboration<T> {
             model: string;
             id: string;
             field?: string;
+            path?: string;
+            range?: TargetRange;
+            meta?: Record<string, unknown>;
         };
         action: string;
         ttl?: Duration;
@@ -134,12 +142,19 @@ export interface ModelCollaboration<T> {
      */
     readonly selfParticipantId: string;
 }
-/** Options for `claim(id, …)`. */
-export interface ClaimOptions {
+export interface ClaimTargetOptions<T = Record<string, unknown>> {
     /** Phase shown to observers while held. Defaults to `'editing'`. */
     action?: string;
+    /** Peer-visible explanation of the work being performed. */
+    description?: string;
     /** Field-level target, for fine-grained claimed-state badges. */
     field?: string;
+    /** Optional path for document/file-like targets. */
+    path?: string;
+    /** Optional range for document/file-like targets. */
+    range?: TargetRange;
+    /** App-defined structured metadata. */
+    meta?: Record<string, unknown>;
     /** Crash-cleanup TTL — the claim auto-releases if the holder dies. */
     ttl?: Duration;
     /**
@@ -159,106 +174,199 @@ export interface ClaimOptions {
      */
     maxQueueDepth?: number;
 }
+/** Options for `claim({ id, ... })`. */
+export interface ClaimParams<T = Record<string, unknown>> extends ClaimTargetOptions<T> {
+    readonly id: string;
+}
+export interface ClaimLookupParams<T = Record<string, unknown>> {
+    readonly id: string;
+    readonly field?: string;
+}
+export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLookupParams<T> {
+    readonly order: readonly Intent[];
+}
 /**
- * A claimed row: the entity's data plus an async-dispose hook, so
+ * A claim handle: the held entity data plus an explicit release hook, so
  *
  * ```ts
- * await ablo.weatherReports.claim('report_stockholm', async (report) => {
- *   await ablo.weatherReports.update(report.id, { status: 'ready' });
+ * const claim = await ablo.weatherReports.claim({
+ *   id: 'report_stockholm',
+ *   action: 'forecasting',
+ *   description: 'Fetching current weather before writing the forecast.',
  * });
+ * try {
+ *   await ablo.weatherReports.update({
+ *     id: claim.target.id,
+ *     data: { status: 'ready' },
+ *     claim,
+ *   });
+ * } finally {
+ *   await claim.release();
+ * }
  * ```
  *
- * releases the claim when the callback returns or throws. Read it like any row
- * (`report.location`); write it through the flat `ablo.<model>.update(report.id, …)`
- * verb — there is no method chaining on the claim.
+ * `data` is a snapshot taken after the lease is held. Write through the flat
+ * `ablo.<model>.update({ id, data, claim })` verb — the handle carries the
+ * lease id and snapshot watermark for attribution + stale protection.
  */
-export type ClaimedRow<T> = T & AsyncDisposable;
+export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposable {
+    readonly object: 'claim';
+    readonly claimId: string;
+    readonly target: {
+        readonly model: string;
+        readonly id: string;
+        readonly field?: string;
+        readonly path?: string;
+        readonly range?: TargetRange;
+        readonly meta?: Record<string, unknown>;
+    };
+    readonly action: string;
+    readonly description?: string;
+    readonly data: T;
+    release(): Promise<void>;
+    revoke(): void;
+}
+export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
+/**
+ * The coordination surface for a model, exposed as a callable namespace.
+ *
+ * Most callers do not need this namespace directly. Put `claim: { ... }` on a
+ * write and the SDK acquires/releases around that one mutation:
+ *
+ * ```ts
+ * await ablo.tasks.update({
+ *   id,
+ *   data: { title },
+ *   claim: {
+ *     field: 'title',
+ *     action: 'renaming',
+ *     description: 'Renaming the task to match the project brief.',
+ *   },
+ * });
+ * ```
+ *
+ * Use `claim({ id, ... })` when a tool spans multiple writes and needs one
+ * handle. `state`, `queue`, and `reorder` are coordination reads/scheduler
+ * controls for UI and operators.
+ */
+export interface ClaimApi<T> {
+    /** Take a claim and get an explicit held-work handle back. */
+    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+    /**
+     * Current holder for a row, or `null` when free. Use this for UI badges and
+     * preflight checks, not for the normal write path.
+     */
+    state(params: ClaimLookupParams<T>): Intent | null;
+    /**
+     * FIFO wait line behind the current holder. Advanced: useful for operator
+     * UIs and schedulers.
+     */
+    queue(params: ClaimLookupParams<T>): {
+        readonly object: 'list';
+        readonly data: readonly Intent[];
+    };
+    /**
+     * Re-rank the wait line. Advanced and permission-gated.
+     */
+    reorder(params: ClaimReorderParams<T>): void;
+    /** Release a manual claim handle early. Single-write claims auto-release. */
+    release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
+}
+export interface ModelRetrieveParams extends ModelRetrieveOptions {
+    readonly id: string;
+}
+export interface ModelCreateParams<T, CreateInput> extends MutationOptions {
+    readonly data: CreateInput;
+    readonly id?: string | null;
+    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+}
+export interface ModelUpdateParams<T> extends MutationOptions {
+    readonly id: string;
+    readonly data: Partial<T>;
+    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+}
+export interface ModelDeleteParams<T> extends MutationOptions {
+    readonly id: string;
+    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+}
 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.
+     *
+     * 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)`.
+     * Mirrors `stripe.customers.retrieve({ id })` — network-backed.
      */
-    retrieve(id: string): T | undefined;
+    retrieve(params: ModelRetrieveParams): 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))`.
+     */
+    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.
      */
-    list(options?: ModelListOptions<T>): T[];
-    /** Count entities matching a filter (synchronous, from local pool). */
-    count(options?: ModelCountOptions<T>): number;
+    getAll(options?: ModelListOptions<T>): T[];
+    /** Count entities in the **local graph** (synchronous, no network). */
+    getCount(options?: ModelCountOptions<T>): number;
     /**
      * Create a new entity — **optimistic, offline-first**. Resolves once
      * the mutation is queued locally, not when the server confirms.
      * Server rejection rolls back automatically; watch `sync.syncStatus`.
      */
-    create(data: CreateInput, options?: MutationOptions): Promise<T>;
+    create(params: ModelCreateParams<T, CreateInput>): Promise<T>;
     /** Update an entity by id — optimistic, offline-first (see `create`). */
-    update(id: string, data: Partial<T>, options?: MutationOptions): Promise<T>;
+    update(params: ModelUpdateParams<T>): Promise<T>;
     /** Delete an entity by id — optimistic, offline-first (see `create`). */
-    delete(id: string, options?: MutationOptions): Promise<void>;
+    delete(params: ModelDeleteParams<T>): 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 handle; reach for its members to observe and steer 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.
+     * - `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
-     * const { data } = ablo.decks.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 `queue(id).data`, reordered. A
-     * privileged operation: the server gates it (the caller needs the
-     * `intent.reorder` capability), so it's fire-and-forget — the new order
-     * arrives reactively through `queue(id)`.
+     * const claim = await ablo.weatherReports.claim({
+     *   id: 'report_stockholm',
+     *   action: 'forecasting',
+     *   description: 'Fetching fresh weather before updating the report.',
+     * });
+     * const weather = await getWeather(claim.data.location);
+     * await ablo.weatherReports.update({
+     *   id: claim.target.id,
+     *   data: { forecast: weather },
+     *   claim,
+     * });
+     * await claim.release();
      *
-     * ```ts
-     * const { data } = ablo.decks.queue('deck_1');
-     * ablo.decks.reorder('deck_1', [data[2], data[0], data[1]]); // promote #2
+     * const holder = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
      * ```
      */
-    reorder(id: string, order: readonly Intent[]): void;
-    /** 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>;