create-agdf 0.14.3 → 0.14.5

package/lib/release/version-coherence.js

@@ -1,34 +1,78 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
-function jsonVersion(relativePath, select = (value) => value.version) {
-  return {
+function valueAtPath(value, path) {
+  return path.reduce((current, key) => current?.[key], value);
+}
+
+function setValueAtPath(value, path, nextVersion) {
+  let current = value;
+  for (const key of path.slice(0, -1)) {
+    if (!current?.[key] || typeof current[key] !== "object" || Array.isArray(current[key])) {
+      throw new Error(`missing JSON version path ${path.join(".")}`);
+    }
+    current = current[key];
+  }
+  const key = path.at(-1);
+  if (typeof current?.[key] !== "string") {
+    throw new Error(`missing JSON version path ${path.join(".")}`);
+  }
+  current[key] = nextVersion;
+}
+
+function jsonVersion(relativePath, path = ["version"], options = {}) {
+  return Object.freeze({
     relativePath,
-    read: (repoRoot) => select(JSON.parse(readFileSync(join(repoRoot, relativePath), "utf8"))),
-  };
+    writable: options.writable ?? false,
+    evidence: options.evidence ?? true,
+    readContent(content) {
+      return valueAtPath(JSON.parse(content), path);
+    },
+    updateContent(content, nextVersion) {
+      const value = JSON.parse(content);
+      setValueAtPath(value, path, nextVersion);
+      return `${JSON.stringify(value, null, 2)}\n`;
+    },
+  });
 }
 
-function textVersion(relativePath, pattern) {
-  return {
+function textVersion(relativePath, pattern, replacement, options = {}) {
+  return Object.freeze({
     relativePath,
-    read: (repoRoot) => readFileSync(join(repoRoot, relativePath), "utf8").match(pattern)?.[1],
-  };
+    writable: options.writable ?? false,
+    evidence: options.evidence ?? true,
+    readContent(content) {
+      return content.match(pattern)?.[1];
+    },
+    updateContent(content, nextVersion) {
+      const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+      const matches = [...content.matchAll(new RegExp(pattern.source, flags))];
+      if (matches.length !== 1) {
+        throw new Error(`expected exactly one version field in ${relativePath}; found ${matches.length}`);
+      }
+      return content.replace(pattern, replacement(nextVersion));
+    },
+  });
 }
 
-const VERSION_SURFACES = [
-  jsonVersion("plugin/.codex-plugin/plugin.json"),
-  jsonVersion("plugin/.claude-plugin/plugin.json"),
-  jsonVersion("create-agdf/package.json"),
-  jsonVersion("agdf/package.json"),
-  jsonVersion("agdf/package.json", (value) => value.dependencies?.["create-agdf"]),
-  jsonVersion("pages/package.json"),
-  jsonVersion("pages/package-lock.json"),
-  jsonVersion("pages/package-lock.json", (value) => value.packages?.[""]?.version),
-  textVersion("pages/src/data/site.ts", /version:\s*"([^"]+)"/),
-  jsonVersion("plugin/submission/openai/capability-matrix.json", (value) => value.releaseVersion),
-  jsonVersion("plugin/submission/openai/reviewer-cases.json", (value) => value.releaseVersion),
-  textVersion("plugin/submission/openai/release-notes.md", /^# AGDF (\S+) —/m),
-  textVersion("plugin/submission/openai/availability.md", /^- release: `([^`]+)`$/m),
+const writable = Object.freeze({ writable: true });
+const authority = Object.freeze({ writable: true, evidence: false });
+
+export const RELEASE_VERSION_SURFACES = Object.freeze([
+  jsonVersion("plugin/meta/agdf-plugin.definition.json", ["version"], authority),
+  jsonVersion("plugin/.codex-plugin/plugin.json", ["version"], writable),
+  jsonVersion("plugin/.claude-plugin/plugin.json", ["version"], writable),
+  jsonVersion("create-agdf/package.json", ["version"], writable),
+  jsonVersion("agdf/package.json", ["version"], writable),
+  jsonVersion("agdf/package.json", ["dependencies", "create-agdf"], writable),
+  jsonVersion("pages/package.json", ["version"], writable),
+  jsonVersion("pages/package-lock.json", ["version"], writable),
+  jsonVersion("pages/package-lock.json", ["packages", "", "version"], writable),
+  textVersion("pages/src/data/site.ts", /version:\s*"([^"]+)"/, (version) => `version: "${version}"`, writable),
+  jsonVersion("plugin/submission/openai/capability-matrix.json", ["releaseVersion"], writable),
+  jsonVersion("plugin/submission/openai/reviewer-cases.json", ["releaseVersion"], writable),
+  textVersion("plugin/submission/openai/release-notes.md", /^# AGDF (\S+) —/m, (version) => `# AGDF ${version} —`, writable),
+  textVersion("plugin/submission/openai/availability.md", /^- release: `([^`]+)`$/m, (version) => `- release: \`${version}\``, writable),
   jsonVersion("create-agdf/generated/plugins/agdf/meta/agdf-plugin.definition.json"),
   jsonVersion("create-agdf/generated/plugins/agdf/.codex-plugin/plugin.json"),
   jsonVersion("create-agdf/generated/plugins/agdf/.claude-plugin/plugin.json"),
