@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/contracts/lib/context-graph-layer.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+/**
+ * The Context Graph layer model — defined ONCE here and imported by every
+ * consumer (Build Plan authoring validation, package validation, StageManifest
+ * role inference, the graph-relative link scanner, and the deterministic check
+ * defaults). This is the single source of truth for "what are the canonical
+ * top-level layers of a Context Graph, and how does a path classify into one."
+ *
+ * The architecture is FIXED top-level layers / FLEXIBLE interior:
+ *   - `summaries/` — the grounding/coverage layer (one folder per Source file).
+ *   - `knowledge/` — the knowledge graph layer; its interior is free
+ *     (`knowledge/claims/`, `knowledge/entities/`, `knowledge/timelines/`, …).
+ *   - `artifacts/`  — task handoffs / supplemental entrypoints.
+ *   - `home.md`    — the primary entrypoint spine file (exact, no children).
+ *
+ * Two faces, one definition:
+ *   - The canonical lowercase set (`CANONICAL_LAYER_DIRS`, `CanonicalLayerSchema`,
+ *     `isCanonicalLayerDeclaration`) is what a Build Plan may DECLARE. Authoring
+ *     is strict: a layer must be declared in exact lowercase (`knowledge/`, not
+ *     `Knowledge/`).
+ *   - The tolerant classifier (`layerForPath`, `roleForLayerPath`) is DEFENSIVE
+ *     POLICING of already-built (possibly hand-edited or bad) outputs. It is
+ *     case-insensitive so a graph that shipped `Knowledge/` notes is still
+ *     routed into the knowledge layer and still policed by the orphan / web
+ *     gates — casing can never be used to dodge a gate. Classification only ever
+ *     widens membership; it never narrows it.
+ */
+// ───────────────────────────────────────────────────────────────────────────
+// Canonical directory layers
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The three canonical top-level DIRECTORY layers, in lockstep lowercase. These
+ * are the only top-level folders a Build Plan may declare for core derived
+ * content. `home.md` is the spine FILE and is handled separately (it is not a
+ * directory layer).
+ */
+export const CANONICAL_LAYER_DIRS = ["summaries", "knowledge", "artifacts"];
+/**
+ * Set form of the canonical directory layers, for membership tests at call
+ * sites (authoring guard, package validation) that previously hand-rolled their
+ * own `new Set(["summaries", "knowledge", "artifacts"])`.
+ */
+export const CANONICAL_LAYER_DIR_SET = new Set(CANONICAL_LAYER_DIRS);
+/**
+ * The canonical layer "label" a path resolves to. Mirrors the directory layers
+ * plus `home` (the spine) and `other` (anything outside the canonical
+ * skeleton). This is the layer identity used for role inference and per-layer
+ * rollups.
+ */
+export const CanonicalLayerSchema = z.enum([
+    "summaries",
+    "knowledge",
+    "artifacts",
+    "home",
+    "other",
+]);
+/**
+ * The exact spine file name. Canonical only as the top-level file `home.md`
+ * with no children.
+ */
+export const HOME_SPINE_FILE = "home.md";
+// ───────────────────────────────────────────────────────────────────────────
+// Path normalization
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Normalize a path to forward slashes with no leading `./` and no trailing
+ * slashes. Shared so every consumer normalizes identically before classifying
+ * — a layer must not depend on `\` vs `/` or a stray trailing separator.
+ */
+export function normalizeLayerPath(value) {
+    return value
+        .replaceAll("\\", "/")
+        .replace(/^\.\/+/, "")
+        .replace(/\/+$/g, "");
+}
+/**
+ * The FIRST path segment of a normalized path (the top-level folder, or the
+ * file name when the path is a bare top-level file). Empty string for an empty
+ * path. Layer membership keys off this segment only, so the entire interior of
+ * `knowledge/` is unconstrained.
+ */
+export function topLevelSegment(value) {
+    const normalized = normalizeLayerPath(value);
+    if (normalized.length === 0)
+        return "";
+    return normalized.split("/")[0] ?? "";
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Authoring face — strict, exact-lowercase declarations
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Is `segment` an EXACT canonical layer declaration a Build Plan may use? Used
+ * by authoring validation. Strict: `knowledge` passes, `Knowledge` does NOT.
+ * The mixed-case form is rejected at authoring so a declaration can never pass
+ * authoring and then break the lowercase-path-based package validators and
+ * runtime scanners downstream.
+ */
+export function isCanonicalLayerDeclaration(segment) {
+    return CANONICAL_LAYER_DIRS.includes(segment);
+}
+/**
+ * Is this normalized top-level path a legal canonical DECLARATION? Accepts the
+ * exact lowercase layer dirs (and their interiors, since only the first segment
+ * is checked) and the exact spine file `home.md`. Strict on case. A non-path
+ * artifact (no folder) is the caller's concern; this only judges path shape.
+ */
+export function isCanonicalDeclarationPath(rawPath) {
+    const normalized = normalizeLayerPath(rawPath);
+    if (normalized.length === 0)
+        return false;
+    const segment = topLevelSegment(normalized);
+    // `home.md` is canonical only as the exact top-level spine file (no children).
+    if (segment === HOME_SPINE_FILE && normalized === segment)
+        return true;
+    return isCanonicalLayerDeclaration(segment);
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Policing face — tolerant, case-insensitive classification
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Classify any path into its canonical layer. Case-INSENSITIVE on the top-level
+ * segment: a custom plan (or a hand-edited output) writing notes into
+ * `Knowledge/` (or `Summaries/`/`Artifacts/`) still classifies into the right
+ * layer, so the orphan + web + connectivity gates can't be dodged by path
+ * casing. Canonical layers are lowercase; this only WIDENS membership, never
+ * narrows it, and is the single classifier every consumer (note role, stage
+ * role, disconnected/web checks, metrics) routes through.
+ *
+ * Returns `home` for the spine file, a directory layer for `summaries/`,
+ * `knowledge/`, `artifacts/`, and `other` for anything else.
+ */
+export function layerForPath(rawPath) {
+    const lower = normalizeLayerPath(rawPath).toLowerCase();
+    if (lower.length === 0)
+        return "other";
+    if (lower === HOME_SPINE_FILE)
+        return "home";
+    const segment = lower.split("/")[0] ?? "";
+    if (CANONICAL_LAYER_DIRS.includes(segment)) {
+        return segment;
+    }
+    return "other";
+}
+/**
+ * The directory layer (or `null`) a check should scan for a given artifact
+ * target path. `home` and `other` have no scannable directory layer, so they
+ * return `null`; the three directory layers return their lowercase dir name.
+ * Used by the deterministic checks to derive their scan root from the artifact
+ * they are attached to instead of hardcoding a layer dir.
+ */
+export function layerDirForPath(rawPath) {
+    const layer = layerForPath(rawPath);
+    return layer === "home" || layer === "other" ? null : layer;
+}
+export function knowledgeNoteKind(rawPath) {
+    const normalized = normalizeLayerPath(rawPath).toLowerCase();
+    const leaf = normalized.split("/").pop() ?? "";
+    if (normalized.startsWith("knowledge/claims/") || leaf.startsWith("claim-"))
+        return "claim";
+    if (normalized.startsWith("knowledge/entities/") || leaf.startsWith("entity-"))
+        return "entity";
+    if (normalized.startsWith("knowledge/indexes/") || leaf.startsWith("index-"))
+        return "index";
+    return null;
+}
+export function roleForLayer(layer) {
+    switch (layer) {
+        case "summaries":
+            return "summary";
+        case "knowledge":
+            return "knowledge";
+        case "artifacts":
+        case "home":
+            return "entrypoint";
+        case "other":
+            return "other";
+    }
+}
+/**
+ * Role for a produced-note path (or any graph-relative path), via the tolerant
+ * classifier. This is the single mapping `roleForPath` callers route through.
+ */
+export function roleForLayerPath(rawPath) {
+    return roleForLayer(layerForPath(rawPath));
+}
+/**
+ * Role for a Build Plan artifact's WRITE path. A directory artifact declared as
+ * a bare layer token (`knowledge`, `summaries`, `artifacts`) carries no
+ * trailing segment; it is still classified as that layer because classification
+ * keys off the (case-insensitive) first segment. The `home`/`home.md` spine is
+ * the entrypoint. This makes a custom plan that writes artifact id "claims" to
+ * path `knowledge/` (or the bare token `knowledge`) still classify as the
+ * knowledge layer, with no reliance on stringly ids.
+ */
+export function roleForWritePath(rawPath) {
+    const path = normalizeLayerPath(rawPath);
+    if (path === "home" || path === HOME_SPINE_FILE)
+        return "entrypoint";
+    return roleForLayerPath(path);
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Graph-relative link scanner
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Matches a graph-relative reference to a canonical layer note inside free text
+ * (note bodies): `summaries/…`, `knowledge/…`, `artifacts/…` (optionally ending
+ * `.md`), or the exact `home.md`, when bounded by whitespace/brackets/quotes.
+ * Derived from `CANONICAL_LAYER_DIRS` so the scanner and the layer model can
+ * never list different folders. A fresh RegExp is returned each call because the
+ * pattern is stateful (`/g`) and reusing one instance across `matchAll` loops
+ * would carry `lastIndex` between callers.
+ */
+export function graphRelativePathPattern() {
+    const dirs = CANONICAL_LAYER_DIRS.join("|");
+    return new RegExp(`(?:^|[\\s"'([{<])((?:${dirs})\\/[A-Za-z0-9._~!$&*+,;=:@%/-]+(?:\\.md)?|${HOME_SPINE_FILE.replace(".", "\\.")})(?=$|[\\s"'\`)\\]}>.,;:])`, "g");
+}

package/dist/packages/contracts/lib/project-paths.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Source of truth for every Interf path on disk.
+ *
+ * Two roots, one helper per named location. Code never string-concatenates
+ * path segments to product locations; it calls the helper here.
+ *
+ * Branded string types catch "passed a Source Folder where I expected a
+ * Project Data Dir" at the type-checker level instead of at runtime.
+ *
+ * Two roots:
+ * - **Interf Home** (`~/.interf/`): per-user, cross-Project state. Holds
+ *   the user-level Build Plan library and the central service registry.
+ * - **Project Data Dir**: a directory that IS a Project's state
+ *   root. Holds `interf.json`, `build-plans/`, the Context Graph output, and
+ *   the service-internal `.service/` scratch dir. The user's Source Folders
+ *   are passed as `--source <path>` — they are inputs, not part of the
+ *   Project data dir.
+ *
+ * No nested `interf/` namespace. The data dir IS the state root, full stop.
+ */
+/** Absolute path to `~/.interf/` (overridable via `INTERF_USER_HOME`). */
+export type InterfHomeRoot = string & {
+    readonly __brand: "InterfHomeRoot";
+};
+/** Absolute path to a directory that IS a Project's state root. */
+export type ProjectDataDir = string & {
+    readonly __brand: "ProjectDataDir";
+};
+/** Absolute path to a Source Folder — the user's input. Read-only by default. */
+export type SourceFolderPath = string & {
+    readonly __brand: "SourceFolderPath";
+};
+/** Absolute path to a Context Graph output directory. */
+export type ContextGraphPath = string & {
+    readonly __brand: "ContextGraphPath";
+};
+/** Project config filename. */
+export declare const PROJECT_CONFIG_FILENAME = "interf.json";
+/** The Context Graph state directory name (lives at `<context-graph>/.interf/`). */
+export declare const CONTEXT_GRAPH_STATE_DIR = ".interf";
+/** Build Plan packages directory name (Project drafts and user library). */
+export declare const BUILD_PLANS_DIR = "build-plans";
+/** Service-internal directory inside a Project data dir. */
+export declare const SERVICE_DIR = ".service";
+/** Service registry filename inside Interf Home. */
+export declare const SERVICE_REGISTRY_FILENAME = "services.json";
+/** Service jobs subdir. */
+export declare const SERVICE_JOBS_DIR = "jobs";
+/** Service action-proposals subdir. */
+export declare const SERVICE_ACTION_PROPOSALS_DIR = "action-proposals";
+/** Service action-plans subdir. */
+export declare const SERVICE_ACTION_PLANS_DIR = "action-plans";
+/** Tests directory inside a Project data dir. */
+export declare const PROJECT_TESTS_DIR = "tests";
+/** Per-run Context Graph output directory inside a Project data dir. */
+export declare const CONTEXT_GRAPHS_DIR = "graphs";
+/** Tests-spec subdir. */
+export declare const PROJECT_TESTS_SPECS_DIR = "specs";
+/** Per-Context Graph tests directory. */
+export declare const CONTEXT_GRAPH_TESTS_DIR = "tests";
+/** Per-Context Graph runtime directory. */
+export declare const CONTEXT_GRAPH_RUNTIME_DIR = "runtime";
+/** Per-Context Graph Build Plan package directory. */
+export declare const CONTEXT_GRAPH_BUILD_PLAN_DIR = "build-plan";
+/** Environment variable that overrides Interf Home for tests. */
+export declare const INTERF_USER_HOME_ENV = "INTERF_USER_HOME";
+/** Interf Home directory name under the OS home dir. */
+export declare const INTERF_HOME_DIR = ".interf";
+/** Projects directory inside Interf Home. */
+export declare const PROJECTS_DIR = "projects";
+/** CLI connection record filename inside Interf Home. */
+export declare const CONNECTION_CONFIG_FILENAME = "connection.json";
+export declare function asProjectDataDir(path: string): ProjectDataDir;
+export declare function asSourceFolderPath(path: string): SourceFolderPath;
+export declare function asContextGraphPath(path: string): ContextGraphPath;
+/** `~/.interf/` (or `INTERF_USER_HOME` override). */
+export declare function interfHomeRoot(): InterfHomeRoot;
+/** `~/.interf/connection.json` — single CLI connection record. */
+export declare function connectionConfigPath(): string;
+/** `~/.interf/build-plans/` — user-level Build Plan library root. */
+export declare function userBuildPlansRoot(): string;
+/** `~/.interf/build-plans/<id>/` — a specific user-library Build Plan package. */
+export declare function userBuildPlanPackagePath(buildPlanId: string): string;
+/** `~/.interf/services.json` — central service registry. */
+export declare function serviceRegistryPath(): string;
+/** `~/.interf/projects/` — root for all Project state. */
+export declare function projectsRoot(): string;
+/** `~/.interf/projects/<project-id>/` — one Project state dir. */
+export declare function projectDataDir(projectId: string): ProjectDataDir;
+/** `<project-data>/interf.json` — Project config source of truth. */
+export declare function projectConfigPath(projectDataDir: ProjectDataDir): string;
+/** `<project-data>/build-plans/` — Project-draft Build Plan packages root. */
+export declare function projectBuildPlansRoot(projectDataDir: ProjectDataDir): string;
+/** `<project-data>/build-plans/<id>/` — a Project-draft Build Plan package. */
+export declare function projectBuildPlanPackagePath(projectDataDir: ProjectDataDir, buildPlanId: string): string;
+/** `<project-data>/<project-id>/` — legacy Project-level Context Graph root. */
+export declare function projectContextGraphPath(projectDataDir: ProjectDataDir, projectName: string): ContextGraphPath;
+/** `<project-data>/graphs/` — per-run Context Graph outputs root. */
+export declare function projectContextGraphsRoot(projectDataDir: ProjectDataDir): string;
+/** `<project-data>/graphs/<run-id>/` — one Build Run's Context Graph output. */
+export declare function projectRunContextGraphPath(projectDataDir: ProjectDataDir, runId: string): ContextGraphPath;
+/** `<project-data>/.service/` — service-owned scratch dir for jobs and proposals. */
+export declare function projectServiceRoot(projectDataDir: ProjectDataDir): string;
+/** `<project-data>/.service/jobs/`. */
+export declare function projectServiceJobsRoot(projectDataDir: ProjectDataDir): string;
+/**
+ * `<project-data>/.service/jobs/shells/` — preserved, inspectable execution
+ * shells for graph-less agent jobs (Build Plan draft/improve, benchmark-question
+ * draft). Each `LocalJobRun.result.shell_path` points at one frozen shell here,
+ * the graph-less analogue of a Context Graph's stage execution shells.
+ */
+export declare function projectServiceJobShellsRoot(projectDataDir: ProjectDataDir): string;
+/** `<project-data>/.service/action-proposals/`. */
+export declare function projectServiceActionProposalsRoot(projectDataDir: ProjectDataDir): string;
+/** `<project-data>/.service/action-plans/`. */
+export declare function projectServiceActionPlansRoot(projectDataDir: ProjectDataDir): string;
+/** `<project-data>/.service/build-runs/` — Project activity index for Build Runs. */
+export declare function projectServiceBuildRunsRoot(projectDataDir: ProjectDataDir): string;
+/** `<project-data>/tests/specs/` — saved benchmark specs. */
+export declare function projectTestsSpecsRoot(projectDataDir: ProjectDataDir): string;
+/** `<context-graph>/.interf/`. */
+export declare function contextGraphStateRoot(contextGraph: ContextGraphPath): string;
+/** `<context-graph>/.interf/interf.json` — runtime contract. */
+export declare function contextGraphConfigPath(contextGraph: ContextGraphPath): string;
+/** `<context-graph>/.interf/build-plan/` — active Build Plan package inside Context Graph. */
+export declare function contextGraphBuildPlanPath(contextGraph: ContextGraphPath): string;
+/** `<context-graph>/.interf/runtime/`. */
+export declare function contextGraphRuntimeRoot(contextGraph: ContextGraphPath): string;
+/** `<context-graph>/.interf/tests/`. */
+export declare function contextGraphTestsRoot(contextGraph: ContextGraphPath): string;
+/** Test target labels: source-files (raw input) vs Context Graph. */
+export type ProjectTestTargetLabel = "source-files" | "context-graph";
+/** `<project-data>/<project>/.interf/tests/`. */
+export declare function projectTestsRoot(projectDataDir: ProjectDataDir, projectName: string): string;
+/** `<project-data>/<project>/.interf/tests/<target>/runs/`. */
+export declare function projectTestRunsRoot(projectDataDir: ProjectDataDir, projectName: string, target: ProjectTestTargetLabel): string;
+/** `<project-data>/<project>/.interf/tests/latest.json`. */
+export declare function projectLatestBenchmarkRunPath(projectDataDir: ProjectDataDir, projectName: string): string;
+/** `<project-data>/<project>/.interf/tests/latest.md`. */
+export declare function projectLatestBenchmarkSummaryPath(projectDataDir: ProjectDataDir, projectName: string): string;
+/** Normalize a free-form string into a stable, kebab-cased id (≤80 chars). */
+export declare function normalizeProjectTestRunId(input: string): string;
+/** `<project-data>/<project>/.interf/tests/<target>/runs/<timestamp>-<run-id>[-<suffix>].json`. */
+export declare function projectTestRunPath(projectDataDir: ProjectDataDir, projectName: string, target: ProjectTestTargetLabel, generatedAt: string, runId: string, runSuffix?: string | null): string;

package/dist/packages/contracts/lib/project-paths.js

@@ -0,0 +1,220 @@
+/**
+ * Source of truth for every Interf path on disk.
+ *
+ * Two roots, one helper per named location. Code never string-concatenates
+ * path segments to product locations; it calls the helper here.
+ *
+ * Branded string types catch "passed a Source Folder where I expected a
+ * Project Data Dir" at the type-checker level instead of at runtime.
+ *
+ * Two roots:
+ * - **Interf Home** (`~/.interf/`): per-user, cross-Project state. Holds
+ *   the user-level Build Plan library and the central service registry.
+ * - **Project Data Dir**: a directory that IS a Project's state
+ *   root. Holds `interf.json`, `build-plans/`, the Context Graph output, and
+ *   the service-internal `.service/` scratch dir. The user's Source Folders
+ *   are passed as `--source <path>` — they are inputs, not part of the
+ *   Project data dir.
+ *
+ * No nested `interf/` namespace. The data dir IS the state root, full stop.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ───────────────────────────────────────────────────────────────────────────
+// Constants — every named segment lives here, nowhere else
+// ───────────────────────────────────────────────────────────────────────────
+/** Project config filename. */
+export const PROJECT_CONFIG_FILENAME = "interf.json";
+/** The Context Graph state directory name (lives at `<context-graph>/.interf/`). */
+export const CONTEXT_GRAPH_STATE_DIR = ".interf";
+/** Build Plan packages directory name (Project drafts and user library). */
+export const BUILD_PLANS_DIR = "build-plans";
+/** Service-internal directory inside a Project data dir. */
+export const SERVICE_DIR = ".service";
+/** Service registry filename inside Interf Home. */
+export const SERVICE_REGISTRY_FILENAME = "services.json";
+/** Service jobs subdir. */
+export const SERVICE_JOBS_DIR = "jobs";
+/** Service action-proposals subdir. */
+export const SERVICE_ACTION_PROPOSALS_DIR = "action-proposals";
+/** Service action-plans subdir. */
+export const SERVICE_ACTION_PLANS_DIR = "action-plans";
+/** Tests directory inside a Project data dir. */
+export const PROJECT_TESTS_DIR = "tests";
+/** Per-run Context Graph output directory inside a Project data dir. */
+export const CONTEXT_GRAPHS_DIR = "graphs";
+/** Tests-spec subdir. */
+export const PROJECT_TESTS_SPECS_DIR = "specs";
+/** Per-Context Graph tests directory. */
+export const CONTEXT_GRAPH_TESTS_DIR = "tests";
+/** Per-Context Graph runtime directory. */
+export const CONTEXT_GRAPH_RUNTIME_DIR = "runtime";
+/** Per-Context Graph Build Plan package directory. */
+export const CONTEXT_GRAPH_BUILD_PLAN_DIR = "build-plan";
+/** Environment variable that overrides Interf Home for tests. */
+export const INTERF_USER_HOME_ENV = "INTERF_USER_HOME";
+/** Interf Home directory name under the OS home dir. */
+export const INTERF_HOME_DIR = ".interf";
+/** Projects directory inside Interf Home. */
+export const PROJECTS_DIR = "projects";
+/** CLI connection record filename inside Interf Home. */
+export const CONNECTION_CONFIG_FILENAME = "connection.json";
+// ───────────────────────────────────────────────────────────────────────────
+// Brand constructors — convert untyped strings at boundaries
+// ───────────────────────────────────────────────────────────────────────────
+export function asProjectDataDir(path) {
+    return path;
+}
+export function asSourceFolderPath(path) {
+    return path;
+}
+export function asContextGraphPath(path) {
+    return path;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Interf Home (~/.interf/) paths
+// ───────────────────────────────────────────────────────────────────────────
+/** `~/.interf/` (or `INTERF_USER_HOME` override). */
+export function interfHomeRoot() {
+    const override = process.env[INTERF_USER_HOME_ENV]?.trim();
+    if (override && override.length > 0)
+        return override;
+    return join(homedir(), INTERF_HOME_DIR);
+}
+/** `~/.interf/connection.json` — single CLI connection record. */
+export function connectionConfigPath() {
+    return join(interfHomeRoot(), CONNECTION_CONFIG_FILENAME);
+}
+/** `~/.interf/build-plans/` — user-level Build Plan library root. */
+export function userBuildPlansRoot() {
+    return join(interfHomeRoot(), BUILD_PLANS_DIR);
+}
+/** `~/.interf/build-plans/<id>/` — a specific user-library Build Plan package. */
+export function userBuildPlanPackagePath(buildPlanId) {
+    return join(userBuildPlansRoot(), buildPlanId);
+}
+/** `~/.interf/services.json` — central service registry. */
+export function serviceRegistryPath() {
+    return join(interfHomeRoot(), SERVICE_REGISTRY_FILENAME);
+}
+/** `~/.interf/projects/` — root for all Project state. */
+export function projectsRoot() {
+    return join(interfHomeRoot(), PROJECTS_DIR);
+}
+/** `~/.interf/projects/<project-id>/` — one Project state dir. */
+export function projectDataDir(projectId) {
+    return asProjectDataDir(join(projectsRoot(), projectId));
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Project Data Dir paths (the data dir IS the state root)
+// ───────────────────────────────────────────────────────────────────────────
+/** `<project-data>/interf.json` — Project config source of truth. */
+export function projectConfigPath(projectDataDir) {
+    return join(projectDataDir, PROJECT_CONFIG_FILENAME);
+}
+/** `<project-data>/build-plans/` — Project-draft Build Plan packages root. */
+export function projectBuildPlansRoot(projectDataDir) {
+    return join(projectDataDir, BUILD_PLANS_DIR);
+}
+/** `<project-data>/build-plans/<id>/` — a Project-draft Build Plan package. */
+export function projectBuildPlanPackagePath(projectDataDir, buildPlanId) {
+    return join(projectBuildPlansRoot(projectDataDir), buildPlanId);
+}
+/** `<project-data>/<project-id>/` — legacy Project-level Context Graph root. */
+export function projectContextGraphPath(projectDataDir, projectName) {
+    return join(projectDataDir, projectName);
+}
+/** `<project-data>/graphs/` — per-run Context Graph outputs root. */
+export function projectContextGraphsRoot(projectDataDir) {
+    return join(projectDataDir, CONTEXT_GRAPHS_DIR);
+}
+/** `<project-data>/graphs/<run-id>/` — one Build Run's Context Graph output. */
+export function projectRunContextGraphPath(projectDataDir, runId) {
+    return join(projectContextGraphsRoot(projectDataDir), runId);
+}
+/** `<project-data>/.service/` — service-owned scratch dir for jobs and proposals. */
+export function projectServiceRoot(projectDataDir) {
+    return join(projectDataDir, SERVICE_DIR);
+}
+/** `<project-data>/.service/jobs/`. */
+export function projectServiceJobsRoot(projectDataDir) {
+    return join(projectServiceRoot(projectDataDir), SERVICE_JOBS_DIR);
+}
+/**
+ * `<project-data>/.service/jobs/shells/` — preserved, inspectable execution
+ * shells for graph-less agent jobs (Build Plan draft/improve, benchmark-question
+ * draft). Each `LocalJobRun.result.shell_path` points at one frozen shell here,
+ * the graph-less analogue of a Context Graph's stage execution shells.
+ */
+export function projectServiceJobShellsRoot(projectDataDir) {
+    return join(projectServiceJobsRoot(projectDataDir), "shells");
+}
+/** `<project-data>/.service/action-proposals/`. */
+export function projectServiceActionProposalsRoot(projectDataDir) {
+    return join(projectServiceRoot(projectDataDir), SERVICE_ACTION_PROPOSALS_DIR);
+}
+/** `<project-data>/.service/action-plans/`. */
+export function projectServiceActionPlansRoot(projectDataDir) {
+    return join(projectServiceRoot(projectDataDir), SERVICE_ACTION_PLANS_DIR);
+}
+/** `<project-data>/.service/build-runs/` — Project activity index for Build Runs. */
+export function projectServiceBuildRunsRoot(projectDataDir) {
+    return join(projectServiceRoot(projectDataDir), "build-runs");
+}
+/** `<project-data>/tests/specs/` — saved benchmark specs. */
+export function projectTestsSpecsRoot(projectDataDir) {
+    return join(projectDataDir, PROJECT_TESTS_DIR, PROJECT_TESTS_SPECS_DIR);
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Context Graph paths (generated graph outputs)
+// ───────────────────────────────────────────────────────────────────────────
+/** `<context-graph>/.interf/`. */
+export function contextGraphStateRoot(contextGraph) {
+    return join(contextGraph, CONTEXT_GRAPH_STATE_DIR);
+}
+/** `<context-graph>/.interf/interf.json` — runtime contract. */
+export function contextGraphConfigPath(contextGraph) {
+    return join(contextGraphStateRoot(contextGraph), PROJECT_CONFIG_FILENAME);
+}
+/** `<context-graph>/.interf/build-plan/` — active Build Plan package inside Context Graph. */
+export function contextGraphBuildPlanPath(contextGraph) {
+    return join(contextGraphStateRoot(contextGraph), CONTEXT_GRAPH_BUILD_PLAN_DIR);
+}
+/** `<context-graph>/.interf/runtime/`. */
+export function contextGraphRuntimeRoot(contextGraph) {
+    return join(contextGraphStateRoot(contextGraph), CONTEXT_GRAPH_RUNTIME_DIR);
+}
+/** `<context-graph>/.interf/tests/`. */
+export function contextGraphTestsRoot(contextGraph) {
+    return join(contextGraphStateRoot(contextGraph), CONTEXT_GRAPH_TESTS_DIR);
+}
+/** `<project-data>/<project>/.interf/tests/`. */
+export function projectTestsRoot(projectDataDir, projectName) {
+    return contextGraphTestsRoot(projectContextGraphPath(projectDataDir, projectName));
+}
+/** `<project-data>/<project>/.interf/tests/<target>/runs/`. */
+export function projectTestRunsRoot(projectDataDir, projectName, target) {
+    return join(projectTestsRoot(projectDataDir, projectName), target, "runs");
+}
+/** `<project-data>/<project>/.interf/tests/latest.json`. */
+export function projectLatestBenchmarkRunPath(projectDataDir, projectName) {
+    return join(projectTestsRoot(projectDataDir, projectName), "latest.json");
+}
+/** `<project-data>/<project>/.interf/tests/latest.md`. */
+export function projectLatestBenchmarkSummaryPath(projectDataDir, projectName) {
+    return join(projectTestsRoot(projectDataDir, projectName), "latest.md");
+}
+/** Normalize a free-form string into a stable, kebab-cased id (≤80 chars). */
+export function normalizeProjectTestRunId(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+/** `<project-data>/<project>/.interf/tests/<target>/runs/<timestamp>-<run-id>[-<suffix>].json`. */
+export function projectTestRunPath(projectDataDir, projectName, target, generatedAt, runId, runSuffix) {
+    const suffix = runSuffix ? `-${normalizeProjectTestRunId(runSuffix)}` : "";
+    return join(projectTestRunsRoot(projectDataDir, projectName, target), `${generatedAt.replace(/[:.]/g, "-")}-${runId}${suffix}.json`);
+}