@petepetrash/circuit 0.1.0

package/dist/flows/compile-schematic-to-flow.js

@@ -0,0 +1,651 @@
+// Pure compiler: FlowSchematic → CompiledFlow(s). Takes a fully-populated schematic
+// (schematic-level axes/stage_path_policy/stages/version present;
+// per-item protocol/writes/check present) and produces compiled CompiledFlow
+// objects shaped like the existing committed `generated/flows/<id>/`
+// fixtures.
+//
+// Compile is per derived axis selection: routes are resolved against
+// `route_overrides[outcome][mode.depth]` when the schematic declares one;
+// reachability is computed against that resolved graph and unreachable
+// items are dropped per axis selection. The result is a discriminated union:
+//
+//   - `kind: 'single'`  when the schematic declares no route_overrides anywhere.
+//                       All axis selections share the same compiled graph.
+//                       Build-time emit writes one `circuit.json`.
+//
+//   - `kind: 'per-mode'` when at least one item declares route_overrides.
+//                        Returns one CompiledFlow per axis selection.
+//                        Build-time emit groups by graph identity, writes
+//                        the largest group to `circuit.json`, and writes
+//                        remaining modes to `<mode-name>.json`.
+//
+// Failure modes are deliberate: if any compile-required field is missing,
+// or any `kind ↔ report schema` pair is one the runner does not support,
+// the compile throws with a clear message naming the offending item.
+import { CompiledFlow } from '../schemas/compiled-flow.js';
+import { isDefaultEquipmentScope } from '../schemas/equipment-scope.js';
+import { RUNTIME_SUCCESS_ROUTE, SCHEMATIC_SUCCESS_ROUTE_ALIASES, schematicOutcomeToRuntimeRoute, } from '../schemas/route-policy.js';
+import { CANONICAL_STAGES } from '../schemas/stage.js';
+import { axisSelectionsForAxes } from './axis-selections.js';
+import { findCheckpointBriefBuilder } from './registries/checkpoint-writers/registry.js';
+import { findVerificationWriter } from './registries/verification-writers/registry.js';
+import { collectSchematicCatalogIssues } from './schematic-catalog-check.js';
+// Step 2 — the live equipment reshape's compile-layer half. Re-exported here so
+// the engine reaches it through the sanctioned compile seam (the engine→flow
+// boundary allowlists this module, not the resolver), keeping the runtime free
+// of any per-flow resolver import. See src/flows/equipment-reshape.ts.
+export { reResolveEquipmentOnCompiledFlow, } from './equipment-reshape.js';
+export class FlowSchematicCompileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FlowSchematicCompileError';
+    }
+}
+function fail(message) {
+    throw new FlowSchematicCompileError(message);
+}
+// (step kind, report schema) pairs the runner's writers actually
+// understand. Both verification and checkpoint kinds consult their
+// per-kind writer registries (the single source of truth — adding a
+// writer there auto-permits the schema here).
+export function ensureSupportedKindReportPair(item) {
+    if (item.execution.kind === 'verification') {
+        if (findVerificationWriter(item.output) === undefined) {
+            fail(`schematic item '${item.id}' has verification kind but writes '${item.output}'; no verification writer is registered for that schema (see src/flows/registries/verification-writers/registry.ts)`);
+        }
+    }
+    if (item.execution.kind === 'checkpoint' && item.writes?.report_path !== undefined) {
+        if (findCheckpointBriefBuilder(item.output) === undefined) {
+            fail(`schematic item '${item.id}' has checkpoint kind writing report '${item.output}'; no checkpoint writer is registered for that schema (see src/flows/registries/checkpoint-writers/registry.ts)`);
+        }
+    }
+}
+function requireSchematicField(value, fieldName, schematicId) {
+    if (value === undefined) {
+        fail(`schematic '${schematicId}' is missing required compile-time field '${fieldName}'`);
+    }
+    return value;
+}
+function requireItemField(value, fieldName, itemId) {
+    if (value === undefined) {
+        fail(`schematic item '${itemId}' is missing required compile-time field '${fieldName}'`);
+    }
+    return value;
+}
+// Resolve a single schematic-side route outcome to its target after applying
+// any depth-specific override. The override map is keyed by CompiledDepth so authors
+// can express "lite-depth variants of this flow skip review" without naming
+// individual axis selections.
+function resolveRouteTarget(item, outcome, mode) {
+    const overrides = item.route_overrides[outcome];
+    const overridden = overrides?.[mode.depth];
+    if (overridden !== undefined)
+        return overridden;
+    return item.routes[outcome];
+}
+// Compute the set of items reachable for a given mode by following every
+// declared schematic route with mode-specific overrides applied. Rich route
+// labels stay in the compiled flow, so steps reachable only through ask,
+// handoff, retry, or revise are real runtime targets instead of hidden
+// authoring notes.
+function computeReachableForMode(schematic, mode) {
+    const itemById = new Map(schematic.items.map((item) => [item.id, item]));
+    const reachable = new Set();
+    const queue = [schematic.starts_at];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (id === undefined)
+            continue;
+        if (reachable.has(id))
+            continue;
+        reachable.add(id);
+        const item = itemById.get(id);
+        if (item === undefined) {
+            fail(`schematic '${schematic.id}' references unknown item id '${id}' through routes (or starts_at)`);
+        }
+        for (const outcome of Object.keys(item.routes)) {
+            const target = resolveRouteTarget(item, outcome, mode);
+            if (target === undefined)
+                continue;
+            if (target.startsWith('@'))
+                continue;
+            queue.push(target);
+        }
+    }
+    return reachable;
+}
+// Build a contract → producing item index from the reachable items. Used
+// to resolve the read-paths for each consuming item's typed input
+// contracts. If a contract has no producer (and is not in
+// initial_contracts) the consumer's compile fails.
+function buildContractProducerIndex(schematicId, items) {
+    const index = new Map();
+    for (const item of items) {
+        if (index.has(item.output)) {
+            const prior = index.get(item.output);
+            fail(`schematic '${schematicId}' items '${prior?.id}' and '${item.id}' both write contract '${item.output}' on the same compiled graph — read-path resolution requires a single producer per contract per mode`);
+        }
+        index.set(item.output, item);
+    }
+    return index;
+}
+function readPathForProducer(producer) {
+    // Prefer the typed report path; fall back to the relay result path
+    // when the producer is a relay step that does not emit a typed
+    // report (Review's audit-step pattern).
+    const writes = requireItemField(producer.writes, 'writes', producer.id);
+    if (writes.report_path !== undefined)
+        return writes.report_path;
+    if (writes.result_path !== undefined)
+        return writes.result_path;
+    fail(`schematic item '${producer.id}' produces '${producer.output}' but has no writes.report_path or writes.result_path — downstream consumers cannot find a read path`);
+}
+function computeReads(item, initialContracts, producerByContract) {
+    const reads = [];
+    const seen = new Set();
+    // Iterate inputs in declaration order so the emitted reads list is
+    // stable and matches the schematic author's intent.
+    for (const contract of Object.values(item.input)) {
+        if (initialContracts.has(contract))
+            continue;
+        const producer = producerByContract.get(contract);
+        if (producer === undefined) {
+            fail(`schematic item '${item.id}' input contract '${contract}' has no producer reachable in this mode and is not in initial_contracts`);
+        }
+        const path = readPathForProducer(producer);
+        if (!seen.has(path)) {
+            reads.push(path);
+            seen.add(path);
+        }
+    }
+    return reads;
+}
+// When the schematic declares the until-loop flag with carried notes, return the
+// head step id and the notes path so the compiler can inject that path into the
+// head step's reads. Returns undefined when no until flag or no carried notes are
+// declared, so non-until flows are untouched.
+function untilHeadCarriedNotesRead(engineFlags) {
+    const until = engineFlags?.iterates_until_condition;
+    if (until === undefined)
+        return undefined;
+    if (until.carried_notes === undefined)
+        return undefined;
+    return { headStep: until.head_step, report: until.carried_notes.report };
+}
+// Map schematic routes to CompiledFlow routes for a given mode. Schematic
+// success aliases populate the runtime success edge because handlers advance
+// on `pass`. The original schematic labels are preserved too, so checkpoint
+// selections and rich route outcomes can execute without a second
+// hand-maintained graph.
+function compileRoutesForMode(item, mode) {
+    const routes = {};
+    let passSet = false;
+    for (const outcome of Object.keys(item.routes)) {
+        const target = resolveRouteTarget(item, outcome, mode);
+        if (target === undefined) {
+            fail(`schematic item '${item.id}' route outcome '${outcome}' has no target after applying mode '${mode.name}' (depth '${mode.depth}') overrides`);
+        }
+        routes[outcome] = target;
+        const flowRoute = schematicOutcomeToRuntimeRoute(outcome);
+        if (flowRoute === undefined)
+            continue;
+        if (passSet) {
+            fail(`schematic item '${item.id}' has multiple outcomes that map to '${RUNTIME_SUCCESS_ROUTE}' (only one allowed); pick whichever maps to the live runtime success edge`);
+        }
+        routes[flowRoute] = target;
+        passSet = true;
+    }
+    if (!passSet) {
+        fail(`schematic item '${item.id}' has no outcome that maps to '${RUNTIME_SUCCESS_ROUTE}'; declare one success route (${SCHEMATIC_SUCCESS_ROUTE_ALIASES.join(' or ')}) so the compiled CompiledFlow has a success edge`);
+    }
+    if (item.execution.kind === 'checkpoint' && item.checkpoint_policy?.choices !== undefined) {
+        const successTarget = routes[RUNTIME_SUCCESS_ROUTE];
+        if (successTarget === undefined) {
+            fail(`schematic checkpoint '${item.id}' has no runtime success route`);
+        }
+        for (const choice of item.checkpoint_policy.choices) {
+            routes[choice.id] ??= successTarget;
+        }
+    }
+    return routes;
+}
+function compileItem(item, reads, routes) {
+    const protocol = requireItemField(item.protocol, 'protocol', item.id);
+    const writes = requireItemField(item.writes, 'writes', item.id);
+    const check = requireItemField(item.check, 'check', item.id);
+    ensureSupportedKindReportPair(item);
+    const stepBase = {
+        id: item.id,
+        title: item.title,
+        protocol,
+        reads: [...reads],
+        routes,
+        ...(item.selection !== undefined ? { selection: item.selection } : {}),
+        ...(item.skill_slots.length === 0 ? {} : { skill_slots: item.skill_slots }),
+        ...(item.equipment_scope === undefined || isDefaultEquipmentScope(item.equipment_scope)
+            ? {}
+            : { equipment_scope: item.equipment_scope }),
+        ...(item.route_from_report === undefined ? {} : { route_from_report: item.route_from_report }),
+    };
+    switch (item.execution.kind) {
+        case 'compose': {
+            const reportPath = requireWritesField(writes, 'report_path', item.id, 'compose');
+            return {
+                ...stepBase,
+                executor: 'orchestrator',
+                kind: 'compose',
+                writes: {
+                    report: { path: reportPath, schema: item.output },
+                },
+                check: {
+                    kind: 'schema_sections',
+                    source: { kind: 'report', ref: 'report' },
+                    required: requireCheckField(check.required, 'required', item.id, 'compose'),
+                },
+            };
+        }
+        case 'verification': {
+            const reportPath = requireWritesField(writes, 'report_path', item.id, 'verification');
+            return {
+                ...stepBase,
+                executor: 'orchestrator',
+                kind: 'verification',
+                writes: {
+                    report: { path: reportPath, schema: item.output },
+                },
+                check: {
+                    kind: 'schema_sections',
+                    source: { kind: 'report', ref: 'report' },
+                    required: requireCheckField(check.required, 'required', item.id, 'verification'),
+                },
+            };
+        }
+        case 'checkpoint': {
+            const policy = requireItemField(item.checkpoint_policy, 'checkpoint_policy', item.id);
+            const requestPath = requireWritesField(writes, 'checkpoint_request_path', item.id, 'checkpoint');
+            const responsePath = requireWritesField(writes, 'checkpoint_response_path', item.id, 'checkpoint');
+            const checkpointWrites = {
+                request: requestPath,
+                response: responsePath,
+            };
+            if (writes.report_path !== undefined) {
+                checkpointWrites.report = { path: writes.report_path, schema: item.output };
+            }
+            return {
+                ...stepBase,
+                executor: 'orchestrator',
+                kind: 'checkpoint',
+                policy,
+                writes: checkpointWrites,
+                check: {
+                    kind: 'checkpoint_selection',
+                    source: { kind: 'checkpoint_response', ref: 'response' },
+                    ...(check.allow === undefined
+                        ? {
+                            allow_from: requireCheckField(check.allow_from, 'allow_from', item.id, 'checkpoint'),
+                        }
+                        : { allow: check.allow }),
+                },
+            };
+        }
+        case 'relay': {
+            const role = item.execution.role;
+            if (role === undefined) {
+                fail(`schematic item '${item.id}' has relay kind but no execution.role`);
+            }
+            const requestPath = requireWritesField(writes, 'request_path', item.id, 'relay');
+            const receiptPath = requireWritesField(writes, 'receipt_path', item.id, 'relay');
+            const resultPath = requireWritesField(writes, 'result_path', item.id, 'relay');
+            const relayWrites = {
+                request: requestPath,
+                receipt: receiptPath,
+                result: resultPath,
+            };
+            if (writes.report_path !== undefined) {
+                relayWrites.report = { path: writes.report_path, schema: item.output };
+            }
+            return {
+                ...stepBase,
+                executor: 'worker',
+                kind: 'relay',
+                role,
+                // Optional per-step worker pin authored on execution.connector. Lifted
+                // onto the compiled relay step so the runtime relay path can read it as
+                // the top-priority connector choice. Omitted when unset, so flows that
+                // pin nothing stay byte-identical.
+                ...(item.execution.connector === undefined ? {} : { connector: item.execution.connector }),
+                ...(item.acceptance_criteria === undefined
+                    ? {}
+                    : { acceptance_criteria: item.acceptance_criteria }),
+                writes: relayWrites,
+                check: {
+                    kind: 'result_verdict',
+                    source: { kind: 'relay_result', ref: 'result' },
+                    pass: requireCheckField(check.pass, 'pass', item.id, 'relay'),
+                },
+            };
+        }
+        case 'sub-run': {
+            const flowRef = item.execution.flow_ref;
+            const goal = item.execution.goal;
+            const depth = item.execution.depth;
+            if (flowRef === undefined) {
+                fail(`schematic item '${item.id}' has sub-run kind but no execution.flow_ref`);
+            }
+            if (goal === undefined) {
+                fail(`schematic item '${item.id}' has sub-run kind but no execution.goal`);
+            }
+            if (depth === undefined) {
+                fail(`schematic item '${item.id}' has sub-run kind but no execution.depth`);
+            }
+            const resultPath = requireWritesField(writes, 'result_path', item.id, 'sub-run');
+            // Emit writes.report as a schema annotation pointing at the same
+            // path as writes.result. The child's result.json IS the typed
+            // report for downstream consumers — no separate materialization
+            // is needed (the sub-run handler short-circuits the v0 abort when
+            // report.path equals result path). This lets close-writers resolve
+            // sub-run output schemas via reportPathForSchemaInRuntimeFlow
+            // without special-casing sub-run.
+            return {
+                ...stepBase,
+                executor: 'orchestrator',
+                kind: 'sub-run',
+                flow_ref: flowRef,
+                goal,
+                depth,
+                writes: {
+                    result: resultPath,
+                    report: { path: resultPath, schema: item.output },
+                },
+                check: {
+                    kind: 'result_verdict',
+                    source: { kind: 'sub_run_result', ref: 'result' },
+                    pass: requireCheckField(check.pass, 'pass', item.id, 'sub-run'),
+                },
+            };
+        }
+        case 'fanout': {
+            const fanout = requireItemField(item.fanout, 'fanout', item.id);
+            const reportPath = requireWritesField(writes, 'report_path', item.id, 'fanout');
+            const branchesDir = requireWritesField(writes, 'branches_dir_path', item.id, 'fanout');
+            return {
+                ...stepBase,
+                executor: 'orchestrator',
+                kind: 'fanout',
+                branches: fanout.branches,
+                ...(fanout.concurrency === undefined ? {} : { concurrency: fanout.concurrency }),
+                ...(fanout.on_child_failure === undefined
+                    ? {}
+                    : { on_child_failure: fanout.on_child_failure }),
+                ...(fanout.rubric === undefined ? {} : { rubric: fanout.rubric }),
+                writes: {
+                    branches_dir: branchesDir,
+                    aggregate: { path: reportPath, schema: item.output },
+                },
+                check: {
+                    kind: 'fanout_aggregate',
+                    source: { kind: 'fanout_results', ref: 'aggregate' },
+                    join: fanout.join,
+                    verdicts: {
+                        admit: requireCheckField(check.pass, 'pass', item.id, 'fanout'),
+                    },
+                },
+            };
+        }
+    }
+}
+function requireWritesField(writes, field, itemId, kind) {
+    const value = writes[field];
+    if (value === undefined) {
+        fail(`schematic item '${itemId}' (${kind}) is missing writes.${field}`);
+    }
+    return value;
+}
+function requireCheckField(value, field, itemId, kind) {
+    if (value === undefined) {
+        fail(`schematic item '${itemId}' (${kind}) is missing check.${field}`);
+    }
+    return value;
+}
+function schematicHasOverrides(schematic) {
+    return schematic.items.some((item) => Object.keys(item.route_overrides).length > 0);
+}
+// Derive the flow's primary result — the report the close stage composes on the
+// success path. run-close binds the @complete terminal to it (e.g. it can
+// downgrade an @complete close when the result report's own outcome is not
+// "complete"). We read it off the close-stage compose steps that route to
+// @complete and write a report, which excludes a close-stage handoff/recovery
+// step that composes a different record on a non-complete terminal (fix's
+// fix-handoff writes continuity.record@v1 on @handoff). A flow may have more
+// than one @complete close path (a tournament close and a normal close); they
+// must converge on one result schema + path. Discordant @complete close writes
+// are a real ambiguity, so we fail closed rather than pick one silently. No
+// @complete close-compose step → undefined.
+function derivePrimaryResult(schematic) {
+    const writes = schematic.items
+        .filter((item) => item.stage === 'close' &&
+        item.execution.kind === 'compose' &&
+        item.writes?.report_path !== undefined &&
+        Object.values(item.routes).some((target) => target === '@complete'))
+        .map((item) => ({
+        schema_name: item.output,
+        path: item.writes?.report_path,
+    }));
+    const first = writes[0];
+    if (first === undefined)
+        return undefined;
+    for (const w of writes) {
+        if (w.schema_name !== first.schema_name || w.path !== first.path) {
+            fail(`schematic '${schematic.id}' has discordant @complete close-stage compose writes (${first.schema_name} at ${first.path} vs ${w.schema_name} at ${w.path}); cannot derive a single runtime_surface.primary_result`);
+        }
+    }
+    return first;
+}
+function frameSchematic(schematic) {
+    const schematicId = schematic.id;
+    const version = requireSchematicField(schematic.version, 'version', schematicId);
+    const stageEntries = requireSchematicField(schematic.stages, 'stages', schematicId);
+    const stagePathPolicy = requireSchematicField(schematic.stage_path_policy, 'stage_path_policy', schematicId);
+    return {
+        schematicId,
+        version,
+        purpose: schematic.purpose,
+        axes: requireSchematicField(schematic.axes, 'axes', schematicId),
+        startsAt: schematic.starts_at,
+        initialContracts: new Set(schematic.initial_contracts),
+        stageEntries: stageEntries.map((p) => ({
+            canonical: p.canonical,
+            id: p.id,
+            title: p.title,
+        })),
+        declaredOmits: stagePathPolicy.mode === 'partial' ? stagePathPolicy.omits : [],
+        stagePathRationale: stagePathPolicy.mode === 'partial' ? stagePathPolicy.rationale : undefined,
+        defaultSelection: schematic.default_selection,
+        engineFlags: schematic.engine_flags,
+        reportFileSurfaces: schematic.report_file_surfaces,
+        requiredConfig: schematic.required_config,
+        primaryResult: derivePrimaryResult(schematic),
+    };
+}
+// Compile the schematic for a single derived axis selection. Reachability +
+// overrides are applied; unreachable items are dropped, empty stages are filtered, and
+// stage_path_policy.omits is widened to include any canonical that ends up
+// empty in this mode (so the CompiledFlow validator's stage path completeness rule
+// stays satisfied).
+function compileForMode(schematic, frame, mode) {
+    const reachable = computeReachableForMode(schematic, mode);
+    const reachableItems = schematic.items.filter((item) => reachable.has(item.id));
+    if (reachableItems.length === 0) {
+        fail(`schematic '${frame.schematicId}' has no reachable items from starts_at '${frame.startsAt}' for mode '${mode.name}'`);
+    }
+    const producerByContract = buildContractProducerIndex(frame.schematicId, reachableItems);
+    const stages = [];
+    const reachedCanonicals = new Set();
+    for (const stage of frame.stageEntries) {
+        const items = reachableItems.filter((i) => i.stage === stage.canonical);
+        if (items.length === 0)
+            continue;
+        reachedCanonicals.add(stage.canonical);
+        stages.push({
+            id: stage.id,
+            title: stage.title,
+            canonical: stage.canonical,
+            steps: items.map((i) => i.id),
+        });
+    }
+    if (stages.length === 0) {
+        fail(`schematic '${frame.schematicId}' compiled to zero stages for mode '${mode.name}'`);
+    }
+    const headCarriedNotesPath = untilHeadCarriedNotesRead(frame.engineFlags);
+    const steps = reachableItems.map((item) => {
+        const reads = computeReads(item, frame.initialContracts, producerByContract);
+        // Until-loop compounding: the carried-notes file is engine-written and has no
+        // schematic producer, so the contract-driven reads above never include it.
+        // Inject it onto the loop's head step so the prompt composer re-inlines the
+        // accumulated lessons each pass (see src/runtime/run/carried-notes.ts). The
+        // path is appended (deduped) and only on the head, so every other step is
+        // byte-identical to a flow with no carried notes.
+        if (headCarriedNotesPath !== undefined &&
+            item.id === headCarriedNotesPath.headStep &&
+            !reads.includes(headCarriedNotesPath.report)) {
+            reads.push(headCarriedNotesPath.report);
+        }
+        const routes = compileRoutesForMode(item, mode);
+        return compileItem(item, reads, routes);
+    });
+    // Per-mode stage_path_policy: union of schematic-declared omits and any
+    // canonical that ended up empty for this mode. The rationale gets
+    // a per-mode suffix so the file is self-explanatory.
+    const declaredOmitSet = new Set(frame.declaredOmits);
+    const autoOmits = [];
+    for (const canonical of CANONICAL_STAGES) {
+        if (declaredOmitSet.has(canonical))
+            continue;
+        if (reachedCanonicals.has(canonical))
+            continue;
+        // Only add if the schematic had a stage entry for this canonical
+        // (otherwise it was already absent at the schematic level).
+        const wasDeclared = frame.stageEntries.some((p) => p.canonical === canonical);
+        if (wasDeclared)
+            autoOmits.push(canonical);
+    }
+    const omits = [...frame.declaredOmits, ...autoOmits];
+    // SpinePolicy discriminator: 'strict' when zero omits, 'partial' when at
+    // least one. If the schematic was 'strict' and per-mode reachability auto-
+    // omits a stage, the compiled output flips to 'partial' with an auto-
+    // generated rationale.
+    const stagePathPolicy = omits.length === 0
+        ? { mode: 'strict' }
+        : {
+            mode: 'partial',
+            omits,
+            rationale: composeStagePathRationale(frame.stagePathRationale, autoOmits, mode),
+        };
+    const flow = {
+        schema_version: '3',
+        id: schematic.id,
+        version: frame.version,
+        purpose: frame.purpose,
+        axes: frame.axes,
+        starts_at: frame.startsAt,
+        stages,
+        stage_path_policy: stagePathPolicy,
+        steps,
+        ...(frame.defaultSelection !== undefined ? { default_selection: frame.defaultSelection } : {}),
+        // Stage 3 (first-class composition): a schematic that declares engine flags
+        // carries them onto the compiled manifest verbatim, so the engine reads them
+        // off the manifest rather than a by-id catalog package.
+        ...(frame.engineFlags !== undefined ? { engine_flags: frame.engineFlags } : {}),
+        // Stage 3b (first-class composition): execution-bearing declarations ride
+        // the manifest so the engine reads them off the compiled flow, not a by-id
+        // catalog package. report_file_surfaces / required_config travel verbatim
+        // from the schematic; runtime_surface.primary_result is derived from the
+        // close stage. Each absent = the flow declares none.
+        ...(frame.reportFileSurfaces !== undefined
+            ? { report_file_surfaces: frame.reportFileSurfaces }
+            : {}),
+        ...(frame.primaryResult !== undefined
+            ? { runtime_surface: { primary_result: frame.primaryResult } }
+            : {}),
+        ...(frame.requiredConfig !== undefined ? { required_config: frame.requiredConfig } : {}),
+    };
+    const parsed = CompiledFlow.safeParse(flow);
+    if (!parsed.success) {
+        fail(`schematic '${frame.schematicId}' compiled to a CompiledFlow that fails parse for mode '${mode.name}': ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+function composeStagePathRationale(declared, autoOmits, mode) {
+    if (autoOmits.length === 0) {
+        return declared ?? '';
+    }
+    const autoNote = `mode '${mode.name}' (depth '${mode.depth}') also omits ${autoOmits
+        .map((c) => `'${c}'`)
+        .join(', ')} because route_overrides leave those canonicals with no reachable items.`;
+    return declared !== undefined && declared.length > 0 ? `${declared} ${autoNote}` : autoNote;
+}
+// Finds a child-run target that names the schematic's own id, or undefined.
+// Covers the two statically knowable child-run shapes the runtime cycle guard
+// would otherwise catch only mid-run: a sub-run item, and a static fanout
+// branch that sub-runs the flow's own id. A dynamic fanout template is left to
+// the runtime guard on purpose — its flow_ref can be a runtime placeholder, not
+// a statically known id, so rejecting it here could be wrong.
+function findSchematicSelfReference(schematic) {
+    for (const item of schematic.items) {
+        if (item.execution.kind === 'sub-run' && item.execution.flow_ref.flow_id === schematic.id) {
+            return `item '${item.id}' is a sub-run whose flow_ref names the schematic's own id`;
+        }
+        const branches = item.fanout?.branches;
+        if (branches?.kind === 'static') {
+            const selfBranch = branches.branches.find((branch) => 'flow_ref' in branch && branch.flow_ref.flow_id === schematic.id);
+            if (selfBranch !== undefined) {
+                return `item '${item.id}' has a fanout branch '${selfBranch.branch_id}' that sub-runs the schematic's own id`;
+            }
+        }
+    }
+    return undefined;
+}
+export function compileSchematicToCompiledFlow(schematic) {
+    // A flow that names itself as a child-run target can never make progress:
+    // every entry into it re-enters the same flow. This is statically obvious, so
+    // reject it at compile time rather than leaving it for the runtime cycle guard
+    // to catch mid-run. Both child-run edges are covered so they report
+    // self-reference identically. Checked before the catalog gate so self-reference
+    // is reported as the most fundamental structural problem, not a downstream
+    // symptom.
+    const selfReference = findSchematicSelfReference(schematic);
+    if (selfReference !== undefined) {
+        fail(`schematic '${schematic.id}' refers to itself: ${selfReference}, which can never make progress`);
+    }
+    // M5 (first-class composition): the fail-closed catalog gate. Every flow that
+    // reaches the compiler — the eight built-ins at emit time and any composed or
+    // edited flow at run time — must fit the block catalog. This is the route-aware
+    // check that the catalog-check seam exposes report-only; here it is enforced.
+    // It runs first, before any framing, so a flow whose items do not match the
+    // block model fails with the most fundamental error rather than a downstream
+    // symptom. The built-ins compile clean (zero by correction); this gate's
+    // standing job is to stop a catalog-incompatible composed flow from compiling.
+    const catalogIssues = collectSchematicCatalogIssues(schematic);
+    if (catalogIssues.length > 0) {
+        const noun = catalogIssues.length === 1 ? 'issue' : 'issues';
+        const detail = catalogIssues.map((issue) => `${issue.item_id}: ${issue.message}`).join('; ');
+        fail(`schematic '${schematic.id}' is not compatible with the block catalog (${catalogIssues.length} ${noun}): ${detail}`);
+    }
+    const frame = frameSchematic(schematic);
+    const axisSelections = axisSelectionsForAxes(frame.schematicId, frame.axes);
+    if (!schematicHasOverrides(schematic)) {
+        // No mode-specific topology. Compile one graph; only route_overrides that
+        // change reachability need per-mode JSON siblings for the CLI loader.
+        const firstMode = axisSelections[0];
+        if (firstMode === undefined) {
+            fail(`schematic '${frame.schematicId}' has no derived axis selections`);
+        }
+        return { kind: 'single', flow: compileForMode(schematic, frame, firstMode) };
+    }
+    const flows = new Map();
+    for (const mode of axisSelections) {
+        flows.set(mode.name, compileForMode(schematic, frame, mode));
+    }
+    return { kind: 'per-mode', flows };
+}
+//# sourceMappingURL=compile-schematic-to-flow.js.map