@graphrefly/graphrefly 0.37.0 → 0.39.0

package/dist/{index-DcWbx58m.d.cts → index-DoYc8BWK.d.cts}

@@ -1,6 +1,6 @@
-import { A as Actor, a as Node, P as PolicyRuleData, G as GuardAction } from './node-fSc-hCv8.cjs';
-import { G as Graph, a as GraphOptions, b as GraphPersistSnapshot, C as CausalChain } from './graph-CaNXUc3c.cjs';
-import { T as TopicGraph } from './index-DAKm44My.cjs';
+import { A as Actor, N as Node, P as PolicyRuleData, G as GuardAction } from './node-BYInONRr.cjs';
+import { G as Graph, a as GraphOptions, c as GraphPersistSnapshot } from './graph-BUwMAxJI.cjs';
+import { T as TopicGraph } from './index-BndG0cpK.cjs';
 
 /**
  * Audit, policy enforcement, and compliance export (roadmap §9.2).
@@ -10,9 +10,10 @@ import { T as TopicGraph } from './index-DAKm44My.cjs';
  *
  * - {@link auditTrail} — reactive mutation log with by-node/by-actor/by-time
  *   queries.
- * - {@link policyEnforcer} — reactive ABAC enforcement; in `"audit"` mode
- *   records would-be denials, in `"enforce"` mode pushes guards onto target
- *   nodes so subsequent writes throw {@link GuardDenied}.
+ * - {@link policyGate} — reactive ABAC gate (Tier 2.3 rename of
+ *   `policyEnforcer`); in `"audit"` mode records would-be denials, in
+ *   `"enforce"` mode pushes guards onto target nodes so subsequent writes
+ *   throw {@link GuardDenied}.
  * - {@link complianceSnapshot} — point-in-time export of graph state +
  *   audit trail + policies for regulatory archival.
  *
@@ -88,7 +89,7 @@ declare class AuditTrailGraph extends Graph {
  * snapshot synchronously.
  */
 declare function auditTrail(target: Graph, opts?: AuditTrailOptions): AuditTrailGraph;
