@decaf-ts/integrations 0.8.0 → 0.10.0

package/lib/types/graph/engine/validation/GraphWorkflowDocumentValidator.d.mts

@@ -0,0 +1,162 @@
+/**
+ * @module integrations/graph/engine/validation/GraphWorkflowDocumentValidator
+ * @summary Nine-stage backend workflow-document validation gate (DECAF-50 §4.8).
+ * @description Validates a canonical {@link GraphWorkflowDocument} and, when
+ * valid, resolves it into a backend-only {@link GraphResolvedWorkflow} — the
+ * only input the {@link GraphExecutionPlanner} accepts. The nine stages run
+ * in the EXACT normative order 1→9:
+ *
+ * 1. workflow structure (shape, JSON safety, unique ids, backend-enforced
+ *    limits, forbidden definition/executor fields, recursive nested loop-body
+ *    validation),
+ * 2. kind resolution against the trusted backend catalogue,
+ * 3. parameters (declared-ness, required presence, typing, metadata keys,
+ *    disabled behavior, binding shapes),
+ * 4. dynamic ports (binding ids refer to effective ports),
+ * 5. edge endpoints (existence, direction, data/structural compatibility,
+ *    boundary routing),
+ * 6. connection policy (policies, counts, duplicates, self-connections),
+ * 7. topology (acyclicity, binding satisfaction, required-value
+ *    satisfiability),
+ * 8. credential-reference authorization (existence, authorization, type
+ *    match, no plain secrets),
+ * 9. capability validation.
+ *
+ * Issues accumulate as structured {@link GraphValidationIssue}s — validation
+ * never fails abruptly; a document with any issue is reported invalid and is
+ * never resolved. Fail-fast consumers (the execution engine) throw
+ * {@link GraphDocumentValidationError} on invalid results.
+ */
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.mts";
+import type { GraphNodeResolutionContext } from "@decaf-ts/ui-decorators/graph";
+import type { GraphCredentialAuthorizer } from "./GraphCredentialReferenceValidator.d.mts";
+import type { GraphWorkflowValidationResult } from "./GraphValidationIssue.d.mts";
+import type { GraphResolvedWorkflow } from "./GraphResolvedWorkflow.d.mts";
+/**
+ * Backend-enforced, configurable document resource limits (DECAF-50 §4.8).
+ * Mirrors the persistence-boundary limits; every value is overridable.
+ */
+export interface GraphWorkflowDocumentValidationLimits {
+    /** Maximum serialized size of the document in bytes. */
+    maxDocumentBytes?: number;
+    /** Maximum nested loop-body document depth (root document is depth 0). */
+    maxNestingDepth?: number;
+    /** Maximum node instances per document level. */
+    maxNodes?: number;
+    /** Maximum edge instances per document level. */
+    maxEdges?: number;
+}
+/**
+ * Default resource limits (technical governance delegates the numbers to
+ * implementation; these match the persistence boundary defaults).
+ */
+export declare const DEFAULT_GRAPH_WORKFLOW_VALIDATION_LIMITS: Required<GraphWorkflowDocumentValidationLimits>;
+/**
+ * Field keys that must never appear on a workflow document or any of its
+ * structural records: client input resembling node definitions, executors,
+ * authoritative ports, or frontend component definitions is rejected before
+ * kind resolution (the planner must never see raw definitions).
+ */
+export declare const GRAPH_DOCUMENT_FORBIDDEN_FIELD_KEYS: readonly string[];
+/**
+ * Options controlling the nine-stage validation gate.
+ */
+export interface GraphWorkflowDocumentValidatorOptions {
+    /** Trusted backend kind catalogue (required). */
+    catalogue: GraphNodeCatalogue;
+    /** Backend-enforced resource limits; defaults to {@link DEFAULT_GRAPH_WORKFLOW_VALIDATION_LIMITS}. */
+    limits?: GraphWorkflowDocumentValidationLimits;
+    /** Pluggable credential existence/authorization hook (DECAF-50 §4.16). */
+    credentialAuthorizer?: GraphCredentialAuthorizer;
+    /** Extra context passed to manifest resolution (credentials, request context). */
+    resolutionContext?: GraphNodeResolutionContext;
+    /**
+     * Transition leniency (§4.18): when `true`, a port with an incoming edge
+     * may also carry a literal binding. Defaults to `false` (conflicting
+     * literal+edge bindings are rejected).
+     */
+    allowLiteralAndEdgeBindings?: boolean;
+}
+/**
+ * Returns `true` when the value structurally looks like a resolved workflow
+ * (resolved node instances + resolved edges + lookup maps over a canonical
+ * document). Used as the planner's runtime input guard.
+ */
+export declare function isGraphResolvedWorkflow(value: unknown): value is GraphResolvedWorkflow;
+/**
+ * The nine-stage backend validation gate (DECAF-50 §4.8).
+ *
+ * Usage: `const result = await validator.validate(document);` — inspect
+ * `result.issues` (structured, in stage order) and `result.resolved` (present
+ * only when valid). Use {@link GraphWorkflowDocumentValidator.validateOrThrow}
+ * for the fail-fast engine path.
+ */
+export declare class GraphWorkflowDocumentValidator {
+    private readonly options;
+    private readonly nodeValidator;
+    private readonly parameterValidator;
+    private readonly edgeValidator;
+    private readonly connectionPolicyValidator;
+    private readonly credentialValidator;
+    constructor(options: GraphWorkflowDocumentValidatorOptions);
+    /**
+     * Fail-fast variant of {@link validate}: resolves the document or throws
+     * {@link GraphDocumentValidationError} carrying every structured issue.
+     */
+    validateOrThrow(document: GraphWorkflowDocument): Promise<GraphResolvedWorkflow>;
+    /**
+     * Runs the nine validation stages in the exact normative order 1→9 and,
+     * when the document is fully valid, resolves it against the backend
+     * catalogue.
+     *
+     * @param document - The canonical workflow document to validate.
+     * @param depth - Current nesting depth (root is 0); enforced against
+     *   `limits.maxNestingDepth` and used to guard recursive loop-body
+     *   validation.
+     * @returns The validation result with accumulated issues and, when valid,
+     *   the resolved workflow.
+     */
+    validate(document: GraphWorkflowDocument, depth?: number): Promise<GraphWorkflowValidationResult>;
+    /**
+     * Stage 1 — document structure. Returns `true` when the document is
+     * structurally sound enough to continue (shape and JSON safety are
+     * hard preconditions); all other findings accumulate as issues.
+     */
+    private validateStructure;
+    /**
+     * Stage 1 — unique node, edge, workflow-input and workflow-output ids.
+     */
+    private validateUniqueIds;
+    /**
+     * Stage 1 — backend-enforced configurable limits: document size, nesting
+     * depth, node count, edge count.
+     */
+    private validateLimits;
+    /**
+     * Stage 1 — recursive nested-workflow validation. Every loop body runs
+     * through the full nine-stage gate; nested issues are merged with a path
+     * prefix identifying the owning loop node.
+     */
+    private validateNestedBodies;
+    /**
+     * Stage 7 — acyclicity (DECAF-32 preserved). Kahn's algorithm over the
+     * resolved executable nodes; connection and data edges both count as
+     * dependencies. Loop constructs are excepted because their bodies are
+     * separate nested documents, validated recursively.
+     */
+    private validateAcyclicity;
+    /**
+     * Stage 7 — required values must be satisfiable: every required workflow
+     * output port must be routable from at least one node output.
+     */
+    private validateRequiredWorkflowOutputs;
+    /**
+     * Stage 9 — capability validation. Declared manifest capabilities must be
+     * known values, and document features that require a capability may only be
+     * used on kinds declaring it (loop configuration requires the `loop`
+     * capability). Lenient transition manifests (legacy executor-only
+     * registrations) are exempt until cutover (§4.18).
+     */
+    private validateCapabilities;
+}

