docs(platform): record Ontology Runtime R2 contract for trusted execution (#328)

[waterbro-8]

Refs #328

What this is

R2 design increment asked for an Ontology Runtime seam and evidence on the issue. This PR records the glossary/boundary, publishes two bounded example payloads on the #302 github-ops pilot, adds fail-closed pure tests for AC-003, and packages semantic-runtime.js on the shared runtime allowlist.

It is not live GitHub execution, not a graph database, and not Sales Workbench vocabulary in core.

Commits

• b6acbca contract + examples + tests
• 5d267c0 add dist/semantic-runtime.js to SHARED_RUNTIME_FILES (first CI failed without this)
• 9b6b7d1 fail closed on invalid expiry, bind retries to target version, and align pre-run transitions with docs(platform): record trusted execution semantic contract R1 (#328) #346

Validation ledger

ID	Criterion	Evidence	Status
AC-001	Glossary freeze + owners + pilot	docs/design/ontology-runtime-r2.md §2–3	PROPOSED — productOwner / technicalOwner still require explicit decision on #328
AC-002	Read-only + write example payloads	examples/github-ops/semantic/*.v1.json	DONE in-repo; parse test passed
AC-003	Safety invariants	apps/server/test/semantic-runtime.test.ts	VERIFIED — 8/8 locally and current-head CI passed
AC-004	Deterministic read-only proof	Read-only example JSON	CONTRACT EXAMPLE ONLY — no live external proof claimed
AC-005	Controlled write proof	Write-capable example JSON	MOCK/CONTRACT LEVEL — no live gh pr merge execution claimed
AC-006	Reconcile #327 / #143 / handoff	design doc §3	DONE as design text
AC-007	Data/security boundary	design doc §7	DONE as design text
AC-008	Evidence ledger	this PR body + current-head checks + review threads	IN PROGRESS — independent re-review required
V-CI	verify workflow on 9b6b7d18	https://github.com/bytefolk/roleweave/actions/runs/35310362566	PASS — ubuntu/macOS, staging, installers, layout parity; security checks also pass

Review follow-up on 9b6b7d1

• Invalid expiresAt now returns proposal_expiry_invalid; malformed time can no longer fail open.
• sameIdempotencyRetry now requires the same target.version.
• proposed/approved → failed are rejected; pre-run transitions match docs(platform): record trusted execution semantic contract R1 (#328) #346.
• Three independent regression tests were added, bringing the semantic-runtime slice to 8 tests.

Local verification

npm run build
node --test --test-timeout=120000 apps/server/dist/test/semantic-runtime.test.js
tests 8 / pass 8 / fail 0

The broader local run reached scripts 203/203, UI 36/36, server 513 pass / 2 skip / 1 unrelated pre-existing WorkBuddy signal-exit assertion, renderer 528/528, and security audit passed at the repository's high threshold. Two unrelated packaged-smoke temp-directory cleanup assertions also fail consistently in this sandbox. Current-head GitHub CI remains authoritative for the supported ubuntu/macos/windows lanes.

First-run CI on b6acbca failed package-layout.test.mjs: packages/shared/dist/index.js imports unpackaged dist/semantic-runtime.js. Fixed in 5d267c0.

No merge, issue close, product acceptance, live business impact, or owner assignment is claimed. Independent re-review is still required.

[waterbro-8]

验证证据（head 5d267c02）

上一轮 PR 描述写的是「CI 必须跑、本地未装依赖」。本轮把命令跑完了，并把首轮 CI 失败修掉。

首轮 CI 失败（b6acbca）

scripts/test/package-layout.test.mjs：

AssertionError: shared runtime inventory must be updated explicitly when source modules change
-   'semantic-runtime.js',

AssertionError: runtime dependencies missing from the explicit allowlist:
packages/shared/dist/index.js imports unpackaged dist/semantic-runtime.js

Job: https://github.com/bytefolk/roleweave/actions/runs/35301940106/job/105466205625

修复：5d267c0 把 dist/semantic-runtime.js 写入 SHARED_RUNTIME_FILES。

复跑 CI（verify 35302429962）全绿

• Node 24 / ubuntu-latest pass（npm run check）https://github.com/bytefolk/roleweave/actions/runs/35302429962/job/105467661920
• Node 24 / macos-14 pass
• Unpacked staging smoke macOS / Windows pass
• Unsigned installers macOS / Windows pass
• Layout parity pass
• CodeQL / Dependency review / Scorecard pass

Ubuntu 日志里 AC 测试：

✔ #328 AC-003: action cannot run without approval
✔ #328 AC-003: retries reuse the same idempotency identity
✔ #328 AC-003: target version change invalidates the proposal
✔ #328 AC-003: indeterminate never becomes succeeded
✔ #328 AC-002: committed github-ops semantic examples stay parseable

同一 job：server suite tests 513 / pass 511（其余 skip）。

本地复跑（Node v24.20.0）

npm ci --ignore-scripts && npm run build
node --test --test-timeout=120000 apps/server/dist/test/semantic-runtime.test.js
ℹ tests 5  pass 5  fail 0

本地全量 server suite 另有 2 条失败（qoder-engine 把 NO_COLOR 警告当成泄漏；WorkBuddy 子进程退出码），与本切片无关；CI ubuntu 上这两条未复现。

仍未完成（不要按合并/关 Issue 处理）

• AC-001 产品负责人未在 feat(platform): establish the portable Ontology Runtime and trusted execution contract #328 点名 owner / 试点
• AC-004 没有对真实 PR 走 proposal → approval → gh pr merge → exact readback
• AC-006 试点指标全部 NOT MEASURED
• 可移植合同尚未 pin 到 digital-employee
• 本 PR 仍 REVIEW_REQUIRED，我不会自合

[PeterGuy326]

Request changes。

CI 和 PR 自带的 5 条 semantic-runtime 测试都通过；但这两个纯函数目前仍有 fail-open/幂等边界问题，不能批准为 AC-003 的安全契约。

阻塞项：

• P1：非法 expiresAt 必须 fail-closed。当前 Date.parse 返回 NaN 时，NaN <= Date.now() 为 false，assertExecutable 会返回 null，把格式错误的过期时间当成可执行。
• P1：重试身份必须绑定 target version。当前 sameIdempotencyRetry 只比较 idempotencyKey、id 和 target.id；即使 target.version 变了，只要 key 被错误复用仍返回 true，和目标版本失效规则冲突。
• P2：实现允许 proposed/approved 直接进入 failed，但 #346 的规范状态机没有这两条迁移；请在规范中解释预运行失败，或收紧实现并补测试。

修复并补回归测试后请重新请求 review；当前没有批准或合并。

[PeterGuy326]

Reviewed current head 9b6b7d1.

• Invalid expiresAt now fails closed with an explicit invalid-expiry result.
• Retry identity now includes target.version, and the regression test covers a changed target version.
• proposed/approved can no longer transition directly to failed; the added tests cover the state-machine boundary.
• The semantic-runtime focused suite is 8/8, and current required hosted checks are green, including Node 24 Ubuntu/macOS, staging smoke, installer/layout parity, CodeQL, dependency review, and Scorecard.
• The diff is limited to the documented contract/examples, pure shared helpers, packaging allowlist, and focused tests; no live GitHub execution or business/product acceptance is claimed.

Technical review is approved. The PR remains BEHIND main and #328 AC-001/productOwner/technicalOwner plus live proof are explicitly still pending; those are separate merge/product gates, not silently approved by this review.

[waterbro-8]

Updated branch onto current main after #331 merged. PeterGuy326 already approved; waiting for the update-branch CI.

[waterbro-8]

Squash-merged #326. Updating this branch onto current main again.

[waterbro-8]

Post-#326 update-branch CI is green on 88b76a82 (Node 24 Ubuntu/macOS, staging smoke, installers, layout parity, CodeQL, dependency review, Scorecard).

Resolved the three outdated review threads from the earlier fail-closed / retry-identity / state-machine comments; those are fixed on 9b6b7d1 and PeterGuy326 already approved the current head.

Still not merging: #328 AC-001 owner/pilot and live AC-004/AC-006 proof remain open.

[waterbro-8]

Squash-merged #324. Updating this branch onto current main again.

[waterbro-8]

Post-#324 update-branch CI is green on 4c40f989 (Node 24 Ubuntu/macOS, staging smoke, installers, layout parity, CodeQL, dependency review, Scorecard). Still not merging: #328 AC-001 owner/pilot and live AC-004/AC-006 remain open.