project-tiny-context-harness 0.8.17 → 0.12.0

package/dist/lib/config.js

@@ -1,36 +1,17 @@
 import path from "node:path";
 import { CANONICAL_CORE_PACKAGE, CURRENT_SCHEMA_VERSION } from "./constants.js";
-import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
-import { pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { harnessConfigPath, harnessRoot } from "./harness-root.js";
+import { pathExists, readText } from "./fs.js";
 import { parseYaml, stringifyYaml } from "./yaml.js";
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { writeMaintenanceText } from "./maintenance-write.js";
 export function defaultConfig(root) {
     return {
         core: {
             package: CANONICAL_CORE_PACKAGE,
             schema_version: CURRENT_SCHEMA_VERSION,
         },
-        profiles: {
-            enabled: ["core-portable", "workflow-default"],
-        },
-        modularity: {
-            limit: 300,
-            policy: "strict_except_generated",
-        },
-        managed_files: [
-            { path: "AGENTS.md", strategy: "merge-block" },
-            { path: "Makefile", strategy: "merge-block" },
-            { path: harnessPath(root, "skills"), strategy: "managed" },
-            {
-                path: harnessPath(root, "ty-context-managed", "context_templates"),
-                strategy: "managed",
-            },
-            {
-                path: harnessPath(root, "ty-context-managed", "make", "ty-context.mk"),
-                strategy: "managed",
-            },
-            { path: "tools", strategy: "managed" },
-            { path: ".github/workflows/harness.yml", strategy: "create-if-missing" },
-        ],
+        managed_files: [{ path: "AGENTS.md", strategy: "merge-block" }],
         never_overwrite: ["project_context/**", "DESIGN.md", "src/**", "tests/**"],
     };
 }
@@ -45,39 +26,27 @@ export async function readConfig(projectRoot) {
 }
 export async function writeConfigIfMissing(projectRoot) {
     const root = await harnessRoot(projectRoot);
-    const configPath = path.join(projectRoot, await harnessConfigPath(projectRoot));
-    if (await pathExists(configPath)) {
+    const configPath = await harnessConfigPath(projectRoot);
+    const before = await captureMutationFileState(projectRoot, configPath);
+    if (before.exists) {
         return false;
     }
-    await writeTextIfChanged(configPath, stringifyYaml(defaultConfig(root)));
+    await writeMaintenanceText(projectRoot, configPath, stringifyYaml(defaultConfig(root)), before);
     return true;
 }
 export function normalizeConfig(value, root = ".agent") {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid harness config object");
+    if (String(value.core?.schema_version) === CURRENT_SCHEMA_VERSION &&
+        ("profiles" in value || "modularity" in value))
+        throw new Error("retired_config_fields: schema 5 does not support profiles or modularity; preserve the file and reconcile changes from old CLI use");
     const fallback = defaultConfig(root);
     return {
         core: {
             package: value.core?.package ?? fallback.core.package,
             schema_version: value.core?.schema_version ?? fallback.core.schema_version,
         },
-        profiles: {
-            enabled: normalizeProfiles(value.profiles?.enabled),
-        },
-        modularity: value.modularity,
         managed_files: value.managed_files ?? fallback.managed_files,
         never_overwrite: value.never_overwrite ?? fallback.never_overwrite,
     };
 }
-const VALID_PROFILES = new Set([
-    "core-portable",
-    "workflow-default",
-    "long-task",
-]);
-function normalizeProfiles(value) {
-    const source = value ?? ["core-portable", "workflow-default"];
-    const enabled = source.filter((profile) => VALID_PROFILES.has(profile));
-    for (const required of ["core-portable", "workflow-default"]) {
-        if (!enabled.includes(required))
-            enabled.push(required);
-    }
-    return [...new Set(enabled)];
-}

package/dist/lib/constants.d.ts

@@ -1,3 +1,3 @@
 export declare const CANONICAL_CORE_PACKAGE = "project-tiny-context-harness";
-export declare const CURRENT_SCHEMA_VERSION = "4";
+export declare const CURRENT_SCHEMA_VERSION = "5";
 export declare const CANONICAL_NPX_COMMAND = "npx --yes --package project-tiny-context-harness@latest ty-context";

package/dist/lib/constants.js

@@ -1,3 +1,3 @@
 export const CANONICAL_CORE_PACKAGE = "project-tiny-context-harness";
-export const CURRENT_SCHEMA_VERSION = "4";
+export const CURRENT_SCHEMA_VERSION = "5";
 export const CANONICAL_NPX_COMMAND = `npx --yes --package ${CANONICAL_CORE_PACKAGE}@latest ty-context`;

package/dist/lib/context-catalog/catalog-default-footprint.d.ts

@@ -0,0 +1,3 @@
+import type { ContextManifest } from "../context-manifest-schema.js";
+export type DefaultContextSelectionReason = "core" | "default_file" | "default_area" | "default_role" | "default_child";
+export declare function selectDefaultContextPaths(manifest: ContextManifest): Map<string, Set<DefaultContextSelectionReason>>;

package/dist/lib/context-catalog/catalog-default-footprint.js

@@ -0,0 +1,51 @@
+import { compareUtf8Paths, normalizeContextPath, sortedContextMap, } from "./catalog-paths.js";
+// This is the advisory startup set only. It does not restrict later reads or
+// turn default Area/read-policy selection into a Context or edit permission.
+export function selectDefaultContextPaths(manifest) {
+    const selected = new Map();
+    const add = (value, reason) => {
+        const normalized = normalizeContextPath(value);
+        const reasons = selected.get(normalized) ?? new Set();
+        reasons.add(reason);
+        selected.set(normalized, reasons);
+    };
+    add("project_context/global.md", "core");
+    // Direct selections do not seed child traversal. In particular, migration can
+    // preserve an implicit core file without activating its previously inert edges.
+    for (const file of manifest.default_files ?? [])
+        add(file, "default_file");
+    for (const area of manifest.areas) {
+        if (area.default)
+            add(area.context, "default_area");
+    }
+    const children = new Map(manifest.contexts.map((context) => [
+        normalizeContextPath(context.path),
+        context.default_children.map(normalizeContextPath),
+    ]));
+    const queue = [];
+    const queued = new Set();
+    const enqueue = (contextPath) => {
+        if (queued.has(contextPath))
+            return;
+        queued.add(contextPath);
+        queue.push(contextPath);
+    };
+    for (const context of manifest.contexts) {
+        if (context.read_policy !== "default")
+            continue;
+        const normalized = normalizeContextPath(context.path);
+        add(normalized, "default_role");
+        enqueue(normalized);
+    }
+    while (queue.length > 0) {
+        const parent = queue.shift();
+        for (const child of children.get(parent) ?? []) {
+            add(child, "default_child");
+            enqueue(child);
+        }
+    }
+    return sortedContextMap([...selected].map(([contextPath, reasons]) => [
+        contextPath,
+        new Set([...reasons].sort(compareUtf8Paths)),
+    ]));
+}

package/dist/lib/context-catalog/catalog-diagnostics.d.ts

@@ -0,0 +1,9 @@
+import type { CatalogDiagnostic, CatalogDiagnosticSeverity } from "./catalog-types.js";
+export declare function catalogDiagnostic(code: string, severity: CatalogDiagnosticSeverity, message: string, location?: {
+    path?: string;
+    line?: number;
+}): CatalogDiagnostic;
+export declare function catalogErrors(diagnostics: CatalogDiagnostic[]): string[];
+export declare function catalogWarnings(diagnostics: CatalogDiagnostic[]): string[];
+export declare function compareCatalogDiagnostics(left: CatalogDiagnostic, right: CatalogDiagnostic): number;
+export declare function sortCatalogDiagnostics(diagnostics: readonly CatalogDiagnostic[]): CatalogDiagnostic[];

package/dist/lib/context-catalog/catalog-diagnostics.js

@@ -0,0 +1,34 @@
+import { compareUtf8Paths, normalizeContextPath } from "./catalog-paths.js";
+const DIAGNOSTIC_SEVERITY_ORDER = {
+    error: 0,
+    warning: 1,
+};
+export function catalogDiagnostic(code, severity, message, location = {}) {
+    return { code, severity, message, ...location };
+}
+export function catalogErrors(diagnostics) {
+    return sortCatalogDiagnostics(diagnostics)
+        .filter((entry) => entry.severity === "error")
+        .map((entry) => entry.message);
+}
+export function catalogWarnings(diagnostics) {
+    return sortCatalogDiagnostics(diagnostics)
+        .filter((entry) => entry.severity === "warning")
+        .map((entry) => entry.message);
+}
+export function compareCatalogDiagnostics(left, right) {
+    return (DIAGNOSTIC_SEVERITY_ORDER[left.severity] -
+        DIAGNOSTIC_SEVERITY_ORDER[right.severity] ||
+        compareUtf8Paths(diagnosticPath(left), diagnosticPath(right)) ||
+        (left.line ?? 0) - (right.line ?? 0) ||
+        compareUtf8Paths(left.code, right.code) ||
+        compareUtf8Paths(left.message, right.message));
+}
+export function sortCatalogDiagnostics(diagnostics) {
+    return [...diagnostics].sort(compareCatalogDiagnostics);
+}
+function diagnosticPath(diagnostic) {
+    // Diagnostics without a path sort first. Path comparison is slash-normalized
+    // and byte-defined; it never depends on the process locale or ICU build.
+    return diagnostic.path ? normalizeContextPath(diagnostic.path) : "";
+}

package/dist/lib/context-catalog/catalog-discovery.d.ts

@@ -0,0 +1,7 @@
+import type { CatalogFile } from "./catalog-types.js";
+import type { CatalogDiagnostic } from "./catalog-types.js";
+export interface CatalogDiscoveryResult {
+    files: CatalogFile[];
+    diagnostics: CatalogDiagnostic[];
+}
+export declare function discoverContextMarkdownFiles(projectRoot: string, fileOverrides?: ReadonlyMap<string, Uint8Array | null>): Promise<CatalogDiscoveryResult>;

package/dist/lib/context-catalog/catalog-discovery.js

@@ -0,0 +1,81 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { listFiles } from "../fs.js";
+import { compareUtf8Paths, normalizeContextPath, normalizeContextPathSpelling, portableContextPathCaseKey, repositoryRelativePathSpelling, } from "./catalog-paths.js";
+import { catalogDiagnostic } from "./catalog-diagnostics.js";
+export async function discoverContextMarkdownFiles(projectRoot, fileOverrides = new Map()) {
+    const contextRoot = path.join(projectRoot, "project_context");
+    const files = (await listFiles(contextRoot))
+        .filter((file) => file.toLowerCase().endsWith(".md"))
+        .map((absolutePath) => ({
+        absolutePath,
+        physicalRelative: repositoryRelativePathSpelling(projectRoot, absolutePath),
+    }))
+        .sort((left, right) => compareUtf8Paths(left.physicalRelative, right.physicalRelative));
+    const diagnostics = [];
+    const result = new Map();
+    const physicalSpellings = new Map();
+    for (const { absolutePath, physicalRelative } of files) {
+        const relative = normalizeContextPath(physicalRelative);
+        const spellings = physicalSpellings.get(relative) ?? [];
+        spellings.push(physicalRelative);
+        physicalSpellings.set(relative, spellings);
+        if (result.has(relative))
+            continue;
+        const metadata = await lstat(absolutePath);
+        result.set(relative, {
+            path: relative,
+            physical_path: physicalRelative,
+            absolute_path: absolutePath,
+            bytes: metadata.size,
+        });
+    }
+    for (const [relative, spellings] of physicalSpellings) {
+        const unique = [...new Set(spellings)].sort(compareUtf8Paths);
+        if (unique.length < 2)
+            continue;
+        diagnostics.push(catalogDiagnostic("context_path_unicode_collision", "error", `Context files ${unique.join(", ")} normalize to the same NFC repository path ${relative}`, { path: relative }));
+    }
+    for (const [relativeInput, bytes] of fileOverrides) {
+        const relative = normalizeContextPath(relativeInput);
+        if (!relative.startsWith("project_context/") ||
+            !relative.toLowerCase().endsWith(".md"))
+            continue;
+        if (bytes === null)
+            result.delete(relative);
+        else {
+            const existing = result.get(relative);
+            if (existing) {
+                result.set(relative, { ...existing, bytes: bytes.byteLength });
+                continue;
+            }
+            const physicalPath = normalizeContextPathSpelling(relativeInput);
+            result.set(relative, {
+                path: relative,
+                physical_path: physicalPath,
+                absolute_path: path.join(projectRoot, ...physicalPath.split("/")),
+                bytes: bytes.byteLength,
+            });
+        }
+    }
+    addContextCaseCollisionDiagnostics(diagnostics, result.keys());
+    return {
+        files: [...result.values()].sort((left, right) => compareUtf8Paths(left.path, right.path)),
+        diagnostics,
+    };
+}
+function addContextCaseCollisionDiagnostics(diagnostics, paths) {
+    const folded = new Map();
+    for (const contextPath of paths) {
+        const key = portableContextPathCaseKey(contextPath);
+        const values = folded.get(key) ?? [];
+        values.push(contextPath);
+        folded.set(key, values);
+    }
+    for (const values of folded.values()) {
+        const unique = [...new Set(values)].sort(compareUtf8Paths);
+        if (unique.length < 2)
+            continue;
+        diagnostics.push(catalogDiagnostic("context_path_case_collision", "error", `Context files ${unique.join(", ")} collide on a case-insensitive filesystem`, { path: unique[0] }));
+    }
+}

package/dist/lib/context-catalog/catalog-load.d.ts

@@ -0,0 +1,8 @@
+import type { ContextCatalog } from "./catalog-types.js";
+export interface LoadContextCatalogOptions {
+    discover_files?: boolean;
+    validate_manifest?: boolean;
+    file_overrides?: ReadonlyMap<string, Uint8Array | null>;
+    directory_overrides?: ReadonlySet<string>;
+}
+export declare function loadContextCatalog(projectRootInput: string, options?: LoadContextCatalogOptions): Promise<ContextCatalog>;

package/dist/lib/context-catalog/catalog-load.js

@@ -0,0 +1,205 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { CONTEXT_MANIFEST_PATH } from "../context-manifest.js";
+import { parseContextManifest } from "../context-manifest-schema.js";
+import { pathExists } from "../fs.js";
+import { rawSchemaVersion } from "../schema-guard.js";
+import { selectDefaultContextPaths } from "./catalog-default-footprint.js";
+import { catalogDiagnostic, sortCatalogDiagnostics, } from "./catalog-diagnostics.js";
+import { discoverContextMarkdownFiles } from "./catalog-discovery.js";
+import { compareUtf8Paths, normalizeContextPath, normalizeContextPathSpelling, sortedContextMap, } from "./catalog-paths.js";
+import { validateCatalogManifest } from "./catalog-validation.js";
+export async function loadContextCatalog(projectRootInput, options = {}) {
+    const projectRoot = path.resolve(projectRootInput);
+    const manifestPath = CONTEXT_MANIFEST_PATH;
+    const absoluteManifestPath = path.join(projectRoot, ...manifestPath.split("/"));
+    const diagnostics = [];
+    const normalizedOverrides = normalizeFileOverrides(options.file_overrides);
+    const fileOverrides = normalizedOverrides.values;
+    diagnostics.push(...normalizedOverrides.diagnostics);
+    const directoryOverrides = normalizeDirectoryOverrides(options.directory_overrides);
+    const discovery = options.discover_files === false
+        ? { files: [], diagnostics: [] }
+        : await discoverContextMarkdownFiles(projectRoot, fileOverrides);
+    const contextFiles = discovery.files;
+    diagnostics.push(...discovery.diagnostics);
+    const withoutCoreFiles = contextFiles.filter((entry) => entry.path !== "project_context/global.md" &&
+        entry.path !== "project_context/architecture.md");
+    const manifestOverride = fileOverrides.has(manifestPath)
+        ? fileOverrides.get(manifestPath)
+        : undefined;
+    if (manifestOverride === null ||
+        (manifestOverride === undefined &&
+            !(await pathExists(absoluteManifestPath)))) {
+        diagnostics.push(catalogDiagnostic("context_manifest_missing", "error", "project_context/context.toml is missing", { path: manifestPath }));
+        addUnregisteredDiagnostics(diagnostics, withoutCoreFiles);
+        return {
+            project_root: projectRoot,
+            manifest_path: manifestPath,
+            areas: [],
+            registered_contexts: [],
+            context_files: contextFiles,
+            unregistered_context_files: withoutCoreFiles,
+            default_footprint: new Map(),
+            roles_by_path: new Map(),
+            read_policies_by_path: new Map(),
+            diagnostics: sortCatalogDiagnostics(diagnostics),
+        };
+    }
+    const manifestContent = manifestOverride === undefined
+        ? await readFile(absoluteManifestPath, "utf8")
+        : Buffer.from(manifestOverride).toString("utf8");
+    const parsed = parseContextManifest(manifestContent, manifestPath);
+    diagnostics.push(...parsed.errors.map((message) => catalogDiagnostic("context_manifest_parse", "error", message, {
+        path: manifestPath,
+    })));
+    if (!parsed.manifest) {
+        addUnregisteredDiagnostics(diagnostics, withoutCoreFiles);
+        return {
+            project_root: projectRoot,
+            manifest_path: manifestPath,
+            manifest_content: manifestContent,
+            areas: [],
+            registered_contexts: [],
+            context_files: contextFiles,
+            unregistered_context_files: withoutCoreFiles,
+            default_footprint: new Map(),
+            roles_by_path: new Map(),
+            read_policies_by_path: new Map(),
+            diagnostics: sortCatalogDiagnostics(diagnostics),
+        };
+    }
+    const validation = options.validate_manifest === false
+        ? {
+            registered_contexts: [],
+            roles_by_path: new Map(),
+            read_policies_by_path: new Map(),
+            diagnostics: [],
+        }
+        : await validateCatalogManifest(projectRoot, parsed.manifest, fileOverrides, directoryOverrides, contextFiles);
+    diagnostics.push(...validation.diagnostics);
+    const registeredPaths = new Set([
+        "project_context/global.md",
+        "project_context/architecture.md",
+        ...parsed.manifest.areas.map((area) => normalizeContextPath(area.context)),
+        ...parsed.manifest.contexts.map((context) => normalizeContextPath(context.path)),
+    ]);
+    const unregisteredContextFiles = contextFiles.filter((entry) => !registeredPaths.has(entry.path));
+    addUnregisteredDiagnostics(diagnostics, unregisteredContextFiles);
+    let defaults = parsed.manifest;
+    try {
+        const version = await rawSchemaVersion(projectRoot);
+        if (version !== undefined && Number(version) < 5)
+            defaults = {
+                ...defaults,
+                default_files: [
+                    ...new Set([
+                        ...(defaults.default_files ?? []),
+                        "project_context/architecture.md",
+                    ]),
+                ],
+            };
+    }
+    catch (error) {
+        diagnostics.push(catalogDiagnostic("config_invalid", "error", String(error)));
+    }
+    return {
+        project_root: projectRoot,
+        manifest_path: manifestPath,
+        manifest_content: manifestContent,
+        manifest: parsed.manifest,
+        areas: projectAreas(parsed.manifest.areas),
+        registered_contexts: projectRegisteredContexts(validation.registered_contexts),
+        context_files: contextFiles,
+        unregistered_context_files: unregisteredContextFiles,
+        default_footprint: selectDefaultContextPaths(defaults),
+        roles_by_path: sortedContextMap(validation.roles_by_path),
+        read_policies_by_path: sortedContextMap(validation.read_policies_by_path),
+        diagnostics: sortCatalogDiagnostics(diagnostics),
+    };
+}
+function normalizeDirectoryOverrides(values) {
+    if (!values)
+        return new Set();
+    return new Set([...values].map(normalizeContextPath));
+}
+function normalizeFileOverrides(values) {
+    if (!values)
+        return { values: new Map(), diagnostics: [] };
+    const normalized = new Map();
+    const diagnostics = [];
+    const spellings = new Map();
+    const entries = [...values].sort(([left], [right]) => compareUtf8Paths(normalizeContextPathSpelling(left), normalizeContextPathSpelling(right)));
+    for (const [file, bytes] of entries) {
+        const relative = normalizeContextPath(file);
+        const valuesForPath = spellings.get(relative) ?? [];
+        valuesForPath.push(normalizeContextPathSpelling(file));
+        spellings.set(relative, valuesForPath);
+        if (!normalized.has(relative))
+            normalized.set(relative, bytes === null ? null : Buffer.from(bytes));
+    }
+    for (const [relative, rawSpellings] of spellings) {
+        const unique = [...new Set(rawSpellings)].sort(compareUtf8Paths);
+        if (unique.length < 2)
+            continue;
+        diagnostics.push(catalogDiagnostic("context_override_path_unicode_collision", "error", `Context file overrides ${unique.join(", ")} normalize to the same NFC repository path ${relative}`, { path: relative }));
+    }
+    return { values: normalized, diagnostics };
+}
+function addUnregisteredDiagnostics(diagnostics, files) {
+    for (const file of files) {
+        diagnostics.push(catalogDiagnostic("context_file_unregistered", "warning", `${file.path} is an unregistered Context Markdown file; add it to project_context/context.toml or move it out of project_context/**`, { path: file.path }));
+    }
+}
+function projectAreas(areas) {
+    return areas
+        .map((area) => ({
+        ...area,
+        id: area.id.normalize("NFC"),
+        root: normalizeContextPath(area.root),
+        context: normalizeContextPath(area.context),
+        forbidden_runtime_dependencies: [...area.forbidden_runtime_dependencies]
+            .map((entry) => entry.normalize("NFC"))
+            .sort(compareUtf8Paths),
+    }))
+        .sort((left, right) => compareUtf8Paths(left.root, right.root) ||
+        compareUtf8Paths(left.id, right.id) ||
+        compareUtf8Paths(left.context, right.context) ||
+        left.line - right.line);
+}
+function projectRegisteredContexts(entries) {
+    return entries
+        .map((entry) => ({
+        ...entry,
+        path: normalizeContextPath(entry.path),
+        area: entry.area
+            ? {
+                ...entry.area,
+                id: entry.area.id.normalize("NFC"),
+                root: normalizeContextPath(entry.area.root),
+                context: normalizeContextPath(entry.area.context),
+                forbidden_runtime_dependencies: [
+                    ...entry.area.forbidden_runtime_dependencies,
+                ]
+                    .map((value) => value.normalize("NFC"))
+                    .sort(compareUtf8Paths),
+            }
+            : undefined,
+        context: entry.context
+            ? {
+                ...entry.context,
+                path: normalizeContextPath(entry.context.path),
+                triggers: [...entry.context.triggers]
+                    .map((value) => value.normalize("NFC"))
+                    .sort(compareUtf8Paths),
+                default_children: [...entry.context.default_children]
+                    .map(normalizeContextPath)
+                    .sort(compareUtf8Paths),
+            }
+            : undefined,
+    }))
+        .sort((left, right) => compareUtf8Paths(left.path, right.path) ||
+        compareUtf8Paths(left.source, right.source) ||
+        compareUtf8Paths(left.role, right.role) ||
+        left.line - right.line);
+}

package/dist/lib/context-catalog/catalog-path-validation.d.ts

@@ -0,0 +1,7 @@
+import type { CatalogFile } from "./catalog-types.js";
+export type CatalogPathErrorReporter = (code: string, message: string, location?: {
+    path?: string;
+    line?: number;
+}) => void;
+export declare function validateCatalogManifestPath(projectRoot: string, rawPath: string, allowedRoot: string, source: string, allowFile: boolean, addError: CatalogPathErrorReporter, fileOverrides?: ReadonlyMap<string, Uint8Array | null>, directoryOverrides?: ReadonlySet<string>, filesByPath?: ReadonlyMap<string, CatalogFile>): Promise<boolean>;
+export declare function looksLikeContextExportArtifact(value: string): boolean;

package/dist/lib/context-catalog/catalog-path-validation.js

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+import { pathExists } from "../fs.js";
+import { assertSafeRepositoryFilePath } from "../repository-path-safety.js";
+import { assertCatalogStagedFilePath } from "./catalog-staged-path-safety.js";
+import { isPathWithin, normalizeContextPath } from "./catalog-paths.js";
+const EXPORT_ARTIFACT_NAME_PATTERNS = [
+    /full-project-context/iu,
+    /当前项目context/iu,
+    /当前项目代码实现(?:context)?/iu,
+    /code-level-implementation/iu,
+    /project-overview/iu,
+    /context-bundle/iu,
+    /context-summary/iu,
+    /context-export/iu,
+];
+export async function validateCatalogManifestPath(projectRoot, rawPath, allowedRoot, source, allowFile, addError, fileOverrides = new Map(), directoryOverrides = new Set(), filesByPath = new Map()) {
+    if (path.isAbsolute(rawPath) ||
+        rawPath.replace(/\\/gu, "/").split("/").includes("..")) {
+        addError("manifest_path_not_relative", `project_context/context.toml ${source} path must be relative and must not contain '..': ${rawPath}`);
+        return false;
+    }
+    const target = path.resolve(projectRoot, rawPath);
+    if (!isPathWithin(allowedRoot, target)) {
+        addError("manifest_path_outside_allowed_root", `project_context/context.toml ${source} escapes its allowed root: ${rawPath}`);
+        return false;
+    }
+    const relative = normalizeContextPath(path.relative(projectRoot, target));
+    const physicalRelative = filesByPath.get(relative)?.physical_path ?? relative;
+    const physicalTarget = path.resolve(projectRoot, physicalRelative);
+    if (allowFile && fileOverrides.has(relative)) {
+        if (fileOverrides.get(relative) === null) {
+            addError("manifest_path_missing", `project_context/context.toml references missing context file: ${relative}`);
+            return false;
+        }
+        try {
+            await assertCatalogStagedFilePath(projectRoot, physicalRelative, directoryOverrides, `catalog_staged_file:${source}`);
+            return true;
+        }
+        catch (error) {
+            addError("manifest_path_staged_unsafe", `project_context/context.toml ${source} staged path is unsafe: ${message(error)}`);
+            return false;
+        }
+    }
+    const existingTarget = allowFile ? physicalTarget : target;
+    if (!(await pathExists(existingTarget))) {
+        addError("manifest_path_missing", `project_context/context.toml references missing ${allowFile ? "context file" : "area root"}: ${normalizeContextPath(rawPath)}`);
+        return false;
+    }
+    const realAllowedRoot = await realpath(allowedRoot);
+    const realTarget = await realpath(existingTarget);
+    if (!isPathWithin(realAllowedRoot, realTarget)) {
+        addError("manifest_path_symlink_escape", `project_context/context.toml ${source} resolves through a symbolic link outside its allowed root: ${rawPath}`);
+        return false;
+    }
+    if (allowFile) {
+        try {
+            await assertSafeRepositoryFilePath(projectRoot, physicalRelative, `catalog_file:${source}`);
+        }
+        catch (error) {
+            addError("manifest_path_unsafe_file", `Unsafe declared Context file ${rawPath}: ${message(error)}`);
+            return false;
+        }
+    }
+    return true;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function looksLikeContextExportArtifact(value) {
+    return EXPORT_ARTIFACT_NAME_PATTERNS.some((pattern) => pattern.test(value));
+}

package/dist/lib/context-catalog/catalog-paths.d.ts

@@ -0,0 +1,11 @@
+import type { CatalogFile, ContextCatalog } from "./catalog-types.js";
+export declare function normalizeContextPath(value: string): string;
+export declare function normalizeContextPathSpelling(value: string): string;
+export declare function resolveProjectPath(projectRoot: string, repositoryRelativePath: string): string;
+export declare function repositoryRelativePath(projectRoot: string, absolutePath: string): string;
+export declare function repositoryRelativePathSpelling(projectRoot: string, absolutePath: string): string;
+export declare function resolveCatalogFile(catalog: Pick<ContextCatalog, "context_files">, repositoryRelativePath: string): CatalogFile | undefined;
+export declare function isPathWithin(root: string, target: string): boolean;
+export declare function compareUtf8Paths(left: string, right: string): number;
+export declare function portableContextPathCaseKey(value: string): string;
+export declare function sortedContextMap<T>(values: Iterable<readonly [string, T]>): Map<string, T>;

package/dist/lib/context-catalog/catalog-paths.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+export function normalizeContextPath(value) {
+    return normalizeContextPathSpelling(value).normalize("NFC");
+}
+// Preserve the physical spelling when discovery needs to diagnose two paths
+// that collapse to the same public NFC key. Catalog consumers should otherwise
+// use normalizeContextPath().
+export function normalizeContextPathSpelling(value) {
+    return value.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}
+export function resolveProjectPath(projectRoot, repositoryRelativePath) {
+    return path.resolve(projectRoot, ...normalizeContextPath(repositoryRelativePath).split("/"));
+}
+export function repositoryRelativePath(projectRoot, absolutePath) {
+    return normalizeContextPath(path.relative(projectRoot, absolutePath));
+}
+export function repositoryRelativePathSpelling(projectRoot, absolutePath) {
+    return normalizeContextPathSpelling(path.relative(projectRoot, absolutePath));
+}
+export function resolveCatalogFile(catalog, repositoryRelativePath) {
+    const key = normalizeContextPath(repositoryRelativePath);
+    return catalog.context_files.find((file) => file.path === key);
+}
+export function isPathWithin(root, target) {
+    const relative = path.relative(root, target);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+export function compareUtf8Paths(left, right) {
+    return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+export function portableContextPathCaseKey(value) {
+    // ECMAScript default case conversion is locale-independent. This key is a
+    // portability collision detector, not a filesystem lookup or ontology.
+    return normalizeContextPath(value).toLowerCase();
+}
+export function sortedContextMap(values) {
+    return new Map([...values].sort(([left], [right]) => compareUtf8Paths(left, right)));
+}