@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/build/traces.js

@@ -0,0 +1,133 @@
+/**
+ * Traces builder — evidence rollup for humans.
+ *
+ * Traces are the visible product. "20 of 20 files processed, 847 pages
+ * read, 18 charts extracted, 92 entities found, 12 checks passed." Each
+ * trace rolls up one quantifiable piece of evidence the user can verify
+ * at a glance.
+ *
+ * Traces are derived (not stored): the builder walks the current
+ * Context Graph's artifacts + Checks / benchmark results + source file index and
+ * rolls them into a single Traces wire shape per request. Future
+ * enhancement: cache the rolled-up Traces on the Context Graph manifest
+ * so Context Graph bundles ship with traces attached.
+ */
+function clampObservedCount(value, total) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 0;
+    return Math.min(Math.max(0, Math.trunc(value)), total);
+}
+/**
+ * Build a Traces wire shape from the inputs available after a Build.
+ * Empty/safe when the Project has no Context Graph yet.
+ */
+export function buildTraces(input) {
+    const generatedAt = input.generatedAt ?? new Date().toISOString();
+    const sourceFiles = input.sourceFileCount;
+    // Files-processed is evidence-backed. Source inventory gives the
+    // denominator; accepted Stage Manifest coverage or supplemental diagnostics must provide the
+    // observed value.
+    const filesProcessed = clampObservedCount(input.filesProcessed, sourceFiles);
+    const filesTotal = sourceFiles;
+    const check_results = input.artifacts.flatMap((artifact) => artifact.check_results ?? []);
+    const requiredCheckResults = check_results.filter((result) => result.required !== false);
+    const checksTotal = requiredCheckResults.length;
+    const checksPassed = requiredCheckResults.filter((result) => result.passed).length;
+    // Phase B quantitative signals — sum any stage-emitted counts that surface
+    // through `CheckResult.details`. Stages opt in by writing { pages_read,
+    // charts_extracted, entities_found } into their check-result details; unwired
+    // stages contribute zero. The top-level Traces shape exposes the totals
+    // when at least one stage emitted; otherwise the fields stay undefined.
+    const sumDetail = (key) => {
+        let total = 0;
+        let saw = false;
+        for (const result of check_results) {
+            const raw = result.details?.[key];
+            if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) {
+                total += Math.trunc(raw);
+                saw = true;
+            }
+        }
+        return saw ? total : -1;
+    };
+    const pagesRead = sumDetail("pages_read");
+    const chartsExtracted = sumDetail("charts_extracted");
+    const entitiesFound = sumDetail("entities_found");
+    const items = [];
+    if (sourceFiles > 0) {
+        items.push({
+            kind: "files-processed",
+            label: "Source files processed",
+            count: filesProcessed,
+            total: sourceFiles,
+            passed: filesProcessed >= sourceFiles,
+            detail: filesProcessed >= sourceFiles
+                ? "Accepted coverage records cover every Source file."
+                : `${sourceFiles - filesProcessed} Source file${sourceFiles - filesProcessed === 1 ? "" : "s"} lack accepted coverage records.`,
+        });
+    }
+    if (pagesRead >= 0) {
+        items.push({
+            kind: "pages-read",
+            label: "Pages read",
+            count: pagesRead,
+            passed: true,
+        });
+    }
+    if (chartsExtracted >= 0) {
+        items.push({
+            kind: "charts-extracted",
+            label: "Charts extracted",
+            count: chartsExtracted,
+            passed: true,
+        });
+    }
+    if (entitiesFound >= 0) {
+        items.push({
+            kind: "entities-found",
+            label: "Entities found",
+            count: entitiesFound,
+            passed: true,
+        });
+    }
+    for (const artifact of input.artifacts) {
+        items.push({
+            kind: `artifact:${artifact.artifact_id}`,
+            label: artifact.summary ?? `Artifact ${artifact.artifact_id}`,
+            passed: artifact.status === "ready",
+            detail: artifact.status === "ready"
+                ? "Built; checks passed."
+                : artifact.status === "failed"
+                    ? "Build failed."
+                    : artifact.status === "not_ready"
+                        ? "Checks did not pass."
+                        : "Skipped.",
+        });
+    }
+    if (checksTotal > 0) {
+        items.push({
+            kind: "checks",
+            label: "Checks passed",
+            count: checksPassed,
+            total: checksTotal,
+            passed: checksPassed === checksTotal,
+        });
+    }
+    const ready = input.readiness?.ready ?? false;
+    return {
+        kind: "interf-context-graph-traces",
+        version: 1,
+        generated_at: generatedAt,
+        graph_id: input.graphId,
+        project_id: input.projectId,
+        files_processed: filesProcessed,
+        files_total: filesTotal,
+        checks_passed: checksPassed,
+        checks_total: checksTotal,
+        ready,
+        ...(pagesRead >= 0 ? { pages_read: pagesRead } : {}),
+        ...(chartsExtracted >= 0 ? { charts_extracted: chartsExtracted } : {}),
+        ...(entitiesFound >= 0 ? { entities_found: entitiesFound } : {}),
+        items,
+    };
+}

