@kontextmind/kxm 0.7.39 → 0.7.43

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

@@ -3,25 +3,25 @@ import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, open
 import { join, resolve } from "node:path";
 import { stringify } from "yaml";
 import {
-  VnextConfigError,
-  VnextSchemaRegistry,
+  KxmConfigError,
+  KxmSchemaRegistry,
   discoverGitRoot,
   legacyConfigFilesAt,
-  loadVnextProject,
+  loadKxmProject,
   migrationReceiptSelfHash,
   parseRestrictedYaml,
-  readVnextMigrationReceipt,
-  validateVnextResources,
-  verifyVnextMigrationReceiptTarget,
-  vnextCanonicalJson,
-  VNEXT_MIGRATION_RECEIPT_PATH,
+  readKxmMigrationReceipt,
+  validateKxmResources,
+  verifyKxmMigrationReceiptTarget,
+  kxmCanonicalJson,
+  KXM_MIGRATION_RECEIPT_PATH,
   type JsonObject,
   type JsonValue,
-  type VnextConfigIssue,
-  type VnextConfigOptions,
-  type VnextResourceKind,
-} from "./vnext-config.ts";
-import { withVnextLocalBindingLock, type VnextLocalBindingLock, type VnextLocalBindingStoreOptions } from "./vnext-bindings.ts";
+  type KxmConfigIssue,
+  type KxmConfigOptions,
+  type KxmResourceKind,
+} from "./project-config.ts";
+import { withKxmLocalBindingLock, type KxmLocalBindingLock, type KxmLocalBindingStoreOptions } from "./bindings.ts";
 
 /* ------------------------------------------------------------------ *
  * Bounded legacy JSON reading (duplicate keys rejected, depth bounded)
@@ -32,12 +32,12 @@ const MAX_LEGACY_JSON_DEPTH = 32;
 const MAX_LEGACY_JSON_NODES = 32_768;
 const MAX_LEGACY_SOURCES = 64;
 
-function migrateIssue(phase: VnextConfigIssue["phase"], code: string, file: string, message: string): VnextConfigIssue {
+function migrateIssue(phase: KxmConfigIssue["phase"], code: string, file: string, message: string): KxmConfigIssue {
   return { phase, code, file, message };
 }
 
 function migrateFail(code: string, file: string, message: string): never {
-  throw new VnextConfigError([migrateIssue("parse", code, file, message)]);
+  throw new KxmConfigError([migrateIssue("parse", code, file, message)]);
 }
 
 /** JSON.parse with duplicate-key rejection and structural bounds. */
