@interf/compiler 0.22.2 → 0.33.0

package/dist/packages/build-plans/package/local-build-plans.js

@@ -5,10 +5,11 @@ import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { warnInterf } from "../../contracts/utils/logger.js";
 import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../contracts/utils/parse.js";
 import { isMarkdownFile } from "../../contracts/utils/file-types.js";
-import { BuildPlanEngineApiSchema, BuildPlanPurposeSchema, BuildPlanStageArtifactReadAccessSchema, BuildPlanStageArtifactWriteAccessSchema, } from "../../engine/build/lib/schema.js";
+import { BuildPlanRuntimeApiSchema, BuildPlanPurposeSchema, BuildPlanStageArtifactReadAccessSchema, BuildPlanStageArtifactWriteAccessSchema, } from "../../runtime/build/lib/schema.js";
 import { RuntimeContractTypeSchema, InterfIdPattern, } from "../../contracts/lib/schema.js";
-import { asPreparationDataDir, preparationBuildPlansRoot, } from "../../contracts/lib/preparation-paths.js";
+import { asProjectDataDir, projectBuildPlansRoot, } from "../../contracts/lib/project-paths.js";
 import { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, contextInterfaceExists, contextInterfaceFilePath, listContextInterfaceArtifacts, readContextInterface, BuildPlanInputSpecSchema, writeContextInterface, } from "./context-interface.js";
