@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/build/stage-reuse.js

@@ -51,6 +51,11 @@ function buildPlanPackageHash(contextGraphPath) {
         hash: fileHash(file.path),
     }))));
 }
+function stageFingerprintProjectIntent(stageDefinition, projectIntent) {
+    if (stageDefinition.contractType === "build-file-evidence")
+        return null;
+    return projectIntent;
+}
 export function computeStageFingerprint(contextGraphPath, stageDefinition) {
     const stageInputs = loadBuildStageInputs(contextGraphPath, stageDefinition.id);
     if (!stageInputs)
@@ -67,6 +72,10 @@ export function computeStageFingerprint(contextGraphPath, stageDefinition) {
             id: plan.context.buildPlanId,
             package_hash: buildPlanPackageHash(contextGraphPath),
         },
+        project: {
+            id: plan.context.project.id,
+            intent: stageFingerprintProjectIntent(stageDefinition, plan.context.projectIntent),
+        },
         source_manifest: {
             manifest_id: sourceManifest.manifest_id,
             generated_at: sourceManifest.generated_at,
@@ -104,6 +113,9 @@ export function computeStageFingerprint(contextGraphPath, stageDefinition) {
                 }))
                     .sort((left, right) => `${left.artifact_id}:${left.path}`.localeCompare(`${right.artifact_id}:${right.path}`)),
             },
+            context_checks: stageDefinition.contractType === "build-file-evidence"
+                ? []
+                : [...plan.contract.context_checks],
         },
     };
     return StageFingerprintSchema.parse(sha256(stableJson(payload)));

package/dist/packages/runtime/build/stage-session.d.ts

@@ -0,0 +1,81 @@
+import { type AgentExecutor } from "../agents/lib/executors.js";
+import { type ExecutionStageLedger, type RuntimeStageContract, type StageExecutionSession } from "./lib/schema.js";
+import type { AgentJobType } from "./lib/schema.js";
+import type { BuildPlanId, ProjectId, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage } from "../../contracts/lib/schema.js";
+export declare function writeStageExecutionSessionStarted(options: {
+    contextGraphPath: string;
+    jobType?: AgentJobType;
+    project: ProjectId;
+    projectIntent?: string | null;
+    buildPlanId: BuildPlanId;
+    buildRunId?: string | null;
+    stageId: RuntimeStage | null;
+    stageLabel: string | null;
+    contractType: RuntimeContractType | null;
+    stageRunId: string;
+    attempt?: number;
+    executor: RuntimeExecutorInfo | AgentExecutor;
+    shellRoot: string | null;
+    contractPath: string | null;
+    promptPath: string | null;
+    eventStreamPath: string | null;
+    statusPath: string | null;
+    summary: string | null;
+}): StageExecutionSession;
+export declare function writeStageExecutionSessionStartedFromLedger(options: {
+    contextGraphPath: string;
+    run: ExecutionStageLedger;
+    contract: RuntimeStageContract;
+    buildRunId?: string | null;
+    shellRoot: string | null;
+    promptPath: string | null;
+    eventStreamPath: string | null;
+    statusPath: string | null;
+}): StageExecutionSession;
+/**
+ * Project the terminal session state from a finished ExecutionStageLedger. The
+ * session is a projection of the ledger, so the ledger→session field mapping
+ * (stage, run id, terminal status, summary, error) lives HERE, once, instead of
+ * being re-stated by hand at every ledger-terminal write site. A `running`
+ * ledger is not terminal and is ignored (no-op) so callers can pass the record
+ * unconditionally. Returns null when no session exists for the run (same
+ * contract as `writeStageExecutionSessionFinished`).
+ */
+export declare function projectSessionFinishedFromLedger(contextGraphPath: string, ledger: ExecutionStageLedger): StageExecutionSession | null;
+export declare function writeStageExecutionSessionFinished(options: {
+    contextGraphPath: string;
+    stageId: string | null;
+    stageRunId: string;
+    status: "succeeded" | "failed";
+    summary: string;
+    error?: string | null;
+}): StageExecutionSession | null;
+export declare function recordStageExecutionSessionValidationAttempt(options: {
+    contextGraphPath: string;
+    stageId: string;
+    stageRunId: string;
+    attempt: number;
+    status: "succeeded" | "failed";
+    summary: string;
+}): StageExecutionSession | null;
+export declare function markStageExecutionSessionsShellPreserved(options: {
+    contextGraphPath: string;
+    shellRoot: string;
+}): void;
+/**
+ * Reconcile sessions after their stage execution shells were pruned. The build
+ * pipeline deletes the whole execution-shells root on a successful build under
+ * non-"always" retention, but the session records live in a SEPARATE
+ * stage-sessions dir and would keep pointing at the deleted shell with
+ * `replay_ready: true` — a dangling pointer (F2). For every session whose shell
+ * root no longer exists on disk, downgrade it so "session exists" still implies
+ * "session is real": `replay_ready` false, preserved-shell manifest path
+ * nulled, and a retention reason recorded. Already-downgraded sessions and
+ * sessions whose shell still exists are left untouched. Best-effort and
+ * idempotent; runs in the build's `finally`, so it must never throw.
+ */
+export declare function reconcilePrunedStageExecutionSessions(options: {
+    contextGraphPath: string;
+    reason?: string;
+}): void;
+export declare function listStageExecutionSessions(contextGraphPath: string): StageExecutionSession[];

