@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/index-D9HKAH_-.d.cts

@@ -0,0 +1,231 @@
+import { a as Node } from './node-Dd6wHSib.cjs';
+import { a as GraphOptions, G as Graph } from './graph-DgohqXK-.cjs';
+
+/**
+ * Domain templates (roadmap §8.2).
+ *
+ * Opinionated Graph factories for common "info → action" domains.
+ * Each template wires up §8.1 reduction primitives (stratify, funnel, feedback,
+ * budgetGate, scorer) with domain-specific stages. Users fork/extend by
+ * accessing named nodes and swapping stages.
+ *
+ * **Source injection (option B):** templates accept a `source` node, not a
+ * hardcoded adapter. Pass `fromOTel(...)`, `fromGitHook(...)`, or a test
+ * `state()` — the topology is the same.
+ *
+ * @module
+ */
+
+/** Stratification branch config for observability signals. */
+type ObservabilityBranch = {
+    name: string;
+    classify: (value: unknown) => boolean;
+};
+/** Options for {@link observabilityGraph}. */
+type ObservabilityGraphOptions = GraphOptions & {
+    /** Ingested signal source (e.g. fromOTel(...) or test state). */
+    source: Node<unknown>;
+    /**
+     * Classification rules for signal stratification.
+     * Default: errors / traces / metrics branches.
+     */
+    branches?: ObservabilityBranch[];
+    /**
+     * Correlation function: receives stratified branch values and produces
+     * correlated insights. Default: identity pass-through.
+     */
+    correlate?: (values: unknown[]) => unknown;
+    /**
+     * SLO verification function: returns a verification result for a
+     * correlated insight. Default: always passes.
+     */
+    sloCheck?: (value: unknown) => unknown;
+    /**
+     * Scorer weights for alert prioritization. One per branch.
+     * Default: equal weights [1, 1, 1].
+     */
+    weights?: number[];
+    /** Max feedback iterations for false-positive learning. Default: 5. */
+    maxFeedbackIterations?: number;
+};
+/**
+ * OTel ingest → stratified reduction → correlation → SLO verification →
+ * alert prioritization → output.
+ *
+ * Well-known node names:
+ * - `"source"` — injected signal source
+ * - `"stratify::branch/<name>"` — per-branch classification
+ * - `"correlate"` — cross-branch correlation
+ * - `"slo_value"`, `"slo_verified"` — SLO verification pair
+ * - `"alerts"` — scored, prioritized output
+ * - `"output"` — final output (alias for alerts)
+ *
+ * @category patterns
+ */
+declare function observabilityGraph(name: string, opts: ObservabilityGraphOptions): Graph;
+/** A structured issue extracted from raw findings. */
+type ExtractedIssue = {
+    id: string;
+    title: string;
+    severity: number;
+    source: string;
+    raw: unknown;
+};
+/** Options for {@link issueTrackerGraph}. */
+type IssueTrackerGraphOptions = GraphOptions & {
+    /** Findings source (e.g. fromGitHook(...), fromFSWatch(...)). */
+    source: Node<unknown>;
+    /**
+     * Extract structured issues from raw findings.
+     * Default: wraps raw value as a single issue.
+     */
+    extract?: (raw: unknown) => ExtractedIssue;
+    /**
+     * Verify an extracted issue (assertion check).
+     * Default: always valid.
+     */
+    verify?: (issue: ExtractedIssue) => unknown;
+    /**
+     * Detect regression by comparing against known patterns.
+     * Receives (current issue, known patterns).
+     * Default: no regression detected.
+     */
+    detectRegression?: (issue: ExtractedIssue, known: unknown) => unknown;
+    /** Max feedback iterations for re-scanning. Default: 3. */
+    maxFeedbackIterations?: number;
+};
+/**
+ * Findings ingest → extraction → verification → regression detection →
+ * distillation → prioritized queue.
+ *
+ * Well-known node names:
+ * - `"source"` — injected findings source
+ * - `"extract"` — structured issue extraction
+ * - `"verify"` — issue verification
+ * - `"known_patterns"` — accumulated known issue patterns (state)
+ * - `"regression"` — regression detection
+ * - `"priority"` — severity-based prioritization
+ * - `"output"` — final prioritized output
+ *
+ * @category patterns
+ */
+declare function issueTrackerGraph(name: string, opts: IssueTrackerGraphOptions): Graph;
+/** Classification result from LLM moderation. */
+type ModerationResult = {
+    label: "safe" | "review" | "block";
+    confidence: number;
+    reason?: string;
+    original: unknown;
+};
+/** Options for {@link contentModerationGraph}. */
+type ContentModerationGraphOptions = GraphOptions & {
+    /** Content source (text/multimedia ingest). */
+    source: Node<unknown>;
+    /**
+     * Classification function: returns a ModerationResult.
+     * Default: labels everything "review" with confidence 0.5.
+     */
+    classify?: (content: unknown) => ModerationResult;
+    /** System prompt for LLM classification. */
+    systemPrompt?: string;
+    /** Scorer weights: [safe, review, block]. Default: [0.1, 1, 2]. */
+    weights?: [number, number, number];
+    /** Max feedback iterations for policy refinement. Default: 5. */
+    maxFeedbackIterations?: number;
+    /** Max review queue size. When set, oldest entries are trimmed on overflow. */
+    maxQueueSize?: number;
+};
+/**
+ * Content ingest → LLM/rule classification → stratified routing (safe/review/block) →
+ * human review queue → scorer → feedback (false positives → policy refinement) → output.
+ *
+ * Well-known node names:
+ * - `"source"` — content ingest
+ * - `"classify"` — LLM or rule-based classification
+ * - `"stratify::branch/safe"`, `"stratify::branch/review"`, `"stratify::branch/block"` — routed branches
+ * - `"review_queue"` — state node for human review items
+ * - `"priority"` — scored priority output
+ * - `"policy"` — writable state for policy refinement
+ * - `"output"` — final moderation output
+ *
+ * @category patterns
+ */
+declare function contentModerationGraph(name: string, opts: ContentModerationGraphOptions): Graph;
+/** Schema validation result. */
+type ValidationResult = {
+    valid: boolean;
+    errors: string[];
+    record: unknown;
+};
+/** Anomaly detection result. */
+type AnomalyResult = {
+    anomaly: boolean;
+    score: number;
+    detail?: string;
+    record: unknown;
+};
+/** Options for {@link dataQualityGraph}. */
+type DataQualityGraphOptions = GraphOptions & {
+    /** Data source (e.g. fromPrisma(...), fromKysely(...)). */
+    source: Node<unknown>;
+    /**
+     * Schema validation function.
+     * Default: always valid.
+     */
+    validate?: (record: unknown) => ValidationResult;
+    /**
+     * Anomaly detection function.
+     * Default: no anomaly.
+     */
+    detectAnomaly?: (record: unknown) => AnomalyResult;
+    /**
+     * Drift detection: compares current record against baseline.
+     * Default: no drift.
+     */
+    detectDrift?: (record: unknown, baseline: unknown) => unknown;
+    /**
+     * Remediation suggestion function.
+     * Default: no suggestion.
+     */
+    suggest?: (result: {
+        validation: ValidationResult;
+        anomaly: AnomalyResult;
+    }) => unknown;
+    /** Max feedback iterations for rule refinement. Default: 3. */
+    maxFeedbackIterations?: number;
+};
+/**
+ * Data ingest → schema validation → anomaly detection → drift alerting →
+ * auto-remediation suggestions → output.
+ *
+ * Well-known node names:
+ * - `"source"` — data ingest
+ * - `"validate"` — schema validation
+ * - `"anomaly"` — anomaly detection
+ * - `"baseline"` — rolling baseline state
+ * - `"drift"` — drift detection
+ * - `"remediate"` — auto-remediation suggestions
+ * - `"output"` — combined quality report
+ *
+ * @category patterns
+ */
+declare function dataQualityGraph(name: string, opts: DataQualityGraphOptions): Graph;
+
+type index_AnomalyResult = AnomalyResult;
+type index_ContentModerationGraphOptions = ContentModerationGraphOptions;
+type index_DataQualityGraphOptions = DataQualityGraphOptions;
+type index_ExtractedIssue = ExtractedIssue;
+type index_IssueTrackerGraphOptions = IssueTrackerGraphOptions;
+type index_ModerationResult = ModerationResult;
+type index_ObservabilityBranch = ObservabilityBranch;
+type index_ObservabilityGraphOptions = ObservabilityGraphOptions;
+type index_ValidationResult = ValidationResult;
+declare const index_contentModerationGraph: typeof contentModerationGraph;
+declare const index_dataQualityGraph: typeof dataQualityGraph;
+declare const index_issueTrackerGraph: typeof issueTrackerGraph;
+declare const index_observabilityGraph: typeof observabilityGraph;
+declare namespace index {
+  export { type index_AnomalyResult as AnomalyResult, type index_ContentModerationGraphOptions as ContentModerationGraphOptions, type index_DataQualityGraphOptions as DataQualityGraphOptions, type index_ExtractedIssue as ExtractedIssue, type index_IssueTrackerGraphOptions as IssueTrackerGraphOptions, type index_ModerationResult as ModerationResult, type index_ObservabilityBranch as ObservabilityBranch, type index_ObservabilityGraphOptions as ObservabilityGraphOptions, type index_ValidationResult as ValidationResult, index_contentModerationGraph as contentModerationGraph, index_dataQualityGraph as dataQualityGraph, index_issueTrackerGraph as issueTrackerGraph, index_observabilityGraph as observabilityGraph };
+}
+
+export { type AnomalyResult as A, type ContentModerationGraphOptions as C, type DataQualityGraphOptions as D, type ExtractedIssue as E, type IssueTrackerGraphOptions as I, type ModerationResult as M, type ObservabilityBranch as O, type ValidationResult as V, type ObservabilityGraphOptions as a, issueTrackerGraph as b, contentModerationGraph as c, dataQualityGraph as d, index as i, observabilityGraph as o };

