@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/{index-DlLp-2Xn.d.cts → index-B-8FCEua.d.cts}

@@ -1,8 +1,9 @@
-import { T as ToObservableOptions, t as toObservable } from './observable-DJt_AxzQ.cjs';
+import { T as ToObservableOptions, t as toObservable } from './observable-kwzpLvbi.cjs';
 import { OnModuleInit, OnModuleDestroy, ExecutionContext, CanActivate, DynamicModule } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
-import { a as Graph, G as GraphOptions, s as GraphPersistSnapshot } from './graph-DNCrvZSn.cjs';
-import { A as Actor, N as Node } from './node-BmerH3kS.cjs';
+import { G as Graph, d as GraphPersistSnapshot } from './graph-DgohqXK-.cjs';
+import { A as Actor } from './node-Dd6wHSib.cjs';
+import { C as CqrsOptions, a as CqrsGraph, E as EventStoreAdapter } from './index-vgcLF5TH.cjs';
 
 /** Class constructor key for decorator registries and Nest `ModuleRef.get()`. */
 type DecoratorHostConstructor = abstract new (...args: unknown[]) => unknown;
@@ -192,7 +193,7 @@ declare function GraphCron(expr: string): (value: DecoratorBoundMethod, context:
  * }
  * ```
  */
-declare function CommandHandler$1(cqrsName: string, commandName: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+declare function CommandHandler(cqrsName: string, commandName: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
 /**
  * Subscribe a method to CQRS event stream DATA — replaces `@EventsHandler()` from `@nestjs/cqrs`.
  *
@@ -256,7 +257,7 @@ declare function QueryHandler(cqrsName: string, projectionName: string): (value:
  * }
  * ```
  */
