project-tiny-context-harness 0.8.17 → 0.12.0

package/dist/lib/context-catalog/catalog-portable-contract.d.ts

@@ -0,0 +1,15 @@
+export type ContextRole = "global" | "architecture" | "area" | "domain" | "subdomain" | "foundation" | "archive" | "contract" | "verification" | "deployment" | "implementation-index" | "decision-rationale";
+export declare const CONTEXT_SCHEMA_VERSION: number;
+export declare const CONTEXT_ROLES: readonly string[];
+export declare const CONTEXT_ROLE_ALIASES: Readonly<{
+    [x: string]: string;
+}>;
+export declare const CONTEXT_READ_POLICIES: readonly string[];
+export declare const CONTEXT_LEGACY_READ_POLICIES: readonly string[];
+export declare const CONTEXT_TOP_LEVEL_FIELDS: Set<string>;
+export declare const CONTEXT_AREA_FIELDS: Set<string>;
+export declare const CONTEXT_NODE_FIELDS: Set<string>;
+export declare const CONTEXT_READ_POLICY_SET: Set<string>;
+export declare const CONTEXT_LEGACY_READ_POLICY_SET: Set<string>;
+export declare function normalizeContextRole(value: string): ContextRole | undefined;
+export declare function isContextReadPolicy(value: string): boolean;

package/dist/lib/context-catalog/catalog-portable-contract.js

@@ -0,0 +1,68 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const rawRules = require("../../../assets/tools/context_rules.json");
+const rules = validateRules(rawRules);
+export const CONTEXT_SCHEMA_VERSION = rules.context_schema_version;
+export const CONTEXT_ROLES = Object.freeze([...rules.roles]);
+export const CONTEXT_ROLE_ALIASES = Object.freeze({
+    ...rules.role_aliases,
+});
+export const CONTEXT_READ_POLICIES = Object.freeze([...rules.read_policies]);
+export const CONTEXT_LEGACY_READ_POLICIES = Object.freeze([
+    ...rules.legacy_read_policies,
+]);
+export const CONTEXT_TOP_LEVEL_FIELDS = new Set(rules.top_level_fields);
+export const CONTEXT_AREA_FIELDS = new Set(rules.area_fields);
+export const CONTEXT_NODE_FIELDS = new Set(rules.context_fields);
+export const CONTEXT_READ_POLICY_SET = new Set(CONTEXT_READ_POLICIES);
+export const CONTEXT_LEGACY_READ_POLICY_SET = new Set(CONTEXT_LEGACY_READ_POLICIES);
+export function normalizeContextRole(value) {
+    const normalized = value.trim().toLowerCase();
+    const aliased = CONTEXT_ROLE_ALIASES[normalized] ?? normalized;
+    return CONTEXT_ROLES.includes(aliased) ? aliased : undefined;
+}
+export function isContextReadPolicy(value) {
+    return CONTEXT_READ_POLICY_SET.has(value);
+}
+function validateRules(value) {
+    if (!isRecord(value)) {
+        throw new Error("context_rules_invalid:root");
+    }
+    const arrayFields = [
+        "roles",
+        "read_policies",
+        "legacy_read_policies",
+        "top_level_fields",
+        "area_fields",
+        "context_fields",
+    ];
+    for (const field of arrayFields) {
+        if (!isUniqueStringArray(value[field])) {
+            throw new Error(`context_rules_invalid:${field}`);
+        }
+    }
+    if (!Number.isInteger(value.context_schema_version) ||
+        Number(value.context_schema_version) < 1) {
+        throw new Error("context_rules_invalid:context_schema_version");
+    }
+    if (!isRecord(value.role_aliases) ||
+        Object.values(value.role_aliases).some((entry) => typeof entry !== "string" || !entry.trim())) {
+        throw new Error("context_rules_invalid:role_aliases");
+    }
+    const typed = value;
+    if (typed.legacy_read_policies.some((policy) => !typed.read_policies.includes(policy))) {
+        throw new Error("context_rules_invalid:legacy_read_policies_subset");
+    }
+    if (Object.values(typed.role_aliases).some((role) => !typed.roles.includes(role))) {
+        throw new Error("context_rules_invalid:role_alias_target");
+    }
+    return typed;
+}
+function isUniqueStringArray(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string" && entry.trim()) &&
+        new Set(value).size === value.length);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/lib/context-catalog/catalog-staged-path-safety.d.ts

@@ -0,0 +1 @@
+export declare function assertCatalogStagedFilePath(repository: string, relative: string, stagedDirectories: ReadonlySet<string>, label: string): Promise<void>;

