@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/index-DknyJ2Fu.d.cts

@@ -0,0 +1,163 @@
+import { a as Node } from './node-Dd6wHSib.cjs';
+import { R as ReactiveMapBundle } from './reactive-map-CwO_COHy.cjs';
+import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-DgohqXK-.cjs';
+import { w as watchTopologyTree } from './topology-tree-CVjt2gp7.cjs';
+
+/** Aggregate topology stats emitted by {@link LensGraph.stats}. */
+interface TopologyStats {
+    /** Total primary nodes across this graph and all transitively mounted subgraphs. */
+    nodeCount: number;
+    /** Total directed edges (derived from deps; no duplicates). */
+    edgeCount: number;
+    /** Count of mounted subgraphs (transitive). */
+    subgraphCount: number;
+    /** Qualified paths with no upstream deps (source nodes). Sorted. */
+    sources: readonly string[];
+    /** Qualified paths with no downstream consumers in-graph (sink nodes). Sorted. */
+    sinks: readonly string[];
+    /** Longest path from any source to any sink (in edges). `0` for empty graphs. */
+    depth: number;
+    /** `true` if the dep DAG contains a cycle (feedback edge). */
+    hasCycles: boolean;
+}
+/** A single health problem entry. */
+interface HealthProblem {
+    path: string;
+    /** V1 only reports `"errored"`. Future versions may add `"completed"`, `"disconnected"`. */
+    status: "errored";
+    /** First errored upstream ancestor along the dep chain, when one exists and is distinct from `path`. */
+    upstreamCause?: string;
+}
+/** Aggregate health snapshot. `ok=true` iff `problems.length === 0`. */
+interface HealthReport {
+    ok: boolean;
+    problems: readonly HealthProblem[];
+}
+/** One per-path flow entry stored in {@link LensGraph.flow}. */
+interface FlowEntry {
+    path: string;
+    /** Cumulative DATA emissions observed since the lens activated. */
+    count: number;
+    /** `monotonicNs()` at the most recent DATA emission, or `null` if none yet. */
+    lastUpdate_ns: number | null;
+}
+/** Options for {@link graphLens}. */
+interface GraphLensOptions {
+    name?: string;
+    graph?: GraphOptions;
+    /**
+     * Limit which node paths `flow` tracks. When omitted, every path in
+     * `target.describe()` is observed. Recommended for graphs with hundreds
+     * of nodes since each tracked path adds one observe-event dispatch per
+     * DATA emission.
+     */
+    pathFilter?: (path: string) => boolean;
+    /**
+     * LRU cap on the {@link LensGraph.flow} map. When set, the flow tracker
+     * evicts least-recently-used paths (by insertion / set order) once the
+     * entry count exceeds this bound. Omit for unbounded (not recommended
+     * for long-running graphs with churning paths). Passed through to the
+     * underlying {@link reactiveMap}'s `maxSize`.
+     */
+    maxFlowPaths?: number;
+}
+/**
+ * Reactive observability surface for a target {@link Graph}.
+ * See {@link graphLens}.
+ *
+ * @category observability
+ */
+declare class LensGraph extends Graph {
+    /**
+     * Aggregate structural stats — `nodeCount`, `edgeCount`, `sources`,
+     * `sinks`, `depth`, `hasCycles`, `subgraphCount`. Recomputes on every
+     * structural change via {@link watchTopologyTree} (transitive).
+     *
+     * Named `stats` (not `topology`) because `Graph.topology` already names
+     * the raw `TopologyEvent` stream on every graph including `LensGraph`;
+     * giving the lens its own `topology` accessor with an incompatible
+     * `Node<TopologyStats>` type would break Liskov substitutability.
+     */
+    readonly stats: Node<TopologyStats>;
+    readonly health: Node<HealthReport>;
+    /**
+     * Per-path flow tracker — a live {@link ReactiveMapBundle} keyed by
+     * qualified path. Use `.get(path)` / `.has(path)` / `.size` for O(1)
+     * sync queries; subscribe to `.entries` for a reactive snapshot of the
+     * whole map. Lazy — the snapshot is materialized only while `.entries`
+     * has subscribers.
+     *
+     * Shape intentionally differs from `stats` / `health` (which are plain
+     * `Node<Report>`) because `flow` is a keyed collection, not a single
+     * aggregate value. The map shape exposes cheaper queries than any
+     * snapshot-based design.
+     */
+    readonly flow: ReactiveMapBundle<string, FlowEntry>;
+    private readonly _target;
+    constructor(target: Graph, opts?: GraphLensOptions);
+    /**
+     * Live causal chain from `from` to `to`. Recomputes whenever the target
+     * mutates. Disposed automatically when the lens is destroyed.
+     *
+     * **Lifetime note:** every call to `why()` registers a lens-owned disposer
+     * that runs on `lens.destroy()`. The returned `dispose` function releases
+     * the internal subscription but does NOT remove the lens-owned disposer —
+     * so heavy calling (e.g. per render frame) accumulates no-op disposers
+     * until lens teardown. Cache the returned handle for long-lived queries.
+     *
+     * @param from - Qualified path of the upstream endpoint.
+     * @param to - Qualified path of the downstream endpoint.
+     * @param opts - See {@link reactiveExplainPath}.
+     */
+    why(from: string, to: string, opts?: {
+        maxDepth?: number;
+        name?: string;
+        findCycle?: boolean;
+    }): {
+        node: Node<CausalChain>;
+        dispose: () => void;
+    };
+    /** Reference to the lensed graph. */
+    get target(): Graph;
+}
+/**
+ * Create a reactive observability lens over a {@link Graph}. Returns a
+ * {@link LensGraph} with three reactive surfaces (`stats`, `health`, `flow`)
+ * plus the `why(from, to)` method.
+ *
+ * The returned graph is detached. Mount it via `target.mount("lens", lens)`
+ * if you want it to appear in the target's `describe()`, or keep it standalone.
+ *
+ * @param target - The graph to observe.
+ * @param opts - See {@link GraphLensOptions}.
+ *
+ * @example
+ * ```ts
+ * const g = new Graph("app");
+ * g.add(state(0, { name: "counter" }));
+ * const lens = graphLens(g);
+ * lens.stats.subscribe((msgs) => console.log(msgs[0]?.[1])); // TopologyStats
+ * // Flow queries — O(1) without subscribing to snapshots:
+ * lens.flow.get("counter");        // FlowEntry | undefined
+ * lens.flow.size;                  // number
+ * lens.flow.entries.subscribe(...); // reactive snapshot, lazy-materialized
+ * ```
+ *
+ * @category observability
+ */
+declare function graphLens(target: Graph, opts?: GraphLensOptions): LensGraph;
+
+type index_FlowEntry = FlowEntry;
+type index_GraphLensOptions = GraphLensOptions;
+type index_HealthProblem = HealthProblem;
+type index_HealthReport = HealthReport;
+type index_LensGraph = LensGraph;
+declare const index_LensGraph: typeof LensGraph;
+type index_TopologyStats = TopologyStats;
+declare const index_graphLens: typeof graphLens;
+declare const index_watchTopologyTree: typeof watchTopologyTree;
+declare namespace index {
+  export { type index_FlowEntry as FlowEntry, type index_GraphLensOptions as GraphLensOptions, type index_HealthProblem as HealthProblem, type index_HealthReport as HealthReport, index_LensGraph as LensGraph, type index_TopologyStats as TopologyStats, index_graphLens as graphLens, index_watchTopologyTree as watchTopologyTree };
+}
+
+export { type FlowEntry as F, type GraphLensOptions as G, type HealthProblem as H, LensGraph as L, type TopologyStats as T, type HealthReport as a, graphLens as g, index as i };

