@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/runtime/service/server-routes-runs.js

@@ -0,0 +1,112 @@
+import { LOCAL_SERVICE_ROUTES, RUN_SUBRESOURCES } from "./routes.js";
+import { parseRequestUrl, sendError, sendJson } from "./server-helpers.js";
+import { isTraversalRelativePath, safeApiFilePath, sendApiFile, } from "./server-api-files.js";
+import { findInstanceBuildRun, findInstanceJob, findInstanceRun, findInstanceVerifyRun, listInstanceRuns, } from "./server-instance-helpers.js";
+import { runObservabilityToStatus } from "../run-observability.js";
+export function tryHandleRuns(req, res, runtime, path, method) {
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.runs) {
+        sendJson(res, 200, { runs: listInstanceRuns(runtime) });
+        return true;
+    }
+    const observableRunMatch = path.match(/^\/v1\/runs\/([^/]+)(?:\/([^/]+))?$/);
+    if (observableRunMatch?.[1]) {
+        const runId = decodeURIComponent(observableRunMatch[1]);
+        const child = observableRunMatch[2];
+        if (method === "GET" && !child) {
+            const run = findInstanceRun(runtime, runId);
+            if (!run)
+                sendError(res, 404, "Run not found.");
+            else
+                sendJson(res, 200, run);
+            return true;
+        }
+        if (method === "GET" && child === RUN_SUBRESOURCES.status) {
+            const run = findInstanceRun(runtime, runId);
+            if (!run)
+                sendError(res, 404, "Run not found.");
+            else
+                sendJson(res, 200, runObservabilityToStatus(run));
+            return true;
+        }
+        const found = findInstanceBuildRun(runtime, runId);
+        if (method === "GET" && child === RUN_SUBRESOURCES.events) {
+            const events = found ? runtime.getBuildRunEvents(found.projectDataDir, runId) : null;
+            if (!events)
+                sendError(res, 404, "Build not found.");
+            else
+                sendJson(res, 200, { events });
+            return true;
+        }
+        if (method === "GET" && child === RUN_SUBRESOURCES.artifacts) {
+            const artifacts = found ? runtime.getBuildRunArtifacts(found.projectDataDir, runId) : null;
+            if (!artifacts)
+                sendError(res, 404, "Build not found.");
+            else
+                sendJson(res, 200, { artifacts });
+            return true;
+        }
+        if (method === "GET" && child === RUN_SUBRESOURCES.files) {
+            const relPath = parseRequestUrl(req).searchParams.get("path")?.trim() ?? "";
+            if (!found) {
+                sendError(res, 404, "Build not found.");
+                return true;
+            }
+            if (!relPath) {
+                sendError(res, 400, "Missing required query parameter: path.");
+                return true;
+            }
+            if (isTraversalRelativePath(relPath)) {
+                sendError(res, 400, "File path escapes Run output root.");
+                return true;
+            }
+            const safePath = safeApiFilePath(found.run.run.context_graph_path, relPath);
+            if (!safePath) {
+                sendError(res, 400, "File path escapes Run output root.");
+                return true;
+            }
+            if (!sendApiFile(res, safePath)) {
+                sendError(res, 404, `File not found: ${relPath}`);
+            }
+            return true;
+        }
+        if (method === "POST" && child === RUN_SUBRESOURCES.cancel) {
+            if (!found) {
+                sendError(res, 404, "Build not found.");
+                return true;
+            }
+            sendJson(res, 200, runtime.cancelBuildRun(runId));
+            return true;
+        }
+    }
+    const verifyRunMatch = path.match(/^\/v1\/verify-runs\/([^/]+)$/);
+    if (method === "GET" && verifyRunMatch?.[1]) {
+        const found = findInstanceVerifyRun(runtime, decodeURIComponent(verifyRunMatch[1]));
+        if (!found)
+            sendError(res, 404, "Verify run not found.");
+        else
+            sendJson(res, 200, found.run);
+        return true;
+    }
+    const jobMatch = path.match(/^\/v1\/jobs\/([^/]+)(?:\/([^/]+))?$/);
+    if (jobMatch?.[1]) {
+        const runId = decodeURIComponent(jobMatch[1]);
+        const child = jobMatch[2];
+        const found = findInstanceJob(runtime, runId);
+        if (method === "GET" && !child) {
+            if (!found)
+                sendError(res, 404, "Job run not found.");
+            else
+                sendJson(res, 200, found.job);
+            return true;
+        }
+        if (method === "GET" && child === "events") {
+            const events = found ? runtime.getJobEvents(found.projectDataDir, runId) : null;
+            if (!events)
+                sendError(res, 404, "Job run not found.");
+            else
+                sendJson(res, 200, { events });
+            return true;
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,37 @@
+import { type Server } from "node:http";
+import { type LocalServiceRunHandlers, type LocalServiceRuntime } from "../runtime.js";
+import { createLocalServiceAuthToken } from "./server-guards.js";
+export { createLocalServiceAuthToken };
+export interface StartLocalServiceOptions {
+    rootPath?: string;
+    host?: string;
+    port?: number;
+    searchFromPort?: number;
+    packageVersion?: string;
+    handlers?: Partial<LocalServiceRunHandlers>;
+    /**
+     * Local authorization policy.
+     *
+     * Product/app-owned loopback defaults to `token-required`: startup
+     * generates a per-instance bearer token unless the caller pins one.
+     * Tests may pass `tokenless-dev` to keep direct fetch fixtures readable.
+     */
+    localAuthMode?: "token-required" | "tokenless-dev";
+    /**
+     * Per-instance bearer token. In token-required mode:
+     * - undefined or `"auto"` generates a fresh random hex token.
+     * - a literal string pins a token for tests.
+     * - `null` is rejected unless `localAuthMode` is `tokenless-dev`.
+     */
+    authToken?: string | null | "auto";
+    ownerKind?: "desktop-app" | "headless";
+    ownerPid?: number;
+}
+export interface StartedLocalService {
+    runtime: LocalServiceRuntime;
+    server: Server;
+    url: string;
+    close(): Promise<void>;
+}
+export declare function createLocalServiceServer(runtime: LocalServiceRuntime): Server;
+export declare function startLocalService(options?: StartLocalServiceOptions): Promise<StartedLocalService>;

package/dist/packages/runtime/service/server.js

@@ -0,0 +1,300 @@
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { LOCAL_SERVICE_LOOPBACK_HOSTS, LocalServiceConfigSchema, LocalServiceErrorSchema, ServiceRegistryEntrySchema, } from "../schemas/index.js";
+import { createLocalServiceRuntime, } from "../runtime.js";
+import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, LOCAL_SERVICE_ROUTES, } from "./routes.js";
+import { registerServiceLocally, unregisterService, } from "./service-registry.js";
+import { rehydrateProjects, } from "../project-store.js";
+import { readSession } from "../auth/session-store.js";
+import { clearConnection, readActiveConnection, writeConnection, } from "../connection-config.js";
+import { attachResponseContext, NO_ORIGIN_RESPONSE_CONTEXT, parseRequestUrl, sendError, writeHeaders, } from "./server-helpers.js";
+import { buildAllowedOrigins, corsHeadersFor, createLocalServiceAuthToken, isAuthorizedLocalBearer, isMutatingMethod, isOriginAllowed, originHeaderValue, requiresLocalServiceAuthorization, validateBearerJwt, } from "./server-guards.js";
+import { sendDesktopAppBoot, sendServiceNotFound, } from "./server-app-boot.js";
+import { tryHandleDiscovery, tryHandleOpenPath, } from "./server-routes-discovery.js";
+import { tryHandlePerProject, tryHandleProjectCollection, } from "./server-routes-projects.js";
+import { tryHandleBuildPlans } from "./server-routes-build-plans.js";
+import { tryHandleRuns } from "./server-routes-runs.js";
+import { notifyServiceChange, tryHandleEvents } from "./server-routes-events.js";
+import { tryHandleActionProposals } from "./server-routes-action-proposals.js";
+import { tryHandleAgents, tryHandleExecutor, } from "./server-routes-agents.js";
+import { tryHandleAuth } from "./server-routes-auth.js";
+export { createLocalServiceAuthToken };
+async function routeApi(req, res, runtime) {
+    const url = parseRequestUrl(req);
+    const path = url.pathname;
+    const method = req.method ?? "GET";
+    const origin = originHeaderValue(req);
+    const allowed = buildAllowedOrigins(runtime.host, runtime.port);
+    // CORS preflight — answered for allowed origins, refused otherwise.
+    if (method === "OPTIONS") {
+        if (!isOriginAllowed(origin, allowed)) {
+            attachResponseContext(res, NO_ORIGIN_RESPONSE_CONTEXT);
+            sendError(res, 403, "Origin not allowed.");
+            return true;
+        }
+        attachResponseContext(res, { cors: corsHeadersFor(origin, allowed) });
+        writeHeaders(res, 204);
+        res.end();
+        return true;
+    }
+    // For non-OPTIONS, attach the CORS context once.
+    attachResponseContext(res, { cors: corsHeadersFor(origin, allowed) });
+    // Protected requests must:
+    //   1. Have an Origin that's local OR no Origin at all (CLI),
+    //   2. Carry a valid Authorization: Bearer <token> if the runtime issued one.
+    //
+    // Only /health, /v1, and /v1/instance stay tokenless for discovery.
+    if (requiresLocalServiceAuthorization(method, path) && path !== LOCAL_SERVICE_ROUTES.events) {
+        if (!isOriginAllowed(origin, allowed)) {
+            sendError(res, 403, "Origin not allowed.");
+            return true;
+        }
+        if (runtime.authMode === "jwt") {
+            const result = await validateBearerJwt(req);
+            if (!result.ok) {
+                writeHeaders(res, 401, { "www-authenticate": "Bearer realm=\"interf-cloud\"" });
+                res.end(`${JSON.stringify(LocalServiceErrorSchema.parse({
+                    error: { message: "Missing or invalid bearer token." },
+                }), null, 2)}\n`);
+                return true;
+            }
+            // Hand the validated claims to downstream handlers (billing
+            // events, route guards) without forcing every handler to re-parse.
+            req.interfAccount = result.account;
+        }
+        else if (!isAuthorizedLocalBearer(req, runtime)) {
+            writeHeaders(res, 401, { "www-authenticate": "Bearer realm=\"interf-local-service\"" });
+            res.end(`${JSON.stringify(LocalServiceErrorSchema.parse({
+                error: { message: "Missing or invalid bearer token." },
+            }), null, 2)}\n`);
+            return true;
+        }
+    }
+    // Dispatch chain — each route module returns true once it has handled
+    // the request. The first match wins; nothing falls through to the next
+    // module after a handler claims the route.
+    if (tryHandleDiscovery(req, res, runtime, path, method))
+        return true;
+    if (tryHandleEvents(req, res, runtime, path, method))
+        return true;
+    if (await tryHandleAuth(req, res, runtime, path, method))
+        return true;
+    if (await tryHandleProjectCollection(req, res, runtime, path, method))
+        return true;
+    if (await tryHandlePerProject(req, res, runtime, path, method))
+        return true;
+    if (await tryHandleBuildPlans(req, res, runtime, path, method))
+        return true;
+    if (tryHandleRuns(req, res, runtime, path, method))
+        return true;
+    if (await tryHandleActionProposals(req, res, runtime, path, method))
+        return true;
+    if (await tryHandleExecutor(req, res, runtime, path, method))
+        return true;
+    if (await tryHandleAgents(req, res, runtime, path, method))
+        return true;
+    if (await tryHandleOpenPath(req, res, runtime, path, method))
+        return true;
+    return false;
+}
+export function createLocalServiceServer(runtime) {
+    return createServer((req, res) => {
+        void (async () => {
+            // Pre-attach a CORS context so app boot GETs and the 404
+            // fallback emit the right headers even before routeApi has a
+            // chance to set its own. The OPTIONS preflight handling and the
+            // mutating-buildPlan guards still happen inside routeApi.
+            const origin = originHeaderValue(req);
+            const allowed = buildAllowedOrigins(runtime.host, runtime.port);
+            attachResponseContext(res, { cors: corsHeadersFor(origin, allowed) });
+            try {
+                const routed = await routeApi(req, res, runtime);
+                if (routed) {
+                    // After a successful mutation from any client (app, CLI, MCP), fan a
+                    // change ping to SSE subscribers so open renderers refresh without
+                    // polling. Run progress is still owned by the active-run poll.
+                    if (isMutatingMethod(req.method) &&
+                        res.statusCode >= 200 &&
+                        res.statusCode < 300) {
+                        notifyServiceChange(runtime);
+                    }
+                    return;
+                }
+                if (sendDesktopAppBoot(req, res, runtime))
+                    return;
+                sendServiceNotFound(res);
+            }
+            catch (error) {
+                sendError(res, 500, error instanceof Error ? error.message : String(error));
+            }
+        })();
+    });
+}
+function resolvePort(optionPort) {
+    if (typeof optionPort === "number")
+        return { port: optionPort, pinned: true };
+    const envPort = Number.parseInt(process.env.INTERF_SERVICE_PORT ?? "", 10);
+    if (Number.isInteger(envPort))
+        return { port: envPort, pinned: true };
+    return { port: LOCAL_SERVICE_DEFAULT_PORT, pinned: false };
+}
+const LOCAL_SERVICE_PORT_FALLBACK_RANGE = 50;
+async function listenWithFallback(server, host, startPort, pinned) {
+    const maxPort = pinned ? startPort : startPort + LOCAL_SERVICE_PORT_FALLBACK_RANGE;
+    for (let port = startPort; port <= maxPort; port += 1) {
+        try {
+            await new Promise((resolveListen, rejectListen) => {
+                const onError = (error) => {
+                    server.off("listening", onListening);
+                    rejectListen(error);
+                };
+                const onListening = () => {
+                    server.off("error", onError);
+                    resolveListen();
+                };
+                server.once("error", onError);
+                server.once("listening", onListening);
+                server.listen(port, host);
+            });
+            return port;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code !== "EADDRINUSE" || port === maxPort)
+                throw error;
+            // Retry on the next port; the server will emit a fresh "listening" event on the next attempt.
+        }
+    }
+    throw new Error(`Could not bind a free port between ${startPort} and ${maxPort}.`);
+}
+export async function startLocalService(options = {}) {
+    const requestedPort = typeof options.searchFromPort === "number"
+        ? { port: options.searchFromPort, pinned: false }
+        : resolvePort(options.port);
+    const requestedHost = options.host ?? process.env.INTERF_SERVICE_HOST ?? LOCAL_SERVICE_DEFAULT_HOST;
+    // Reject non-loopback host bindings before we even configure anything.
+    // This guards against `INTERF_SERVICE_HOST=0.0.0.0` env injection or a
+    // call site that passes a LAN IP. The schema-level refinement also
+    // rejects, but we want a clearer error message.
+    if (!LOCAL_SERVICE_LOOPBACK_HOSTS.includes(requestedHost)) {
+        throw new Error(`Refusing to bind local service to non-loopback host '${requestedHost}'. ` +
+            `Use one of ${LOCAL_SERVICE_LOOPBACK_HOSTS.join(", ")} ` +
+            `(adjust the --host flag or INTERF_SERVICE_HOST env var).`);
+    }
+    const config = LocalServiceConfigSchema.parse({
+        host: requestedHost,
+        port: requestedPort.port,
+    });
+    const rootPath = options.rootPath ?? process.cwd();
+    const resolvedRoot = resolve(rootPath);
+    // auth-token policy: app-owned/product loopback is token-required by
+    // default. Tests must opt into the explicit tokenless-dev mode.
+    const authToken = (() => {
+        const localAuthMode = options.localAuthMode ?? "token-required";
+        if (localAuthMode === "tokenless-dev")
+            return null;
+        if (options.authToken === null) {
+            throw new Error("authToken:null requires localAuthMode:'tokenless-dev'.");
+        }
+        if (options.authToken === "auto")
+            return createLocalServiceAuthToken();
+        if (typeof options.authToken === "string")
+            return options.authToken;
+        return createLocalServiceAuthToken();
+    })();
+    // Boot-time auth: read the persisted session, if any. The session file
+    // is local-only and stamps `account_id` on every billing event so audit
+    // trails connect runs to a signed-in user. Loopback engines stay JWT-free.
+    const bootAccount = (() => {
+        try {
+            return readSession();
+        }
+        catch {
+            return null;
+        }
+    })();
+    const runtime = createLocalServiceRuntime({
+        rootPath: resolvedRoot,
+        host: config.host,
+        port: config.port,
+        packageVersion: options.packageVersion,
+        ownerKind: options.ownerKind ?? "headless",
+        ...(options.ownerPid ? { ownerPid: options.ownerPid } : {}),
+        handlers: options.handlers,
+        ...(authToken ? { authToken } : {}),
+        currentAccount: bootAccount,
+    });
+    // Rehydrate saved Projects so subsequent
+    // build / benchmark / readiness calls find them after a service restart.
+    try {
+        rehydrateProjects(runtime);
+    }
+    catch {
+        // best effort
+    }
+    const server = createLocalServiceServer(runtime);
+    const boundPort = await listenWithFallback(server, config.host, config.port, requestedPort.pinned);
+    runtime.setBoundPort(boundPort);
+    const health = runtime.health();
+    const url = health.service_url;
+    const startedAt = health.instance_started_at ?? new Date().toISOString();
+    // Central stop-lookup registry — one entry per running instance.
+    // Runtime stop uses this as a fallback when the active connection record is missing.
+    const writeRegistryEntry = () => {
+        try {
+            registerServiceLocally(ServiceRegistryEntrySchema.parse({
+                pid: process.pid,
+                host: config.host,
+                port: boundPort,
+                url,
+                started_at: startedAt,
+                owner_kind: options.ownerKind ?? "headless",
+                ...(options.ownerPid ? { owner_pid: options.ownerPid } : {}),
+                ...(authToken ? { auth_token: authToken } : {}),
+            }));
+        }
+        catch {
+            // best effort: registry corruption shouldn't take the service down
+        }
+    };
+    writeRegistryEntry();
+    runtime.setOnRegistryChanged(writeRegistryEntry);
+    // Write the single-record CLI connection so `interf project`,
+    // `interf build`, etc. can find this engine without a pointer file.
+    try {
+        writeConnection({ url, auth_token: authToken });
+    }
+    catch {
+        // best effort: connection file is convenience, not correctness
+    }
+    return {
+        runtime,
+        server,
+        url,
+        close: () => new Promise((resolveClose, rejectClose) => {
+            runtime.setOnRegistryChanged(null);
+            server.close((error) => {
+                if (error) {
+                    rejectClose(error);
+                    return;
+                }
+                try {
+                    unregisterService(process.pid);
+                }
+                catch {
+                    // best effort
+                }
+                try {
+                    // Clear connection record only if it still points at us.
+                    const current = readActiveConnection();
+                    if (current?.url === url)
+                        clearConnection();
+                }
+                catch {
+                    // best effort
+                }
+                resolveClose();
+            });
+        }),
+    };
+}

