@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/{engine → runtime}/build/state-health.js

@@ -1,22 +1,21 @@
 import { basename } from "node:path";
-import { readInterfConfig, resolveSourceFolderPath, } from "../../project/interf-detect.js";
-import { discoverSourceFiles } from "./discovery.js";
-import { loadRuntimeRun } from "./runtime.js";
+import { readInterfConfig, } from "../../projects/interf-detect.js";
+import { loadExecutionStageLedger } from "./runtime.js";
 import { loadState } from "./state-io.js";
-import { validateVerifiableContextSetup, validateBuildStage, validateVerifiableContext, } from "./validate.js";
-import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./verifiable-context-schema.js";
-import { buildPlanPackagePathForVerifiableContext } from "./verifiable-context-paths.js";
+import { loadContextGraphSourceManifest } from "./source-manifest.js";
+import { validateContextGraph, } from "./validate.js";
+import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./context-graph-schema.js";
+import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
 import { getActiveBuildPlan, resolveRequiredBuildPlanFromConfig } from "../../build-plans/package/build-plan-definitions.js";
 import { countBuildArtifactsAtPath } from "./artifact-counts.js";
-export function computeVerifiableContextHealth(dirPath) {
+export function computeContextGraphHealth(dirPath) {
     const now = new Date().toISOString();
     const config = readInterfConfig(dirPath);
     const targetName = config?.name ?? basename(dirPath);
-    const sourcePath = config ? resolveSourceFolderPath(dirPath, config) : dirPath;
-    const sourceTotal = config ? discoverSourceFiles(sourcePath, dirPath).totalCount : 0;
+    const sourceTotal = loadContextGraphSourceManifest(dirPath)?.source_total ?? 0;
     const state = loadState(dirPath);
-    const validation = validateVerifiableContextSetup(dirPath);
-    const activeRun = loadRuntimeRun(dirPath);
+    const buildPlanValidation = validateContextGraph(dirPath);
+    const activeRun = loadExecutionStageLedger(dirPath);
     const buildPlanId = config
         ? resolveRequiredBuildPlanFromConfig(config, `.interf/interf.json for ${dirPath}`)
         : null;
@@ -29,14 +28,10 @@ export function computeVerifiableContextHealth(dirPath) {
             buildPlan = null;
         }
     }
-    const stageResults = buildPlan?.stages.map((stage) => ({
-        stage,
-        validation: validateBuildStage(dirPath, stage.id),
-    })) ?? [];
-    const completedStages = stageResults.filter((entry) => entry.validation.ok).length;
-    const firstFailed = stageResults.find((entry) => !entry.validation.ok) ?? null;
-    const buildPlanValidation = validateVerifiableContext(dirPath);
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(dirPath));
+    const completedStages = buildPlanValidation.counts.completed_stages ?? 0;
+    const firstFailedStage = Object.entries(buildPlanValidation.stage_results)
+        .find(([, ok]) => !ok)?.[0] ?? null;
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(dirPath));
     const artifactMetrics = Object.fromEntries((schema ? listBuildPlanContextArtifacts(schema) : []).map((artifact) => [
         `artifact_${artifact.id}`,
         countBuildArtifactsAtPath(dirPath, artifact.path, artifact.kind),
@@ -45,7 +40,7 @@ export function computeVerifiableContextHealth(dirPath) {
     let stage = "idle";
     let summary = "Idle — no source files have been built yet.";
     const errors = buildPlanValidation.errors.length;
-    if (!validation.config_present || !validation.config_valid || !validation.config_type_match || !validation.build_plan_valid || !validation.schema_valid) {
+    if (!buildPlanValidation.checks.config_present || !buildPlanValidation.checks.config_valid || !buildPlanValidation.checks.config_type_match || !buildPlanValidation.checks.build_plan_valid || !buildPlanValidation.checks.schema_valid) {
         status = "failed";
         stage = "failed";
         summary = buildPlanValidation.summary;
@@ -72,20 +67,20 @@ export function computeVerifiableContextHealth(dirPath) {
     }
     else {
         status = "stale";
-        stage = firstFailed?.stage.id ?? "built";
-        summary = firstFailed?.validation.summary ?? buildPlanValidation.summary;
+        stage = firstFailedStage ?? buildPlanValidation.stage;
+        summary = buildPlanValidation.summary;
     }
     const checks = {
-        ...validation,
+        ...buildPlanValidation.checks,
         ...(buildPlan
             ? Object.fromEntries(buildPlan.stages.map((buildPlanStage) => [
                 `stage_${buildPlanStage.id}_ok`,
-                stageResults.find((entry) => entry.stage.id === buildPlanStage.id)?.validation.ok ?? false,
+                buildPlanValidation.stage_results[buildPlanStage.id] ?? false,
             ]))
             : {}),
     };
     return {
-        kind: "verifiable-context-health",
+        kind: "context-graph-health",
         version: 2,
         generated_at: now,
         target_name: targetName,
@@ -103,7 +98,7 @@ export function computeVerifiableContextHealth(dirPath) {
         checks,
     };
 }
-export function resolveVerifiableContextStatus(..._args) {
+export function resolveContextGraphStatus(..._args) {
     const state = _args[_args.length - 1];
     if (state?.error_count && state.error_count > 0)
         return "failed";

package/dist/packages/runtime/build/state-io.d.ts

@@ -0,0 +1,12 @@
+import { type ContextGraphHealth, type ContextGraphState, type ContextGraphViewSpec, type SourceFiles, type SourceManifest, type SourceState } from "./lib/schema.js";
+export declare function loadState<T>(dirPath: string): T | null;
+export declare function saveState<T>(dirPath: string, state: T): void;
+export declare function loadContextGraphHealth(dirPath: string): ContextGraphHealth | null;
+export declare function saveContextGraphHealth(dirPath: string, health: ContextGraphHealth): void;
+export declare function loadContextGraphViewSpec(dirPath: string): ContextGraphViewSpec | null;
+export declare function saveContextGraphViewSpec(dirPath: string, viewSpec: ContextGraphViewSpec): void;
+export declare function loadContextGraphSourceManifest(dirPath: string): SourceManifest | null;
+export declare function loadContextGraphSourceFiles(dirPath: string): SourceFiles | null;
+export declare function loadContextGraphSourceState(dirPath: string): SourceState | null;
+export declare function saveEmptyExecutionInventory(dirPath: string): void;
+export declare function initContextGraphState(): ContextGraphState;

package/dist/packages/runtime/build/state-io.js

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync, } from "node:fs";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { ContextGraphHealthSchema, ContextGraphStateSchema, ContextGraphViewSpecSchema, SourceFilesSchema, SourceManifestSchema, SourceStateSchema, } from "./lib/schema.js";
+import { emptyExecutionInventory, } from "./runtime-inventory.js";
+import { contextGraphExecutionInventoryPath, contextGraphRuntimeHealthPath, contextGraphRuntimeSourceFilesPath, contextGraphRuntimeSourceManifestPath, contextGraphRuntimeSourceStatePath, contextGraphRuntimeStatePath, contextGraphRuntimeViewSpecPath, } from "./context-graph-paths.js";
+import { writeJsonAtomic } from "./atomic-fs.js";
+export function loadState(dirPath) {
+    const path = contextGraphRuntimeStatePath(dirPath);
+    if (!existsSync(path))
+        return null;
+    const raw = readJsonFileUnchecked(path, "runtime state");
+    if (raw === null)
+        return null;
+    const parsed = ContextGraphStateSchema.safeParse(raw);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    warnInterf(`Warning: failed to validate runtime state at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+    return null;
+}
+export function saveState(dirPath, state) {
+    writeJsonAtomic(contextGraphRuntimeStatePath(dirPath), state);
+}
+export function loadContextGraphHealth(dirPath) {
+    const path = contextGraphRuntimeHealthPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "context-graph health", ContextGraphHealthSchema);
+}
+export function saveContextGraphHealth(dirPath, health) {
+    writeJsonAtomic(contextGraphRuntimeHealthPath(dirPath), health);
+}
+export function loadContextGraphViewSpec(dirPath) {
+    const path = contextGraphRuntimeViewSpecPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return loadViewSpec(path, ContextGraphViewSpecSchema);
+}
+export function saveContextGraphViewSpec(dirPath, viewSpec) {
+    writeJsonAtomic(contextGraphRuntimeViewSpecPath(dirPath), viewSpec);
+}
+export function loadContextGraphSourceManifest(dirPath) {
+    const path = contextGraphRuntimeSourceManifestPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "context-graph source manifest", SourceManifestSchema);
+}
+export function loadContextGraphSourceFiles(dirPath) {
+    const manifest = loadContextGraphSourceManifest(dirPath);
+    if (manifest) {
+        return SourceFilesSchema.parse({
+            kind: "interf-source-files",
+            version: 1,
+            generated_at: manifest.generated_at,
+            source: manifest.source,
+            source_total: manifest.source_total,
+            files: manifest.files.map((file) => ({
+                id: file.id,
+                path: file.path,
+                locator: file.locator,
+                ...(typeof file.size_bytes === "number" ? { size_bytes: file.size_bytes } : {}),
+            })),
+        });
+    }
+    const path = contextGraphRuntimeSourceFilesPath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "context-graph source files", SourceFilesSchema);
+}
+export function loadContextGraphSourceState(dirPath) {
+    const manifest = loadContextGraphSourceManifest(dirPath);
+    if (manifest) {
+        return SourceStateSchema.parse({
+            kind: "interf-source-state",
+            version: 1,
+            graph_id: manifest.manifest_id,
+            generated_at: manifest.generated_at,
+            run_id: manifest.run_id,
+            source: manifest.source,
+            source_total: manifest.source_total,
+            files: manifest.files.map((file) => ({
+                id: file.id,
+                path: file.path,
+                locator: file.locator,
+                ...(typeof file.size_bytes === "number" ? { size_bytes: file.size_bytes } : {}),
+            })),
+        });
+    }
+    const path = contextGraphRuntimeSourceStatePath(dirPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "context-graph source state", SourceStateSchema);
+}
+export function saveEmptyExecutionInventory(dirPath) {
+    writeJsonAtomic(contextGraphExecutionInventoryPath(dirPath), emptyExecutionInventory());
+}
+export function initContextGraphState() {
+    return {
+        version: 2,
+        pending: [],
+        stages: {},
+        last_add: null,
+        last_build: null,
+        warning_count: 0,
+        error_count: 0,
+    };
+}
+function loadViewSpec(filePath, schema) {
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        const parsed = schema.safeParse(raw);
+        return parsed.success ? parsed.data ?? null : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/packages/runtime/build/state-view.d.ts

@@ -0,0 +1,5 @@
+import { type ContextGraphViewSpec, type SourceFiles, type SourceState } from "./lib/schema.js";
+export declare function ensureContextGraphViewSpec(dirPath: string): ContextGraphViewSpec;
+export declare function ensureContextGraphSourceFiles(dirPath: string): SourceFiles;
+export declare function ensureContextGraphSourceState(dirPath: string, sourceFiles?: SourceFiles): SourceState;
+export declare function normalizeContextGraphViewSpec(existing: ContextGraphViewSpec, defaults?: ContextGraphViewSpec): ContextGraphViewSpec;

package/dist/packages/runtime/build/state-view.js

@@ -0,0 +1,121 @@
+import { basename } from "node:path";
+import { readInterfConfig, resolveSourceFolderPath } from "../../projects/interf-detect.js";
+import { SourceFilesSchema, SourceStateSchema, } from "./lib/schema.js";
+import { loadContextGraphSourceFiles, loadContextGraphSourceState, loadContextGraphViewSpec, saveContextGraphViewSpec, } from "./state-io.js";
+import { loadContextGraphSourceManifest, sourceManifestToSourceFiles, sourceManifestToSourceState, } from "./source-manifest.js";
+import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
+import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./context-graph-schema.js";
+import { getActiveBuildPlan, resolveRequiredBuildPlanFromConfig } from "../../build-plans/package/build-plan-definitions.js";
+export function ensureContextGraphViewSpec(dirPath) {
+    const existing = loadContextGraphViewSpec(dirPath);
+    const now = new Date().toISOString();
+    const contextGraphName = readInterfConfig(dirPath)?.name ?? basename(dirPath);
+    const defaults = buildDefaultContextGraphViewSpec(dirPath, contextGraphName, now);
+    if (existing) {
+        const normalized = normalizeContextGraphViewSpec(existing, defaults);
+        if (JSON.stringify(normalized) !== JSON.stringify(existing)) {
+            saveContextGraphViewSpec(dirPath, normalized);
+        }
+        return normalized;
+    }
+    saveContextGraphViewSpec(dirPath, defaults);
+    return defaults;
+}
+export function ensureContextGraphSourceFiles(dirPath) {
+    const existing = loadContextGraphSourceFiles(dirPath);
+    if (existing)
+        return existing;
+    const manifest = loadContextGraphSourceManifest(dirPath);
+    if (manifest)
+        return sourceManifestToSourceFiles(manifest);
+    const config = readInterfConfig(dirPath);
+    const now = new Date().toISOString();
+    const sourceFiles = SourceFilesSchema.parse({
+        kind: "interf-source-files",
+        version: 1,
+        generated_at: now,
+        source: {
+            id: "src-unscanned",
+            kind: "local-folder",
+            locator: resolveSourceFolderPath(dirPath, config),
+        },
+        source_total: 0,
+        files: [],
+    });
+    return sourceFiles;
+}
+export function ensureContextGraphSourceState(dirPath, sourceFiles) {
+    const existing = loadContextGraphSourceState(dirPath);
+    if (existing)
+        return existing;
+    const manifest = loadContextGraphSourceManifest(dirPath);
+    if (manifest)
+        return sourceManifestToSourceState(manifest);
+    const resolvedSourceFiles = sourceFiles ?? ensureContextGraphSourceFiles(dirPath);
+    const sourceState = SourceStateSchema.parse({
+        kind: "interf-source-state",
+        version: 1,
+        graph_id: "source-manifest-unrecorded",
+        generated_at: resolvedSourceFiles.generated_at,
+        run_id: null,
+        source: resolvedSourceFiles.source,
+        source_total: resolvedSourceFiles.source_total,
+        files: resolvedSourceFiles.files,
+    });
+    return sourceState;
+}
+export function normalizeContextGraphViewSpec(existing, defaults) {
+    const resolvedDefaults = defaults ?? existing;
+    return {
+        ...resolvedDefaults,
+        ...existing,
+        cards: Array.isArray(existing.cards) && existing.cards.length > 0
+            ? existing.cards.map((card) => {
+                if (card.format !== "fraction" || card.denominator_metric)
+                    return card;
+                const defaultCard = resolvedDefaults.cards.find((candidate) => candidate.id === card.id);
+                return {
+                    ...card,
+                    denominator_metric: defaultCard?.denominator_metric ?? "stage_total",
+                };
+            })
+            : resolvedDefaults.cards,
+        sections: Array.isArray(existing.sections) && existing.sections.length > 0 ? existing.sections : resolvedDefaults.sections,
+        document_scope: Array.isArray(existing.document_scope) && existing.document_scope.length > 0
+            ? existing.document_scope
+            : resolvedDefaults.document_scope,
+    };
+}
+function buildDefaultContextGraphViewSpec(dirPath, contextGraphName, generatedAt) {
+    const config = readInterfConfig(dirPath);
+    resolveRequiredBuildPlanFromConfig(config, `.interf/interf.json for ${dirPath}`);
+    const buildPlan = getActiveBuildPlan(dirPath);
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(dirPath));
+    const schemaArtifacts = schema ? listBuildPlanContextArtifacts(schema) : [];
+    const outputDocumentPaths = schemaArtifacts
+        .map((artifact) => artifact.path);
+    const defaultNote = schemaArtifacts.find((artifact) => artifact.kind === "file")?.path ?? null;
+    return {
+        kind: "context-graph-view-spec",
+        version: 2,
+        generated_at: generatedAt,
+        target_name: contextGraphName,
+        health_source: ".interf/runtime/health.json",
+        state_source: ".interf/runtime/state.json",
+        default_note: defaultNote,
+        document_scope: outputDocumentPaths,
+        cards: [
+            { id: "source-total", label: "Source Files", metric: "source_total", format: "number" },
+            { id: "stage-total", label: "Stages", metric: "stage_total", format: "number" },
+            { id: "completed-stages", label: "Completed", metric: "completed_stages", denominator_metric: "stage_total", format: "fraction" },
+        ],
+        sections: [
+            { id: "status", type: "status", title: "Build Status", path: ".interf/runtime/health.json" },
+            { id: "cards", type: "cards", title: "Key Metrics", path: ".interf/runtime/health.json" },
+            ...(outputDocumentPaths.length > 0
+                ? [{ id: "outputs", type: "documents", title: "Requested outputs", paths: outputDocumentPaths }]
+                : []),
+            { id: "build-plan", type: "documents", title: "Build Plan Docs", paths: ["build-plan/README.md", ...buildPlan.stages.map((stage) => `build-plan/build/stages/${stage.skillDir}`)] },
+        ],
+    };
+}

package/dist/packages/runtime/build/state.d.ts

@@ -0,0 +1,7 @@
+export type { RuntimeStatus, BuildStage, ContextGraphState, ContextGraphHealth, ViewSection, ViewCard, ContextGraphViewSpec, SourceFiles, SourceState, StageInputs, } from "./lib/schema.js";
+export { contextGraphRuntimeStatePath as statePath, contextGraphRuntimeHealthPath as healthPath, contextGraphRuntimeViewSpecPath as viewSpecPath, contextGraphRuntimeSourceFilesPath as sourceFilesPath, contextGraphRuntimeSourceStatePath as sourceStatePath, } from "./context-graph-paths.js";
+export { loadState, saveState, loadContextGraphHealth, saveContextGraphHealth, loadContextGraphViewSpec, loadContextGraphSourceFiles, loadContextGraphSourceState, saveContextGraphViewSpec, initContextGraphState, } from "./state-io.js";
+export { refreshContextGraphArtifacts, } from "./state-artifacts.js";
+export { computeContextGraphHealth, resolveContextGraphStatus, resolveBuildStage, } from "./state-health.js";
+export { ensureContextGraphViewSpec, ensureContextGraphSourceFiles, ensureContextGraphSourceState, normalizeContextGraphViewSpec, } from "./state-view.js";
+export declare function initializeBuildRuntimeState(dirPath: string): void;

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

@@ -0,0 +1,12 @@
+export { contextGraphRuntimeStatePath as statePath, contextGraphRuntimeHealthPath as healthPath, contextGraphRuntimeViewSpecPath as viewSpecPath, contextGraphRuntimeSourceFilesPath as sourceFilesPath, contextGraphRuntimeSourceStatePath as sourceStatePath, } from "./context-graph-paths.js";
+export { loadState, saveState, loadContextGraphHealth, saveContextGraphHealth, loadContextGraphViewSpec, loadContextGraphSourceFiles, loadContextGraphSourceState, saveContextGraphViewSpec, initContextGraphState, } from "./state-io.js";
+export { refreshContextGraphArtifacts, } from "./state-artifacts.js";
+export { computeContextGraphHealth, resolveContextGraphStatus, resolveBuildStage, } from "./state-health.js";
+export { ensureContextGraphViewSpec, ensureContextGraphSourceFiles, ensureContextGraphSourceState, normalizeContextGraphViewSpec, } from "./state-view.js";
+import { saveEmptyExecutionInventory, initContextGraphState, saveState } from "./state-io.js";
+import { refreshContextGraphArtifacts } from "./state-artifacts.js";
+export function initializeBuildRuntimeState(dirPath) {
+    saveState(dirPath, initContextGraphState());
+    saveEmptyExecutionInventory(dirPath);
+    refreshContextGraphArtifacts(dirPath, { ensureViewSpec: true });
+}

package/dist/packages/runtime/build/summary-coverage-index.d.ts

@@ -0,0 +1,21 @@
+/** Stable delimiters around the managed coverage block in `home.md`. */
+export declare const HOME_COVERAGE_BLOCK_BEGIN = "<!-- interf:coverage-index:begin -->";
+export declare const HOME_COVERAGE_BLOCK_END = "<!-- interf:coverage-index:end -->";
+export interface SummaryCoverageIndexResult {
+    /** Number of summary notes the home coverage block wikilinks. */
+    summaries: number;
+    /** The file the navigation links were written into. */
+    indexPath: string;
+}
+/**
+ * Ensure `home.md` wikilinks every summary the build produced, via a managed,
+ * deterministic coverage block. Call this at build finalization, AFTER the stage
+ * agents have produced summaries, BEFORE the connectivity check runs. Guarantees
+ * every summary note has an inbound graph edge from the entrypoint spine
+ * regardless of agent behavior.
+ *
+ * Returns the count of linked summaries, or `null` when there is nothing to index
+ * (no `summaries/` layer). Never throws into the build: assembly is already
+ * complete; this is the connectivity floor laid on top.
+ */
+export declare function ensureSummaryCoverageIndex(contextGraphPath: string): SummaryCoverageIndexResult | null;

package/dist/packages/runtime/build/summary-coverage-index.js

@@ -0,0 +1,189 @@
+/**
+ * Deterministic NAVIGATION layer that GUARANTEES every summary note is reachable
+ * through the link web, independent of agent behavior.
+ *
+ * THE PROBLEM IT SOLVES
+ * The summarize stage produces one summary note per Source file. Knowledge and
+ * entrypoint stages are SUPPOSED to wikilink those summaries into the graph, but
+ * that relies on the stage agent doing it. When the agent skips a summary, that
+ * summary becomes a free-floating island: no note links it, it links no note,
+ * undirected degree 0. The `graph_notes_connected` readiness check then fails,
+ * and the rendered semantic graph shows the coverage layer as scattered dots.
+ *
+ * THE GUARANTEE
+ * After the stage agents run, the build calls `ensureSummaryCoverageIndex`. It
+ * is pure structure, deterministic, and idempotent. It writes a managed
+ * "Coverage index" block into `home.md` — the entrypoint spine — holding a
+ * `[[full/graph/path]]` wikilink to EVERY summary note the build produced,
+ * grouped by source folder. A full graph path resolves uniquely in the
+ * connectivity check's link resolver, so each summary gains a guaranteed
+ * INBOUND edge from `home.md`. `home.md` is itself part of the fixed skeleton
+ * and the graph spine, so it is never an island. Result: no summary can be a
+ * free-floating island, regardless of what the stage agent linked.
+ *
+ * WHY home.md (NOT a new note under summaries/)
+ * `home.md` is exactly what entrypoints are for: routing the reader into the
+ * content layers. The entrypoint SKILL already models a "Coverage" section in
+ * home that links every summary. Putting the index in the spine — rather than a
+ * new note inside `summaries/` — keeps the `summaries/` layer purely
+ * source-grounded summary notes (so the per-summary content contract,
+ * `frontmatter_required_keys` / `frontmatter_valid` / source-ref checks, still
+ * holds for every file there) while still guaranteeing connectivity.
+ *
+ * WHAT IT IS NOT
+ * This is a NAVIGATION layer: links only, exactly what `home.md` / entrypoints
+ * are for. It invents NO knowledge, NO claims, NO project-specific content, and
+ * hardcodes NOTHING about any Source. It only adds `[[wikilinks]]` from the
+ * entrypoint spine down to summaries the build already produced. It respects the
+ * fixed Context Graph skeleton: it edits only `home.md`, adds no new top-level
+ * folder, and creates no note inside the content layers.
+ *
+ * IDEMPOTENT / DETERMINISTIC
+ * Same graph in → same home block out. The block is regenerated from the current
+ * on-disk summary set every call (notes sorted, grouped deterministically) and is
+ * delimited by stable markers, so re-running REPLACES it in place rather than
+ * appending. Agent-authored home content outside the markers is preserved.
+ * Re-running on an already-finalized graph is a no-op on content.
+ *
+ * Best-effort: a failure to write must never fail a build (the stage outputs are
+ * already on disk). The connectivity check still runs after and is the source of
+ * truth on readiness.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { writeFileAtomic } from "./atomic-fs.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { isOutputMarkdownFile } from "./validate.js";
+import { HOME_SPINE_FILE } from "../../contracts/lib/context-graph-layer.js";
+const SUMMARIES_LAYER_DIR = "summaries";
+/** Stable delimiters around the managed coverage block in `home.md`. */
+export const HOME_COVERAGE_BLOCK_BEGIN = "<!-- interf:coverage-index:begin -->";
+export const HOME_COVERAGE_BLOCK_END = "<!-- interf:coverage-index:end -->";
+/**
+ * Normalize a graph-relative file path to the link form the connectivity check
+ * resolves: forward slashes, no leading `./`, no trailing `.md`. Mirrors
+ * `normalizeGraphPath` in check-evaluator so the wikilinks this module emits are
+ * the exact tokens that check credits as web edges.
+ */
+function toGraphPath(relativePath) {
+    return relativePath
+        .replaceAll("\\", "/")
+        .replace(/^\.\/+/, "")
+        .replace(/\.md$/i, "")
+        .replace(/\/+$/g, "");
+}
+/**
+ * Every summary note in the graph, as graph paths, deterministically sorted.
+ * Uses the same `isOutputMarkdownFile` filter the connectivity check and the
+ * semantic-graph builder use, so the spine links exactly the notes the check
+ * scores for connectivity.
+ */
+function listSummaryNoteGraphPaths(contextGraphPath) {
+    const summariesDir = join(contextGraphPath, SUMMARIES_LAYER_DIR);
+    if (!existsSync(summariesDir))
+        return [];
+    return listFilesRecursive(summariesDir, isOutputMarkdownFile)
+        .map((file) => toGraphPath(relative(contextGraphPath, file)))
+        .sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Group summary note graph paths by their source folder (the segment(s) between
+ * `summaries/` and the note leaf), purely for a navigable, grouped block.
+ * Grouping is cosmetic — connectivity is guaranteed by the per-note wikilink
+ * regardless of grouping — so a note directly under the layer falls into a single
+ * root group.
+ */
+function groupBySourceFolder(graphPaths) {
+    const groups = new Map();
+    for (const graphPath of graphPaths) {
+        const withoutLayer = graphPath.replace(new RegExp(`^${SUMMARIES_LAYER_DIR}/`), "");
+        const lastSlash = withoutLayer.lastIndexOf("/");
+        const group = lastSlash >= 0 ? withoutLayer.slice(0, lastSlash) : SUMMARIES_LAYER_DIR;
+        const bucket = groups.get(group);
+        if (bucket)
+            bucket.push(graphPath);
+        else
+            groups.set(group, [graphPath]);
+    }
+    return groups;
+}
+/**
+ * Render the managed coverage block: a stable-delimited `## Coverage` section
+ * that wikilinks every summary by its full graph path, grouped by source folder.
+ * Deterministic for a given summary set.
+ */
+function renderCoverageBlock(graphPaths) {
+    const lines = [
+        HOME_COVERAGE_BLOCK_BEGIN,
+        "## Coverage",
+        "",
+        "Every Source summary in this Context Graph, linked so the coverage layer stays",
+        "connected to this entrypoint. Navigation only — links, no new content.",
+        "",
+    ];
+    const groups = groupBySourceFolder(graphPaths);
+    const groupNames = [...groups.keys()].sort((left, right) => left.localeCompare(right));
+    for (const group of groupNames) {
+        lines.push(`### ${group}`, "");
+        for (const graphPath of groups.get(group) ?? []) {
+            lines.push(`- [[${graphPath}]]`);
+        }
+        lines.push("");
+    }
+    lines.push(HOME_COVERAGE_BLOCK_END);
+    return lines.join("\n");
+}
+/**
+ * Write or replace the managed coverage block in `home.md`. The block is
+ * delimited by stable markers and fully rewritten each call, so agent-authored
+ * spine content outside the markers is preserved and re-running is idempotent. If
+ * `home.md` does not exist yet, a minimal spine carrying the block is created —
+ * home is part of the fixed skeleton, so ensuring it exists is legitimate.
+ */
+function writeCoverageBlockIntoHome(contextGraphPath, block) {
+    const homePath = join(contextGraphPath, HOME_SPINE_FILE);
+    if (!existsSync(homePath)) {
+        writeFileAtomic(homePath, `# Home\n\n${block}\n`);
+        return;
+    }
+    const current = readFileSync(homePath, "utf8");
+    const beginIndex = current.indexOf(HOME_COVERAGE_BLOCK_BEGIN);
+    const endIndex = current.indexOf(HOME_COVERAGE_BLOCK_END);
+    let next;
+    if (beginIndex >= 0 && endIndex > beginIndex) {
+        // Replace the existing managed block in place (idempotent).
+        const before = current.slice(0, beginIndex);
+        const after = current.slice(endIndex + HOME_COVERAGE_BLOCK_END.length);
+        next = `${before}${block}${after}`;
+    }
+    else {
+        // Append the managed block once, separated from existing spine content.
+        const trimmed = current.replace(/\s+$/g, "");
+        next = `${trimmed}\n\n${block}\n`;
+    }
+    if (next !== current)
+        writeFileAtomic(homePath, next);
+}
+/**
+ * Ensure `home.md` wikilinks every summary the build produced, via a managed,
+ * deterministic coverage block. Call this at build finalization, AFTER the stage
+ * agents have produced summaries, BEFORE the connectivity check runs. Guarantees
+ * every summary note has an inbound graph edge from the entrypoint spine
+ * regardless of agent behavior.
+ *
+ * Returns the count of linked summaries, or `null` when there is nothing to index
+ * (no `summaries/` layer). Never throws into the build: assembly is already
+ * complete; this is the connectivity floor laid on top.
+ */
+export function ensureSummaryCoverageIndex(contextGraphPath) {
+    if (!existsSync(contextGraphPath))
+        return null;
+    const graphPaths = listSummaryNoteGraphPaths(contextGraphPath);
+    if (graphPaths.length === 0)
+        return null;
+    writeCoverageBlockIntoHome(contextGraphPath, renderCoverageBlock(graphPaths));
+    return {
+        summaries: graphPaths.length,
+        indexPath: HOME_SPINE_FILE,
+    };
+}

package/dist/packages/runtime/build/traces.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+import type { ArtifactStatus, Readiness } from "../../contracts/lib/schema.js";
+import type { Traces } from "../../contracts/lib/project-schema.js";
+export interface BuildTracesInput {
+    projectId: string;
+    graphId: string;
+    readiness: Readiness | null;
+    artifacts: readonly ArtifactStatus[];
+    sourceFileCount: number;
+    filesProcessed?: number;
+    generatedAt?: string;
+}
+/**
+ * Build a Traces wire shape from the inputs available after a Build.
+ * Empty/safe when the Project has no Context Graph yet.
+ */
+export declare function buildTraces(input: BuildTracesInput): Traces;