@@ -40,25 +84,35 @@ const VERSION_SURFACES = [
   jsonVersion("create-agdf/generated/plugins/copilot/agdf/runtime/create-agdf/package.json"),
   jsonVersion("create-agdf/generated/submissions/openai/agdf/meta/agdf-plugin.definition.json"),
   jsonVersion("create-agdf/generated/submissions/openai/agdf/.codex-plugin/plugin.json"),
-  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/capability-matrix.json", (value) => value.releaseVersion),
-  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/reviewer-cases.json", (value) => value.releaseVersion),
-  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/listing.json", (value) => value.releaseVersion),
-  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/inventory.json", (value) => value.releaseVersion),
-  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/readiness.json", (value) => value.releaseVersion),
-  textVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/release-notes.md", /^# AGDF (\S+) —/m),
-  textVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/availability.md", /^- release: `([^`]+)`$/m),
-  textVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/readiness.md", /^- release: `([^`]+)`$/m),
-];
+  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/capability-matrix.json", ["releaseVersion"]),
+  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/reviewer-cases.json", ["releaseVersion"]),
+  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/listing.json", ["releaseVersion"]),
+  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/inventory.json", ["releaseVersion"]),
+  jsonVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/readiness.json", ["releaseVersion"]),
+  textVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/release-notes.md", /^# AGDF (\S+) —/m, () => ""),
+  textVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/availability.md", /^- release: `([^`]+)`$/m, () => ""),
+  textVersion("create-agdf/generated/submissions/openai/agdf/submission/openai/readiness.md", /^- release: `([^`]+)`$/m, () => ""),
+]);
+
+export const WRITABLE_RELEASE_VERSION_SURFACES = Object.freeze(
+  RELEASE_VERSION_SURFACES.filter((surface) => surface.writable),
+);
 
 export function collectReleaseVersionEvidence({ repoRoot }) {
   repoRoot = resolve(repoRoot);
-  const definitionPath = join(repoRoot, "plugin", "meta", "agdf-plugin.definition.json");
-  const expectedVersion = JSON.parse(readFileSync(definitionPath, "utf8")).version;
-  const entries = VERSION_SURFACES.map(({ relativePath, read }) => {
-    const absolutePath = join(repoRoot, relativePath);
-    if (!existsSync(absolutePath)) return { relativePath, actualVersion: undefined };
-    return { relativePath, actualVersion: read(repoRoot) };
-  });
+  const authoritySurface = RELEASE_VERSION_SURFACES[0];
+  const definitionPath = join(repoRoot, authoritySurface.relativePath);
+  const expectedVersion = authoritySurface.readContent(readFileSync(definitionPath, "utf8"));
+  const entries = RELEASE_VERSION_SURFACES
+    .filter((surface) => surface.evidence)
+    .map((surface) => {
+      const absolutePath = join(repoRoot, surface.relativePath);
+      if (!existsSync(absolutePath)) return { relativePath: surface.relativePath, actualVersion: undefined };
+      return {
+        relativePath: surface.relativePath,
+        actualVersion: surface.readContent(readFileSync(absolutePath, "utf8")),
+      };
+    });
   return { expectedVersion, entries };
 }
 

package/lib/runtime/distribution-profile-history.js

@@ -0,0 +1,173 @@
+import { createHash } from "node:crypto";
+
+const SHA256 = /^[a-f0-9]{64}$/;
+const RELEASE_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const TOP_LEVEL_KEYS = ["contracts", "releases", "schema_version"];
+const CONTRACT_KEYS = ["contract_digest", "distribution_profiles"];
+const RELEASE_KEYS = ["contract_id", "entry_digest", "profile_id", "provenance_schema_version", "status"];
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
+    );
+  }
+  return value;
+}
+
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+function digest(value) {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+
+function exactKeys(value, expected) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && JSON.stringify(Object.keys(value).sort()) === JSON.stringify(expected);
+}
+
+function sortedKeys(value) {
+  const keys = Object.keys(value);
+  return JSON.stringify(keys) === JSON.stringify([...keys].sort());
+}
+
+function invalid(reason) {
+  return { status: "invalid", reason };
+}
+
+export function canonicalDistributionProfileDigest(distributionProfiles) {
+  return digest(distributionProfiles);
+}
+
+export function canonicalDistributionProfileEntryDigest({
+  version,
+  contract_id,
+  contract_digest,
+  provenance_schema_version = 1,
+  profile_id = "runtime-plugin",
+  status = "supported",
+}) {
+  return digest({
+    version,
+    contract_id,
+    contract_digest,
+    provenance_schema_version,
+    profile_id,
+    status,
+  });
+}
+
+export function validateDistributionProfileHistory(catalogue) {
+  if (!exactKeys(catalogue, TOP_LEVEL_KEYS)
+      || catalogue.schema_version !== 1
+      || !catalogue.contracts || typeof catalogue.contracts !== "object" || Array.isArray(catalogue.contracts)
+      || !catalogue.releases || typeof catalogue.releases !== "object" || Array.isArray(catalogue.releases)
+      || !sortedKeys(catalogue.contracts)
+      || !sortedKeys(catalogue.releases)
+      || Object.keys(catalogue.contracts).length === 0
+      || Object.keys(catalogue.releases).length === 0) {
+    return invalid("profile_history_invalid");
+  }
+
+  const contractDigests = new Set();
+  for (const contract of Object.values(catalogue.contracts)) {
+    if (!exactKeys(contract, CONTRACT_KEYS)
+        || !contract.distribution_profiles
+        || typeof contract.distribution_profiles !== "object"
+        || Array.isArray(contract.distribution_profiles)
+        || !SHA256.test(contract.contract_digest ?? "")
+        || canonicalDistributionProfileDigest(contract.distribution_profiles) !== contract.contract_digest) {
+      return invalid("profile_history_invalid");
+    }
+    if (contractDigests.has(contract.contract_digest)) return invalid("profile_history_invalid");
+    contractDigests.add(contract.contract_digest);
+  }
+
+  const referencedContracts = new Set();
+  for (const [version, release] of Object.entries(catalogue.releases)) {
+    const contract = catalogue.contracts[release?.contract_id];
+    if (!RELEASE_VERSION.test(version)
+        || !exactKeys(release, RELEASE_KEYS)
+        || !contract
+        || release.provenance_schema_version !== 1
+        || release.profile_id !== "runtime-plugin"
+        || release.status !== "supported"
+        || !SHA256.test(release.entry_digest ?? "")) {
+      return invalid("profile_history_invalid");
+    }
+    referencedContracts.add(release.contract_id);
+    const expectedDigest = canonicalDistributionProfileEntryDigest({
+      version,
+      contract_id: release.contract_id,
+      contract_digest: contract.contract_digest,
+      provenance_schema_version: release.provenance_schema_version,
+      profile_id: release.profile_id,
+      status: release.status,
+    });
+    if (release.entry_digest !== expectedDigest) return invalid("profile_history_invalid");
+  }
+  if (referencedContracts.size !== Object.keys(catalogue.contracts).length) {
+    return invalid("profile_history_invalid");
+  }
+
+  return { status: "matched", reason: "profile_history_valid" };
+}
+
+export function classifyHistoricalDistributionProfile({ catalogue, version, distributionProfiles }) {
+  const validation = validateDistributionProfileHistory(catalogue);
+  if (validation.status !== "matched") {
+    return {
+      status: "invalid",
+      reason: "profile_history_invalid",
+      release_version: null,
+      contract_id: null,
+      contract_digest: null,
+      entry_digest: null,
+    };
+  }
+  const release = Object.hasOwn(catalogue.releases, version) ? catalogue.releases[version] : null;
+  if (!release) {
+    return {
+      status: "unsupported",
+      reason: "historical_contract_unsupported",
+      release_version: null,
+      contract_id: null,
+      contract_digest: null,
+      entry_digest: null,
+    };
+  }
+  const contract = catalogue.contracts[release.contract_id];
+  if (!distributionProfiles || typeof distributionProfiles !== "object" || Array.isArray(distributionProfiles)) {
+    return {
+      status: "invalid",
+      reason: "historical_contract_invalid",
+      release_version: version,
+      contract_id: release.contract_id,
+      contract_digest: contract.contract_digest,
+      entry_digest: release.entry_digest,
+    };
+  }
+  const observedDigest = canonicalDistributionProfileDigest(distributionProfiles);
+  if (observedDigest !== contract.contract_digest
+      || canonicalJson(distributionProfiles) !== canonicalJson(contract.distribution_profiles)) {
+    return {
+      status: "invalid",
+      reason: "historical_contract_invalid",
+      release_version: version,
+      contract_id: release.contract_id,
+      contract_digest: contract.contract_digest,
+      entry_digest: release.entry_digest,
+    };
+  }
+  return {
+    status: "matched",
+    reason: "historical_contract_matched",
+    release_version: version,
+    contract_id: release.contract_id,
+    contract_digest: contract.contract_digest,
+    entry_digest: release.entry_digest,
+  };
+}

package/lib/runtime/plugin-provenance.js

@@ -137,6 +137,22 @@ export function validateDistributionProfiles(definition) {
   return { status: "matched", contract };
 }
 
+function classifyInstalledHistoricalProfile(catalogue, definition, classifyHistoricalProfile) {
+  if (typeof classifyHistoricalProfile !== "function") {
+    return { status: "invalid", reason: "profile_history_invalid" };
+  }
+  const result = classifyHistoricalProfile({
+    catalogue,
+    version: definition?.version,
+    distributionProfiles: definition?.distributionProfiles,
+  });
+  if (result.status !== "matched") return result;
+  return {
+    ...result,
+    contract: catalogue.contracts[result.contract_id].distribution_profiles,
+  };
+}
+
 export function inspectGeneratedRepositoryMarketplace(targetDir) {
   const marketplacePath = join(targetDir, ".agents", "plugins", "marketplace.json");
   if (!existsSync(marketplacePath)) return { status: "absent", marketplacePath };
@@ -196,11 +212,23 @@ export function inspectInstallationProvenance(pluginRoot, {
   allowLegacy = false,
   profileId = "runtime-plugin",
   inventoryDigest = null,
+  allowHistoricalProfilesForMigration = false,
+  distributionProfileHistory = null,
+  classifyHistoricalProfile = null,
 } = {}) {
   const markerPath = join(pluginRoot, INSTALLATION_PROVENANCE_FILE);
   const legacyPath = join(pluginRoot, LEGACY_LOCAL_INSTALL_FILE);
   if (!existsSync(markerPath)) {
     if (allowLegacy && existsSync(legacyPath)) {
+      const currentProfile = validateDistributionProfiles(definition);
+      if (Object.hasOwn(definition ?? {}, "distributionProfiles")
+          && currentProfile.status !== "matched") {
+        return allowHistoricalProfilesForMigration
+          ? classifyInstalledHistoricalProfile(distributionProfileHistory, definition, classifyHistoricalProfile).status === "matched"
+            ? { status: "invalid", reason: "installation_provenance_invalid" }
+            : classifyInstalledHistoricalProfile(distributionProfileHistory, definition, classifyHistoricalProfile)
+          : currentProfile;
+      }
       const marker = readJson(legacyPath);
       if (!marker
           || marker.schema_version !== 1
@@ -223,8 +251,14 @@ export function inspectInstallationProvenance(pluginRoot, {
     if (profile.status !== "matched") return profile;
     return { status: "missing", reason: "installation_provenance_missing" };
   }
-  const profile = validateDistributionProfiles(definition);
-  if (profile.status !== "matched") return profile;
+  const currentProfile = validateDistributionProfiles(definition);
+  const historicalProfile = currentProfile.status !== "matched" && allowHistoricalProfilesForMigration
+    ? classifyInstalledHistoricalProfile(distributionProfileHistory, definition, classifyHistoricalProfile)
+    : null;
+  if (currentProfile.status !== "matched" && historicalProfile?.status !== "matched") {
+    return historicalProfile ?? currentProfile;
+  }
+  const profile = currentProfile.status === "matched" ? currentProfile : historicalProfile;
   const marker = readJson(markerPath);
   if (!marker
       || marker.schema_version !== 1
@@ -247,7 +281,16 @@ export function inspectInstallationProvenance(pluginRoot, {
   if (observedSourceDigest !== marker.source_digest) {
     return { status: "invalid", reason: "source_digest_mismatch", marker, observedSourceDigest };
   }
-  return { status: "matched", marker, observedSourceDigest };
+  return {
+    status: "matched",
+    marker,
+    observedSourceDigest,
+    profileClassification: historicalProfile ? "supported_historical" : "current",
+    historicalReleaseVersion: historicalProfile?.release_version ?? null,
+    historicalContractId: historicalProfile?.contract_id ?? null,
+    historicalContractDigest: historicalProfile?.contract_digest ?? null,
+    historicalEntryDigest: historicalProfile?.entry_digest ?? null,
+  };
 }
 
 export const distributionProfileContract = Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "description": "Install AGDF plugins, bootstrap supported repository surfaces and validate durable governance state.",
   "type": "module",
   "files": [
@@ -27,8 +27,11 @@
     "install:copilot": "node ./scripts/install-local-plugin.js copilot",
     "install:opencode": "node ./scripts/install-local-plugin.js opencode",
     "test:release-version-coherence": "node ./scripts/release-version-coherence-test.js",
+    "release:bump": "node ./scripts/release-bump.js",
+    "test:release-bump": "node ./scripts/release-bump-test.js",
+    "test:distribution-profile-history": "node ./scripts/distribution-profile-history-test.js",
     "test:public-plugin": "node ./scripts/public-plugin-test.js",
-    "release:prepare": "npm run sync-package-assets && npm run test:release-version-coherence && npm run test:public-plugin",
+    "release:prepare": "npm run sync-package-assets && npm run test:distribution-profile-history && npm run test:release-bump && npm run test:release-version-coherence && npm run test:public-plugin",
     "test:delivery-path-search": "node ./scripts/delivery-path-search-test.js",
     "test:delivery-path-search-unit": "node ./scripts/delivery-path-search-unit-test.js",
     "test:delivery-path-search-generator": "node ./scripts/delivery-path-search-generator-test.js",
@@ -37,6 +40,7 @@
     "test:cli-modularization": "node ./scripts/cli-modularization-test.js",
     "test:local-validator": "node ./scripts/local-validator-test.js",
     "test:local-marketplace": "node ./scripts/local-marketplace-test.js",
+    "test:claude-cache-recovery": "node ./scripts/claude-cache-recovery-test.js",
     "test:copilot-profile": "node ./scripts/copilot-profile-test.js",
     "test:local-development-install": "npm run release:prepare && node ./scripts/local-development-install-test.js",
     "test:package-contents": "node ./scripts/package-contents-test.js",
@@ -58,7 +62,7 @@
     "test:proportionality": "node ./scripts/proportionality-benchmark-test.js",
     "test:release-bootstrap": "node ./scripts/release-bootstrap-smoke-test.js",
     "test:routing": "npm run sync-package-assets && node ./scripts/test-routing.js",
-    "smoke-test": "npm run release:prepare && npm run test:cli-modularization && npm run test:local-validator && npm run test:local-marketplace && npm run test:copilot-profile && npm run test:local-development-install && npm run test:package-build && npm run test:package-contents && npm run test:lifecycle && npm run test:copilot-repository-retention && npm run test:control-state && npm run test:parent-reconciliation && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:agent-skills-conformance && npm run test:skill-evals && npm run eval:skills && npm run test:proportionality && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && npm run test:opencode-hardening && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
+    "smoke-test": "npm run release:prepare && npm run test:cli-modularization && npm run test:local-validator && npm run test:local-marketplace && npm run test:claude-cache-recovery && npm run test:copilot-profile && npm run test:local-development-install && npm run test:package-build && npm run test:package-contents && npm run test:lifecycle && npm run test:copilot-repository-retention && npm run test:control-state && npm run test:parent-reconciliation && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:agent-skills-conformance && npm run test:skill-evals && npm run eval:skills && npm run test:proportionality && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && npm run test:opencode-hardening && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
     "prepack": "npm run release:prepare"
   },
   "keywords": [