@decaf-ts/integrations 0.7.0 → 0.9.0

package/lib/types/graph/engine/runs/types.d.mts

@@ -0,0 +1,83 @@
+/**
+ * @module integrations/graph/engine/runs/types
+ * @summary Graph run lifecycle contracts (engine side).
+ * @description Engine-scoped run contracts for the lifecycle subsystem
+ * (DECAF-50 §4.14–§4.16). The frontend-safe run wire contract —
+ * `GraphRunStatus`, `GraphRunEventEnvelope`, `GraphRunEventEnvelopeInput`
+ * and the run limits/terminal predicates — lives in
+ * `@decaf-ts/ui-decorators/graph` (imported from there).
+ *
+ * Engine-only contracts: the full {@link GraphRun} shape (whose `result?`
+ * carries engine dates) and the run store/event-store/create-request/
+ * document-resolver ports.
+ */
+import type { Context, MaybeContextualArg } from "@decaf-ts/core";
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.mts";
+import type { GraphExecutionErrorPayload } from "@decaf-ts/ui-decorators/graph";
+import type { GraphRunEventEnvelope, GraphRunStatus } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Engine-side run record (DECAF-50 §4.14): lifecycle status, timestamps, and
+ * — once terminal — the execution result, error payload, and the fingerprint
+ * of the document the run executed.
+ */
+export interface GraphRun {
+    /** Unique run id. */
+    runId: string;
+    /** Workflow (document) id the run executes. */
+    workflowId: string;
+    /** Owning user; `null` for anonymous callers. */
+    ownerUser: string | null;
+    /** Current lifecycle status. */
+    status: GraphRunStatus;
+    /** ISO timestamp when the run was created. */
+    createdAt: string;
+    /** ISO timestamp when execution started, once it has. */
+    startedAt?: string;
+    /** ISO timestamp when the run reached a terminal state. */
+    finishedAt?: string;
+    /** Execution result, present on successful completion. */
+    result?: GraphExecutionResult;
+    /** Structured error payload, present on failure. */
+    error?: GraphExecutionErrorPayload;
+    /** Fingerprint of the executed document (stable SHA-256). */
+    documentFingerprint?: string;
+}
+/**
+ * Persistence port for run records: durable implementations save/read runs
+ * with an optional leading Decaf {@link Context}.
+ */
+export interface GraphRunEventStore {
+    /** Appends a sequenced event envelope and notifies live subscribers. */
+    append(event: GraphRunEventEnvelope): Promise<void>;
+    /** Returns the run's envelopes with `sequence` greater than the given one (SSE replay). */
+    listAfter(runId: string, sequence: number): Promise<GraphRunEventEnvelope[]>;
+    /**
+     * Subscribes a live listener to the run's stream; returns an unsubscribe function.
+     */
+    subscribe(runId: string, listener: (event: GraphRunEventEnvelope) => void): () => void;
+    /**
+     * Releases all retained event state for a finished run (after the replay
+     * window). Optional: in-memory stores implement it; durable stores may
+     * no-op or keep events for audit.
+     */
+    release?(runId: string): void;
+}
+/** Persistence port for run records: save and read {@link GraphRun}s by id, with optional leading {@link Context}. */
+export interface GraphRunStore {
+    saveRun(run: GraphRun, ...args: MaybeContextualArg<Context>): Promise<void>;
+    readRun(runId: string, ...args: MaybeContextualArg<Context>): Promise<GraphRun | null>;
+}
+/** A run-creation request: an inline workflow document, or a saved `workflowId` plus optional input values. */
+export interface GraphRunCreateRequest {
+    /** Inline workflow document to execute. */
+    workflow?: GraphWorkflowDocument;
+    /** Saved workflow id to execute (requires a document resolver). */
+    workflowId?: string;
+    /** Input values bound to the workflow's input ports. */
+    inputs?: GraphExecutionValues;
+}
+/** Resolves a saved workflow document by id for by-`workflowId` run requests. */
+export interface GraphRunDocumentResolver {
+    resolve(workflowId: string, ownerUser: string | null, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
+}

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

@@ -5,13 +5,13 @@
  * types (`ExprValue`, `ConditionExpression`, `CodeCondition`,
  * `SwitchCaseCondition`, `SwitchCase`, `SwitchNodeMetadata`,
  * `NodeMetadataChange`, `GraphExecutionEvent`, `GraphExecutionErrorPayload`)
- * live in `../shared/types`; engine modules import shared symbols from there
- * and engine-private symbols from here.
+ * live in `@decaf-ts/ui-decorators/graph`; engine modules import shared
+ * symbols from there and engine-private symbols from here.
  */
-import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionStatus } from "../shared/constants.d.cts";
-import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "../shared/types.d.cts";
-export type { GraphExecutionErrorPayload, GraphExecutionEvent, } from "../shared/types.d.cts";
+import type { GraphCredentialReference, GraphJsonValue, GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionStatus } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Unique identifier for a single graph execution run.
  */
