@decaf-ts/integrations 0.8.0 → 0.9.0

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

@@ -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.mts";
+import { GraphRunService } from "../../graph/index.d.mts";
+/** 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;
+}

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

@@ -0,0 +1,22 @@
+import { BaseModel } from "@decaf-ts/core";
+/**
+ * Persistent run record for the graph run lifecycle (DECAF-50 §4.14): one
+ * row per {@link GraphRun}, storing lifecycle status, the executed
+ * document's fingerprint, inputs, result, and error payloads. Written and
+ * read through {@link GraphRunModelService}, which adapts it to the
+ * engine-side {@link GraphRun} shape.
+ */
+export declare class GraphRunModel extends BaseModel {
+    runId: string;
+    workflowId: string;
+    owner?: string;
+    status: string;
+    documentFingerprint?: string;
+    inputs?: Record<string, unknown>;
+    result?: Record<string, unknown>;
+    error?: Record<string, unknown>;
+    createdAt: Date;
+    startedAt?: Date;
+    finishedAt?: Date;
+    constructor(arg?: Partial<GraphRunModel>);
+}

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

@@ -0,0 +1,22 @@
+import { BaseModel } from "@decaf-ts/core";
+/**
+ * Persistent run record for the graph run lifecycle (DECAF-50 §4.14): one
+ * row per {@link GraphRun}, storing lifecycle status, the executed
+ * document's fingerprint, inputs, result, and error payloads. Written and
+ * read through {@link GraphRunModelService}, which adapts it to the
+ * engine-side {@link GraphRun} shape.
+ */
+export declare class GraphRunModel extends BaseModel {
+    runId: string;
+    workflowId: string;
+    owner?: string;
+    status: string;
+    documentFingerprint?: string;
+    inputs?: Record<string, unknown>;
+    result?: Record<string, unknown>;
+    error?: Record<string, unknown>;
+    createdAt: Date;
+    startedAt?: Date;
+    finishedAt?: Date;
+    constructor(arg?: Partial<GraphRunModel>);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/nest/graph/GraphRunModelService
+ * @summary Persistent run store on the Decaf model layer.
+ * @description Persists {@link GraphRun} rows as {@link GraphRunModel} via
+ * the Decaf {@link ModelService}, implementing the engine-side
+ * {@link GraphRunStore} and converting between the engine run shape and the
+ * JSON-safe persisted columns.
+ */
+import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
+import type { GraphRun, GraphRunStore } from "../../graph/engine/runs/types.d.cts";
+import { GraphRunModel } from "./GraphRunModel.d.cts";
+/**
+ * Model-backed {@link GraphRunStore}: persists runs as {@link GraphRunModel}
+ * rows via the Decaf ModelService, converting between the engine-side
+ * {@link GraphRun} shape and the JSON-safe persisted columns.
+ */
+export declare class GraphRunModelService extends ModelService<GraphRunModel> implements GraphRunStore {
+    constructor();
+    saveRun(run: GraphRun, ...args: MaybeContextualArg<Context>): Promise<void>;
+    readRun(runId: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun | null>;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/nest/graph/GraphRunModelService
+ * @summary Persistent run store on the Decaf model layer.
+ * @description Persists {@link GraphRun} rows as {@link GraphRunModel} via
+ * the Decaf {@link ModelService}, implementing the engine-side
+ * {@link GraphRunStore} and converting between the engine run shape and the
+ * JSON-safe persisted columns.
+ */
+import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
+import type { GraphRun, GraphRunStore } from "../../graph/engine/runs/types.d.mts";
+import { GraphRunModel } from "./GraphRunModel.d.mts";
+/**
+ * Model-backed {@link GraphRunStore}: persists runs as {@link GraphRunModel}
+ * rows via the Decaf ModelService, converting between the engine-side
+ * {@link GraphRun} shape and the JSON-safe persisted columns.
+ */
+export declare class GraphRunModelService extends ModelService<GraphRunModel> implements GraphRunStore {
+    constructor();
+    saveRun(run: GraphRun, ...args: MaybeContextualArg<Context>): Promise<void>;
+    readRun(runId: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun | null>;
+}

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

@@ -0,0 +1,28 @@
+import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeCatalogue } from "../../graph/index.d.cts";
+import type { GraphWorkflowValidationResult } from "../../graph/index.d.cts";
+import { type GraphWorkflowDocumentLimits } from "./GraphWorkflowDocumentLimits.d.cts";
+/**
+ * Field keys that must never appear on a submitted workflow document or any
+ * of its structural records (DECAF-50 §4.16): client input resembling node,
+ * definition, executor, authoritative ports, or frontend component
+ * definitions is rejected at the boundary.
+ */
+export declare const GRAPH_WORKFLOW_FORBIDDEN_FIELD_KEYS: readonly string[];
+/** Options for boundary validation: document resource limits and the trusted catalogue to resolve kinds against. */
+export interface GraphWorkflowBoundaryValidationOptions {
+    limits?: GraphWorkflowDocumentLimits;
+    catalogue?: GraphNodeCatalogue;
+}
+/**
+ * Validates a submitted canonical workflow document at the persistence
+ * boundary (DECAF-50 §4.10/§4.16): document shape, JSON safety, forbidden
+ * definition/executor/component fields, duplicate ids, backend-enforced
+ * resource limits, structural validity (via the shared document contract
+ * assertions) and catalogue kind existence. Issues accumulate as structured
+ * {@link GraphValidationIssue}s instead of failing abruptly.
+ *
+ * Full nine-stage document/catalogue validation (DECAF-50 §4.8) is owned by
+ * the engine validation phase; this boundary pass is the persistence gate.
+ */
+export declare function validateGraphWorkflowDocumentAtBoundary(document: GraphWorkflowDocument, options?: GraphWorkflowBoundaryValidationOptions): GraphWorkflowValidationResult;

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

@@ -0,0 +1,28 @@
+import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeCatalogue } from "../../graph/index.d.mts";
+import type { GraphWorkflowValidationResult } from "../../graph/index.d.mts";
+import { type GraphWorkflowDocumentLimits } from "./GraphWorkflowDocumentLimits.d.mts";
+/**
+ * Field keys that must never appear on a submitted workflow document or any
+ * of its structural records (DECAF-50 §4.16): client input resembling node,
+ * definition, executor, authoritative ports, or frontend component
+ * definitions is rejected at the boundary.
+ */
+export declare const GRAPH_WORKFLOW_FORBIDDEN_FIELD_KEYS: readonly string[];
+/** Options for boundary validation: document resource limits and the trusted catalogue to resolve kinds against. */
+export interface GraphWorkflowBoundaryValidationOptions {
+    limits?: GraphWorkflowDocumentLimits;
+    catalogue?: GraphNodeCatalogue;
+}
+/**
+ * Validates a submitted canonical workflow document at the persistence
+ * boundary (DECAF-50 §4.10/§4.16): document shape, JSON safety, forbidden
+ * definition/executor/component fields, duplicate ids, backend-enforced
+ * resource limits, structural validity (via the shared document contract
+ * assertions) and catalogue kind existence. Issues accumulate as structured
+ * {@link GraphValidationIssue}s instead of failing abruptly.
+ *
+ * Full nine-stage document/catalogue validation (DECAF-50 §4.8) is owned by
+ * the engine validation phase; this boundary pass is the persistence gate.
+ */
+export declare function validateGraphWorkflowDocumentAtBoundary(document: GraphWorkflowDocument, options?: GraphWorkflowBoundaryValidationOptions): GraphWorkflowValidationResult;

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

@@ -0,0 +1,62 @@
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import { DecafRequestContext } from "@decaf-ts/for-nest";
+import type { GraphWorkflowValidationResult } from "../../graph/index.d.cts";
+import { GraphWorkflowService } from "./GraphWorkflowService.d.cts";
+import type { GraphWorkflowDocumentLimits } from "./GraphWorkflowDocumentLimits.d.cts";
+/** Options for the workflow persistence HTTP API (DECAF-50 §4.10): authentication mode and document resource limits. */
+export interface GraphWorkflowControllerOptions {
+    /**
+     * `"required"` rejects unauthenticated calls with `401` (default,
+     * SAA-595 secure-defaults alignment); `"optional"` tolerates
+     * anonymous/system callers for standalone module runs (DECAF-48 §4.15)
+     * while still enforcing ownership between distinct users — 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 workflows. Defaults to `false` —
+     * ownership checks fail closed for absent identities (SAA-595 F3).
+     */
+    allowAnonymousAccess?: boolean;
+    /** Backend-enforced resource limits (DECAF-50 §4.16). */
+    limits?: GraphWorkflowDocumentLimits;
+}
+/** Response of a successful workflow save: persisted identity and timestamp. */
+export interface GraphWorkflowSaveResponse {
+    workflowId: string;
+    name?: string;
+    savedAt: string;
+}
+/**
+ * Canonical workflow document persistence endpoints (DECAF-50 §4.10):
+ *
+ * - `PUT   /graph/workflows/{workflowId}` — validate and persist a canonical
+ *   document (or a `{ document, editor, metadata }` snapshot wrapper, whose
+ *   editor state is preserved verbatim for lossless round trips).
+ * - `GET  /graph/workflows/{workflowId}` — load the canonical document;
+ *   legacy persisted snapshots are converted losslessly on the read path.
+ * - `POST /graph/workflows/validate` — run boundary validation and return
+ *   structured issues (`code`, `path`, `nodeId`, `edgeId`, `message`,
+ *   safe `details`).
+ *
+ * @class GraphWorkflowController
+ */
+export declare class GraphWorkflowController {
+    private readonly workflowService;
+    private readonly requestContext?;
+    private readonly options;
+    constructor(workflowService: GraphWorkflowService, requestContext?: DecafRequestContext | undefined, options?: GraphWorkflowControllerOptions);
+    /**
+     * 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;
+    saveWorkflow(workflowId: string, body: unknown): Promise<GraphWorkflowSaveResponse>;
+    getWorkflow(workflowId: string): Promise<GraphWorkflowDocument>;
+    validateWorkflow(body: unknown): Promise<GraphWorkflowValidationResult>;
+    private isCanonicalWrapper;
+    private documentOf;
+}

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

@@ -0,0 +1,62 @@
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import { DecafRequestContext } from "@decaf-ts/for-nest";
+import type { GraphWorkflowValidationResult } from "../../graph/index.d.mts";
+import { GraphWorkflowService } from "./GraphWorkflowService.d.mts";
+import type { GraphWorkflowDocumentLimits } from "./GraphWorkflowDocumentLimits.d.mts";
+/** Options for the workflow persistence HTTP API (DECAF-50 §4.10): authentication mode and document resource limits. */
+export interface GraphWorkflowControllerOptions {
+    /**
+     * `"required"` rejects unauthenticated calls with `401` (default,
+     * SAA-595 secure-defaults alignment); `"optional"` tolerates
+     * anonymous/system callers for standalone module runs (DECAF-48 §4.15)
+     * while still enforcing ownership between distinct users — 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 workflows. Defaults to `false` —
+     * ownership checks fail closed for absent identities (SAA-595 F3).
+     */
+    allowAnonymousAccess?: boolean;
+    /** Backend-enforced resource limits (DECAF-50 §4.16). */
+    limits?: GraphWorkflowDocumentLimits;
+}
+/** Response of a successful workflow save: persisted identity and timestamp. */
+export interface GraphWorkflowSaveResponse {
+    workflowId: string;
+    name?: string;
+    savedAt: string;
+}
+/**
+ * Canonical workflow document persistence endpoints (DECAF-50 §4.10):
+ *
+ * - `PUT   /graph/workflows/{workflowId}` — validate and persist a canonical
+ *   document (or a `{ document, editor, metadata }` snapshot wrapper, whose
+ *   editor state is preserved verbatim for lossless round trips).
+ * - `GET  /graph/workflows/{workflowId}` — load the canonical document;
+ *   legacy persisted snapshots are converted losslessly on the read path.
+ * - `POST /graph/workflows/validate` — run boundary validation and return
+ *   structured issues (`code`, `path`, `nodeId`, `edgeId`, `message`,
+ *   safe `details`).
+ *
+ * @class GraphWorkflowController
+ */
+export declare class GraphWorkflowController {
+    private readonly workflowService;
+    private readonly requestContext?;
+    private readonly options;
+    constructor(workflowService: GraphWorkflowService, requestContext?: DecafRequestContext | undefined, options?: GraphWorkflowControllerOptions);
+    /**
+     * 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;
+    saveWorkflow(workflowId: string, body: unknown): Promise<GraphWorkflowSaveResponse>;
+    getWorkflow(workflowId: string): Promise<GraphWorkflowDocument>;
+    validateWorkflow(body: unknown): Promise<GraphWorkflowValidationResult>;
+    private isCanonicalWrapper;
+    private documentOf;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Backend-enforced, configurable resource limits for canonical workflow
+ * documents submitted at the persistence boundary (DECAF-50 §4.16).
+ *
+ * Defaults (technical governance delegates the numbers to implementation):
+ * - `maxDocumentBytes: 2_000_000` — a full canonical document serializes to
+ *   well under 2 MB for realistic graphs; the cap blocks oversized payloads
+ *   before deep validation runs.
+ * - `maxNestingDepth: 10` — nested loop bodies are themselves documents; ten
+ *   levels of nesting is far beyond any sane workflow while keeping recursive
+ *   validation cheap.
+ * - `maxNodes: 500` — per document level (nested loop bodies are limited
+ *   independently), generous for editor-built graphs.
+ * - `maxEdges: 1_000` — roughly twice the node cap, matching typical
+ *   fan-out without enabling quadratic edge bombs.
+ *
+ * Every limit is enforced backend-side before persistence and can be
+ * overridden through `GraphExecutionModuleOptions.workflows.limits`.
+ *
+ * @module integrations/nest/graph/workflow-limits
+ */
+export interface GraphWorkflowDocumentLimits {
+    /** 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 document resource limits (§4.16): payload size, nesting depth, node and edge counts. */
+export declare const DEFAULT_GRAPH_WORKFLOW_DOCUMENT_LIMITS: Required<GraphWorkflowDocumentLimits>;

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

@@ -0,0 +1,33 @@
+/**
+ * Backend-enforced, configurable resource limits for canonical workflow
+ * documents submitted at the persistence boundary (DECAF-50 §4.16).
+ *
+ * Defaults (technical governance delegates the numbers to implementation):
+ * - `maxDocumentBytes: 2_000_000` — a full canonical document serializes to
+ *   well under 2 MB for realistic graphs; the cap blocks oversized payloads
+ *   before deep validation runs.
+ * - `maxNestingDepth: 10` — nested loop bodies are themselves documents; ten
+ *   levels of nesting is far beyond any sane workflow while keeping recursive
+ *   validation cheap.
+ * - `maxNodes: 500` — per document level (nested loop bodies are limited
+ *   independently), generous for editor-built graphs.
+ * - `maxEdges: 1_000` — roughly twice the node cap, matching typical
+ *   fan-out without enabling quadratic edge bombs.
+ *
+ * Every limit is enforced backend-side before persistence and can be
+ * overridden through `GraphExecutionModuleOptions.workflows.limits`.
+ *
+ * @module integrations/nest/graph/workflow-limits
+ */
+export interface GraphWorkflowDocumentLimits {
+    /** 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 document resource limits (§4.16): payload size, nesting depth, node and edge counts. */
+export declare const DEFAULT_GRAPH_WORKFLOW_DOCUMENT_LIMITS: Required<GraphWorkflowDocumentLimits>;

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

@@ -0,0 +1,13 @@
+import { ValidationError } from "@decaf-ts/db-decorators";
+import type { GraphValidationIssue } from "../../graph/index.d.cts";
+/**
+ * Raised when a submitted workflow document fails boundary validation and
+ * must not be persisted (DECAF-50 §4.10). Carries the structured issues so
+ * HTTP transports can surface them without re-running validation.
+ *
+ * @class GraphWorkflowDocumentRejectedError
+ */
+export declare class GraphWorkflowDocumentRejectedError extends ValidationError {
+    readonly issues: GraphValidationIssue[];
+    constructor(issues: GraphValidationIssue[]);
+}

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

@@ -0,0 +1,13 @@
+import { ValidationError } from "@decaf-ts/db-decorators";
+import type { GraphValidationIssue } from "../../graph/index.d.mts";
+/**
+ * Raised when a submitted workflow document fails boundary validation and
+ * must not be persisted (DECAF-50 §4.10). Carries the structured issues so
+ * HTTP transports can surface them without re-running validation.
+ *
+ * @class GraphWorkflowDocumentRejectedError
+ */
+export declare class GraphWorkflowDocumentRejectedError extends ValidationError {
+    readonly issues: GraphValidationIssue[];
+    constructor(issues: GraphValidationIssue[]);
+}

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

@@ -1,6 +1,24 @@
 import { BaseModel } from "@decaf-ts/core";
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Canonical workflow persistence model (DECAF-50 §4.10).
+ *
+ * `document` is the executable source of truth. `snapshot` is retained
+ * temporarily (DECAF-50 §4.18 transition) so legacy persisted snapshots keep
+ * loading through lossless read-path conversion; it must never become the
+ * executable source of truth again and is removed at cutover (P7).
+ *
+ * `owner` implements the DECAF-48 `{ workflowId, ownerUser }` ownership tuple:
+ * the authenticated user that created the workflow, or `undefined` for
+ * system/standalone saves (tolerated per DECAF-48 §4.15).
+ *
+ * @class GraphWorkflowModel
+ */
 export declare class GraphWorkflowModel extends BaseModel {
     workflowId: string;
-    snapshot: Record<string, unknown>;
+    name?: string;
+    document?: GraphWorkflowDocument;
+    owner?: string;
+    snapshot?: Record<string, unknown>;
     constructor(arg?: Partial<GraphWorkflowModel>);
 }

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

@@ -1,6 +1,24 @@
 import { BaseModel } from "@decaf-ts/core";
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Canonical workflow persistence model (DECAF-50 §4.10).
+ *
+ * `document` is the executable source of truth. `snapshot` is retained
+ * temporarily (DECAF-50 §4.18 transition) so legacy persisted snapshots keep
+ * loading through lossless read-path conversion; it must never become the
+ * executable source of truth again and is removed at cutover (P7).
+ *
+ * `owner` implements the DECAF-48 `{ workflowId, ownerUser }` ownership tuple:
+ * the authenticated user that created the workflow, or `undefined` for
+ * system/standalone saves (tolerated per DECAF-48 §4.15).
+ *
+ * @class GraphWorkflowModel
+ */
 export declare class GraphWorkflowModel extends BaseModel {
     workflowId: string;
-    snapshot: Record<string, unknown>;
+    name?: string;
+    document?: GraphWorkflowDocument;
+    owner?: string;
+    snapshot?: Record<string, unknown>;
     constructor(arg?: Partial<GraphWorkflowModel>);
 }

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

@@ -1,7 +1,54 @@
 import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
+import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import { GraphNodeCatalogue } from "../../graph/index.d.cts";
+import type { GraphWorkflowValidationResult } from "../../graph/index.d.cts";
 import { GraphWorkflowModel } from "./GraphWorkflowModel.d.cts";
+import { type GraphWorkflowDocumentLimits } from "./GraphWorkflowDocumentLimits.d.cts";
+/** DI token for {@link GraphWorkflowServiceOptions}. */
+export declare const GRAPH_WORKFLOW_OPTIONS = "GRAPH_WORKFLOW_OPTIONS";
+/** Options for {@link GraphWorkflowService}: backend-enforced document resource limits. */
+export interface GraphWorkflowServiceOptions {
+    /** Backend-enforced resource limits for submitted documents (§4.16). */
+    limits?: GraphWorkflowDocumentLimits;
+    /**
+     * Explicit DECAF-48 §4.15 standalone tolerance: when `true`, anonymous
+     * callers are tolerated on owned workflows. Defaults to `false` —
+     * ownership checks fail closed for absent identities (SAA-595 F3).
+     */
+    allowAnonymousAccess?: boolean;
+}
+/**
+ * Resolves the authenticated user identifier from a request context
+ * (DECAF-36 Req-B5: the auth handler accumulates `{ user, roles, organization }`
+ * onto the context). Returns `undefined` for anonymous/system callers, which
+ * the explicit DECAF-48 §4.15 standalone tolerance
+ * (`allowAnonymousAccess`) may admit on owned resources (SAA-595 F3).
+ */
+export declare function graphWorkflowOwnerOf(ctx: Context | undefined): string | undefined;
 export declare class GraphWorkflowService extends ModelService<GraphWorkflowModel> {
-    constructor();
+    protected limits: Required<GraphWorkflowDocumentLimits>;
+    protected catalogue: GraphNodeCatalogue | undefined;
+    private allowAnonymousAccess;
+    constructor(options?: GraphWorkflowServiceOptions, catalogue?: GraphNodeCatalogue);
+    /**
+     * Applies options to this service instance and returns it.
+     *
+     * `@service` classes resolve through the injectable-decorators singleton
+     * registry, which does not forward constructor arguments reliably (Nest
+     * provider options included); the module wiring uses this method to apply
+     * {@link GRAPH_WORKFLOW_OPTIONS} deterministically (SAA-595 F3).
+     */
+    configure(options: GraphWorkflowServiceOptions): this;
+    saveDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel>;
+    getDocument(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
+    validateDocument(document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowValidationResult>;
     saveSnapshot(workflowId: string, snapshot: Record<string, unknown>, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel>;
     loadSnapshot(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel | null>;
+    /**
+     * Guards a persisted workflow record with the centralized
+     * {@link assertGraphResourceOwnership} check, honouring this service's
+     * configured `allowAnonymousAccess` tolerance (SAA-595 F3).
+     */
+    private assertOwnership;
+    private applyCanonicalWrapper;
 }

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

@@ -1,7 +1,54 @@
 import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
+import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import { GraphNodeCatalogue } from "../../graph/index.d.mts";
+import type { GraphWorkflowValidationResult } from "../../graph/index.d.mts";
 import { GraphWorkflowModel } from "./GraphWorkflowModel.d.mts";
+import { type GraphWorkflowDocumentLimits } from "./GraphWorkflowDocumentLimits.d.mts";
+/** DI token for {@link GraphWorkflowServiceOptions}. */
+export declare const GRAPH_WORKFLOW_OPTIONS = "GRAPH_WORKFLOW_OPTIONS";
+/** Options for {@link GraphWorkflowService}: backend-enforced document resource limits. */
+export interface GraphWorkflowServiceOptions {
+    /** Backend-enforced resource limits for submitted documents (§4.16). */
+    limits?: GraphWorkflowDocumentLimits;
+    /**
+     * Explicit DECAF-48 §4.15 standalone tolerance: when `true`, anonymous
+     * callers are tolerated on owned workflows. Defaults to `false` —
+     * ownership checks fail closed for absent identities (SAA-595 F3).
+     */
+    allowAnonymousAccess?: boolean;
+}
+/**
+ * Resolves the authenticated user identifier from a request context
+ * (DECAF-36 Req-B5: the auth handler accumulates `{ user, roles, organization }`
+ * onto the context). Returns `undefined` for anonymous/system callers, which
+ * the explicit DECAF-48 §4.15 standalone tolerance
+ * (`allowAnonymousAccess`) may admit on owned resources (SAA-595 F3).
+ */
+export declare function graphWorkflowOwnerOf(ctx: Context | undefined): string | undefined;
 export declare class GraphWorkflowService extends ModelService<GraphWorkflowModel> {
-    constructor();
+    protected limits: Required<GraphWorkflowDocumentLimits>;
+    protected catalogue: GraphNodeCatalogue | undefined;
+    private allowAnonymousAccess;
+    constructor(options?: GraphWorkflowServiceOptions, catalogue?: GraphNodeCatalogue);
+    /**
+     * Applies options to this service instance and returns it.
+     *
+     * `@service` classes resolve through the injectable-decorators singleton
+     * registry, which does not forward constructor arguments reliably (Nest
+     * provider options included); the module wiring uses this method to apply
+     * {@link GRAPH_WORKFLOW_OPTIONS} deterministically (SAA-595 F3).
+     */
+    configure(options: GraphWorkflowServiceOptions): this;
+    saveDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel>;
+    getDocument(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
+    validateDocument(document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowValidationResult>;
     saveSnapshot(workflowId: string, snapshot: Record<string, unknown>, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel>;
     loadSnapshot(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel | null>;
+    /**
+     * Guards a persisted workflow record with the centralized
+     * {@link assertGraphResourceOwnership} check, honouring this service's
+     * configured `allowAnonymousAccess` tolerance (SAA-595 F3).
+     */
+    private assertOwnership;
+    private applyCanonicalWrapper;
 }

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

@@ -2,6 +2,14 @@ export * from "./GraphExecutionResultModel.d.cts";
 export * from "./GraphResultService.d.cts";
 export * from "./GraphWorkflowModel.d.cts";
 export * from "./GraphWorkflowService.d.cts";
+export * from "./GraphWorkflowDocumentLimits.d.cts";
+export * from "./GraphWorkflowBoundaryValidation.d.cts";
+export * from "./GraphWorkflowErrors.d.cts";
+export * from "./GraphWorkflowController.d.cts";
+export * from "./GraphRunModel.d.cts";
+export * from "./GraphRunModelService.d.cts";
+export * from "./GraphRunController.d.cts";
 export * from "./GraphExecutorRegistryFactory.d.cts";
 export * from "./GraphExecutionController.d.cts";
+export * from "./GraphNodeCatalogueController.d.cts";
 export * from "./GraphExecutionModule.d.cts";