package/dist/index-DoWMs-Kk.d.cts

@@ -0,0 +1,135 @@
+import { P as PolicyRuleData, a as Node, A as Actor } from './node-Dd6wHSib.cjs';
+import { G as Graph, a as GraphOptions, b as GraphDescribeOptions, c as GraphDescribeOutput, D as DescribeFilter } from './graph-DgohqXK-.cjs';
+import { P as PolicyEnforcerGraph, a as PolicyViolation } from './index-BayHDRx6.cjs';
+import { T as TopicGraph } from './index-BanNUILp.cjs';
+
+/**
+ * Composable safety layer (roadmap §9.0b).
+ *
+ * {@link guardedExecution} wraps any {@link Graph} with:
+ *
+ * - {@link policyEnforcer} — reactive ABAC, policies stored as a `Node` so
+ *   LLMs / humans can update them at runtime. Now with full transitive
+ *   dynamic coverage via `watchTopologyTree`.
+ * - Scoped {@link GuardedExecutionGraph.scopedDescribe} — delegates to
+ *   `target.describe({actor})` so callers see only what the actor is
+ *   allowed to see.
+ * - The enforcer's `violations` topic is republished as `violations` on
+ *   the wrapper, composable with {@link graphLens}.`health` alerts.
+ *
+ * V1 scope: policies + actor + scoped describe. Budget-as-option is NOT
+ * in V1 — it requires a cost-tracking design that hasn't landed yet.
+ * Callers who need a budget limit today append a budget-aware
+ * {@link PolicyRuleData} to the policies list (check current cost and
+ * `deny` when exhausted).
+ *
+ * @module
+ */
+
+/** Options for {@link guardedExecution}. */
+interface GuardedExecutionOptions {
+    /**
+     * Policies enforced against every guarded write. Static list or a live
+     * `Node<readonly PolicyRuleData[]>` (LLM-updatable).
+     *
+     * **Deny-by-default gotcha:** the underlying `policyFromRules()` denies any
+     * action that matches no rule. An empty policies list in `mode: "enforce"`
+     * therefore blocks EVERY write AND every `observe` through the stacked
+     * guard — including `scopedDescribe()`. If you want a permissive base, add
+     * at least `{ effect: "allow", action: "*" }` and layer deny rules on top.
+     * In `mode: "audit"` no guards are stacked, so empty policies are safe.
+     */
+    policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>;
+    /**
+     * Actor whose perspective drives {@link GuardedExecutionGraph.scopedDescribe}
+     * and {@link GuardedExecutionGraph.describe} — when omitted, callers must
+     * pass `{actor}` explicitly or they get the target's raw describe.
+     */
+    actor?: Actor;
+    /**
+     * `"enforce"` (default) — push guards onto target nodes so disallowed
+     * writes throw {@link GuardDenied}.
+     * `"audit"` — record would-be denials to the `violations` topic without
+     * blocking writes.
+     */
+    mode?: "audit" | "enforce";
+    /** Ring-buffer cap for the `violations` topic. Default 1000 (inherited from policyEnforcer). */
+    violationsLimit?: number;
+    /** Wrapper graph name. Default `${target.name}_guarded`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Wrapper over a target {@link Graph} providing reactive ABAC + scoped
+ * describe. Mounts a {@link PolicyEnforcerGraph} under `enforcer`.
+ *
+ * @category patterns
+ */
+declare class GuardedExecutionGraph extends Graph {
+    readonly enforcer: PolicyEnforcerGraph;
+    readonly violations: TopicGraph<PolicyViolation>;
+    private readonly _target;
+    private readonly _defaultActor;
+    constructor(target: Graph, opts: GuardedExecutionOptions);
+    /**
+     * Describe the **target** graph scoped to the configured actor. Returns
+     * only nodes the actor is permitted to see (via the target's node guards
+     * filtering `describe()` via `actor`).
+     *
+     * Pass `{actor}` in opts to override the configured actor for this call.
+     * Pass any standard {@link GraphDescribeOptions} fields (`detail`,
+     * `fields`, `filter`) — they apply to the target's describe.
+     *
+     * **Mode interaction:**
+     * - In `mode: "enforce"` (default), the enforcer stacks a policy-derived
+     *   guard on every target node. `scopedDescribe({actor})` then filters by
+     *   the AND of per-node guards AND the stacked policy guard.
+     * - In `mode: "audit"`, NO guards are stacked — `scopedDescribe` filters
+     *   purely by the target's pre-existing per-node guards. If a target has
+     *   no node-level guards, the policy rules you pass have no effect on
+     *   visibility (they only populate the `violations` topic on writes).
+     */
+    scopedDescribe(opts?: Omit<GraphDescribeOptions, "actor"> & {
+        actor?: Actor;
+    }): GraphDescribeOutput;
+    /** The wrapped graph (escape hatch for tooling). */
+    get target(): Graph;
+}
+/**
+ * Wrap a {@link Graph} with {@link policyEnforcer} plus a scoped describe
+ * lens. Returns a {@link GuardedExecutionGraph} that can be mounted, diffed,
+ * or composed with {@link graphLens}.
+ *
+ * @param target - The graph to guard.
+ * @param opts - See {@link GuardedExecutionOptions}.
+ *
+ * @example
+ * ```ts
+ * const guarded = guardedExecution(app, {
+ *   actor: { type: "human", id: "alice" },
+ *   policies: [
+ *     { effect: "allow", action: "read", actorType: "human" },
+ *     { effect: "deny", action: "write", pathPattern: "system::*" },
+ *   ],
+ *   mode: "enforce",
+ * });
+ *
+ * const view = guarded.scopedDescribe({ detail: "standard" });
+ * guarded.violations.events.subscribe(msgs => console.log("violations:", msgs));
+ * ```
+ *
+ * @category patterns
+ */
+declare function guardedExecution(target: Graph, opts: GuardedExecutionOptions): GuardedExecutionGraph;
+
+declare const index_DescribeFilter: typeof DescribeFilter;
+type index_GuardedExecutionGraph = GuardedExecutionGraph;
+declare const index_GuardedExecutionGraph: typeof GuardedExecutionGraph;
+type index_GuardedExecutionOptions = GuardedExecutionOptions;
+declare const index_guardedExecution: typeof guardedExecution;
+declare namespace index {
+  export { index_DescribeFilter as DescribeFilter, index_GuardedExecutionGraph as GuardedExecutionGraph, type index_GuardedExecutionOptions as GuardedExecutionOptions, index_guardedExecution as guardedExecution };
+}
+
+export { GuardedExecutionGraph as G, type GuardedExecutionOptions as a, guardedExecution as g, index as i };

package/dist/{messaging-XDoYablx.d.ts → index-DuB5aO4-.d.ts}

@@ -1,13 +1,18 @@
-import { N as Node } from './node-BmerH3kS.js';
-import { a as Graph, G as GraphOptions } from './graph-CCwGKLCm.js';
+import { a as Node } from './node-Dd6wHSib.js';
+import { G as Graph, a as GraphOptions } from './graph-Qjg9gWHI.js';
 
 /**
  * Messaging patterns (roadmap §4.2).
  *
- * Pulsar-inspired messaging features modeled as graph factories:
- * - `topic()` for append-only topic streams
- * - `subscription()` for cursor-based consumers
- * - `jobQueue()` for queue claim/ack flow
+ * Pulsar-inspired messaging primitives modeled as graph factories:
+ * - `topic()` for append-only topic streams with a retained window.
+ * - `subscription()` for cursor-based consumers.
+ * - `topicBridge()` for autonomous topic-to-topic relay.
+ * - `messagingHub()` for a lazy topic registry.
+ *
+ * Job queue / job flow primitives live in `patterns/job-queue` — they are a
+ * distinct domain that happens to share reactive-log / reactive-map
+ * infrastructure with topics.
  */
 
 type TopicOptions = {
@@ -62,55 +67,6 @@ declare class SubscriptionGraph<T> extends Graph {
         ack?: boolean;
     }): readonly T[];
 }