package/dist/packages/runtime/build/stage-session.js

@@ -0,0 +1,308 @@
+import { existsSync, readFileSync, readdirSync, } from "node:fs";
+import { isAbsolute, join, relative, } from "node:path";
+import { preservedShellManifestPath, shellWorkspaceManifestPath, } from "../agents/lib/shell-paths.js";
+import { buildRuntimeExecutorInfo, } from "../agents/lib/executors.js";
+import { contextGraphRuntimeStageSessionPath, contextGraphRuntimeStageSessionsRoot, } from "./context-graph-paths.js";
+import { writeJsonAtomic } from "./atomic-fs.js";
+import { ExecutionShellPathsSchema, StageExecutionSessionSchema, } from "./lib/schema.js";
+function contextRelative(contextGraphPath, path) {
+    if (!path)
+        return null;
+    const rel = isAbsolute(path) ? relative(contextGraphPath, path) : path;
+    return rel.replaceAll("\\", "/");
+}
+function shellRuntimeFile(contextGraphPath, shellRoot, fileName) {
+    if (!shellRoot)
+        return null;
+    return contextRelative(contextGraphPath, join(shellRoot, "runtime", fileName));
+}
+/**
+ * Context-relative path to a shell runtime file ONLY when it exists on disk.
+ * Used for artifacts that are written DURING the run (e.g. the agent reasoning
+ * transcript), so a session never advertises a dangling path: null at session
+ * start (the file does not exist yet, and a non-reasoning run never creates it),
+ * the real path once it has been teed. `shellRootRel` is the context-relative
+ * shell root (`.` for the no-shell case, which has no runtime dir to reference).
+ */
+function runtimeFileIfExists(contextGraphPath, shellRootRel, fileName) {
+    if (!shellRootRel || shellRootRel === ".")
+        return null;
+    const rel = `${shellRootRel.replace(/\/+$/, "")}/runtime/${fileName}`;
+    return existsSync(join(contextGraphPath, rel)) ? rel : null;
+}
+function readShellPaths(shellRoot) {
+    if (!shellRoot)
+        return null;
+    const filePath = join(shellRoot, "runtime", "paths.json");
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return ExecutionShellPathsSchema.parse(JSON.parse(readFileSync(filePath, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+// Stage jobs key the session dir off `stage_id`. Non-stage jobs (job_type !==
+// "stage"/"source-inventory") carry a null stage_id, so they bucket under a
+// stable "_job" segment keyed by stage_run_id. Stage layout is unchanged: every
+// current writer passes a real stage id.
+function stageSessionPath(contextGraphPath, stageId, stageRunId) {
+    return contextGraphRuntimeStageSessionPath(contextGraphPath, stageId ?? "_job", stageRunId);
+}
+function readSessionAt(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return StageExecutionSessionSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+function readSession(contextGraphPath, stageId, stageRunId) {
+    return readSessionAt(stageSessionPath(contextGraphPath, stageId, stageRunId));
+}
+function writeSession(contextGraphPath, session) {
+    const parsed = StageExecutionSessionSchema.parse(session);
+    writeJsonAtomic(stageSessionPath(contextGraphPath, parsed.stage_id, parsed.stage_run_id), parsed);
+    return parsed;
+}
+function nextAttemptForStage(contextGraphPath, stageId) {
+    return listStageExecutionSessions(contextGraphPath)
+        .filter((session) => session.stage_id === stageId)
+        .length + 1;
+}
+export function writeStageExecutionSessionStarted(options) {
+    const now = new Date().toISOString();
+    const shellRoot = options.shellRoot;
+    const paths = readShellPaths(shellRoot);
+    const shellRootPath = contextRelative(options.contextGraphPath, shellRoot) ?? ".";
+    const workspacePath = shellRoot ? shellWorkspaceManifestPath(shellRoot) : null;
+    const preservedPath = shellRoot ? preservedShellManifestPath(shellRoot) : null;
+    const executor = "execute" in options.executor
+        ? buildRuntimeExecutorInfo(options.executor)
+        : options.executor;
+    const existing = readSession(options.contextGraphPath, options.stageId, options.stageRunId);
+    return writeSession(options.contextGraphPath, {
+        kind: "interf-stage-execution-session",
+        version: 1,
+        job_type: existing?.job_type ?? options.jobType ?? "stage",
+        generated_at: existing?.generated_at ?? now,
+        updated_at: now,
+        project: options.project,
+        project_intent: options.projectIntent ?? null,
+        context_graph_path: options.contextGraphPath,
+        build_plan: options.buildPlanId,
+        build_run_id: options.buildRunId ?? null,
+        stage_id: options.stageId,
+        stage_label: options.stageLabel,
+        contract_type: options.contractType,
+        stage_run_id: options.stageRunId,
+        attempt: existing?.attempt ?? options.attempt ?? nextAttemptForStage(options.contextGraphPath, options.stageId),
+        status: existing?.status ?? "running",
+        executor,
+        shell: {
+            root_path: shellRootPath,
+            workspace_manifest_path: workspacePath && existsSync(workspacePath)
+                ? contextRelative(options.contextGraphPath, workspacePath)
+                : null,
+            preserved_shell_manifest_path: preservedPath && existsSync(preservedPath)
+                ? contextRelative(options.contextGraphPath, preservedPath)
+                : null,
+            replay_ready: Boolean(shellRoot && existsSync(join(shellRoot, "AGENTS.md"))),
+            retention_reason: existing?.shell.retention_reason ?? null,
+        },
+        logs: {
+            prompt_path: contextRelative(options.contextGraphPath, options.promptPath),
+            event_stream_path: contextRelative(options.contextGraphPath, options.eventStreamPath),
+            status_path: contextRelative(options.contextGraphPath, options.statusPath),
+        },
+        runtime_files: {
+            project_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "project.json"),
+            contract_path: contextRelative(options.contextGraphPath, options.contractPath),
+            paths_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "paths.json"),
+            source_locator_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "source-locator.json"),
+            source_manifest_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "source-manifest.json"),
+            source_state_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "source-state.json"),
+            stage_inputs_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "stage-inputs.json"),
+            expected_inputs_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "expected-inputs.json"),
+            reviewed_inputs_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "reviewed-inputs.json"),
+            previous_attempts_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "previous-attempts.json"),
+            retry_feedback_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "retry-feedback.md"),
+            last_validation_failure_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "last-validation-failure.txt"),
+            verifier_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "check-stage.mjs"),
+            stage_evidence_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "stage-evidence.json"),
+            reasoning_path: existing?.runtime_files.reasoning_path
+                ?? runtimeFileIfExists(options.contextGraphPath, shellRootPath, "agent-reasoning.jsonl"),
+        },
+        artifacts: {
+            reads: paths?.reads ?? [],
+            writes: paths?.writes ?? [],
+        },
+        validation_attempts: existing?.validation_attempts ?? [],
+        summary: options.summary,
+        error: existing?.error ?? null,
+    });
+}
+export function writeStageExecutionSessionStartedFromLedger(options) {
+    return writeStageExecutionSessionStarted({
+        contextGraphPath: options.contextGraphPath,
+        project: options.contract.project.id,
+        projectIntent: options.contract.project.intent,
+        buildPlanId: options.contract.build_plan.id,
+        buildRunId: options.buildRunId ?? null,
+        stageId: options.run.stage,
+        stageLabel: options.run.stage_label,
+        contractType: options.run.contract_type,
+        stageRunId: options.run.run_id,
+        executor: options.run.executor,
+        shellRoot: options.shellRoot,
+        contractPath: options.shellRoot
+            ? join(options.shellRoot, "runtime", "stage-contract.json")
+            : join(options.contextGraphPath, options.run.contract_path),
+        promptPath: options.promptPath,
+        eventStreamPath: options.eventStreamPath,
+        statusPath: options.statusPath,
+        summary: options.run.summary,
+    });
+}
+/**
+ * Project the terminal session state from a finished ExecutionStageLedger. The
+ * session is a projection of the ledger, so the ledger→session field mapping
+ * (stage, run id, terminal status, summary, error) lives HERE, once, instead of
+ * being re-stated by hand at every ledger-terminal write site. A `running`
+ * ledger is not terminal and is ignored (no-op) so callers can pass the record
+ * unconditionally. Returns null when no session exists for the run (same
+ * contract as `writeStageExecutionSessionFinished`).
+ */
+export function projectSessionFinishedFromLedger(contextGraphPath, ledger) {
+    if (ledger.status === "running")
+        return null;
+    return writeStageExecutionSessionFinished({
+        contextGraphPath,
+        stageId: ledger.stage,
+        stageRunId: ledger.run_id,
+        status: ledger.status,
+        summary: ledger.summary,
+        error: ledger.error,
+    });
+}
+export function writeStageExecutionSessionFinished(options) {
+    const current = readSession(options.contextGraphPath, options.stageId, options.stageRunId);
+    if (!current)
+        return null;
+    return writeSession(options.contextGraphPath, {
+        ...current,
+        updated_at: new Date().toISOString(),
+        status: options.status,
+        summary: options.summary,
+        error: options.error ?? null,
+        runtime_files: {
+            ...current.runtime_files,
+            // The reasoning transcript is teed DURING the run, so resolve it at finish:
+            // set the path iff the agent actually emitted reasoning (file exists), else
+            // leave null. Keeps "session references a reasoning file" => "the file is real".
+            reasoning_path: current.runtime_files.reasoning_path
+                ?? runtimeFileIfExists(options.contextGraphPath, current.shell.root_path, "agent-reasoning.jsonl"),
+        },
+    });
+}
+export function recordStageExecutionSessionValidationAttempt(options) {
+    const current = readSession(options.contextGraphPath, options.stageId, options.stageRunId);
+    if (!current)
+        return null;
+    const withoutExisting = current.validation_attempts
+        .filter((attempt) => attempt.attempt !== options.attempt);
+    return writeSession(options.contextGraphPath, {
+        ...current,
+        updated_at: new Date().toISOString(),
+        validation_attempts: [
+            ...withoutExisting,
+            {
+                attempt: options.attempt,
+                recorded_at: new Date().toISOString(),
+                status: options.status,
+                summary: options.summary,
+            },
+        ].sort((left, right) => left.attempt - right.attempt),
+    });
+}
+export function markStageExecutionSessionsShellPreserved(options) {
+    const shellRootPath = contextRelative(options.contextGraphPath, options.shellRoot);
+    const preservedPath = preservedShellManifestPath(options.shellRoot);
+    const preservedRel = existsSync(preservedPath)
+        ? contextRelative(options.contextGraphPath, preservedPath)
+        : null;
+    for (const session of listStageExecutionSessions(options.contextGraphPath)) {
+        if (session.shell.root_path !== shellRootPath)
+            continue;
+        writeSession(options.contextGraphPath, {
+            ...session,
+            updated_at: new Date().toISOString(),
+            shell: {
+                ...session.shell,
+                preserved_shell_manifest_path: preservedRel,
+                replay_ready: session.shell.replay_ready && existsSync(join(options.shellRoot, "AGENTS.md")),
+            },
+        });
+    }
+}
+/**
+ * Reconcile sessions after their stage execution shells were pruned. The build
+ * pipeline deletes the whole execution-shells root on a successful build under
+ * non-"always" retention, but the session records live in a SEPARATE
+ * stage-sessions dir and would keep pointing at the deleted shell with
+ * `replay_ready: true` — a dangling pointer (F2). For every session whose shell
+ * root no longer exists on disk, downgrade it so "session exists" still implies
+ * "session is real": `replay_ready` false, preserved-shell manifest path
+ * nulled, and a retention reason recorded. Already-downgraded sessions and
+ * sessions whose shell still exists are left untouched. Best-effort and
+ * idempotent; runs in the build's `finally`, so it must never throw.
+ */
+export function reconcilePrunedStageExecutionSessions(options) {
+    const reason = options.reason
+        ?? "Stage execution shell pruned after a successful Build (on-failure retention).";
+    for (const session of listStageExecutionSessions(options.contextGraphPath)) {
+        const shellRootAbsolute = join(options.contextGraphPath, session.shell.root_path);
+        if (existsSync(shellRootAbsolute))
+            continue;
+        if (!session.shell.replay_ready
+            && session.shell.preserved_shell_manifest_path === null
+            && session.shell.retention_reason !== null) {
+            continue;
+        }
+        writeSession(options.contextGraphPath, {
+            ...session,
+            updated_at: new Date().toISOString(),
+            shell: {
+                ...session.shell,
+                preserved_shell_manifest_path: null,
+                replay_ready: false,
+                retention_reason: reason,
+            },
+        });
+    }
+}
+export function listStageExecutionSessions(contextGraphPath) {
+    const root = contextGraphRuntimeStageSessionsRoot(contextGraphPath);
+    if (!existsSync(root))
+        return [];
+    const sessions = [];
+    for (const stageId of readdirSync(root)) {
+        const stageRoot = join(root, stageId);
+        if (!existsSync(stageRoot))
+            continue;
+        for (const stageRunId of readdirSync(stageRoot)) {
+            const session = readSessionAt(join(stageRoot, stageRunId, "session.json"));
+            if (session)
+                sessions.push(session);
+        }
+    }
+    return sessions.sort((left, right) => {
+        const byGenerated = Date.parse(left.generated_at) - Date.parse(right.generated_at);
+        if (byGenerated !== 0)
+            return byGenerated;
+        return left.stage_run_id.localeCompare(right.stage_run_id);
+    });
+}

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

