@graphrefly/ts 0.0.0 → 0.0.2

package/dist/adapters/nestjs.d.ts

@@ -0,0 +1,385 @@
+import { DataIssue } from '../data/index.js';
+import { d as Graph } from '../graph-ho5sotHP.js';
+import { N as Node } from '../types-C9NOgNJw.js';
+import '../core/index.js';
+import '../messages-CAzUPPJM.js';
+import '../codec-BB7p8fJc.js';
+import '../describe-B_A5fbXH.js';
+
+/**
+ * Focused NestJS boundary bindings for GraphReFly (D474/D478).
+ *
+ * This subpath stays dependency-light: it exposes graph boundary primitives,
+ * token/provider shapes, and decorator metadata without importing Nest itself.
+ * User-land Nest modules/controllers bind these helpers to real decorators and
+ * host lifecycle objects at the framework edge.
+ */
+
+declare const NEST_BOUNDARY_ENVELOPE_VERSION = 1;
+declare const NEST_BOUNDARY_PAYLOAD_MAX_BYTES: number;
+declare const NEST_HTTP_DIAGNOSTICS_MAX_RETAINED = 100;
+/** D478 minimal graph-visible transport envelope. Payload must be data-only. */
+interface NestBoundaryEnvelope<T = unknown> {
+    readonly bindingId: string;
+    readonly version: number;
+    readonly payload: T;
+    readonly requestId?: string;
+}
+/** Reply-capable egress must carry host-private request correlation (D478). */
+type NestReplyEnvelope<T = unknown> = NestBoundaryEnvelope<T> & {
+    readonly requestId: string;
+};
+type NestBoundaryKind = "request" | "guard" | "interceptor" | "error" | "lifecycle" | "cron" | "diagnostics" | "ws" | "message";
+type NestEgressKind = "http" | "guard-decision" | "ws-ack" | "ws-reply" | "message-reply";
+type NestFilterMode = "handle" | "observe";
+type NestDiagnosticPhase = "adapter" | "http" | "guard" | "filter" | "cron" | "lifecycle" | "ws" | "message" | NestBoundaryKind | NestEgressKind;
+interface NestHttpResponsePayload<TBody = unknown> {
+    readonly status: number;
+    readonly body?: TBody;
+    readonly headers?: Record<string, string>;
+}
+interface HttpDataIssue extends DataIssue {
+    readonly status: number;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+}
+type NestIssueResponse<THost = unknown> = (issue: DataIssue, host: THost) => NestHttpResponsePayload;
+type NestProtocolErrorResponse<THost = unknown> = (errorPayload: unknown, host: THost) => NestHttpResponsePayload;
+interface NestBoundaryDiagnostic {
+    readonly kind: "binding-mismatch" | "dispose-pending" | "malformed-egress" | "stale-egress" | "terminal-egress" | "timeout" | "resolve-threw" | "reject-threw";
+    readonly phase?: NestDiagnosticPhase;
+    readonly requestId?: string;
+    readonly bindingId?: string;
+    readonly expectedBindingId?: string;
+    readonly message: string;
+    readonly error?: unknown;
+}
+interface NestDiagnosticErrorPayload {
+    readonly name?: string;
+    readonly message: string;
+}
+interface NestDiagnosticPayload {
+    readonly kind: NestBoundaryDiagnostic["kind"];
+    readonly phase: NestDiagnosticPhase;
+    readonly requestId?: string;
+    readonly bindingId?: string;
+    readonly expectedBindingId?: string;
+    readonly message: string;
+    readonly error?: NestDiagnosticErrorPayload;
+}
+interface NestDiagnosticInput extends NestBoundaryDiagnostic {
+    readonly phase?: NestDiagnosticPhase;
+}
+interface NestDiagnosticsOptions extends Omit<NestIngressOptions<NestDiagnosticInput, NestDiagnosticPayload>, "payload"> {
+    readonly phase?: NestDiagnosticPhase;
+}
+type NestDiagnosticIngressBoundary = NestIngressBoundary<NestDiagnosticInput, NestDiagnosticPayload>;
+interface NestIngressBoundary<THost = unknown, TPayload = THost> {
+    readonly kind: NestBoundaryKind;
+    readonly bindingId: string;
+    readonly version: number;
+    readonly node: Node<NestBoundaryEnvelope<TPayload>>;
+    envelope(host: THost, opts?: NestIngressEmitOptions<TPayload>): NestBoundaryEnvelope<TPayload>;
+    emit(host: THost, opts?: NestIngressEmitOptions<TPayload>): NestBoundaryEnvelope<TPayload>;
+}
+interface NestIngressOptions<THost, TPayload> {
+    readonly bindingId?: string;
+    readonly name?: string;
+    readonly version?: number;
+    readonly maxPayloadBytes?: number;
+    readonly requestId?: string | ((host: THost) => string | undefined);
+    readonly requireRequestId?: boolean;
+    readonly payload?: (host: THost) => TPayload;
+}
+interface NestIngressEmitOptions<TPayload> {
+    readonly requestId?: string;
+    readonly bindingId?: string;
+    readonly version?: number;
+    readonly payload?: TPayload;
+    readonly requireRequestId?: boolean;
+}
+interface NestReplyResponseHandle<TPayload> {
+    resolve(payload: TPayload, envelope: NestReplyEnvelope<TPayload>): void;
+    reject(error: unknown, envelope?: NestReplyEnvelope<TPayload>): void;
+}
+interface NestReplyPendingRegistration<TPayload> {
+    readonly requestId: string;
+    readonly handle: NestReplyResponseHandle<TPayload>;
+    readonly bindingId?: string;
+}
+interface NestReplyBoundary<TPayload = unknown> {
+    readonly kind: NestEgressKind;
+    readonly bindingId: string;
+    attach(registration: NestReplyPendingRegistration<TPayload>): () => boolean;
+    pendingCount(): number;
+    diagnostics(): readonly NestBoundaryDiagnostic[];
+    dispose(): void;
+}
+interface NestHttpResponseHandle<TPayload> extends NestReplyResponseHandle<TPayload> {
+}
+interface NestHttpPendingRegistration<TPayload> extends NestReplyPendingRegistration<TPayload> {
+}
+interface NestHttpBoundary<TPayload = unknown> extends NestReplyBoundary<TPayload> {
+    readonly kind: "http";
+}
+interface ToNestHttpOptions<TPayload> {
+    readonly bindingId?: string;
+    readonly diagnosticBoundary?: NestDiagnosticIngressBoundary;
+    readonly diagnosticPhase?: NestDiagnosticPhase;
+    readonly maxDiagnostics?: number;
+    readonly maxPayloadBytes?: number;
+    readonly name?: string;
+    readonly transform?: (payload: TPayload, envelope: NestReplyEnvelope<TPayload>) => TPayload;
+    readonly label?: string;
+}
+interface NestBoundaryDecoratorOptions<THost = unknown, TPayload = unknown> {
+    readonly bindingId?: string;
+    readonly payload?: (host: THost) => TPayload;
+    readonly requestId?: string | ((host: THost) => string | undefined);
+    readonly order?: number;
+}
+interface NestFilterDecoratorOptions<THost = unknown, TPayload = unknown> extends NestBoundaryDecoratorOptions<THost, TPayload> {
+    readonly mode?: NestFilterMode;
+    readonly issueResponse?: NestIssueResponse<THost>;
+    readonly protocolError?: NestProtocolErrorResponse<THost>;
+}
+interface NestHttpReplyDecoratorOptions<THost = unknown> {
+    readonly bindingId: string;
+    readonly order?: number;
+    readonly issueResponse?: NestIssueResponse<THost>;
+    readonly protocolError?: NestProtocolErrorResponse<THost>;
+}
+interface NestGuardDecisionDecoratorOptions<THost = unknown> {
+    readonly bindingId: string;
+    readonly order?: number;
+    readonly issueResponse?: NestIssueResponse<THost>;
+    readonly protocolError?: NestProtocolErrorResponse<THost>;
+}
+interface NestGraphRunOptions<THost = unknown> {
+    readonly requestId?: string | ((host: THost) => string | undefined);
+}
+interface NestGraphBoundaryRunnerOptions {
+    readonly diagnosticBoundary?: NestDiagnosticIngressBoundary;
+    readonly diagnosticPhase?: NestDiagnosticPhase;
+}
+interface NestGraphBoundaryRunner {
+    run<THost = unknown>(target: DecoratorHostConstructor | object, methodKey: string | symbol, host: THost, opts?: NestGraphRunOptions<THost>): Promise<unknown> | undefined;
+    dispose(): void;
+}
+interface NestExecutionContextLike {
+    getClass(): DecoratorHostConstructor;
+    getHandler(): DecoratorBoundMethod;
+    switchToHttp?(): {
+        getRequest<T = unknown>(): T;
+    };
+}
+interface NestCallHandlerLike {
+    handle(): unknown;
+}
+interface NestGraphBoundaryInterceptorOptions<THost = unknown> extends NestGraphRunOptions<THost>, NestGraphBoundaryRunnerOptions {
+    readonly host?: (context: NestExecutionContextLike) => THost;
+    readonly runner?: NestGraphBoundaryRunner;
+}
+interface NestGraphBoundaryInterceptor {
+    intercept(context: NestExecutionContextLike, next?: NestCallHandlerLike): Promise<unknown> | unknown;
+    dispose(): void;
+}
+/** Injection token for a root graph singleton. */
+declare const GRAPHREFLY_ROOT_GRAPH: unique symbol;
+/** Injection token for adapter module options. */
+declare const GRAPHREFLY_MODULE_OPTIONS: unique symbol;
+/** Injection token for a request-scoped graph. */
+declare const GRAPHREFLY_REQUEST_GRAPH: unique symbol;
+type DecoratorHostConstructor = abstract new (...args: unknown[]) => unknown;
+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;
+}
+type NestBoundaryBindingDirection = "ingress" | "egress";
+interface NestIngressBindingMeta {
+    readonly direction: "ingress";
+    kind: NestBoundaryKind;
+    bindingId: string;
+    methodKey: string | symbol;
+    readonly boundary: NestIngressBoundary<unknown, unknown>;
+    readonly payload?: (host: unknown) => unknown;
+    readonly requestId?: string | ((host: unknown) => string | undefined);
+    readonly order?: number;
+    readonly mode?: NestFilterMode;
+    readonly issueResponse?: NestIssueResponse<unknown>;
+    readonly protocolError?: NestProtocolErrorResponse<unknown>;
+}
+interface NestHttpReplyBindingMeta {
+    readonly direction: "egress";
+    readonly kind: "http";
+    readonly bindingId: string;
+    readonly methodKey: string | symbol;
+    readonly replyNode: Node<NestReplyEnvelope<unknown>>;
+    readonly order?: number;
+    readonly issueResponse?: NestIssueResponse<unknown>;
+    readonly protocolError?: NestProtocolErrorResponse<unknown>;
+}
+interface NestGuardDecisionBindingMeta {
+    readonly direction: "egress";
+    readonly kind: "guard-decision";
+    readonly bindingId: string;
+    readonly methodKey: string | symbol;
+    readonly decisionNode: Node<NestReplyEnvelope<GraphGuardDecision>>;
+    readonly order?: number;
+    readonly issueResponse?: NestIssueResponse<unknown>;
+    readonly protocolError?: NestProtocolErrorResponse<unknown>;
+}
+interface NestWsAckBindingMeta {
+    readonly direction: "egress";
+    readonly kind: "ws-ack";
+    readonly bindingId: string;
+    readonly methodKey: string | symbol;
+    readonly ackNode: Node<NestReplyEnvelope<unknown>>;
+    readonly order?: number;
+}
+interface NestWsReplyBindingMeta {
+    readonly direction: "egress";
+    readonly kind: "ws-reply";
+    readonly bindingId: string;
+    readonly methodKey: string | symbol;
+    readonly replyNode: Node<NestReplyEnvelope<unknown>>;
+    readonly order?: number;
+}
+interface NestMessageReplyBindingMeta {
+    readonly direction: "egress";
+    readonly kind: "message-reply";
+    readonly bindingId: string;
+    readonly methodKey: string | symbol;
+    readonly replyNode: Node<NestReplyEnvelope<unknown>>;
+    readonly order?: number;
+}
+type NestBoundaryBindingMeta = NestIngressBindingMeta | NestHttpReplyBindingMeta | NestGuardDecisionBindingMeta | NestWsAckBindingMeta | NestWsReplyBindingMeta | NestMessageReplyBindingMeta;
+declare const EVENT_HANDLERS: WeakMap<DecoratorHostConstructor, OnGraphEventMeta[]>;
+declare const INTERVAL_HANDLERS: WeakMap<DecoratorHostConstructor, GraphIntervalMeta[]>;
+declare const CRON_HANDLERS: WeakMap<DecoratorHostConstructor, GraphCronMeta[]>;
+declare const NEST_BOUNDARY_BINDINGS: WeakMap<DecoratorHostConstructor, NestBoundaryBindingMeta[]>;
+type GraphMethodDecorator = MethodDecorator & ((value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void);
+/** Minimal Nest provider object shape without importing @nestjs/common. */
+type NestProviderBinding<T = unknown> = {
+    readonly provide: string | symbol;
+    readonly useValue: T;
+} | {
+    readonly provide: string | symbol;
+    readonly useFactory: (...args: unknown[]) => T;
+};
+/** Get the injection token for a named feature graph. */
+declare function getGraphToken(name: string): symbol;
+/** Get the injection token for a node at a qualified path. */
+declare function getNodeToken(path: string): symbol;
+/** Get the injection token for a named Nest boundary binding. */
+declare function getNestBoundaryToken(bindingId: string): symbol;
+/** Build a dependency-free provider binding shape for user-land Nest modules. */
+declare function nestProvider<T>(provide: string | symbol, useValue: T): NestProviderBinding<T>;
+/** D474 P0 HTTP request ingress. */
+declare function fromNestReq<THost = unknown, TPayload = THost>(graph: Graph, opts?: NestIngressOptions<THost, TPayload>): NestIngressBoundary<THost, TPayload>;
+/** D474 P0 guard/admission ingress. */
+declare function fromNestGuard<THost = unknown, TPayload = THost>(graph: Graph, opts?: NestIngressOptions<THost, TPayload>): NestIngressBoundary<THost, TPayload>;
+/** D474 P1 interceptor ingress. */
+declare function fromNestIntercept<THost = unknown, TPayload = THost>(graph: Graph, opts?: NestIngressOptions<THost, TPayload>): NestIngressBoundary<THost, TPayload>;
+/** D474 P0 error/filter ingress. */
+declare function fromNestError<THost = unknown, TPayload = THost>(graph: Graph, opts?: NestIngressOptions<THost, TPayload>): NestIngressBoundary<THost, TPayload>;
+/** D474 P1 Nest lifecycle hook ingress. */
+declare function fromNestLifecycle<THost = unknown, TPayload = THost>(graph: Graph, opts?: NestIngressOptions<THost, TPayload>): NestIngressBoundary<THost, TPayload>;
+/** D474 P1 schedule/cron ingress. */
+declare function fromNestCron<THost = unknown, TPayload = THost>(graph: Graph, opts?: NestIngressOptions<THost, TPayload>): NestIngressBoundary<THost, TPayload>;
+/** D494 explicit graph-visible diagnostics ingress. Emits sanitized data-only payloads. */
+declare function fromNestDiagnostics(graph: Graph, opts?: NestDiagnosticsOptions): NestDiagnosticIngressBoundary;
+/** D474 later/optional WebSocket ingress. Kept thin for first-slice experiments. */
+declare function fromNestWs<THost = unknown, TPayload = THost>(graph: Graph, opts?: NestIngressOptions<THost, TPayload>): NestIngressBoundary<THost, TPayload>;
+/** D474 later/optional microservice/message ingress. */
+declare function fromNestMessage<THost = unknown, TPayload = THost>(graph: Graph, opts?: NestIngressOptions<THost, TPayload>): NestIngressBoundary<THost, TPayload>;
+/**
+ * D474 HTTP egress resolver.
+ *
+ * The returned boundary owns only a host-private pending map. It never stores
+ * response/socket/ack handles in graph DATA and only resolves handles whose
+ * requestId (and optional bindingId) match an egress envelope.
+ */
+declare function toNestHttp<TPayload = unknown>(egress: Node<NestReplyEnvelope<TPayload>>, opts?: ToNestHttpOptions<TPayload>): NestHttpBoundary<TPayload>;
+/** D478 route-request decorator over an existing ingress boundary. */
+declare function GraphReq<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestBoundaryDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D478 route-guard decorator over an existing ingress boundary. */
+declare function GraphGuard<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestBoundaryDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D478 route-interceptor decorator over an existing ingress boundary. */
+declare function GraphIntercept<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestBoundaryDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D484 generic filter decorator over an existing ingress boundary. */
+declare function GraphFilter<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestFilterDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D484 exception-oriented sugar over GraphFilter. */
+declare function GraphError<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestFilterDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D478 lifecycle decorator over an existing ingress boundary. */
+declare function GraphLifecycle<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestBoundaryDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D478 cron/schedule decorator over an existing ingress boundary. */
+declare function GraphCron<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestBoundaryDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D488 WebSocket message ingress decorator over an existing boundary. */
+declare function GraphWs<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestBoundaryDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D488 microservice/message ingress decorator over an existing boundary. */
+declare function GraphMessage<THost = unknown, TPayload = unknown>(boundary: NestIngressBoundary<THost, TPayload>, opts?: NestBoundaryDecoratorOptions<THost, TPayload>): GraphMethodDecorator;
+/** D478 HTTP reply decorator over an existing reply node. */
+declare function GraphHttpReply<THost = unknown, TPayload = unknown>(replyNode: Node<NestReplyEnvelope<TPayload>>, opts: NestHttpReplyDecoratorOptions<THost>): GraphMethodDecorator;
+type GraphGuardDecision = {
+    readonly kind: "allow";
+    readonly reason?: string;
+    readonly metadata?: Record<string, unknown>;
+} | {
+    readonly kind: "deny";
+    readonly reason?: string;
+    readonly status?: number;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+    readonly issue?: DataIssue | HttpDataIssue;
+    readonly metadata?: Record<string, unknown>;
+};
+/** D484 guard decision egress decorator over an existing reply-correlated decision node. */
+declare function GraphGuardDecision<THost = unknown>(decisionNode: Node<NestReplyEnvelope<GraphGuardDecision>>, opts: NestGuardDecisionDecoratorOptions<THost>): GraphMethodDecorator;
+/** D488 WebSocket acknowledgement egress decorator over an existing reply-correlated node. */
+declare function GraphWsAck<TPayload = unknown>(ackNode: Node<NestReplyEnvelope<TPayload>>, opts: {
+    readonly bindingId: string;
+    readonly order?: number;
+}): GraphMethodDecorator;
+/** D488 WebSocket reply egress decorator over an existing reply-correlated node. */
+declare function GraphWsReply<TPayload = unknown>(replyNode: Node<NestReplyEnvelope<TPayload>>, opts: {
+    readonly bindingId: string;
+    readonly order?: number;
+}): GraphMethodDecorator;
+/** D488 microservice/message reply egress decorator over an existing reply-correlated node. */
+declare function GraphMessageReply<TPayload = unknown>(replyNode: Node<NestReplyEnvelope<TPayload>>, opts: {
+    readonly bindingId: string;
+    readonly order?: number;
+}): GraphMethodDecorator;
+declare function createNestGraphBoundaryRunner(opts?: NestGraphBoundaryRunnerOptions): NestGraphBoundaryRunner;
+declare function createNestGraphBoundaryInterceptor<THost = unknown>(opts?: NestGraphBoundaryInterceptorOptions<THost>): NestGraphBoundaryInterceptor;
+declare function getNestBoundaryBindings(target: DecoratorHostConstructor | object, methodKey?: string | symbol): readonly NestBoundaryBindingMeta[];
+declare function resolveNestMethodKey(ctor: DecoratorHostConstructor, handler: DecoratorBoundMethod): string | symbol | undefined;
+declare function bindingRequestId<THost>(host: THost, binding: NestBoundaryBindingMeta, fallback?: string | ((host: THost) => string | undefined)): string | undefined;
+declare function bindingEmitOptions<THost>(host: THost, binding: NestIngressBindingMeta, requestId?: string): NestIngressEmitOptions<unknown>;
+declare function isDataIssue(value: unknown): value is DataIssue;
+declare function isHttpDataIssue(value: unknown): value is HttpDataIssue;
+declare function issueResponse<THost = unknown>(issue: DataIssue, _host?: THost): NestHttpResponsePayload;
+declare function protocolError<THost = unknown>(_errorPayload: unknown, _host?: THost): NestHttpResponsePayload;
+declare function lowerHttpReplyPayload<THost = unknown>(payload: unknown, host: THost, opts?: {
+    readonly issueResponse?: NestIssueResponse<THost>;
+}): NestHttpResponsePayload;
+declare function lowerProtocolError<THost = unknown>(errorPayload: unknown, host: THost, opts?: {
+    readonly protocolError?: NestProtocolErrorResponse<THost>;
+}): NestHttpResponsePayload;
+declare function sanitizeNestDiagnostic(diagnostic: NestDiagnosticInput, defaultPhase?: NestDiagnosticPhase): NestDiagnosticPayload;
+/** Register a method as a DATA-event handler for a graph observe path. */
+declare function OnGraphEvent(nodeName: string): GraphMethodDecorator;
+/** Register fixed-interval metadata for a user-land NestJS scheduler bridge. */
+declare function GraphInterval(ms: number): GraphMethodDecorator;
+
+export { CRON_HANDLERS, type DecoratorBoundMethod, type DecoratorHostConstructor, EVENT_HANDLERS, GRAPHREFLY_MODULE_OPTIONS, GRAPHREFLY_REQUEST_GRAPH, GRAPHREFLY_ROOT_GRAPH, GraphCron, type GraphCronMeta, GraphError, GraphFilter, GraphGuard, GraphGuardDecision, GraphHttpReply, GraphIntercept, GraphInterval, type GraphIntervalMeta, GraphLifecycle, GraphMessage, GraphMessageReply, type GraphMethodDecorator, GraphReq, GraphWs, GraphWsAck, GraphWsReply, type HttpDataIssue, INTERVAL_HANDLERS, NEST_BOUNDARY_BINDINGS, NEST_BOUNDARY_ENVELOPE_VERSION, NEST_BOUNDARY_PAYLOAD_MAX_BYTES, NEST_HTTP_DIAGNOSTICS_MAX_RETAINED, type NestBoundaryBindingDirection, type NestBoundaryBindingMeta, type NestBoundaryDecoratorOptions, type NestBoundaryDiagnostic, type NestBoundaryEnvelope, type NestBoundaryKind, type NestCallHandlerLike, type NestDiagnosticErrorPayload, type NestDiagnosticIngressBoundary, type NestDiagnosticInput, type NestDiagnosticPayload, type NestDiagnosticPhase, type NestDiagnosticsOptions, type NestEgressKind, type NestExecutionContextLike, type NestFilterDecoratorOptions, type NestFilterMode, type NestGraphBoundaryInterceptor, type NestGraphBoundaryInterceptorOptions, type NestGraphBoundaryRunner, type NestGraphBoundaryRunnerOptions, type NestGraphRunOptions, type NestGuardDecisionBindingMeta, type NestGuardDecisionDecoratorOptions, type NestHttpBoundary, type NestHttpPendingRegistration, type NestHttpReplyBindingMeta, type NestHttpReplyDecoratorOptions, type NestHttpResponseHandle, type NestHttpResponsePayload, type NestIngressBindingMeta, type NestIngressBoundary, type NestIngressEmitOptions, type NestIngressOptions, type NestIssueResponse, type NestMessageReplyBindingMeta, type NestProtocolErrorResponse, type NestProviderBinding, type NestReplyBoundary, type NestReplyEnvelope, type NestReplyPendingRegistration, type NestReplyResponseHandle, type NestWsAckBindingMeta, type NestWsReplyBindingMeta, OnGraphEvent, type OnGraphEventMeta, type ToNestHttpOptions, bindingEmitOptions, bindingRequestId, createNestGraphBoundaryInterceptor, createNestGraphBoundaryRunner, fromNestCron, fromNestDiagnostics, fromNestError, fromNestGuard, fromNestIntercept, fromNestLifecycle, fromNestMessage, fromNestReq, fromNestWs, getGraphToken, getNestBoundaryBindings, getNestBoundaryToken, getNodeToken, isDataIssue, isHttpDataIssue, issueResponse, lowerHttpReplyPayload, lowerProtocolError, nestProvider, protocolError, resolveNestMethodKey, sanitizeNestDiagnostic, toNestHttp };

package/dist/adapters/nestjs.js

@@ -0,0 +1,112 @@
+import {
+  CRON_HANDLERS,
+  EVENT_HANDLERS,
+  GRAPHREFLY_MODULE_OPTIONS,
+  GRAPHREFLY_REQUEST_GRAPH,
+  GRAPHREFLY_ROOT_GRAPH,
+  GraphCron,
+  GraphError,
+  GraphFilter,
+  GraphGuard,
+  GraphGuardDecision,
+  GraphHttpReply,
+  GraphIntercept,
+  GraphInterval,
+  GraphLifecycle,
+  GraphMessage,
+  GraphMessageReply,
+  GraphReq,
+  GraphWs,
+  GraphWsAck,
+  GraphWsReply,
+  INTERVAL_HANDLERS,
+  NEST_BOUNDARY_BINDINGS,
+  NEST_BOUNDARY_ENVELOPE_VERSION,
+  NEST_BOUNDARY_PAYLOAD_MAX_BYTES,
+  NEST_HTTP_DIAGNOSTICS_MAX_RETAINED,
+  OnGraphEvent,
+  bindingEmitOptions,
+  bindingRequestId,
+  createNestGraphBoundaryInterceptor,
+  createNestGraphBoundaryRunner,
+  fromNestCron,
+  fromNestDiagnostics,
+  fromNestError,
+  fromNestGuard,
+  fromNestIntercept,
+  fromNestLifecycle,
+  fromNestMessage,
+  fromNestReq,
+  fromNestWs,
+  getGraphToken,
+  getNestBoundaryBindings,
+  getNestBoundaryToken,
+  getNodeToken,
+  isDataIssue,
+  isHttpDataIssue,
+  issueResponse,
+  lowerHttpReplyPayload,
+  lowerProtocolError,
+  nestProvider,
+  protocolError,
+  resolveNestMethodKey,
+  sanitizeNestDiagnostic,
+  toNestHttp
+} from "../chunk-MQEQMS7B.js";
+import "../chunk-DGUM43GV.js";
+export {
+  CRON_HANDLERS,
+  EVENT_HANDLERS,
+  GRAPHREFLY_MODULE_OPTIONS,
+  GRAPHREFLY_REQUEST_GRAPH,
+  GRAPHREFLY_ROOT_GRAPH,
+  GraphCron,
+  GraphError,
+  GraphFilter,
+  GraphGuard,
+  GraphGuardDecision,
+  GraphHttpReply,
+  GraphIntercept,
+  GraphInterval,
+  GraphLifecycle,
+  GraphMessage,
+  GraphMessageReply,
+  GraphReq,
+  GraphWs,
+  GraphWsAck,
+  GraphWsReply,
+  INTERVAL_HANDLERS,
+  NEST_BOUNDARY_BINDINGS,
+  NEST_BOUNDARY_ENVELOPE_VERSION,
+  NEST_BOUNDARY_PAYLOAD_MAX_BYTES,
+  NEST_HTTP_DIAGNOSTICS_MAX_RETAINED,
+  OnGraphEvent,
+  bindingEmitOptions,
+  bindingRequestId,
+  createNestGraphBoundaryInterceptor,
+  createNestGraphBoundaryRunner,
+  fromNestCron,
+  fromNestDiagnostics,
+  fromNestError,
+  fromNestGuard,
+  fromNestIntercept,
+  fromNestLifecycle,
+  fromNestMessage,
+  fromNestReq,
+  fromNestWs,
+  getGraphToken,
+  getNestBoundaryBindings,
+  getNestBoundaryToken,
+  getNodeToken,
+  isDataIssue,
+  isHttpDataIssue,
+  issueResponse,
+  lowerHttpReplyPayload,
+  lowerProtocolError,
+  nestProvider,
+  protocolError,
+  resolveNestMethodKey,
+  sanitizeNestDiagnostic,
+  toNestHttp
+};
+//# sourceMappingURL=nestjs.js.map

package/dist/adapters/nestjs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/adapters/observe-storage.d.cts

@@ -1,12 +1,12 @@
-import { O as ObserveEvent, d as Graph } from '../graph-s23RbbFO.cjs';
+import { O as ObserveEvent, d as Graph } from '../graph-CWK3HLPB.cjs';
 import { d as AppendLogStorageTier } from '../append-log-DisvEReb.cjs';
 import { O as ObserveEventFrame } from '../observe-event-log-0SVsx7JG.cjs';
 export { c as ObserveEventLogPage } from '../observe-event-log-0SVsx7JG.cjs';
 import '../core/index.cjs';
-import '../types-bNMSWKqF.cjs';
-import '../messages-BZqrGGm1.cjs';
+import '../types-BS6CyR-x.cjs';
+import '../messages-CAzUPPJM.cjs';
 import '../codec-BB7p8fJc.cjs';
-import '../describe-Ciu8SUnN.cjs';
+import '../describe-CQRrkv-Q.cjs';
 
 /**
  * Graph-bound observe storage adapters.

package/dist/adapters/observe-storage.d.ts

@@ -1,12 +1,12 @@
-import { O as ObserveEvent, d as Graph } from '../graph-DfdF9zy4.js';
+import { O as ObserveEvent, d as Graph } from '../graph-ho5sotHP.js';
 import { d as AppendLogStorageTier } from '../append-log-DzKMmjxx.js';
 import { O as ObserveEventFrame } from '../observe-event-log-Dnm76owp.js';
 export { c as ObserveEventLogPage } from '../observe-event-log-Dnm76owp.js';
 import '../core/index.js';
-import '../types-h12mNYbq.js';
-import '../messages-BZqrGGm1.js';
+import '../types-C9NOgNJw.js';
+import '../messages-CAzUPPJM.js';
 import '../codec-BB7p8fJc.js';
-import '../describe-BZb7AS2y.js';
+import '../describe-B_A5fbXH.js';
 
 /**
  * Graph-bound observe storage adapters.

package/dist/adapters/observe-storage.js

@@ -1,9 +1,10 @@
 import {
   observeEventFrame
-} from "../chunk-K3FXTC3I.js";
-import "../chunk-6PHB5CJS.js";
-import "../chunk-DKP56CSW.js";
-import "../chunk-4VLAQHZI.js";
+} from "../chunk-HJACH5PU.js";
+import "../chunk-ZLFRB6FI.js";
+import "../chunk-JKAYLDQV.js";
+import "../chunk-K7FB3JTD.js";
+import "../chunk-DGUM43GV.js";
 
 // src/adapters/observe-storage.ts
 function attachObserveSink(graph, sink, opts = {}) {

package/dist/adapters/observe-storage.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/observe-storage.ts"],"sourcesContent":["/**\n * Graph-bound observe storage adapters.\n *\n * Passive storage lives under ../storage. This subpath owns bridges that need\n * Graph.observe() and therefore sit above both graph and passive storage (D125).\n */\n\nimport type { Graph } from \"../graph/graph.js\";\nimport type { ObserveEvent } from \"../graph/inspect.js\";\nimport type { AppendLogStorageTier } from \"../storage/append-log.js\";\nimport {\n\ttype ObserveEventFrame,\n\ttype ObserveEventLogPage,\n\tobserveEventFrame,\n} from \"../storage/observe-event-log.js\";\n\n/** Adapter-owned sink for observed graph events (D57/D74/D125). */\nexport interface ObserveSink<T = ObserveEvent> {\n\t/** Persist or forward one mapped observe event. Thenables are serialized in observe order. */\n\twrite(event: T): void | PromiseLike<void>;\n\t/** Optional adapter flush barrier. Runs after all earlier writes. */\n\tflush?(): void | PromiseLike<void>;\n\t/** Optional adapter rollback hook. Runs after all earlier writes. */\n\trollback?(): void | PromiseLike<void>;\n\t/** Optional adapter cleanup hook. Runs once after queued work drains. */\n\tdispose?(): void | PromiseLike<void>;\n}\n\n/** Error routing context for attachObserveSink lifecycle hooks. */\nexport interface ObserveSinkErrorContext<T = ObserveEvent> {\n\tphase: \"map\" | \"write\" | \"flush\" | \"rollback\" | \"dispose\";\n\tevent?: ObserveEvent;\n\tvalue?: T;\n}\n\n/** Queue-drain completion callback for observe-sink control calls (D75). */\nexport type ObserveSinkDone = () => void;\n\n/** Options for attaching a sink to the read-only observe egress (D74/D125). */\nexport interface AttachObserveSinkOptions<T = ObserveEvent> {\n\t/** Optional exact-id or subtree path filter; forwarded to `graph.observe(path?)`. */\n\tpath?: string;\n\t/** Optional projection/filter. Return `undefined` to drop an observed event. */\n\tmap?: (event: ObserveEvent) => T | undefined;\n\t/** Optional error hook for mapper, write, and lifecycle failures. */\n\tonError?: (error: unknown, ctx: ObserveSinkErrorContext<T>) => void;\n}\n\n/** Done-only callback control handle for an attached observe sink (D75). */\nexport interface ObserveSinkHandle {\n\tflush(done?: ObserveSinkDone): void;\n\trollback(done?: ObserveSinkDone): void;\n\tdispose(done?: ObserveSinkDone): void;\n}\n\ntype QueueItem<T> =\n\t| { kind: \"write\"; event: ObserveEvent; value: T }\n\t| { kind: \"flush\"; done?: ObserveSinkDone }\n\t| { kind: \"rollback\"; done?: ObserveSinkDone }\n\t| { kind: \"dispose\" };\n\n/** Options for persisting Graph.observe() events into an append log. */\nexport interface AttachObserveEventLogOptions<T = ObserveEvent> {\n\tpath?: string;\n\tstream?: string;\n\tmap?: (event: ObserveEvent) => T | undefined;\n\tonError?: (error: unknown, ctx: ObserveSinkErrorContext<ObserveEventFrame<T>>) => void;\n}\n\n/** Done-callback lifecycle handle for an attached observe-event log. */\nexport interface ObserveEventLogHandle extends ObserveSinkHandle {\n\tflush(done?: ObserveSinkDone): void;\n\trollback(done?: ObserveSinkDone): void;\n\tdispose(done?: ObserveSinkDone): void;\n}\n\nexport type { ObserveEventFrame, ObserveEventLogPage };\n\n/**\n * Attach adapter-owned storage to `Graph.observe()` read-only egress (D57/D74/D125). Writes are\n * serialized in observe order; lifecycle barriers drain the queue without mutating graph topology.\n */\nexport function attachObserveSink<T = ObserveEvent>(\n\tgraph: Graph,\n\tsink: ObserveSink<T>,\n\topts: AttachObserveSinkOptions<T> = {},\n): ObserveSinkHandle {\n\tconst { map, onError, path } = opts;\n\tconst queue: QueueItem<T>[] = [];\n\tconst disposeDone: ObserveSinkDone[] = [];\n\tlet draining = false;\n\tlet disposeRequested = false;\n\tlet disposed = false;\n\n\tfunction report(error: unknown, ctx: ObserveSinkErrorContext<T>): void {\n\t\tif (!onError) return;\n\t\ttry {\n\t\t\tonError(error, ctx);\n\t\t} catch {\n\t\t\t// Error routing is best-effort; never let adapter logging wedge the queue.\n\t\t}\n\t}\n\n\tfunction callDone(done?: ObserveSinkDone): void {\n\t\ttry {\n\t\t\tdone?.();\n\t\t} catch {\n\t\t\t// Completion callbacks are advisory only; never wedge the queue on observer code.\n\t\t}\n\t}\n\n\tfunction run(item: QueueItem<T>): void | PromiseLike<void> {\n\t\tswitch (item.kind) {\n\t\t\tcase \"write\":\n\t\t\t\treturn sink.write(item.value);\n\t\t\tcase \"flush\":\n\t\t\t\treturn sink.flush?.();\n\t\t\tcase \"rollback\":\n\t\t\t\treturn sink.rollback?.();\n\t\t\tcase \"dispose\":\n\t\t\t\treturn sink.dispose?.();\n\t\t}\n\t}\n\n\tfunction finish(item: QueueItem<T>): void {\n\t\tif (item.kind === \"dispose\") {\n\t\t\tdisposed = true;\n\t\t\tfor (const done of disposeDone.splice(0)) callDone(done);\n\t\t} else if (item.kind !== \"write\") {\n\t\t\tcallDone(item.done);\n\t\t}\n\t\tdraining = false;\n\t\tdrain();\n\t}\n\n\tfunction fail(item: QueueItem<T>, error: unknown): void {\n\t\tif (item.kind === \"write\")\n\t\t\treport(error, { phase: \"write\", event: item.event, value: item.value });\n\t\telse report(error, { phase: item.kind });\n\t\tfinish(item);\n\t}\n\n\tfunction chainThenable(item: QueueItem<T>, value: unknown): boolean {\n\t\tif ((typeof value !== \"object\" && typeof value !== \"function\") || value === null) return false;\n\n\t\tlet then: unknown;\n\t\ttry {\n\t\t\tthen = (value as { then?: unknown }).then;\n\t\t} catch (error) {\n\t\t\tfail(item, error);\n\t\t\treturn true;\n\t\t}\n\t\tif (typeof then !== \"function\") return false;\n\n\t\tlet settled = false;\n\t\tconst settle = (next: () => void) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tnext();\n\t\t};\n\t\ttry {\n\t\t\t(then as (onFulfilled: () => void, onRejected: (error: unknown) => void) => unknown).call(\n\t\t\t\tvalue,\n\t\t\t\t() => settle(() => finish(item)),\n\t\t\t\t(error) => settle(() => fail(item, error)),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tsettle(() => fail(item, error));\n\t\t}\n\t\treturn true;\n\t}\n\n\tfunction drain(): void {\n\t\tif (draining) return;\n\t\tconst item = queue.shift();\n\t\tif (!item) return;\n\t\tdraining = true;\n\t\tlet result: void | PromiseLike<void>;\n\t\ttry {\n\t\t\tresult = run(item);\n\t\t} catch (error) {\n\t\t\tfail(item, error);\n\t\t\treturn;\n\t\t}\n\t\tif (chainThenable(item, result)) return;\n\t\tfinish(item);\n\t}\n\n\tfunction enqueueBarrier(kind: \"flush\" | \"rollback\", done?: ObserveSinkDone): void {\n\t\tif (disposeRequested) {\n\t\t\tcallDone(done);\n\t\t\treturn;\n\t\t}\n\t\tqueue.push({ kind, done });\n\t\tdrain();\n\t}\n\n\tconst stop = graph.observe(path).subscribe((event) => {\n\t\tif (disposeRequested) return;\n\t\tlet value: T | undefined;\n\t\ttry {\n\t\t\tvalue = map ? map(event) : (event as unknown as T);\n\t\t} catch (error) {\n\t\t\treport(error, { phase: \"map\", event });\n\t\t\treturn;\n\t\t}\n\t\tif (value === undefined) return;\n\t\tqueue.push({ kind: \"write\", event, value });\n\t\tdrain();\n\t});\n\n\treturn {\n\t\tflush(done?: ObserveSinkDone): void {\n\t\t\tenqueueBarrier(\"flush\", done);\n\t\t},\n\t\trollback(done?: ObserveSinkDone): void {\n\t\t\tenqueueBarrier(\"rollback\", done);\n\t\t},\n\t\tdispose(done?: ObserveSinkDone): void {\n\t\t\tif (disposed) {\n\t\t\t\tcallDone(done);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (done) disposeDone.push(done);\n\t\t\tif (disposeRequested) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tdisposeRequested = true;\n\t\t\tstop();\n\t\t\tqueue.push({ kind: \"dispose\" });\n\t\t\tdrain();\n\t\t},\n\t};\n}\n\n/**\n * Persist Graph.observe() events to an append log. This is a graph-bound\n * adapter over passive storage frames, not graph restore or projection.\n */\nexport function attachObserveEventLog<T = ObserveEvent>(\n\tgraph: Graph,\n\tlog: AppendLogStorageTier<ObserveEventFrame<T>>,\n\topts: AttachObserveEventLogOptions<T> = {},\n): ObserveEventLogHandle {\n\treturn attachObserveSink<ObserveEventFrame<T>>(\n\t\tgraph,\n\t\t{ write: (frame) => log.append(frame).then(() => undefined) },\n\t\t{\n\t\t\tpath: opts.path,\n\t\t\tmap: (event) => {\n\t\t\t\tconst value = opts.map ? opts.map(event) : (event as unknown as T);\n\t\t\t\treturn value === undefined ? undefined : observeEventFrame(event, value, opts);\n\t\t\t},\n\t\t\tonError: opts.onError,\n\t\t},\n\t);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/adapters/observe-storage.ts"],"sourcesContent":["/**\n * Graph-bound observe storage adapters.\n *\n * Passive storage lives under ../storage. This subpath owns bridges that need\n * Graph.observe() and therefore sit above both graph and passive storage (D125).\n */\n\nimport type { Graph } from \"../graph/graph.js\";\nimport type { ObserveEvent } from \"../graph/inspect.js\";\nimport type { AppendLogStorageTier } from \"../storage/append-log.js\";\nimport {\n\ttype ObserveEventFrame,\n\ttype ObserveEventLogPage,\n\tobserveEventFrame,\n} from \"../storage/observe-event-log.js\";\n\n/** Adapter-owned sink for observed graph events (D57/D74/D125). */\nexport interface ObserveSink<T = ObserveEvent> {\n\t/** Persist or forward one mapped observe event. Thenables are serialized in observe order. */\n\twrite(event: T): void | PromiseLike<void>;\n\t/** Optional adapter flush barrier. Runs after all earlier writes. */\n\tflush?(): void | PromiseLike<void>;\n\t/** Optional adapter rollback hook. Runs after all earlier writes. */\n\trollback?(): void | PromiseLike<void>;\n\t/** Optional adapter cleanup hook. Runs once after queued work drains. */\n\tdispose?(): void | PromiseLike<void>;\n}\n\n/** Error routing context for attachObserveSink lifecycle hooks. */\nexport interface ObserveSinkErrorContext<T = ObserveEvent> {\n\tphase: \"map\" | \"write\" | \"flush\" | \"rollback\" | \"dispose\";\n\tevent?: ObserveEvent;\n\tvalue?: T;\n}\n\n/** Queue-drain completion callback for observe-sink control calls (D75). */\nexport type ObserveSinkDone = () => void;\n\n/** Options for attaching a sink to the read-only observe egress (D74/D125). */\nexport interface AttachObserveSinkOptions<T = ObserveEvent> {\n\t/** Optional exact-id or subtree path filter; forwarded to `graph.observe(path?)`. */\n\tpath?: string;\n\t/** Optional projection/filter. Return `undefined` to drop an observed event. */\n\tmap?: (event: ObserveEvent) => T | undefined;\n\t/** Optional error hook for mapper, write, and lifecycle failures. */\n\tonError?: (error: unknown, ctx: ObserveSinkErrorContext<T>) => void;\n}\n\n/** Done-only callback control handle for an attached observe sink (D75). */\nexport interface ObserveSinkHandle {\n\tflush(done?: ObserveSinkDone): void;\n\trollback(done?: ObserveSinkDone): void;\n\tdispose(done?: ObserveSinkDone): void;\n}\n\ntype QueueItem<T> =\n\t| { kind: \"write\"; event: ObserveEvent; value: T }\n\t| { kind: \"flush\"; done?: ObserveSinkDone }\n\t| { kind: \"rollback\"; done?: ObserveSinkDone }\n\t| { kind: \"dispose\" };\n\n/** Options for persisting Graph.observe() events into an append log. */\nexport interface AttachObserveEventLogOptions<T = ObserveEvent> {\n\tpath?: string;\n\tstream?: string;\n\tmap?: (event: ObserveEvent) => T | undefined;\n\tonError?: (error: unknown, ctx: ObserveSinkErrorContext<ObserveEventFrame<T>>) => void;\n}\n\n/** Done-callback lifecycle handle for an attached observe-event log. */\nexport interface ObserveEventLogHandle extends ObserveSinkHandle {\n\tflush(done?: ObserveSinkDone): void;\n\trollback(done?: ObserveSinkDone): void;\n\tdispose(done?: ObserveSinkDone): void;\n}\n\nexport type { ObserveEventFrame, ObserveEventLogPage };\n\n/**\n * Attach adapter-owned storage to `Graph.observe()` read-only egress (D57/D74/D125). Writes are\n * serialized in observe order; lifecycle barriers drain the queue without mutating graph topology.\n */\nexport function attachObserveSink<T = ObserveEvent>(\n\tgraph: Graph,\n\tsink: ObserveSink<T>,\n\topts: AttachObserveSinkOptions<T> = {},\n): ObserveSinkHandle {\n\tconst { map, onError, path } = opts;\n\tconst queue: QueueItem<T>[] = [];\n\tconst disposeDone: ObserveSinkDone[] = [];\n\tlet draining = false;\n\tlet disposeRequested = false;\n\tlet disposed = false;\n\n\tfunction report(error: unknown, ctx: ObserveSinkErrorContext<T>): void {\n\t\tif (!onError) return;\n\t\ttry {\n\t\t\tonError(error, ctx);\n\t\t} catch {\n\t\t\t// Error routing is best-effort; never let adapter logging wedge the queue.\n\t\t}\n\t}\n\n\tfunction callDone(done?: ObserveSinkDone): void {\n\t\ttry {\n\t\t\tdone?.();\n\t\t} catch {\n\t\t\t// Completion callbacks are advisory only; never wedge the queue on observer code.\n\t\t}\n\t}\n\n\tfunction run(item: QueueItem<T>): void | PromiseLike<void> {\n\t\tswitch (item.kind) {\n\t\t\tcase \"write\":\n\t\t\t\treturn sink.write(item.value);\n\t\t\tcase \"flush\":\n\t\t\t\treturn sink.flush?.();\n\t\t\tcase \"rollback\":\n\t\t\t\treturn sink.rollback?.();\n\t\t\tcase \"dispose\":\n\t\t\t\treturn sink.dispose?.();\n\t\t}\n\t}\n\n\tfunction finish(item: QueueItem<T>): void {\n\t\tif (item.kind === \"dispose\") {\n\t\t\tdisposed = true;\n\t\t\tfor (const done of disposeDone.splice(0)) callDone(done);\n\t\t} else if (item.kind !== \"write\") {\n\t\t\tcallDone(item.done);\n\t\t}\n\t\tdraining = false;\n\t\tdrain();\n\t}\n\n\tfunction fail(item: QueueItem<T>, error: unknown): void {\n\t\tif (item.kind === \"write\")\n\t\t\treport(error, { phase: \"write\", event: item.event, value: item.value });\n\t\telse report(error, { phase: item.kind });\n\t\tfinish(item);\n\t}\n\n\tfunction chainThenable(item: QueueItem<T>, value: unknown): boolean {\n\t\tif ((typeof value !== \"object\" && typeof value !== \"function\") || value === null) return false;\n\n\t\tlet then: unknown;\n\t\ttry {\n\t\t\tthen = (value as { then?: unknown }).then;\n\t\t} catch (error) {\n\t\t\tfail(item, error);\n\t\t\treturn true;\n\t\t}\n\t\tif (typeof then !== \"function\") return false;\n\n\t\tlet settled = false;\n\t\tconst settle = (next: () => void) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tnext();\n\t\t};\n\t\ttry {\n\t\t\t(then as (onFulfilled: () => void, onRejected: (error: unknown) => void) => unknown).call(\n\t\t\t\tvalue,\n\t\t\t\t() => settle(() => finish(item)),\n\t\t\t\t(error) => settle(() => fail(item, error)),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tsettle(() => fail(item, error));\n\t\t}\n\t\treturn true;\n\t}\n\n\tfunction drain(): void {\n\t\tif (draining) return;\n\t\tconst item = queue.shift();\n\t\tif (!item) return;\n\t\tdraining = true;\n\t\tlet result: void | PromiseLike<void>;\n\t\ttry {\n\t\t\tresult = run(item);\n\t\t} catch (error) {\n\t\t\tfail(item, error);\n\t\t\treturn;\n\t\t}\n\t\tif (chainThenable(item, result)) return;\n\t\tfinish(item);\n\t}\n\n\tfunction enqueueBarrier(kind: \"flush\" | \"rollback\", done?: ObserveSinkDone): void {\n\t\tif (disposeRequested) {\n\t\t\tcallDone(done);\n\t\t\treturn;\n\t\t}\n\t\tqueue.push({ kind, done });\n\t\tdrain();\n\t}\n\n\tconst stop = graph.observe(path).subscribe((event) => {\n\t\tif (disposeRequested) return;\n\t\tlet value: T | undefined;\n\t\ttry {\n\t\t\tvalue = map ? map(event) : (event as unknown as T);\n\t\t} catch (error) {\n\t\t\treport(error, { phase: \"map\", event });\n\t\t\treturn;\n\t\t}\n\t\tif (value === undefined) return;\n\t\tqueue.push({ kind: \"write\", event, value });\n\t\tdrain();\n\t});\n\n\treturn {\n\t\tflush(done?: ObserveSinkDone): void {\n\t\t\tenqueueBarrier(\"flush\", done);\n\t\t},\n\t\trollback(done?: ObserveSinkDone): void {\n\t\t\tenqueueBarrier(\"rollback\", done);\n\t\t},\n\t\tdispose(done?: ObserveSinkDone): void {\n\t\t\tif (disposed) {\n\t\t\t\tcallDone(done);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (done) disposeDone.push(done);\n\t\t\tif (disposeRequested) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tdisposeRequested = true;\n\t\t\tstop();\n\t\t\tqueue.push({ kind: \"dispose\" });\n\t\t\tdrain();\n\t\t},\n\t};\n}\n\n/**\n * Persist Graph.observe() events to an append log. This is a graph-bound\n * adapter over passive storage frames, not graph restore or projection.\n */\nexport function attachObserveEventLog<T = ObserveEvent>(\n\tgraph: Graph,\n\tlog: AppendLogStorageTier<ObserveEventFrame<T>>,\n\topts: AttachObserveEventLogOptions<T> = {},\n): ObserveEventLogHandle {\n\treturn attachObserveSink<ObserveEventFrame<T>>(\n\t\tgraph,\n\t\t{ write: (frame) => log.append(frame).then(() => undefined) },\n\t\t{\n\t\t\tpath: opts.path,\n\t\t\tmap: (event) => {\n\t\t\t\tconst value = opts.map ? opts.map(event) : (event as unknown as T);\n\t\t\t\treturn value === undefined ? undefined : observeEventFrame(event, value, opts);\n\t\t\t},\n\t\t\tonError: opts.onError,\n\t\t},\n\t);\n}\n"],"mappings":"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","names":[]}