@exellix/graph-engine 6.0.0

package/dist/src/inspection/types.d.ts

@@ -0,0 +1,321 @@
+import type { CatalogBinding, CatalogRequestEntry, GraphDocumentMetadata, GraphEdge, GraphNode, GraphPredicate, GraphReadabilityKind } from '../types/refs.js';
+import type { WebScopeQuestion } from '../types/narrix.js';
+import type { ScopedDataReaderOutput, ScopedDataReaderPackOutput } from '../runtime/localSkills/scopedDataReader.js';
+import type { LocalSkillKey } from '../runtime/localSkills/index.js';
+export type { GraphEdge, GraphPredicate, GraphReadabilityKind, WebScopeQuestion, LocalSkillKey };
+export type { ScopedDataReaderOutput, ScopedDataReaderPackOutput };
+/**
+ * The scoping question for a single node: what it asks, where it reads its data from,
+ * and where it writes its output to.
+ */
+export type NodeScopingQuestion = {
+    nodeId: string;
+    /** Human-readable label (graphReadability.title). */
+    name: string | undefined;
+    /** Plain-language question or intent (graphReadability.asks || inputs.question). */
+    question: string | undefined;
+    /** Role classification of this node (graphReadability.kind). */
+    kind: GraphReadabilityKind | undefined;
+    /** Where the node sources its data from. */
+    sources: NodeScopeSource[];
+    /** Where the node writes its output to. */
+    targets: NodeScopeTarget[];
+};
+/** One data source for a node. */
+export type NodeScopeSource = {
+    /** Category of the source. */
+    type: 'executionMemory' | 'outputsMemory' | 'scopedData' | 'jobMemory' | 'variables' | 'literal';
+    /** Dot-path in execution / job memory / variables. */
+    path?: string;
+    /** x-scoped-data scoping map id (scopedData type only). */
+    scopingMapId?: string;
+    /** Dot-path used to resolve the entity id (scopedData type only). */
+    entityIdPath?: string;
+    /** Question id for question-based scoped reads (scopedData type only). */
+    questionId?: string;
+    /** Expected answer keys from the scope map (graphReadability.reads). */
+    expectedKeys?: string[];
+    /** Human-readable label for this source (from jobContextMapping or inputs key). */
+    label?: string;
+};
+/** One output target for a node. */
+export type NodeScopeTarget = {
+    /** Dot-path in execution/output memory where the node writes. */
+    path: string;
+    /** Target memory lane. Defaults to executionMemory for older inspection consumers. */
+    memory?: 'executionMemory' | 'outputsMemory';
+    mode?: 'replace' | 'append' | 'merge';
+    /** Possible output values / tier names (graphReadability.produces). */
+    produces?: string[];
+};
+/**
+ * Scoping question extended with live fetched x-scoped-data for a given entityId.
+ */
+export type NodeScopingData = NodeScopingQuestion & {
+    entityId: string;
+    data: ScopedDataReaderOutput | ScopedDataReaderPackOutput | null;
+    error?: string;
+};
+/** A single execution-memory path reference with optional metadata. */
+export type MemoryPath = {
+    path: string;
+    /** Memory lane for this path when known. */
+    memory?: 'executionMemory' | 'outputsMemory';
+    /** Which field or mapping this came from (for traceability). */
+    source?: string;
+    required?: boolean;
+};
+/**
+ * Conceptual execution-memory shape for a node: what it expects before running
+ * and what it writes after completing.
+ */
+export type NodeMemoryShape = {
+    nodeId: string;
+    before: {
+        /** Paths this node reads from execution/job memory (from jobContextMapping + inputs). */
+        reads: MemoryPath[];
+        /** Paths upstream nodes in the graph are expected to have written before this node runs. */
+        expects: MemoryPath[];
+    };
+    after: {
+        /** Paths this node writes to execution memory. */
+        writes: MemoryPath[];
+        /** Paths this node writes to outputs memory. */
+        outputsMemoryWrites?: MemoryPath[];
+    };
+};
+/**
+ * Visibility into the Narrix discovery configuration of a node.
+ */
+export type NodeNarrixDiscovery = {
+    nodeId: string;
+    /** Whether narrix is wired on this node. */
+    enabled: boolean;
+    /** Framework question id this node answers (e.g. q0, q1, q6). */
+    questionId?: string;
+    /** Passthrough of `taskConfiguration.narrix.layer` (opaque; graph / pack defines labels; engine does not interpret). */
+    layer?: string;
+    /** Narrative type ids the engine focuses discovery on. */
+    narrativeTypeIds?: string[];
+    webScope: {
+        /** Whether web scoping is enabled. */
+        enabled: boolean;
+        /** When true, skips DB short-circuit and always fetches from web. */
+        forced?: boolean;
+        /** Web scope questions with stable ids and purposes. */
+        questions?: WebScopeQuestion[];
+        /** Dot-path to entity id in execution memory for web scope. */
+        entityIdPath?: string;
+        /** Dot-path to entity type in execution memory for web scope. */
+        entityTypePath?: string;
+        /** Whether CVE/vendor/product tokens are appended to the web-scope question from raw input. */
+        enrichFromRaw?: boolean;
+    };
+    /** Fixed execution-memory paths where narrix writes its output. */
+    outputPaths: {
+        signals: 'executionMemory._narrix.scoping.signals';
+        stories: 'executionMemory._narrix.scoping.stories';
+    };
+};
+/**
+ * Full inspection of a single graph node — scoping question, memory shape,
+ * and narrix discovery config.
+ */
+export type NodeInspection = {
+    nodeId: string;
+    /** "task" | "finalizer" | custom string. */
+    nodeType: string;
+    skillKey: string | undefined;
+    kind: GraphReadabilityKind | undefined;
+    scopingQuestion: NodeScopingQuestion;
+    memoryShape: NodeMemoryShape;
+    /** null when narrix is not configured on this node. */
+    narrixDiscovery: NodeNarrixDiscovery | null;
+    /** Planning-only catalog binding when present on `metadata.catalogBinding`. */
+    catalogBinding: CatalogBinding | undefined;
+    /** Planning-only single-node catalog gap when present on `metadata.catalogRequest`. */
+    catalogRequest: CatalogRequestEntry | undefined;
+};
+/**
+ * The I/O connection across a single graph edge: what the source node writes
+ * and what the destination node reads from those paths.
+ */
+export type NodeIOEdge = {
+    from: string;
+    to: string;
+    /** Paths that `from` writes to either memory lane. */
+    writtenPaths: string[];
+    /** Paths that `from` writes to execution memory. */
+    executionWrittenPaths?: string[];
+    /** Paths that `from` writes to outputs memory. */
+    outputsWrittenPaths?: string[];
+    /** Paths that `to` reads from either memory lane (intersection with writtenPaths). */
+    readPaths: string[];
+    /** Paths that `to` reads from execution memory. */
+    executionReadPaths?: string[];
+    /** Paths that `to` reads from outputs memory. */
+    outputsReadPaths?: string[];
+    when?: GraphPredicate;
+};
+/** Synthetic node id for Layer 01 (graph entry); not executed, for inspection UIs only. */
+export declare const EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID = "__exellixGraphEntry";
+/** Synthetic node id for Layer 08 (graph response); not executed, for inspection UIs only. */
+export declare const EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID = "__exellixGraphResponse";
+/**
+ * `node.metadata` flag set on nodes synthesized by {@link materializeVirtualBoundaryDiagram}.
+ * Executors and loaders must strip these nodes (or ignore them) before running the graph.
+ */
+export declare const EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY: "__exellixVirtualBoundary";
+/**
+ * Top-level property on synthetic edges from {@link materializeVirtualBoundaryDiagram}.
+ * @see EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY
+ */
+export declare const EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY: "__exellixVirtualBoundary";
+export type MaterializeVirtualBoundaryDiagramOptions = {
+    /**
+     * When `true` (default), synthetic nodes include `metadata[EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY] === true`.
+     */
+    markSyntheticNodes?: boolean;
+    /**
+     * When `true` (default), synthetic edges include `edge[EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY] === true`.
+     */
+    markSyntheticEdges?: boolean;
+};
+/**
+ * Metadata describing synthetic Layer 01 / 08 materialization; stable ids match {@link GraphVirtualIO}.
+ */
+export type MaterializedVirtualBoundaryDiagramMeta = {
+    entryNodeId: typeof EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID;
+    responseNodeId: typeof EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID;
+    firstWaveNodeIds: string[];
+    canonicalFinalizerId: string | null;
+    syntheticNodeIds: readonly [typeof EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, typeof EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID];
+    /** Synthetic nodes are never executed by exellix-graph. */
+    notExecutable: true;
+    nodeMarker: typeof EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY;
+    edgeMarker: typeof EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY;
+};
+/**
+ * Deep-copied authored `nodes` / `edges` plus synthetic boundary nodes and edges.
+ * @see stripMaterializedVirtualBoundaryDiagram
+ */
+export type MaterializedVirtualBoundaryDiagram = {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    virtualMeta: MaterializedVirtualBoundaryDiagramMeta;
+};
+export type GraphVirtualIONodeRole = 'graph-entry' | 'graph-response';
+/**
+ * A virtual boundary node mirroring platform layers 01 and 08 from `.docs/graph-io-visibility.md`.
+ * These are not authored in graph JSON and are not executed by the runtime.
+ */
+export type GraphVirtualIONode = {
+    id: string;
+    role: GraphVirtualIONodeRole;
+    /** Cross-reference to the graph I/O visibility doc layers. */
+    layer: 1 | 8;
+    description: string;
+};
+export type GraphVirtualIOEdge = {
+    from: string;
+    to: string;
+};
+/**
+ * Synthesized request/response boundaries for tooling and diagrams.
+ * Edges: entry → each first-wave DAG node; terminal finalizer/barrier → final response (when unambiguous).
+ * The final response shape itself is declared at root `graph.response`.
+ */
+export type GraphVirtualIO = {
+    nodes: GraphVirtualIONode[];
+    edges: GraphVirtualIOEdge[];
+    /** DAG nodes with no incoming authored edges (start after `execution.input.*` is seeded). */
+    firstWaveNodeIds: string[];
+    /**
+     * Single finalizer with no outgoing edges, when the graph has exactly one finalizer node.
+     * Otherwise null (invalid or ambiguous graph for canonical `finalOutput`).
+     */
+    canonicalFinalizerId: string | null;
+};
+/**
+ * Layer 01 anchor for diagramming — not present in graph JSON.
+ * @see getVirtualGraphEntryLayer
+ */
+export type VirtualGraphEntryLayer = {
+    virtualNode: GraphVirtualIONode;
+    /** Synthetic edges from the entry anchor to each first-wave real node id. */
+    outgoingEdges: GraphVirtualIOEdge[];
+    firstWaveNodeIds: string[];
+};
+/**
+ * Layer 08 anchor for diagramming — not present in graph JSON.
+ * @see getVirtualGraphResponseLayer
+ */
+export type VirtualGraphResponseLayer = {
+    virtualNode: GraphVirtualIONode;
+    /** Synthetic barrier edge from the canonical finalizer to the response anchor (empty when ambiguous). */
+    incomingEdges: GraphVirtualIOEdge[];
+    canonicalFinalizerId: string | null;
+};
+/**
+ * Full graph-level inspection: per-node inspections, execution order,
+ * I/O edges between nodes, and extracted catalog references.
+ */
+export type GraphInspection = {
+    graphId: string;
+    nodes: Record<string, NodeInspection>;
+    /** Node ids in topological execution order. */
+    executionOrder: string[];
+    edges: GraphEdge[];
+    /** Per-edge I/O visibility. */
+    ioEdges: NodeIOEdge[];
+    catalogs: GraphCatalogs;
+    /**
+     * Graph `metadata` (same shape as `variables.__graphModel` during execution).
+     */
+    graphDocumentModel: GraphDocumentMetadata;
+    /**
+     * Virtual Layer 01 / 08 nodes and edges for visualization; not part of executable `nodes` / `edges`.
+     */
+    virtualIO: GraphVirtualIO;
+};
+/**
+ * All catalog references extracted from a graph JSON, aggregated across all nodes.
+ */
+export type CatalogBindingSummary = {
+    nodeId: string;
+    catalogType: string;
+    catalogId: string;
+    version: string;
+};
+export type GraphCatalogs = {
+    /** x-scoped-data scoping map ids referenced in the graph. */
+    scopingMapIds: string[];
+    /** Narrix framework question ids referenced in the graph. */
+    narrixQuestionIds: string[];
+    /** Distinct `metadata.narrix.layer` strings on nodes (opaque metadata for tooling; not engine semantics). */
+    narrixLayers: string[];
+    /** Narrix narrative type ids referenced across all nodes. */
+    narrixNarrativeTypeIds: string[];
+    /** Local (deterministic) skill keys used in this graph. */
+    localSkillKeys: LocalSkillKey[];
+    /** AI / external skill keys used in this graph (not local skills). */
+    aiSkillKeys: string[];
+    /** Node role kinds referenced in the graph. */
+    graphReadabilityKinds: GraphReadabilityKind[];
+    /**
+     * Planning-only: `metadata.catalogBinding.catalogId` where `catalogType === 'scoped-question'`.
+     */
+    scopedQuestionCatalogIds: string[];
+    /**
+     * Planning-only: `metadata.catalogBinding.catalogId` where `catalogType === 'discovery-definition'`.
+     */
+    discoveryDefinitionCatalogIds: string[];
+    /** Per-node catalog bindings (authoring). */
+    catalogBindings: CatalogBindingSummary[];
+    /** Counts of `graph.metadata.catalogRequests` by catalog family. */
+    catalogRequestCounts: {
+        scopedQuestion: number;
+        discoveryDefinition: number;
+        other: number;
+    };
+};