+import { BuildPlanAuthoringBriefSchema, } from "../authoring/brief.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
 const LocalBuildPlanStageDefinitionSchema = z.object({
     id: z.string().regex(InterfIdPattern),
@@ -23,8 +24,9 @@ const LocalBuildPlanStageDefinitionSchema = z.object({
 const LocalBuildPlanDefinitionSchema = z.object({
     id: z.string().regex(InterfIdPattern),
     type: z.literal("build-plan"),
-    engine_api: BuildPlanEngineApiSchema.optional(),
+    runtime_api: BuildPlanRuntimeApiSchema.optional(),
     purpose: BuildPlanPurposeSchema.optional(),
+    brief: BuildPlanAuthoringBriefSchema.optional(),
     inputs: z.array(BuildPlanInputSpecSchema).min(1).optional(),
     label: z.string().min(1),
     hint: z.string().min(1),
@@ -62,14 +64,14 @@ export function mergeStagePolicyNotesForStages(stages, baseNotes, overrideNotes)
     }
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
-function buildPlanRootPath(prepDataDir) {
-    return preparationBuildPlansRoot(asPreparationDataDir(prepDataDir));
+function buildPlanRootPath(projectDataDir) {
+    return projectBuildPlansRoot(asProjectDataDir(projectDataDir));
 }
 export function builtinBuildPlanPackagePath(buildPlanId) {
     return join(PACKAGE_ROOT, "public-repo", "build-plans", buildPlanId);
 }
-export function buildPlanDefinitionPath(prepDataDir, id) {
-    return join(buildPlanRootPath(prepDataDir), id);
+export function buildPlanDefinitionPath(projectDataDir, id) {
+    return join(buildPlanRootPath(projectDataDir), id);
 }
 function isSupportedBuildPlanStarterDocPath(relativePath) {
     if (relativePath === "README.md")
@@ -139,7 +141,7 @@ export function loadBuildPlanDefinitionFromDir(dirPath) {
         buildPlanSchemaPath: contextInterfaceFilePath(dirPath),
     };
 }
-export function isNeutralScaffoldBuildPlanDefinition(definition) {
+function isNeutralScaffoldBuildPlanDefinition(definition) {
     const hasScaffoldPurpose = definition.purpose?.label === "From-scratch Build Plan draft" ||
         Boolean(definition.purpose?.task_hint?.includes("Replace this neutral scaffold"));
     const hasScaffoldStage = Boolean(definition.stages?.some((stage) => stage.id === "prepare" &&
@@ -149,9 +151,9 @@ export function isNeutralScaffoldBuildPlanDefinition(definition) {
         artifact.description.includes("neutral authoring scaffold"));
     return hasScaffoldPurpose || hasScaffoldStage || hasScaffoldArtifact;
 }
-export function listLocalBuildPlanDefinitions(prepDataDir) {
+export function listLocalBuildPlanDefinitions(projectDataDir) {
     const definitions = new Map();
-    const root = buildPlanRootPath(prepDataDir);
+    const root = buildPlanRootPath(projectDataDir);
     if (existsSync(root)) {
         for (const entryPath of readdirSync(root).map((entry) => join(root, entry))) {
             try {
@@ -169,14 +171,14 @@ export function listLocalBuildPlanDefinitions(prepDataDir) {
     }
     return [...definitions.values()].sort((a, b) => a.label.localeCompare(b.label));
 }
-export function loadLocalBuildPlanDefinition(prepDataDir, id) {
-    const definition = loadBuildPlanDefinitionFromDir(buildPlanDefinitionPath(prepDataDir, id));
+export function loadLocalBuildPlanDefinition(projectDataDir, id) {
+    const definition = loadBuildPlanDefinitionFromDir(buildPlanDefinitionPath(projectDataDir, id));
     if (!definition || isNeutralScaffoldBuildPlanDefinition(definition))
         return null;
     return definition;
 }
-export function resolveBuildPlanPackageSourcePath(prepDataDir, buildPlanId) {
-    const localPath = buildPlanDefinitionPath(prepDataDir, buildPlanId);
+export function resolveBuildPlanPackageSourcePath(projectDataDir, buildPlanId) {
+    const localPath = buildPlanDefinitionPath(projectDataDir, buildPlanId);
     const local = loadBuildPlanDefinitionFromDir(localPath);
     if (local && !isNeutralScaffoldBuildPlanDefinition(local))
         return localPath;
@@ -187,7 +189,7 @@ export function resolveBuildPlanPackageSourcePath(prepDataDir, buildPlanId) {
 }
 export function seedLocalDefaultBuildPlan(options) {
     const buildPlanId = "interf-default";
-    const targetPath = buildPlanDefinitionPath(options.prepDataDir, buildPlanId);
+    const targetPath = buildPlanDefinitionPath(options.projectDataDir, buildPlanId);
     if (existsSync(join(targetPath, "build-plan.json"))) {
         return { buildPlanId, targetPath, alreadyExisted: true };
     }
@@ -199,7 +201,7 @@ export function seedLocalDefaultBuildPlan(options) {
     patchBuildPlanPackageMetadata(targetPath, {
         id: buildPlanId,
         label: "Built-in Interf Build Plan",
-        hint: "Built-in file-processing Build Plan: summarize source-grounded evidence, structure cross-file connections, and shape verifiable context around the saved readiness checks.",
+        hint: "Built-in file-processing Build Plan: summarize source-grounded evidence, structure cross-file connections, and shape the Context Graph around the saved Checks.",
     });
     return { buildPlanId, targetPath, alreadyExisted: false };
 }
@@ -226,7 +228,7 @@ export function patchBuildPlanPackageMetadata(dirPath, options) {
     const nextBuildPlanJson = {
         ...buildPlanJson,
         type: "build-plan",
-        engine_api: buildPlanJson.engine_api ?? {
+        runtime_api: buildPlanJson.runtime_api ?? {
             kind: "build",
             version: 1,
         },
@@ -377,11 +379,12 @@ export function validateBuildPlanPackage(dirPath) {
     if (buildPlanSchema) {
         const stages = def.stages ?? [];
         const stageIds = new Set(stages.map((stage) => stage.id));
-        const seenPaths = new Map();
+        const seenArtifactsByPath = new Map();
         const seenArtifactIds = new Set();
         const schemaArtifacts = listContextInterfaceArtifacts(buildPlanSchema);
         const artifactById = new Map(schemaArtifacts.map((artifact) => [artifact.id, artifact]));
         const normalizedParts = (value) => value.replaceAll("\\", "/").split("/").filter(Boolean);
+        const normalizedPathKey = (value) => normalizedParts(value).join("/");
         const hasOverlappingPath = (value, other) => {
             const a = normalizedParts(value);
             const b = normalizedParts(other);
@@ -389,32 +392,57 @@ export function validateBuildPlanPackage(dirPath) {
             const longer = a.length <= b.length ? b : a;
             return shorter.every((part, index) => longer[index] === part);
         };
+        const requiredLayerPaths = new Set(["summaries", "knowledge", "artifacts"]);
+        const isRequiredLayerArtifact = (artifact) => artifact.kind === "directory" && requiredLayerPaths.has(normalizedPathKey(artifact.path));
+        const allowsRequiredLayerContainment = (artifact, existingArtifact) => {
+            const artifactPath = normalizedPathKey(artifact.path);
+            const existingPath = normalizedPathKey(existingArtifact.path);
+            if (artifactPath === existingPath)
+                return false;
+            if (!hasOverlappingPath(artifact.path, existingArtifact.path))
+                return false;
+            return isRequiredLayerArtifact(artifact) || isRequiredLayerArtifact(existingArtifact);
+        };
         for (const artifact of schemaArtifacts) {
             if (seenArtifactIds.has(artifact.id)) {
                 errors.push(`build-plan.schema.json repeats Artifact id "${artifact.id}".`);
             }
             seenArtifactIds.add(artifact.id);
-            const existingPathOwner = seenPaths.get(artifact.path);
+            const pathKey = normalizedPathKey(artifact.path);
+            const existingPathOwner = seenArtifactsByPath.get(pathKey);
             if (existingPathOwner) {
                 errors.push(`build-plan.schema.json repeats Artifact path "${artifact.path}".`);
             }
-            for (const [existingPath, existingZoneId] of seenPaths.entries()) {
-                if (existingPath === artifact.path)
+            for (const existingArtifact of seenArtifactsByPath.values()) {
+                if (normalizedPathKey(existingArtifact.path) === pathKey)
                     continue;
-                if (hasOverlappingPath(artifact.path, existingPath)) {
-                    errors.push(`build-plan.schema.json Artifacts "${artifact.id}" and "${existingZoneId}" overlap on path "${artifact.path}" / "${existingPath}".`);
+                if (hasOverlappingPath(artifact.path, existingArtifact.path) &&
+                    !allowsRequiredLayerContainment(artifact, existingArtifact)) {
+                    errors.push(`build-plan.schema.json Artifacts "${artifact.id}" and "${existingArtifact.id}" overlap on path "${artifact.path}" / "${existingArtifact.path}".`);
                 }
             }
-            seenPaths.set(artifact.path, artifact.id);
-            if ((artifact.role === "input" || artifact.role === "runtime") && artifact.owned_by.length > 0) {
-                errors.push(`build-plan.schema.json Artifact "${artifact.id}" cannot declare owners because its role is "${artifact.role}".`);
-            }
+            seenArtifactsByPath.set(pathKey, artifact);
             for (const owner of artifact.owned_by) {
                 if (!stageIds.has(owner)) {
                     errors.push(`build-plan.schema.json references unknown stage "${owner}" for Artifact path "${artifact.path}".`);
+                    continue;
+                }
+                const ownerStage = stages.find((stage) => stage.id === owner);
+                if (ownerStage && !ownerStage.writes.includes(artifact.id)) {
+                    errors.push(`build-plan.schema.json Artifact "${artifact.id}" is owned by stage "${owner}" but that stage does not write it in build-plan.json.`);
                 }
             }
         }
+        for (const requiredPath of ["summaries", "knowledge", "artifacts"]) {
+            const artifact = seenArtifactsByPath.get(requiredPath);
+            if (!artifact) {
+                errors.push(`File-based Build Plan packages must declare a writable Artifact at "${requiredPath}".`);
+                continue;
+            }
+            if (artifact.owned_by.length === 0) {
+                errors.push(`File-based Build Plan Artifact "${artifact.id}" at "${requiredPath}" must be owned by at least one stage.`);
+            }
+        }
         for (const stage of stages) {
             for (const artifactId of stage.reads) {
                 if (!artifactById.has(artifactId)) {
@@ -427,9 +455,6 @@ export function validateBuildPlanPackage(dirPath) {
                     errors.push(`Stage "${stage.id}" writes unknown Artifact "${artifactId}".`);
                     continue;
                 }
-                if (artifact.role === "input" || artifact.role === "runtime") {
-                    errors.push(`Stage "${stage.id}" writes Artifact "${artifactId}" but Artifacts with role "${artifact.role}" are engine-owned inputs, not writable stage outputs.`);
-                }
                 if (!artifact.owned_by.includes(stage.id)) {
                     errors.push(`Stage "${stage.id}" writes Artifact "${artifactId}" but that Artifact is not owned by the stage in build-plan.schema.json.`);
                 }
@@ -457,7 +482,7 @@ function describeContextInterfaceValidationIssues(dirPath) {
     if (!existsSync(buildPlanSchemaPath)) {
         return ["build-plan.schema.json is missing."];
     }
-    const raw = readJsonFileUnchecked(buildPlanSchemaPath, "Build Plan context interface");
+    const raw = readJsonFileUnchecked(buildPlanSchemaPath, "Build Plan requested Artifact contract");
     if (raw === null) {
         return ["build-plan.schema.json is invalid JSON."];
     }

package/dist/packages/build-plans/package/user-build-plans.js

@@ -1,7 +1,7 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { warnInterf } from "../../contracts/utils/logger.js";
-import { userBuildPlanPackagePath, userBuildPlansRoot, } from "../../contracts/lib/preparation-paths.js";
+import { userBuildPlanPackagePath, userBuildPlansRoot, } from "../../contracts/lib/project-paths.js";
 import { loadBuildPlanDefinitionFromDir, } from "./local-build-plans.js";
 export function userBuildPlanPath(id) {
     return userBuildPlanPackagePath(id);

package/dist/packages/contracts/index.d.ts

@@ -1,3 +1,5 @@
 export * as schema from "./lib/schema.js";
-export type { AgentRecord, AgentsRegistry, Artifact, ArtifactId, ArtifactShape, ArtifactStatus, CanonicalRole, Check, CheckKind, GateStatus, Locator, LocatorKind, BuildPlanId, PreparationName, Proof, ReadinessGate, ReadinessStatus, Readiness, ReadyVerdict, RoleMap, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, Source, SourceFile, SourceFiles, SourceKind, SourceSnapshot, StageInput, StageInputs, StandardEvidenceFrontmatterKey, TestCaseExpect, TestTargetType, VerifyTargetResult, } from "./lib/schema.js";
-export { CANONICAL_ROLES, CHECK_KINDS, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";
+export * as projectSchema from "./lib/project-schema.js";
+export type { AgentRecord, AgentsRegistry, Artifact, ArtifactId, ArtifactShape, ArtifactStatus, CanonicalRole, Check, CheckKind, BuildCheckRow, BuildEvidenceIssueState, BuildEvidenceMetric, BuildEvidenceRef, BuildEvidenceResource, ContextCheck, ContextCheckDeclaration, ContextCheckProjection, ContextCheckStatus, GateStatus, Locator, LocatorKind, BuildPlanId, ProjectId, CheckResult, ReadinessGate, ReadinessStatus, Readiness, ReadyVerdict, RoleMap, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, Source, SourceFile, SourceFiles, SourceKind, SourceState, StageEvidence, StageEvidenceCount, StageEvidenceEdge, StageEvidenceItem, StageEvidenceOutputRef, StageEvidenceSourceRef, StageInput, StageInputs, StandardEvidenceFrontmatterKey, TestCaseExpect, TestTargetType, VerifyTargetResult, } from "./lib/schema.js";
+export type { ContextGraph, ContextGraphLocator, DriftKind, ProjectName, ProjectSourceState, Trace, Traces, } from "./lib/project-schema.js";
+export { CANONICAL_ROLES, CHECK_PARAM_CONTRACTS, CHECK_KINDS, ContextCheckDeclarationSchema, ContextCheckProjectionSchema, ContextCheckSchema, ContextCheckStatusSchema, BuildCheckRowSchema, BuildEvidenceIssueStateSchema, BuildEvidenceMetricSchema, BuildEvidenceRefSchema, BuildEvidenceResourceSchema, EvidenceCountKeySchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, StageEvidenceOutputRefSchema, StageEvidenceSchema, StageEvidenceSourceRefSchema, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";

package/dist/packages/contracts/index.js

@@ -1,2 +1,3 @@
 export * as schema from "./lib/schema.js";
-export { CANONICAL_ROLES, CHECK_KINDS, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";
+export * as projectSchema from "./lib/project-schema.js";
+export { CANONICAL_ROLES, CHECK_PARAM_CONTRACTS, CHECK_KINDS, ContextCheckDeclarationSchema, ContextCheckProjectionSchema, ContextCheckSchema, ContextCheckStatusSchema, BuildCheckRowSchema, BuildEvidenceIssueStateSchema, BuildEvidenceMetricSchema, BuildEvidenceRefSchema, BuildEvidenceResourceSchema, EvidenceCountKeySchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, StageEvidenceOutputRefSchema, StageEvidenceSchema, StageEvidenceSourceRefSchema, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";

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

@@ -0,0 +1,137 @@
+/**
+ * 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/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,211 @@
+/**
+ * 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/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`);
+}