新增发布 readiness artifact SDK 校验 workflow

2026-06-16 09:32:28 +08:00
parent f4f4b3c744
commit 7177a29fc6
9 changed files with 267 additions and 32 deletions
--- a/PROJECT_COMPLETION_TRACKER.md
+++ b/PROJECT_COMPLETION_TRACKER.md
@@ -9,7 +9,7 @@ turn-by-turn continuation notes and next-batch execution records.
 ## Current Status

 - Active continuation file: `text14.txt`
- Latest completed batch: project release readiness gate artifact
+- Latest completed batch: project release readiness artifact validation workflow
 - Latest relevant commit: use `git log -1 --oneline` after each committed batch
 - Working tree at tracker creation: clean
 - Required policy: LinuxCNC remains the only CNC semantic source
@@ -43,12 +43,12 @@ The project is complete for the current scope when all of the following are true
 | Native nc_files baseline | Stable | Last recorded Layer 1: `total 107`, `pass 101`, `expected_fail 6`, `unexpected_fail 0`. |
 | Native sim configs baseline | Stable | Last recorded Layer 2: `total 159`, `pass 151`, `expected_fail 8`, `unexpected_fail 0`. |
 | OPFS/session persistence | Stable for current scope | Browser smoke passes, SDK re-exports OPFS/session helpers including `readMachineSessionReadiness()` and `createMachineSessionPersistenceSummary()`, the UI exposes `getMachineSessionPersistenceSummary()`, and `docs/opfs-session-persistence.md` defines the project-level release gate. |
-| SDK/API surface | Stable for current scope | SDK re-exports core, OPFS/session readiness/load helpers, sim-config staging, project release readiness, INI panel entry/launcher/control-page/shell/workflow overview helpers, the session readiness workflow report, and the shell API surface inventory with a Node surface smoke. |
+| SDK/API surface | Stable for current scope | SDK re-exports core, OPFS/session readiness/load helpers, sim-config staging, project release readiness report/artifact validation, INI panel entry/launcher/control-page/shell/workflow overview helpers, the session readiness workflow report, and the shell API surface inventory with a Node surface smoke. |
 | Browser/UI workflow | Stable for current scope | Workflow overview embedding mount DOM closure is complete, and INI panel session workflows plus read-only control/shell handoff expose, render, and report OPFS/session readiness, OPFS/session persistence summary, and API surface inventory before loading or reading WASM session state. |
 | Workflow overview embedding | Stable for current scope | Report/display/render, DOM contract/readiness/renderer, mount result/display/render, mount DOM contract/readiness/renderer/wrapper exist. |
 | Host/runtime boundary proof | Stable blocked state | Host smoke passes; runtime families remain blocked and `docs/host-runtime-boundary-handoff.md` records host readiness, promotion blockers, dispatch, and evidence gates. |
 | Documentation/release gate | Stable for current scope | `docs/project-release-handoff.md` links README, panel entry, SDK, OPFS/session, sim-config, host/runtime, source reuse, drift, tracker acceptance paths, and the machine-readable release readiness report/artifact. |
-| Project release gate wrapper | Stable | `tests/host/verify_project_release_gate.sh` runs the documented minimum release validation commands, writes `build/project-release-readiness.json`, verifies it, and ends with `project_release_gate=ok`. |
+| Project release gate wrapper | Stable | `tests/host/verify_project_release_gate.sh` runs the documented minimum release validation commands, writes `build/project-release-readiness.json`, verifies it through the SDK artifact validation workflow, and ends with `project_release_gate=ok`. |

 ## Blocked Runtime Families

--- a/text14.txt
+++ b/text14.txt
@@ -2918,3 +2918,85 @@ artifact 摘要：

 继续只做实质能力推进。下一批优先选择真实 browser/UI workflow 或外部 shell 可消费能力；
 如果继续 release 路径，必须产出可执行 gate 或可消费 artifact，不再只做文档/记录补强。
