project-tiny-context-harness 0.8.17 → 0.12.0

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,86 @@
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { assertSupportedSchema } from "../schema-guard.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) {
+    await assertSupportedSchema(input.project_root, "context create");
+    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,51 @@ 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 file of manifest.default_files ?? [])
+        addOwner(file);
+    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 +101,3 @@ function resolveProjectFile(projectRoot, relativePath) {
     }
     return absolutePath;
 }
-function normalizeContextPath(value) {
-    return value.replace(/\\/gu, "/").replace(/^\.\//u, "");
-}

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

@@ -0,0 +1,6 @@
+export declare const CONTEXT_DOCTOR_DEFAULTS: Readonly<{
+    context_file_soft_budget_bytes: number;
+}>;
+export interface ContextDoctorOptions {
+    context_file_soft_budget_bytes?: number;
+}

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

@@ -0,0 +1,3 @@
+export const CONTEXT_DOCTOR_DEFAULTS = Object.freeze({
+    context_file_soft_budget_bytes: 64 * 1024,
+});

package/dist/lib/context-export.js

@@ -3,8 +3,11 @@ import { createHash } from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
-import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged, } from "./fs.js";
+import { listFiles, pathExists, readText, } from "./fs.js";
 import { harnessRoot } from "./harness-root.js";
+import { assertSupportedSchema } from "./schema-guard.js";
+import { withMaintenanceLock } from "./maintenance-lock.js";
+import { writeMaintenanceText } from "./maintenance-write.js";
 import { SAFE_EXAMPLE_FILE_NAMES, shouldExcludeRelativePath, shouldIncludeCodeFile, toPosix, } from "./source-files.js";
 const execFileAsync = promisify(execFile);
 const EXPORT_HEADER = "Export artifact. Do not reference from project_context/context.toml.";
