project-tiny-context-harness 0.8.16 → 0.11.0

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

@@ -0,0 +1,148 @@
+import path from "node:path";
+import { CONTEXT_LEGACY_READ_POLICY_SET, isContextReadPolicy, normalizeContextRole, } from "./catalog-portable-contract.js";
+import { catalogDiagnostic } from "./catalog-diagnostics.js";
+import { compareUtf8Paths, normalizeContextPath, normalizeContextPathSpelling, portableContextPathCaseKey, } from "./catalog-paths.js";
+import { looksLikeContextExportArtifact, validateCatalogManifestPath, } from "./catalog-path-validation.js";
+export async function validateCatalogManifest(projectRoot, manifest, fileOverrides = new Map(), directoryOverrides = new Set(), contextFiles = []) {
+    const diagnostics = [];
+    const registeredContexts = [];
+    const rolesByPath = new Map();
+    const readPoliciesByPath = new Map();
+    const addError = (code, message, location = {}) => {
+        diagnostics.push(catalogDiagnostic(code, "error", message, location));
+    };
+    const addWarning = (code, message, location = {}) => {
+        diagnostics.push(catalogDiagnostic(code, "warning", message, location));
+    };
+    if (manifest.areas.length === 0) {
+        addError("manifest_area_missing", "project_context/context.toml must declare at least one [[areas]] entry");
+    }
+    const areaIds = new Map();
+    const registeredPaths = new Set();
+    const filesByPath = new Map(contextFiles.map((file) => [file.path, file]));
+    const registeredPathSpellings = new Map();
+    const registeredPathCases = new Map();
+    const defaultAreas = manifest.areas.filter((area) => area.default);
+    if (manifest.areas.length > 0 && defaultAreas.length !== 1) {
+        addError("manifest_default_area_count", `project_context/context.toml must mark exactly one [[areas]] entry with default = true; found ${defaultAreas.length}`);
+    }
+    for (const area of manifest.areas) {
+        const canonicalAreaId = area.id.normalize("NFC");
+        const previousAreaId = areaIds.get(canonicalAreaId);
+        if (previousAreaId !== undefined) {
+            if (previousAreaId === area.id)
+                addError("manifest_area_id_duplicate", `project_context/context.toml has duplicate area id: ${area.id}`, { line: area.line });
+            else {
+                const aliases = [previousAreaId, area.id].sort(compareUtf8Paths);
+                addError("manifest_area_id_unicode_collision", `project_context/context.toml area ids ${aliases.join(", ")} normalize to the same NFC id ${canonicalAreaId}`, { line: area.line });
+            }
+        }
+        else
+            areaIds.set(canonicalAreaId, area.id);
+        await validateCatalogManifestPath(projectRoot, area.root, projectRoot, `area ${area.id} root`, false, addError, fileOverrides, directoryOverrides, filesByPath);
+        const relative = normalizeContextPath(area.context);
+        reportRegisteredPathCollision(relative, area.context, area.line, registeredPathSpellings, registeredPathCases, addError);
+        registeredPaths.add(relative);
+        await addRegisteredContext(projectRoot, registeredContexts, rolesByPath, readPoliciesByPath, {
+            source: "area",
+            rawPath: area.context,
+            role: "area",
+            line: area.line,
+            sourceLabel: `area ${area.id}`,
+            area,
+        }, addError, fileOverrides, directoryOverrides, filesByPath);
+    }
+    for (const context of manifest.contexts) {
+        const relative = normalizeContextPath(context.path);
+        reportRegisteredPathCollision(relative, context.path, context.line, registeredPathSpellings, registeredPathCases, addError);
+        registeredPaths.add(relative);
+        if (context.read_policy && !isContextReadPolicy(context.read_policy)) {
+            addError("manifest_read_policy_unsupported", `project_context/context.toml line ${context.line} has unsupported read_policy: ${context.read_policy}`, { path: relative, line: context.line });
+        }
+        if (context.read_policy &&
+            CONTEXT_LEGACY_READ_POLICY_SET.has(context.read_policy)) {
+            addWarning("manifest_read_policy_legacy", `project_context/context.toml line ${context.line} uses legacy read_policy ${context.read_policy}; Schema v4 preserves its current selection behavior and migration must be explicit`, { path: relative, line: context.line });
+        }
+        const role = normalizeContextRole(context.role);
+        if (!role) {
+            addError("manifest_context_role_unsupported", `project_context/context.toml line ${context.line} has unsupported context role: ${context.role}`, { path: relative, line: context.line });
+            continue;
+        }
+        await addRegisteredContext(projectRoot, registeredContexts, rolesByPath, readPoliciesByPath, {
+            source: "context",
+            rawPath: context.path,
+            role,
+            readPolicy: context.read_policy,
+            line: context.line,
+            sourceLabel: `context ${context.path}`,
+            context,
+        }, addError, fileOverrides, directoryOverrides, filesByPath);
+    }
+    const contextsByPath = new Map(manifest.contexts.map((entry) => [normalizeContextPath(entry.path), entry]));
+    for (const context of manifest.contexts) {
+        for (const child of context.default_children) {
+            const normalizedChild = normalizeContextPath(child);
+            if (!registeredPaths.has(normalizedChild)) {
+                addError("manifest_default_child_unregistered", `project_context/context.toml line ${context.line} default_children references unregistered Context path: ${child}`, { path: normalizedChild, line: context.line });
+                continue;
+            }
+            if (contextsByPath.get(normalizedChild)?.read_policy === "never-default") {
+                addWarning("manifest_never_default_child_conflict", `project_context/context.toml line ${context.line} default_children selects ${normalizedChild} even though its current read_policy is never-default; Schema v4 preserves this behavior and a future migration must remove the edge or change the policy explicitly`, { path: normalizedChild, line: context.line });
+            }
+        }
+    }
+    return {
+        registered_contexts: registeredContexts,
+        roles_by_path: rolesByPath,
+        read_policies_by_path: readPoliciesByPath,
+        diagnostics,
+    };
+}
+function reportRegisteredPathCollision(relative, rawPath, line, spellings, cases, addError) {
+    const rawSpelling = normalizeContextPathSpelling(rawPath);
+    const previous = spellings.get(relative);
+    if (previous === undefined) {
+        spellings.set(relative, rawSpelling);
+    }
+    else if (previous === rawSpelling) {
+        addError("manifest_context_path_duplicate", `project_context/context.toml has duplicate Context path: ${relative}`, { path: relative, line });
+    }
+    else {
+        const aliases = [previous, rawSpelling].sort(compareUtf8Paths);
+        addError("manifest_context_path_unicode_collision", `project_context/context.toml Context paths ${aliases.join(", ")} normalize to the same NFC repository path ${relative}`, { path: relative, line });
+    }
+    const caseKey = portableContextPathCaseKey(relative);
+    const previousCase = cases.get(caseKey);
+    if (previousCase === undefined)
+        cases.set(caseKey, relative);
+    else if (previousCase !== relative) {
+        const aliases = [previousCase, relative].sort(compareUtf8Paths);
+        addError("manifest_context_path_case_collision", `project_context/context.toml Context paths ${aliases.join(", ")} collide on a case-insensitive filesystem`, { path: aliases[0], line });
+    }
+}
+async function addRegisteredContext(projectRoot, registeredContexts, rolesByPath, readPoliciesByPath, input, addError, fileOverrides, directoryOverrides, filesByPath) {
+    const relative = normalizeContextPath(input.rawPath);
+    if (looksLikeContextExportArtifact(relative)) {
+        addError("manifest_export_artifact_forbidden", `project_context/context.toml ${input.sourceLabel} must not reference temporary export artifact ${input.rawPath}; export artifacts belong in tmp/ty-context/context-exports/** and must not be registered as Context graph nodes or implementation-index`, { path: relative, line: input.line });
+        return;
+    }
+    if (!relative.startsWith("project_context/") || !relative.endsWith(".md")) {
+        addError("manifest_context_path_invalid", `project_context/context.toml ${input.sourceLabel} must reference a markdown file under project_context/: ${input.rawPath}`, { path: relative, line: input.line });
+        return;
+    }
+    if (!(await validateCatalogManifestPath(projectRoot, input.rawPath, path.join(projectRoot, "project_context"), input.sourceLabel, true, addError, fileOverrides, directoryOverrides, filesByPath))) {
+        return;
+    }
+    rolesByPath.set(relative, input.role);
+    if (input.readPolicy)
+        readPoliciesByPath.set(relative, input.readPolicy);
+    registeredContexts.push({
+        source: input.source,
+        path: relative,
+        role: input.role,
+        read_policy: input.readPolicy,
+        line: input.line,
+        area: input.area,
+        context: input.context,
+    });
+}