package/lib/types/graph/engine/validation/index.d.cts

@@ -1,8 +1,19 @@
 /**
  * @module integrations/graph/validation
  * @summary Graph validation utilities.
- * @description Re-exports the definition validator, port schema resolver, and value validator.
+ * @description Re-exports the legacy definition/port/value validators plus
+ * the DECAF-50 §4.8 nine-stage document validation gate, structured issues,
+ * resolved-workflow types, and the normative validation error hierarchy.
  */
 export * from "./GraphDefinitionValidator.d.cts";
 export * from "./GraphPortSchemaResolver.d.cts";
 export * from "./GraphValueValidator.d.cts";
+export * from "./GraphValidationIssue.d.cts";
+export * from "./GraphValidationErrors.d.cts";
+export * from "./GraphResolvedWorkflow.d.cts";
+export * from "./GraphNodeInstanceValidator.d.cts";
+export * from "./GraphParameterValidator.d.cts";
+export * from "./GraphEdgeInstanceValidator.d.cts";
+export * from "./GraphConnectionPolicyValidator.d.cts";
+export * from "./GraphCredentialReferenceValidator.d.cts";
+export * from "./GraphWorkflowDocumentValidator.d.cts";

package/lib/types/graph/engine/validation/index.d.mts

@@ -1,8 +1,19 @@
 /**
  * @module integrations/graph/validation
  * @summary Graph validation utilities.
- * @description Re-exports the definition validator, port schema resolver, and value validator.
+ * @description Re-exports the legacy definition/port/value validators plus
+ * the DECAF-50 §4.8 nine-stage document validation gate, structured issues,
+ * resolved-workflow types, and the normative validation error hierarchy.
  */
 export * from "./GraphDefinitionValidator.d.mts";
 export * from "./GraphPortSchemaResolver.d.mts";
 export * from "./GraphValueValidator.d.mts";
