@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/{engine → runtime}/client.js

@@ -1,6 +1,7 @@
-import { BuildRunCreateRequestSchema, BuildRunResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringResultSchema, } from "./lib/schema.js";
-import { LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, preparationSubresourcePath, } from "./routes.js";
-import { readActiveConnection } from "./connection-config.js";
+import { BuildRunListResponseSchema, BuildRunResourceSchema, RunObservabilityResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, BenchmarkQuestionDraftCreateRequestSchema, BenchmarkQuestionDraftResultSchema, ResetResultSchema, ProjectBuildRunCreateRequestSchema, ProjectResetRequestSchema, ProjectVerifyRunCreateRequestSchema, VerifyRunResourceSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringResultSchema, } from "./schemas/index.js";
+import { LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, projectSubresourcePath, } from "./service/routes.js";
+import { INTERF_AUTH_TOKEN_ENV, readActiveConnection } from "./connection-config.js";
+import { isTerminalStatus } from "./runtime-status.js";
 async function connectOrNull(options = {}) {
     const conn = readActiveConnection({
         urlOverride: options.url ?? null,
@@ -34,12 +35,12 @@ export function configuredLocalServiceUrl() {
     return buildLocalServiceUrl();
 }
 /**
- * Resolve the bearer token for the active connection. In 0.13 there is
- * exactly one source of truth: `~/.interf/connection.json` (or the
- * `INTERF_SERVICE_TOKEN` env override).
+ * Resolve the bearer token for the active connection. There is exactly
+ * one source of truth: `~/.interf/connection.json` (or the
+ * `INTERF_AUTH_TOKEN` env override).
  */
 export function resolveLocalServiceAuthToken() {
-    const explicit = process.env.INTERF_SERVICE_TOKEN?.trim();
+    const explicit = process.env[INTERF_AUTH_TOKEN_ENV]?.trim();
     if (explicit)
         return explicit;
     const conn = readActiveConnection();
@@ -68,9 +69,9 @@ async function fetchJson(url, options = {}) {
     }
 }
 /**
- * Resolve a connection. In 0.13 this is the only path to the engine — read
- * `~/.interf/connection.json` (written by `interf web`) or honor the
- * `INTERF_SERVICE_URL` / `INTERF_SERVICE_TOKEN` env overrides.
+ * Resolve a connection — the only path to the engine. Read
+ * `~/.interf/connection.json` (written by `interf runtime`) or honor the
+ * `INTERF_SERVICE_URL` / `INTERF_AUTH_TOKEN` env overrides.
  */
 export async function findLocalService(options = {}) {
     void options.timeoutMs;
@@ -80,18 +81,18 @@ function authHeaders(authToken) {
     return authToken ? { authorization: `Bearer ${authToken}` } : {};
 }
 // ─────────────────────────────────────────────────────────────────────────
-// Preparation-keyed run submission helpers (0.13)
+// Project-keyed run submission helpers
 // ─────────────────────────────────────────────────────────────────────────
 export async function submitBuildRunToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = BuildRunCreateRequestSchema.parse(options.request);
+    const request = ProjectBuildRunCreateRequestSchema.parse(options.request);
     const headers = {
         ...authHeaders(connection.authToken),
         ...(options.idempotencyKey ? { "x-interf-idempotency-key": options.idempotencyKey } : {}),
     };
-    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "buildRuns")}`;
+    const url = `${connection.serviceUrl}${projectSubresourcePath(options.projectId, "buildRuns")}`;
     const resource = BuildRunResourceSchema.parse(await fetchJson(url, {
         method: "POST",
         body: JSON.stringify(request),
@@ -106,8 +107,8 @@ export async function submitVerifyRunToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = VerifyRunCreateRequestSchema.parse(options.request);
-    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "verifyRuns")}`;
+    const request = ProjectVerifyRunCreateRequestSchema.parse(options.request);
+    const url = `${connection.serviceUrl}${projectSubresourcePath(options.projectId, "verifyRuns")}`;
     const resource = VerifyRunResourceSchema.parse(await fetchJson(url, {
         method: "POST",
         body: JSON.stringify(request),
@@ -122,8 +123,8 @@ export async function submitResetToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = ResetRequestSchema.parse(options.request);
-    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "reset")}`;
+    const request = ProjectResetRequestSchema.parse(options.request);
+    const url = `${connection.serviceUrl}${projectSubresourcePath(options.projectId, "reset")}`;
     const result = ResetResultSchema.parse(await fetchJson(url, {
         method: "POST",
         body: JSON.stringify(request),
@@ -179,18 +180,29 @@ export async function approveActionProposalInLocalService(options) {
     });
     return decided ?? proposal;
 }
-function isTerminalJobStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
-function isTerminalRunStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
 export async function getLocalBuildRun(options) {
-    return BuildRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}/v1/build-runs/${encodeURIComponent(options.runId)}`, {
+    const headers = authHeaders(options.authToken ?? resolveLocalServiceAuthToken());
+    const runValue = await fetchJson(`${options.serviceUrl}/v1/runs/${encodeURIComponent(options.runId)}`, {
         method: "GET",
         timeoutMs: 2000,
-        headers: authHeaders(options.authToken ?? resolveLocalServiceAuthToken()),
+        headers,
+    });
+    const direct = BuildRunResourceSchema.safeParse(runValue);
+    if (direct.success)
+        return direct.data;
+    const observable = RunObservabilityResourceSchema.parse(runValue);
+    if (observable.run_type !== "build" || !observable.project) {
+        throw new Error(`Run ${options.runId} is not a Build run.`);
+    }
+    const projectRuns = BuildRunListResponseSchema.parse(await fetchJson(`${options.serviceUrl}/v1/projects/${encodeURIComponent(observable.project)}/runs`, {
+        method: "GET",
+        timeoutMs: 2000,
+        headers,
     }));
+    const run = projectRuns.runs.find((candidate) => candidate.run_id === options.runId);
+    if (!run)
+        throw new Error(`Build run ${options.runId} was not found in Project ${observable.project}.`);
+    return BuildRunResourceSchema.parse({ run });
 }
 /**
  * Ask the local service to cancel a running Build run by id. Resolves
@@ -198,7 +210,7 @@ export async function getLocalBuildRun(options) {
  * returns 404 (unknown run id) or any non-2xx status.
  */
 export async function cancelLocalBuildRun(options) {
-    const value = await fetchJson(`${options.serviceUrl}/v1/build-runs/${encodeURIComponent(options.runId)}/cancel`, {
+    const value = await fetchJson(`${options.serviceUrl}/v1/runs/${encodeURIComponent(options.runId)}/cancel`, {
         method: "POST",
         timeoutMs: options.timeoutMs ?? 2000,
         headers: authHeaders(options.authToken ?? resolveLocalServiceAuthToken()),
@@ -227,7 +239,7 @@ export async function waitForLocalBuildRun(options) {
             authToken: options.authToken ?? null,
         });
         options.onUpdate?.(resource);
-        if (isTerminalRunStatus(resource.run.status))
+        if (isTerminalStatus(resource.run.status))
             return resource;
         await new Promise((resolveWait) => setTimeout(resolveWait, delay));
         if (explicit === undefined) {
@@ -253,7 +265,7 @@ export async function waitForLocalVerifyRun(options) {
             authToken: options.authToken ?? null,
         });
         options.onUpdate?.(resource);
-        if (isTerminalRunStatus(resource.status))
+        if (isTerminalStatus(resource.status))
             return resource;
         await new Promise((resolveWait) => setTimeout(resolveWait, delay));
         if (explicit === undefined) {
@@ -278,7 +290,7 @@ export async function waitForLocalJobRun(options) {
             authToken: options.authToken ?? null,
         });
         options.onUpdate?.(job);
-        if (isTerminalJobStatus(job.status))
+        if (isTerminalStatus(job.status))
             return job;
         if (options.timeoutMs && Date.now() - startedAt > options.timeoutMs) {
             throw new Error(`Timed out waiting for local job ${options.runId}.`);
@@ -294,12 +306,12 @@ function resultError(job, defaultMessage) {
     }
     return job.error ?? defaultMessage;
 }
-export async function submitReadinessCheckDraftToLocalService(options) {
+export async function submitBenchmarkQuestionDraftToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = ReadinessCheckDraftCreateRequestSchema.parse(options.request);
-    const initialJob = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "readinessCheckDrafts")}`, {
+    const request = BenchmarkQuestionDraftCreateRequestSchema.parse(options.request);
+    const initialJob = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${projectSubresourcePath(options.projectId, "benchmarkQuestionDrafts")}`, {
         method: "POST",
         body: JSON.stringify(request),
         headers: authHeaders(connection.authToken),
@@ -319,16 +331,16 @@ export async function submitReadinessCheckDraftToLocalService(options) {
             serviceUrl: connection.serviceUrl,
             job,
             result: null,
-            error: resultError(job, "Drafting readiness checks failed in the local Interf service."),
+            error: resultError(job, "Drafting benchmark questions failed in the local Interf service."),
         };
     }
-    const parsed = ReadinessCheckDraftResultSchema.safeParse(job.result);
+    const parsed = BenchmarkQuestionDraftResultSchema.safeParse(job.result);
     if (!parsed.success) {
         return {
             serviceUrl: connection.serviceUrl,
             job,
             result: null,
-            error: "Drafting readiness checks finished without a valid result.",
+            error: "Drafting benchmark questions finished without a valid result.",
         };
     }
     return {
@@ -342,7 +354,7 @@ export async function submitBuildPlanAuthoringRunToLocalService(options) {
     if (!connection)
         return null;
     const request = BuildPlanAuthoringCreateRequestSchema.parse(options.request);
-    const initialJob = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "buildPlanDraftRuns")}`, {
+    const initialJob = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${projectSubresourcePath(options.projectId, "buildPlanDraftRuns")}`, {
         method: "POST",
         body: JSON.stringify(request),
         headers: authHeaders(connection.authToken),

package/dist/packages/{engine → runtime}/connection-config.d.ts

@@ -2,8 +2,9 @@
  * Single CLI connection record at `~/.interf/connection.json`.
  *
  * The CLI is a thin authorized client of one connected instance. Switch by
- * starting `interf web` (writes a local connection), `interf login` (writes a
- * remote connection), or by passing `--url` / env vars to override per-call.
+ * starting `interf runtime` (writes a local connection), `interf login`
+ * (writes a remote connection), or by passing `--url` / env vars to override
+ * per-call.
  *
  * No per-folder pointer files. No registry of multiple connections.
  */

package/dist/packages/{engine → runtime}/connection-config.js

@@ -2,18 +2,19 @@
  * Single CLI connection record at `~/.interf/connection.json`.
  *
  * The CLI is a thin authorized client of one connected instance. Switch by
- * starting `interf web` (writes a local connection), `interf login` (writes a
- * remote connection), or by passing `--url` / env vars to override per-call.
+ * starting `interf runtime` (writes a local connection), `interf login`
+ * (writes a remote connection), or by passing `--url` / env vars to override
+ * per-call.
  *
  * No per-folder pointer files. No registry of multiple connections.
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { z } from "zod";
-import { connectionConfigPath, interfHomeRoot } from "./instance-paths.js";
+import { connectionConfigPath, interfHomeRoot } from "../contracts/lib/project-paths.js";
 export const ConnectionRecordSchema = z.object({
     url: z.string().url(),
-    /** Bearer token for non-loopback connections. Null for loopback. */
+    /** Bearer token for token-required local or remote instances. Null only for explicit tokenless dev/test instances. */
     auth_token: z.string().min(1).nullable().default(null),
 }).strict();
 export const INTERF_SERVICE_URL_ENV = "INTERF_SERVICE_URL";
@@ -57,8 +58,8 @@ export function readActiveConnection(options = {}) {
 export function writeConnection(record) {
     const validated = ConnectionRecordSchema.parse(record);
     const configPath = connectionConfigPath();
-    mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(configPath, `${JSON.stringify(validated, null, 2)}\n`);
+    mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+    writeFileSync(configPath, `${JSON.stringify(validated, null, 2)}\n`, { mode: 0o600 });
 }
 /** Clear the connection record. No-op if missing. */
 export function clearConnection() {
@@ -68,8 +69,8 @@ export function clearConnection() {
 }
 /** Ensure `~/.interf/` exists and is a directory. */
 export function ensureInterfHome() {
-    mkdirSync(interfHomeRoot(), { recursive: true });
+    mkdirSync(interfHomeRoot(), { recursive: true, mode: 0o700 });
 }
 /** Canonical message printed when a CLI command needs a connection but has none. */
 export const CONNECT_OR_ERROR_HINT = "Not connected to any Interf instance.\n" +
-    "Start one with `interf web` or `interf web start`, or set --url / `interf login` for a remote one.";
+    "Start one with `interf runtime` or `interf runtime start`, or set --url / `interf login` for a remote one.";

package/dist/packages/runtime/context-checks.d.ts

@@ -0,0 +1,10 @@
+import { type Artifact, type ArtifactStatus, type ContextCheck } from "../contracts/lib/schema.js";
+import type { BuildPlanAuthoringBrief } from "../build-plans/authoring/brief.js";
+export declare function buildPlanContextChecks(input: {
+    brief?: BuildPlanAuthoringBrief | null;
+    artifacts: readonly Artifact[];
+}): ContextCheck[];
+export declare function projectContextChecksForRun(input: {
+    contextChecks: readonly ContextCheck[];
+    artifactStatuses: readonly ArtifactStatus[];
+}): ContextCheck[];

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

@@ -0,0 +1,127 @@
+// COMPAT — legacy Context Check derivation, scheduled for removal once the
+// Graph Manifest readiness rollup is the only path readers consume.
+//
+// The new product spine is primary_metrics + readiness in GraphManifest
+// (see internal/plans/stage-manifest-context-graph-execution-plan-2026-05-27.md
+// Phase 7). This module still runs because:
+//   1. runtime-build-runs writes context_checks into the immutable Run record
+//      so old Run records remain consistent.
+//   2. runtime-project-reads exposes a fallback "context-checks" gate when no
+//      GraphManifest exists yet (pre-refactor builds).
+// Removal path: once all live instances have at least one GraphManifest-backed
+// Build, drop the writes in runtime-build-runs and the fallback gate in
+// runtime-project-reads, then delete this file. Do not add new callers.
+import { ContextCheckSchema, } from "../contracts/lib/schema.js";
+import { slugify } from "../contracts/utils/naming.js";
+function boundedContextCheckId(value, fallback) {
+    const normalized = slugify(value) || fallback;
+    if (normalized.length <= 80)
+        return normalized;
+    return normalized.slice(0, 80).replace(/-+$/g, "") || fallback;
+}
+function uniqueContextCheckId(value, used) {
+    const base = boundedContextCheckId(value, "context-check");
+    if (!used.has(base)) {
+        used.add(base);
+        return base;
+    }
+    for (let index = 2; index < 1000; index += 1) {
+        const suffix = `-${index}`;
+        const candidate = `${base.slice(0, 80 - suffix.length).replace(/-+$/g, "")}${suffix}`;
+        if (!used.has(candidate)) {
+            used.add(candidate);
+            return candidate;
+        }
+    }
+    throw new Error(`Could not allocate a unique Context Check id for ${value}.`);
+}
+function contextCheckId(check, index, used) {
+    return uniqueContextCheckId(check.id ?? check.label ?? `context-check-${index + 1}`, used);
+}
+function derivedContextCheckForArtifact(artifact, used) {
+    const firstCheck = artifact.checks.find((check) => check.required !== false) ?? artifact.checks[0] ?? null;
+    return ContextCheckSchema.parse({
+        id: uniqueContextCheckId(`artifact-${artifact.id}`, used),
+        label: firstCheck?.description ?? artifact.description,
+        backed_by_artifact_ids: [artifact.id],
+        required: firstCheck?.required ?? true,
+        evidence_expectation: artifact.description,
+    });
+}
+export function buildPlanContextChecks(input) {
+    const authoredChecks = input.brief?.checks ?? [];
+    const used = new Set();
+    if (authoredChecks.length > 0) {
+        return authoredChecks.map((check, index) => ContextCheckSchema.parse({
+            id: contextCheckId(check, index, used),
+            label: check.label,
+            ...(check.description ? { description: check.description } : {}),
+            backed_by_artifact_ids: check.backed_by_artifact_ids,
+            required: check.required,
+            ...(check.evidence_expectation ?? check.evidence
+                ? { evidence_expectation: check.evidence_expectation ?? check.evidence }
+                : {}),
+        }));
+    }
+    return input.artifacts.map((artifact) => derivedContextCheckForArtifact(artifact, used));
+}
+function artifactStatusMap(statuses) {
+    return new Map(statuses.map((status) => [status.artifact_id, status]));
+}
+function statusForBackedArtifacts(statuses) {
+    if (statuses.length === 0)
+        return "pending";
+    if (statuses.some((status) => status.status === "failed"))
+        return "failed";
+    if (statuses.some((status) => status.status === "not_ready"))
+        return "pending";
+    if (statuses.every((status) => status.status === "ready"))
+        return "passed";
+    if (statuses.every((status) => status.status === "skipped"))
+        return "skipped";
+    return "pending";
+}
+function firstIssue(statuses) {
+    for (const status of statuses) {
+        const failedCheck = status.check_results.find((result) => result.required !== false && !result.passed);
+        if (failedCheck)
+            return failedCheck.summary;
+        if (status.status === "failed" && status.summary)
+            return status.summary;
+    }
+    return null;
+}
+function evidenceSummary(check, statuses) {
+    const ready = statuses.filter((status) => status.status === "ready").length;
+    if (statuses.length > 0 && ready === statuses.length) {
+        return check.evidence_expectation ?? `${ready}/${statuses.length} backed Artifact${statuses.length === 1 ? "" : "s"} accepted.`;
+    }
+    return null;
+}
+export function projectContextChecksForRun(input) {
+    const statusesByArtifact = artifactStatusMap(input.artifactStatuses);
+    return input.contextChecks.map((check) => {
+        const missingArtifactIds = check.backed_by_artifact_ids
+            .filter((artifactId) => !statusesByArtifact.has(artifactId));
+        const backedStatuses = check.backed_by_artifact_ids
+            .map((artifactId) => statusesByArtifact.get(artifactId) ?? null)
+            .filter((status) => status !== null);
+        const checkStatuses = backedStatuses;
+        const status = statusForBackedArtifacts(checkStatuses);
+        const issue = check.backed_by_artifact_ids.length === 0
+            ? "Context Check is not backed by a requested Artifact."
+            : missingArtifactIds.length > 0
+                ? `Context Check references missing requested Artifact${missingArtifactIds.length === 1 ? "" : "s"}: ${missingArtifactIds.join(", ")}.`
+                : status === "failed" ? firstIssue(checkStatuses) : null;
+        const projectedStatus = issue && check.required !== false
+            ? "failed"
+            : status;
+        const evidence = projectedStatus === "passed" ? evidenceSummary(check, checkStatuses) : null;
+        return ContextCheckSchema.parse({
+            ...check,
+            status: projectedStatus,
+            ...(evidence ? { evidence } : {}),
+            ...(issue ? { issue } : {}),
+        });
+    });
+}

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

@@ -0,0 +1,9 @@
+export declare function ensureContextGraphScaffold(projectDataDir: string, projectName: string, buildPlanId?: string): string;
+export declare function ensureContextGraphScaffoldAt(options: {
+    projectDataDir: string;
+    contextGraphPath: string;
+    projectName: string;
+    buildPlanId?: string;
+}): string;
+export declare function createContextGraph(name: string, projectDataDir: string, buildPlanId: string | undefined, sourceFolderPath: string): string;
+export declare function defaultContextGraphNameForSource(projectDataDir: string): string;

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

@@ -0,0 +1,135 @@
+import { mkdirSync, existsSync, writeFileSync, } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
+import { getBuildPlan } from "../build-plans/package/build-plan-definitions.js";
+import { loadBuildPlanDefinitionFromDir, seedLocalDefaultBuildPlan } from "../build-plans/package/local-build-plans.js";
+import { initializeBuildRuntimeState, } from "./build/state.js";
+import { refreshContextGraphBootstrapGuidance } from "./agents/lib/context-graph-bootstrap.js";
+import { assertContextGraphContainer, assertContextGraphName, } from "../projects/interf-detect.js";
+import { seedContextGraphBuildPlanPackage } from "../build-plans/package/interf-build-plan-package.js";
+import { asProjectDataDir, projectContextGraphPath, } from "../contracts/lib/project-paths.js";
+import { ensureBuildPlanArtifactTargets, listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./build/context-graph-schema.js";
+import { findProjectConfig, loadSourceFolderConfig, buildPlanIdForProjectConfig, resolveProjectSourceBindingPath, saveContextGraphInterfConfig, } from "../projects/source-config.js";
+import { defaultControlPathForContextGraph, testRootForContextGraph, buildPlanPackagePathForContextGraph } from "./build/context-graph-paths.js";
+import { DEFAULT_BUILD_PLAN_ID } from "../build-plans/build-plan-resolution.js";
+const DEFAULT_INTERFIGNORE = [
+    ".claude/",
+    ".codex/",
+    ".agents/",
+    ".cursor/",
+    ".interf/tests/",
+    ".interf/tests/targets/sandboxes/",
+    ".interf/runtime/",
+    "",
+].join("\n");
+const UNBUILT_CONTEXT_GRAPH_PLACEHOLDER = "Not yet built. Run `interf build` to build this Context Graph.";
+function renderUnbuiltContextGraphFile(contextGraphName, relativePath) {
+    return [
+        `# ${contextGraphName} — ${relativePath}`,
+        "",
+        UNBUILT_CONTEXT_GRAPH_PLACEHOLDER,
+        "",
+    ].join("\n");
+}
+function contextGraphGitignoreEntries(contextGraphPath) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
+    const artifactEntries = (schema ? listBuildPlanContextArtifacts(schema) : [])
+        .map((artifact) => artifact.kind === "file" ? artifact.path : `${artifact.path}/`);
+    return [
+        ...artifactEntries,
+        ".claude/",
+        ".codex/",
+        ".agents/",
+        ".cursor/",
+        ".interf/tests/",
+        ".interf/tests/targets/sandboxes/",
+        ".interf/runtime/",
+    ];
+}
+function scaffoldContextGraphOutputs(contextGraphPath, contextGraphName) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
+    if (!schema) {
+        throw new Error(`Missing Build Plan schema at ${buildPlanPackagePathForContextGraph(contextGraphPath)}.`);
+    }
+    ensureBuildPlanArtifactTargets(contextGraphPath, schema);
+    for (const artifact of listBuildPlanContextArtifacts(schema)) {
+        if (!artifact.required || artifact.kind !== "file")
+            continue;
+        const targetPath = join(contextGraphPath, artifact.path);
+        if (existsSync(targetPath))
+            continue;
+        writeFileSync(targetPath, renderUnbuiltContextGraphFile(contextGraphName, artifact.path));
+    }
+}
+function localBuildPlanMatches(contextGraphPath, buildPlanId) {
+    const localBuildPlan = loadBuildPlanDefinitionFromDir(buildPlanPackagePathForContextGraph(contextGraphPath));
+    return localBuildPlan?.id === buildPlanId;
+}
+export function ensureContextGraphScaffold(projectDataDir, projectName, buildPlanId = DEFAULT_BUILD_PLAN_ID) {
+    const contextGraphPath = projectContextGraphPath(asProjectDataDir(projectDataDir), projectName);
+    return ensureContextGraphScaffoldAt({
+        projectDataDir,
+        contextGraphPath,
+        projectName,
+        buildPlanId,
+    });
+}
+export function ensureContextGraphScaffoldAt(options) {
+    const { projectDataDir, contextGraphPath, projectName, buildPlanId = DEFAULT_BUILD_PLAN_ID, } = options;
+    assertContextGraphName(projectName, "Context Graph");
+    assertContextGraphContainer(projectDataDir);
+    mkdirSync(contextGraphPath, { recursive: true });
+    mkdirSync(testRootForContextGraph(contextGraphPath), { recursive: true });
+    if (buildPlanId === DEFAULT_BUILD_PLAN_ID) {
+        seedLocalDefaultBuildPlan({ projectDataDir });
+    }
+    const selectedBuildPlan = getBuildPlan(buildPlanId, { projectDataDir });
+    if (!localBuildPlanMatches(contextGraphPath, selectedBuildPlan.id)) {
+        seedContextGraphBuildPlanPackage({
+            contextGraphPath,
+            projectDataDir,
+            buildPlanId: selectedBuildPlan.id,
+        });
+    }
+    if (!existsSync(join(contextGraphPath, ".gitignore"))) {
+        writeFileSync(join(contextGraphPath, ".gitignore"), [...contextGraphGitignoreEntries(contextGraphPath), ""].join("\n"));
+    }
+    return contextGraphPath;
+}
+export function createContextGraph(name, projectDataDir, buildPlanId = DEFAULT_BUILD_PLAN_ID, sourceFolderPath) {
+    assertContextGraphName(name, "Context Graph");
+    if (!sourceFolderPath || typeof sourceFolderPath !== "string") {
+        throw new Error("createContextGraph requires an explicit sourceFolderPath. Pass the absolute Source Folder path the Context Graph binds to.");
+    }
+    const savedProject = findProjectConfig(loadSourceFolderConfig(projectDataDir), name);
+    const effectiveBuildPlanId = buildPlanIdForProjectConfig(savedProject) ?? buildPlanId;
+    const selectedBuildPlan = getBuildPlan(effectiveBuildPlanId, { projectDataDir });
+    const contextGraphPath = ensureContextGraphScaffold(projectDataDir, name, selectedBuildPlan.id);
+    const resolvedSourceFolderPath = savedProject
+        ? resolveProjectSourceBindingPath(projectDataDir, savedProject)
+        : sourceFolderPath;
+    const sourceRelativePath = relative(contextGraphPath, resolvedSourceFolderPath).split(sep).join("/") || ".";
+    saveContextGraphInterfConfig(contextGraphPath, {
+        type: "context-graph",
+        name,
+        intent: savedProject?.intent ?? "",
+        build_plan: selectedBuildPlan.id,
+        build_plan_origin: {
+            selected: selectedBuildPlan.id,
+            local_draft: false,
+        },
+        source: {
+            path: sourceRelativePath,
+            control_path: defaultControlPathForContextGraph(contextGraphPath),
+            project_path: sourceRelativePath,
+        },
+    });
+    writeFileSync(join(contextGraphPath, ".interfignore"), DEFAULT_INTERFIGNORE);
+    scaffoldContextGraphOutputs(contextGraphPath, name);
+    refreshContextGraphBootstrapGuidance(contextGraphPath);
+    writeFileSync(join(contextGraphPath, ".gitignore"), [...contextGraphGitignoreEntries(contextGraphPath), ""].join("\n"));
+    initializeBuildRuntimeState(contextGraphPath);
+    return contextGraphPath;
+}
+export function defaultContextGraphNameForSource(projectDataDir) {
+    return basename(projectDataDir);
+}

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

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