@abloatai/ablo 0.34.1 → 0.36.0

package/dist/client/resourceTypes.d.ts

@@ -1,253 +1,12 @@
 /**
- * Shared resource types for the typed clients and private HTTP transport.
- * the commit and claim shapes, the session-mint params and resource, and the
- * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
- * imports.
- */
-import type { ReadDependency, TrackDependency } from '../coordination/schema.js';
-import type { ClientCommitReceipt, CommitStatus } from '../wire/commit.js';
-import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
-export type { ModelTarget, ModelClaim };
-import type { SchemaRecord } from '../schema/schema.js';
-import type { SyncGroupInput } from '../schema/roles.js';
-import type { Claim, ClaimStream, ClaimWaitOptions, Duration, HeldClaim } from '../types/streams.js';
-import type { ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod } from './createModelProxy.js';
-/**
- * The operations available on each model in the sync engine:
- *   `retrieve({ id })` — an async single-row server read
- *   `list({ where })` — an async collection server read
- *   `get(id)` / `getAll(...)` / `getCount(...)` — synchronous local-cache reads
- *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
- *   `claim({ id })` — a durable claim handle for coordinated writes
- */
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, ModelOperations, } from './createModelProxy.js';
-export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
-export type CommitWait = CommitStatus;
-export type IfClaimedPolicy = 'return' | 'fail';
-export interface ClaimedOptions {
-    /**
-     * What to do when another participant has claimed the target: `return` lets
-     * the read proceed; `fail` throws `AbloClaimedError`. Inspect claim state via
-     * `ablo.<model>.claim.state({ id })`. Waiting is a claim-side concern — take
-     * `ablo.<model>.claim({ id })` (it queues fairly); reads never block.
-     */
-    readonly ifClaimed?: IfClaimedPolicy;
-}
-export type { ClaimWaitOptions } from '../types/streams.js';
-export interface ModelReadOptions extends ClaimedOptions {
-}
-export interface ClaimCreateOptions {
-    readonly target: ModelTarget;
-    /** Peer-visible description of the work — the same field on every claim
-     *  surface. Defaults to `'editing'` when omitted. */
-    readonly description?: string;
-    readonly ttl?: Duration;
-    /**
-     * Join the server's fair FIFO queue when the target is already claimed,
-     * rather than failing immediately. `create` then resolves only once the
-     * lease is actually ours (the server pushes `claim_acquired` if the target
-     * was free, or `claim_granted` when we reach the head of the line). Without
-     * this, a contended claim throws. Used by `ablo.<model>.claim` so writers
-     * serialize instead of racing.
-     */
-    readonly queue?: boolean;
-    /** Cap on how long to wait for a queued grant before rejecting. */
-    readonly waitTimeoutMs?: number;
-    /**
-     * Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of
-     * waiting if the queue is already `>= maxQueueDepth` when we join.
-     */
-    readonly maxQueueDepth?: number;
-}
-export interface CommitOperationInput {
-    readonly action: ModelOperationAction;
-    /** The model name — matches `ablo.<model>` and the schema's `model()`. */
-    readonly model: string;
-    readonly id?: string | null;
-    readonly data?: Record<string, unknown> | null;
-    readonly transactionId?: string | null;
-    readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
-    /** Fencing token (Option B) from the batch's claim handle; server-validated. */
-    readonly fenceToken?: number | null;
-}
-export interface CommitCreateOptions {
-    readonly idempotencyKey?: string | null;
-    readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
-    /**
-     * A claim handle from `ablo.<model>.claim({ id })` (or the HTTP claim
-     * surface). Same vocabulary as the per-model writes: the handle's
-     * snapshot watermark becomes the batch `readAt` default and `onStale`
-     * defaults to `'reject'`, so a commit that follows a claim is guarded
-     * against concurrent edits without re-stating the watermark by hand.
-     * Explicit `readAt`/`onStale` on the options win.
-     */
-    readonly claim?: Claim | null;
-    /** One atomic batch. Use a one-element array for a single operation. */
-    readonly operations: readonly CommitOperationInput[];
-    readonly wait?: CommitWait;
-    /**
-     * Batch-level read dependencies — the "did anything I looked at change?" guard.
-     * Declare the rows (`{ model, id, readAt, fields? }`) or sync groups
-     * (`{ group, readAt }`, for example `deck:abc`) this batch was premised on; the
-     * server checks that none moved since `readAt` and fires the entry's `onStale`
-     * over the batch. This is distinct from the write-target `readAt`: it guards what
-     * you read, not what you write.
-     */
-    readonly reads?: readonly ReadDependency[] | null;
-    /**
-     * Durable read-dependencies to register as part of this batch — the persisted
-     * sibling of `reads`. Where `reads` guards only this commit, a `track` entry
-     * (`{ model, id, readAt? }` for a row or `{ group, readAt? }` for a sync group)
-     * lives on past it: a later matching change rides back on a future receipt's
-     * `notifications`. A track-only batch (just `track`, an empty `operations`) is
-     * the batch form of `ablo.<model>.track()`.
-     */
-    readonly track?: readonly TrackDependency[] | null;
-}
-/** Public projection inferred from the canonical runtime schema. */
-export type CommitReceipt = ClientCommitReceipt;
-export interface CommitResource {
-    create(options: CommitCreateOptions): Promise<CommitReceipt>;
-}
-export interface ClaimResource extends ClaimStream {
-    create(options: ClaimCreateOptions): Promise<Claim>;
-    list(target?: Partial<ModelTarget>): readonly ModelClaim[];
-    waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
-}
-export interface ModelMutationOptions extends ClaimedOptions {
-    readonly claimRef?: string | {
-        readonly id: string;
-    } | null;
-    readonly idempotencyKey?: string | null;
-    readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
-    readonly wait?: CommitWait;
-    readonly claim?: Claim | ClaimOptions | null;
-    /** Fencing token (Option B) from the claim; server-validated at commit. */
-    readonly fenceToken?: number | null;
-}
-/**
- * The stateless HTTP claim surface. Most code puts a `claim` directly on the write
- * (`update({ id, data, claim })`) and lets the SDK release it; reach for this
- * namespace for multi-step handles and coordination screens.
- *
- * It is the same surface as the reactive claim API, but because every read is a
- * server round-trip, `state`, `queue`, and `reorder` are awaited here. The
- * WebSocket client resolves those synchronously from its local cache, which is what
- * lets it read a claim's state inside a React render; a stateless client has no
- * cache to read, so the promise is unavoidable.
+ * The public resource-type surface.
  *
- * It is derived from `ClaimReadApi` through {@link AwaitedClaimMethod} so the two
- * transports cannot drift: the only difference is the promise wrapper that
- * statelessness forces. `claim({ id })` is identical on both (already async);
- * `state`, `queue`, `reorder`, and `release` are the awaited form.
+ * The transport-facing half of these types moved down into the settlement core
+ * (ADR 0016). This module keeps the
+ * consumer-facing import path intact and rejoins it with the model-proxy types
+ * that stay here — `ModelOperations` chief among them, because it returns the
+ * live participant handle.
  */
