@abloatai/ablo 0.34.1 → 0.36.0

package/dist/client/humans.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `humans()` — the reactive materialiser, declared as a capability (ADR 0016).
+ *
+ * The bare client is the coordination layer: commit, read, observe, claim.
+ * Add `humans()` when people are watching — it declares the local, watchable
+ * copy: the offline store, live queries, presence, and the framework
+ * bindings. There is no `agents()` counterpart, and the absence is the
+ * message: agents are the default caller, not a special one.
+ *
+ * Transitional shape: the contract fields do real configuration work
+ * (`requires.duplex` rejects it on a request-response client at construction
+ * time; `materialises` is the five-second membership test as a checkable
+ * property), and `init` constructs what the widened context carries enough
+ * to build — the presence stream, attached to the connection the context
+ * carries, and the store cluster (this client's runtime, the component
+ * graph, the registered models, and the `BaseSyncedStore`), now that the
+ * context carries the resolved url and the credential source. What still
+ * lives in the composition root — the credential lifecycle, `ready()`, the
+ * model proxies, the resources, the framework bindings — migrates here as
+ * the context grows to carry what it needs.
+ */
+import type { PluginContext, AppliedChange } from '../transaction/plugin.js';
+import type { SchemaRecord } from '../transaction/schema/schema.js';
+import { type AttachablePresenceStream } from '../sync/createPresenceStream.js';
+import { kStoreCluster, type StoreCluster } from './storeCluster.js';
+import type { InternalAbloOptions } from './options.js';
+/**
+ * What `humans()` contributes to the client — exactly the members that merge
+ * onto it, nothing else. Whether a plugin materialises is declared on the
+ * plugin itself, never restated on its surface.
+ *
+ * The one exception is deliberate and invisible to merging:
+ * {@link kStoreCluster} is symbol-keyed, and surface members merge onto the
+ * client by string key alone — so the cluster reaches the host without ever
+ * becoming client API.
+ */
+export interface HumansSurface {
+    /**
+     * Who is here and what they are doing. Attached to the connection at
+     * construction; calls before the socket opens mutate local state and skip
+     * the wire send, and the stream re-announces on every connect.
+     */
+    readonly presence: AttachablePresenceStream;
+    /**
+     * The constructed store cluster, when the context carried enough to build
+     * it (the connection, the resolved url, the credential source, and a
+     * schema). Absent on a thinner context — the presence stream's own
+     * tolerance, applied to the store.
+     */
+    readonly [kStoreCluster]?: StoreCluster;
+}
+/**
+ * The reactive materialiser. Installed by default when `Ablo({ ... })` is
+ * constructed over the socket with no `plugins` list; listed explicitly, it
+ * reads as what it is — this client renders for people.
+ */
+export declare function humans(): {
+    readonly id: "humans";
+    readonly requires: {
+        readonly duplex: true;
+    };
+    readonly materialises: true;
+    readonly stages: {
+        readonly apply: ({ changes }: {
+            readonly changes: readonly AppliedChange[];
+        }) => void;
+    };
+    readonly init: (context: PluginContext<InternalAbloOptions<SchemaRecord>>) => HumansSurface;
+};

package/dist/client/humans.js