@@ -16,14 +19,21 @@ const GIT_LS_MAX_BUFFER = 64 * 1024 * 1024;
 const APPROX_TEXT_TOKEN_LIMIT_CHARS = 8_000_000;
 const SENSITIVE_ASSIGNMENT_PATTERN = /^(\s*(?:[-*]\s*)?(?:[`"']?[\w.-]*(?:secret|token|cookie|password|api[_-]?key)[\w.-]*[`"']?\s*[:=]\s*))(.+?)\s*$/i;
 export async function runExportContext(projectRoot, options = {}) {
+    if (!options.check)
+        await assertSupportedSchema(projectRoot, "export-context");
     const requestedModeCount = Number(options.full === true) + Number(options.code === true);
     if (requestedModeCount !== 1) {
         throw new Error("export-context requires exactly one of --full or --code");
     }
-    if (options.code) {
-        return runCodeImplementationExport(projectRoot, options);
-    }
-    return runFullContextExport(projectRoot, options);
+    const execute = () => options.code
+        ? runCodeImplementationExport(projectRoot, options)
+        : runFullContextExport(projectRoot, options);
+    if (options.check)
+        return execute();
+    return withMaintenanceLock(projectRoot, "export", async () => {
+        await assertSupportedSchema(projectRoot, "export-context");
+        return execute();
+    });
 }
 async function runFullContextExport(projectRoot, options) {
     const outputPath = resolveOutputPath(projectRoot, options.output, options.now, "full");
@@ -93,8 +103,7 @@ async function runFullContextExport(projectRoot, options) {
         "",
     ].join("\n");
     if (!options.check) {
-        await ensureDir(path.dirname(outputPath));
-        await writeTextIfChanged(outputPath, content);
+        await writeMaintenanceText(projectRoot, outputRelativePath, content);
     }
     return {
         mode: "full",
@@ -171,8 +180,7 @@ async function runCodeImplementationExport(projectRoot, options) {
         "",
     ].join("\n");
     if (!options.check) {
-        await ensureDir(path.dirname(outputPath));
-        await writeTextIfChanged(outputPath, content);
+        await writeMaintenanceText(projectRoot, outputRelativePath, content);
     }
     return {
         mode: "code",

package/dist/lib/context-inspect/context-inspect-projection.d.ts

@@ -0,0 +1,8 @@
+import type { ContextCatalog } from "../context-catalog/catalog-types.js";
+import type { ContextMarkdownCatalogAnalysis } from "../context-markdown/context-markdown-types.js";
+import type { ContextInspectResult } from "./context-inspect-types.js";
+export declare function projectContextInspection(input: {
+    catalog: ContextCatalog;
+    markdown: ContextMarkdownCatalogAnalysis;
+    context_path: string;
+}): ContextInspectResult;

package/dist/lib/context-inspect/context-inspect-projection.js

@@ -0,0 +1,48 @@
+import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
+const CORE_ROLES = new Map([
+    ["project_context/global.md", "global"],
+    ["project_context/architecture.md", "architecture"],
+]);
+export function projectContextInspection(input) {
+    const fileAnalysis = input.markdown.files.find((candidate) => candidate.path === input.context_path);
+    if (!fileAnalysis)
+        throw new Error(`Context Markdown analysis omitted ${input.context_path}`);
+    const registered = input.catalog.registered_contexts.find((candidate) => candidate.path === input.context_path);
+    const coreRole = CORE_ROLES.get(input.context_path);
+    const reasons = [
+        ...(input.catalog.default_footprint.get(input.context_path) ?? []),
+    ].sort(compareUtf8Paths);
+    const declarationKeys = new Set(fileAnalysis.declarations.map((entry) => `${entry.type}\0${entry.id}`));
+    return {
+        schema_version: 1,
+        path: input.context_path,
+        registration: registered || coreRole !== undefined ? "registered" : "unregistered",
+        source: coreRole !== undefined ? "core" : (registered?.source ?? null),
+        role: coreRole ?? registered?.role ?? null,
+        read_policy: registered?.read_policy ?? null,
+        read_when: registered?.context?.read_when ?? null,
+        triggers: [...(registered?.context?.triggers ?? [])],
+        default_children: [...(registered?.context?.default_children ?? [])],
+        bytes: fileAnalysis.bytes,
+        default_footprint: {
+            selected: reasons.length > 0,
+            reasons,
+        },
+        referenced_by: input.markdown.references
+            .filter((reference) => reference.status === "valid" &&
+            reference.target_path === input.context_path)
+            .sort(referenceOrder),
+        references: [...fileAnalysis.references].sort(referenceOrder),
+        stable_key_declarations: fileAnalysis.declarations,
+        stable_key_conflicts: input.markdown.declaration_conflicts.filter((conflict) => declarationKeys.has(`${conflict.type}\0${conflict.id}`)),
+        diagnostics: input.catalog.diagnostics.filter((diagnostic) => diagnostic.severity === "error" ||
+            diagnostic.path === undefined ||
+            diagnostic.path === input.context_path),
+    };
+}
+function referenceOrder(left, right) {
+    return (compareUtf8Paths(left.source_path, right.source_path) ||
+        left.line - right.line ||
+        left.column - right.column ||
+        compareUtf8Paths(left.destination, right.destination));
+}

package/dist/lib/context-inspect/context-inspect-render.d.ts

@@ -0,0 +1,2 @@
+import type { ContextInspectResult } from "./context-inspect-types.js";
+export declare function renderContextInspectText(result: ContextInspectResult): string;

package/dist/lib/context-inspect/context-inspect-render.js

@@ -0,0 +1,21 @@
+export function renderContextInspectText(result) {
+    const lines = [
+        `Context: ${result.path}`,
+        `registration=${result.registration} source=${result.source ?? "none"} role=${result.role ?? "unknown"}`,
+        `read_policy=${result.read_policy ?? "none"} bytes=${result.bytes}`,
+        `default=${result.default_footprint.selected}${result.default_footprint.reasons.length > 0 ? ` reasons=${result.default_footprint.reasons.join(",")}` : ""}`,
+        `read_when=${result.read_when ?? "none"}`,
+        `triggers=${result.triggers.length > 0 ? result.triggers.join(", ") : "none"}`,
+        `default_children=${result.default_children.length > 0 ? result.default_children.join(", ") : "none"}`,
+        `referenced_by=${result.referenced_by.length}`,
+    ];
+    for (const reference of result.referenced_by)
+        lines.push(`  ${reference.source_path}:${reference.line}:${reference.column} (${reference.kind})`);
+    lines.push(`references=${result.references.length}`);
+    for (const reference of result.references)
+        lines.push(`  ${reference.line}:${reference.column} ${reference.status} ${reference.target_path ?? reference.destination}`);
+    lines.push(`stable_key_declarations=${result.stable_key_declarations.length} conflicts=${result.stable_key_conflicts.length}`);
+    for (const diagnostic of result.diagnostics)
+        lines.push(`${diagnostic.severity}: ${diagnostic.code}: ${diagnostic.message}`);
+    return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,29 @@
+import type { CatalogDiagnostic } from "../context-catalog/catalog-types.js";
+import type { ContextRole } from "../context-catalog/catalog-portable-contract.js";
+import type { DefaultContextSelectionReason } from "../context-catalog/catalog-default-footprint.js";
+import type { ContextMarkdownReference, ContextStableKeyConflict, ContextStableKeyDeclaration } from "../context-markdown/context-markdown-types.js";
+export interface ContextInspectResult {
+    schema_version: 1;
+    path: string;
+    registration: "registered" | "unregistered";
+    source: "core" | "area" | "context" | null;
+    role: ContextRole | null;
+    read_policy: string | null;
+    read_when: string | null;
+    triggers: string[];
+    default_children: string[];
+    bytes: number;
+    default_footprint: {
+        selected: boolean;
+        reasons: DefaultContextSelectionReason[];
+    };
+    referenced_by: ContextMarkdownReference[];
+    references: ContextMarkdownReference[];
+    stable_key_declarations: ContextStableKeyDeclaration[];
+    stable_key_conflicts: ContextStableKeyConflict[];
+    diagnostics: CatalogDiagnostic[];
+}
+export interface ContextInspectInput {
+    project_root: string;
+    context_path: string;
+}

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

@@ -0,0 +1,2 @@
+import type { ContextInspectInput, ContextInspectResult } from "./context-inspect-types.js";
+export declare function inspectContext(input: ContextInspectInput): Promise<ContextInspectResult>;

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

@@ -0,0 +1,77 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { loadContextCatalog } from "../context-catalog/catalog-load.js";
+import { isPathWithin, normalizeContextPath, } from "../context-catalog/catalog-paths.js";
+import { analyzeContextMarkdownCatalog } from "../context-markdown/context-markdown-analysis.js";
+import { projectContextInspection } from "./context-inspect-projection.js";
+export async function inspectContext(input) {
+    const projectRoot = path.resolve(input.project_root);
+    const contextPath = normalizeInspectedPath(input.context_path);
+    let catalog;
+    try {
+        catalog = await loadContextCatalog(projectRoot);
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to load Context Catalog: ${message(error)}`, { cause: error });
+    }
+    const file = catalog.context_files.find((candidate) => candidate.path === contextPath);
+    if (!file)
+        throw new CliCommandError(CLI_EXIT_CODES.io, `Context inspect target is not an eligible Markdown file: ${contextPath}`);
+    try {
+        await verifyOrdinaryInRepositoryFile(projectRoot, file.absolute_path);
+    }
+    catch (error) {
+        if (error instanceof CliCommandError)
+            throw error;
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to inspect Context file identity: ${message(error)}`, { cause: error });
+    }
+    let markdown;
+    try {
+        markdown = await analyzeContextMarkdownCatalog({
+            project_root: projectRoot,
+            files: catalog.context_files,
+            long_line_threshold: Number.MAX_SAFE_INTEGER,
+        });
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to analyze Context Markdown: ${message(error)}`, { cause: error });
+    }
+    try {
+        return projectContextInspection({
+            catalog,
+            markdown,
+            context_path: contextPath,
+        });
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.internal, message(error), {
+            cause: error,
+        });
+    }
+}
+function normalizeInspectedPath(value) {
+    if (path.isAbsolute(value))
+        throw new CliCommandError(CLI_EXIT_CODES.io, "Context inspect requires a repository-relative path");
+    const normalized = normalizeContextPath(value);
+    if (!normalized.startsWith("project_context/") ||
+        !normalized.toLowerCase().endsWith(".md") ||
+        normalized.split("/").includes(".."))
+        throw new CliCommandError(CLI_EXIT_CODES.io, `Context inspect target must be a Markdown file under project_context/: ${value}`);
+    return normalized;
+}
+async function verifyOrdinaryInRepositoryFile(projectRoot, absolutePath) {
+    const metadata = await lstat(absolutePath);
+    if (!metadata.isFile() || metadata.isSymbolicLink())
+        throw new CliCommandError(CLI_EXIT_CODES.io, "Context inspect target must be an ordinary file");
+    const repositoryIdentity = await realpath(projectRoot);
+    // Catalog discovery owns the canonical NFC key -> physical file mapping.
+    // Re-resolving the key would lose an NFD spelling on filesystems that keep
+    // canonical-equivalent names distinct.
+    const targetIdentity = await realpath(absolutePath);
+    if (!isPathWithin(repositoryIdentity, targetIdentity))
+        throw new CliCommandError(CLI_EXIT_CODES.io, "Context inspect target resolves outside the repository");
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/context-manifest-schema.d.ts

@@ -1,4 +1,4 @@
-export type ContextRole = "global" | "architecture" | "area" | "domain" | "subdomain" | "foundation" | "archive" | "contract" | "verification" | "deployment" | "implementation-index" | "decision-rationale";
+export type { ContextRole } from "./context-catalog/catalog-portable-contract.js";
 export interface ContextAreaEntry {
     line: number;
     id: string;
@@ -18,6 +18,7 @@ export interface ContextNodeEntry {
     default_children: string[];
 }
 export interface ContextManifest {
+    default_files?: string[];
     areas: ContextAreaEntry[];
     contexts: ContextNodeEntry[];
 }