-export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<HeldClaim<T>>) & {
-    [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
-};
-/** A single data operation a scoped **agent** session may perform on a model. */
-export type SessionOperation = 'read' | 'create' | 'update' | 'delete';
-/** Parameters for minting an end-user session — full data authority within the
- *  organization. Mints an `ek_` token. `user.id` is your end user's id from your
- *  own identity provider and becomes the session's `participantId`; Ablo does not
- *  model your users, so it is treated as an opaque string at the trust boundary. */
-export interface CreateUserSessionParams {
-    /** Your end user. `id` becomes the token's `participantId`. */
-    user: {
-        id: string;
-    };
-    /** Mint the session into this organization instead of the key's own — for a
-     *  platform that serves many tenants from one backend. Requires the `sk_` key to
-     *  carry the `ephemeral:mint-any-org` scope; omit it for the normal
-     *  single-tenant case. */
-    organizationId?: string;
-    /** Sync groups this session may subscribe to — typed (`'default'` or
-     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
-     *  `@abloatai/ablo/schema`). Omit for the server default:
-     *  `[org:<your org>, user:<user.id>]`. */
-    syncGroups?: readonly SyncGroupInput[];
-    /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
-    ttlSeconds?: number;
-    /** Opaque identity blob echoed back to the client as `ablo.user`. */
-    userMeta?: Record<string, unknown>;
-    agent?: never;
-    can?: never;
-}
-/** Mint params for a scoped **agent** session — mints a restricted `rk_` token
- *  gated to exactly the operations named in `can`. `can` is typed off your
- *  schema (no magic `'task.update'` strings): `{ Task: ['update'], Deck: ['read'] }`
- *  — the SDK serializes each entry to the wire allowlist (`task.update`). */
-export interface CreateAgentSessionParams<S extends SchemaRecord> {
-    /** Your agent. `id` becomes the token's `participantId`. */
-    agent: {
-        id: string;
-    };
-    /** Per-model operation allowlist, typed against the schema's model names. */
-    can: Partial<Record<keyof S & string, readonly SessionOperation[]>>;
-    /** Sync groups this session may subscribe to — typed (`'default'` or
-     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
-     *  `@abloatai/ablo/schema`). Omit for the server default: the org
-     *  anchor (`org:<your org>`) + the agent's own anchor. */
-    syncGroups?: readonly SyncGroupInput[];
-    /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
-    ttlSeconds?: number;
-    /** Opaque identity blob echoed back to the client as `ablo.agent`. */
-    userMeta?: Record<string, unknown>;
-    user?: never;
-}
-/** Params for {@link Ablo.sessions}.create — a discriminated union: pass
- *  `{ user }` for a full-authority end-user session (`ek_`) or `{ agent, can }`
- *  for a scoped agent session (`rk_`). */
-export type CreateSessionParams<S extends SchemaRecord> = CreateUserSessionParams | CreateAgentSessionParams<S>;
-/** Params for {@link Ablo.agents}.create — a flattened agent descriptor (no
- *  `{ agent }` discriminator: `agents.create` only ever mints an agent). Unlike
- *  {@link CreateSessionParams} it resolves to a connected, scoped {@link Ablo}
- *  client rather than a raw token. */
-export interface CreateAgentClientParams<S extends SchemaRecord> {
-    /** The wire participant identity (`agent:<id>`) that claim exclusion and the
-     *  FIFO queue gate on. Omit it to get a fresh random id — a distinct, independent
-     *  participant, which is the default and what you want for concurrent agents.
-     *  Pass a stable string only when one logical agent must re-attach to its own
-     *  held claims across reconnects or restarts. */
-    id?: string;
-    /** A human-readable label for logs and attribution (carried in `userMeta.name`).
-     *  It is independent of `id`: two agents that share a `name` still receive
-     *  distinct ids and coordinate as separate participants — `name` never derives or
-     *  collapses identity. */
-    name?: string;
-    /** Per-model operation allowlist, typed against the schema's model names. */
-    can: Partial<Record<keyof S & string, readonly SessionOperation[]>>;
-    /** Sync groups this agent may subscribe to — typed (`'default'` or
-     *  `<namespace>:<id>`). Omit for the server default (org anchor + the
-     *  agent's own anchor). */
-    syncGroups?: readonly SyncGroupInput[];
-    /** Token lifetime in seconds. Defaults to 900 (15 minutes); the returned client
-     *  re-mints before expiry, so a long-running agent never handles rotation
-     *  itself. */
-    ttlSeconds?: number;
-    /** Extra opaque identity blob echoed on the session scope. Merged with
-     *  `name` (the `name` param wins if you also set `userMeta.name`). */
-    userMeta?: Record<string, unknown>;
-}
-/** A minted session. `token` is the secret the holder presents as its bearer. */
-export interface AbloSession {
-    object: 'session';
-    /** Stable id of the minted credential (for revocation). */
-    id: string;
-    /** The short-lived session token — `ek_` for a `{ user }` session, `rk_`
-     *  for an `{ agent }` session. Hand this to the participant's runtime. */
-    token: string;
-    /** ISO-8601 expiry. */
-    expiresAt: string;
-    organizationId: string;
-    scope: {
-        organizationId: string;
-        syncGroups: readonly string[];
-        operations: readonly string[];
-        participantKind: 'user' | 'agent' | 'system';
-        participantId: string;
-    };
-    userMeta: Record<string, unknown>;
-}
+export * from '../transaction/resources/httpResources.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, } from '../transaction/resources/modelOperations.js';
+export type { ModelOperations } from './createModelProxy.js';

package/dist/client/resourceTypes.js

@@ -1,7 +1,10 @@
 /**
- * Shared resource types for the typed clients and private HTTP transport.
- * the commit and claim shapes, the session-mint params and resource, and the
- * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
- * imports.
+ * The public resource-type surface.
+ *
+ * The transport-facing half of these types moved down into the settlement core
+ * (ADR 0016). This module keeps the
+ * consumer-facing import path intact and rejoins it with the model-proxy types
+ * that stay here — `ModelOperations` chief among them, because it returns the
+ * live participant handle.
  */
-export {};
+export * from '../transaction/resources/httpResources.js';

package/dist/client/schemaConfig.d.ts

@@ -3,11 +3,11 @@
  * functions: {@link computeFKDepthPriority} works out a safe row-insertion
  * order from the schema's foreign-key relations, and
  * {@link deriveConfigFromSchema} packages that ordering, together with a few
- * defaults, into the {@link SyncEngineConfig} a client uses at startup. Both
+ * defaults, into the {@link RuntimeConfig} a client uses at startup. Both
  * are deterministic transforms of the schema and hold no engine state.
  */
-import type { Schema } from '../schema/schema.js';
-import type { SyncEngineConfig } from '../interfaces/index.js';
+import type { Schema } from '../transaction/schema/schema.js';
+import type { RuntimeConfig } from '../interfaces/index.js';
 /**
  * Computes a create-priority map that gives the engine a safe order for
  * inserting rows, so a child row is never written before the parent its
@@ -41,4 +41,4 @@ import type { SyncEngineConfig } from '../interfaces/index.js';
  * algorithms."
  */
 export declare function computeFKDepthPriority(schema: Schema): ReadonlyMap<string, number>;
-export declare function deriveConfigFromSchema(schema: Schema): SyncEngineConfig;
+export declare function deriveConfigFromSchema(schema: Schema): RuntimeConfig;

package/dist/client/schemaConfig.js

@@ -3,10 +3,10 @@
  * functions: {@link computeFKDepthPriority} works out a safe row-insertion
  * order from the schema's foreign-key relations, and
  * {@link deriveConfigFromSchema} packages that ordering, together with a few
- * defaults, into the {@link SyncEngineConfig} a client uses at startup. Both
+ * defaults, into the {@link RuntimeConfig} a client uses at startup. Both
  * are deterministic transforms of the schema and hold no engine state.
  */
-import { schemaHash } from '../schema/serialize.js';
+import { schemaHash, modelHash, toSchemaJSON } from '../schema/serialize.js';
 // ── Config derivation from schema ─────────────────────────────────────────
 /**
  * Computes a create-priority map that gives the engine a safe order for
@@ -172,6 +172,10 @@ export function deriveConfigFromSchema(schema) {
         // schema the server currently has active. The server and the `ablo push`
         // command compute this same hash.
         expectedSchemaHash: schemaHash(schema),
+        // Per-model hashes for the SEMANTIC drift check: on a whole-hash mismatch
+        // the client compares only the models it declares, so an additive server
+        // change stays silent and a real divergence names the exact models.
+        expectedModelHashes: Object.fromEntries(Object.entries(toSchemaJSON(schema).models).map(([key, model]) => [key, modelHash(model)])),
         // For a projection (`selectModels`/`omitModels`), also carry the full source
         // schema's hash. The drift check accepts a server match on either hash, so a
         // subset client stays quiet against a server running its full source schema.

package/dist/client/storeCluster.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The store cluster — what `humans()` constructs at `init` now that the
+ * plugin context carries the resolved url and the credential source
+ * (ADR 0016; docs/plans/package-split.md, sequence step 2): this client's
+ * runtime, the internal component graph, the registered model classes, and
+ * the `BaseSyncedStore` that orchestrates them. The engine consumes the
+ * cluster instead of constructing it; what remains in the composition root
+ * (credential lifecycle, ready(), model proxies, resources) migrates in
+ * later steps.
+ *
+ * The cluster rides the humans surface under {@link kStoreCluster}, a
+ * symbol: `layerPluginSurface` merges only string-keyed members onto the
+ * client, so the handoff never becomes public client API. When the plugin
+ * contract adopts context patches (the decoration end-state), this channel
+ * dissolves into them.
+ */
+import type { PluginContext } from '../transaction/plugin.js';
+import type { Schema, SchemaRecord } from '../transaction/schema/schema.js';
+import { type RuntimeContext } from '../RuntimeContext.js';
+import { BaseSyncedStore } from '../BaseSyncedStore.js';
+import { type DefaultCollaborationEvents } from '../sync/SyncWebSocket.js';
+import { type InternalComponents } from './createInternalComponents.js';
+import type { InternalAbloOptions } from './options.js';
+/**
+ * The private handoff slot on the humans surface. Symbol-keyed on purpose:
+ * surface members merge onto the client by string key, and the cluster is
+ * construction machinery, not client API.
+ */
+export declare const kStoreCluster: unique symbol;
+/** What `humans().init` constructs and the engine consumes. */
+export interface StoreCluster {
+    /** This client's runtime — every component below was constructed with it. */
+    readonly runtime: RuntimeContext;
+    /** The component graph: registry, pool, bootstrap, database, sync client, hydration. */
+    readonly components: InternalComponents;
+    /** The store orchestrating the graph, holding the host-built connection. */
+    readonly store: BaseSyncedStore<DefaultCollaborationEvents, Schema<SchemaRecord>>;
+}
+/**
+ * Builds the cluster from what the context carries, or returns `null` when
+ * it does not carry enough (no connection, no resolved url, no credential
+ * source, or no schema on the options bag) — the same tolerance the
+ * presence stream established: `init` constructs what the context can
+ * support and no more. The reactive factory always supplies all four and
+ * treats a missing cluster as a configuration fault.
+ */
+export declare function buildStoreCluster(context: PluginContext<InternalAbloOptions<SchemaRecord>>): StoreCluster | null;

package/dist/client/storeCluster.js

@@ -0,0 +1,118 @@
+/**
+ * The store cluster — what `humans()` constructs at `init` now that the
+ * plugin context carries the resolved url and the credential source
+ * (ADR 0016; docs/plans/package-split.md, sequence step 2): this client's
+ * runtime, the internal component graph, the registered model classes, and
+ * the `BaseSyncedStore` that orchestrates them. The engine consumes the
+ * cluster instead of constructing it; what remains in the composition root
+ * (credential lifecycle, ready(), model proxies, resources) migrates in
+ * later steps.
+ *
+ * The cluster rides the humans surface under {@link kStoreCluster}, a
+ * symbol: `layerPluginSurface` merges only string-keyed members onto the
+ * client, so the handoff never becomes public client API. When the plugin
+ * contract adopts context patches (the decoration end-state), this channel
+ * dissolves into them.
+ */
+import { shouldUseInMemoryPersistence } from '../transaction/persistence.js';
+import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../RuntimeContext.js';
+import { initRuntime } from '../context.js';
+import { alwaysOnline } from '../adapters/alwaysOnline.js';
+import { BaseSyncedStore } from '../BaseSyncedStore.js';
+import { SyncWebSocket } from '../sync/SyncWebSocket.js';
+import { createInternalComponents, } from './createInternalComponents.js';
+import { registerModelsFromSchema } from './modelRegistration.js';
+import { deriveConfigFromSchema } from './schemaConfig.js';
+import { createDefaultMutationExecutor } from './wsMutationExecutor.js';
+/**
+ * The private handoff slot on the humans surface. Symbol-keyed on purpose:
+ * surface members merge onto the client by string key, and the cluster is
+ * construction machinery, not client API.
+ */
+export const kStoreCluster = Symbol('ablo.humans.storeCluster');
+/**
+ * The contract types the connection as the core `WsTransport`; on the
+ * reactive path the factory constructs the materialising subclass with the
+ * default collaboration vocabulary, and this guard is where that knowledge
+ * becomes a type. A connection that is not the subclass means the cluster
+ * cannot be built here.
+ */
+function isReactiveSocket(transport) {
+    return transport instanceof SyncWebSocket;
+}
+/**
+ * Builds the cluster from what the context carries, or returns `null` when
+ * it does not carry enough (no connection, no resolved url, no credential
+ * source, or no schema on the options bag) — the same tolerance the
+ * presence stream established: `init` constructs what the context can
+ * support and no more. The reactive factory always supplies all four and
+ * treats a missing cluster as a configuration fault.
+ */
+export function buildStoreCluster(context) {
+    const options = context.options;
+    const { url, auth, transport, logger } = context;
+    if (!options?.schema || !url || !auth || !isReactiveSocket(transport)) {
+        return null;
+    }
+    const schema = options.schema;
+    // Config derives from the schema; caller-supplied overrides layer on top,
+    // caller winning per key.
+    const config = {
+        ...deriveConfigFromSchema(schema),
+        ...options.configOverrides,
+    };
+    // The default executor sends `{ type: 'commit', ... }` over the context's
+    // connection; before it opens, sends reject with the diagnosed not-ready
+    // error and the MutationQueue owns the retry. A caller-supplied executor
+    // still wins (test mocks, alternative transports).
+    const executor = options.mutationExecutor ?? createDefaultMutationExecutor(() => transport);
+    // This client's runtime — the instance the whole graph is constructed
+    // with, so two clients in one process never read each other's logger,
+    // config, or executor. `getModelMetadata` closes over this client's own
+    // registry (assigned once the graph exists below), never the
+    // active-registry global.
+    let registryForMetadata;
+    const runtime = {
+        logger,
+        observability: options.observability ?? noopObservability,
+        analytics: options.analytics ?? noopAnalytics,
+        sessionErrorDetector: options.sessionErrorDetector ?? defaultSessionErrorDetector,
+        onlineStatus: options.onlineStatus ??
+            (shouldUseInMemoryPersistence(options) ? alwaysOnline() : browserOnlineStatus),
+        config,
+        mutationExecutor: executor,
+        getModelMetadata: (name) => registryForMetadata?.getMetadata(name),
+    };
+    // The module-global bridge: code not yet constructed with an instance
+    // (model instances, the react hooks, the socket's context ports) still
+    // reads it. Last-writer-wins there, exactly as before the runtime became
+    // per-client. Retired reference by reference (docs/plans/package-split.md).
+    initRuntime(runtime);
+    const components = createInternalComponents({
+        schema,
+        url,
+        options,
+        auth,
+        runtime,
+    });
+    registryForMetadata = components.modelRegistry;
+    registerModelsFromSchema(schema, components.modelRegistry);
+    const store = new BaseSyncedStore({
+        syncClient: components.syncClient,
+        database: components.database,
+        objectPool: components.objectPool,
+        modelRegistry: components.modelRegistry,
+        syncWebSocket: transport,
+        schema,
+        url,
+        auth,
+        runtime,
+        // The resolved list, so the store's delta pipeline dispatches the
+        // declared stage handlers — including this plugin's own `apply`.
+        stagePlugins: context.plugins ?? [],
+    }, 
+    // Collaboration vocabulary is the application's: the SDK subscribes to
+    // the event types the caller declares and to nothing by default.
+    { collaborationEvents: options.collaborationEvents ?? [] });
+    return { runtime, components, store };
+}

package/dist/client/storeLifecycle.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The materialiser's lifecycle: the first credential mint, identity
+ * resolution, the credential-refresh machinery, and the idempotent `ready()`
+ * that drives the store's initialize generator to completion. Extracted from
+ * the composition root along the humans() seam (docs/plans/package-split.md):
+ * the engine wires it with the prelude's credential slice and consumes
+ * `ready`; resolved identity flows back through one callback, so the
+ * engine-side state it seeds (the self locals, the streams) stays with the
+ * engine.
+ */
+import type { SchemaRecord, Schema } from '../transaction/schema/schema.js';
+import type { ParticipantKind } from '../transaction/types/participant.js';
+import type { Logger } from '../transaction/logger.js';
+import type { AuthCredentialSource } from '../transaction/auth/credentialSource.js';
+import type { ApiKeySetter } from '../transaction/auth/apiKey.js';
+import type { AbloError } from '../transaction/errors.js';
+import type { InternalAbloOptions } from './options.js';
+import type { StoreCluster } from './storeCluster.js';
+/** What identity resolution settled, handed back for the engine to seed. */
+export interface IdentitySeed {
+    readonly userId: string;
+    readonly participantKind: ParticipantKind;
+    /** The resolved account scope; null until known. */
+    readonly accountScope: string | null;
+    readonly syncGroups: readonly string[];
+}
+export interface StoreLifecycle {
+    /**
+     * Drives initialization to completion: first mint, identity resolution,
+     * seeding, then the store's initialize generator. Idempotent — the first
+     * call starts it, later calls share the promise; a failed attempt clears
+     * the memo so retry triggers can re-bootstrap.
+     */
+    ready(): Promise<void>;
+    /** Stops the credential refresh scheduler, if identity resolution installed one. */
+    dispose(): void;
+}
+export interface StoreLifecycleDeps<S extends SchemaRecord> {
+    readonly cluster: StoreCluster;
+    readonly schema: Schema<S>;
+    readonly internalOptions: InternalAbloOptions<S>;
+    readonly authCredentials: AuthCredentialSource;
+    readonly credentialResolver: (() => Promise<string | null>) | null;
+    readonly configuredApiKey: string | ApiKeySetter | null;
+    readonly configuredAuthToken: string | null;
+    readonly url: string;
+    readonly kind: ParticipantKind;
+    readonly logger: Logger;
+    /** The engine's up-front options validation; a present error makes `ready()` reject with it. */
+    readonly validationError: AbloError | null;
+    /** Seeds resolved identity into the engine's own state: the self locals and the streams. */
+    readonly onIdentityResolved: (seed: IdentitySeed) => void;
+}
+/**
+ * Wires the credential machinery onto the cluster and returns the `ready`
+ * the client exposes. Wiring happens now — the refresh lifecycle, the
+ * lazy-query auth recovery, the executor binding, and the opt-in auto-start;
+ * the first mint waits for `ready()` so the first connection carries a
+ * token.
+ */
+export declare function startStoreLifecycle<S extends SchemaRecord>(deps: StoreLifecycleDeps<S>): StoreLifecycle;