@decaf-ts/integrations 0.8.0 → 0.9.0

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

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

@@ -1,8 +1,20 @@
 import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
 import { GraphExecutionResultModel } from "./GraphExecutionResultModel.d.cts";
 import type { GraphExecutionResult } from "../../graph/index.d.cts";
+/**
+ * Model-backed persistence for {@link GraphExecutionResultModel} rows: the
+ * terminal snapshot the (deprecated) synchronous `POST /graph/execute`
+ * surface persists after a run completes. Access control lives at the
+ * controller/route layer, which gates reads through the run ownership check.
+ */
 export declare class GraphResultService extends ModelService<GraphExecutionResultModel> {
     constructor();
+    /**
+     * Persists a finished run's result, stamping the owning user resolved
+     * from the request context onto the `owner` column (SAA-595 F1); results
+     * saved without a resolved identity carry no owner.
+     */
     saveResult(result: GraphExecutionResult, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResultModel>;
+    /** Reads a result row by run id; returns `null` when no result was persisted (never throws). */
     findByRunId(runId: string, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResultModel | null>;
 }

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

@@ -1,8 +1,20 @@
 import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
 import { GraphExecutionResultModel } from "./GraphExecutionResultModel.d.mts";
 import type { GraphExecutionResult } from "../../graph/index.d.mts";
+/**
+ * Model-backed persistence for {@link GraphExecutionResultModel} rows: the
+ * terminal snapshot the (deprecated) synchronous `POST /graph/execute`
+ * surface persists after a run completes. Access control lives at the
+ * controller/route layer, which gates reads through the run ownership check.
+ */
 export declare class GraphResultService extends ModelService<GraphExecutionResultModel> {
     constructor();
+    /**
+     * Persists a finished run's result, stamping the owning user resolved
+     * from the request context onto the `owner` column (SAA-595 F1); results
+     * saved without a resolved identity carry no owner.
+     */
     saveResult(result: GraphExecutionResult, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResultModel>;
+    /** Reads a result row by run id; returns `null` when no result was persisted (never throws). */
     findByRunId(runId: string, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResultModel | null>;
 }

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

@@ -0,0 +1,87 @@
+/**
+ * @module integrations/nest/graph/GraphRunController
+ * @summary Asynchronous run lifecycle HTTP API (DECAF-50 §4.14–§4.15).
+ * @description Creates (`POST /graph/runs`), reads
+ * (`GET /graph/runs/:runId`), cancels (`DELETE /graph/runs/:runId`), and
+ * replays (`SSE /graph/runs/:runId/events`) graph runs on top of
+ * {@link GraphRunService}, enforcing authentication, run limits, and
+ * ownership; engine errors surface as `500` with their message while Nest
+ * {@link HttpException}s pass through unchanged.
+ */
+import { MessageEvent } from "@nestjs/common";
+import { Observable } from "rxjs";
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import { DecafRequestContext } from "@decaf-ts/for-nest";
+import type { GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionValues } from "../../graph/index.d.cts";
+import { GraphRunService } from "../../graph/index.d.cts";
+/** DI token for {@link GraphRunControllerOptions}. */
+export declare const GRAPH_RUN_OPTIONS = "GRAPH_RUN_OPTIONS";
+/** Options for the run lifecycle HTTP API (DECAF-50 §4.14–§4.15): authentication mode and run limits. */
+export interface GraphRunControllerOptions {
+    /**
+     * Whether an authenticated request context is required (default
+     * `"required"`, SAA-595 secure-defaults alignment). `"optional"` admits
+     * anonymous requests for standalone module runs (DECAF-48 §4.15) — pair it
+     * with an explicit `allowAnonymousAccess` decision.
+     */
+    auth?: "required" | "optional";
+    /**
+     * Explicit DECAF-48 §4.15 standalone tolerance: when `true`, anonymous
+     * callers are tolerated on owned runs. Defaults to `false` — ownership
+     * checks fail closed for absent identities (SAA-595 F3).
+     */
+    allowAnonymousAccess?: boolean;
+    /** Run limits forwarded to {@link GraphRunService}. */
+    limits?: GraphRunLimits;
+}
+/** Response of `POST /graph/runs`: the queued run's identity and its event/result URLs. */
+export interface GraphRunCreatedResponse {
+    runId: string;
+    workflowId: string;
+    status: "queued";
+    eventsUrl: string;
+    resultUrl: string;
+}
+/** Request body for creating a run: an inline workflow document or a saved `workflowId`, plus optional inputs. */
+export interface GraphRunRequestBody {
+    workflow?: GraphWorkflowDocument;
+    workflowId?: string;
+    inputs?: GraphExecutionValues;
+}
+/**
+ * Asynchronous run lifecycle HTTP API (DECAF-50 §4.14–§4.15):
+ * `POST /graph/runs` creates and schedules a run (202 Accepted), run
+ * read/cancel endpoints expose lifecycle state, and
+ * `GET /graph/runs/:runId/events` streams the run's sequenced event
+ * envelopes over SSE until a terminal event closes the stream. Every
+ * operation is ownership-checked against the requesting user.
+ */
+export declare class GraphRunController {
+    private readonly runService;
+    private readonly requestContext?;
+    private readonly options;
+    constructor(runService: GraphRunService, requestContext?: DecafRequestContext | undefined, options?: GraphRunControllerOptions);
+    /**
+     * Enforces the configured authentication mode: `auth` defaults to
+     * `"required"` (SAA-595 secure-defaults alignment) and rejects
+     * unauthenticated calls with `401`; `"optional"` admits anonymous
+     * requests for standalone module runs (DECAF-48 §4.15).
+     */
+    private requireAuthenticatedContext;
+    private ownerUserOf;
+    /** Concurrency-bucket key for the per-caller run cap: the owner, else the request IP, else a shared anonymous bucket. */
+    private concurrencyKeyOf;
+    /**
+     * Creates and schedules a run (DECAF-50 §4.14): accepts an inline workflow
+     * document or a saved `workflowId` plus optional inputs, answers
+     * `202 Accepted` with the queued run's identity and its event/result URLs.
+     * The per-caller concurrency cap buckets by owner user, then request IP,
+     * then a shared anonymous bucket (SAA-595 F4).
+     */
+    createRun(body: GraphRunRequestBody): Promise<GraphRunCreatedResponse>;
+    getRun(runId: string): Promise<Record<string, unknown>>;
+    cancelRun(runId: string): Promise<Record<string, unknown>>;
+    events(runId: string, afterSequence?: string): Promise<Observable<MessageEvent>>;
+    private parseAfterSequence;
+}