@graphrefly/graphrefly 0.1.0

package/dist/index-D_geH2Bm.d.cts

@@ -0,0 +1,940 @@
+import { R as ReactiveLogSnapshot, o as observeGraph$, c as observeNode$, t as toMessages$, d as toObservable } from './reactive-log-BfvfNWQh.cjs';
+import { OnModuleInit, OnModuleDestroy, ExecutionContext, CanActivate, DynamicModule } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { G as Graph, a as GraphOptions, q as GraphPersistSnapshot } from './graph-CL_ZDAj9.cjs';
+import { A as Actor, N as Node } from './meta-BsF6Sag9.cjs';
+
+/** Class constructor key for decorator registries and Nest `ModuleRef.get()`. */
+type DecoratorHostConstructor = abstract new (...args: unknown[]) => unknown;
+/**
+ * TC39 Stage 3 class method decorator first argument (the method itself).
+ * Narrower than `Function` for Biome `noBannedTypes`.
+ */
+type DecoratorBoundMethod = (...args: unknown[]) => unknown;
+interface OnGraphEventMeta {
+    nodeName: string;
+    methodKey: string | symbol;
+}
+interface GraphIntervalMeta {
+    ms: number;
+    methodKey: string | symbol;
+}
+interface GraphCronMeta {
+    expr: string;
+    methodKey: string | symbol;
+}
+/** Registry: constructor → event handler metadata. */
+declare const EVENT_HANDLERS: Map<DecoratorHostConstructor, OnGraphEventMeta[]>;
+/** Registry: constructor → interval metadata. */
+declare const INTERVAL_HANDLERS: Map<DecoratorHostConstructor, GraphIntervalMeta[]>;
+/** Registry: constructor → cron metadata. */
+declare const CRON_HANDLERS: Map<DecoratorHostConstructor, GraphCronMeta[]>;
+interface CommandHandlerMeta {
+    cqrsName: string;
+    commandName: string;
+    methodKey: string | symbol;
+}
+interface EventHandlerMeta {
+    cqrsName: string;
+    eventName: string;
+    methodKey: string | symbol;
+}
+interface QueryHandlerMeta {
+    cqrsName: string;
+    projectionName: string;
+    methodKey: string | symbol;
+}
+interface SagaHandlerMeta {
+    cqrsName: string;
+    eventNames: readonly string[];
+    sagaName: string;
+    methodKey: string | symbol;
+}
+/** Registry: constructor → command handler metadata. */
+declare const COMMAND_HANDLERS: Map<DecoratorHostConstructor, CommandHandlerMeta[]>;
+/** Registry: constructor → event handler metadata. */
+declare const CQRS_EVENT_HANDLERS: Map<DecoratorHostConstructor, EventHandlerMeta[]>;
+/** Registry: constructor → query handler metadata. */
+declare const QUERY_HANDLERS: Map<DecoratorHostConstructor, QueryHandlerMeta[]>;
+/** Registry: constructor → saga handler metadata. */
+declare const SAGA_HANDLERS: Map<DecoratorHostConstructor, SagaHandlerMeta[]>;
+/**
+ * Inject a `Graph` instance into a NestJS service or controller.
+ *
+ * - No argument → injects the root graph (from `forRoot()`).
+ * - With `name` → injects the named feature graph (from `forFeature({ name })`).
+ * - With `"request"` → injects the request-scoped graph (requires `requestScope: true`).
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class PaymentService {
+ *   constructor(
+ *     @InjectGraph() private root: Graph,
+ *     @InjectGraph("payments") private payments: Graph,
+ *   ) {}
+ * }
+ * ```
+ */
+declare function InjectGraph(name?: string): ParameterDecorator & PropertyDecorator;
+/**
+ * Inject a `CqrsGraph` instance into a NestJS service or controller.
+ *
+ * Typed alternative to `@InjectGraph(name)` — returns `CqrsGraph` instead of `Graph`,
+ * giving access to `.command()`, `.dispatch()`, `.event()`, `.projection()`, `.saga()`.
+ *
+ * @param name - The CQRS graph name (from `forCqrs({ name })`).
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class OrderService {
+ *   constructor(@InjectCqrsGraph("orders") private orders: CqrsGraph) {
+ *     orders.dispatch("placeOrder", { id: "1" }); // fully typed
+ *   }
+ * }
+ * ```
+ */
+declare function InjectCqrsGraph(name: string): ParameterDecorator & PropertyDecorator;
+/**
+ * Inject a `Node` from the graph by its qualified path.
+ *
+ * The path must be declared in the `nodes` array of `forRoot()` or `forFeature()`.
+ * The module registers a factory provider that resolves the node from the root graph
+ * at injection time.
+ *
+ * @example
+ * ```ts
+ * GraphReflyModule.forRoot({ nodes: ["payment::validate"] })
+ *
+ * @Injectable()
+ * export class PaymentService {
+ *   constructor(@InjectNode("payment::validate") private validate: Node<boolean>) {}
+ * }
+ * ```
+ */
+declare function InjectNode(path: string): ParameterDecorator & PropertyDecorator;
+/**
+ * Subscribe a method to a graph node's DATA emissions — replaces `@OnEvent()`.
+ *
+ * The method is called with the value payload on each `DATA` message from the
+ * named node. Routes through `graph.observe()` so actor guards are respected.
+ * Subscription is created on module init and disposed on destroy.
+ *
+ * For full protocol access (DIRTY, COMPLETE, ERROR, custom types), use
+ * `graph.observe()` directly instead of this decorator.
+ *
+ * @param nodeName - Qualified node path (e.g. `"orders::placed"`).
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class OrderService {
+ *   @OnGraphEvent("orders::placed")
+ *   handleOrder(value: Order) { ... }
+ * }
+ * ```
+ */
+declare function OnGraphEvent(nodeName: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+/**
+ * Run a method on a fixed interval — replaces `@Interval()` from `@nestjs/schedule`.
+ *
+ * Backed by a `fromTimer` node added to the root graph as `__schedule__.<className>.<methodName>`.
+ * Visible in `graph.describe()`, pausable via `graph.signal(name, [[PAUSE]])`.
+ *
+ * @param ms - Interval in milliseconds.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class CleanupService {
+ *   @GraphInterval(5000)
+ *   pruneStale() { ... }
+ * }
+ * ```
+ */
+declare function GraphInterval(ms: number): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+/**
+ * Run a method on a cron schedule — replaces `@Cron()` from `@nestjs/schedule`.
+ *
+ * Backed by a `fromCron` node added to the root graph as `__schedule__.<className>.<methodName>`.
+ * Visible in `graph.describe()`, pausable via PAUSE/RESUME signals.
+ *
+ * @param expr - 5-field cron expression (`min hour dom month dow`).
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class ReportService {
+ *   @GraphCron("0 9 * * 1")
+ *   weeklyReport() { ... }
+ * }
+ * ```
+ */
+declare function GraphCron(expr: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+/**
+ * Register a method as a CQRS command handler — replaces `@CommandHandler()` from `@nestjs/cqrs`.
+ *
+ * The method receives `(payload, { emit })` — same signature as `CqrsGraph.command()` handlers.
+ * Wired reactively via the explorer on module init.
+ *
+ * @param cqrsName - Name of the CQRS graph (from `forCqrs({ name })`).
+ * @param commandName - Command to handle.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class OrderService {
+ *   @CommandHandler("orders", "placeOrder")
+ *   handlePlace(payload: PlaceOrderDto, { emit }: CommandActions) {
+ *     emit("orderPlaced", { orderId: payload.id, amount: payload.amount });
+ *   }
+ * }
+ * ```
+ */
+declare function CommandHandler$1(cqrsName: string, commandName: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+/**
+ * Subscribe a method to CQRS event stream DATA — replaces `@EventsHandler()` from `@nestjs/cqrs`.
+ *
+ * The method receives each `CqrsEvent` envelope as events arrive. Subscription is reactive
+ * via `graph.observe()` — actor guards are respected.
+ *
+ * @param cqrsName - Name of the CQRS graph.
+ * @param eventName - Event stream to subscribe to.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class NotificationService {
+ *   @EventHandler("orders", "orderPlaced")
+ *   onOrderPlaced(event: CqrsEvent<{ orderId: string }>) {
+ *     console.log("Order placed:", event.payload.orderId);
+ *   }
+ * }
+ * ```
+ */
+declare function EventHandler(cqrsName: string, eventName: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+/**
+ * Subscribe a method to CQRS projection changes — replaces `@QueryHandler()` from `@nestjs/cqrs`.
+ *
+ * The method is called reactively whenever the projection's value changes (DATA emission).
+ * This is push-based, not request-response — the projection recomputes on upstream events.
+ *
+ * @param cqrsName - Name of the CQRS graph.
+ * @param projectionName - Projection to observe.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class DashboardService {
+ *   @QueryHandler("orders", "orderCount")
+ *   onCountChanged(count: number) {
+ *     this.broadcast({ type: "orderCount", value: count });
+ *   }
+ * }
+ * ```
+ */
+declare function QueryHandler(cqrsName: string, projectionName: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+/**
+ * Register a method as a CQRS saga — replaces RxJS saga streams from `@nestjs/cqrs`.
+ *
+ * The method receives each new `CqrsEvent` from the specified event streams. Backed by
+ * `CqrsGraph.saga()` — tracks last-processed entry, only delivers new events.
+ *
+ * @param cqrsName - Name of the CQRS graph.
+ * @param sagaName - Name for this saga node in the graph.
+ * @param eventNames - Event streams to react to.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class FulfillmentService {
+ *   @SagaHandler("orders", "fulfillment", ["orderPlaced", "paymentConfirmed"])
+ *   onOrderFlow(event: CqrsEvent) {
+ *     if (event.type === "paymentConfirmed") this.shipOrder(event.payload);
+ *   }
+ * }
+ * ```
+ */
+declare function SagaHandler$1(cqrsName: string, sagaName: string, eventNames: readonly string[]): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+
+declare class GraphReflyEventExplorer implements OnModuleInit, OnModuleDestroy {
+    private readonly graph;
+    private readonly moduleRef;
+    private readonly disposers;
+    private readonly scheduleNodeNames;
+    constructor(graph: Graph, moduleRef: ModuleRef);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    private wireEvents;
+    private wireEventHandler;
+    private wireIntervals;
+    private wireIntervalHandler;
+    private wireCrons;
+    private wireCronHandler;
+    private wireCqrsCommands;
+    private wireCqrsCommand;
+    private wireCqrsEvents;
+    private wireCqrsEventHandler;
+    private wireCqrsQueries;
+    private wireCqrsQuery;
+    private wireCqrsSagas;
+    private wireCqrsSaga;
+    private observeNode;
+    private observeNodeOn;
+    private resolveCqrsGraph;
+    private resolveInstance;
+}
+
+/**
+ * Client-to-server commands for the WebSocket observe protocol.
+ */
+type ObserveWsCommand = {
+    type: "subscribe";
+    path: string;
+} | {
+    type: "unsubscribe";
+    path: string;
+} | {
+    type: "ack";
+    path: string;
+    count?: number;
+};
+/**
+ * Server-to-client messages for the WebSocket observe protocol.
+ */
+type ObserveWsMessage<T = unknown> = {
+    type: "data";
+    path: string;
+    value: T;
+} | {
+    type: "error";
+    path: string;
+    error: string;
+} | {
+    type: "complete";
+    path: string;
+} | {
+    type: "subscribed";
+    path: string;
+} | {
+    type: "unsubscribed";
+    path: string;
+} | {
+    type: "err";
+    message: string;
+};
+type ObserveSSEOptions = {
+    actor?: Actor;
+    serialize?: (value: unknown) => string;
+    keepAliveMs?: number;
+    signal?: AbortSignal;
+    /** Pending DATA count at which PAUSE is sent upstream. Enables backpressure when set. */
+    highWaterMark?: number;
+    /** Pending DATA count at which RESUME is sent upstream. Defaults to `Math.floor(highWaterMark / 2)`. */
+    lowWaterMark?: number;
+};
+/**
+ * Creates an SSE `ReadableStream` that streams DATA values from a graph node.
+ *
+ * Routes through `graph.observe(path, { actor })` so node guards are respected.
+ * The stream emits `event: data` for DATA, `event: error` for ERROR, and
+ * `event: complete` for COMPLETE (then closes). TEARDOWN also closes the stream.
+ *
+ * @param graph - The graph to observe.
+ * @param path - Qualified node path to observe.
+ * @param opts - Actor context, serialization, keep-alive.
+ * @returns A `ReadableStream<Uint8Array>` suitable for NestJS SSE endpoints.
+ *
+ * @example
+ * ```ts
+ * @Sse("events/:path")
+ * streamEvents(@Param("path") path: string, @Req() req: Request) {
+ *   return observeSSE(this.graph, path, { actor: getActor(req) });
+ * }
+ * ```
+ */
+declare function observeSSE(graph: Graph, path: string, opts?: ObserveSSEOptions): ReadableStream<Uint8Array>;
+type ObserveSubscriptionOptions<T = unknown> = {
+    actor?: Actor;
+    /**
+     * Optional value filter. Only matching DATA values are enqueued.
+     *
+     * **Note:** `filter` and `highWaterMark` are semantically decoupled — the
+     * watermark counts items that pass the filter, not total upstream work.
+     * If the filter rejects most items, backpressure may never engage despite
+     * high upstream throughput. For upstream-level resource protection, place a
+     * filtering derived node in the graph before the observe point instead.
+     */
+    filter?: (value: T) => boolean;
+    /** Pending DATA count at which PAUSE is sent upstream. Enables backpressure when set. */
+    highWaterMark?: number;
+    /** Pending DATA count at which RESUME is sent upstream. Defaults to `Math.floor(highWaterMark / 2)`. */
+    lowWaterMark?: number;
+};
+/**
+ * Creates an `AsyncIterableIterator` that yields DATA values from a graph node.
+ *
+ * Designed for GraphQL subscription resolvers (Apollo, Mercurius, etc.).
+ * Routes through `graph.observe(path, { actor })` for guard-scoped access.
+ *
+ * The iterator completes on COMPLETE/TEARDOWN and throws on ERROR.
+ *
+ * @param graph - The graph to observe.
+ * @param path - Qualified node path to observe.
+ * @param opts - Actor context, optional value filter.
+ * @returns An async iterable that yields DATA payloads.
+ *
+ * @example
+ * ```ts
+ * // Apollo-style resolver
+ * Subscription: {
+ *   orderStatus: {
+ *     subscribe: (_parent, args, ctx) =>
+ *       observeSubscription(ctx.graph, `orders::${args.id}::status`, {
+ *         actor: ctx.actor,
+ *       }),
+ *   },
+ * }
+ * ```
+ */
+declare function observeSubscription<T = unknown>(graph: Graph, path: string, opts?: ObserveSubscriptionOptions<T>): AsyncIterableIterator<T>;
+type ObserveGatewayOptions = {
+    extractActor?: (client: unknown) => Actor | undefined;
+    parse?: (data: string) => ObserveWsCommand;
+    /** Pending DATA count per subscription at which PAUSE is sent upstream. Enables backpressure when set. */
+    highWaterMark?: number;
+    /** Pending DATA count per subscription at which RESUME is sent upstream. Defaults to `Math.floor(highWaterMark / 2)`. */
+    lowWaterMark?: number;
+};
+/**
+ * Manages per-client WebSocket subscriptions to graph nodes via `observe()`.
+ *
+ * Not a NestJS decorator or base class — a standalone helper that can be
+ * wired into any WebSocket gateway. Each client can subscribe/unsubscribe
+ * to individual node paths. Actor-scoped observation respects node guards.
+ *
+ * @example
+ * ```ts
+ * @WebSocketGateway()
+ * export class GraphGateway {
+ *   private gw = new ObserveGateway(this.graph);
+ *
+ *   constructor(@InjectGraph() private graph: Graph) {}
+ *
+ *   handleConnection(client: WebSocket) {
+ *     this.gw.handleConnection(client);
+ *   }
+ *
+ *   handleDisconnect(client: WebSocket) {
+ *     this.gw.handleDisconnect(client);
+ *   }
+ *
+ *   @SubscribeMessage("observe")
+ *   onObserve(client: WebSocket, data: unknown) {
+ *     this.gw.handleMessage(client, data);
+ *   }
+ * }
+ * ```
+ */
+declare class ObserveGateway {
+    private readonly graph;
+    private readonly clients;
+    private readonly extractActor;
+    private readonly parse;
+    private readonly highWaterMark;
+    private readonly lowWaterMark;
+    constructor(graph: Graph, opts?: ObserveGatewayOptions);
+    /**
+     * Register a new client. Call from `handleConnection`.
+     */
+    handleConnection(client: unknown): void;
+    /**
+     * Unregister a client and dispose all its subscriptions. Call from `handleDisconnect`.
+     */
+    handleDisconnect(client: unknown): void;
+    /**
+     * Handle an incoming client message (subscribe/unsubscribe/ack command).
+     *
+     * @param client - The WebSocket client reference.
+     * @param raw - Raw message data (string or parsed object).
+     * @param send - Function to send a message back to the client.
+     *   Defaults to `client.send(JSON.stringify(msg))`.
+     */
+    handleMessage(client: unknown, raw: unknown, send?: (msg: ObserveWsMessage) => void): void;
+    /**
+     * Number of active subscriptions for a client. Useful for tests.
+     */
+    subscriptionCount(client: unknown): number;
+    /**
+     * Dispose all clients and subscriptions.
+     */
+    destroy(): void;
+    private subscribe;
+    private unsubscribe;
+    private ack;
+}
+
+/**
+ * Property name under which the extracted {@link Actor} is stored on the
+ * request object. Downstream code (controllers, gateways) reads
+ * `req[ACTOR_KEY]` to pass actor context to graph operations.
+ */
+declare const ACTOR_KEY: "graphReflyActor";
+/**
+ * Extracts a GraphReFly {@link Actor} from a NestJS {@link ExecutionContext}.
+ *
+ * Return `undefined` to fall back to {@link DEFAULT_ACTOR}.
+ */
+type ActorExtractor = (context: ExecutionContext) => Actor | undefined;
+/**
+ * Creates an {@link ActorExtractor} that reads a JWT payload from `req.user`
+ * (the standard Passport.js location) and maps it to a GraphReFly {@link Actor}.
+ *
+ * @param mapping - Optional transform from the JWT payload to an Actor.
+ *   When omitted, the payload is used directly (must have `type` and `id`).
+ *
+ * @example
+ * ```ts
+ * // Default: req.user is already { type, id, ... }
+ * GraphReflyGuard(fromJwtPayload())
+ *
+ * // Custom mapping from your JWT claims
+ * GraphReflyGuard(fromJwtPayload((payload) => ({
+ *   type: payload.role === "admin" ? "human" : "llm",
+ *   id: payload.sub,
+ *   org: payload.org_id,
+ * })))
+ * ```
+ */
+declare function fromJwtPayload(mapping?: (payload: unknown) => Actor): ActorExtractor;
+/**
+ * Creates an {@link ActorExtractor} that reads an Actor from a request header.
+ *
+ * The header value is parsed as JSON. Useful for service-to-service calls
+ * where the caller embeds actor context in a custom header.
+ *
+ * @param headerName - HTTP header name (case-insensitive). Default: `"x-graphrefly-actor"`.
+ *
+ * @example
+ * ```ts
+ * GraphReflyGuard(fromHeader("x-actor"))
+ * ```
+ */
+declare function fromHeader(headerName?: string): ActorExtractor;
+/**
+ * Reads the extracted {@link Actor} from a request object (set by {@link GraphReflyGuardImpl}).
+ *
+ * Returns {@link DEFAULT_ACTOR} if no actor was attached.
+ *
+ * @example
+ * ```ts
+ * @Get("status")
+ * getStatus(@Req() req: Request) {
+ *   const actor = getActor(req);
+ *   return this.graph.describe({ actor });
+ * }
+ * ```
+ */
+declare function getActor(req: unknown): Actor;
+/**
+ * NestJS guard that extracts a GraphReFly {@link Actor} from the execution
+ * context and attaches it to the request as `req.graphReflyActor`.
+ *
+ * This guard always returns `true` (allows the request through). Access
+ * control is handled by GraphReFly node guards (`policy()`), not by this
+ * NestJS guard. The purpose is purely to **bridge** authentication context.
+ *
+ * @example
+ * ```ts
+ * // Global guard — every request gets an Actor
+ * app.useGlobalGuards(new GraphReflyGuardImpl(fromJwtPayload()));
+ *
+ * // Controller-scoped
+ * @UseGuards(GraphReflyGuard(fromJwtPayload()))
+ * @Controller("api")
+ * export class ApiController { ... }
+ * ```
+ */
+declare class GraphReflyGuardImpl implements CanActivate {
+    private readonly extractor;
+    constructor(extractor: ActorExtractor);
+    canActivate(context: ExecutionContext): boolean;
+}
+/**
+ * Factory that creates a {@link GraphReflyGuardImpl} instance. Use with
+ * NestJS `@UseGuards()` or `app.useGlobalGuards()`.
+ *
+ * @param extractor - How to extract an Actor from the request context.
+ *   Defaults to {@link fromJwtPayload} (reads `req.user`).
+ *
+ * @example
+ * ```ts
+ * import { GraphReflyGuard, fromJwtPayload } from "@graphrefly/graphrefly-ts/compat/nestjs";
+ *
+ * @UseGuards(GraphReflyGuard())
+ * @Controller("graph")
+ * export class GraphController { ... }
+ * ```
+ */
+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<ReactiveLogSnapshot<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;
+    /** Snapshot to hydrate via `graph.restore()` after build. */
+    snapshot?: GraphPersistSnapshot;
+    /** Build callback — registers nodes/mounts on the graph. */
+    build?: (graph: Graph) => void;
+    /** Qualified node paths to expose as injectable providers. */
+    nodes?: readonly string[];
+    /** Enable a request-scoped graph (injectable via `@InjectGraph("request")`). */
+    requestScope?: boolean;
+}
+interface GraphReflyCqrsOptions {
+    /** Feature name — becomes the mount name in the root graph. */
+    name: string;
+    /** CQRS graph options (forwarded to `cqrs()` factory). */
+    cqrs?: CqrsOptions;
+    /** Build callback — registers commands, events, projections, sagas on the CqrsGraph. */
+    build?: (graph: CqrsGraph) => void;
+    /** Event store adapter for persistence (wired via `useEventStore()`). */
+    eventStore?: EventStoreAdapter;
+    /**
+     * Node paths (local to this feature) to expose as injectable providers.
+     * Tokens are auto-qualified as `featureName::path`.
+     */
+    nodes?: readonly string[];
+}
+interface GraphReflyFeatureOptions {
+    /** Feature name — becomes the mount name in the root graph. */
+    name: string;
+    /** Build callback — registers nodes/mounts on the feature graph. */
+    build?: (graph: Graph) => void;
+    /** Snapshot to hydrate after build. */
+    snapshot?: GraphPersistSnapshot;
+    /**
+     * Node paths (local to this feature) to expose as injectable providers.
+     * Tokens are auto-qualified as `featureName::path` to avoid collisions.
+     */
+    nodes?: readonly string[];
+}
+declare class GraphReflyModule {
+    /**
+     * Register the root `Graph` singleton in the NestJS DI container.
+     *
+     * The root graph is `@Global()` — injectable everywhere without importing
+     * the module again. Use `@InjectGraph()` to inject it.
+     *
+     * Lifecycle:
+     * - **init:** Graph created in factory. If `build` is provided, it runs
+     *   first (registers nodes/mounts). If `snapshot` is provided, values
+     *   are restored via `graph.restore()`.
+     * - **destroy:** Calls `graph.destroy()` — sends `[[TEARDOWN]]` to all
+     *   nodes, including mounted feature subgraphs (cascading teardown).
+     */
+    static forRoot(opts?: GraphReflyRootOptions): DynamicModule;
+    /**
+     * Register a feature subgraph that auto-mounts into the root graph.
+     *
+     * The feature graph is created in the factory, built/restored, then
+     * mounted into root via `root.mount(name, featureGraph)`. On app
+     * shutdown, root's `graph.destroy()` cascades TEARDOWN through all
+     * mounted subgraphs (no explicit remove needed).
+     *
+     * Node tokens are auto-qualified as `featureName::path` to prevent
+     * collisions between features declaring nodes with the same local name.
+     *
+     * Injectable via `@InjectGraph(name)`.
+     */
+    static forFeature(opts: GraphReflyFeatureOptions): DynamicModule;
+    /**
+     * Register a CQRS subgraph that auto-mounts into the root graph.
+     *
+     * Creates a `CqrsGraph` via the `cqrs()` factory (roadmap §4.5), mounts it
+     * into the root graph, and exposes it for DI via `@InjectGraph(name)`.
+     *
+     * CQRS decorators (`@CommandHandler`, `@EventHandler`, `@QueryHandler`,
+     * `@SagaHandler`) are discovered by the explorer and wired to this graph
+     * on module init.
+     *
+     * @example
+     * ```ts
+     * GraphReflyModule.forCqrs({
+     *   name: "orders",
+     *   build: (g) => {
+     *     g.event("orderPlaced");
+     *     g.projection("orderCount", ["orderPlaced"], (_s, evts) => evts.length, 0);
+     *   },
+     * })
+     * ```
+     */
+    static forCqrs(opts: GraphReflyCqrsOptions): DynamicModule;
+}
+
+/** Injection token for the root `Graph` singleton created by `forRoot()`. */
+declare const GRAPHREFLY_ROOT_GRAPH: unique symbol;
+/** Injection token for the request-scoped `Graph` created by request scope config. */
+declare const GRAPHREFLY_REQUEST_GRAPH: unique symbol;
+/**
+ * Get the injection token for a named feature graph.
+ *
+ * Feature graphs registered via `GraphReflyModule.forFeature({ name })` are
+ * injectable using this token (or via the `@InjectGraph(name)` decorator).
+ */
+declare function getGraphToken(name: string): symbol;
+/**
+ * Get the injection token for a node at a qualified path.
+ *
+ * Nodes declared in `forRoot({ nodes })` or `forFeature({ nodes })` are
+ * injectable using this token (or via the `@InjectNode(path)` decorator).
+ */
+declare function getNodeToken(path: string): symbol;
+
+declare const index_ACTOR_KEY: typeof ACTOR_KEY;
+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;
+type index_CommandHandlerMeta = CommandHandlerMeta;
+declare const index_EVENT_HANDLERS: typeof EVENT_HANDLERS;
+declare const index_EventHandler: typeof EventHandler;
+type index_EventHandlerMeta = EventHandlerMeta;
+declare const index_GRAPHREFLY_REQUEST_GRAPH: typeof GRAPHREFLY_REQUEST_GRAPH;
+declare const index_GRAPHREFLY_ROOT_GRAPH: typeof GRAPHREFLY_ROOT_GRAPH;
+declare const index_GraphCron: typeof GraphCron;
+type index_GraphCronMeta = GraphCronMeta;
+declare const index_GraphInterval: typeof GraphInterval;
+type index_GraphIntervalMeta = GraphIntervalMeta;
+type index_GraphReflyCqrsOptions = GraphReflyCqrsOptions;
+type index_GraphReflyEventExplorer = GraphReflyEventExplorer;
+declare const index_GraphReflyEventExplorer: typeof GraphReflyEventExplorer;
+type index_GraphReflyFeatureOptions = GraphReflyFeatureOptions;
+declare const index_GraphReflyGuard: typeof GraphReflyGuard;
+type index_GraphReflyGuardImpl = GraphReflyGuardImpl;
+declare const index_GraphReflyGuardImpl: typeof GraphReflyGuardImpl;
+type index_GraphReflyModule = GraphReflyModule;
+declare const index_GraphReflyModule: typeof GraphReflyModule;
+type index_GraphReflyRootOptions = GraphReflyRootOptions;
+declare const index_INTERVAL_HANDLERS: typeof INTERVAL_HANDLERS;
+declare const index_InjectCqrsGraph: typeof InjectCqrsGraph;
+declare const index_InjectGraph: typeof InjectGraph;
+declare const index_InjectNode: typeof InjectNode;
+type index_ObserveGateway = ObserveGateway;
+declare const index_ObserveGateway: typeof ObserveGateway;
+type index_ObserveGatewayOptions = ObserveGatewayOptions;
+type index_ObserveSSEOptions = ObserveSSEOptions;
+type index_ObserveSubscriptionOptions<T = unknown> = ObserveSubscriptionOptions<T>;
+type index_ObserveWsCommand = ObserveWsCommand;
+type index_ObserveWsMessage<T = unknown> = ObserveWsMessage<T>;
+declare const index_OnGraphEvent: typeof OnGraphEvent;
+type index_OnGraphEventMeta = OnGraphEventMeta;
+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;
+type index_SagaHandlerMeta = SagaHandlerMeta;
+declare const index_fromHeader: typeof fromHeader;
+declare const index_fromJwtPayload: typeof fromJwtPayload;
+declare const index_getActor: typeof getActor;
+declare const index_getGraphToken: typeof getGraphToken;
+declare const index_getNodeToken: typeof getNodeToken;
+declare const index_observeGraph$: typeof observeGraph$;
+declare const index_observeNode$: typeof observeNode$;
+declare const index_observeSSE: typeof observeSSE;
+declare const index_observeSubscription: typeof observeSubscription;
+declare const index_toMessages$: typeof toMessages$;
+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_fromHeader as fromHeader, index_fromJwtPayload as fromJwtPayload, index_getActor as getActor, index_getGraphToken as getGraphToken, index_getNodeToken as getNodeToken, index_observeGraph$ as observeGraph$, index_observeNode$ as observeNode$, index_observeSSE as observeSSE, index_observeSubscription as observeSubscription, index_toMessages$ as toMessages$, 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 };