package/dist/lib/context-catalog/catalog-staged-path-safety.js

@@ -0,0 +1,36 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { assertProtectedRepositoryDirectory, assertSafeRepositoryFilePath, resolveInsideRepository, } from "../repository-path-safety.js";
+import { normalizeContextPath, normalizeContextPathSpelling, } from "./catalog-paths.js";
+export async function assertCatalogStagedFilePath(repository, relative, stagedDirectories, label) {
+    const absolute = resolveInsideRepository(repository, relative, label);
+    const parent = normalizeContextPathSpelling(path.posix.dirname(relative));
+    let physicalCursor = "";
+    for (const segment of parent.split("/")) {
+        if (!segment || segment === ".")
+            continue;
+        physicalCursor = physicalCursor ? `${physicalCursor}/${segment}` : segment;
+        const canonicalCursor = normalizeContextPath(physicalCursor);
+        const candidate = path.join(repository, ...physicalCursor.split("/"));
+        const status = await lstat(candidate).catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (!status) {
+            if (!stagedDirectories.has(canonicalCursor))
+                throw new Error(`staged_parent_not_declared:${label}:${canonicalCursor}`);
+            continue;
+        }
+        await assertProtectedRepositoryDirectory(repository, candidate, `${label}:parent`);
+    }
+    const target = await lstat(absolute).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (target)
+        await assertSafeRepositoryFilePath(repository, relative, label, {
+            destinationMayBeAbsent: true,
+        });
+}

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

@@ -0,0 +1,40 @@
+import type { ContextAreaEntry, ContextManifest, ContextNodeEntry } from "../context-manifest-schema.js";
+import type { ContextRole } from "./catalog-portable-contract.js";
+import type { DefaultContextSelectionReason } from "./catalog-default-footprint.js";
+export type CatalogDiagnosticSeverity = "error" | "warning";
+export interface CatalogDiagnostic {
+    code: string;
+    severity: CatalogDiagnosticSeverity;
+    message: string;
+    path?: string;
+    line?: number;
+}
+export interface CatalogFile {
+    path: string;
+    physical_path: string;
+    absolute_path: string;
+    bytes: number;
+}
+export interface CatalogRegisteredContext {
+    source: "area" | "context";
+    path: string;
+    role: ContextRole;
+    read_policy?: string;
+    line: number;
+    area?: ContextAreaEntry;
+    context?: ContextNodeEntry;
+}
+export interface ContextCatalog {
+    project_root: string;
+    manifest_path: string;
+    manifest_content?: string;
+    manifest?: ContextManifest;
+    areas: ContextAreaEntry[];
+    registered_contexts: CatalogRegisteredContext[];
+    context_files: CatalogFile[];
+    unregistered_context_files: CatalogFile[];
+    default_footprint: Map<string, Set<DefaultContextSelectionReason>>;
+    roles_by_path: Map<string, ContextRole>;
+    read_policies_by_path: Map<string, string>;
+    diagnostics: CatalogDiagnostic[];
+}

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

@@ -0,0 +1,9 @@
+import type { ContextManifest } from "../context-manifest-schema.js";
+import type { CatalogFile, CatalogDiagnostic, CatalogRegisteredContext } from "./catalog-types.js";
+export interface CatalogManifestValidation {
+    registered_contexts: CatalogRegisteredContext[];
+    roles_by_path: Map<string, CatalogRegisteredContext["role"]>;
+    read_policies_by_path: Map<string, string>;
+    diagnostics: CatalogDiagnostic[];
+}
+export declare function validateCatalogManifest(projectRoot: string, manifest: ContextManifest, fileOverrides?: ReadonlyMap<string, Uint8Array | null>, directoryOverrides?: ReadonlySet<string>, contextFiles?: readonly CatalogFile[]): Promise<CatalogManifestValidation>;

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

@@ -0,0 +1,156 @@
+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));
+    };
+    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 (defaultAreas.length > 1) {
+        addError("manifest_default_area_count", `project_context/context.toml may mark at most one [[areas]] entry with default = true; found ${defaultAreas.length}`);
+    }
+    const directDefaults = new Set();
+    for (const file of [
+        "project_context/global.md",
+        ...(manifest.default_files ?? []),
+    ]) {
+        const key = normalizeContextPath(file);
+        if (directDefaults.has(key))
+            addError("manifest_default_file_duplicate", `Duplicate default file: ${file}`);
+        directDefaults.add(key);
+        await validateCatalogManifestPath(projectRoot, file, path.join(projectRoot, "project_context"), "default file", true, addError, fileOverrides, directoryOverrides, filesByPath);
+    }
+    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-controlling-source.d.ts