@@ -0,0 +1,78 @@
+/**
+ * `humans()` — the reactive materialiser, declared as a capability (ADR 0016).
+ *
+ * The bare client is the coordination layer: commit, read, observe, claim.
+ * Add `humans()` when people are watching — it declares the local, watchable
+ * copy: the offline store, live queries, presence, and the framework
+ * bindings. There is no `agents()` counterpart, and the absence is the
+ * message: agents are the default caller, not a special one.
+ *
+ * Transitional shape: the contract fields do real configuration work
+ * (`requires.duplex` rejects it on a request-response client at construction
+ * time; `materialises` is the five-second membership test as a checkable
+ * property), and `init` constructs what the widened context carries enough
+ * to build — the presence stream, attached to the connection the context
+ * carries, and the store cluster (this client's runtime, the component
+ * graph, the registered models, and the `BaseSyncedStore`), now that the
+ * context carries the resolved url and the credential source. What still
+ * lives in the composition root — the credential lifecycle, `ready()`, the
+ * model proxies, the resources, the framework bindings — migrates here as
+ * the context grows to carry what it needs.
+ */
+import { AbloValidationError } from '../transaction/errors.js';
+import { createPresenceStream, } from '../sync/createPresenceStream.js';
+import { buildStoreCluster, kStoreCluster, } from './storeCluster.js';
+/**
+ * The reactive materialiser. Installed by default when `Ablo({ ... })` is
+ * constructed over the socket with no `plugins` list; listed explicitly, it
+ * reads as what it is — this client renders for people.
+ */
+export function humans() {
+    // The apply handler's target. `init` binds it to the store it constructs;
+    // until then the handler is a no-op, and nothing dispatches before then —
+    // the store itself is the pipeline that dispatches.
+    let applyChanges = null;
+    return {
+        id: 'humans',
+        // Live queries, presence, and claim push are server-initiated frames, so
+        // a request-response client rejects this plugin while it is being
+        // configured — a typed error, not a subscription that never delivers.
+        requires: { duplex: true },
+        // The point of the plugin: it keeps a local copy of rows. A stateless
+        // caller can assert its own list is uniformly false.
+        materialises: true,
+        stages: {
+            // Deltas land in the materialised in-memory graph at `apply` — the
+            // declaration and the handler are one field, so this cannot name a
+            // stage and forget the work.
+            apply: ({ changes }) => { applyChanges?.(changes); },
+        },
+        init: (context) => {
+            const cluster = buildStoreCluster(context);
+            if (cluster) {
+                // One client per humans() instance: the apply handler routes into
+                // the store this init built, so a shared instance would silently
+                // apply one client's deltas into another client's store.
+                if (applyChanges) {
+                    throw new AbloValidationError('This humans() instance is already installed on a client. ' +
+                        'Construct a fresh humans() for each Ablo({ ... }) call.', { code: 'invalid_options', param: 'plugins' });
+                }
+                applyChanges = (changes) => { cluster.store.applyChangesToPool(changes); };
+            }
+            return {
+                presence: createPresenceStream({
+                    participantId: context.participant?.id ?? '',
+                    syncGroups: [...(context.syncGroups ?? [])],
+                    // Peers' kinds are server-stamped; only the local `self` entry is ours.
+                    isAgent: context.participant?.kind === 'agent',
+                }, 
+                // The host built the connection before resolving the plugin list, so
+                // the stream attaches now and starts the moment the feed opens.
+                context.transport ?? null),
+                ...(cluster ? { [kStoreCluster]: cluster } : {}),
+            };
+        },
+        // `satisfies` rather than a return annotation, so `id` keeps its literal
+        // type and a plugin list's surface can be keyed by id at the type level.
+    };
+}

package/dist/client/modelRegistration.d.ts

@@ -5,6 +5,6 @@
  * and opt-in field-level reactivity) and registers the model's properties,
  * relations, and any local-database indexes.
  */
-import type { Schema } from '../schema/schema.js';
+import type { Schema } from '../transaction/schema/schema.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
 export declare function registerModelsFromSchema(schema: Schema, registry: ModelRegistry): void;

package/dist/client/modelRegistration.js

@@ -6,9 +6,9 @@
  * relations, and any local-database indexes.
  */
 import { z } from 'zod';
-import { baseFieldsSchema } from '../schema/schema.js';
+import { baseFieldsSchema } from '../transaction/schema/schema.js';
 import { Model } from '../Model.js';
-import { LoadStrategy, PropertyType } from '../types/index.js';
+import { PropertyType } from '../transaction/types/index.js';
 // ── Auto model registration from schema ───────────────────────────────────
 export function registerModelsFromSchema(schema, registry) {
     registry.startBatch();
@@ -50,10 +50,10 @@ export function registerModelsFromSchema(schema, registry) {
         ];
         const computed = modelDef.computed;
         const DynamicModel = createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed, isLazy);