package/dist/src/inspection/types.js

@@ -0,0 +1,14 @@
+/** Synthetic node id for Layer 01 (graph entry); not executed, for inspection UIs only. */
+export const EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID = '__exellixGraphEntry';
+/** Synthetic node id for Layer 08 (graph response); not executed, for inspection UIs only. */
+export const EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID = '__exellixGraphResponse';
+/**
+ * `node.metadata` flag set on nodes synthesized by {@link materializeVirtualBoundaryDiagram}.
+ * Executors and loaders must strip these nodes (or ignore them) before running the graph.
+ */
+export const EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY = '__exellixVirtualBoundary';
+/**
+ * Top-level property on synthetic edges from {@link materializeVirtualBoundaryDiagram}.
+ * @see EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY
+ */
+export const EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY = '__exellixVirtualBoundary';

package/dist/src/inspection/validateAiTasksNodeExtensions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Structural validation for task-node ai-tasks 7.1.x extensions (smartInput, inputSynthesis).
+ * Used by tooling (`validateCatalogPlanning`) and runtime (`executeNode`) with the same rules.
+ */
+import type { TaskNode } from '../types/refs.js';
+export type AiTasksNodeExtensionIssue = {
+    code: string;
+    path: string;
+    message: string;
+};
+export declare function collectAiTasksNodeExtensionIssues(node: TaskNode, nodePathPrefix: string): AiTasksNodeExtensionIssue[];
+export declare function assertAiTasksNodeExtensionsValid(node: TaskNode, nodePathPrefix: string): void;

