@interf/compiler 0.22.2 → 0.50.0

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

@@ -5,10 +5,13 @@ 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 { CANONICAL_LAYER_DIRS, } from "../../contracts/lib/context-graph-layer.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 { DEFAULT_BUILD_PLAN_ID } from "../build-plan-resolution.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
 const LocalBuildPlanStageDefinitionSchema = z.object({
     id: z.string().regex(InterfIdPattern),
@@ -23,8 +26,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,25 +66,29 @@ 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);
 }
+// The single, readable list of which package-relative docs `collectStarterDocs`
+// and `buildPlanPackageCopyPaths` treat as portable starter docs: the package
+// README plus the three authoring-doc trees. A relative path qualifies when it
+// equals or lives under one of these entries.
+const SUPPORTED_STARTER_DOC_PATHS = [
+    "README.md",
+    "improve/",
+    "use/query/",
+    "build/stages/",
+];
 function isSupportedBuildPlanStarterDocPath(relativePath) {
-    if (relativePath === "README.md")
-        return true;
-    if (relativePath.startsWith("improve/"))
-        return true;
-    if (relativePath.startsWith("use/query/"))
-        return true;
-    if (relativePath.startsWith("build/stages/"))
-        return true;
-    return false;
+    return SUPPORTED_STARTER_DOC_PATHS.some((supported) => supported.endsWith("/")
+        ? relativePath.startsWith(supported)
+        : relativePath === supported);
 }
 function collectStarterDocs(dirPath) {
     return listFilesRecursive(dirPath, isMarkdownFile)
@@ -90,7 +98,11 @@ function collectStarterDocs(dirPath) {
         relativePath,
         content: readFileSync(join(dirPath, relativePath), "utf8"),
     }))
-        .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+        // Codepoint order, not locale order: starter-doc ordering must be
+        // deterministic across machines (full vs small ICU, LANG/LC_ALL). With
+        // localeCompare, "README.md" sorts before lowercase paths in some locales
+        // and after in others, which made this collection environment-dependent.
+        .sort((a, b) => (a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0));
 }
 function buildPlanPackageCopyPaths(dirPath) {
     return [
@@ -139,7 +151,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 +161,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 +181,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;
@@ -186,8 +198,8 @@ export function resolveBuildPlanPackageSourcePath(prepDataDir, buildPlanId) {
     return null;
 }
 export function seedLocalDefaultBuildPlan(options) {
-    const buildPlanId = "interf-default";
-    const targetPath = buildPlanDefinitionPath(options.prepDataDir, buildPlanId);
+    const buildPlanId = DEFAULT_BUILD_PLAN_ID;
+    const targetPath = buildPlanDefinitionPath(options.projectDataDir, buildPlanId);
     if (existsSync(join(targetPath, "build-plan.json"))) {
         return { buildPlanId, targetPath, alreadyExisted: true };
     }
@@ -199,7 +211,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, build task-aware knowledge, and shape the Context Graph around the Project intent and coverage metrics.",
     });
     return { buildPlanId, targetPath, alreadyExisted: false };
 }
@@ -226,7 +238,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 +389,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,49 +402,74 @@ export function validateBuildPlanPackage(dirPath) {
             const longer = a.length <= b.length ? b : a;
             return shorter.every((part, index) => longer[index] === part);
         };
+        // Canonical required layer dirs come from the central layer model. Package
+        // validation is a strict-declaration context (it mirrors authoring), so it
+        // matches the exact lowercase dir name a Build Plan must declare.
+        const requiredLayerPaths = new Set(CANONICAL_LAYER_DIRS);
+        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}".`);
+                errors.push(`build-plan.schema.json repeats requested output 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}".`);
+                errors.push(`build-plan.schema.json repeats requested output 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 requested outputs "${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}".`);
+                    errors.push(`build-plan.schema.json references unknown stage "${owner}" for requested output 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 requested output "${artifact.id}" is owned by stage "${owner}" but that stage does not write it in build-plan.json.`);
                 }
             }
         }