package/dist/packages/{engine → runtime/service}/service-registry.d.ts

@@ -1,9 +1,9 @@
 /**
  * Central service registry at `~/.interf/services.json`.
  *
- * Every running `interf web` instance writes an entry here on start and
+ * Every running `interf runtime` instance writes an entry here on start and
  * removes it on close. CLI/UX code consults this registry for explicit
- * `interf web stop` lookup.
+ * `interf runtime stop` lookup.
  *
  * Entry shape:
  *   {
@@ -11,11 +11,11 @@
  *   }
  *
  * Atomic write: write to a sibling tmp file, then rename. Concurrent
- * `interf web` invocations get last-writer-wins semantics; pruning of
+ * `interf runtime` invocations get last-writer-wins semantics; pruning of
  * stale entries makes that self-healing.
  */
-import { interfHomeRoot, serviceRegistryPath } from "../contracts/lib/preparation-paths.js";
-import { type ServiceRegistryEntry } from "./lib/schema.js";
+import { interfHomeRoot, serviceRegistryPath } from "../../contracts/lib/project-paths.js";
+import { type ServiceRegistryEntry } from "../schemas/index.js";
 /**
  * Read the service registry. Removes entries whose pid is no longer alive
  * before returning. Does not health-check the HTTP endpoint — that is too

package/dist/packages/{engine → runtime/service}/service-registry.js

@@ -1,9 +1,9 @@
 /**
  * Central service registry at `~/.interf/services.json`.
  *
- * Every running `interf web` instance writes an entry here on start and
+ * Every running `interf runtime` instance writes an entry here on start and
  * removes it on close. CLI/UX code consults this registry for explicit
- * `interf web stop` lookup.
+ * `interf runtime stop` lookup.
  *
  * Entry shape:
  *   {
@@ -11,13 +11,13 @@
  *   }
  *
  * Atomic write: write to a sibling tmp file, then rename. Concurrent
- * `interf web` invocations get last-writer-wins semantics; pruning of
+ * `interf runtime` invocations get last-writer-wins semantics; pruning of
  * stale entries makes that self-healing.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
-import { interfHomeRoot, serviceRegistryPath, } from "../contracts/lib/preparation-paths.js";
-import { ServiceRegistrySchema, ServiceRegistryEntrySchema, } from "./lib/schema.js";
+import { interfHomeRoot, serviceRegistryPath, } from "../../contracts/lib/project-paths.js";
+import { ServiceRegistrySchema, ServiceRegistryEntrySchema, } from "../schemas/index.js";
 /** Returns true when the OS still has a process with this pid. */
 function isProcessAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -54,10 +54,10 @@ function readRegistryRaw() {
 function writeRegistryRaw(registry) {
     const path = serviceRegistryPath();
     const dir = dirname(path);
-    mkdirSync(dir, { recursive: true });
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
     const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
     const parsed = ServiceRegistrySchema.parse(registry);
-    writeFileSync(tmpPath, `${JSON.stringify(parsed, null, 2)}\n`);
+    writeFileSync(tmpPath, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
     try {
         renameSync(tmpPath, path);
     }

package/dist/packages/runtime/verify/benchmark-run.d.ts

@@ -0,0 +1,81 @@
+import type { AgentExecutor } from "../agents/lib/executors.js";
+import type { ProjectConfig } from "../../projects/lib/schema.js";
+import type { RuntimeExecutorInfo } from "../../contracts/lib/schema.js";
+import { type TestTargetCandidate, type TestTargetResult } from "./verify.js";
+import type { TestSandboxRetentionMode } from "./verify-sandbox.js";
+import { type BenchmarkRun, type TestRunMode } from "./lib/schema.js";
+export interface SavedBenchmarkOutcome {
+    runPath: string;
+    displayRunPath?: string;
+    executor?: RuntimeExecutorInfo | null;
+    target: TestTargetCandidate;
+    result: TestTargetResult;
+}
+export interface BenchmarkRunResult {
+    sourcePath: string;
+    projectConfig: ProjectConfig;
+    contextGraphPath: string | null;
+    /**
+     * restored. Populated when the verify run targets
+     * `source-files`; null when targeting context graph. Aggregates back
+     * onto the saved `BenchmarkRun` payload's `source_files` field.
+     */
+    sourceFilesOutcome: SavedBenchmarkOutcome | null;
+    contextGraphOutcome: SavedBenchmarkOutcome | null;
+    benchmarkRunPath: string | null;
+    benchmarkRun: BenchmarkRun | null;
+}
+export declare function benchmarkPassRate(outcome: SavedBenchmarkOutcome): number;
+export declare function readSavedBenchmarkRun(projectDataDir: string, projectName: string): BenchmarkRun | null;
+export declare function parseBenchmarkRun(value: unknown): BenchmarkRun | null;
+export declare function readBenchmarkRunAtPath(filePath: string, label?: string): BenchmarkRun | null;
+export declare function readCurrentSavedBenchmarkRun(options: {
+    projectDataDir: string;
+    projectName: string;
+}): {
+    benchmarkRun: BenchmarkRun | null;
+    stale: boolean;
+};
+export declare function saveBenchmarkRun(options: {
+    sourcePath: string;
+    contextGraphPath: string | null;
+    projectName: string;
+    checksFingerprint: string;
+    sourceFilesOutcome?: SavedBenchmarkOutcome | null;
+    contextGraphOutcome: SavedBenchmarkOutcome | null;
+}): string;
+export declare function runSavedContextGraphBenchmark(options: {
+    sourcePath: string;
+    projectConfig: ProjectConfig;
+    executor?: AgentExecutor | null;
+    contextGraphPath?: string | null;
+    preserveSandboxes?: TestSandboxRetentionMode;
+    runSuffix?: string | null;
+}): Promise<SavedBenchmarkOutcome | null>;
+/**
+ * Run the saved benchmark checks against Source references from the recorded
+ * Source Manifest so users can compare raw Source access with the Context Graph.
+ */
+export declare function runSavedSourceFilesBenchmark(options: {
+    sourcePath: string;
+    projectConfig: ProjectConfig;
+    contextGraphPath: string | null;
+    executor?: AgentExecutor | null;
+    preserveSandboxes?: TestSandboxRetentionMode;
+    runSuffix?: string | null;
+}): Promise<SavedBenchmarkOutcome | null>;
+export declare function runBenchmarkForExecutor(options: {
+    sourcePath: string;
+    projectConfig: ProjectConfig;
+    contextGraphPath: string | null;
+    executor?: AgentExecutor | null;
+    preserveSandboxes?: TestSandboxRetentionMode;
+    runSuffix?: string | null;
+    saveLatest?: boolean;
+    /**
+     * Selects which target the benchmark checks judge against.
+     * `both` runs the Source files baseline and the Context Graph under one
+     * saved benchmark payload so the UI can compare them directly.
+     */
+    target?: TestRunMode;
+}): Promise<BenchmarkRunResult>;