@deksden-com/dd-flow-cli 0.4.0 → 0.4.1

package/dist/domain/flow-contract.js

@@ -1,11 +1,16 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Ajv } from "ajv/dist/ajv.js";
 import { parse as parseYaml } from "yaml";
 import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
+let validateBundledFlowContract;
 export const defaultFlowContract = {
     id: "dd-flow-canonical-2026-05",
     version: 1,
+    capabilities: [],
     stages: {
         registered: { terminal: false },
         prime: { terminal: false },
@@ -59,7 +64,39 @@ export function loadProjectFlowContract(projectRoot) {
     if (!contractPath) {
         return defaultFlowContract;
     }
-    return normalizeFlowContract(readFlowContractObject(contractPath), contractPath);
+    try {
+        const value = readFlowContractObject(contractPath);
+        validateFlowContractStructure(value);
+        return normalizeFlowContract(value);
+    }
+    catch (error) {
+        if (error instanceof AppError) {
+            throw new AppError(error.code, `${contractPath}: ${error.message}`, error.exitCode, { ...error.details, file: contractPath });
+        }
+        throw error;
+    }
+}
+function validateFlowContractStructure(value) {
+    const validate = validateBundledFlowContract ??= new Ajv({ allErrors: true, strict: false, validateFormats: false }).compile(JSON.parse(fs.readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "schemas", "flow-contract.schema.json"), "utf8")));
+    if (validate(value))
+        return;
+    const errors = (validate.errors ?? []).map((error) => ({
+        path: ajvErrorPath(error),
+        message: error.message ?? "schema validation failed",
+        keyword: error.keyword
+    }));
+    const first = errors[0] ?? { path: "/", message: "schema validation failed", keyword: "schema" };
+    throw new AppError("validation", `${first.path} ${first.message}`, 2, { path: first.path, errors });
+}
+function ajvErrorPath(error) {
+    const property = error.keyword === "required"
+        ? error.params.missingProperty
+        : error.keyword === "additionalProperties"
+            ? error.params.additionalProperty
+            : error.keyword === "uniqueItems"
+                ? Math.max(Number(error.params.i), Number(error.params.j))
+                : undefined;
+    return property ? childPath(error.instancePath, String(property)) : error.instancePath || "/";
 }
 export function flowContractForState(state) {
     if (!state.flow_contract) {
@@ -68,7 +105,7 @@ export function flowContractForState(state) {
     if (typeof state.flow_contract !== "object" || Array.isArray(state.flow_contract)) {
         return defaultFlowContract;
     }
-    return normalizeFlowContract(state.flow_contract, "state.flow_contract");
+    return normalizeFlowContract(state.flow_contract);
 }
 export function normalizeStage(value, contract) {
     return contract.legacy_aliases[value] ?? value;
@@ -95,16 +132,269 @@ export function canTransition(from, to, contract = defaultFlowContract) {
     }
     return contract.transitions[normalizedFrom]?.includes(normalizedTo) ?? false;
 }
-function normalizeFlowContract(value, label) {
-    const id = requireString(value.id, `${label}.id`);
-    const version = requireNumber(value.version, `${label}.version`);
-    const stages = normalizeStages(value.stages, `${label}.stages`);
-    const legacyAliases = normalizeStringMap(value.legacy_aliases ?? {}, `${label}.legacy_aliases`);
-    const transitions = normalizeTransitions(value.transitions, `${label}.transitions`, stages, legacyAliases);
-    const readiness = normalizeReadiness(value.readiness, `${label}.readiness`, stages, legacyAliases);
-    const mergeQueue = normalizeMergeQueue(value.merge_queue, `${label}.merge_queue`, stages, legacyAliases);
-    const defaults = normalizeDefaults(value.defaults, `${label}.defaults`);
-    return { id, version, stages, transitions, readiness, merge_queue: mergeQueue, defaults, legacy_aliases: legacyAliases };
+export function resolveFlowFlags(contract, input) {
+    const catalog = contract.flow_flags;
+    const now = input.now ?? new Date().toISOString();
+    if (!catalog) {
+        const values = {};
+        return {
+            contract: { id: contract.id, version: contract.version, capabilities: contract.capabilities },
+            flow_kind: input.flowKind,
+            preset: { requested: input.preset ?? null, applied: "none", source_ref: `${contract.id}#flow_flags.none` },
+            snapshot_revision: input.snapshotRevision ?? 1,
+            resolution_status: "valid",
+            resolved_at: now,
+            values,
+            compatibility_projection: { task_profile_revision: null, legacy_flow_profile_read: false },
+            snapshot_checksum: checksumForFlowFlagValues(values),
+            floors_applied: []
+        };
+    }
+    const flow = catalog.flows[input.flowKind] ?? catalog.flows.custom;
+    if (!flow) {
+        throw new AppError("validation", `Flow kind has no flow-flag contract: ${input.flowKind}`, 2, {
+            flow_kind: input.flowKind,
+            supported: Object.keys(catalog.flows)
+        });
+    }
+    const defaultPreset = flow.default_preset ?? flow.defaults?.preset;
+    if (!defaultPreset || !catalog.presets[defaultPreset]) {
+        throw new AppError("validation", `Flow kind has no valid default preset: ${input.flowKind}`, 2);
+    }
+    const appliedPreset = input.preset ?? defaultPreset;
+    const presetValues = catalog.presets[appliedPreset];
+    if (!presetValues) {
+        throw new AppError("validation", `Unknown flow preset: ${appliedPreset}`, 2, {
+            preset: appliedPreset,
+            allowed: Object.keys(catalog.presets)
+        });
+    }
+    const supported = new Set(flow.supported);
+    const values = {};
+    const floorsApplied = [];
+    applyFlagMap(values, catalog, supported, catalog.presets[defaultPreset] ?? {}, "flow_default", `${contract.id}#flow_flags.flows.${input.flowKind}`, "flow default preset", now);
+    if (input.preset) {
+        applyFlagMap(values, catalog, supported, presetValues, "preset", `${contract.id}#flow_flags.presets.${appliedPreset}`, `preset ${appliedPreset}`, now);
+    }
+    const taskProfile = recordValue(input.taskProfile);
+    const profileFlags = taskProfileFlagMap(taskProfile);
+    const profileSource = taskProfile?.flow_flags || taskProfile?.flags ? "task_profile" : taskProfile?.flow_profile ? "compatibility_alias" : "task_profile";
+    applyFlagMap(values, catalog, supported, profileFlags, profileSource, "task_profile", "task profile override", now, true);
+    applyFlagMap(values, catalog, supported, input.protocolOverrides ?? {}, "protocol_override", "protocol_override", "protocol override", now, true, input.snapshotRevision ?? 1);
+    applyFlagMap(values, catalog, supported, input.runOverrides ?? {}, "run_override", "run_override", "RUN override", now, true, input.snapshotRevision ?? 1);
+    for (const key of supported) {
+        if (!values[key]) {
+            throw new AppError("validation", `Preset resolution is incomplete for flag: ${key}`, 2, {
+                flow_kind: input.flowKind,
+                preset: appliedPreset
+            });
+        }
+    }
+    const facts = taskFacts(taskProfile);
+    for (const [floorIndex, floor] of (catalog.mandatory_floors ?? []).entries()) {
+        if (!floorMatches(floor.when, facts))
+            continue;
+        for (const [key, floorValue] of Object.entries(floor.values)) {
+            if (!supported.has(key))
+                continue;
+            const definition = catalog.definitions[key];
+            if (!definition)
+                continue;
+            validateFlagValue(key, definition, floorValue);
+            const current = values[key];
+            if (!current || flagStrength(key, current.value, definition) < flagStrength(key, floorValue, definition)) {
+                if (current && ["task_profile", "compatibility_alias", "protocol_override", "run_override"].includes(current.source.kind)) {
+                    throw new AppError("validation", `Override is below mandatory floor for ${key}`, 2, {
+                        flag: key,
+                        requested: current.value,
+                        floor: floorValue,
+                        floor_index: floorIndex,
+                        reason: floor.reason
+                    });
+                }
+                values[key] = valueRecord(key, definition, floorValue, "escalation", `mandatory_floors[${floorIndex}]`, floor.reason, now, input.snapshotRevision ?? 1);
+                floorsApplied.push(`${key}=floor:${floorIndex}`);
+            }
+        }
+    }
+    const taskProfileRevision = numberValue(taskProfile?.revision);
+    return {
+        contract: { id: contract.id, version: contract.version, capabilities: contract.capabilities },
+        flow_kind: input.flowKind,
+        preset: {
+            requested: input.preset ?? null,
+            applied: appliedPreset,
+            source_ref: `${contract.id}#flow_flags.presets.${appliedPreset}`
+        },
+        snapshot_revision: input.snapshotRevision ?? 1,
+        resolution_status: "valid",
+        resolved_at: now,
+        values,
+        compatibility_projection: {
+            task_profile_revision: taskProfileRevision,
+            legacy_flow_profile_read: Boolean(taskProfile?.flow_profile)
+        },
+        snapshot_checksum: checksumForFlowFlagValues(values),
+        floors_applied: floorsApplied
+    };
+}
+function applyFlagMap(target, catalog, supported, sourceMap, sourceKind, sourceRef, rationale, now, rejectUnknown = false, revision = null) {
+    for (const [key, value] of Object.entries(sourceMap)) {
+        if (!catalog.definitions[key]) {
+            if (rejectUnknown)
+                throw new AppError("validation", `Unknown flow flag: ${key}`, 2, { flag: key, source: sourceRef });
+            continue;
+        }
+        if (!supported.has(key)) {
+            if (rejectUnknown)
+                throw new AppError("validation", `Flow flag is unsupported for this flow: ${key}`, 2, { flag: key });
+            continue;
+        }
+        const definition = catalog.definitions[key];
+        validateFlagValue(key, definition, value);
+        target[key] = valueRecord(key, definition, value, sourceKind, sourceRef, rationale, now, revision);
+    }
+}
+function valueRecord(key, definition, value, sourceKind, sourceRef, rationale, now, revision) {
+    return {
+        value: value,
+        value_type: definition.type,
+        owner: definition.owner,
+        source: { kind: sourceKind, ref: sourceRef, revision },
+        rationale: `${key}: ${rationale}`,
+        resolved_at: now
+    };
+}
+function validateFlagValue(key, definition, value, errorPath) {
+    const validType = definition.type === "boolean"
+        ? typeof value === "boolean"
+        : definition.type === "number"
+            ? typeof value === "number" && Number.isFinite(value)
+            : definition.type === "string"
+                ? typeof value === "string"
+                : typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null;
+    if (!validType || (definition.values && !definition.values.some((candidate) => candidate === value))) {
+        throw new AppError("validation", `Invalid value for flow flag: ${key}`, 2, {
+            ...(errorPath ? { path: errorPath } : {}),
+            flag: key,
+            value,
+            expected: definition.values ?? definition.type
+        });
+    }
+}
+function taskProfileFlagMap(profile) {
+    if (!profile)
+        return {};
+    const flags = recordValue(profile.flow_flags) ?? recordValue(profile.flags);
+    const result = { ...(flags ?? {}) };
+    const route = recordValue(profile.route);
+    if (route?.planning !== undefined)
+        result["planning.mode"] = route.planning;
+    const verification = recordValue(profile.verification);
+    if (verification?.depth !== undefined)
+        result["verification.depth"] = verification.depth;
+    if (verification?.mode !== undefined)
+        result["verification.depth"] = verification.mode;
+    const evidence = recordValue(profile.evidence);
+    if (evidence?.level !== undefined)
+        result["evidence.level"] = evidence.level;
+    return result;
+}
+function taskFacts(profile) {
+    const impact = recordValue(profile?.impact);
+    return {
+        ...(profile ?? {}),
+        risk: profile?.risk ?? impact?.risk,
+        contract: profile?.contract ?? impact?.contract,
+        operations: profile?.operations ?? impact?.operations
+    };
+}
+function floorMatches(when, facts) {
+    for (const [key, expected] of Object.entries(when)) {
+        if (key === "contract_not") {
+            if (expected.includes(facts.contract))
+                return false;
+            continue;
+        }
+        const actual = facts[key];
+        const expectedValues = Array.isArray(expected) ? expected : [expected];
+        if (!expectedValues.includes(actual))
+            return false;
+    }
+    return true;
+}
+function flagStrength(key, value, definition) {
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    const ranks = {
+        "planning.mode": ["no_plan", "compact_plan", "full_plan"],
+        "plan.review.mode": ["self", "grouped", "focused", "mixed"],
+        "subagents.route": ["self_check", "grouped_subagent", "focused_subagent", "mixed"],
+        "subagents.grouping": ["off", "allowlisted"],
+        "subagents.pool_fallback": ["one", "runtime"],
+        "observability.detail": ["compact", "normal", "full"],
+        "knowledge.extract": ["skip", "conditional", "required"],
+        "knowledge.promote": ["skip", "conditional", "required"],
+        "workspace.bootstrap.mode": ["not_required", "revalidate", "required"],
+        "merge.ceremony": ["compact", "normal", "full"],
+        "merge.report_detail": ["compact", "normal", "full"],
+        "verification.depth": ["minimal", "standard", "full"],
+        "evidence.level": ["final_report", "protocol_record", "proof_bundle", "verification_passport", "rollout_evidence"]
+    };
+    return ranks[key]?.indexOf(String(value)) ?? definition.values?.indexOf(value) ?? 0;
+}
+export function isFlowFlagDowngrade(key, candidate, baseline) {
+    return flagStrength(key, candidate, { type: "string", owner: "flow_contract" })
+        < flagStrength(key, baseline, { type: "string", owner: "flow_contract" });
+}
+export function checksumForFlowFlagValues(values) {
+    return crypto.createHash("sha256").update(JSON.stringify(sortRecord(values))).digest("hex");
+}
+function sortRecord(value) {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, value[key]]));
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+export function normalizeFlowContract(value) {
+    const id = requireString(value.id, "/id");
+    const version = requireNumber(value.version, "/version");
+    if (version > 3)
+        fail("/version", `unsupported flow-contract version: ${version}`);
+    if (version === 3 && !/^dd-flow-canonical-[0-9]{4}-[0-9]{2}$/.test(id)) {
+        fail("/id", "must identify a canonical version 3 flow contract");
+    }
+    if (value.flow_flags !== undefined && version !== 3)
+        fail("/version", "must be 3 when flow_flags is present");
+    const capabilities = normalizeStringArray(value.capabilities ?? [], "/capabilities");
+    const stages = normalizeStages(value.stages, "/stages");
+    const legacyAliases = normalizeStringMap(value.legacy_aliases ?? {}, "/legacy_aliases");
+    const transitions = normalizeTransitions(value.transitions, "/transitions", stages, legacyAliases);
+    const readiness = normalizeReadiness(value.readiness, "/readiness", stages, legacyAliases);
+    const mergeQueue = normalizeMergeQueue(value.merge_queue, "/merge_queue", stages, legacyAliases);
+    const defaults = normalizeDefaults(value.defaults, "/defaults");
+    const flowFlags = value.flow_flags === undefined ? undefined : normalizeFlowFlags(value.flow_flags, "/flow_flags");
+    const entrypoints = recordValue(value.entrypoints);
+    const autoPolicy = recordValue(value.auto_policy);
+    const routeAliases = value.route_aliases === undefined ? undefined : normalizeStringMap(value.route_aliases, "/route_aliases");
+    return {
+        id,
+        version,
+        capabilities,
+        stages,
+        transitions,
+        readiness,
+        merge_queue: mergeQueue,
+        defaults,
+        legacy_aliases: legacyAliases,
+        ...(entrypoints ? { entrypoints } : {}),
+        ...(autoPolicy ? { auto_policy: autoPolicy } : {}),
+        ...(routeAliases ? { route_aliases: routeAliases } : {}),
+        ...(flowFlags ? { flow_flags: flowFlags } : {})
+    };
 }
 function findProjectFlowContractPath(projectRoot) {
     const basePath = path.join(projectRoot, ".memory-bank", "dd-flow", "flow-contract");
@@ -129,35 +419,39 @@ function readFlowContractObject(file) {
 }
 function normalizeStages(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new AppError("validation", `${label} must be an object`, 2);
+        fail(label, "must be an object");
     }
     const stages = {};
     for (const [stage, config] of Object.entries(value)) {
+        const stagePath = childPath(label, stage);
         if (!config || typeof config !== "object" || Array.isArray(config)) {
-            throw new AppError("validation", `${label}.${stage} must be an object`, 2);
+            fail(stagePath, "must be an object");
         }
         const terminal = config.terminal;
-        stages[stage] = { terminal: typeof terminal === "boolean" ? terminal : false };
+        if (typeof terminal !== "boolean")
+            fail(childPath(stagePath, "terminal"), "must be a boolean");
+        stages[stage] = { terminal };
     }
     if (!stages.registered || !stages.closed || !stages.cancelled) {
-        throw new AppError("validation", `${label} must include registered, closed, and cancelled stages`, 2);
+        fail(label, "must include registered, closed, and cancelled stages");
     }
     return stages;
 }
 function normalizeTransitions(value, label, stages, aliases) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new AppError("validation", `${label} must be an object`, 2);
+        fail(label, "must be an object");
     }
     const transitions = {};
     for (const [from, tos] of Object.entries(value)) {
+        const transitionPath = childPath(label, from);
         const normalizedFrom = aliases[from] ?? from;
-        requireKnownStage(normalizedFrom, stages, `${label}.${from}`);
+        requireKnownStage(normalizedFrom, stages, transitionPath);
         if (!Array.isArray(tos) || tos.some((to) => typeof to !== "string")) {
-            throw new AppError("validation", `${label}.${from} must be a string array`, 2);
+            fail(transitionPath, "must be a string array");
         }
-        transitions[normalizedFrom] = tos.map((to) => {
+        transitions[normalizedFrom] = tos.map((to, index) => {
             const normalizedTo = aliases[to] ?? to;
-            requireKnownStage(normalizedTo, stages, `${label}.${from}`);
+            requireKnownStage(normalizedTo, stages, childPath(transitionPath, index));
             return normalizedTo;
         });
     }
@@ -165,59 +459,225 @@ function normalizeTransitions(value, label, stages, aliases) {
 }
 function normalizeReadiness(value, label, stages, aliases) {
     const object = requireObject(value, label);
-    const command = requireString(object.command, `${label}.command`);
+    const command = requireString(object.command, childPath(label, "command"));
     if (command !== "ready-for-merge") {
-        throw new AppError("validation", `${label}.command must be ready-for-merge`, 2);
+        fail(childPath(label, "command"), "must be ready-for-merge");
     }
     if (!Array.isArray(object.allowed_from) || object.allowed_from.some((stage) => typeof stage !== "string")) {
-        throw new AppError("validation", `${label}.allowed_from must be a string array`, 2);
+        fail(childPath(label, "allowed_from"), "must be a string array");
     }
-    const allowedFrom = object.allowed_from.map((stage) => normalizeKnownStage(stage, stages, aliases, `${label}.allowed_from`));
-    const targetStage = normalizeKnownStage(requireString(object.target_stage, `${label}.target_stage`), stages, aliases, label);
+    const allowedFrom = object.allowed_from.map((stage, index) => normalizeKnownStage(stage, stages, aliases, childPath(childPath(label, "allowed_from"), index)));
+    const targetStagePath = childPath(label, "target_stage");
+    const targetStage = normalizeKnownStage(requireString(object.target_stage, targetStagePath), stages, aliases, targetStagePath);
     return { command, allowed_from: allowedFrom, target_stage: targetStage };
 }
 function normalizeMergeQueue(value, label, stages, aliases) {
     const object = requireObject(value, label);
-    const complete = requireObject(object.complete, `${label}.complete`);
+    const completePath = childPath(label, "complete");
+    const complete = requireObject(object.complete, completePath);
+    const targetStagePath = childPath(completePath, "target_stage");
     return {
         complete: {
-            target_stage: normalizeKnownStage(requireString(complete.target_stage, `${label}.complete.target_stage`), stages, aliases, label),
-            next_action: requireString(complete.next_action, `${label}.complete.next_action`)
+            target_stage: normalizeKnownStage(requireString(complete.target_stage, targetStagePath), stages, aliases, targetStagePath),
+            next_action: requireString(complete.next_action, childPath(completePath, "next_action"))
         }
     };
 }
 function normalizeDefaults(value, label) {
     const object = requireObject(value, label);
-    return { registered_next_action: requireString(object.registered_next_action, `${label}.registered_next_action`) };
+    return { registered_next_action: requireString(object.registered_next_action, childPath(label, "registered_next_action")) };
 }
 function normalizeStringMap(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new AppError("validation", `${label} must be an object`, 2);
+        fail(label, "must be an object");
     }
     const output = {};
     for (const [key, mapValue] of Object.entries(value)) {
         if (typeof mapValue !== "string" || mapValue.length === 0) {
-            throw new AppError("validation", `${label}.${key} must be a non-empty string`, 2);
+            fail(childPath(label, key), "must be a non-empty string");
         }
         output[key] = mapValue;
     }
     return output;
 }
+function normalizeStringArray(value, label) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) {
+        fail(label, "must be a string array");
+    }
+    return [...value];
+}
+function normalizeFlowFlags(value, label) {
+    const object = requireObject(value, label);
+    const definitionsPath = childPath(label, "definitions");
+    const definitionsObject = requireObject(object.definitions, definitionsPath);
+    const definitions = {};
+    for (const [key, rawDefinition] of Object.entries(definitionsObject)) {
+        const definitionPath = childPath(definitionsPath, key);
+        const definition = requireObject(rawDefinition, definitionPath);
+        const typePath = childPath(definitionPath, "type");
+        const type = requireString(definition.type, typePath);
+        if (!["boolean", "enum", "number", "string"].includes(type)) {
+            fail(typePath, "is unsupported");
+        }
+        const rawValues = definition.values;
+        if (rawValues !== undefined && (!Array.isArray(rawValues) || rawValues.some((item) => !isFlagScalar(item)))) {
+            fail(childPath(definitionPath, "values"), "must contain scalar values");
+        }
+        definitions[key] = {
+            type,
+            ...(rawValues ? { values: rawValues } : {}),
+            owner: requireString(definition.owner, childPath(definitionPath, "owner")),
+            ...(typeof definition.description === "string" ? { description: definition.description } : {})
+        };
+    }
+    const presetsPath = childPath(label, "presets");
+    const presetsObject = requireObject(object.presets, presetsPath);
+    const presets = {};
+    for (const [name, rawPreset] of Object.entries(presetsObject)) {
+        const presetPath = childPath(presetsPath, name);
+        const preset = normalizeFlagMap(rawPreset, presetPath);
+        for (const [key, item] of Object.entries(preset)) {
+            const definition = definitions[key];
+            if (!definition)
+                fail(childPath(presetPath, key), `references unknown flow flag: ${key}`);
+            validateFlagValue(key, definition, item, childPath(presetPath, key));
+        }
+        presets[name] = preset;
+    }
+    const flowsPath = childPath(label, "flows");
+    const flowsObject = requireObject(object.flows, flowsPath);
+    const flows = {};
+    for (const [name, rawFlow] of Object.entries(flowsObject)) {
+        const flowPath = childPath(flowsPath, name);
+        const flow = requireObject(rawFlow, flowPath);
+        const flowDefaults = recordValue(flow.defaults);
+        const defaultPresetPath = childPath(flowPath, "default_preset");
+        const defaultPreset = requireString(flow.default_preset, defaultPresetPath);
+        const supportedPath = childPath(flowPath, "supported");
+        const supported = normalizeStringArray(flow.supported, supportedPath);
+        const duplicateIndex = supported.findIndex((key, index) => supported.indexOf(key) !== index);
+        if (duplicateIndex >= 0)
+            fail(childPath(supportedPath, duplicateIndex), `duplicates flow flag: ${supported[duplicateIndex]}`);
+        supported.forEach((key, index) => {
+            if (!definitions[key])
+                fail(childPath(supportedPath, index), `references unknown flow flag: ${key}`);
+        });
+        if (!presets[defaultPreset])
+            fail(defaultPresetPath, `references unknown preset: ${defaultPreset}`);
+        const legacyDefault = flowDefaults?.preset;
+        if (typeof legacyDefault === "string" && legacyDefault !== defaultPreset) {
+            fail(childPath(childPath(flowPath, "defaults"), "preset"), "must match default_preset");
+        }
+        for (const [presetName, preset] of Object.entries(presets)) {
+            for (const key of supported) {
+                if (!(key in preset))
+                    fail(childPath(childPath(presetsPath, presetName), key), `is required by flow: ${name}`);
+            }
+        }
+        flows[name] = {
+            default_preset: defaultPreset,
+            supported,
+            ...(typeof flowDefaults?.preset === "string" ? { defaults: { preset: flowDefaults.preset } } : {})
+        };
+    }
+    const floorsValue = object.mandatory_floors ?? [];
+    const floorsPath = childPath(label, "mandatory_floors");
+    if (!Array.isArray(floorsValue))
+        fail(floorsPath, "must be an array");
+    const mandatory_floors = floorsValue.map((rawFloor, index) => {
+        const floorPath = childPath(floorsPath, index);
+        const floor = requireObject(rawFloor, floorPath);
+        const valuesPath = childPath(floorPath, "values");
+        const values = normalizeFlagMap(floor.values, valuesPath);
+        for (const [key, item] of Object.entries(values)) {
+            const definition = definitions[key];
+            if (!definition)
+                fail(childPath(valuesPath, key), `references unknown flow flag: ${key}`);
+            validateFlagValue(key, definition, item, childPath(valuesPath, key));
+        }
+        return {
+            when: requireObject(floor.when, childPath(floorPath, "when")),
+            values,
+            reason: requireString(floor.reason, childPath(floorPath, "reason"))
+        };
+    });
+    const precedencePath = childPath(label, "source_precedence");
+    const precedence = normalizeSourcePrecedence(object.source_precedence, precedencePath);
+    const reductionMatrix = recordValue(object.reduction_matrix);
+    const consumerMatrix = recordValue(object.consumer_matrix);
+    if (reductionMatrix) {
+        for (const preset of Object.keys(reductionMatrix)) {
+            if (!presets[preset])
+                fail(childPath(childPath(label, "reduction_matrix"), preset), `references unknown preset: ${preset}`);
+        }
+    }
+    if (consumerMatrix) {
+        for (const key of Object.keys(consumerMatrix)) {
+            if (!definitions[key])
+                fail(childPath(childPath(label, "consumer_matrix"), key), `references unknown flow flag: ${key}`);
+        }
+    }
+    return {
+        source_precedence: precedence,
+        definitions,
+        presets,
+        flows,
+        mandatory_floors,
+        ...(reductionMatrix ? { reduction_matrix: reductionMatrix } : {}),
+        ...(consumerMatrix ? { consumer_matrix: Object.fromEntries(Object.entries(consumerMatrix).map(([key, items]) => [key, normalizeStringArray(items, childPath(childPath(label, "consumer_matrix"), key))])) } : {})
+    };
+}
+function normalizeSourcePrecedence(value, label) {
+    const supported = ["flow_default", "preset", "task_profile", "protocol_override", "run_override", "escalation", "compatibility_alias"];
+    const required = ["flow_default", "preset", "task_profile", "protocol_override", "run_override"];
+    const items = normalizeStringArray(value ?? required, label);
+    const result = [];
+    items.forEach((item, index) => {
+        if (!supported.includes(item))
+            fail(childPath(label, index), `contains unsupported source kind: ${item}`);
+        if (items.indexOf(item) !== index)
+            fail(childPath(label, index), `duplicates source kind: ${item}`);
+        result.push(item);
+    });
+    let previous = -1;
+    for (const source of required) {
+        const index = result.indexOf(source);
+        if (index < 0)
+            fail(label, `must include source kind: ${source}`);
+        if (index < previous)
+            fail(childPath(label, index), `must preserve mandatory source order at: ${source}`);
+        previous = index;
+    }
+    return result;
+}
+function normalizeFlagMap(value, label) {
+    const object = requireObject(value, label);
+    const result = {};
+    for (const [key, item] of Object.entries(object)) {
+        if (!isFlagScalar(item))
+            fail(childPath(label, key), "must be a scalar");
+        result[key] = item;
+    }
+    return result;
+}
+function isFlagScalar(value) {
+    return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
 function requireObject(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new AppError("validation", `${label} must be an object`, 2);
+        fail(label, "must be an object");
     }
     return value;
 }
 function requireString(value, label) {
     if (typeof value !== "string" || value.length === 0) {
-        throw new AppError("validation", `${label} must be a non-empty string`, 2);
+        fail(label, "must be a non-empty string");
     }
     return value;
 }
 function requireNumber(value, label) {
     if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
-        throw new AppError("validation", `${label} must be a positive integer`, 2);
+        fail(label, "must be a positive integer");
     }
     return value;
 }
@@ -228,6 +688,12 @@ function normalizeKnownStage(value, stages, aliases, label) {
 }
 function requireKnownStage(value, stages, label) {
     if (!Object.prototype.hasOwnProperty.call(stages, value)) {
-        throw new AppError("validation", `${label} references unknown stage: ${value}`, 2);
+        fail(label, `references unknown stage: ${value}`);
     }
 }
+function childPath(parent, segment) {
+    return `${parent}/${String(segment).replaceAll("~", "~0").replaceAll("/", "~1")}`;
+}
+function fail(errorPath, message) {
+    throw new AppError("validation", `${errorPath} ${message}`, 2, { path: errorPath });
+}