@abloatai/humans 0.37.0

package/dist/local/client/resourceTypes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The interactive 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 * from '@abloatai/transaction/resources/httpResources';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, } from '@abloatai/transaction/resources/modelOperations';
+export type { ModelOperations } from './createModelProxy.js';

package/dist/local/client/resourceTypes.js

@@ -0,0 +1,10 @@
+/**
+ * The interactive 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 * from '@abloatai/transaction/resources/httpResources';

package/dist/local/client/schemaConfig.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Derives engine configuration from a schema. This module holds two pure
+ * 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 RuntimeConfig} a client uses at startup. Both
+ * are deterministic transforms of the schema and hold no engine state.
+ */
+import type { Schema } from '@abloatai/transaction/schema/schema';
+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
+ * foreign key references.
+ *
+ * Every `belongsTo` relation is an edge from a child model to its parent. This
+ * function runs Tarjan's strongly-connected-components algorithm over that
+ * graph, which does two things at once: it groups any models that reference
+ * each other in a cycle into a single component, and it produces those
+ * components in an order where parents come before children. Each model then
+ * gets a numeric priority from that order, where a lower number means "insert
+ * earlier". Top-level models with no parent — an organization or a theme, say —
+ * come first, and the deepest descendants come last.
+ *
+ * Models in the same cycle share a priority, so within a cycle the order rows
+ * were queued in breaks the tie. To break a cycle deterministically instead,
+ * mark one side of it with `belongsTo(target, fk, { defer: true })`. A deferred
+ * edge is left out of the graph, which turns the cycle into a chain and gives
+ * the deferred child a strictly higher priority than its parent. Pair it with a
+ * Postgres `DEFERRABLE INITIALLY DEFERRED` constraint if you also want the
+ * database to relax its check. See {@link BelongsToOptions.defer}.
+ *
+ * The returned map is keyed by each model's wire type name
+ * ({@link ModelDef.typename}, falling back to the schema key), because that is
+ * the name the engine looks up at commit time. Keying by the schema key would
+ * miss that lookup, and every model would fall back to the default priority.
+ *
+ * The result does not depend on which model the walk starts from, and the
+ * algorithm runs in time linear in the number of models plus relations.
+ * Reference: Tarjan, R. (1972), "Depth-first search and linear graph
+ * algorithms."
+ */
+export declare function computeFKDepthPriority(schema: Schema): ReadonlyMap<string, number>;
+export declare function deriveConfigFromSchema(schema: Schema): RuntimeConfig;

package/dist/local/client/schemaConfig.js

