@kontextmind/kxm 0.7.39 → 0.7.43

package/plugins/kxm/src/{vnext-repair.ts → repair.ts}

@@ -16,33 +16,33 @@ import {
 } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import {
-  VnextConfigError,
-  VnextSchemaRegistry,
-  loadVnextProject,
+  KxmConfigError,
+  KxmSchemaRegistry,
+  loadKxmProject,
   assertNoRegisteredGates,
   parseRestrictedYaml,
   type JsonObject,
-  type VnextConfigIssue,
-  type VnextConfigOptions,
-  type VnextProjectBundle,
-} from "./vnext-config.ts";
+  type KxmConfigIssue,
+  type KxmConfigOptions,
+  type KxmProjectBundle,
+} from "./project-config.ts";
 import {
-  CURRENT_VNEXT_TEMPLATE_VARIANT,
-  VNEXT_TEMPLATE_ID,
-  VNEXT_TEMPLATE_PROVENANCE_PATH,
-  renderVnextTemplate,
-  resolveVnextTemplateBaseline,
-  SUPPORTED_VNEXT_TEMPLATE_VARIANTS,
-  vnextContentSha256,
-  type VnextRenderedTemplate,
-  type VnextTemplateProvenance,
-  type VnextTemplateVariant,
-} from "./vnext-template.ts";
-import { computeVnextResourcePermissionDiff } from "./vnext-permission.ts";
-import type { VnextResourceKind } from "./vnext-config.ts";
+  CURRENT_KXM_TEMPLATE_VARIANT,
+  KXM_TEMPLATE_ID,
+  KXM_TEMPLATE_PROVENANCE_PATH,
+  renderKxmTemplate,
+  resolveKxmTemplateBaseline,
+  SUPPORTED_KXM_TEMPLATE_VARIANTS,
+  kxmContentSha256,
+  type KxmRenderedTemplate,
+  type KxmTemplateProvenance,
+  type KxmTemplateVariant,
+} from "./template.ts";
+import { computeKxmResourcePermissionDiff } from "./permission.ts";
+import type { KxmResourceKind } from "./project-config.ts";
 
 /** Map a managed template path to its resource kind for permission diffing. */
