halfcode-compiler.xnl 0.2.9 → 0.3.1

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

@@ -1,5 +1,6 @@
-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 { d as CodeClosureError, p as validateCodeClosure } from "./src-BX7wrSq1.js";
 import { createHash } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region ../runtime-authoring/src/resource-authoring.ts
@@ -37,7 +38,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 +63,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 +72,7 @@ function planResourceAuthoring(runtime, input, _config) {
 		schemaVersion: RESOURCE_AUTHORING_SCHEMA_VERSION,
 		proposal,
 		kindDefinition,
+		writerSpecRevision,
 		catalog,
 		resources: inspection.resources,
 		authorityDigest
@@ -156,11 +159,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 +185,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 +211,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 +221,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 +260,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 +276,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 +329,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 +344,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 +394,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 +402,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 +434,8 @@ function normalizeReceipt(value) {
 		"catalogId",
 		"resourceId",
 		"kind",
-		"apiVersion",
+		"envelopeVersion",
+		"writerSpecVersion",
 		"sourceShape",
 		"documentUri",
 		"authorityDigestBefore",
@@ -401,6 +448,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 +466,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 +500,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 +557,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) : "";
@@ -548,6 +601,55 @@ function fail(code, message) {
 	throw new ResourceAuthoringError(code, message);
 }
 //#endregion
+//#region ../runtime-authoring/src/code-execution.ts
+/** Each restore owns a fresh module table; this is not an untrusted-code sandbox. */
+function restoreCodeClosure(runtime, input, expectedDigest) {
+	validateCodeClosure(input, runtime.environment, expectedDigest);
+	const closure = JSON.parse(JSON.stringify(input));
+	const ambient = /* @__PURE__ */ new Map();
+	for (const name of Object.keys(closure.environment.ambient)) {
+		if (!runtime.ambientModules || !Object.hasOwn(runtime.ambientModules, name)) throw new CodeClosureError("missing-ambient", `Missing explicit ambient exports: ${name}`);
+		ambient.set(name, runtime.ambientModules[name]);
+	}
+	const modules = new Map(closure.modules.map((module) => [module.path, module]));
+	const assets = new Map(closure.assets.map((asset) => [asset.path, asset.format === "json" ? JSON.parse(asset.content) : asset.content]));
+	const table = /* @__PURE__ */ new Map();
+	const load = (path) => {
+		const cached = table.get(path);
+		if (cached) return cached.exports;
+		const source = modules.get(path);
+		if (!source) throw new CodeClosureError("missing-module", `Frozen module absent: ${path}`);
+		const module = { exports: {} };
+		table.set(path, module);
+		const edges = new Map(source.dependencies.map((edge) => [edge.specifier, edge]));
+		const requireFrozen = (specifier) => {
+			const edge = edges.get(specifier);
+			if (!edge) throw new CodeClosureError("undeclared-dependency", `No frozen edge for ${path}: ${specifier}`);
+			if (edge.kind === "module") return load(edge.target);
+			if (edge.kind === "asset") return assets.get(edge.target);
+			return ambient.get(edge.target);
+		};
+		try {
+			new Function("require", "module", "exports", source.code)(requireFrozen, module, module.exports);
+			return module.exports;
+		} catch (error) {
+			table.delete(path);
+			throw error;
+		}
+	};
+	return Object.freeze({
+		binding: Object.freeze(closure.binding),
+		closureDigest: closure.digest,
+		exports: load(closure.entryPath)
+	});
+}
+function bindCodeClosure(runtime, closure, expectedDigest) {
+	const restored = restoreCodeClosure(runtime, closure, expectedDigest);
+	const callable = restored.exports[restored.binding.exportName];
+	if (typeof callable !== "function") throw new CodeClosureError("missing-export", `CodeBinding export is not callable: ${restored.binding.exportName}`);
+	return (...args) => Reflect.apply(callable, void 0, args);
+}
+//#endregion
 //#region ../runtime-authoring/src/index.ts
 const runtimeScope = new AsyncLocalStorage();
 function runWithRuntime(runtime, callback) {
@@ -585,4 +687,4 @@ const runtimeAuthoringPackage = {
 	owns: "target-neutral deterministic-code runtime and effect boundary"
 };
 //#endregion
-export { runWithRuntime as a, ResourceAuthoringError as c, planResourceAuthoring as d, logger as i, applyResourceAuthoring as l, currentRuntime as n, runtimeAuthoringPackage as o, invokeEffect as r, RESOURCE_AUTHORING_SCHEMA_VERSION as s, createAuthoringBindings as t, deriveResourceAuthoringRegistryRevision as u };
+export { runWithRuntime as a, restoreCodeClosure as c, applyResourceAuthoring as d, deriveResourceAuthoringRegistryRevision as f, logger as i, RESOURCE_AUTHORING_SCHEMA_VERSION as l, currentRuntime as n, runtimeAuthoringPackage as o, planResourceAuthoring as p, invokeEffect as r, bindCodeClosure as s, createAuthoringBindings as t, ResourceAuthoringError as u };

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

@@ -1,4 +1,4 @@
-import { l as resourceRefToFqn, u as resolveObjectOperationCompilation } from "./src-3pnDAjBD.js";
+import { l as resourceRefToFqn, m as resolveObjectOperationCompilation } from "./src-BX7wrSq1.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) => ({