package/dist/packages/{engine/build/validate-verifiable-context.d.ts → runtime/build/validate-context-graph.d.ts}

@@ -1,4 +1,4 @@
-export interface VerifiableContextValidationSummary {
+export interface ContextGraphValidationSummary {
     config_present: boolean;
     config_valid: boolean;
     config_type_match: boolean;
@@ -16,12 +16,12 @@ export interface BuildStageValidation {
     checks: Record<string, boolean>;
     errors: string[];
 }
-export interface VerifiableContextValidation extends BuildStageValidation {
+export interface ContextGraphValidation extends BuildStageValidation {
     stage_results: Record<string, boolean>;
 }
-export declare function validateVerifiableContextSetup(dirPath: string): VerifiableContextValidationSummary;
+export declare function validateContextGraphSetup(dirPath: string): ContextGraphValidationSummary;
 export declare function validateBuildStage(dirPath: string, stageId: string): BuildStageValidation;
-export declare function validateVerifiableContext(dirPath: string): VerifiableContextValidation;
+export declare function validateContextGraph(dirPath: string): ContextGraphValidation;
 export declare function validateBuildSummarize(dirPath: string): BuildStageValidation;
-export declare function validateVerifiableContextStructure(dirPath: string): BuildStageValidation;
-export declare function validateBuildOutput(dirPath: string): VerifiableContextValidation;
+export declare function validateContextGraphKnowledge(dirPath: string): BuildStageValidation;
+export declare function validateBuildOutput(dirPath: string): ContextGraphValidation;

package/dist/packages/{engine/build/validate-verifiable-context.js → runtime/build/validate-context-graph.js}

@@ -1,21 +1,20 @@
 import { existsSync } from "node:fs";
-import { discoverSourceFiles } from "./discovery.js";
-import { BUILD_PLAN_SCHEMA_FILE, findBuildPlanContextArtifact, readBuildPlanContextFile, buildPlanSchemaExists, } from "./verifiable-context-schema.js";
-import { resolveSourceFolderPath } from "../../project/interf-detect.js";
-import { verifiableContextInterfConfigPath, buildPlanPackagePathForVerifiableContext } from "./verifiable-context-paths.js";
-import { readVerifiableContextConfig } from "./validate.js";
+import { BUILD_PLAN_SCHEMA_FILE, findBuildPlanContextArtifact, readBuildPlanContextFile, buildPlanSchemaExists, } from "./context-graph-schema.js";
+import { contextGraphInterfConfigPath, buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
+import { readContextGraphConfig } from "./validate.js";
 import { loadState } from "./state.js";
 import { getActiveBuildPlan, resolveRequiredBuildPlanFromConfig, } from "../../build-plans/package/build-plan-definitions.js";
 import { countBuildArtifactsAtPath } from "./artifact-counts.js";
 import { evaluateChecks } from "./check-evaluator.js";
+import { loadContextGraphSourceManifest } from "./source-manifest.js";
 function buildPlanSchemaPresent(dirPath) {
-    return buildPlanSchemaExists(buildPlanPackagePathForVerifiableContext(dirPath));
+    return buildPlanSchemaExists(buildPlanPackagePathForContextGraph(dirPath));
 }
 function buildPlanJsonPresent(dirPath) {
-    return existsSync(buildPlanPackagePathForVerifiableContext(dirPath) + "/build-plan.json");
+    return existsSync(buildPlanPackagePathForContextGraph(dirPath) + "/build-plan.json");
 }
 function readBuildPlanValidationContext(dirPath) {
-    const config = readVerifiableContextConfig(dirPath);
+    const config = readContextGraphConfig(dirPath);
     const buildPlanId = config.valid
         ? resolveRequiredBuildPlanFromConfig(config.value, `.interf/interf.json for ${dirPath}`)
         : null;
@@ -28,16 +27,16 @@ function readBuildPlanValidationContext(dirPath) {
             buildPlan = null;
         }
     }
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(dirPath));
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(dirPath));
     const state = loadState(dirPath);
-    const sourceTotal = config.valid
-        ? discoverSourceFiles(resolveSourceFolderPath(dirPath, config.value), dirPath).totalCount
-        : 0;
+    const sourceManifest = loadContextGraphSourceManifest(dirPath);
+    const sourceTotal = sourceManifest?.source_total ?? 0;
     return {
         config,
         buildPlan,
         schema,
         state,
+        sourceManifest,
         sourceTotal,
         buildPlanId,
     };
@@ -45,14 +44,14 @@ function readBuildPlanValidationContext(dirPath) {
 function stageRequired(sourceTotal, writeCounts, stageRecordPresent) {
     return sourceTotal > 0 || writeCounts > 0 || stageRecordPresent;
 }
-function artifactWriteCount(verifiableContextPath, schema, stage) {
+function artifactWriteCount(contextGraphPath, schema, stage) {
     const artifactCounts = {};
     let total = 0;
     for (const artifactId of stage.writes) {
         const artifact = findBuildPlanContextArtifact(schema, artifactId);
         if (!artifact)
             continue;
-        const count = countBuildArtifactsAtPath(verifiableContextPath, artifact.path, artifact.kind);
+        const count = countBuildArtifactsAtPath(contextGraphPath, artifact.path, artifact.kind);
         artifactCounts[artifactId] = count;
         total += count;
     }
@@ -76,7 +75,7 @@ function artifactsBuiltByStage(schema, stage) {
         return artifact.shape.kind === "path" && (stage.writes.includes(artifact.id) || stage.writes.includes(artifact.shape.path));
     });
 }
-function artifactCheckFailures(verifiableContextPath, artifacts, counts) {
+function artifactCheckFailures(contextGraphPath, artifacts, counts) {
     const failures = [];
     for (const artifact of artifacts) {
         const checks = artifact.checks ?? [];
@@ -84,7 +83,7 @@ function artifactCheckFailures(verifiableContextPath, artifacts, counts) {
             continue;
         const targetPath = artifact.shape.kind === "path" ? artifact.shape.path : undefined;
         const result = evaluateChecks(checks, {
-            rootPath: verifiableContextPath,
+            rootPath: contextGraphPath,
             targetPath,
             counts,
         });
@@ -107,7 +106,7 @@ function mergeValidationCounts(sourceTotal, stageRecord, artifactCounts) {
     }
     return merged;
 }
-export function validateVerifiableContextSetup(dirPath) {
+export function validateContextGraphSetup(dirPath) {
     const context = readBuildPlanValidationContext(dirPath);
     return {
         config_present: context.config.present,
@@ -132,11 +131,11 @@ export function validateBuildStage(dirPath, stageId) {
     };
     const errors = [];
     if (!checks.config_present)
-        errors.push(`Missing ${verifiableContextInterfConfigPath(dirPath)}.`);
+        errors.push(`Missing ${contextGraphInterfConfigPath(dirPath)}.`);
     else if (!checks.config_valid)
-        errors.push(`Could not parse ${verifiableContextInterfConfigPath(dirPath)}.`);
+        errors.push(`Could not parse ${contextGraphInterfConfigPath(dirPath)}.`);
     else if (!checks.config_type_match)
-        errors.push("Config is not a verifiable context.");
+        errors.push("Config is not a context graph.");
     if (!checks.build_plan_present)
         errors.push("Missing .interf/build-plan/build-plan.json.");
     else if (!checks.build_plan_valid)
@@ -145,6 +144,11 @@ export function validateBuildStage(dirPath, stageId) {
         errors.push(`Missing .interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}.`);
     else if (!checks.schema_valid)
         errors.push(`Could not parse .interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}.`);
+    checks.source_files_present = context.sourceTotal > 0;
+    checks.source_manifest_valid = context.sourceManifest !== null && context.sourceTotal > 0;
+    if (!checks.source_files_present) {
+        errors.push("No Source Manifest has been recorded for this Context Graph.");
+    }
     const buildPlanStage = context.buildPlan?.stages.find((stage) => stage.id === stageId) ?? null;
     checks.stage_present = buildPlanStage !== null;
     if (!checks.stage_present) {
@@ -163,14 +167,17 @@ export function validateBuildStage(dirPath, stageId) {
     if (buildPlanStage && context.schema) {
         const artifacts = artifactsBuiltByStage(context.schema, buildPlanStage);
         const failures = artifactCheckFailures(dirPath, artifacts, artifactCounts);
-        checks.artifact_checks_ok = failures.length === 0;
-        artifactErrors = failures.map((proof) => `Artifact check "${proof.check_id}" failed for ${proof.kind}: ${proof.summary}`);
+        checks.artifact_diagnostics_ok = failures.length === 0;
+        artifactErrors = failures.map((result) => `Requested output diagnostic "${result.check_id}" failed for ${result.kind}: ${result.summary}`);
     }
     else {
-        checks.artifact_checks_ok = false;
+        checks.artifact_diagnostics_ok = false;
     }
     if (required && checks.stage_record_present && !checks.stage_finished) {
-        errors.push(`Stage "${stageId}" has no finished_at proof in runtime state.`);
+        errors.push(`Stage "${stageId}" has no finished_at evidence in runtime state.`);
+    }
+    if (required && !checks.stage_record_present) {
+        errors.push(`Stage "${stageId}" has no runtime state record.`);
     }
     if (required && checks.stage_record_present && !checks.stage_succeeded) {
         errors.push(`Stage "${stageId}" is not marked succeeded in runtime state.`);
@@ -178,12 +185,12 @@ export function validateBuildStage(dirPath, stageId) {
     if (required) {
         errors.push(...artifactErrors);
     }
-    const ok = required ? errors.length === 0 : errors.length === 0;
-    const summary = !required
-        ? `Stage "${stageId}" is not required yet.`
-        : ok
-            ? `Stage "${stageId}" verified.`
-            : `Stage "${stageId}" failed — ${errors[0] ?? "artifact checks not satisfied."}`;
+    const ok = errors.length === 0;
+    const summary = ok
+        ? required
+            ? `Stage "${stageId}" checks passed.`
+            : `Stage "${stageId}" is not required yet.`
+        : `Stage "${stageId}" failed — ${errors[0] ?? "stage output validation not satisfied."}`;
     return {
         ok,
         required,
@@ -198,7 +205,7 @@ export function validateBuildStage(dirPath, stageId) {
         errors,
     };
 }
-export function validateVerifiableContext(dirPath) {
+export function validateContextGraph(dirPath) {
     const context = readBuildPlanValidationContext(dirPath);
     const checks = {
         config_present: context.config.present,
@@ -208,6 +215,8 @@ export function validateVerifiableContext(dirPath) {
         build_plan_valid: context.buildPlan !== null,
         schema_present: buildPlanSchemaPresent(dirPath),
         schema_valid: context.schema !== null,
+        source_files_present: context.sourceTotal > 0,
+        source_manifest_valid: context.sourceManifest !== null && context.sourceTotal > 0,
     };
     if (!context.buildPlan) {
         const errors = ["Could not load the active Build Plan package."];
@@ -226,6 +235,10 @@ export function validateVerifiableContext(dirPath) {
     const errors = [];
     let completedStages = 0;
     let failedStage = "built";
+    if (!checks.source_files_present) {
+        errors.push("No Source Manifest has been recorded for this Context Graph.");
+        failedStage = "source";
+    }
     for (const stage of context.buildPlan.stages) {
         const validation = validateBuildStage(dirPath, stage.id);
         stageResults[stage.id] = validation.ok;
@@ -243,8 +256,8 @@ export function validateVerifiableContext(dirPath) {
         required: context.sourceTotal > 0,
         stage: failedStage,
         summary: ok
-            ? `Build Plan verified — ${completedStages}/${context.buildPlan.stages.length} stages satisfied.`
-            : `Build Plan failed — ${errors[0] ?? "stage artifact checks not satisfied."}`,
+            ? `Build Plan checks passed — ${completedStages}/${context.buildPlan.stages.length} stages satisfied.`
+            : `Build Plan failed — ${errors[0] ?? "stage output validation not satisfied."}`,
         counts: {
             source_total: context.sourceTotal,
             stage_total: context.buildPlan.stages.length,
@@ -258,9 +271,9 @@ export function validateVerifiableContext(dirPath) {
 export function validateBuildSummarize(dirPath) {
     return validateBuildStage(dirPath, "summarize");
 }
-export function validateVerifiableContextStructure(dirPath) {
-    return validateBuildStage(dirPath, "structure");
+export function validateContextGraphKnowledge(dirPath) {
+    return validateBuildStage(dirPath, "knowledge");
 }
 export function validateBuildOutput(dirPath) {
-    return validateVerifiableContext(dirPath);
+    return validateContextGraph(dirPath);
 }

package/dist/packages/{engine → runtime}/build/validate.d.ts

@@ -1,5 +1,5 @@
-import { readInterfConfig } from "../../project/interf-detect.js";
-export declare function readVerifiableContextConfig(dirPath: string): {
+import { readInterfConfig } from "../../projects/interf-detect.js";
+export declare function readContextGraphConfig(dirPath: string): {
     present: boolean;
     valid: boolean;
     value: ReturnType<typeof readInterfConfig>;
@@ -11,11 +11,11 @@ export declare function validateSynthFiles(files: string[], options?: {
     invalid_frontmatter: number;
     short_abstracts: number;
 };
-export declare function countBrokenWikilinks(verifiableContextRoot: string, noteIndexRoots: string[], linkScanRoots: string[]): number;
+export declare function countBrokenWikilinks(contextGraphRoot: string, noteIndexRoots: string[], linkScanRoots: string[]): number;
 export declare function asNumber(value: unknown): number;
 export declare function isOutputMarkdownFile(filePath: string): boolean;
 export declare function safeReadText(filePath: string): string | null;
 export declare function extractSynthAbstract(frontmatter: Record<string, unknown>, body: string): string | null;
 export declare function countSynthAbstractWords(frontmatter: Record<string, unknown>, body: string): number;
-export { validateVerifiableContextSetup, validateBuildStage, validateVerifiableContext, validateBuildSummarize, validateVerifiableContextStructure, validateBuildOutput, } from "./validate-verifiable-context.js";
-export type { VerifiableContextValidationSummary, BuildStageValidation, VerifiableContextValidation, } from "./validate-verifiable-context.js";
+export { validateContextGraphSetup, validateBuildStage, validateContextGraph, validateBuildSummarize, validateContextGraphKnowledge, validateBuildOutput, } from "./validate-context-graph.js";
+export type { ContextGraphValidationSummary, BuildStageValidation, ContextGraphValidation, } from "./validate-context-graph.js";

package/dist/packages/{engine → runtime}/build/validate.js

@@ -1,15 +1,15 @@
 import { existsSync, readFileSync, statSync, } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
-import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./verifiable-context-schema.js";
-import { buildPlanPackagePathForVerifiableContext } from "./verifiable-context-paths.js";
+import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./context-graph-schema.js";
+import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
 import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
-import { readInterfConfig } from "../../project/interf-detect.js";
+import { readInterfConfig } from "../../projects/interf-detect.js";
 import { parseJsonFrontmatter } from "../../contracts/utils/parse.js";
-import { verifiableContextInterfConfigPath } from "./verifiable-context-paths.js";
+import { contextGraphInterfConfigPath } from "./context-graph-paths.js";
 const MIN_ABSTRACT_WORDS = 5;
 const WIKILINK_PATTERN = /!?\[\[([^[\]]+)\]\]/g;
-export function readVerifiableContextConfig(dirPath) {
-    const configPath = verifiableContextInterfConfigPath(dirPath);
+export function readContextGraphConfig(dirPath) {
+    const configPath = contextGraphInterfConfigPath(dirPath);
     const value = readInterfConfig(dirPath);
     const present = existsSync(configPath);
     if (!present) {
@@ -25,7 +25,7 @@ export function readVerifiableContextConfig(dirPath) {
         valid: value !== null,
         value,
         typeMatch() {
-            return value?.type === "verifiable-context" && typeof value?.source?.path === "string";
+            return value?.type === "context-graph" && typeof value?.source?.path === "string";
         },
     };
 }
@@ -51,9 +51,9 @@ export function validateSynthFiles(files, options) {
         short_abstracts: shortAbstracts,
     };
 }
-export function countBrokenWikilinks(verifiableContextRoot, noteIndexRoots, linkScanRoots) {
-    const artifactPathById = verifiableContextArtifactDirectoryPaths(verifiableContextRoot);
-    const directoryLeafParents = verifiableContextDirectoryLeafParents(artifactPathById);
+export function countBrokenWikilinks(contextGraphRoot, noteIndexRoots, linkScanRoots) {
+    const artifactPathById = contextGraphArtifactDirectoryPaths(contextGraphRoot);
+    const directoryLeafParents = contextGraphDirectoryLeafParents(artifactPathById);
     const noteIndex = new Set();
     for (const filePath of dedupeFiles(noteIndexRoots)) {
         for (const target of collectWikilinkTargets(filePath)) {
@@ -74,15 +74,15 @@ export function countBrokenWikilinks(verifiableContextRoot, noteIndexRoots, link
             if (!target)
                 continue;
             if (target.includes("/")) {
-                if (!wikilinkPathExists(verifiableContextRoot, target, artifactPathById, directoryLeafParents, filePath)) {
+                if (!wikilinkPathExists(contextGraphRoot, target, artifactPathById, directoryLeafParents, filePath)) {
                     brokenLinks += 1;
                 }
                 continue;
             }
             if (!noteIndex.has(target.toLowerCase()) &&
                 !noteIndex.has(noteName(target).toLowerCase()) &&
-                !wikilinkPathExists(verifiableContextRoot, target, artifactPathById, directoryLeafParents, filePath) &&
-                !wikilinkPathExists(verifiableContextRoot, noteName(target), artifactPathById, directoryLeafParents, filePath)) {
+                !wikilinkPathExists(contextGraphRoot, target, artifactPathById, directoryLeafParents, filePath) &&
+                !wikilinkPathExists(contextGraphRoot, noteName(target), artifactPathById, directoryLeafParents, filePath)) {
                 brokenLinks += 1;
             }
         }
@@ -171,28 +171,28 @@ function countWords(text) {
 function noteName(filePath) {
     return basename(filePath, extname(filePath));
 }
-function wikilinkPathExists(verifiableContextRoot, target, artifactPathById, directoryLeafParents, sourceFilePath) {
-    return linkPathCandidates(verifiableContextRoot, target, artifactPathById, directoryLeafParents, sourceFilePath)
+function wikilinkPathExists(contextGraphRoot, target, artifactPathById, directoryLeafParents, sourceFilePath) {
+    return linkPathCandidates(contextGraphRoot, target, artifactPathById, directoryLeafParents, sourceFilePath)
         .some((candidate) => existsSync(candidate));
 }
-function linkPathCandidates(verifiableContextRoot, target, artifactPathById, directoryLeafParents, sourceFilePath) {
+function linkPathCandidates(contextGraphRoot, target, artifactPathById, directoryLeafParents, sourceFilePath) {
     const candidates = new Set();
-    addPathCandidate(candidates, join(verifiableContextRoot, target));
+    addPathCandidate(candidates, join(contextGraphRoot, target));
     if (sourceFilePath && (target.startsWith("./") || target.startsWith("../"))) {
-        addPathCandidateIfInside(candidates, verifiableContextRoot, resolve(dirname(sourceFilePath), target));
+        addPathCandidateIfInside(candidates, contextGraphRoot, resolve(dirname(sourceFilePath), target));
     }
     const [firstSegment] = target.split("/");
     if (firstSegment) {
         const parentPath = directoryLeafParents.get(firstSegment);
         if (parentPath) {
-            addPathCandidate(candidates, join(verifiableContextRoot, parentPath, target));
+            addPathCandidate(candidates, join(contextGraphRoot, parentPath, target));
         }
     }
     if (firstSegment) {
         const normalizedPrefix = artifactPathById.get(firstSegment);
         if (normalizedPrefix) {
             const remainder = target.slice(firstSegment.length).replace(/^\/+/, "");
-            addPathCandidate(candidates, join(verifiableContextRoot, normalizedPrefix, remainder));
+            addPathCandidate(candidates, join(contextGraphRoot, normalizedPrefix, remainder));
         }
     }
     return Array.from(candidates);
@@ -201,15 +201,15 @@ function addPathCandidate(candidates, absolutePath) {
     candidates.add(absolutePath);
     candidates.add(`${absolutePath}.md`);
 }
-function addPathCandidateIfInside(candidates, verifiableContextRoot, absolutePath) {
-    const root = resolve(verifiableContextRoot);
+function addPathCandidateIfInside(candidates, contextGraphRoot, absolutePath) {
+    const root = resolve(contextGraphRoot);
     const candidate = resolve(absolutePath);
     if (candidate !== root && !candidate.startsWith(`${root}/`))
         return;
     addPathCandidate(candidates, candidate);
 }
-function verifiableContextArtifactDirectoryPaths(verifiableContextRoot) {
-    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(verifiableContextRoot);
+function contextGraphArtifactDirectoryPaths(contextGraphRoot) {
+    const buildPlanRoot = buildPlanPackagePathForContextGraph(contextGraphRoot);
     const schema = readBuildPlanContextFile(buildPlanRoot);
     if (!schema)
         return new Map();
@@ -217,7 +217,7 @@ function verifiableContextArtifactDirectoryPaths(verifiableContextRoot) {
         .filter((artifact) => artifact.kind === "directory")
         .map((artifact) => [artifact.id, artifact.path]));
 }
-function verifiableContextDirectoryLeafParents(artifactPathById) {
+function contextGraphDirectoryLeafParents(artifactPathById) {
     const parents = new Map();
     for (const artifactPath of artifactPathById.values()) {
         const [root, leaf, ...rest] = artifactPath.split("/");
@@ -256,4 +256,4 @@ function addFrontmatterLinkTarget(targets, value) {
         }
     }
 }
-export { validateVerifiableContextSetup, validateBuildStage, validateVerifiableContext, validateBuildSummarize, validateVerifiableContextStructure, validateBuildOutput, } from "./validate-verifiable-context.js";
+export { validateContextGraphSetup, validateBuildStage, validateContextGraph, validateBuildSummarize, validateContextGraphKnowledge, validateBuildOutput, } from "./validate-context-graph.js";

package/dist/packages/{engine → runtime}/client.d.ts

@@ -1,4 +1,4 @@
-import { type ActionProposalApprovalRequest, type ActionProposalCreateRequest, type ActionProposalResource, type BuildRunCreateRequest, type BuildRunResource, type LocalJobRunResource, type LocalServiceHealth, type ReadinessCheckDraftCreateRequest, type ReadinessCheckDraftResult, type ResetRequest, type ResetResult, type VerifyRunCreateRequest, type VerifyRunResource, type BuildPlanAuthoringCreateRequest, type BuildPlanAuthoringResult } from "./lib/schema.js";
+import { type ActionProposalApprovalRequest, type ActionProposalCreateRequest, type ActionProposalResource, type BuildRunCreateRequest, type BuildRunResource, type LocalJobRunResource, type LocalServiceHealth, type BenchmarkQuestionDraftCreateRequest, type BenchmarkQuestionDraftResult, type ResetRequest, type ResetResult, type VerifyRunCreateRequest, type VerifyRunResource, type BuildPlanAuthoringCreateRequest, type BuildPlanAuthoringResult } from "./schemas/index.js";
 export interface FindOrStartLocalServiceOptions {
     url?: string;
     authToken?: string;
@@ -20,37 +20,37 @@ export interface LocalServiceJobSubmitted {
 }
 export declare function configuredLocalServiceUrl(): string;
 /**
- * Resolve the bearer token for the active connection. In 0.13 there is
- * exactly one source of truth: `~/.interf/connection.json` (or the
- * `INTERF_SERVICE_TOKEN` env override).
+ * Resolve the bearer token for the active connection. There is exactly
+ * one source of truth: `~/.interf/connection.json` (or the
+ * `INTERF_AUTH_TOKEN` env override).
  */
 export declare function resolveLocalServiceAuthToken(): string | null;
 /**
- * Resolve a connection. In 0.13 this is the only path to the engine — read
- * `~/.interf/connection.json` (written by `interf web`) or honor the
- * `INTERF_SERVICE_URL` / `INTERF_SERVICE_TOKEN` env overrides.
+ * Resolve a connection — the only path to the engine. Read
+ * `~/.interf/connection.json` (written by `interf runtime`) or honor the
+ * `INTERF_SERVICE_URL` / `INTERF_AUTH_TOKEN` env overrides.
  */
 export declare function findLocalService(options?: {
     timeoutMs?: number;
 }): Promise<LocalServiceConnection | null>;
 export declare function submitBuildRunToLocalService(options: {
-    preparationId: string;
-    request: BuildRunCreateRequest;
+    projectId: string;
+    request: Omit<BuildRunCreateRequest, "project">;
     idempotencyKey?: string;
 }): Promise<{
     serviceUrl: string;
     resource: BuildRunResource;
 } | null>;
 export declare function submitVerifyRunToLocalService(options: {
-    preparationId: string;
-    request: VerifyRunCreateRequest;
+    projectId: string;
+    request: Omit<VerifyRunCreateRequest, "project">;
 }): Promise<{
     serviceUrl: string;
     resource: VerifyRunResource;
 } | null>;
 export declare function submitResetToLocalService(options: {
-    preparationId: string;
-    request: ResetRequest;
+    projectId: string;
+    request: Omit<ResetRequest, "project">;
 }): Promise<{
     serviceUrl: string;
     result: ResetResult;
@@ -128,14 +128,14 @@ export declare function waitForLocalJobRun(options: {
     authToken?: string | null;
     onUpdate?: (job: LocalJobRunResource) => void;
 }): Promise<LocalJobRunResource>;
-export declare function submitReadinessCheckDraftToLocalService(options: {
-    preparationId: string;
-    request: ReadinessCheckDraftCreateRequest;
+export declare function submitBenchmarkQuestionDraftToLocalService(options: {
+    projectId: string;
+    request: BenchmarkQuestionDraftCreateRequest;
     onSubmitted?: (submission: LocalServiceJobSubmitted) => void;
     onUpdate?: (job: LocalJobRunResource) => void;
-}): Promise<LocalServiceJobSubmission<ReadinessCheckDraftResult> | null>;
+}): Promise<LocalServiceJobSubmission<BenchmarkQuestionDraftResult> | null>;
 export declare function submitBuildPlanAuthoringRunToLocalService(options: {
-    preparationId: string;
+    projectId: string;
     request: BuildPlanAuthoringCreateRequest;
     onSubmitted?: (submission: LocalServiceJobSubmitted) => void;
     onUpdate?: (job: LocalJobRunResource) => void;