package/dist/src/inspection/validateAiTasksNodeExtensions.js

@@ -0,0 +1,119 @@
+import { graphEngineMemoryPathValidationMessage, isAllowedGraphEngineMemoryPath, } from '../runtime/graphEngineMemoryPaths.js';
+import { normalizeSmartInputPath } from '../runtime/smartInputPaths.js';
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function validateMemoryPath(rawPath, issuePath, invalidCode) {
+    if (!isNonEmptyString(rawPath)) {
+        return [
+            {
+                code: invalidCode,
+                path: issuePath,
+                message: graphEngineMemoryPathValidationMessage(String(rawPath)),
+            },
+        ];
+    }
+    const trimmed = rawPath.trim();
+    if (!isAllowedGraphEngineMemoryPath(trimmed)) {
+        return [
+            {
+                code: invalidCode,
+                path: issuePath,
+                message: graphEngineMemoryPathValidationMessage(trimmed),
+            },
+        ];
+    }
+    return [];
+}
+export function collectAiTasksNodeExtensionIssues(node, nodePathPrefix) {
+    const issues = [];
+    const base = nodePathPrefix;
+    const smart = node.smartInput;
+    if (smart != null) {
+        if (!isPlainObject(smart)) {
+            issues.push({ code: 'SMART_INPUT_PATHS_INVALID', path: `${base}.smartInput`, message: 'smartInput must be an object' });
+        }
+        else {
+            const paths = smart.paths;
+            if (!Array.isArray(paths)) {
+                issues.push({
+                    code: 'SMART_INPUT_PATHS_INVALID',
+                    path: `${base}.smartInput.paths`,
+                    message: 'paths must be an array of strings or { path, title?, required? } objects',
+                });
+            }
+            else {
+                for (let i = 0; i < paths.length; i++) {
+                    const normalized = normalizeSmartInputPath(paths[i]);
+                    if (normalized == null) {
+                        issues.push({
+                            code: 'SMART_INPUT_PATHS_INVALID',
+                            path: `${base}.smartInput.paths[${i}]`,
+                            message: 'each entry must be a non-empty string or an object with a non-empty path string',
+                        });
+                        continue;
+                    }
+                    issues.push(...validateMemoryPath(normalized, `${base}.smartInput.paths[${i}]`, 'SMART_INPUT_PATHS_INVALID'));
+                }
+            }
+            const strict = smart.strict;
+            if (strict !== undefined && typeof strict !== 'boolean') {
+                issues.push({ code: 'SMART_INPUT_PATHS_INVALID', path: `${base}.smartInput.strict`, message: 'strict must be a boolean when present' });
+            }
+        }
+    }
+    const profile = node.taskConfiguration?.aiTaskProfile;
+    const synth = profile?.inputSynthesis;
+    if (synth != null && synth.enabled === true) {
+        const dest = synth.destination;
+        if (dest !== 'job' && dest !== 'task' && dest !== 'execution') {
+            issues.push({
+                code: 'INPUT_SYNTHESIS_DESTINATION_INVALID',
+                path: `${base}.taskConfiguration.aiTaskProfile.inputSynthesis.destination`,
+                message: 'destination must be "job", "task", or "execution" when inputSynthesis.enabled',
+            });
+        }
+        if (!isNonEmptyString(synth.outputKey)) {
+            issues.push({
+                code: 'INPUT_SYNTHESIS_OUTPUT_KEY_REQUIRED',
+                path: `${base}.taskConfiguration.aiTaskProfile.inputSynthesis.outputKey`,
+                message: 'outputKey is required when inputSynthesis.enabled',
+            });
+        }
+        const sources = synth.sources;
+        if (!Array.isArray(sources) || sources.length === 0) {
+            issues.push({
+                code: 'INPUT_SYNTHESIS_SOURCES_INVALID',
+                path: `${base}.taskConfiguration.aiTaskProfile.inputSynthesis.sources`,
+                message: 'sources must be a non-empty array of strings when inputSynthesis.enabled',
+            });
+        }
+        else {
+            for (let i = 0; i < sources.length; i++) {
+                issues.push(...validateMemoryPath(sources[i], `${base}.taskConfiguration.aiTaskProfile.inputSynthesis.sources[${i}]`, 'INPUT_SYNTHESIS_SOURCES_INVALID'));
+            }
+        }
+        const mode = synth.mode;
+        if (mode != null && mode !== 'merge' && mode !== 'replace') {
+            issues.push({
+                code: 'INPUT_SYNTHESIS_SOURCES_INVALID',
+                path: `${base}.taskConfiguration.aiTaskProfile.inputSynthesis.mode`,
+                message: 'mode must be "merge", "replace", or omitted',
+            });
+        }
+    }
+    return issues;
+}
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+export function assertAiTasksNodeExtensionsValid(node, nodePathPrefix) {
+    const issues = collectAiTasksNodeExtensionIssues(node, nodePathPrefix);
+    if (!issues.length)
+        return;
+    const first = issues[0];
+    const err = new Error(`${first.code}: ${first.message}`);
+    err.code = first.code;
+    err.issues = issues;
+    throw err;
+}