+
+三十七、2026-06-16 继续执行记录：project release readiness artifact validation workflow
+
+本轮继续按“每批必须产出可调用 API、可验证 workflow、可执行 gate、或真实 UI/browser 能力”推进，
+把 release readiness artifact 从 host 测试里的硬编码断言推进为 SDK 可调用的 artifact parse/validation
+workflow。外部工具现在可以直接复用 SDK 校验 `build/project-release-readiness.json`，host gate verifier
+也改为复用同一套 SDK workflow。
+
+完成内容：
+
+- `runtime/sdk/src/project-release-readiness.js` 新增：
+  - `parseProjectReleaseReadinessArtifactJson()`；
+  - `createProjectReleaseReadinessArtifactValidation()`；
+- artifact validation 输出：
+  - `apiName: "project-release-readiness-artifact-validation"`；
+  - `validationVersion`；
+  - `phase`；
+  - `ready`；
+  - `missing`；
+  - `artifactApiName`；
+  - `artifactVersion`；
+  - `gateCount`；
+  - `blockedRuntimeFamilies`；
+  - `rows`；
+- 修复 artifact validation 中空 `gates` 数组会因 `Array.every()` 空真值被误判为 passed 的问题；
+- `runtime/sdk/src/index.js` re-export 新 parse/validation API；
+- `tests/host/verify_project_release_readiness_artifact.mjs` 改为调用 SDK parse/validation workflow；
+- `verify_sdk_surface.mjs` 覆盖：
+  - artifact JSON parse；
+  - ready artifact validation；
+  - 空 artifact blocked/missing；
+  - blocked runtime family 不被误 promotion；
+- `runtime/sdk/README.md` 和 `docs/project-release-handoff.md` 记录外部工具如何复用 artifact validation API；
+- `verify_project_release_handoff_docs.mjs` 覆盖新 artifact validation API；
+- `PROJECT_COMPLETION_TRACKER.md` 同步 latest completed batch、SDK/API surface 与 release gate wrapper 状态；
+- 未新增控制按钮；
+- 未执行 action-plan；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未运行 opt-in runtime probes；
+- 未 promotion blocked runtime family；
+- 未改变 LinuxCNC interpreter、tool、parameter、planner、kinematics、remap 或 LinuxCNC-owned
+  runtime semantics。
+
+验证已通过：
+
+```bash
+git diff --check
+wasm-port/tests/sdk/node/verify_sdk_surface.sh
+wasm-port/tests/host/verify_project_release_readiness_artifact.sh
+wasm-port/tests/docs/node/verify_project_release_handoff_docs.sh
+wasm-port/tools/verify_vendor_sync.sh
+wasm-port/tools/verify_no_standalone_cnc_semantics.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+wasm-port/tests/host/verify_project_release_gate.sh
+```
+
+关键输出：
+
+```text
+sdk_surface_node_smoke=ok
+project_release_readiness_artifact_node_smoke=ok
+project_release_handoff_docs_node_smoke=ok
+vendor sync up to date
+standalone CNC semantics guard complete
+interp_wasm_node_smoke=ok
+sim_configs_wasm_node_inventory_unexpected_fail=0
+ui_node_smokes=ok
+browser_ini_shell_integration_workflow_smoke=ok
+project_release_readiness_artifact=/home/cnc/桌面/cnc_wams/wasm-port/build/project-release-readiness.json
+host_wasm_opfs_browser_smokes=ok
+project_release_gate=ok
+```
+
+下一步工作计划：
+
+继续只做实质能力推进。优先选择真实 browser/UI workflow 或外部 shell 可消费能力；
+如果继续 release 路径，必须继续产出可调用 API、可验证 workflow、可执行 gate 或可消费 artifact。
--- a/wasm-port/docs/project-release-handoff.md
+++ b/wasm-port/docs/project-release-handoff.md
@@ -41,7 +41,9 @@ continuation records are in `../text14.txt`.
  evidence driven and only reports `ready: true` when the caller supplies
  release gate evidence such as `project_release_gate=ok`. The project release
  gate writes the same report to `build/project-release-readiness.json` and
