create-yss-spec 3.4.1 → 3.4.4

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

@@ -0,0 +1,210 @@
+import { readFile, readdir, writeFile, stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import net from "node:net";
+import path from "node:path";
+import { parseXmlDocument } from "../vendor/xml.mjs";
+import { runCommand } from "./command-runner.mjs";
+import { assertJavaPlatform, platformDigest } from "./backend-platform.mjs";
+
+const array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const fail = message => { throw new TypeError(`platform-dependencies: ${message}`); };
+const gav = item => `${item.groupId}:${item.artifactId}`;
+export async function platformEvidenceArtifacts(evidenceDir) {
+  const artifacts = [];
+  for (const entry of await readdir(evidenceDir, { withFileTypes: true })) {
+    if (entry.isFile() && (entry.name.endsWith('.log') || ['effective-pom.xml', 'boot-bom-effective.xml', 'dependency-trees.json', 'platform-tests.xml'].includes(entry.name))) {
+      artifacts.push({ ref: entry.name, digest: platformDigest(await readFile(path.join(evidenceDir, entry.name))) });
+    }
+  }
+  return artifacts.sort((a, b) => a.ref.localeCompare(b.ref));
+}
+export function checkPlatformTests(source, capabilities = []) {
+  const suite = parseXmlDocument(source).testsuite;
+  const cases = array(suite?.testcase);
+  const required = ['httpJsonRoundTrip', 'httpValidationRejectsBlank', 'validationAndJsonAutoConfiguration', 'mybatisCanMapVerificationQuery', ...(capabilities.includes('feign-client') ? ['feignCanDecodeJson'] : [])];
+  if (!suite || required.some(name => !cases.some(item => item['@_name'] === name && !['failure', 'error', 'skipped'].some(key => Object.hasOwn(item, key))))) fail('integration tests missing, failed or skipped');
+  return { status: 'passed', test_count: cases.length };
+}
+export async function verifyPlatformTests(projectRoot, evidenceDir, manifest, startedAt) {
+  try {
+    const module = `${manifest.project_name}-${manifest.architecture_family === 'domain-driven' ? 'bootstrap' : 'server'}`;
+    const reportPath = path.join(projectRoot, module, 'target/surefire-reports', `TEST-${manifest.base_package}.PlatformIntegrationTest.xml`);
+    if (!startedAt || (await stat(reportPath)).mtimeMs < startedAt) fail("stale integration test report");
+    const source = await readFile(reportPath, 'utf8');
+    await writeFile(path.join(evidenceDir, 'platform-tests.xml'), source);
+    return checkPlatformTests(source, manifest.module_profile?.requested_capabilities);
+  } catch (error) { return { status: 'failed', error: error.message }; }
+}
+export function checkPlatformDependencies(profile, effectivePom, dependencyTrees, { bootBom, mainArtifact, components = {} } = {}) {
+  const xml = parseXmlDocument(effectivePom);
+  const projects = array(xml.projects?.project ?? xml.project);
+  if (!projects.length || !dependencyTrees.length) fail("missing effective POM or dependency tree");
+  const main = dependencyTrees.filter(item => gav(item) === mainArtifact);
+  if (main.length !== 1) fail("missing or duplicate startup-module runtime tree");
+  const nodes = [];
+  const visit = item => { if (!["compile", "runtime"].includes(item.scope ?? "compile")) return; nodes.push(item); array(item.children).forEach(visit); };
+  array(main[0].children).forEach(visit);
+  const bom = parseXmlDocument(bootBom ?? "<missing/>").project;
+  if (bom?.groupId !== "org.springframework.boot" || bom.artifactId !== "spring-boot-dependencies" || bom.version !== profile.spring_boot_version) fail("wrong or missing independent Boot BOM");
+  const managed = new Map(array(bom.dependencyManagement?.dependencies?.dependency).map(item => [gav(item), item.version]));
+  if (!managed.size) fail("empty Boot BOM dependency management");
+  for (const item of nodes) {
+    const expected = managed.get(gav(item)) ?? components[gav(item)];
+    if (/^(com\.baomidou|org\.springdoc|org\.springframework\.cloud|com\.yss\.cloud)$/.test(item.groupId) && !expected) fail(`missing component recipe: ${gav(item)}`);
+    if (expected && String(item.version) !== String(expected)) fail(`resolved version differs from BOM/recipe: ${gav(item)}`);
+    if (/^(org\.springframework(?:\.boot)?$|org\.apache\.tomcat\.embed|jakarta\.(servlet|validation)|javax\.(servlet|validation)|(?:tools|com\.fasterxml)\.jackson|org\.slf4j|ch\.qos\.logback)/.test(item.groupId) && !expected) fail(`unmanaged platform runtime artifact: ${gav(item)}`);
+  }
+  const requireArtifact = (group, artifact, match) => {
+    const hits = nodes.filter(item => gav(item) === `${group}:${artifact}`);
+    if (!hits.length || hits.some(item => !match(String(item.version)))) fail(`${group}:${artifact} absent or incompatible`);
+  };
+  const line = (version, prefix) => version === prefix || version.startsWith(`${prefix}.`);
+  requireArtifact("org.springframework.boot", profile.web_starter, version => version === profile.spring_boot_version);
+  requireArtifact("org.springframework", "spring-webmvc", version => line(version, profile.framework_line));
+  requireArtifact("org.apache.tomcat.embed", "tomcat-embed-core", version => line(version, profile.tomcat_line));
+  requireArtifact("com.baomidou", profile.mybatis_plus_starter, version => /^3\./.test(version));
+  requireArtifact(profile.jackson_major === 3 ? "tools.jackson.core" : "com.fasterxml.jackson.core", "jackson-databind", version => version.startsWith(`${profile.jackson_major}.`));
+  for (const item of nodes) {
+    if (item.groupId === "org.springframework.boot" && String(item.version) !== profile.spring_boot_version) fail(`Boot dependency mismatch: ${gav(item)}`);
+    if (item.groupId === "org.springframework" && !line(String(item.version), profile.framework_line)) fail(`Spring dependency mismatch: ${gav(item)}`);
+    if (item.groupId === "org.apache.tomcat.embed" && !line(String(item.version), profile.tomcat_line)) fail(`Tomcat dependency mismatch: ${gav(item)}`);
+    if (item.groupId === "org.springframework.cloud" && /openfeign/.test(item.artifactId) && !line(String(item.version), profile.openfeign_line)) fail("OpenFeign line mismatch");
+    if (item.groupId === "org.springdoc" && !String(item.version).startsWith(`${profile.springdoc_major}.`)) fail("springdoc major mismatch");
+    if (profile.validation_namespace === "jakarta" && ["javax.servlet", "javax.validation"].includes(item.groupId)) fail(`legacy Java EE API: ${gav(item)}`);
+    if (profile.validation_namespace === "jakarta" && item.groupId === "jakarta.validation" && !String(item.version).startsWith("3.")) fail("Jakarta Validation version mismatch");
+    if (item.groupId === "jakarta.servlet" && !line(String(item.version), profile.servlet_version)) fail("Servlet API version mismatch");
+    if (profile.validation_namespace === "javax" && item.groupId === "jakarta.validation" && !String(item.version).startsWith("2.")) fail("Boot 2 requires javax Validation classes");
+    if (profile.validation_namespace === "javax" && item.groupId === "javax.servlet" && !String(item.version).startsWith("4.")) fail("Boot 2 Servlet mismatch");
+    if (item.groupId === "com.baomidou" && /spring-boot[34]-starter|mybatis-plus-boot-starter/.test(item.artifactId) && item.artifactId !== profile.mybatis_plus_starter) fail("mixed MyBatis-Plus starters");
+  }
+  let bootPluginFound = false;
+  for (const project of projects) {
+    const target = project.properties?.["maven.compiler.release"] ?? project.properties?.["maven.compiler.target"] ?? project.properties?.["java.version"];
+    if (![String(profile.java_version), ...(profile.java_version === 8 ? ["1.8"] : [])].includes(String(target))) fail("effective Java target mismatch");
+    for (const plugin of array(project.build?.plugins?.plugin)) if (gav(plugin) === "org.springframework.boot:spring-boot-maven-plugin") {
+      bootPluginFound = true;
+      if (plugin.version !== profile.spring_boot_version) fail("Boot plugin version mismatch");
+    }
+  }
+  if (!bootPluginFound) fail("Boot plugin absent");
+  return { status: "passed", runtime_artifacts: nodes, artifact_count: nodes.length, effective_pom_digest: platformDigest(effectivePom), dependency_tree_digest: platformDigest(dependencyTrees) };
+}
+
+export async function platformCommand(projectRoot, evidenceDir, label, args, environment, options = {}) {
+  const stdout_ref = path.join(evidenceDir, `${label}.stdout.log`);
+  const stderr_ref = path.join(evidenceDir, `${label}.stderr.log`);
+  const executed_at = new Date().toISOString();
+  const start = Date.now();
+  const result = await runCommand(path.join(projectRoot, "mvnw"), args, { cwd: projectRoot, env: environment, timeoutMs: options.timeoutMs || 180000, signal: options.signal, stdoutFile: stdout_ref, stderrFile: stderr_ref, secrets: [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD], progress: true });
+  return { command: `./mvnw ${args.join(" ")}`, exit_code: result.status, termination: result.termination, executed_at, duration_ms: Date.now() - start, stdout_ref, stderr_ref, stdout: result.stdout, stderr: result.stderr };
+}
+export async function verifyPlatformDependencies(projectRoot, evidenceDir, profile, environment, options = {}) {
+  const commands = [];
+  const run = async (label, args) => {
+    const result = await platformCommand(projectRoot, evidenceDir, label, args, environment, options);
+    const { stdout, stderr, ...record } = result;
+    commands.push(record);
+    if (result.exit_code !== 0) fail(`${label} failed; see ${record.stderr_ref}`);
+    return result;
+  };
+  try {
+    const java = await run("platform-java", ["-version"]);
+    assertJavaPlatform(`${java.stdout}\n${java.stderr}`, { java_version: profile.java_version });
+    const pom = path.join(evidenceDir, "effective-pom.xml");
+    const bootBom = path.join(evidenceDir, "boot-bom-effective.xml");
+    await run("platform-boot-bom", ["org.apache.maven.plugins:maven-help-plugin:3.5.1:effective-pom", `-Dartifact=org.springframework.boot:spring-boot-dependencies:${profile.spring_boot_version}`, `-Doutput=${bootBom}`]);
+    await run("platform-effective-pom", ["org.apache.maven.plugins:maven-help-plugin:3.5.1:effective-pom", `-Doutput=${pom}`]);
+    await run("platform-dependency-tree", ["org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree", "-DoutputType=json", "-DoutputFile=.yss/platform-dependencies.json"]);
+    const trees = [];
+    const visited = new Set();
+    for (const directory of [projectRoot, ...(await readdir(projectRoot, { withFileTypes: true })).filter(item => item.isDirectory() && item.name.startsWith(`${path.basename(projectRoot)}-`)).map(item => path.join(projectRoot, item.name))]) {
+      const candidates = [directory];
+      // DDD adapter contains the nested web module.
+      for (const entry of await readdir(directory, { withFileTypes: true })) if (entry.isDirectory() && entry.name.startsWith(`${path.basename(projectRoot)}-`)) candidates.push(path.join(directory, entry.name));
+      for (const candidate of candidates) {
+        if (visited.has(candidate)) continue;
+        visited.add(candidate);
+        try { trees.push(JSON.parse(await readFile(path.join(candidate, ".yss/platform-dependencies.json"), "utf8"))); }
+        catch (error) { if (error.code !== "ENOENT") throw error; }
+      }
+    }
+    await writeFile(path.join(evidenceDir, "dependency-trees.json"), JSON.stringify(trees, null, 2));
+    return { ...checkPlatformDependencies(profile, await readFile(pom, "utf8"), trees, { bootBom: await readFile(bootBom, "utf8"), mainArtifact: `${options.manifest.maven_coordinates.group_id}:${options.manifest.project_name}-${options.manifest.architecture_family === "domain-driven" ? "bootstrap" : "server"}`, components: options.components }), commands };
+  } catch (error) { return { status: "failed", error: error.message, commands }; }
+}
+
+async function freePort() {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+  const port = server.address().port;
+  await new Promise(resolve => server.close(resolve));
+  return port;
+}
+export function checkRuntimeArchive(entries, artifacts, { providedLombokVersion } = {}) {
+  if (!Array.isArray(artifacts) || !artifacts.length) fail("missing runtime artifact inventory");
+  const names = new Set(entries.split(/\r?\n/));
+  const expected = new Set();
+  for (const item of artifacts.filter(item => (item.type ?? "jar") === "jar")) {
+    const name = `BOOT-INF/lib/${item.artifactId}-${item.version}${item.classifier ? `-${item.classifier}` : ""}.jar`;
+    expected.add(name);
+    if (!names.has(name)) fail(`runtime jar missing ${name}`);
+  }
+  const bootVersion = artifacts.find(item => item.groupId === "org.springframework.boot")?.version;
+  // Boot's repackage goal injects its matching jarmode helper outside the dependency tree.
+  for (const name of names) if (name.startsWith("BOOT-INF/lib/") && name.endsWith(".jar") && !expected.has(name)
+    && name !== `BOOT-INF/lib/lombok-${providedLombokVersion}.jar`
+    && !["tools", "layertools"].some(kind => name === `BOOT-INF/lib/spring-boot-jarmode-${kind}-${bootVersion}.jar`)) fail(`unexpected packaged runtime jar: ${name}`);
+  return { status: "passed" };
+}
+async function inspectRuntimeJar(jar, evidenceDir, environment, options) {
+  const tool = environment.JAVA_HOME ? path.join(environment.JAVA_HOME, "bin/jar") : "jar";
+  const stdoutFile = path.join(evidenceDir, "runtime-jar-entries.log");
+  const stderrFile = path.join(evidenceDir, "runtime-jar.stderr.log");
+  const result = await runCommand(tool, ["tf", jar], { env: environment, timeoutMs: 30000, stdoutFile, stderrFile });
+  if (result.status !== 0) fail("cannot inspect packaged runtime jar");
+  return checkRuntimeArchive(result.stdout, options.runtimeArtifacts, options);
+}
+export async function verifyPlatformStartup(projectRoot, evidenceDir, manifest, environment, options = {}) {
+  const runtimeModule = `${manifest.project_name}-${manifest.architecture_family === "domain-driven" ? "bootstrap" : "server"}`;
+  const runtimeTarget = path.join(projectRoot, runtimeModule, "target");
+  try {
+    const packaged = (await readdir(runtimeTarget)).filter(name => name.endsWith(".jar") && !/-sources|-javadoc|-tests/.test(name));
+    if (packaged.length !== 1) fail("expected exactly one production runtime jar");
+    await inspectRuntimeJar(path.join(runtimeTarget, packaged[0]), evidenceDir, environment, options);
+  } catch (error) { return { status: "failed", error: error.message, commands: [] }; }
+  const packaging = await platformCommand(projectRoot, evidenceDir, "platform-local-package", ["-Pscaffold-local", "package", "-DskipTests"], environment, options);
+  const { stdout: ignoredOut, stderr: ignoredErr, ...command } = packaging;
+  if (packaging.exit_code !== 0) return { status: "failed", error: "local packaging failed", commands: [command] };
+  const module = `${manifest.project_name}-${manifest.architecture_family === "domain-driven" ? "bootstrap" : "server"}`;
+  const target = path.join(projectRoot, module, "target");
+  const jars = (await readdir(target)).filter(name => name.endsWith(".jar") && !/-sources|-javadoc|-tests/.test(name));
+  if (jars.length !== 1) return { status: "failed", error: "expected exactly one executable jar", commands: [command] };
+  const port = await freePort();
+  const java = environment.JAVA_HOME ? path.join(environment.JAVA_HOME, "bin/java") : "java";
+  const args = ["-jar", path.join(target, jars[0]), "--spring.profiles.active=scaffold-local", "--server.address=127.0.0.1", `--server.port=${port}`];
+  const processStartedAt = new Date().toISOString();
+  let output = "", errors = "", started = false, exited = false;
+  const child = spawn(java, args, { cwd: projectRoot, env: environment, stdio: ["ignore", "pipe", "pipe"] });
+  child.stdout.on("data", data => { output += data; if (/Started .* in /.test(output)) started = true; });
+  child.stderr.on("data", data => { errors += data; });
+  child.on("error", error => { errors += error.message; exited = true; });
+  const closed = new Promise(resolve => child.once("close", code => { exited = true; resolve(code); }));
+  let passed = false;
+  const deadline = Date.now() + Math.min(options.timeoutMs || 60000, 120000);
+  try {
+    while (!exited && Date.now() < deadline && !options.signal?.aborted) {
+      if (started) {
+        try { const response = await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(1000) }); if (response.status > 0 && response.status < 500) { passed = true; break; } } catch {}
+      }
+      await new Promise(resolve => setTimeout(resolve, 250));
+    }
+  } finally {
+    if (!exited) child.kill("SIGTERM");
+    const killTimer = setTimeout(() => { if (!exited) child.kill("SIGKILL"); }, 3000);
+    await closed; clearTimeout(killTimer);
+  }
+  const redact = text => [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD].filter(Boolean).reduce((value, secret) => value.replaceAll(secret, "[REDACTED]"), text);
+  await writeFile(path.join(evidenceDir, "startup.stdout.log"), redact(output));
+  await writeFile(path.join(evidenceDir, "startup.stderr.log"), redact(errors));
+  return { status: passed ? "passed" : "failed", commands: [command], executed_at: processStartedAt, artifact_digest: platformDigest(await readFile(path.join(target, jars[0]))), stdout_ref: path.join(evidenceDir, "startup.stdout.log"), stderr_ref: path.join(evidenceDir, "startup.stderr.log") };
+}

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

