@interf/compiler 0.1.8

package/dist/lib/validate.js

@@ -0,0 +1,838 @@
+import { existsSync, readFileSync, } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import { countFilesRecursive, listFilesRecursive } from "./filesystem.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { readInterfConfig, resolveKnowledgeBaseSourcePath } from "./interf.js";
+import { parseJsonFrontmatter, safeReadJsonFile } from "./parse.js";
+import { getInterfaceWorkflow, resolveInterfaceWorkflowFromConfig, } from "./workflow-definitions.js";
+import { InterfaceCoverageSchema, InterfaceRelevantSchema, InterfaceStateSchema, KnowledgeBaseInventorySchema, KnowledgeBaseStateSchema, } from "./schema.js";
+function extractFirstSection(text, headings) {
+    for (const heading of headings) {
+        const section = extractSection(text, heading);
+        if (section)
+            return section;
+    }
+    return null;
+}
+function sectionHasAnyMarker(section, markers) {
+    if (typeof section !== "string")
+        return false;
+    return markers.some((marker) => new RegExp(`(^|\\n)\\s{0,3}#{0,6}\\s*${escapeRegExp(marker)}`, "im").test(section));
+}
+const REQUIRED_DIGEST_FIELDS = [
+    "source_kind",
+    "evidence_tier",
+    "truth_mode",
+    "state",
+];
+const MIN_ABSTRACT_WORDS = 5;
+const WIKILINK_PATTERN = /!?\[\[([^[\]]+)\]\]/g;
+export function validateKnowledgeBase(dirPath) {
+    const config = readKnowledgeBaseConfig(dirPath);
+    const summaryFiles = listFilesRecursive(join(dirPath, "summaries"), isMarkdownFile);
+    const summaryValidation = validateSynthFiles(summaryFiles);
+    const brokenLinks = countBrokenWikilinks(dirPath, [join(dirPath, "summaries"), join(dirPath, "knowledge")], [join(dirPath, "summaries"), join(dirPath, "knowledge")]);
+    return {
+        config_present: config.present,
+        config_valid: config.valid,
+        config_type_match: config.typeMatch("knowledge-base"),
+        summary_frontmatter_valid: summaryValidation.invalid_frontmatter === 0,
+        abstracts_valid: summaryValidation.short_abstracts === 0,
+        invalid_frontmatter: summaryValidation.invalid_frontmatter,
+        short_abstracts: summaryValidation.short_abstracts,
+        broken_links: brokenLinks,
+    };
+}
+export function validateInterfaceKnowledgeBase(dirPath) {
+    const config = readKnowledgeBaseConfig(dirPath);
+    // Resolve knowledge-base path from config
+    const configValue = config.value;
+    const knowledgeBaseConfig = configValue?.knowledge_base;
+    const knowledgeBasePath = knowledgeBaseConfig?.path;
+    const resolvedKnowledgeBasePath = knowledgeBasePath ? resolve(dirPath, knowledgeBasePath) : null;
+    const knowledgeBasePathValid = resolvedKnowledgeBasePath !== null && existsSync(join(resolvedKnowledgeBasePath, "summaries"));
+    const brokenLinks = countBrokenWikilinks(dirPath, [join(dirPath, "knowledge"), join(dirPath, "briefs"), join(dirPath, "summaries")], [join(dirPath, "knowledge"), join(dirPath, "briefs"), join(dirPath, "summaries")]);
+    return {
+        config_present: config.present,
+        config_valid: config.valid,
+        config_type_match: config.typeMatch("interface"),
+        knowledge_base_path_valid: knowledgeBasePathValid,
+        broken_links: brokenLinks,
+    };
+}
+export function validateKnowledgeBaseSummarize(dirPath) {
+    const config = readKnowledgeBaseConfig(dirPath);
+    const configValue = config.value;
+    const sourceConfig = configValue?.source;
+    const sourcePath = resolveKnowledgeBaseSourcePath(dirPath, sourceConfig && typeof sourceConfig.path === "string"
+        ? { type: "knowledge-base", name: basename(dirPath), source: { path: sourceConfig.path } }
+        : null);
+    const discovery = discoverSourceFiles(sourcePath, dirPath);
+    const sourceTotal = discovery.totalCount;
+    const summariesPresent = existsSync(join(dirPath, "summaries"));
+    const summaryFiles = listFilesRecursive(join(dirPath, "summaries"), isMarkdownFile);
+    const summaryValidation = validateSynthFiles(summaryFiles);
+    const summarized = summaryFiles.length;
+    const sourceCovered = Math.min(sourceTotal, summarized);
+    const toExtract = Math.max(0, sourceTotal - sourceCovered);
+    const required = sourceTotal > 0 || summarized > 0;
+    const checks = {
+        config_present: config.present,
+        config_valid: config.valid,
+        config_type_match: config.typeMatch("knowledge-base"),
+        summaries_present: summariesPresent,
+        full_source_coverage: toExtract === 0,
+        summary_frontmatter_valid: summaryValidation.invalid_frontmatter === 0,
+        abstracts_valid: summaryValidation.short_abstracts === 0,
+    };
+    const errors = [];
+    if (!checks.config_present)
+        errors.push("Missing interf.json.");
+    else if (!checks.config_valid)
+        errors.push("Could not parse interf.json.");
+    else if (!checks.config_type_match)
+        errors.push("Config is not a knowledge base.");
+    if (required && !checks.summaries_present)
+        errors.push("Missing summaries/ directory.");
+    if (!checks.full_source_coverage)
+        errors.push("Not every source file has a summary yet.");
+    if (!checks.summary_frontmatter_valid)
+        errors.push("Some summary files have invalid or incomplete frontmatter.");
+    if (!checks.abstracts_valid)
+        errors.push("Some summary files are missing a valid abstract block.");
+    const ok = errors.length === 0;
+    const summary = !required
+        ? "Extract not required yet — no source files discovered."
+        : ok
+            ? `Extract verified — ${sourceCovered}/${sourceTotal} source files are covered by valid summaries.`
+            : `Extract failed — ${errors[0] ?? "incomplete summary coverage."}`;
+    return {
+        ok,
+        required,
+        summary,
+        counts: {
+            source_total: sourceTotal,
+            source_covered: sourceCovered,
+            summarized,
+            to_summarize: toExtract,
+            invalid_frontmatter: summaryValidation.invalid_frontmatter,
+            short_abstracts: summaryValidation.short_abstracts,
+        },
+        checks,
+        errors,
+    };
+}
+export function validateKnowledgeBaseCompile(dirPath) {
+    const extractValidation = validateKnowledgeBaseSummarize(dirPath);
+    const config = readKnowledgeBaseConfig(dirPath);
+    const statePath = join(dirPath, ".interf", "state.json");
+    const inventoryPath = join(dirPath, ".interf", "inventory.json");
+    const statePresent = existsSync(statePath);
+    const inventoryPresent = existsSync(inventoryPath);
+    const state = statePresent
+        ? safeReadJsonFile(statePath, "knowledge-base state")
+        : null;
+    const inventory = inventoryPresent
+        ? safeReadJsonFile(inventoryPath, "knowledge-base inventory")
+        : null;
+    const summarized = countFilesRecursive(join(dirPath, "summaries"));
+    const compiled = asNumber(state?.compiled);
+    const legacyInventoryFiles = Array.isArray(inventory?.files)
+        ? inventory.files.filter((item) => !!item && typeof item === "object")
+        : [];
+    const summaryInventoryFiles = Array.isArray(inventory?.summaries)
+        ? inventory.summaries.filter((item) => !!item && typeof item === "object")
+        : [];
+    const entryInventoryFiles = Array.isArray(inventory?.entries)
+        ? inventory.entries.filter((item) => !!item && typeof item === "object")
+        : [];
+    const inventoryTotal = typeof inventory?.total === "number"
+        ? inventory.total
+        : typeof inventory?.summary_total === "number"
+            ? inventory.summary_total
+            : entryInventoryFiles.length;
+    const inventoryFiles = legacyInventoryFiles.length > 0
+        ? legacyInventoryFiles
+        : summaryInventoryFiles.length > 0
+            ? summaryInventoryFiles
+            : entryInventoryFiles;
+    const frontmatterScanned = legacyInventoryFiles.length > 0
+        ? inventoryFiles.filter((file) => file.frontmatter_scanned === true).length
+        : summaryInventoryFiles.length > 0
+            ? inventoryFiles.filter((file) => typeof file.file === "string" && typeof file.source === "string").length
+            : inventoryFiles.filter((file) => (typeof file.summary === "string" || typeof file.digest === "string") &&
+                typeof file.source === "string").length;
+    const abstractsRead = legacyInventoryFiles.length > 0
+        ? inventoryFiles.filter((file) => file.abstract_read === true).length
+        : summaryInventoryFiles.length > 0
+            ? inventoryFiles.filter((file) => typeof file.status === "string").length
+            : inventoryFiles.filter((file) => typeof file.state === "string").length;
+    const entryAbstractsRead = entryInventoryFiles.length > 0
+        ? entryInventoryFiles.filter((file) => typeof file.abstract === "string" && file.abstract.trim().length > 0).length
+        : 0;
+    const effectiveAbstractsRead = entryInventoryFiles.length > 0 && summaryInventoryFiles.length === 0 && legacyInventoryFiles.length === 0
+        ? Math.max(abstractsRead, entryAbstractsRead)
+        : abstractsRead;
+    const fullReads = asNumber(state?.full_reads);
+    const entityFiles = countFilesRecursive(join(dirPath, "knowledge", "entities"));
+    const claimFiles = countFilesRecursive(join(dirPath, "knowledge", "claims"));
+    const indexFiles = countFilesRecursive(join(dirPath, "knowledge", "indexes"));
+    const outputs = entityFiles + claimFiles + indexFiles;
+    const brokenLinks = countBrokenWikilinks(dirPath, [join(dirPath, "summaries"), join(dirPath, "knowledge")], [join(dirPath, "summaries"), join(dirPath, "knowledge")]);
+    const required = extractValidation.required || outputs > 0 || compiled > 0 || inventoryPresent;
+    const checks = {
+        config_present: config.present,
+        config_valid: config.valid,
+        config_type_match: config.typeMatch("knowledge-base"),
+        summarize_complete: extractValidation.ok && extractValidation.required,
+        state_present: statePresent,
+        state_valid: state !== null && KnowledgeBaseStateSchema.safeParse(state).success,
+        inventory_present: inventoryPresent,
+        inventory_valid: inventory !== null && KnowledgeBaseInventorySchema.safeParse(inventory).success,
+        inventory_complete: Boolean(state?.inventory_complete) === true,
+        inventory_matches_summaries: inventoryTotal === summarized && inventoryFiles.length === summarized,
+        frontmatter_inventory_complete: frontmatterScanned === summarized,
+        abstracts_cover_summaries: asNumber(state?.abstracts_read) >= summarized && effectiveAbstractsRead >= summarized,
+        synced_complete: compiled >= summarized && summarized > 0,
+        outputs_present: outputs > 0,
+        links_valid: brokenLinks === 0,
+    };
+    const errors = [];
+    if (!checks.config_present)
+        errors.push("Missing interf.json.");
+    else if (!checks.config_valid)
+        errors.push("Could not parse interf.json.");
+    else if (!checks.config_type_match)
+        errors.push("Config is not a knowledge base.");
+    if (!checks.summarize_complete)
+        errors.push("Knowledge-base summarize is incomplete or invalid.");
+    if (!checks.state_present)
+        errors.push("Missing .interf/state.json.");
+    else if (!checks.state_valid)
+        errors.push("Could not parse .interf/state.json.");
+    if (!checks.inventory_present)
+        errors.push("Missing .interf/inventory.json.");
+    else if (!checks.inventory_valid)
+        errors.push("Could not parse .interf/inventory.json or it has the wrong shape.");
+    if (checks.inventory_present && checks.inventory_valid && !checks.inventory_complete) {
+        errors.push("state.json does not mark inventory_complete.");
+    }
+    if (checks.inventory_present && checks.inventory_valid && !checks.inventory_matches_summaries) {
+        errors.push("Inventory does not match the summary set.");
+    }
+    if (checks.inventory_present && checks.inventory_valid && !checks.frontmatter_inventory_complete) {
+        errors.push("Not every summary is marked frontmatter_scanned in inventory.");
+    }
+    if (checks.state_present && checks.state_valid && !checks.abstracts_cover_summaries) {
+        errors.push("Abstract review does not cover the full summary set.");
+    }
+    if (checks.state_present && checks.state_valid && !checks.synced_complete) {
+        errors.push("state.json compiled count does not cover the full summary set.");
+    }
+    if (!checks.outputs_present)
+        errors.push("Knowledge-base compile outputs are missing or empty.");
+    const ok = required ? errors.length === 0 : true;
+    const summary = !required
+        ? "Knowledge-base compile not required yet — no summaries exist yet."
+        : ok
+            ? `Knowledge-base compile verified — ${compiled}/${summarized} summaries compiled, ${entityFiles} entities, ${claimFiles} claims.`
+            : `Knowledge-base compile failed — ${errors[0] ?? "incomplete graph compile."}`;
+    return {
+        ok,
+        required,
+        summary,
+        counts: {
+            source_total: extractValidation.counts.source_total,
+            summarized,
+            compiled,
+            inventory_total: inventoryTotal,
+            frontmatter_scanned: frontmatterScanned,
+            abstracts_read: Math.max(asNumber(state?.abstracts_read), effectiveAbstractsRead),
+            full_reads: fullReads,
+            entity_files: entityFiles,
+            claim_files: claimFiles,
+            index_files: indexFiles,
+            outputs,
+        },
+        checks,
+        errors,
+    };
+}
+export function validateInterfacePlan(dirPath) {
+    const config = readKnowledgeBaseConfig(dirPath);
+    const configValue = config.value;
+    const knowledgeBaseConfig = configValue?.knowledge_base;
+    const knowledgeBasePath = knowledgeBaseConfig?.path;
+    const resolvedKnowledgeBasePath = knowledgeBasePath ? resolve(dirPath, knowledgeBasePath) : null;
+    const knowledgeBasePathValid = resolvedKnowledgeBasePath !== null && existsSync(join(resolvedKnowledgeBasePath, "summaries"));
+    const compilePlanPath = join(dirPath, "compile-plan.md");
+    const agentsPath = join(dirPath, "AGENTS.md");
+    const homePath = join(dirPath, "home.md");
+    const compilePlanPresent = existsSync(compilePlanPath);
+    const compilePlanText = compilePlanPresent ? safeReadText(compilePlanPath) : null;
+    const workflowId = resolveInterfaceWorkflowFromConfig(configValue);
+    const sourcePath = knowledgeBasePathValid && resolvedKnowledgeBasePath
+        ? resolveKnowledgeBaseSourcePath(resolvedKnowledgeBasePath)
+        : undefined;
+    const workflow = getInterfaceWorkflow(workflowId, { sourcePath, workspacePath: dirPath });
+    const stageChecks = workflow.stages.map((stage, index) => {
+        const section = compilePlanText
+            ? extractFirstSection(compilePlanText, [
+                `Stage ${index + 1}: ${stage.label}`,
+                `Stage ${index + 1} — ${stage.label}`,
+            ])
+            : null;
+        return {
+            id: stage.id,
+            label: stage.label,
+            contract_type: stage.contractType,
+            present: section !== null,
+            defined: sectionMatchesInterfaceContract(section, stage.contractType),
+        };
+    });
+    const compilePlanSections = stageChecks.every((stage) => stage.present);
+    const stage1Defined = stageChecks[0]?.defined ?? false;
+    const stage2Defined = stageChecks[1]?.defined ?? false;
+    const stage3Defined = stageChecks[2]?.defined ?? false;
+    const allStageDefinitionsValid = stageChecks.every((stage) => stage.defined);
+    const agentsPresent = existsSync(agentsPath);
+    const homePresent = existsSync(homePath);
+    const outputMentions = countMatches(compilePlanText ?? "", /(?:briefs\/|summaries\/|knowledge\/|home\.md)/gi);
+    const required = true;
+    const checks = {
+        config_present: config.present,
+        config_valid: config.valid,
+        config_type_match: config.typeMatch("interface"),
+        knowledge_base_path_valid: knowledgeBasePathValid,
+        compile_plan_present: compilePlanPresent,
+        compile_plan_sections: compilePlanSections,
+        stage1_defined: stage1Defined,
+        stage2_defined: stage2Defined,
+        stage3_defined: stage3Defined,
+        all_stage_definitions_valid: allStageDefinitionsValid,
+        stage_checks: stageChecks,
+        agents_present: agentsPresent,
+        home_present: homePresent,
+    };
+    const errors = [];
+    if (!checks.config_present)
+        errors.push("Missing interf.json.");
+    else if (!checks.config_valid)
+        errors.push("Could not parse interf.json.");
+    else if (!checks.config_type_match)
+        errors.push("Config is not an interface.");
+    if (!checks.knowledge_base_path_valid)
+        errors.push("knowledgeBase.path does not resolve to a valid knowledgeBase.");
+    if (!checks.compile_plan_present)
+        errors.push("Missing compile-plan.md.");
+    else if (!checks.compile_plan_sections)
+        errors.push("compile-plan.md is missing one or more required stage sections.");
+    if (checks.compile_plan_present) {
+        for (const [index, stage] of stageChecks.entries()) {
+            if (!stage.defined) {
+                errors.push(`Stage ${index + 1} ${stage.label.toLowerCase()} plan is incomplete.`);
+            }
+        }
+    }
+    if (!checks.agents_present)
+        errors.push("Missing AGENTS.md.");
+    if (!checks.home_present)
+        errors.push("Missing home.md.");
+    const ok = errors.length === 0;
+    const summary = ok
+        ? `Interface plan verified — ${stageChecks.filter((stage) => stage.defined).length}/${stageChecks.length} stages defined with ${outputMentions} output references.`
+        : `Interface plan failed — ${errors[0] ?? "compile plan is incomplete."}`;
+    return {
+        ok,
+        required,
+        summary,
+        counts: {
+            stage_sections_expected: stageChecks.length,
+            stage_sections_present: stageChecks.filter((stage) => stage.present).length,
+            output_mentions: outputMentions,
+        },
+        checks,
+        errors,
+    };
+}
+export function validateInterfaceRetrieve(dirPath) {
+    const config = readKnowledgeBaseConfig(dirPath);
+    const configValue = config.value;
+    const knowledgeBaseConfig = configValue?.knowledge_base;
+    const knowledgeBasePath = knowledgeBaseConfig?.path;
+    const resolvedKnowledgeBasePath = knowledgeBasePath ? resolve(dirPath, knowledgeBasePath) : null;
+    const knowledgeBasePathValid = resolvedKnowledgeBasePath !== null && existsSync(join(resolvedKnowledgeBasePath, "summaries"));
+    const knowledgeBaseTotal = knowledgeBasePathValid ? countFilesRecursive(join(resolvedKnowledgeBasePath, "summaries")) : 0;
+    const statePath = join(dirPath, ".interf", "state.json");
+    const relevantPath = join(dirPath, ".interf", "relevant.json");
+    const coveragePath = join(dirPath, ".interf", "coverage.json");
+    const statePresent = existsSync(statePath);
+    const relevantPresent = existsSync(relevantPath);
+    const coveragePresent = existsSync(coveragePath);
+    const state = statePresent
+        ? safeReadJsonFile(statePath, "interface state")
+        : null;
+    const relevant = relevantPresent
+        ? safeReadJsonFile(relevantPath, "interface retrieved set")
+        : null;
+    const coverage = coveragePresent
+        ? safeReadJsonFile(coveragePath, "interface coverage proof")
+        : null;
+    const queryStarted = Boolean(state?.retrieve_complete) ||
+        Boolean(state?.analyze_complete) ||
+        Boolean(state?.compile_complete) ||
+        typeof state?.last_retrieve === "string" ||
+        typeof state?.last_analyze === "string" ||
+        typeof state?.last_compile === "string" ||
+        relevantPresent ||
+        coveragePresent;
+    const proof = coverage && typeof coverage.proof === "object" && coverage.proof
+        ? coverage.proof
+        : null;
+    const bridgeRelevantEntries = asFileEntries(relevant?.relevant);
+    const bridgeRejectedEntries = asFileEntries(relevant?.rejected);
+    const bridgeCoverageShape = coverage !== null &&
+        typeof coverage?.query_timestamp === "string" &&
+        typeof coverage?.coverage_complete === "boolean" &&
+        !!coverage?.entities &&
+        typeof coverage.entities === "object" &&
+        !!coverage?.comparators &&
+        typeof coverage.comparators === "object" &&
+        Array.isArray(coverage?.gaps);
+    const derivedRelevantFiles = asStringArray(proof?.retrieved).length > 0
+        ? asStringArray(proof?.retrieved)
+        : bridgeRelevantEntries.map((entry) => entry.file);
+    const relevantFiles = asStringArray(relevant?.relevant_files).length > 0
+        ? asStringArray(relevant?.relevant_files)
+        : derivedRelevantFiles;
+    const deltaFiles = asStringArray(relevant?.delta_files).length > 0
+        ? asStringArray(relevant?.delta_files)
+        : asStringArray(state?.delta_files);
+    const explicitCandidateFiles = asStringArray(coverage?.candidate_files);
+    const scannedFiles = asStringArray(proof?.scanned).length > 0
+        ? asStringArray(proof?.scanned)
+        : dedupeStrings([
+            ...bridgeRelevantEntries.map((entry) => entry.file),
+            ...bridgeRejectedEntries.map((entry) => entry.file),
+        ]);
+    const candidateFiles = explicitCandidateFiles.length > 0
+        ? explicitCandidateFiles
+        : scannedFiles;
+    const abstractReviewedFiles = asStringArray(coverage?.abstract_reviewed_files).length > 0
+        ? asStringArray(coverage?.abstract_reviewed_files)
+        : asStringArray(proof?.reviewed).length > 0
+            ? asStringArray(proof?.reviewed)
+            : candidateFiles;
+    const selectedFiles = asStringArray(coverage?.selected_files).length > 0
+        ? asStringArray(coverage?.selected_files)
+        : derivedRelevantFiles;
+    const rejectedFiles = asRejectedEntries(coverage?.rejected_files);
+    const rejectedPaths = rejectedFiles.length > 0
+        ? rejectedFiles.map((entry) => entry.path)
+        : asStringArray(proof?.excluded).length > 0
+            ? asStringArray(proof?.excluded)
+            : bridgeRejectedEntries.map((entry) => entry.file);
+    const frontmatterScanned = asNumber(coverage?.frontmatter_scanned) ||
+        asNumber(state?.frontmatter_scanned) ||
+        asNumber(relevant?.total_scanned);
+    const candidateCount = asNumber(coverage?.candidates_after_frontmatter) ||
+        asNumber(state?.candidate_count) ||
+        candidateFiles.length;
+    const abstractsRead = asNumber(coverage?.abstracts_reviewed) ||
+        asNumber(state?.abstracts_read) ||
+        abstractReviewedFiles.length;
+    const selectedCount = asNumber(coverage?.relevant_selected) ||
+        asNumber(state?.relevant_count) ||
+        asNumber(relevant?.total_relevant) ||
+        selectedFiles.length;
+    const rejectedCount = asNumber(coverage?.rejected) ||
+        asNumber(state?.rejected_count) ||
+        asNumber(relevant?.total_rejected) ||
+        rejectedPaths.length;
+    const deltaCount = asNumber(state?.delta_count) || deltaFiles.length;
+    const expansionPasses = asNumber(coverage?.expansion_passes) ||
+        asNumber(state?.expansion_passes);
+    const relevantValid = (relevant !== null &&
+        typeof relevant?.generated_at === "string" &&
+        typeof relevant?.knowledge_base_summary_count === "number" &&
+        Array.isArray(relevant?.relevant_files) &&
+        Array.isArray(relevant?.delta_files)) ||
+        (relevant !== null &&
+            typeof relevant?.query_timestamp === "string" &&
+            Array.isArray(relevant?.relevant) &&
+            Array.isArray(relevant?.rejected) &&
+            typeof relevant?.total_scanned === "number" &&
+            typeof relevant?.total_relevant === "number" &&
+            typeof relevant?.total_rejected === "number") ||
+        Array.isArray(proof?.retrieved);
+    const coverageValid = (coverage !== null &&
+        typeof coverage?.generated_at === "string" &&
+        typeof coverage?.knowledge_base_summary_count === "number" &&
+        typeof coverage?.frontmatter_scanned === "number" &&
+        typeof coverage?.expansion_passes === "number" &&
+        Array.isArray(coverage?.candidate_files) &&
+        Array.isArray(coverage?.abstract_reviewed_files) &&
+        Array.isArray(coverage?.selected_files) &&
+        Array.isArray(coverage?.rejected_files) &&
+        rejectedFiles.length === rejectedPaths.length) ||
+        (coverage !== null &&
+            typeof coverage?.generated_at === "string" &&
+            typeof coverage?.knowledge_base_summary_total === "number" &&
+            typeof coverage?.frontmatter_scanned === "number" &&
+            typeof coverage?.candidates_after_frontmatter === "number" &&
+            typeof coverage?.abstracts_reviewed === "number" &&
+            typeof coverage?.relevant_selected === "number" &&
+            typeof coverage?.rejected === "number" &&
+            typeof coverage?.expansion_passes === "number" &&
+            typeof coverage?.coverage_complete === "boolean" &&
+            proof !== null &&
+            Array.isArray(proof.scanned) &&
+            Array.isArray(proof.reviewed) &&
+            Array.isArray(proof.retrieved) &&
+            Array.isArray(proof.excluded)) ||
+        bridgeCoverageShape;
+    const selectedSet = new Set(selectedFiles);
+    const rejectedSet = new Set(rejectedPaths);
+    const candidateSet = new Set(candidateFiles);
+    const scannedSet = new Set(scannedFiles);
+    const abstractSet = new Set(abstractReviewedFiles);
+    const relevantSet = new Set(relevantFiles);
+    const selectedRejectedUnion = new Set([...selectedFiles, ...rejectedPaths]);
+    const usesProofScanCoverage = explicitCandidateFiles.length === 0 &&
+        Array.isArray(proof?.scanned) &&
+        typeof coverage?.candidates_after_frontmatter === "number";
+    const knowledgeBaseCountMatch = knowledgeBasePathValid &&
+        coverageValid &&
+        (relevant !== null && typeof relevant?.knowledge_base_summary_count === "number"
+            ? asNumber(relevant.knowledge_base_summary_count) === knowledgeBaseTotal
+            : frontmatterScanned === knowledgeBaseTotal || candidateCount <= knowledgeBaseTotal) &&
+        (typeof coverage?.knowledge_base_summary_count === "number"
+            ? asNumber(coverage.knowledge_base_summary_count) === knowledgeBaseTotal
+            : typeof coverage?.knowledge_base_summary_total === "number"
+                ? asNumber(coverage?.knowledge_base_summary_total) === knowledgeBaseTotal
+                : frontmatterScanned === knowledgeBaseTotal);
+    const fullFrontmatterScan = knowledgeBasePathValid && coverageValid && frontmatterScanned === knowledgeBaseTotal;
+    const candidatePartitionValid = coverageValid &&
+        setIntersectionSize(selectedSet, rejectedSet) === 0 &&
+        (usesProofScanCoverage
+            ? scannedSet.size === selectedRejectedUnion.size &&
+                isSubset(selectedSet, scannedSet) &&
+                isSubset(rejectedSet, scannedSet)
+            : candidateSet.size === selectedRejectedUnion.size &&
+                isSubset(selectedSet, candidateSet) &&
+                isSubset(rejectedSet, candidateSet));
+    const abstractsCoverCandidates = coverageValid &&
+        (usesProofScanCoverage
+            ? selectedFiles.every((file) => abstractSet.has(file)) &&
+                abstractSet.size >= candidateCount &&
+                abstractsRead >= candidateCount
+            : isSubset(candidateSet, abstractSet));
+    const selectedMatchRelevant = coverageValid &&
+        relevantValid &&
+        setsEqual(selectedSet, relevantSet);
+    const deltaSubset = relevantValid &&
+        isSubset(new Set(deltaFiles), selectedSet);
+    const stateCountsMatch = state !== null &&
+        asNumber(state.frontmatter_scanned) === frontmatterScanned &&
+        asNumber(state.candidate_count) === candidateCount &&
+        asNumber(state.abstracts_read) === abstractsRead &&
+        asNumber(state.expansion_passes) === expansionPasses &&
+        asNumber(state.relevant_count) === selectedCount &&
+        asNumber(state.rejected_count) === rejectedCount &&
+        asNumber(state.delta_count) === deltaCount;
+    const stateFlagsMatch = state !== null &&
+        state.retrieve_complete === true &&
+        state.coverage_complete === true;
+    const checks = {
+        knowledge_base_path_valid: knowledgeBasePathValid,
+        state_present: statePresent,
+        state_valid: state !== null && InterfaceStateSchema.safeParse(state).success,
+        relevant_present: relevantPresent || Array.isArray(proof?.retrieved),
+        relevant_valid: relevantValid ||
+            (relevant !== null && InterfaceRelevantSchema.safeParse(relevant).success),
+        coverage_present: coveragePresent,
+        coverage_valid: coverageValid ||
+            (coverage !== null && InterfaceCoverageSchema.safeParse(coverage).success),
+        knowledge_base_count_match: knowledgeBaseCountMatch,
+        full_frontmatter_scan: fullFrontmatterScan,
+        candidate_partition_valid: candidatePartitionValid,
+        abstracts_cover_candidates: abstractsCoverCandidates,
+        selected_match_relevant: selectedMatchRelevant,
+        delta_subset: deltaSubset,
+        state_counts_match: stateCountsMatch,
+        state_flags_match: stateFlagsMatch,
+    };
+    const errors = [];
+    if (queryStarted) {
+        if (!knowledgeBasePathValid)
+            errors.push("Knowledge base is missing or invalid.");
+        if (!statePresent)
+            errors.push("Missing .interf/state.json.");
+        else if (state === null)
+            errors.push("Could not parse .interf/state.json.");
+        if (!relevantPresent && !Array.isArray(proof?.retrieved))
+            errors.push("Missing .interf/relevant.json.");
+        else if (!relevantValid)
+            errors.push("Could not parse .interf/relevant.json or it has the wrong shape.");
+        if (!coveragePresent)
+            errors.push("Missing .interf/coverage.json.");
+        else if (!coverageValid)
+            errors.push("Could not parse .interf/coverage.json or it has the wrong shape.");
+        if (coveragePresent && coverageValid && !knowledgeBaseCountMatch)
+            errors.push("Coverage proof does not match the current knowledge-base summary count.");
+        if (coveragePresent && coverageValid && !fullFrontmatterScan)
+            errors.push("Coverage proof does not show a full frontmatter scan.");
+        if (coveragePresent && coverageValid && !candidatePartitionValid)
+            errors.push("Candidate, selected, and rejected sets are inconsistent.");
+        if (coveragePresent && coverageValid && !abstractsCoverCandidates)
+            errors.push("Not every candidate file was abstract-reviewed.");
+        if (relevantPresent && coveragePresent && relevantValid && coverageValid && !selectedMatchRelevant) {
+            errors.push("Selected files in coverage proof do not match relevant_files.");
+        }
+        if (relevantPresent && coveragePresent && relevantValid && coverageValid && !deltaSubset) {
+            errors.push("delta_files are not a subset of selected relevant files.");
+        }
+        if (statePresent && state !== null && coveragePresent && coverageValid && relevantPresent && relevantValid && !stateCountsMatch) {
+            errors.push("state.json counts do not match the retrieved set and coverage proof.");
+        }
+        if (statePresent && state !== null && !stateFlagsMatch) {
+            errors.push("state.json is missing retrieve_complete or coverage_complete.");
+        }
+    }
+    const ok = queryStarted ? errors.length === 0 : true;
+    const summary = !queryStarted
+        ? "Coverage not required yet — interface retrieve has not started."
+        : ok
+            ? `Coverage verified — scanned ${frontmatterScanned}/${knowledgeBaseTotal}, reviewed ${abstractsRead} abstracts, selected ${selectedCount}, rejected ${rejectedCount}.`
+            : `Coverage failed — ${errors[0] ?? "inconsistent retrieval proof."}`;
+    return {
+        ok,
+        required: queryStarted,
+        summary,
+        counts: {
+            knowledge_base_total: knowledgeBaseTotal,
+            frontmatter_scanned: frontmatterScanned,
+            candidate_count: candidateCount,
+            abstracts_read: abstractsRead,
+            selected_count: selectedCount,
+            rejected_count: rejectedCount,
+            delta_count: deltaCount,
+            expansion_passes: expansionPasses,
+        },
+        checks,
+        errors,
+    };
+}
+function readKnowledgeBaseConfig(dirPath) {
+    const configPath = join(dirPath, "interf.json");
+    const present = existsSync(configPath);
+    if (!present) {
+        return {
+            present: false,
+            valid: false,
+            value: null,
+            typeMatch: () => false,
+        };
+    }
+    const value = readInterfConfig(dirPath);
+    return {
+        present: true,
+        valid: value !== null,
+        value,
+        typeMatch(expected) {
+            return value?.type === expected;
+        },
+    };
+}
+function validateSynthFiles(files) {
+    let invalidFrontmatter = 0;
+    let shortAbstracts = 0;
+    for (const filePath of files) {
+        const content = safeReadText(filePath);
+        if (content === null)
+            continue;
+        const parsed = parseMarkdownFrontmatter(content);
+        if (!parsed || !hasRequiredSynthFields(parsed.frontmatter)) {
+            invalidFrontmatter += 1;
+            continue;
+        }
+        const abstractWords = countAbstractWords(parsed.frontmatter, parsed.body);
+        if (abstractWords < MIN_ABSTRACT_WORDS) {
+            shortAbstracts += 1;
+        }
+    }
+    return {
+        invalid_frontmatter: invalidFrontmatter,
+        short_abstracts: shortAbstracts,
+    };
+}
+function countBrokenWikilinks(knowledgeBaseRoot, noteIndexRoots, linkScanRoots) {
+    const noteIndex = new Set();
+    for (const filePath of dedupeFiles(noteIndexRoots)) {
+        noteIndex.add(noteName(filePath).toLowerCase());
+    }
+    let brokenLinks = 0;
+    for (const filePath of dedupeFiles(linkScanRoots)) {
+        const content = safeReadText(filePath);
+        if (content === null)
+            continue;
+        const matches = content.matchAll(WIKILINK_PATTERN);
+        for (const match of matches) {
+            const rawTarget = match[1]?.trim();
+            if (!rawTarget)
+                continue;
+            const target = rawTarget.split("|")[0]?.split("#")[0]?.trim();
+            if (!target)
+                continue;
+            if (target.includes("/")) {
+                const directPath = join(knowledgeBaseRoot, target);
+                const markdownPath = directPath.endsWith(".md")
+                    ? directPath
+                    : `${directPath}.md`;
+                if (!existsSync(directPath) && !existsSync(markdownPath)) {
+                    brokenLinks += 1;
+                }
+                continue;
+            }
+            if (!noteIndex.has(target.toLowerCase())) {
+                brokenLinks += 1;
+            }
+        }
+    }
+    return brokenLinks;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+function asRejectedEntries(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => !!item &&
+        typeof item === "object" &&
+        typeof item.path === "string" &&
+        typeof item.reason === "string");
+}
+function asFileEntries(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => !!item &&
+        typeof item === "object" &&
+        typeof item.file === "string");
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function isSubset(left, right) {
+    for (const item of left) {
+        if (!right.has(item))
+            return false;
+    }
+    return true;
+}
+function setsEqual(left, right) {
+    return left.size === right.size && isSubset(left, right);
+}
+function setIntersectionSize(left, right) {
+    let count = 0;
+    for (const item of left) {
+        if (right.has(item))
+            count += 1;
+    }
+    return count;
+}
+function dedupeStrings(values) {
+    return Array.from(new Set(values));
+}
+function extractSection(content, heading) {
+    const pattern = new RegExp(`(?:^|\\n)## ${escapeRegExp(heading)}\\s*\\n([\\s\\S]*?)(?=\\n## |\\s*$)`);
+    const match = content.match(pattern);
+    return match?.[1]?.trim() ?? null;
+}
+function sectionMatchesInterfaceContract(section, contractType) {
+    switch (contractType) {
+        case "interface-retrieval":
+            return sectionHasAnyMarker(section, [
+                "Filter criteria",
+                "Categories:",
+                "Priority evidence tiers:",
+                "Truth modes to prioritize or downweight:",
+                "Key entities:",
+                "Expected relevant file count:",
+            ]);
+        case "interface-analysis":
+            return sectionHasAnyMarker(section, [
+                "Batching:",
+                "Claims:",
+                "Entities:",
+                "extract",
+            ]);
+        case "interface-output":
+            return sectionHasAnyMarker(section, [
+                "home.md",
+                "Output files",
+                "briefs/",
+                "knowledge/",
+            ]);
+        default:
+            return false;
+    }
+}
+function countMatches(content, pattern) {
+    return [...content.matchAll(pattern)].length;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function dedupeFiles(dirPaths) {
+    const seen = new Set();
+    const files = [];
+    for (const dirPath of dirPaths) {
+        for (const filePath of listFilesRecursive(dirPath, isMarkdownFile)) {
+            if (seen.has(filePath))
+                continue;
+            seen.add(filePath);
+            files.push(filePath);
+        }
+    }
+    return files;
+}
+function parseMarkdownFrontmatter(content) {
+    return parseJsonFrontmatter(content);
+}
+function hasRequiredSynthFields(frontmatter) {
+    const hasSourceReference = "source" in frontmatter || "source_file" in frontmatter || "raw" in frontmatter;
+    return hasSourceReference && REQUIRED_DIGEST_FIELDS.every((field) => field in frontmatter);
+}
+function countAbstractWords(frontmatter, body) {
+    const frontmatterAbstract = typeof frontmatter.abstract === "string" ? frontmatter.abstract : null;
+    if (frontmatterAbstract && frontmatterAbstract.trim().length > 0) {
+        return countWords(frontmatterAbstract);
+    }
+    const match = body.match(/^## Abstract\s+([\s\S]*?)(?:\n## |\n# |$)/m);
+    if (!match)
+        return 0;
+    return countWords(match[1]);
+}
+function safeReadText(filePath) {
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function countWords(text) {
+    return text
+        .split(/\s+/)
+        .map((word) => word.trim())
+        .filter((word) => /[A-Za-z0-9]/.test(word)).length;
+}
+function noteName(filePath) {
+    return basename(filePath, extname(filePath));
+}
+function isMarkdownFile(filePath) {
+    return extname(filePath) === ".md" && basename(filePath) !== "AGENTS.md";
+}
+//# sourceMappingURL=validate.js.map