halfcode-compiler.xnl 0.2.9 → 0.3.0

package/dist/resource-core-Brj8naBr.d.ts

@@ -0,0 +1,47 @@
+import { et as ResourceMetadata, i as AuthoredResourceTree, p as ResourceDiagnostic, st as ResourcePackageReadPort, yt as ResourceDigestContribution } from "./index-DboIOEr8.js";
+//#region ../resource-core/src/composition-error.d.ts
+declare class ResourceCompositionError extends Error {
+  readonly diagnostics: readonly ResourceDiagnostic[];
+  constructor(diagnostics: readonly ResourceDiagnostic[]);
+}
+//#endregion
+//#region ../resource-core/src/resource-material.d.ts
+interface ReadResourceMaterialInput {
+  readonly tree: AuthoredResourceTree;
+  readonly rootDir: string;
+  readonly resourceId: string;
+  readonly uri: string;
+}
+interface ResourceMaterial {
+  readonly resourceId: string;
+  readonly uri: string;
+  readonly sourceUri: string;
+  readonly digest: string;
+  readonly contribution: ResourceDigestContribution;
+  bytes(): Uint8Array;
+}
+declare class ResourceMaterialError extends Error {
+  readonly diagnostics: readonly ResourceDiagnostic[];
+  constructor(diagnostics: readonly ResourceDiagnostic[]);
+}
+declare function readResourceMaterial(input: ReadResourceMaterialInput): Promise<ResourceMaterial>;
+//#endregion
+//#region ../resource-core/src/directory-resource-package-read-port.d.ts
+declare function createDirectoryResourcePackageReadPort(rootDir: string): Promise<ResourcePackageReadPort>;
+//#endregion
+//#region ../resource-core/src/resource-envelope.d.ts
+interface ResourceMetadataDecodeInput {
+  readonly fields: Readonly<Record<string, unknown>>;
+  readonly removedFieldContainers?: readonly Readonly<Record<string, unknown>>[];
+  readonly lifecycle?: unknown;
+  readonly location: string;
+  readonly source: "XNL" | "Markdown";
+}
+type ResourceMetadataDecodeResult = Readonly<{
+  metadata: ResourceMetadata;
+}> | Readonly<{
+  diagnostic: ResourceDiagnostic;
+}>;
+declare function decodeResourceMetadata(input: ResourceMetadataDecodeInput): ResourceMetadataDecodeResult;
+//#endregion
+export { ReadResourceMaterialInput as a, readResourceMaterial as c, createDirectoryResourcePackageReadPort as i, ResourceCompositionError as l, ResourceMetadataDecodeResult as n, ResourceMaterial as o, decodeResourceMetadata as r, ResourceMaterialError as s, ResourceMetadataDecodeInput as t };

package/dist/resource-core.d.ts

