@interf/compiler 0.5.1 → 0.6.3

package/dist/packages/compiler/runtime-types.d.ts

@@ -0,0 +1,43 @@
+import { type WorkflowExecutor } from "../agents/lib/executors.js";
+import { type WorkflowId, type RuntimeContractType, type RuntimeRun, type RuntimeStage, type RuntimeStageAcceptance, type RuntimeStageContract, type RuntimeStageInstructions } from "./lib/schema.js";
+export type RuntimeRunStatus = "running" | "succeeded" | "failed";
+export type RuntimeStageContractDraft = Omit<RuntimeStageContract, "kind" | "version" | "generated_at" | "run_id" | "target_type" | "target_name" | "workflow" | "stage" | "stage_label" | "contract_type" | "executor">;
+export interface RuntimeStageExecutionOptions {
+    executor: WorkflowExecutor;
+    compiledPath: string;
+    executionPath?: string;
+    compiledName: string;
+    workflow: WorkflowId;
+    workflowSourcePath?: string;
+    stage: RuntimeStage;
+    stageLabel: string;
+    contractType: RuntimeContractType;
+    summary: string;
+    contract: RuntimeStageContractDraft;
+    buildPrompt: (contractPath: string) => string;
+    completionCheck?: (() => boolean) | null;
+}
+export interface RuntimeSummarizeExecutionOptions extends RuntimeStageExecutionOptions {
+    startingSummaryCount: number;
+    targetCount: number;
+}
+export interface RuntimeStageAcceptanceValidation {
+    ok: boolean;
+    summary: string;
+    failures: string[];
+}
+export interface RuntimeStageContractOptions {
+    compiledName: string;
+    stageId: string;
+    stageLabel: string;
+    counts?: Record<string, number>;
+    extraReadArtifacts?: string[];
+    stageReadArtifacts: string[];
+    stageWriteArtifacts: string[];
+    workflowNotes?: string[];
+    localSkillDocs?: string[];
+    instructions: RuntimeStageInstructions;
+    acceptance?: RuntimeStageAcceptance;
+}
+export interface RuntimeRunPatch extends Partial<Pick<RuntimeRun, "counts" | "summary" | "status" | "error" | "exit_code" | "finished_at">> {
+}

package/dist/packages/compiler/runtime-types.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/compiler/runtime.d.ts

@@ -0,0 +1,6 @@
+export type { RuntimeRunPatch, RuntimeRunStatus, RuntimeStageAcceptanceValidation, RuntimeStageContractDraft, RuntimeStageExecutionOptions, RuntimeSummarizeExecutionOptions, RuntimeStageContractOptions, } from "./runtime-types.js";
+export { archivedStageContractPath, eventLogPath, logsDirPath, promptLogPath, runHistoryPath, runPath, stageContractPath, statusLogPath, } from "./runtime-paths.js";
+export { validateStageContractAcceptance } from "./runtime-acceptance.js";
+export { buildStagePrompt } from "./runtime-prompt.js";
+export { buildRuntimeStageContract, } from "./runtime-contracts.js";
+export { beginRuntimeRun, loadRuntimeRun, markRuntimeRunFailedAfterValidation, markRuntimeRunSucceededAfterValidation, runExecutorStage, runExecutorSummarizeStage, saveRuntimeRun, updateRuntimeRun, writeStageContract, } from "./runtime-runs.js";

package/dist/packages/compiler/runtime.js

@@ -0,0 +1,5 @@
+export { archivedStageContractPath, eventLogPath, logsDirPath, promptLogPath, runHistoryPath, runPath, stageContractPath, statusLogPath, } from "./runtime-paths.js";
+export { validateStageContractAcceptance } from "./runtime-acceptance.js";
+export { buildStagePrompt } from "./runtime-prompt.js";
+export { buildRuntimeStageContract, } from "./runtime-contracts.js";
+export { beginRuntimeRun, loadRuntimeRun, markRuntimeRunFailedAfterValidation, markRuntimeRunSucceededAfterValidation, runExecutorStage, runExecutorSummarizeStage, saveRuntimeRun, updateRuntimeRun, writeStageContract, } from "./runtime-runs.js";

package/dist/packages/compiler/state-artifacts.d.ts

