@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/base/composition/index.d.cts

@@ -0,0 +1,469 @@
+import { Messages, NodeOptions, Node } from '@graphrefly/pure-ts/core';
+export { D as DistillBundle, a as DistillOptions, E as Extraction, d as distill } from '../../distill-De6Rnn15.cjs';
+export { B as BundleTriad, E as EmitTriad, a as ExternalBundleOptions, b as ExternalRegister, e as externalBundle, c as externalProducer } from '../../external-register-CWyroXb_.cjs';
+import { Graph } from '@graphrefly/pure-ts/graph';
+export { T as ToObservableOptions, t as toObservable } from '../../observable-BXQoW1P-.cjs';
+import { ReactiveLogBundle, PubSubChange, NodeInput } from '@graphrefly/pure-ts/extra';
+import 'rxjs';
+
+/**
+ * Watermark-based backpressure controller — reactive PAUSE/RESUME flow control.
+ *
+ * Purely synchronous, event-driven. No timers, no polling, no Promises.
+ * Each controller instance uses a unique lockId so multiple controllers
+ * on the same upstream node do not collide.
+ *
+ * @module
+ */
+
+type WatermarkOptions = {
+    /** Pending count at which PAUSE is sent upstream. */
+    highWaterMark: number;
+    /** Pending count at which RESUME is sent upstream (after being paused). */
+    lowWaterMark: number;
+};
+type WatermarkController = {
+    /** Call when a DATA message is buffered/enqueued. Returns `true` if PAUSE was just sent. */
+    onEnqueue(): boolean;
+    /** Call when a buffered item is consumed. Returns `true` if RESUME was just sent. */
+    onDequeue(): boolean;
+    /** Current un-consumed item count. */
+    readonly pending: number;
+    /** Whether upstream is currently paused by this controller. */
+    readonly paused: boolean;
+    /** Dispose: if paused, sends RESUME to unblock upstream. */
+    dispose(): void;
+};
+/**
+ * Creates a watermark-based backpressure controller.
+ *
+ * @param sendUp - Callback that delivers messages upstream (typically `handle.up`).
+ * @param opts - High/low watermark thresholds (item counts).
+ * @returns A {@link WatermarkController}.
+ *
+ * @example
+ * ```ts
+ * const handle = graph.observe("fast-source");
+ * const wm = createWatermarkController(
+ *   (msgs) => handle.up(msgs),
+ *   { highWaterMark: 64, lowWaterMark: 16 },
+ * );
+ *
+ * // In sink callback:
+ * handle.subscribe((msgs) => {
+ *   for (const msg of msgs) {
+ *     if (msg[0] === DATA) {
+ *       buffer.push(msg[1]);
+ *       wm.onEnqueue();
+ *     }
+ *   }
+ * });
+ *
+ * // When consumer drains:
+ * const item = buffer.shift();
+ * wm.onDequeue();
+ * ```
+ *
+ * @category extra
+ */
+declare function createWatermarkController(sendUp: (messages: Messages) => void, opts: WatermarkOptions): WatermarkController;
+
+/**
+ * Phase 13.C — `selector` + `materialize` composers (DS-13.C / G2 lock C).
+ *
+ * Two paired primitives for dynamic-mount routing:
+ *
+ * - {@link selector} — projects an input value to a routing key, deduped.
+ *   Equivalent to `map + distinctUntilChanged`, but the dedup is the
+ *   semantic point: the key changes ONLY when the routed-to slot should
+ *   change. Fires `materialize` re-mounts efficiently.
+ *
+ * - {@link materialize} — given a reactive `key` and a reactive map of
+ *   `key → factory` thunks, mounts the matching factory's Graph under
+ *   `parent` at a stable slot name. When `key` changes, unmounts the old
+ *   slot and mounts the new factory's output. When `factories` mutates but
+ *   `key` stays the same, the current slot continues to run on the OLD
+ *   factory ("current sessions complete on old factory; new sessions use
+ *   new factory" — full hot-swap correctness deferred to G10, parked).
+ *
+ * Reusable beyond the agent layer:
+ * - `harnessLoop` strategy routing — the strategy node IS a `selector`.
+ * - `pipelineGraph` dynamic stage selection.
+ * - `refineLoop` strategy swap.
+ * - Phase 13.I `spawnable()` mounts agent slots via `materialize`.
+ */
+
+/** Options for operator nodes: NodeOptions without `describeKind` (set internally). */
+type ExtraOpts = Omit<NodeOptions<unknown>, "describeKind">;
+/** Options for {@link selector}. */
+type SelectorOpts<TKey> = ExtraOpts & {
+    /**
+     * Equality comparator for the projected key. Defaults to {@link Object.is}.
+     * Used to suppress re-emits when the input changes but the projected key
+     * does not — this is the load-bearing behavior that lets downstream
+     * `materialize` skip unnecessary unmount/remount cycles.
+     */
+    equals?: (a: TKey, b: TKey) => boolean;
+};
+/**
+ * Projects each upstream value to a routing key, deduped on the key. The
+ * output node emits a key only when the projected key actually changes —
+ * pairs cleanly with {@link materialize}, which re-mounts only on key
+ * change.
+ *
+ * **Differs from `map`:** `map(input, fn)` fires on every upstream wave
+ * regardless of output value. `selector(input, fn)` fires only when the
+ * projected key CHANGES (under `equals`), so downstream re-mount logic is
+ * stable.
+ *
+ * @param input - Upstream node carrying the value to project.
+ * @param fn - Synchronous projection function.
+ * @param opts - Optional {@link SelectorOpts}.
+ * @returns `Node<TKey>` carrying the latest projected key (deduped).
+ *
+ * @example
+ * ```ts
+ * import { selector, materialize, state } from "@graphrefly/graphrefly-ts";
+ *
+ * type Request = { kind: "research" | "summarize" | "code"; payload: unknown };
+ * const requestNode = state<Request>({ kind: "research", payload: {} });
+ *
+ * const presetId = selector(requestNode, (req) => req.kind);
+ * // presetId is `Node<"research" | "summarize" | "code">`, deduped.
+ * // Downstream materialize re-mounts ONLY when the kind axis changes.
+ * ```
+ *
+ * @category extra
+ */
+declare function selector<TIn, TKey>(input: Node<TIn>, fn: (input: TIn) => TKey, opts?: SelectorOpts<TKey>): Node<TKey>;
+/**
+ * Factory thunk for a {@link materialize} slot. Called once per mount cycle
+ * to mint a fresh `TGraph` instance. The instance is mounted under
+ * `parent.mount(slotName, ...)` and unmounted via `parent.remove(slotName)`
+ * when `key` next changes.
+ *
+ * Each invocation MUST return a fresh, never-before-mounted Graph instance —
+ * `Graph.mount` rejects re-mounting an instance that is already mounted
+ * elsewhere in the tree. Caching factory output is unsafe.
+ */
+type GraphFactory<TGraph extends Graph> = () => TGraph;
+/** Options for {@link materialize}. */
+type MaterializeOpts = ExtraOpts & {
+    /**
+     * Local mount name on the parent graph. Default `"materialized"`.
+     *
+     * Two materialize calls on the SAME parent must use distinct `slotName`
+     * values, otherwise the second mount throws "mount already exists".
+     * For a hub mounting many slots (e.g. {@link spawnable}'s preset
+     * registry), use `slotName: \`preset-\${id}\`` or similar.
+     */
+    slotName?: string;
+};
+/**
+ * Reactive dynamic mount: mounts the Graph instance for `key` under
+ * `parent.mount(slotName, ...)`, and re-mounts when `key` changes.
+ *
+ * **Lifecycle.** First DATA on `key` triggers a mount: look up
+ * `factories.get(key)`, call the factory thunk, mount the result under
+ * `parent`. Each subsequent `key` change unmounts the previous slot and
+ * mounts the new one. When this materialize node terminates (subscriber
+ * teardown, `COMPLETE` from `key`, `Graph.destroy`), the active slot is
+ * unmounted via `parent.remove(slotName)`.
+ *
+ * **Hot-swap policy (G10 deferred).** When `factories` mutates but `key`
+ * stays the same, the currently-mounted slot is NOT re-instantiated —
+ * "current sessions complete on old factory; new sessions use new
+ * factory." Atomic disconnect/reconnect of an in-flight slot to a new
+ * factory is parked under G10 (see `optimizations.md` "G10 atomic
+ * registry hot-swap").
+ *
+ * **Output.** The returned `Node<TGraph>` emits the currently-mounted
+ * Graph reference whenever a mount occurs. Consumers can subscribe to
+ * watch slot changes, or read `.cache` for the active mount. SENTINEL
+ * (no DATA) when no slot is currently mounted (e.g. `key` has no matching
+ * factory).
+ *
+ * **Spec compliance.**
+ * - No polling: mount transitions are reactive on `key` / `factories`.
+ * - No raw async: factory invocation is synchronous; if a factory needs
+ *   async setup, it returns a Graph that handles its own setup internally.
+ * - Mount/unmount happens as side-effects inside the reactive `subscribe`
+ *   handler — sanctioned per spec §5.9 (Graph topology mutations are
+ *   imperative writes at the system boundary, not in-flight reactive
+ *   triggers).
+ *
+ * @param key - Reactive routing key. Re-mounts on each key change (deduped
+ *   by reference; pair with {@link selector} for projection-based dedup).
+ * @param factories - Reactive map of `key → factory thunk`. Factory map
+ *   mutations don't disturb the active slot until the next key change.
+ * @param parent - Graph to mount slots under. The `slotName` (default
+ *   `"materialized"`) must be free on `parent` at construction time.
+ * @param opts - Optional {@link MaterializeOpts}.
+ * @returns `Node<TGraph>` carrying the active mount.
+ *
+ * @example
+ * ```ts
+ * import { materialize, selector, state, Graph } from "@graphrefly/graphrefly-ts";
+ *
+ * const parent = new Graph("parent");
+ * const factories = state<ReadonlyMap<string, () => Graph>>(new Map([
+ *   ["researcher", () => new ResearchAgentGraph()],
+ *   ["coder",      () => new CoderAgentGraph()],
+ * ]));
+ * const key = selector(requestNode, (r) => r.kind);
+ * const slot = materialize(key, factories, parent, { slotName: "agent" });
+ * // `slot.cache` is the active agent graph; `parent.node("agent::out")`
+ * // resolves into whichever agent is currently mounted.
+ * ```
+ *
+ * @category extra
+ */
+declare function materialize<TKey, TGraph extends Graph>(key: Node<TKey>, factories: Node<ReadonlyMap<TKey, GraphFactory<TGraph>>>, parent: Graph, opts?: MaterializeOpts): Node<TGraph>;
+
+/**
+ * Lazy per-topic state hub (roadmap §3.2) — lightweight last-value broadcasts.
+ *
+ * Each topic is a sentinel `node<unknown>()` with push-on-subscribe replay of
+ * the most recent published value (no push until the first `publish`). For
+ * Pulsar-inspired retained message logs,
+ * cursor-based subscriptions, and job-queue semantics, use `messagingHub()` in
+ * `utils/messaging` — built on `TopicGraph` / `SubscriptionGraph` with
+ * retention policies, absolute cursor tracking, and per-subscriber state.
+ *
+ * Presentation layer (base/composition). Moved from pure-ts during cleave A3
+ * (no substrate core/graph dependency on pubsub found).
+ */
+
+/**
+ * Storage contract for {@link pubsub} — registry only.
+ *
+ * Tracks the set of topic names plus a monotonic `version` counter that
+ * advances on topic create/remove. Does NOT own per-topic message storage —
+ * per-topic cached last values live in the topic nodes themselves (sentinel
+ * until the first publish).
+ *
+ * For distributed / persistent per-topic storage, use `messagingHub()` in
+ * `utils/messaging`, which composes `TopicGraph` under a lazy registry.
+ *
+ * @category base
+ */
+interface PubSubBackend {
+    /** Monotonic counter; advances on topic create/remove. */
+    readonly version: number;
+    readonly topicCount: number;
+    hasTopic(name: string): boolean;
+    topicNames(): IterableIterator<string>;
+    /** Records topic creation. Returns `true` if newly added (advances `version`). */
+    createTopic(name: string): boolean;
+    /** Records topic removal. Returns `true` if it existed (advances `version`). */
+    removeTopic(name: string): boolean;
+}
+/**
+ * Default in-memory registry backend.
+ *
+ * @category base
+ */
+declare class NativePubSubBackend implements PubSubBackend {
+    private _version;
+    private readonly _topics;
+    get version(): number;
+    get topicCount(): number;
+    hasTopic(name: string): boolean;
+    topicNames(): IterableIterator<string>;
+    createTopic(name: string): boolean;
+    removeTopic(name: string): boolean;
+}
+type PubSubHubOptions = {
+    /**
+     * Storage backend. Defaults to `NativePubSubBackend`. Pluggable for audit /
+     * monitoring / mirror-to-external-broker use cases.
+     */
+    backend?: PubSubBackend;
+    /**
+     * DS-14 / DS14R2 — opt-in delta companion. When set, the hub appends a
+     * typed {@link PubSubChange} record in the **same batch frame** as the
+     * topic emission / teardown (same-wave consistency — subscribers reading
+     * both a topic and `mutationLog` never see torn state).
+     *
+     * Records the locked `PubSubChange` verbs that apply to this last-value
+     * hub: `publish` (per `publish` / `publishMany`) and `remove` (per
+     * `removeTopic`). The `ack` verb is a cursor concern of `messagingHub()`
+     * and does not apply here. **Note:** the locked `publish` payload carries
+     * `value` only (no topic name) — callers needing per-topic delta
+     * correlation should embed identity in the value or use `messagingHub()`.
+     *
+     * `true` = defaults; object form forwards `maxSize` / `name` to the inner
+     * `reactiveLog`.
+     */
+    mutationLog?: true | {
+        maxSize?: number;
+        name?: string;
+    };
+};
+/**
+ * Lazy per-topic state hub. Topics are single-value sentinel nodes
+ * with push-on-subscribe replay of the most recent publish.
+ *
+ * @category base
+ */
+interface PubSubHub {
+    /**
+     * Returns the topic node, creating it on first use.
+     *
+     * @param name - Topic key.
+     * @returns `Node` whose value is the last published payload. Starts in
+     *   sentinel state — no push-on-subscribe until the first publish.
+     */
+    topic(name: string): Node<unknown>;
+    /** Publishes a value to the topic (lazily creating the topic if missing). */
+    publish(name: string, value: unknown): void;
+    /**
+     * Bulk publish — single outer batch for all entries. No-op if empty.
+     *
+     * **Iterable consumption (F6):** `entries` is consumed once (single-pass).
+     * Pass an array or `Set` for multi-shot callers. Iteration happens INSIDE
+     * the batch frame — if the iterator throws mid-way, the batch is discarded
+     * and NO publishes are visible to subscribers (all-or-nothing within one
+     * call).
+     */
+    publishMany(entries: Iterable<[string, unknown]>): void;
+    /** Removes a topic; sends `TEARDOWN` to its node. Returns `true` if it existed. */
+    removeTopic(name: string): boolean;
+    /** Checks topic existence without creating. O(1). */
+    has(name: string): boolean;
+    /** Number of topics currently registered. O(1). */
+    readonly size: number;
+    /** Iterator over topic names. */
+    topicNames(): IterableIterator<string>;
+    /**
+     * DS14R2 — present iff `mutationLog` was configured. Append-only log of
+     * `publish` / `remove` deltas, same-wave-consistent with topic emissions.
+     */
+    readonly mutationLog?: ReactiveLogBundle<PubSubChange>;
+}
+/**
+ * Creates a lazy per-topic state hub.
+ *
+ * @param options - Optional pluggable `backend` (defaults to `NativePubSubBackend`).
+ * @returns Hub with lazy `topic()` / `publish()` / `publishMany()` / `removeTopic()` /
+ *   `has()` / `size` / `topicNames()`.
+ *
+ * @remarks
+ * **Scope:** Each topic is a sentinel node — retains only the last published
+ * value (no push-on-subscribe before the first publish). For Pulsar-inspired
+ * retention + cursor reading, use `messagingHub()` in `utils/messaging`.
+ *
+ * **`removeTopic`:** Sends `TEARDOWN` to the topic node; all subscribers receive
+ * the TEARDOWN message. Subsequent `publish(name, value)` silently recreates the
+ * topic with a fresh node — existing subscribers to the old node do NOT reconnect.
+ *
+ * @example
+ * ```ts
+ * import { pubsub } from "@graphrefly/graphrefly";
+ *
+ * const hub = pubsub();
+ * const t = hub.topic("events");
+ * t.subscribe((msgs) => console.log(msgs));
+ * hub.publish("events", { ok: true });
+ * hub.publishMany([["events", 1], ["status", "ready"]]);
+ * ```
+ *
+ * @category base
+ */
+declare function pubsub(options?: PubSubHubOptions): PubSubHub;
+
+/**
+ * `singleFromAny` — keyed promise/Node de-duplication ("singleflight").
+ *
+ * Given a `factory: (key) => NodeInput<T>`, returns a callable that dedupes
+ * concurrent invocations sharing the same key — all callers with the same
+ * key while a request is in-flight receive the same `Promise<T>`. Once the
+ * underlying source settles (DATA, ERROR, or COMPLETE), the cache entry is
+ * cleared so the next call re-invokes the factory.
+ *
+ * This is the classic "singleflight" pattern from Go, generalised over the
+ * library's `NodeInput<T>` bridge so callers can pass Promise-returning
+ * factories, Node-returning factories, or plain value factories with
+ * identical semantics.
+ *
+ * Use cases:
+ * - `withReplayCache` cache-miss thundering-herd dedup
+ * - Shared HTTP fetches keyed by URL
+ * - Expensive compute keyed by request fingerprint
+ *
+ * @example
+ * ```ts
+ * const fetchUser = singleFromAny<string, User>((id) => fetch(`/users/${id}`).then(r => r.json()));
+ * // Two concurrent callers with id="42" → one underlying fetch, two Promises resolving to the same User.
+ * const [a, b] = await Promise.all([fetchUser("42"), fetchUser("42")]);
+ * ```
+ *
+ * @category extra
+ */
+
+interface SingleFromAnyOptions<K> {
+    /**
+     * Convert a typed key into a cache-string. Defaults to `String(key)`, which
+     * works for primitive keys; callers with object keys should provide a
+     * stable serializer (e.g., canonical JSON).
+     */
+    keyFn?: (key: K) => string;
+}
+/**
+ * Dedupe concurrent `factory(key)` invocations. Returns a bound callable.
+ *
+ * @param factory - Produces a `NodeInput<T>` for each unique key.
+ * @param opts - Optional key-stringification.
+ * @returns A function `(key: K) => Promise<T>` whose inflight results are shared per key.
+ */
+declare function singleFromAny<K, T>(factory: (key: K) => NodeInput<T>, opts?: SingleFromAnyOptions<K>): (key: K) => Promise<T>;
+/**
+ * Reactive variant: returns a bound callable that hands out `Node<T>` values.
+ * All concurrent callers with the same key during an in-flight source share
+ * the same Node. When the underlying source **terminally** settles (ERROR
+ * or COMPLETE), the Node is removed from the cache so the next call
+ * re-invokes `factory`. DATA is NOT terminal — callers subscribing after
+ * the first DATA still receive the shared Node (and push-on-subscribe per
+ * the spec's cached-DATA contract).
+ *
+ * Use when downstream wants reactive subscription (not a one-shot Promise).
+ *
+ * @category extra
+ */
+declare function singleNodeFromAny<K, T>(factory: (key: K) => NodeInput<T>, opts?: SingleFromAnyOptions<K>): (key: K) => Node<T>;
+
+/**
+ * Composite data patterns (roadmap §3.2b).
+ *
+ * These helpers compose existing primitives (`node`, `switchMap`, `reactiveMap`,
+ * `dynamicNode`, `fromAny`) without introducing new protocol semantics.
+ */
+
+/**
+ * Verification payload shape is intentionally user-defined.
+ */
+type VerifyValue = unknown;
+type VerifiableOptions<TVerify = VerifyValue> = Omit<NodeOptions, "describeKind" | "initial"> & {
+    /** Reactive re-verification trigger. */
+    trigger?: NodeInput<unknown>;
+    /** Re-run verification whenever `source` settles. */
+    autoVerify?: boolean;
+    /** Initial verification companion value. */
+    initialVerified?: TVerify | null;
+};
+type VerifiableBundle<T, TVerify = VerifyValue> = {
+    /** Coerced source node. */
+    node: Node<T>;
+    /** Latest verification result (`null` before first verification). */
+    verified: Node<TVerify | null>;
+    /** Effective trigger node used for verification, if any. */
+    trigger: Node<unknown> | null;
+};
+/**
+ * Composes a value node with a reactive verification companion.
+ *
+ * Uses `switchMap` so newer triggers cancel stale in-flight verification work.
+ */
+declare function verifiable<T, TVerify = VerifyValue>(source: NodeInput<T>, verifyFn: (value: T) => NodeInput<TVerify>, opts?: VerifiableOptions<TVerify>): VerifiableBundle<T, TVerify>;
+
+export { type ExtraOpts, type GraphFactory, type MaterializeOpts, NativePubSubBackend, type PubSubBackend, type PubSubHub, type PubSubHubOptions, type SelectorOpts, type SingleFromAnyOptions, type VerifiableBundle, type VerifiableOptions, type VerifyValue, type WatermarkController, type WatermarkOptions, createWatermarkController, materialize, pubsub, selector, singleFromAny, singleNodeFromAny, verifiable };