create-yss-spec 3.4.5 → 3.4.7

package/template/scripts/lib/backend-platform.mjs

@@ -9,13 +9,161 @@ export const PLATFORM_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta
 export const PLATFORM_CATALOG_REF = "docs/engineering/backend-platforms.json";
 export const PLATFORM_SKILLS = ["yss-ddd-scaffold-generator", "yss-layered-mvc-scaffold-generator"];
 const fail = (message) => { throw new TypeError(`backend-platform: ${message}`); };
+const componentFail = (code, message) => {
+  const error = new TypeError(`component-capability: ${code}: ${message}`);
+  error.code = code;
+  throw error;
+};
 const stable = (value) => Array.isArray(value) ? value.map(stable) : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])])) : value;
 export const platformDigest = value => `sha256:${createHash("sha256").update(typeof value === "string" || Buffer.isBuffer(value) ? value : JSON.stringify(stable(value ?? null))).digest("hex")}`;
+const exactVersion = value => typeof value === "string" && value.length > 0 && !/[\[\](),*+]|\bx\b|latest/i.test(value);
+const portableEvidence = item => item && typeof item.ref === "string" && item.ref.length > 0 && !path.isAbsolute(item.ref) && !item.ref.split(/[\\/]/).includes("..") && /^sha256:[a-f0-9]{64}$/.test(item.digest ?? "");
+const sha256 = value => /^sha256:[a-f0-9]{64}$/.test(value ?? "");
+const gitTree = value => /^[a-f0-9]{40}$/.test(value ?? "");
+const major = value => Number.parseInt(String(value ?? "").match(/^(\d+)/)?.[1] ?? "", 10);
+const platformGeneration = profile => major(profile?.spring_boot_version) === 2 ? { line: "boot2-java8", componentMajor: 2 } : major(profile?.spring_boot_version) === 3 ? { line: "boot3-java17", componentMajor: 3 } : { line: "boot4", componentMajor: null };
+const COMPONENT_PLATFORM_LINES = new Set(["boot2-java8", "boot3-java17"]);
+const normalizedComponentPlatformLine = profile => COMPONENT_PLATFORM_LINES.has(profile?.component_platform_line) ? profile.component_platform_line : undefined;
+const retirementEvidenceComplete = value => {
+  const required = new Set(["organization-code-search", "maven-download-metrics", "runtime-bean-and-configuration-scan", "30-90-day-zero-usage-window"]);
+  if (!Array.isArray(value) || !value.every(item => item?.status === "zero" && typeof item.ref === "string" && item.ref.length > 0)) return false;
+  for (const item of value) required.delete(item.kind);
+  return required.size === 0;
+};
+const candidateArtifactFieldsEmpty = binding =>
+  ["resolved_version", "published_at", "pom_sha256", "jar_sha256", "sources_jar_sha256", "source_tree"].every(field => binding[field] === null) &&
+  Array.isArray(binding.evidence) && binding.evidence.length === 0 &&
+  Array.isArray(binding.blockers) && binding.blockers.length > 0;
+function validateArtifactBinding(binding, label, { role, expected, snapshot, allowedStatuses = ["candidate"] }) {
+  if (!binding || typeof binding !== "object" || typeof role !== "string" || !role.length || binding.role !== role || !allowedStatuses.includes(binding.status)) componentFail("component-binding-drift", `invalid artifact binding: ${label}`);
+  if (!binding.group_id || !binding.artifact_id || !exactVersion(binding.declared_version)) componentFail("component-artifact-coordinate-conflict", `invalid candidate artifact coordinate: ${label}`);
+  if (expected && (binding.group_id !== expected.group_id || binding.artifact_id !== expected.artifact_id || binding.declared_version !== expected.version)) componentFail("component-binding-drift", `candidate artifact differs from compatibility coordinates: ${label}`);
+  if (snapshot !== binding.declared_version.endsWith("-SNAPSHOT")) componentFail("component-artifact-coordinate-conflict", `candidate artifact release kind mismatch: ${label}`);
+  if (binding.status === "candidate" && !candidateArtifactFieldsEmpty(binding)) componentFail("component-evidence-missing", `candidate artifact must remain unresolved until evidence is published: ${label}`);
+  if (binding.status === "resolved") {
+    if (snapshot || binding.resolved_version !== binding.declared_version || !sha256(binding.pom_sha256) || !sha256(binding.jar_sha256) || !sha256(binding.sources_jar_sha256)) componentFail("component-evidence-missing", `resolved external release lacks immutable version or POM/JAR/sources digest: ${label}`);
+    if (binding.published_at !== null && (typeof binding.published_at !== "string" || !binding.published_at.length)) componentFail("component-binding-drift", `invalid external release timestamp: ${label}`);
+    if (binding.source_tree !== null && !gitTree(binding.source_tree)) componentFail("component-binding-drift", `invalid external release source tree: ${label}`);
+    if (!Array.isArray(binding.evidence) || !Array.isArray(binding.blockers)) componentFail("component-evidence-missing", `resolved external release evidence fields are invalid: ${label}`);
+  }
+}
+export function componentCapabilityDigest(value, capabilityId = value?.capability_id) {
+  const { capability_id, component_digest, status, evidence, blockers, ...recipe } = value ?? {};
+  return platformDigest({ capability_id: capabilityId, ...recipe });
+}
+function validateBoot3Java17Policy(entry, profile) {
+  if (profile.component_platform_line !== "boot3-java17") return;
+  if (profile.spring_cloud_version !== "2025.0.3" || profile.spring_cloud_alibaba_version !== "2025.0.0.0" || profile.validation_namespace !== "jakarta" || profile.jackson_major !== 2 || profile.auto_configuration_imports_path !== "META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports") componentFail("component-binding-drift", `Boot 3.5/JDK17 platform constraints changed: ${profile.id}`);
+  if (!entry.platform_artifact_bindings || !Array.isArray(entry.external_snapshot_bindings) || !Array.isArray(entry.external_artifact_bindings)) componentFail("component-binding-drift", `Boot 3.5/JDK17 artifact binding structures are missing: ${entry.id}`);
+  if (entry.external_snapshot_bindings.length) componentFail("component-artifact-coordinate-conflict", `Boot 3.5/JDK17 does not allow unresolved external SNAPSHOT bindings: ${entry.id}`);
+  const components = entry.component_capabilities ?? {};
+  const exactComponent = (capabilityId, expected) => {
+    const artifacts = components[capabilityId]?.artifacts;
+    if (!Array.isArray(artifacts) || artifacts.length !== expected.length || artifacts.some((artifact, index) => `${artifact.group_id}:${artifact.artifact_id}:${artifact.declared_version}` !== expected[index])) componentFail("component-binding-drift", `Boot 3.5/JDK17 component coordinates changed: ${entry.id}:${capabilityId}`);
+  };
+  exactComponent("contract.request-validation", [`org.springframework.boot:spring-boot-starter-validation:${profile.spring_boot_version}`]);
+  exactComponent("component.cache", ["com.yss.cloud:yss-component-cache-starter:3.1.0-SNAPSHOT"]);
+  exactComponent("component.distributed-id", ["com.yss.cloud:yss-component-distributed-id:3.1.0-SNAPSHOT"]);
+  if (Object.values(components).some(item => item.artifacts?.some(artifact => artifact.artifact_id === "yss-component-excel-starter"))) componentFail("component-new-adoption-forbidden", `removed yss-component-excel-starter is present: ${entry.id}`);
+  exactComponent("component.excel-import-export", ["com.yss.cloud:yss-component-excel-mvc:3.0.0-SNAPSHOT"]);
+  for (const [capabilityId, item] of Object.entries(components)) {
+    if (item.status !== "blocked" || item.verified_architectures.length || item.evidence.length || item.artifacts.some(artifact => ["resolved_version", "pom_sha256", "jar_sha256", "source_tree"].some(field => artifact[field] !== null))) componentFail("component-evidence-missing", `Boot 3.5/JDK17 unpublished component must remain blocked and unresolved: ${entry.id}:${capabilityId}`);
+  }
+  const external = entry.external_artifact_bindings;
+  if (external.length !== 1 || `${external[0].group_id}:${external[0].artifact_id}:${external[0].declared_version}` !== "org.apache.fesod:fesod-sheet:2.0.2-incubating" || external[0].status !== "resolved") componentFail("component-binding-drift", `Boot 3.5/JDK17 Fesod release binding changed: ${entry.id}`);
+}
+function validateComponentCatalog(value, root = PLATFORM_ROOT) {
+  if (Object.hasOwn(value, "component_capabilities") || Object.hasOwn(value, "component_capability_ids")) componentFail("component-binding-drift", "component capabilities must be nested in their compatibility entry");
+  for (const entry of value.compatibility) {
+    const profile = value.profiles.find(item => item.id === entry.profile_id && item.spring_boot_version === entry.spring_boot_version);
+    if (!profile) componentFail("component-unavailable-for-platform", `compatibility profile is missing: ${entry.id}`);
+    const generation = platformGeneration(profile);
+    if (!COMPONENT_PLATFORM_LINES.has(generation.line) || profile.component_platform_line !== generation.line) componentFail("component-platform-generation-mismatch", `profile component line does not match ${generation.line}: ${profile.id}`);
+    if (entry.platform_artifact_bindings !== undefined) {
+      if (!entry.platform_artifact_bindings || Array.isArray(entry.platform_artifact_bindings) || Object.keys(entry.platform_artifact_bindings).sort().join(",") !== "bom,parent") componentFail("component-binding-drift", `platform artifact bindings must contain parent and bom: ${entry.id}`);
+      validateArtifactBinding(entry.platform_artifact_bindings.parent, `${entry.id}:parent`, { role: "parent", expected: entry.parent, snapshot: true });
+      validateArtifactBinding(entry.platform_artifact_bindings.bom, `${entry.id}:bom`, { role: "bom", expected: entry.bom, snapshot: true });
+    }
+    for (const [field, snapshot] of [["external_snapshot_bindings", true], ["external_artifact_bindings", false]]) {
+      const bindings = entry[field];
+      if (bindings === undefined) continue;
+      if (!Array.isArray(bindings)) componentFail("component-binding-drift", `${field} must be an array: ${entry.id}`);
+      const coordinates = new Set();
+      for (const binding of bindings) {
+        validateArtifactBinding(binding, `${entry.id}:${field}:${binding?.group_id ?? "?"}:${binding?.artifact_id ?? "?"}`, { role: binding?.role, snapshot, allowedStatuses: field === "external_artifact_bindings" ? ["candidate", "resolved"] : ["candidate"] });
+        const coordinate = `${binding.group_id}:${binding.artifact_id}`;
+        if (coordinates.has(coordinate)) componentFail("component-artifact-coordinate-conflict", `duplicate ${field} coordinate: ${entry.id}:${coordinate}`);
+        coordinates.add(coordinate);
+      }
+    }
+    let artifactResolution = null;
+    if (entry.artifact_resolution_evidence !== undefined) {
+      const binding = entry.artifact_resolution_evidence;
+      if (!portableEvidence(binding) || typeof binding.report_id !== "string" || typeof binding.repository_id !== "string") componentFail("component-evidence-missing", `invalid artifact resolution evidence: ${entry.id}`);
+      let bytes;
+      try { bytes = readFileSync(path.join(root, binding.ref)); }
+      catch { componentFail("component-evidence-missing", `artifact resolution evidence is unreadable: ${entry.id}`); }
+      if (platformDigest(bytes) !== binding.digest) componentFail("component-binding-drift", `artifact resolution evidence drift: ${entry.id}`);
+      try { artifactResolution = JSON.parse(bytes); }
+      catch { componentFail("component-binding-drift", `artifact resolution evidence is not valid JSON: ${entry.id}`); }
+      if (artifactResolution.schema_version !== 1 || artifactResolution.kind !== "backend-component-artifact-resolution" || artifactResolution.report_id !== binding.report_id || artifactResolution.repository?.id !== binding.repository_id || !Array.isArray(artifactResolution.artifacts)) componentFail("component-binding-drift", `artifact resolution evidence identity mismatch: ${entry.id}`);
+      artifactResolution = new Map(artifactResolution.artifacts.map(item => [`${item.group_id}:${item.artifact_id}:${item.declared_version}`, item]));
+    }
+    if (entry.component_capabilities === undefined) continue;
+    if (!entry.component_capabilities || Array.isArray(entry.component_capabilities) || typeof entry.component_capabilities !== "object") componentFail("component-evidence-missing", `component capability map is invalid: ${entry.id}`);
+    for (const [capabilityId, item] of Object.entries(entry.component_capabilities)) {
+      const key = `${entry.id}:${capabilityId}`;
+      if (!capabilityId.includes(".") || !item || typeof item !== "object") componentFail("component-binding-drift", `invalid component capability binding: ${key}`);
+      if (!["candidate", "verified", "blocked"].includes(item.status) || !Array.isArray(item.verified_architectures) || !Array.isArray(item.artifacts) || !Array.isArray(item.evidence) || !Array.isArray(item.blockers)) componentFail("component-evidence-missing", `incomplete capability entry: ${key}`);
+      if (item.provider_kind !== undefined && !["yss-component", "platform-managed"].includes(item.provider_kind)) componentFail("component-binding-drift", `invalid component provider kind: ${key}`);
+      if (item.provider_kind === "platform-managed") {
+        if (capabilityId !== "contract.request-validation" || item.artifacts.length !== 1) componentFail("component-binding-drift", `unsupported platform-managed capability: ${key}`);
+        const artifact = item.artifacts[0];
+        if (artifact.group_id !== "org.springframework.boot" || artifact.artifact_id !== "spring-boot-starter-validation" || artifact.declared_version !== profile.spring_boot_version) componentFail("component-binding-drift", `platform-managed validation must match Spring Boot ${profile.spring_boot_version}: ${key}`);
+      }
+      if (!["active", "maintenance", "deprecated", "retired"].includes(item.lifecycle ?? "active") || !["allowed", "forbidden"].includes(item.adoption_policy ?? "allowed")) componentFail("component-binding-drift", `invalid component lifecycle/adoption policy: ${key}`);
+      if (item.lifecycle === "retired" && !retirementEvidenceComplete(item.retirement_evidence)) componentFail("component-retirement-evidence-missing", `organizational zero-consumption evidence is incomplete: ${key}`);
+      if (new Set(item.verified_architectures).size !== item.verified_architectures.length || item.verified_architectures.some(family => !["domain-driven", "layered-mvc"].includes(family))) componentFail("component-binding-drift", `invalid verified architectures: ${key}`);
+      const coordinates = new Set();
+      for (const artifact of item.artifacts) {
+        const coordinate = `${artifact.group_id}:${artifact.artifact_id}`;
+        if (!artifact.group_id || !artifact.artifact_id || !exactVersion(artifact.declared_version) || coordinates.has(coordinate)) componentFail("component-artifact-coordinate-conflict", `invalid or duplicate artifact coordinate in ${key}: ${coordinate}`);
+        if (artifact.resolved_version !== null && artifact.resolved_version !== undefined && !exactVersion(artifact.resolved_version)) componentFail("component-artifact-coordinate-conflict", `invalid resolved version in ${key}: ${coordinate}`);
+        if (artifact.declared_version.endsWith("-SNAPSHOT") && artifact.resolved_version && (artifact.resolved_version === artifact.declared_version || artifact.resolved_version.endsWith("-SNAPSHOT"))) componentFail("component-artifact-coordinate-conflict", `SNAPSHOT is not uniquely resolved in ${key}: ${coordinate}`);
+        if (artifactResolution) {
+          const resolved = artifactResolution.get(`${coordinate}:${artifact.declared_version}`);
+          if (!resolved) componentFail("component-evidence-missing", `artifact is absent from resolution evidence: ${key}:${coordinate}`);
+          const expectedPom = resolved.pom_sha256 ? `sha256:${resolved.pom_sha256}` : null;
+          const expectedJar = resolved.jar_sha256 ? `sha256:${resolved.jar_sha256}` : null;
+          const expectedTree = resolved.sources_match_source_tree === true && resolved.pom_matches_source_tree === true ? resolved.source_tree : null;
+          if (artifact.resolved_version !== resolved.resolved_version || artifact.pom_sha256 !== expectedPom || artifact.jar_sha256 !== expectedJar || artifact.source_tree !== expectedTree) componentFail("component-binding-drift", `artifact binding differs from resolution evidence: ${key}:${coordinate}`);
+        }
+        coordinates.add(coordinate);
+      }
+      if (!sha256(item.component_digest) || item.component_digest !== componentCapabilityDigest(item, capabilityId)) componentFail("component-binding-drift", `component digest mismatch: ${key}`);
+      if (item.status === "verified") {
+        if (!item.verified_architectures.length || !item.artifacts.length || !item.evidence.length || item.blockers.length) componentFail("component-evidence-missing", `verified capability is incomplete: ${key}`);
+        if (entry.status !== "verified") componentFail("component-unavailable-for-platform", `verified capability belongs to an unverified compatibility entry: ${key}`);
+        if (item.artifacts.some(artifact => !exactVersion(artifact.resolved_version) || !sha256(artifact.pom_sha256) || !sha256(artifact.jar_sha256) || !gitTree(artifact.source_tree))) componentFail("component-evidence-missing", `verified artifact evidence is missing: ${key}`);
+        const generation = platformGeneration(value.profiles.find(profile => profile.id === entry.profile_id));
+        if (generation.componentMajor !== null && item.artifacts.some(artifact => major(artifact.declared_version) !== generation.componentMajor)) componentFail("component-platform-generation-mismatch", `${key} does not match ${generation.line}`);
+        if (item.evidence.some(evidence => !portableEvidence(evidence) || !item.verified_architectures.includes(evidence.architecture_family))) componentFail("component-evidence-missing", `verified capability evidence is invalid: ${key}`);
+      } else if (!item.blockers.length) componentFail("component-evidence-missing", `unverified capability lacks blockers: ${key}`);
+    }
+    validateBoot3Java17Policy(entry, profile);
+  }
+}
 export function loadBackendPlatforms(root = PLATFORM_ROOT) {
   const value = JSON.parse(readFileSync(path.join(root, PLATFORM_CATALOG_REF), "utf8"));
-  if (value.schema_version !== 1 || value.kind !== "backend-platform-catalog" || !Array.isArray(value.profiles) || !Array.isArray(value.compatibility)) fail("invalid catalog");
+  if (value.schema_version !== 2 || value.kind !== "backend-platform-catalog" || !Array.isArray(value.profiles) || !Array.isArray(value.compatibility)) fail("invalid catalog");
   if (new Set(value.profiles.map(item => `${item.id}:${item.spring_boot_version}:${item.java_version}`)).size !== value.profiles.length || new Set(value.compatibility.map(item => item.id)).size !== value.compatibility.length) fail("duplicate catalog release/id");
-  for (const profile of value.profiles) if (!/^\d+\.\d+\.\d+$/.test(profile.spring_boot_version)) fail("catalog requires exact patch versions");
+  for (const profile of value.profiles) {
+    if (!/^\d+\.\d+\.\d+$/.test(profile.spring_boot_version)) fail("catalog requires exact patch versions");
+    const generation = platformGeneration(profile);
+    if (COMPONENT_PLATFORM_LINES.has(generation.line) && profile.component_platform_line !== generation.line) componentFail("component-platform-generation-mismatch", `profile component line does not match ${generation.line}: ${profile.id}`);
+    if (!COMPONENT_PLATFORM_LINES.has(generation.line) && profile.component_platform_line !== undefined) componentFail("component-platform-generation-mismatch", `unsupported component platform line for ${profile.id}: ${profile.component_platform_line}`);
+  }
+  validateComponentCatalog(value, root);
   return value;
 }
 export function platformProfile(id, catalog = loadBackendPlatforms(), version) {
@@ -27,15 +175,20 @@ export function platformProfile(id, catalog = loadBackendPlatforms(), version) {
 }
 export function platformRecipeDigest(profile, entry) {
   const { candidate_blockers, recommended, ...recipe } = profile;
-  return platformDigest({ profile: recipe, entry: { id: entry.id, profile_id: entry.profile_id, spring_boot_version: entry.spring_boot_version, parent: entry.parent, bom: entry.bom, components: entry.components ?? {} } });
+  return platformDigest({ profile: recipe, entry: { id: entry.id, profile_id: entry.profile_id, spring_boot_version: entry.spring_boot_version, parent: entry.parent, bom: entry.bom, components: entry.components ?? {}, platform_artifact_bindings: entry.platform_artifact_bindings ?? {}, external_snapshot_bindings: entry.external_snapshot_bindings ?? [], external_artifact_bindings: entry.external_artifact_bindings ?? [] } });
 }
 export function platformBinding(profile, entry) {
-  return { schema_version: 2, profile_id: profile.id, spring_boot_version: profile.spring_boot_version, java_version: profile.java_version, parent: entry.parent, bom: entry.bom, compatibility_id: entry.id, compatibility_digest: platformRecipeDigest(profile, entry) };
+  const componentPlatformLine = normalizedComponentPlatformLine(profile);
+  return { schema_version: 2, profile_id: profile.id, spring_boot_version: profile.spring_boot_version, java_version: profile.java_version, ...(componentPlatformLine ? { component_platform_line: componentPlatformLine } : {}), parent: entry.parent, bom: entry.bom, compatibility_id: entry.id, compatibility_digest: platformRecipeDigest(profile, entry) };
 }
-export function resolveBackendPlatform(binding, { catalog = loadBackendPlatforms(), requireVerified = true, root = PLATFORM_ROOT } = {}) {
+export function resolveBackendPlatform(binding, options = {}) {
+  const root = options.root ?? PLATFORM_ROOT;
+  const catalog = options.catalog ?? loadBackendPlatforms(root);
+  const requireVerified = options.requireVerified ?? true;
   if (!binding || binding.schema_version !== 2) fail("missing platform_configuration v2 (v1 is historical read-only); 生命周期须展示 Boot/Java/YSS 组合并取得用户确认");
   const profile = platformProfile(binding.profile_id, catalog, binding.spring_boot_version);
   if (binding.spring_boot_version !== profile.spring_boot_version || binding.java_version !== profile.java_version) fail("unsupported exact Boot/Java combination (x/latest and Java 8/11 for Boot 3.5/4.1 are rejected)");
+  if (binding.component_platform_line !== normalizedComponentPlatformLine(profile)) fail("component_platform_line does not match the selected platform profile");
   const entry = catalog.compatibility.find(item => item.id === binding.compatibility_id);
   const evidenceReports = [];
   if (!entry || entry.profile_id !== profile.id || entry.spring_boot_version !== profile.spring_boot_version) fail("YSS compatibility entry missing; parent/BOM/starter verification required");
@@ -66,6 +219,80 @@ export function resolveBackendPlatform(binding, { catalog = loadBackendPlatforms
   }
   return { profile, entry, evidenceReports };
 }
+export function resolveComponentCapabilities(binding, capabilityIds, architectureFamily, options = {}) {
+  const root = options.root ?? PLATFORM_ROOT;
+  const catalog = options.catalog ?? loadBackendPlatforms(root);
+  let resolvedPlatform;
+  try { resolvedPlatform = resolveBackendPlatform(binding, { catalog, root, requireVerified: false }); }
+  catch (error) {
+    const code = /drift|stale/i.test(error.message ?? "") ? "component-binding-drift" : "component-unavailable-for-platform";
+    componentFail(code, error.message);
+  }
+  if (!Array.isArray(capabilityIds) || !capabilityIds.length || capabilityIds.some(id => typeof id !== "string" || !id.length) || new Set(capabilityIds).size !== capabilityIds.length) componentFail("component-unavailable-for-platform", "capability ids must be a non-empty unique list");
+  if (!["domain-driven", "layered-mvc"].includes(architectureFamily)) componentFail("component-unavailable-for-platform", `unsupported architecture family: ${architectureFamily}`);
+  const records = capabilityIds.map(capabilityId => {
+    const item = resolvedPlatform.entry.component_capabilities?.[capabilityId];
+    if (!item) componentFail("component-unavailable-for-platform", `${capabilityId} is not declared for ${resolvedPlatform.entry.id}`);
+    if (item.lifecycle === "retired" && !retirementEvidenceComplete(item.retirement_evidence)) componentFail("component-retirement-evidence-missing", `${capabilityId} lacks organizational zero-consumption evidence`);
+    if ((item.adoption_policy ?? "allowed") === "forbidden" && !(options.allowForbiddenExisting ?? false)) componentFail("component-new-adoption-forbidden", `${capabilityId} is ${item.lifecycle ?? "deprecated"}; use ${item.replacement_binding_id ?? item.replacement_gav ?? "the approved migration route"}`);
+    const generation = platformGeneration(resolvedPlatform.profile);
+    if (generation.componentMajor !== null && item.artifacts.some(artifact => major(artifact.declared_version) !== generation.componentMajor)) componentFail("component-platform-generation-mismatch", `${capabilityId} requires component ${generation.componentMajor}.x for ${generation.line}`);
+    if (item.status !== "verified") {
+      const blockers = (item.blockers ?? []).join("; ");
+      const code = item.blockers?.some(blocker => blocker.startsWith("component-platform-generation-mismatch:"))
+        ? "component-platform-generation-mismatch"
+        : item.blockers?.some(blocker => blocker.startsWith("component-new-adoption-forbidden:"))
+          ? "component-new-adoption-forbidden"
+          : item.blockers?.some(blocker => blocker.startsWith("component-retirement-evidence-missing:"))
+            ? "component-retirement-evidence-missing"
+            : item.blockers?.some(blocker => blocker.startsWith("component-artifact-coordinate-conflict:"))
+              ? "component-artifact-coordinate-conflict"
+              : item.blockers?.some(blocker => blocker.startsWith("component-binding-drift:"))
+                ? "component-binding-drift"
+                : item.blockers?.some(blocker => blocker.startsWith("component-evidence-missing:"))
+                  ? "component-evidence-missing"
+                  : "component-unavailable-for-platform";
+      componentFail(code, `${capabilityId} is ${item.status}; ${blockers}`);
+    }
+    if (!item.verified_architectures.includes(architectureFamily)) componentFail("component-unavailable-for-platform", `${capabilityId} is not verified for ${architectureFamily}`);
+    if (!item.artifacts.length || item.artifacts.some(artifact => !artifact.group_id || !artifact.artifact_id || !exactVersion(artifact.declared_version) || !exactVersion(artifact.resolved_version) || !sha256(artifact.pom_sha256) || !sha256(artifact.jar_sha256) || !gitTree(artifact.source_tree))) componentFail("component-evidence-missing", `${capabilityId} lacks exact artifact evidence`);
+    const artifactCoordinates = item.artifacts.map(artifact => `${artifact.group_id}:${artifact.artifact_id}`);
+    if (new Set(artifactCoordinates).size !== artifactCoordinates.length || item.artifacts.some(artifact => artifact.declared_version.endsWith("-SNAPSHOT") && (artifact.resolved_version === artifact.declared_version || artifact.resolved_version.endsWith("-SNAPSHOT")))) componentFail("component-artifact-coordinate-conflict", `${capabilityId} has duplicate coordinates or an unresolved SNAPSHOT`);
+    if (item.component_digest !== componentCapabilityDigest(item, capabilityId)) componentFail("component-binding-drift", `${capabilityId} component digest changed`);
+    return { capabilityId, item };
+  });
+  if (options.requirePlatformVerified ?? true) {
+    try { resolveBackendPlatform(binding, { catalog, root, requireVerified: true }); }
+    catch (error) {
+      const code = /drift|stale/i.test(error.message ?? "") ? "component-binding-drift" : "component-unavailable-for-platform";
+      componentFail(code, error.message);
+    }
+  }
+  const coordinates = new Map();
+  for (const { capabilityId, item } of records) for (const artifact of item.artifacts) {
+    const coordinate = `${artifact.group_id}:${artifact.artifact_id}`;
+    const previous = coordinates.get(coordinate);
+    const version = `${artifact.declared_version}->${artifact.resolved_version}`;
+    if (previous && previous.version !== version) componentFail("component-artifact-coordinate-conflict", `${coordinate} resolves to both ${previous.version} (${previous.capabilityId}) and ${version} (${capabilityId})`);
+    coordinates.set(coordinate, { version, capabilityId });
+  }
+  return records.map(({ capabilityId, item }) => {
+    const evidence = item.evidence.filter(record => record.architecture_family === architectureFamily);
+    if (!evidence.length) componentFail("component-evidence-missing", `${capabilityId} lacks ${architectureFamily} evidence`);
+    for (const record of evidence) {
+      if (!portableEvidence(record)) componentFail("component-evidence-missing", `${capabilityId} has invalid portable evidence`);
+      let bytes;
+      try { bytes = readFileSync(path.join(root, record.ref)); }
+      catch { componentFail("component-evidence-missing", `${capabilityId} evidence is unreadable: ${record.ref}`); }
+      if (platformDigest(bytes) !== record.digest) componentFail("component-binding-drift", `${capabilityId} evidence bytes changed`);
+      let report;
+      try { report = JSON.parse(bytes); }
+      catch { componentFail("component-binding-drift", `${capabilityId} evidence is not valid JSON`); }
+      if (report.schema_version !== 1 || report.kind !== "backend-component-capability-evidence" || report.status !== "passed" || report.capability_id !== capabilityId || report.compatibility_id !== resolvedPlatform.entry.id || report.profile_id !== resolvedPlatform.profile.id || report.spring_boot_version !== resolvedPlatform.profile.spring_boot_version || report.architecture_family !== architectureFamily || report.component_digest !== item.component_digest || platformDigest(report.artifacts) !== platformDigest(item.artifacts)) componentFail("component-binding-drift", `${capabilityId} evidence identity mismatch`);
+    }
+    return { capability_id: capabilityId, status: item.status, verified_architectures: [...item.verified_architectures], artifacts: item.artifacts.map(artifact => ({ ...artifact })), evidence: evidence.map(record => ({ ...record })), component_digest: item.component_digest };
+  });
+}
 export function assertContractPlatform(contract, decision, options = {}) {
   const binding = contract.platform_configuration;
   const resolved = resolveBackendPlatform(binding, options);

package/template/scripts/lib/existing-backend-architecture.mjs

@@ -17,10 +17,11 @@ function file(root,ref){relative(ref);let current=realpathSync(root);for(const p
 function parse(bytes){const doc=parseDocument(String(bytes),{uniqueKeys:true,maxAliasCount:0});requireThat(!doc.errors.length,'ARCH_EVIDENCE_FORMAT',doc.errors[0]?.message);return doc.toJS({maxAliasCount:0});}
 function bound(root,binding){requireThat(binding&&text(binding.ref)&&digest(binding.digest),'ARCH_EVIDENCE_REF','缺少原始证据 ref/digest');const bytes=readFileSync(file(root,binding.ref));requireThat(sha(bytes)===binding.digest,'ARCH_EVIDENCE_STALE',`原始证据已改变: ${binding.ref}`);return parse(bytes);}
 function same(a,b,code,label){requireThat(existingArchitectureDigest(a)===existingArchitectureDigest(b),code,label);}
-const FIELDS=['schema_version','source_kind','architecture_family','architecture_profile','repository_id','project_id','source_digest','build_units_digest'];
+const REQUIRED_FIELDS=['schema_version','source_kind','architecture_family','architecture_profile','repository_id','project_id','source_digest','build_units_digest'];
+const FIELDS=[...REQUIRED_FIELDS,'platform_configuration'];
 export function validateExistingArchitecture(identity,registry){
  requireThat(identity?.schema_version===2&&identity.source_kind==='existing-registration','ARCH_SOURCE_UNSUPPORTED','仅支持 existing-registration v2');
- requireThat(FIELDS.every(k=>identity[k]!==undefined)&&Object.keys(identity).every(k=>FIELDS.includes(k)),'ARCH_IDENTITY_SHAPE','既有身份字段缺失或混入生成事实');
+ requireThat(REQUIRED_FIELDS.every(k=>identity[k]!==undefined)&&Object.keys(identity).every(k=>FIELDS.includes(k)),'ARCH_IDENTITY_SHAPE','既有身份字段缺失或混入生成事实');
  const p=registry.existing_project_profiles?.[identity.architecture_profile];
  requireThat(p&&p.source_kind==='existing-registration'&&p.build_system==='maven'&&p.architecture_family===identity.architecture_family,'ARCH_PROFILE_UNSUPPORTED','未支持的既有工程架构/Profile');
  requireThat(['domain-driven','layered-mvc'].includes(identity.architecture_family)&&text(identity.repository_id)&&text(identity.project_id)&&digest(identity.source_digest)&&digest(identity.build_units_digest),'ARCH_IDENTITY_SHAPE','既有身份未绑定项目或源码/构建摘要');

package/template/scripts/lib/implementation-contract-compiler.mjs

@@ -1,4 +1,4 @@
-import { resolveBackendPlatform } from "./backend-platform.mjs";
+import { resolveBackendPlatform, resolveComponentCapabilities } from "./backend-platform.mjs";
 import { safe } from './strategic-handoff-io.mjs';
 import { selectSliceWorkUnit, normalizeSliceContract, withinSlicePath } from './slice-contract.mjs';
 import { createApprovedExecutionContext, createApprovedRecompilationContext, assertApprovedExecutionContext } from './approved-execution-context.mjs';
@@ -8,7 +8,7 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
-import { DEFAULT_REGISTRY, loadSkillRegistry } from "./skill-registry.mjs";
+import { DEFAULT_REGISTRY, loadSkillRegistry, resolveSkillForNewUse } from "./skill-registry.mjs";
 import { ROOT } from "./skill-supply-chain.mjs";
 import { architectureDigest, assertArchitectureAgreement, validateArchitectureIdentity, verifyArchitectureEvidence } from "./backend-architecture.mjs";
 import { enforceFrontendDelivery } from "./frontend-delivery-boundary.mjs";
@@ -26,6 +26,20 @@ function fail(message) {
   throw new TypeError(message);
 }
 
+function componentFail(code, message) {
+  const error = new TypeError(`component-capability: ${code}: ${message}`);
+  error.code = code;
+  throw error;
+}
+
+function bindComponentContext(bindings, architectureIdentity) {
+  return bindings.map((binding) => ({
+    ...binding,
+    architecture_family: architectureIdentity.architecture_family,
+    platform_configuration: structuredClone(architectureIdentity.platform_configuration)
+  }));
+}
+
 function stable(value) {
   if (Array.isArray(value)) return value.map(stable);
   if (!value || typeof value !== "object") return value;
@@ -46,11 +60,29 @@ export function loadCompilerContract(filePath = DEFAULT_COMPILER_CONTRACT) {
   return loadYaml(filePath, "实现合同编译器合同");
 }
 
-function assertV2(registry, compilerContract) {
-  if (registry?.schema_version !== 2) fail("技能注册表 schema v1 已停止支持；请迁移到 capability/typed-dependency v2");
+function assertV3(registry, compilerContract) {
+  if (registry?.schema_version !== 3) fail("技能注册表 schema v1/v2 已停止支持；请迁移到 provider/deprecation v3");
   if (compilerContract?.schema_version !== 2) fail("实现合同编译器合同 schema v1 已停止支持；请迁移到 v2");
 }
 
+function skillFail(code, message, details = {}) {
+  const error = new TypeError(`${code}: ${message}`);
+  error.code = code;
+  error.details = details;
+  throw error;
+}
+
+function componentBindingIds(registry, capabilityIds, skillIds, nonExpanding = []) {
+  const capabilitySet = new Set(capabilityIds);
+  const skillSet = new Set([
+    ...skillIds,
+    ...nonExpanding.filter(item => item.type === "component-dependency").map(item => item.skill)
+  ]);
+  return [...new Set(registry.capabilities
+    .filter(capability => capability.provider?.kind === "yss-component" && (capabilitySet.has(capability.id) || skillSet.has(capability.primary_skill)))
+    .map(capability => capability.provider.binding_id))];
+}
+
 function assertNoRemovedId(value, field) {
   for (const id of value) if (REMOVED_SKILL_IDS.has(id)) fail(`${field} 使用已移除 skill id ${id}；不提供兼容 alias`);
 }
@@ -77,7 +109,7 @@ export function compileImplementationContract({
   technical_design,
   readOnly = false
 }) {
-  assertV2(registry, compilerContract);
+  assertV3(registry, compilerContract);
   const recompilationExecution=approved_slice?createApprovedRecompilationContext(approved_slice,{root,work_unit_id}):undefined;
   const deliveryInput = enforceFrontendDelivery({ slice_id, frontend_delivery }, { root });
   if (!Array.isArray(recipeIds) || !Array.isArray(requiredCapabilities) || !Array.isArray(conditions)) {
@@ -91,7 +123,7 @@ export function compileImplementationContract({
   for (const recipeId of requestedRecipes) if (!knownRecipes.has(recipeId)) fail(`未知 recipe: ${recipeId}`);
   const orderedRecipes = registry.recipes.filter((recipe) => requestedRecipes.has(recipe.id));
   const retiredRecipes = new Set(["backend.domain-behavior", "backend.persistence-mybatis", "backend.http-api"]);
-  for (const recipe of orderedRecipes) if (retiredRecipes.has(recipe.id) || recipe.maturity === "deprecated") fail(`deprecated/read-only Recipe ${recipe.id}；必须按架构重新编译`);
+  for (const recipe of orderedRecipes) if (retiredRecipes.has(recipe.id) || recipe.maturity === "deprecated") skillFail("skill-deprecated", `Recipe ${recipe.id} 已停止新用法；必须按架构重新编译`, { recipe_id: recipe.id });
   const architectural = orderedRecipes.some((recipe) => recipe.architecture_family) || requiredCapabilities.some((id) => id.startsWith("layer."));
   let architectureProfile;
   if (architectural || architecture_identity) {
@@ -101,7 +133,6 @@ export function compileImplementationContract({
     for (const recipe of orderedRecipes) if (recipe.architecture_family && recipe.architecture_family !== architecture_identity.architecture_family) fail(`Recipe ${recipe.id} 与架构族不匹配`);
   }
 
-  if (architecture_identity?.platform_configuration) resolveBackendPlatform(architecture_identity.platform_configuration);
   enforceTechnicalDesign({ technical_design, conditions, architecture_identity, slice_id }, { root, execution:recompilationExecution, readOnly });
 
   const capabilitySources = new Map();
@@ -127,7 +158,7 @@ export function compileImplementationContract({
     const family = capabilities.get(id).architecture_family ?? (dddCapabilities.has(id) ? "domain-driven" : null);
     if (family && family !== architecture_identity?.architecture_family) fail(`capability ${id} 与 architecture_identity 不匹配`);
   }
-  const knownSkills = new Set(registry.skills.map((skill) => skill.id));
+  const knownSkills = new Set([...(registry.skills ?? []), ...(registry.external_skills ?? [])].map((skill) => skill.id));
   const conditionSet = new Set(conditions);
   const reasons = new Map();
   const nonExpanding = [];
@@ -142,6 +173,7 @@ export function compileImplementationContract({
   for (const capabilityId of orderedCapabilities) {
     const skill = capabilities.get(capabilityId).primary_skill;
     if (!knownSkills.has(skill)) fail(`${capabilityId} 解析到未知 skill: ${skill}`);
+    resolveSkillForNewUse(registry, skill);
     if (!roots.includes(skill)) roots.push(skill);
     for (const source of capabilitySources.get(capabilityId)) addReason(skill, { ...source, capability: capabilityId });
   }
@@ -156,6 +188,7 @@ export function compileImplementationContract({
     const dependencies = [...(registry.skill_dependencies?.[skill] ?? [])]
       .sort((left, right) => left.skill.localeCompare(right.skill));
     for (const dependency of dependencies) {
+      if (knownSkills.has(dependency.skill)) resolveSkillForNewUse(registry, dependency.skill);
       const conditionMatches = !dependency.when || conditionSet.has(dependency.when);
       if (dependency.type === "context-conditional" && !conditionMatches) {
         excludedConditional.push({ from: skill, ...dependency });
@@ -177,6 +210,23 @@ export function compileImplementationContract({
   for (const root of roots) visit(root);
   enforceHarnessSkillScope(orderedSkills, registry, { root });
 
+  const requiredSkillSet = new Set(orderedSkills);
+  const componentCapabilityIds = componentBindingIds(registry, orderedCapabilities, requiredSkillSet, nonExpanding);
+  let componentBindings = [];
+  if (componentCapabilityIds.length && !architecture_identity?.platform_configuration) {
+    componentFail("component-platform-binding-required", `组件能力 ${componentCapabilityIds.join(", ")} 必须绑定 architecture_identity.platform_configuration v2`);
+  }
+  if (architecture_identity?.platform_configuration) {
+    if (componentCapabilityIds.length) {
+      componentBindings = bindComponentContext(resolveComponentCapabilities(
+        architecture_identity.platform_configuration,
+        componentCapabilityIds,
+        architecture_identity.architecture_family,
+        { root }
+      ), architecture_identity);
+    } else resolveBackendPlatform(architecture_identity.platform_configuration, { root });
+  }
+
   return {
     schema_version: 2,
     status: "draft",
@@ -193,6 +243,10 @@ export function compileImplementationContract({
     recipe_ids: orderedRecipes.map((recipe) => recipe.id),
     conditions: [...conditionSet].sort(),
     required_capabilities: orderedCapabilities,
+    ...(componentBindings.length ? {
+      component_bindings: structuredClone(componentBindings),
+      component_bindings_digest: digestDocument(componentBindings)
+    } : {}),
     required_skills: orderedSkills,
     reason_chains: Object.fromEntries(orderedSkills.map((skill) => [skill, reasons.get(skill) ?? []])),
     non_expanding_dependencies: nonExpanding,
@@ -213,7 +267,7 @@ export function compileDefaultImplementationContract(input = {}) {
 }
 
 export function evaluateContractFreshness(contract, { registry, compilerContract, root = ROOT, approved_slice, readOnly = false, work_unit_id }, execution) {
-  assertV2(registry, compilerContract);
+  assertV3(registry, compilerContract);
   try { contract=normalizeSliceContract(contract,{root}); } catch(error) { return {freshness:'stale',reasons:[error.message]}; }
   if (![2,3].includes(contract?.schema_version)) fail("Slice Implementation Contract schema v1 已停止支持；必须重新编译 v2 合同");
   const all=contract;
@@ -240,6 +294,35 @@ export function evaluateContractFreshness(contract, { registry, compilerContract
     }
     if (resolution.architecture_identity_digest !== architectureDigest(resolution.architecture_identity)) reasons.push("architecture-identity-digest-changed");
   }
+  const requiredCapabilitySet = new Set(resolution.required_capabilities ?? []);
+  const requiredSkillSet = new Set(resolution.required_skills ?? []);
+  const componentCapabilityIds = componentBindingIds(registry, requiredCapabilitySet, requiredSkillSet, resolution.non_expanding_dependencies ?? []);
+  if (componentCapabilityIds.length) {
+    if (!Array.isArray(resolution.component_bindings) || !resolution.component_bindings.length) {
+      reasons.push("component-binding-drift");
+    } else {
+      try {
+        const storedIds = new Set(resolution.component_bindings.map((binding) => binding.capability_id));
+        if (componentCapabilityIds.some((id) => !storedIds.has(id))) throw Object.assign(new TypeError("component-binding-drift: required capability binding missing"), { code: "component-binding-drift" });
+        const groups = new Map();
+        for (const binding of resolution.component_bindings) {
+          if (!binding.platform_configuration || !binding.architecture_family) throw Object.assign(new TypeError("component-binding-drift: binding context missing"), { code: "component-binding-drift" });
+          const key = digestDocument({ platform_configuration: binding.platform_configuration, architecture_family: binding.architecture_family });
+          if (!groups.has(key)) groups.set(key, { platform_configuration: binding.platform_configuration, architecture_family: binding.architecture_family, capability_ids: [] });
+          groups.get(key).capability_ids.push(binding.capability_id);
+        }
+        const currentBindings = [...groups.values()].flatMap((group) => bindComponentContext(resolveComponentCapabilities(
+          group.platform_configuration,
+          group.capability_ids,
+          group.architecture_family,
+          { root }
+        ), { platform_configuration: group.platform_configuration, architecture_family: group.architecture_family }));
+        if (resolution.component_bindings_digest !== digestDocument(currentBindings) || digestDocument(resolution.component_bindings) !== digestDocument(currentBindings)) reasons.push("component-binding-drift");
+      } catch (error) {
+        reasons.push(error.code ?? ["component-new-adoption-forbidden", "component-retirement-evidence-missing", "component-platform-generation-mismatch", "component-unavailable-for-platform", "component-artifact-coordinate-conflict", "component-evidence-missing", "component-binding-drift"].find((code) => error.message?.includes(code)) ?? "component-binding-drift");
+      }
+    }
+  }
   return { freshness: reasons.length ? "stale" : "current", reasons };
 }
 
@@ -259,6 +342,7 @@ export function validateExecutionResult(result, contract, current) {
   if (resolution.readiness_blockers?.length) blockers.push(...resolution.readiness_blockers);
   if (consumed.contract_id !== contract.contract_id || consumed.contract_version !== contract.contract_version) blockers.push("contract-version-mismatch");
   if (consumed.registry_digest !== resolution.registry_digest || consumed.compiler_contract_digest !== resolution.compiler_contract_digest) blockers.push("resolution-digest-mismatch");
+  if (resolution.component_bindings_digest && consumed.component_bindings_digest !== resolution.component_bindings_digest) blockers.push("component-binding-mismatch");
   if (!Array.isArray(result.verification_results) || !result.verification_results.length) blockers.push("verification-not-executed");
   else for (const item of result.verification_results) {
     if (!item?.command || item.exit_code === undefined || !item.executed_at) blockers.push("verification-result-incomplete");