@abloatai/ablo 0.36.0 → 0.37.0

package/dist/client/resourceTypes.d.ts

@@ -1,12 +0,0 @@
-/**
- * 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 * 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,10 +0,0 @@
-/**
- * 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 * from '../transaction/resources/httpResources.js';

package/dist/client/schemaConfig.d.ts

@@ -1,44 +0,0 @@
-/**
- * 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 '../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
- * 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/client/schemaConfig.js

@@ -1,185 +0,0 @@
-/**
- * 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/client/storeCluster.d.ts

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,118 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-/**
- * 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;