@@ -168,7 +168,7 @@ function detectDuplicateKeys(text: string, label: string): void {
  * Legacy source model
  * ------------------------------------------------------------------ */
 
-export interface VnextLegacySource {
+export interface KxmLegacySource {
   path: string;
   sha256: string;
   bytes: number;
@@ -180,23 +180,23 @@ function sha256Of(input: string | Uint8Array): string {
 }
 
 /** Read every legacy configuration file with bounds and exact duplicate-key rejection. */
-export function readVnextLegacySources(root: string): VnextLegacySource[] {
+export function readKxmLegacySources(root: string): KxmLegacySource[] {
   const files = legacyConfigFilesAt(root);
   if (files.length > MAX_LEGACY_SOURCES) {
-    throw new VnextConfigError([migrateIssue("discovery", "legacy_source_limit", ".kxm/config", `legacy configuration exceeds ${MAX_LEGACY_SOURCES} files`)]);
+    throw new KxmConfigError([migrateIssue("discovery", "legacy_source_limit", ".kxm/config", `legacy configuration exceeds ${MAX_LEGACY_SOURCES} files`)]);
   }
   return files.map((path) => {
     const absolute = join(root, ...path.split("/"));
     const stat = lstatSync(absolute);
     if (stat.isSymbolicLink() || !stat.isFile()) {
-      throw new VnextConfigError([migrateIssue("path", "legacy_source_invalid", path, "legacy configuration must be a regular file, not a link")]);
+      throw new KxmConfigError([migrateIssue("path", "legacy_source_invalid", path, "legacy configuration must be a regular file, not a link")]);
     }
     const buffer = readFileSync(absolute);
     let text: string;
     try {
       text = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
     } catch {
-      throw new VnextConfigError([migrateIssue("parse", "invalid_utf8", path, "document is not valid UTF-8")]);
+      throw new KxmConfigError([migrateIssue("parse", "invalid_utf8", path, "document is not valid UTF-8")]);
     }
     return {
       path,
@@ -207,8 +207,8 @@ export function readVnextLegacySources(root: string): VnextLegacySource[] {
   });
 }
 
-export function legacySourceDigest(sources: readonly VnextLegacySource[]): string {
-  return sha256Of(vnextCanonicalJson(sources.map((source) => ({ path: source.path, sha256: source.sha256, bytes: source.bytes }))));
+export function legacySourceDigest(sources: readonly KxmLegacySource[]): string {
+  return sha256Of(kxmCanonicalJson(sources.map((source) => ({ path: source.path, sha256: source.sha256, bytes: source.bytes }))));
 }
 
 /* ------------------------------------------------------------------ *
@@ -227,7 +227,7 @@ const KNOWN_STAGE_FIELDS = new Set(["id", "label", "instructions", "requiredEvid
 const KNOWN_POLICY_FIELDS = new Set(["kind", "minProducers", "eligibleAgents", "acceptedStatuses", "degradation"]);
 const KNOWN_TRANSITION_FIELDS = new Set(["target", "maxTransitions"]);
 
-export interface VnextMigrationAmbiguity {
+export interface KxmMigrationAmbiguity {
   key: string;
   category: "unsupported" | "identity" | "step-kind" | "terminal-status" | "transition-budget" | "evidence-policy" | "permission" | "secret-reference";
   sourcePath: string;
@@ -235,20 +235,20 @@ export interface VnextMigrationAmbiguity {
   allowedValues: readonly (string | number)[];
 }
 
-export interface VnextMigrationUnmapped {
+export interface KxmMigrationUnmapped {
   sourcePath: string;
   jsonPointer: string;
   valueSha256: string;
   sensitive: boolean;
 }
 
-export interface VnextMigrationRename {
+export interface KxmMigrationRename {
   from: string;
   to: string;
   kind: "agent" | "model" | "workflow" | "step" | "evidence" | "outcome";
 }
 
-export interface VnextMigrationPermissionChange {
+export interface KxmMigrationPermissionChange {
   sourcePath: string;
   targetPath: string;
   direction: "narrowing" | "expansion" | "unknown";
@@ -257,13 +257,13 @@ export interface VnextMigrationPermissionChange {
 }
 
 interface MutablePlan {
-  ambiguities: VnextMigrationAmbiguity[];
+  ambiguities: KxmMigrationAmbiguity[];
   invalidDecisions: string[];
   decisionKeys: Set<string>;
   decisionAllowedValues: Map<string, readonly (string | number)[]>;
-  unmapped: VnextMigrationUnmapped[];
-  renames: VnextMigrationRename[];
-  permissionChanges: VnextMigrationPermissionChange[];
+  unmapped: KxmMigrationUnmapped[];
+  renames: KxmMigrationRename[];
+  permissionChanges: KxmMigrationPermissionChange[];
 }
 
 function compareCodeUnits(left: string, right: string): number {
@@ -317,12 +317,12 @@ function recordUnmapped(plan: MutablePlan, sourcePath: string, pointer: string,
   // not be recoverable by offline guessing against a committed plan. Record
   // only the serialized byte length as proof something was dropped.
   const digestInput = sensitive
-    ? { redacted: true, bytes: Buffer.byteLength(vnextCanonicalJson(value === undefined ? null : value), "utf8") }
+    ? { redacted: true, bytes: Buffer.byteLength(kxmCanonicalJson(value === undefined ? null : value), "utf8") }
     : (value === undefined ? null : value);
   plan.unmapped.push({
     sourcePath,
     jsonPointer: pointer,
-    valueSha256: sha256Of(vnextCanonicalJson(digestInput)),
+    valueSha256: sha256Of(kxmCanonicalJson(digestInput)),
     sensitive,
   });
 }
@@ -348,7 +348,7 @@ function mapIdentity(
   plan: MutablePlan,
   sourcePath: string,
   raw: string,
-  kind: VnextMigrationRename["kind"],
+  kind: KxmMigrationRename["kind"],
   taken: Map<string, string>,
   decisions: Readonly<Record<string, JsonValue>>,
   dropPointer?: string,
@@ -387,7 +387,7 @@ function mapIdentity(
       `identity:${kind}:${keyFragment(raw)}`,
       "identity",
       sourcePath,
-      `${kind} name ${JSON.stringify(elide(raw, 200))} cannot be normalized to a vNext identifier; supply a decision with the target identifier`,
+      `${kind} name ${JSON.stringify(elide(raw, 200))} cannot be normalized to a KXM identifier; supply a decision with the target identifier`,
       ["<identifier>"],
       decisions,
     );
@@ -474,7 +474,7 @@ function decisionValueAllowed(key: string, value: JsonValue | undefined, allowed
 function resolveDecision(
   plan: MutablePlan,
   key: string,
-  category: VnextMigrationAmbiguity["category"],
+  category: KxmMigrationAmbiguity["category"],
   sourcePath: string,
   message: string,
   allowedValues: readonly (string | number)[],
@@ -510,7 +510,7 @@ interface ConvertedAgents {
 
 function convertAgentsRoster(
   plan: MutablePlan,
-  source: VnextLegacySource,
+  source: KxmLegacySource,
   decisions: Readonly<Record<string, JsonValue>>,
   agentNames: Map<string, string>,
 ): ConvertedAgents {
@@ -618,7 +618,7 @@ function convertAgentsRoster(
     }
     const thinking = asString(record.thinking);
     if (thinking) {
-      // vNext agents select models; thinking belongs to a model profile. Emit
+      // KXM agents select models; thinking belongs to a model profile. Emit
       // a per-agent profile when the model mapped cleanly.
       const selector = asObject(agent.model as JsonValue | undefined);
       if (selector && typeof selector.profile !== "string") {
@@ -662,7 +662,7 @@ const IMPLEMENTED_GATES = new Set(["test", "scm-delivery"]);
 
 function convertGatesRoster(
   plan: MutablePlan,
-  source: VnextLegacySource,
+  source: KxmLegacySource,
   decisions: Readonly<Record<string, JsonValue>>,
 ): void {
   const root = asObject(source.value);
@@ -696,7 +696,7 @@ function convertGatesRoster(
         `gate:${keyFragment(name)}`,
         "unsupported",
         source.path,
-        `gate ${JSON.stringify(elide(name, 200))} has no registered deterministic runner in vNext; it is preserved in the migration report only`,
+        `gate ${JSON.stringify(elide(name, 200))} has no registered deterministic runner in KXM; it is preserved in the migration report only`,
         ["report-only"],
         decisions,
       );
@@ -721,7 +721,7 @@ function mapStageRef(context: StageContext, raw: string): string {
 
 function convertTransition(
   plan: MutablePlan,
-  source: VnextLegacySource,
+  source: KxmLegacySource,
   context: StageContext,
   stageId: string,
   stageKey: string,
@@ -746,13 +746,13 @@ function convertTransition(
   const sourceIndex = context.stageIds.indexOf(stageId);
   if (target === "$terminal") {
     // Legacy $terminal always completes the run successfully regardless of
-    // outcome; vNext requires an explicit terminal status.
+    // outcome; KXM requires an explicit terminal status.
     const chosen = resolveDecision(
       plan,
       `terminal:${context.workflowKey}:${stageKey}:${outcome}`,
       "terminal-status",
       source.path,
-      `legacy transition ${context.workflowId}/${stageId} outcome ${outcome} ends the run; choose the vNext terminal status (legacy semantics completed the run even on failure outcomes)`,
+      `legacy transition ${context.workflowId}/${stageId} outcome ${outcome} ends the run; choose the KXM terminal status (legacy semantics completed the run even on failure outcomes)`,
       outcome === "passed" ? ["completed"] : ["completed", "failed", "cancelled"],
       decisions,
     );
@@ -803,7 +803,7 @@ function convertTransition(
       `backedge:${context.workflowKey}:${stageKey}:${outcome}`,
       "transition-budget",
       source.path,
-      `back-edge ${context.workflowId}/${stageId} -> ${targetId} (outcome ${outcome}) has no per-edge budget in legacy; vNext requires maxTransitions (1-100)`,
+      `back-edge ${context.workflowId}/${stageId} -> ${targetId} (outcome ${outcome}) has no per-edge budget in legacy; KXM requires maxTransitions (1-100)`,
       [2, 3, 4, 5],
       decisions,
     );
@@ -816,7 +816,7 @@ function convertTransition(
 
 function convertWorkflowFile(
   plan: MutablePlan,
-  source: VnextLegacySource,
+  source: KxmLegacySource,
   decisions: Readonly<Record<string, JsonValue>>,
   agentIds: ReadonlyMap<string, JsonObject>,
   agentRawNames: ReadonlyMap<string, string>,
@@ -847,7 +847,7 @@ function convertWorkflowFile(
       : `preview-${(normalizeIdentifier(rawId) || "unnamed").slice(0, 46).replace(/[-_]+$/u, "")}-${createHash("sha256").update(`${rawId}#${source.path}#${definitionIndex}`, "utf8").digest("hex").slice(0, 8)}`;
     const workflowKey = keyFragment(rawId);
 
-    // Hub/webhook-specific fields have no vNext workflow equivalent; the
+    // Hub/webhook-specific fields have no KXM workflow equivalent; the
     // trigger surface is a later phase. Record them (secrets hashed).
     for (const field of ["source", "project", "event", "filter", "delivery", "ttlMs", "promptTemplate"] as const) {
       if (definition[field] !== undefined) recordUnmapped(plan, source.path, `${basePointer}/${field}`, definition[field], false);
@@ -860,7 +860,7 @@ function convertWorkflowFile(
           `secret:${workflowKey}:${field}`,
           "secret-reference",
           source.path,
-          `workflow ${workflowId} field ${field} configures a webhook secret; vNext workflows never embed secrets — confirm the field is dropped and re-granted through scoped secret references when the trigger surface lands`,
+          `workflow ${workflowId} field ${field} configures a webhook secret; KXM workflows never embed secrets — confirm the field is dropped and re-granted through scoped secret references when the trigger surface lands`,
           ["drop"],
           decisions,
         );
@@ -986,7 +986,7 @@ function convertWorkflowFile(
           `instructions:${workflowKey}:${stepKey}`,
           "unsupported",
           source.path,
-          `stage ${stepId} has no instructions; vNext agent steps require executable instructions — confirm the stage is dropped`,
+          `stage ${stepId} has no instructions; KXM agent steps require executable instructions — confirm the stage is dropped`,
           ["drop"],
           decisions,
         );
@@ -1161,8 +1161,8 @@ function convertWorkflowFile(
               "evidence-policy",
               source.path,
               acceptedStatusesMalformed
-                ? `evidence policy ${policyKey} acceptedStatuses is malformed (not an array) and was preserved in the report; confirm mapping the policy to vNext 'passed'`
-                : `evidence policy ${policyKey} accepted statuses ${JSON.stringify(elide(accepted.map((candidate) => String(candidate)).join(","), 200))} cannot map losslessly; confirm mapping to vNext 'passed'`,
+                ? `evidence policy ${policyKey} acceptedStatuses is malformed (not an array) and was preserved in the report; confirm mapping the policy to KXM 'passed'`
+                : `evidence policy ${policyKey} accepted statuses ${JSON.stringify(elide(accepted.map((candidate) => String(candidate)).join(","), 200))} cannot map losslessly; confirm mapping to KXM 'passed'`,
               ["passed"],
               decisions,
             );
@@ -1183,7 +1183,7 @@ function convertWorkflowFile(
               sourcePath: source.path,
               targetPath: `.kxm/workflows/${workflowId}.yaml`,
               direction: "expansion",
-              summary: `step ${stepId}: assignment pool widens from the single legacy coordinator to coordinator plus evidence producers so vNext producer evidence stays in scope`,
+              summary: `step ${stepId}: assignment pool widens from the single legacy coordinator to coordinator plus evidence producers so KXM producer evidence stays in scope`,
               decisionKey: `evidence:${workflowKey}:${stepKey}:${policyKey}`,
             });
             resolveDecision(
@@ -1223,7 +1223,7 @@ function convertWorkflowFile(
       }
       if (requiredEvidence.length > 0) step.requiredEvidence = requiredEvidence;
       if (policyProducers.size > 0) {
-        // vNext evidence producers must execute within the step assignment
+        // KXM evidence producers must execute within the step assignment
         // pool: widen it beyond the legacy single-coordinator shape.
         const pool = [stepAgent, ...[...policyProducers].filter((candidate) => candidate !== stepAgent).sort(compareCodeUnits)];
         step.assignments = {
@@ -1246,7 +1246,7 @@ function convertWorkflowFile(
             continue;
           }
           if (seenOutcomes.has(outcome)) {
-            // Two legacy outcome keys normalize to the same vNext outcome;
+            // Two legacy outcome keys normalize to the same KXM outcome;
             // never merge their edges last-wins.
             recordUnmapped(plan, source.path, `${pointer}/on/${pointerEscape(rawOutcome)}`, rawTransition, false);
             continue;
@@ -1270,7 +1270,7 @@ function convertWorkflowFile(
       }
       step.on = transitions;
       if (typeof stage.maxTransitions === "number") {
-        // Legacy per-stage transition budgets have no vNext equivalent;
+        // Legacy per-stage transition budgets have no KXM equivalent;
         // per-edge budgets and the global limit cover the same bound.
         recordUnmapped(plan, source.path, `${pointer}/maxTransitions`, stage.maxTransitions, false);
       }
@@ -1302,7 +1302,7 @@ function convertWorkflowFile(
       recordUnmapped(plan, source.path, `${basePointer}/maxTransitions`, definition.maxTransitions, false);
     }
     if (workflow.limits === undefined) {
-      // vNext requires a global budget whenever any back-edge exists.
+      // KXM requires a global budget whenever any back-edge exists.
       const hasBackEdge = steps.some((step) => Object.values(asObject(step.on as JsonValue) ?? {}).some((rule) => {
         const target = typeof rule === "string" ? rule : asObject(rule)?.target;
         return typeof target === "string" && target !== "$terminal" && stageIds.indexOf(target) <= stageIds.indexOf(String(step.id));
@@ -1313,7 +1313,7 @@ function convertWorkflowFile(
           `budget:${workflowKey}`,
           "transition-budget",
           source.path,
-          `workflow ${workflowId} has back-edges but no legacy global maxTransitions; vNext requires limits.maxTransitions (1-1000)`,
+          `workflow ${workflowId} has back-edges but no legacy global maxTransitions; KXM requires limits.maxTransitions (1-1000)`,
           [28],
           decisions,
         );
@@ -1368,18 +1368,18 @@ function convertWorkflowFile(
 
 /* ------------------------- plan assembly -------------------------- */
 
-export interface VnextMigrationPlanResult {
+export interface KxmMigrationPlanResult {
   plan: JsonObject;
   resources: Map<string, JsonObject>;
-  ambiguities: readonly VnextMigrationAmbiguity[];
+  ambiguities: readonly KxmMigrationAmbiguity[];
   decisionKeys: ReadonlySet<string>;
   decisionAllowedValues: ReadonlyMap<string, readonly (string | number)[]>;
   invalidDecisions: readonly string[];
   decisions: Readonly<Record<string, JsonValue>>;
-  sources: readonly VnextLegacySource[];
+  sources: readonly KxmLegacySource[];
 }
 
-export interface VnextMigrationOptions extends VnextConfigOptions {
+export interface KxmMigrationOptions extends KxmConfigOptions {
   decisions?: Readonly<Record<string, JsonValue>>;
   projectId?: string;
   projectName?: string;
@@ -1395,18 +1395,18 @@ function sortedRecord<T>(map: ReadonlyMap<string, T>, prefix: string): Map<strin
 function migrationGitRoot(start: string): string {
   const root = discoverGitRoot(start);
   if (!root) {
-    throw new VnextConfigError([migrateIssue("discovery", "git_root_required", ".", "kxm migrate must run inside the authoritative Git worktree")]);
+    throw new KxmConfigError([migrateIssue("discovery", "git_root_required", ".", "kxm migrate must run inside the authoritative Git worktree")]);
   }
   return root;
 }
 
 /** Convert legacy configuration into a deterministic, schema-shaped migration plan. */
-export function planVnextMigration(projectRoot: string, options: VnextMigrationOptions = {}): VnextMigrationPlanResult {
+export function planKxmMigration(projectRoot: string, options: KxmMigrationOptions = {}): KxmMigrationPlanResult {
   const root = migrationGitRoot(projectRoot);
-  const registry = new VnextSchemaRegistry(options.schemasDir);
-  const sources = readVnextLegacySources(root);
+  const registry = new KxmSchemaRegistry(options.schemasDir);
+  const sources = readKxmLegacySources(root);
   if (sources.length === 0) {
-    throw new VnextConfigError([migrateIssue("discovery", "legacy_sources_missing", ".kxm/config", "no legacy configuration files found to migrate")]);
+    throw new KxmConfigError([migrateIssue("discovery", "legacy_sources_missing", ".kxm/config", "no legacy configuration files found to migrate")]);
   }
   const decisions = options.decisions ?? {};
   const plan: MutablePlan = { ambiguities: [], invalidDecisions: [], decisionKeys: new Set(), decisionAllowedValues: new Map(), unmapped: [], renames: [], permissionChanges: [] };
@@ -1449,11 +1449,11 @@ export function planVnextMigration(projectRoot: string, options: VnextMigrationO
 
   const projectId = options.projectId ?? `prj_mig${sha256Of(legacySourceDigest(sources)).slice(7, 39)}`;
   if (!PROJECT_ID.test(projectId)) {
-    throw new VnextConfigError([migrateIssue("semantic", "project_id_invalid", ".kxm/project.yaml", "project ID must satisfy the kxm.project.v1 opaque ID grammar and use the prj_ prefix")]);
+    throw new KxmConfigError([migrateIssue("semantic", "project_id_invalid", ".kxm/project.yaml", "project ID must satisfy the kxm.project.v1 opaque ID grammar and use the prj_ prefix")]);
   }
   const projectName = options.projectName ?? "Migrated legacy project";
   if (projectName.length < 1 || projectName.length > 120 || /[\u0000\r\n]/.test(projectName)) {
-    throw new VnextConfigError([migrateIssue("semantic", "project_name_invalid", ".kxm/project.yaml", "project name must contain 1-120 characters on one line")]);
+    throw new KxmConfigError([migrateIssue("semantic", "project_name_invalid", ".kxm/project.yaml", "project name must contain 1-120 characters on one line")]);
   }
 
   const resources = new Map<string, JsonObject>();
@@ -1484,8 +1484,8 @@ export function planVnextMigration(projectRoot: string, options: VnextMigrationO
 
   // Validate every converted resource against its exact schema before the
   // plan is considered applicable.
-  const schemaIssues: VnextConfigIssue[] = [];
-  const kindOf = (path: string): VnextResourceKind => path === ".kxm/project.yaml" ? "project"
+  const schemaIssues: KxmConfigIssue[] = [];
+  const kindOf = (path: string): KxmResourceKind => path === ".kxm/project.yaml" ? "project"
     : path.endsWith("repo.yaml") ? "repository"
     : path.startsWith(".kxm/agents/") ? "agent"
     : path.startsWith(".kxm/models/") ? "model"
@@ -1493,14 +1493,14 @@ export function planVnextMigration(projectRoot: string, options: VnextMigrationO
   const idOf = (path: string): string | undefined => path === ".kxm/project.yaml" || path.endsWith("repo.yaml")
     ? undefined
     : path.slice(path.lastIndexOf("/") + 1, -".yaml".length);
-  const semanticResources = new Map<string, { kind: VnextResourceKind; id?: string; value: JsonObject }>();
+  const semanticResources = new Map<string, { kind: KxmResourceKind; id?: string; value: JsonObject }>();
   for (const [path, value] of [...resources.entries()].sort(([left], [right]) => compareCodeUnits(left, right))) {
     const kind = kindOf(path);
     schemaIssues.push(...registry.validate(kind, value, path));
     const id = idOf(path);
     semanticResources.set(path, kind === "repository" ? { kind, id: "control", value } : { kind, ...(id === undefined ? {} : { id }), value });
   }
-  if (schemaIssues.length > 0) throw new VnextConfigError(schemaIssues);
+  if (schemaIssues.length > 0) throw new KxmConfigError(schemaIssues);
   // Full semantic validation gates a resolved plan: while ambiguities remain,
   // the intermediate resource set may legitimately be incomplete (for example
   // a workflow whose coordinator decision is still pending), and the operator
@@ -1508,8 +1508,8 @@ export function planVnextMigration(projectRoot: string, options: VnextMigrationO
   // Apply always re-plans and requires zero ambiguities, so this check still
   // runs before any write.
   if (plan.ambiguities.length === 0) {
-    const semanticIssues = validateVnextResources(semanticResources, options);
-    if (semanticIssues.length > 0) throw new VnextConfigError(semanticIssues);
+    const semanticIssues = validateKxmResources(semanticResources, options);
+    if (semanticIssues.length > 0) throw new KxmConfigError(semanticIssues);
   }
 
   const planRecord: JsonObject = {
@@ -1537,7 +1537,7 @@ export function planVnextMigration(projectRoot: string, options: VnextMigrationO
     canApply: plan.ambiguities.length === 0,
   };
   const planIssues = registry.validateMigrationPlan(planRecord, "kxm.migration-plan.v1");
-  if (planIssues.length > 0) throw new VnextConfigError(planIssues);
+  if (planIssues.length > 0) throw new KxmConfigError(planIssues);
 
   return {
     plan: planRecord,
@@ -1553,14 +1553,14 @@ export function planVnextMigration(projectRoot: string, options: VnextMigrationO
 
 /* ------------------------- decisions file -------------------------- */
 
-export function readVnextMigrationDecisions(path: string, schemasDir?: string): JsonObject {
+export function readKxmMigrationDecisions(path: string, schemasDir?: string): JsonObject {
   if (!existsSync(path)) {
-    throw new VnextConfigError([migrateIssue("discovery", "decisions_missing", path, "migration decisions file does not exist")]);
+    throw new KxmConfigError([migrateIssue("discovery", "decisions_missing", path, "migration decisions file does not exist")]);
   }
-  const registry = new VnextSchemaRegistry(schemasDir);
+  const registry = new KxmSchemaRegistry(schemasDir);
   const value = parseRestrictedYaml(readFileSync(path), path);
   const issues = registry.validateMigrationDecision(value, path);
-  if (issues.length > 0) throw new VnextConfigError(issues);
+  if (issues.length > 0) throw new KxmConfigError(issues);
   return value;
 }
 
@@ -1572,7 +1572,7 @@ function resolutionsOf(decisions: JsonObject): Record<string, JsonValue> {
 
 /* ------------------------- apply / verify -------------------------- */
 
-export interface VnextMigrationApplyResult {
+export interface KxmMigrationApplyResult {
   action: "applied" | "planned" | "already-migrated";
   projectRoot: string;
   receiptPath?: string;
@@ -1581,7 +1581,7 @@ export interface VnextMigrationApplyResult {
   plan?: JsonObject;
 }
 
-export interface VnextMigrationApplyOptions extends VnextMigrationOptions {
+export interface KxmMigrationApplyOptions extends KxmMigrationOptions {
   dryRun?: boolean;
   decisionsFile?: string;
   localStateRoot?: string;
@@ -1621,34 +1621,34 @@ function writeDurable(path: string, content: Buffer): void {
 }
 
 /** Apply a reviewed migration: stage, validate the complete target, install, and receipt. */
-export function applyVnextMigration(projectRoot: string, options: VnextMigrationApplyOptions = {}): VnextMigrationApplyResult {
+export function applyKxmMigration(projectRoot: string, options: KxmMigrationApplyOptions = {}): KxmMigrationApplyResult {
   const root = migrationGitRoot(projectRoot);
-  const storeOptions: VnextLocalBindingStoreOptions = {
+  const storeOptions: KxmLocalBindingStoreOptions = {
     ...(options.localStateRoot === undefined ? {} : { stateRoot: options.localStateRoot }),
     ...(options.schemasDir === undefined ? {} : { schemasDir: options.schemasDir }),
   };
 
-  const execute = (lock: VnextLocalBindingLock | undefined): VnextMigrationApplyResult => {
-    const receiptAbsolute = join(root, ...VNEXT_MIGRATION_RECEIPT_PATH.split("/"));
+  const execute = (lock: KxmLocalBindingLock | undefined): KxmMigrationApplyResult => {
+    const receiptAbsolute = join(root, ...KXM_MIGRATION_RECEIPT_PATH.split("/"));
     // Already-migrated detection precedes planning and decision checks: a
     // validated receipt makes re-apply an idempotent no-op even when legacy
     // sources were later removed or no decisions are supplied.
     if (existsSync(receiptAbsolute)) {
       const stat = lstatSync(receiptAbsolute);
       if (stat.isSymbolicLink() || !stat.isFile()) {
-        throw new VnextConfigError([migrateIssue("path", "migration_receipt_invalid", VNEXT_MIGRATION_RECEIPT_PATH, "migration receipt must be a regular file, not a link")]);
+        throw new KxmConfigError([migrateIssue("path", "migration_receipt_invalid", KXM_MIGRATION_RECEIPT_PATH, "migration receipt must be a regular file, not a link")]);
       }
-      const existing = loadVnextProject(root, options);
+      const existing = loadKxmProject(root, options);
       return {
         action: "already-migrated",
         projectRoot: root,
-        receiptPath: VNEXT_MIGRATION_RECEIPT_PATH,
+        receiptPath: KXM_MIGRATION_RECEIPT_PATH,
         configRevision: existing.configRevision,
         files: [],
       };
     }
 
-    const decisionsRecord = options.decisionsFile ? readVnextMigrationDecisions(options.decisionsFile, options.schemasDir) : undefined;
+    const decisionsRecord = options.decisionsFile ? readKxmMigrationDecisions(options.decisionsFile, options.schemasDir) : undefined;
     const decisions = decisionsRecord ? resolutionsOf(decisionsRecord) : (options.decisions ?? {});
     // Plan once with the real decisions: resolveDecision validates every
     // supplied value inline, so an invalid value can never masquerade as a
@@ -1656,16 +1656,16 @@ export function applyVnextMigration(projectRoot: string, options: VnextMigration
     // universe the operator reviewed; decision keys are accepted from the
     // union of both plans because binding decisions (coordinator, identities)
     // can make plan-1 keys unnecessary without invalidating the review.
-    const first = planVnextMigration(root, { ...options, decisions });
+    const first = planKxmMigration(root, { ...options, decisions });
     if (decisionsRecord) {
       if (decisionsRecord.projectId !== first.plan.projectId) {
-        throw new VnextConfigError([migrateIssue("semantic", "decision_project_mismatch", options.decisionsFile ?? "<decisions>", "decisions file projectId does not match the recomputed plan")]);
+        throw new KxmConfigError([migrateIssue("semantic", "decision_project_mismatch", options.decisionsFile ?? "<decisions>", "decisions file projectId does not match the recomputed plan")]);
       }
       if (decisionsRecord.projectName !== first.plan.projectName) {
-        throw new VnextConfigError([migrateIssue("semantic", "decision_project_mismatch", options.decisionsFile ?? "<decisions>", "decisions file projectName does not match the recomputed plan")]);
+        throw new KxmConfigError([migrateIssue("semantic", "decision_project_mismatch", options.decisionsFile ?? "<decisions>", "decisions file projectName does not match the recomputed plan")]);
       }
       if (decisionsRecord.sourceDigest !== first.plan.sourceDigest) {
-        throw new VnextConfigError([migrateIssue("semantic", "decision_source_changed", options.decisionsFile ?? "<decisions>", "legacy sources changed after the decisions file was reviewed")]);
+        throw new KxmConfigError([migrateIssue("semantic", "decision_source_changed", options.decisionsFile ?? "<decisions>", "legacy sources changed after the decisions file was reviewed")]);
       }
     }
     if (Object.keys(decisions).length > 0) {
@@ -1674,7 +1674,7 @@ export function applyVnextMigration(projectRoot: string, options: VnextMigration
       // e.g. a coordinator choice superseded by a raw-name binding) are
       // validated against the universe's allowed values here. Anything else
       // was never part of any review.
-      const universe = planVnextMigration(root, { ...options, decisions: {} });
+      const universe = planKxmMigration(root, { ...options, decisions: {} });
       const unknown: string[] = [];
       const invalid: string[] = [];
       for (const [key, value] of Object.entries(decisions)) {
@@ -1687,11 +1687,11 @@ export function applyVnextMigration(projectRoot: string, options: VnextMigration
         }
       }
       if (unknown.length > 0) {
-        throw new VnextConfigError(unknown.sort(compareCodeUnits).map((key) => migrateIssue("semantic", "decision_unknown", key, "decision key does not match any current ambiguity")));
+        throw new KxmConfigError(unknown.sort(compareCodeUnits).map((key) => migrateIssue("semantic", "decision_unknown", key, "decision key does not match any current ambiguity")));
       }
       const allInvalid = [...new Set([...invalid, ...first.invalidDecisions])].sort(compareCodeUnits);
       if (allInvalid.length > 0) {
-        throw new VnextConfigError(allInvalid.map((key) => migrateIssue("semantic", "decision_value_invalid", key, "decision value is not one of the plan's allowed values")));
+        throw new KxmConfigError(allInvalid.map((key) => migrateIssue("semantic", "decision_value_invalid", key, "decision value is not one of the plan's allowed values")));
       }
     }
     if (first.ambiguities.length > 0) {
@@ -1700,14 +1700,14 @@ export function applyVnextMigration(projectRoot: string, options: VnextMigration
 
     const files = [...first.resources.entries()].sort(([left], [right]) => compareCodeUnits(left, right))
       .map(([path, value]) => ({ path, bytes: Buffer.from(stringify(value, { lineWidth: 0 }), "utf8") }));
-    // Refuse to overwrite any existing vNext state or legacy inputs.
+    // Refuse to overwrite any existing KXM state or legacy inputs.
     const collisions = files.filter((file) => existsSync(join(root, ...file.path.split("/"))));
     if (collisions.length > 0) {
-      throw new VnextConfigError(collisions.map((file) => migrateIssue("semantic", "migration_target_exists", file.path, "target resource already exists; refusing to overwrite")));
+      throw new KxmConfigError(collisions.map((file) => migrateIssue("semantic", "migration_target_exists", file.path, "target resource already exists; refusing to overwrite")));
     }
     // Never write through a linked or non-directory parent component: walk
     // every target parent from the project root before the first write.
-    const parentIssues: VnextConfigIssue[] = [];
+    const parentIssues: KxmConfigIssue[] = [];
     for (const file of files) {
       const segments = file.path.split("/");
       let current = root;
@@ -1721,7 +1721,7 @@ export function applyVnextMigration(projectRoot: string, options: VnextMigration
         }
       }
     }
-    if (parentIssues.length > 0) throw new VnextConfigError(parentIssues);
+    if (parentIssues.length > 0) throw new KxmConfigError(parentIssues);
 
     if (options.dryRun) {
       // Preflight is complete (decisions, collisions, linked parents); a
@@ -1741,29 +1741,29 @@ export function applyVnextMigration(projectRoot: string, options: VnextMigration
         writeDurable(absolute, file.bytes);
       }
       // Validate the complete installed bundle before issuing the receipt.
-      const bundle = loadVnextProject(root, { ...options, allowUnreceiptedLegacyConfig: true });
+      const bundle = loadKxmProject(root, { ...options, allowUnreceiptedLegacyConfig: true });
       const receipt: JsonObject = {
         schema: "kxm.migration-receipt.v1",
         migrationId: `mig_${sha256Of(`${first.plan.sourceDigest}\n${bundle.configRevision}`).slice(7, 39)}`,
         projectId: String(first.plan.projectId),
         sourceDigest: String(first.plan.sourceDigest),
-        decisionDigest: sha256Of(vnextCanonicalJson((decisionsRecord ?? { schema: "kxm.migration-decision.v1", projectId: first.plan.projectId, projectName: first.plan.projectName, sourceDigest: first.plan.sourceDigest, resolutions: decisions }) as JsonObject)),
+        decisionDigest: sha256Of(kxmCanonicalJson((decisionsRecord ?? { schema: "kxm.migration-decision.v1", projectId: first.plan.projectId, projectName: first.plan.projectName, sourceDigest: first.plan.sourceDigest, resolutions: decisions }) as JsonObject)),
         configRevision: bundle.configRevision,
         sources: first.plan.sources as JsonValue,
         resources: files.map((file) => ({ path: file.path, sha256: sha256Of(file.bytes), bytes: file.bytes.byteLength })),
       };
       receipt.receiptSha256 = migrationReceiptSelfHash(receipt);
-      const registry = new VnextSchemaRegistry(options.schemasDir);
-      const receiptIssues = registry.validateMigrationReceipt(receipt, VNEXT_MIGRATION_RECEIPT_PATH);
-      if (receiptIssues.length > 0) throw new VnextConfigError(receiptIssues);
+      const registry = new KxmSchemaRegistry(options.schemasDir);
+      const receiptIssues = registry.validateMigrationReceipt(receipt, KXM_MIGRATION_RECEIPT_PATH);
+      if (receiptIssues.length > 0) throw new KxmConfigError(receiptIssues);
       written.push(receiptAbsolute);
       writeDurable(receiptAbsolute, Buffer.from(stringify(receipt, { lineWidth: 0 }), "utf8"));
       // The receipt must make the mixed tree loadable.
-      const verified = loadVnextProject(root, options);
+      const verified = loadKxmProject(root, options);
       return {
         action: "applied",
         projectRoot: root,
-        receiptPath: VNEXT_MIGRATION_RECEIPT_PATH,
+        receiptPath: KXM_MIGRATION_RECEIPT_PATH,
         configRevision: verified.configRevision,
         files: files.map((file) => file.path),
         plan: first.plan,
@@ -1780,67 +1780,67 @@ export function applyVnextMigration(projectRoot: string, options: VnextMigration
   };
 
   if (options.dryRun) return execute(undefined);
-  return withVnextLocalBindingLock(root, storeOptions, (lock) => execute(lock));
+  return withKxmLocalBindingLock(root, storeOptions, (lock) => execute(lock));
 }
 
 /* ------------------------- verify ---------------------------------- */
 
-export interface VnextMigrationVerifyResult {
+export interface KxmMigrationVerifyResult {
   ok: boolean;
   projectRoot: string;
   receiptPath: string;
   configRevision?: string;
-  issues: readonly VnextConfigIssue[];
+  issues: readonly KxmConfigIssue[];
 }
 
 /** Re-check a migration receipt against current legacy sources and the target bundle. No writes. */
-export function verifyVnextMigration(projectRoot: string, options: VnextConfigOptions = {}): VnextMigrationVerifyResult {
+export function verifyKxmMigration(projectRoot: string, options: KxmConfigOptions = {}): KxmMigrationVerifyResult {
   const root = migrationGitRoot(projectRoot);
-  const receiptAbsolute = join(root, ...VNEXT_MIGRATION_RECEIPT_PATH.split("/"));
+  const receiptAbsolute = join(root, ...KXM_MIGRATION_RECEIPT_PATH.split("/"));
   if (!existsSync(receiptAbsolute)) {
     return {
       ok: false,
       projectRoot: root,
-      receiptPath: VNEXT_MIGRATION_RECEIPT_PATH,
-      issues: [migrateIssue("discovery", "migration_receipt_missing", VNEXT_MIGRATION_RECEIPT_PATH, "no migration receipt exists")],
+      receiptPath: KXM_MIGRATION_RECEIPT_PATH,
+      issues: [migrateIssue("discovery", "migration_receipt_missing", KXM_MIGRATION_RECEIPT_PATH, "no migration receipt exists")],
     };
   }
   try {
-    const bundle = loadVnextProject(root, options);
+    const bundle = loadKxmProject(root, options);
     const receipt = bundle.migrationReceipt;
     if (!receipt) {
       if (legacyConfigFilesAt(root).length === 0) {
         // Every legacy source was removed after migration: the receipt was
-        // never consulted at load. Read it directly; readVnextMigrationReceipt
+        // never consulted at load. Read it directly; readKxmMigrationReceipt
         // surfaces one migration_source_missing issue per declared source.
-        const direct = readVnextMigrationReceipt(root, options);
+        const direct = readKxmMigrationReceipt(root, options);
         return {
           ok: false,
           projectRoot: root,
-          receiptPath: VNEXT_MIGRATION_RECEIPT_PATH,
+          receiptPath: KXM_MIGRATION_RECEIPT_PATH,
           configRevision: bundle.configRevision,
-          issues: direct.issues.length > 0 ? direct.issues : [migrateIssue("semantic", "migration_receipt_invalid", VNEXT_MIGRATION_RECEIPT_PATH, "receipt did not validate")],
+          issues: direct.issues.length > 0 ? direct.issues : [migrateIssue("semantic", "migration_receipt_invalid", KXM_MIGRATION_RECEIPT_PATH, "receipt did not validate")],
         };
       }
       return {
         ok: false,
         projectRoot: root,
-        receiptPath: VNEXT_MIGRATION_RECEIPT_PATH,
+        receiptPath: KXM_MIGRATION_RECEIPT_PATH,
         configRevision: bundle.configRevision,
-        issues: [migrateIssue("semantic", "migration_receipt_invalid", VNEXT_MIGRATION_RECEIPT_PATH, "receipt did not validate during project load")],
+        issues: [migrateIssue("semantic", "migration_receipt_invalid", KXM_MIGRATION_RECEIPT_PATH, "receipt did not validate during project load")],
       };
     }
-    const targetIssues = verifyVnextMigrationReceiptTarget(root, receipt, bundle.resources, bundle.configRevision);
+    const targetIssues = verifyKxmMigrationReceiptTarget(root, receipt, bundle.resources, bundle.configRevision);
     return {
       ok: targetIssues.length === 0,
       projectRoot: root,
-      receiptPath: VNEXT_MIGRATION_RECEIPT_PATH,
+      receiptPath: KXM_MIGRATION_RECEIPT_PATH,
       configRevision: bundle.configRevision,
       issues: targetIssues,
     };
   } catch (error) {
-    if (error instanceof VnextConfigError) {
-      return { ok: false, projectRoot: root, receiptPath: VNEXT_MIGRATION_RECEIPT_PATH, issues: error.issues };
+    if (error instanceof KxmConfigError) {
+      return { ok: false, projectRoot: root, receiptPath: KXM_MIGRATION_RECEIPT_PATH, issues: error.issues };
     }
     throw error;
   }