@@ -1,4 +1,4 @@
-import { A as buildResourceDependencySnapshot, B as ResourceTombstone, C as BuildResourceDependencySnapshotInput, D as ResourceDependencySnapshot, E as ResourceDependencyEdge, F as EffectiveResourceEntry, H as composeLayeredResourceRegistry, I as EffectiveResourceRegistry, L as ResourceLayerDescriptor, M as sha256Digest, N as ComposeLayeredResourceRegistryInput, O as ResourceDigestContribution, P as EffectiveKindDefinition, R as ResourceLayerInput, S as validateResourceTree, T as ResourceContentIdentity, U as Sha256Digest, V as ResourceTombstoneOrigin, _ as ResourceValue, a as ResourceDescriptor, b as SourceShape, c as ResourceKindContract, d as ResourceRecord, f as ResourceRegistry, g as ResourceValidationError, h as ResourceTreeBuildResult, i as RegisteredKindDefinition, j as createResourceContentIdentity, k as SnapshotResource, l as ResourceMetadata, m as ResourceTree, n as LoadedResourceTree, o as ResourceDiagnostic, p as ResourceScalar, r as LoadedResourceTreeBuildResult, s as ResourceIdentity, t as LoadResourceTreeOptions, u as ResourceNode, v as ResourceValueList, w as CreateResourceContentIdentityInput, x as loadResourceTree, y as ResourceValueMap, z as ResourceOrigin } from "./index-CDIT65pI.js";
-import { a as ResourceCompositionError, i as readResourceMaterial, n as ResourceMaterial, r as ResourceMaterialError, t as ReadResourceMaterialInput } from "./resource-core-C0Fj-VJA.js";
-import { n as ResourceLayerContentIdentityInput, r as resolveEffectiveResourceContentIdentities, t as ResolveEffectiveResourceContentIdentitiesInput } from "./effective-content-identities-CSVFi-N5.js";
-export { BuildResourceDependencySnapshotInput, ComposeLayeredResourceRegistryInput, CreateResourceContentIdentityInput, EffectiveKindDefinition, EffectiveResourceEntry, EffectiveResourceRegistry, LoadResourceTreeOptions, LoadedResourceTree, LoadedResourceTreeBuildResult, ReadResourceMaterialInput, RegisteredKindDefinition, ResolveEffectiveResourceContentIdentitiesInput, ResourceCompositionError, ResourceContentIdentity, ResourceDependencyEdge, ResourceDependencySnapshot, ResourceDescriptor, ResourceDiagnostic, ResourceDigestContribution, ResourceIdentity, ResourceKindContract, ResourceLayerContentIdentityInput, ResourceLayerDescriptor, ResourceLayerInput, ResourceMaterial, ResourceMaterialError, ResourceMetadata, ResourceNode, ResourceOrigin, ResourceRecord, ResourceRegistry, ResourceScalar, ResourceTombstone, ResourceTombstoneOrigin, ResourceTree, ResourceTreeBuildResult, ResourceValidationError, ResourceValue, ResourceValueList, ResourceValueMap, type Sha256Digest, SnapshotResource, SourceShape, buildResourceDependencySnapshot, composeLayeredResourceRegistry, createResourceContentIdentity, loadResourceTree, readResourceMaterial, resolveEffectiveResourceContentIdentities, sha256Digest, validateResourceTree };
+import { $ as RESOURCE_ENVELOPE_VERSION, A as validateResourceTreeFromReadPort, At as ResourceOrigin, B as KindSpecRevision, C as ResourceValue, Ct as sha256Digest, D as loadResourceTree, Dt as EffectiveResourceRegistry, E as SourceShape, Et as EffectiveResourceEntry, F as KindContractLockReader, Ft as canonicalJson, G as ReaderProfile, H as KindWriterRegistration, I as KindReaderRegistration, It as compareCodeUnits, J as ResourceResolutionReceipt, K as ReaderTarget, L as KindSemanticContract, Lt as digestCanonical, M as JsonSchema, Mt as ResourceTombstoneOrigin, N as JsonSchemaValidator, Nt as composeLayeredResourceRegistry, O as loadResourceTreeFromReadPort, Ot as ResourceLayerDescriptor, P as KindContractLock, Pt as Sha256Digest, Q as RESOURCE_ENVELOPE_FINGERPRINT, R as KindSourceContract, S as ResourceValidationError, St as createResourceContentIdentity, T as ResourceValueMap, Tt as EffectiveKindDefinition, U as PortableSpec, V as KindSubjectOwner, W as PortableValue, X as CORE_BOOTSTRAP_WRITER_SPEC_VERSIONS, Y as SpecResolutionDefinition, Z as RESOURCE_ENVELOPE_CONTRACT, _ as ResourceRecord, _t as ResourceDependencyEdge, a as AuthoredResourceTreeBuildResult, at as ResourcePackageEntry, b as ResourceTree, bt as SnapshotResource, c as RegisteredKindDefinition, ct as ResourcePackageReadPortOptions, d as ResolvedResourceTree, dt as dirnameResourcePackageSourcePath, et as ResourceMetadata, f as ResourceDescriptor, ft as joinResourcePackageSourcePath, g as ResourceNode, gt as ResourceContentIdentity, h as ResourceKindContract, ht as CreateResourceContentIdentityInput, i as AuthoredResourceTree, it as ResourcePackageDirectoryEntry, j as CompatibilityPolicy, jt as ResourceTombstone, k as validateResourceTree, kt as ResourceLayerInput, l as ResolvedResourceRecord, lt as ResourcePackageSourcePathError, m as ResourceIdentity, mt as BuildResourceDependencySnapshotInput, n as AuthoredResourceRegistry, nt as isSpecVersion, o as KindSpecRevisionDescriptor, ot as ResourcePackageEntryKind, p as ResourceDiagnostic, pt as relativeResourcePackageSourcePath, q as ResolvedSpec, r as AuthoredResourceSpec, rt as ResourcePackageAwaitable, s as LoadResourceTreeOptions, st as ResourcePackageReadPort, t as AuthoredResourceRecord, tt as SpecVersion, u as ResolvedResourceRegistry, ut as canonicalResourcePackageSourcePath, v as ResourceRegistry, vt as ResourceDependencySnapshot, w as ResourceValueList, wt as ComposeLayeredResourceRegistryInput, x as ResourceTreeBuildResult, xt as buildResourceDependencySnapshot, y as ResourceScalar, yt as ResourceDigestContribution, z as KindSourceShape } from "./index-DboIOEr8.js";
+import { a as ReadResourceMaterialInput, c as readResourceMaterial, i as createDirectoryResourcePackageReadPort, l as ResourceCompositionError, n as ResourceMetadataDecodeResult, o as ResourceMaterial, r as decodeResourceMetadata, s as ResourceMaterialError, t as ResourceMetadataDecodeInput } from "./resource-core-Brj8naBr.js";
+import { n as ResourceLayerContentIdentityInput, r as resolveEffectiveResourceContentIdentities, t as ResolveEffectiveResourceContentIdentitiesInput } from "./effective-content-identities-drMRhYE2.js";
+export { AuthoredResourceRecord, AuthoredResourceRegistry, AuthoredResourceSpec, AuthoredResourceTree, AuthoredResourceTreeBuildResult, BuildResourceDependencySnapshotInput, CORE_BOOTSTRAP_WRITER_SPEC_VERSIONS, CompatibilityPolicy, ComposeLayeredResourceRegistryInput, CreateResourceContentIdentityInput, EffectiveKindDefinition, EffectiveResourceEntry, EffectiveResourceRegistry, JsonSchema, JsonSchemaValidator, KindContractLock, KindContractLockReader, KindReaderRegistration, KindSemanticContract, KindSourceContract, KindSourceShape, KindSpecRevision, KindSpecRevisionDescriptor, KindSubjectOwner, KindWriterRegistration, LoadResourceTreeOptions, PortableSpec, PortableValue, RESOURCE_ENVELOPE_CONTRACT, RESOURCE_ENVELOPE_FINGERPRINT, RESOURCE_ENVELOPE_VERSION, ReadResourceMaterialInput, ReaderProfile, ReaderTarget, RegisteredKindDefinition, ResolveEffectiveResourceContentIdentitiesInput, ResolvedResourceRecord, ResolvedResourceRegistry, ResolvedResourceTree, ResolvedSpec, ResourceCompositionError, ResourceContentIdentity, ResourceDependencyEdge, ResourceDependencySnapshot, ResourceDescriptor, ResourceDiagnostic, ResourceDigestContribution, ResourceIdentity, ResourceKindContract, ResourceLayerContentIdentityInput, ResourceLayerDescriptor, ResourceLayerInput, ResourceMaterial, ResourceMaterialError, ResourceMetadata, ResourceMetadataDecodeInput, ResourceMetadataDecodeResult, ResourceNode, ResourceOrigin, ResourcePackageAwaitable, ResourcePackageDirectoryEntry, ResourcePackageEntry, ResourcePackageEntryKind, ResourcePackageReadPort, ResourcePackageReadPortOptions, ResourcePackageSourcePathError, ResourceRecord, ResourceRegistry, ResourceResolutionReceipt, ResourceScalar, ResourceTombstone, ResourceTombstoneOrigin, ResourceTree, ResourceTreeBuildResult, ResourceValidationError, ResourceValue, ResourceValueList, ResourceValueMap, type Sha256Digest, SnapshotResource, SourceShape, SpecResolutionDefinition, SpecVersion, buildResourceDependencySnapshot, canonicalJson, canonicalResourcePackageSourcePath, compareCodeUnits, composeLayeredResourceRegistry, createDirectoryResourcePackageReadPort, createResourceContentIdentity, decodeResourceMetadata, digestCanonical, dirnameResourcePackageSourcePath, isSpecVersion, joinResourcePackageSourcePath, loadResourceTree, loadResourceTreeFromReadPort, readResourceMaterial, relativeResourcePackageSourcePath, resolveEffectiveResourceContentIdentities, sha256Digest, validateResourceTree, validateResourceTreeFromReadPort };

