@decaf-ts/integrations 0.8.0 → 0.10.0

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

@@ -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.mts";
+import type { GraphResolvedEdgeInstance } from "./GraphResolvedWorkflow.d.mts";
+/**
+ * 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];
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @module integrations/graph/engine/validation/GraphResolvedWorkflow
+ * @summary Backend-only resolved workflow types (DECAF-50 §4.8/§4.9).
+ * @description A {@link GraphResolvedWorkflow} is a canonical
+ * {@link GraphWorkflowDocument} whose node kinds have been resolved against
+ * the trusted backend catalogue (manifest + executor + dynamic ports) and
+ * whose edges have been flattened into resolved endpoints. It is the ONLY
+ * input the {@link GraphExecutionPlanner} accepts.
+ */
+import type { GraphEdgeInstance, GraphJsonValue, GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+/**
+ * A node instance resolved against the backend catalogue.
+ */
+export interface GraphResolvedNodeInstance {
+    /** The canonical node instance from the document. */
+    instance: GraphNodeInstance;
+    /** The effective (dynamics-expanded) manifest for the instance. */
+    manifest: GraphResolvedNodeManifest;
+    /** The trusted executor paired with the kind in the catalogue. */
+    executor: GraphNodeExecutor;
+}
+/**
+ * An edge instance with flattened endpoints. Workflow-scope endpoints use
+ * the `GRAPH_WORKFLOW_BOUNDARY` node id (`"$workflow"`) so the value store's
+ * boundary bucket keeps working unchanged.
+ */
+export interface GraphResolvedEdgeInstance {
+    /** Edge id (unique within the document). */
+    id: string;
+    /** `data` or `connection`. */
+    type: "data" | "connection";
+    /** Source node id, or the workflow boundary id for workflow inputs. */
+    sourceNodeId: string;
+    /** Source port id (workflow input port or node output/connection port). */
+    sourcePort: string;
+    /** Target node id, or the workflow boundary id for workflow outputs. */
+    targetNodeId: string;
+    /** Target port id (workflow output port or node input/connection port). */
+    targetPort: string;
+    /** Optional edge label. */
+    label?: string;
+    /** Edge-owned metadata permitted by the shared contract. */
+    metadata?: Record<string, GraphJsonValue>;
+    /** The canonical edge instance from the document. */
+    edge: GraphEdgeInstance;
+}
+/**
+ * A canonical workflow document fully resolved against the backend catalogue.
+ * Backend-only — never serialised to clients.
+ */
+export interface GraphResolvedWorkflow {
+    /** The canonical document that was validated. */
+    document: GraphWorkflowDocument;
+    /** Resolved node instances, in document order. */
+    nodes: GraphResolvedNodeInstance[];
+    /** Resolved edge instances, in document order. */
+    edges: GraphResolvedEdgeInstance[];
+    /** Node lookup by id. */
+    nodeById: Map<string, GraphResolvedNodeInstance>;
+    /** Incoming edges per node id (boundary excluded from keys). */
+    incomingByNode: Map<string, GraphResolvedEdgeInstance[]>;
+    /** Outgoing edges per node id (boundary excluded from keys). */
+    outgoingByNode: Map<string, GraphResolvedEdgeInstance[]>;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @module integrations/graph/engine/validation/GraphResolvedWorkflow
+ * @summary Backend-only resolved workflow types (DECAF-50 §4.8/§4.9).
+ * @description A {@link GraphResolvedWorkflow} is a canonical
+ * {@link GraphWorkflowDocument} whose node kinds have been resolved against
+ * the trusted backend catalogue (manifest + executor + dynamic ports) and
+ * whose edges have been flattened into resolved endpoints. It is the ONLY
+ * input the {@link GraphExecutionPlanner} accepts.
+ */
+import type { GraphEdgeInstance, GraphJsonValue, GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+/**
+ * A node instance resolved against the backend catalogue.
+ */
+export interface GraphResolvedNodeInstance {
+    /** The canonical node instance from the document. */
+    instance: GraphNodeInstance;
+    /** The effective (dynamics-expanded) manifest for the instance. */
+    manifest: GraphResolvedNodeManifest;
+    /** The trusted executor paired with the kind in the catalogue. */
+    executor: GraphNodeExecutor;
+}
+/**
+ * An edge instance with flattened endpoints. Workflow-scope endpoints use
+ * the `GRAPH_WORKFLOW_BOUNDARY` node id (`"$workflow"`) so the value store's
+ * boundary bucket keeps working unchanged.
+ */
+export interface GraphResolvedEdgeInstance {
+    /** Edge id (unique within the document). */
+    id: string;
+    /** `data` or `connection`. */
+    type: "data" | "connection";
+    /** Source node id, or the workflow boundary id for workflow inputs. */
+    sourceNodeId: string;
+    /** Source port id (workflow input port or node output/connection port). */
+    sourcePort: string;
+    /** Target node id, or the workflow boundary id for workflow outputs. */
+    targetNodeId: string;
+    /** Target port id (workflow output port or node input/connection port). */
+    targetPort: string;
+    /** Optional edge label. */
+    label?: string;
+    /** Edge-owned metadata permitted by the shared contract. */
+    metadata?: Record<string, GraphJsonValue>;
+    /** The canonical edge instance from the document. */
+    edge: GraphEdgeInstance;
+}
+/**
+ * A canonical workflow document fully resolved against the backend catalogue.
+ * Backend-only — never serialised to clients.
+ */
+export interface GraphResolvedWorkflow {
+    /** The canonical document that was validated. */
+    document: GraphWorkflowDocument;
+    /** Resolved node instances, in document order. */
+    nodes: GraphResolvedNodeInstance[];
+    /** Resolved edge instances, in document order. */
+    edges: GraphResolvedEdgeInstance[];
+    /** Node lookup by id. */
+    nodeById: Map<string, GraphResolvedNodeInstance>;
+    /** Incoming edges per node id (boundary excluded from keys). */
+    incomingByNode: Map<string, GraphResolvedEdgeInstance[]>;
+    /** Outgoing edges per node id (boundary excluded from keys). */
+    outgoingByNode: Map<string, GraphResolvedEdgeInstance[]>;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * @module integrations/graph/engine/validation/GraphValidationErrors
+ * @summary Normative validation error hierarchy for graph modules (DECAF-50 §4.8).
+ * @description Decaf error hierarchy ONLY (constitution §1.1.3): these errors
+ * extend the base Decaf errors, never raw `Error`. They are thrown for
+ * fail-fast paths (e.g. the engine refusing to execute an invalid document);
+ * the nine-stage validator itself accumulates structured
+ * {@link GraphValidationIssue}s instead of throwing.
+ */
+import { AuthorizationError } from "@decaf-ts/core";
+import { ValidationError } from "@decaf-ts/db-decorators";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.cts";
+/**
+ * Thrown when a workflow document is structurally or semantically invalid.
+ * Carries the structured issues found by the nine-stage validator.
+ */
+export declare class GraphDocumentValidationError extends ValidationError {
+    readonly issues: GraphValidationIssue[];
+    constructor(message: string, issues?: GraphValidationIssue[]);
+}
+/**
+ * Thrown when an edge violates connection-policy rules.
+ */
+export declare class GraphConnectionValidationError extends ValidationError {
+    readonly edgeId?: string;
+    constructor(message: string, edgeId?: string);
+}
+/**
+ * Thrown when a credential reference fails existence, authorization, or
+ * type-match checks.
+ */
+export declare class GraphCredentialAuthorizationError extends AuthorizationError {
+    constructor(message: string);
+}

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

@@ -0,0 +1,34 @@
+/**
+ * @module integrations/graph/engine/validation/GraphValidationErrors
+ * @summary Normative validation error hierarchy for graph modules (DECAF-50 §4.8).
+ * @description Decaf error hierarchy ONLY (constitution §1.1.3): these errors
+ * extend the base Decaf errors, never raw `Error`. They are thrown for
+ * fail-fast paths (e.g. the engine refusing to execute an invalid document);
+ * the nine-stage validator itself accumulates structured
+ * {@link GraphValidationIssue}s instead of throwing.
+ */
+import { AuthorizationError } from "@decaf-ts/core";
+import { ValidationError } from "@decaf-ts/db-decorators";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.mts";
+/**
+ * Thrown when a workflow document is structurally or semantically invalid.
+ * Carries the structured issues found by the nine-stage validator.
+ */
+export declare class GraphDocumentValidationError extends ValidationError {
+    readonly issues: GraphValidationIssue[];
+    constructor(message: string, issues?: GraphValidationIssue[]);
+}
+/**
+ * Thrown when an edge violates connection-policy rules.
+ */
+export declare class GraphConnectionValidationError extends ValidationError {
+    readonly edgeId?: string;
+    constructor(message: string, edgeId?: string);
+}
+/**
+ * Thrown when a credential reference fails existence, authorization, or
+ * type-match checks.
+ */
+export declare class GraphCredentialAuthorizationError extends AuthorizationError {
+    constructor(message: string);
+}

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

@@ -0,0 +1,39 @@
+/**
+ * @module integrations/graph/engine/validation/GraphValidationIssue
+ * @summary Structured workflow-document validation issues (DECAF-50 §4.8).
+ * @description Structured issue accumulation for the nine-stage backend
+ * workflow validation gate. Validators record {@link GraphValidationIssue}s
+ * instead of failing abruptly; a completed
+ * {@link GraphWorkflowValidationResult} carries every issue found plus, when
+ * valid, the resolved workflow consumed by the planner.
+ */
+import type { GraphJsonValue } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedWorkflow } from "./GraphResolvedWorkflow.d.cts";
+/**
+ * A single validation finding for a workflow document.
+ */
+export interface GraphValidationIssue {
+    /** Stable machine-readable issue code (e.g. `kind.unknown`). */
+    code: string;
+    /** Dotted path to the offending part of the document. */
+    path: string;
+    /** Human-readable description of the issue. */
+    message: string;
+    /** Node instance the issue refers to, when applicable. */
+    nodeId?: string;
+    /** Edge instance the issue refers to, when applicable. */
+    edgeId?: string;
+    /** Safe extra context (JSON values only — never credentials). */
+    details?: Record<string, GraphJsonValue>;
+}
+/**
+ * Result of validating (and, when valid, resolving) a workflow document.
+ */
+export interface GraphWorkflowValidationResult {
+    /** `true` when the document passed all nine validation stages. */
+    valid: boolean;
+    /** Every issue found, in normative stage order 1→9. */
+    issues: GraphValidationIssue[];
+    /** The resolved workflow, present when `valid` is `true`. */
+    resolved?: GraphResolvedWorkflow;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * @module integrations/graph/engine/validation/GraphValidationIssue
+ * @summary Structured workflow-document validation issues (DECAF-50 §4.8).
+ * @description Structured issue accumulation for the nine-stage backend
+ * workflow validation gate. Validators record {@link GraphValidationIssue}s
+ * instead of failing abruptly; a completed
+ * {@link GraphWorkflowValidationResult} carries every issue found plus, when
+ * valid, the resolved workflow consumed by the planner.
+ */
+import type { GraphJsonValue } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedWorkflow } from "./GraphResolvedWorkflow.d.mts";
+/**
+ * A single validation finding for a workflow document.
+ */
+export interface GraphValidationIssue {
+    /** Stable machine-readable issue code (e.g. `kind.unknown`). */
+    code: string;
+    /** Dotted path to the offending part of the document. */
+    path: string;
+    /** Human-readable description of the issue. */
+    message: string;
+    /** Node instance the issue refers to, when applicable. */
+    nodeId?: string;
+    /** Edge instance the issue refers to, when applicable. */
+    edgeId?: string;
+    /** Safe extra context (JSON values only — never credentials). */
+    details?: Record<string, GraphJsonValue>;
+}
+/**
+ * Result of validating (and, when valid, resolving) a workflow document.
+ */
+export interface GraphWorkflowValidationResult {
+    /** `true` when the document passed all nine validation stages. */
+    valid: boolean;
+    /** Every issue found, in normative stage order 1→9. */
+    issues: GraphValidationIssue[];
+    /** The resolved workflow, present when `valid` is `true`. */
+    resolved?: GraphResolvedWorkflow;
+}

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

@@ -0,0 +1,162 @@
+/**
+ * @module integrations/graph/engine/validation/GraphWorkflowDocumentValidator
+ * @summary Nine-stage backend workflow-document validation gate (DECAF-50 §4.8).
+ * @description Validates a canonical {@link GraphWorkflowDocument} and, when
+ * valid, resolves it into a backend-only {@link GraphResolvedWorkflow} — the
+ * only input the {@link GraphExecutionPlanner} accepts. The nine stages run
+ * in the EXACT normative order 1→9:
+ *
+ * 1. workflow structure (shape, JSON safety, unique ids, backend-enforced
+ *    limits, forbidden definition/executor fields, recursive nested loop-body
+ *    validation),
+ * 2. kind resolution against the trusted backend catalogue,
+ * 3. parameters (declared-ness, required presence, typing, metadata keys,
+ *    disabled behavior, binding shapes),
+ * 4. dynamic ports (binding ids refer to effective ports),
+ * 5. edge endpoints (existence, direction, data/structural compatibility,
+ *    boundary routing),
+ * 6. connection policy (policies, counts, duplicates, self-connections),
+ * 7. topology (acyclicity, binding satisfaction, required-value
+ *    satisfiability),
+ * 8. credential-reference authorization (existence, authorization, type
+ *    match, no plain secrets),
+ * 9. capability validation.
+ *
+ * Issues accumulate as structured {@link GraphValidationIssue}s — validation
+ * never fails abruptly; a document with any issue is reported invalid and is
+ * never resolved. Fail-fast consumers (the execution engine) throw
+ * {@link GraphDocumentValidationError} on invalid results.
+ */
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.cts";
+import type { GraphNodeResolutionContext } from "@decaf-ts/ui-decorators/graph";
+import type { GraphCredentialAuthorizer } from "./GraphCredentialReferenceValidator.d.cts";
+import type { GraphWorkflowValidationResult } from "./GraphValidationIssue.d.cts";
+import type { GraphResolvedWorkflow } from "./GraphResolvedWorkflow.d.cts";
+/**
+ * Backend-enforced, configurable document resource limits (DECAF-50 §4.8).
+ * Mirrors the persistence-boundary limits; every value is overridable.
+ */
+export interface GraphWorkflowDocumentValidationLimits {
+    /** 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 resource limits (technical governance delegates the numbers to
+ * implementation; these match the persistence boundary defaults).
+ */
+export declare const DEFAULT_GRAPH_WORKFLOW_VALIDATION_LIMITS: Required<GraphWorkflowDocumentValidationLimits>;
+/**
+ * Field keys that must never appear on a workflow document or any of its
+ * structural records: client input resembling node definitions, executors,
+ * authoritative ports, or frontend component definitions is rejected before
+ * kind resolution (the planner must never see raw definitions).
+ */
+export declare const GRAPH_DOCUMENT_FORBIDDEN_FIELD_KEYS: readonly string[];
+/**
+ * Options controlling the nine-stage validation gate.
+ */
+export interface GraphWorkflowDocumentValidatorOptions {
+    /** Trusted backend kind catalogue (required). */
+    catalogue: GraphNodeCatalogue;
+    /** Backend-enforced resource limits; defaults to {@link DEFAULT_GRAPH_WORKFLOW_VALIDATION_LIMITS}. */
+    limits?: GraphWorkflowDocumentValidationLimits;
+    /** Pluggable credential existence/authorization hook (DECAF-50 §4.16). */
+    credentialAuthorizer?: GraphCredentialAuthorizer;
+    /** Extra context passed to manifest resolution (credentials, request context). */
+    resolutionContext?: GraphNodeResolutionContext;
+    /**
+     * Transition leniency (§4.18): when `true`, a port with an incoming edge
+     * may also carry a literal binding. Defaults to `false` (conflicting
+     * literal+edge bindings are rejected).
+     */
+    allowLiteralAndEdgeBindings?: boolean;
+}
+/**
+ * Returns `true` when the value structurally looks like a resolved workflow
+ * (resolved node instances + resolved edges + lookup maps over a canonical
+ * document). Used as the planner's runtime input guard.
+ */
+export declare function isGraphResolvedWorkflow(value: unknown): value is GraphResolvedWorkflow;
+/**
+ * The nine-stage backend validation gate (DECAF-50 §4.8).
+ *
+ * Usage: `const result = await validator.validate(document);` — inspect
+ * `result.issues` (structured, in stage order) and `result.resolved` (present
+ * only when valid). Use {@link GraphWorkflowDocumentValidator.validateOrThrow}
+ * for the fail-fast engine path.
+ */
+export declare class GraphWorkflowDocumentValidator {
+    private readonly options;
+    private readonly nodeValidator;
+    private readonly parameterValidator;
+    private readonly edgeValidator;
+    private readonly connectionPolicyValidator;
+    private readonly credentialValidator;
+    constructor(options: GraphWorkflowDocumentValidatorOptions);
+    /**
+     * Fail-fast variant of {@link validate}: resolves the document or throws
+     * {@link GraphDocumentValidationError} carrying every structured issue.
+     */
+    validateOrThrow(document: GraphWorkflowDocument): Promise<GraphResolvedWorkflow>;
+    /**
+     * Runs the nine validation stages in the exact normative order 1→9 and,
+     * when the document is fully valid, resolves it against the backend
+     * catalogue.
+     *
+     * @param document - The canonical workflow document to validate.
+     * @param depth - Current nesting depth (root is 0); enforced against
+     *   `limits.maxNestingDepth` and used to guard recursive loop-body
+     *   validation.
+     * @returns The validation result with accumulated issues and, when valid,
+     *   the resolved workflow.
+     */
+    validate(document: GraphWorkflowDocument, depth?: number): Promise<GraphWorkflowValidationResult>;
+    /**
+     * Stage 1 — document structure. Returns `true` when the document is
+     * structurally sound enough to continue (shape and JSON safety are
+     * hard preconditions); all other findings accumulate as issues.
+     */
+    private validateStructure;
+    /**
+     * Stage 1 — unique node, edge, workflow-input and workflow-output ids.
+     */
+    private validateUniqueIds;
+    /**
+     * Stage 1 — backend-enforced configurable limits: document size, nesting
+     * depth, node count, edge count.
+     */
+    private validateLimits;
+    /**
+     * Stage 1 — recursive nested-workflow validation. Every loop body runs
+     * through the full nine-stage gate; nested issues are merged with a path
+     * prefix identifying the owning loop node.
+     */
+    private validateNestedBodies;
+    /**
+     * Stage 7 — acyclicity (DECAF-32 preserved). Kahn's algorithm over the
+     * resolved executable nodes; connection and data edges both count as
+     * dependencies. Loop constructs are excepted because their bodies are
+     * separate nested documents, validated recursively.
+     */
+    private validateAcyclicity;
+    /**
+     * Stage 7 — required values must be satisfiable: every required workflow
+     * output port must be routable from at least one node output.
+     */
+    private validateRequiredWorkflowOutputs;
+    /**
+     * Stage 9 — capability validation. Declared manifest capabilities must be
+     * known values, and document features that require a capability may only be
+     * used on kinds declaring it (loop configuration requires the `loop`
+     * capability). Lenient transition manifests (legacy executor-only
+     * registrations) are exempt until cutover (§4.18).
+     */
+    private validateCapabilities;
+}