-type JobState = "queued" | "inflight";
-type JobEnvelope<T> = {
-    id: string;
-    payload: T;
-    attempts: number;
-    metadata: Readonly<Record<string, unknown>>;
-    state: JobState;
-};
-type JobQueueOptions = {
-    graph?: GraphOptions;
-};
-declare class JobQueueGraph<T> extends Graph {
-    private readonly _pending;
-    private readonly _jobs;
-    private _seq;
-    readonly pending: Node<readonly string[]>;
-    readonly jobs: Node<ReadonlyMap<string, JobEnvelope<T>>>;
-    readonly depth: Node<number>;
-    constructor(name: string, opts?: JobQueueOptions);
-    enqueue(payload: T, opts?: {
-        id?: string;
-        metadata?: Record<string, unknown>;
-    }): string;
-    claim(limit?: number): readonly JobEnvelope<T>[];
-    ack(id: string): boolean;
-    nack(id: string, opts?: {
-        requeue?: boolean;
-    }): boolean;
-}
-type JobFlowOptions = {
-    graph?: GraphOptions;
-    stages?: readonly string[];
-    maxPerPump?: number;
-};
-declare class JobFlowGraph<T> extends Graph {
-    private readonly _stageNames;
-    private readonly _queues;
-    private readonly _completed;
-    readonly completed: Node<readonly JobEnvelope<T>[]>;
-    readonly completedCount: Node<number>;
-    constructor(name: string, opts?: JobFlowOptions);
-    stages(): readonly string[];
-    queue(stage: string): JobQueueGraph<T>;
-    enqueue(payload: T, opts?: {
-        id?: string;
-        metadata?: Record<string, unknown>;
-    }): string;
-    retainedCompleted(): readonly JobEnvelope<T>[];
-}
 type TopicBridgeOptions<TIn, TOut> = {
     graph?: GraphOptions;
     cursor?: number;
@@ -210,7 +166,7 @@ declare function topic<T>(name: string, opts?: TopicOptions): TopicGraph<T>;
  *
  * @example
  * ```ts
- * import { messagingHub } from "@graphrefly/graphrefly-ts";
+ * import { messagingHub } from "@graphrefly/graphrefly/patterns/messaging";
  *
  * const hub = messagingHub("main", { defaultTopicOptions: { retainedLimit: 256 } });
  * hub.publish("orders", { id: 1 });
@@ -223,47 +179,29 @@ declare function messagingHub(name: string, opts?: MessagingHubOptions): Messagi
  * Creates a cursor-based subscription graph over a topic.
  */
 declare function subscription<T>(name: string, topicGraph: TopicGraph<T>, opts?: SubscriptionOptions): SubscriptionGraph<T>;
-/**
- * Creates a Pulsar-inspired job queue graph with claim/ack/nack workflow.
- */
-declare function jobQueue<T>(name: string, opts?: JobQueueOptions): JobQueueGraph<T>;
-/**
- * Creates an autonomous multi-stage queue chain graph.
- */
-declare function jobFlow<T>(name: string, opts?: JobFlowOptions): JobFlowGraph<T>;
 /**
  * Creates an autonomous cursor-based topic relay graph.
  */
 declare function topicBridge<TIn, TOut = TIn>(name: string, sourceTopic: TopicGraph<TIn>, targetTopic: TopicGraph<TOut>, opts?: TopicBridgeOptions<TIn, TOut>): TopicBridgeGraph<TIn, TOut>;
 
-type messaging_JobEnvelope<T> = JobEnvelope<T>;
-type messaging_JobFlowGraph<T> = JobFlowGraph<T>;
-declare const messaging_JobFlowGraph: typeof JobFlowGraph;
-type messaging_JobFlowOptions = JobFlowOptions;
-type messaging_JobQueueGraph<T> = JobQueueGraph<T>;
-declare const messaging_JobQueueGraph: typeof JobQueueGraph;
-type messaging_JobQueueOptions = JobQueueOptions;
-type messaging_JobState = JobState;
-type messaging_MessagingHubGraph = MessagingHubGraph;
-declare const messaging_MessagingHubGraph: typeof MessagingHubGraph;
-type messaging_MessagingHubOptions = MessagingHubOptions;
-type messaging_SubscriptionGraph<T> = SubscriptionGraph<T>;
-declare const messaging_SubscriptionGraph: typeof SubscriptionGraph;
-type messaging_SubscriptionOptions = SubscriptionOptions;
-type messaging_TopicBridgeGraph<TIn, TOut = TIn> = TopicBridgeGraph<TIn, TOut>;
-declare const messaging_TopicBridgeGraph: typeof TopicBridgeGraph;
-type messaging_TopicBridgeOptions<TIn, TOut> = TopicBridgeOptions<TIn, TOut>;
-type messaging_TopicGraph<T> = TopicGraph<T>;
-declare const messaging_TopicGraph: typeof TopicGraph;
-type messaging_TopicOptions = TopicOptions;
-declare const messaging_jobFlow: typeof jobFlow;
-declare const messaging_jobQueue: typeof jobQueue;
-declare const messaging_messagingHub: typeof messagingHub;
-declare const messaging_subscription: typeof subscription;
-declare const messaging_topic: typeof topic;
-declare const messaging_topicBridge: typeof topicBridge;
-declare namespace messaging {
-  export { type messaging_JobEnvelope as JobEnvelope, messaging_JobFlowGraph as JobFlowGraph, type messaging_JobFlowOptions as JobFlowOptions, messaging_JobQueueGraph as JobQueueGraph, type messaging_JobQueueOptions as JobQueueOptions, type messaging_JobState as JobState, messaging_MessagingHubGraph as MessagingHubGraph, type messaging_MessagingHubOptions as MessagingHubOptions, messaging_SubscriptionGraph as SubscriptionGraph, type messaging_SubscriptionOptions as SubscriptionOptions, messaging_TopicBridgeGraph as TopicBridgeGraph, type messaging_TopicBridgeOptions as TopicBridgeOptions, messaging_TopicGraph as TopicGraph, type messaging_TopicOptions as TopicOptions, messaging_jobFlow as jobFlow, messaging_jobQueue as jobQueue, messaging_messagingHub as messagingHub, messaging_subscription as subscription, messaging_topic as topic, messaging_topicBridge as topicBridge };
+type index_MessagingHubGraph = MessagingHubGraph;
+declare const index_MessagingHubGraph: typeof MessagingHubGraph;
+type index_MessagingHubOptions = MessagingHubOptions;
+type index_SubscriptionGraph<T> = SubscriptionGraph<T>;
+declare const index_SubscriptionGraph: typeof SubscriptionGraph;
+type index_SubscriptionOptions = SubscriptionOptions;
+type index_TopicBridgeGraph<TIn, TOut = TIn> = TopicBridgeGraph<TIn, TOut>;
+declare const index_TopicBridgeGraph: typeof TopicBridgeGraph;
+type index_TopicBridgeOptions<TIn, TOut> = TopicBridgeOptions<TIn, TOut>;
+type index_TopicGraph<T> = TopicGraph<T>;
+declare const index_TopicGraph: typeof TopicGraph;
+type index_TopicOptions = TopicOptions;
+declare const index_messagingHub: typeof messagingHub;
+declare const index_subscription: typeof subscription;
+declare const index_topic: typeof topic;
+declare const index_topicBridge: typeof topicBridge;
+declare namespace index {
+  export { index_MessagingHubGraph as MessagingHubGraph, type index_MessagingHubOptions as MessagingHubOptions, index_SubscriptionGraph as SubscriptionGraph, type index_SubscriptionOptions as SubscriptionOptions, index_TopicBridgeGraph as TopicBridgeGraph, type index_TopicBridgeOptions as TopicBridgeOptions, index_TopicGraph as TopicGraph, type index_TopicOptions as TopicOptions, index_messagingHub as messagingHub, index_subscription as subscription, index_topic as topic, index_topicBridge as topicBridge };
 }
 
-export { TopicGraph as T, messaging as m };
+export { MessagingHubGraph as M, SubscriptionGraph as S, TopicGraph as T, type MessagingHubOptions as a, type SubscriptionOptions as b, TopicBridgeGraph as c, type TopicBridgeOptions as d, type TopicOptions as e, topicBridge as f, index as i, messagingHub as m, subscription as s, topic as t };