-function resourceKindForTemplatePath(path: string): VnextResourceKind {
+function resourceKindForTemplatePath(path: string): KxmResourceKind {
   if (path === ".kxm/project.yaml") return "project";
   if (path === ".kxm/gates.yaml") return "gate-registry";
   if (path.endsWith("repo.yaml")) return "repository";
@@ -58,11 +58,11 @@ const MAX_MANAGED_FILE_BYTES = 256 * 1024;
 const MAX_MANAGED_TOTAL_BYTES = 8 * 1024 * 1024;
 const PORTABLE_PATH = /^(?:\.|(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/)(?!.*[. ](?:\/|$))[^/\\\u0000-\u001F]+(?:\/[^/\\\u0000-\u001F]+)*)$/;
 
-export type VnextTemplateClassification = "unchanged" | "user-only" | "template-only" | "converged" | "conflict";
+export type KxmTemplateClassification = "unchanged" | "user-only" | "template-only" | "converged" | "conflict";
 
-export interface VnextTemplateChange {
+export interface KxmTemplateChange {
   path: string;
-  classification: VnextTemplateClassification;
+  classification: KxmTemplateClassification;
   baseSha256?: string;
   localSha256?: string;
   targetSha256?: string;
@@ -71,7 +71,7 @@ export interface VnextTemplateChange {
   reason?: string;
 }
 
-export interface VnextTemplateRepairPlan {
+export interface KxmTemplateRepairPlan {
   projectRoot: string;
   projectId: string;
   projectName: string;
@@ -79,11 +79,11 @@ export interface VnextTemplateRepairPlan {
   targetTemplateRevision: string;
   changesRequired: boolean;
   canApply: boolean;
-  changes: readonly VnextTemplateChange[];
-  issues: readonly VnextConfigIssue[];
+  changes: readonly KxmTemplateChange[];
+  issues: readonly KxmConfigIssue[];
 }
 
-interface VnextInitOperationFile {
+interface KxmInitOperationFile {
   path: string;
   observedSha256: string | null;
   targetSha256: string;
@@ -91,7 +91,7 @@ interface VnextInitOperationFile {
   action: "create" | "replace" | "none";
 }
 
-interface VnextInitOperation {
+interface KxmInitOperation {
   schema: "kxm.init-operation.v1";
   operationId: string;
   kind: "create" | "repair";
@@ -99,26 +99,26 @@ interface VnextInitOperation {
   projectRoot: string;
   projectId: string;
   projectName: string;
-  templateId: typeof VNEXT_TEMPLATE_ID;
+  templateId: typeof KXM_TEMPLATE_ID;
   sourceTemplateRevision: string | null;
   targetTemplateRevision: string;
   planSha256: string;
-  files: readonly VnextInitOperationFile[];
+  files: readonly KxmInitOperationFile[];
 }
 
-export interface VnextOperationResult {
+export interface KxmOperationResult {
   kind: "create" | "repair";
   resumed: boolean;
-  bundle: VnextProjectBundle;
+  bundle: KxmProjectBundle;
   files: readonly string[];
 }
 
-export interface VnextRepairRuntimeOptions {
+export interface KxmRepairRuntimeOptions {
   schemasDir?: string;
   repositoryBindings?: Readonly<Record<string, string>>;
   registeredExecutors?: Iterable<string>;
   registeredToolPresets?: Iterable<string>;
-  templateVariant?: VnextTemplateVariant;
+  templateVariant?: KxmTemplateVariant;
   testFaultAt?: "prepared" | "first-resource" | "provenance" | "verified";
 }
 
@@ -126,12 +126,12 @@ function compareCodeUnits(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
-function repairIssue(code: string, file: string, message: string, phase: VnextConfigIssue["phase"] = "semantic"): VnextConfigIssue {
+function repairIssue(code: string, file: string, message: string, phase: KxmConfigIssue["phase"] = "semantic"): KxmConfigIssue {
   return { phase, code, file, message };
 }
 
-function fail(code: string, file: string, message: string, phase: VnextConfigIssue["phase"] = "semantic"): never {
-  throw new VnextConfigError([repairIssue(code, file, message, phase)]);
+function fail(code: string, file: string, message: string, phase: KxmConfigIssue["phase"] = "semantic"): never {
+  throw new KxmConfigError([repairIssue(code, file, message, phase)]);
 }
 
 function syncDirectory(path: string): void {
@@ -189,7 +189,7 @@ function transactionRoot(projectRoot: string): string {
   return join(resolve(projectRoot), TRANSACTION_NAME);
 }
 
-export function vnextInitTransactionPath(projectRoot: string): string {
+export function kxmInitTransactionPath(projectRoot: string): string {
   return transactionRoot(projectRoot);
 }
 
@@ -211,7 +211,7 @@ function backupFile(projectRoot: string, portablePath: string): string {
 
 function portableManagedPath(path: string): boolean {
   return path.startsWith(".kxm/")
-    && path !== VNEXT_TEMPLATE_PROVENANCE_PATH
+    && path !== KXM_TEMPLATE_PROVENANCE_PATH
     && path.length <= 1024
     && !path.includes("\\")
     && !isAbsolute(path)
@@ -239,81 +239,81 @@ function readOptionalManaged(projectRoot: string, path: string): Buffer | undefi
   return readRegularBounded(file, path);
 }
 
-function readProjectAndProvenance(projectRoot: string, schemasDir?: string): { project: JsonObject; provenance: VnextTemplateProvenance; provenanceBytes: Buffer } | undefined {
+function readProjectAndProvenance(projectRoot: string, schemasDir?: string): { project: JsonObject; provenance: KxmTemplateProvenance; provenanceBytes: Buffer } | undefined {
   const projectFile = join(projectRoot, ".kxm", "project.yaml");
-  const provenanceFile = join(projectRoot, ...VNEXT_TEMPLATE_PROVENANCE_PATH.split("/"));
+  const provenanceFile = join(projectRoot, ...KXM_TEMPLATE_PROVENANCE_PATH.split("/"));
   if (!existsSync(projectFile) || !existsSync(provenanceFile)) return undefined;
   const projectBytes = readOptionalManaged(projectRoot, ".kxm/project.yaml");
-  const provenanceBytes = readOptionalManaged(projectRoot, VNEXT_TEMPLATE_PROVENANCE_PATH);
+  const provenanceBytes = readOptionalManaged(projectRoot, KXM_TEMPLATE_PROVENANCE_PATH);
   if (!projectBytes || !provenanceBytes) return undefined;
   const project = parseRestrictedYaml(projectBytes, ".kxm/project.yaml");
-  const provenanceValue = parseRestrictedYaml(provenanceBytes, VNEXT_TEMPLATE_PROVENANCE_PATH);
-  const registry = new VnextSchemaRegistry(schemasDir);
+  const provenanceValue = parseRestrictedYaml(provenanceBytes, KXM_TEMPLATE_PROVENANCE_PATH);
+  const registry = new KxmSchemaRegistry(schemasDir);
   const issues = [
     ...registry.validate("project", project, ".kxm/project.yaml"),
-    ...registry.validateTemplateProvenance(provenanceValue, VNEXT_TEMPLATE_PROVENANCE_PATH),
+    ...registry.validateTemplateProvenance(provenanceValue, KXM_TEMPLATE_PROVENANCE_PATH),
   ];
-  if (issues.length > 0) throw new VnextConfigError(issues);
-  const provenance = resolveVnextTemplateBaseline(provenanceValue);
-  if (!provenance) fail("template_provenance_revision_invalid", VNEXT_TEMPLATE_PROVENANCE_PATH, "template provenance does not exactly match a supported built-in baseline");
+  if (issues.length > 0) throw new KxmConfigError(issues);
+  const provenance = resolveKxmTemplateBaseline(provenanceValue);
+  if (!provenance) fail("template_provenance_revision_invalid", KXM_TEMPLATE_PROVENANCE_PATH, "template provenance does not exactly match a supported built-in baseline");
   if (project.id !== provenance.inputs.projectId) {
-    fail("template_provenance_project_mismatch", VNEXT_TEMPLATE_PROVENANCE_PATH, "template provenance belongs to a different project identity");
+    fail("template_provenance_project_mismatch", KXM_TEMPLATE_PROVENANCE_PATH, "template provenance belongs to a different project identity");
   }
   const seen = new Set<string>();
   let prior = "";
   let totalBytes = 0;
   for (const record of provenance.files) {
-    if (!portableManagedPath(record.path)) fail("template_provenance_path_invalid", VNEXT_TEMPLATE_PROVENANCE_PATH, `managed path ${record.path} is invalid`, "path");
+    if (!portableManagedPath(record.path)) fail("template_provenance_path_invalid", KXM_TEMPLATE_PROVENANCE_PATH, `managed path ${record.path} is invalid`, "path");
     const folded = record.path.toLocaleLowerCase("en-US");
-    if (seen.has(folded)) fail("template_provenance_path_collision", VNEXT_TEMPLATE_PROVENANCE_PATH, `managed path ${record.path} collides after case folding`, "path");
-    if (prior && compareCodeUnits(prior, record.path) >= 0) fail("template_provenance_order_invalid", VNEXT_TEMPLATE_PROVENANCE_PATH, "managed files are not in strict code-unit order");
+    if (seen.has(folded)) fail("template_provenance_path_collision", KXM_TEMPLATE_PROVENANCE_PATH, `managed path ${record.path} collides after case folding`, "path");
+    if (prior && compareCodeUnits(prior, record.path) >= 0) fail("template_provenance_order_invalid", KXM_TEMPLATE_PROVENANCE_PATH, "managed files are not in strict code-unit order");
     totalBytes += record.bytes;
     seen.add(folded);
     prior = record.path;
   }
   if (provenance.files.length > MAX_MANAGED_FILES || totalBytes > MAX_MANAGED_TOTAL_BYTES) {
-    fail("template_provenance_bounds_exceeded", VNEXT_TEMPLATE_PROVENANCE_PATH, "managed template manifest exceeds bounded file or byte limits", "parse");
+    fail("template_provenance_bounds_exceeded", KXM_TEMPLATE_PROVENANCE_PATH, "managed template manifest exceeds bounded file or byte limits", "parse");
   }
   return { project, provenance, provenanceBytes };
 }
 
 /** Classify exact whole-file B/L/T states without writing or inferring a missing baseline. */
-export function planVnextTemplateRepair(
+export function planKxmTemplateRepair(
   projectRoot: string,
-  options: VnextRepairRuntimeOptions = {},
-): VnextTemplateRepairPlan | undefined {
+  options: KxmRepairRuntimeOptions = {},
+): KxmTemplateRepairPlan | undefined {
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const source = readProjectAndProvenance(root, options.schemasDir);
   if (!source) return undefined;
-  const target = renderVnextTemplate(
+  const target = renderKxmTemplate(
     source.provenance.inputs.projectId,
     source.provenance.inputs.projectName,
-    options.templateVariant ?? CURRENT_VNEXT_TEMPLATE_VARIANT,
+    options.templateVariant ?? CURRENT_KXM_TEMPLATE_VARIANT,
   );
   const baseByPath = new Map(source.provenance.files.map((record) => [record.path, record]));
   const targetByPath = new Map(target.provenance.files.map((record) => [record.path, record]));
   const paths = [...new Set([...baseByPath.keys(), ...targetByPath.keys()])].sort(compareCodeUnits);
-  const sourceRenderer = SUPPORTED_VNEXT_TEMPLATE_VARIANTS
-    .map((variant) => renderVnextTemplate(source.provenance.inputs.projectId, source.provenance.inputs.projectName, variant))
+  const sourceRenderer = SUPPORTED_KXM_TEMPLATE_VARIANTS
+    .map((variant) => renderKxmTemplate(source.provenance.inputs.projectId, source.provenance.inputs.projectName, variant))
     .find((candidate) => candidate.templateRevision === source.provenance.templateRevision);
-  const expectedProvenance = sourceRenderer?.files.get(VNEXT_TEMPLATE_PROVENANCE_PATH);
-  const issues: VnextConfigIssue[] = [];
-  if (!expectedProvenance || vnextContentSha256(source.provenanceBytes) !== vnextContentSha256(expectedProvenance)) {
+  const expectedProvenance = sourceRenderer?.files.get(KXM_TEMPLATE_PROVENANCE_PATH);
+  const issues: KxmConfigIssue[] = [];
+  if (!expectedProvenance || kxmContentSha256(source.provenanceBytes) !== kxmContentSha256(expectedProvenance)) {
     issues.push(repairIssue(
       "template_provenance_user_modified",
-      VNEXT_TEMPLATE_PROVENANCE_PATH,
+      KXM_TEMPLATE_PROVENANCE_PATH,
       "template provenance formatting or bytes differ from the supported baseline and require review",
     ));
   }
-  const changes = paths.map((path): VnextTemplateChange => {
+  const changes = paths.map((path): KxmTemplateChange => {
     const base = baseByPath.get(path);
     const targetRecord = targetByPath.get(path);
     const local = readOptionalManaged(root, path);
-    const localSha256 = local && vnextContentSha256(local);
+    const localSha256 = local && kxmContentSha256(local);
     const baseSha256 = base?.sha256;
     if (base && localSha256 === base.sha256 && local?.byteLength !== base.bytes) {
-      fail("template_provenance_bytes_invalid", VNEXT_TEMPLATE_PROVENANCE_PATH, `recorded byte count for ${path} does not match its baseline content`);
+      fail("template_provenance_bytes_invalid", KXM_TEMPLATE_PROVENANCE_PATH, `recorded byte count for ${path} does not match its baseline content`);
     }
     const targetSha256 = targetRecord?.sha256;
     if (baseSha256 === localSha256 && localSha256 === targetSha256) {
@@ -336,7 +336,7 @@ export function planVnextTemplateRepair(
         const baseValue = base ? sourceRenderer?.values.get(path) : undefined;
         const targetValue = target.values.get(path);
         const detail = baseValue && targetValue
-          ? computeVnextResourcePermissionDiff(resourceKindForTemplatePath(path), path, baseValue, targetValue)
+          ? computeKxmResourcePermissionDiff(resourceKindForTemplatePath(path), path, baseValue, targetValue)
               .map((change) => `${change.path} ${change.field} ${change.direction}`)
               .join("; ")
           : "";
@@ -403,8 +403,8 @@ export function planVnextTemplateRepair(
   };
 }
 
-function operationPlanSha(operation: Omit<VnextInitOperation, "planSha256" | "phase">): string {
-  return vnextContentSha256(JSON.stringify({
+function operationPlanSha(operation: Omit<KxmInitOperation, "planSha256" | "phase">): string {
+  return kxmContentSha256(JSON.stringify({
     kind: operation.kind,
     projectRoot: operation.projectRoot,
     projectId: operation.projectId,
@@ -416,7 +416,7 @@ function operationPlanSha(operation: Omit<VnextInitOperation, "planSha256" | "ph
   }));
 }
 
-function writeOperation(projectRoot: string, operation: VnextInitOperation): void {
+function writeOperation(projectRoot: string, operation: KxmInitOperation): void {
   const root = transactionRoot(projectRoot);
   const file = operationFile(projectRoot);
   const temporary = join(root, `.operation-${operation.operationId}-${randomUUID()}.tmp`);
@@ -429,13 +429,13 @@ function writeOperation(projectRoot: string, operation: VnextInitOperation): voi
   }
 }
 
-function updatePhase(projectRoot: string, operation: VnextInitOperation, phase: VnextInitOperation["phase"]): VnextInitOperation {
+function updatePhase(projectRoot: string, operation: KxmInitOperation, phase: KxmInitOperation["phase"]): KxmInitOperation {
   const updated = { ...operation, phase };
   writeOperation(projectRoot, updated);
   return updated;
 }
 
-function readOperation(projectRoot: string, schemasDir?: string): VnextInitOperation | undefined {
+function readOperation(projectRoot: string, schemasDir?: string): KxmInitOperation | undefined {
   const root = transactionRoot(projectRoot);
   if (!existsSync(root)) return undefined;
   const stat = lstatSync(root);
@@ -448,10 +448,10 @@ function readOperation(projectRoot: string, schemasDir?: string): VnextInitOpera
     fail("init_transaction_record_missing", TRANSACTION_NAME, "initialization transaction without an operation record contains unrecognized state");
   }
   const value = parseRestrictedYaml(readRegularBounded(file, `${TRANSACTION_NAME}/${OPERATION_FILE}`), `${TRANSACTION_NAME}/${OPERATION_FILE}`);
-  const registry = new VnextSchemaRegistry(schemasDir);
+  const registry = new KxmSchemaRegistry(schemasDir);
   const issues = registry.validateInitOperation(value, `${TRANSACTION_NAME}/${OPERATION_FILE}`);
-  if (issues.length > 0) throw new VnextConfigError(issues);
-  const operation = value as unknown as VnextInitOperation;
+  if (issues.length > 0) throw new KxmConfigError(issues);
+  const operation = value as unknown as KxmInitOperation;
   if (!sameHostPath(operation.projectRoot, projectRoot)) fail("init_transaction_project_mismatch", TRANSACTION_NAME, "operation belongs to a different project root");
   const expectedPlanSha = operationPlanSha(operation);
   if (operation.planSha256 !== expectedPlanSha) fail("init_transaction_plan_hash_invalid", TRANSACTION_NAME, "operation plan hash does not match its immutable intent");
@@ -469,7 +469,7 @@ function readOperation(projectRoot: string, schemasDir?: string): VnextInitOpera
   return operation;
 }
 
-export function hasVnextInitTransaction(projectRoot: string): boolean {
+export function hasKxmInitTransaction(projectRoot: string): boolean {
   return existsSync(transactionRoot(projectRoot));
 }
 
@@ -484,12 +484,12 @@ function writeTarget(projectRoot: string, path: string, bytes: Buffer): void {
   writeDurableNew(file, bytes, 0o600);
 }
 
-function writeAndVerifyBackups(projectRoot: string, operation: VnextInitOperation): void {
+function writeAndVerifyBackups(projectRoot: string, operation: KxmInitOperation): void {
   if (operation.kind !== "repair") return;
   for (const entry of operation.files) {
     if (entry.observedSha256 === null) continue;
     const current = readOptionalManaged(projectRoot, entry.path);
-    if (!current || vnextContentSha256(current) !== entry.observedSha256) {
+    if (!current || kxmContentSha256(current) !== entry.observedSha256) {
       fail("repair_preimage_changed", entry.path, "destination changed before transaction preparation; local bytes were preserved");
     }
     const file = backupFile(projectRoot, entry.path);
@@ -498,14 +498,14 @@ function writeAndVerifyBackups(projectRoot: string, operation: VnextInitOperatio
   }
 }
 
-function writeKnownBackups(projectRoot: string, operation: VnextInitOperation): void {
+function writeKnownBackups(projectRoot: string, operation: KxmInitOperation): void {
   if (operation.kind !== "repair" || !operation.sourceTemplateRevision) return;
   const source = rendererForRevision(operation, operation.sourceTemplateRevision);
   if (!source) fail("init_transaction_source_unknown", TRANSACTION_NAME, "operation source is not a supported built-in template");
   for (const entry of operation.files) {
     if (entry.observedSha256 === null) continue;
     const bytes = source.files.get(entry.path);
-    if (!bytes || vnextContentSha256(bytes) !== entry.observedSha256) {
+    if (!bytes || kxmContentSha256(bytes) !== entry.observedSha256) {
       fail("init_transaction_backup_source_invalid", entry.path, "supported source template cannot reproduce the pinned preimage");
     }
     const file = backupFile(projectRoot, entry.path);
@@ -514,29 +514,29 @@ function writeKnownBackups(projectRoot: string, operation: VnextInitOperation):
   }
 }
 
-function verifyBackups(projectRoot: string, operation: VnextInitOperation): void {
+function verifyBackups(projectRoot: string, operation: KxmInitOperation): void {
   if (operation.kind !== "repair") return;
   for (const entry of operation.files) {
     if (entry.observedSha256 === null) continue;
     const bytes = readOptionalManaged(join(transactionRoot(projectRoot), "backups"), entry.path);
-    if (!bytes || vnextContentSha256(bytes) !== entry.observedSha256) {
+    if (!bytes || kxmContentSha256(bytes) !== entry.observedSha256) {
       fail("init_transaction_backup_invalid", entry.path, "pinned preimage backup is missing or corrupt");
     }
   }
 }
 
-function verifyTargetArtifacts(projectRoot: string, operation: VnextInitOperation): void {
+function verifyTargetArtifacts(projectRoot: string, operation: KxmInitOperation): void {
   let total = 0;
   for (const entry of operation.files) {
     const bytes = readTarget(projectRoot, entry.path);
     if (!bytes) fail("init_transaction_target_missing", entry.path, "pinned target artifact is missing");
     total += bytes.byteLength;
-    if (vnextContentSha256(bytes) !== entry.targetSha256) fail("init_transaction_target_mismatch", entry.path, "pinned target artifact hash does not match the operation");
+    if (kxmContentSha256(bytes) !== entry.targetSha256) fail("init_transaction_target_mismatch", entry.path, "pinned target artifact hash does not match the operation");
   }
   if (operation.files.length > MAX_MANAGED_FILES || total > MAX_MANAGED_TOTAL_BYTES) fail("init_transaction_bounds_exceeded", TRANSACTION_NAME, "operation exceeds bounded file or byte limits", "parse");
 }
 
-function loaderOptions(options: VnextRepairRuntimeOptions): VnextConfigOptions {
+function loaderOptions(options: KxmRepairRuntimeOptions): KxmConfigOptions {
   assertNoRegisteredGates(options);
   return {
     ...(options.schemasDir === undefined ? {} : { schemasDir: options.schemasDir }),
@@ -550,7 +550,7 @@ function sourceConfigFiles(projectRoot: string): string[] {
   const fixed = [
     ".kxm/project.yaml",
     ".kxm/gates.yaml",
-    VNEXT_TEMPLATE_PROVENANCE_PATH,
+    KXM_TEMPLATE_PROVENANCE_PATH,
     ".kxm/project/env.yaml",
     ".kxm/repo/repo.yaml",
     ".kxm/repo/env.yaml",
@@ -587,7 +587,7 @@ function absoluteMemberBindings(projectRoot: string, project: JsonObject, explic
   return bindings;
 }
 
-function prepareShadow(projectRoot: string, operation: VnextInitOperation, options: VnextRepairRuntimeOptions): void {
+function prepareShadow(projectRoot: string, operation: KxmInitOperation, options: KxmRepairRuntimeOptions): void {
   const shadow = shadowRoot(projectRoot);
   mkdirSync(shadow, { recursive: true, mode: 0o700 });
   let total = 0;
@@ -613,20 +613,20 @@ function prepareShadow(projectRoot: string, operation: VnextInitOperation, optio
   }
   const project = parseRestrictedYaml(readFileSync(join(shadow, ".kxm", "project.yaml")), ".kxm/project.yaml");
   const bound = absoluteMemberBindings(projectRoot, project, options.repositoryBindings);
-  loadVnextProject(shadow, { ...loaderOptions(options), repositoryBindings: bound });
+  loadKxmProject(shadow, { ...loaderOptions(options), repositoryBindings: bound });
   const provenance = readProjectAndProvenance(shadow, options.schemasDir)?.provenance;
   if (!provenance || provenance.templateRevision !== operation.targetTemplateRevision) {
-    fail("repair_shadow_provenance_invalid", VNEXT_TEMPLATE_PROVENANCE_PATH, "prospective template provenance does not match the pinned target");
+    fail("repair_shadow_provenance_invalid", KXM_TEMPLATE_PROVENANCE_PATH, "prospective template provenance does not match the pinned target");
   }
 }
 
 function createOperation(
   projectRoot: string,
   kind: "create" | "repair",
-  rendered: VnextRenderedTemplate,
-  files: readonly VnextInitOperationFile[],
+  rendered: KxmRenderedTemplate,
+  files: readonly KxmInitOperationFile[],
   sourceTemplateRevision: string | null,
-): VnextInitOperation {
+): KxmInitOperation {
   const root = resolve(projectRoot);
   const operationWithoutHash = {
     schema: "kxm.init-operation.v1" as const,
@@ -635,7 +635,7 @@ function createOperation(
     projectRoot: root,
     projectId: rendered.projectId,
     projectName: rendered.projectName,
-    templateId: VNEXT_TEMPLATE_ID as typeof VNEXT_TEMPLATE_ID,
+    templateId: KXM_TEMPLATE_ID as typeof KXM_TEMPLATE_ID,
     sourceTemplateRevision,
     targetTemplateRevision: rendered.templateRevision,
     files: [...files].sort((left, right) => compareCodeUnits(left.path, right.path)),
@@ -647,19 +647,19 @@ function createOperation(
   };
 }
 
-function validateOperationRecord(operation: VnextInitOperation, schemasDir?: string): void {
+function validateOperationRecord(operation: KxmInitOperation, schemasDir?: string): void {
   const label = `${TRANSACTION_NAME}/${OPERATION_FILE}`;
   const value = parseRestrictedYaml(Buffer.from(JSON.stringify(operation), "utf8"), label);
-  const issues = new VnextSchemaRegistry(schemasDir).validateInitOperation(value, label);
-  if (issues.length > 0) throw new VnextConfigError(issues);
+  const issues = new KxmSchemaRegistry(schemasDir).validateInitOperation(value, label);
+  if (issues.length > 0) throw new KxmConfigError(issues);
 }
 
 function prepareOperation(
   projectRoot: string,
-  operation: VnextInitOperation,
-  rendered: VnextRenderedTemplate,
-  options: VnextRepairRuntimeOptions,
-): VnextInitOperation {
+  operation: KxmInitOperation,
+  rendered: KxmRenderedTemplate,
+  options: KxmRepairRuntimeOptions,
+): KxmInitOperation {
   const transaction = transactionRoot(projectRoot);
   validateOperationRecord(operation, options.schemasDir);
   validateOperationIntent(projectRoot, operation);
@@ -670,7 +670,7 @@ function prepareOperation(
   try {
     for (const entry of operation.files) {
       const bytes = rendered.files.get(entry.path);
-      if (!bytes || vnextContentSha256(bytes) !== entry.targetSha256) fail("template_target_unavailable", entry.path, "renderer cannot reproduce the pinned target bytes");
+      if (!bytes || kxmContentSha256(bytes) !== entry.targetSha256) fail("template_target_unavailable", entry.path, "renderer cannot reproduce the pinned target bytes");
       writeTarget(projectRoot, entry.path, bytes);
     }
     writeAndVerifyBackups(projectRoot, operation);
@@ -700,7 +700,7 @@ function ensureDestinationParents(projectRoot: string, path: string): void {
 function destinationSha(projectRoot: string, path: string): string | undefined {
   const file = join(projectRoot, ...path.split("/"));
   if (!existsSync(file)) return undefined;
-  return vnextContentSha256(readRegularBounded(file, path));
+  return kxmContentSha256(readRegularBounded(file, path));
 }
 
 function requireConditionalLinkSupport(directory: string, operationId: string, path: string): void {
@@ -718,17 +718,17 @@ function requireConditionalLinkSupport(directory: string, operationId: string, p
   }
 }
 
-function atomicInstallTarget(projectRoot: string, operation: VnextInitOperation, entry: VnextInitOperationFile): void {
+function atomicInstallTarget(projectRoot: string, operation: KxmInitOperation, entry: KxmInitOperationFile): void {
   const destination = join(projectRoot, ...entry.path.split("/"));
   ensureDestinationParents(projectRoot, entry.path);
   const directory = dirname(destination);
   const temporaryPrefix = `.kxm-repair-${operation.operationId}-`;
-  const pathKey = vnextContentSha256(entry.path).slice("sha256:".length, "sha256:".length + 16);
+  const pathKey = kxmContentSha256(entry.path).slice("sha256:".length, "sha256:".length + 16);
   const displaced = join(directory, `${temporaryPrefix}${pathKey}.preimage`);
   if (existsSync(displaced)) {
     const stat = lstatSync(displaced);
     if (stat.isSymbolicLink() || !stat.isFile()) fail("repair_preimage_temporary_invalid", entry.path, "stale displaced preimage is not a regular file", "path");
-    if (entry.observedSha256 === null || vnextContentSha256(readFileSync(displaced)) !== entry.observedSha256) {
+    if (entry.observedSha256 === null || kxmContentSha256(readFileSync(displaced)) !== entry.observedSha256) {
       fail("repair_preimage_temporary_mismatch", entry.path, "stale displaced preimage does not match the pinned operation");
     }
     if (!existsSync(destination)) {
@@ -762,7 +762,7 @@ function atomicInstallTarget(projectRoot: string, operation: VnextInitOperation,
     if (entry.observedSha256 !== null) {
       renameSync(destination, displaced);
       syncDirectory(directory);
-      if (vnextContentSha256(readFileSync(displaced)) !== entry.observedSha256) {
+      if (kxmContentSha256(readFileSync(displaced)) !== entry.observedSha256) {
         if (!existsSync(destination)) {
           try { linkSync(displaced, destination); }
           catch { fail("repair_preimage_restore_blocked", entry.path, "changed destination was displaced but could not be conditionally restored; its bytes remain in the operation preimage file"); }
@@ -795,7 +795,7 @@ function atomicInstallTarget(projectRoot: string, operation: VnextInitOperation,
   if (destinationSha(projectRoot, entry.path) !== entry.targetSha256) fail("repair_install_verification_failed", entry.path, "installed target hash does not match the pinned operation");
 }
 
-function installedCreateMatches(projectRoot: string, operation: VnextInitOperation): boolean {
+function installedCreateMatches(projectRoot: string, operation: KxmInitOperation): boolean {
   const configRoot = join(projectRoot, ".kxm");
   if (!existsSync(configRoot)) return false;
   const actual: string[] = [];
@@ -833,7 +833,7 @@ function syncTreeDirectories(root: string): void {
   for (const directory of directories.reverse()) syncDirectory(directory);
 }
 
-function rebuildCreateShadow(projectRoot: string, operation: VnextInitOperation, options: VnextRepairRuntimeOptions): void {
+function rebuildCreateShadow(projectRoot: string, operation: KxmInitOperation, options: KxmRepairRuntimeOptions): void {
   const shadow = shadowRoot(projectRoot);
   rmSync(shadow, { recursive: true, force: true });
   prepareShadow(projectRoot, operation, options);
@@ -846,10 +846,10 @@ function rebuildCreateShadow(projectRoot: string, operation: VnextInitOperation,
 
 function applyOperation(
   projectRoot: string,
-  original: VnextInitOperation,
-  options: VnextRepairRuntimeOptions,
+  original: KxmInitOperation,
+  options: KxmRepairRuntimeOptions,
   resumed: boolean,
-): VnextOperationResult {
+): KxmOperationResult {
   assertNoRegisteredGates(options);
   let operation = original;
   const effectiveOptions = options;
@@ -866,23 +866,23 @@ function applyOperation(
       fail("create_resume_conflict", ".kxm", "existing project configuration does not match the pinned create operation");
     }
   } else {
-    const resources = operation.files.filter((entry) => entry.path !== VNEXT_TEMPLATE_PROVENANCE_PATH && entry.action !== "none");
+    const resources = operation.files.filter((entry) => entry.path !== KXM_TEMPLATE_PROVENANCE_PATH && entry.action !== "none");
     let installed = 0;
     for (const entry of resources) {
       atomicInstallTarget(projectRoot, operation, entry);
       installed += 1;
       if (installed === 1 && options.testFaultAt === "first-resource") throw new Error("injected init fault after first resource");
     }
-    loadVnextProject(projectRoot, loaderOptions(effectiveOptions));
-    const provenance = operation.files.find((entry) => entry.path === VNEXT_TEMPLATE_PROVENANCE_PATH);
+    loadKxmProject(projectRoot, loaderOptions(effectiveOptions));
+    const provenance = operation.files.find((entry) => entry.path === KXM_TEMPLATE_PROVENANCE_PATH);
     if (!provenance) fail("repair_provenance_target_missing", TRANSACTION_NAME, "repair operation has no final provenance target");
     atomicInstallTarget(projectRoot, operation, provenance);
     if (options.testFaultAt === "provenance") throw new Error("injected init fault after provenance");
   }
-  const bundle = loadVnextProject(projectRoot, loaderOptions(effectiveOptions));
+  const bundle = loadKxmProject(projectRoot, loaderOptions(effectiveOptions));
   const source = readProjectAndProvenance(projectRoot, effectiveOptions.schemasDir);
   if (!source || source.provenance.templateRevision !== operation.targetTemplateRevision) {
-    fail("init_operation_verification_failed", VNEXT_TEMPLATE_PROVENANCE_PATH, "installed provenance does not match the pinned transaction");
+    fail("init_operation_verification_failed", KXM_TEMPLATE_PROVENANCE_PATH, "installed provenance does not match the pinned transaction");
   }
   operation = updatePhase(projectRoot, operation, "verified");
   if (options.testFaultAt === "verified") throw new Error("injected init fault after verification");
@@ -891,16 +891,16 @@ function applyOperation(
   return { kind: operation.kind, resumed, bundle, files };
 }
 
-export function prepareAndApplyVnextCreate(
+export function prepareAndApplyKxmCreate(
   projectRoot: string,
-  rendered: VnextRenderedTemplate,
-  options: VnextRepairRuntimeOptions = {},
-): VnextOperationResult {
+  rendered: KxmRenderedTemplate,
+  options: KxmRepairRuntimeOptions = {},
+): KxmOperationResult {
   assertNoRegisteredGates(options);
-  const files = [...rendered.files.entries()].map(([path, bytes]): VnextInitOperationFile => ({
+  const files = [...rendered.files.entries()].map(([path, bytes]): KxmInitOperationFile => ({
     path,
     observedSha256: null,
-    targetSha256: vnextContentSha256(bytes),
+    targetSha256: kxmContentSha256(bytes),
     classification: "template-only",
     action: "create",
   }));
@@ -910,20 +910,20 @@ export function prepareAndApplyVnextCreate(
   return applyOperation(projectRoot, prepared, options, false);
 }
 
-export function prepareAndApplyVnextRepair(
-  plan: VnextTemplateRepairPlan,
-  options: VnextRepairRuntimeOptions = {},
-): VnextOperationResult {
+export function prepareAndApplyKxmRepair(
+  plan: KxmTemplateRepairPlan,
+  options: KxmRepairRuntimeOptions = {},
+): KxmOperationResult {
   assertNoRegisteredGates(options);
   if (!plan.canApply) fail("template_repair_not_applicable", ".kxm", "template repair has conflicts, policy changes, or no safe template-only update");
-  const rendered = renderVnextTemplate(plan.projectId, plan.projectName, options.templateVariant ?? CURRENT_VNEXT_TEMPLATE_VARIANT);
+  const rendered = renderKxmTemplate(plan.projectId, plan.projectName, options.templateVariant ?? CURRENT_KXM_TEMPLATE_VARIANT);
   if (rendered.templateRevision !== plan.targetTemplateRevision) fail("template_repair_target_changed", ".kxm", "template target changed after planning");
   const actionable = plan.changes.filter((change) => change.classification === "template-only");
-  const provenanceBytes = rendered.files.get(VNEXT_TEMPLATE_PROVENANCE_PATH);
-  if (!provenanceBytes) fail("template_provenance_target_missing", VNEXT_TEMPLATE_PROVENANCE_PATH, "renderer did not produce provenance");
-  const sourceProvenance = readOptionalManaged(plan.projectRoot, VNEXT_TEMPLATE_PROVENANCE_PATH);
-  if (!sourceProvenance) fail("template_provenance_missing", VNEXT_TEMPLATE_PROVENANCE_PATH, "repair requires recorded provenance");
-  const files: VnextInitOperationFile[] = actionable.map((change) => ({
+  const provenanceBytes = rendered.files.get(KXM_TEMPLATE_PROVENANCE_PATH);
+  if (!provenanceBytes) fail("template_provenance_target_missing", KXM_TEMPLATE_PROVENANCE_PATH, "renderer did not produce provenance");
+  const sourceProvenance = readOptionalManaged(plan.projectRoot, KXM_TEMPLATE_PROVENANCE_PATH);
+  if (!sourceProvenance) fail("template_provenance_missing", KXM_TEMPLATE_PROVENANCE_PATH, "repair requires recorded provenance");
+  const files: KxmInitOperationFile[] = actionable.map((change) => ({
     path: change.path,
     observedSha256: change.localSha256 ?? null,
     targetSha256: change.targetSha256 as string,
@@ -931,9 +931,9 @@ export function prepareAndApplyVnextRepair(
     action: change.action,
   }));
   files.push({
-    path: VNEXT_TEMPLATE_PROVENANCE_PATH,
-    observedSha256: vnextContentSha256(sourceProvenance),
-    targetSha256: vnextContentSha256(provenanceBytes),
+    path: KXM_TEMPLATE_PROVENANCE_PATH,
+    observedSha256: kxmContentSha256(sourceProvenance),
+    targetSha256: kxmContentSha256(provenanceBytes),
     classification: "template-only",
     action: "replace",
   });
@@ -943,20 +943,20 @@ export function prepareAndApplyVnextRepair(
   return applyOperation(plan.projectRoot, prepared, options, false);
 }
 
-function rendererForRevision(operation: VnextInitOperation, revision: string): VnextRenderedTemplate | undefined {
-  for (const variant of SUPPORTED_VNEXT_TEMPLATE_VARIANTS) {
-    const rendered = renderVnextTemplate(operation.projectId, operation.projectName, variant);
+function rendererForRevision(operation: KxmInitOperation, revision: string): KxmRenderedTemplate | undefined {
+  for (const variant of SUPPORTED_KXM_TEMPLATE_VARIANTS) {
+    const rendered = renderKxmTemplate(operation.projectId, operation.projectName, variant);
     if (rendered.templateRevision === revision) return rendered;
   }
   return undefined;
 }
 
-function rendererForOperation(operation: VnextInitOperation): VnextRenderedTemplate | undefined {
+function rendererForOperation(operation: KxmInitOperation): KxmRenderedTemplate | undefined {
   return rendererForRevision(operation, operation.targetTemplateRevision);
 }
 
 /** Re-derive every executable operation field from immutable built-in templates. */
-function validateOperationIntent(projectRoot: string, operation: VnextInitOperation): void {
+function validateOperationIntent(projectRoot: string, operation: KxmInitOperation): void {
   const target = rendererForOperation(operation);
   if (!target) fail("init_transaction_target_unknown", TRANSACTION_NAME, "operation target is not a supported built-in template");
   const entries = new Map(operation.files.map((entry) => [entry.path, entry]));
@@ -969,7 +969,7 @@ function validateOperationIntent(projectRoot: string, operation: VnextInitOperat
       const entry = entries.get(path);
       if (!entry
         || entry.observedSha256 !== null
-        || entry.targetSha256 !== vnextContentSha256(bytes)
+        || entry.targetSha256 !== kxmContentSha256(bytes)
         || entry.classification !== "template-only"
         || entry.action !== "create") {
         fail("init_transaction_create_file_invalid", path, "create operation file does not match its built-in target");
@@ -997,18 +997,18 @@ function validateOperationIntent(projectRoot: string, operation: VnextInitOperat
     }
     if (base.sha256 !== next.sha256) safeChangedPaths.push(path);
   }
-  const provenanceEntry = entries.get(VNEXT_TEMPLATE_PROVENANCE_PATH);
-  const sourceProvenanceBytes = source.files.get(VNEXT_TEMPLATE_PROVENANCE_PATH) as Buffer;
-  const targetProvenanceBytes = target.files.get(VNEXT_TEMPLATE_PROVENANCE_PATH) as Buffer;
+  const provenanceEntry = entries.get(KXM_TEMPLATE_PROVENANCE_PATH);
+  const sourceProvenanceBytes = source.files.get(KXM_TEMPLATE_PROVENANCE_PATH) as Buffer;
+  const targetProvenanceBytes = target.files.get(KXM_TEMPLATE_PROVENANCE_PATH) as Buffer;
   if (!provenanceEntry
-    || provenanceEntry.observedSha256 !== vnextContentSha256(sourceProvenanceBytes)
-    || provenanceEntry.targetSha256 !== vnextContentSha256(targetProvenanceBytes)
+    || provenanceEntry.observedSha256 !== kxmContentSha256(sourceProvenanceBytes)
+    || provenanceEntry.targetSha256 !== kxmContentSha256(targetProvenanceBytes)
     || provenanceEntry.classification !== "template-only"
     || provenanceEntry.action !== "replace") {
-    fail("init_transaction_provenance_intent_invalid", VNEXT_TEMPLATE_PROVENANCE_PATH, "repair provenance action does not match supported source and target templates");
+    fail("init_transaction_provenance_intent_invalid", KXM_TEMPLATE_PROVENANCE_PATH, "repair provenance action does not match supported source and target templates");
   }
   for (const [path, entry] of entries) {
-    if (path === VNEXT_TEMPLATE_PROVENANCE_PATH) continue;
+    if (path === KXM_TEMPLATE_PROVENANCE_PATH) continue;
     const base = sourceRecords.get(path);
     const next = targetRecords.get(path);
     if (!base || !next || base.sha256 === next.sha256
@@ -1028,9 +1028,9 @@ function validateOperationIntent(projectRoot: string, operation: VnextInitOperat
 
 function finishPreparingOperation(
   projectRoot: string,
-  operation: VnextInitOperation,
-  options: VnextRepairRuntimeOptions,
-): VnextInitOperation {
+  operation: KxmInitOperation,
+  options: KxmRepairRuntimeOptions,
+): KxmInitOperation {
   const rendered = rendererForOperation(operation);
   if (!rendered) fail("init_transaction_renderer_unavailable", TRANSACTION_NAME, "this binary cannot reproduce the pinned pre-application target");
   for (const directory of ["targets", "backups", "shadow"]) {
@@ -1038,7 +1038,7 @@ function finishPreparingOperation(
   }
   for (const entry of operation.files) {
     const bytes = rendered.files.get(entry.path);
-    if (!bytes || vnextContentSha256(bytes) !== entry.targetSha256) fail("template_target_unavailable", entry.path, "renderer cannot reproduce the pinned target bytes");
+    if (!bytes || kxmContentSha256(bytes) !== entry.targetSha256) fail("template_target_unavailable", entry.path, "renderer cannot reproduce the pinned target bytes");
     writeTarget(projectRoot, entry.path, bytes);
   }
   writeKnownBackups(projectRoot, operation);
@@ -1050,10 +1050,10 @@ function finishPreparingOperation(
 }
 
 /** Resume only a validated fixed transaction; filesystem truth wins over its phase hint. */
-export function resumeVnextInitTransaction(
+export function resumeKxmInitTransaction(
   projectRoot: string,
-  options: VnextRepairRuntimeOptions = {},
-): VnextOperationResult | undefined {
+  options: KxmRepairRuntimeOptions = {},
+): KxmOperationResult | undefined {
   assertNoRegisteredGates(options);
   let operation = readOperation(projectRoot, options.schemasDir);
   if (!operation) {
@@ -1070,7 +1070,7 @@ export function resumeVnextInitTransaction(
 }
 
 /** Remove a verified transaction only after associated local binding intent is durable. */
-export function commitVnextInitTransaction(projectRoot: string, schemasDir?: string): void {
+export function commitKxmInitTransaction(projectRoot: string, schemasDir?: string): void {
   const operation = readOperation(projectRoot, schemasDir);
   if (!operation || operation.phase !== "verified") {
     fail("init_transaction_not_verified", TRANSACTION_NAME, "initialization transaction cannot commit before installed state is verified");
@@ -1084,7 +1084,7 @@ export function commitVnextInitTransaction(projectRoot: string, schemasDir?: str
 }
 
 /** Validate a pending transaction for dry-run reporting without writing or cleanup. */
-export function inspectVnextInitTransaction(projectRoot: string, schemasDir?: string): VnextInitOperation | undefined {
+export function inspectKxmInitTransaction(projectRoot: string, schemasDir?: string): KxmInitOperation | undefined {
   const operation = readOperation(projectRoot, schemasDir);
   if (operation && operation.phase !== "preparing") {
     verifyTargetArtifacts(projectRoot, operation);