package/dist/resource-core.js

@@ -1,5 +1,5 @@
-import { a as isLoadedResourceTreeAuthentic, c as sha256Digest, d as markEffectiveRegistryAuthentic, f as ResourceCompositionError, i as readonlyMap, m as digestCanonical, n as loadResourceTree, o as buildResourceDependencySnapshot, p as compareCodeUnits, r as validateResourceTree, s as createResourceContentIdentity, t as ResourceValidationError } from "./src-D3qSzGFn.js";
-import { t as resolveEffectiveResourceContentIdentities } from "./effective-content-identities-DV5fTr5Q.js";
+import { C as digestCanonical, D as dirnameResourcePackageSourcePath, E as canonicalResourcePackageSourcePath, O as joinResourcePackageSourcePath, S as compareCodeUnits, T as ResourcePackageSourcePathError, a as validateResourceTreeFromReadPort, b as ResourceCompositionError, c as RESOURCE_ENVELOPE_CONTRACT, d as isSpecVersion, f as readonlyMap, g as sha256Digest, h as createResourceContentIdentity, i as validateResourceTree, k as relativeResourcePackageSourcePath, l as RESOURCE_ENVELOPE_FINGERPRINT, m as buildResourceDependencySnapshot, n as loadResourceTree, o as decodeResourceMetadata, p as isAuthoredResourceTreeAuthentic, r as loadResourceTreeFromReadPort, s as CORE_BOOTSTRAP_WRITER_SPEC_VERSIONS, t as ResourceValidationError, u as RESOURCE_ENVELOPE_VERSION, w as createDirectoryResourcePackageReadPort, x as canonicalJson, y as markEffectiveRegistryAuthentic } from "./src-jggOQtq3.js";
+import { t as resolveEffectiveResourceContentIdentities } from "./effective-content-identities-CV6XFBZy.js";
 import { lstat, readFile, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 //#region ../resource-core/src/layered-registry.ts
@@ -236,9 +236,9 @@ function cloneResourceRecord(resource) {
 }
 function cloneResourceMetadata(metadata) {
 	return Object.freeze({
-		apiVersion: metadata.apiVersion,
-		...metadata.lifecycle === void 0 ? {} : { lifecycle: metadata.lifecycle },
-		...metadata.version === void 0 ? {} : { version: metadata.version }
+		envelopeVersion: metadata.envelopeVersion,
+		specVersion: metadata.specVersion,
+		...metadata.lifecycle === void 0 ? {} : { lifecycle: metadata.lifecycle }
 	});
 }
 function cloneResourceValue(value) {
@@ -252,10 +252,17 @@ function cloneRegisteredKindDefinition(definition) {
 	return Object.freeze({
 		resourceId: definition.resourceId,
 		resourceKind: definition.resourceKind,
+		subjectFqn: definition.subjectFqn,
 		sourceShapes: Object.freeze([...definition.sourceShapes].sort(compareCodeUnits)),
 		requiredFiles: Object.freeze([...definition.requiredFiles].sort(compareCodeUnits)),
-		currentApiVersion: definition.currentApiVersion,
-		supportedApiVersions: Object.freeze([...definition.supportedApiVersions].sort(compareCodeUnits)),
+		specRevisions: Object.freeze(definition.specRevisions.map((revision) => Object.freeze({
+			specVersion: revision.specVersion,
+			schemaRef: revision.schemaRef,
+			schemaFingerprint: revision.schemaFingerprint,
+			contractFingerprint: revision.contractFingerprint,
+			semanticContract: Object.freeze({ ...revision.semanticContract }),
+			stability: revision.stability
+		})).sort((left, right) => left.specVersion - right.specVersion)),
 		documentCardinality: definition.documentCardinality,
 		documentUri: definition.documentUri
 	});
@@ -263,10 +270,17 @@ function cloneRegisteredKindDefinition(definition) {
 function normalizedKindContract(definition) {
 	return {
 		resourceKind: definition.resourceKind,
+		subjectFqn: definition.subjectFqn,
 		sourceShapes: [...definition.sourceShapes].sort(compareCodeUnits),
 		requiredFiles: [...definition.requiredFiles].sort(compareCodeUnits),
-		currentApiVersion: definition.currentApiVersion,
-		supportedApiVersions: [...definition.supportedApiVersions].sort(compareCodeUnits),
+		specRevisions: definition.specRevisions.map((revision) => ({
+			specVersion: revision.specVersion,
+			schemaRef: revision.schemaRef,
+			schemaFingerprint: revision.schemaFingerprint,
+			contractFingerprint: revision.contractFingerprint,
+			semanticContract: revision.semanticContract,
+			stability: revision.stability
+		})),
 		documentCardinality: definition.documentCardinality
 	};
 }
@@ -326,7 +340,7 @@ var ResourceMaterialError = class extends Error {
 	}
 };
 async function readResourceMaterial(input) {
-	if (!isLoadedResourceTreeAuthentic(input.tree)) throw materialError("RESOURCE_MATERIAL_TREE_UNTRUSTED", input.resourceId, "Resource materials require an authentic LoadedResourceTree.");
+	if (!isAuthoredResourceTreeAuthentic(input.tree)) throw materialError("RESOURCE_MATERIAL_TREE_UNTRUSTED", input.resourceId, "Resource materials require an authentic AuthoredResourceTree.");
 	const record = findResource(input.tree, input.resourceId);
 	const identity = input.tree.contentIdentities.get(input.resourceId);
 	if (!record || record.sourceShape !== "directory" || !identity) throw materialError("RESOURCE_MATERIAL_RESOURCE_INVALID", input.resourceId, `Resource '${input.resourceId}' is not an authentic directory resource.`);
@@ -400,4 +414,4 @@ function materialError(code, resourceId, message) {
 	})]);
 }
 //#endregion