package/dist/src/inspection/validateCatalogPlanning.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Structural validation for catalog planning metadata (`metadata.catalogBinding`, `metadata.catalogRequests`).
+ * Tooling-only — the executor does not call this and does not treat failures as runtime errors.
+ */
+import type { CatalogBinding, CatalogRequestEntry, Graph } from '../types/refs.js';
+export type CatalogPlanningValidationIssue = {
+    path: string;
+    message: string;
+};
+/**
+ * Validates catalog planning shapes on `graph.metadata` and each task node's `metadata`.
+ * Does not fetch external catalogs or compare to `metadata.narrix` / scoping maps.
+ */
+export declare function validateCatalogPlanning(graph: Graph): {
+    ok: boolean;
+    errors: CatalogPlanningValidationIssue[];
+};
+/** Type guard: structural check only (same rules as validation). */
+export declare function isCatalogBinding(value: unknown): value is CatalogBinding;
+/** Type guard: structural check only (same rules as validation). */
+export declare function isCatalogRequestEntry(value: unknown): value is CatalogRequestEntry;

package/dist/src/inspection/validateCatalogPlanning.js

@@ -0,0 +1,187 @@
+/**
+ * Structural validation for catalog planning metadata (`metadata.catalogBinding`, `metadata.catalogRequests`).
+ * Tooling-only — the executor does not call this and does not treat failures as runtime errors.
+ */
+import { getGraphNodes } from './graphInspection.js';
+import { assertCanonicalGraphDocument } from '../runtime/validateCanonicalGraphDocument.js';
+import { collectAiTasksNodeExtensionIssues } from './validateAiTasksNodeExtensions.js';
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function validateCatalogBinding(path, raw, errors) {
+    if (!isPlainObject(raw)) {
+        errors.push({ path, message: 'catalogBinding must be a plain object' });
+        return;
+    }
+    const b = raw;
+    if (!isNonEmptyString(b.catalogType)) {
+        errors.push({ path: `${path}.catalogType`, message: 'required non-empty string' });
+    }
+    if (!isNonEmptyString(b.catalogId)) {
+        errors.push({ path: `${path}.catalogId`, message: 'required non-empty string' });
+    }
+    if (b.version != null && typeof b.version !== 'string') {
+        errors.push({ path: `${path}.version`, message: 'when present, must be a string' });
+    }
+    if (b.notes != null && typeof b.notes !== 'string') {
+        errors.push({ path: `${path}.notes`, message: 'when present, must be a string' });
+    }
+}
+function validateCatalogRequestEntry(path, raw, errors) {
+    if (!isPlainObject(raw)) {
+        errors.push({ path, message: 'catalog request entry must be a plain object' });
+        return;
+    }
+    const e = raw;
+    if (!isNonEmptyString(e.status)) {
+        errors.push({ path: `${path}.status`, message: 'required non-empty string' });
+    }
+    if (!isNonEmptyString(e.catalogType)) {
+        errors.push({ path: `${path}.catalogType`, message: 'required non-empty string' });
+    }
+    if (!isNonEmptyString(e.requestedId)) {
+        errors.push({ path: `${path}.requestedId`, message: 'required non-empty string' });
+    }
+    if (e.title != null && typeof e.title !== 'string') {
+        errors.push({ path: `${path}.title`, message: 'when present, must be a string' });
+    }
+    if (!isNonEmptyString(e.reason)) {
+        errors.push({ path: `${path}.reason`, message: 'required non-empty string' });
+    }
+    if (e.requestedByNodeId != null && typeof e.requestedByNodeId !== 'string') {
+        errors.push({ path: `${path}.requestedByNodeId`, message: 'when present, must be a string' });
+    }
+    const ct = e.catalogType;
+    if (ct === 'scoped-question') {
+        if (!isNonEmptyString(e.title)) {
+            errors.push({ path: `${path}.title`, message: 'required non-empty string for catalogType scoped-question' });
+        }
+        if (!isNonEmptyString(e.asks)) {
+            errors.push({ path: `${path}.asks`, message: 'required non-empty string for catalogType scoped-question' });
+        }
+        if (!isNonEmptyString(e.entityType)) {
+            errors.push({ path: `${path}.entityType`, message: 'required non-empty string for catalogType scoped-question' });
+        }
+        if (e.proposedScopingMapId != null && typeof e.proposedScopingMapId !== 'string') {
+            errors.push({ path: `${path}.proposedScopingMapId`, message: 'when present, must be a string' });
+        }
+        if (e.planningNotes != null && typeof e.planningNotes !== 'string') {
+            errors.push({ path: `${path}.planningNotes`, message: 'when present, must be a string' });
+        }
+        return;
+    }
+    if (ct === 'discovery-definition') {
+        if (e.purpose != null && typeof e.purpose !== 'string') {
+            errors.push({ path: `${path}.purpose`, message: 'when present, must be a string' });
+        }
+        if (e.datasetId != null && typeof e.datasetId !== 'string') {
+            errors.push({ path: `${path}.datasetId`, message: 'when present, must be a string' });
+        }
+        if (e.layer != null && typeof e.layer !== 'string') {
+            errors.push({ path: `${path}.layer`, message: 'when present, must be a string' });
+        }
+        if (e.narrativeTypeIds != null) {
+            if (!Array.isArray(e.narrativeTypeIds)) {
+                errors.push({ path: `${path}.narrativeTypeIds`, message: 'when present, must be an array of strings' });
+            }
+            else {
+                for (let i = 0; i < e.narrativeTypeIds.length; i++) {
+                    if (typeof e.narrativeTypeIds[i] !== 'string') {
+                        errors.push({ path: `${path}.narrativeTypeIds[${i}]`, message: 'each narrativeTypeId must be a string' });
+                    }
+                }
+            }
+        }
+        if (e.enableWebScope != null && typeof e.enableWebScope !== 'boolean') {
+            errors.push({ path: `${path}.enableWebScope`, message: 'when present, must be a boolean' });
+        }
+        if (e.discoveryNotes != null && typeof e.discoveryNotes !== 'string') {
+            errors.push({ path: `${path}.discoveryNotes`, message: 'when present, must be a string' });
+        }
+        if (e.expectedSemanticOutputs != null) {
+            if (!Array.isArray(e.expectedSemanticOutputs)) {
+                errors.push({ path: `${path}.expectedSemanticOutputs`, message: 'when present, must be an array of strings' });
+            }
+            else {
+                for (let i = 0; i < e.expectedSemanticOutputs.length; i++) {
+                    if (typeof e.expectedSemanticOutputs[i] !== 'string') {
+                        errors.push({ path: `${path}.expectedSemanticOutputs[${i}]`, message: 'each entry must be a string' });
+                    }
+                }
+            }
+        }
+        if (e.compatibleTaskTypes != null) {
+            if (!Array.isArray(e.compatibleTaskTypes)) {
+                errors.push({ path: `${path}.compatibleTaskTypes`, message: 'when present, must be an array of strings' });
+            }
+            else {
+                for (let i = 0; i < e.compatibleTaskTypes.length; i++) {
+                    if (typeof e.compatibleTaskTypes[i] !== 'string') {
+                        errors.push({ path: `${path}.compatibleTaskTypes[${i}]`, message: 'each entry must be a string' });
+                    }
+                }
+            }
+        }
+        return;
+    }
+    errors.push({
+        path: `${path}.catalogType`,
+        message: `unsupported catalogType "${ct}" (expected "scoped-question" or "discovery-definition")`,
+    });
+}
+/**
+ * Validates catalog planning shapes on `graph.metadata` and each task node's `metadata`.
+ * Does not fetch external catalogs or compare to `metadata.narrix` / scoping maps.
+ */
+export function validateCatalogPlanning(graph) {
+    assertCanonicalGraphDocument(graph, { graphId: graph?.id });
+    const errors = [];
+    const gm = graph.metadata;
+    if (gm != null && typeof gm === 'object' && !Array.isArray(gm)) {
+        const cr = gm.catalogRequests;
+        if (cr != null) {
+            if (!Array.isArray(cr)) {
+                errors.push({ path: 'metadata.catalogRequests', message: 'must be an array when present' });
+            }
+            else {
+                cr.forEach((entry, i) => {
+                    validateCatalogRequestEntry(`metadata.catalogRequests[${i}]`, entry, errors);
+                });
+            }
+        }
+    }
+    const nodes = getGraphNodes(graph);
+    for (const node of nodes) {
+        if (node.type === 'finalizer')
+            continue;
+        const tn = node;
+        const meta = tn.metadata;
+        if (meta != null) {
+            if (meta.catalogBinding != null) {
+                validateCatalogBinding(`nodes[${tn.id}].metadata.catalogBinding`, meta.catalogBinding, errors);
+            }
+            if (meta.catalogRequest != null) {
+                validateCatalogRequestEntry(`nodes[${tn.id}].metadata.catalogRequest`, meta.catalogRequest, errors);
+            }
+        }
+        for (const ext of collectAiTasksNodeExtensionIssues(tn, `nodes[${tn.id}]`)) {
+            errors.push({ path: ext.path, message: `${ext.code}: ${ext.message}` });
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+/** Type guard: structural check only (same rules as validation). */
+export function isCatalogBinding(value) {
+    const e = [];
+    validateCatalogBinding('', value, e);
+    return e.length === 0;
+}
+/** Type guard: structural check only (same rules as validation). */
+export function isCatalogRequestEntry(value) {
+    const e = [];
+    validateCatalogRequestEntry('', value, e);
+    return e.length === 0;
+}