+export * from "./GraphValidationIssue.d.mts";
+export * from "./GraphValidationErrors.d.mts";
+export * from "./GraphResolvedWorkflow.d.mts";
+export * from "./GraphNodeInstanceValidator.d.mts";
+export * from "./GraphParameterValidator.d.mts";
+export * from "./GraphEdgeInstanceValidator.d.mts";
+export * from "./GraphConnectionPolicyValidator.d.mts";
+export * from "./GraphCredentialReferenceValidator.d.mts";
+export * from "./GraphWorkflowDocumentValidator.d.mts";

package/lib/types/graph/index.d.cts

@@ -1,12 +1,12 @@
 /**
  * @module integrations/graph
  * @summary Decaf Graph Execution Engine (backend convenience export).
- * @description Re-exports `./engine`, which in turn re-exports `./shared`
- * (frontend-safe declarations) plus all engine modules. Backend consumers
+ * @description Re-exports `./engine` (all engine modules). Backend consumers
  * import from `@decaf-ts/integrations/graph` and get a single unified surface.
  *
- * Frontend bundles MUST import from `@decaf-ts/integrations/graph/shared`
- * instead to avoid pulling in the execution engine.
+ * Frontend-safe shared declarations (node kinds, types, constants) live in
+ * `@decaf-ts/ui-decorators/graph` — frontend bundles MUST import from there
+ * to avoid pulling in the execution engine.
  */
 import "./log/LogParameters";
 export * from "./engine/index.d.cts";

package/lib/types/graph/index.d.mts