@@ -0,0 +1,4 @@
+import type { ContextControllingSourceConflict, ContextControllingSourceDeclaration, ContextControllingSourceRawDeclaration } from "./context-markdown/context-markdown-types.js";
+export declare function resolveContextControllingSourceDeclaration(projectRoot: string, declaration: ContextControllingSourceRawDeclaration): Promise<ContextControllingSourceDeclaration>;
+export declare function contextControllingSourceConflicts(declarations: readonly ContextControllingSourceDeclaration[]): ContextControllingSourceConflict[];
+export declare function canonicalControllingSourcePath(value: string): string;

package/dist/lib/context-controlling-source.js

@@ -0,0 +1,106 @@
+import { readFile, realpath } from "node:fs/promises";
+import { TextDecoder } from "node:util";
+import { compareUtf8Paths, normalizeContextPath, repositoryRelativePathSpelling, } from "./context-catalog/catalog-paths.js";
+import { normalizeRepositoryFile } from "./repository-path-safety.js";
+import { assertSafeRepositoryFilePath } from "./repository-path-safety.js";
+export async function resolveContextControllingSourceDeclaration(projectRoot, declaration) {
+    let targetPath;
+    try {
+        targetPath = canonicalControllingSourcePath(declaration.declared_path);
+    }
+    catch (error) {
+        return invalidDeclaration(declaration, null, error);
+    }
+    try {
+        const safe = await assertSafeRepositoryFilePath(projectRoot, targetPath, `context_controlling_source:${declaration.source_path}:${declaration.line}`);
+        const physicalPath = normalizeContextPath(repositoryRelativePathSpelling(safe.repository, await realpath(safe.absolute)));
+        if (physicalPath !== targetPath)
+            return {
+                ...declaration,
+                target_path: targetPath,
+                status: "invalid",
+                detail: `declared path casing or spelling differs from the physical repository path ${physicalPath}`,
+            };
+        const decoded = decodeStrictUtf8(await readFile(safe.absolute));
+        if (decoded === null)
+            return {
+                ...declaration,
+                target_path: targetPath,
+                status: "invalid",
+                detail: "declared controlling Source must be a non-NUL strict UTF-8 file",
+            };
+        return {
+            ...declaration,
+            target_path: targetPath,
+            status: "valid",
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const status = message.includes("not_found") ? "missing" : "invalid";
+        return {
+            ...declaration,
+            target_path: targetPath,
+            status,
+            detail: message,
+        };
+    }
+}
+export function contextControllingSourceConflicts(declarations) {
+    const byTarget = new Map();
+    for (const declaration of declarations) {
+        if (declaration.status !== "valid" || !declaration.target_path)
+            continue;
+        const rows = byTarget.get(declaration.target_path) ?? [];
+        rows.push(declaration);
+        byTarget.set(declaration.target_path, rows);
+    }
+    const conflicts = [];
+    for (const [targetPath, rows] of byTarget) {
+        if (rows.length < 2)
+            continue;
+        const domains = [...new Set(rows.map((row) => row.domain))].sort();
+        conflicts.push({
+            kind: domains.length === 1 ? "duplicate" : "domain_conflict",
+            target_path: targetPath,
+            domains,
+            owners: rows
+                .map((row) => ({
+                source_path: row.source_path,
+                line: row.line,
+                domain: row.domain,
+            }))
+                .sort((left, right) => compareUtf8Paths(left.source_path, right.source_path) ||
+                left.line - right.line ||
+                left.domain.localeCompare(right.domain)),
+        });
+    }
+    return conflicts.sort((left, right) => compareUtf8Paths(left.target_path, right.target_path));
+}
+export function canonicalControllingSourcePath(value) {
+    if (value !== value.normalize("NFC") || value !== value.trim())
+        throw new Error(`context_controlling_source_path_noncanonical:${value}`);
+    if (value.includes("\\") || /[?#]/u.test(value))
+        throw new Error(`context_controlling_source_path_noncanonical:${value}`);
+    const normalized = normalizeRepositoryFile(value, "context_controlling_source");
+    if (normalized !== value)
+        throw new Error(`context_controlling_source_path_noncanonical:${value}`);
+    return normalized;
+}
+function invalidDeclaration(declaration, targetPath, error) {
+    return {
+        ...declaration,
+        target_path: targetPath,
+        status: "invalid",
+        detail: error instanceof Error ? error.message : String(error),
+    };
+}
+function decodeStrictUtf8(bytes) {
+    try {
+        const value = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return value.includes("\0") ? null : value;
+    }
+    catch {
+        return null;
+    }
+}

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-write.d.ts

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