@abloatai/humans 0.37.0

package/src/local/client/resourceTypes.ts

@@ -0,0 +1,37 @@
+/**
+ * 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';
+
+// The request contract for `ablo.<model>` — also core, re-joined here so this
+// module stays the single import path for the whole resource surface.
+export type {
+  LocalCountOptions,
+  LocalReadOptions,
+  ModelListScope,
+  ServerReadOptions,
+  ModelRetrieveParams,
+  ModelCreateParams,
+  ModelUpdateParams,
+  ModelDeleteParams,
+  ClaimOptions,
+  ClaimParams,
+  ClaimLookupParams,
+  ClaimReorderParams,
+  Claim,
+  ClaimHeartbeat,
+  ClaimHeartbeatOptions,
+  HeldClaim,
+  HeldLease,
+} from '@abloatai/transaction/resources/modelOperations';
+
+// `ModelOperations` binds the request contract to reactive model instances, so
+// it lives with the factory that builds it rather than with the core.
+export type { ModelOperations } from './createModelProxy.js';

package/src/local/client/schemaConfig.ts

@@ -0,0 +1,194 @@
+/**
+ * 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 { RelationDef } from '@abloatai/transaction/schema/relation';
+import type { RuntimeConfig } from '../interfaces/index.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
+ * 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: Schema): ReadonlyMap<string, number> {
+  // schemaKey → typename (wire name used at transaction time)
+  const keyToTypename = new Map<string, string>();
+  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<string, readonly string[]>();
+  for (const [key, def] of Object.entries(schema.models)) {
+    const out: string[] = [];
+    for (const rel of Object.values(def.relations) as (RelationDef & { options?: { defer?: boolean } })[]) {
+      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<string, number>();
+  const lowlink = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+  const sccs: string[][] = [];
+  let counter = 0;
+
+  function strongconnect(v: string): void {
+    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: string[] = [];
+      let w: string;
+      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<string, number>();
+  sccs.forEach((scc, i) => {
+    for (const node of scc) nodeToSccIdx.set(node, i);
+  });
+
+  const sccDepth = new Map<number, number>();
+  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<string, number>();
+  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: Schema): RuntimeConfig {
+  // 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/src/local/client/storeCluster.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 { shouldUseInMemoryPersistence } from '../persistence.js';
+import type { MutationExecutor, RuntimeConfig } from '../interfaces/index.js';
+import type { ModelRegistry } from '../ModelRegistry.js';
+import {
+  noopObservability,
+  browserOnlineStatus,
+  defaultSessionErrorDetector,
+  noopAnalytics,
+  type RuntimeContext,
+} 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,
+  type InternalComponents,
+} from './createInternalComponents.js';
+import { registerModelsFromSchema } from './modelRegistration.js';
+import { deriveConfigFromSchema } from './schemaConfig.js';
+import { createDefaultMutationExecutor } from './wsMutationExecutor.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 const kStoreCluster = Symbol.for('ablo.humans.store-cluster');
+
+/** 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;
+}
+
+/**
+ * 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: unknown): transport is SyncWebSocket {
+  if (!transport || typeof transport !== 'object') return false;
+  const candidate = transport as Record<string, unknown>;
+  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: PluginContext<InternalAbloOptions>,
+): StoreCluster | null {
+  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: RuntimeConfig = {
+    ...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: MutationExecutor =
+    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: ModelRegistry | undefined = undefined;
+  const runtime: RuntimeContext = {
+    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 };
+}