-/** A single policy denial recorded by {@link PolicyEnforcerGraph}. */
+/** A single policy denial recorded by {@link PolicyGateGraph}. */
 interface PolicyViolation {
     timestamp_ns: number;
     wall_clock_ns: number;
@@ -99,8 +100,8 @@ interface PolicyViolation {
     /** `"observed"` (audit mode after-the-fact) or `"blocked"` (enforce mode pre-write). */
     result: "observed" | "blocked";
 }
-/** Options for {@link policyEnforcer}. */
-interface PolicyEnforcerOptions {
+/** Options for {@link policyGate}. */
+interface PolicyGateOptions {
     name?: string;
     graph?: GraphOptions;
     /**
@@ -122,14 +123,28 @@ interface PolicyEnforcerOptions {
      * `target` OR any transitively-mounted subgraph after construction are
      * guarded automatically (enforce mode only).
      *
+     * Accepts a static `readonly string[]` or a reactive
+     * `Node<readonly string[]>` (Tier 3.4 — F.9 reactive primitive carve-out).
+     * When a `Node` is passed, the enforcer rebinds the guarded path set on
+     * every emission: paths added to the new set get wrapped, paths removed
+     * from the new set get released, and the audit-mode allow-list filter
+     * uses the latest cached value. Static-array callers retain the current
+     * "caller owns the path set" semantics.
+     *
      * **Cost:** unrestricted mode runs `describe({detail:"minimal"})` once
      * at construction (O(N) over the graph tree) plus one topology
      * subscription per graph instance in the mount tree. Restricted mode
-     * skips both and disables dynamic coverage — callers providing
-     * `paths` must re-create on subgraph changes.
+     * (static or reactive) skips both and disables `watchTopologyTree`
+     * dynamic coverage — for reactive callers, the path-set Node is the
+     * single source of truth for which paths are guarded.
+     */
+    paths?: readonly string[] | Node<readonly string[]>;
+    /**
+     * Ring-buffer cap for the violations topic. Default: 1000. Static
+     * number only — reactive form is deferred pending TopicGraph reactive
+     * `retainedLimit` support (see Tier 10.8 design follow-up in
+     * `docs/optimizations.md`).
      */
-    paths?: readonly string[];
-    /** Ring-buffer cap for the violations topic. Default: 1000. */
     violationsLimit?: number;
 }
 /**
@@ -138,14 +153,14 @@ interface PolicyEnforcerOptions {
  * to update them at runtime; the enforcer rebinds its internal
  * {@link NodeGuard} on every push.
  */
-declare class PolicyEnforcerGraph extends Graph {
+declare class PolicyGateGraph extends Graph {
     readonly policies: Node<readonly PolicyRuleData[]>;
     readonly violations: TopicGraph<PolicyViolation>;
     readonly violationCount: Node<number>;
     private readonly _target;
     private readonly _mode;
     private _currentGuard;
-    constructor(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts: PolicyEnforcerOptions);
+    constructor(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts: PolicyGateOptions);
     private _publishViolation;
     /** Snapshot of recorded violations. */
     all(): readonly PolicyViolation[];
@@ -157,37 +172,16 @@ declare class PolicyEnforcerGraph extends Graph {
  * static rule list or a {@link Node} of rules (LLM-updatable). Records
  * `PolicyViolation` entries to `violations` topic; in `"enforce"` mode also
  * pushes guards onto target nodes so disallowed writes throw.
- */
-declare function policyEnforcer(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts?: PolicyEnforcerOptions): PolicyEnforcerGraph;
-/**
- * Reactive {@link CausalChain} that recomputes whenever the audited graph
- * changes. Returns a `Node<CausalChain>` suitable for subscription, mounting,
- * or composition (e.g. inside `graphLens.why(node)`).
  *
- * **How it stays live:** an internal `version` state is bumped by an observer
- * attached to `target.observe()`; the derived chain depends on `version`, so
- * each mutation triggers a recompute. To avoid stalling on no-op events, only
- * `data`, `error`, `complete`, and `teardown` bump the version (matching the
- * audit defaults).
- */
-/**
- * @deprecated Use `graph.explain(from, to, { reactive: true, ... })` directly.
- *   This free-function wrapper now dispatches to the consolidated
- *   {@link Graph.explain} overload for mental-model consistency with
- *   `describe` / `observe`. Will be removed pre-1.0.
+ * Self-tags via `g.tagFactory("policyGate", placeholderArgs(opts))` so
+ * `graph.describe()` surfaces `factory: "policyGate"` provenance (Phase 2.5
+ * DT5 ride-along, locked with the Tier 2.3 rename).
  */
-declare function reactiveExplainPath(target: Graph, from: string, to: string, opts?: {
-    maxDepth?: number;
-    name?: string;
-    findCycle?: boolean;
-}): {
-    node: Node<CausalChain>;
-    dispose: () => void;
-};
+declare function policyGate(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts?: PolicyGateOptions): PolicyGateGraph;
 /** Options for {@link complianceSnapshot}. */
 interface ComplianceSnapshotOptions {
     audit?: AuditTrailGraph;
-    policies?: PolicyEnforcerGraph;
+    policies?: PolicyGateGraph;
     /** Actor recorded as the snapshot taker. */
     actor?: Actor;
 }
@@ -236,16 +230,15 @@ declare const index_AuditTrailGraph: typeof AuditTrailGraph;
 type index_AuditTrailOptions = AuditTrailOptions;
 type index_ComplianceSnapshotOptions = ComplianceSnapshotOptions;
 type index_ComplianceSnapshotResult = ComplianceSnapshotResult;
-type index_PolicyEnforcerGraph = PolicyEnforcerGraph;
-declare const index_PolicyEnforcerGraph: typeof PolicyEnforcerGraph;
-type index_PolicyEnforcerOptions = PolicyEnforcerOptions;
+type index_PolicyGateGraph = PolicyGateGraph;
+declare const index_PolicyGateGraph: typeof PolicyGateGraph;
+type index_PolicyGateOptions = PolicyGateOptions;
 type index_PolicyViolation = PolicyViolation;
 declare const index_auditTrail: typeof auditTrail;
 declare const index_complianceSnapshot: typeof complianceSnapshot;
-declare const index_policyEnforcer: typeof policyEnforcer;
-declare const index_reactiveExplainPath: typeof reactiveExplainPath;
+declare const index_policyGate: typeof policyGate;
 declare namespace index {
-  export { type index_AuditEntry as AuditEntry, index_AuditTrailGraph as AuditTrailGraph, type index_AuditTrailOptions as AuditTrailOptions, type index_ComplianceSnapshotOptions as ComplianceSnapshotOptions, type index_ComplianceSnapshotResult as ComplianceSnapshotResult, index_PolicyEnforcerGraph as PolicyEnforcerGraph, type index_PolicyEnforcerOptions as PolicyEnforcerOptions, type index_PolicyViolation as PolicyViolation, index_auditTrail as auditTrail, index_complianceSnapshot as complianceSnapshot, index_policyEnforcer as policyEnforcer, index_reactiveExplainPath as reactiveExplainPath };
+  export { type index_AuditEntry as AuditEntry, index_AuditTrailGraph as AuditTrailGraph, type index_AuditTrailOptions as AuditTrailOptions, type index_ComplianceSnapshotOptions as ComplianceSnapshotOptions, type index_ComplianceSnapshotResult as ComplianceSnapshotResult, index_PolicyGateGraph as PolicyGateGraph, type index_PolicyGateOptions as PolicyGateOptions, type index_PolicyViolation as PolicyViolation, index_auditTrail as auditTrail, index_complianceSnapshot as complianceSnapshot, index_policyGate as policyGate };
 }
 
-export { type AuditEntry as A, type ComplianceSnapshotOptions as C, PolicyEnforcerGraph as P, type PolicyViolation as a, AuditTrailGraph as b, type AuditTrailOptions as c, type ComplianceSnapshotResult as d, type PolicyEnforcerOptions as e, auditTrail as f, complianceSnapshot as g, index as i, policyEnforcer as p, reactiveExplainPath as r };
+export { type AuditEntry as A, type ComplianceSnapshotOptions as C, PolicyGateGraph as P, type PolicyViolation as a, AuditTrailGraph as b, type AuditTrailOptions as c, type ComplianceSnapshotResult as d, type PolicyGateOptions as e, auditTrail as f, complianceSnapshot as g, index as i, policyGate as p };

package/dist/{index-D0ZxFXYl.d.ts → index-DszPlZzK.d.ts}

@@ -1,6 +1,6 @@
-import { a as Node } from './node-fSc-hCv8.js';
-import { G as Graph, a as GraphOptions } from './graph-YQXDndFy.js';
-import { R as ReactiveLogBundle } from './reactive-log-jirQsxMY.js';
+import { N as Node } from './node-BYInONRr.js';
+import { G as Graph, a as GraphOptions } from './graph-30XSgtVX.js';
+import { a as ReactiveLogBundle } from './reactive-log-BlAsPLl2.js';
 import { AppendLogStorageTier } from './extra/storage-tiers.js';
 
 type TopicOptions = {

package/dist/{index-BECJ8M0T.d.cts → index-DyM4tFAe.d.cts}

@@ -1,8 +1,8 @@
-import { a as Node } from './node-fSc-hCv8.cjs';
-import { R as ReactiveLogBundle } from './reactive-log-ScpWyqny.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
+import { B as BaseAuditRecord } from './index-DINuaZlJ.cjs';
+import { a as ReactiveLogBundle } from './reactive-log-_zeEnB9H.cjs';
 import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
-import { a as GraphOptions, G as Graph } from './graph-CaNXUc3c.cjs';
-import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.cjs';
+import { a as GraphOptions, G as Graph } from './graph-BUwMAxJI.cjs';
 
 /**
  * CQRS patterns (roadmap §4.5).
@@ -64,13 +64,14 @@ declare const cqrsEventKeyOf: (e: CqrsEvent) => string;
 interface DispatchRecord<T = unknown> extends BaseAuditRecord {
     readonly commandName: string;
     readonly payload: T;
-    readonly status: "success" | "failed";
+    /** Action result. Tier 1.6.2 canonical enum (renamed from `status`). */
+    readonly outcome: "success" | "failure";
     readonly error?: unknown;
     readonly errorType?: string;
     /**
      * Event names emitted by the handler.
-     * - `status: "success"`: events that persisted in the event log.
-     * - `status: "failed"`: events the handler ATTEMPTED to emit before throwing;
+     * - `outcome: "success"`: events that persisted in the event log.
+     * - `outcome: "failure"`: events the handler ATTEMPTED to emit before throwing;
      *   they were rolled back and did NOT persist. Documents the failed attempt's
      *   intentions for debugging handler logic. The actual event log shows only
      *   what's durable.
@@ -80,7 +81,8 @@ interface DispatchRecord<T = unknown> extends BaseAuditRecord {
 declare const dispatchKeyOf: <T>(r: DispatchRecord<T>) => string;
 interface SagaInvocation<T = unknown> extends BaseAuditRecord {
     readonly eventType: string;
-    readonly status: "success" | "failed";
+    /** Action result. Tier 1.6.2 canonical enum (renamed from `status`). */
+    readonly outcome: "success" | "failure";
     readonly error?: unknown;
     readonly errorType?: string;
     readonly aggregateId?: string;

package/dist/{index-D11pGlaI.d.cts → index-FVoPvhAu.d.cts}

@@ -1,9 +1,9 @@
-import { T as ToObservableOptions, t as toObservable } from './observable-Cqty11jG.cjs';
+import { T as ToObservableOptions, t as toObservable } from './observable-DMIlYJV1.cjs';
 import { OnModuleInit, OnModuleDestroy, ExecutionContext, CanActivate, DynamicModule } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
-import { G as Graph, b as GraphPersistSnapshot } from './graph-CaNXUc3c.cjs';
-import { A as Actor } from './node-fSc-hCv8.cjs';
-import { c as CqrsOptions, b as CqrsGraph, a as CqrsEvent } from './index-BECJ8M0T.cjs';
+import { G as Graph, c as GraphPersistSnapshot } from './graph-BUwMAxJI.cjs';
+import { A as Actor } from './node-BYInONRr.cjs';
+import { c as CqrsOptions, b as CqrsGraph, a as CqrsEvent } from './index-DyM4tFAe.cjs';
 import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
 
 /** Class constructor key for decorator registries and Nest `ModuleRef.get()`. */

package/dist/{index-BwtIbzSV.d.cts → index-H_I66pav.d.cts}

@@ -1,5 +1,5 @@
-import { G as Graph } from './graph-CaNXUc3c.cjs';
-import { M as MeasurementAdapter } from './reactive-layout-DrGjuwyC.cjs';
+import { G as Graph } from './graph-BUwMAxJI.cjs';
+import { M as MeasurementAdapter } from './reactive-layout-8CSc0tiA.cjs';
 
 /**
  * Three-pane demo shell (roadmap §7.2).

package/dist/{index-e1m3ZHgc.d.cts → index-IwFqHxCs.d.cts}

@@ -1,5 +1,5 @@
-import { a as Node } from './node-fSc-hCv8.cjs';
-import { a as GraphOptions, G as Graph } from './graph-CaNXUc3c.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
+import { a as GraphOptions, G as Graph } from './graph-BUwMAxJI.cjs';
 
 /**
  * Domain templates (roadmap §8.2).

package/dist/index-K-vl_c6A.d.cts

@@ -0,0 +1,113 @@
+import { N as Node, a as NodeOptions } from './node-BYInONRr.cjs';
+import { a as GraphOptions, G as Graph } from './graph-BUwMAxJI.cjs';
+
+/**
+ * Reduction primitives (roadmap §8.1).
+ *
+ * Composable building blocks for taking heterogeneous massive inputs and producing
+ * prioritized, auditable, human-actionable output. Each primitive is either a Graph
+ * factory or a Node factory, built on top of core + extra primitives.
+ *
+ * @module
+ */
+
+type StepRef = string | Node<unknown>;
+/** A named stage for {@link funnel}. */
+type FunnelStage = {
+    /** Stage name (mounted as subgraph). */
+    name: string;
+    /** Builder: receives a sub-graph, should add an `"input"` and `"output"` node. */
+    build: (sub: Graph) => void;
+};
+/** Options for {@link funnel}. */
+type FunnelOptions = GraphOptions & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Multi-source merge with sequential reduction stages.
+ *
+ * Sources are merged into a single stream. Each stage is a named subgraph
+ * (mounted via `graph.mount()`). Stages connect linearly:
+ * `merged → stage[0].input → stage[0].output → stage[1].input → ...`
+ *
+ * @param name - Graph name.
+ * @param sources - Input nodes to merge.
+ * @param stages - Sequential reduction stages.
+ * @param opts - Optional graph/meta options.
+ * @returns Graph with `"merged"` and mounted stage subgraphs.
+ *
+ * @category patterns
+ */
+declare function funnel<T>(name: string, sources: ReadonlyArray<Node<T>>, stages: ReadonlyArray<FunnelStage>, opts?: FunnelOptions): Graph;
+/** Options for {@link feedback}. */
+type FeedbackOptions = {
+    /** Maximum feedback iterations before stopping (default: 10). */
+    maxIterations?: number;
+    /** Optional budget gate node path for cost-bounded iteration. */
+    budgetNode?: StepRef;
+    meta?: Record<string, unknown>;
+};
+/**
+ * Introduce a bounded reactive cycle into an existing graph.
+ *
+ * When `condition` emits a non-null DATA value, the feedback effect routes it
+ * back to the `reentry` state node — creating a cycle. Bounded by
+ * `maxIterations` (default 10). The counter node (`__feedback_<condition>`)
+ * is the source of truth — reset it to 0 to allow more iterations.
+ *
+ * To remove the feedback cycle, call `graph.remove("__feedback_<condition>")`.
+ *
+ * @param graph - Existing graph to augment with a feedback cycle.
+ * @param condition - Path to a node whose DATA triggers feedback.
+ * @param reentry - Path to a state node that receives the feedback value.
+ * @param opts - Iteration bounds and metadata.
+ * @returns The same graph (mutated with feedback nodes added).
+ *
+ * @category patterns
+ */
+declare function feedback(graph: Graph, condition: string, reentry: string, opts?: FeedbackOptions): Graph;
+/** A scored item with full breakdown. */
+type ScoredItem<T = unknown> = {
+    /** Original value. */
+    value: T;
+    /** Final weighted score. */
+    score: number;
+    /** Per-signal breakdown: signal index → weighted contribution. */
+    breakdown: number[];
+};
+/** Options for {@link scorer}. */
+type ScorerOptions = Omit<NodeOptions<unknown>, "describeKind" | "name" | "meta"> & {
+    meta?: Record<string, unknown>;
+    /** Custom scoring function per signal. Default: identity (signal value IS the score). */
+    scoreFns?: ReadonlyArray<(value: unknown) => number>;
+};
+/**
+ * Reactive multi-signal scoring with live weights.
+ *
+ * Each source emits items to score. Weights are reactive state nodes that
+ * LLM or human can adjust live. Output is sorted scored items with full
+ * breakdown.
+ *
+ * @param sources - Signal nodes (each emits a numeric score dimension).
+ * @param weights - Reactive weight nodes (one per source).
+ * @param opts - Optional node/meta options.
+ * @returns Node emitting scored output.
+ *
+ * @category patterns
+ */
+declare function scorer(sources: ReadonlyArray<Node<number>>, weights: ReadonlyArray<Node<number>>, opts?: ScorerOptions): Node<ScoredItem<number[]>>;
+
+type index_FeedbackOptions = FeedbackOptions;
+type index_FunnelOptions = FunnelOptions;
+type index_FunnelStage = FunnelStage;
+type index_ScoredItem<T = unknown> = ScoredItem<T>;
+type index_ScorerOptions = ScorerOptions;
+type index_StepRef = StepRef;
+declare const index_feedback: typeof feedback;
+declare const index_funnel: typeof funnel;
+declare const index_scorer: typeof scorer;
+declare namespace index {
+  export { type index_FeedbackOptions as FeedbackOptions, type index_FunnelOptions as FunnelOptions, type index_FunnelStage as FunnelStage, type index_ScoredItem as ScoredItem, type index_ScorerOptions as ScorerOptions, type index_StepRef as StepRef, index_feedback as feedback, index_funnel as funnel, index_scorer as scorer };
+}
+
+export { type FeedbackOptions as F, type ScoredItem as S, type FunnelOptions as a, type FunnelStage as b, type ScorerOptions as c, type StepRef as d, funnel as e, feedback as f, index as i, scorer as s };

package/dist/{index-C4N-dg5U.d.cts → index-KlZ_ZUip.d.cts}

@@ -1,5 +1,5 @@
-import { j as CompileSpecOptions, G as GraphSpec, c as GraphSpecCatalog, C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from './index-DCAuN9u5.cjs';
-import { G as Graph, o as GraphNodeFactory, m as GraphDiffResult } from './graph-CaNXUc3c.cjs';
+import { j as CompileSpecOptions, G as GraphSpec, c as GraphSpecCatalog, C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from './index-DlrWu9Hs.cjs';
+import { G as Graph, p as GraphNodeFactory, n as GraphDiffResult } from './graph-BUwMAxJI.cjs';
 import { KvStorageTier } from './extra/storage-tiers.cjs';
 
 /**