@interf/compiler 0.6.1 → 0.6.4

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

@@ -0,0 +1,262 @@
+import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import chalk from "chalk";
+import { countFilesRecursive } from "../shared/filesystem.js";
+import { buildRuntimeExecutorInfo } from "../agents/lib/executors.js";
+import { RuntimeRunSchema, } from "./lib/schema.js";
+import { getWorkflowStageDefinition, getWorkflowStagePosition, getWorkflowStages, } from "../workflow-package/workflow-definitions.js";
+import { archivedStageContractPath, eventLogPath, logsDirPath, promptLogPath, runHistoryPath, runPath, stageContractPath, statusLogPath, } from "./runtime-paths.js";
+import { warnInterf } from "../shared/logger.js";
+export function loadRuntimeRun(dirPath) {
+    const path = runPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const parsed = RuntimeRunSchema.safeParse(raw);
+        if (parsed.success)
+            return parsed.data;
+        warnInterf(`Warning: failed to validate runtime run at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    catch (error) {
+        warnInterf(`Warning: failed to read runtime run at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+export function saveRuntimeRun(dirPath, run) {
+    mkdirSync(dirname(runPath(dirPath)), { recursive: true });
+    writeFileSync(runPath(dirPath), JSON.stringify(run, null, 2) + "\n");
+}
+export function writeStageContract(dirPath, contract) {
+    mkdirSync(dirname(stageContractPath(dirPath)), { recursive: true });
+    const path = stageContractPath(dirPath);
+    writeFileSync(path, JSON.stringify(contract, null, 2) + "\n");
+    return path;
+}
+function writeArchivedStageContract(dirPath, runId, contract) {
+    const path = archivedStageContractPath(dirPath, runId);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(contract, null, 2) + "\n");
+    return path;
+}
+export async function runExecutorStage(options) {
+    const startedRun = startRuntimeRun(options);
+    const prompt = options.buildPrompt(startedRun.activeContractPath);
+    writeRuntimeRunPrompt(options.compiledPath, startedRun.run.run_id, prompt);
+    const executionPath = options.executionPath ?? options.compiledPath;
+    const code = await options.executor.execute(executionPath, prompt, {
+        eventLogPath: eventLogPath(options.compiledPath, startedRun.run.run_id),
+        statusLogPath: statusLogPath(options.compiledPath, startedRun.run.run_id),
+        completionCheck: options.completionCheck,
+    });
+    finalizeRuntimeRun(options.compiledPath, code);
+    return code;
+}
+export async function runExecutorSummarizeStage(options) {
+    const startedRun = startRuntimeRun(options);
+    const prompt = options.buildPrompt(startedRun.activeContractPath);
+    let lastReported = 0;
+    writeRuntimeRunPrompt(options.compiledPath, startedRun.run.run_id, prompt);
+    const executionPath = options.executionPath ?? options.compiledPath;
+    const progressPromise = options.executor.execute(executionPath, prompt, {
+        eventLogPath: eventLogPath(options.compiledPath, startedRun.run.run_id),
+        statusLogPath: statusLogPath(options.compiledPath, startedRun.run.run_id),
+        completionCheck: options.completionCheck,
+    });
+    const timer = setInterval(() => {
+        const currentSummaryCount = countFilesRecursive(join(options.compiledPath, "summaries"));
+        const completed = Math.max(0, Math.min(options.targetCount, currentSummaryCount - options.startingSummaryCount));
+        if (completed <= lastReported)
+            return;
+        lastReported = completed;
+        updateRuntimeRun(options.compiledPath, {
+            counts: {
+                ...startedRun.run.counts,
+                completed_summaries: completed,
+                target_summaries: options.targetCount,
+            },
+            summary: `${options.stageLabel} ${completed}/${options.targetCount} source files into summaries.`,
+        });
+        console.log(chalk.dim(`  STATUS: wrote ${completed}/${options.targetCount} summaries`));
+    }, 10000);
+    try {
+        const code = await progressPromise;
+        finalizeRuntimeRun(options.compiledPath, code);
+        return code;
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+export function beginRuntimeRun(dirPath, run) {
+    saveRuntimeRun(dirPath, run);
+    return run;
+}
+export function updateRuntimeRun(dirPath, patch) {
+    const current = loadRuntimeRun(dirPath);
+    if (!current)
+        return null;
+    const next = {
+        ...current,
+        ...patch,
+        updated_at: new Date().toISOString(),
+    };
+    saveRuntimeRun(dirPath, next);
+    return next;
+}
+export function markRuntimeRunFailedAfterValidation(dirPath, summary) {
+    const current = loadRuntimeRun(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = current.finished_at ?? new Date().toISOString();
+    const next = {
+        ...current,
+        status: "failed",
+        updated_at: new Date().toISOString(),
+        finished_at: finishedAt,
+        exit_code: 1,
+        error: summary,
+        summary,
+    };
+    saveRuntimeRun(dirPath, next);
+    replaceOrAppendRunHistoryEntry(dirPath, next);
+    return next;
+}
+export function markRuntimeRunSucceededAfterValidation(dirPath, summary) {
+    const current = loadRuntimeRun(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = current.finished_at ?? new Date().toISOString();
+    const next = {
+        ...current,
+        status: "succeeded",
+        updated_at: new Date().toISOString(),
+        finished_at: finishedAt,
+        exit_code: 0,
+        error: null,
+        summary,
+    };
+    saveRuntimeRun(dirPath, next);
+    replaceOrAppendRunHistoryEntry(dirPath, next);
+    return next;
+}
+function startRuntimeRun(options) {
+    const runId = createRunId();
+    const generatedAt = new Date().toISOString();
+    const workflowStages = getWorkflowStages(options.workflow, options.workflowSourcePath);
+    const stagePosition = getWorkflowStagePosition(options.workflow, options.stage, options.workflowSourcePath);
+    const stageDefinition = getWorkflowStageDefinition(options.workflow, options.stage, options.workflowSourcePath);
+    const contract = {
+        kind: "interf-stage-contract",
+        version: 1,
+        generated_at: generatedAt,
+        run_id: runId,
+        target_type: "compiled",
+        target_name: options.compiledName,
+        workflow: {
+            id: options.workflow,
+            stage_index: stagePosition?.stageIndex ?? null,
+            stage_total: stagePosition?.stageTotal ?? workflowStages.length,
+            stages: stagePosition?.stages ?? workflowStages,
+        },
+        stage: options.stage,
+        stage_label: stageDefinition?.label ?? options.stageLabel,
+        contract_type: options.contractType,
+        executor: buildRuntimeExecutorInfo(options.executor),
+        instructions: options.contract.instructions,
+        counts: options.contract.counts,
+        ...(options.contract.acceptance ? { acceptance: options.contract.acceptance } : {}),
+        artifacts: options.contract.artifacts,
+        policies: options.contract.policies,
+    };
+    const activeContractPath = writeStageContract(options.compiledPath, contract);
+    const archivedContractPath = writeArchivedStageContract(options.compiledPath, runId, contract);
+    const run = {
+        kind: "interf-run",
+        version: 1,
+        run_id: runId,
+        target_type: "compiled",
+        target_name: options.compiledName,
+        workflow: options.workflow,
+        stage: options.stage,
+        stage_label: stageDefinition?.label ?? options.stageLabel,
+        contract_type: options.contractType,
+        status: "running",
+        executor: buildRuntimeExecutorInfo(options.executor),
+        started_at: generatedAt,
+        updated_at: generatedAt,
+        finished_at: null,
+        contract_path: relative(options.compiledPath, archivedContractPath),
+        ...(options.executionPath ? { execution_path: relative(options.compiledPath, options.executionPath) } : {}),
+        counts: { ...contract.counts },
+        output_artifacts: [...contract.artifacts.writes],
+        logs: {
+            prompt_path: relative(options.compiledPath, promptLogPath(options.compiledPath, runId)),
+            event_stream_path: relative(options.compiledPath, eventLogPath(options.compiledPath, runId)),
+            status_path: relative(options.compiledPath, statusLogPath(options.compiledPath, runId)),
+        },
+        summary: options.summary,
+        exit_code: null,
+        error: null,
+    };
+    return {
+        run: beginRuntimeRun(options.compiledPath, run),
+        activeContractPath: options.executionPath
+            ? "runtime/stage-contract.json"
+            : relative(options.compiledPath, activeContractPath),
+    };
+}
+function finalizeRuntimeRun(dirPath, code) {
+    const current = loadRuntimeRun(dirPath);
+    if (!current)
+        return null;
+    const finishedAt = new Date().toISOString();
+    const next = {
+        ...current,
+        status: code === 0 ? "succeeded" : "failed",
+        updated_at: finishedAt,
+        finished_at: finishedAt,
+        exit_code: code,
+        error: code === 0 ? null : `Executor exited with code ${code}.`,
+        summary: code === 0
+            ? `${current.stage_label} completed successfully.`
+            : `${current.stage_label} failed with exit code ${code}.`,
+    };
+    saveRuntimeRun(dirPath, next);
+    appendFileSync(runHistoryPath(dirPath), JSON.stringify(next) + "\n");
+    return next;
+}
+function writeRuntimeRunPrompt(dirPath, runId, prompt) {
+    mkdirSync(logsDirPath(dirPath), { recursive: true });
+    writeFileSync(promptLogPath(dirPath, runId), `${prompt}\n`);
+}
+function createRunId() {
+    return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function replaceOrAppendRunHistoryEntry(dirPath, run) {
+    const historyPath = runHistoryPath(dirPath);
+    if (!existsSync(historyPath)) {
+        appendFileSync(historyPath, JSON.stringify(run) + "\n");
+        return;
+    }
+    const raw = readFileSync(historyPath, "utf8");
+    const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+    let replaced = false;
+    const nextLines = lines.map((line) => {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.run_id === run.run_id) {
+                replaced = true;
+                return JSON.stringify(run);
+            }
+        }
+        catch {
+            // preserve malformed history lines as-is
+        }
+        return line;
+    });
+    if (!replaced)
+        nextLines.push(JSON.stringify(run));
+    writeFileSync(historyPath, `${nextLines.join("\n")}\n`);
+}

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 "./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 "./compiled-paths.js";
+import { getActiveCompiledWorkflow, resolveRequiredCompiledWorkflowFromConfig } from "../workflow-package/workflow-definitions.js";
+import { listFilesRecursive } from "../shared/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 "../shared/logger.js";
+import { readJsonFileUnchecked, readJsonFileWithSchema } from "../shared/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 "./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 "./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;