@@ -0,0 +1,175 @@
+import { assertSourceFingerprint } from "./backend-platform-provenance.mjs";
+/** Shared, exact backend platform selection. Catalog entries are maintenance-owned. */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PLATFORM_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+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 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")}`;
+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 (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");
+  return value;
+}
+export function platformProfile(id, catalog = loadBackendPlatforms(), version) {
+  const matches = catalog.profiles.filter(item => item.id === id && (!version || item.spring_boot_version === version));
+  if (matches.length > 1) fail("multiple patches: select an exact spring_boot_version");
+  const result = matches[0];
+  if (!result) fail(`unsupported platform_profile: ${id}`);
+  return result;
+}
+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 ?? {} } });
+}
+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) };
+}
+export function resolveBackendPlatform(binding, { catalog = loadBackendPlatforms(), requireVerified = true, root = PLATFORM_ROOT } = {}) {
+  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)");
+  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");
+  if (platformDigest(binding) !== platformDigest(platformBinding(profile, entry))) fail("stale compatibility digest or YSS coordinates");
+  if (requireVerified) {
+    if (entry.status !== "verified") fail(`YSS combination ${entry.id} is not verified`);
+    if (!Array.isArray(entry.evidence) || !entry.evidence.length) fail("verified combination lacks evidence");
+    for (const item of entry.evidence) {
+      if (!item.ref || !item.digest || path.isAbsolute(item.ref) || item.ref.split(/[\\/]/).includes("..")) fail("invalid portable evidence reference");
+      const bytes = readFileSync(path.join(root, item.ref));
+      if (platformDigest(bytes) !== item.digest) fail("compatibility evidence drift");
+      const report = JSON.parse(bytes);
+      if (report.verification_scope !== "empty-scaffold") fail("qualification requires empty-scaffold evidence");
+      if (report.recipe_digest !== platformRecipeDigest(profile, entry)) fail("evidence recipe drift");
+      assertSourceFingerprint(report.source_fingerprint, report.architecture_family);
+      if (!/^sha256:[a-f0-9]{64}$/.test(report.generated_tree_digest ?? "")) fail("missing generated tree digest");
+      evidenceReports.push(report);
+      if (report.status !== "passed" || report.spring_boot_version !== profile.spring_boot_version || report.java_version !== profile.java_version || report.architecture_family !== item.architecture_family || platformDigest(report.parent) !== platformDigest(entry.parent) || platformDigest(report.bom) !== platformDigest(entry.bom)) fail("compatibility evidence identity mismatch");
+      for (const phase of ["validate", "test", "package"]) if (!report.commands?.some(cmd => cmd.command === `./mvnw ${phase}` && cmd.exit_code === 0 && cmd.stdout_ref && cmd.stderr_ref && cmd.executed_at)) fail("missing real Maven evidence");
+      if (report.dependency_check !== "passed" || report.startup_check !== "passed" || report.integration_tests?.status !== "passed") fail("missing dependency/startup/integration-test evidence");
+      const required = ["effective-pom.xml", "dependency-trees.json", "platform-tests.xml", "boot-bom-effective.xml", "runtime-jar-entries.log", "startup.stdout.log", "startup.stderr.log", ...["validate", "test", "package"].flatMap(phase => [`mvnw-${phase}.stdout.log`, `mvnw-${phase}.stderr.log`])];
+      if (!Array.isArray(report.evidence_artifacts) || required.some(ref => !report.evidence_artifacts.some(artifact => artifact.ref === ref))) fail("missing portable evidence artifacts");
+      for (const artifact of report.evidence_artifacts) {
+        if (!artifact.ref || path.isAbsolute(artifact.ref) || artifact.ref.split(/[\\/]/).includes("..")) fail("invalid evidence artifact path");
+        if (platformDigest(readFileSync(path.join(root, path.dirname(item.ref), artifact.ref))) !== artifact.digest) fail("evidence artifact drift");
+      }
+    }
+  }
+  return { profile, entry, evidenceReports };
+}
+export function assertContractPlatform(contract, decision, options = {}) {
+  const binding = contract.platform_configuration;
+  const resolved = resolveBackendPlatform(binding, options);
+  if (contract.profiles?.platform !== resolved.profile.id || contract.profiles?.validation_namespace !== resolved.profile.validation_namespace) fail("platform and validation_namespace are inconsistent");
+  if (platformDigest(contract.maven_coordinates?.parent) !== platformDigest(binding.parent) || contract.maven_coordinates?.yss_components_version !== binding.bom.version || binding.bom.group_id !== "com.yss.cloud" || binding.bom.artifact_id !== "yss-components-bom") fail("YSS Maven coordinates mismatch");
+  if (decision && platformDigest(decision.platform_configuration) !== platformDigest(binding)) fail("decision/contract platform_configuration mismatch");
+  if (options.requireVerified !== false && !resolved.entry.evidence?.some(item => item.architecture_family === contract.architecture_family)) fail("architecture has no compatibility evidence");
+  for (const capability of contract.module_profile?.requested_capabilities ?? []) if (!resolved.entry.capabilities?.includes(capability)) fail(`unverified capability: ${capability}`);
+  if (options.requireVerified !== false && !resolved.evidenceReports.some(report => report.architecture_family === contract.architecture_family && (contract.module_profile?.requested_capabilities ?? []).every(capability => report.verified_capabilities?.includes(capability)))) fail("architecture/capability combination lacks evidence");
+  return resolved;
+}
+export function assertPlatformAgreement(left, right) {
+  if (platformDigest(left) !== platformDigest(right)) fail("platform_configuration drift between contract and Manifest");
+}
+export function javaMajor(output) {
+  const value = output.match(/(?:java|openjdk) version "(?:1\.)?(\d+)|Java version:\s*(?:1\.)?(\d+)/i);
+  return value ? Number(value[1] ?? value[2]) : null;
+}
+export function assertJavaPlatform(output, binding) {
+  if (javaMajor(output) !== binding.java_version) fail(`JDK mismatch: expected Java ${binding.java_version}`);
+}
+export function platformTemplateVars(profile) {
+  return { boot_version: profile.spring_boot_version, java_version: profile.java_version === 8 ? "1.8" : String(profile.java_version), java_range: profile.java_version === 8 ? "[1.8,1.9)" : `[${profile.java_version},${profile.java_version + 1})`, web_starter: profile.web_starter, web_test_starter: profile.web_test_starter, aop_starter: profile.aop_starter, swagger_artifact: profile.swagger_artifact, ...Object.fromEntries(Object.entries(profile.versions).map(([key, value]) => [`${key}_version`, value])) };
+}
+
+export function platformSmokeTest(basePackage, profile, capabilities = []) {
+  const mapper = profile.jackson_major === 3 ? "tools.jackson.databind.json.JsonMapper" : "com.fasterxml.jackson.databind.ObjectMapper";
+  return `package ${basePackage};
+
+import ${profile.validation_namespace}.validation.Validator;
+import ${profile.validation_namespace}.validation.Valid;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Import;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import ${profile.validation_namespace}.validation.constraints.NotBlank;
+import ${mapper};
+import org.apache.ibatis.annotations.Select;
+import org.apache.ibatis.session.SqlSession;
+import org.apache.ibatis.session.SqlSessionFactory;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+import static org.junit.jupiter.api.Assertions.*;
+
+/** Mechanical integration only: no business endpoint or production storage. */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@Import(PlatformIntegrationTest.ProbeController.class)
+@ActiveProfiles("scaffold-test")
+class PlatformIntegrationTest {
+    @Value("\${local.server.port}") int port;
+    @Autowired Validator validator;
+    public static class ProbePayload {
+        @NotBlank private String value;
+        public String getValue() { return value; }
+        public void setValue(String value) { this.value = value; }
+    }
+    @RestController
+    public static class ProbeController {
+        @PostMapping(value = "/__scaffold_probe", consumes = "application/json", produces = "application/json")
+        public ProbePayload echo(@Valid @RequestBody ProbePayload body) { return body; }
+    }
+    @Test void httpJsonRoundTrip() throws Exception { httpProbe("probe", 200); }
+    @Test void httpValidationRejectsBlank() throws Exception { httpProbe("", 400); }
+    private void httpProbe(String value, int expectedStatus) throws Exception {
+        java.net.HttpURLConnection connection = (java.net.HttpURLConnection) new java.net.URL("http://127.0.0.1:" + port + "/__scaffold_probe").openConnection();
+        connection.setConnectTimeout(5000); connection.setReadTimeout(5000);
+        connection.setRequestMethod("POST"); connection.setRequestProperty("Content-Type", "application/json"); connection.setDoOutput(true);
+        ProbePayload request = new ProbePayload(); request.setValue(value);
+        try {
+            try (java.io.OutputStream stream = connection.getOutputStream()) { stream.write(mapper.writeValueAsBytes(request)); }
+            assertEquals(expectedStatus, connection.getResponseCode());
+            if (expectedStatus == 200) {
+                assertTrue(connection.getContentType().startsWith("application/json"));
+                try (java.io.InputStream stream = connection.getInputStream()) { assertEquals(value, mapper.readValue(stream, ProbePayload.class).getValue()); }
+            }
+        } finally { connection.disconnect(); }
+    }
+    @Autowired ${mapper.split(".").at(-1)} mapper;
+    @Autowired SqlSessionFactory sqlSessionFactory;
+    static final class ValidationProbe { @NotBlank String value = ""; }
+    @Test void validationAndJsonAutoConfiguration() throws Exception {
+        assertFalse(validator.validate(new ValidationProbe()).isEmpty());
+        assertEquals("\\\"probe\\\"", mapper.writeValueAsString("probe"));
+    }
+    interface ProbeMapper { @Select("SELECT 1") int probe(); }
+    @Test void mybatisCanMapVerificationQuery() throws Exception {
+        try (SqlSession session = sqlSessionFactory.openSession()) {
+            if (!session.getConfiguration().hasMapper(ProbeMapper.class)) session.getConfiguration().addMapper(ProbeMapper.class);
+            assertEquals(1, session.getMapper(ProbeMapper.class).probe());
+        }
+    }
+${capabilities.includes("feign-client") ? `    @Autowired org.springframework.cloud.openfeign.${profile.java_version === 8 ? "FeignContext" : "FeignClientFactory"} feignFactory;
+    @Test void feignCanDecodeJson() throws Exception {
+        feign.codec.Decoder decoder = feignFactory.getInstance("platform-probe", feign.codec.Decoder.class);
+        assertNotNull(decoder);
+        feign.Request request = feign.Request.create(feign.Request.HttpMethod.GET, "http://localhost/probe", java.util.Collections.emptyMap(), (byte[]) null, java.nio.charset.StandardCharsets.UTF_8, null);
+        feign.Response response = feign.Response.builder().request(request).status(200).reason("OK")
+            .headers(java.util.Collections.singletonMap("Content-Type", java.util.Collections.singletonList("application/json")))
+            .body("{}", java.nio.charset.StandardCharsets.UTF_8).build();
+        assertTrue(decoder.decode(response, java.util.Map.class) instanceof java.util.Map);
+    }
+` : ""}}
+`;
+}

package/template/scripts/lib/backend-scaffold-prerequisites.mjs

@@ -102,7 +102,7 @@ export async function validateBackendScaffoldPrerequisites(contract, { contractF
   const approvalRef = prerequisites.engineering_contract_approval_ref;
   if (approvalRef !== contract.lifecycle_approval_ref || approvalRef !== contract.approval?.approval_ref) fail("工程合同批准引用与脚手架合同不一致");
   const approvalFile = resolveLocalRef(root, approvalRef, "工程合同批准记录");
-  const approval = loadApprovalRecord(approvalFile);
+  const approval = loadApprovalRecord(approvalFile, 'gate.engineering-contract-approved');
   validateApprovalRecord(approval, { requireApproved: true, root });
   if (approval.gate_id !== "gate.engineering-contract-approved") fail("工程合同批准记录 gate_id 必须为 gate.engineering-contract-approved");
   if (!Array.isArray(approval.approval_scope) || !approval.approval_scope.includes(contract.contract_id) || !approval.approval_scope.includes(contract.project_name)) fail("工程合同批准范围未覆盖当前合同和项目");

package/template/scripts/lib/decision-continuation.mjs

@@ -0,0 +1,79 @@
+import { decisionIO, decisionDigest, decisionError, assertUserDecisionRequirement } from './user-decision.mjs';
+
+export const CONTINUATION_CAPABILITY = 'approved-scope-continuation-v1';
+const fail = message => decisionError('user-decision-continuation-invalid', message);
+const strings = value => Array.isArray(value) && value.length > 0 && value.every(x => typeof x === 'string' && x.trim()) && new Set(value).size === value.length;
+const sameSet = (a, b) => strings(a) && strings(b) && a.length === b.length && a.every(x => b.includes(x));
+const basisFields = ['business_scope', 'acceptance', 'contract_commitments', 'authorization', 'risk_acceptance', 'quality', 'external_commitments'];
+
+// A continuation validates an explicit human mandate and an independent current
+// review. It never infers semantic equivalence from whitespace or a boolean flag.
+export function assertDecisionContinuation(requirement, roles, options = {}) {
+  const io = decisionIO(options);
+  const policy = roles.user_decision_policy.continuation;
+  if (policy?.capability !== CONTINUATION_CAPABILITY || !policy.boundaries.includes(requirement.boundary)) fail('未授权的延续边界');
+  const proof = io.document(requirement.continuation_ref);
+  if (proof.schema_version !== 1 || proof.kind !== CONTINUATION_CAPABILITY || proof.boundary !== requirement.boundary || proof.subject?.ref !== requirement.subject_ref || !sameSet(proof.scope, requirement.scope)) fail('当前边界、资产或范围不匹配');
+  const current = (asset, parse = true) => {
+    if (!asset?.ref || !asset.version || !asset.digest || decisionDigest(io.bytes(asset.ref)) !== asset.digest) fail(`当前证据缺失或过期: ${asset?.ref}`);
+    return parse ? io.document(asset.ref) : null;
+  };
+  if (!proof.source || proof.source.continuation_ref || proof.source.boundary !== 'delivery-scope') fail('必须引用原始交付范围批准，不能链式扩权');
+  const sourceResult = assertUserDecisionRequirement(proof.source, { ...options, rolesDoc: roles });
+  const mandate = io.document(proof.source.subject_ref);
+  if (mandate.schema_version !== 1 || mandate.kind !== 'delivery-authorization' || !Array.isArray(mandate.targets)) fail('缺少已展示并批准的交付授权清单');
+  if (!requirement.scope.every(x => proof.source.scope.includes(x))) fail('超出原始批准范围');
+  const matches = mandate.targets.filter(x => x.boundary === requirement.boundary && x.subject_ref === requirement.subject_ref && requirement.scope.every(s => x.scope?.includes(s)));
+  if (matches.length !== 1) fail('原授权未唯一覆盖当前边界、资产和范围');
+  const target = matches[0];
+  if (!basisFields.every(key => strings(target.decision_basis?.[key]))) fail('原授权缺少业务、验收、契约、授权、风险、质量或对外承诺依据');
+  if (!Array.isArray(mandate.basis) || !mandate.basis.length) fail('原授权缺少可读取的决定依据');
+  for (const asset of mandate.basis) {
+    if (!asset.ref || !asset.version || decisionDigest(io.bytes(asset.ref)) !== asset.digest) fail('原授权决定依据变化，须重新决定');
+  }
+  const external = current(mandate.external_policy);
+  if (external.status !== 'confirmed' || !Array.isArray(external.requirements)) fail('项目外部审批要求尚未确认，不能自动延续');
+  current(proof.subject, false);
+  if (requirement.boundary === 'implementation-scope') {
+    const manifest = io.document(proof.subject.ref);
+    if (manifest.kind !== 'implementation-scope' || !Array.isArray(manifest.slices)) fail('实施范围清单无效');
+    for (const ticket of requirement.scope) {
+      const slices = manifest.slices.filter(x => x.ticket_ref === ticket);
+      const limit = target.implementation_limits?.[ticket];
+      if (slices.length !== 1 || !limit || !sameSet(slices[0].repositories, limit.repositories) || !sameSet(slices[0].allowed_write_paths, limit.allowed_write_paths)) fail('实施仓库或写路径超出原授权边界');
+    }
+  }
+  if (!Array.isArray(proof.basis) || !proof.basis.length) fail('缺少本次实际验证证据');
+  for (const asset of proof.basis) {
+    if (!asset.ref || !asset.version || decisionDigest(io.bytes(asset.ref)) !== asset.digest) fail('本次验证证据过期');
+  }
+  const review = current(proof.review);
+  const actor = roles.roles.find(x => x.id === review.role_id);
+  if (!actor || !roles.runtimes.some(x => x.id === review.runtime_id) || !review.principal_ref || !review.drafter_principal_ref || review.principal_ref === review.drafter_principal_ref) fail('缺少独立专业审查身份');
+  const eligible = roles.gate_policy.continuation_reviews?.[requirement.boundary] || roles.gate_policy.dual_digital_human?.find(x => x.gate === requirement.boundary)?.countersigners;
+  if (!eligible?.includes(review.role_id)) fail('审查能力不覆盖当前边界');
+  if (review.decision !== 'approved' || !['within-approved-scope', 'presentation-only', 'implementation-detail'].includes(review.classification)) fail('未知或实质变化须重新决定');
+  if (!Array.isArray(review.material_changes) || review.material_changes.length || !Array.isArray(review.findings)) fail('存在实质变化或未完成影响分析');
+  for (const finding of review.findings) {
+    if (!finding.id || !finding.reason || !['requirement-violation', 'missing-evidence', 'important-risk', 'suggestion'].includes(finding.kind)) fail('审查发现未分类');
+    if (finding.kind === 'suggestion' && !finding.follow_up) fail('非阻断建议缺少待办去向');
+    if (finding.kind !== 'suggestion' && finding.status !== 'resolved') fail('未解决的缺陷、证据缺口或重要风险');
+  }
+  if (review.boundary !== requirement.boundary || !sameSet(review.scope, requirement.scope) || decisionDigest(review.subject) !== decisionDigest(proof.subject) || decisionDigest(review.basis) !== decisionDigest(proof.basis)) fail('审查未绑定当前资产、范围和验证证据');
+  if (decisionDigest(review.decision_basis) !== decisionDigest(target.decision_basis)) fail('决定依据有实质变化');
+  if (!review.reason?.trim() || !review.comparison?.before || !review.comparison?.after) fail('缺少可审阅的前后差异和等价性说明');
+  // Before is an immutable, originally approved snapshot; after is the current candidate.
+  const before = review.comparison.before;
+  if (!mandate.basis.some(x => decisionDigest(x) === decisionDigest(before)) || decisionDigest(review.comparison.after) !== decisionDigest(proof.subject)) fail('前后差异未绑定原授权快照和当前资产');
+  for (const obligation of external.requirements) {
+    if (!obligation.id || !strings(obligation.boundaries) || !strings(obligation.principals)) fail('外部审批制度记录不完整');
+    if (!obligation.boundaries.includes(requirement.boundary)) continue;
+    for (const principal of obligation.principals) {
+      const reply = proof.external_decisions?.find(x => x.obligation_id === obligation.id && x.principal_ref === principal);
+      if (!reply || reply.requirement?.continuation_ref || reply.requirement?.boundary !== requirement.boundary || reply.requirement?.subject_ref !== requirement.subject_ref || !sameSet(reply.requirement?.scope, requirement.scope)) fail('外部强制审批缺失或范围不符');
+      const result = assertUserDecisionRequirement(reply.requirement, { ...options, rolesDoc: roles });
+      if (!result.validated.length || result.validated.some(x => x.principal_ref !== principal)) fail('外部审批人与制度要求不符');
+    }
+  }
+  return { ...sourceResult, continued: true, review_ref: proof.review.ref };
+}

package/template/scripts/lib/delivery-preflight.mjs

@@ -1,3 +1,4 @@
+import { normalizeSliceContract, sourceSliceContract, parseSliceYaml } from './slice-contract.mjs';
 import { assertExistingSliceStructure, createApprovedExecutionContext, verifySliceContractApproval } from './approved-execution-context.mjs';
 import path from 'node:path';
 import { readFileSync, existsSync } from 'node:fs';
@@ -46,7 +47,7 @@ function requireBackendCapability(key) {
 }
 
 /** Read-only: never executes input commands, starts services, unpacks archives or writes receipts. */
-export async function preflightDelivery(input,{stage,root=process.cwd()}={}) {
+export async function preflightDelivery(input,{stage,root=process.cwd(),work_unit_id}={}) {
   try { ensure(STAGES.includes(stage),'未知阶段；必须是 prepare|build|export|accept');schema(input,'docs/process/schemas/delivery-preflight-input.schema.json'); }
   catch(error) { return invalidPreflightInput(error.message); }
   root=path.resolve(root,input.governance_root||'.');
@@ -78,7 +79,7 @@ export async function preflightDelivery(input,{stage,root=process.cwd()}={}) {
     if(input.architecture_identity.source_kind==='existing-registration')ensure(input.architecture_identity.repository_id===input.scope.repository_id&&input.architecture_identity.project_id===input.scope.project_id,'架构身份与预检目标仓库/项目不一致');
   },{source:'architecture_identity'});
   if(valid.has('architecture.identity'))await run('architecture.profile',()=>{ensure(architecture.validateArchitectureIdentity(input.architecture_identity).maturity==='supported','不支持未达到 supported 的 architecture_profile');},{source:'architecture_profile'});
-  if(['build','export','accept'].includes(stage)&&assets.slice_contract)await run('slice_contract.execution',()=>{requireBackendCapability('slice_contract');execution=createApprovedExecutionContext(assets.slice_contract,{root});},{from:'build',source:assets.slice_contract.approval_ref||'slice_contract',evidence:[assets.slice_contract.ref,...(assets.slice_contract.approval_ref?[assets.slice_contract.approval_ref]:[])]});
+  if(['build','export','accept'].includes(stage)&&assets.slice_contract)await run('slice_contract.execution',()=>{requireBackendCapability('slice_contract');execution=createApprovedExecutionContext(assets.slice_contract,{root,work_unit_id});},{from:'build',source:assets.slice_contract.approval_ref||'slice_contract',evidence:[assets.slice_contract.ref,...(assets.slice_contract.approval_ref?[assets.slice_contract.approval_ref]:[])]});
   const archDeps=['architecture.identity',...['repository_registration','engineering_baseline','manifest'].map(x=>`architecture.${x}`)];
   if(archDeps.every(x=>valid.has(x)))await run('architecture',()=>{
     ensure(typeof architecture.verifyArchitectureEvidence==='function','不支持既有工程原始证据验证，请同步支持该身份版本的模板运行时');
@@ -143,12 +144,12 @@ async function verifyAsset(key,data,binding,{root,input,documents,assets,executi
     await validateTechnicalDesign(data,{root,sliceRef:input.scope.slice_id,readOnly:true,execution});
     await approved(root,binding,['gate.engineering-contract-approved','gate.technical-design-approved']);
   } else if(key==='slice_contract') {
-    const contract=data.slice_contract||data;
+    const contract=normalizeSliceContract(data,{root});
     assertExistingSliceStructure(contract);
-    ensure(contract.schema_version===2&&contract.status==='approved'&&contract.slice_id===input.scope.slice_id,'Slice 合同版本、批准状态或切片不匹配');
+    ensure([2,3].includes(contract.schema_version)&&contract.status==='approved'&&contract.slice_id===input.scope.slice_id,'Slice 合同版本、批准状态或切片不匹配');
     ensure(binding.id===contract.contract_id&&binding.version===contract.contract_version,'Slice 合同身份与引用不一致');
     const compiler=read(safe(ROOT,'.agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml'));
-    for(const [section,fields]of Object.entries(compiler.slice_contract_required))for(const field of fields)ensure(Object.hasOwn(section==='root'?contract:contract[section]||{},field),`合同缺少 ${section}.${field}`);
+    if(contract.schema_version===2)for(const [section,fields]of Object.entries(compiler.slice_contract_required))for(const field of fields)ensure(Object.hasOwn(section==='root'?contract:contract[section]||{},field),`合同缺少 ${section}.${field}`);
     ensure(contract.readiness.blockers.length===0&&contract.readiness.stale_inputs.length===0,'Slice 合同仍有 blocker 或 stale input');
     const resolution=contract.resolution;
     ensure(resolution.freshness==='current','Slice resolution 非 current');

package/template/scripts/lib/digital-human-roles.mjs

@@ -388,6 +388,16 @@ export function validateDigitalHumanRoles(doc, { skillIds, stageIds, gateIds, ar
   }
 
   const decisions = doc.user_decision_policy;
+  if (decisions?.continuation) {
+    const continuation = decisions.continuation;
+    if (continuation.capability !== 'approved-scope-continuation-v1' || continuation.source_boundary !== 'delivery-scope' || continuation.unknown_change !== 'blocked' || continuation.external_policy_unconfirmed !== 'no-automatic-continuation') fail('授权延续策略不能省略未知变化或外部制度保护');
+    requireStringArray(continuation.boundaries, 'continuation.boundaries');
+    for (const boundary of continuation.boundaries) {
+      if (!gateIds.has(boundary) && boundary !== 'implementation-scope') fail(`未支持的延续边界: ${boundary}`);
+      requireStringArray(policy.continuation_reviews?.[boundary], `${boundary}.continuation_reviews`);
+      for (const role of policy.continuation_reviews[boundary]) if (!actors.has(role)) fail(`未知延续审查角色: ${role}`);
+    }
+  }
   if (decisions?.schema_version !== 1 || decisions.default_responder !== "requester" || decisions.delegate_requires_requester_evidence !== true) fail("缺少统一用户决定策略");
   requireStringArray(decisions.gates, "user_decision_policy.gates");
   for (const gate of decisions.gates) if (!gateIds.has(gate)) fail(`用户决定引用未知门禁: ${gate}`);

package/template/scripts/lib/frontend-delivery-boundary.mjs

@@ -1,3 +1,4 @@
+import { normalizeSliceContract, sourceSliceContract, parseSliceYaml } from './slice-contract.mjs';
 import { loadDeliveryProfile } from './harness-execution-scope.mjs';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -8,6 +9,7 @@ import { ROOT, read, safe, ensure, digest } from './strategic-handoff-io.mjs';
 // Always re-executes the verifier; a caller-supplied "verified" flag is never evidence.
 export function enforceFrontendDelivery(state={}, {root=ROOT,phase='inputs'}={}) {
   ensure(['preflight','design','contract','inputs','implementation','verification'].includes(phase),`未知前端交付阶段: ${phase}`);
+  if(state.schema_version===3)state=normalizeSliceContract(state,{root});
   const profile=loadDeliveryProfile(root);
   let contract;
   const contractRef=state.slice_contract_ref||state.contract?.slice_contract_ref;
@@ -35,6 +37,7 @@ export function enforceFrontendDelivery(state={}, {root=ROOT,phase='inputs'}={})
     const file=path.resolve(root,contractRef);
     if(existsSync(file)) {
       const document=read(file);contract=document.slice_contract||document;
+      if(contract.schema_version===3)contract=normalizeSliceContract(contract,{root});
       const direct=contract.frontend?.delivery, resolved=contract.resolution?.frontend_delivery;
       ensure(!direct||!resolved||digest(direct)===digest(resolved),'Slice Contract 前端交付绑定冲突');
       binding=direct||resolved||binding;