@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/external-register-CWyroXb_.d.cts

@@ -0,0 +1,138 @@
+import { NodeOptions, Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * External-register helpers — the common `register({emit, error, complete})`
+ * contract shared by webhook, MCP, syslog, StatsD, OTel and other callback-
+ * based integrations. Absorbs the `active` flag that every such adapter needs
+ * to guard against emits after teardown (§5.10 boundary pattern).
+ *
+ * Two shapes:
+ *
+ * - {@link externalProducer} — single channel. Lazy activation: the register
+ *   fn runs when the node gains its first subscriber; its returned cleanup
+ *   runs on deactivation.
+ *
+ * - {@link externalBundle} — multiple named channels. Eager activation: the
+ *   register fn runs at bundle construction time so externally-owned servers
+ *   (HTTP endpoints, UDP sockets) start accepting traffic immediately. A
+ *   shared refcount fires the returned cleanup once every channel has fully
+ *   torn down.
+ */
+
+type ExtraOpts = Omit<NodeOptions<unknown>, "describeKind">;
+/**
+ * Standard emit-triad passed to a single-channel external registrar.
+ *
+ * Post-teardown calls on any of these are automatically no-ops — the
+ * registrar does not need its own guard flag.
+ *
+ * @category extra
+ */
+type EmitTriad<T> = {
+    /** Emit a value as `DATA`. */
+    emit: (value: T) => void;
+    /** Terminate with `ERROR`. Subsequent `emit` / `error` / `complete` are ignored. */
+    error: (err: unknown) => void;
+    /** Terminate with `COMPLETE`. Subsequent `emit` / `error` / `complete` are ignored. */
+    complete: () => void;
+};
+/**
+ * Multi-channel emit bundle. Each declared channel name maps to an emit fn;
+ * `error` and `complete` terminate every channel atomically.
+ *
+ * @category extra
+ */
+type BundleTriad<TChannels extends Record<string, unknown>> = {
+    [K in keyof TChannels]: (value: TChannels[K]) => void;
+} & {
+    /** Terminate every channel with `ERROR`. */
+    error: (err: unknown) => void;
+    /** Terminate every channel with `COMPLETE`. */
+    complete: () => void;
+};
+/**
+ * Generic external registrator contract. The caller installs handlers into a
+ * third-party library / framework / server and optionally returns a cleanup
+ * callback. Returning `undefined` / `void` is equivalent to a no-op cleanup.
+ *
+ * @category extra
+ */
+type ExternalRegister<H> = (handlers: H) => (() => void) | undefined;
+/**
+ * Wraps a callback-style external integration as a reactive source.
+ *
+ * The registrar installs the supplied `emit` / `error` / `complete` handlers
+ * into the external SDK; post-teardown calls are silently dropped. Synchronous
+ * exceptions thrown by the registrar surface as terminal `ERROR`.
+ *
+ * @param register - Installs handlers. Optionally returns a cleanup fn.
+ * @param opts - Node options (name, equals, resubscribable, ...).
+ *
+ * @example
+ * ```ts
+ * import { externalProducer } from "@graphrefly/graphrefly-ts";
+ *
+ * const hook$ = externalProducer<Payload>(({ emit, error }) => {
+ *   const id = transport.onMessage((raw) => {
+ *     try { emit(parse(raw)); } catch (e) { error(e); }
+ *   });
+ *   return () => transport.off(id);
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function externalProducer<T = unknown>(register: ExternalRegister<EmitTriad<T>>, opts?: ExtraOpts): Node<T>;
+/**
+ * Options for {@link externalBundle}.
+ *
+ * @category extra
+ */
+type ExternalBundleOptions<TChannels extends Record<string, unknown>> = {
+    /** Base name prefix for channel nodes; each node is named `${name}::${channel}`. */
+    name?: string;
+    /** Per-channel node options (equals, resubscribable, ...). */
+    channelOpts?: {
+        [K in keyof TChannels]?: ExtraOpts;
+    };
+};
+/**
+ * Multi-channel variant — one `Node<T>` per named channel, sharing a single
+ * registrar. Activation is eager: the registrar runs at construction time so
+ * externally-owned servers (HTTP, UDP, queue consumers) can start accepting
+ * traffic immediately. The returned cleanup fires once every channel has been
+ * subscribed and then fully deactivated (refcount-on-teardown).
+ *
+ * Any call to `error` or `complete` propagates to every channel atomically.
+ *
+ * @param register - Installs handlers for each channel plus shared error/complete.
+ * @param channels - Ordered channel names; determines the returned object shape.
+ * @param opts - Optional name prefix and per-channel node options.
+ *
+ * @example
+ * ```ts
+ * import { externalBundle } from "@graphrefly/graphrefly-ts";
+ *
+ * type OTelChannels = { traces: Span; metrics: Metric; logs: LogRec };
+ * const otel = externalBundle<OTelChannels>(
+ *   ({ traces, metrics, logs, error }) => {
+ *     app.post("/v1/traces",  (req, res) => { traces(req.body);  res.sendStatus(200); });
+ *     app.post("/v1/metrics", (req, res) => { metrics(req.body); res.sendStatus(200); });
+ *     app.post("/v1/logs",    (req, res) => { logs(req.body);    res.sendStatus(200); });
+ *     server.on("error", error);
+ *     return () => server.close();
+ *   },
+ *   ["traces", "metrics", "logs"],
+ * );
+ * otel.traces.subscribe(...);
+ * ```
+ *
+ * @category extra
+ */
+declare function externalBundle<TChannels extends Record<string, unknown>>(register: ExternalRegister<BundleTriad<TChannels>>, channels: readonly (keyof TChannels & string)[], opts?: ExternalBundleOptions<TChannels>): {
+    [K in keyof TChannels]: Node<TChannels[K]>;
+} & {
+    dispose(): void;
+};
+
+export { type BundleTriad as B, type EmitTriad as E, type ExternalBundleOptions as a, type ExternalRegister as b, externalProducer as c, externalBundle as e };

package/dist/external-register-CWyroXb_.d.ts

@@ -0,0 +1,138 @@
+import { NodeOptions, Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * External-register helpers — the common `register({emit, error, complete})`
+ * contract shared by webhook, MCP, syslog, StatsD, OTel and other callback-
+ * based integrations. Absorbs the `active` flag that every such adapter needs
+ * to guard against emits after teardown (§5.10 boundary pattern).
+ *
+ * Two shapes:
+ *
+ * - {@link externalProducer} — single channel. Lazy activation: the register
+ *   fn runs when the node gains its first subscriber; its returned cleanup
+ *   runs on deactivation.
+ *
+ * - {@link externalBundle} — multiple named channels. Eager activation: the
+ *   register fn runs at bundle construction time so externally-owned servers
+ *   (HTTP endpoints, UDP sockets) start accepting traffic immediately. A
+ *   shared refcount fires the returned cleanup once every channel has fully
+ *   torn down.
+ */
+
+type ExtraOpts = Omit<NodeOptions<unknown>, "describeKind">;
+/**
+ * Standard emit-triad passed to a single-channel external registrar.
+ *
+ * Post-teardown calls on any of these are automatically no-ops — the
+ * registrar does not need its own guard flag.
+ *
+ * @category extra
+ */
+type EmitTriad<T> = {
+    /** Emit a value as `DATA`. */
+    emit: (value: T) => void;
+    /** Terminate with `ERROR`. Subsequent `emit` / `error` / `complete` are ignored. */
+    error: (err: unknown) => void;
+    /** Terminate with `COMPLETE`. Subsequent `emit` / `error` / `complete` are ignored. */
+    complete: () => void;
+};
+/**
+ * Multi-channel emit bundle. Each declared channel name maps to an emit fn;
+ * `error` and `complete` terminate every channel atomically.
+ *
+ * @category extra
+ */
+type BundleTriad<TChannels extends Record<string, unknown>> = {
+    [K in keyof TChannels]: (value: TChannels[K]) => void;
+} & {
+    /** Terminate every channel with `ERROR`. */
+    error: (err: unknown) => void;
+    /** Terminate every channel with `COMPLETE`. */
+    complete: () => void;
+};
+/**
+ * Generic external registrator contract. The caller installs handlers into a
+ * third-party library / framework / server and optionally returns a cleanup
+ * callback. Returning `undefined` / `void` is equivalent to a no-op cleanup.
+ *
+ * @category extra
+ */
+type ExternalRegister<H> = (handlers: H) => (() => void) | undefined;
+/**
+ * Wraps a callback-style external integration as a reactive source.
+ *
+ * The registrar installs the supplied `emit` / `error` / `complete` handlers
+ * into the external SDK; post-teardown calls are silently dropped. Synchronous
+ * exceptions thrown by the registrar surface as terminal `ERROR`.
+ *
+ * @param register - Installs handlers. Optionally returns a cleanup fn.
+ * @param opts - Node options (name, equals, resubscribable, ...).
+ *
+ * @example
+ * ```ts
+ * import { externalProducer } from "@graphrefly/graphrefly-ts";
+ *
+ * const hook$ = externalProducer<Payload>(({ emit, error }) => {
+ *   const id = transport.onMessage((raw) => {
+ *     try { emit(parse(raw)); } catch (e) { error(e); }
+ *   });
+ *   return () => transport.off(id);
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function externalProducer<T = unknown>(register: ExternalRegister<EmitTriad<T>>, opts?: ExtraOpts): Node<T>;
+/**
+ * Options for {@link externalBundle}.
+ *
+ * @category extra
+ */
+type ExternalBundleOptions<TChannels extends Record<string, unknown>> = {
+    /** Base name prefix for channel nodes; each node is named `${name}::${channel}`. */
+    name?: string;
+    /** Per-channel node options (equals, resubscribable, ...). */
+    channelOpts?: {
+        [K in keyof TChannels]?: ExtraOpts;
+    };
+};
+/**
+ * Multi-channel variant — one `Node<T>` per named channel, sharing a single
+ * registrar. Activation is eager: the registrar runs at construction time so
+ * externally-owned servers (HTTP, UDP, queue consumers) can start accepting
+ * traffic immediately. The returned cleanup fires once every channel has been
+ * subscribed and then fully deactivated (refcount-on-teardown).
+ *
+ * Any call to `error` or `complete` propagates to every channel atomically.
+ *
+ * @param register - Installs handlers for each channel plus shared error/complete.
+ * @param channels - Ordered channel names; determines the returned object shape.
+ * @param opts - Optional name prefix and per-channel node options.
+ *
+ * @example
+ * ```ts
+ * import { externalBundle } from "@graphrefly/graphrefly-ts";
+ *
+ * type OTelChannels = { traces: Span; metrics: Metric; logs: LogRec };
+ * const otel = externalBundle<OTelChannels>(
+ *   ({ traces, metrics, logs, error }) => {
+ *     app.post("/v1/traces",  (req, res) => { traces(req.body);  res.sendStatus(200); });
+ *     app.post("/v1/metrics", (req, res) => { metrics(req.body); res.sendStatus(200); });
+ *     app.post("/v1/logs",    (req, res) => { logs(req.body);    res.sendStatus(200); });
+ *     server.on("error", error);
+ *     return () => server.close();
+ *   },
+ *   ["traces", "metrics", "logs"],
+ * );
+ * otel.traces.subscribe(...);
+ * ```
+ *
+ * @category extra
+ */
+declare function externalBundle<TChannels extends Record<string, unknown>>(register: ExternalRegister<BundleTriad<TChannels>>, channels: readonly (keyof TChannels & string)[], opts?: ExternalBundleOptions<TChannels>): {
+    [K in keyof TChannels]: Node<TChannels[K]>;
+} & {
+    dispose(): void;
+};
+
+export { type BundleTriad as B, type EmitTriad as E, type ExternalBundleOptions as a, type ExternalRegister as b, externalProducer as c, externalBundle as e };

package/dist/{fallback-74oxi34l.d.cts → fallback-Bx46zqky.d.cts}

@@ -1,6 +1,5 @@
-import { KvStorageTier } from './extra/storage-tiers.cjs';
-import { C as ChatMessage, a as LLMInvokeOptions, L as LLMAdapter, b as LLMResponse, S as StreamDelta } from './types-C0_yquda.cjs';
-import { d as canonicalJson$1 } from './content-addressed-storage-4-ST1tYk.cjs';
+import { KvStorageTier } from '@graphrefly/pure-ts/extra';
+import { a as ChatMessage, b as LLMInvokeOptions, L as LLMAdapter, c as LLMResponse, S as StreamDelta } from './types-BB5Lw-pB.cjs';
 
 /**
  * `withReplayCache` — content-addressed response cache over `KvStorageTier`.
@@ -86,12 +85,6 @@ interface WithReplayCacheOptions {
 }
 /** Wrap an adapter with a replay cache. */
 declare function withReplayCache(inner: LLMAdapter, opts: WithReplayCacheOptions): LLMAdapter;
-/**
- * Canonical JSON — re-exported from `src/extra/content-addressed-storage.ts`
- * so `fallbackAdapter` and other cache-adjacent code that historically
- * imported from here continue to work. Same behavior.
- */
-declare const canonicalJson: typeof canonicalJson$1;
 
 /**
  * `fallbackAdapter` — fixture-backed {@link LLMAdapter} for offline demos,
@@ -247,4 +240,4 @@ interface FallbackAdapterOptions {
  */
 declare function fallbackAdapter(opts?: FallbackAdapterOptions): LLMAdapter;
 
-export { type FallbackAdapterOptions as F, type ReplayCacheKeyContext as R, type WithReplayCacheOptions as W, type FallbackFixture as a, FallbackMissError as b, type FallbackMissPolicy as c, ReplayCacheMissError as d, type ReplayCacheMode as e, canonicalJson as f, fallbackAdapter as g, withReplayCache as w };
+export { type FallbackAdapterOptions as F, type ReplayCacheKeyContext as R, type WithReplayCacheOptions as W, type FallbackFixture as a, FallbackMissError as b, type FallbackMissPolicy as c, ReplayCacheMissError as d, type ReplayCacheMode as e, fallbackAdapter as f, withReplayCache as w };

package/dist/{fallback-DUyyBTBK.d.ts → fallback-pIWW8A2d.d.ts}

@@ -1,6 +1,5 @@
-import { KvStorageTier } from './extra/storage-tiers.js';
-import { C as ChatMessage, a as LLMInvokeOptions, L as LLMAdapter, b as LLMResponse, S as StreamDelta } from './types-CWFysE9E.js';
-import { d as canonicalJson$1 } from './content-addressed-storage-DuYMjV7o.js';
+import { KvStorageTier } from '@graphrefly/pure-ts/extra';
+import { a as ChatMessage, b as LLMInvokeOptions, L as LLMAdapter, c as LLMResponse, S as StreamDelta } from './types-BB5Lw-pB.js';
 
 /**
  * `withReplayCache` — content-addressed response cache over `KvStorageTier`.
@@ -86,12 +85,6 @@ interface WithReplayCacheOptions {
 }
 /** Wrap an adapter with a replay cache. */
 declare function withReplayCache(inner: LLMAdapter, opts: WithReplayCacheOptions): LLMAdapter;
-/**
- * Canonical JSON — re-exported from `src/extra/content-addressed-storage.ts`
- * so `fallbackAdapter` and other cache-adjacent code that historically
- * imported from here continue to work. Same behavior.
- */
-declare const canonicalJson: typeof canonicalJson$1;
 
 /**
  * `fallbackAdapter` — fixture-backed {@link LLMAdapter} for offline demos,
@@ -247,4 +240,4 @@ interface FallbackAdapterOptions {
  */
 declare function fallbackAdapter(opts?: FallbackAdapterOptions): LLMAdapter;
 
-export { type FallbackAdapterOptions as F, type ReplayCacheKeyContext as R, type WithReplayCacheOptions as W, type FallbackFixture as a, FallbackMissError as b, type FallbackMissPolicy as c, ReplayCacheMissError as d, type ReplayCacheMode as e, canonicalJson as f, fallbackAdapter as g, withReplayCache as w };
+export { type FallbackAdapterOptions as F, type ReplayCacheKeyContext as R, type WithReplayCacheOptions as W, type FallbackFixture as a, FallbackMissError as b, type FallbackMissPolicy as c, ReplayCacheMissError as d, type ReplayCacheMode as e, fallbackAdapter as f, withReplayCache as w };

package/dist/guarded-execution-BcdtxeBk.d.ts

@@ -0,0 +1,207 @@
+import { Node, Actor, PolicyRuleData } from '@graphrefly/pure-ts/core';
+import { Graph, GraphDescribeOutput, GraphOptions, GraphDescribeOptions } from '@graphrefly/pure-ts/graph';
+import { P as PolicyGateGraph, e as PolicyViolation } from './audit-BAXb3VOg.js';
+import { TopicGraph } from './utils/messaging/index.js';
+
+/**
+ * Composable safety layer (roadmap §9.0b — Tier 5.1 Wave-B rebuild).
+ *
+ * {@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.
+ *   Full transitive dynamic coverage via `watchTopologyTree`.
+ * - Reactive {@link GuardedExecutionGraph.scopedDescribeNode} — a thin
+ *   delegate over `target.describe({ reactive: true, actor })` that re-derives
+ *   on every settle (topology change, error transition, actor swap).
+ * - The enforcer's `violations` topic is republished as `violations` on
+ *   the wrapper, composable with {@link graphLens}'s `health`.
+ * - The wrapper-level `lints` topic surfaces non-policy diagnostic warnings
+ *   (`empty-policies` / `audit-no-effect` / `no-actor`) so misconfigurations
+ *   are caught reactively rather than via thrown errors at scattered call sites.
+ * - The `scope` derived publishes the current configuration tuple
+ *   (`{actor, mode, policiesCount}`) for dashboards.
+ *
+ * V1 scope: policies + actor + reactive scoped describe + lints + scope.
+ * 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
+ */
+
+/** Diagnostic warning published on {@link GuardedExecutionGraph.lints}. */
+interface GuardedExecutionLint {
+    /**
+     * - `"empty-policies"` — `policies` Node emitted an empty array in
+     *   `mode: "enforce"`. Static empty arrays throw at construction; this
+     *   covers the reactive case.
+     * - `"audit-no-effect"` — `mode: "audit"` plus the target has no per-node
+     *   guards, so `scopedDescribeNode` filters by per-node guards only and
+     *   policies will never gate visibility (they still populate `violations`
+     *   on writes).
+     * - `"no-actor"` — neither a wrapper-configured nor per-call actor was
+     *   supplied. `scopedDescribeNode` falls back to "describe everything"
+     *   for the corresponding subscription.
+     */
+    kind: "empty-policies" | "audit-no-effect" | "no-actor";
+    message: string;
+    timestamp_ns: number;
+}
+/** Configuration tuple published on {@link GuardedExecutionGraph.scope}. */
+interface GuardedScope {
+    /** The wrapper-configured default actor, or `null` when none configured. */
+    actor: Actor | null;
+    mode: "audit" | "enforce";
+    /** Current policy count (reactive — re-emits on `policies` Node updates). */
+    policiesCount: number;
+}
+/** Options for {@link guardedExecution}. */
+interface GuardedExecutionOptions {
+    /**
+     * Policies enforced against every guarded write. Static list or a live
+     * `Node<readonly PolicyRuleData[]>` (LLM-updatable).
+     *
+     * **Empty-policies handling:**
+     * - Static empty array + `mode: "enforce"` throws `RangeError` at
+     *   construction (deny-by-default is almost certainly a misconfiguration).
+     * - Node-supplied empty array + `mode: "enforce"` emits a one-time
+     *   `"empty-policies"` lint on first such emission (the wrapper can't
+     *   throw mid-run — surface the warning reactively).
+     * - `mode: "audit"` tolerates empty policies (no guards stacked; policies
+     *   only feed the `violations` channel on writes).
+     */
+    policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>;
+    /**
+     * Default actor used when the caller invokes
+     * {@link GuardedExecutionGraph.scopedDescribeNode} without an override.
+     * Accepts a static {@link Actor} or a `Node<Actor>` — when a Node is
+     * supplied, the reactive describe re-derives on every actor emission so
+     * harnesses binding a per-turn actor get a single live describe Node
+     * instead of re-creating one per turn.
+     *
+     * Omit to scope per-call only. A `"no-actor"` lint fires once per instance
+     * if neither a configured nor per-call actor is ever supplied (the
+     * resulting describe is unscoped — full visibility).
+     */
+    actor?: Actor | Node<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;
+    /** Ring-buffer cap for the `lints` topic. Default 64 — each lint kind fires at most once per instance. */
+    lintsLimit?: number;
+    /** Wrapper graph name. Default `${target.name}_guarded`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Wrapper over a target {@link Graph} providing reactive ABAC + reactive
+ * scoped describe + diagnostic lints. Mounts a {@link PolicyGateGraph} under
+ * `enforcer`, a {@link TopicGraph} of {@link GuardedExecutionLint} under
+ * `lints`, and a `scope` derived publishing `{actor, mode, policiesCount}`.
+ *
+ * @category patterns
+ */
+declare class GuardedExecutionGraph extends Graph {
+    readonly enforcer: PolicyGateGraph;
+    readonly violations: TopicGraph<PolicyViolation>;
+    readonly lints: TopicGraph<GuardedExecutionLint>;
+    readonly scope: Node<GuardedScope>;
+    /**
+     * Canonical reactive describe scoped to the wrapper's configured `actor`.
+     * Subscribes ONCE at construction; lifecycle owned by the wrapper (disposed
+     * on `wrapper.destroy()`). Use this property for the common case
+     * (long-lived consumer wanting "describe scoped to my actor"); use
+     * {@link scopedDescribeNode} only when a per-call actor override or
+     * different `detail`/`fields` is required.
+     *
+     * Re-derives on every settle of the target graph: structural changes,
+     * status transitions (errors flip nodes into `"errored"`), and actor
+     * emissions (when a `Node<Actor>` is bound, including the SENTINEL bridge
+     * applied internally — see qa G1B).
+     */
+    readonly scopedDescribe: Node<GraphDescribeOutput>;
+    private readonly _target;
+    private readonly _actorNode;
+    private readonly _mode;
+    private readonly _firedLintKinds;
+    constructor(target: Graph, opts: GuardedExecutionOptions);
+    private _fireLint;
+    /**
+     * **Per-call escape hatch.** Prefer {@link scopedDescribe} (the mounted
+     * property) for the common case of "describe scoped to my actor." Use
+     * this method ONLY when you need a per-call actor override or different
+     * `detail`/`fields`/`filter`.
+     *
+     * Returns a live `Node<GraphDescribeOutput>` scoped to the supplied (or
+     * configured) actor, plus an explicit `dispose` for caller-controlled
+     * lifecycle. Re-derives on every settle of the target graph: structural
+     * changes, status transitions, and actor emissions (when a `Node<Actor>`
+     * is bound).
+     *
+     * **Lifecycle (qa G1A — EC1 fix).** Each call instantiates a fresh
+     * `target.describe({reactive: true})` handle (with its own version state,
+     * observe handle, transitive topology subscriptions, derived + keepalive).
+     * The caller MUST invoke the returned `dispose()` when finished to release
+     * these resources. Disposers ARE also tracked on the wrapper graph so
+     * `wrapper.destroy()` cleans up any handles the caller forgot — but a
+     * long-lived wrapper with heavy per-call usage will leak until destroy
+     * unless `dispose()` is called explicitly.
+     *
+     * @param actorOverride - Optional per-call override. Static {@link Actor}
+     *   or `Node<Actor>`. Omit to use the wrapper-configured default.
+     * @param opts - Standard {@link GraphDescribeOptions} fields (`detail`,
+     *   `fields`, `filter`). `actor` / `reactive` / `reactiveName` are
+     *   controlled by the wrapper.
+     * @returns `{node, dispose}` — `node` is the live describe Node; `dispose`
+     *   tears down the underlying reactive describe subscription idempotently.
+     */
+    scopedDescribeNode(actorOverride?: Actor | Node<Actor>, opts?: Omit<GraphDescribeOptions, "actor" | "reactive" | "reactiveName">): {
+        node: Node<GraphDescribeOutput>;
+        dispose: () => void;
+    };
+    /** The wrapped graph (escape hatch for tooling). */
+    get target(): Graph;
+}
+/**
+ * Wrap a {@link Graph} with {@link policyGate} plus a reactive 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: node<Actor>([], { initial: { type: "human", id: "alice" } }), // reactive — re-derive on swap
+ *   policies: [
+ *     { effect: "allow", action: "read", actorType: "human" },
+ *     { effect: "deny", action: "write", pathPattern: "system::*" },
+ *   ],
+ *   mode: "enforce",
+ * });
+ *
+ * // Canonical: subscribe to the mounted reactive describe (no per-call leak).
+ * guarded.scopedDescribe.subscribe((msgs) => { /* live describe per actor / topology change *\/ });
+ * // Per-call escape hatch (different actor / detail) — caller manages dispose.
+ * const detailed = guarded.scopedDescribeNode(undefined, { detail: "standard" });
+ * try { detailed.node.subscribe(/* … *\/); } finally { detailed.dispose(); }
+ * guarded.violations.events.subscribe(msgs => console.log("violations:", msgs));
+ * guarded.lints.events.subscribe(msgs => console.warn("lints:", msgs));
+ * guarded.scope.subscribe(msgs => console.log("scope:", msgs));
+ * ```
+ *
+ * @category patterns
+ */
+declare function guardedExecution(target: Graph, opts: GuardedExecutionOptions): GuardedExecutionGraph;
+
+export { GuardedExecutionGraph as G, type GuardedExecutionLint as a, type GuardedExecutionOptions as b, type GuardedScope as c, guardedExecution as g };