@abloatai/ablo 0.34.0 → 0.35.0

package/dist/{client → transaction/transport}/httpClient.d.ts

@@ -1,9 +1,9 @@
-import type { AbloOptions } from './options.js';
-import type { CommitResource, HttpClaimApi, ModelReadOptions, CreateSessionParams, AbloSession } from './resourceTypes.js';
-import type { ModelCreateParams, ModelDeleteParams, ServerReadOptions, ModelRetrieveParams, ModelUpdateParams } from './createModelProxy.js';
+import type { HttpClientConfig } from './httpOptions.js';
+import type { CommitResource, HttpClaimApi, ModelReadOptions, CreateSessionParams, AbloSession } from '../resources/httpResources.js';
+import type { ModelCreateParams, ModelDeleteParams, ServerReadOptions, ModelRetrieveParams, ModelTrackParams, ModelTrackResult, ModelUpdateParams } from '../resources/modelOperations.js';
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
-import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
-export interface AbloHttpClientOptions<S extends SchemaRecord> extends AbloOptions<S> {
+import type { ModelUpdater, ContentionOptions } from '../resources/functionalUpdate.js';
+export interface AbloHttpClientOptions<S extends SchemaRecord> extends HttpClientConfig<S> {
     /**
      * Per-request deadline. A black-holed HTTP request otherwise has no platform
      * timeout and can stall a headless worker forever. Pass `0` to disable it.
@@ -14,11 +14,16 @@ export interface AbloHttpClientOptions<S extends SchemaRecord> extends AbloOptio
 /**
  * The per-model surface of the stateless HTTP client — everything reachable over
  * request/response: reads (`retrieve` and `list`), writes (`create`, `update`,
- * and `delete`), and the durable-lease {@link HttpClaimApi | claim} plane for
- * coordinated writes. It deliberately omits the stateful client's local-cache
- * reads (`get`, `getAll`, `getCount`) and live subscriptions (`onChange`), which
- * need a persistent socket; those are absent from the type, so reaching for one
- * is a compile error rather than a runtime gap.
+ * and `delete`), the durable-lease {@link HttpClaimApi | claim} plane for
+ * coordinated writes, and `track`, which registers a durable premise on a row.
+ * It deliberately omits the stateful client's local-only
+ * reads (the `local` namespace) and live subscriptions (`onChange`), which need
+ * a resident graph and a persistent socket; those are absent from the type, so
+ * reaching for one is a compile error rather than a runtime gap.
+ *
+ * This is also the base the reactive per-model surface is composed from, rather
+ * than a parallel list it happens to agree with — a verb added here arrives
+ * there without a second edit.
  *
  * The typed model contract is transport-independent: `retrieve` returns one row,
  * `list` returns rows, `create`/`update` return the resulting row, and `delete`
@@ -27,12 +32,32 @@ export interface AbloHttpClientOptions<S extends SchemaRecord> extends AbloOptio
  * access syntax when they switch transport.
  */
 export interface HttpModelClient<T, C = T> {
+    /**
+     * Reads one row by id. Resolves to `undefined` when no such row exists — a
+     * miss is data-absence, not an error.
+     *
+     * This is the default "get me this row", and the one a stateless client
+     * wants, since it holds nothing locally. A client with a resident graph
+     * answers from it first and falls back to the network, which is why the
+     * synchronous `local.retrieve` exists alongside this: same read, restricted
+     * to what is already here.
+     */
     retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<T | undefined>;
+    /**
+     * Reads the rows matching a filter. Same resolution as `retrieve`, in bulk,
+     * and deduplicated so concurrent identical calls share one request.
+     */
     list(options?: ServerReadOptions<T>): Promise<T[]>;
     /**
-     * Creates a row and returns the confirmed server row, including any
-     * framework-applied defaults. Matches the stateful client's `create`. Passing an
-     * id that already exists is idempotent: the existing row is returned unchanged.
+     * Creates a row and returns it, including any framework-applied defaults.
+     * Passing an id that already exists is idempotent: the existing row is
+     * returned unchanged.
+     *
+     * When the client keeps a local graph the write is optimistic — it resolves
+     * once the mutation is queued locally, and a server rejection rolls it back
+     * (watch `sync.syncStatus`). A stateless client has no local graph to roll
+     * back, so it resolves on the server's confirmation instead. The same is true
+     * of `update` and `delete`.
      */
     create(params: ModelCreateParams<T, C>): Promise<T>;
     update(params: ModelUpdateParams<T>): Promise<T>;
@@ -48,14 +73,32 @@ export interface HttpModelClient<T, C = T> {
     update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<T | undefined>;
     delete(params: ModelDeleteParams<T>): Promise<void>;
     claim: HttpClaimApi<T>;
+    /**
+     * Registers a durable premise on a row — "keep telling me about this one".
+     * Any change that lands on the tracked row rides back on the `notifications`
+     * of this client's next commit, so a long-running agent learns its context
+     * went stale without re-reading. A track it already holds is refreshed, not
+     * duplicated.
+     *
+     * ```ts
+     * await ablo.tasks.track({ id: 'task_42' });
+     * // …minutes of other work later, on the next write…
+     * const res = await ablo.commits.create({ operations: [ … ] });
+     * res.notifications; // populated if task_42 moved in the meantime
+     * ```
+     *
+     * The returned `notifications` are only the tracks that had ALREADY fired at
+     * registration time; the ongoing signal arrives on later receipts.
+     */
+    track(params: ModelTrackParams): Promise<ModelTrackResult>;
 }
 /**
  * The type of the stateless HTTP client: a typed {@link HttpModelClient} per
  * schema model, plus `commits`, `dispose`, and the session-mint surface. It
  * exposes only what request/response transport can do, so reaching for a
- * stateful-only capability — `get`, `getAll`, `getCount`, `onChange`, or the
- * synchronous `claim.state`/`queue`/`reorder` reads — is a compile error rather
- * than a value that is `undefined` at runtime.
+ * stateful-only capability — the `local` reads, `onChange`, or the synchronous
+ * `claim.state`/`queue`/`reorder` reads — is a compile error rather than a value
+ * that is `undefined` at runtime.
  */
 export type AbloHttpClient<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: HttpModelClient<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;

package/dist/{client → transaction/transport}/httpClient.js

@@ -18,6 +18,7 @@
  * stateful client offers.
  */
 import { createHttpTransport, } from './httpTransport.js';
+import { modelWireNames } from '../auth/capability.js';
 import { AbloConnectionError, AbloValidationError } from '../errors.js';
 /**
  * Private transport members that pass straight through the facade. Everything
@@ -96,6 +97,7 @@ function createHttpModelClient(protocol) {
             await protocol.delete(mutationOptions(params));
         },
         claim: protocol.claim,
+        track: (params) => protocol.track(params),
     };
 }
 /**
@@ -107,13 +109,11 @@ function createHttpModelClient(protocol) {
 /** @internal Constructed only through the public `Ablo({ transport: 'http' })` factory. */
 export function createAbloHttpClient(options) {
     const { schema, ...rest } = options;
-    const modelTypenames = Object.fromEntries(Object.entries(schema.models).map(([key, definition]) => [
-        key,
-        definition.typename ?? key,
-    ]));
     const transport = createHttpTransport({
         ...rest,
-        modelTypenames,
+        // Derived from the schema this client is bound to, never assembled by hand
+        // — see `auth/capability.ts`.
+        modelTypenames: modelWireNames(schema.models),
     });
     const schemaModels = new Set(Object.keys(schema.models));
     const models = new Map();

package/dist/transaction/transport/httpOptions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The slice of client configuration the HTTP transport reads.
+ *
+ * The composed `Ablo({ ... })` bag is assembled by the consumer and carries far
+ * more than this — persistence, offline, reactivity. The transport needs only
+ * the fields below, so the core declares them and stays out of the composition
+ * surface (ADR 0016).
+ *
+ * TypeScript is structural, so a consumer's full options object satisfies this
+ * without declaring `extends`; the composition root keeps owning its own type.
+ */
+import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type { AuthClientOptions } from '../auth/apiKey.js';
+import type { CoordinationObservability } from '../observability.js';
+import type { CommitOutboxScope } from '../transactions/settlement/commitEnvelope.js';
+import type { DurableWriteStore, DurableWritesConfig } from '../durableWrites.js';
+export interface HttpClientConfig<S extends SchemaRecord = SchemaRecord> extends AuthClientOptions {
+    schema: Schema<S>;
+    /** Overrides where credential exchange and bootstrap are reached. */
+    bootstrapBaseUrl?: string;
+    fetch?: typeof fetch | undefined;
+    defaultHeaders?: Record<string, string | null | undefined> | undefined;
+    defaultQuery?: Record<string, string | undefined> | undefined;
+    observability?: CoordinationObservability;
+    /** Crash-durable writes: the outbox is sealed before a request is dispatched. */
+    durableWrites?: DurableWritesConfig;
+    /** Compatibility input for pre-`durableWrites` clients. */
+    commitOutbox?: DurableWriteStore;
+    /** Compatibility input and internal child-client identity seam. */
+    commitOutboxScope?: CommitOutboxScope;
+    /** Which transport carries this client's traffic. */
+    transport?: 'websocket' | 'http' | undefined;
+}

package/dist/transaction/transport/httpOptions.js

@@ -0,0 +1,12 @@
+/**
+ * The slice of client configuration the HTTP transport reads.
+ *
+ * The composed `Ablo({ ... })` bag is assembled by the consumer and carries far
+ * more than this — persistence, offline, reactivity. The transport needs only
+ * the fields below, so the core declares them and stays out of the composition
+ * surface (ADR 0016).
+ *
+ * TypeScript is structural, so a consumer's full options object satisfies this
+ * without declaring `extends`; the composition root keeps owning its own type.
+ */
+export {};