+        for (const requiredPath of CANONICAL_LAYER_DIRS) {
+            const artifact = seenArtifactsByPath.get(requiredPath);
+            if (!artifact) {
+                errors.push(`File-based Build Plan packages must declare a writable requested output at "${requiredPath}".`);
+                continue;
+            }
+            if (artifact.owned_by.length === 0) {
+                errors.push(`File-based Build Plan requested output "${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)) {
-                    errors.push(`Stage "${stage.id}" reads unknown Artifact "${artifactId}".`);
+                    errors.push(`Stage "${stage.id}" reads unknown requested output "${artifactId}".`);
                 }
             }
             for (const artifactId of stage.writes) {
                 const artifact = artifactById.get(artifactId);
                 if (!artifact) {
-                    errors.push(`Stage "${stage.id}" writes unknown Artifact "${artifactId}".`);
+                    errors.push(`Stage "${stage.id}" writes unknown requested output "${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.`);
+                    errors.push(`Stage "${stage.id}" writes requested output "${artifactId}" but that output is not owned by the stage in build-plan.schema.json.`);
                 }
             }
         }
@@ -452,21 +490,33 @@ export function validateBuildPlanPackage(dirPath) {
         counts,
     };
 }
-function describeContextInterfaceValidationIssues(dirPath) {
+/**
+ * Explain WHY a `build-plan.schema.json` failed to read. Exported so the
+ * regression test can assert the corrected branch directly: a valid schema must
+ * return `[]` (no issues), an invalid one must return the concrete Zod issues.
+ * The previous inverted `if (parsed.success)` reported a VALID schema as
+ * "missing or invalid."
+ */
+export function describeContextInterfaceValidationIssues(dirPath) {
     const buildPlanSchemaPath = contextInterfaceFilePath(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 output contract");
     if (raw === null) {
         return ["build-plan.schema.json is invalid JSON."];
     }
     const parsed = ContextInterfaceSchema.safeParse(raw);
-    if (parsed.success) {
-        return ["build-plan.schema.json is missing or invalid."];
+    if (!parsed.success) {
+        // Invalid schema: surface the concrete Zod issues. Matches the sibling
+        // `readContextInterface` (context-interface.ts:174), which treats
+        // `!parsed.success` as the failure case. The previous `if (parsed.success)`
+        // was inverted and reported a VALID schema as "missing or invalid."
+        return parsed.error.issues.map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+            return `build-plan.schema.json ${path}: ${issue.message}`;
+        });
     }
-    return parsed.error.issues.map((issue) => {
-        const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
-        return `build-plan.schema.json ${path}: ${issue.message}`;
-    });
+    // A valid schema has no issues to describe.
+    return [];
 }

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,6 @@
 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, ProjectIntent, CheckResult, ReadinessGate, ReadinessStatus, Readiness, ReadyVerdict, RoleMap, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, Source, SourceBinding, SourceFile, SourceFiles, SourceKind, SourceState, StageEvidence, StageEvidenceCount, StageEvidenceEdge, StageEvidenceItem, StageEvidenceOutputRef, StageEvidenceSourceRef, StageInput, StageInputs, StandardEvidenceFrontmatterKey, TestCaseExpect, TestTargetType, VerifyTargetResult, } from "./lib/schema.js";