@@ -0,0 +1,185 @@
+/**
+ * Derives engine configuration from a schema. This module holds two pure
+ * 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 RuntimeConfig} a client uses at startup. Both
+ * are deterministic transforms of the schema and hold no engine state.
+ */
+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
+ * inserting rows, so a child row is never written before the parent its
+ * foreign key references.
+ *
+ * Every `belongsTo` relation is an edge from a child model to its parent. This
+ * function runs Tarjan's strongly-connected-components algorithm over that
+ * graph, which does two things at once: it groups any models that reference
+ * each other in a cycle into a single component, and it produces those
+ * components in an order where parents come before children. Each model then
+ * gets a numeric priority from that order, where a lower number means "insert
+ * earlier". Top-level models with no parent — an organization or a theme, say —
+ * come first, and the deepest descendants come last.
+ *
+ * Models in the same cycle share a priority, so within a cycle the order rows
+ * were queued in breaks the tie. To break a cycle deterministically instead,
+ * mark one side of it with `belongsTo(target, fk, { defer: true })`. A deferred
+ * edge is left out of the graph, which turns the cycle into a chain and gives
+ * the deferred child a strictly higher priority than its parent. Pair it with a
+ * Postgres `DEFERRABLE INITIALLY DEFERRED` constraint if you also want the
+ * database to relax its check. See {@link BelongsToOptions.defer}.
+ *
+ * The returned map is keyed by each model's wire type name
+ * ({@link ModelDef.typename}, falling back to the schema key), because that is
+ * the name the engine looks up at commit time. Keying by the schema key would
+ * miss that lookup, and every model would fall back to the default priority.
+ *
+ * The result does not depend on which model the walk starts from, and the
+ * algorithm runs in time linear in the number of models plus relations.
+ * Reference: Tarjan, R. (1972), "Depth-first search and linear graph
+ * algorithms."
+ */
+export function computeFKDepthPriority(schema) {
+    // schemaKey → typename (wire name used at transaction time)
+    const keyToTypename = new Map();
+    for (const [key, def] of Object.entries(schema.models)) {
+        keyToTypename.set(key, def.typename ?? key);
+    }
+    // Adjacency: schemaKey → parent schema keys pulled from `belongsTo`.
+    // Parents not in the schema (e.g. external types) are dropped so the
+    // graph stays closed. Edges marked `{ defer: true }` are also
+    // dropped — the schema author has declared this side of a cycle to
+    // be the "soft" one (insert with null FK, patch later), so the
+    // dependency-graph walker treats it as if the edge weren't there.
+    // That breaks the cycle deterministically and lets the other side
+    // become a strict topological predecessor.
+    const parentsOf = new Map();
+    for (const [key, def] of Object.entries(schema.models)) {
+        const out = [];
+        for (const rel of Object.values(def.relations)) {
+            if (rel.type !== 'belongsTo')
+                continue;
+            if (!keyToTypename.has(rel.target))
+                continue;
+            if (rel.options?.defer === true)
+                continue;
+            out.push(rel.target);
+        }
+        parentsOf.set(key, out);
+    }
+    // Tarjan SCC bookkeeping
+    const dfsIndex = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    let counter = 0;
+    function strongconnect(v) {
+        dfsIndex.set(v, counter);
+        lowlink.set(v, counter);
+        counter++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of parentsOf.get(v) ?? []) {
+            if (!dfsIndex.has(w)) {
+                strongconnect(w);
+                lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
+            }
+            else if (onStack.has(w)) {
+                // Back-edge into the active DFS path — w is in the same SCC as v.
+                lowlink.set(v, Math.min(lowlink.get(v), dfsIndex.get(w)));
+            }
+        }
+        // v is the root of an SCC: pop everything down to v inclusive.
+        if (lowlink.get(v) === dfsIndex.get(v)) {
+            const component = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                component.push(w);
+            } while (w !== v);
+            sccs.push(component);
+        }
+    }
+    for (const key of keyToTypename.keys()) {
+        if (!dfsIndex.has(key))
+            strongconnect(key);
+    }
+    // Tarjan emits SCCs in reverse topological order of the condensation.
+    // In our edge convention (child→parent), reverse-topo of the
+    // condensation means root-SCCs (no outgoing edges = no parents)
+    // first, leaf-SCCs (deepest descendants) last. We could just use
+    // emit-order as the priority — but that gives independent sibling
+    // SCCs different priorities, which is semantically wrong: siblings
+    // don't depend on each other and shouldn't be ordered relative to
+    // each other.
+    //
+    // Instead, do one more pass to compute *longest-path depth* on the
+    // condensation DAG: depth(SCC) = max(depth(parent SCC)) + 1, or 0
+    // for SCCs with no in-schema parents. SCCs at the same depth get
+    // the same priority — siblings stay tied, insertion order in the
+    // queue breaks the tie. Priority = (depth + 1) * 10.
+    //
+    // We can compute this in a single pass over the SCCs because
+    // Tarjan's emit-order *is* a valid topological order of the
+    // condensation: when we process sccs[i], every parent SCC has
+    // already been assigned a depth.
+    const nodeToSccIdx = new Map();
+    sccs.forEach((scc, i) => {
+        for (const node of scc)
+            nodeToSccIdx.set(node, i);
+    });
+    const sccDepth = new Map();
+    sccs.forEach((scc, i) => {
+        let maxParentDepth = -1;
+        for (const node of scc) {
+            for (const parent of parentsOf.get(node) ?? []) {
+                const parentSccIdx = nodeToSccIdx.get(parent);
+                if (parentSccIdx === undefined)
+                    continue;
+                if (parentSccIdx === i)
+                    continue; // intra-SCC edge — not a dep
+                const d = sccDepth.get(parentSccIdx);
+                if (d !== undefined && d > maxParentDepth)
+                    maxParentDepth = d;
+            }
+        }
+        sccDepth.set(i, maxParentDepth + 1);
+    });
+    const out = new Map();
+    sccs.forEach((scc, i) => {
+        const priority = (sccDepth.get(i) + 1) * 10;
+        for (const key of scc) {
+            out.set(keyToTypename.get(key), priority);
+        }
+    });
+    return out;
+}
+export function deriveConfigFromSchema(schema) {
+    // Field-level serialization for commits happens in the transaction queue,
+    // which reads each model's declared fields from the model registry at commit
+    // time. There is no per-field metadata to configure here, so these maps stay
+    // empty.
+    return {
+        modelCreatePriority: computeFKDepthPriority(schema),
+        defaultCreatePriority: 40,
+        defaultNonCreatePriority: 50,
+        essentialFields: {},
+        classNameFallbackMap: {},
+        // Hash this schema once, so startup can detect when it has drifted from the
+        // 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.
+        // Undefined for a directly-authored schema — plain equality applies there.
+        expectedSourceSchemaHash: schema.sourceSchemaHash,
+    };
+}

package/dist/local/client/storeCluster.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 '../../plugin.js';
+import { type RuntimeContext } from '../RuntimeContext.js';
+import { BaseSyncedStore } from '../BaseSyncedStore.js';
+import { type InternalComponents } from './createInternalComponents.js';
+import type { InternalAbloOptions } from './options.js';
+export 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;
+}
+/**
+ * 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>): StoreCluster | null;

package/dist/local/client/storeCluster.js

@@ -0,0 +1,133 @@
+/**
+ * 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 '../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.for('ablo.humans.store-cluster');
+/**
+ * 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) {
+    if (!transport || typeof transport !== 'object')
+        return false;
+    const candidate = transport;
+    return [
+        'subscribe',
+        'sendCollaborationEvent',
+        'disconnect',
+        'isConnected',
+        'getSyncGroups',
+        'setSyncGroups',
+        'setLastSyncId',
+        'getLastSyncId',
+        'acknowledge',
+        'allowConnect',
+        'connect',
+    ].every((method) => typeof candidate[method] === 'function');
+}
+/**
+ * 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 = undefined;
+    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/local/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 interactive composition root (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 '@abloatai/transaction/schema/schema';
+import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { Logger } from '@abloatai/transaction/logger';
+import type { AuthCredentialSource } from '@abloatai/transaction/auth/credentialSource';
+import type { CredentialProvider } from '@abloatai/transaction/auth/apiKey';
+import type { AbloError } from '@abloatai/transaction/errors';
+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: CredentialProvider | null;
+    readonly configuredApiKey: string | CredentialProvider | 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;