@@ -0,0 +1,8 @@
+import { type CompiledHealth, type CompiledRawSnapshot, type CompiledViewSpec } from "./lib/schema.js";
+export declare function refreshCompiledArtifacts(dirPath: string, options?: {
+    ensureViewSpec?: boolean;
+}): {
+    health: CompiledHealth;
+    viewSpec?: CompiledViewSpec;
+    rawSnapshot: CompiledRawSnapshot;
+};

package/dist/packages/compiler/state-artifacts.js

@@ -0,0 +1,13 @@
+import { saveCompiledHealth, } from "./state-io.js";
+import { computeCompiledHealth, } from "./state-health.js";
+import { ensureCompiledRawSnapshot, ensureCompiledViewSpec, } from "./state-view.js";
+export function refreshCompiledArtifacts(dirPath, options) {
+    const health = computeCompiledHealth(dirPath);
+    saveCompiledHealth(dirPath, health);
+    const rawSnapshot = ensureCompiledRawSnapshot(dirPath);
+    let viewSpec;
+    if (options?.ensureViewSpec) {
+        viewSpec = ensureCompiledViewSpec(dirPath);
+    }
+    return { health, viewSpec, rawSnapshot };
+}

package/dist/packages/compiler/state-health.d.ts

@@ -0,0 +1,4 @@
+import { type CompiledHealth, type CompiledStage, type RuntimeStatus } from "./lib/schema.js";
+export declare function computeCompiledHealth(dirPath: string): CompiledHealth;
+export declare function resolveCompiledStatus(..._args: unknown[]): RuntimeStatus;
+export declare function resolveCompiledStage(...args: unknown[]): CompiledStage;

package/dist/packages/compiler/state-health.js