-declare function SagaHandler$1(cqrsName: string, sagaName: string, eventNames: readonly string[]): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+declare function SagaHandler(cqrsName: string, sagaName: string, eventNames: readonly string[]): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
 
 declare class GraphReflyEventExplorer implements OnModuleInit, OnModuleDestroy {
     private readonly graph;
@@ -579,194 +580,6 @@ declare class GraphReflyGuardImpl implements CanActivate {
  */
 declare function GraphReflyGuard(extractor?: ActorExtractor): GraphReflyGuardImpl;
 
-/**
- * CQRS patterns (roadmap §4.5).
- *
- * Composition layer over reactiveLog (3.2), pipeline/sagas (4.1), event bus (4.2),
- * projections (4.3). Guards (1.5) enforce command/query boundary.
- *
- * - `cqrs(name, opts?)` → `CqrsGraph` — top-level factory
- * - `CqrsGraph.command(name, handler)` — write-only node; guard rejects `observe`
- * - `CqrsGraph.event(name)` — backed by `reactiveLog`; append-only
- * - `CqrsGraph.projection(name, events, reducer, initial)` — read-only derived; guard rejects `write`
- * - `CqrsGraph.saga(name, events, handler)` — event-driven side effects
- */
-
-/**
- * Immutable envelope for events emitted by command handlers.
- *
- * `seq` is a per-graph monotonic counter that provides stable ordering when
- * multiple events share the same `timestampNs` (same wall-clock tick).
- */
-type CqrsEvent<T = unknown> = {
-    type: string;
-    payload: T;
-    /** Wall-clock nanoseconds (via `wallClockNs()`). */
-    timestampNs: number;
-    /** Monotonic sequence within this CqrsGraph instance. */
-    seq: number;
-    /** V0 identity of the event log node at append time (§6.0b). */
-    v0?: {
-        id: string;
-        version: number;
-    };
-};
-/**
- * Opaque replay cursor returned by `loadEvents`. Pass it back to
- * `loadEvents` to resume from the last position.
- */
-type EventStoreCursor = {
-    readonly __brand?: "EventStoreCursor";
-    [key: string]: unknown;
-};
-/**
- * Result of `loadEvents` — events plus an opaque cursor for resumption.
- */
-type LoadEventsResult = {
-    events: CqrsEvent[];
-    cursor: EventStoreCursor | undefined;
-};
-/**
- * Pluggable persistence for CQRS events.
- *
- * **`persist`:** Must be synchronous. Called from the dispatch path inside
- * `batch()`. Adapters that need async I/O should buffer internally and
- * expose a `flush()` method for explicit drain.
- */
-interface EventStoreAdapter {
-    persist(event: CqrsEvent): void;
-    /**
-     * Load persisted events. When `cursor` is provided, returns only events
-     * after that position. The returned `cursor` should be passed to the next
-     * `loadEvents` call for incremental replay.
-     */
-    loadEvents(eventType: string, cursor?: EventStoreCursor): LoadEventsResult | Promise<LoadEventsResult>;
-    /** Optional explicit flush for adapters with async I/O. */
-    flush?(): Promise<void>;
-}
-declare class MemoryEventStore implements EventStoreAdapter {
-    private readonly _store;
-    persist(event: CqrsEvent): void;
-    loadEvents(eventType: string, cursor?: EventStoreCursor): LoadEventsResult;
-    clear(): void;
-}
-type CommandActions = {
-    /** Append an event to a named event log (bypasses event guard). */
-    emit: (eventName: string, payload: unknown) => void;
-};
-/**
- * Command handler receives the dispatch payload and actions to emit events.
- *
- * **Purity:** Handlers should not mutate the payload. Event emission via
- * `actions.emit()` is the only sanctioned side effect.
- */
-type CommandHandler<T = unknown> = (payload: T, actions: CommandActions) => void;
-/**
- * Projection reducer folds events into a read model.
- *
- * **Purity contract:** Reducers MUST be pure — return a new state value
- * without mutating `state` or any event. The `state` parameter is the
- * original `initial` value on every invocation (full event-sourcing replay),
- * so mutation would corrupt future recomputations.
- */
-type ProjectionReducer<TState = unknown, TEvent = unknown> = (state: TState, events: readonly CqrsEvent<TEvent>[]) => TState;
-type SagaHandler<T = unknown> = (event: CqrsEvent<T>) => void;
-type CqrsOptions = {
-    graph?: GraphOptions;
-};
-declare class CqrsGraph extends Graph {
-    private readonly _eventLogs;
-    private readonly _commandHandlers;
-    private readonly _projections;
-    private readonly _sagas;
-    private readonly _keepaliveDisposers;
-    private _eventStore;
-    private _seq;
-    constructor(name: string, opts?: CqrsOptions);
-    destroy(): void;
-    /**
-     * Register a named event stream backed by `reactiveLog`.
-     * Guard denies external `write` — only commands append internally.
-     */
-    event(name: string): Node<readonly CqrsEvent[]>;
-    /** Internal: append to an event log, auto-registering if needed. */
-    private _appendEvent;
-    /**
-     * Register a command with its handler. Guard denies `observe` (write-only).
-     * Use `dispatch(name, payload)` to execute.
-     *
-     * The command node carries dynamic `meta.error` — a reactive companion
-     * that holds the last handler error (or `null` on success).
-     */
-    command<T = unknown>(name: string, handler: CommandHandler<T>): Node<T>;
-    /**
-     * Execute a registered command. Wraps the entire dispatch in `batch()` so
-     * the command node DATA and all emitted events settle atomically.
-     *
-     * If the handler throws, `meta.error` on the command node is set to the
-     * error and the exception is re-thrown.
-     */
-    dispatch<T = unknown>(commandName: string, payload: T): void;
-    /**
-     * Register a read-only projection derived from event streams.
-     * Guard denies `write` — value is computed from events only.
-     *
-     * **Purity contract:** The `reducer` must be a pure function — it receives
-     * the original `initial` on every invocation (full event-sourcing replay).
-     * Never mutate `initial`; always return a new value.
-     */
-    projection<TState>(name: string, eventNames: readonly string[], reducer: ProjectionReducer<TState>, initial: TState): Node<TState>;
-    /**
-     * Register an event-driven side effect. Runs handler for each **new** event
-     * from the specified streams (tracks last-processed entry count per stream).
-     *
-     * The saga node carries dynamic `meta.error` — a reactive companion that
-     * holds the last handler error (or `null` on success). Handler errors do
-     * not propagate out of the saga run (the event cursor still advances so
-     * the same entry is not delivered twice).
-     */
-    saga<T = unknown>(name: string, eventNames: readonly string[], handler: SagaHandler<T>): Node<unknown>;
-    useEventStore(adapter: EventStoreAdapter): void;
-    /**
-     * Replay persisted events through a reducer to rebuild a read model.
-     * Requires an event store adapter wired via `useEventStore()`.
-     */
-    rebuildProjection<TState>(eventNames: readonly string[], reducer: ProjectionReducer<TState>, initial: TState): Promise<TState>;
-}
-/**
- * Create a CQRS graph container.
- *
- * @example
- * ```ts
- * const app = cqrs("orders");
- * app.event("orderPlaced");
- * app.command("placeOrder", (payload, { emit }) => {
- *   emit("orderPlaced", { orderId: payload.id, amount: payload.amount });
- * });
- * app.projection("orderCount", ["orderPlaced"], (_s, events) => events.length, 0);
- * app.dispatch("placeOrder", { id: "1", amount: 100 });
- * ```
- */
-declare function cqrs(name: string, opts?: CqrsOptions): CqrsGraph;
-
-type cqrs$1_CommandActions = CommandActions;
-type cqrs$1_CommandHandler<T = unknown> = CommandHandler<T>;
-type cqrs$1_CqrsEvent<T = unknown> = CqrsEvent<T>;
-type cqrs$1_CqrsGraph = CqrsGraph;
-declare const cqrs$1_CqrsGraph: typeof CqrsGraph;
-type cqrs$1_CqrsOptions = CqrsOptions;
-type cqrs$1_EventStoreAdapter = EventStoreAdapter;
-type cqrs$1_EventStoreCursor = EventStoreCursor;
-type cqrs$1_LoadEventsResult = LoadEventsResult;
-type cqrs$1_MemoryEventStore = MemoryEventStore;
-declare const cqrs$1_MemoryEventStore: typeof MemoryEventStore;
-type cqrs$1_ProjectionReducer<TState = unknown, TEvent = unknown> = ProjectionReducer<TState, TEvent>;
-type cqrs$1_SagaHandler<T = unknown> = SagaHandler<T>;
-declare const cqrs$1_cqrs: typeof cqrs;
-declare namespace cqrs$1 {
-  export { type cqrs$1_CommandActions as CommandActions, type cqrs$1_CommandHandler as CommandHandler, type cqrs$1_CqrsEvent as CqrsEvent, cqrs$1_CqrsGraph as CqrsGraph, type cqrs$1_CqrsOptions as CqrsOptions, type cqrs$1_EventStoreAdapter as EventStoreAdapter, type cqrs$1_EventStoreCursor as EventStoreCursor, type cqrs$1_LoadEventsResult as LoadEventsResult, cqrs$1_MemoryEventStore as MemoryEventStore, type cqrs$1_ProjectionReducer as ProjectionReducer, type cqrs$1_SagaHandler as SagaHandler, cqrs$1_cqrs as cqrs };
-}
-
 interface GraphReflyRootOptions {
     /** Root graph name (default: `"root"`). */
     name?: string;
@@ -884,6 +697,7 @@ type index_ActorExtractor = ActorExtractor;
 declare const index_COMMAND_HANDLERS: typeof COMMAND_HANDLERS;
 declare const index_CQRS_EVENT_HANDLERS: typeof CQRS_EVENT_HANDLERS;
 declare const index_CRON_HANDLERS: typeof CRON_HANDLERS;
+declare const index_CommandHandler: typeof CommandHandler;
 type index_CommandHandlerMeta = CommandHandlerMeta;
 declare const index_EVENT_HANDLERS: typeof EVENT_HANDLERS;
 declare const index_EventHandler: typeof EventHandler;
@@ -921,6 +735,7 @@ declare const index_QUERY_HANDLERS: typeof QUERY_HANDLERS;
 declare const index_QueryHandler: typeof QueryHandler;
 type index_QueryHandlerMeta = QueryHandlerMeta;
 declare const index_SAGA_HANDLERS: typeof SAGA_HANDLERS;
+declare const index_SagaHandler: typeof SagaHandler;
 type index_SagaHandlerMeta = SagaHandlerMeta;
 declare const index_ToObservableOptions: typeof ToObservableOptions;
 declare const index_fromHeader: typeof fromHeader;
@@ -932,7 +747,7 @@ declare const index_observeSSE: typeof observeSSE;
 declare const index_observeSubscription: typeof observeSubscription;
 declare const index_toObservable: typeof toObservable;
 declare namespace index {
-  export { index_ACTOR_KEY as ACTOR_KEY, type index_ActorExtractor as ActorExtractor, index_COMMAND_HANDLERS as COMMAND_HANDLERS, index_CQRS_EVENT_HANDLERS as CQRS_EVENT_HANDLERS, index_CRON_HANDLERS as CRON_HANDLERS, CommandHandler$1 as CommandHandler, type index_CommandHandlerMeta as CommandHandlerMeta, index_EVENT_HANDLERS as EVENT_HANDLERS, index_EventHandler as EventHandler, type index_EventHandlerMeta as EventHandlerMeta, index_GRAPHREFLY_REQUEST_GRAPH as GRAPHREFLY_REQUEST_GRAPH, index_GRAPHREFLY_ROOT_GRAPH as GRAPHREFLY_ROOT_GRAPH, index_GraphCron as GraphCron, type index_GraphCronMeta as GraphCronMeta, index_GraphInterval as GraphInterval, type index_GraphIntervalMeta as GraphIntervalMeta, type index_GraphReflyCqrsOptions as GraphReflyCqrsOptions, index_GraphReflyEventExplorer as GraphReflyEventExplorer, type index_GraphReflyFeatureOptions as GraphReflyFeatureOptions, index_GraphReflyGuard as GraphReflyGuard, index_GraphReflyGuardImpl as GraphReflyGuardImpl, index_GraphReflyModule as GraphReflyModule, type index_GraphReflyRootOptions as GraphReflyRootOptions, index_INTERVAL_HANDLERS as INTERVAL_HANDLERS, index_InjectCqrsGraph as InjectCqrsGraph, index_InjectGraph as InjectGraph, index_InjectNode as InjectNode, index_ObserveGateway as ObserveGateway, type index_ObserveGatewayOptions as ObserveGatewayOptions, type index_ObserveSSEOptions as ObserveSSEOptions, type index_ObserveSubscriptionOptions as ObserveSubscriptionOptions, type index_ObserveWsCommand as ObserveWsCommand, type index_ObserveWsMessage as ObserveWsMessage, index_OnGraphEvent as OnGraphEvent, type index_OnGraphEventMeta as OnGraphEventMeta, index_QUERY_HANDLERS as QUERY_HANDLERS, index_QueryHandler as QueryHandler, type index_QueryHandlerMeta as QueryHandlerMeta, index_SAGA_HANDLERS as SAGA_HANDLERS, SagaHandler$1 as SagaHandler, type index_SagaHandlerMeta as SagaHandlerMeta, index_ToObservableOptions as ToObservableOptions, index_fromHeader as fromHeader, index_fromJwtPayload as fromJwtPayload, index_getActor as getActor, index_getGraphToken as getGraphToken, index_getNodeToken as getNodeToken, index_observeSSE as observeSSE, index_observeSubscription as observeSubscription, index_toObservable as toObservable };
+  export { index_ACTOR_KEY as ACTOR_KEY, type index_ActorExtractor as ActorExtractor, index_COMMAND_HANDLERS as COMMAND_HANDLERS, index_CQRS_EVENT_HANDLERS as CQRS_EVENT_HANDLERS, index_CRON_HANDLERS as CRON_HANDLERS, index_CommandHandler as CommandHandler, type index_CommandHandlerMeta as CommandHandlerMeta, index_EVENT_HANDLERS as EVENT_HANDLERS, index_EventHandler as EventHandler, type index_EventHandlerMeta as EventHandlerMeta, index_GRAPHREFLY_REQUEST_GRAPH as GRAPHREFLY_REQUEST_GRAPH, index_GRAPHREFLY_ROOT_GRAPH as GRAPHREFLY_ROOT_GRAPH, index_GraphCron as GraphCron, type index_GraphCronMeta as GraphCronMeta, index_GraphInterval as GraphInterval, type index_GraphIntervalMeta as GraphIntervalMeta, type index_GraphReflyCqrsOptions as GraphReflyCqrsOptions, index_GraphReflyEventExplorer as GraphReflyEventExplorer, type index_GraphReflyFeatureOptions as GraphReflyFeatureOptions, index_GraphReflyGuard as GraphReflyGuard, index_GraphReflyGuardImpl as GraphReflyGuardImpl, index_GraphReflyModule as GraphReflyModule, type index_GraphReflyRootOptions as GraphReflyRootOptions, index_INTERVAL_HANDLERS as INTERVAL_HANDLERS, index_InjectCqrsGraph as InjectCqrsGraph, index_InjectGraph as InjectGraph, index_InjectNode as InjectNode, index_ObserveGateway as ObserveGateway, type index_ObserveGatewayOptions as ObserveGatewayOptions, type index_ObserveSSEOptions as ObserveSSEOptions, type index_ObserveSubscriptionOptions as ObserveSubscriptionOptions, type index_ObserveWsCommand as ObserveWsCommand, type index_ObserveWsMessage as ObserveWsMessage, index_OnGraphEvent as OnGraphEvent, type index_OnGraphEventMeta as OnGraphEventMeta, index_QUERY_HANDLERS as QUERY_HANDLERS, index_QueryHandler as QueryHandler, type index_QueryHandlerMeta as QueryHandlerMeta, index_SAGA_HANDLERS as SAGA_HANDLERS, index_SagaHandler as SagaHandler, type index_SagaHandlerMeta as SagaHandlerMeta, index_ToObservableOptions as ToObservableOptions, index_fromHeader as fromHeader, index_fromJwtPayload as fromJwtPayload, index_getActor as getActor, index_getGraphToken as getGraphToken, index_getNodeToken as getNodeToken, index_observeSSE as observeSSE, index_observeSubscription as observeSubscription, index_toObservable as toObservable };
 }
 
-export { ACTOR_KEY as A, type ObserveSubscriptionOptions as B, COMMAND_HANDLERS as C, type ObserveWsCommand as D, EVENT_HANDLERS as E, type ObserveWsMessage as F, GRAPHREFLY_REQUEST_GRAPH as G, OnGraphEvent as H, INTERVAL_HANDLERS as I, type OnGraphEventMeta as J, QueryHandler as K, type QueryHandlerMeta as L, SagaHandler$1 as M, type SagaHandlerMeta as N, ObserveGateway as O, fromHeader as P, QUERY_HANDLERS as Q, fromJwtPayload as R, SAGA_HANDLERS as S, getActor as T, getGraphToken as U, getNodeToken as V, observeSSE as W, observeSubscription as X, type ActorExtractor as a, CQRS_EVENT_HANDLERS as b, cqrs$1 as c, CRON_HANDLERS as d, CommandHandler$1 as e, type CommandHandlerMeta as f, EventHandler as g, type EventHandlerMeta as h, index as i, GRAPHREFLY_ROOT_GRAPH as j, GraphCron as k, type GraphCronMeta as l, GraphInterval as m, type GraphIntervalMeta as n, type GraphReflyCqrsOptions as o, GraphReflyEventExplorer as p, type GraphReflyFeatureOptions as q, GraphReflyGuard as r, GraphReflyGuardImpl as s, GraphReflyModule as t, type GraphReflyRootOptions as u, InjectCqrsGraph as v, InjectGraph as w, InjectNode as x, type ObserveGatewayOptions as y, type ObserveSSEOptions as z };
+export { ACTOR_KEY as A, type ObserveWsCommand as B, COMMAND_HANDLERS as C, type ObserveWsMessage as D, EVENT_HANDLERS as E, OnGraphEvent as F, GRAPHREFLY_REQUEST_GRAPH as G, type OnGraphEventMeta as H, INTERVAL_HANDLERS as I, QueryHandler as J, type QueryHandlerMeta as K, SagaHandler as L, type SagaHandlerMeta as M, fromHeader as N, ObserveGateway as O, fromJwtPayload as P, QUERY_HANDLERS as Q, getActor as R, SAGA_HANDLERS as S, getGraphToken as T, getNodeToken as U, observeSSE as V, observeSubscription as W, type ActorExtractor as a, CQRS_EVENT_HANDLERS as b, CRON_HANDLERS as c, CommandHandler as d, type CommandHandlerMeta as e, EventHandler as f, type EventHandlerMeta as g, GRAPHREFLY_ROOT_GRAPH as h, index as i, GraphCron as j, type GraphCronMeta as k, GraphInterval as l, type GraphIntervalMeta as m, type GraphReflyCqrsOptions as n, GraphReflyEventExplorer as o, type GraphReflyFeatureOptions as p, GraphReflyGuard as q, GraphReflyGuardImpl as r, GraphReflyModule as s, type GraphReflyRootOptions as t, InjectCqrsGraph as u, InjectGraph as v, InjectNode as w, type ObserveGatewayOptions as x, type ObserveSSEOptions as y, type ObserveSubscriptionOptions as z };

package/dist/index-B-gqvYel.d.ts

@@ -0,0 +1,135 @@
+import { P as PolicyRuleData, a as Node, A as Actor } from './node-Dd6wHSib.js';
+import { G as Graph, a as GraphOptions, b as GraphDescribeOptions, c as GraphDescribeOutput, D as DescribeFilter } from './graph-Qjg9gWHI.js';
+import { P as PolicyEnforcerGraph, a as PolicyViolation } from './index-CiaVoZGo.js';
+import { T as TopicGraph } from './index-DuB5aO4-.js';
+
+/**
+ * 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/index-B2PRuolf.d.cts

@@ -0,0 +1,86 @@
+import { a as Node } from './node-Dd6wHSib.cjs';
+import { G as Graph, a as GraphOptions } from './graph-DgohqXK-.cjs';
+
+/**
+ * Job queue patterns (roadmap §4.2).
+ *
+ * Queue / flow primitives modeled as graph factories:
+ * - `jobQueue()` — claim/ack/nack workflow with reactive depth.
+ * - `jobFlow()` — multi-stage queue chain.
+ *
+ * Topic / subscription / hub primitives live in `patterns/messaging`.
+ */
+
+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>[];
+}
+/**
+ * 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>;
+
+type index_JobEnvelope<T> = JobEnvelope<T>;
+type index_JobFlowGraph<T> = JobFlowGraph<T>;
+declare const index_JobFlowGraph: typeof JobFlowGraph;
+type index_JobFlowOptions = JobFlowOptions;
+type index_JobQueueGraph<T> = JobQueueGraph<T>;
+declare const index_JobQueueGraph: typeof JobQueueGraph;
+type index_JobQueueOptions = JobQueueOptions;
+type index_JobState = JobState;
+declare const index_jobFlow: typeof jobFlow;
+declare const index_jobQueue: typeof jobQueue;
+declare namespace index {
+  export { type index_JobEnvelope as JobEnvelope, index_JobFlowGraph as JobFlowGraph, type index_JobFlowOptions as JobFlowOptions, index_JobQueueGraph as JobQueueGraph, type index_JobQueueOptions as JobQueueOptions, type index_JobState as JobState, index_jobFlow as jobFlow, index_jobQueue as jobQueue };
+}
+
+export { type JobEnvelope as J, JobFlowGraph as a, type JobFlowOptions as b, JobQueueGraph as c, type JobQueueOptions as d, type JobState as e, jobQueue as f, index as i, jobFlow as j };