@@ -49,6 +49,7 @@ export interface GraphExecutionOptions {
     usePinnedValues?: boolean;
     writeThroughCache?: boolean;
     metadata?: Record<string, unknown>;
+    abortSignal?: AbortSignal;
 }
 /**
  * Result of executing a single node.
@@ -67,13 +68,16 @@ export interface GraphNodeExecutionResult {
 }
 /**
  * Result of executing an entire workflow.
+ *
+ * The executed source of truth is the canonical {@link GraphWorkflowDocument}
+ * (never a decorated workflow definition).
  */
 export interface GraphExecutionResult {
     runId: GraphRunId;
     parentRunId?: GraphRunId;
     workflowId: GraphWorkflowId;
     status: GraphExecutionStatus;
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     inputs: GraphExecutionValues;
     outputs: GraphExecutionValues;
     nodeResults: Record<GraphNodeId, GraphNodeExecutionResult>;
@@ -82,14 +86,34 @@ export interface GraphExecutionResult {
     finishedAt?: Date;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Credential references resolved for a node execution (DECAF-50 §4.9/§4.16).
+ * Documents carry references only; secret material never enters the request.
+ */
+export type GraphResolvedCredentials = Record<string, GraphCredentialReference>;
+/**
+ * Request passed to request-based node executors (DECAF-50 §4.9).
+ * Configuration (`parameters`, `credentials`, `metadata`) and input data
+ * (`inputs`) are separated.
+ */
+export interface GraphNodeExecutionRequest {
+    nodeId: string;
+    kind: string;
+    inputs: GraphExecutionValues;
+    parameters: Record<string, GraphJsonValue>;
+    credentials: GraphResolvedCredentials;
+    metadata?: Record<string, GraphJsonValue>;
+}
 /**
  * Options used to construct a {@link GraphExecutionContext}.
  */
 export interface GraphExecutionContextOptions {
     runId: GraphRunId;
     parentRunId?: GraphRunId;
-    workflow: GraphWorkflowDefinition;
-    node: GraphNodeDefinition;
+    workflowId: GraphWorkflowId;
+    document: GraphWorkflowDocument;
+    node: GraphNodeInstance;
+    manifest: GraphResolvedNodeManifest;
     path: string[];
     metadata?: Record<string, unknown>;
 }
@@ -97,7 +121,8 @@ export interface GraphExecutionContextOptions {
  * Metadata describing a loop node's behaviour.
  */
 export interface GraphLoopMetadata {
-    body: GraphWorkflowDefinition | unknown;
+    /** The nested loop-body workflow document (DECAF-50 §4.9). */
+    body: GraphWorkflowDocument;
     maxIterations?: number;
     timeoutMs?: number;
     condition?: GraphConditionDefinition;
@@ -142,7 +167,7 @@ export interface GraphPinningMetadata {
  * Options for pinning a node after a completed run.
  */
 export interface GraphPinNodeOptions {
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     plan: unknown;
     result: GraphExecutionResult;
     nodeId: string;
@@ -153,7 +178,7 @@ export interface GraphPinNodeOptions {
  * Options for unpinning a node.
  */
 export interface GraphUnpinNodeOptions {
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     nodeId: string;
     fingerprint: string;
     namespace?: string;

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

@@ -5,13 +5,13 @@
  * types (`ExprValue`, `ConditionExpression`, `CodeCondition`,
  * `SwitchCaseCondition`, `SwitchCase`, `SwitchNodeMetadata`,
  * `NodeMetadataChange`, `GraphExecutionEvent`, `GraphExecutionErrorPayload`)
- * live in `../shared/types`; engine modules import shared symbols from there
- * and engine-private symbols from here.
+ * live in `@decaf-ts/ui-decorators/graph`; engine modules import shared
+ * symbols from there and engine-private symbols from here.
  */
-import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionStatus } from "../shared/constants.d.mts";
-import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "../shared/types.d.mts";
-export type { GraphExecutionErrorPayload, GraphExecutionEvent, } from "../shared/types.d.mts";
+import type { GraphCredentialReference, GraphJsonValue, GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionStatus } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
 /**
  * Unique identifier for a single graph execution run.
  */
@@ -49,6 +49,7 @@ export interface GraphExecutionOptions {
     usePinnedValues?: boolean;
     writeThroughCache?: boolean;
     metadata?: Record<string, unknown>;
+    abortSignal?: AbortSignal;
 }
 /**
  * Result of executing a single node.
@@ -67,13 +68,16 @@ export interface GraphNodeExecutionResult {
 }
 /**
  * Result of executing an entire workflow.
+ *
+ * The executed source of truth is the canonical {@link GraphWorkflowDocument}
+ * (never a decorated workflow definition).
  */
 export interface GraphExecutionResult {
     runId: GraphRunId;
     parentRunId?: GraphRunId;
     workflowId: GraphWorkflowId;
     status: GraphExecutionStatus;
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     inputs: GraphExecutionValues;
     outputs: GraphExecutionValues;
     nodeResults: Record<GraphNodeId, GraphNodeExecutionResult>;
@@ -82,14 +86,34 @@ export interface GraphExecutionResult {
     finishedAt?: Date;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Credential references resolved for a node execution (DECAF-50 §4.9/§4.16).
+ * Documents carry references only; secret material never enters the request.
+ */
+export type GraphResolvedCredentials = Record<string, GraphCredentialReference>;
+/**
+ * Request passed to request-based node executors (DECAF-50 §4.9).
+ * Configuration (`parameters`, `credentials`, `metadata`) and input data
+ * (`inputs`) are separated.
+ */
+export interface GraphNodeExecutionRequest {
+    nodeId: string;
+    kind: string;
+    inputs: GraphExecutionValues;
+    parameters: Record<string, GraphJsonValue>;
+    credentials: GraphResolvedCredentials;
+    metadata?: Record<string, GraphJsonValue>;
+}
 /**
  * Options used to construct a {@link GraphExecutionContext}.
  */
 export interface GraphExecutionContextOptions {
     runId: GraphRunId;
     parentRunId?: GraphRunId;
-    workflow: GraphWorkflowDefinition;
-    node: GraphNodeDefinition;
+    workflowId: GraphWorkflowId;
+    document: GraphWorkflowDocument;
+    node: GraphNodeInstance;
+    manifest: GraphResolvedNodeManifest;
     path: string[];
     metadata?: Record<string, unknown>;
 }
@@ -97,7 +121,8 @@ export interface GraphExecutionContextOptions {
  * Metadata describing a loop node's behaviour.
  */
 export interface GraphLoopMetadata {
-    body: GraphWorkflowDefinition | unknown;
+    /** The nested loop-body workflow document (DECAF-50 §4.9). */
+    body: GraphWorkflowDocument;
     maxIterations?: number;
     timeoutMs?: number;
     condition?: GraphConditionDefinition;
@@ -142,7 +167,7 @@ export interface GraphPinningMetadata {
  * Options for pinning a node after a completed run.
  */
 export interface GraphPinNodeOptions {
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     plan: unknown;
     result: GraphExecutionResult;
     nodeId: string;
@@ -153,7 +178,7 @@ export interface GraphPinNodeOptions {
  * Options for unpinning a node.
  */
 export interface GraphUnpinNodeOptions {
-    workflow: GraphWorkflowDefinition;
+    document: GraphWorkflowDocument;
     nodeId: string;
     fingerprint: string;
     namespace?: string;

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

@@ -0,0 +1,32 @@
+/**
+ * @module integrations/graph/engine/validation/GraphConnectionPolicyValidator
+ * @summary Connection-policy validation (DECAF-50 §4.8 stage 6).
+ * @description Enforces the connection policies declared on effective ports:
+ * allowed/blocked node kinds, allowed port categories, connection counts
+ * (`maxConnections`, `allowMultiple`), self-connections (`allowSelf`), and
+ * conflicting duplicate edges.
+ */
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.cts";
+import type { GraphResolvedWorkflow } from "./GraphResolvedWorkflow.d.cts";
+/**
+ * Validates connection policies and edge-level structural conflicts.
+ */
+export declare class GraphConnectionPolicyValidator {
+    /**
+     * Stage 6 — connection policies and counts. Operates on the resolved
+     * workflow (stage 5 output). Records issues; never mutates the graph.
+     */
+    validate(workflow: Pick<GraphResolvedWorkflow, "edges" | "nodeById">, issues: GraphValidationIssue[]): void;
+    /**
+     * Conflicting duplicate edges: two edges with identical flattened
+     * endpoints (`source:port -> target:port`) are rejected, whatever their
+     * ids.
+     */
+    private validateDuplicates;
+    /**
+     * Port-declared connection policies: kind allow/block lists, port
+     * categories, self-connections, and connection counts.
+     */
+    private validatePolicies;
+    private validateEdgePolicy;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * @module integrations/graph/engine/validation/GraphConnectionPolicyValidator
+ * @summary Connection-policy validation (DECAF-50 §4.8 stage 6).
+ * @description Enforces the connection policies declared on effective ports:
+ * allowed/blocked node kinds, allowed port categories, connection counts
+ * (`maxConnections`, `allowMultiple`), self-connections (`allowSelf`), and
+ * conflicting duplicate edges.
+ */
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.mts";
+import type { GraphResolvedWorkflow } from "./GraphResolvedWorkflow.d.mts";
+/**
+ * Validates connection policies and edge-level structural conflicts.
+ */
+export declare class GraphConnectionPolicyValidator {
+    /**
+     * Stage 6 — connection policies and counts. Operates on the resolved
+     * workflow (stage 5 output). Records issues; never mutates the graph.
+     */
+    validate(workflow: Pick<GraphResolvedWorkflow, "edges" | "nodeById">, issues: GraphValidationIssue[]): void;
+    /**
+     * Conflicting duplicate edges: two edges with identical flattened
+     * endpoints (`source:port -> target:port`) are rejected, whatever their
+     * ids.
+     */
+    private validateDuplicates;
+    /**
+     * Port-declared connection policies: kind allow/block lists, port
+     * categories, self-connections, and connection counts.
+     */
+    private validatePolicies;
+    private validateEdgePolicy;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * @module integrations/graph/engine/validation/GraphCredentialReferenceValidator
+ * @summary Credential-reference authorization (DECAF-50 §4.8 stage 8).
+ * @description Validates that credential references required by node
+ * manifests exist, are authorized, and match the declared credential types,
+ * and that plain credential secrets never appear in workflow documents.
+ *
+ * Existence/authorization checks run against a pluggable
+ * {@link GraphCredentialAuthorizer} hook; server-side integrations wire the
+ * real credential store into it (DECAF-50 §4.16). Without an authorizer,
+ * shape and type-match validation still run — silent credential material in
+ * documents is rejected unconditionally.
+ */
+import type { GraphCredentialReference, GraphCredentialRequirement, GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.cts";
+/**
+ * Server-side hook resolving credential references.
+ */
+export interface GraphCredentialAuthorizer {
+    /** Returns whether the referenced credential exists. */
+    hasCredential(reference: GraphCredentialReference): Promise<boolean> | boolean;
+    /** Returns whether the reference is authorized for the current context. */
+    authorize(reference: GraphCredentialReference, requirement?: GraphCredentialRequirement): Promise<boolean> | boolean;
+}
+/**
+ * Validates credential references and the absence of plain secrets.
+ */
+export declare class GraphCredentialReferenceValidator {
+    private readonly authorizer?;
+    constructor(authorizer?: GraphCredentialAuthorizer | undefined);
+    /**
+     * Stage 8 — credential-reference authorization for one resolved node.
+     */
+    validate(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string): Promise<void>;
+    /**
+     * Collects the credential references carried by a node instance:
+     * credential-type parameter values and the `credentials` record in
+     * instance metadata.
+     */
+    private collectReferences;
+    private normalize;
+    private checkType;
+    /**
+     * Plain credential secrets must never appear in workflow documents: any
+     * parameter or metadata key on the secret deny-list is an issue at any
+     * nesting depth (objects and arrays are walked recursively with a depth
+     * cap and cycle guard), as is a credential reference object carrying
+     * extra material (e.g. a `secret` or `value` member).
+     */
+    private scanPlainSecrets;
+    /**
+     * Recursive worker for {@link scanPlainSecrets}: walks one parameter or
+     * metadata value, reporting a `credential.plain-secret` issue when the
+     * current path's key is on the deny-list, and recursing into objects and
+     * arrays otherwise (array items append a `[]` path segment). The
+     * {@link MAX_PLAIN_SECRET_SCAN_DEPTH} cap bounds the walk — deep enough
+     * for legitimate documents, and a guard against pathological/cyclic
+     * input — so nested deny-list keys are caught at any practical depth.
+     */
+    private scanPlainSecretValue;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * @module integrations/graph/engine/validation/GraphCredentialReferenceValidator
+ * @summary Credential-reference authorization (DECAF-50 §4.8 stage 8).
+ * @description Validates that credential references required by node
+ * manifests exist, are authorized, and match the declared credential types,
+ * and that plain credential secrets never appear in workflow documents.
+ *
+ * Existence/authorization checks run against a pluggable
+ * {@link GraphCredentialAuthorizer} hook; server-side integrations wire the
+ * real credential store into it (DECAF-50 §4.16). Without an authorizer,
+ * shape and type-match validation still run — silent credential material in
+ * documents is rejected unconditionally.
+ */
+import type { GraphCredentialReference, GraphCredentialRequirement, GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.mts";
+/**
+ * Server-side hook resolving credential references.
+ */
+export interface GraphCredentialAuthorizer {
+    /** Returns whether the referenced credential exists. */
+    hasCredential(reference: GraphCredentialReference): Promise<boolean> | boolean;
+    /** Returns whether the reference is authorized for the current context. */
+    authorize(reference: GraphCredentialReference, requirement?: GraphCredentialRequirement): Promise<boolean> | boolean;
+}
+/**
+ * Validates credential references and the absence of plain secrets.
+ */
+export declare class GraphCredentialReferenceValidator {
+    private readonly authorizer?;
+    constructor(authorizer?: GraphCredentialAuthorizer | undefined);
+    /**
+     * Stage 8 — credential-reference authorization for one resolved node.
+     */
+    validate(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string): Promise<void>;
+    /**
+     * Collects the credential references carried by a node instance:
+     * credential-type parameter values and the `credentials` record in
+     * instance metadata.
+     */
+    private collectReferences;
+    private normalize;
+    private checkType;
+    /**
+     * Plain credential secrets must never appear in workflow documents: any
+     * parameter or metadata key on the secret deny-list is an issue at any
+     * nesting depth (objects and arrays are walked recursively with a depth
+     * cap and cycle guard), as is a credential reference object carrying
+     * extra material (e.g. a `secret` or `value` member).
+     */
+    private scanPlainSecrets;
+    /**
+     * Recursive worker for {@link scanPlainSecrets}: walks one parameter or
+     * metadata value, reporting a `credential.plain-secret` issue when the
+     * current path's key is on the deny-list, and recursing into objects and
+     * arrays otherwise (array items append a `[]` path segment). The
+     * {@link MAX_PLAIN_SECRET_SCAN_DEPTH} cap bounds the walk — deep enough
+     * for legitimate documents, and a guard against pathological/cyclic
+     * input — so nested deny-list keys are caught at any practical depth.
+     */
+    private scanPlainSecretValue;
+}

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

@@ -1,21 +1,23 @@
 /**
  * @module integrations/graph/validation/GraphDefinitionValidator
- * @summary Validates graph workflow definitions before execution.
- * @description Checks workflow structure, node IDs, relation endpoints/ports, required port sources, cycles, and loop metadata.
+ * @summary Legacy structural checks for decorated workflow definitions.
+ * @description Kept for the §4.18 transition. Full workflow validation moved
+ * to the nine-stage document gate ({@link GraphWorkflowDocumentValidator});
+ * this shim only performs the cheap structural checks that do not require
+ * catalogue resolution.
  */
 import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import { GraphExecutionPlanner } from "../planning/GraphExecutionPlanner.d.cts";
 /**
- * Validates a {@link GraphWorkflowDefinition} before execution.
+ * Performs cheap structural checks on a legacy {@link GraphWorkflowDefinition}.
+ *
+ * @deprecated Validate canonical documents with
+ *   {@link GraphWorkflowDocumentValidator} instead.
  */
 export declare class GraphDefinitionValidator {
-    private readonly planner;
-    constructor(planner?: GraphExecutionPlanner);
     /**
-     * Validates the workflow definition.
+     * Validates the workflow definition structure.
      *
-     * @throws {GraphInputError} when the workflow has no name or invalid structure.
-     * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
+     * @throws {GraphInputError} when the workflow has no name or duplicate node ids.
      */
     validate(workflow: GraphWorkflowDefinition): void;
 }

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

@@ -1,21 +1,23 @@
 /**
  * @module integrations/graph/validation/GraphDefinitionValidator
- * @summary Validates graph workflow definitions before execution.
- * @description Checks workflow structure, node IDs, relation endpoints/ports, required port sources, cycles, and loop metadata.
+ * @summary Legacy structural checks for decorated workflow definitions.
+ * @description Kept for the §4.18 transition. Full workflow validation moved
+ * to the nine-stage document gate ({@link GraphWorkflowDocumentValidator});
+ * this shim only performs the cheap structural checks that do not require
+ * catalogue resolution.
  */
 import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import { GraphExecutionPlanner } from "../planning/GraphExecutionPlanner.d.mts";
 /**
- * Validates a {@link GraphWorkflowDefinition} before execution.
+ * Performs cheap structural checks on a legacy {@link GraphWorkflowDefinition}.
+ *
+ * @deprecated Validate canonical documents with
+ *   {@link GraphWorkflowDocumentValidator} instead.
  */
 export declare class GraphDefinitionValidator {
-    private readonly planner;
-    constructor(planner?: GraphExecutionPlanner);
     /**
-     * Validates the workflow definition.
+     * Validates the workflow definition structure.
      *
-     * @throws {GraphInputError} when the workflow has no name or invalid structure.
-     * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
+     * @throws {GraphInputError} when the workflow has no name or duplicate node ids.
      */
     validate(workflow: GraphWorkflowDefinition): void;
 }

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

@@ -0,0 +1,32 @@
+/**
+ * @module integrations/graph/engine/validation/GraphEdgeInstanceValidator
+ * @summary Edge endpoint validation (DECAF-50 §4.8 stage 5).
+ * @description Validates that edge endpoints exist (nodes, workflow ports,
+ * and effective node ports), that source/target directions are valid, that
+ * data and structural (connection) edges use compatible ports, and that
+ * boundary routing is valid. Produces flattened
+ * {@link GraphResolvedEdgeInstance}s for the planner.
+ */
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeInstance, GraphResolvedEdgeInstance } from "./GraphResolvedWorkflow.d.cts";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.cts";
+/**
+ * Validates edge instances and resolves them into flattened plan edges.
+ */
+export declare class GraphEdgeInstanceValidator {
+    /**
+     * Stage 5 — edge endpoints. Returns the resolved (flattened) edges for
+     * every structurally valid edge; invalid edges are skipped (issues
+     * recorded) so the planner only ever sees valid routing.
+     *
+     * Port existence/direction checks are skipped for nodes whose manifest
+     * policy allows undeclared parameters (transition placeholder kinds with
+     * no declared ports) — the catalogue is authoritative and those legacy
+     * registrations declare no port surface to check against.
+     */
+    resolveEdges(document: GraphWorkflowDocument, nodesById: Map<string, GraphResolvedNodeInstance>, issues: GraphValidationIssue[]): GraphResolvedEdgeInstance[];
+    private resolveEndpoint;
+    private validateDirectionAndType;
+    private hasPortDirection;
+    private pushPortIssue;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * @module integrations/graph/engine/validation/GraphEdgeInstanceValidator
+ * @summary Edge endpoint validation (DECAF-50 §4.8 stage 5).
+ * @description Validates that edge endpoints exist (nodes, workflow ports,
+ * and effective node ports), that source/target directions are valid, that
+ * data and structural (connection) edges use compatible ports, and that
+ * boundary routing is valid. Produces flattened
+ * {@link GraphResolvedEdgeInstance}s for the planner.
+ */
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeInstance, GraphResolvedEdgeInstance } from "./GraphResolvedWorkflow.d.mts";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.mts";
+/**
+ * Validates edge instances and resolves them into flattened plan edges.
+ */
+export declare class GraphEdgeInstanceValidator {
+    /**
+     * Stage 5 — edge endpoints. Returns the resolved (flattened) edges for
+     * every structurally valid edge; invalid edges are skipped (issues
+     * recorded) so the planner only ever sees valid routing.
+     *
+     * Port existence/direction checks are skipped for nodes whose manifest
+     * policy allows undeclared parameters (transition placeholder kinds with
+     * no declared ports) — the catalogue is authoritative and those legacy
+     * registrations declare no port surface to check against.
+     */
+    resolveEdges(document: GraphWorkflowDocument, nodesById: Map<string, GraphResolvedNodeInstance>, issues: GraphValidationIssue[]): GraphResolvedEdgeInstance[];
+    private resolveEndpoint;
+    private validateDirectionAndType;
+    private hasPortDirection;
+    private pushPortIssue;
+}