@@ -0,0 +1,132 @@
+import { basename, join } from "node:path";
+import { existsSync } from "node:fs";
+import { readInterfConfig, resolveSourceFolderPath, } from "../project-model/interf-detect.js";
+import { discoverSourceFiles } from "../../lib/discovery.js";
+import { loadRuntimeRun } from "./runtime.js";
+import { loadState } from "./state-io.js";
+import { validateCompiled, validateCompiledStage, validateCompiledWorkflow, } from "./validate.js";
+import { readCompiledSchemaFile } from "./compiled-schema.js";
+import { workflowPackagePathForCompiled } from "../project-model/compiled-paths.js";
+import { getActiveCompiledWorkflow, resolveRequiredCompiledWorkflowFromConfig } from "../workflow-package/workflow-definitions.js";
+import { listFilesRecursive } from "../../lib/filesystem.js";
+function countZoneArtifacts(compiledPath, zonePath, kind) {
+    const absolutePath = join(compiledPath, zonePath);
+    if (!existsSync(absolutePath))
+        return 0;
+    if (kind === "file")
+        return 1;
+    return listFilesRecursive(absolutePath).length;
+}
+export function computeCompiledHealth(dirPath) {
+    const now = new Date().toISOString();
+    const config = readInterfConfig(dirPath);
+    const targetName = config?.name ?? basename(dirPath);
+    const sourcePath = config ? resolveSourceFolderPath(dirPath, config) : dirPath;
+    const sourceTotal = config ? discoverSourceFiles(sourcePath, dirPath).totalCount : 0;
+    const state = loadState(dirPath);
+    const validation = validateCompiled(dirPath);
+    const activeRun = loadRuntimeRun(dirPath);
+    const workflowId = config
+        ? resolveRequiredCompiledWorkflowFromConfig(config, `.interf/interf.json for ${dirPath}`)
+        : null;
+    let workflow = null;
+    if (workflowId) {
+        try {
+            workflow = getActiveCompiledWorkflow(dirPath, workflowId);
+        }
+        catch {
+            workflow = null;
+        }
+    }
+    const stageResults = workflow?.stages.map((stage) => ({
+        stage,
+        validation: validateCompiledStage(dirPath, stage.id),
+    })) ?? [];
+    const completedStages = stageResults.filter((entry) => entry.validation.ok).length;
+    const firstFailed = stageResults.find((entry) => !entry.validation.ok) ?? null;
+    const workflowValidation = validateCompiledWorkflow(dirPath);
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(dirPath));
+    const zoneMetrics = Object.fromEntries((schema?.zones ?? []).map((zone) => [
+        `zone_${zone.id}`,
+        countZoneArtifacts(dirPath, zone.path, zone.kind),
+    ]));
+    let status = "idle";
+    let stage = "idle";
+    let summary = "Idle — no source files have been compiled yet.";
+    const errors = workflowValidation.errors.length;
+    if (!validation.config_present || !validation.config_valid || !validation.config_type_match || !validation.workflow_valid || !validation.schema_valid) {
+        status = "failed";
+        stage = "failed";
+        summary = workflowValidation.summary;
+    }
+    else if (activeRun?.status === "running") {
+        status = "running";
+        stage = activeRun.stage;
+        summary = `Running — ${activeRun.stage_label} via ${activeRun.executor.display_name}. ${activeRun.summary}`;
+    }
+    else if (sourceTotal === 0 && completedStages === 0) {
+        status = "idle";
+        stage = "idle";
+        summary = "Idle — no source files have been compiled yet.";
+    }
+    else if (activeRun?.status === "failed") {
+        status = "failed";
+        stage = activeRun.stage;
+        summary = activeRun.error ?? activeRun.summary;
+    }
+    else if (workflowValidation.ok) {
+        status = "compiled";
+        stage = "compiled";
+        summary = `Compiled — ${completedStages}/${workflow?.stages.length ?? 0} workflow stages satisfied.`;
+    }
+    else {
+        status = "stale";
+        stage = firstFailed?.stage.id ?? "compiled";
+        summary = firstFailed?.validation.summary ?? workflowValidation.summary;
+    }
+    const checks = {
+        ...validation,
+        ...(workflow
+            ? Object.fromEntries(workflow.stages.map((workflowStage) => [
+                `stage_${workflowStage.id}_ok`,
+                stageResults.find((entry) => entry.stage.id === workflowStage.id)?.validation.ok ?? false,
+            ]))
+            : {}),
+    };
+    return {
+        kind: "compiled-health",
+        version: 2,
+        generated_at: now,
+        target_name: targetName,
+        status,
+        stage,
+        summary,
+        metrics: {
+            source_total: sourceTotal,
+            stage_total: workflow?.stages.length ?? 0,
+            completed_stages: completedStages,
+            warnings: state?.warning_count ?? 0,
+            errors: (state?.error_count ?? 0) + errors,
+            ...zoneMetrics,
+        },
+        checks,
+    };
+}
+export function resolveCompiledStatus(..._args) {
+    const state = _args[_args.length - 1];
+    if (state?.error_count && state.error_count > 0)
+        return "failed";
+    if (!state?.stages || Object.keys(state.stages).length === 0)
+        return "idle";
+    const allSucceeded = Object.values(state.stages).every((stage) => stage.status === "succeeded");
+    return allSucceeded ? "compiled" : "stale";
+}
+export function resolveCompiledStage(...args) {
+    const state = args[0];
+    if (state?.error_count && state.error_count > 0)
+        return "failed";
+    if (!state?.stages || Object.keys(state.stages).length === 0)
+        return "idle";
+    const failedStage = Object.entries(state.stages).find(([, stage]) => stage.status !== "succeeded");
+    return failedStage?.[0] ?? "compiled";
+}

package/dist/packages/compiler/state-io.d.ts

@@ -0,0 +1,10 @@
+import { type CompiledHealth, type CompiledRawSnapshot, type CompiledState, type CompiledViewSpec } from "./lib/schema.js";
+export declare function loadState<T>(dirPath: string): T | null;
+export declare function saveState<T>(dirPath: string, state: T): void;
+export declare function loadCompiledHealth(dirPath: string): CompiledHealth | null;
+export declare function saveCompiledHealth(dirPath: string, health: CompiledHealth): void;
+export declare function loadCompiledViewSpec(dirPath: string): CompiledViewSpec | null;
+export declare function saveCompiledViewSpec(dirPath: string, viewSpec: CompiledViewSpec): void;
+export declare function loadCompiledRawSnapshot(dirPath: string): CompiledRawSnapshot | null;
+export declare function saveEmptyCompiledInventory(dirPath: string): void;
+export declare function initCompiledState(): CompiledState;

package/dist/packages/compiler/state-io.js