-        // Respect the schema's load strategy so lazy models skip IDB hydration + bootstrap
-        const loadStrategy = modelDef.load === 'lazy' || modelDef.load === 'manual'
-            ? LoadStrategy.lazy
-            : LoadStrategy.instant;
+        // The schema's strategy carries straight through — authoring and runtime
+        // name the same set, so there is nothing here to translate and nothing to
+        // fall out of step. Lazy models skip IDB hydration and bootstrap.
+        const loadStrategy = modelDef.load;
         registry.registerModel(modelName, DynamicModel, {
             loadStrategy,
             fields: modelDef.fields,
@@ -70,14 +70,14 @@ export function registerModelsFromSchema(schema, registry) {
         // id, and indexing every scalar is worse still.
         const indexedFields = new Set();
         for (const relDef of Object.values(modelDef.relations)) {
-            if (relDef.type === 'belongsTo' && relDef.foreignKey && relDef.options?.index === true) {
+            if (relDef.type === 'belongsTo' && relDef.foreignKey && relDef.options.index === true) {
                 indexedFields.add(relDef.foreignKey);
             }
         }
         // Register fields as properties (from Zod shape).
         for (const [fieldName, rawZodType] of Object.entries(modelDef.shape)) {
             const zodType = rawZodType;
-            const isOptional = zodType.isOptional?.() ?? false;
+            const isOptional = zodType.isOptional();
             // A field is indexed if it is the foreign key of a
             // `belongsTo({ index: true })` relation. A `description === 'indexed'` tag
             // also works, for consumers using the `field.*().indexed()` builder.
@@ -87,7 +87,7 @@ export function registerModelsFromSchema(schema, registry) {
             // would walk every nested property and create an atom per leaf, producing a
             // storm of updates on each commit or streaming change. Reference tracking
             // watches only reassignment, which is how blob consumers actually use them.
-            const wireType = modelDef.fields?.[fieldName]?.type;
+            const wireType = modelDef.fields[fieldName]?.type;
             const observability = wireType === 'json' ? 'ref' : undefined;
             registry.registerProperty(modelName, fieldName, {
                 type: PropertyType.property,

package/dist/client/options.d.ts

@@ -4,19 +4,21 @@
  * construction surface exposed through `@abloatai/ablo/core`.
  * This module holds only types and has no runtime imports.
  */
-import type { Schema, SchemaRecord } from '../schema/schema.js';
-import type { SyncEngineConfig, SyncLogger, MutationExecutor, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
-import type { AbloPersistence } from './persistence.js';
-import type { DurableWriteStore, DurableWritesConfig } from '../transactions/durableWriteStore.js';
-import type { CommitOutboxScope } from '../transactions/commitEnvelope.js';
+import type { Schema, SchemaRecord } from '../transaction/schema/schema.js';
+import type { RuntimeConfig, Logger, MutationExecutor, ObservabilityProvider, Analytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
+import type { AbloPersistence } from '../transaction/persistence.js';
+import type { DurableWriteStore, DurableWritesConfig } from '../transaction/durableWrites.js';
+import type { CommitOutboxScope } from '../transaction/transactions/settlement/commitEnvelope.js';
 /**
  * An async function that resolves an apiKey at request time. Use it for credential
  * rotation — read from a vault, refresh from session storage, or pull from an
  * existing auth session. The canonical definition lives in `./auth`; it is
  * re-exported here for convenience.
  */
-export type { ApiKeySetter } from './auth.js';
-import type { ApiKeySetter } from './auth.js';
+export type { ApiKeySetter } from '../transaction/auth/apiKey.js';
+import type { ApiKeySetter } from '../transaction/auth/apiKey.js';
+import type { AbloPlugin } from '../transaction/plugin.js';
+import type { ParticipantKind } from '../transaction/types/participant.js';
 /**
  * Options for the {@link Ablo} client.
  *
@@ -39,6 +41,13 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * pass; start here.
      */
     schema: Schema<S>;
+    /**
+     * The capabilities installed on this client. Each plugin appears once in
+     * the list; a duplicate, or a plugin the chosen transport cannot carry,
+     * fails while the client is being constructed with an error naming the
+     * plugin. Omitted, the client installs `humans()` — today's default.
+     */
+    plugins?: readonly AbloPlugin[];
     /**
      * The API key — the auth field most apps set. It accepts three shapes:
      *
@@ -117,6 +126,15 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * })
      * ```
      */
+    /**
+     * Wire message types to surface as collaboration events, e.g.
+     * `['document:selection', 'document:cursor']`.
+     *
+     * These name your application's own concepts, so the SDK ships no default —
+     * a schema with no documents should never receive document events. Declare
+     * the ones you broadcast.
+     */
+    collaborationEvents?: readonly string[];
     durableWrites?: DurableWritesConfig;
     /**
      * @deprecated Use `durableWrites: { store, namespace }`.
@@ -142,8 +160,8 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * serverless handlers. It offers the same `ablo.<model>` surface and coordination
      * plane, but every call is a single HTTP round-trip, identity rides the bearer
      * credential, and no socket is opened. With `'http'` the return type narrows to
-     * {@link AbloHttpClient}, so stateful-only capabilities such as `get`, `getAll`,
-     * and `onChange` become compile errors instead of runtime gaps.
+     * {@link AbloHttpClient}, so stateful-only capabilities such as the `local`
+     * reads and `onChange` become compile errors instead of runtime gaps.
      *
      * Session minting through `sessions.create` is available on both transports.
      *
@@ -154,12 +172,18 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Turns Ablo's diagnostic logging on or off. `true` surfaces the `[Ablo]`
      * coordination trace — claims requested, queued, granted, and released, agent
      * handovers, and connection state — so you can watch the coordination between
-     * humans and agents while debugging. Omitting it, or `false`, keeps the quiet
+     * agents and people while debugging. Omitting it, or `false`, keeps the quiet
      * default of warnings and errors only. For a middle ground use {@link logLevel}.
      * The `ABLO_LOG_LEVEL` environment variable overrides it, and a custom logger
      * takes precedence.
      */
     debug?: boolean | undefined;
+    /**
+     * Route Ablo's log lines through your own logger (pino, winston, a test spy)
+     * instead of the default console `[Ablo]` logger. Supplying one bypasses
+     * {@link debug}/{@link logLevel} — your logger owns the thresholds.
+     */
+    logger?: Logger;
     /**
      * The log threshold for the default `[Ablo]` logger; takes precedence over
      * {@link debug}. `'info'` shows coordination and connection events without the
@@ -189,6 +213,33 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * session token (`ek_`/`rk_`) or you route through a controlled server proxy.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
+    /**
+     * How far a write goes before its promise settles, for every model write on
+     * this client. The same word each write already takes per call
+     * (`create({ …, wait: 'confirmed' })`); setting it here makes it the default
+     * instead of repeating it.
+     *
+     * A write resolves as soon as it is applied locally and queued. That is what
+     * makes the UI immediate, and it is right for most writes — but it means a
+     * write the server later REFUSES has no caller left to tell. The rejection
+     * reverts the local row and reaches `ablo.onMutationFailure(…)`, and an
+     * application that subscribes to neither shows the change, then loses it,
+     * with nothing thrown anywhere.
+     *
+     * ```ts
+     * const ablo = new Ablo({ schema, apiKey, wait: 'confirmed' });
+     * try {
+     *   await ablo.documents.update({ id, data });   // throws if refused
+     * } catch (err) {
+     *   if (err instanceof AbloError) show(err.message);
+     * }
+     * ```
+     *
+     * The cost is real: each write now waits for the server's answer, so it is a
+     * choice between immediacy and certainty rather than a strict improvement.
+     * A per-call `wait` still wins over this.
+     */
+    wait?: 'queued' | 'confirmed' | undefined;
 }
 export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
@@ -257,7 +308,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * @deprecated The server derives the participant kind from the apiKey's scope.
      * Pass `apiKey` only.
      */
-    kind?: 'user' | 'agent' | 'system';
+    kind?: ParticipantKind;
     /**
      * @deprecated The server derives user identity from the apiKey's scope, or from
      * the `Ablo-Acting-User` request header for multi-tenant setups. Pass `apiKey`
@@ -277,12 +328,12 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     capabilityToken?: string;
     /** Custom logger (default: console). Supplying one bypasses {@link debug}/{@link logLevel}. */
-    logger?: SyncLogger;
+    logger?: Logger;
     /**
      * Turns Ablo's diagnostic logging on or off. `true` surfaces the `[Ablo]`
      * coordination trace — claims acquired, queued, granted, and released, agent
      * handovers, and connection state — along with internal lifecycle events, so you
-     * can watch the coordination between humans and agents. Omitting it, or `false`,
+     * can watch the coordination between agents and people. Omitting it, or `false`,
      * keeps the quiet default of warnings and errors only. For a middle ground use
      * {@link logLevel}. The `ABLO_LOG_LEVEL` environment variable overrides it, and a
      * custom {@link logger} takes precedence.
@@ -307,6 +358,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     persistence?: AbloPersistence;
     /** Internal mirror of {@link AbloOptions.durableWrites}. */
+    /** Wire message types to surface as collaboration events. Empty unless declared. */
+    collaborationEvents?: readonly string[];
     durableWrites?: DurableWritesConfig;
     /** @deprecated Internal mirror of {@link AbloOptions.commitOutbox}. */
     commitOutbox?: DurableWriteStore;
@@ -344,12 +397,12 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Custom observability provider (Sentry, Honeycomb, OTel, etc.).
      * Default: a noop implementation that drops all breadcrumbs and spans.
      */
-    observability?: SyncObservabilityProvider;
+    observability?: ObservabilityProvider;
     /**
      * Custom analytics provider (PostHog, Amplitude, Segment, etc.).
      * Default: a noop implementation that drops all events.
      */
-    analytics?: SyncAnalytics;
+    analytics?: Analytics;
     /**
      * Detect whether an error from a mutation/bootstrap response means the
      * user's session has expired. Used to surface re-auth prompts. Default:
@@ -371,12 +424,12 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     mutationExecutor?: MutationExecutor;
     /**
-     * Partial overrides for the auto-derived `SyncEngineConfig`. Merged on
+     * Partial overrides for the auto-derived `RuntimeConfig`. Merged on
      * top of `deriveConfigFromSchema(schema)`. Use this when you need
      * specific `modelCreatePriority`, `batchableModels`, or
      * `essentialFields` settings that the schema cannot express.
      */
-    configOverrides?: Partial<SyncEngineConfig>;
+    configOverrides?: Partial<RuntimeConfig>;
     /**
      * The sync groups (entity scopes) this client subscribes to. Normally the server
      * derives these from the apiKey's scope; pass them explicitly when the key does
@@ -402,4 +455,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * identity from the token through the identity endpoint instead.
      */
     organizationId?: string;
+    /** The client-wide write default — see {@link AbloOptions.wait}. Projected
+     *  from the public option rather than restated, so the two cannot diverge. */
+    wait?: AbloOptions['wait'];
 }

package/dist/client/reactiveEngine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The reactive engine assembly (ADR 0016). `Ablo({ ... })` resolves auth and
+ * capabilities; `humans().init` constructs the store cluster; the lifecycle
+ * — first mint, identity, ready() — lives in `./storeLifecycle.ts`. What
+ * remains here is assembly around those parts: the claim stream and
+ * participant manager, options validation, the typed model proxies, and the
+ * commit/claim/session resources — composed into the reactive client.
+ *
+ * Extracted from the factory so the composition root stays a root: resolve,
+ * dispatch, return. The remaining assembly converts to decoration of a
+ * host-built core client with the per-model surface split — the cut's own
+ * design step (docs/plans/package-split.md).
+ */
+import type { SchemaRecord } from '../transaction/schema/schema.js';
+import type { StoreCluster } from './storeCluster.js';
+import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
+import type { AttachablePresenceStream } from '../sync/createPresenceStream.js';
+import type { AbloOptions } from './options.js';
+import type { ClientPrelude } from './clientPrelude.js';
+import type { Ablo } from './Ablo.js';
+/**
+ * What the reactive build is fed: the factory's pass over the options bag
+ * ({@link ClientPrelude} — auth, url, logging, identity, shared with the other
+ * client shapes), plus the four things that must exist before the store does.
+ *
+ * The prelude half is extended, never restated. A second copy of those fields
+ * would drift the moment one side gained a resolver the other did not.
+ */
+export interface ReactiveEngineInputs<S extends SchemaRecord> extends ClientPrelude<S> {
+    options: AbloOptions<S>;
+    /**
+     * The connection, constructed by the factory before the plugin list
+     * resolved — the same instance `PluginContext.transport` carries. The
+     * store takes it as a dependency and owns the lifecycle.
+     */
+    transport: SyncWebSocket;
+    /** The humans() plugin's contribution — built by its `init`, already
+     *  attached to the connection the context carried. */
+    presence: AttachablePresenceStream;
+    /**
+     * The store cluster `humans().init` constructed from the widened context:
+     * this client's runtime, the component graph, and the store. The engine
+     * assembles around it and constructs none of it.
+     */
+    cluster: StoreCluster;
+    /**
+     * Constructs a sibling client (`ablo.agents.create(...)` mints a scoped key
+     * and builds a second engine with it). Injected by the factory — a direct
+     * import back into it would close a runtime cycle.
+     */
+    createSibling: (options: AbloOptions<S>) => Ablo<S>;
+}
+export declare function buildReactiveEngine<const S extends SchemaRecord>(inputs: ReactiveEngineInputs<S>): Ablo<S>;