-export { ResourceCompositionError, ResourceMaterialError, ResourceValidationError, buildResourceDependencySnapshot, composeLayeredResourceRegistry, createResourceContentIdentity, loadResourceTree, readResourceMaterial, resolveEffectiveResourceContentIdentities, sha256Digest, validateResourceTree };
+export { CORE_BOOTSTRAP_WRITER_SPEC_VERSIONS, RESOURCE_ENVELOPE_CONTRACT, RESOURCE_ENVELOPE_FINGERPRINT, RESOURCE_ENVELOPE_VERSION, ResourceCompositionError, ResourceMaterialError, ResourcePackageSourcePathError, ResourceValidationError, buildResourceDependencySnapshot, canonicalJson, canonicalResourcePackageSourcePath, compareCodeUnits, composeLayeredResourceRegistry, createDirectoryResourcePackageReadPort, createResourceContentIdentity, decodeResourceMetadata, digestCanonical, dirnameResourcePackageSourcePath, isSpecVersion, joinResourcePackageSourcePath, loadResourceTree, loadResourceTreeFromReadPort, readResourceMaterial, relativeResourcePackageSourcePath, resolveEffectiveResourceContentIdentities, sha256Digest, validateResourceTree, validateResourceTreeFromReadPort };

package/dist/resource-projection.d.ts

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

package/dist/skill-capsule.d.ts

@@ -1,3 +1,3 @@
-import { I as SkillCapsuleDependency } from "./index-Cqh9pEBa.js";
-import { S as skillCapsuleDistributionProjection, _ as applySkillCapsuleDistributionPlan, a as PlannedSkillCapsule, b as compilerSkillPackage, c as SkillCapsuleContentDigest, d as SkillCapsuleDistributionReceipt, f as SkillCapsuleIdentity, g as SkillReference, h as SkillDescriptor, i as PlanSkillCapsuleDistributionInput, l as SkillCapsuleDistributionError, m as SkillCapsuleProvenanceManifest, n as CompileResourceSkillCapsuleInput, o as PlannedSkillFile, p as SkillCapsulePlan, r as CompileSkillCapsuleInput, s as SkillCapsuleApplyStep, t as ApplySkillCapsuleDistributionOptions, u as SkillCapsuleDistributionPlan, v as compileResourceSkillCapsule, x as planSkillCapsuleDistribution, y as compileSkillCapsule } from "./index-B515mMkO.js";
+import { I as SkillCapsuleDependency } from "./index-DEikbOFh.js";
+import { S as skillCapsuleDistributionProjection, _ as applySkillCapsuleDistributionPlan, a as PlannedSkillCapsule, b as compilerSkillPackage, c as SkillCapsuleContentDigest, d as SkillCapsuleDistributionReceipt, f as SkillCapsuleIdentity, g as SkillReference, h as SkillDescriptor, i as PlanSkillCapsuleDistributionInput, l as SkillCapsuleDistributionError, m as SkillCapsuleProvenanceManifest, n as CompileResourceSkillCapsuleInput, o as PlannedSkillFile, p as SkillCapsulePlan, r as CompileSkillCapsuleInput, s as SkillCapsuleApplyStep, t as ApplySkillCapsuleDistributionOptions, u as SkillCapsuleDistributionPlan, v as compileResourceSkillCapsule, x as planSkillCapsuleDistribution, y as compileSkillCapsule } from "./index-CR7wJSSX.js";
 export { ApplySkillCapsuleDistributionOptions, CompileResourceSkillCapsuleInput, CompileSkillCapsuleInput, PlanSkillCapsuleDistributionInput, PlannedSkillCapsule, PlannedSkillFile, SkillCapsuleApplyStep, SkillCapsuleContentDigest, type SkillCapsuleDependency, SkillCapsuleDistributionError, SkillCapsuleDistributionPlan, SkillCapsuleDistributionReceipt, SkillCapsuleIdentity, SkillCapsulePlan, SkillCapsuleProvenanceManifest, SkillDescriptor, SkillReference, applySkillCapsuleDistributionPlan, compileResourceSkillCapsule, compileSkillCapsule, compilerSkillPackage, planSkillCapsuleDistribution, skillCapsuleDistributionProjection };

package/dist/skill-capsule.js

@@ -1,2 +1,2 @@
-import { a as compilerSkillPackage, i as compileSkillCapsule, n as applySkillCapsuleDistributionPlan, o as planSkillCapsuleDistribution, r as compileResourceSkillCapsule, s as skillCapsuleDistributionProjection, t as SkillCapsuleDistributionError } from "./src-CaQ25rMj.js";
+import { a as compilerSkillPackage, i as compileSkillCapsule, n as applySkillCapsuleDistributionPlan, o as planSkillCapsuleDistribution, r as compileResourceSkillCapsule, s as skillCapsuleDistributionProjection, t as SkillCapsuleDistributionError } from "./src-DLJUCH0M.js";
 export { SkillCapsuleDistributionError, applySkillCapsuleDistributionPlan, compileResourceSkillCapsule, compileSkillCapsule, compilerSkillPackage, planSkillCapsuleDistribution, skillCapsuleDistributionProjection };

package/dist/{src-3pnDAjBD.js → src-B0Hja_dk.js}