+export type { ContextGraph, ContextGraphArtifactHandoff, ContextGraphHandoff, ContextGraphLocator, ContextGraphPortableHandoff, DriftKind, ProjectName, ProjectSourceState, Trace, Traces, } from "./lib/project-schema.js";
+export { CANONICAL_ROLES, CHECK_PARAM_CONTRACTS, CHECK_KINDS, ContextCheckDeclarationSchema, ContextCheckProjectionSchema, ContextCheckSchema, ContextCheckStatusSchema, ProjectIntentSchema, SourceBindingSchema, BuildCheckRowSchema, BuildEvidenceIssueStateSchema, BuildEvidenceMetricSchema, BuildEvidenceRefSchema, BuildEvidenceResourceSchema, EvidenceCountKeySchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, StageEvidenceOutputRefSchema, StageEvidenceSchema, StageEvidenceSourceRefSchema, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";
+export { ContextGraphArtifactHandoffSchema, ContextGraphHandoffSchema, ContextGraphPortableHandoffSchema, } from "./lib/project-schema.js";

package/dist/packages/contracts/index.js

@@ -1,2 +1,4 @@
 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, ProjectIntentSchema, SourceBindingSchema, BuildCheckRowSchema, BuildEvidenceIssueStateSchema, BuildEvidenceMetricSchema, BuildEvidenceRefSchema, BuildEvidenceResourceSchema, EvidenceCountKeySchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, StageEvidenceOutputRefSchema, StageEvidenceSchema, StageEvidenceSourceRefSchema, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";
+export { ContextGraphArtifactHandoffSchema, ContextGraphHandoffSchema, ContextGraphPortableHandoffSchema, } from "./lib/project-schema.js";

package/dist/packages/contracts/lib/context-graph-layer.d.ts

@@ -0,0 +1,161 @@
+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.
+ */
+/**
+ * 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 declare const CANONICAL_LAYER_DIRS: readonly ["summaries", "knowledge", "artifacts"];
+export type CanonicalLayerDir = (typeof CANONICAL_LAYER_DIRS)[number];
+/**
+ * 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 declare const CANONICAL_LAYER_DIR_SET: ReadonlySet<CanonicalLayerDir>;
+/**
+ * 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 declare const CanonicalLayerSchema: z.ZodEnum<{
+    other: "other";
+    knowledge: "knowledge";
+    summaries: "summaries";
+    artifacts: "artifacts";
+    home: "home";
+}>;
+export type CanonicalLayer = z.infer<typeof CanonicalLayerSchema>;
+/**
+ * The exact spine file name. Canonical only as the top-level file `home.md`
+ * with no children.
+ */
+export declare const HOME_SPINE_FILE = "home.md";
+/**
+ * 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 declare function normalizeLayerPath(value: string): string;
+/**
+ * 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 declare function topLevelSegment(value: string): string;
+/**
+ * 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 declare function isCanonicalLayerDeclaration(segment: string): boolean;
+/**
+ * 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 declare function isCanonicalDeclarationPath(rawPath: string): boolean;
+/**
+ * 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 declare function layerForPath(rawPath: string): CanonicalLayer;
+/**
+ * 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 declare function layerDirForPath(rawPath: string): CanonicalLayerDir | null;
+/**
+ * The fine-grained kind of a note INSIDE the knowledge layer, by the structural
+ * convention every consumer agreed on: a `knowledge/claims/` folder (or a
+ * `claim-` leaf) is a claim, `knowledge/entities/` (or `entity-`) an entity,
+ * `knowledge/indexes/` (or `index-`) an index. `null` means "knowledge note
+ * with no recognized sub-kind". This is the single definition both the
+ * StageManifest note-kind labels and the semantic-graph node kinds delegate to,
+ * so the `knowledge/claims/` / `claim-` rules can never drift between them.
+ *
+ * Only the STRUCTURAL rules live here (folder prefix + leaf-token prefix). The
+ * looser "leaf merely contains `index`" heuristic is intentionally NOT here; it
+ * is a semantic-graph display nicety, and folding it in would silently
+ * reclassify manifest note kinds. Case-insensitive, like the rest of this
+ * module, so casing can never dodge the classification.
+ */
+export type KnowledgeNoteKind = "claim" | "entity" | "index" | null;
+export declare function knowledgeNoteKind(rawPath: string): KnowledgeNoteKind;
+/**
+ * The ResourceRef role a canonical layer maps to. `summaries → summary`,
+ * `knowledge → knowledge`, `artifacts`/`home → entrypoint`, `other → other`.
+ * Kept here (next to the layer model) so manifest role inference and the layer
+ * classifier never drift apart. The string union is the same as
+ * `ResourceRoleSchema`'s layer-bearing members; it is intentionally a plain
+ * union so this module has no import cycle back into the big schema.
+ */
+export type ContextGraphLayerRole = "summary" | "knowledge" | "entrypoint" | "other";
+export declare function roleForLayer(layer: CanonicalLayer): ContextGraphLayerRole;
+/**
+ * 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 declare function roleForLayerPath(rawPath: string): ContextGraphLayerRole;
+/**
+ * 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 declare function roleForWritePath(rawPath: string): ContextGraphLayerRole;
+/**
+ * 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 declare function graphRelativePathPattern(): RegExp;