@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/runtime/build/check-evaluator.js

@@ -0,0 +1,575 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { parseJsonFrontmatter } from "../../contracts/utils/parse.js";
+import { CheckKindSchema, SourceManifestSchema, } from "../../contracts/lib/schema.js";
+import { countBrokenWikilinks, isOutputMarkdownFile, validateSynthFiles, } from "./validate.js";
+/**
+ * Build a CheckResult envelope from an evaluator outcome. Centralizes the
+ * timestamp + required-flag plumbing so individual evaluators can
+ * focus on the pass/fail decision and a one-line summary.
+ */
+function makeCheckResult(check, passed, summary, details) {
+    return {
+        check_id: check.id,
+        kind: check.kind,
+        passed,
+        required: check.required,
+        summary,
+        ...(details !== undefined ? { details } : {}),
+        evaluated_at: new Date().toISOString(),
+    };
+}
+function resolveTargetPath(check, context) {
+    const target = context.targetPath;
+    if (!target)
+        return null;
+    const root = resolve(context.rootPath);
+    const absolute = resolve(root, target);
+    // Defense in depth — schema-level validation already rejects path
+    // traversal, but a hand-edited Build Plan or stale on-disk fixture could
+    // slip through. Reject anything that escapes the root.
+    if (absolute !== root && !absolute.startsWith(`${root}/`)) {
+        return null;
+    }
+    return absolute;
+}
+function listMarkdownFiles(absolutePath) {
+    if (!existsSync(absolutePath))
+        return [];
+    try {
+        const stats = statSync(absolutePath);
+        if (stats.isFile()) {
+            return isOutputMarkdownFile(absolutePath) ? [absolutePath] : [];
+        }
+        if (stats.isDirectory()) {
+            return listFilesRecursive(absolutePath, isOutputMarkdownFile);
+        }
+    }
+    catch {
+        return [];
+    }
+    return [];
+}
+function countFiles(absolutePath) {
+    if (!existsSync(absolutePath))
+        return 0;
+    try {
+        const stats = statSync(absolutePath);
+        if (stats.isFile())
+            return 1;
+        if (stats.isDirectory()) {
+            return listFilesRecursive(absolutePath, () => true).length;
+        }
+    }
+    catch {
+        return 0;
+    }
+    return 0;
+}
+function countSourceSummaryFolders(absolutePath, options) {
+    if (!existsSync(absolutePath))
+        return { actual: 0, missingSummary: [] };
+    try {
+        const stats = statSync(absolutePath);
+        if (!stats.isDirectory())
+            return { actual: 0, missingSummary: [] };
+        const missingSummary = [];
+        let actual = 0;
+        for (const entry of readdirSync(absolutePath, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dirPath = join(absolutePath, entry.name);
+            const hasSummary = existsSync(join(dirPath, options.summaryFile));
+            const hasManifest = existsSync(join(dirPath, options.manifestFile));
+            if (hasSummary || hasManifest) {
+                actual += 1;
+            }
+            else {
+                missingSummary.push(entry.name);
+            }
+        }
+        return { actual, missingSummary };
+    }
+    catch {
+        return { actual: 0, missingSummary: [] };
+    }
+}
+function summaryDirectoriesWithEvidence(absolutePath, options) {
+    const dirs = new Set();
+    if (!existsSync(absolutePath))
+        return dirs;
+    for (const file of listFilesRecursive(absolutePath, () => true)) {
+        const name = basename(file);
+        if (name !== options.summaryFile && name !== options.manifestFile)
+            continue;
+        dirs.add(relative(absolutePath, dirname(file)).replaceAll("\\", "/"));
+    }
+    return dirs;
+}
+function sourceSummaryFolderCandidates(sourcePath, sourceFileId, basenameCounts) {
+    const normalized = sourcePath.replaceAll("\\", "/");
+    const base = basename(normalized);
+    const candidates = [
+        normalized,
+        sourceFileId,
+        basenameCounts.get(base) === 1 ? base : "",
+    ].filter((candidate) => candidate.length > 0);
+    return [...new Set(candidates)];
+}
+function sourceSummaryCoverage(absolutePath, manifest, options) {
+    const evidenceDirs = summaryDirectoriesWithEvidence(absolutePath, options);
+    const matchedDirs = new Set();
+    const missingSourcePaths = [];
+    const basenameCounts = new Map();
+    for (const sourceFile of manifest.files) {
+        const base = basename(sourceFile.path.replaceAll("\\", "/"));
+        basenameCounts.set(base, (basenameCounts.get(base) ?? 0) + 1);
+    }
+    for (const sourceFile of manifest.files) {
+        const candidates = sourceSummaryFolderCandidates(sourceFile.path, sourceFile.id, basenameCounts);
+        const matched = candidates.find((candidate) => evidenceDirs.has(candidate));
+        if (matched) {
+            matchedDirs.add(matched);
+        }
+        else {
+            missingSourcePaths.push(sourceFile.path);
+        }
+    }
+    return {
+        actual: manifest.files.length - missingSourcePaths.length,
+        expected: manifest.source_total,
+        missingSourcePaths,
+        extraSummaryFolders: [...evidenceDirs].filter((dir) => !matchedDirs.has(dir)).sort((left, right) => left.localeCompare(right)),
+    };
+}
+function checkPhrases(check) {
+    if (Array.isArray(check.params?.phrases)) {
+        return check.params.phrases.filter((phrase) => typeof phrase === "string");
+    }
+    if (typeof check.params?.text === "string") {
+        return [check.params.text];
+    }
+    return [];
+}
+function frontmatterKeys(check) {
+    return Array.isArray(check.params?.keys)
+        ? check.params.keys.filter((key) => typeof key === "string" && key.trim().length > 0)
+        : [];
+}
+function hasNonEmptyFrontmatterValue(value) {
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (typeof value === "number" || typeof value === "boolean")
+        return true;
+    if (Array.isArray(value))
+        return value.some(hasNonEmptyFrontmatterValue);
+    if (value && typeof value === "object")
+        return Object.keys(value).length > 0;
+    return false;
+}
+function collectFrontmatterFailures(files, predicate) {
+    const invalid = [];
+    const missing = [];
+    for (const file of files) {
+        const parsed = parseJsonFrontmatter(readFileSync(file, "utf8"));
+        if (!parsed) {
+            invalid.push(file);
+            continue;
+        }
+        if (!predicate(parsed.frontmatter)) {
+            missing.push(file);
+        }
+    }
+    return { invalid, missing };
+}
+function loadSourceManifestForCheck(context, path = ".interf/runtime/source-manifest.json") {
+    const manifestPath = resolve(context.rootPath, path);
+    if (!existsSync(manifestPath))
+        return { manifest: null, error: `Source Manifest does not exist at ${path}.` };
+    try {
+        const manifest = SourceManifestSchema.parse(JSON.parse(readFileSync(manifestPath, "utf8")));
+        return { manifest, error: null };
+    }
+    catch (error) {
+        return {
+            manifest: null,
+            error: `Source Manifest is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function loadRequiredSourceManifestForCheck(check, context) {
+    const manifestPath = typeof check.params?.manifest_path === "string"
+        ? check.params.manifest_path
+        : ".interf/runtime/source-manifest.json";
+    const loaded = loadSourceManifestForCheck(context, manifestPath);
+    if (loaded.manifest)
+        return { manifest: loaded.manifest, failure: null };
+    return {
+        manifest: null,
+        failure: makeCheckResult(check, false, loaded.error ?? "Source Manifest is required for this source-bound check.", { manifest_path: manifestPath }),
+    };
+}
+function sourceManifestPageTotal(context) {
+    const loaded = loadSourceManifestForCheck(context);
+    if (!loaded.manifest)
+        return { total: 0, error: loaded.error };
+    let total = 0;
+    for (const file of loaded.manifest.files) {
+        const pageUnits = file.inspectable_units.filter((unit) => unit.kind === "page").length;
+        total += pageUnits > 0 ? pageUnits : file.page_count ?? 0;
+    }
+    return { total, error: null };
+}
+const EVALUATORS = {
+    file_exists(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for file_exists check.");
+        }
+        if (!existsSync(target)) {
+            return makeCheckResult(check, false, "File or directory does not exist.", { path: context.targetPath });
+        }
+        try {
+            const stats = statSync(target);
+            if (stats.isFile() && stats.size === 0) {
+                return makeCheckResult(check, false, "File exists but is empty.", { path: context.targetPath });
+            }
+            return makeCheckResult(check, true, `Path exists (${stats.isDirectory() ? "directory" : "file"}).`);
+        }
+        catch {
+            return makeCheckResult(check, false, "Could not stat target path.", { path: context.targetPath });
+        }
+    },
+    source_manifest_valid(check, context) {
+        const manifestPath = typeof check.params?.path === "string"
+            ? check.params.path
+            : ".interf/runtime/source-manifest.json";
+        const loaded = loadSourceManifestForCheck(context, manifestPath);
+        if (!loaded.manifest) {
+            return makeCheckResult(check, false, loaded.error ?? "Source Manifest is invalid.");
+        }
+        return makeCheckResult(check, true, `Source Manifest lists ${loaded.manifest.source_total} source file(s).`, { source_manifest_id: loaded.manifest.manifest_id, source_total: loaded.manifest.source_total });
+    },
+    min_file_count(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for min_file_count check.");
+        }
+        const min = typeof check.params?.min === "number" ? check.params.min : 1;
+        const actual = countFiles(target);
+        if (actual >= min) {
+            return makeCheckResult(check, true, `${actual} file(s) (≥ ${min}).`, { actual, min });
+        }
+        return makeCheckResult(check, false, `Found ${actual} file(s); expected at least ${min}.`, { actual, min });
+    },
+    min_file_count_matches_source(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for min_file_count_matches_source check.");
+        }
+        const sourceManifest = loadRequiredSourceManifestForCheck(check, context);
+        if (!sourceManifest.manifest)
+            return sourceManifest.failure ?? makeCheckResult(check, false, "Source Manifest is required.");
+        const matchKey = typeof check.params?.match === "string" ? check.params.match : "source_total";
+        const expected = matchKey === "source_total"
+            ? sourceManifest.manifest.source_total
+            : context.counts?.[matchKey];
+        if (typeof expected !== "number") {
+            return makeCheckResult(check, false, `Cannot evaluate: count "${matchKey}" not available in context.`, { matchKey });
+        }
+        if (expected <= 0) {
+            return makeCheckResult(check, false, `Cannot evaluate: count "${matchKey}" must be greater than zero.`, { matchKey, expected });
+        }
+        const actual = countFiles(target);
+        if (actual >= expected) {
+            return makeCheckResult(check, true, `${actual} of ${expected} source files covered.`, { actual, expected, source_manifest_id: sourceManifest.manifest.manifest_id });
+        }
+        return makeCheckResult(check, false, `Only ${actual} of ${expected} source files covered.`, { actual, expected, matchKey, source_manifest_id: sourceManifest.manifest.manifest_id });
+    },
+    source_summary_folders(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for source_summary_folders check.");
+        }
+        const sourceManifest = loadRequiredSourceManifestForCheck(check, context);
+        if (!sourceManifest.manifest)
+            return sourceManifest.failure ?? makeCheckResult(check, false, "Source Manifest is required.");
+        const matchKey = typeof check.params?.match === "string" ? check.params.match : "source_total";
+        const expected = matchKey === "source_total"
+            ? sourceManifest.manifest.source_total
+            : context.counts?.[matchKey];
+        if (typeof expected !== "number") {
+            return makeCheckResult(check, false, `Cannot evaluate: count "${matchKey}" not available in context.`, { matchKey });
+        }
+        if (expected <= 0) {
+            return makeCheckResult(check, false, `Cannot evaluate: count "${matchKey}" must be greater than zero.`, { matchKey, expected });
+        }
+        const summaryFile = typeof check.params?.summary_file === "string" ? check.params.summary_file : "summary.md";
+        const manifestFile = typeof check.params?.manifest_file === "string" ? check.params.manifest_file : "manifest.md";
+        const coverage = matchKey === "source_total"
+            ? sourceSummaryCoverage(target, sourceManifest.manifest, { summaryFile, manifestFile })
+            : {
+                ...countSourceSummaryFolders(target, { summaryFile, manifestFile }),
+                expected,
+                missingSourcePaths: [],
+                extraSummaryFolders: [],
+            };
+        if (coverage.actual >= expected) {
+            return makeCheckResult(check, true, `${coverage.actual} source summary folder(s) covered for ${expected} source file(s).`, {
+                actual: coverage.actual,
+                expected,
+                summaryFile,
+                manifestFile,
+                source_manifest_id: sourceManifest.manifest.manifest_id,
+                extraSummaryFolders: coverage.extraSummaryFolders,
+            });
+        }
+        return makeCheckResult(check, false, `Only ${coverage.actual} source summary folder(s) covered for ${expected} source file(s).`, {
+            actual: coverage.actual,
+            expected,
+            matchKey,
+            summaryFile,
+            manifestFile,
+            missingSourcePaths: coverage.missingSourcePaths,
+            extraSummaryFolders: coverage.extraSummaryFolders,
+        });
+    },
+    source_page_coverage(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for source_page_coverage check.");
+        }
+        const expected = sourceManifestPageTotal(context);
+        if (expected.error)
+            return makeCheckResult(check, false, expected.error);
+        if (expected.total <= 0) {
+            if (check.params?.allow_no_pages === true) {
+                return makeCheckResult(check, true, "Source Manifest does not declare page-level units.");
+            }
+            return makeCheckResult(check, false, "Source Manifest does not declare page-level units. Add page_count or page inspectable_units, or set params.allow_no_pages explicitly.");
+        }
+        const pagesDir = typeof check.params?.pages_dir === "string" ? check.params.pages_dir : "pages";
+        const summaryFile = typeof check.params?.summary_file === "string" ? check.params.summary_file : "summary.md";
+        const actual = listFilesRecursive(target)
+            .filter((file) => file.endsWith(`/${summaryFile}`) && file.includes(`/${pagesDir}/`))
+            .length;
+        if (actual >= expected.total) {
+            return makeCheckResult(check, true, `${actual} page summary file(s) cover ${expected.total} page unit(s).`, { actual, expected: expected.total });
+        }
+        return makeCheckResult(check, false, `Only ${actual} page summary file(s) cover ${expected.total} page unit(s).`, { actual, expected: expected.total, pagesDir, summaryFile });
+    },
+    frontmatter_valid(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for frontmatter_valid check.");
+        }
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeCheckResult(check, true, "No markdown files to validate.");
+        }
+        const validation = validateSynthFiles(files);
+        if (validation.invalid_frontmatter === 0) {
+            return makeCheckResult(check, true, `${files.length} markdown file(s) have valid frontmatter.`);
+        }
+        return makeCheckResult(check, false, `${validation.invalid_frontmatter} of ${files.length} markdown file(s) have invalid frontmatter.`, { invalid: validation.invalid_frontmatter, total: files.length });
+    },
+    frontmatter_required_keys(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for frontmatter_required_keys check.");
+        }
+        const keys = Array.isArray(check.params?.keys) ? check.params.keys.filter((k) => typeof k === "string") : [];
+        if (keys.length === 0) {
+            return makeCheckResult(check, false, "Build Plan check is missing required frontmatter keys. Use `params.keys: string[]`.");
+        }
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeCheckResult(check, true, "No markdown files to validate.");
+        }
+        const validation = validateSynthFiles(files, { requiredFrontmatterKeys: keys });
+        if (validation.invalid_frontmatter === 0) {
+            return makeCheckResult(check, true, `All ${files.length} markdown file(s) have required keys: ${keys.join(", ")}.`);
+        }
+        return makeCheckResult(check, false, `${validation.invalid_frontmatter} of ${files.length} file(s) missing required keys (${keys.join(", ")}).`, { invalid: validation.invalid_frontmatter, total: files.length, requiredKeys: keys });
+    },
+    frontmatter_nonempty_keys(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for frontmatter_nonempty_keys check.");
+        }
+        const keys = frontmatterKeys(check);
+        if (keys.length === 0) {
+            return makeCheckResult(check, false, "Build Plan check is missing non-empty frontmatter keys. Use `params.keys: string[]`.");
+        }
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeCheckResult(check, false, "No markdown files to validate.");
+        }
+        const { invalid, missing } = collectFrontmatterFailures(files, (frontmatter) => keys.every((key) => hasNonEmptyFrontmatterValue(frontmatter[key])));
+        if (invalid.length === 0 && missing.length === 0) {
+            return makeCheckResult(check, true, `All ${files.length} markdown file(s) have non-empty keys: ${keys.join(", ")}.`);
+        }
+        return makeCheckResult(check, false, `${invalid.length + missing.length} of ${files.length} markdown file(s) are missing non-empty keys (${keys.join(", ")}).`, { invalid, missing, requiredKeys: keys });
+    },
+    source_refs_required(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for source_refs_required check.");
+        }
+        const keys = frontmatterKeys(check);
+        const sourceRefKeys = keys.length > 0 ? keys : ["source_refs", "source_ref", "source_path"];
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeCheckResult(check, false, "No markdown files to validate.");
+        }
+        const { invalid, missing } = collectFrontmatterFailures(files, (frontmatter) => sourceRefKeys.some((key) => hasNonEmptyFrontmatterValue(frontmatter[key])));
+        if (invalid.length === 0 && missing.length === 0) {
+            return makeCheckResult(check, true, `All ${files.length} markdown file(s) have source refs.`);
+        }
+        return makeCheckResult(check, false, `${invalid.length + missing.length} of ${files.length} markdown file(s) are missing source refs.`, { invalid, missing, sourceRefKeys });
+    },
+    wikilinks_valid(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeCheckResult(check, false, "No target path provided for wikilinks_valid check.");
+        }
+        const broken = countBrokenWikilinks(context.rootPath, [context.rootPath], [target]);
+        if (broken === 0) {
+            return makeCheckResult(check, true, "All wikilinks resolve.");
+        }
+        return makeCheckResult(check, false, `${broken} broken wikilink(s).`, { broken });
+    },
+    must_not_contain(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target || !existsSync(target)) {
+            return makeCheckResult(check, false, "Target path does not exist.", { path: context.targetPath });
+        }
+        const phrases = checkPhrases(check);
+        if (phrases.length === 0) {
+            return makeCheckResult(check, false, "Artifact diagnostic is missing forbidden text. Use `params.phrases: string[]` or `params.text: string`.");
+        }
+        try {
+            const stats = statSync(target);
+            const files = stats.isFile() ? [target] : listFilesRecursive(target, () => true);
+            const offenders = [];
+            for (const file of files) {
+                const content = readFileSync(file, "utf8");
+                for (const phrase of phrases) {
+                    if (content.includes(phrase)) {
+                        offenders.push(`${file}: contains "${phrase}"`);
+                        break;
+                    }
+                }
+            }
+            if (offenders.length === 0) {
+                return makeCheckResult(check, true, `No forbidden phrases found across ${files.length} file(s).`);
+            }
+            return makeCheckResult(check, false, `${offenders.length} file(s) contain forbidden phrases.`, { offenders, phrases });
+        }
+        catch (error) {
+            return makeCheckResult(check, false, `Error reading target: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+    must_contain(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target || !existsSync(target)) {
+            return makeCheckResult(check, false, "Target path does not exist.", { path: context.targetPath });
+        }
+        const phrases = checkPhrases(check);
+        if (phrases.length === 0) {
+            return makeCheckResult(check, false, "Artifact diagnostic is missing required text. Use `params.phrases: string[]` or `params.text: string`.");
+        }
+        try {
+            const stats = statSync(target);
+            // For directories, must_contain checks across ALL files (every phrase
+            // must appear in at least one file). For files, all phrases must
+            // appear in that single file.
+            if (stats.isFile()) {
+                const content = readFileSync(target, "utf8");
+                const missing = phrases.filter((phrase) => !content.includes(phrase));
+                if (missing.length === 0) {
+                    return makeCheckResult(check, true, `All ${phrases.length} required phrase(s) present.`);
+                }
+                return makeCheckResult(check, false, `${missing.length} required phrase(s) missing.`, { missing });
+            }
+            const files = listFilesRecursive(target, () => true);
+            const remaining = new Set(phrases);
+            for (const file of files) {
+                const content = readFileSync(file, "utf8");
+                for (const phrase of [...remaining]) {
+                    if (content.includes(phrase))
+                        remaining.delete(phrase);
+                }
+                if (remaining.size === 0)
+                    break;
+            }
+            if (remaining.size === 0) {
+                return makeCheckResult(check, true, `All ${phrases.length} required phrase(s) found across files.`);
+            }
+            return makeCheckResult(check, false, `${remaining.size} required phrase(s) missing across all files.`, { missing: [...remaining] });
+        }
+        catch (error) {
+            return makeCheckResult(check, false, `Error reading target: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+    qa_match(check, context) {
+        const expected = typeof check.params?.expected === "string" ? check.params.expected : "";
+        const strictness = typeof check.params?.strictness === "string" ? check.params.strictness : "loose";
+        const answer = context.agentAnswer ?? "";
+        if (!expected) {
+            return makeCheckResult(check, false, "qa_match check requires `params.expected: string`.");
+        }
+        if (!answer) {
+            return makeCheckResult(check, false, "No agent answer available for qa_match evaluation.");
+        }
+        if (strictness === "strict") {
+            const passed = answer.trim() === expected.trim();
+            return makeCheckResult(check, passed, passed ? "Answer matches expected exactly." : "Answer does not match expected.");
+        }
+        // Loose: case-insensitive substring match either direction.
+        const a = answer.trim().toLowerCase();
+        const e = expected.trim().toLowerCase();
+        const passed = a.includes(e) || e.includes(a);
+        return makeCheckResult(check, passed, passed ? "Answer matches expected (loose)." : "Answer does not match expected.");
+    },
+};
+/**
+ * Evaluate a single Check against a context, returning a CheckResult.
+ */
+export function evaluateCheck(check, context) {
+    const evaluator = EVALUATORS[check.kind];
+    if (!evaluator) {
+        return {
+            check_id: check.id,
+            kind: check.kind,
+            passed: false,
+            required: check.required,
+            summary: `Unknown check kind: ${check.kind}`,
+            evaluated_at: new Date().toISOString(),
+        };
+    }
+    return evaluator(check, context);
+}
+/**
+ * Evaluate a list of checks. Aggregate ready/not_ready verdict over
+ * the check_results: `ready` if every required check passed, otherwise
+ * `not_ready`. Soft checks (required: false) that fail produce a
+ * check result but don't change the verdict.
+ */
+export function evaluateChecks(checks, context) {
+    const check_results = checks.map((check) => evaluateCheck(check, context));
+    const failures = check_results.filter((result) => !result.passed && result.required);
+    return {
+        check_results,
+        ready: failures.length === 0,
+        failures,
+    };
+}
+/**
+ * Type guard for the canonical CheckKinds. Useful at parse boundaries
+ * where a string came from on-disk JSON.
+ */
+export function isCheckKind(value) {
+    return CheckKindSchema.safeParse(value).success;
+}

package/dist/packages/runtime/build/context-graph-paths.d.ts

@@ -0,0 +1,51 @@
+export declare const CONTEXT_GRAPH_INTERF_DIR = ".interf";
+export declare const CONTEXT_GRAPH_CONFIG_FILE = "interf.json";
+export declare const CONTEXT_GRAPH_BUILD_PLAN_DIR = "build-plan";
+export declare const CONTEXT_GRAPH_TEST_DIR = "tests";
+export declare const CONTEXT_GRAPH_TEST_TARGETS_DIR = "targets";
+export declare const CONTEXT_GRAPH_RUNTIME_DIR = "runtime";
+export declare const CONTEXT_GRAPH_RUNTIME_STATE_FILE = "state.json";
+export declare const CONTEXT_GRAPH_RUNTIME_HEALTH_FILE = "health.json";
+export declare const CONTEXT_GRAPH_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
+export declare const CONTEXT_GRAPH_RUNTIME_SOURCE_MANIFEST_FILE = "source-manifest.json";
+export declare const CONTEXT_GRAPH_RUNTIME_SOURCE_MANIFEST_AUDIT_FILE = "source-manifest.audit.json";
+export declare const CONTEXT_GRAPH_RUNTIME_SOURCE_FILES_FILE = "source-files.json";
+export declare const CONTEXT_GRAPH_RUNTIME_SOURCE_STATE_FILE = "source-state.json";
+export declare const CONTEXT_GRAPH_RUNTIME_STAGE_INPUTS_DIR = "stages";
+export declare const CONTEXT_GRAPH_RUNTIME_STAGE_INPUTS_FILE = "inputs.json";
+export declare const CONTEXT_GRAPH_RUNTIME_INVENTORY_FILE = "inventory.json";
+export declare const CONTEXT_GRAPH_RUNTIME_RUN_FILE = "run.json";
+export declare const CONTEXT_GRAPH_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
+export declare const CONTEXT_GRAPH_RUNTIME_STAGE_CONTRACT_FILE = "stage-contract.json";
+export declare function contextGraphRuntimeRoot(contextGraphPath: string): string;
+export declare function contextGraphRuntimeFilePath(contextGraphPath: string, fileName: string): string;
+export declare function contextGraphInterfRoot(contextGraphPath: string): string;
+export declare function contextGraphInterfConfigPath(contextGraphPath: string): string;
+export declare function buildPlanPackagePathForContextGraph(contextGraphPath: string): string;
+export declare function testRootForContextGraph(contextGraphPath: string): string;
+export declare function testTargetsRootForContextGraph(contextGraphPath: string): string;
+export declare function stageExecutionShellsRoot(contextGraphPath: string): string;
+export declare function buildPlanImprovementLoopsRoot(contextGraphPath: string): string;
+export declare function buildPlanImprovementRunRoot(contextGraphPath: string, runId: string): string;
+export declare function buildPlanImprovementLoopRoot(contextGraphPath: string, runId: string, loopIndex: number): string;
+export declare function targetTestRunsRootForContextGraph(contextGraphPath: string): string;
+export declare function targetTestSandboxesRootForContextGraph(contextGraphPath: string): string;
+export declare function contextGraphRuntimeLogsRoot(contextGraphPath: string): string;
+export declare function contextGraphRuntimeArchivedStageContractPath(contextGraphPath: string, runId: string): string;
+export declare function contextGraphQueryAcceptanceRoot(contextGraphPath: string): string;
+export declare function contextGraphRuntimeStatePath(contextGraphPath: string): string;
+export declare function contextGraphRuntimeHealthPath(contextGraphPath: string): string;
+export declare function contextGraphRuntimeViewSpecPath(contextGraphPath: string): string;
+export declare function contextGraphRuntimeSourceManifestPath(contextGraphPath: string): string;
+export declare function contextGraphRuntimeSourceManifestAuditPath(contextGraphPath: string): string;
+export declare function contextGraphRuntimeSourceFilesPath(contextGraphPath: string): string;
+export declare function contextGraphRuntimeSourceStatePath(contextGraphPath: string): string;
+export declare function contextGraphRuntimeStagesRoot(contextGraphPath: string): string;
+export declare function contextGraphRuntimeStageRoot(contextGraphPath: string, stageId: string): string;
+export declare function contextGraphRuntimeStageInputsPath(contextGraphPath: string, stageId: string): string;
+export declare function contextGraphExecutionInventoryPath(contextGraphPath: string): string;
+export declare function contextGraphExecutionStageLedgerPath(contextGraphPath: string): string;
+export declare function contextGraphExecutionStageLedgerHistoryPath(contextGraphPath: string): string;
+export declare function contextGraphRuntimeStageContractPath(contextGraphPath: string): string;
+export declare function resolveSourceControlPathForContextGraph(contextGraphPath: string): string;
+export declare function defaultControlPathForContextGraph(contextGraphPath: string): string;