@kontextmind/kxm 0.7.40 → 0.7.44

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

@@ -5,65 +5,65 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep }
 import { Ajv2020, type ErrorObject, type ValidateFunction } from "ajv/dist/2020.js";
 import {
   RestrictedYamlError,
-  VNEXT_YAML_LIMITS,
+  KXM_YAML_LIMITS,
   parseRestrictedYaml as parseRestrictedYamlShared,
-  type VnextYamlLimits,
+  type KxmYamlLimits,
 } from "./restricted-yaml.mjs";
-import { resolveVnextTemplateBaseline } from "./vnext-template.ts";
+import { resolveKxmTemplateBaseline } from "./template.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
-import { BUILTIN_HARNESS_IDS, DEFAULT_HARNESS, validateHarnessModelPair } from "./vnext-harness.ts";
+import { BUILTIN_HARNESS_IDS, DEFAULT_HARNESS, validateHarnessModelPair } from "./harness.ts";
 
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 export type JsonObject = { [key: string]: JsonValue };
-export type { VnextYamlLimits };
-export { VNEXT_YAML_LIMITS };
+export type { KxmYamlLimits };
+export { KXM_YAML_LIMITS };
 
-export type VnextValidationPhase = "discovery" | "parse" | "schema" | "path" | "reference" | "semantic";
+export type KxmValidationPhase = "discovery" | "parse" | "schema" | "path" | "reference" | "semantic";
 