@@ -1,12 +1,12 @@
 /**
  * @module integrations/graph
  * @summary Decaf Graph Execution Engine (backend convenience export).
- * @description Re-exports `./engine`, which in turn re-exports `./shared`
- * (frontend-safe declarations) plus all engine modules. Backend consumers
+ * @description Re-exports `./engine` (all engine modules). Backend consumers
  * import from `@decaf-ts/integrations/graph` and get a single unified surface.
  *
- * Frontend bundles MUST import from `@decaf-ts/integrations/graph/shared`
- * instead to avoid pulling in the execution engine.
+ * Frontend-safe shared declarations (node kinds, types, constants) live in
+ * `@decaf-ts/ui-decorators/graph` — frontend bundles MUST import from there
+ * to avoid pulling in the execution engine.
  */
 import "./log/LogParameters";
 export * from "./engine/index.d.mts";

package/lib/types/graph/log/GraphRunLogger.d.cts

@@ -1,5 +1,5 @@
 import type { Logger, LogMeta, StringLike } from "@decaf-ts/logging";
-import type { GraphExecutionEvent } from "../shared/types.d.cts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Signature of the context's event emitter used to forward log entries onto
  * the existing graph execution Observable.
@@ -60,6 +60,10 @@ export declare class GraphRunLogger implements Logger {
     /** @inheritdoc */
     debug(msg: StringLike, meta?: LogMeta): void;
     /** @inheritdoc */
+    action(action: string, meta?: LogMeta): void;
+    /** @inheritdoc */
+    action(action: string, code: number, meta?: LogMeta): void;
+    /** @inheritdoc */
     setConfig(): void;
     /** @inheritdoc */
     for(_method?: string | ((...args: any[]) => any) | {

package/lib/types/graph/log/GraphRunLogger.d.mts

@@ -1,5 +1,5 @@
 import type { Logger, LogMeta, StringLike } from "@decaf-ts/logging";
-import type { GraphExecutionEvent } from "../shared/types.d.mts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Signature of the context's event emitter used to forward log entries onto
  * the existing graph execution Observable.
@@ -60,6 +60,10 @@ export declare class GraphRunLogger implements Logger {
     /** @inheritdoc */
     debug(msg: StringLike, meta?: LogMeta): void;
     /** @inheritdoc */
+    action(action: string, meta?: LogMeta): void;
+    /** @inheritdoc */
+    action(action: string, code: number, meta?: LogMeta): void;
+    /** @inheritdoc */
     setConfig(): void;
     /** @inheritdoc */
     for(_method?: string | ((...args: any[]) => any) | {

package/lib/types/index.d.cts

@@ -7,6 +7,6 @@ export * from "./utils.d.cts";
 export * from "./namespaces/index.d.cts";
 export * from "./feature-flags/index.d.cts";
 export declare const VERSION: string;
-export declare const COMMIT = "2a891e0";
-export declare const FULL_VERSION = "0.7.0-2a891e0";
+export declare const COMMIT = "1d7b1fb";
+export declare const FULL_VERSION = "0.9.0-1d7b1fb";
 export declare const PACKAGE_NAME: string;

package/lib/types/index.d.mts

@@ -7,6 +7,6 @@ export * from "./utils.d.mts";
 export * from "./namespaces/index.d.mts";
 export * from "./feature-flags/index.d.mts";
 export declare const VERSION: string;
-export declare const COMMIT = "2a891e0";
-export declare const FULL_VERSION = "0.7.0-2a891e0";
+export declare const COMMIT = "1d7b1fb";
+export declare const FULL_VERSION = "0.9.0-1d7b1fb";
 export declare const PACKAGE_NAME: string;

package/lib/types/nest/graph/GraphExecutionController.d.cts

@@ -1,29 +1,108 @@
+/**
+ * @module integrations/nest/graph/GraphExecutionController
+ * @summary Legacy synchronous graph execution surface (SAA-595).
+ * @description The deprecated `POST /graph/execute` endpoint, the deprecated
+ * global `SSE /graph/events` stream, plus the run-result read and workflow
+ * persistence endpoints. All execution now flows through
+ * {@link GraphRunService}; only canonical documents are accepted (inline
+ * node/definition/executor/ports/component fields are rejected at the
+ * boundary) and the global stream is disabled unless explicitly enabled.
+ */
 import { MessageEvent } from "@nestjs/common";
 import { Observable } from "rxjs";
-import { GraphExecutionEngine, type GraphExecutionValues } from "../../graph/index.d.cts";
-import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import { GraphExecutionEngine, GraphRunService, type GraphExecutionValues } from "../../graph/index.d.cts";
+import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
 import { DecafRequestContext } from "@decaf-ts/for-nest";
 import { GraphResultService } from "./GraphResultService.d.cts";
 import { GraphWorkflowService } from "./GraphWorkflowService.d.cts";
+/** DI token for {@link GraphExecutionControllerOptions}. */
+export declare const GRAPH_EXECUTION_OPTIONS = "GRAPH_EXECUTION_OPTIONS";
+/**
+ * Options for the legacy execution surface (SAA-595): the deprecated global
+ * SSE stream is disabled unless explicitly enabled, and when enabled every
+ * emitted event is ownership-gated against the connected caller.
+ */
+export interface GraphExecutionControllerOptions {
+    /**
+     * Whether the deprecated global `GET /graph/events` SSE stream is exposed
+     * at all. Defaults to `false`: the run-scoped, replayable
+     * `GET /graph/runs/{runId}/events` transport is the canonical stream
+     * (DECAF-50 §4.15). When `true`, each connected caller only receives
+     * events for runs they own.
+     */
+    enableGlobalEventStream?: boolean;
+}
+/**
+ * Execution payloads accept a canonical {@link GraphWorkflowDocument} only
+ * (DECAF-50 §4.16 cutover): client payloads carrying legacy definitions,
+ * snapshots, or inline node/definition/executor/ports/component fields are
+ * rejected at the boundary.
+ */
 export interface GraphExecutePayload {
-    workflow: GraphWorkflowDefinition;
+    workflow: GraphWorkflowDocument;
     inputs: GraphExecutionValues;
 }
+/** Response of the (deprecated) synchronous execute endpoint: run id, terminal status, and output values. */
 export interface GraphExecuteResponse {
     runId: string;
     status: string;
     outputs: Record<string, unknown>;
 }
+/**
+ * Legacy synchronous graph execution surface (DECAF-50 §4.14/§4.18): the
+ * `POST /graph/execute` endpoint (deprecated in favour of the run lifecycle
+ * at `POST /graph/runs`), the legacy `PUT /graph/:id/execute` alias, and the
+ * deprecated global SSE event stream. All execution now flows through
+ * {@link GraphRunService}; only canonical documents are accepted.
+ */
 export declare class GraphExecutionController {
     private readonly engine;
     private readonly resultService;
     private readonly workflowService;
+    private readonly runService;
     private readonly requestContext?;
+    private readonly options;
     private readonly eventSubject;
-    constructor(engine: GraphExecutionEngine, resultService: GraphResultService, workflowService: GraphWorkflowService, requestContext?: DecafRequestContext | undefined);
+    constructor(engine: GraphExecutionEngine, resultService: GraphResultService, workflowService: GraphWorkflowService, runService: GraphRunService, requestContext?: DecafRequestContext | undefined, options?: GraphExecutionControllerOptions);
+    /**
+     * @deprecated DECAF-50 §4.14/§4.18 cutover: the synchronous execution
+     * endpoint is deprecated in favour of the asynchronous run lifecycle
+     * (`POST /graph/runs`). It is kept, not removed, within this
+     * specification. Only canonical {@link GraphWorkflowDocument} payloads are
+     * accepted; legacy definition/snapshot payloads and inline
+     * node/definition/executor/ports/component fields are rejected (§4.16).
+     */
     execute(body: GraphExecutePayload): Promise<GraphExecuteResponse>;
+    /**
+     * DECAF-50 §4.16 cutover: only a canonical {@link GraphWorkflowDocument}
+     * is accepted. Payloads resembling legacy decorated definitions, snapshot
+     * wrappers, or any other non-canonical shape are rejected with a Decaf
+     * {@link ValidationError} before the engine or planner sees them.
+     */
+    private requireCanonicalDocument;
+    /**
+     * @deprecated DECAF-50 §4.15 cutover (SAA-595 F2): the global `/graph/events`
+     * stream is disabled by default — the run-scoped, authorized, replayable
+     * `GET /graph/runs/{runId}/events` transport is the canonical stream. Hosts
+     * with a residual transition need may re-enable it explicitly via
+     * {@link GraphExecutionControllerOptions.enableGlobalEventStream}; every
+     * event is then ownership-gated at emit: a connected caller only ever
+     * receives events for runs they own.
+     */
     events(): Observable<MessageEvent>;
+    /** Encodes one engine event in the global stream's wire format: a `["graph", type, runId, envelope]` SSE message tuple. */
+    private messageOf;
+    /** Strict ownership gate for the global stream: only run owners see their runs' events. */
+    private callerOwnsRun;
+    /**
+     * Reads a persisted execution result by run id (DECAF-50 §4.18). Gated
+     * through the centralized run ownership check first (SAA-595 F1): a
+     * cross-user or anonymous caller gets `403` for a run owned by another
+     * user before any result data is read.
+     */
     getResult(runId: string): Promise<unknown>;
+    /** Concurrency-bucket key for the per-caller run cap: the owner, else the request IP, else a shared anonymous bucket. */
+    private concurrencyKeyOf;
     saveWorkflow(id: string, snapshot: Record<string, unknown>): Promise<{
         workflowId: string;
         savedAt: string;

package/lib/types/nest/graph/GraphExecutionController.d.mts

@@ -1,29 +1,108 @@
+/**
+ * @module integrations/nest/graph/GraphExecutionController
+ * @summary Legacy synchronous graph execution surface (SAA-595).
+ * @description The deprecated `POST /graph/execute` endpoint, the deprecated
+ * global `SSE /graph/events` stream, plus the run-result read and workflow
+ * persistence endpoints. All execution now flows through
+ * {@link GraphRunService}; only canonical documents are accepted (inline
+ * node/definition/executor/ports/component fields are rejected at the
+ * boundary) and the global stream is disabled unless explicitly enabled.
+ */
 import { MessageEvent } from "@nestjs/common";
 import { Observable } from "rxjs";
-import { GraphExecutionEngine, type GraphExecutionValues } from "../../graph/index.d.mts";
-import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import { GraphExecutionEngine, GraphRunService, type GraphExecutionValues } from "../../graph/index.d.mts";
+import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
 import { DecafRequestContext } from "@decaf-ts/for-nest";
 import { GraphResultService } from "./GraphResultService.d.mts";
 import { GraphWorkflowService } from "./GraphWorkflowService.d.mts";
+/** DI token for {@link GraphExecutionControllerOptions}. */
+export declare const GRAPH_EXECUTION_OPTIONS = "GRAPH_EXECUTION_OPTIONS";
+/**
+ * Options for the legacy execution surface (SAA-595): the deprecated global
+ * SSE stream is disabled unless explicitly enabled, and when enabled every
+ * emitted event is ownership-gated against the connected caller.
+ */
+export interface GraphExecutionControllerOptions {
+    /**
+     * Whether the deprecated global `GET /graph/events` SSE stream is exposed
+     * at all. Defaults to `false`: the run-scoped, replayable
+     * `GET /graph/runs/{runId}/events` transport is the canonical stream
+     * (DECAF-50 §4.15). When `true`, each connected caller only receives
+     * events for runs they own.
+     */
+    enableGlobalEventStream?: boolean;
+}
+/**
+ * Execution payloads accept a canonical {@link GraphWorkflowDocument} only
+ * (DECAF-50 §4.16 cutover): client payloads carrying legacy definitions,
+ * snapshots, or inline node/definition/executor/ports/component fields are
+ * rejected at the boundary.
+ */
 export interface GraphExecutePayload {
-    workflow: GraphWorkflowDefinition;
+    workflow: GraphWorkflowDocument;
     inputs: GraphExecutionValues;
 }
+/** Response of the (deprecated) synchronous execute endpoint: run id, terminal status, and output values. */
 export interface GraphExecuteResponse {
     runId: string;
     status: string;
     outputs: Record<string, unknown>;
 }
+/**
+ * Legacy synchronous graph execution surface (DECAF-50 §4.14/§4.18): the
+ * `POST /graph/execute` endpoint (deprecated in favour of the run lifecycle
+ * at `POST /graph/runs`), the legacy `PUT /graph/:id/execute` alias, and the
+ * deprecated global SSE event stream. All execution now flows through
+ * {@link GraphRunService}; only canonical documents are accepted.
+ */
 export declare class GraphExecutionController {
     private readonly engine;
     private readonly resultService;
     private readonly workflowService;
+    private readonly runService;
     private readonly requestContext?;
+    private readonly options;
     private readonly eventSubject;
-    constructor(engine: GraphExecutionEngine, resultService: GraphResultService, workflowService: GraphWorkflowService, requestContext?: DecafRequestContext | undefined);
+    constructor(engine: GraphExecutionEngine, resultService: GraphResultService, workflowService: GraphWorkflowService, runService: GraphRunService, requestContext?: DecafRequestContext | undefined, options?: GraphExecutionControllerOptions);
+    /**
+     * @deprecated DECAF-50 §4.14/§4.18 cutover: the synchronous execution
+     * endpoint is deprecated in favour of the asynchronous run lifecycle
+     * (`POST /graph/runs`). It is kept, not removed, within this
+     * specification. Only canonical {@link GraphWorkflowDocument} payloads are
+     * accepted; legacy definition/snapshot payloads and inline
+     * node/definition/executor/ports/component fields are rejected (§4.16).
+     */
     execute(body: GraphExecutePayload): Promise<GraphExecuteResponse>;
+    /**
+     * DECAF-50 §4.16 cutover: only a canonical {@link GraphWorkflowDocument}
+     * is accepted. Payloads resembling legacy decorated definitions, snapshot
+     * wrappers, or any other non-canonical shape are rejected with a Decaf
+     * {@link ValidationError} before the engine or planner sees them.
+     */
+    private requireCanonicalDocument;
+    /**
+     * @deprecated DECAF-50 §4.15 cutover (SAA-595 F2): the global `/graph/events`
+     * stream is disabled by default — the run-scoped, authorized, replayable
+     * `GET /graph/runs/{runId}/events` transport is the canonical stream. Hosts
+     * with a residual transition need may re-enable it explicitly via
+     * {@link GraphExecutionControllerOptions.enableGlobalEventStream}; every
+     * event is then ownership-gated at emit: a connected caller only ever
+     * receives events for runs they own.
+     */
     events(): Observable<MessageEvent>;
+    /** Encodes one engine event in the global stream's wire format: a `["graph", type, runId, envelope]` SSE message tuple. */
+    private messageOf;
+    /** Strict ownership gate for the global stream: only run owners see their runs' events. */
+    private callerOwnsRun;
+    /**
+     * Reads a persisted execution result by run id (DECAF-50 §4.18). Gated
+     * through the centralized run ownership check first (SAA-595 F1): a
+     * cross-user or anonymous caller gets `403` for a run owned by another
+     * user before any result data is read.
+     */
     getResult(runId: string): Promise<unknown>;
+    /** Concurrency-bucket key for the per-caller run cap: the owner, else the request IP, else a shared anonymous bucket. */
+    private concurrencyKeyOf;
     saveWorkflow(id: string, snapshot: Record<string, unknown>): Promise<{
         workflowId: string;
         savedAt: string;

package/lib/types/nest/graph/GraphExecutionModule.d.cts

@@ -1,4 +1,25 @@
+/**
+ * @module integrations/nest/graph/GraphExecutionModule
+ * @summary NestJS graph backend module wiring (DECAF-50 §4.10–§4.16).
+ * @description The dynamic module assembling the graph backend: the
+ * {@link GraphExecutionEngine}, the trusted {@link GraphNodeCatalogue} with
+ * built-in registrations, the run lifecycle services and stores, and the
+ * HTTP/SSE controllers (catalogue, workflows, runs, legacy execution) — each
+ * configurable with authentication enforcement and backend-enforced
+ * resource limits via {@link GraphExecutionModuleOptions}.
+ */
 import { DynamicModule } from "@nestjs/common";
+import { type GraphCredentialAuthorizer } from "../../graph/index.d.cts";
+import { type GraphExecutionControllerOptions } from "./GraphExecutionController.d.cts";
+import { type GraphCatalogueControllerOptions } from "./GraphNodeCatalogueController.d.cts";
+import { type GraphRunControllerOptions } from "./GraphRunController.d.cts";
+import { type GraphWorkflowServiceOptions } from "./GraphWorkflowService.d.cts";
+import { type GraphWorkflowControllerOptions } from "./GraphWorkflowController.d.cts";
+/**
+ * Options for {@link GraphExecutionModule.forRoot}: adapter bootstrapping
+ * plus per-API (catalogue, workflows, runs) authentication and limit
+ * configuration.
+ */
 export interface GraphExecutionModuleOptions {
     /**
      * When `true`, the module bootstraps a default RamAdapter for standalone
@@ -13,7 +34,50 @@ export interface GraphExecutionModuleOptions {
      * Defaults to `"graph-engine"`.
      */
     adapterUser?: string;
+    /**
+     * Options for the node catalogue HTTP API (DECAF-50 §4.13): authentication
+     * enforcement and backend-enforced rate limits for the expensive
+     * `resolve`/`methods` operations.
+     */
+    catalogue?: GraphCatalogueControllerOptions;
+    /**
+     * Options for the canonical workflow persistence HTTP API (DECAF-50 §4.10):
+     * authentication enforcement and backend-enforced document resource limits.
+     */
+    workflows?: GraphWorkflowControllerOptions & GraphWorkflowServiceOptions;
+    /**
+     * Options for the asynchronous run lifecycle API (DECAF-50 §4.14–§4.15):
+     * authentication enforcement and backend-enforced run resource limits.
+     */
+    runs?: GraphRunControllerOptions;
+    /**
+     * Options for the legacy synchronous execution surface (SAA-595): the
+     * deprecated global SSE stream is disabled unless explicitly enabled.
+     */
+    execution?: GraphExecutionControllerOptions;
+    /**
+     * Production hosts MUST wire a {@link GraphCredentialAuthorizer} backed by
+     * their credential store (DECAF-50 §4.8 stage 8). Without it, stage-8
+     * credential checks are shape/type-only: a reference that is
+     * well-formed and type-matched is accepted without verifying that the
+     * credential exists or that the run is authorized to use it (SAA-595 F8).
+     */
+    credentialAuthorizer?: GraphCredentialAuthorizer;
 }
+/**
+ * NestJS module wiring the graph execution stack (DECAF-50 §4.13–§4.16): the
+ * engine, catalogue, workflow persistence, run lifecycle/SSE controllers,
+ * and their services. Configure via {@link GraphExecutionModule.forRoot}.
+ */
 export declare class GraphExecutionModule {
+    /**
+     * Creates the dynamic module. Boots a default RamAdapter for standalone
+     * development unless `initAdapter` is `false`. Wires the optional
+     * {@link GraphCredentialAuthorizer} into the engine's stage-8 validator
+     * (SAA-595 F8), and applies the workflow options to the
+     * {@link GraphWorkflowService} singleton via its {@link
+     * GraphWorkflowService.configure} method, since `@service` constructor
+     * injection does not forward provider options reliably.
+     */
     static forRoot(options?: GraphExecutionModuleOptions): DynamicModule;
 }