package/dist/lib/context-create/context-create-path.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeContextCreatePath(value: string): string;
+export declare function normalizeContextFilePath(value: string, command: string): string;

package/dist/lib/context-create/context-create-path.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+const PORTABLE_SEGMENT_FORBIDDEN = /[<>:"|?*\u0000-\u001f]/u;
+const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/iu;
+export function normalizeContextCreatePath(value) {
+    return normalizeContextFilePath(value, "context create");
+}
+export function normalizeContextFilePath(value, command) {
+    if (!value || path.isAbsolute(value) || /^[A-Za-z]:/u.test(value))
+        invalid(value, command);
+    const normalized = value.replace(/\\/gu, "/").replace(/^\.\//u, "");
+    const segments = normalized.split("/");
+    if (segments.length < 2 ||
+        segments[0] !== "project_context" ||
+        segments.some(invalidSegment) ||
+        !segments.at(-1)?.toLowerCase().endsWith(".md"))
+        invalid(value, command);
+    return normalized;
+}
+function invalidSegment(segment) {
+    return (!segment ||
+        segment === "." ||
+        segment === ".." ||
+        PORTABLE_SEGMENT_FORBIDDEN.test(segment) ||
+        /[. ]$/u.test(segment) ||
+        WINDOWS_RESERVED.test(segment));
+}
+function invalid(value, command) {
+    throw new CliCommandError(CLI_EXIT_CODES.arguments, `${command} path must be a portable Markdown path below project_context/: ${value}`);
+}

package/dist/lib/context-create/context-create-template.d.ts

@@ -0,0 +1,2 @@
+import type { ContextRole } from "../context-catalog/catalog-portable-contract.js";
+export declare function renderContextCreateScaffold(contextPath: string, role: ContextRole): string;

package/dist/lib/context-create/context-create-template.js

@@ -0,0 +1,95 @@
+const ROLE_SECTIONS = {
+    global: [
+        "Project Goal",
+        "Boundaries",
+        "Durable Context",
+        "Verification Entry Points",
+    ],
+    architecture: [
+        "System Boundary",
+        "Component Map",
+        "Data / Control Flow",
+        "Constraints And Tradeoffs",
+    ],
+    area: ["Responsibility", "Durable Facts", "Boundaries", "Code Entry Points"],
+    domain: [
+        "Responsibility",
+        "Durable Domain Facts",
+        "Boundaries",
+        "Code Entry Points",
+    ],
+    subdomain: [
+        "Responsibility",
+        "Durable Subdomain Facts",
+        "Parent Boundary",
+        "Code Entry Points",
+    ],
+    foundation: [
+        "Foundation Responsibility",
+        "Shared Rules",
+        "Consumers",
+        "Change Boundaries",
+    ],
+    archive: [
+        "Archive Scope",
+        "Historical Context",
+        "Current Applicability",
+        "Successor Owners",
+    ],
+    contract: [
+        "Contract Scope",
+        "Inputs",
+        "Outputs",
+        "Compatibility And Constraints",
+    ],
+    verification: [
+        "Owner",
+        "Verification Paths",
+        "Required Preparation",
+        "Expected Signals",
+        "Forbidden Evidence",
+    ],
+    deployment: [
+        "Owner",
+        "Runtime Topology",
+        "Deployment Paths",
+        "Recovery",
+        "Forbidden Evidence",
+    ],
+    "implementation-index": [
+        "Responsibility",
+        "Repository Entry Points",
+        "Change Routing",
+        "Boundaries",
+    ],
+    "decision-rationale": [
+        "Decision",
+        "Reason",
+        "Alternatives",
+        "Revisit Trigger",
+    ],
+};
+export function renderContextCreateScaffold(contextPath, role) {
+    const title = titleFromPath(contextPath);
+    const lines = [
+        `# ${roleLabel(role)} Context: ${title}`,
+        "",
+        `<!-- ty-context-scaffold role=${role} registration=unregistered -->`,
+        "",
+    ];
+    for (const section of ROLE_SECTIONS[role])
+        lines.push(`## ${section}`, "", "- TODO", "");
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+function titleFromPath(contextPath) {
+    const filename = contextPath.split("/").at(-1) ?? "Context";
+    const stem = filename.replace(/\.md$/iu, "");
+    const spaced = stem.replace(/[-_]+/gu, " ").trim();
+    return spaced || "Context";
+}
+function roleLabel(role) {
+    return role
+        .split("-")
+        .map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`)
+        .join(" ");
+}

package/dist/lib/context-create/context-create-types.d.ts

@@ -0,0 +1,28 @@
+import type { ContextRole } from "../context-catalog/catalog-portable-contract.js";
+export interface ContextCreateInput {
+    project_root: string;
+    context_path: string;
+    role: string;
+}
+export interface ContextFootprintSnapshot {
+    path_count: number;
+    bytes: number;
+}
+export interface ContextCreateResult {
+    schema_version: 1;
+    path: string;
+    role: ContextRole;
+    created: true;
+    registration: "unregistered";
+    manifest_modified: false;
+    bytes: number;
+    default_footprint: {
+        changed: false;
+        before: ContextFootprintSnapshot;
+        after: ContextFootprintSnapshot;
+        added: [];
+        removed: [];
+        reason: string;
+    };
+    next_steps: string[];
+}

package/dist/lib/context-create/context-create-types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/context-create/context-create-write.d.ts

@@ -0,0 +1 @@
+export declare function publishContextScaffold(repository: string, relativePath: string, bytes: Uint8Array): Promise<void>;

package/dist/lib/context-create/context-create-write.js

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import { link, open, readFile, unlink } from "node:fs/promises";
+import path from "node:path";
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { assertSafeRepositoryFilePath, ensureSafeRepositoryDirectory, } from "../repository-path-safety.js";
+export async function publishContextScaffold(repository, relativePath, bytes) {
+    const parent = path.posix.dirname(relativePath);
+    const directory = await ensureSafeRepositoryDirectory(repository, parent, "context_create_parent").catch(asIoFailure);
+    const destination = await assertSafeRepositoryFilePath(repository, relativePath, "context_create_target", { destinationMayBeAbsent: true }).catch(asIoFailure);
+    if (destination.status)
+        collision(relativePath);
+    const temporary = path.join(directory.absolute, `.${path.basename(destination.absolute)}.ty-context-create-${randomUUID()}.tmp`);
+    let temporaryExists = false;
+    let published = false;
+    try {
+        const handle = await open(temporary, "wx", 0o666);
+        temporaryExists = true;
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        const staged = await readFile(temporary);
+        if (!Buffer.from(bytes).equals(staged))
+            throw new Error("context_create_temporary_readback_mismatch");
+        await assertDestinationAbsent(repository, relativePath);
+        try {
+            await link(temporary, destination.absolute);
+            published = true;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                collision(relativePath);
+            throw error;
+        }
+        await unlink(temporary);
+        temporaryExists = false;
+        const finalBytes = await readFile(destination.absolute);
+        if (!Buffer.from(bytes).equals(finalBytes))
+            throw new Error("context_create_final_readback_mismatch");
+    }
+    catch (error) {
+        const cleanup = temporaryExists
+            ? await removeTemporary(temporary)
+            : undefined;
+        if (cleanup)
+            throw new AggregateError([error, cleanup], published
+                ? `context create published ${relativePath}, but temporary cleanup failed`
+                : `context create failed and temporary cleanup failed for ${relativePath}`);
+        if (error instanceof CliCommandError)
+            throw error;
+        throw new CliCommandError(CLI_EXIT_CODES.io, published
+            ? `context create published ${relativePath}, but final verification failed: ${message(error)}`
+            : `unable to create Context scaffold ${relativePath}: ${message(error)}`, { cause: error });
+    }
+}
+async function assertDestinationAbsent(repository, relativePath) {
+    const destination = await assertSafeRepositoryFilePath(repository, relativePath, "context_create_target", { destinationMayBeAbsent: true }).catch(asIoFailure);
+    if (destination.status)
+        collision(relativePath);
+}
+async function removeTemporary(temporary) {
+    try {
+        await unlink(temporary);
+        return undefined;
+    }
+    catch (error) {
+        return error;
+    }
+}
+function collision(relativePath) {
+    throw new CliCommandError(CLI_EXIT_CODES.io, `context create refuses to overwrite existing target: ${relativePath}`);
+}
+function asIoFailure(error) {
+    if (error instanceof CliCommandError)
+        throw error;
+    throw new CliCommandError(CLI_EXIT_CODES.io, message(error), {
+        cause: error,
+    });
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/context-create/context-create.d.ts

@@ -0,0 +1,2 @@
+import type { ContextCreateInput, ContextCreateResult } from "./context-create-types.js";
+export declare function createContextScaffold(input: ContextCreateInput): Promise<ContextCreateResult>;

package/dist/lib/context-create/context-create.js

@@ -0,0 +1,84 @@
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { loadContextCatalog } from "../context-catalog/catalog-load.js";
+import { normalizeContextPath } from "../context-catalog/catalog-paths.js";
+import { CONTEXT_ROLES, normalizeContextRole, } from "../context-catalog/catalog-portable-contract.js";
+import { normalizeContextCreatePath } from "./context-create-path.js";
+import { renderContextCreateScaffold } from "./context-create-template.js";
+import { publishContextScaffold } from "./context-create-write.js";
+export async function createContextScaffold(input) {
+    const contextPath = normalizeContextCreatePath(input.context_path);
+    const role = normalizeContextRole(input.role);
+    if (!role)
+        throw new CliCommandError(CLI_EXIT_CODES.arguments, `context create role must be one of: ${CONTEXT_ROLES.join(", ")}`);
+    const catalog = await loadCatalog(input.project_root);
+    assertUnregisteredTarget(catalog, contextPath);
+    const blocking = catalog.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (blocking.length > 0)
+        throw new CliCommandError(CLI_EXIT_CODES.catalog, `context create requires a valid Context Catalog: ${blocking
+            .map((entry) => entry.message)
+            .join("; ")}`);
+    const content = renderContextCreateScaffold(contextPath, role);
+    const bytes = Buffer.from(content, "utf8");
+    const footprint = contextFootprintSnapshot(catalog);
+    await publishContextScaffold(input.project_root, contextPath, bytes);
+    return {
+        schema_version: 1,
+        path: contextPath,
+        role,
+        created: true,
+        registration: "unregistered",
+        manifest_modified: false,
+        bytes: bytes.length,
+        default_footprint: {
+            changed: false,
+            before: footprint,
+            after: { ...footprint },
+            added: [],
+            removed: [],
+            reason: "unregistered scaffolds do not participate in the default footprint",
+        },
+        next_steps: [
+            "Replace every TODO with durable facts owned by this Context.",
+            `Inspect the unregistered scaffold with: ty-context context inspect ${contextPath}`,
+            "Register only after the file satisfies its Role recovery requirements; create never edits the Manifest.",
+        ],
+    };
+}
+async function loadCatalog(projectRoot) {
+    try {
+        return await loadContextCatalog(projectRoot);
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to load Context Catalog: ${message(error)}`, { cause: error });
+    }
+}
+function assertUnregisteredTarget(catalog, contextPath) {
+    const folded = contextPath.toLocaleLowerCase("en-US");
+    const registered = registeredPaths(catalog).find((candidate) => candidate.toLocaleLowerCase("en-US") === folded);
+    if (registered)
+        throw new CliCommandError(CLI_EXIT_CODES.catalog, `context create only creates unregistered scaffolds; Manifest already owns ${registered}`);
+    const existing = catalog.context_files.find((candidate) => candidate.path.toLocaleLowerCase("en-US") === folded);
+    if (existing)
+        throw new CliCommandError(CLI_EXIT_CODES.io, `context create refuses to overwrite existing target: ${existing.path}`);
+}
+function registeredPaths(catalog) {
+    return [
+        "project_context/global.md",
+        "project_context/architecture.md",
+        ...(catalog.manifest?.areas.map((entry) => entry.context) ?? []),
+        ...(catalog.manifest?.contexts.map((entry) => entry.path) ?? []),
+    ].map(normalizeContextPath);
+}
+function contextFootprintSnapshot(catalog) {
+    const files = new Map(catalog.context_files.map((entry) => [entry.path, entry.bytes]));
+    let bytes = 0;
+    for (const contextPath of catalog.default_footprint.keys())
+        bytes +=
+            contextPath === catalog.manifest_path
+                ? Buffer.byteLength(catalog.manifest_content ?? "", "utf8")
+                : (files.get(contextPath) ?? 0);
+    return { path_count: catalog.default_footprint.size, bytes };
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -1,7 +1,7 @@
-import { type ContextManifest } from "./context-manifest-schema.js";
+import { type DefaultContextSelectionReason } from "./context-catalog/catalog-default-footprint.js";
+export { selectDefaultContextPaths, type DefaultContextSelectionReason, } from "./context-catalog/catalog-default-footprint.js";
 export declare const DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES: number;
 export declare const DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES: number;
-export type DefaultContextSelectionReason = "core" | "default_area" | "default_role" | "default_child";
 export interface DefaultContextFileFootprint {
     path: string;
     bytes: number;
@@ -13,4 +13,3 @@ export interface DefaultContextFootprint {
     duplicate_groups: string[][];
 }
 export declare function inspectDefaultContextFootprint(projectRootInput: string): Promise<DefaultContextFootprint>;
-export declare function selectDefaultContextPaths(manifest: ContextManifest): Map<string, Set<DefaultContextSelectionReason>>;

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

@@ -1,22 +1,30 @@
 import { createHash } from "node:crypto";
 import { lstat, readFile } from "node:fs/promises";
 import path from "node:path";
-import { parseContextManifest, } from "./context-manifest-schema.js";
+import { loadContextCatalog } from "./context-catalog/catalog-load.js";
+import { compareUtf8Paths, normalizeContextPath, normalizeContextPathSpelling, resolveCatalogFile, } from "./context-catalog/catalog-paths.js";
+export { selectDefaultContextPaths, } from "./context-catalog/catalog-default-footprint.js";
 export const DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES = 64 * 1024;
 export const DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES = 16 * 1024;
 export async function inspectDefaultContextFootprint(projectRootInput) {
     const projectRoot = path.resolve(projectRootInput);
-    const manifestPath = "project_context/context.toml";
-    const manifestContent = await readFile(path.join(projectRoot, ...manifestPath.split("/")), "utf8");
-    const parsed = parseContextManifest(manifestContent, manifestPath);
-    if (!parsed.manifest || parsed.errors.length > 0) {
-        throw new Error(`context_manifest_invalid:${parsed.errors.join("|")}`);
+    const catalog = await loadContextCatalog(projectRoot, {
+        validate_manifest: false,
+    });
+    const parseErrors = catalog.diagnostics
+        .filter((entry) => entry.code === "context_manifest_parse" ||
+        entry.code === "context_manifest_missing")
+        .map((entry) => entry.message);
+    if (!catalog.manifest || parseErrors.length > 0) {
+        throw new Error(`context_manifest_invalid:${parseErrors.join("|")}`);
     }
-    const selected = selectDefaultContextPaths(parsed.manifest);
+    const selected = catalog.default_footprint;
     const files = [];
     const hashes = new Map();
-    for (const [relativePath, reasons] of [...selected.entries()].sort(([left], [right]) => left.localeCompare(right))) {
-        const absolutePath = resolveProjectFile(projectRoot, relativePath);
+    const physicalPaths = physicalDefaultPaths(catalog.manifest);
+    for (const [relativePath, reasons] of [...selected.entries()].sort(([left], [right]) => compareUtf8Paths(left, right))) {
+        const absolutePath = resolveCatalogFile(catalog, relativePath)?.absolute_path ??
+            resolveProjectFile(projectRoot, physicalPaths.get(relativePath) ?? relativePath);
         const metadata = await lstat(absolutePath);
         if (metadata.isSymbolicLink()) {
             throw new Error(`default_context_path_symlink_not_allowed:${relativePath}`);
@@ -32,7 +40,7 @@ export async function inspectDefaultContextFootprint(projectRootInput) {
         files.push({
             path: relativePath,
             bytes: content.byteLength,
-            reasons: [...reasons].sort(),
+            reasons: [...reasons].sort(compareUtf8Paths),
         });
     }
     return {
@@ -40,62 +48,49 @@ export async function inspectDefaultContextFootprint(projectRootInput) {
         total_bytes: files.reduce((total, file) => total + file.bytes, 0),
         duplicate_groups: [...hashes.values()]
             .filter((group) => group.length > 1)
-            .map((group) => [...group].sort())
-            .sort(([left], [right]) => left.localeCompare(right)),
+            .map((group) => [...group].sort(compareUtf8Paths))
+            .sort(comparePathGroups),
     };
 }
-// 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();
-        const changed = !reasons.has(reason);
-        reasons.add(reason);
-        selected.set(normalized, reasons);
-        return changed;
+function physicalDefaultPaths(manifest) {
+    const physical = new Map();
+    const addOwner = (rawPath) => {
+        const canonical = normalizeContextPath(rawPath);
+        const spelling = normalizeContextPathSpelling(rawPath);
+        const previous = physical.get(canonical);
+        if (previous !== undefined && previous !== spelling)
+            throw new Error(`default_context_path_unicode_collision:${canonical}:${[previous, spelling].sort(compareUtf8Paths).join(",")}`);
+        physical.set(canonical, spelling);
     };
     for (const core of [
         "project_context/context.toml",
         "project_context/global.md",
         "project_context/architecture.md",
     ])
-        add(core, "core");
-    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);
+        addOwner(core);
+    for (const area of manifest.areas)
+        addOwner(area.context);
+    for (const context of manifest.contexts)
+        addOwner(context.path);
+    for (const context of manifest.contexts)
+        for (const child of context.default_children) {
+            const canonical = normalizeContextPath(child);
+            if (!physical.has(canonical))
+                physical.set(canonical, normalizeContextPathSpelling(child));
         }
+    return physical;
+}
+function comparePathGroups(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const comparison = compareUtf8Paths(left[index], right[index]);
+        if (comparison !== 0)
+            return comparison;
     }
-    return selected;
+    return left.length - right.length;
 }
 function resolveProjectFile(projectRoot, relativePath) {
-    const absolutePath = path.resolve(projectRoot, ...normalizeContextPath(relativePath).split("/"));
+    const absolutePath = path.resolve(projectRoot, ...normalizeContextPathSpelling(relativePath).split("/"));
     const relative = path.relative(projectRoot, absolutePath);
     if (relative.startsWith(`..${path.sep}`) ||
         relative === ".." ||
@@ -104,6 +99,3 @@ function resolveProjectFile(projectRoot, relativePath) {
     }
     return absolutePath;
 }
-function normalizeContextPath(value) {
-    return value.replace(/\\/gu, "/").replace(/^\.\//u, "");
-}