@decaf-ts/integrations 0.7.0 → 0.9.0

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;
 }

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

@@ -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.mts";
+import { type GraphExecutionControllerOptions } from "./GraphExecutionController.d.mts";
+import { type GraphCatalogueControllerOptions } from "./GraphNodeCatalogueController.d.mts";
+import { type GraphRunControllerOptions } from "./GraphRunController.d.mts";
+import { type GraphWorkflowServiceOptions } from "./GraphWorkflowService.d.mts";
+import { type GraphWorkflowControllerOptions } from "./GraphWorkflowController.d.mts";
+/**
+ * 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;
 }

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

@@ -1,7 +1,19 @@
 import { BaseModel } from "@decaf-ts/core";
+/**
+ * Persisted terminal snapshot of one graph run (written by
+ * {@link GraphResultService} after the deprecated synchronous execute
+ * endpoint completes). Keyed by `runId`; the optional `owner` column (added
+ * by SAA-595 F1) records the run's owning user so result reads can be
+ * ownership-gated at the route layer.
+ */
 export declare class GraphExecutionResultModel extends BaseModel {
     runId: string;
     workflowId: string;
+    /**
+     * Owning user of the run this result belongs to (SAA-595 F1); absent for
+     * legacy/anonymous results, which carry no enforceable ownership.
+     */
+    owner?: string;
     status: string;
     inputs: Record<string, unknown>;
     outputs: Record<string, unknown>;

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

@@ -1,7 +1,19 @@
 import { BaseModel } from "@decaf-ts/core";
+/**
+ * Persisted terminal snapshot of one graph run (written by
+ * {@link GraphResultService} after the deprecated synchronous execute
+ * endpoint completes). Keyed by `runId`; the optional `owner` column (added
+ * by SAA-595 F1) records the run's owning user so result reads can be
+ * ownership-gated at the route layer.
+ */
 export declare class GraphExecutionResultModel extends BaseModel {
     runId: string;
     workflowId: string;
+    /**
+     * Owning user of the run this result belongs to (SAA-595 F1); absent for
+     * legacy/anonymous results, which carry no enforceable ownership.
+     */
+    owner?: string;
     status: string;
     inputs: Record<string, unknown>;
     outputs: Record<string, unknown>;

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

@@ -1,41 +1,54 @@
 /**
  * @module integrations/nest/graph/GraphExecutorRegistryFactory
- * @summary Factory that builds a populated {@link GraphNodeExecutorRegistry}.
- * @description Creates a registry pre-loaded with the demo executors used by
- * the graph execution backend's sample workflows. The executors cover the
- * flow-control kinds (including Code, Log, and Switch with code conditions),
- * the DECAF-48 `core.utility.log` Log node, the agent kind, and the loop
- * kinds. Additional executors can be registered on the returned registry
- * before it is handed to the {@link GraphExecutionEngine}.
+ * @summary Factory that builds a populated {@link GraphNodeCatalogue} and its
+ * {@link GraphNodeExecutorRegistry} compatibility facade.
+ * @description Creates a catalogue pre-loaded with the DECAF-50 built-in
+ * manifest+executor registrations plus the demo executors used by the graph
+ * execution backend's sample workflows. The catalogue is the single
+ * kind→registration map (DECAF-50 §4.7); the returned registry is a facade
+ * over it, so no second executor map exists.
  */
-import { GraphNodeExecutorRegistry, GraphExecutionEngine, type GraphNodeExecutor, IsolatedVmCodeSandboxEvaluator } from "../../graph/index.d.cts";
+import { GraphNodeCatalogue, GraphNodeExecutorRegistry, GraphExecutionEngine, type GraphNodeExecutor, IsolatedVmCodeSandboxEvaluator } from "../../graph/index.d.cts";
 /**
- * Builds a {@link GraphNodeExecutorRegistry} populated with the demo executors.
+ * Builds a {@link GraphNodeCatalogue} populated with the built-in
+ * manifest+executor registrations and the arithmetic demo executors, wrapped
+ * with its {@link GraphNodeExecutorRegistry} facade.
  *
- * Executors are registered by **node kind** (the same key the engine uses to
- * resolve executors at runtime). The for-angular demo nodes use the kind as
- * their tag, so the same key works for both dispatch-by-kind and
- * dispatch-by-tag.
+ * The built-in kinds whose executors need the engine instance (loops, Code,
+ * Switch) are only registered by {@link createDemoEngineConfig}'s
+ * `onEngineCreated` hook via {@link registerEngineBoundGraphNodes}.
  *
- * Registered kinds:
- * - `math.add`, `math.multiply` — arithmetic demo executors.
- * - `core.flow.*` — flow-control kinds (map, delay, return, merge, if,
- *   parallel, errorBoundary, humanApproval). The `core.flow.code`,
- *   `core.flow.log`, and `core.flow.switch` kinds are registered in
- *   `onEngineCreated` via their real executors because Code and Switch
- *   need the engine's `codeSandboxEvaluator`.
- * - `core.agent` — agent node.
- * - `core.loop.foreach`, `core.loop.while`, `core.loop.until` — loop executors
- *   (registered after the engine is created via `onEngineCreated`).
+ * @param extra - Additional executor registrations to merge into the catalogue.
+ * @returns The populated catalogue and its registry facade.
+ */
+export declare function createGraphNodeCatalogue(extra?: Record<string, GraphNodeExecutor>): {
+    catalogue: GraphNodeCatalogue;
+    registry: GraphNodeExecutorRegistry;
+};
+/**
+ * Builds a {@link GraphNodeExecutorRegistry} facade over a populated
+ * {@link GraphNodeCatalogue} (compatibility entry point).
  *
- * @param extra - Additional executors to merge into the registry.
- * @returns A populated registry ready for use with {@link GraphExecutionEngine}.
+ * @param extra - Additional executor registrations to merge into the catalogue.
+ * @returns The registry facade; the underlying catalogue is available as
+ * `registry.catalog`.
  */
 export declare function createGraphExecutorRegistry(extra?: Record<string, GraphNodeExecutor>): GraphNodeExecutorRegistry;
 /**
- * Builds a {@link GraphExecutionEngineConfig} populated with all demo executors
- * including loop executors that need a back-reference to the engine and the
- * Code node executor that needs the engine's `codeSandboxEvaluator`.
+ * Registers the engine-bound built-in kinds (loops, Code, Switch) on an
+ * existing catalogue, replacing their placeholder-free entries with the real
+ * engine-bound executors.
+ *
+ * @param catalogue - The catalogue receiving the registrations.
+ * @param engine - The engine instance the loop/Code/Switch executors bind to.
+ * @returns The catalogue with the engine-bound registrations applied.
+ */
+export declare function registerEngineBoundGraphNodes(catalogue: GraphNodeCatalogue, engine: GraphExecutionEngine): GraphNodeCatalogue;
+/**
+ * Builds a `GraphExecutionEngineConfig` populated with all built-in
+ * registrations including loop executors that need a back-reference to the
+ * engine and the Code node executor that needs the engine's
+ * `codeSandboxEvaluator`.
  *
  * The config wires an {@link IsolatedVmCodeSandboxEvaluator} (backed by
  * `isolated-vm`) so the Code Node runs in a truly isolated V8 sandbox.
@@ -43,6 +56,7 @@ export declare function createGraphExecutorRegistry(extra?: Record<string, Graph
  * @returns A config object ready for `new GraphExecutionEngine(config)`.
  */
 export declare function createDemoEngineConfig(): {
+    catalogue: GraphNodeCatalogue;
     registry: GraphNodeExecutorRegistry;
     defaultOptions: {
         failFast: boolean;

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

@@ -1,41 +1,54 @@
 /**
  * @module integrations/nest/graph/GraphExecutorRegistryFactory
- * @summary Factory that builds a populated {@link GraphNodeExecutorRegistry}.
- * @description Creates a registry pre-loaded with the demo executors used by
- * the graph execution backend's sample workflows. The executors cover the
- * flow-control kinds (including Code, Log, and Switch with code conditions),
- * the DECAF-48 `core.utility.log` Log node, the agent kind, and the loop
- * kinds. Additional executors can be registered on the returned registry
- * before it is handed to the {@link GraphExecutionEngine}.
+ * @summary Factory that builds a populated {@link GraphNodeCatalogue} and its
+ * {@link GraphNodeExecutorRegistry} compatibility facade.
+ * @description Creates a catalogue pre-loaded with the DECAF-50 built-in
+ * manifest+executor registrations plus the demo executors used by the graph
+ * execution backend's sample workflows. The catalogue is the single
+ * kind→registration map (DECAF-50 §4.7); the returned registry is a facade
+ * over it, so no second executor map exists.
  */
-import { GraphNodeExecutorRegistry, GraphExecutionEngine, type GraphNodeExecutor, IsolatedVmCodeSandboxEvaluator } from "../../graph/index.d.mts";
+import { GraphNodeCatalogue, GraphNodeExecutorRegistry, GraphExecutionEngine, type GraphNodeExecutor, IsolatedVmCodeSandboxEvaluator } from "../../graph/index.d.mts";
 /**
- * Builds a {@link GraphNodeExecutorRegistry} populated with the demo executors.
+ * Builds a {@link GraphNodeCatalogue} populated with the built-in
+ * manifest+executor registrations and the arithmetic demo executors, wrapped
+ * with its {@link GraphNodeExecutorRegistry} facade.
  *
- * Executors are registered by **node kind** (the same key the engine uses to
- * resolve executors at runtime). The for-angular demo nodes use the kind as
- * their tag, so the same key works for both dispatch-by-kind and
- * dispatch-by-tag.
+ * The built-in kinds whose executors need the engine instance (loops, Code,
+ * Switch) are only registered by {@link createDemoEngineConfig}'s
+ * `onEngineCreated` hook via {@link registerEngineBoundGraphNodes}.
  *
- * Registered kinds:
- * - `math.add`, `math.multiply` — arithmetic demo executors.
- * - `core.flow.*` — flow-control kinds (map, delay, return, merge, if,
- *   parallel, errorBoundary, humanApproval). The `core.flow.code`,
- *   `core.flow.log`, and `core.flow.switch` kinds are registered in
- *   `onEngineCreated` via their real executors because Code and Switch
- *   need the engine's `codeSandboxEvaluator`.
- * - `core.agent` — agent node.
- * - `core.loop.foreach`, `core.loop.while`, `core.loop.until` — loop executors
- *   (registered after the engine is created via `onEngineCreated`).
+ * @param extra - Additional executor registrations to merge into the catalogue.
+ * @returns The populated catalogue and its registry facade.
+ */
+export declare function createGraphNodeCatalogue(extra?: Record<string, GraphNodeExecutor>): {
+    catalogue: GraphNodeCatalogue;
+    registry: GraphNodeExecutorRegistry;
+};
+/**
+ * Builds a {@link GraphNodeExecutorRegistry} facade over a populated
+ * {@link GraphNodeCatalogue} (compatibility entry point).
  *
- * @param extra - Additional executors to merge into the registry.
- * @returns A populated registry ready for use with {@link GraphExecutionEngine}.
+ * @param extra - Additional executor registrations to merge into the catalogue.
+ * @returns The registry facade; the underlying catalogue is available as
+ * `registry.catalog`.
  */
 export declare function createGraphExecutorRegistry(extra?: Record<string, GraphNodeExecutor>): GraphNodeExecutorRegistry;
 /**
- * Builds a {@link GraphExecutionEngineConfig} populated with all demo executors
- * including loop executors that need a back-reference to the engine and the
- * Code node executor that needs the engine's `codeSandboxEvaluator`.
+ * Registers the engine-bound built-in kinds (loops, Code, Switch) on an
+ * existing catalogue, replacing their placeholder-free entries with the real
+ * engine-bound executors.
+ *
+ * @param catalogue - The catalogue receiving the registrations.
+ * @param engine - The engine instance the loop/Code/Switch executors bind to.
+ * @returns The catalogue with the engine-bound registrations applied.
+ */
+export declare function registerEngineBoundGraphNodes(catalogue: GraphNodeCatalogue, engine: GraphExecutionEngine): GraphNodeCatalogue;
+/**
+ * Builds a `GraphExecutionEngineConfig` populated with all built-in
+ * registrations including loop executors that need a back-reference to the
+ * engine and the Code node executor that needs the engine's
+ * `codeSandboxEvaluator`.
  *
  * The config wires an {@link IsolatedVmCodeSandboxEvaluator} (backed by
  * `isolated-vm`) so the Code Node runs in a truly isolated V8 sandbox.
@@ -43,6 +56,7 @@ export declare function createGraphExecutorRegistry(extra?: Record<string, Graph
  * @returns A config object ready for `new GraphExecutionEngine(config)`.
  */
 export declare function createDemoEngineConfig(): {
+    catalogue: GraphNodeCatalogue;
     registry: GraphNodeExecutorRegistry;
     defaultOptions: {
         failFast: boolean;

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

@@ -0,0 +1,70 @@
+import { DecafRequestContext } from "@decaf-ts/for-nest";
+import type { GraphCredentialReference, GraphJsonValue, GraphNodeMethodType } from "@decaf-ts/ui-decorators/graph";
+import { GraphNodeCatalogue } from "../../graph/index.d.cts";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+/** DI token for {@link GraphCatalogueControllerOptions}. */
+export declare const GRAPH_CATALOGUE_CONTROLLER_OPTIONS = "GRAPH_CATALOGUE_CONTROLLER_OPTIONS";
+/** Rate-limit configuration for an expensive catalogue operation: sliding window length and request cap. */
+export interface GraphCatalogueRateLimitOptions {
+    windowMs?: number;
+    maxRequests?: number;
+}
+/**
+ * Options for the catalogue HTTP API (DECAF-50 §4.13): authentication mode
+ * and per-operation rate limits for the expensive `resolve`/`methods`
+ * endpoints.
+ */
+export interface GraphCatalogueControllerOptions {
+    /** Whether an authenticated request context is required (default `"required"`). */
+    auth?: "required" | "optional";
+    /** Rate limit for manifest-resolution requests. */
+    resolveRateLimit?: GraphCatalogueRateLimitOptions;
+    /** Rate limit for node-method invocations. */
+    methodsRateLimit?: GraphCatalogueRateLimitOptions;
+}
+/** Request body for resolving a node's effective manifest against instance parameters. */
+export interface GraphNodeResolveRequest {
+    parameters?: Record<string, GraphJsonValue>;
+    metadata?: Record<string, GraphJsonValue>;
+}
+/** Request body for invoking a declared node method. */
+export interface GraphNodeMethodRequestDto {
+    parameters?: Record<string, GraphJsonValue>;
+    payload?: GraphJsonValue;
+    credentials?: GraphCredentialReference[];
+    methodType?: GraphNodeMethodType;
+}
+/**
+ * Catalogue HTTP API (DECAF-50 §4.13): serves registered node manifests as
+ * data (never constructors), resolves effective manifests for node
+ * instances, and invokes declared node methods. Enforces configured
+ * authentication and per-user rate limits on the expensive
+ * `resolve`/`methods` operations, and rejects non-JSON-safe request bodies.
+ */
+export declare class GraphNodeCatalogueController {
+    private readonly catalogue;
+    private readonly requestContext?;
+    private readonly options;
+    private readonly rateBuckets;
+    constructor(catalogue: GraphNodeCatalogue, requestContext?: DecafRequestContext | undefined, options?: GraphCatalogueControllerOptions);
+    private requireAuthenticatedContext;
+    /**
+     * Builds the rate-limit bucket key for an operation: the authenticated
+     * owner resolved via {@link graphWorkflowOwnerOf} (SAA-595 F6), falling
+     * back to the context `user.id`, then the request IP, then a shared
+     * `"anonymous"` bucket.
+     */
+    private rateLimitKey;
+    private enforceRateLimit;
+    listNodeTypes(ifNoneMatch: string | undefined, res: {
+        setHeader(name: string, value: string): void;
+        status(code: number): void;
+    }): Promise<unknown>;
+    getNodeType(kind: string): Promise<unknown>;
+    getNodeTypeIcon(kind: string): Promise<unknown>;
+    resolveNodeType(kind: string, body?: GraphNodeResolveRequest): Promise<GraphResolvedNodeManifest>;
+    invokeNodeMethod(kind: string, method: string, body?: GraphNodeMethodRequestDto): Promise<GraphJsonValue>;
+    private assertKnownKind;
+    private declaredMethod;
+    private authorizeCredentials;
+}

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

@@ -0,0 +1,70 @@
+import { DecafRequestContext } from "@decaf-ts/for-nest";
+import type { GraphCredentialReference, GraphJsonValue, GraphNodeMethodType } from "@decaf-ts/ui-decorators/graph";
+import { GraphNodeCatalogue } from "../../graph/index.d.mts";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+/** DI token for {@link GraphCatalogueControllerOptions}. */
+export declare const GRAPH_CATALOGUE_CONTROLLER_OPTIONS = "GRAPH_CATALOGUE_CONTROLLER_OPTIONS";
+/** Rate-limit configuration for an expensive catalogue operation: sliding window length and request cap. */
+export interface GraphCatalogueRateLimitOptions {
+    windowMs?: number;
+    maxRequests?: number;
+}
+/**
+ * Options for the catalogue HTTP API (DECAF-50 §4.13): authentication mode
+ * and per-operation rate limits for the expensive `resolve`/`methods`
+ * endpoints.
+ */
+export interface GraphCatalogueControllerOptions {
+    /** Whether an authenticated request context is required (default `"required"`). */
+    auth?: "required" | "optional";
+    /** Rate limit for manifest-resolution requests. */
+    resolveRateLimit?: GraphCatalogueRateLimitOptions;
+    /** Rate limit for node-method invocations. */
+    methodsRateLimit?: GraphCatalogueRateLimitOptions;
+}
+/** Request body for resolving a node's effective manifest against instance parameters. */
+export interface GraphNodeResolveRequest {
+    parameters?: Record<string, GraphJsonValue>;
+    metadata?: Record<string, GraphJsonValue>;
+}
+/** Request body for invoking a declared node method. */
+export interface GraphNodeMethodRequestDto {
+    parameters?: Record<string, GraphJsonValue>;
+    payload?: GraphJsonValue;
+    credentials?: GraphCredentialReference[];
+    methodType?: GraphNodeMethodType;
+}
+/**
+ * Catalogue HTTP API (DECAF-50 §4.13): serves registered node manifests as
+ * data (never constructors), resolves effective manifests for node
+ * instances, and invokes declared node methods. Enforces configured
+ * authentication and per-user rate limits on the expensive
+ * `resolve`/`methods` operations, and rejects non-JSON-safe request bodies.
+ */
+export declare class GraphNodeCatalogueController {
+    private readonly catalogue;
+    private readonly requestContext?;
+    private readonly options;
+    private readonly rateBuckets;
+    constructor(catalogue: GraphNodeCatalogue, requestContext?: DecafRequestContext | undefined, options?: GraphCatalogueControllerOptions);
+    private requireAuthenticatedContext;
+    /**
+     * Builds the rate-limit bucket key for an operation: the authenticated
+     * owner resolved via {@link graphWorkflowOwnerOf} (SAA-595 F6), falling
+     * back to the context `user.id`, then the request IP, then a shared
+     * `"anonymous"` bucket.
+     */
+    private rateLimitKey;
+    private enforceRateLimit;
+    listNodeTypes(ifNoneMatch: string | undefined, res: {
+        setHeader(name: string, value: string): void;
+        status(code: number): void;
+    }): Promise<unknown>;
+    getNodeType(kind: string): Promise<unknown>;
+    getNodeTypeIcon(kind: string): Promise<unknown>;
+    resolveNodeType(kind: string, body?: GraphNodeResolveRequest): Promise<GraphResolvedNodeManifest>;
+    invokeNodeMethod(kind: string, method: string, body?: GraphNodeMethodRequestDto): Promise<GraphJsonValue>;
+    private assertKnownKind;
+    private declaredMethod;
+    private authorizeCredentials;
+}