@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/utils/graphspec/index.d.cts

@@ -0,0 +1,449 @@
+import { Node, DescribeNodeOutput } from '@graphrefly/pure-ts/core';
+import { Graph, GraphDescribeOutput } from '@graphrefly/pure-ts/graph';
+import { L as LLMAdapter } from '../../types-BB5Lw-pB.cjs';
+import '@graphrefly/pure-ts/extra';
+
+/**
+ * LLM graph composition (roadmap §8.3).
+ *
+ * Declarative GraphSpec schema + compiler/decompiler for graph topology.
+ * The LLM designs graphs as JSON; `compileSpec` instantiates them;
+ * `decompileSpec` extracts them back. Templates support reusable subgraph
+ * patterns. Feedback edges express bounded cycles via §8.1 feedback().
+ *
+ * **Tier 1.5.3 Phase 3 (2026-04-27):** `GraphSpec` is a structural alias of
+ * {@link GraphDescribeOutput} with two LLM-author-friendly extras
+ * (`templates?` / `feedback?`). Per-node factory references are encoded in
+ * `meta.factory` + `meta.factoryArgs` (no more `fn` / `source` / `config` /
+ * `initial` fields). State node initial values live in
+ * `meta.factoryArgs.initial` (state self-tags with
+ * `factoryTag("state", { initial })`).
+ *
+ * @module
+ */
+
+/**
+ * A single node declaration in a GraphSpec — structural alias of
+ * {@link DescribeNodeOutput}.
+ *
+ * Per-node factory provenance lives in `meta.factory` + `meta.factoryArgs`
+ * (use {@link factoryTag} to stamp them at construction time). State node
+ * initial values come through `meta.factoryArgs.initial` for tagged states,
+ * with fallback to `value` (since spec projection retains state values).
+ */
+type GraphSpecNode = DescribeNodeOutput;
+/** Template instantiation node — expanded at compile time. */
+type GraphSpecTemplateRef = {
+    type: "template";
+    /** Name of the template to instantiate. */
+    template: string;
+    /** Parameter bindings: template param name → node name. */
+    bind: Record<string, string>;
+};
+/** A reusable subgraph pattern with parameter substitution. */
+type GraphSpecTemplate = {
+    /** Parameter names (prefixed with $ in node refs). */
+    params: string[];
+    /** Node declarations within the template. */
+    nodes: Record<string, GraphSpecNode>;
+    /** Which node's output is the template's output. */
+    output: string;
+};
+/** A feedback edge: bounded cycle from condition to reentry. */
+type GraphSpecFeedbackEdge = {
+    /** Node whose DATA triggers the feedback. */
+    from: string;
+    /** State node that receives the feedback value. */
+    to: string;
+    /** Max iterations before stopping (default: 10). */
+    maxIterations?: number;
+};
+/**
+ * Declarative graph topology for LLM composition (§8.3).
+ *
+ * Tier 1.5.3 Phase 3 (2026-04-27): structural alias of
+ * {@link GraphDescribeOutput} extended with optional `templates` /
+ * `feedback` fields for LLM-author convenience. Top-level `factory` /
+ * `factoryArgs` (Phase 2.5 carry) ride along on every describe output.
+ *
+ * Round-trip property: `decompileSpec(g) === g.describe({ detail: "spec" })`
+ * (modulo the small feedback-edge extraction sugar).
+ */
+type GraphSpec = Omit<GraphDescribeOutput, "nodes" | "expand"> & {
+    /** Node declarations (keyed by node name). Either a structural describe entry or a template ref. */
+    nodes: Record<string, GraphSpecNode | GraphSpecTemplateRef>;
+    /** Reusable subgraph templates (LLM-author extra; not present in `describe()` output). */
+    templates?: Record<string, GraphSpecTemplate>;
+    /** Feedback edges (bounded cycles, LLM-author extra). */
+    feedback?: GraphSpecFeedbackEdge[];
+};
+/**
+ * Factory for creating a derived/effect/operator node from catalog.
+ * Receives resolved dep nodes and the config from the spec.
+ */
+type FnFactory = (deps: Node<unknown>[], config: Record<string, unknown>) => Node<unknown>;
+/**
+ * Factory for creating a producer node from catalog.
+ * Receives the config from the spec.
+ */
+type SourceFactory = (config: Record<string, unknown>) => Node<unknown>;
+/** Simple config field descriptor for LLM prompt generation and validation. */
+type ConfigFieldSchema = {
+    /** Human-readable type: "string", "number", "boolean", "string[]", etc. */
+    type: string;
+    /** Whether this field is required (default: true). */
+    required?: boolean;
+    /** Allowed values (enum constraint). */
+    enum?: readonly (string | number | boolean)[];
+    /** Human-readable description for LLM context. */
+    description?: string;
+    /** Default value if omitted. */
+    default?: unknown;
+};
+/**
+ * Rich catalog entry: bundles a runtime factory with LLM-facing metadata.
+ *
+ * The metadata is used to:
+ * 1. Auto-generate prompt text for {@link llmCompose} (replaces manual `catalogDescription`)
+ * 2. Validate LLM output in {@link validateSpec} (catch wrong fn names, invalid config)
+ * 3. Provide actionable error messages for {@link llmRefine} feedback loops
+ *
+ * Developers register ONE object; the library handles prompt generation and validation.
+ */
+type CatalogFnEntry = {
+    /** Runtime factory. */
+    factory: FnFactory;
+    /** One-line description for LLM prompt (what it does, not how). */
+    description: string;
+    /** Config field schemas. Keys are config field names. */
+    configSchema?: Record<string, ConfigFieldSchema>;
+    /** Example config objects (shown in prompt for complex fns). */
+    examples?: Record<string, unknown>[];
+    /** Category tags for grouping in prompt (e.g., "resilience", "reduction", "ai"). */
+    tags?: string[];
+};
+/** Rich catalog entry for producer sources. */
+type CatalogSourceEntry = {
+    /** Runtime factory. */
+    factory: SourceFactory;
+    /** One-line description for LLM prompt. */
+    description: string;
+    /** Config field schemas. */
+    configSchema?: Record<string, ConfigFieldSchema>;
+    /** Example config objects. */
+    examples?: Record<string, unknown>[];
+    /** Category tags. */
+    tags?: string[];
+};
+/**
+ * Top-level Graph factory — used when a spec was produced from a graph that
+ * called `Graph.prototype.tagFactory(name, args)`. The catalog supplies a
+ * function that takes the recorded `factoryArgs` (JSON-serializable subset)
+ * and returns a fully-wired Graph. Runtime context (LLMAdapter instances,
+ * callbacks, embedders) is captured by the closure — the args themselves are
+ * a documentation fragment, not a complete construction recipe.
+ *
+ * Tier 1.5.3 Phase 2.5 (DG1=B, 2026-04-27).
+ */
+type GraphSpecFactory = (factoryArgs: unknown) => Graph;
+/**
+ * Fn/source lookup table passed to compileSpec and llmCompose.
+ *
+ * Accepts both bare factories (backward-compatible) and rich {@link CatalogFnEntry}
+ * / {@link CatalogSourceEntry} objects. When rich entries are provided, the library
+ * auto-generates LLM prompts and validates LLM output against the catalog.
+ *
+ * `graphFactories` (Tier 1.5.3 Phase 2.5) handles top-level Graph-returning
+ * factories — when `spec.factory` matches a key, `compileSpec` delegates the
+ * entire reconstruction to that factory.
+ */
+type GraphSpecCatalog = {
+    fns?: Record<string, FnFactory | CatalogFnEntry>;
+    sources?: Record<string, SourceFactory | CatalogSourceEntry>;
+    graphFactories?: Record<string, GraphSpecFactory>;
+};
+/** Type guard: is this a rich catalog fn entry (vs bare factory)? */
+declare function isRichFnEntry(entry: FnFactory | CatalogFnEntry): entry is CatalogFnEntry;
+/** Type guard: is this a rich catalog source entry (vs bare factory)? */
+declare function isRichSourceEntry(entry: SourceFactory | CatalogSourceEntry): entry is CatalogSourceEntry;
+/** Extract the runtime factory from a catalog entry (rich or bare). */
+declare function extractFnFactory(entry: FnFactory | CatalogFnEntry): FnFactory;
+/** Extract the runtime factory from a catalog source entry (rich or bare). */
+declare function extractSourceFactory(entry: SourceFactory | CatalogSourceEntry): SourceFactory;
+/**
+ * Auto-generate catalog prompt text from rich catalog entries.
+ *
+ * Groups fns by tag, formats each as `- name: description. Config: { ... }`.
+ * Falls back to listing names only for bare factories.
+ */
+declare function generateCatalogPrompt(catalog: GraphSpecCatalog): string;
+/**
+ * Validate a GraphSpec against a catalog.
+ *
+ * Checks that fn/source names reference actual catalog entries, and validates
+ * config fields against configSchema when rich entries are available.
+ * Returns additional errors beyond structural {@link validateSpec} checks.
+ */
+declare function validateSpecAgainstCatalog(spec: GraphSpec, catalog: GraphSpecCatalog): GraphSpecValidation;
+/** Validation result from {@link validateSpec}. */
+type GraphSpecValidation = {
+    valid: boolean;
+    errors: string[];
+    /**
+     * Non-fatal advisories. Currently includes feedback edges whose `from`
+     * refers to an `effect` node (effects produce no DATA — the feedback
+     * counter will never advance). Always present (empty array when nothing
+     * is flagged) — symmetry with `errors` so callers can read
+     * `result.warnings.length` without a null check.
+     */
+    warnings: string[];
+};
+/**
+ * Validate a GraphSpec JSON object.
+ *
+ * Checks structural validity: required fields, node types, dep references,
+ * template references, feedback edge targets, self-cycles, and bind completeness.
+ *
+ * **Effect-node feedback advisory (C24-3).** When a feedback edge's `from`
+ * refers to an `effect` node, the validator flags it via `warnings` (not
+ * `errors`) — effect nodes produce no DATA emission, so a feedback counter
+ * targeting one will never advance. The spec compiles either way; the
+ * advisory exists because the misconfiguration is silent at runtime
+ * (counter at 0 forever) without it.
+ */
+declare function validateSpec(spec: unknown): GraphSpecValidation;
+/**
+ * The change-set fed to {@link validateOwnership}. Mirrors the minimal slice
+ * of a PR diff the lint needs: the set of factory identifiers whose
+ * implementation the diff touches, plus the PR author and (optionally) the
+ * raw commit-message text so the `Override-Owner:` trailer can be detected.
+ *
+ * **Why factory-keyed (not path-keyed) — locked decision (DS-14.5.A Q5
+ * sub-flag).** PR-diff → spec-node mapping resolves through `meta.factory`
+ * provenance, NOT a `meta.ownerPath` glob. A diff that edits the
+ * implementation of factory `"rateLimiter"` maps to *every* spec node whose
+ * `meta.factory === "rateLimiter"`. This reuses the existing
+ * `factoryTag` / `decompileSpec` round-trip (the same `meta.factory` field
+ * `compileSpec` consumes) — no parallel ownership-path indexing scheme.
+ */
+type OwnershipPrDiff = {
+    /**
+     * Factory identifiers (the `meta.factory` value) whose source the PR
+     * modifies. A spec node is "edited by this PR" iff its `meta.factory` is
+     * in this set. Nodes without `meta.factory` cannot be mapped from a code
+     * diff and are therefore never flagged (silent — consistent with the
+     * un-annotated rule).
+     */
+    readonly editedFactories: readonly string[];
+    /** PR author's `Actor.id`. Compared against each edited node's `meta.owner`. */
+    readonly author: string;
+    /**
+     * Raw commit message(s) text. If any line is an `Override-Owner: <reason>`
+     * trailer (case-insensitive key, non-empty reason) the lint hard-fail is
+     * bypassed and recorded as an audit-trail override (Q5 sub-lock i — any
+     * committer may use it; it is recorded, never silently granted).
+     */
+    readonly commitMessage?: string;
+};
+/** One cross-owner violation surfaced by {@link validateOwnership}. */
+type OwnershipViolation = {
+    /** Spec node path that carries `meta.owner` and was edited by a non-owner. */
+    readonly node: string;
+    /** The `meta.owner` value on that node. */
+    readonly owner: string;
+    /** The PR author who edited it. */
+    readonly author: string;
+    /** The `meta.factory` that mapped the diff onto this node. */
+    readonly factory: string;
+};
+/** Result of {@link validateOwnership}. */
+type OwnershipValidation = {
+    /**
+     * `true` when no hard-fail applies — either no cross-owner edit, or every
+     * cross-owner edit is bypassed by a valid `Override-Owner:` trailer.
+     */
+    readonly ok: boolean;
+    /** Cross-owner edits that hard-fail (empty when `ok`). */
+    readonly violations: readonly OwnershipViolation[];
+    /**
+     * Cross-owner edits that WOULD have failed but were bypassed by an
+     * `Override-Owner:` commit trailer. Pure audit trail — CI / reviewers
+     * grep this to surface override abuse. Present (possibly empty) so callers
+     * can read `.overridden.length` without a null check.
+     */
+    readonly overridden: readonly OwnershipViolation[];
+    /**
+     * The override reason parsed from the `Override-Owner:` trailer, when one
+     * was present and applied. `undefined` when no trailer was used.
+     */
+    readonly overrideReason?: string;
+};
+/**
+ * Multi-agent subgraph ownership PR lint (DS-14.5.A delta #5, L0 rung;
+ * spec §2.3a INV-OWNER-2).
+ *
+ * Hard-fails a pull request whose code diff edits a spec node carrying
+ * `meta.owner` when the PR author is not that owner. Nodes **without**
+ * `meta.owner` are silent (no advisory, no failure) — "shared infrastructure"
+ * is exactly the un-annotated case; no separate allow-list is maintained.
+ *
+ * **Rules (Q5 lock):**
+ * - Edited node has no `meta.owner` → silent.
+ * - Edited node has `meta.owner` AND `author === meta.owner` → OK.
+ * - Edited node has `meta.owner` AND `author !== meta.owner` → **violation**
+ *   (hard-fail) unless an `Override-Owner: <reason>` commit trailer is present,
+ *   in which case the violation is moved to `overridden` (audit trail) and
+ *   `ok` stays `true`.
+ *
+ * **PR-diff → spec-node mapping (Q5 sub-flag lock):** `meta.factory`
+ * resolution. A node is "edited" iff its `meta.factory` appears in
+ * `prDiff.editedFactories`. This reuses the `factoryTag` / `decompileSpec`
+ * round-trip rather than introducing a `meta.ownerPath` glob. Nodes without
+ * `meta.factory` can't be mapped from a code diff and are never flagged.
+ *
+ * Pure function — no `Node` / `Graph` returned, no side effects. Designed to
+ * be called from a `graphrefly check-spec`-adjacent CI step (delta #6, Phase
+ * 16) or any host PR gate.
+ *
+ * @param spec - The committed GraphSpec (or any `describe({ detail: "spec" })`
+ *   projection / structural superset).
+ * @param prDiff - The factory-keyed diff slice + author + commit text.
+ */
+declare function validateOwnership(spec: unknown, prDiff: OwnershipPrDiff): OwnershipValidation;
+/** Options for {@link compileSpec}. */
+type CompileSpecOptions = {
+    /** Fn/source catalog for resolving named factories. */
+    catalog?: GraphSpecCatalog;
+    /**
+     * How to handle nodes whose `fn` / `source` is missing from the catalog.
+     * - `"placeholder"` (default): silently substitute identity passthroughs
+     *   (`node([], () => {})` / `node(deps, (bd, a, ctx) => a.emit(bd[0]?.at(-1)))`). Backward-
+     *   compatible — preserves the historical "soft compile" behavior.
+     * - `"warn"`: substitute placeholders AND log each missing entry via
+     *   `console.warn`, or via the `onWarn` callback if supplied.
+     * - `"error"`: collect every missing entry across the whole spec, then
+     *   throw an `Error` listing them all (no partial graph returned).
+     */
+    onMissing?: "error" | "warn" | "placeholder";
+    /** Custom warning sink. Used only when `onMissing === "warn"`. Defaults to `console.warn`. */
+    onWarn?: (message: string) => void;
+};
+/**
+ * Instantiate a Graph from a GraphSpec.
+ *
+ * Handles template expansion (mounted subgraphs), feedback wiring via §8.1
+ * feedback(), node factory lookup from the catalog, and topology validation.
+ *
+ * @param spec - Declarative graph topology.
+ * @param opts - Catalog and compile options.
+ * @returns A running Graph.
+ * @throws On validation failure, missing catalog entries, or unresolvable deps.
+ *
+ * @category patterns
+ */
+declare function compileSpec(spec: GraphSpec, opts?: CompileSpecOptions): Graph;
+/**
+ * Extract a {@link GraphSpec} from a running graph.
+ *
+ * Tier 1.5.3 Phase 3 (2026-04-27): thin projection over
+ * `graph.describe({ detail: "spec" })`. The describe-output already carries
+ * structural fields (`type`, `deps`, optional `value`) plus per-node
+ * `meta.factory` / `meta.factoryArgs` for tagged factories and top-level
+ * `factory` / `factoryArgs` for graph-level tags. The only sugar this helper
+ * adds is a feedback-edge recovery scan over `meta.feedbackFrom` /
+ * `meta.feedbackTo` companion fields stamped by the §8.1 `feedback()`
+ * primitive.
+ *
+ * **Removed in Phase 3:** template fingerprinting / `_templateName` /
+ * `_templateBind` recovery. Mounted subgraphs surface as nested `subname::*`
+ * paths in `desc.nodes`; if you need the template-instantiation form, build
+ * the spec by hand or read the meta companions directly.
+ *
+ * @param graph - Running graph to decompile.
+ * @returns A GraphSpec representation.
+ *
+ * @category patterns
+ */
+declare function decompileSpec(graph: Graph): GraphSpec;
+/** A single change in a spec diff. */
+type SpecDiffEntry = {
+    type: "added" | "removed" | "changed";
+    path: string;
+    detail?: string;
+};
+/** Structural diff between two GraphSpecs. */
+type SpecDiffResult = {
+    entries: SpecDiffEntry[];
+    summary: string;
+};
+/**
+ * Compute a structural diff between two GraphSpecs.
+ *
+ * Template-aware: reports "changed template definition" vs "changed
+ * instantiation bindings." No runtime needed — pure JSON comparison.
+ *
+ * @param specA - The "before" spec.
+ * @param specB - The "after" spec.
+ * @returns Diff entries and a human-readable summary.
+ *
+ * @category patterns
+ */
+declare function specDiff(specA: GraphSpec, specB: GraphSpec): SpecDiffResult;
+/** Options for {@link llmCompose}. */
+type LLMComposeOptions = {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Extra instructions appended to the system prompt. */
+    systemPromptExtra?: string;
+    /**
+     * Available fn/source catalog names for the LLM to reference.
+     * When omitted and `catalog` contains rich {@link CatalogFnEntry} entries,
+     * the prompt is auto-generated via {@link generateCatalogPrompt}.
+     */
+    catalogDescription?: string;
+    /**
+     * Catalog for auto-prompt generation and catalog-aware validation.
+     * When rich entries are provided, the catalog prompt is auto-generated
+     * and LLM output is validated against fn/source names and config schemas.
+     */
+    catalog?: GraphSpecCatalog;
+    /**
+     * Max auto-refine attempts when the LLM output fails catalog validation.
+     * Each attempt feeds the validation errors back to the LLM via llmRefine.
+     * Default: 0 (no auto-refine). Set to 2-3 for production use.
+     */
+    maxAutoRefine?: number;
+};
+/**
+ * Ask an LLM to compose a GraphSpec from a natural-language problem description.
+ *
+ * The LLM generates a GraphSpec (with templates + feedback), validated before
+ * returning. The spec is for human review before compilation via compileSpec().
+ *
+ * @param problem - Natural language problem description.
+ * @param adapter - LLM adapter for the generation call.
+ * @param opts - Model options and catalog description.
+ * @returns A validated GraphSpec.
+ * @throws On invalid LLM output or validation failure.
+ *
+ * @category patterns
+ */
+declare function llmCompose(problem: string, adapter: LLMAdapter, opts?: LLMComposeOptions): Promise<GraphSpec>;
+/** Options for {@link llmRefine}. */
+type LLMRefineOptions = LLMComposeOptions;
+/**
+ * Ask an LLM to modify an existing GraphSpec based on feedback or changed requirements.
+ *
+ * @param currentSpec - The current GraphSpec to modify.
+ * @param feedback - Natural language feedback or changed requirements.
+ * @param adapter - LLM adapter for the generation call.
+ * @param opts - Model options.
+ * @returns A new GraphSpec incorporating the feedback.
+ * @throws On invalid LLM output or validation failure.
+ *
+ * @category patterns
+ */
+declare function llmRefine(currentSpec: GraphSpec, feedback: string, adapter: LLMAdapter, opts?: LLMRefineOptions): Promise<GraphSpec>;
+
+export { type CatalogFnEntry, type CatalogSourceEntry, type CompileSpecOptions, type ConfigFieldSchema, type FnFactory, type GraphSpec, type GraphSpecCatalog, type GraphSpecFactory, type GraphSpecFeedbackEdge, type GraphSpecNode, type GraphSpecTemplate, type GraphSpecTemplateRef, type GraphSpecValidation, type LLMComposeOptions, type LLMRefineOptions, type OwnershipPrDiff, type OwnershipValidation, type OwnershipViolation, type SourceFactory, type SpecDiffEntry, type SpecDiffResult, compileSpec, decompileSpec, extractFnFactory, extractSourceFactory, generateCatalogPrompt, isRichFnEntry, isRichSourceEntry, llmCompose, llmRefine, specDiff, validateOwnership, validateSpec, validateSpecAgainstCatalog };