@graphrefly/graphrefly 0.39.0 → 0.40.0

package/dist/index-CIRG8Hxp.d.cts

@@ -1,135 +0,0 @@
-import { P as PolicyRuleData, N as Node, A as Actor } from './node-BYInONRr.cjs';
-import { G as Graph, a as GraphOptions, d as GraphDescribeOptions, b as GraphDescribeOutput, D as DescribeFilter } from './graph-BUwMAxJI.cjs';
-import { P as PolicyGateGraph, a as PolicyViolation } from './index-DoYc8BWK.cjs';
-import { T as TopicGraph } from './index-BndG0cpK.cjs';
-
-/**
- * Composable safety layer (roadmap §9.0b).
- *
- * {@link guardedExecution} wraps any {@link Graph} with:
- *
- * - {@link policyGate} — reactive ABAC (Tier 2.3 rename of `policyEnforcer`),
- *   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 policyGate). */
-    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 PolicyGateGraph} under `enforcer`.
- *
- * @category patterns
- */
-declare class GuardedExecutionGraph extends Graph {
-    readonly enforcer: PolicyGateGraph;
-    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 policyGate} 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/index-Cey6VTnX.d.ts

@@ -1,166 +0,0 @@
-import { N as Node } from './node-BYInONRr.js';
-import { R as ReactiveMapBundle } from './reactive-map-jFIsE6Kt.js';
-import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-30XSgtVX.js';
-import { w as watchTopologyTree } from './topology-tree-BtvbgMXJ.js';
-
-/** 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.
-     *
-     * Tier 3.5: rebuilt on top of `graph.explain(from, to, { reactive: true })`
-     * after the deprecated `reactiveExplainPath` wrapper was deleted.
-     *
-     * @param from - Qualified path of the upstream endpoint.
-     * @param to - Qualified path of the downstream endpoint.
-     * @param opts - See {@link Graph.explain} (`{ reactive: true }` overload).
-     */
-    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-CpLpJb6A.d.cts

@@ -1,166 +0,0 @@
-import { N as Node } from './node-BYInONRr.cjs';
-import { R as ReactiveMapBundle } from './reactive-map-B2qfD3hb.cjs';
-import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-BUwMAxJI.cjs';
-import { w as watchTopologyTree } from './topology-tree-B5Ngw3j0.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.
-     *
-     * Tier 3.5: rebuilt on top of `graph.explain(from, to, { reactive: true })`
-     * after the deprecated `reactiveExplainPath` wrapper was deleted.
-     *
-     * @param from - Qualified path of the upstream endpoint.
-     * @param to - Qualified path of the downstream endpoint.
-     * @param opts - See {@link Graph.explain} (`{ reactive: true }` overload).
-     */
-    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 };