@astra-spec/sdk 0.0.1

package/dist/validation/semantic.js

@@ -0,0 +1,751 @@
+// Semantic validation: cross-references, constraint resolution, and
+// `from:`-path direction rules. Operates on parsed dict-like data
+// (matching the Python validator) so it doesn't depend on type narrowing.
+import { collectNodeDecisions, getInputIds, getOutputIds, isConditionMet, loadYaml, resolveAnalysisTree, } from "../helpers.js";
+export class SemanticError {
+    code;
+    message;
+    path;
+    constructor(code, message, path) {
+        this.code = code;
+        this.message = message;
+        this.path = path;
+    }
+    toString() {
+        return this.path ? `[${this.code}] ${this.path}: ${this.message}` : `[${this.code}] ${this.message}`;
+    }
+}
+const ID_PATTERN = /^[a-z][a-z0-9_]*$/;
+function asDict(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+/** Parse a `../scope.id` style path. Returns null on malformed input. */
+function parseFromPath(ref) {
+    let up = 0;
+    let rest = ref;
+    while (rest.startsWith("../")) {
+        up += 1;
+        rest = rest.slice(3);
+    }
+    if (!rest || rest.startsWith(".") || rest.endsWith("."))
+        return null;
+    const segments = rest.split(".");
+    for (const seg of segments)
+        if (!ID_PATTERN.test(seg))
+            return null;
+    return { up, segments };
+}
+function checkPathExclusivity(data, errors, pathPrefix = "") {
+    const subAnalyses = asDict(data.analyses) ?? {};
+    for (const [subId, raw] of Object.entries(subAnalyses)) {
+        const sub = asDict(raw);
+        if (!sub)
+            continue;
+        const fullPath = pathPrefix ? `${pathPrefix}.analyses.${subId}` : `analyses.${subId}`;
+        if (sub.path) {
+            const extra = Object.keys(sub).filter((k) => k !== "path").sort();
+            if (extra.length) {
+                errors.push(new SemanticError("PATH_FIELD_CONFLICT", `Sub-analysis '${subId}' has 'path:' alongside fields ${JSON.stringify(extra)}; ` +
+                    `content must come from the referenced file. Move these fields into the sub's astra.yaml.`, fullPath));
+            }
+        }
+        else {
+            checkPathExclusivity(sub, errors, fullPath);
+        }
+    }
+}
+/** Validate an Analysis dict semantically. Returns the list of errors. */
+export function validateAnalysis(data, options = {}) {
+    const errors = [];
+    let working = data;
+    // Run before any external `path:` resolution merges over content fields.
+    checkPathExclusivity(working, errors);
+    if (options.basePath) {
+        working = resolveAnalysisTree(working, options.basePath);
+    }
+    for (const field of ["version", "name", "inputs", "outputs"]) {
+        if (working[field] == null) {
+            errors.push(new SemanticError("MISSING_ROOT_FIELD", `Root analysis is missing required field '${field}'`, field));
+        }
+    }
+    const inputs = asArray(working.inputs);
+    const outputs = asArray(working.outputs);
+    const priorInsights = asDict(working.prior_insights) ?? {};
+    const inputIds = new Set();
+    for (const inp of inputs) {
+        const id = inp?.id;
+        if (id && inputIds.has(id)) {
+            errors.push(new SemanticError("DUPLICATE_INPUT", `Duplicate input ID: ${id}`, `inputs.${id}`));
+        }
+        if (id)
+            inputIds.add(id);
+    }
+    const outputIds = new Set();
+    for (const out of outputs) {
+        const id = out?.id;
+        if (id && outputIds.has(id)) {
+            errors.push(new SemanticError("DUPLICATE_OUTPUT", `Duplicate output ID: ${id}`, `outputs.${id}`));
+        }
+        if (id)
+            outputIds.add(id);
+    }
+    const rootDecisions = collectNodeDecisions(working);
+    errors.push(..._validateDecisions(rootDecisions, priorInsights, ""));
+    errors.push(..._validateInsightArtifacts(asDict(working.prior_insights) ?? {}, outputIds, "", "prior_insights"));
+    errors.push(..._validateInsightArtifacts(asDict(working.findings) ?? {}, outputIds, "", "findings"));
+    const subAnalyses = asDict(working.analyses) ?? {};
+    const subOutputIds = new Set();
+    for (const [analysisId, raw] of Object.entries(subAnalyses)) {
+        const sub = asDict(raw);
+        if (!sub)
+            continue;
+        for (const out of asArray(sub.outputs)) {
+            const oid = out?.id;
+            if (oid)
+                subOutputIds.add(`${analysisId}.${oid}`);
+        }
+    }
+    errors.push(..._validateOutputsFrom(outputs, working, ""));
+    errors.push(..._validateOutputDependencies(outputs, {
+        analysisInputIds: inputIds,
+        decisionsInScope: rootDecisions,
+        pathPrefix: "",
+        extraValidIds: subOutputIds,
+    }));
+    errors.push(..._validateOutputWhen(outputs, rootDecisions, ""));
+    for (const [analysisId, raw] of Object.entries(subAnalyses)) {
+        const sub = asDict(raw);
+        if (!sub)
+            continue;
+        errors.push(..._validateAnalysisNode(analysisId, sub, priorInsights, [working], "analyses"));
+    }
+    return errors;
+}
+function _validateAnalysisNode(nodeId, node, priorInsights, ancestorChain, pathPrefix) {
+    const errors = [];
+    const nodePath = `${pathPrefix}.${nodeId}`;
+    // Path-only stub (not yet resolved): skip deep checks.
+    if (node.path && !node.inputs && !node.outputs)
+        return errors;
+    for (const field of ["inputs", "outputs"]) {
+        if (!node[field]) {
+            errors.push(new SemanticError("MISSING_SUB_FIELD", `Sub-analysis '${nodeId}' is missing required field: ${field}`, nodePath));
+        }
+    }
+    // Decision `from:` checks.
+    const allDecisions = (asDict(node.decisions) ?? {});
+    for (const [decisionId, decision] of Object.entries(allDecisions)) {
+        const ref = decision?.from;
+        if (ref) {
+            errors.push(..._validateDecisionFrom(ref, ancestorChain, `${nodePath}.decisions.${decisionId}`));
+        }
+    }
+    // Inputs.
+    const nodeInputs = asArray(node.inputs);
+    const nodeInputIds = new Set();
+    for (const inp of nodeInputs) {
+        const id = inp?.id;
+        if (id)
+            nodeInputIds.add(id);
+        const ref = inp?.from;
+        if (ref)
+            errors.push(..._validateInputFrom(ref, ancestorChain, nodeId, nodePath));
+    }
+    // Output IDs unique.
+    const nodeOutputIds = new Set();
+    for (const out of asArray(node.outputs)) {
+        const id = out?.id;
+        if (id && nodeOutputIds.has(id)) {
+            errors.push(new SemanticError("DUPLICATE_OUTPUT", `Duplicate output ID in analysis node: ${id}`, `${nodePath}.outputs.${id}`));
+        }
+        if (id)
+            nodeOutputIds.add(id);
+    }
+    const nodeOutputs = asArray(node.outputs);
+    errors.push(..._validateOutputsFrom(nodeOutputs, node, nodePath));
+    const nodeDecisions = collectNodeDecisions(node);
+    // Build the constraint scope: locally-defined decisions plus any `from:`
+    // alias resolved one ancestor up (matches the Python `constraint_scope`).
+    const constraintScope = { ...nodeDecisions };
+    for (const [decisionId, decision] of Object.entries(allDecisions)) {
+        const ref = decision?.from;
+        if (!ref)
+            continue;
+        const parsed = parseFromPath(ref);
+        if (!parsed || parsed.up <= 0 || parsed.segments.length !== 1)
+            continue;
+        const targetScope = _resolveAncestorScope(ancestorChain, parsed.up);
+        if (!targetScope)
+            continue;
+        const targetDecisions = (asDict(targetScope.decisions) ?? {});
+        const seg = parsed.segments[0];
+        if (seg in targetDecisions) {
+            const tgt = targetDecisions[seg];
+            if (tgt)
+                constraintScope[decisionId] = tgt;
+        }
+    }
+    errors.push(..._validateDecisions(nodeDecisions, priorInsights, nodePath, constraintScope));
+    errors.push(..._validateInsightArtifacts(asDict(node.prior_insights) ?? {}, nodeOutputIds, nodePath, "prior_insights"));
+    errors.push(..._validateInsightArtifacts(asDict(node.findings) ?? {}, nodeOutputIds, nodePath, "findings"));
+    const subAnalyses = asDict(node.analyses) ?? {};
+    const subOutputIds = new Set();
+    for (const [subId, raw] of Object.entries(subAnalyses)) {
+        const sub = asDict(raw);
+        if (!sub)
+            continue;
+        for (const out of asArray(sub.outputs)) {
+            const oid = out?.id;
+            if (oid)
+                subOutputIds.add(`${subId}.${oid}`);
+        }
+    }
+    errors.push(..._validateOutputDependencies(nodeOutputs, {
+        analysisInputIds: nodeInputIds,
+        decisionsInScope: constraintScope,
+        pathPrefix: nodePath,
+        extraValidIds: subOutputIds,
+    }));
+    errors.push(..._validateOutputWhen(nodeOutputs, constraintScope, nodePath));
+    for (const [subId, raw] of Object.entries(subAnalyses)) {
+        const sub = asDict(raw);
+        if (!sub)
+            continue;
+        errors.push(..._validateAnalysisNode(subId, sub, priorInsights, [...ancestorChain, node], `${nodePath}.analyses`));
+    }
+    return errors;
+}
+function _validateOutputsFrom(outputs, currentScope, pathPrefix) {
+    const errors = [];
+    const prefix = pathPrefix ? `${pathPrefix}.outputs` : "outputs";
+    for (const out of outputs) {
+        const ref = out?.from;
+        const id = out?.id;
+        if (!ref || !id)
+            continue;
+        errors.push(..._validateOutputFrom(ref, currentScope, `${prefix}.${id}`));
+    }
+    return errors;
+}
+function _validateInsightArtifacts(insights, outputIds, pathPrefix, section) {
+    const errors = [];
+    if (!insights || Object.keys(insights).length === 0)
+        return errors;
+    const prefix = pathPrefix ? `${pathPrefix}.${section}` : section;
+    for (const [insightId, raw] of Object.entries(insights)) {
+        const insight = asDict(raw);
+        if (!insight)
+            continue;
+        const insightPath = `${prefix}.${insightId}`;
+        const evidenceList = asArray(insight.evidence);
+        evidenceList.forEach((ev, i) => {
+            const artifactRef = ev?.artifact;
+            if (artifactRef !== undefined && !outputIds.has(artifactRef)) {
+                errors.push(new SemanticError("INVALID_ARTIFACT_REF", `Evidence artifact '${artifactRef}' not found in declared outputs`, `${insightPath}.evidence[${i}].artifact`));
+            }
+        });
+    }
+    return errors;
+}
+function _validateDecisions(decisions, priorInsights, pathPrefix, constraintScope) {
+    const errors = [];
+    const scope = constraintScope ?? decisions;
+    const decisionsPrefix = pathPrefix ? `${pathPrefix}.decisions` : "decisions";
+    for (const [decisionId, decision] of Object.entries(decisions)) {
+        const decisionPath = `${decisionsPrefix}.${decisionId}`;
+        const options = (asDict(decision.options) ?? {});
+        const defaultOpt = decision.default;
+        if (defaultOpt != null && !(defaultOpt in options)) {
+            errors.push(new SemanticError("INVALID_DEFAULT", `Default option '${defaultOpt}' not found in options`, decisionPath));
+        }
+        const when = decision.when;
+        if (when) {
+            const conds = typeof when === "string" ? [when] : when;
+            for (const cond of conds) {
+                const ref = cond.startsWith("~") ? cond.slice(1) : cond;
+                const parts = ref.split(".");
+                if (parts.length !== 2) {
+                    errors.push(new SemanticError("INVALID_WHEN_REF", `Decision 'when' condition '${cond}' has invalid format`, decisionPath));
+                    continue;
+                }
+                const [whenDecisionId, whenOptionId] = parts;
+                if (!(whenDecisionId in decisions) && !(whenDecisionId in scope)) {
+                    errors.push(new SemanticError("INVALID_WHEN_REF", `'when' references non-existent decision '${whenDecisionId}'`, decisionPath));
+                }
+                else {
+                    const refDecision = decisions[whenDecisionId] ?? scope[whenDecisionId];
+                    const refOptions = refDecision ? (asDict(refDecision.options) ?? {}) : {};
+                    if (refDecision && !(whenOptionId in refOptions)) {
+                        errors.push(new SemanticError("INVALID_WHEN_REF", `'when' references non-existent option '${whenOptionId}' in decision '${whenDecisionId}'`, decisionPath));
+                    }
+                }
+                if (whenDecisionId === decisionId) {
+                    errors.push(new SemanticError("INVALID_WHEN_REF", "'when' cannot reference own decision", decisionPath));
+                }
+            }
+        }
+        for (const [optionId, optionRaw] of Object.entries(options)) {
+            const option = optionRaw;
+            const optionPath = `${decisionPath}.options.${optionId}`;
+            const insightRefs = asArray(option.insights);
+            insightRefs.forEach((insightRef, i) => {
+                if (!(insightRef in priorInsights)) {
+                    errors.push(new SemanticError("INVALID_INSIGHT_REF", `Option insight '${insightRef}' not found in prior_insights`, `${optionPath}.insights[${i}]`));
+                }
+            });
+            for (const ref of asArray(option.incompatible_with)) {
+                errors.push(..._validateConstraintRef(ref, scope, optionPath));
+            }
+            for (const ref of asArray(option.requires)) {
+                errors.push(..._validateConstraintRef(ref, scope, optionPath));
+            }
+            const isExcluded = option.excluded === true;
+            const excludedReason = option.excluded_reason;
+            if (isExcluded && !excludedReason) {
+                errors.push(new SemanticError("MISSING_EXCLUDED_REASON", `Excluded option '${optionId}' must have an 'excluded_reason'`, optionPath));
+            }
+            if (excludedReason && !isExcluded) {
+                errors.push(new SemanticError("ORPHAN_EXCLUDED_REASON", `Option '${optionId}' has 'excluded_reason' but is not marked excluded`, optionPath));
+            }
+        }
+        if (defaultOpt != null && defaultOpt in options) {
+            const defaultOption = options[defaultOpt];
+            if (defaultOption.excluded === true) {
+                errors.push(new SemanticError("EXCLUDED_DEFAULT", `Default option '${defaultOpt}' is marked as excluded`, decisionPath));
+            }
+        }
+    }
+    return errors;
+}
+function _validateOutputWhen(outputs, decisions, pathPrefix) {
+    const errors = [];
+    const outputsPrefix = pathPrefix ? `${pathPrefix}.outputs` : "outputs";
+    for (const out of outputs) {
+        const id = out?.id;
+        if (!id)
+            continue;
+        const when = out.when;
+        if (!when)
+            continue;
+        const conds = typeof when === "string" ? [when] : when;
+        const outputPath = `${outputsPrefix}.${id}`;
+        for (const cond of conds) {
+            const ref = cond.startsWith("~") ? cond.slice(1) : cond;
+            const parts = ref.split(".");
+            if (parts.length !== 2) {
+                errors.push(new SemanticError("INVALID_WHEN_REF", `Output 'when' condition '${cond}' has invalid format`, outputPath));
+                continue;
+            }
+            const [decisionId, optionId] = parts;
+            if (!(decisionId in decisions)) {
+                errors.push(new SemanticError("INVALID_WHEN_REF", `Output 'when' references non-existent decision '${decisionId}'`, outputPath));
+            }
+            else {
+                const refDecision = decisions[decisionId];
+                const refOptions = (asDict(refDecision.options) ?? {});
+                if (!(optionId in refOptions)) {
+                    errors.push(new SemanticError("INVALID_WHEN_REF", `Output 'when' references non-existent option '${optionId}' in decision '${decisionId}'`, outputPath));
+                }
+            }
+        }
+    }
+    return errors;
+}
+function _validateOutputDependencies(outputs, args) {
+    const errors = [];
+    const { analysisInputIds, decisionsInScope, pathPrefix, extraValidIds } = args;
+    const outputsPrefix = pathPrefix ? `${pathPrefix}.outputs` : "outputs";
+    const outputIds = new Set();
+    for (const out of outputs)
+        if (out?.id)
+            outputIds.add(out.id);
+    const siblingOrExtra = new Set([...outputIds, ...(extraValidIds ?? new Set())]);
+    const validInputIds = new Set([...analysisInputIds, ...siblingOrExtra]);
+    const depGraph = {};
+    for (const out of outputs) {
+        const id = out?.id;
+        if (!id)
+            continue;
+        const outPath = `${outputsPrefix}.${id}`;
+        if (out.from) {
+            depGraph[id] = [];
+            continue;
+        }
+        const declaredInputs = asArray(out.inputs);
+        depGraph[id] = declaredInputs.filter((i) => siblingOrExtra.has(i));
+        for (const inpId of declaredInputs) {
+            if (!validInputIds.has(inpId)) {
+                errors.push(new SemanticError("INVALID_OUTPUT_INPUT", `Output input '${inpId}' is not a declared analysis input or sibling output`, `${outPath}.inputs`));
+            }
+        }
+        const declaredDecisions = asArray(out.decisions);
+        for (const decId of declaredDecisions) {
+            if (!(decId in decisionsInScope)) {
+                errors.push(new SemanticError("INVALID_OUTPUT_DECISION", `Output decision '${decId}' is not a decision in scope`, `${outPath}.decisions`));
+            }
+        }
+        const recipe = asDict(out.recipe);
+        const command = recipe?.command;
+        if (typeof command === "string" && command) {
+            errors.push(..._validateCommandTemplate(command, new Set(declaredInputs), new Set(declaredDecisions), `${outPath}.recipe.command`));
+        }
+    }
+    const cycle = _detectOutputCycle(depGraph);
+    if (cycle) {
+        errors.push(new SemanticError("OUTPUT_CYCLE", `Dependency cycle detected: ${cycle.join(" -> ")}`, outputsPrefix));
+    }
+    return errors;
+}
+/** Iterate Python `string.Formatter.parse()`-style fields out of a
+ *  format string. Yields `{ field, formatSpec, conversion }` for each
+ *  placeholder; `{{` and `}}` are emitted as literal braces (skipped). */
+function* iterTemplateFields(command) {
+    let i = 0;
+    while (i < command.length) {
+        const ch = command[i];
+        if (ch === "{") {
+            if (command[i + 1] === "{") {
+                // literal {
+                i += 2;
+                continue;
+            }
+            // find matching } (no nested braces inside placeholders for our purposes)
+            const end = command.indexOf("}", i + 1);
+            if (end < 0) {
+                throw new Error("Single '{' encountered in format string");
+            }
+            const body = command.slice(i + 1, end);
+            // Conversion: !s, !r, !a — single char after `!`.
+            let field = body;
+            let conversion = null;
+            let formatSpec = "";
+            const colon = field.indexOf(":");
+            if (colon >= 0) {
+                formatSpec = field.slice(colon + 1);
+                field = field.slice(0, colon);
+            }
+            const bang = field.indexOf("!");
+            if (bang >= 0) {
+                conversion = field.slice(bang + 1);
+                field = field.slice(0, bang);
+            }
+            yield { field, formatSpec, conversion };
+            i = end + 1;
+        }
+        else if (ch === "}") {
+            if (command[i + 1] === "}") {
+                i += 2;
+                continue;
+            }
+            throw new Error("Single '}' encountered in format string");
+        }
+        else {
+            i++;
+        }
+    }
+}
+function _validateCommandTemplate(command, declaredInputs, declaredDecisions, path) {
+    const errors = [];
+    let fields;
+    try {
+        fields = [...iterTemplateFields(command)];
+    }
+    catch (e) {
+        return [new SemanticError("INVALID_COMMAND_TEMPLATE", e.message, path)];
+    }
+    const declared = {
+        inputs: declaredInputs,
+        decisions: declaredDecisions,
+    };
+    for (const { field, formatSpec, conversion } of fields) {
+        if (field == null)
+            continue;
+        if (field === "" || formatSpec || conversion) {
+            errors.push(new SemanticError("INVALID_COMMAND_TEMPLATE", `Invalid command placeholder '{${field}}'`, path));
+            continue;
+        }
+        if (field === "output" || field === "inputs")
+            continue;
+        const dot = field.indexOf(".");
+        if (dot >= 0) {
+            const head = field.slice(0, dot);
+            const tail = field.slice(dot + 1);
+            if (!tail.includes(".") && head in declared) {
+                if (!declared[head].has(tail)) {
+                    const singular = head === "inputs" ? "input" : "decision";
+                    errors.push(new SemanticError("UNDECLARED_TEMPLATE_REF", `Command placeholder '{${field}}' references undeclared ${singular} '${tail}' (add it to Output.${head})`, path));
+                }
+                continue;
+            }
+        }
+        errors.push(new SemanticError("INVALID_COMMAND_TEMPLATE", `Unknown command placeholder '{${field}}' (use {inputs}, {inputs.<id>}, {decisions.<id>}, or {output})`, path));
+    }
+    return errors;
+}
+function _detectOutputCycle(depGraph) {
+    const White = 0;
+    const Gray = 1;
+    const Black = 2;
+    const color = {};
+    for (const id of Object.keys(depGraph))
+        color[id] = White;
+    const path = [];
+    function dfs(node) {
+        color[node] = Gray;
+        path.push(node);
+        for (const dep of depGraph[node] ?? []) {
+            if (!(dep in color))
+                continue;
+            if (color[dep] === Gray) {
+                const start = path.indexOf(dep);
+                return [...path.slice(start), dep];
+            }
+            if (color[dep] === White) {
+                const result = dfs(dep);
+                if (result)
+                    return result;
+            }
+        }
+        path.pop();
+        color[node] = Black;
+        return null;
+    }
+    for (const id of Object.keys(depGraph)) {
+        if (color[id] === White) {
+            const result = dfs(id);
+            if (result)
+                return result;
+        }
+    }
+    return null;
+}
+function _resolveAncestorScope(chain, up) {
+    if (up <= 0 || up > chain.length)
+        return null;
+    return chain[chain.length - up] ?? null;
+}
+function _validateDecisionFrom(ref, ancestorChain, decisionPath) {
+    const mkErr = (m) => [new SemanticError("INVALID_DECISION_FROM", m, decisionPath)];
+    const parsed = parseFromPath(ref);
+    if (!parsed)
+        return mkErr(`Decision.from '${ref}' has invalid path syntax`);
+    if (parsed.up === 0)
+        return mkErr(`Decision.from '${ref}' must start with '../' to reference an ancestor decision`);
+    if (parsed.segments.length !== 1)
+        return mkErr(`Decision.from '${ref}' must reference a single decision id ` +
+            `(no descent into sibling/child scopes allowed; lift the decision to a common ancestor instead)`);
+    const target = _resolveAncestorScope(ancestorChain, parsed.up);
+    if (!target)
+        return mkErr(`Decision.from '${ref}' escapes ${parsed.up} level(s) but only ${ancestorChain.length} ancestor scope(s) available`);
+    const targetDecisions = (asDict(target.decisions) ?? {});
+    if (!(parsed.segments[0] in targetDecisions))
+        return mkErr(`Decision.from '${ref}' points to non-existent ancestor decision '${parsed.segments[0]}'`);
+    return [];
+}
+function _validateInputFrom(ref, ancestorChain, currentNodeId, nodePath) {
+    const mkErr = (m) => [new SemanticError("INVALID_FROM", m, nodePath)];
+    const parsed = parseFromPath(ref);
+    if (!parsed)
+        return mkErr(`Input.from '${ref}' has invalid path syntax`);
+    if (parsed.up === 0)
+        return mkErr(`Input.from '${ref}' must start with '../' to escape upward ` +
+            `(downward references aren't allowed on Inputs; consume sub outputs via Output re-export)`);
+    const target = _resolveAncestorScope(ancestorChain, parsed.up);
+    if (!target)
+        return mkErr(`Input.from '${ref}' escapes ${parsed.up} level(s) but only ${ancestorChain.length} ancestor scope(s) available`);
+    if (parsed.segments.length === 1) {
+        if (!getInputIds(target).has(parsed.segments[0]))
+            return mkErr(`Input.from '${ref}' points to non-existent ancestor input '${parsed.segments[0]}'`);
+        return [];
+    }
+    let current = target;
+    const heads = parsed.segments.slice(0, -1);
+    for (let i = 0; i < heads.length; i++) {
+        const seg = heads[i];
+        const subAnalyses = asDict(current.analyses) ?? {};
+        if (!(seg in subAnalyses))
+            return mkErr(`Input.from '${ref}': sub-analysis '${seg}' not found at depth ${i} in target scope`);
+        if (parsed.up === 1 && i === 0 && seg === currentNodeId)
+            return mkErr(`Input.from '${ref}' cannot reference own outputs`);
+        current = subAnalyses[seg];
+    }
+    const tail = parsed.segments[parsed.segments.length - 1];
+    if (!getOutputIds(current).has(tail))
+        return mkErr(`Input.from '${ref}': output '${tail}' not found in target sub-analysis`);
+    return [];
+}
+function _validateOutputFrom(ref, currentScope, outputPath) {
+    const mkErr = (m) => [
+        new SemanticError("INVALID_OUTPUT_FROM", m, outputPath),
+    ];
+    const parsed = parseFromPath(ref);
+    if (!parsed)
+        return mkErr(`Output.from '${ref}' has invalid path syntax`);
+    if (parsed.up !== 0)
+        return mkErr(`Output.from '${ref}' must descend into a sub-analysis ` +
+            `(upward references aren't allowed; outputs flow up via per-layer re-export)`);
+    if (parsed.segments.length < 2)
+        return mkErr(`Output.from '${ref}' must take the form 'child.out_id' ` +
+            `(at least one descent step into a named sub-analysis)`);
+    let current = currentScope;
+    const heads = parsed.segments.slice(0, -1);
+    for (let i = 0; i < heads.length; i++) {
+        const seg = heads[i];
+        const subAnalyses = asDict(current.analyses) ?? {};
+        if (!(seg in subAnalyses))
+            return mkErr(`Output.from '${ref}': sub-analysis '${seg}' not found at depth ${i}`);
+        current = subAnalyses[seg];
+    }
+    const tail = parsed.segments[parsed.segments.length - 1];
+    if (!getOutputIds(current).has(tail))
+        return mkErr(`Output.from '${ref}': output '${tail}' not found in target sub-analysis`);
+    return [];
+}
+function _validateConstraintRef(ref, decisions, optionPath) {
+    const parts = ref.split(".");
+    if (parts.length !== 2) {
+        return [
+            new SemanticError("INVALID_CONSTRAINT_FORMAT", `Constraint '${ref}' should be in 'decision.option' format`, optionPath),
+        ];
+    }
+    const [decisionId, optionId] = parts;
+    if (!(decisionId in decisions)) {
+        return [
+            new SemanticError("INVALID_CONSTRAINT_REF", `Constraint ref '${ref}' points to non-existent decision '${decisionId}'`, optionPath),
+        ];
+    }
+    const options = (asDict(decisions[decisionId].options) ?? {});
+    if (!(optionId in options)) {
+        return [
+            new SemanticError("INVALID_CONSTRAINT_REF", `Constraint ref '${ref}' points to non-existent option '${optionId}'`, optionPath),
+        ];
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Universe validation
+// ---------------------------------------------------------------------------
+export function validateUniverse(universeData, analysisData) {
+    return _validateUniverseNode(universeData, analysisData, "", []);
+}
+function _validateUniverseNode(universeNode, analysisNode, pathPrefix, ancestorUniverseChain) {
+    const errors = [];
+    const analysisDecisions = collectNodeDecisions(analysisNode);
+    const allAnalysisDecisions = (asDict(analysisNode.decisions) ?? {});
+    const universeDecisions = (asDict(universeNode.decisions) ?? {});
+    const decisionsPath = pathPrefix ? `${pathPrefix}.decisions` : "decisions";
+    const fromDecisionIds = new Set();
+    for (const [id, decision] of Object.entries(allAnalysisDecisions)) {
+        if (decision && decision.from)
+            fromDecisionIds.add(id);
+    }
+    for (const [decisionId, optionId] of Object.entries(universeDecisions)) {
+        if (fromDecisionIds.has(decisionId)) {
+            errors.push(new SemanticError("FROM_DECISION_IN_UNIVERSE", `Universe should not set decision '${decisionId}' (it uses 'from' to reference a parent decision)`, `${decisionsPath}.${decisionId}`));
+            continue;
+        }
+        if (!(decisionId in analysisDecisions)) {
+            errors.push(new SemanticError("UNKNOWN_DECISION", `Universe references unknown decision '${decisionId}'`, `${decisionsPath}.${decisionId}`));
+            continue;
+        }
+        const decision = analysisDecisions[decisionId];
+        const options = (asDict(decision.options) ?? {});
+        if (!(optionId in options)) {
+            errors.push(new SemanticError("UNKNOWN_OPTION", `Universe selects unknown option '${optionId}' for decision '${decisionId}'`, `${decisionsPath}.${decisionId}`));
+        }
+        else if (options[optionId].excluded === true) {
+            errors.push(new SemanticError("EXCLUDED_OPTION_SELECTED", `Universe selects excluded option '${optionId}' for decision '${decisionId}'`, `${decisionsPath}.${decisionId}`));
+        }
+    }
+    // Merge universe selections from this and all ancestor levels for `when:` evaluation.
+    const allUniverseDecisions = {};
+    for (const ancestor of ancestorUniverseChain)
+        Object.assign(allUniverseDecisions, ancestor);
+    Object.assign(allUniverseDecisions, universeDecisions);
+    for (const decisionId of Object.keys(analysisDecisions)) {
+        if (fromDecisionIds.has(decisionId))
+            continue;
+        const decision = analysisDecisions[decisionId];
+        const when = decision.when;
+        if (when) {
+            if (!isConditionMet(when, allUniverseDecisions)) {
+                if (decisionId in universeDecisions) {
+                    errors.push(new SemanticError("INACTIVE_DECISION", `Universe specifies decision '${decisionId}' but its condition '${JSON.stringify(when)}' is not met`, `${decisionsPath}.${decisionId}`));
+                }
+                continue;
+            }
+        }
+        if (!(decisionId in universeDecisions)) {
+            errors.push(new SemanticError("MISSING_DECISION", `Universe missing decision '${decisionId}'`, `${decisionsPath}.${decisionId}`));
+        }
+    }
+    // Build effective selections (resolve `from:` from the matching ancestor universe).
+    const effective = { ...universeDecisions };
+    for (const decisionId of fromDecisionIds) {
+        const ref = allAnalysisDecisions[decisionId].from ?? "";
+        const parsed = parseFromPath(ref);
+        if (!parsed || parsed.up <= 0 || parsed.segments.length !== 1)
+            continue;
+        if (parsed.up > ancestorUniverseChain.length)
+            continue;
+        const targetUniverse = ancestorUniverseChain[ancestorUniverseChain.length - parsed.up];
+        const tgt = parsed.segments[0];
+        if (tgt in targetUniverse)
+            effective[decisionId] = targetUniverse[tgt];
+    }
+    errors.push(..._validateNodeUniverseConstraints(effective, analysisDecisions, decisionsPath));
+    const analysisSub = (asDict(analysisNode.analyses) ?? {});
+    const universeSub = (asDict(universeNode.analyses) ?? {});
+    const analysesPrefix = pathPrefix ? `${pathPrefix}.analyses` : "analyses";
+    for (const analysisId of Object.keys(universeSub)) {
+        if (!(analysisId in analysisSub)) {
+            errors.push(new SemanticError("UNKNOWN_ANALYSIS", `Universe references unknown analysis: ${analysisId}`, `${analysesPrefix}.${analysisId}`));
+        }
+    }
+    for (const [analysisId, sub] of Object.entries(analysisSub)) {
+        const subUniverse = (universeSub[analysisId] ?? {});
+        errors.push(..._validateUniverseNode(subUniverse, sub, `${analysesPrefix}.${analysisId}`, [...ancestorUniverseChain, universeDecisions]));
+    }
+    return errors;
+}
+function _validateNodeUniverseConstraints(universeDecisions, analysisDecisions, pathPrefix) {
+    const errors = [];
+    for (const [decisionId, optionId] of Object.entries(universeDecisions)) {
+        const decision = analysisDecisions[decisionId];
+        if (!decision)
+            continue;
+        const options = (asDict(decision.options) ?? {});
+        const option = options[optionId];
+        if (!option)
+            continue;
+        const path = `${pathPrefix}.${decisionId}`;
+        for (const ref of asArray(option.incompatible_with)) {
+            const parts = ref.split(".");
+            if (parts.length === 2 && universeDecisions[parts[0]] === parts[1]) {
+                errors.push(new SemanticError("INCOMPATIBLE_OPTIONS", `Option '${decisionId}.${optionId}' is incompatible with '${ref}'`, path));
+            }
+        }
+        for (const ref of asArray(option.requires)) {
+            const parts = ref.split(".");
+            if (parts.length === 2 && universeDecisions[parts[0]] !== parts[1]) {
+                const actual = universeDecisions[parts[0]] ?? "(not set)";
+                errors.push(new SemanticError("MISSING_REQUIRED_OPTION", `Option '${decisionId}.${optionId}' requires '${ref}' but got '${actual}'`, path));
+            }
+        }
+    }
+    return errors;
+}
+// ---------------------------------------------------------------------------
+// File-level wrappers
+// ---------------------------------------------------------------------------
+import { dirname } from "node:path";
+export function validateAnalysisFile(filePath) {
+    return validateAnalysis(loadYaml(filePath), { basePath: dirname(filePath) });
+}
+export function validateUniverseFile(universePath, analysisPath) {
+    return validateUniverse(loadYaml(universePath), loadYaml(analysisPath));
+}
+//# sourceMappingURL=semantic.js.map