@@ -0,0 +1,76 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { warnInterf } from "../../lib/logger.js";
+import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../lib/parse.js";
+import { CompiledHealthSchema, CompiledRawSnapshotSchema, CompiledStateSchema, CompiledViewSpecSchema, } from "./lib/schema.js";
+import { emptyCompiledInventory, } from "./runtime-inventory.js";
+import { healthPath, rawSnapshotPath, statePath, viewSpecPath } from "./state-paths.js";
+import { compiledRuntimeInventoryPath, compiledRuntimeRoot, } from "../project-model/compiled-paths.js";
+export function loadState(dirPath) {
+    const path = statePath(dirPath);
+    if (!existsSync(path))
+        return null;
+    const raw = readJsonFileUnchecked(path, "runtime state");
+    if (raw === null)
+        return null;
+    const parsed = CompiledStateSchema.safeParse(raw);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    warnInterf(`Warning: failed to validate runtime state at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+    return null;
+}
+export function saveState(dirPath, state) {
+    mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });
+    writeFileSync(statePath(dirPath), JSON.stringify(state, null, 2) + "\n");
+}
+export function loadCompiledHealth(dirPath) {
+    const path = healthPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "compiled health", CompiledHealthSchema);
+}
+export function saveCompiledHealth(dirPath, health) {
+    mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });
+    writeFileSync(healthPath(dirPath), JSON.stringify(health, null, 2) + "\n");
+}
+export function loadCompiledViewSpec(dirPath) {
+    const path = viewSpecPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return loadViewSpec(path, CompiledViewSpecSchema);
+}
+export function saveCompiledViewSpec(dirPath, viewSpec) {
+    mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });
+    writeFileSync(viewSpecPath(dirPath), JSON.stringify(viewSpec, null, 2) + "\n");
+}
+export function loadCompiledRawSnapshot(dirPath) {
+    const path = rawSnapshotPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "compiled raw snapshot", CompiledRawSnapshotSchema);
+}
+export function saveEmptyCompiledInventory(dirPath) {
+    mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });
+    writeFileSync(compiledRuntimeInventoryPath(dirPath), JSON.stringify(emptyCompiledInventory(), null, 2) + "\n");
+}
+export function initCompiledState() {
+    return {
+        version: 2,
+        pending: [],
+        stages: {},
+        last_add: null,
+        last_compile: null,
+        warning_count: 0,
+        error_count: 0,
+    };
+}
+function loadViewSpec(filePath, schema) {
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        const parsed = schema.safeParse(raw);
+        return parsed.success ? parsed.data ?? null : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/packages/compiler/state-paths.d.ts

@@ -0,0 +1,4 @@
+export declare function statePath(dirPath: string): string;
+export declare function healthPath(dirPath: string): string;
+export declare function viewSpecPath(dirPath: string): string;
+export declare function rawSnapshotPath(dirPath: string): string;

package/dist/packages/compiler/state-paths.js

@@ -0,0 +1,13 @@
+import { compiledRawSnapshotMetadataPath, compiledRuntimeHealthPath, compiledRuntimeStatePath, compiledRuntimeViewSpecPath, } from "../project-model/compiled-paths.js";
+export function statePath(dirPath) {
+    return compiledRuntimeStatePath(dirPath);
+}
+export function healthPath(dirPath) {
+    return compiledRuntimeHealthPath(dirPath);
+}
+export function viewSpecPath(dirPath) {
+    return compiledRuntimeViewSpecPath(dirPath);
+}
+export function rawSnapshotPath(dirPath) {
+    return compiledRawSnapshotMetadataPath(dirPath);
+}

package/dist/packages/compiler/state-view.d.ts

@@ -0,0 +1,4 @@
+import { type CompiledRawSnapshot, type CompiledViewSpec } from "./lib/schema.js";
+export declare function ensureCompiledViewSpec(dirPath: string): CompiledViewSpec;
+export declare function ensureCompiledRawSnapshot(dirPath: string): CompiledRawSnapshot;
+export declare function normalizeCompiledViewSpec(existing: CompiledViewSpec, defaults?: CompiledViewSpec): CompiledViewSpec;

package/dist/packages/compiler/state-view.js

@@ -0,0 +1,103 @@
+import { basename, relative } from "node:path";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { discoverSourceFiles } from "../../lib/discovery.js";
+import { readInterfConfig, resolveSourceFolderPath } from "../project-model/interf-detect.js";
+import { loadCompiledViewSpec, saveCompiledViewSpec, } from "./state-io.js";
+import { rawSnapshotPath } from "./state-paths.js";
+import { compiledRuntimeRoot, workflowPackagePathForCompiled } from "../project-model/compiled-paths.js";
+import { readCompiledSchemaFile } from "./compiled-schema.js";
+import { getActiveCompiledWorkflow, resolveRequiredCompiledWorkflowFromConfig } from "../workflow-package/workflow-definitions.js";
+export function ensureCompiledViewSpec(dirPath) {
+    const existing = loadCompiledViewSpec(dirPath);
+    const now = new Date().toISOString();
+    const compiledName = readInterfConfig(dirPath)?.name ?? basename(dirPath);
+    const defaults = buildDefaultCompiledViewSpec(dirPath, compiledName, now);
+    if (existing) {
+        const normalized = normalizeCompiledViewSpec(existing, defaults);
+        if (JSON.stringify(normalized) !== JSON.stringify(existing)) {
+            saveCompiledViewSpec(dirPath, normalized);
+        }
+        return normalized;
+    }
+    saveCompiledViewSpec(dirPath, defaults);
+    return defaults;
+}
+export function ensureCompiledRawSnapshot(dirPath) {
+    const now = new Date().toISOString();
+    const config = readInterfConfig(dirPath);
+    const compiledName = config?.name ?? basename(dirPath);
+    const sourcePath = resolveSourceFolderPath(dirPath, config);
+    const discovery = discoverSourceFiles(sourcePath, dirPath);
+    const sampleFiles = [...discovery.sourceFiles]
+        .sort((a, b) => a.length - b.length || a.localeCompare(b))
+        .slice(0, 10);
+    const sourceRoot = relative(dirPath, sourcePath) || ".";
+    const artifact = {
+        kind: "compiled-raw-snapshot",
+        version: 1,
+        generated_at: now,
+        target_name: compiledName,
+        source_root: sourceRoot,
+        raw_root: sourceRoot,
+        source_total: discovery.totalCount,
+        sample_files: sampleFiles,
+    };
+    mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });
+    writeFileSync(rawSnapshotPath(dirPath), JSON.stringify(artifact, null, 2) + "\n");
+    return artifact;
+}
+export function normalizeCompiledViewSpec(existing, defaults) {
+    const resolvedDefaults = defaults ?? existing;
+    return {
+        ...resolvedDefaults,
+        ...existing,
+        cards: Array.isArray(existing.cards) && existing.cards.length > 0
+            ? existing.cards.map((card) => {
+                if (card.format !== "fraction" || card.denominator_metric)
+                    return card;
+                const defaultCard = resolvedDefaults.cards.find((candidate) => candidate.id === card.id);
+                return {
+                    ...card,
+                    denominator_metric: defaultCard?.denominator_metric ?? "stage_total",
+                };
+            })
+            : resolvedDefaults.cards,
+        sections: Array.isArray(existing.sections) && existing.sections.length > 0 ? existing.sections : resolvedDefaults.sections,
+        graph_scope: Array.isArray(existing.graph_scope) && existing.graph_scope.length > 0
+            ? existing.graph_scope
+            : resolvedDefaults.graph_scope,
+    };
+}
+function buildDefaultCompiledViewSpec(dirPath, compiledName, generatedAt) {
+    const config = readInterfConfig(dirPath);
+    const workflowId = resolveRequiredCompiledWorkflowFromConfig(config, `.interf/interf.json for ${dirPath}`);
+    const workflow = getActiveCompiledWorkflow(dirPath, workflowId);
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(dirPath));
+    const outputDocumentPaths = (schema?.zones ?? [])
+        .filter((zone) => zone.role === "output" && zone.kind !== "runtime")
+        .map((zone) => zone.path);
+    const defaultNote = (schema?.zones ?? []).find((zone) => zone.role === "output" && zone.kind === "file")?.path ?? null;
+    return {
+        kind: "compiled-view-spec",
+        version: 2,
+        generated_at: generatedAt,
+        target_name: compiledName,
+        health_source: ".interf/runtime/health.json",
+        state_source: ".interf/runtime/state.json",
+        default_note: defaultNote,
+        graph_scope: outputDocumentPaths,
+        cards: [
+            { id: "source-total", label: "Source Files", metric: "source_total", format: "number" },
+            { id: "stage-total", label: "Stages", metric: "stage_total", format: "number" },
+            { id: "completed-stages", label: "Completed", metric: "completed_stages", denominator_metric: "stage_total", format: "fraction" },
+        ],
+        sections: [
+            { id: "status", type: "status", title: "Compile Status", path: ".interf/runtime/health.json" },
+            { id: "cards", type: "cards", title: "Key Metrics", path: ".interf/runtime/health.json" },
+            ...(outputDocumentPaths.length > 0
+                ? [{ id: "outputs", type: "documents", title: "Output Zones", paths: outputDocumentPaths }]
+                : []),
+            { id: "workflow", type: "documents", title: "Workflow Docs", paths: ["workflow/README.md", ...workflow.stages.map((stage) => `workflow/compile/stages/${stage.skillDir}`)] },
+        ],
+    };
+}

package/dist/packages/compiler/state.d.ts

@@ -0,0 +1,7 @@
+export type { RuntimeStatus, CompiledStage, CompiledState, CompiledHealth, ViewSection, ViewCard, CompiledViewSpec, CompiledRawSnapshot, } from "./lib/schema.js";
+export { statePath, healthPath, viewSpecPath, rawSnapshotPath, } from "./state-paths.js";
+export { loadState, saveState, loadCompiledHealth, saveCompiledHealth, loadCompiledViewSpec, loadCompiledRawSnapshot, saveCompiledViewSpec, initCompiledState, } from "./state-io.js";
+export { refreshCompiledArtifacts, } from "./state-artifacts.js";
+export { computeCompiledHealth, resolveCompiledStatus, resolveCompiledStage, } from "./state-health.js";
+export { ensureCompiledViewSpec, ensureCompiledRawSnapshot, normalizeCompiledViewSpec, } from "./state-view.js";
+export declare function initializeCompiledRuntimeState(dirPath: string): void;

package/dist/packages/compiler/state.js

@@ -0,0 +1,12 @@
+export { statePath, healthPath, viewSpecPath, rawSnapshotPath, } from "./state-paths.js";
+export { loadState, saveState, loadCompiledHealth, saveCompiledHealth, loadCompiledViewSpec, loadCompiledRawSnapshot, saveCompiledViewSpec, initCompiledState, } from "./state-io.js";
+export { refreshCompiledArtifacts, } from "./state-artifacts.js";
+export { computeCompiledHealth, resolveCompiledStatus, resolveCompiledStage, } from "./state-health.js";
+export { ensureCompiledViewSpec, ensureCompiledRawSnapshot, normalizeCompiledViewSpec, } from "./state-view.js";
+import { saveEmptyCompiledInventory, initCompiledState, saveState } from "./state-io.js";
+import { refreshCompiledArtifacts } from "./state-artifacts.js";
+export function initializeCompiledRuntimeState(dirPath) {
+    saveState(dirPath, initCompiledState());
+    saveEmptyCompiledInventory(dirPath);
+    refreshCompiledArtifacts(dirPath, { ensureViewSpec: true });
+}

package/dist/packages/compiler/validate-compiled.d.ts

@@ -0,0 +1,27 @@
+export interface CompiledValidationSummary {
+    config_present: boolean;
+    config_valid: boolean;
+    config_type_match: boolean;
+    workflow_present: boolean;
+    workflow_valid: boolean;
+    schema_present: boolean;
+    schema_valid: boolean;
+}
+export interface CompiledStageValidation {
+    ok: boolean;
+    required: boolean;
+    stage: string;
+    summary: string;
+    counts: Record<string, number>;
+    checks: Record<string, boolean>;
+    errors: string[];
+}
+export interface CompiledWorkflowValidation extends CompiledStageValidation {
+    stage_results: Record<string, boolean>;
+}
+export declare function validateCompiled(dirPath: string): CompiledValidationSummary;
+export declare function validateCompiledStage(dirPath: string, stageId: string): CompiledStageValidation;
+export declare function validateCompiledWorkflow(dirPath: string): CompiledWorkflowValidation;
+export declare function validateCompiledSummarize(dirPath: string): CompiledStageValidation;
+export declare function validateCompiledStructure(dirPath: string): CompiledStageValidation;
+export declare function validateCompiledCompile(dirPath: string): CompiledWorkflowValidation;