@interf/compiler 0.33.0 → 0.50.0

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.js

@@ -25,7 +25,7 @@ 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; Build evidence or accepted stage evidence must provide the
+    // denominator; accepted Stage Manifest coverage or supplemental diagnostics must provide the
     // observed value.
     const filesProcessed = clampObservedCount(input.filesProcessed, sourceFiles);
     const filesTotal = sourceFiles;
@@ -62,8 +62,8 @@ export function buildTraces(input) {
             total: sourceFiles,
             passed: filesProcessed >= sourceFiles,
             detail: filesProcessed >= sourceFiles
-                ? "Build evidence covers every Source file."
-                : `${sourceFiles - filesProcessed} Source file${sourceFiles - filesProcessed === 1 ? "" : "s"} lack accepted Build evidence.`,
+                ? "Accepted coverage records cover every Source file."
+                : `${sourceFiles - filesProcessed} Source file${sourceFiles - filesProcessed === 1 ? "" : "s"} lack accepted coverage records.`,
         });
     }
     if (pagesRead >= 0) {

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

@@ -23,5 +23,5 @@ export declare function validateContextGraphSetup(dirPath: string): ContextGraph
 export declare function validateBuildStage(dirPath: string, stageId: string): BuildStageValidation;
 export declare function validateContextGraph(dirPath: string): ContextGraphValidation;
 export declare function validateBuildSummarize(dirPath: string): BuildStageValidation;
-export declare function validateContextGraphStructure(dirPath: string): BuildStageValidation;
+export declare function validateContextGraphKnowledge(dirPath: string): BuildStageValidation;
 export declare function validateBuildOutput(dirPath: string): ContextGraphValidation;

package/dist/packages/runtime/build/validate-context-graph.js

@@ -168,7 +168,7 @@ export function validateBuildStage(dirPath, stageId) {
         const artifacts = artifactsBuiltByStage(context.schema, buildPlanStage);
         const failures = artifactCheckFailures(dirPath, artifacts, artifactCounts);
         checks.artifact_diagnostics_ok = failures.length === 0;
-        artifactErrors = failures.map((result) => `Artifact diagnostic "${result.check_id}" failed for ${result.kind}: ${result.summary}`);
+        artifactErrors = failures.map((result) => `Requested output diagnostic "${result.check_id}" failed for ${result.kind}: ${result.summary}`);
     }
     else {
         checks.artifact_diagnostics_ok = false;
@@ -190,7 +190,7 @@ export function validateBuildStage(dirPath, stageId) {
         ? required
             ? `Stage "${stageId}" checks passed.`
             : `Stage "${stageId}" is not required yet.`
-        : `Stage "${stageId}" failed — ${errors[0] ?? "Artifact diagnostics not satisfied."}`;
+        : `Stage "${stageId}" failed — ${errors[0] ?? "stage output validation not satisfied."}`;
     return {
         ok,
         required,
@@ -257,7 +257,7 @@ export function validateContextGraph(dirPath) {
         stage: failedStage,
         summary: ok
             ? `Build Plan checks passed — ${completedStages}/${context.buildPlan.stages.length} stages satisfied.`
-            : `Build Plan failed — ${errors[0] ?? "stage Artifact diagnostics not satisfied."}`,
+            : `Build Plan failed — ${errors[0] ?? "stage output validation not satisfied."}`,
         counts: {
             source_total: context.sourceTotal,
             stage_total: context.buildPlan.stages.length,
@@ -271,8 +271,8 @@ export function validateContextGraph(dirPath) {
 export function validateBuildSummarize(dirPath) {
     return validateBuildStage(dirPath, "summarize");
 }
-export function validateContextGraphStructure(dirPath) {
-    return validateBuildStage(dirPath, "structure");
+export function validateContextGraphKnowledge(dirPath) {
+    return validateBuildStage(dirPath, "knowledge");
 }
 export function validateBuildOutput(dirPath) {
     return validateContextGraph(dirPath);

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

@@ -17,5 +17,5 @@ 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 { validateContextGraphSetup, validateBuildStage, validateContextGraph, validateBuildSummarize, validateContextGraphStructure, validateBuildOutput, } from "./validate-context-graph.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/runtime/build/validate.js

@@ -256,4 +256,4 @@ function addFrontmatterLinkTarget(targets, value) {
         }
     }
 }
-export { validateContextGraphSetup, validateBuildStage, validateContextGraph, validateBuildSummarize, validateContextGraphStructure, validateBuildOutput, } from "./validate-context-graph.js";
+export { validateContextGraphSetup, validateBuildStage, validateContextGraph, validateBuildSummarize, validateContextGraphKnowledge, validateBuildOutput, } from "./validate-context-graph.js";

package/dist/packages/runtime/client.d.ts

@@ -35,7 +35,7 @@ export declare function findLocalService(options?: {
 }): Promise<LocalServiceConnection | null>;
 export declare function submitBuildRunToLocalService(options: {
     projectId: string;
-    request: BuildRunCreateRequest;
+    request: Omit<BuildRunCreateRequest, "project">;
     idempotencyKey?: string;
 }): Promise<{
     serviceUrl: string;
@@ -43,14 +43,14 @@ export declare function submitBuildRunToLocalService(options: {
 } | null>;
 export declare function submitVerifyRunToLocalService(options: {
     projectId: string;
-    request: VerifyRunCreateRequest;
+    request: Omit<VerifyRunCreateRequest, "project">;
 }): Promise<{
     serviceUrl: string;
     resource: VerifyRunResource;
 } | null>;
 export declare function submitResetToLocalService(options: {
     projectId: string;
-    request: ResetRequest;
+    request: Omit<ResetRequest, "project">;
 }): Promise<{
     serviceUrl: string;
     result: ResetResult;

package/dist/packages/runtime/client.js

@@ -1,6 +1,7 @@
-import { BuildRunCreateRequestSchema, BuildRunListResponseSchema, BuildRunResourceSchema, RunObservabilityResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, BenchmarkQuestionDraftCreateRequestSchema, BenchmarkQuestionDraftResultSchema, ResetRequestSchema, ResetResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringResultSchema, } from "./schemas/index.js";
+import { BuildRunListResponseSchema, BuildRunResourceSchema, RunObservabilityResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, BenchmarkQuestionDraftCreateRequestSchema, BenchmarkQuestionDraftResultSchema, ResetResultSchema, ProjectBuildRunCreateRequestSchema, ProjectResetRequestSchema, ProjectVerifyRunCreateRequestSchema, VerifyRunResourceSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringResultSchema, } from "./schemas/index.js";
 import { LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, projectSubresourcePath, } from "./service/routes.js";
 import { INTERF_AUTH_TOKEN_ENV, readActiveConnection } from "./connection-config.js";
+import { isTerminalStatus } from "./runtime-status.js";
 async function connectOrNull(options = {}) {
     const conn = readActiveConnection({
         urlOverride: options.url ?? null,
@@ -86,7 +87,7 @@ export async function submitBuildRunToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = BuildRunCreateRequestSchema.parse(options.request);
+    const request = ProjectBuildRunCreateRequestSchema.parse(options.request);
     const headers = {
         ...authHeaders(connection.authToken),
         ...(options.idempotencyKey ? { "x-interf-idempotency-key": options.idempotencyKey } : {}),
@@ -106,7 +107,7 @@ export async function submitVerifyRunToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = VerifyRunCreateRequestSchema.parse(options.request);
+    const request = ProjectVerifyRunCreateRequestSchema.parse(options.request);
     const url = `${connection.serviceUrl}${projectSubresourcePath(options.projectId, "verifyRuns")}`;
     const resource = VerifyRunResourceSchema.parse(await fetchJson(url, {
         method: "POST",
@@ -122,7 +123,7 @@ export async function submitResetToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = ResetRequestSchema.parse(options.request);
+    const request = ProjectResetRequestSchema.parse(options.request);
     const url = `${connection.serviceUrl}${projectSubresourcePath(options.projectId, "reset")}`;
     const result = ResetResultSchema.parse(await fetchJson(url, {
         method: "POST",
@@ -179,12 +180,6 @@ export async function approveActionProposalInLocalService(options) {
     });
     return decided ?? proposal;
 }
-function isTerminalJobStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
-function isTerminalRunStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
 export async function getLocalBuildRun(options) {
     const headers = authHeaders(options.authToken ?? resolveLocalServiceAuthToken());
     const runValue = await fetchJson(`${options.serviceUrl}/v1/runs/${encodeURIComponent(options.runId)}`, {
@@ -244,7 +239,7 @@ export async function waitForLocalBuildRun(options) {
             authToken: options.authToken ?? null,
         });
         options.onUpdate?.(resource);
-        if (isTerminalRunStatus(resource.run.status))
+        if (isTerminalStatus(resource.run.status))
             return resource;
         await new Promise((resolveWait) => setTimeout(resolveWait, delay));
         if (explicit === undefined) {
@@ -270,7 +265,7 @@ export async function waitForLocalVerifyRun(options) {
             authToken: options.authToken ?? null,
         });
         options.onUpdate?.(resource);
-        if (isTerminalRunStatus(resource.status))
+        if (isTerminalStatus(resource.status))
             return resource;
         await new Promise((resolveWait) => setTimeout(resolveWait, delay));
         if (explicit === undefined) {
@@ -295,7 +290,7 @@ export async function waitForLocalJobRun(options) {
             authToken: options.authToken ?? null,
         });
         options.onUpdate?.(job);
-        if (isTerminalJobStatus(job.status))
+        if (isTerminalStatus(job.status))
             return job;
         if (options.timeoutMs && Date.now() - startedAt > options.timeoutMs) {
             throw new Error(`Timed out waiting for local job ${options.runId}.`);

package/dist/packages/runtime/context-checks.js

@@ -1,3 +1,16 @@
+// COMPAT — legacy Context Check derivation, scheduled for removal once the
+// Graph Manifest readiness rollup is the only path readers consume.
+//
+// The new product spine is primary_metrics + readiness in GraphManifest
+// (see internal/plans/stage-manifest-context-graph-execution-plan-2026-05-27.md
+// Phase 7). This module still runs because:
+//   1. runtime-build-runs writes context_checks into the immutable Run record
+//      so old Run records remain consistent.
+//   2. runtime-project-reads exposes a fallback "context-checks" gate when no
+//      GraphManifest exists yet (pre-refactor builds).
+// Removal path: once all live instances have at least one GraphManifest-backed
+// Build, drop the writes in runtime-build-runs and the fallback gate in
+// runtime-project-reads, then delete this file. Do not add new callers.
 import { ContextCheckSchema, } from "../contracts/lib/schema.js";
 import { slugify } from "../contracts/utils/naming.js";
 function boundedContextCheckId(value, fallback) {

package/dist/packages/runtime/context-graph-scaffold.js

@@ -79,7 +79,7 @@ export function ensureContextGraphScaffoldAt(options) {
     assertContextGraphContainer(projectDataDir);
     mkdirSync(contextGraphPath, { recursive: true });
     mkdirSync(testRootForContextGraph(contextGraphPath), { recursive: true });
-    if (buildPlanId === "interf-default") {
+    if (buildPlanId === DEFAULT_BUILD_PLAN_ID) {
         seedLocalDefaultBuildPlan({ projectDataDir });
     }
     const selectedBuildPlan = getBuildPlan(buildPlanId, { projectDataDir });
@@ -111,6 +111,7 @@ export function createContextGraph(name, projectDataDir, buildPlanId = DEFAULT_B
     saveContextGraphInterfConfig(contextGraphPath, {
         type: "context-graph",
         name,
+        intent: savedProject?.intent ?? "",
         build_plan: selectedBuildPlan.id,
         build_plan_origin: {
             selected: selectedBuildPlan.id,

package/dist/packages/runtime/context-graph-semantic-graph.d.ts

@@ -0,0 +1,9 @@
+import { type ContextGraphSemanticGraph } from "./schemas/index.js";
+import type { SourceManifest } from "../contracts/lib/schema.js";
+export declare function buildContextGraphSemanticGraph(options: {
+    contextGraphPath: string;
+    projectId: string;
+    generatedAt?: string;
+    sourceManifest?: SourceManifest | null;
+    entrypointPath?: string | null;
+}): ContextGraphSemanticGraph;