halfcode-compiler.xnl 0.1.1 → 0.2.0

package/dist/application-assembly.js

@@ -1,2 +1,2 @@
-import { a as assertObjectOperationCatalog, c as resolveApplicationAssembly, i as assertObjectOperationCall, l as resourceRefToFqn, n as applicationAssemblyPackage, o as assertObjectOperationDefinition, r as assertExecuteObjectOperationRequest, s as loadApplicationAssembly, t as ObjectOperationContractError } from "./src-Dv8bfFUo.js";
+import { a as assertObjectOperationCatalog, c as resolveApplicationAssembly, i as assertObjectOperationCall, l as resourceRefToFqn, n as applicationAssemblyPackage, o as assertObjectOperationDefinition, r as assertExecuteObjectOperationRequest, s as loadApplicationAssembly, t as ObjectOperationContractError } from "./src-DJr-I4Kc.js";
 export { ObjectOperationContractError, applicationAssemblyPackage, assertExecuteObjectOperationRequest, assertObjectOperationCall, assertObjectOperationCatalog, assertObjectOperationDefinition, loadApplicationAssembly, resolveApplicationAssembly, resourceRefToFqn };

package/dist/{index-DuRG4TQo.d.ts → index-DKwcVwK6.d.ts}

@@ -1,4 +1,4 @@
-import { n as ResourceDescriptor } from "./index-Ba5Gt9iW.js";
+import { r as ResourceDescriptor } from "./index-DqYap2u_.js";
 //#region ../resource-projection/src/index.d.ts
 interface ResourceRegistry {
   readonly byKind: ReadonlyMap<string, readonly ResourceDescriptor[]>;

package/dist/{index-Ba5Gt9iW.d.ts → index-DqYap2u_.d.ts}

@@ -35,8 +35,22 @@ interface ResourceRecord extends ResourceDescriptor {
   format: "xnl";
   node: ResourceNode;
 }
+interface ResourceKindContract {
+  resourceKind: string;
+  sourceShapes: readonly SourceShape[];
+  currentApiVersion: string;
+  supportedApiVersions: readonly string[];
+  documentCardinality?: "one" | "many";
+}
+interface RegisteredKindDefinition extends ResourceKindContract {
+  resourceId: string;
+  requiredFiles: readonly string[];
+  documentCardinality: "one" | "many";
+  documentUri: string;
+}
 interface ResourceRegistry {
   readonly byKind: ReadonlyMap<string, readonly ResourceRecord[]>;
+  readonly kindDefinitions: ReadonlyMap<string, RegisteredKindDefinition>;
 }
 interface ResourceTree {
   manifest: ResourceRecord;
@@ -64,4 +78,4 @@ declare class ResourceValidationError extends Error {
 declare function loadResourceTree(options: LoadResourceTreeOptions): Promise<ResourceTree>;
 declare function validateResourceTree(options: LoadResourceTreeOptions): Promise<ResourceDiagnostic[]>;
 //#endregion
-export { loadResourceTree as _, ResourceMetadata as a, ResourceRegistry as c, ResourceTreeBuildResult as d, ResourceValidationError as f, SourceShape as g, ResourceValueMap as h, ResourceIdentity as i, ResourceScalar as l, ResourceValueList as m, ResourceDescriptor as n, ResourceNode as o, ResourceValue as p, ResourceDiagnostic as r, ResourceRecord as s, LoadResourceTreeOptions as t, ResourceTree as u, validateResourceTree as v };
+export { ResourceValueMap as _, ResourceIdentity as a, validateResourceTree as b, ResourceNode as c, ResourceScalar as d, ResourceTree as f, ResourceValueList as g, ResourceValue as h, ResourceDiagnostic as i, ResourceRecord as l, ResourceValidationError as m, RegisteredKindDefinition as n, ResourceKindContract as o, ResourceTreeBuildResult as p, ResourceDescriptor as r, ResourceMetadata as s, LoadResourceTreeOptions as t, ResourceRegistry as u, SourceShape as v, loadResourceTree as y };

package/dist/{index-D-cBhQVw.d.ts → index-wU-iKJnW.d.ts}

@@ -1,5 +1,5 @@
 import { t as ApplicationAssembly } from "./index-FdimP_SL.js";
-import { t as ResourceRegistry } from "./index-DuRG4TQo.js";
+import { t as ResourceRegistry } from "./index-DKwcVwK6.js";
 //#region ../compiler-skill/src/index.d.ts
 interface SkillDescriptor {
   name: string;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 import { A as ObjectTargets, B as assertExecuteObjectOperationRequest, C as ObjectOperationDefinition, D as ObjectOperationTargetDeclaration, E as ObjectOperationOwnerKind, F as ResourceSource, G as resolveApplicationAssembly, H as assertObjectOperationCatalog, I as SkillCapsuleResource, K as resourceRefToFqn, L as TextMaterial, M as ResolveApplicationAssemblyOptions, N as ResolvedAssemblyPortBinding, O as ObjectTargetKindDefinition, P as ResourceInclude, R as TextResource, S as ObjectOperationContractError, T as ObjectOperationHandler, U as assertObjectOperationDefinition, V as assertObjectOperationCall, W as loadApplicationAssembly, _ as ObjectInvocationMode, a as AssemblyResource, b as ObjectOperationCatalog, c as BusinessObjectSopResource, d as ExecuteObjectOperationRequest, f as JsonObject, g as ObjectInvocation, h as LoadApplicationAssemblyOptions, i as AssemblyPortBinding, j as PageObjectResource, k as ObjectTargetRef, l as CodeBinding, m as JsonValue, n as ApplicationScope, o as AuthoringModuleDescriptor, p as JsonPrimitive, r as AssemblyPort, s as BusinessObjectResource, t as ApplicationAssembly, u as ContractedCallableResource, v as ObjectOperationBehavior, w as ObjectOperationEffect, x as ObjectOperationConfig, y as ObjectOperationCall, z as applicationAssemblyPackage } from "./index-FdimP_SL.js";
-import { a as SkillReference, c as compilerSkillPackage, i as SkillDescriptor, n as CompileSkillCapsuleInput, o as compileResourceSkillCapsule, r as SkillCapsulePlan, s as compileSkillCapsule, t as CompileResourceSkillCapsuleInput } from "./index-D-cBhQVw.js";
+import { a as SkillReference, c as compilerSkillPackage, i as SkillDescriptor, n as CompileSkillCapsuleInput, o as compileResourceSkillCapsule, r as SkillCapsulePlan, s as compileSkillCapsule, t as CompileResourceSkillCapsuleInput } from "./index-wU-iKJnW.js";
 export { type ApplicationAssembly, type ApplicationScope, type AssemblyPort, type AssemblyPortBinding, type AssemblyResource, type AuthoringModuleDescriptor, type BusinessObjectResource, type BusinessObjectSopResource, type CodeBinding, CompileResourceSkillCapsuleInput, CompileSkillCapsuleInput, type ContractedCallableResource, type ExecuteObjectOperationRequest, type JsonObject, type JsonPrimitive, type JsonValue, type LoadApplicationAssemblyOptions, type ObjectInvocation, type ObjectInvocationMode, type ObjectOperationBehavior, type ObjectOperationCall, type ObjectOperationCatalog, type ObjectOperationConfig, ObjectOperationContractError, type ObjectOperationDefinition, type ObjectOperationEffect, type ObjectOperationHandler, type ObjectOperationOwnerKind, type ObjectOperationTargetDeclaration, type ObjectTargetKindDefinition, type ObjectTargetRef, type ObjectTargets, type PageObjectResource, type ResolveApplicationAssemblyOptions, type ResolvedAssemblyPortBinding, type ResourceInclude, type ResourceSource, SkillCapsulePlan, type SkillCapsuleResource, SkillDescriptor, SkillReference, type TextMaterial, type TextResource, applicationAssemblyPackage, assertExecuteObjectOperationRequest, assertObjectOperationCall, assertObjectOperationCatalog, assertObjectOperationDefinition, compileResourceSkillCapsule, compileSkillCapsule, compilerSkillPackage, loadApplicationAssembly, resolveApplicationAssembly, resourceRefToFqn };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as assertObjectOperationCatalog, c as resolveApplicationAssembly, i as assertObjectOperationCall, l as resourceRefToFqn, n as applicationAssemblyPackage, o as assertObjectOperationDefinition, r as assertExecuteObjectOperationRequest, s as loadApplicationAssembly, t as ObjectOperationContractError } from "./src-Dv8bfFUo.js";
+import { a as assertObjectOperationCatalog, c as resolveApplicationAssembly, i as assertObjectOperationCall, l as resourceRefToFqn, n as applicationAssemblyPackage, o as assertObjectOperationDefinition, r as assertExecuteObjectOperationRequest, s as loadApplicationAssembly, t as ObjectOperationContractError } from "./src-DJr-I4Kc.js";
 import "./application-assembly.js";
-import { n as compileSkillCapsule, r as compilerSkillPackage, t as compileResourceSkillCapsule } from "./src-DEuFHizY.js";
+import { n as compileSkillCapsule, r as compilerSkillPackage, t as compileResourceSkillCapsule } from "./src-B36aAZZE.js";
 export { ObjectOperationContractError, applicationAssemblyPackage, assertExecuteObjectOperationRequest, assertObjectOperationCall, assertObjectOperationCatalog, assertObjectOperationDefinition, compileResourceSkillCapsule, compileSkillCapsule, compilerSkillPackage, loadApplicationAssembly, resolveApplicationAssembly, resourceRefToFqn };

package/dist/kind-definition.d.ts

@@ -1,9 +1,21 @@
-import { n as ResourceDescriptor } from "./index-Ba5Gt9iW.js";
+import { o as ResourceKindContract, r as ResourceDescriptor } from "./index-DqYap2u_.js";
 //#region ../kind-definition/src/index.d.ts
-interface KindDefinition extends ResourceDescriptor {
+interface KindDefinition extends ResourceDescriptor, ResourceKindContract {
   kind: "KindDefinition";
+}
+interface ResourceMigrationDefinition<T> {
+  id: string;
   resourceKind: string;
-  sourceShapes: readonly ("file" | "directory" | "manifest")[];
+  fromApiVersion: string;
+  toApiVersion: string;
+  migrate: (resource: T) => T;
+}
+declare class ResourceMigrationRegistry<T> {
+  private readonly definitions;
+  private readonly ids;
+  register(definition: ResourceMigrationDefinition<T>): this;
+  plan(resourceKind: string, fromApiVersion: string, toApiVersion: string): readonly ResourceMigrationDefinition<T>[];
+  migrate(resourceKind: string, fromApiVersion: string, toApiVersion: string, resource: T): T;
 }
 declare const kindDefinitionPackage: {
   readonly role: "framework";
@@ -11,4 +23,4 @@ declare const kindDefinitionPackage: {
   readonly owns: "resource kind validation authority";
 };
 //#endregion
-export { KindDefinition, kindDefinitionPackage };
+export { KindDefinition, ResourceMigrationDefinition, ResourceMigrationRegistry, kindDefinitionPackage };

package/dist/kind-definition.js

@@ -1,8 +1,40 @@
 //#region ../kind-definition/src/index.ts
+var ResourceMigrationRegistry = class {
+	definitions = [];
+	ids = /* @__PURE__ */ new Set();
+	register(definition) {
+		if (this.ids.has(definition.id)) throw new Error(`Duplicate migration id '${definition.id}'`);
+		if (!definition.id || !definition.resourceKind || !definition.fromApiVersion || !definition.toApiVersion) throw new Error("Migration definitions require id, resourceKind, fromApiVersion, and toApiVersion");
+		if (definition.fromApiVersion === definition.toApiVersion) throw new Error(`Migration '${definition.id}' must change apiVersion`);
+		this.ids.add(definition.id);
+		this.definitions.push(Object.freeze({ ...definition }));
+		return this;
+	}
+	plan(resourceKind, fromApiVersion, toApiVersion) {
+		if (fromApiVersion === toApiVersion) return [];
+		const steps = [];
+		const visited = /* @__PURE__ */ new Set();
+		let current = fromApiVersion;
+		while (current !== toApiVersion) {
+			if (visited.has(current)) throw new Error(`Migration cycle detected for Kind '${resourceKind}' at '${current}'`);
+			visited.add(current);
+			const candidates = this.definitions.filter((definition) => definition.resourceKind === resourceKind && definition.fromApiVersion === current);
+			if (candidates.length === 0) throw new Error(`No migration for Kind '${resourceKind}' from '${current}' to '${toApiVersion}'`);
+			if (candidates.length > 1) throw new Error(`Ambiguous migration for Kind '${resourceKind}' from '${current}': ${candidates.map((candidate) => candidate.id).join(", ")}`);
+			const step = candidates[0];
+			steps.push(step);
+			current = step.toApiVersion;
+		}
+		return Object.freeze(steps);
+	}
+	migrate(resourceKind, fromApiVersion, toApiVersion, resource) {
+		return this.plan(resourceKind, fromApiVersion, toApiVersion).reduce((value, step) => step.migrate(value), resource);
+	}
+};
 const kindDefinitionPackage = {
 	role: "framework",
 	area: "kind-definition",
 	owns: "resource kind validation authority"
 };
 //#endregion
-export { kindDefinitionPackage };
+export { ResourceMigrationRegistry, kindDefinitionPackage };

package/dist/resource-core.d.ts

@@ -1,2 +1,2 @@
-import { _ as loadResourceTree, a as ResourceMetadata, c as ResourceRegistry, d as ResourceTreeBuildResult, f as ResourceValidationError, g as SourceShape, h as ResourceValueMap, i as ResourceIdentity, l as ResourceScalar, m as ResourceValueList, n as ResourceDescriptor, o as ResourceNode, p as ResourceValue, r as ResourceDiagnostic, s as ResourceRecord, t as LoadResourceTreeOptions, u as ResourceTree, v as validateResourceTree } from "./index-Ba5Gt9iW.js";
-export { LoadResourceTreeOptions, ResourceDescriptor, ResourceDiagnostic, ResourceIdentity, ResourceMetadata, ResourceNode, ResourceRecord, ResourceRegistry, ResourceScalar, ResourceTree, ResourceTreeBuildResult, ResourceValidationError, ResourceValue, ResourceValueList, ResourceValueMap, SourceShape, loadResourceTree, validateResourceTree };
+import { _ as ResourceValueMap, a as ResourceIdentity, b as validateResourceTree, c as ResourceNode, d as ResourceScalar, f as ResourceTree, g as ResourceValueList, h as ResourceValue, i as ResourceDiagnostic, l as ResourceRecord, m as ResourceValidationError, n as RegisteredKindDefinition, o as ResourceKindContract, p as ResourceTreeBuildResult, r as ResourceDescriptor, s as ResourceMetadata, t as LoadResourceTreeOptions, u as ResourceRegistry, v as SourceShape, y as loadResourceTree } from "./index-DqYap2u_.js";
+export { LoadResourceTreeOptions, RegisteredKindDefinition, ResourceDescriptor, ResourceDiagnostic, ResourceIdentity, ResourceKindContract, ResourceMetadata, ResourceNode, ResourceRecord, ResourceRegistry, ResourceScalar, ResourceTree, ResourceTreeBuildResult, ResourceValidationError, ResourceValue, ResourceValueList, ResourceValueMap, SourceShape, loadResourceTree, validateResourceTree };

package/dist/resource-core.js

@@ -1,2 +1,2 @@
-import { n as loadResourceTree, r as validateResourceTree, t as ResourceValidationError } from "./src-COEMEqZw.js";
+import { n as loadResourceTree, r as validateResourceTree, t as ResourceValidationError } from "./src-xibObw5e.js";
 export { ResourceValidationError, loadResourceTree, validateResourceTree };

package/dist/resource-projection.d.ts

@@ -1,2 +1,2 @@
-import { n as resourceProjectionPackage, t as ResourceRegistry } from "./index-DuRG4TQo.js";
+import { n as resourceProjectionPackage, t as ResourceRegistry } from "./index-DKwcVwK6.js";
 export { ResourceRegistry, resourceProjectionPackage };

package/dist/skill-capsule.d.ts

@@ -1,2 +1,2 @@
-import { a as SkillReference, c as compilerSkillPackage, i as SkillDescriptor, n as CompileSkillCapsuleInput, o as compileResourceSkillCapsule, r as SkillCapsulePlan, s as compileSkillCapsule, t as CompileResourceSkillCapsuleInput } from "./index-D-cBhQVw.js";
+import { a as SkillReference, c as compilerSkillPackage, i as SkillDescriptor, n as CompileSkillCapsuleInput, o as compileResourceSkillCapsule, r as SkillCapsulePlan, s as compileSkillCapsule, t as CompileResourceSkillCapsuleInput } from "./index-wU-iKJnW.js";
 export { CompileResourceSkillCapsuleInput, CompileSkillCapsuleInput, SkillCapsulePlan, SkillDescriptor, SkillReference, compileResourceSkillCapsule, compileSkillCapsule, compilerSkillPackage };

package/dist/skill-capsule.js

@@ -1,2 +1,2 @@
-import { n as compileSkillCapsule, r as compilerSkillPackage, t as compileResourceSkillCapsule } from "./src-DEuFHizY.js";
+import { n as compileSkillCapsule, r as compilerSkillPackage, t as compileResourceSkillCapsule } from "./src-B36aAZZE.js";
 export { compileResourceSkillCapsule, compileSkillCapsule, compilerSkillPackage };

package/dist/{src-DEuFHizY.js → src-B36aAZZE.js}

@@ -1,4 +1,4 @@
-import { l as resourceRefToFqn, u as resolveObjectOperationCompilation } from "./src-Dv8bfFUo.js";
+import { l as resourceRefToFqn, u as resolveObjectOperationCompilation } from "./src-DJr-I4Kc.js";
 import { n as parseResourceMappings, r as planResourceMappings, t as applyResourceMappingPlan } from "./src-BlKlpg0J.js";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";

package/dist/{src-Dv8bfFUo.js → src-DJr-I4Kc.js}

@@ -1,4 +1,4 @@
-import { n as loadResourceTree } from "./src-COEMEqZw.js";
+import { n as loadResourceTree } from "./src-xibObw5e.js";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { parse } from "yaml";

package/dist/{src-COEMEqZw.js → src-xibObw5e.js}

@@ -3,8 +3,9 @@ import { readFile, readdir, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 //#region ../resource-core/src/xnl-loader.ts
 async function buildXnlResourceTree(options) {
+	const requestedRoot = resolve(options.rootDir);
 	const context = {
-		rootDir: resolve(options.rootDir),
+		rootDir: await realpath(requestedRoot).catch(() => requestedRoot),
 		diagnostics: [],
 		kindDefinitions: /* @__PURE__ */ new Map(),
 		resources: [],
@@ -22,7 +23,10 @@ async function buildXnlResourceTree(options) {
 		diagnostics: [],
 		tree: {
 			manifest,
-			registry: { byKind },
+			registry: {
+				byKind,
+				kindDefinitions: context.kindDefinitions
+			},
 			diagnostics: []
 		}
 	};
@@ -88,6 +92,7 @@ async function loadCatalog(catalog, manifestDir, context) {
 				context.diagnostics.push(kindMismatch(record.kind, catalog.kind, record.documentUri));
 				continue;
 			}
+			validateResourceApiVersion(record, definition, context.diagnostics);
 			await validateRequiredFiles(dirname(file), record, definition, context.diagnostics);
 			validateIdentity(record, context);
 			context.resources.push(record);
@@ -95,15 +100,25 @@ async function loadCatalog(catalog, manifestDir, context) {
 			for (const nested of catalogs.filter((item) => item.kind !== "KindDefinition")) await loadCatalog(nested, dirname(file), context);
 			continue;
 		}
-		const record = await loadXnlRecord(file, catalog.shape, context);
-		if (!record) continue;
-		if (record.kind !== catalog.kind) {
-			context.diagnostics.push(kindMismatch(record.kind, catalog.kind, record.documentUri));
+		if (definition.documentCardinality === "many" && catalog.shape !== "single-file") {
+			context.diagnostics.push({
+				code: "RESOURCE_DOCUMENT_CARDINALITY_UNSUPPORTED",
+				location: catalog.location,
+				message: `Kind '${catalog.kind}' allows multiple document roots only in a single-file catalog.`
+			});
 			continue;
 		}
-		await validateRequiredFiles(dirname(file), record, definition, context.diagnostics);
-		validateIdentity(record, context);
-		context.resources.push(record);
+		const records = await loadXnlRecords(file, catalog.shape, context, definition.documentCardinality);
+		for (const record of records) {
+			if (record.kind !== catalog.kind) {
+				context.diagnostics.push(kindMismatch(record.kind, catalog.kind, record.documentUri));
+				continue;
+			}
+			validateResourceApiVersion(record, definition, context.diagnostics);
+			await validateRequiredFiles(dirname(file), record, definition, context.diagnostics);
+			validateIdentity(record, context);
+			context.resources.push(record);
+		}
 	}
 }
 async function catalogFiles(catalog, manifestDir, context) {
@@ -130,6 +145,9 @@ async function catalogFiles(catalog, manifestDir, context) {
 	return entries.filter((entry) => entry.isDirectory()).sort((left, right) => left.name.localeCompare(right.name)).map((entry) => join(root, entry.name, catalog.entry));
 }
 async function loadXnlRecord(filePath, sourceShape, context) {
+	return (await loadXnlRecords(filePath, sourceShape, context, "one"))[0];
+}
+async function loadXnlRecords(filePath, sourceShape, context, documentCardinality) {
 	const documentUri = documentUriFor(context.rootDir, filePath);
 	const source = await readFile(filePath, "utf8").catch(() => void 0);
 	if (source === void 0) {
@@ -138,9 +156,9 @@ async function loadXnlRecord(filePath, sourceShape, context) {
 			location: documentUri,
 			message: "Resource file does not exist."
 		});
-		return;
+		return [];
 	}
-	let root;
+	let roots;
 	try {
 		const parsed = parseXnl(source, { textBlockStyle: true });
 		if (parsed.warnings?.length) {
@@ -149,25 +167,32 @@ async function loadXnlRecord(filePath, sourceShape, context) {
 				location: documentUri,
 				message: parsed.warnings.map((warning) => warning.message).join("; ")
 			});
-			return;
+			return [];
 		}
-		if (parsed.nodes.length !== 1 || !isDataElement(parsed.nodes[0])) {
+		if (parsed.nodes.length === 0 || parsed.nodes.some((node) => !isDataElement(node)) || documentCardinality === "one" && parsed.nodes.length !== 1) {
 			context.diagnostics.push({
 				code: "RESOURCE_XNL_ROOT_INVALID",
 				location: documentUri,
-				message: "XNL resource documents must contain exactly one data-element root."
+				message: documentCardinality === "one" ? "XNL resource documents must contain exactly one data-element root." : "XNL resource forests must contain one or more data-element roots."
 			});
-			return;
+			return [];
 		}
-		root = parsed.nodes[0];
+		roots = parsed.nodes;
 	} catch (error) {
 		context.diagnostics.push({
 			code: "RESOURCE_XNL_SYNTAX",
 			location: documentUri,
 			message: `Invalid XNL resource document: ${error instanceof Error ? error.message : String(error)}`
 		});
-		return;
+		return [];
 	}
+	return roots.flatMap((root) => {
+		const record = resourceRecordFromRoot(root, filePath, sourceShape, context);
+		return record ? [record] : [];
+	});
+}
+function resourceRecordFromRoot(root, filePath, sourceShape, context) {
+	const documentUri = documentUriFor(context.rootDir, filePath);
 	const node = normalizeNode(root);
 	const resourceId = node.resourceId;
 	const apiVersion = asString(node.metadata.apiVersion);
@@ -265,20 +290,55 @@ function normalizeKindDefinition(record, diagnostics) {
 	const resourceKind = asString(record.node.properties.resourceKind) ?? record.resourceId.split(".").at(-1);
 	const shapes = record.node.properties.sourceShapes;
 	const sourceShapes = Array.isArray(shapes) ? shapes.filter(isXnlShape) : [];
-	if (!resourceKind || sourceShapes.length === 0) {
+	const currentApiVersion = asString(record.node.properties.currentApiVersion);
+	const versions = record.node.properties.supportedApiVersions;
+	const supportedApiVersions = Array.isArray(versions) ? versions.filter((value) => typeof value === "string" && Boolean(value.trim())) : [];
+	const cardinalityValue = asString(record.node.properties.documentCardinality) ?? "one";
+	if (!resourceKind || sourceShapes.length === 0 || !currentApiVersion || supportedApiVersions.length === 0 || !isDocumentCardinality(cardinalityValue)) {
 		diagnostics.push({
 			code: "KIND_DEFINITION_INVALID",
 			location: record.documentUri,
-			message: "KindDefinition requires resourceKind (or an id suffix) and sourceShapes."
+			message: "KindDefinition requires resourceKind (or an id suffix), sourceShapes, currentApiVersion, and supportedApiVersions."
+		});
+		return;
+	}
+	if (!supportedApiVersions.includes(currentApiVersion)) {
+		diagnostics.push({
+			code: "KIND_DEFINITION_VERSION_INVALID",
+			location: record.documentUri,
+			message: `Kind '${resourceKind}' currentApiVersion '${currentApiVersion}' must be included in supportedApiVersions.`
 		});
 		return;
 	}
+	if (cardinalityValue === "many" && sourceShapes.some((shape) => shape !== "single-file")) {
+		diagnostics.push({
+			code: "KIND_DEFINITION_CARDINALITY_INVALID",
+			location: record.documentUri,
+			message: `Kind '${resourceKind}' documentCardinality 'many' requires only the single-file source shape.`
+		});
+		return;
+	}
+	const requiredFiles = ((record.node.subdomains.DescriptorContract?.subdomains.RequiredFiles)?.body ?? []).filter(isResourceNode).filter((node) => node.tag === "File").map((node) => asString(node.properties.name)).filter((value) => Boolean(value));
 	return {
+		resourceId: record.resourceId,
 		resourceKind,
-		sourceShapes,
-		requiredFiles: ((record.node.subdomains.DescriptorContract?.subdomains.RequiredFiles)?.body ?? []).filter(isResourceNode).filter((node) => node.tag === "File").map((node) => asString(node.properties.name)).filter((value) => Boolean(value))
+		sourceShapes: Object.freeze([...sourceShapes]),
+		requiredFiles: Object.freeze([...requiredFiles]),
+		currentApiVersion,
+		supportedApiVersions: Object.freeze([...new Set(supportedApiVersions)]),
+		documentCardinality: cardinalityValue,
+		documentUri: record.documentUri
 	};
 }
+function validateResourceApiVersion(record, definition, diagnostics) {
+	if (definition.supportedApiVersions.includes(record.metadata.apiVersion)) return;
+	diagnostics.push({
+		code: "RESOURCE_API_VERSION_UNSUPPORTED",
+		location: record.documentUri,
+		message: `Kind '${record.kind}' does not support apiVersion '${record.metadata.apiVersion}'.`,
+		hint: `Current apiVersion is '${definition.currentApiVersion}'.`
+	});
+}
 async function validateRequiredFiles(resourceDir, record, definition, diagnostics) {
 	for (const name of definition.requiredFiles) {
 		if (!isPlainEntry(name)) {
@@ -366,6 +426,9 @@ function kindMismatch(actual, expected, location) {
 function isXnlShape(value) {
 	return value === "single-file" || value === "directory" || value === "manifest";
 }
+function isDocumentCardinality(value) {
+	return value === "one" || value === "many";
+}
 function isPlainEntry(value) {
 	return Boolean(value) && !value.includes("/") && !value.includes("\\") && !value.includes("..");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcode-compiler.xnl",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Compile XNL-described applications into runtime-ready skill capsules.",
   "type": "module",
   "private": false,