@decaf-ts/integrations 0.8.0 → 0.9.0

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

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

@@ -0,0 +1,37 @@
+/**
+ * @module integrations/graph/engine/validation/GraphNodeInstanceValidator
+ * @summary Kind resolution and dynamic-port validation (DECAF-50 §4.8 stages 2 and 4).
+ * @description Stage 2 resolves every node instance against the trusted
+ * backend catalogue (kind existence, effective manifest with expanded
+ * dynamic ports, paired executor). Stage 4 validates that the effective
+ * dynamic ports resolved consistently and that binding ids refer to
+ * effective ports.
+ */
+import type { GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.cts";
+import type { GraphNodeResolutionContext, GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.cts";
+import type { GraphResolvedNodeInstance } from "./GraphResolvedWorkflow.d.cts";
+/**
+ * Resolves node instances against the backend catalogue and validates the
+ * resolved dynamic-port surface.
+ */
+export declare class GraphNodeInstanceValidator {
+    private readonly catalogue;
+    constructor(catalogue: GraphNodeCatalogue);
+    /**
+     * Stage 2 — kind resolution. Every node kind must exist in the backend
+     * catalogue; the effective manifest (with dynamic ports expanded from the
+     * instance parameters) and the paired executor are attached to the
+     * resolved node. Nodes that fail resolution are skipped (issues recorded)
+     * and never reach the planner.
+     */
+    resolveNodes(nodes: GraphNodeInstance[], issues: GraphValidationIssue[], resolutionContext?: GraphNodeResolutionContext): Promise<Map<string, GraphResolvedNodeInstance>>;
+    /**
+     * Stage 4 — dynamic ports and binding ids. Verifies that input/output
+     * binding ids refer to ports on the effective (dynamics-expanded) manifest
+     * surface, unless the manifest policy explicitly allows undeclared
+     * parameters (transition placeholder kinds).
+     */
+    validateEffectivePorts(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string): void;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * @module integrations/graph/engine/validation/GraphNodeInstanceValidator
+ * @summary Kind resolution and dynamic-port validation (DECAF-50 §4.8 stages 2 and 4).
+ * @description Stage 2 resolves every node instance against the trusted
+ * backend catalogue (kind existence, effective manifest with expanded
+ * dynamic ports, paired executor). Stage 4 validates that the effective
+ * dynamic ports resolved consistently and that binding ids refer to
+ * effective ports.
+ */
+import type { GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.mts";
+import type { GraphNodeResolutionContext, GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.mts";
+import type { GraphResolvedNodeInstance } from "./GraphResolvedWorkflow.d.mts";
+/**
+ * Resolves node instances against the backend catalogue and validates the
+ * resolved dynamic-port surface.
+ */
+export declare class GraphNodeInstanceValidator {
+    private readonly catalogue;
+    constructor(catalogue: GraphNodeCatalogue);
+    /**
+     * Stage 2 — kind resolution. Every node kind must exist in the backend
+     * catalogue; the effective manifest (with dynamic ports expanded from the
+     * instance parameters) and the paired executor are attached to the
+     * resolved node. Nodes that fail resolution are skipped (issues recorded)
+     * and never reach the planner.
+     */
+    resolveNodes(nodes: GraphNodeInstance[], issues: GraphValidationIssue[], resolutionContext?: GraphNodeResolutionContext): Promise<Map<string, GraphResolvedNodeInstance>>;
+    /**
+     * Stage 4 — dynamic ports and binding ids. Verifies that input/output
+     * binding ids refer to ports on the effective (dynamics-expanded) manifest
+     * surface, unless the manifest policy explicitly allows undeclared
+     * parameters (transition placeholder kinds).
+     */
+    validateEffectivePorts(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string): void;
+}

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

@@ -0,0 +1,92 @@
+/**
+ * @module integrations/graph/engine/validation/GraphParameterValidator
+ * @summary Parameter and binding validation (DECAF-50 §4.8 stage 3).
+ * @description Validates node parameters against the effective resolved
+ * manifest: declared-ness (unless the manifest policy explicitly allows
+ * undeclared parameters), required presence, value typing, declarative
+ * validation rules, metadata keys, disabled-node behavior, and input binding
+ * validity (literal schema conformance, expression shape, literal/edge
+ * conflicts, and required-input satisfiability). Security-sensitive
+ * validation is invariant under visibility state — hidden or
+ * conditionally-hidden parameters are validated exactly like visible ones.
+ */
+import type { GraphCredentialReference, GraphJsonValue, GraphNodeInstance, GraphValueSchema } from "@decaf-ts/ui-decorators/graph";
+import { GRAPH_DISABLED_NODE_BEHAVIORS } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.cts";
+import type { GraphResolvedEdgeInstance } from "./GraphResolvedWorkflow.d.cts";
+/**
+ * Checks a JSON value against a {@link GraphValueSchema}.
+ *
+ * `model` schemas are treated as `object` (property-level checks apply only
+ * when a `properties` map is declared).
+ */
+export declare function checkGraphValueAgainstSchema(value: unknown, schema: GraphValueSchema | undefined): {
+    valid: boolean;
+    message?: string;
+};
+/**
+ * Returns `true` when the value looks like a plain credential reference
+ * (a `credentialId` string, optionally with a `credentialType`).
+ */
+export declare function isGraphCredentialReferenceLike(value: unknown): value is GraphCredentialReference;
+/**
+ * Keys that must never carry plain secret material in a workflow document
+ * (DECAF-50 §4.8/§4.16 — documents store credential references only).
+ */
+export declare const GRAPH_PLAIN_SECRET_KEYS: readonly ["secret", "secrets", "password", "passwd", "token", "accessToken", "refreshToken", "apiKey", "api_key", "privateKey", "credentials"];
+/**
+ * Validates the parameters, bindings, metadata, and disabled behavior of a
+ * single resolved node instance.
+ */
+export declare class GraphParameterValidator {
+    /**
+     * Validates a node's parameters, instance metadata keys, disabled
+     * behavior, and binding shapes against the effective manifest.
+     *
+     * Called at stage 3 (parameters) with the manifest resolved at stage 2.
+     */
+    validate(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string): void;
+    /**
+     * Declared-ness, required presence, typing, and declarative validation
+     * rules for parameter values. Validation is visibility-invariant: hidden
+     * parameters are validated identically (visibility cannot bypass
+     * security-sensitive validation).
+     */
+    private validateParameters;
+    /**
+     * Type-checks a parameter value against its parameter definition.
+     */
+    private checkParameterValue;
+    /**
+     * Instance metadata keys: unsafe keys and engine-reserved keys are
+     * rejected; when the manifest declares an explicit allow-list
+     * (`metadata.allowedInstanceMetadataKeys`), only listed keys are allowed.
+     */
+    private validateMetadataKeys;
+    /**
+     * Disabled-node behavior must be one of the explicit
+     * {@link GRAPH_DISABLED_NODE_BEHAVIORS} values when configured.
+     */
+    private validateDisabledBehavior;
+    /**
+     * Binding shape validity: literal bindings must conform to the effective
+     * port schema (when declared), expression bindings must be non-empty
+     * strings, and binding values must be JSON-safe.
+     */
+    private validateBindingShapes;
+    /**
+     * Stage-7 binding satisfaction checks: a port with an incoming edge must
+     * not also carry a literal binding (unless explicitly allowed), and every
+     * required effective input port must be satisfiable (incoming edge,
+     * literal, or expression binding).
+     */
+    validateBindingSatisfaction(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, incoming: GraphResolvedEdgeInstance[], issues: GraphValidationIssue[], path: string, options?: {
+        allowLiteralAndEdgeBindings?: boolean;
+    }): void;
+    /**
+     * Resolves the effective disabled-node behavior for a node: instance
+     * metadata override, else the document settings, else the default.
+     */
+    static disabledBehaviorOf(node: GraphNodeInstance, settings: Record<string, GraphJsonValue> | undefined): (typeof GRAPH_DISABLED_NODE_BEHAVIORS)[number];
+}