@@ -3,11 +3,10 @@ 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 { healthPath, sourceManifestPath, sourceFilesPath, sourceStatePath, statePath, viewSpecPath, } from "./state-paths.js";
-import { contextGraphExecutionInventoryPath, } from "./context-graph-paths.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 = statePath(dirPath);
+    const path = contextGraphRuntimeStatePath(dirPath);
     if (!existsSync(path))
         return null;
     const raw = readJsonFileUnchecked(path, "runtime state");
@@ -21,28 +20,28 @@ export function loadState(dirPath) {
     return null;
 }
 export function saveState(dirPath, state) {
-    writeJsonAtomic(statePath(dirPath), state);
+    writeJsonAtomic(contextGraphRuntimeStatePath(dirPath), state);
 }
 export function loadContextGraphHealth(dirPath) {
-    const path = healthPath(dirPath);
+    const path = contextGraphRuntimeHealthPath(dirPath);
     if (!existsSync(path))
         return null;
     return readJsonFileWithSchema(path, "context-graph health", ContextGraphHealthSchema);
 }
 export function saveContextGraphHealth(dirPath, health) {
-    writeJsonAtomic(healthPath(dirPath), health);
+    writeJsonAtomic(contextGraphRuntimeHealthPath(dirPath), health);
 }
 export function loadContextGraphViewSpec(dirPath) {
-    const path = viewSpecPath(dirPath);
+    const path = contextGraphRuntimeViewSpecPath(dirPath);
     if (!existsSync(path))
         return null;
     return loadViewSpec(path, ContextGraphViewSpecSchema);
 }
 export function saveContextGraphViewSpec(dirPath, viewSpec) {
-    writeJsonAtomic(viewSpecPath(dirPath), viewSpec);
+    writeJsonAtomic(contextGraphRuntimeViewSpecPath(dirPath), viewSpec);
 }
 export function loadContextGraphSourceManifest(dirPath) {
-    const path = sourceManifestPath(dirPath);
+    const path = contextGraphRuntimeSourceManifestPath(dirPath);
     if (!existsSync(path))
         return null;
     return readJsonFileWithSchema(path, "context-graph source manifest", SourceManifestSchema);
@@ -64,7 +63,7 @@ export function loadContextGraphSourceFiles(dirPath) {
             })),
         });
     }
