@interf/compiler 0.33.0 → 0.50.0

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

@@ -1,9 +1,10 @@
 import { type ArtifactRef, type BuildRun, type InterfRunEvent, type EvidenceRecord } from "./execution/lib/schema.js";
 import { type RunEventSink } from "./execution/events.js";
-import { RunListingCache, ReadinessCache, MtimeListingCache, BuildPlanListingCache } from "./runtime-caches.js";
+import { RunListingCache, ReadinessCache, MtimeListingCache, BuildPlanListingCache, ContextGraphResourceCache } from "./runtime-caches.js";
 import { type Readiness } from "../contracts/lib/schema.js";
+import type { ContextGraphHandoff } from "../contracts/lib/project-schema.js";
 import type { ProjectConfig } from "../projects/lib/schema.js";
-import type { ActionProposalCreateRequest, ActionProposalPlan, ActionProposalResource, BuildPlanAuthoringRuntimeRequest, BuildPlanAuthoringResult, BuildPlanChangeResult, BuildPlanResource, BuildRunCreateRequest, BuildRunResource, LocalExecutorStatus, LocalJobEvent, LocalJobEventAppendRequest, LocalJobRunResource, LocalRunHandlerResult, LocalServiceHealth, ProjectResource, BenchmarkQuestionDraftRuntimeRequest, BenchmarkQuestionDraftResult, ResetResult, RunObservabilityResource, SourceFileResource, ContextGraphResource, VerifyRunCreateRequest, VerifyRunResource } from "./schemas/index.js";
+import type { ActionProposalCreateRequest, ActionProposalPlan, ActionProposalResource, BuildPlanAuthoringRuntimeRequest, BuildPlanAuthoringResult, BuildPlanChangeResult, BuildPlanResource, BuildRunCreateRequest, BuildRunResource, LocalExecutorStatus, LocalJobEvent, LocalJobEventAppendRequest, LocalJobRunResource, LocalRunHandlerResult, LocalServiceHealth, ProjectResource, BenchmarkQuestionDraftRuntimeRequest, BenchmarkQuestionDraftResult, ResetResult, RunObservabilityResource, SourceFileResource, ContextGraphResource, StageExecutionSession, VerifyRunCreateRequest, VerifyRunResource } from "./schemas/index.js";
 import { type AgentsRegistryRoleState, type AgentsRegistryState } from "./runtime-executor.js";
 import type { AgentPrefs, AgentRecord, RoleMap } from "../contracts/lib/schema.js";
 export interface LocalServiceBuildRunContext {
@@ -388,7 +389,7 @@ export declare class LocalServiceRuntime {
                 version: 1;
                 generated_at: string;
                 project: string;
-                status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale";
+                status: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale";
                 ready: boolean;
                 summary: string;
                 context_graph_path: string | null;
@@ -396,7 +397,7 @@ export declare class LocalServiceRuntime {
                     gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
                     ok: boolean;
                     summary: string;
-                    status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+                    status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
                     detail?: string | undefined;
                     run_id?: string | null | undefined;
                     artifact_path?: string | null | undefined;
@@ -427,7 +428,7 @@ export declare class LocalServiceRuntime {
                     gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
                     ok: boolean;
                     summary: string;
-                    status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+                    status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
                     detail?: string | undefined;
                     run_id?: string | null | undefined;
                     artifact_path?: string | null | undefined;
@@ -449,11 +450,11 @@ export declare class LocalServiceRuntime {
         }[];
         artifacts: {
             artifact_id: string;
-            status: "failed" | "skipped" | "ready" | "not_ready";
+            status: "ready" | "failed" | "skipped" | "not_ready";
             built_by_stages: string[];
             check_results: {
                 check_id: string;
-                kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                 passed: boolean;
                 required: boolean;
                 summary: string;
@@ -490,7 +491,7 @@ export declare class LocalServiceRuntime {
             version: 1;
             generated_at: string;
             project: string;
-            status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale";
+            status: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale";
             ready: boolean;
             summary: string;
             context_graph_path: string | null;
@@ -498,7 +499,7 @@ export declare class LocalServiceRuntime {
                 gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
                 ok: boolean;
                 summary: string;
-                status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+                status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
                 detail?: string | undefined;
                 run_id?: string | null | undefined;
                 artifact_path?: string | null | undefined;
@@ -529,7 +530,7 @@ export declare class LocalServiceRuntime {
                 gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
                 ok: boolean;
                 summary: string;
-                status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+                status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
                 detail?: string | undefined;
                 run_id?: string | null | undefined;
                 artifact_path?: string | null | undefined;
@@ -745,7 +746,7 @@ export declare class LocalServiceRuntime {
                 version: 1;
                 generated_at: string;
                 project: string;
-                status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale";
+                status: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale";
                 ready: boolean;
                 summary: string;
                 context_graph_path: string | null;
@@ -753,7 +754,7 @@ export declare class LocalServiceRuntime {
                     gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
                     ok: boolean;
                     summary: string;
-                    status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+                    status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
                     detail?: string | undefined;
                     run_id?: string | null | undefined;
                     artifact_path?: string | null | undefined;
@@ -784,7 +785,7 @@ export declare class LocalServiceRuntime {
                     gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
                     ok: boolean;
                     summary: string;
-                    status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+                    status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
                     detail?: string | undefined;
                     run_id?: string | null | undefined;
                     artifact_path?: string | null | undefined;
@@ -820,7 +821,7 @@ export declare class LocalServiceRuntime {
             version: 1;
             generated_at: string;
             project: string;
-            status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale";
+            status: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale";
             ready: boolean;
             summary: string;
             context_graph_path: string | null;
@@ -828,7 +829,7 @@ export declare class LocalServiceRuntime {
                 gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
                 ok: boolean;
                 summary: string;
-                status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+                status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
                 detail?: string | undefined;
                 run_id?: string | null | undefined;
                 artifact_path?: string | null | undefined;
@@ -859,7 +860,7 @@ export declare class LocalServiceRuntime {
                 gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
                 ok: boolean;
                 summary: string;
-                status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+                status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
                 detail?: string | undefined;
                 run_id?: string | null | undefined;
                 artifact_path?: string | null | undefined;
@@ -874,7 +875,7 @@ export declare class LocalServiceRuntime {
         version: 1;
         generated_at: string;
         project: string;
-        status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale";
+        status: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale";
         ready: boolean;
         summary: string;
         context_graph_path: string | null;
@@ -882,7 +883,7 @@ export declare class LocalServiceRuntime {
             gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
             ok: boolean;
             summary: string;
-            status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+            status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
             detail?: string | undefined;
             run_id?: string | null | undefined;
             artifact_path?: string | null | undefined;
@@ -913,7 +914,7 @@ export declare class LocalServiceRuntime {
             gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
             ok: boolean;
             summary: string;
-            status?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "stale" | undefined;
+            status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
             detail?: string | undefined;
             run_id?: string | null | undefined;
             artifact_path?: string | null | undefined;
@@ -946,6 +947,7 @@ export declare class LocalServiceRuntime {
         }[];
         source_kind: "builtin" | "local";
         built_in: boolean;
+        scope: "builtin" | "user" | "local";
         active_for_projects: string[];
         context_checks: {
             id: string;
@@ -965,7 +967,7 @@ export declare class LocalServiceRuntime {
             };
             checks: {
                 id: string;
-                kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                 required: boolean;
                 description?: string | undefined;
                 params?: Record<string, unknown> | undefined;
@@ -1000,7 +1002,7 @@ export declare class LocalServiceRuntime {
                 output?: {
                     checks: {
                         id: string;
-                        kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                        kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                         required: boolean;
                         description?: string | undefined;
                         params?: Record<string, unknown> | undefined;
@@ -1032,7 +1034,7 @@ export declare class LocalServiceRuntime {
                 };
                 checks: {
                     id: string;
-                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                     required: boolean;
                     description?: string | undefined;
                     params?: Record<string, unknown> | undefined;
@@ -1055,7 +1057,420 @@ export declare class LocalServiceRuntime {
                 summary?: string | undefined;
             } | null | undefined;
         } | undefined;
+        created_at?: string | null | undefined;
+        updated_at?: string | null | undefined;
     }[]>;
+    /**
+     * Per-Build-run Context Graph resource cache. A succeeded Build's graph is
+     * immutable, so the full `ContextGraphResource` (readiness join, semantic
+     * graph, evidence, validation) is memoized keyed by run id + graph-manifest
+     * mtime. Busted on Build completion and Build Plan change via
+     * `invalidateProject` on the matching write paths.
+     */
+    readonly contextGraphResourceCache: ContextGraphResourceCache<{
+        kind: "interf-context-graph";
+        version: 1;
+        intent: string;
+        project: string;
+        path: string;
+        exists: boolean;
+        readiness: {
+            kind: "interf-readiness-state";
+            version: 1;
+            generated_at: string;
+            project: string;
+            status: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale";
+            ready: boolean;
+            summary: string;
+            context_graph_path: string | null;
+            build: {
+                gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
+                ok: boolean;
+                summary: string;
+                status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
+                detail?: string | undefined;
+                run_id?: string | null | undefined;
+                artifact_path?: string | null | undefined;
+            } | null;
+            check_results: {
+                configured: number;
+                fingerprint: string | null;
+                source_files: {
+                    passed: number;
+                    total: number;
+                    pass_rate: number | null;
+                    stale: boolean;
+                    checks_fingerprint?: string | null | undefined;
+                    run_id?: string | null | undefined;
+                    run_path?: string | null | undefined;
+                } | null;
+                context_graph: {
+                    passed: number;
+                    total: number;
+                    pass_rate: number | null;
+                    stale: boolean;
+                    checks_fingerprint?: string | null | undefined;
+                    run_id?: string | null | undefined;
+                    run_path?: string | null | undefined;
+                } | null;
+            };
+            checks: {
+                gate: "context-graph" | "project-config" | "build-run" | "artifact-diagnostics" | "context-checks" | "benchmarks" | "benchmarks-current";
+                ok: boolean;
+                summary: string;
+                status?: "ready" | "not-ready" | "failed" | "not-configured" | "not-built" | "building" | "built" | "checking" | "stale" | undefined;
+                detail?: string | undefined;
+                run_id?: string | null | undefined;
+                artifact_path?: string | null | undefined;
+            }[];
+            latest_build_run_id?: string | null | undefined;
+            latest_benchmark_run_id?: string | null | undefined;
+        };
+        artifact_handoffs: {
+            label: string;
+            locator: {
+                kind: "local-path" | "remote-url" | "api-served";
+                value: string;
+            };
+            role: "entrypoint" | "artifact" | "guidance" | "source-index";
+            artifact_id?: string | undefined;
+            path?: string | undefined;
+            artifact_kind?: "file" | "directory" | undefined;
+            summary?: string | undefined;
+        }[];
+        artifacts: {
+            path: string;
+            role: "runtime" | "output" | "source" | "evidence" | "benchmark";
+            stage_id?: string | null | undefined;
+            label?: string | undefined;
+            sha256?: string | undefined;
+        }[];
+        primary_metrics: {
+            key: string;
+            label: string;
+            value: number;
+            primary: boolean;
+            total?: number | undefined;
+            unit?: string | undefined;
+            issue_state?: "pass" | "fail" | "missing" | "review" | undefined;
+            detail?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        stage_summaries: {
+            stage_id: string;
+            stage_label: string;
+            role: "source" | "summary" | "other" | "knowledge" | "entrypoint" | "diagnostic";
+            manifest_path: string;
+            summary: string;
+            produced_total: number;
+            missing_required_total: number;
+            metrics: {
+                key: string;
+                label: string;
+                value: number;
+                primary: boolean;
+                total?: number | undefined;
+                unit?: string | undefined;
+                issue_state?: "pass" | "fail" | "missing" | "review" | undefined;
+                detail?: string | undefined;
+                metadata?: Record<string, unknown> | undefined;
+            }[];
+        }[];
+        entrypoints: {
+            id: string;
+            role: "source" | "summary" | "other" | "knowledge" | "entrypoint" | "diagnostic";
+            kind: string;
+            label: string;
+            source_refs: string[];
+            links: string[];
+            required: boolean;
+            path?: string | undefined;
+            locator?: string | undefined;
+            stage_id?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        resources: {
+            id: string;
+            role: "source" | "summary" | "other" | "knowledge" | "entrypoint" | "diagnostic";
+            kind: string;
+            label: string;
+            source_refs: string[];
+            links: string[];
+            required: boolean;
+            path?: string | undefined;
+            locator?: string | undefined;
+            stage_id?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        stage_sessions: {
+            kind: "interf-stage-execution-session";
+            version: 1;
+            job_type: "stage" | "source-inventory";
+            generated_at: string;
+            updated_at: string;
+            project: string;
+            project_intent: string | null;
+            context_graph_path: string;
+            build_plan: string;
+            build_run_id: string | null;
+            stage_id: string | null;
+            stage_label: string | null;
+            contract_type: string | null;
+            stage_run_id: string;
+            attempt: number;
+            status: "running" | "failed" | "succeeded";
+            executor: {
+                kind: "local-agent" | "connected-provider" | "managed";
+                name: string;
+                display_name: string;
+                command: string | null;
+                model?: string | null | undefined;
+                effort?: string | null | undefined;
+                profile?: string | null | undefined;
+                timeout_ms?: number | null | undefined;
+            };
+            shell: {
+                root_path: string;
+                workspace_manifest_path: string | null;
+                preserved_shell_manifest_path: string | null;
+                replay_ready: boolean;
+                retention_reason: string | null;
+            };
+            logs: {
+                prompt_path: string | null;
+                event_stream_path: string | null;
+                status_path: string | null;
+            };
+            runtime_files: {
+                project_path: string | null;
+                contract_path: string | null;
+                paths_path: string | null;
+                source_locator_path: string | null;
+                source_manifest_path: string | null;
+                source_state_path: string | null;
+                stage_inputs_path: string | null;
+                expected_inputs_path: string | null;
+                reviewed_inputs_path: string | null;
+                previous_attempts_path: string | null;
+                retry_feedback_path: string | null;
+                last_validation_failure_path: string | null;
+                verifier_path: string | null;
+                stage_evidence_path: string | null;
+                reasoning_path: string | null;
+            };
+            artifacts: {
+                reads: {
+                    artifact_id: string;
+                    artifact_path: string;
+                    shell_root_path: string;
+                    input_mount_path: string | null;
+                    output_mount_path: string | null;
+                }[];
+                writes: {
+                    artifact_id: string;
+                    artifact_path: string;
+                    shell_root_path: string;
+                    input_mount_path: string | null;
+                    output_mount_path: string | null;
+                }[];
+            };
+            validation_attempts: {
+                attempt: number;
+                recorded_at: string;
+                status: "failed" | "succeeded";
+                summary: string;
+            }[];
+            summary: string | null;
+            error: string | null;
+        }[];
+        graph_id?: string | undefined;
+        project_id?: string | undefined;
+        build_run_id?: string | null | undefined;
+        source_manifest_id?: string | null | undefined;
+        created_at?: string | undefined;
+        is_latest?: boolean | undefined;
+        build_plan?: string | null | undefined;
+        latest_build_run_id?: string | null | undefined;
+        latest_benchmark_run_id?: string | null | undefined;
+        entrypoint_artifact?: {
+            label: string;
+            locator: {
+                kind: "local-path" | "remote-url" | "api-served";
+                value: string;
+            };
+            role: "entrypoint" | "artifact" | "guidance" | "source-index";
+            artifact_id?: string | undefined;
+            path?: string | undefined;
+            artifact_kind?: "file" | "directory" | undefined;
+            summary?: string | undefined;
+        } | null | undefined;
+        portable_handoff?: {
+            locator: {
+                kind: "local-path" | "remote-url" | "api-served";
+                value: string;
+            };
+            instructions?: string | undefined;
+        } | null | undefined;
+        build_evidence?: {
+            kind: "interf-build-evidence";
+            version: 1;
+            generated_at: string;
+            project_id: string;
+            build_run_id: string | null;
+            ready: boolean;
+            summary: string;
+            rows: {
+                id: string;
+                assertion: string;
+                metric: {
+                    observed: number;
+                    total?: number | undefined;
+                    unit?: string | undefined;
+                };
+                evidence: {
+                    kind: "output" | "source-inventory" | "stage-record" | "validator" | "trace" | "stage-evidence";
+                    label: string;
+                    ref?: string | undefined;
+                    path?: string | undefined;
+                    run_id?: string | undefined;
+                    stage_id?: string | undefined;
+                    artifact_id?: string | undefined;
+                };
+                issue_state?: "pass" | "fail" | "missing" | "review" | undefined;
+                issue?: string | undefined;
+            }[];
+        } | undefined;
+        semantic_graph?: {
+            kind: "interf-context-graph-semantic-graph";
+            version: 1;
+            generated_at: string;
+            nodes: {
+                id: string;
+                kind: "source" | "index" | "summary" | "project" | "knowledge" | "artifact" | "note" | "home" | "claim" | "entity";
+                label: string;
+                source_refs: string[];
+                link_count: number;
+                backlink_count: number;
+                path?: string | null | undefined;
+                summary?: string | null | undefined;
+            }[];
+            edges: {
+                id: string;
+                kind: "links-to" | "source-ref" | "contains" | "handoff";
+                source: string;
+                target: string;
+                label: string;
+                detail: string;
+            }[];
+            stats: {
+                notes: number;
+                links: number;
+                source_refs: number;
+                unresolved_links: number;
+            };
+        } | undefined;
+        graph_manifest?: {
+            kind: "interf-graph-manifest";
+            version: 1;
+            generated_at: string;
+            project: string;
+            graph_id: string;
+            run_id: string | null;
+            build_plan: string;
+            intent: string | null;
+            graph_path: string;
+            primary_metrics: {
+                key: string;
+                label: string;
+                value: number;
+                primary: boolean;
+                total?: number | undefined;
+                unit?: string | undefined;
+                issue_state?: "pass" | "fail" | "missing" | "review" | undefined;
+                detail?: string | undefined;
+                metadata?: Record<string, unknown> | undefined;
+            }[];
+            stages: {
+                stage_id: string;
+                stage_label: string;
+                role: "source" | "summary" | "other" | "knowledge" | "entrypoint" | "diagnostic";
+                manifest_path: string;
+                summary: string;
+                produced_total: number;
+                missing_required_total: number;
+                metrics: {
+                    key: string;
+                    label: string;
+                    value: number;
+                    primary: boolean;
+                    total?: number | undefined;
+                    unit?: string | undefined;
+                    issue_state?: "pass" | "fail" | "missing" | "review" | undefined;
+                    detail?: string | undefined;
+                    metadata?: Record<string, unknown> | undefined;
+                }[];
+            }[];
+            entrypoints: {
+                id: string;
+                role: "source" | "summary" | "other" | "knowledge" | "entrypoint" | "diagnostic";
+                kind: string;
+                label: string;
+                source_refs: string[];
+                links: string[];
+                required: boolean;
+                path?: string | undefined;
+                locator?: string | undefined;
+                stage_id?: string | undefined;
+                metadata?: Record<string, unknown> | undefined;
+            }[];
+            resources: {
+                id: string;
+                role: "source" | "summary" | "other" | "knowledge" | "entrypoint" | "diagnostic";
+                kind: string;
+                label: string;
+                source_refs: string[];
+                links: string[];
+                required: boolean;
+                path?: string | undefined;
+                locator?: string | undefined;
+                stage_id?: string | undefined;
+                metadata?: Record<string, unknown> | undefined;
+            }[];
+            graph_outputs: {
+                nodes: number;
+                edges: number;
+                notes: number;
+                links: number;
+                source_refs: number;
+                claims?: number | undefined;
+                entities?: number | undefined;
+            };
+            readiness: {
+                status: "ready" | "not-ready";
+                ready: boolean;
+                summary: string;
+                missing_required_total: number;
+                missing: {
+                    resource_id: string;
+                    status: "missing" | "blocked" | "not-relevant";
+                    reason: string;
+                }[];
+                context_graph_path?: string | null | undefined;
+            };
+        } | null | undefined;
+        readiness_rollup?: {
+            status: "ready" | "not-ready";
+            ready: boolean;
+            summary: string;
+            missing_required_total: number;
+            missing: {
+                resource_id: string;
+                status: "missing" | "blocked" | "not-relevant";
+                reason: string;
+            }[];
+            context_graph_path?: string | null | undefined;
+        } | null | undefined;
+    } | null>;
     constructor(options: LocalServiceRuntimeOptions);
     setBoundPort(port: number): void;
     /** Set a hook that fires whenever the registered Projects change. */
@@ -1112,6 +1527,8 @@ export declare class LocalServiceRuntime {
     listContextGraphs(projectDataDir: string, projectName?: string | null): ContextGraphResource[];
     getContextGraph(projectDataDir: string, graphId: string): ContextGraphResource | null;
     getLatestContextGraph(projectDataDir: string, projectName: string): ContextGraphResource | null;
+    listLatestContextGraphStageSessions(projectDataDir: string, projectName: string): StageExecutionSession[];
+    getContextGraphHandoff(projectDataDir: string, projectName: string): ContextGraphHandoff | null;
     listBuildPlans(projectDataDir: string): BuildPlanResource[];
     getBuildPlanResource(projectDataDir: string, buildPlanId: string): BuildPlanResource | null;
     applyBuildPlanChange(projectDataDir: string, requestValue: unknown): BuildPlanChangeResult;