-  validates it with `verify_project_release_readiness_artifact.sh`.
+  validates it with `verify_project_release_readiness_artifact.sh`. External
+  tools can load that artifact with `parseProjectReleaseReadinessArtifactJson()`
+  and validate it with `createProjectReleaseReadinessArtifactValidation()`.
 - OPFS/session callers can use `createMachineSessionPersistenceSummary()` or
  `linuxCncIniPanelApi.getMachineSessionPersistenceSummary()` to inspect
  machine files, session snapshot, session readiness, session load, readonly
--- a/wasm-port/runtime/sdk/README.md
+++ b/wasm-port/runtime/sdk/README.md
@@ -47,6 +47,7 @@ import {
  createMachineSessionPersistenceRenderState,
  createMachineSessionPersistenceSummary,
  createMachineSessionSnapshotPayload,
+  createProjectReleaseReadinessArtifactValidation,
  createProjectReleaseReadinessReport,
  createSessionSnapshot,
  defaultMachinePaths,
@@ -69,6 +70,7 @@ import {
  mountIniPanelShellWorkflowOverviewEmbeddingMountState,
  normalizeOpfsPath,
  parameterFilePath,
+  parseProjectReleaseReadinessArtifactJson,
  planIniFileContextStaging,
  planSimConfigStaging,
  readMachineSessionReadiness,
@@ -194,7 +196,10 @@ and `../PROJECT_COMPLETION_TRACKER.md`.
 The executable release gate uses the same helper to write
 `build/project-release-readiness.json` after all project checks pass, then
 validates that artifact with
-`tests/host/verify_project_release_readiness_artifact.sh`.
+`tests/host/verify_project_release_readiness_artifact.sh`. External tools can
+load that JSON with `parseProjectReleaseReadinessArtifactJson()` and validate
+it with `createProjectReleaseReadinessArtifactValidation()` without copying the
+host test assertions.

 ## OPFS/session persistence exports

--- a/wasm-port/runtime/sdk/src/index.js
+++ b/wasm-port/runtime/sdk/src/index.js
@@ -1,6 +1,10 @@
 export { createLinuxCncIniSdk } from "./linuxcnc-ini.js";
 export { createLinuxCncInterpSdk } from "./linuxcnc-interp.js";
-export { createProjectReleaseReadinessReport } from "./project-release-readiness.js";
+export {
+  createProjectReleaseReadinessArtifactValidation,
+  createProjectReleaseReadinessReport,
+  parseProjectReleaseReadinessArtifactJson,
+} from "./project-release-readiness.js";
 export {
  analyzeIniRuntimeBoundaries,
  planIniFileContextStaging,
--- a/wasm-port/runtime/sdk/src/project-release-readiness.js
+++ b/wasm-port/runtime/sdk/src/project-release-readiness.js
@@ -67,6 +67,9 @@ const BLOCKED_RUNTIME_FAMILIES = [
  "L4-PYTHON-REMAP",
 ];

+const PROJECT_RELEASE_READINESS_ARTIFACT_API = "project-release-readiness-report";
+const PROJECT_RELEASE_READINESS_ARTIFACT_VERSION = 1;
+
 function outputContains(observedOutputs, expectedOutput) {
  return observedOutputs.some((output) => String(output).includes(expectedOutput));
 }
@@ -81,6 +84,14 @@ function readGatePassed({ gate, gateResults, observedOutputs }) {
  return false;
 }

+function objectOrEmpty(value) {
+  return value && typeof value === "object" ? value : {};
+}
+
+function arrayOrEmpty(value) {
+  return Array.isArray(value) ? value : [];
+}
+
 export function createProjectReleaseReadinessReport({
  gateResults = {},
  observedOutputs = [],
@@ -118,8 +129,8 @@ export function createProjectReleaseReadinessReport({
  ];

  return {
-    apiName: "project-release-readiness-report",
-    reportVersion: 1,
+    apiName: PROJECT_RELEASE_READINESS_ARTIFACT_API,
+    reportVersion: PROJECT_RELEASE_READINESS_ARTIFACT_VERSION,
    phase: ready ? "ready" : "waiting",
    ready,
    missing,
@@ -152,3 +163,69 @@ export function createProjectReleaseReadinessReport({
    ],
  };
 }
+
+export function parseProjectReleaseReadinessArtifactJson(text) {
+  return JSON.parse(String(text));
+}
+
+export function createProjectReleaseReadinessArtifactValidation(artifact = {}) {
+  const artifactObject = objectOrEmpty(artifact);
+  const releaseGate = objectOrEmpty(artifactObject.releaseGate);
+  const simConfigInventory = objectOrEmpty(artifactObject.simConfigInventory);
+  const gates = arrayOrEmpty(artifactObject.gates);
+  const rows = arrayOrEmpty(artifactObject.rows);
+  const gateCountReady = gates.length === REQUIRED_RELEASE_GATES.length;
+  const gatesPassed = gateCountReady && gates.every(({ passed }) => passed === true);
+  const missing = [
+    ...(artifactObject.apiName === PROJECT_RELEASE_READINESS_ARTIFACT_API ? [] : ["apiName"]),
+    ...(artifactObject.reportVersion === PROJECT_RELEASE_READINESS_ARTIFACT_VERSION ? [] : ["reportVersion"]),
+    ...(artifactObject.phase === "ready" ? [] : ["phase"]),
+    ...(artifactObject.ready === true ? [] : ["ready"]),
+    ...(Array.isArray(artifactObject.missing) && artifactObject.missing.length === 0 ? [] : ["missing"]),
+    ...(releaseGate.command === "wasm-port/tests/host/verify_project_release_gate.sh" ? [] : ["releaseGate.command"]),
+    ...(releaseGate.passed === true ? [] : ["releaseGate.passed"]),
+    ...(releaseGate.expectedOutput === "project_release_gate=ok" ? [] : ["releaseGate.expectedOutput"]),
+    ...(simConfigInventory.executed === 28 ? [] : ["simConfigInventory.executed"]),
+    ...(simConfigInventory.passed === 28 ? [] : ["simConfigInventory.passed"]),
+    ...(simConfigInventory.skipped === 131 ? [] : ["simConfigInventory.skipped"]),
+    ...(simConfigInventory.unexpectedFail === 0 ? [] : ["simConfigInventory.unexpectedFail"]),
+    ...(arrayOrEmpty(artifactObject.blockedRuntimeFamilies).join(",") === BLOCKED_RUNTIME_FAMILIES.join(",")
+      ? []
+      : ["blockedRuntimeFamilies"]),
+    ...(arrayOrEmpty(artifactObject.promotedBlockedFamilies).length === 0 ? [] : ["promotedBlockedFamilies"]),
+    ...(gateCountReady ? [] : ["gates.length"]),
+    ...(gatesPassed ? [] : ["gates.passed"]),
+    ...(rows.find(({ id, value }) => id === "project-release-gate" && value === "passed")
+      ? []
+      : ["rows.project-release-gate"]),
+  ];
+
+  return {
+    apiName: "project-release-readiness-artifact-validation",
+    validationVersion: 1,
+    phase: missing.length === 0 ? "ready" : "blocked",
+    ready: missing.length === 0,
+    missing,
+    artifactApiName: artifactObject.apiName ?? null,
+    artifactVersion: artifactObject.reportVersion ?? null,
+    gateCount: gates.length,
+    blockedRuntimeFamilies: arrayOrEmpty(artifactObject.blockedRuntimeFamilies),
+    rows: [
+      {
+        id: "artifact",
+        label: "Readiness artifact",
+        value: artifactObject.apiName ?? "missing",
+      },
+      {
+        id: "project-release-gate",
+        label: "Project release gate",
+        value: releaseGate.passed === true ? "passed" : "missing",
+      },
+      {
+        id: "validation",
+        label: "Artifact validation",
+        value: missing.length === 0 ? "ready" : missing.join(", "),
+      },
+    ],
+  };
+}
--- a/wasm-port/tests/docs/node/verify_project_release_handoff_docs.mjs
+++ b/wasm-port/tests/docs/node/verify_project_release_handoff_docs.mjs
@@ -32,6 +32,8 @@ for (const phrase of [
  "PROJECT_COMPLETION_TRACKER.md",
  "runtime/sdk/src/index.js",
  "createProjectReleaseReadinessReport()",
+  "parseProjectReleaseReadinessArtifactJson()",
+  "createProjectReleaseReadinessArtifactValidation()",
  "createIniPanelShellApiSurfaceInventory()",
  "createIniPanelShellSessionReadinessWorkflowReport()",
  "workflow overview embedding mount DOM",
@@ -89,6 +91,8 @@ for (const phrase of [
  "OPFS/session persistence exports",
  "Project release readiness export",
  "createProjectReleaseReadinessReport()",
+  "parseProjectReleaseReadinessArtifactJson()",
+  "createProjectReleaseReadinessArtifactValidation()",
  "build/project-release-readiness.json",
  "INI panel shell handoff exports",
  "createIniPanelShellApiSurfaceInventory()",
--- a/wasm-port/tests/host/verify_project_release_readiness_artifact.mjs
+++ b/wasm-port/tests/host/verify_project_release_readiness_artifact.mjs
@@ -3,33 +3,23 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

+import {
+  createProjectReleaseReadinessArtifactValidation,
+  parseProjectReleaseReadinessArtifactJson,
+} from "../../runtime/sdk/src/index.js";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = resolve(__dirname, "../..");
 const artifactPath = process.argv[2] ?? resolve(root, "build/project-release-readiness.json");
-const artifact = JSON.parse(readFileSync(artifactPath, "utf8"));
+const artifact = parseProjectReleaseReadinessArtifactJson(readFileSync(artifactPath, "utf8"));
+const validation = createProjectReleaseReadinessArtifactValidation(artifact);

-assert.equal(artifact.apiName, "project-release-readiness-report");
-assert.equal(artifact.reportVersion, 1);
-assert.equal(artifact.phase, "ready");
-assert.equal(artifact.ready, true);
-assert.deepEqual(artifact.missing, []);
-assert.equal(artifact.releaseGate.command, "wasm-port/tests/host/verify_project_release_gate.sh");
-assert.equal(artifact.releaseGate.passed, true);
-assert.equal(artifact.releaseGate.expectedOutput, "project_release_gate=ok");
-assert.equal(artifact.simConfigInventory.executed, 28);
-assert.equal(artifact.simConfigInventory.passed, 28);
-assert.equal(artifact.simConfigInventory.skipped, 131);
-assert.equal(artifact.simConfigInventory.unexpectedFail, 0);
-assert.deepEqual(artifact.blockedRuntimeFamilies, [
-  "L4-USER-M-PROCESS",
-  "L4-TOOL-DB",
-  "L4-PYTHON-REMAP",
-]);
-assert.deepEqual(artifact.promotedBlockedFamilies, []);
-assert.equal(artifact.gates.every(({ passed }) => passed === true), true);
-assert.equal(
-  artifact.rows.find(({ id }) => id === "project-release-gate")?.value,
-  "passed",
-);
+assert.equal(validation.apiName, "project-release-readiness-artifact-validation");
+assert.equal(validation.ready, true);
+assert.equal(validation.phase, "ready");
+assert.deepEqual(validation.missing, []);
+assert.equal(validation.artifactApiName, "project-release-readiness-report");
+assert.equal(validation.artifactVersion, 1);
+assert.equal(validation.gateCount, 9);

 console.log("project_release_readiness_artifact_node_smoke=ok");
--- a/wasm-port/tests/sdk/node/verify_sdk_surface.mjs
+++ b/wasm-port/tests/sdk/node/verify_sdk_surface.mjs
@@ -28,7 +28,9 @@ import {
  createMachineSessionPersistenceDisplayViewModel,
  createMachineSessionPersistenceRenderState,
  createMachineSessionPersistenceSummary,
+  createProjectReleaseReadinessArtifactValidation,
  createProjectReleaseReadinessReport,
+  parseProjectReleaseReadinessArtifactJson,
  createSessionSnapshot,
  defaultMachinePaths,
  gcodeFilenameFromProgramPath,
@@ -73,7 +75,9 @@ const trackerText = readFileSync(resolve(root, "../PROJECT_COMPLETION_TRACKER.md
 const requiredExports = [
  ["createLinuxCncIniSdk", createLinuxCncIniSdk],
  ["createLinuxCncInterpSdk", createLinuxCncInterpSdk],
+  ["createProjectReleaseReadinessArtifactValidation", createProjectReleaseReadinessArtifactValidation],
  ["createProjectReleaseReadinessReport", createProjectReleaseReadinessReport],
+  ["parseProjectReleaseReadinessArtifactJson", parseProjectReleaseReadinessArtifactJson],
  ["planIniFileContextStaging", planIniFileContextStaging],
  ["planSimConfigStaging", planSimConfigStaging],
  ["analyzeIniRuntimeBoundaries", analyzeIniRuntimeBoundaries],
@@ -170,6 +174,73 @@ const releaseReadinessReady = createProjectReleaseReadinessReport({
 });
 assert.equal(releaseReadinessReady.ready, true);
 assert.equal(releaseReadinessReady.releaseGate.passed, true);
+const releaseReadinessArtifact = parseProjectReleaseReadinessArtifactJson(JSON.stringify(createProjectReleaseReadinessReport({
+  gateResults: {
+    "diff-check": true,
+    "vendor-sync": true,
+    "standalone-cnc-semantics": true,
+    "interp-wasm": true,
+    "sim-config-inventory": true,
+    "ini-panel-browser": true,
+    "ui-node-smokes": true,
+    "host-smokes": true,
+    "project-release-gate": true,
+  },
+})));
+assert.equal(releaseReadinessArtifact.apiName, "project-release-readiness-report");
+assert.deepEqual(createProjectReleaseReadinessArtifactValidation(releaseReadinessArtifact), {
+  apiName: "project-release-readiness-artifact-validation",
+  validationVersion: 1,
+  phase: "ready",
+  ready: true,
+  missing: [],
+  artifactApiName: "project-release-readiness-report",
+  artifactVersion: 1,
+  gateCount: 9,
+  blockedRuntimeFamilies: [
+    "L4-USER-M-PROCESS",
+    "L4-TOOL-DB",
+    "L4-PYTHON-REMAP",
+  ],
+  rows: [
+    {
+      id: "artifact",
+      label: "Readiness artifact",
+      value: "project-release-readiness-report",
+    },
+    {
+      id: "project-release-gate",
+      label: "Project release gate",
+      value: "passed",
+    },
+    {
+      id: "validation",
+      label: "Artifact validation",
+      value: "ready",
+    },
+  ],
+});
+assert.deepEqual(
+  createProjectReleaseReadinessArtifactValidation({}).missing,
+  [
+    "apiName",
+    "reportVersion",
+    "phase",
+    "ready",
+    "missing",
+    "releaseGate.command",
+    "releaseGate.passed",
+    "releaseGate.expectedOutput",
+    "simConfigInventory.executed",
+    "simConfigInventory.passed",
+    "simConfigInventory.skipped",
+    "simConfigInventory.unexpectedFail",
+    "blockedRuntimeFamilies",
+    "gates.length",
+    "gates.passed",
+    "rows.project-release-gate",
+  ],
+);
 assert.equal(
  createProjectReleaseReadinessReport({
    observedOutputs: ["project_release_gate=ok"],