-export interface VnextConfigIssue {
-  phase: VnextValidationPhase;
+export interface KxmConfigIssue {
+  phase: KxmValidationPhase;
   code: string;
   file: string;
   message: string;
 }
 
-export class VnextConfigError extends Error {
-  readonly issues: readonly VnextConfigIssue[];
+export class KxmConfigError extends Error {
+  readonly issues: readonly KxmConfigIssue[];
 
-  constructor(issues: readonly VnextConfigIssue[]) {
+  constructor(issues: readonly KxmConfigIssue[]) {
     const sorted = sortIssues(issues);
     super(sorted.map((issue) => `${issue.file}: ${issue.code}: ${issue.message}`).join("\n"));
-    this.name = "VnextConfigError";
+    this.name = "KxmConfigError";
     this.issues = sorted;
   }
 }
 
-export type VnextResourceKind = "project" | "repository" | "agent" | "model" | "environment" | "workflow" | "gate-registry";
+export type KxmResourceKind = "project" | "repository" | "agent" | "model" | "environment" | "workflow" | "gate-registry";
 
-export interface VnextResource {
-  kind: VnextResourceKind;
+export interface KxmResource {
+  kind: KxmResourceKind;
   id?: string;
   file: string;
   logicalPath: string;
   value: JsonObject;
 }
 
-export interface VnextProjectBundle {
+export interface KxmProjectBundle {
   projectRoot: string;
-  project: VnextResource;
-  repositories: ReadonlyMap<string, VnextResource>;
-  agents: ReadonlyMap<string, VnextResource>;
-  models: ReadonlyMap<string, VnextResource>;
-  workflows: ReadonlyMap<string, VnextResource>;
-  environments: readonly VnextResource[];
-  gateRegistry?: VnextResource;
+  project: KxmResource;
+  repositories: ReadonlyMap<string, KxmResource>;
+  agents: ReadonlyMap<string, KxmResource>;
+  models: ReadonlyMap<string, KxmResource>;
+  workflows: ReadonlyMap<string, KxmResource>;
+  environments: readonly KxmResource[];
+  gateRegistry?: KxmResource;
   templateProvenance?: JsonObject;
   migrationReceipt?: JsonObject;
-  resources: readonly VnextResource[];
+  resources: readonly KxmResource[];
   configRevision: string;
 }
 
-export interface VnextConfigOptions {
+export interface KxmConfigOptions {
   schemasDir?: string;
   repositoryBindings?: Readonly<Record<string, string>>;
   registeredExecutors?: Iterable<string>;
@@ -73,24 +73,24 @@ export interface VnextConfigOptions {
   allowUnreceiptedLegacyConfig?: boolean;
 }
 
-export type VnextInitializationMode = "create" | "migrate" | "repair" | "ready";
+export type KxmInitializationMode = "create" | "migrate" | "repair" | "ready";
 
-export interface VnextInitializationPlan {
-  mode: VnextInitializationMode;
+export interface KxmInitializationPlan {
+  mode: KxmInitializationMode;
   inspectedFrom: string;
   projectRoot?: string;
   legacyRoot?: string;
   changesRequired: boolean;
-  issues: readonly VnextConfigIssue[];
+  issues: readonly KxmConfigIssue[];
   legacyInputs: readonly string[];
   configRevision?: string;
 }
 
-function defaultVnextSchemaDir(): string {
-  return join(findKxmRepoRoot(import.meta.url), "schemas", "vnext");
+function defaultKxmSchemaDir(): string {
+  return join(findKxmRepoRoot(import.meta.url), "schemas");
 }
-const DEFAULT_SCHEMA_DIR = defaultVnextSchemaDir();
-const RESOURCE_SCHEMA: Readonly<Record<VnextResourceKind, { identity: string; file: string }>> = Object.freeze({
+const DEFAULT_SCHEMA_DIR = defaultKxmSchemaDir();
+const RESOURCE_SCHEMA: Readonly<Record<KxmResourceKind, { identity: string; file: string }>> = Object.freeze({
   project: { identity: "kxm.project.v1", file: "project.schema.json" },
   repository: { identity: "kxm.repository.v1", file: "repository.schema.json" },
   agent: { identity: "kxm.agent.v1", file: "agent.schema.json" },
@@ -115,35 +115,35 @@ function compareCodeUnits(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
-function sortIssues(issues: readonly VnextConfigIssue[]): VnextConfigIssue[] {
+function sortIssues(issues: readonly KxmConfigIssue[]): KxmConfigIssue[] {
   return [...issues].sort((left, right) => compareCodeUnits(left.file, right.file)
     || compareCodeUnits(left.phase, right.phase)
     || compareCodeUnits(left.code, right.code)
     || compareCodeUnits(left.message, right.message));
 }
 
-function issue(phase: VnextValidationPhase, code: string, file: string, message: string): VnextConfigIssue {
+function issue(phase: KxmValidationPhase, code: string, file: string, message: string): KxmConfigIssue {
   return { phase, code, file, message };
 }
 
-function fail(phase: VnextValidationPhase, code: string, file: string, message: string): never {
-  throw new VnextConfigError([issue(phase, code, file, message)]);
+function fail(phase: KxmValidationPhase, code: string, file: string, message: string): never {
+  throw new KxmConfigError([issue(phase, code, file, message)]);
 }
 
 function isJsonObject(value: JsonValue): value is JsonObject {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-/** Parse the restricted, JSON-compatible YAML profile used by all vNext configuration. */
+/** Parse the restricted, JSON-compatible YAML profile used by all KXM configuration. */
 export function parseRestrictedYaml(
   input: string | Uint8Array,
   label = "<yaml>",
-  limits: Readonly<VnextYamlLimits> = VNEXT_YAML_LIMITS,
+  limits: Readonly<KxmYamlLimits> = KXM_YAML_LIMITS,
 ): JsonObject {
   try {
     return parseRestrictedYamlShared(input, label, limits);
   } catch (error) {
-    if (error instanceof RestrictedYamlError) throw new VnextConfigError(error.issues);
+    if (error instanceof RestrictedYamlError) throw new KxmConfigError(error.issues);
     throw error;
   }
 }
@@ -154,10 +154,10 @@ function readJsonObject(file: string): Record<string, unknown> {
   return parsed as Record<string, unknown>;
 }
 
-export class VnextSchemaRegistry {
+export class KxmSchemaRegistry {
   readonly schemasDir: string;
   readonly ajv: Ajv2020;
-  readonly validators = new Map<VnextResourceKind, ValidateFunction>();
+  readonly validators = new Map<KxmResourceKind, ValidateFunction>();
   readonly localBindingsValidator: ValidateFunction;
   readonly templateProvenanceValidator: ValidateFunction;
   readonly initOperationValidator: ValidateFunction;
@@ -194,20 +194,20 @@ export class VnextSchemaRegistry {
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, permissionDiffFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, runEventFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, driveReceiptFile)));
-    for (const [kind, definition] of Object.entries(RESOURCE_SCHEMA) as [VnextResourceKind, { identity: string; file: string }][]) {
-      const validator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${definition.file}`);
+    for (const [kind, definition] of Object.entries(RESOURCE_SCHEMA) as [KxmResourceKind, { identity: string; file: string }][]) {
+      const validator = this.ajv.getSchema(`https://schemas.kxm.dev/${definition.file}`);
       if (!validator) throw new Error(`schema did not compile: ${definition.file}`);
       this.validators.set(kind, validator);
     }
-    const localBindingsValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${localBindingsFile}`);
-    const templateProvenanceValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${templateProvenanceFile}`);
-    const initOperationValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${initOperationFile}`);
-    const migrationPlanValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${migrationPlanFile}`);
-    const migrationDecisionValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${migrationDecisionFile}`);
-    const migrationReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${migrationReceiptFile}`);
-    const permissionDiffValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${permissionDiffFile}`);
-    const runEventValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${runEventFile}`);
-    const driveReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${driveReceiptFile}`);
+    const localBindingsValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${localBindingsFile}`);
+    const templateProvenanceValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${templateProvenanceFile}`);
+    const initOperationValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${initOperationFile}`);
+    const migrationPlanValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${migrationPlanFile}`);
+    const migrationDecisionValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${migrationDecisionFile}`);
+    const migrationReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${migrationReceiptFile}`);
+    const permissionDiffValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${permissionDiffFile}`);
+    const runEventValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${runEventFile}`);
+    const driveReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${driveReceiptFile}`);
     if (!localBindingsValidator) throw new Error(`schema did not compile: ${localBindingsFile}`);
     if (!templateProvenanceValidator) throw new Error(`schema did not compile: ${templateProvenanceFile}`);
     if (!initOperationValidator) throw new Error(`schema did not compile: ${initOperationFile}`);
@@ -228,50 +228,50 @@ export class VnextSchemaRegistry {
     this.driveReceiptValidator = driveReceiptValidator;
   }
 
-  validate(kind: VnextResourceKind, value: JsonObject, file: string): VnextConfigIssue[] {
+  validate(kind: KxmResourceKind, value: JsonObject, file: string): KxmConfigIssue[] {
     const definition = RESOURCE_SCHEMA[kind];
     if (value.schema !== definition.identity) {
       return [issue("schema", "schema_identity_mismatch", file, `expected ${definition.identity}, received ${String(value.schema)}`)];
     }
     const validator = this.validators.get(kind);
-    if (!validator) throw new Error(`missing vNext validator for ${kind}`);
+    if (!validator) throw new Error(`missing KXM validator for ${kind}`);
     if (validator(value)) return [];
     return (validator.errors ?? []).map((error) => schemaIssue(file, error));
   }
 
-  validateLocalBindings(value: JsonObject, file: string): VnextConfigIssue[] {
+  validateLocalBindings(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.local-repository-bindings.v1", this.localBindingsValidator);
   }
 
-  validateTemplateProvenance(value: JsonObject, file: string): VnextConfigIssue[] {
+  validateTemplateProvenance(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.template-provenance.v1", this.templateProvenanceValidator);
   }
 
-  validateInitOperation(value: JsonObject, file: string): VnextConfigIssue[] {
+  validateInitOperation(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.init-operation.v1", this.initOperationValidator);
   }
 
-  validateMigrationPlan(value: JsonObject, file: string): VnextConfigIssue[] {
+  validateMigrationPlan(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.migration-plan.v1", this.migrationPlanValidator);
   }
 
-  validateMigrationDecision(value: JsonObject, file: string): VnextConfigIssue[] {
+  validateMigrationDecision(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.migration-decision.v1", this.migrationDecisionValidator);
   }
 
-  validateMigrationReceipt(value: JsonObject, file: string): VnextConfigIssue[] {
+  validateMigrationReceipt(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.migration-receipt.v1", this.migrationReceiptValidator);
   }
 
-  validatePermissionDiff(value: JsonObject, file: string): VnextConfigIssue[] {
+  validatePermissionDiff(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.permission-diff.v1", this.permissionDiffValidator);
   }
 
-  validateDriveReceipt(value: JsonObject, file: string): VnextConfigIssue[] {
+  validateDriveReceipt(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.drive-receipt.v1", this.driveReceiptValidator);
   }
 
-  private validateAuxiliary(value: JsonObject, file: string, identity: string, validator: ValidateFunction): VnextConfigIssue[] {
+  private validateAuxiliary(value: JsonObject, file: string, identity: string, validator: ValidateFunction): KxmConfigIssue[] {
     if (value.schema !== identity) {
       return [issue("schema", "schema_identity_mismatch", file, `expected ${identity}, received ${String(value.schema)}`)];
     }
@@ -280,13 +280,13 @@ export class VnextSchemaRegistry {
   }
 }
 
-let cachedRunEventRegistry: VnextSchemaRegistry | undefined;
+let cachedRunEventRegistry: KxmSchemaRegistry | undefined;
 
 /** Validate a local run event against `kxm.run-event.v1`. Throws `run_event_invalid`. */
 export function validateRunEvent(value: unknown, file: string): void {
-  const registry = (cachedRunEventRegistry ??= new VnextSchemaRegistry());
+  const registry = (cachedRunEventRegistry ??= new KxmSchemaRegistry());
   if (!registry.runEventValidator(value)) {
-    throw new VnextConfigError([issue(
+    throw new KxmConfigError([issue(
       "schema",
       "run_event_invalid",
       file,
@@ -297,9 +297,9 @@ export function validateRunEvent(value: unknown, file: string): void {
 
 /** Validate a drive receipt against `kxm.drive-receipt.v1`. Throws `drive_receipt_invalid`. */
 export function validateDriveReceipt(value: unknown, file: string): void {
-  const registry = (cachedRunEventRegistry ??= new VnextSchemaRegistry());
+  const registry = (cachedRunEventRegistry ??= new KxmSchemaRegistry());
   if (!value || typeof value !== "object" || Array.isArray(value) || (value as JsonObject).schema !== "kxm.drive-receipt.v1") {
-    throw new VnextConfigError([issue(
+    throw new KxmConfigError([issue(
       "schema",
       "drive_receipt_invalid",
       file,
@@ -307,7 +307,7 @@ export function validateDriveReceipt(value: unknown, file: string): void {
     )]);
   }
   if (!registry.driveReceiptValidator(value)) {
-    throw new VnextConfigError([issue(
+    throw new KxmConfigError([issue(
       "schema",
       "drive_receipt_invalid",
       file,
@@ -316,7 +316,7 @@ export function validateDriveReceipt(value: unknown, file: string): void {
   }
 }
 
-function schemaIssue(file: string, error: ErrorObject): VnextConfigIssue {
+function schemaIssue(file: string, error: ErrorObject): KxmConfigIssue {
   const location = error.instancePath || "/";
   const suffix = error.params && "additionalProperty" in error.params
     ? ` (${String(error.params.additionalProperty)})`
@@ -346,7 +346,7 @@ function containedHostPath(root: string, candidate: string): boolean {
   return path === "" || (!isAbsolute(path) && path !== ".." && !path.startsWith(`..${sep}`));
 }
 
-function portableBindingIssue(root: string, pathHint: string, repositoryId: string): VnextConfigIssue | undefined {
+function portableBindingIssue(root: string, pathHint: string, repositoryId: string): KxmConfigIssue | undefined {
   let current = root;
   for (const segment of pathHint === "." ? [] : pathHint.split("/")) {
     current = join(current, segment);
@@ -368,7 +368,7 @@ function portableBindingIssue(root: string, pathHint: string, repositoryId: stri
 }
 
 /** The portable relative-path rule every project-owned pathHint must satisfy. */
-export function vnextPortablePath(path: string): boolean {
+export function kxmPortablePath(path: string): boolean {
   return portablePath(path);
 }
 
@@ -386,12 +386,12 @@ function portablePath(path: string): boolean {
 }
 
 /** The identifier rule every path-derived resource identity must satisfy. */
-export function vnextResourceIdentifier(id: string): boolean {
+export function kxmResourceIdentifier(id: string): boolean {
   return id.length <= 64 && IDENTIFIER.test(id) && !WINDOWS_RESERVED.test(id);
 }
 
 function resourceIdentifier(id: string): boolean {
-  return vnextResourceIdentifier(id);
+  return kxmResourceIdentifier(id);
 }
 
 function displayPath(root: string, file: string): string {
@@ -400,14 +400,14 @@ function displayPath(root: string, file: string): string {
 }
 
 function readResource(
-  registry: VnextSchemaRegistry,
+  registry: KxmSchemaRegistry,
   root: string,
   file: string,
   logicalPath: string,
-  kind: VnextResourceKind,
+  kind: KxmResourceKind,
   id?: string,
   containmentRoot = root,
-): VnextResource {
+): KxmResource {
   const label = displayPath(root, file);
   let stat;
   try {
@@ -429,11 +429,11 @@ function readResource(
   if (!stat.isFile()) fail("path", "resource_not_file", label, "configuration resource must be a regular file");
   const value = parseRestrictedYaml(readFileSync(file), label);
   const issues = registry.validate(kind, value, label);
-  if (issues.length > 0) throw new VnextConfigError(issues);
+  if (issues.length > 0) throw new KxmConfigError(issues);
   return { kind, ...(id === undefined ? {} : { id }), file, logicalPath, value };
 }
 
-function readTemplateProvenance(registry: VnextSchemaRegistry, root: string): JsonObject | undefined {
+function readTemplateProvenance(registry: KxmSchemaRegistry, root: string): JsonObject | undefined {
   const file = join(root, ".kxm", "template-provenance.yaml");
   if (!existsSync(file)) return undefined;
   const label = ".kxm/template-provenance.yaml";
@@ -453,8 +453,8 @@ function readTemplateProvenance(registry: VnextSchemaRegistry, root: string): Js
   }
   const value = parseRestrictedYaml(readFileSync(file), label);
   const issues = registry.validateTemplateProvenance(value, label);
-  if (issues.length > 0) throw new VnextConfigError(issues);
-  if (!resolveVnextTemplateBaseline(value)) {
+  if (issues.length > 0) throw new KxmConfigError(issues);
+  if (!resolveKxmTemplateBaseline(value)) {
     fail("semantic", "template_provenance_revision_invalid", label, "template provenance does not exactly match a supported built-in baseline");
   }
   const files = Array.isArray(value.files) ? value.files : [];
@@ -482,19 +482,19 @@ function readTemplateProvenance(registry: VnextSchemaRegistry, root: string): Js
 }
 
 function listNamedResources(
-  registry: VnextSchemaRegistry,
+  registry: KxmSchemaRegistry,
   root: string,
   directory: string,
   logicalDirectory: string,
   kind: "agent" | "model" | "workflow",
-): Map<string, VnextResource> {
-  const resources = new Map<string, VnextResource>();
+): Map<string, KxmResource> {
+  const resources = new Map<string, KxmResource>();
   if (!existsSync(directory)) return resources;
   const stat = lstatSync(directory);
   if (stat.isSymbolicLink() || !stat.isDirectory()) {
     fail("path", "resource_directory_invalid", displayPath(root, directory), "resource directory must be a regular directory");
   }
-  const issues: VnextConfigIssue[] = [];
+  const issues: KxmConfigIssue[] = [];
   const entries = readdirSync(directory, { withFileTypes: true }).sort((left, right) => compareCodeUnits(left.name, right.name));
   for (const entry of entries) {
     if (entry.isDirectory()) {
@@ -521,11 +521,11 @@ function listNamedResources(
       const resource = readResource(registry, root, join(directory, entry.name), `${logicalDirectory}/${id}.yaml`, kind, id);
       resources.set(id, resource);
     } catch (error) {
-      if (error instanceof VnextConfigError) issues.push(...error.issues);
+      if (error instanceof KxmConfigError) issues.push(...error.issues);
       else throw error;
     }
   }
-  if (issues.length > 0) throw new VnextConfigError(issues);
+  if (issues.length > 0) throw new KxmConfigError(issues);
   return resources;
 }
 
@@ -550,7 +550,7 @@ function names(value: JsonValue | undefined): string[] {
   return Array.isArray(value) ? value.filter((candidate): candidate is string => typeof candidate === "string") : [];
 }
 
-function mapResource(resource: VnextResource, map: Map<string, VnextResource>, issues: VnextConfigIssue[]): void {
+function mapResource(resource: KxmResource, map: Map<string, KxmResource>, issues: KxmConfigIssue[]): void {
   const id = resource.id;
   if (!id) return;
   const collision = [...map.keys()].find((candidate) => candidate.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
@@ -561,7 +561,7 @@ function mapResource(resource: VnextResource, map: Map<string, VnextResource>, i
   map.set(id, resource);
 }
 
-function validatePortablePaths(resource: VnextResource, issues: VnextConfigIssue[]): void {
+function validatePortablePaths(resource: KxmResource, issues: KxmConfigIssue[]): void {
   const candidates: { path: string; label: string }[] = [];
   if (resource.kind === "project") {
     for (const candidate of valuesOf(resource.value, "repositories")) {
@@ -587,11 +587,11 @@ function validatePortablePaths(resource: VnextResource, issues: VnextConfigIssue
 
 function selectorCandidates(
   selectorValue: JsonValue | undefined,
-  models: ReadonlyMap<string, VnextResource>,
+  models: ReadonlyMap<string, KxmResource>,
   file: string,
   label: string,
-  issues: VnextConfigIssue[],
-): VnextResource[] {
+  issues: KxmConfigIssue[],
+): KxmResource[] {
   const selector = objectValue(selectorValue);
   if (!selector) return [];
   const profile = stringValue(selector.profile);
@@ -616,7 +616,7 @@ interface ModelCandidate {
   model?: string;
 }
 
-function modelCandidates(selectorValue: JsonValue | undefined, models: ReadonlyMap<string, VnextResource>): ModelCandidate[] {
+function modelCandidates(selectorValue: JsonValue | undefined, models: ReadonlyMap<string, KxmResource>): ModelCandidate[] {
   const selector = objectValue(selectorValue);
   if (!selector) return [];
   const profile = stringValue(selector.profile);
@@ -656,8 +656,8 @@ function compatibleModel(left: ModelCandidate, right: ModelCandidate): boolean {
 function diversityCandidates(
   stepSelector: JsonValue | undefined,
   allowedAgents: readonly string[],
-  agents: ReadonlyMap<string, VnextResource>,
-  models: ReadonlyMap<string, VnextResource>,
+  agents: ReadonlyMap<string, KxmResource>,
+  models: ReadonlyMap<string, KxmResource>,
 ): ModelCandidate[] {
   const stepCandidates = modelCandidates(stepSelector, models);
   const resolved: ModelCandidate[] = [];
@@ -672,7 +672,7 @@ function diversityCandidates(
   return [...new Map(resolved.map((candidate) => [candidate.key, candidate])).values()];
 }
 
-function validateEnvironment(resource: VnextResource, issues: VnextConfigIssue[]): void {
+function validateEnvironment(resource: KxmResource, issues: KxmConfigIssue[]): void {
   const values = objectValue(resource.value.values) ?? {};
   const secretNames = new Set<string>();
   for (const candidate of valuesOf(resource.value, "secrets")) {
@@ -694,7 +694,7 @@ function accessRank(value: JsonValue | undefined): number {
   return value === "write" ? 2 : value === "read" ? 1 : 0;
 }
 
-function validateToolScope(agent: VnextResource, step: JsonObject, file: string, stepId: string, issues: VnextConfigIssue[]): void {
+function validateToolScope(agent: KxmResource, step: JsonObject, file: string, stepId: string, issues: KxmConfigIssue[]): void {
   const requested = objectValue(step.tools);
   if (!requested) return;
   const ceiling = objectValue(agent.value.tools);
@@ -718,7 +718,7 @@ function validateToolScope(agent: VnextResource, step: JsonObject, file: string,
   }
 }
 
-function validateToolPolicy(resource: VnextResource, policy: JsonObject | undefined, label: string, issues: VnextConfigIssue[]): void {
+function validateToolPolicy(resource: KxmResource, policy: JsonObject | undefined, label: string, issues: KxmConfigIssue[]): void {
   if (!policy) return;
   const allowed = new Set(names(policy.allow));
   for (const tool of names(policy.deny)) {
@@ -727,11 +727,11 @@ function validateToolPolicy(resource: VnextResource, policy: JsonObject | undefi
 }
 
 /** Validate an in-memory resource set with the same semantic rules as a loaded project. */
-export function validateVnextResources(
-  resources: ReadonlyMap<string, { kind: VnextResourceKind; id?: string; value: JsonObject }>,
-  options: VnextConfigOptions = {},
-): VnextConfigIssue[] {
-  const make = (logicalPath: string, kind: VnextResourceKind, id: string | undefined, value: JsonObject): VnextResource => ({
+export function validateKxmResources(
+  resources: ReadonlyMap<string, { kind: KxmResourceKind; id?: string; value: JsonObject }>,
+  options: KxmConfigOptions = {},
+): KxmConfigIssue[] {
+  const make = (logicalPath: string, kind: KxmResourceKind, id: string | undefined, value: JsonObject): KxmResource => ({
     kind,
     ...(id === undefined ? {} : { id }),
     file: logicalPath,
@@ -739,13 +739,13 @@ export function validateVnextResources(
     value,
   });
   assertNoRegisteredGates(options);
-  let gateRegistry: VnextResource | undefined;
-  let project: VnextResource | undefined;
-  const repositories = new Map<string, VnextResource>();
-  const agents = new Map<string, VnextResource>();
-  const models = new Map<string, VnextResource>();
-  const workflows = new Map<string, VnextResource>();
-  const environments: VnextResource[] = [];
+  let gateRegistry: KxmResource | undefined;
+  let project: KxmResource | undefined;
+  const repositories = new Map<string, KxmResource>();
+  const agents = new Map<string, KxmResource>();
+  const models = new Map<string, KxmResource>();
+  const workflows = new Map<string, KxmResource>();
+  const environments: KxmResource[] = [];
   for (const [logicalPath, resource] of resources) {
     const made = make(logicalPath, resource.kind, resource.id, resource.value);
     if (resource.kind === "project") project = made;
@@ -761,12 +761,12 @@ export function validateVnextResources(
 }
 
 function validateAgentScope(
-  agent: VnextResource,
+  agent: KxmResource,
   step: JsonObject,
   repositories: ReadonlySet<string>,
   file: string,
   stepId: string,
-  issues: VnextConfigIssue[],
+  issues: KxmConfigIssue[],
 ): void {
   validateToolScope(agent, step, file, stepId, issues);
   const agentRepositories = objectValue(agent.value.repositories) ?? {};
@@ -800,12 +800,12 @@ function transition(value: JsonValue): { target?: string; maxTransitions?: numbe
 }
 
 function validateWorkflow(
-  workflow: VnextResource,
-  agents: ReadonlyMap<string, VnextResource>,
-  models: ReadonlyMap<string, VnextResource>,
+  workflow: KxmResource,
+  agents: ReadonlyMap<string, KxmResource>,
+  models: ReadonlyMap<string, KxmResource>,
   repositories: ReadonlySet<string>,
   gates: ReadonlySet<string> | undefined,
-  issues: VnextConfigIssue[],
+  issues: KxmConfigIssue[],
 ): void {
   const file = workflow.logicalPath;
   const coordinator = stringValue(workflow.value.coordinator) ?? "coordinator";
@@ -1029,7 +1029,7 @@ function validateWorkflow(
   }
 }
 
-function validateModelReferences(models: ReadonlyMap<string, VnextResource>, issues: VnextConfigIssue[]): void {
+function validateModelReferences(models: ReadonlyMap<string, KxmResource>, issues: KxmConfigIssue[]): void {
   for (const model of models.values()) {
     for (const [index, fallback] of valuesOf(model.value, "fallbacks").entries()) {
       selectorCandidates(fallback, models, model.logicalPath, `fallbacks[${index}]`, issues);
@@ -1058,17 +1058,17 @@ function validateModelReferences(models: ReadonlyMap<string, VnextResource>, iss
 }
 
 function validateBundle(
-  project: VnextResource,
-  repositories: ReadonlyMap<string, VnextResource>,
-  agents: ReadonlyMap<string, VnextResource>,
-  models: ReadonlyMap<string, VnextResource>,
-  workflows: ReadonlyMap<string, VnextResource>,
-  environments: readonly VnextResource[],
-  options: VnextConfigOptions,
-  gateRegistry?: VnextResource,
+  project: KxmResource,
+  repositories: ReadonlyMap<string, KxmResource>,
+  agents: ReadonlyMap<string, KxmResource>,
+  models: ReadonlyMap<string, KxmResource>,
+  workflows: ReadonlyMap<string, KxmResource>,
+  environments: readonly KxmResource[],
+  options: KxmConfigOptions,
+  gateRegistry?: KxmResource,
   projectRoot?: string,
-): VnextConfigIssue[] {
-  const issues: VnextConfigIssue[] = [];
+): KxmConfigIssue[] {
+  const issues: KxmConfigIssue[] = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate): candidate is JsonObject => Boolean(candidate));
   const repositoryIds = new Set<string>();
   const foldedRepositories = new Map<string, string>();
@@ -1168,7 +1168,7 @@ function validateBundle(
           }
         }
       } catch (error) {
-        if (error instanceof VnextConfigError) {
+        if (error instanceof KxmConfigError) {
           issues.push(...error.issues);
         }
       }
@@ -1178,17 +1178,17 @@ function validateBundle(
   return sortIssues(issues);
 }
 
-export function vnextCanonicalJson(value: JsonValue): string {
+export function kxmCanonicalJson(value: JsonValue): string {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map((candidate) => vnextCanonicalJson(candidate)).join(",")}]`;
-  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${vnextCanonicalJson(value[key] as JsonValue)}`).join(",")}}`;
+  if (Array.isArray(value)) return `[${value.map((candidate) => kxmCanonicalJson(candidate)).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${kxmCanonicalJson(value[key] as JsonValue)}`).join(",")}}`;
 }
 
 function canonicalize(value: JsonValue): string {
-  return vnextCanonicalJson(value);
+  return kxmCanonicalJson(value);
 }
 
-function bundleRevision(resources: readonly VnextResource[]): string {
+function bundleRevision(resources: readonly KxmResource[]): string {
   const hash = createHash("sha256");
   for (const resource of [...resources].sort((left, right) => compareCodeUnits(left.logicalPath, right.logicalPath))) {
     hash.update(resource.logicalPath, "utf8");
@@ -1218,8 +1218,8 @@ export function discoverGitRoot(start = process.cwd()): string | undefined {
   return existsSync(root) && lstatSync(root).isDirectory() ? root : undefined;
 }
 
-/** Find the authoritative vNext project only at the nearest Git worktree root. */
-export function discoverVnextProjectRoot(start = process.cwd()): string | undefined {
+/** Find the authoritative KXM project only at the nearest Git worktree root. */
+export function discoverKxmProjectRoot(start = process.cwd()): string | undefined {
   const gitRoot = discoverGitRoot(start);
   return gitRoot && existsSync(join(gitRoot, ".kxm", "project.yaml")) ? gitRoot : undefined;
 }
@@ -1227,23 +1227,23 @@ export function discoverVnextProjectRoot(start = process.cwd()): string | undefi
 /** The former caller-supplied gate allowlist cannot substitute for reviewed YAML. */
 export function assertNoRegisteredGates(options: object): void {
   if ("registeredGates" in options) {
-    throw new VnextConfigError([issue("semantic", "registered_gates_removed", ".kxm/gates.yaml", "registeredGates was removed; declare gates in .kxm/gates.yaml")]);
+    throw new KxmConfigError([issue("semantic", "registered_gates_removed", ".kxm/gates.yaml", "registeredGates was removed; declare gates in .kxm/gates.yaml")]);
   }
 }
 
-/** Load and semantically validate one complete, path-derived vNext configuration bundle. */
-export function loadVnextProject(projectRoot: string, options: VnextConfigOptions = {}): VnextProjectBundle {
+/** Load and semantically validate one complete, path-derived KXM configuration bundle. */
+export function loadKxmProject(projectRoot: string, options: KxmConfigOptions = {}): KxmProjectBundle {
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   let migrationReceipt: JsonObject | undefined;
   if (legacyConfigFilesAt(root).length > 0 && options.allowUnreceiptedLegacyConfig !== true) {
-    const receiptCheck = readVnextMigrationReceipt(root, options);
-    if (receiptCheck.issues.length > 0) throw new VnextConfigError(receiptCheck.issues);
+    const receiptCheck = readKxmMigrationReceipt(root, options);
+    if (receiptCheck.issues.length > 0) throw new KxmConfigError(receiptCheck.issues);
     migrationReceipt = receiptCheck.receipt;
   }
-  const registry = new VnextSchemaRegistry(options.schemasDir);
+  const registry = new KxmSchemaRegistry(options.schemasDir);
   const project = readResource(registry, root, join(root, ".kxm", "project.yaml"), ".kxm/project.yaml", "project");
-  const earlyIssues: VnextConfigIssue[] = [];
+  const earlyIssues: KxmConfigIssue[] = [];
   validatePortablePaths(project, earlyIssues);
   const templateProvenance = readTemplateProvenance(registry, root);
   if (templateProvenance && templateProvenance.inputs && typeof templateProvenance.inputs === "object" && !Array.isArray(templateProvenance.inputs)) {
@@ -1253,7 +1253,7 @@ export function loadVnextProject(projectRoot: string, options: VnextConfigOption
     }
   }
   if (migrationReceipt && stringValue(migrationReceipt.projectId) !== stringValue(project.value.id)) {
-    earlyIssues.push(issue("semantic", "migration_project_mismatch", VNEXT_MIGRATION_RECEIPT_PATH, "migration receipt belongs to a different project identity"));
+    earlyIssues.push(issue("semantic", "migration_project_mismatch", KXM_MIGRATION_RECEIPT_PATH, "migration receipt belongs to a different project identity"));
   }
   const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories")
     .map((candidate) => stringValue(objectValue(candidate)?.id))
@@ -1265,21 +1265,21 @@ export function loadVnextProject(projectRoot: string, options: VnextConfigOption
       earlyIssues.push(issue("reference", "repository_binding_unknown", ".kxm/project.yaml", `host-local binding references unknown repository ${repositoryId}`));
     }
   }
-  if (earlyIssues.length > 0) throw new VnextConfigError(earlyIssues);
+  if (earlyIssues.length > 0) throw new KxmConfigError(earlyIssues);
 
   const agents = listNamedResources(registry, root, join(root, ".kxm", "agents"), ".kxm/agents", "agent");
   const models = listNamedResources(registry, root, join(root, ".kxm", "models"), ".kxm/models", "model");
   const workflows = listNamedResources(registry, root, join(root, ".kxm", "workflows"), ".kxm/workflows", "workflow");
   const gatePath = join(root, ".kxm", "gates.yaml");
   const gateRegistry = existsSync(gatePath) ? readResource(registry, root, gatePath, ".kxm/gates.yaml", "gate-registry") : undefined;
-  const environments: VnextResource[] = [];
-  const repositories = new Map<string, VnextResource>();
-  const loadIssues: VnextConfigIssue[] = [];
+  const environments: KxmResource[] = [];
+  const repositories = new Map<string, KxmResource>();
+  const loadIssues: KxmConfigIssue[] = [];
 
   const projectEnvironment = join(root, ".kxm", "project", "env.yaml");
   if (existsSync(projectEnvironment)) {
     try { environments.push(readResource(registry, root, projectEnvironment, ".kxm/project/env.yaml", "environment")); }
-    catch (error) { if (error instanceof VnextConfigError) loadIssues.push(...error.issues); else throw error; }
+    catch (error) { if (error instanceof KxmConfigError) loadIssues.push(...error.issues); else throw error; }
   }
 
   const seenBindings = new Map<string, string>();
@@ -1358,7 +1358,7 @@ export function loadVnextProject(projectRoot: string, options: VnextConfigOption
           definitionValidated = repositories.get(repositoryId) === resource;
         }
       } catch (error) {
-        if (error instanceof VnextConfigError) loadIssues.push(...error.issues);
+        if (error instanceof KxmConfigError) loadIssues.push(...error.issues);
         else throw error;
       }
     } else if (required || hasLocalBinding) {
@@ -1370,14 +1370,14 @@ export function loadVnextProject(projectRoot: string, options: VnextConfigOption
         loadIssues.push(issue("reference", "repository_environment_without_definition", `.kxm/repositories/${repositoryId}/env.yaml`, `repository ${repositoryId} environment requires a validated matching repo.yaml`));
       } else {
         try { environments.push(readResource(registry, root, environmentFile, `.kxm/repositories/${repositoryId}/env.yaml`, "environment", undefined, binding)); }
-        catch (error) { if (error instanceof VnextConfigError) loadIssues.push(...error.issues); else throw error; }
+        catch (error) { if (error instanceof KxmConfigError) loadIssues.push(...error.issues); else throw error; }
       }
     }
   }
-  if (loadIssues.length > 0) throw new VnextConfigError(loadIssues);
+  if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
 
   const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
-  if (issues.length > 0) throw new VnextConfigError(issues);
+  if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...(gateRegistry ? [gateRegistry] : [])]
     .sort((left, right) => compareCodeUnits(left.logicalPath, right.logicalPath));
   return {
@@ -1401,15 +1401,15 @@ export function loadVnextProject(projectRoot: string, options: VnextConfigOption
  * revision and per-resource bytes. Load-time coexistence only pins the
  * legacy sources; this stricter check backs `kxm migrate verify`.
  */
-export function verifyVnextMigrationReceiptTarget(
+export function verifyKxmMigrationReceiptTarget(
   root: string,
   receipt: JsonObject,
-  resources: readonly VnextResource[],
+  resources: readonly KxmResource[],
   configRevision: string,
-): VnextConfigIssue[] {
-  const issues: VnextConfigIssue[] = [];
+): KxmConfigIssue[] {
+  const issues: KxmConfigIssue[] = [];
   if (receipt.configRevision !== configRevision) {
-    issues.push(issue("semantic", "migration_target_changed", VNEXT_MIGRATION_RECEIPT_PATH, "target configuration revision no longer matches the migration receipt"));
+    issues.push(issue("semantic", "migration_target_changed", KXM_MIGRATION_RECEIPT_PATH, "target configuration revision no longer matches the migration receipt"));
   }
   const declared = new Map<string, JsonObject>();
   for (const candidate of Array.isArray(receipt.resources) ? receipt.resources : []) {
@@ -1459,7 +1459,7 @@ function legacyInputsAt(root: string): string[] {
   return candidates.filter((candidate) => existsSync(join(root, ...candidate.split("/"))));
 }
 
-export const VNEXT_MIGRATION_RECEIPT_PATH = ".kxm/migration-receipt.yaml";
+export const KXM_MIGRATION_RECEIPT_PATH = ".kxm/migration-receipt.yaml";
 const LEGACY_CONFIG_FILES = [".kxm/config/agents.json", ".kxm/config/gates.json"] as const;
 
 /** Individual legacy configuration files (not directories, not runtime state) that a migration receipt must cover. */
@@ -1496,9 +1496,9 @@ export function legacyConfigFilesAt(root: string): string[] {
   return files;
 }
 
-export interface VnextMigrationReceiptCheck {
+export interface KxmMigrationReceiptCheck {
   receipt?: JsonObject;
-  issues: VnextConfigIssue[];
+  issues: KxmConfigIssue[];
 }
 
 function hashFileRecord(root: string, relativePath: string): { path: string; sha256: string; bytes: number } | undefined {
@@ -1514,7 +1514,7 @@ function hashFileRecord(root: string, relativePath: string): { path: string; sha
 
 export function migrationReceiptSelfHash(receipt: JsonObject): string {
   const { receiptSha256: _ignored, ...unsigned } = receipt;
-  return `sha256:${createHash("sha256").update(vnextCanonicalJson(unsigned as JsonObject), "utf8").digest("hex")}`;
+  return `sha256:${createHash("sha256").update(kxmCanonicalJson(unsigned as JsonObject), "utf8").digest("hex")}`;
 }
 
 /**
@@ -1522,36 +1522,36 @@ export function migrationReceiptSelfHash(receipt: JsonObject): string {
  * exact coverage of the legacy configuration files still present. Does not
  * compare the target configuration revision (computed by the caller).
  */
-export function readVnextMigrationReceipt(root: string, options: VnextConfigOptions = {}): VnextMigrationReceiptCheck {
-  const receiptPath = join(root, ...VNEXT_MIGRATION_RECEIPT_PATH.split("/"));
+export function readKxmMigrationReceipt(root: string, options: KxmConfigOptions = {}): KxmMigrationReceiptCheck {
+  const receiptPath = join(root, ...KXM_MIGRATION_RECEIPT_PATH.split("/"));
   const legacyFiles = legacyConfigFilesAt(root);
   if (!existsSync(receiptPath)) {
     return {
-      issues: legacyFiles.map((file) => issue("semantic", "legacy_vnext_conflict", file, "legacy and vNext configuration cannot coexist before an accepted migration receipt")),
+      issues: legacyFiles.map((file) => issue("semantic", "legacy_kxm_conflict", file, "legacy and KXM configuration cannot coexist before an accepted migration receipt")),
     };
   }
   const receiptStat = lstatSync(receiptPath);
   if (receiptStat.isSymbolicLink() || !receiptStat.isFile()) {
-    return { issues: [issue("path", "migration_receipt_invalid", VNEXT_MIGRATION_RECEIPT_PATH, "migration receipt must be a regular file, not a link")] };
+    return { issues: [issue("path", "migration_receipt_invalid", KXM_MIGRATION_RECEIPT_PATH, "migration receipt must be a regular file, not a link")] };
   }
   let receipt: JsonObject;
   try {
-    receipt = parseRestrictedYaml(readFileSync(receiptPath), VNEXT_MIGRATION_RECEIPT_PATH);
+    receipt = parseRestrictedYaml(readFileSync(receiptPath), KXM_MIGRATION_RECEIPT_PATH);
   } catch (error) {
-    if (error instanceof VnextConfigError) return { issues: [...error.issues] };
+    if (error instanceof KxmConfigError) return { issues: [...error.issues] };
     throw error;
   }
-  const registry = new VnextSchemaRegistry(options.schemasDir);
-  const schemaIssues = registry.validateMigrationReceipt(receipt, VNEXT_MIGRATION_RECEIPT_PATH);
+  const registry = new KxmSchemaRegistry(options.schemasDir);
+  const schemaIssues = registry.validateMigrationReceipt(receipt, KXM_MIGRATION_RECEIPT_PATH);
   if (schemaIssues.length > 0) return { issues: schemaIssues };
   if (receipt.receiptSha256 !== migrationReceiptSelfHash(receipt)) {
-    return { issues: [issue("semantic", "migration_receipt_hash_mismatch", VNEXT_MIGRATION_RECEIPT_PATH, "receipt self-hash does not match its content")] };
+    return { issues: [issue("semantic", "migration_receipt_hash_mismatch", KXM_MIGRATION_RECEIPT_PATH, "receipt self-hash does not match its content")] };
   }
   const sources = (Array.isArray(receipt.sources) ? receipt.sources : [])
     .map((candidate) => (candidate && typeof candidate === "object" && !Array.isArray(candidate) ? (candidate as JsonObject).path : undefined))
     .filter((candidate): candidate is string => typeof candidate === "string")
     .sort(compareCodeUnits);
-  const issues: VnextConfigIssue[] = [];
+  const issues: KxmConfigIssue[] = [];
   const declared = new Set(sources);
   for (const file of legacyFiles) {
     if (!declared.has(file)) {
@@ -1585,15 +1585,15 @@ function discoverLegacyRoot(start: string): { root: string; inputs: string[] } |
 }
 
 /** Classify init without changing files. Applying create/repair/migration is a separate, explicit operation. */
-export function planVnextInitialization(start = process.cwd(), options: VnextConfigOptions = {}): VnextInitializationPlan {
+export function planKxmInitialization(start = process.cwd(), options: KxmConfigOptions = {}): KxmInitializationPlan {
   const inspectedFrom = resolve(start);
-  const projectRoot = discoverVnextProjectRoot(inspectedFrom);
+  const projectRoot = discoverKxmProjectRoot(inspectedFrom);
   if (projectRoot) {
     try {
-      const bundle = loadVnextProject(projectRoot, options);
+      const bundle = loadKxmProject(projectRoot, options);
       return { mode: "ready", inspectedFrom, projectRoot, changesRequired: false, issues: [], legacyInputs: [], configRevision: bundle.configRevision };
     } catch (error) {
-      if (!(error instanceof VnextConfigError)) throw error;
+      if (!(error instanceof KxmConfigError)) throw error;
       const legacyInputs = legacyInputsAt(projectRoot);
       if (legacyInputs.length > 0) {
         return { mode: "migrate", inspectedFrom, projectRoot, legacyRoot: projectRoot, changesRequired: true, issues: error.issues, legacyInputs };