-    const path = sourceFilesPath(dirPath);
+    const path = contextGraphRuntimeSourceFilesPath(dirPath);
     if (!existsSync(path))
         return null;
     return readJsonFileWithSchema(path, "context-graph source files", SourceFilesSchema);
@@ -88,7 +87,7 @@ export function loadContextGraphSourceState(dirPath) {
             })),
         });
     }
-    const path = sourceStatePath(dirPath);
+    const path = contextGraphRuntimeSourceStatePath(dirPath);
     if (!existsSync(path))
         return null;
     return readJsonFileWithSchema(path, "context-graph source state", SourceStateSchema);

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

@@ -113,7 +113,7 @@ function buildDefaultContextGraphViewSpec(dirPath, contextGraphName, generatedAt
             { 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: "Output Artifacts", paths: outputDocumentPaths }]
+                ? [{ 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

@@ -1,5 +1,5 @@
 export type { RuntimeStatus, BuildStage, ContextGraphState, ContextGraphHealth, ViewSection, ViewCard, ContextGraphViewSpec, SourceFiles, SourceState, StageInputs, } from "./lib/schema.js";
-export { statePath, healthPath, viewSpecPath, sourceFilesPath, sourceStatePath, } from "./state-paths.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";

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

@@ -1,4 +1,4 @@
-export { statePath, healthPath, viewSpecPath, sourceFilesPath, sourceStatePath, } from "./state-paths.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";

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;