@interf/compiler 0.22.2 → 0.33.0

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

@@ -0,0 +1,1165 @@
+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 { type Readiness } from "../contracts/lib/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 AgentsRegistryRoleState, type AgentsRegistryState } from "./runtime-executor.js";
+import type { AgentPrefs, AgentRecord, RoleMap } from "../contracts/lib/schema.js";
+export interface LocalServiceBuildRunContext {
+    runId: string;
+    sourcePath: string;
+    contextGraphPath: string;
+    projectConfig: ProjectConfig;
+    events: RunEventSink;
+}
+export interface LocalServiceVerifyRunContext {
+    runId: string;
+    sourcePath: string;
+    contextGraphPath: string;
+    projectConfig: ProjectConfig;
+}
+export interface LocalServiceJobRunContext {
+    runId: string;
+    sourcePath: string;
+    emit(event: LocalJobEventAppendRequest): void;
+}
+export interface LocalServiceActionPlanningContext {
+    sourcePath: string;
+    projects: ProjectConfig[];
+    projectHealth: Array<{
+        name: string;
+        benchmark_questions: number;
+        context_graph_ready: boolean;
+        can_run_benchmark: boolean;
+        recommended_next_actions: string[];
+    }>;
+    sourceFolders: Array<{
+        value: string;
+        label: string;
+        hint: string;
+    }>;
+    recentProposals: ActionProposalResource[];
+}
+export interface LocalServiceRunHandlers {
+    planActionProposal(request: ActionProposalCreateRequest, context: LocalServiceActionPlanningContext): Promise<ActionProposalPlan>;
+    createBuildRun(request: BuildRunCreateRequest, context: LocalServiceBuildRunContext): Promise<LocalRunHandlerResult>;
+    createVerifyRun(request: VerifyRunCreateRequest, context: LocalServiceVerifyRunContext): Promise<LocalRunHandlerResult>;
+    createBenchmarkQuestionDraft(request: BenchmarkQuestionDraftRuntimeRequest, context: LocalServiceJobRunContext): Promise<BenchmarkQuestionDraftResult>;
+    createBuildPlanAuthoringRun(request: BuildPlanAuthoringRuntimeRequest, context: LocalServiceJobRunContext): Promise<BuildPlanAuthoringResult>;
+}
+export interface LocalServiceRuntimeOptions {
+    rootPath: string;
+    host: string;
+    port: number;
+    packageVersion?: string;
+    ownerKind?: "desktop-app" | "headless";
+    ownerPid?: number;
+    startedAt?: string;
+    handlers?: Partial<LocalServiceRunHandlers>;
+    /**
+     * Per-instance bearer token. The server requires it on protected local
+     * API requests: mutating routes plus non-discovery `/v1` reads.
+     * Optional only because test code can opt into tokenless-dev mode.
+     */
+    authToken?: string;
+    /**
+     * Active account context for this engine. Populated at boot from
+     * `~/.interf/auth/session.json`. Null for pre-auth / loopback sessions.
+     * Entitlement guards treat null as Free tier.
+     */
+    currentAccount?: import("./auth/account-context.js").CurrentAccount | null;
+    /**
+     * How the server authenticates mutating requests.
+     *
+     * `"hex"` (default) — per-instance hex bearer compared against `authToken`.
+     *   The loopback engine uses this. The loopback bind + CORS allowlist are
+     *   the real security boundary; the hex bearer is a belt-and-braces guard.
+     *
+     * `"jwt"` — `Authorization: Bearer <jwt>` validated against the WorkOS
+     *   JWKS. Used by the cloud engine binding when it lands. Validated claims
+     *   are attached to the request as `(req as any).interfAccount` so route
+     *   handlers can stamp `account_id` without re-parsing.
+     */
+    authMode?: "hex" | "jwt";
+}
+/**
+ * Per-Project context tracked by the runtime. Multiple Projects can
+ * be registered against one running service; each one owns its rootPath and
+ * activity timestamps. Routes pass the project explicitly to every
+ * runtime operation that needs one, so there is no swap-state to manage.
+ */
+export interface ProjectContext {
+    rootPath: string;
+    startedAt: string;
+    lastActivity: string;
+}
+/**
+ * Tracking record for a Build run that the runtime can still cancel. The
+ * record is created when the background build starts and cleared when it
+ * reaches a terminal state. `cancelled` is set once a cancel request has
+ * been observed so the background loop can record the right terminal event
+ * (and so the persisted record is marked even when no executor child is
+ * running yet). `projectDataDir` lets the cancel path invalidate the right
+ * Project's caches without walking the registry.
+ */
+export interface ActiveBuildRunHandle {
+    projectDataDir: string;
+    contextGraphPath: string;
+    project: string;
+    cancelled: boolean;
+    cancelledAt?: string;
+}
+export declare class LocalServiceRuntime {
+    readonly host: string;
+    port: number;
+    readonly startedAt: string;
+    readonly packageVersion?: string;
+    readonly ownerKind: "desktop-app" | "headless";
+    readonly ownerPid?: number;
+    readonly handlers: Partial<LocalServiceRunHandlers>;
+    /**
+     * The seed root path the runtime was constructed with. Used as a
+     * non-Project fallback when a Project-independent route
+     * (Build Plans, action proposals, runs listings) needs an anchor to load
+     * shared state (user-library Build Plans, bundled Build Plans, etc).
+     */
+    readonly rootPath: string;
+    /**
+     * Per-instance bearer token. Protected routes require this on the
+     * Authorization header. `null` means tokenless-dev mode (test harness).
+     */
+    readonly authToken: string | null;
+    /**
+     * Auth dispatch mode. See {@link LocalServiceRuntimeOptions.authMode}.
+     * Default is `"hex"` so loopback engines and existing tests are unaffected.
+     */
+    readonly authMode: "hex" | "jwt";
+    /**
+     * Active account / signed-in user for this engine instance. Populated at
+     * boot from `~/.interf/auth/session.json`. `null` for pre-auth /
+     * anonymous sessions; entitlement guards treat null as Free tier.
+     */
+    currentAccount: import("./auth/account-context.js").CurrentAccount | null;
+    /** Map of projectDataDir -> ProjectContext. */
+    private projectContexts;
+    /** Hook called whenever a Project is registered or deregistered. */
+    private onRegistryChanged;
+    /** In-flight runs across all projects. Used for `idle_for_seconds`. */
+    private activeRunCount;
+    /**
+     * Active Build run cancellation handles, keyed by run id. Populated
+     * when a Build run is launched and cleared once the run reaches a
+     * terminal state. Each entry remembers where the persisted record lives
+     * so cancel can mark it without re-resolving the Project.
+     */
+    activeBuildRuns: Map<string, ActiveBuildRunHandle>;
+    /**
+     * Active local job runs, keyed by run id. Build Plan drafting,
+     * Build Plan improvement, and benchmark-question drafting all persist
+     * through the local-job store; recovery must not mark these as
+     * interrupted while this runtime is still executing them.
+     */
+    activeJobRuns: Set<string>;
+    /**
+     * Idempotency-key cache for `POST .../build-runs`. Outer key is the
+     * resolved project root; inner key is the client-supplied idempotency
+     * value. Namespacing per project prevents key collisions across
+     * tenants on the same engine (CSO finding: a malicious project could
+     * otherwise hijack another project's run id by reusing its key).
+     * Entries expire after the idempotency TTL defined in `runtime-build-runs.ts`.
+     */
+    idempotencyKeyCache: Map<string, Map<string, {
+        runId: string;
+        expiresAt: number;
+    }>>;
+    /**
+     * Read-side caches. Polling clients (Interf Desktop renderer, CLI status loops)
+     * hit list/get endpoints multiple times per second; without these,
+     * every request re-walks the filesystem and re-parses every JSON
+     * record through Zod. The runtime invalidates each cache on the
+     * matching write path. See {@link runtime-caches} for design notes.
+     */
+    readonly buildRunCache: RunListingCache<{
+        kind: "interf-build-run";
+        version: 1;
+        run_id: string;
+        status: "running" | "failed" | "cancelled" | "queued" | "succeeded";
+        project: string;
+        build_plan: string;
+        backend: "native";
+        source_path: string;
+        context_graph_path: string;
+        created_at: string;
+        stages: {
+            run_id: string;
+            stage_id: string;
+            status: "running" | "failed" | "queued" | "succeeded";
+            artifacts: {
+                path: string;
+                role: "runtime" | "output" | "source" | "evidence" | "benchmark";
+                stage_id?: string | null | undefined;
+                label?: string | undefined;
+                sha256?: string | undefined;
+            }[];
+            stage_label?: string | undefined;
+            stage_index?: number | undefined;
+            stage_total?: number | undefined;
+            started_at?: string | null | undefined;
+            finished_at?: string | null | undefined;
+            summary?: string | null | undefined;
+            contract?: {
+                reads: string[];
+                writes: string[];
+                stage_label?: string | undefined;
+                stage_index?: number | undefined;
+                stage_total?: number | undefined;
+            } | undefined;
+            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;
+            } | null | undefined;
+            logs?: {
+                prompt_path?: string | undefined;
+                event_stream_path?: string | undefined;
+                status_path?: string | undefined;
+                contract_path?: string | undefined;
+                evidence_path?: string | undefined;
+            } | undefined;
+            latest_evidence?: {
+                id: string;
+                run_id: string;
+                generated_at: string;
+                summary: string;
+                artifacts: {
+                    path: string;
+                    role: "runtime" | "output" | "source" | "evidence" | "benchmark";
+                    stage_id?: string | null | undefined;
+                    label?: string | undefined;
+                    sha256?: string | undefined;
+                }[];
+                checks: {
+                    id: string;
+                    label: string;
+                    ok: boolean;
+                    detail?: string | undefined;
+                }[];
+                stage_id?: string | null | undefined;
+                files_processed?: number | undefined;
+            } | null | undefined;
+            failure?: string | null | undefined;
+        }[];
+        events: ({
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "run.started";
+            project: string;
+            backend: "native";
+            build_plan?: string | undefined;
+            context_graph_path?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "stage.started";
+            stage_id: string;
+            stage_index?: number | undefined;
+            stage_total?: number | undefined;
+            logs?: {
+                prompt_path?: string | undefined;
+                event_stream_path?: string | undefined;
+                status_path?: string | undefined;
+                contract_path?: string | undefined;
+                evidence_path?: string | undefined;
+            } | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "file.processed";
+            stage_id: string;
+            path: string;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "artifact.written";
+            stage_id: string;
+            artifact: {
+                path: string;
+                role: "runtime" | "output" | "source" | "evidence" | "benchmark";
+                stage_id?: string | null | undefined;
+                label?: string | undefined;
+                sha256?: string | undefined;
+            };
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "evidence.updated";
+            evidence: {
+                id: string;
+                run_id: string;
+                generated_at: string;
+                summary: string;
+                artifacts: {
+                    path: string;
+                    role: "runtime" | "output" | "source" | "evidence" | "benchmark";
+                    stage_id?: string | null | undefined;
+                    label?: string | undefined;
+                    sha256?: string | undefined;
+                }[];
+                checks: {
+                    id: string;
+                    label: string;
+                    ok: boolean;
+                    detail?: string | undefined;
+                }[];
+                stage_id?: string | null | undefined;
+                files_processed?: number | undefined;
+            };
+            stage_id?: string | null | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "log.appended";
+            stream: "status" | "trace" | "system";
+            message: string;
+            stage_id?: string | null | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "stage.passed";
+            stage_id: string;
+            summary?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "stage.failed";
+            stage_id: string;
+            error: string;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "run.completed";
+            summary?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "run.failed";
+            error: string;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "run.cancelled";
+            reason?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "checks.evaluated";
+            passed: number;
+            total: number;
+            target?: "source-files" | "context-graph" | undefined;
+            checks_fingerprint?: string | undefined;
+            stale?: boolean | undefined;
+            test_run_id?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "readiness.updated";
+            project: string;
+            readiness: {
+                kind: "interf-readiness-state";
+                version: 1;
+                generated_at: string;
+                project: string;
+                status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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;
+            };
+        })[];
+        context_checks: {
+            id: string;
+            label: string;
+            backed_by_artifact_ids: string[];
+            required: boolean;
+            description?: string | undefined;
+            evidence_expectation?: string | undefined;
+            status?: "passed" | "pending" | "running" | "failed" | "skipped" | undefined;
+            evidence?: string | undefined;
+            issue?: string | undefined;
+        }[];
+        artifacts: {
+            artifact_id: string;
+            status: "failed" | "skipped" | "ready" | "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";
+                passed: boolean;
+                required: boolean;
+                summary: string;
+                evaluated_at: string;
+                details?: Record<string, unknown> | undefined;
+            }[];
+            summary?: string | undefined;
+        }[];
+        started_at?: string | null | undefined;
+        finished_at?: string | null | undefined;
+        latest_evidence?: {
+            id: string;
+            run_id: string;
+            generated_at: string;
+            summary: string;
+            artifacts: {
+                path: string;
+                role: "runtime" | "output" | "source" | "evidence" | "benchmark";
+                stage_id?: string | null | undefined;
+                label?: string | undefined;
+                sha256?: string | undefined;
+            }[];
+            checks: {
+                id: string;
+                label: string;
+                ok: boolean;
+                detail?: string | undefined;
+            }[];
+            stage_id?: string | null | undefined;
+            files_processed?: number | undefined;
+        } | null | undefined;
+        readiness?: {
+            kind: "interf-readiness-state";
+            version: 1;
+            generated_at: string;
+            project: string;
+            status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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;
+        } | null | undefined;
+    }>;
+    readonly verifyRunCache: RunListingCache<{
+        run_id: string;
+        status: "running" | "failed" | "cancelled" | "queued" | "succeeded";
+        project: string;
+        source_path: string;
+        context_graph_path: string | null;
+        benchmark_run: {
+            kind: "interf-benchmark-run";
+            version: 1;
+            generated_at: string;
+            mode: "source-files" | "context-graph" | "both";
+            source_path: string;
+            project: {
+                name: string;
+                context_graph_path: string | null;
+            };
+            source_files: {
+                label: string;
+                run_path: string;
+                ok: boolean;
+                passed_cases: number;
+                total_cases: number;
+                passed_checks: number;
+                total_checks: number;
+                source_usage: "unknown" | "source-baseline" | "graph-only" | "graph-source-verified";
+                target: {
+                    type: "source-files" | "context-graph";
+                    name: string;
+                    path: string;
+                    build_plan: string;
+                };
+                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;
+                } | null | undefined;
+            } | null;
+            context_graph: {
+                label: string;
+                run_path: string;
+                ok: boolean;
+                passed_cases: number;
+                total_cases: number;
+                passed_checks: number;
+                total_checks: number;
+                source_usage: "unknown" | "source-baseline" | "graph-only" | "graph-source-verified";
+                target: {
+                    type: "source-files" | "context-graph";
+                    name: string;
+                    path: string;
+                    build_plan: string;
+                };
+                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;
+                } | null | undefined;
+            } | null;
+            summary: {
+                source_files_pass_rate: number | null;
+                context_graph_pass_rate: number | null;
+            };
+            checks_fingerprint?: string | undefined;
+        } | null;
+        events: ({
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "run.started";
+            project: string;
+            backend: "native";
+            build_plan?: string | undefined;
+            context_graph_path?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "stage.started";
+            stage_id: string;
+            stage_index?: number | undefined;
+            stage_total?: number | undefined;
+            logs?: {
+                prompt_path?: string | undefined;
+                event_stream_path?: string | undefined;
+                status_path?: string | undefined;
+                contract_path?: string | undefined;
+                evidence_path?: string | undefined;
+            } | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "file.processed";
+            stage_id: string;
+            path: string;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "artifact.written";
+            stage_id: string;
+            artifact: {
+                path: string;
+                role: "runtime" | "output" | "source" | "evidence" | "benchmark";
+                stage_id?: string | null | undefined;
+                label?: string | undefined;
+                sha256?: string | undefined;
+            };
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "evidence.updated";
+            evidence: {
+                id: string;
+                run_id: string;
+                generated_at: string;
+                summary: string;
+                artifacts: {
+                    path: string;
+                    role: "runtime" | "output" | "source" | "evidence" | "benchmark";
+                    stage_id?: string | null | undefined;
+                    label?: string | undefined;
+                    sha256?: string | undefined;
+                }[];
+                checks: {
+                    id: string;
+                    label: string;
+                    ok: boolean;
+                    detail?: string | undefined;
+                }[];
+                stage_id?: string | null | undefined;
+                files_processed?: number | undefined;
+            };
+            stage_id?: string | null | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "log.appended";
+            stream: "status" | "trace" | "system";
+            message: string;
+            stage_id?: string | null | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "stage.passed";
+            stage_id: string;
+            summary?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "stage.failed";
+            stage_id: string;
+            error: string;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "run.completed";
+            summary?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "run.failed";
+            error: string;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "run.cancelled";
+            reason?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "checks.evaluated";
+            passed: number;
+            total: number;
+            target?: "source-files" | "context-graph" | undefined;
+            checks_fingerprint?: string | undefined;
+            stale?: boolean | undefined;
+            test_run_id?: string | undefined;
+        } | {
+            event_id: string;
+            run_id: string;
+            timestamp: string;
+            type: "readiness.updated";
+            project: string;
+            readiness: {
+                kind: "interf-readiness-state";
+                version: 1;
+                generated_at: string;
+                project: string;
+                status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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;
+            };
+        })[];
+        target?: "source-files" | "context-graph" | "both" | undefined;
+        started_at?: string | null | undefined;
+        finished_at?: string | null | undefined;
+        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;
+        } | null | undefined;
+        agent_label?: string | null | undefined;
+        parent_run_id?: string | null | undefined;
+        batch?: {
+            child_run_ids: string[];
+            total_agents: number;
+            completed_agents: number;
+            succeeded_agents: number;
+            failed_agents: number;
+        } | null | undefined;
+        readiness?: {
+            kind: "interf-readiness-state";
+            version: 1;
+            generated_at: string;
+            project: string;
+            status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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;
+        } | null | undefined;
+        error?: string | null | undefined;
+    }>;
+    readonly readinessCache: ReadinessCache<{
+        kind: "interf-readiness-state";
+        version: 1;
+        generated_at: string;
+        project: string;
+        status: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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?: "failed" | "ready" | "not-configured" | "not-built" | "building" | "built" | "checking" | "not-ready" | "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;
+    }>;
+    readonly sourceFilesCache: MtimeListingCache<{
+        project: string;
+        path: string;
+        absolute_path: string;
+        size_bytes: number;
+        modified_at: string | null;
+        source_folder_path: string;
+        source_manifest_id?: string | undefined;
+        source_file_id?: string | undefined;
+        locator?: string | undefined;
+        kind?: "image" | "pdf" | "document" | "spreadsheet" | "presentation" | "text" | "other" | undefined;
+    }[]>;
+    readonly buildPlanListingCache: BuildPlanListingCache<{
+        id: string;
+        build_plan_id: string;
+        path: string;
+        inputs: {
+            id: string;
+            label: string;
+            description: string;
+            required: boolean;
+            examples?: string[] | undefined;
+        }[];
+        source_kind: "builtin" | "local";
+        built_in: boolean;
+        active_for_projects: string[];
+        context_checks: {
+            id: string;
+            label: string;
+            backed_by_artifact_ids: string[];
+            required: boolean;
+            description?: string | undefined;
+            evidence_expectation?: string | undefined;
+        }[];
+        artifacts: {
+            id: string;
+            description: string;
+            shape: {
+                kind: "path";
+                path: string;
+                artifact_kind: "file" | "directory";
+            };
+            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";
+                required: boolean;
+                description?: string | undefined;
+                params?: Record<string, unknown> | undefined;
+            }[];
+            built_by_stages: string[];
+        }[];
+        stages: {
+            id: string;
+            label: string;
+            contract_type: string;
+            skill_dir: string;
+            role: string;
+            reads: string[];
+            writes: string[];
+            description?: string | undefined;
+        }[];
+        label?: string | undefined;
+        hint?: string | undefined;
+        purpose?: {
+            label: string;
+            task_hint: string;
+        } | undefined;
+        brief?: {
+            requested_artifacts: {
+                title: string;
+                checks: (string | {
+                    label: string;
+                })[];
+                id?: string | undefined;
+                purpose?: string | undefined;
+                description?: string | undefined;
+                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";
+                        required: boolean;
+                        description?: string | undefined;
+                        params?: Record<string, unknown> | undefined;
+                    }[];
+                    path?: string | undefined;
+                    shape?: {
+                        kind: "path";
+                        path: string;
+                        artifact_kind: "file" | "directory";
+                    } | undefined;
+                    stage_hint?: string | undefined;
+                } | undefined;
+            }[];
+            checks: {
+                label: string;
+                backed_by_artifact_ids: string[];
+                required: boolean;
+                id?: string | undefined;
+                description?: string | undefined;
+                evidence?: string | undefined;
+                evidence_expectation?: string | undefined;
+            }[];
+            artifact_requirements: {
+                id: string;
+                shape: {
+                    kind: "path";
+                    path: string;
+                    artifact_kind: "file" | "directory";
+                };
+                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";
+                    required: boolean;
+                    description?: string | undefined;
+                    params?: Record<string, unknown> | undefined;
+                }[];
+                description?: string | undefined;
+                stage_hint?: string | undefined;
+            }[];
+            intent: string;
+            user_prep_instructions?: string | undefined;
+            source_context?: {
+                items: {
+                    name?: string | undefined;
+                    path?: string | undefined;
+                    kind?: string | undefined;
+                    page_count?: number | undefined;
+                    note?: string | undefined;
+                }[];
+                observations: string[];
+                limitations: string[];
+                summary?: string | undefined;
+            } | null | undefined;
+        } | undefined;
+    }[]>;
+    constructor(options: LocalServiceRuntimeOptions);
+    setBoundPort(port: number): void;
+    /** Set a hook that fires whenever the registered Projects change. */
+    setOnRegistryChanged(handler: (() => void) | null): void;
+    /**
+     * Register a Project with this runtime. Returns the ProjectContext.
+     * Idempotent: re-registering an existing Project updates `lastActivity`.
+     */
+    registerProject(projectDataDir: string): ProjectContext;
+    /**
+     * Remove a project from the runtime. Returns true if a project was
+     * removed.
+     */
+    deregisterProject(projectDataDir: string): boolean;
+    /**
+     * Most recently active project, or the first registered if none has
+     * activity yet. Server code uses this as the fallback when a request
+     * does not specify a project. Throws if none are registered.
+     */
+    defaultProjectDataDir(): string;
+    /** Look up a Project context by rootPath. */
+    getProjectContext(projectDataDir: string): ProjectContext | null;
+    /** All registered Projects, ordered by registration time. */
+    listRegisteredProjects(): ProjectContext[];
+    /** True when no projects are registered. */
+    hasNoProjects(): boolean;
+    /** Number of registered Projects. */
+    registeredProjectCount(): number;
+    /** Increment in-flight run counter. Call when a long-running run starts. */
+    beginActiveRun(): void;
+    /** Decrement in-flight run counter. Pair with `beginActiveRun`. */
+    endActiveRun(): void;
+    /** Sum of in-flight runs across all projects. */
+    activeRuns(): number;
+    beginActiveJobRun(runId: string): void;
+    endActiveJobRun(runId: string): void;
+    /**
+     * Mark the project as recently active. Routes call this on entry so
+     * `idleForSeconds` and the registry graphs stay in sync with the
+     * actual request cadence.
+     */
+    touchProject(projectDataDir: string): void;
+    /** Seconds since the most recent Project activity (0 if active). */
+    idleForSeconds(): number;
+    health(projectDataDir?: string): LocalServiceHealth;
+    listProjects(projectDataDir: string): ProjectResource[];
+    getProject(projectDataDir: string, projectName: string): ProjectResource | null;
+    listProjectReadiness(projectDataDir: string): Readiness[];
+    getProjectReadiness(projectDataDir: string, projectName: string): Readiness | null;
+    listReadiness(projectDataDir: string): Readiness[];
+    getReadiness(projectDataDir: string, projectName: string): Readiness | null;
+    computeProjectReadiness(projectDataDir: string, project: ProjectConfig): Readiness;
+    listSourceFiles(projectDataDir: string, projectName?: string | null): SourceFileResource[];
+    listContextGraphs(projectDataDir: string, projectName?: string | null): ContextGraphResource[];
+    getContextGraph(projectDataDir: string, graphId: string): ContextGraphResource | null;
+    getLatestContextGraph(projectDataDir: string, projectName: string): ContextGraphResource | null;
+    listBuildPlans(projectDataDir: string): BuildPlanResource[];
+    getBuildPlanResource(projectDataDir: string, buildPlanId: string): BuildPlanResource | null;
+    applyBuildPlanChange(projectDataDir: string, requestValue: unknown): BuildPlanChangeResult;
+    applyReset(projectDataDir: string, requestValue: unknown): ResetResult;
+    resolveProjectConfig(projectDataDir: string, projectName: string, overrides?: Partial<Pick<ProjectConfig, "build_plan">>): ProjectConfig;
+    ensureContextGraphForRun(projectDataDir: string, projectConfig: ProjectConfig, runId: string): string;
+    defaultProjectId(projectDataDir: string): string;
+    getExecutorStatus(): LocalExecutorStatus;
+    selectExecutor(requestValue: unknown): LocalExecutorStatus;
+    getAgentsRegistry(): AgentsRegistryState;
+    registerCustomAgent(input: {
+        name: string;
+        display_name: string;
+        command: string;
+    }): AgentsRegistryState;
+    unregisterCustomAgent(name: string): AgentsRegistryState;
+    patchAgentsRoleMap(patch: Record<string, string>): AgentsRegistryRoleState;
+    setAgentPrefs(name: string, prefs: AgentPrefs): AgentsRegistryState;
+    listActionProposals(projectDataDir: string): ActionProposalResource[];
+    getActionProposal(projectDataDir: string, proposalId: string): ActionProposalResource | null;
+    createActionProposal(projectDataDir: string, requestValue: unknown): Promise<ActionProposalResource>;
+    decideActionProposal(projectDataDir: string, proposalId: string, requestValue: unknown): Promise<ActionProposalResource | null>;
+    listRunObservability(projectDataDir: string): RunObservabilityResource[];
+    getRunObservability(projectDataDir: string, runId: string): RunObservabilityResource | null;
+    listBuildPlanRuns(projectDataDir: string, buildPlanId: string): RunObservabilityResource[];
+    listBuildRuns(projectDataDir: string): BuildRunResource[];
+    listBuildRunsForProject(projectDataDir: string, projectName: string): BuildRun[];
+    getBuildRun(projectDataDir: string, runId: string): BuildRunResource | null;
+    getBuildRunEvents(projectDataDir: string, runId: string): InterfRunEvent[] | null;
+    getBuildRunEvidence(projectDataDir: string, runId: string): EvidenceRecord[] | null;
+    getBuildRunArtifacts(projectDataDir: string, runId: string): ArtifactRef[] | null;
+    createBuildRun(projectDataDir: string, requestValue: unknown): Promise<BuildRunResource>;
+    cancelBuildRun(runId: string): {
+        cancelled: boolean;
+        reason?: string;
+    };
+    findIdempotentBuildRun(projectDataDir: string, key: string): string | null;
+    recordIdempotentBuildRun(projectDataDir: string, key: string, runId: string): void;
+    expireIdempotencyKeyForTesting(projectDataDir: string, key: string): boolean;
+    listVerifyRuns(projectDataDir: string): VerifyRunResource[];
+    listVerifyRunsForProject(projectDataDir: string, projectName: string): VerifyRunResource[];
+    getVerifyRun(projectDataDir: string, runId: string): VerifyRunResource | null;
+    createVerifyRun(projectDataDir: string, requestValue: unknown): Promise<VerifyRunResource>;
+    listJobs(projectDataDir: string): LocalJobRunResource[];
+    getJob(projectDataDir: string, runId: string): LocalJobRunResource | null;
+    getJobEvents(projectDataDir: string, runId: string): LocalJobEvent[] | null;
+    createBenchmarkQuestionDraftRun(projectDataDir: string, requestValue: unknown): Promise<LocalJobRunResource>;
+    createBuildPlanAuthoringRun(projectDataDir: string, requestValue: unknown, jobType?: "build-plan-draft" | "build-plan-improvement"): Promise<LocalJobRunResource>;
+}
+export declare function createLocalServiceRuntime(options: LocalServiceRuntimeOptions): LocalServiceRuntime;
+export type { AgentPrefs, AgentRecord, RoleMap };