@@ -1,4 +1,4 @@
-import { n as loadResourceTree } from "./src-D3qSzGFn.js";
+import { n as loadResourceTree } from "./src-jggOQtq3.js";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { parse } from "yaml";
@@ -388,14 +388,11 @@ async function readTextResource(module, record, kind) {
 async function readSkillCapsule(module, record) {
 	const metadataMaterial = await readRequiredMaterial(module, record, "SkillMetadata");
 	const template = await readRequiredMaterial(module, record, "Template");
-	const version = record.metadata.version;
-	const apiVersion = record.metadata.apiVersion;
-	if (!apiVersion) throw new Error(`SKILL_CAPSULE_API_VERSION_MISSING: ${record.logicalPath} is missing XNL metadata apiVersion`);
-	if (!version) throw new Error(`SKILL_CAPSULE_VERSION_MISSING: ${record.logicalPath} is missing XNL metadata version`);
 	const parsedMetadata = parse(metadataMaterial.content);
 	if (!parsedMetadata || typeof parsedMetadata !== "object" || Array.isArray(parsedMetadata)) throw new Error(`SKILL_CAPSULE_METADATA_INVALID: ${record.logicalPath} Skill metadata must be a YAML object`);
 	const yamlVersion = parsedMetadata.version;
-	if (yamlVersion !== void 0 && yamlVersion !== version) throw new Error(`SKILL_CAPSULE_VERSION_CONFLICT: ${requiredFqn(record)} YAML version ${JSON.stringify(yamlVersion)} does not match XNL version ${version}`);
+	if (typeof yamlVersion !== "string" || !yamlVersion.trim()) throw new Error(`SKILL_CAPSULE_VERSION_MISSING: ${record.logicalPath} Skill metadata must declare a non-empty version`);
+	const version = yamlVersion.trim();
 	const hasXnlName = Object.prototype.hasOwnProperty.call(record.node.properties, "name");
 	const xnlName = stringResourceValue(record.node.properties.name);
 	if (hasXnlName && !xnlName) throw new Error(`SKILL_CAPSULE_NAME_INVALID: ${requiredFqn(record)} XNL name must be a non-empty string`);
@@ -404,7 +401,8 @@ async function readSkillCapsule(module, record) {
 		kind: "SkillCapsule",
 		fqn: requiredFqn(record),
 		...xnlName ? { name: xnlName } : {},
-		apiVersion,
+		envelopeVersion: record.metadata.envelopeVersion,
+		specVersion: record.metadata.specVersion,
 		version,
 		description: requiredDescription(record),
 		metadata: {

package/dist/{src-CaQ25rMj.js → src-DLJUCH0M.js}

@@ -1,4 +1,4 @@
-import { l as resourceRefToFqn, u as resolveObjectOperationCompilation } from "./src-3pnDAjBD.js";
+import { l as resourceRefToFqn, u as resolveObjectOperationCompilation } from "./src-B0Hja_dk.js";
 import { c as unsafeUnicodeCodeUnitIssue, i as planResourceMappings, o as safePathLexicalIssue, r as parseResourceMappings, t as ResourceMappingPathError } from "./src-25wZPUyX.js";
 import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, posix, resolve } from "node:path";
@@ -70,7 +70,8 @@ async function planSkillCapsuleDistribution(input) {
 			const targetRelativePath = posix.join(identity.name, file.targetRelativePath);
 			return plannedSkillFile({
 				skillFqn: identity.fqn,
-				skillApiVersion: identity.apiVersion,
+				skillEnvelopeVersion: identity.envelopeVersion,
+				skillSpecVersion: identity.specVersion,
 				skillVersion: identity.version,
 				capsuleRelativePath: file.targetRelativePath,
 				targetRelativePath
@@ -294,7 +295,8 @@ function skillIdentity(skill) {
 	return Object.freeze({
 		fqn: skill.fqn,
 		name: skillOutputName(skill),
-		apiVersion: skill.apiVersion,
+		envelopeVersion: skill.envelopeVersion,
+		specVersion: skill.specVersion,
 		version: skill.version
 	});
 }
@@ -338,7 +340,7 @@ function assertValidDistributionPlan(plan) {
 	const capsuleByFqn = /* @__PURE__ */ new Map();
 	for (const capsule of plan.capsules) {
 		validateSkillOutputName(capsule.identity.name);
-		if (!capsule.identity.fqn.trim() || !capsule.identity.apiVersion.trim() || !capsule.identity.version.trim()) failDistribution("SKILL_PLAN_IDENTITY_INVALID", "planned Skill identity requires non-empty FQN, apiVersion and version");
+		if (!capsule.identity.fqn.trim() || !capsule.identity.envelopeVersion.trim() || !Number.isSafeInteger(capsule.identity.specVersion) || capsule.identity.specVersion <= 0 || !capsule.identity.version.trim()) failDistribution("SKILL_PLAN_IDENTITY_INVALID", "planned Skill identity requires non-empty FQN/envelopeVersion/version and a positive specVersion");
 		if (capsuleByFqn.has(capsule.identity.fqn)) failDistribution("SKILL_PLAN_CAPSULE_DUPLICATE", `duplicate planned capsule ${capsule.identity.fqn}`);
 		capsuleByFqn.set(capsule.identity.fqn, capsule);
 		for (const file of capsule.files) {
@@ -348,7 +350,7 @@ function assertValidDistributionPlan(plan) {
 		assertCanonicalSkillEntry(capsule);
 		for (const file of capsule.files) {
 			assertValidPlannedFile(file);
-			if (file.skillFqn !== capsule.identity.fqn || file.skillApiVersion !== capsule.identity.apiVersion || file.skillVersion !== capsule.identity.version) failDistribution("SKILL_PLAN_FILE_OWNER_INVALID", `file ${file.targetRelativePath} has the wrong Skill owner`);
+			if (file.skillFqn !== capsule.identity.fqn || file.skillEnvelopeVersion !== capsule.identity.envelopeVersion || file.skillSpecVersion !== capsule.identity.specVersion || file.skillVersion !== capsule.identity.version) failDistribution("SKILL_PLAN_FILE_OWNER_INVALID", `file ${file.targetRelativePath} has the wrong Skill owner`);
 			if (file.targetRelativePath !== posix.join(capsule.identity.name, file.capsuleRelativePath)) failDistribution("SKILL_PLAN_TARGET_INVALID", `file ${file.targetRelativePath} is outside Skill output ${capsule.identity.name}`);
 		}
 		assertCanonicalSkillProvenance(capsule);
@@ -448,7 +450,8 @@ function bytesEqual(left, right) {
 function fileDigestProjection(file) {
 	return {
 		skillFqn: file.skillFqn,
-		skillApiVersion: file.skillApiVersion,
+		skillEnvelopeVersion: file.skillEnvelopeVersion,
+		skillSpecVersion: file.skillSpecVersion,
 		skillVersion: file.skillVersion,
 		capsuleRelativePath: file.capsuleRelativePath,
 		targetRelativePath: file.targetRelativePath,
@@ -476,7 +479,8 @@ function canonicalSkillProvenanceBytes(identity, payloadFiles) {
 		generatedBy: "halfcode.skill-distribution/v1",
 		source: {
 			fqn: identity.fqn,
-			apiVersion: identity.apiVersion,
+			envelopeVersion: identity.envelopeVersion,
+			specVersion: identity.specVersion,
 			version: identity.version
 		},
 		payloadFiles: payloadFiles.map((file) => ({

package/dist/{src-3MZLm339.js → src-hrUy4DJ9.js}

@@ -1,5 +1,5 @@
-import "./src-D3qSzGFn.js";
-import { t as resolveEffectiveResourceContentIdentities } from "./effective-content-identities-DV5fTr5Q.js";
+import { d as isSpecVersion, u as RESOURCE_ENVELOPE_VERSION } from "./src-jggOQtq3.js";
+import { t as resolveEffectiveResourceContentIdentities } from "./effective-content-identities-CV6XFBZy.js";
 import { createHash } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region ../runtime-authoring/src/resource-authoring.ts
@@ -37,7 +37,8 @@ function planResourceAuthoring(runtime, input, _config) {
 	if (proposal.operation === "create" !== (proposal.expected.state === "absent")) fail("RESOURCE_AUTHORING_EXPECTED_STATE_INVALID", "Create requires absent state and update requires present state.");
 	const kindDefinition = planning.kindDefinitions.find((item) => item.kind === proposal.kind);
 	if (!kindDefinition) fail("RESOURCE_AUTHORING_KIND_UNKNOWN", `Kind '${proposal.kind}' is not registered.`);
-	if (!kindDefinition.supportedApiVersions.includes(proposal.apiVersion)) fail("RESOURCE_AUTHORING_API_VERSION_UNSUPPORTED", `Kind '${proposal.kind}' does not support '${proposal.apiVersion}'.`);
+	const writerSpecRevision = kindDefinition.specRevisions.find((revision) => revision.specVersion === proposal.writerSpecVersion);
+	if (!writerSpecRevision) fail("RESOURCE_AUTHORING_WRITER_SPEC_VERSION_UNREGISTERED", `Kind '${proposal.kind}' has no exact writer spec revision ${proposal.writerSpecVersion}.`);
 	if (!kindDefinition.sourceShapes.includes(proposal.sourceShape)) fail("RESOURCE_AUTHORING_SOURCE_SHAPE_UNSUPPORTED", `Kind '${proposal.kind}' does not support '${proposal.sourceShape}'.`);
 	const catalog = planning.catalogs.find((item) => item.catalogId === proposal.catalogId);
 	if (!catalog) fail("RESOURCE_AUTHORING_CATALOG_UNKNOWN", `Catalog '${proposal.catalogId}' is not registered.`);
@@ -61,7 +62,7 @@ function planResourceAuthoring(runtime, input, _config) {
 	for (const resource of inspection.resources) {
 		if (resourceIds.has(resource.resourceId)) fail("RESOURCE_AUTHORING_AUTHORITY_INVALID", "Authority document repeats a resource identity.");
 		resourceIds.add(resource.resourceId);
-		if (resource.kind !== proposal.kind || resource.apiVersion !== proposal.apiVersion) fail("RESOURCE_AUTHORING_AUTHORITY_INVALID", "Every authority root must match the proposed Kind and apiVersion.");
+		if (resource.kind !== proposal.kind || resource.envelopeVersion !== proposal.envelopeVersion || resource.writerSpecVersion !== proposal.writerSpecVersion) fail("RESOURCE_AUTHORING_AUTHORITY_INVALID", "Every authority root must match the proposed Kind, envelopeVersion and writerSpecVersion.");
 	}
 	if (!resourceIds.has(proposal.resourceId)) fail("RESOURCE_AUTHORING_AUTHORITY_INVALID", `Authority document does not contain target '${proposal.resourceId}'.`);
 	const authorityDigest = digestText(proposal.authorityText);
@@ -70,6 +71,7 @@ function planResourceAuthoring(runtime, input, _config) {
 		schemaVersion: RESOURCE_AUTHORING_SCHEMA_VERSION,
 		proposal,
 		kindDefinition,
+		writerSpecRevision,
 		catalog,
 		resources: inspection.resources,
 		authorityDigest
@@ -156,11 +158,12 @@ function verifyCandidate(candidate, prepared, plan) {
 	const identity = identities.get(plan.proposal.resourceId);
 	const resource = target?.resource;
 	const origin = target?.effectiveOrigin;
-	if (!resource || !identity || !origin || target.kind !== plan.proposal.kind || resource.metadata.apiVersion !== plan.proposal.apiVersion || resource.sourceShape !== plan.proposal.sourceShape || resource.documentUri !== plan.proposal.documentUri || identity.authorityDigest !== plan.authorityDigest || origin.layerId !== candidate.targetLayerId || origin.documentUri !== plan.proposal.documentUri) fail("RESOURCE_AUTHORING_REFRESH_INVALID", "Candidate refresh does not project the planned effective resource and authority.");
+	if (!resource || !identity || !origin || target.kind !== plan.proposal.kind || resource.metadata.envelopeVersion !== plan.proposal.envelopeVersion || resource.metadata.specVersion !== plan.proposal.writerSpecVersion || resource.sourceShape !== plan.proposal.sourceShape || resource.documentUri !== plan.proposal.documentUri || identity.authorityDigest !== plan.authorityDigest || origin.layerId !== candidate.targetLayerId || origin.documentUri !== plan.proposal.documentUri) fail("RESOURCE_AUTHORING_REFRESH_INVALID", "Candidate refresh does not project the planned effective resource and authority.");
 	const actualRoots = recordsAtDocument(candidate.tree, plan.proposal.documentUri).map((record) => ({
 		resourceId: record.resourceId,
 		kind: record.kind,
-		apiVersion: record.metadata.apiVersion
+		envelopeVersion: record.metadata.envelopeVersion,
+		writerSpecVersion: record.metadata.specVersion
 	})).sort(compareInspectedRoots);
 	const plannedRoots = [...plan.resources].sort(compareInspectedRoots);
 	if (canonicalJson(actualRoots) !== canonicalJson(plannedRoots)) fail("RESOURCE_AUTHORING_REFRESH_INVALID", "Candidate refresh changed the whole authority-document resource set.");
@@ -181,7 +184,8 @@ function verifyCandidate(candidate, prepared, plan) {
 		catalogId: plan.proposal.catalogId,
 		resourceId: plan.proposal.resourceId,
 		kind: plan.proposal.kind,
-		apiVersion: plan.proposal.apiVersion,
+		envelopeVersion: plan.proposal.envelopeVersion,
+		writerSpecVersion: plan.proposal.writerSpecVersion,
 		sourceShape: plan.proposal.sourceShape,
 		documentUri: plan.proposal.documentUri,
 		authorityDigestBefore: prepared.authorityDigestBefore,
@@ -206,7 +210,7 @@ function verifyCandidate(candidate, prepared, plan) {
 function verifyReceipt(value, plan, expected) {
 	const receipt = normalizeReceipt(value);
 	const authorityDigestBefore = plan.proposal.expected.state === "present" ? plan.proposal.expected.authorityDigest : null;
-	if (receipt.planDigest !== plan.planDigest || receipt.operation !== plan.proposal.operation || receipt.catalogId !== plan.proposal.catalogId || receipt.resourceId !== plan.proposal.resourceId || receipt.kind !== plan.proposal.kind || receipt.apiVersion !== plan.proposal.apiVersion || receipt.sourceShape !== plan.proposal.sourceShape || receipt.documentUri !== plan.proposal.documentUri || receipt.authorityDigestBefore !== authorityDigestBefore || receipt.authorityDigestAfter !== plan.authorityDigest || receipt.registryRevisionBefore !== plan.proposal.expected.registryRevision || receipt.registryRevisionAfter === receipt.registryRevisionBefore || receipt.effectiveOrigin.documentUri !== plan.proposal.documentUri || canonicalJson(receipt.authorityResourceIds) !== canonicalJson(plan.resources.map((item) => item.resourceId).sort(compareCodeUnits)) || expected && canonicalJson(receipt) !== canonicalJson(expected)) fail("RESOURCE_AUTHORING_COMMIT_INVALID", "Durable receipt does not match the exact accepted plan and refresh projection.");
+	if (receipt.planDigest !== plan.planDigest || receipt.operation !== plan.proposal.operation || receipt.catalogId !== plan.proposal.catalogId || receipt.resourceId !== plan.proposal.resourceId || receipt.kind !== plan.proposal.kind || receipt.envelopeVersion !== plan.proposal.envelopeVersion || receipt.writerSpecVersion !== plan.proposal.writerSpecVersion || receipt.sourceShape !== plan.proposal.sourceShape || receipt.documentUri !== plan.proposal.documentUri || receipt.authorityDigestBefore !== authorityDigestBefore || receipt.authorityDigestAfter !== plan.authorityDigest || receipt.registryRevisionBefore !== plan.proposal.expected.registryRevision || receipt.registryRevisionAfter === receipt.registryRevisionBefore || receipt.effectiveOrigin.documentUri !== plan.proposal.documentUri || canonicalJson(receipt.authorityResourceIds) !== canonicalJson(plan.resources.map((item) => item.resourceId).sort(compareCodeUnits)) || expected && canonicalJson(receipt) !== canonicalJson(expected)) fail("RESOURCE_AUTHORING_COMMIT_INVALID", "Durable receipt does not match the exact accepted plan and refresh projection.");
 	return receipt;
 }
 function normalizeProposal(value) {
@@ -216,13 +220,15 @@ function normalizeProposal(value) {
 		"catalogId",
 		"resourceId",
 		"kind",
-		"apiVersion",
+		"envelopeVersion",
+		"writerSpecVersion",
 		"sourceShape",
 		"documentUri",
 		"authorityText",
 		"expected"
 	], "proposal");
 	if (input.schemaVersion !== "halfcode.resource-authoring/v1") invalid("proposal.schemaVersion");
+	if (input.envelopeVersion !== "halfcode.resource-envelope/v1") invalid("proposal.envelopeVersion");
 	if (input.operation !== "create" && input.operation !== "update") invalid("proposal.operation");
 	if (input.sourceShape !== "single-file") fail("RESOURCE_AUTHORING_SOURCE_SHAPE_UNSUPPORTED", "The initial authoring transaction supports only single-file authority.");
 	const documentUri = normalizeDocumentUri(input.documentUri, "proposal.documentUri");
@@ -253,7 +259,8 @@ function normalizeProposal(value) {
 		catalogId: requiredString(input.catalogId, "proposal.catalogId"),
 		resourceId: requiredString(input.resourceId, "proposal.resourceId"),
 		kind: requiredString(input.kind, "proposal.kind"),
-		apiVersion: requiredString(input.apiVersion, "proposal.apiVersion"),
+		envelopeVersion: RESOURCE_ENVELOPE_VERSION,
+		writerSpecVersion: exactSpecVersion(input.writerSpecVersion, "proposal.writerSpecVersion"),
 		sourceShape: "single-file",
 		documentUri,
 		authorityText,
@@ -268,20 +275,24 @@ function normalizePlanningAuthority(value) {
 	], "planning");
 	const registryRevision = digestString(input.registryRevision, "planning.registryRevision");
 	const kindDefinitions = ownArray(input.kindDefinitions, "planning.kindDefinitions").map((item, index) => {
+		const location = `planning.kindDefinitions[${index}]`;
 		const record = ownRecord(item, [
 			"kind",
-			"supportedApiVersions",
+			"specRevisions",
 			"sourceShapes",
 			"documentCardinality"
-		], `planning.kindDefinitions[${index}]`);
+		], location);
 		const sourceShapes = ownArray(record.sourceShapes, `planning.kindDefinitions[${index}].sourceShapes`).map((shape) => {
 			if (shape !== "single-file") fail("RESOURCE_AUTHORING_SOURCE_SHAPE_UNSUPPORTED", "Planning authority contains an unsupported source shape.");
 			return shape;
 		});
 		if (record.documentCardinality !== "one" && record.documentCardinality !== "many") invalid(`planning.kindDefinitions[${index}].documentCardinality`);
+		const specRevisions = ownArray(record.specRevisions, `${location}.specRevisions`).map((revision, revisionIndex) => normalizeSpecRevision(revision, `${location}.specRevisions[${revisionIndex}]`)).sort((left, right) => left.specVersion - right.specVersion);
+		if (specRevisions.length === 0) invalid(`${location}.specRevisions`);
+		requireUnique(specRevisions.map((revision) => String(revision.specVersion)), `${location} spec revision`);
 		return deepFreeze({
-			kind: requiredString(record.kind, `planning.kindDefinitions[${index}].kind`),
-			supportedApiVersions: [...uniqueStrings(record.supportedApiVersions, `planning.kindDefinitions[${index}].supportedApiVersions`)].sort(compareCodeUnits),
+			kind: requiredString(record.kind, `${location}.kind`),
+			specRevisions,
 			sourceShapes: sourceShapes.sort(compareCodeUnits),
 			documentCardinality: record.documentCardinality
 		});
@@ -317,12 +328,14 @@ function normalizeInspection(value) {
 		const record = ownRecord(item, [
 			"resourceId",
 			"kind",
-			"apiVersion"
+			"envelopeVersion",
+			"writerSpecVersion"
 		], `authorityInspection.resources[${index}]`);
 		return deepFreeze({
 			resourceId: requiredString(record.resourceId, `authorityInspection.resources[${index}].resourceId`),
 			kind: requiredString(record.kind, `authorityInspection.resources[${index}].kind`),
-			apiVersion: requiredString(record.apiVersion, `authorityInspection.resources[${index}].apiVersion`)
+			envelopeVersion: requiredString(record.envelopeVersion, `authorityInspection.resources[${index}].envelopeVersion`),
+			writerSpecVersion: exactSpecVersion(record.writerSpecVersion, `authorityInspection.resources[${index}].writerSpecVersion`)
 		});
 	}).sort(compareInspectedRoots);
 	return deepFreeze({
@@ -330,11 +343,40 @@ function normalizeInspection(value) {
 		resources
 	});
 }
+function normalizeSpecRevision(value, location) {
+	const input = ownRecord(value, [
+		"specVersion",
+		"schemaRef",
+		"schemaFingerprint",
+		"contractFingerprint",
+		"semanticContract",
+		"stability"
+	], location);
+	const semantic = ownRecord(input.semanticContract, [
+		"semanticValidatorFingerprint",
+		"referenceProjectionFingerprint",
+		"compilerInputFingerprint"
+	], `${location}.semanticContract`);
+	if (input.stability !== "experimental" && input.stability !== "stable" && input.stability !== "deprecated") invalid(`${location}.stability`);
+	return deepFreeze({
+		specVersion: exactSpecVersion(input.specVersion, `${location}.specVersion`),
+		schemaRef: requiredString(input.schemaRef, `${location}.schemaRef`),
+		schemaFingerprint: digestString(input.schemaFingerprint, `${location}.schemaFingerprint`),
+		contractFingerprint: digestString(input.contractFingerprint, `${location}.contractFingerprint`),
+		semanticContract: {
+			semanticValidatorFingerprint: digestString(semantic.semanticValidatorFingerprint, `${location}.semanticContract.semanticValidatorFingerprint`),
+			referenceProjectionFingerprint: digestString(semantic.referenceProjectionFingerprint, `${location}.semanticContract.referenceProjectionFingerprint`),
+			compilerInputFingerprint: digestString(semantic.compilerInputFingerprint, `${location}.semanticContract.compilerInputFingerprint`)
+		},
+		stability: input.stability
+	});
+}
 function normalizePlan(value) {
 	const input = ownRecord(value, [
 		"schemaVersion",
 		"proposal",
 		"kindDefinition",
+		"writerSpecRevision",
 		"catalog",
 		"resources",
 		"authorityDigest",
@@ -351,6 +393,7 @@ function normalizePlan(value) {
 		schemaVersion: RESOURCE_AUTHORING_SCHEMA_VERSION,
 		proposal,
 		kindDefinition: authority.kindDefinitions[0],
+		writerSpecRevision: normalizeSpecRevision(input.writerSpecRevision, "plan.writerSpecRevision"),
 		catalog: authority.catalogs[0],
 		resources: normalizeInspection({
 			documentUri: proposal.documentUri,
@@ -358,6 +401,8 @@ function normalizePlan(value) {
 		}).resources,
 		authorityDigest: digestString(input.authorityDigest, "plan.authorityDigest")
 	};
+	const admittedRevision = unsigned.kindDefinition.specRevisions.find((revision) => revision.specVersion === proposal.writerSpecVersion);
+	if (!admittedRevision || canonicalJson(admittedRevision) !== canonicalJson(unsigned.writerSpecRevision)) fail("RESOURCE_AUTHORING_PLAN_FORGED", "Plan writer spec revision is not the exact admitted revision.");
 	const planDigest = digestString(input.planDigest, "plan.planDigest");
 	if (digestValue(unsigned) !== planDigest) fail("RESOURCE_AUTHORING_PLAN_FORGED", "Resource authoring plan digest is invalid.");
 	return deepFreeze({
@@ -388,7 +433,8 @@ function normalizeReceipt(value) {
 		"catalogId",
 		"resourceId",
 		"kind",
-		"apiVersion",
+		"envelopeVersion",
+		"writerSpecVersion",
 		"sourceShape",
 		"documentUri",
 		"authorityDigestBefore",
@@ -401,6 +447,7 @@ function normalizeReceipt(value) {
 		"receiptDigest"
 	], "receipt");
 	if (input.schemaVersion !== "halfcode.resource-authoring/v1") invalid("receipt.schemaVersion");
+	if (input.envelopeVersion !== "halfcode.resource-envelope/v1") invalid("receipt.envelopeVersion");
 	if (input.operation !== "create" && input.operation !== "update") invalid("receipt.operation");
 	if (input.sourceShape !== "single-file") invalid("receipt.sourceShape");
 	const origin = ownRecordOptional(input.effectiveOrigin, [
@@ -418,7 +465,8 @@ function normalizeReceipt(value) {
 		catalogId: requiredString(input.catalogId, "receipt.catalogId"),
 		resourceId: requiredString(input.resourceId, "receipt.resourceId"),
 		kind: requiredString(input.kind, "receipt.kind"),
-		apiVersion: requiredString(input.apiVersion, "receipt.apiVersion"),
+		envelopeVersion: RESOURCE_ENVELOPE_VERSION,
+		writerSpecVersion: exactSpecVersion(input.writerSpecVersion, "receipt.writerSpecVersion"),
 		sourceShape: "single-file",
 		documentUri: normalizeDocumentUri(input.documentUri, "receipt.documentUri"),
 		authorityDigestBefore: input.authorityDigestBefore === null ? null : digestString(input.authorityDigestBefore, "receipt.authorityDigestBefore"),
@@ -451,7 +499,7 @@ function recordsAtDocument(tree, documentUri) {
 	return [...tree.registry.byKind.values()].flatMap((records) => [...records]).filter((record) => record.documentUri === documentUri);
 }
 function compareInspectedRoots(left, right) {
-	return compareCodeUnits(left.resourceId, right.resourceId) || compareCodeUnits(left.kind, right.kind) || compareCodeUnits(left.apiVersion, right.apiVersion);
+	return compareCodeUnits(left.resourceId, right.resourceId) || compareCodeUnits(left.kind, right.kind) || compareCodeUnits(left.envelopeVersion, right.envelopeVersion) || left.writerSpecVersion - right.writerSpecVersion;
 }
 function compareCodeUnits(left, right) {
 	return left < right ? -1 : left > right ? 1 : 0;
@@ -508,6 +556,10 @@ function digestString(value, location) {
 	if (!/^sha256:[0-9a-f]{64}$/u.test(text)) invalid(location);
 	return text;
 }
+function exactSpecVersion(value, location) {
+	if (!isSpecVersion(value)) invalid(location);
+	return value;
+}
 function normalizeDocumentUri(value, location) {
 	const text = requiredString(value, location);
 	const logicalPath = text.startsWith("vfs://@/") ? text.slice(8) : "";