package/dist/index-DBe_8XW5.d.cts

@@ -0,0 +1,143 @@
+import { a as Node, N as NodeOptions, c as NodeActions } from './node-Dd6wHSib.cjs';
+import { D as DerivedFn } from './sugar-DHttV0LX.cjs';
+import { G as Graph, a as GraphOptions } from './graph-DgohqXK-.cjs';
+
+/**
+ * Orchestration patterns (roadmap §4.1).
+ *
+ * Domain-layer helpers that build workflow shapes on top of core + extra primitives.
+ * Exported under the `patterns.orchestration` namespace to avoid collisions with
+ * Phase 2 operator names (for example `gate`, `forEach`).
+ */
+
+type StepRef = string | Node<unknown>;
+type OrchestrationMeta = {
+    orchestration?: true;
+    orchestration_type?: string;
+};
+type OrchestrationStepOptions = Omit<NodeOptions<unknown>, "describeKind" | "name" | "meta"> & {
+    deps?: ReadonlyArray<StepRef>;
+    meta?: Record<string, unknown> & OrchestrationMeta;
+};
+type BranchResult<T> = {
+    branch: "then" | "else";
+    value: T;
+};
+type SensorControls<T> = {
+    node: Node<T>;
+    push(value: T): void;
+    error(err: unknown): void;
+    complete(): void;
+};
+type LoopOptions = Omit<OrchestrationStepOptions, "deps"> & {
+    iterations?: number | StepRef;
+};
+type SubPipelineBuilder = (sub: Graph) => void;
+/**
+ * Creates an orchestration graph container.
+ */
+declare function pipeline(name: string, opts?: GraphOptions): Graph;
+/**
+ * Registers a workflow task node.
+ */
+declare function task<T>(graph: Graph, name: string, run: DerivedFn<T>, opts?: OrchestrationStepOptions): Node<T>;
+/**
+ * Emits tagged branch outcomes (`then` / `else`) for each source value.
+ */
+declare function branch<T>(graph: Graph, name: string, source: StepRef, predicate: (value: T) => boolean, opts?: Omit<OrchestrationStepOptions, "deps">): Node<BranchResult<T>>;
+type ApprovalOptions = Omit<OrchestrationStepOptions, "deps"> & {
+    isApproved?: (value: unknown) => boolean;
+};
+/**
+ * Human/LLM approval gate over a source value.
+ */
+declare function approval<T>(graph: Graph, name: string, source: StepRef, approver: StepRef, opts?: ApprovalOptions): Node<T>;
+interface GateOptions {
+    /** Maximum queue size. Oldest values are FIFO-dropped when exceeded. Default: Infinity. */
+    maxPending?: number;
+    /** Start in open mode (auto-approve). Default: false. */
+    startOpen?: boolean;
+    meta?: Record<string, unknown>;
+}
+/** Control surface returned by {@link gate}. */
+interface GateController<T> {
+    /** The output node registered in the graph (subscribe to receive approved values). */
+    node: Node<T>;
+    /** Reactive queue of values waiting for approval. */
+    pending: Node<T[]>;
+    /** Derived count of pending items. */
+    count: Node<number>;
+    /** Whether the gate is currently open (auto-approving). */
+    isOpen: Node<boolean>;
+    /** Approve and forward the next `count` pending values (default: 1). */
+    approve(count?: number): void;
+    /** Reject (discard) the next `count` pending values (default: 1). */
+    reject(count?: number): void;
+    /**
+     * Transform and forward `count` pending values (default: 1).
+     * `fn` receives `(value, index, pending)` — Array.map-style.
+     */
+    modify(fn: (value: T, index: number, pending: readonly T[]) => T, count?: number): void;
+    /** Flush all pending values and auto-approve future values. */
+    open(): void;
+    /** Re-enable manual gating (stop auto-approving). */
+    close(): void;
+}
+/**
+ * Human-in-the-loop gate: queues incoming values from `source` and lets an external
+ * controller {@link GateController.approve approve}, {@link GateController.reject reject},
+ * or {@link GateController.modify modify} them before forwarding downstream.
+ *
+ * Observable surfaces (`pending`, `count`, `isOpen`) are reactive nodes registered in
+ * the graph. The gate output node is also registered.
+ */
+declare function gate<T>(graph: Graph, name: string, source: StepRef, opts?: GateOptions): GateController<T>;
+/**
+ * Registers a join step that emits a tuple of latest dependency values.
+ */
+declare function join<T extends readonly unknown[]>(graph: Graph, name: string, deps: {
+    [K in keyof T]: StepRef;
+}, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+/**
+ * Registers a loop step that applies `iterate` to each source value N times.
+ */
+declare function loop<T>(graph: Graph, name: string, source: StepRef, iterate: (value: T, iteration: number, actions: NodeActions) => T, opts?: LoopOptions): Node<T>;
+/**
+ * Mounts and returns a child workflow graph.
+ */
+declare function subPipeline(graph: Graph, name: string, childOrBuild?: Graph | SubPipelineBuilder, opts?: GraphOptions): Graph;
+/**
+ * Registers a producer-style sensor source and returns imperative controls.
+ */
+declare function sensor<T>(graph: Graph, name: string, initial?: T, opts?: Omit<NodeOptions<unknown>, "name" | "describeKind" | "meta"> & {
+    meta?: Record<string, unknown>;
+}): SensorControls<T>;
+/**
+ * Registers an error-recovery step for a source.
+ */
+declare function onFailure<T>(graph: Graph, name: string, source: StepRef, recover: (err: unknown, actions: NodeActions) => T, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+
+type index_ApprovalOptions = ApprovalOptions;
+type index_BranchResult<T> = BranchResult<T>;
+type index_GateController<T> = GateController<T>;
+type index_GateOptions = GateOptions;
+type index_LoopOptions = LoopOptions;
+type index_OrchestrationStepOptions = OrchestrationStepOptions;
+type index_SensorControls<T> = SensorControls<T>;
+type index_StepRef = StepRef;
+type index_SubPipelineBuilder = SubPipelineBuilder;
+declare const index_approval: typeof approval;
+declare const index_branch: typeof branch;
+declare const index_gate: typeof gate;
+declare const index_join: typeof join;
+declare const index_loop: typeof loop;
+declare const index_onFailure: typeof onFailure;
+declare const index_pipeline: typeof pipeline;
+declare const index_sensor: typeof sensor;
+declare const index_subPipeline: typeof subPipeline;
+declare const index_task: typeof task;
+declare namespace index {
+  export { type index_ApprovalOptions as ApprovalOptions, type index_BranchResult as BranchResult, type index_GateController as GateController, type index_GateOptions as GateOptions, type index_LoopOptions as LoopOptions, type index_OrchestrationStepOptions as OrchestrationStepOptions, type index_SensorControls as SensorControls, type index_StepRef as StepRef, type index_SubPipelineBuilder as SubPipelineBuilder, index_approval as approval, index_branch as branch, index_gate as gate, index_join as join, index_loop as loop, index_onFailure as onFailure, index_pipeline as pipeline, index_sensor as sensor, index_subPipeline as subPipeline, index_task as task };
+}
+
+export { type ApprovalOptions as A, type BranchResult as B, type GateController as G, type LoopOptions as L, type OrchestrationStepOptions as O, type SensorControls as S, type GateOptions as a, type StepRef as b, type SubPipelineBuilder as c, approval as d, branch as e, subPipeline as f, gate as g, index as i, join as j, loop as l, onFailure as o, pipeline as p, sensor as s, task as t };

package/dist/{memory-C6Z2tGpC.d.cts → index-DCeTyFlB.d.ts}

@@ -1,5 +1,5 @@
-import { N as Node } from './node-BmerH3kS.cjs';
-import { a as Graph } from './graph-DNCrvZSn.cjs';
+import { a as Node } from './node-Dd6wHSib.js';
+import { G as Graph } from './graph-Qjg9gWHI.js';
 
 /**
  * Memory patterns (roadmap §4.3).
@@ -111,29 +111,29 @@ declare function collection<T>(name: string, opts?: CollectionOptions<T>): Colle
 declare function vectorIndex<TMeta>(opts?: VectorIndexOptions<TMeta>): VectorIndexBundle<TMeta>;
 declare function knowledgeGraph<TEntity, TRelation extends string = string>(name: string): KnowledgeGraphGraph<TEntity, TRelation>;
 
-type memory_CollectionEntry<T> = CollectionEntry<T>;
-type memory_CollectionGraph<T> = CollectionGraph<T>;
-type memory_CollectionOptions<T> = CollectionOptions<T>;
-type memory_CollectionPolicy = CollectionPolicy;
-type memory_HnswAdapter<TMeta> = HnswAdapter<TMeta>;
-type memory_KnowledgeEdge<TRelation extends string = string> = KnowledgeEdge<TRelation>;
-type memory_KnowledgeGraphGraph<TEntity, TRelation extends string = string> = KnowledgeGraphGraph<TEntity, TRelation>;
-type memory_LightCollectionBundle<T> = LightCollectionBundle<T>;
-type memory_LightCollectionEntry<T> = LightCollectionEntry<T>;
-type memory_LightCollectionOptions = LightCollectionOptions;
-type memory_RankedCollectionEntry<T> = RankedCollectionEntry<T>;
-type memory_VectorBackend = VectorBackend;
-type memory_VectorIndexBundle<TMeta> = VectorIndexBundle<TMeta>;
-type memory_VectorIndexOptions<TMeta> = VectorIndexOptions<TMeta>;
-type memory_VectorRecord<TMeta> = VectorRecord<TMeta>;
-type memory_VectorSearchResult<TMeta> = VectorSearchResult<TMeta>;
-declare const memory_collection: typeof collection;
-declare const memory_decay: typeof decay;
-declare const memory_knowledgeGraph: typeof knowledgeGraph;
-declare const memory_lightCollection: typeof lightCollection;
-declare const memory_vectorIndex: typeof vectorIndex;
-declare namespace memory {
-  export { type memory_CollectionEntry as CollectionEntry, type memory_CollectionGraph as CollectionGraph, type memory_CollectionOptions as CollectionOptions, type memory_CollectionPolicy as CollectionPolicy, type memory_HnswAdapter as HnswAdapter, type memory_KnowledgeEdge as KnowledgeEdge, type memory_KnowledgeGraphGraph as KnowledgeGraphGraph, type memory_LightCollectionBundle as LightCollectionBundle, type memory_LightCollectionEntry as LightCollectionEntry, type memory_LightCollectionOptions as LightCollectionOptions, type memory_RankedCollectionEntry as RankedCollectionEntry, type memory_VectorBackend as VectorBackend, type memory_VectorIndexBundle as VectorIndexBundle, type memory_VectorIndexOptions as VectorIndexOptions, type memory_VectorRecord as VectorRecord, type memory_VectorSearchResult as VectorSearchResult, memory_collection as collection, memory_decay as decay, memory_knowledgeGraph as knowledgeGraph, memory_lightCollection as lightCollection, memory_vectorIndex as vectorIndex };
+type index_CollectionEntry<T> = CollectionEntry<T>;
+type index_CollectionGraph<T> = CollectionGraph<T>;
+type index_CollectionOptions<T> = CollectionOptions<T>;
+type index_CollectionPolicy = CollectionPolicy;
+type index_HnswAdapter<TMeta> = HnswAdapter<TMeta>;
+type index_KnowledgeEdge<TRelation extends string = string> = KnowledgeEdge<TRelation>;
+type index_KnowledgeGraphGraph<TEntity, TRelation extends string = string> = KnowledgeGraphGraph<TEntity, TRelation>;
+type index_LightCollectionBundle<T> = LightCollectionBundle<T>;
+type index_LightCollectionEntry<T> = LightCollectionEntry<T>;
+type index_LightCollectionOptions = LightCollectionOptions;
+type index_RankedCollectionEntry<T> = RankedCollectionEntry<T>;
+type index_VectorBackend = VectorBackend;
+type index_VectorIndexBundle<TMeta> = VectorIndexBundle<TMeta>;
+type index_VectorIndexOptions<TMeta> = VectorIndexOptions<TMeta>;
+type index_VectorRecord<TMeta> = VectorRecord<TMeta>;
+type index_VectorSearchResult<TMeta> = VectorSearchResult<TMeta>;
+declare const index_collection: typeof collection;
+declare const index_decay: typeof decay;
+declare const index_knowledgeGraph: typeof knowledgeGraph;
+declare const index_lightCollection: typeof lightCollection;
+declare const index_vectorIndex: typeof vectorIndex;
+declare namespace index {
+  export { type index_CollectionEntry as CollectionEntry, type index_CollectionGraph as CollectionGraph, type index_CollectionOptions as CollectionOptions, type index_CollectionPolicy as CollectionPolicy, type index_HnswAdapter as HnswAdapter, type index_KnowledgeEdge as KnowledgeEdge, type index_KnowledgeGraphGraph as KnowledgeGraphGraph, type index_LightCollectionBundle as LightCollectionBundle, type index_LightCollectionEntry as LightCollectionEntry, type index_LightCollectionOptions as LightCollectionOptions, type index_RankedCollectionEntry as RankedCollectionEntry, type index_VectorBackend as VectorBackend, type index_VectorIndexBundle as VectorIndexBundle, type index_VectorIndexOptions as VectorIndexOptions, type index_VectorRecord as VectorRecord, type index_VectorSearchResult as VectorSearchResult, index_collection as collection, index_decay as decay, index_knowledgeGraph as knowledgeGraph, index_lightCollection as lightCollection, index_vectorIndex as vectorIndex };
 }
 
-export { type CollectionEntry as C, type HnswAdapter as H, type KnowledgeGraphGraph as K, type LightCollectionBundle as L, type RankedCollectionEntry as R, type VectorIndexBundle as V, type VectorSearchResult as a, type CollectionGraph as b, type CollectionOptions as c, type CollectionPolicy as d, type KnowledgeEdge as e, type LightCollectionEntry as f, type LightCollectionOptions as g, type VectorBackend as h, type VectorIndexOptions as i, type VectorRecord as j, collection as k, decay as l, memory as m, knowledgeGraph as n, lightCollection as o, vectorIndex as v };
+export { type CollectionEntry as C, type HnswAdapter as H, type KnowledgeGraphGraph as K, type LightCollectionBundle as L, type RankedCollectionEntry as R, type VectorSearchResult as V, type VectorIndexBundle as a, type CollectionGraph as b, type CollectionOptions as c, type CollectionPolicy as d, type KnowledgeEdge as e, type LightCollectionEntry as f, type LightCollectionOptions as g, type VectorBackend as h, index as i, type VectorIndexOptions as j, type VectorRecord as k, collection as l, decay as m, knowledgeGraph as n, lightCollection as o, vectorIndex as v };