@decaf-ts/integrations 0.7.0 → 0.9.0

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

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