docs(platform): record trusted execution semantic contract R1 (#328) by waterbro-8 · Pull Request #346 · bytefolk/roleweave

waterbro-8 · 2026-09-18T03:15:41Z

Summary

Records the R1→R2 design decision for #328 without changing runtime behavior.

ADR-0009: glossary freeze, execution state machine, invariants, ownership, pilot (GitHub ops A GitHub-operations team that can file issues, open PRs and merge — with authoring and merging split across positions #302 as technical proof; Sales Workbench not committed).
docs/design/trusted-execution-v1.md: example payloads (read-only analysis + squash-merge action), safety tests to add later, workbench trace, security/retention, pilot metrics.
Reconciles with feat(memory): define the RoleWeave memory plane for bounded context, archival, and multi-agent recall #327 memory plane, feat(turns): session follow-up context — inject a bounded trusted window into engine spawns #143 short window, and docs/design/workflow-handoff-v1.md.

Do not implement #328 runtime until this decision is accepted.

Test plan

Documents only; examples contain no credentials or customer data
Product/technical owners recorded
digital-employee portable schema promotion tracked as a child issue after acceptance

Freeze the glossary, state-machine invariants, GitHub-ops technical proof, and reconciliation with #327, #143, and workflow-handoff-v1. No runtime change until this decision is accepted.

waterbro-8 · 2026-09-18T03:18:06Z

@PeterGuy326 奕舟，#327 / #328 的 R1 设计已经写成文档 PR，请你过 Gate D0（先不开发）。

整体路线：记忆分四层——源日志、链式 segment+head+索引、mem 里的 durable 派生记录、下一 turn 的逐条准入。FIFO 只管短窗，LRU 只管进程缓存，TTL 只管召回资格、不默默删源。多 Agent 用 branch head，禁止互相覆盖 checkpoint。验收看净 token 和质量，不看毛 prompt 缩短。

和 #328 的关系：327 管「带什么上下文」；328 管「对哪个业务对象做了什么、有没有 readback」。技术证明继续走 #302 GitHub ops；Sales Workbench 未承诺。

分仓（接受后再建子 issue）：

digital-employee：segment 契约、逐条准入、硬预算、压缩恢复
context：archive 引用与 digest（不改 ADR-0006）
mem：durable-memory.v1 的 expiry/pin/forget/readback
RoleWeave：receipt UI、pin/forget、handoff 带 checkpoint

PR：

本轮只有文档，没有运行时改动。

waterbro-8 · 2026-09-18T03:27:58Z

自验结果（文档 PR，对照 #328）

本 PR 是纯文档 R1（ADR-0009 + docs/design/trusted-execution-v1.md + CHANGELOG），无运行时改动。内容能撑住 needs-design / Gate D0 设计稿，还不能合，也不能算出关。

CI：红，不能当绿

Node 24 / macos-14 失败
renderer/test/App.test.tsx:1685（keeps the employee workbench mounted while the overview handles or…）5s timeout。同仓库 docs(memory): record RoleWeave memory-plane R1 design (#327) #345 的同一 job 是绿的，本 PR 不碰 renderer。判断是 macOS 测试超时抖动。
Unpacked staging smoke / Windows x64 失败
staged process tree did not exit + refusing Windows cleanup because the bound root is no longer current。docs(memory): record RoleWeave memory-plane R1 design (#327) #345 同 job 是绿的。判断是 Windows 冒烟清理失败，不是文档回归。因此 Layout parity 被 skip。

其余（ubuntu verify、macOS unpacked、两边 unsigned installer、CodeQL、Scorecard）是绿的。未在本地复现 Electron / Windows 冒烟。

对照 #328

有：词汇表、状态机、只读/写入两条示例、安全不变量（实现子 issue 才测）、feat(memory): define the RoleWeave memory plane for bounded context, archival, and multi-agent recall #327 / feat(turns): session follow-up context — inject a bounded trusted window into engine spawns #143 / handoff / A GitHub-operations team that can file issues, open PRs and merge — with authoring and merging split across positions #302 和解、试点指标、安全边界
明确：技术证明走 A GitHub-operations team that can file issues, open PRs and merge — with authoring and merging split across positions #302；Sales Workbench 未承诺
还缺：产品/技术负责人仍是「待分诊」；AC-003/004 的真实测试和端到端证明不在本 PR（设计稿阶段正确）

合并

REVIEW_REQUIRED，已请求 @PeterGuy326，目前 0 review。失败 check 也会挡住合并。mergeStateStatus: BLOCKED。

PeterGuy326

Request changes。

这是一份方向清楚的 R1/R2 设计稿，但当前还不能作为可信执行契约合并。

阻塞项：

P1：ActionProposal 没有携带自身的 target digest/version；不变量和 idempotencyKey 明确依赖 targetDigest，且 target 变化必须使 proposal 失效，但示例的 proposal.target 只有 kind/locator，无法把审批绑定到具体 head。
P1：approval 只有 approvalId 和 state=granted，没有 approver principal、proposal/target 绑定、授予/过期/撤销信息。canRun 要求有效 permission/approval；不补这些绑定，批准能力可能被跨 proposal/target 重放。
P2：示例中的 sha256:1111、sha256:aaaa、sha:deadbeef 等与前面约定的 sha256: 不一致，也不是完整 SHA-256 值；请统一成合法示例或显式 placeholder。

另外，当前 head 的 Node 24 / macos-14 和 Unpacked staging smoke / Windows x64 仍失败，导致 Layout parity 被 skip；即使失败看起来与文档无关，也需要在当前 head 上重跑并恢复合并门禁。修订后请重新请求 review。

PeterGuy326 · 2026-09-18T03:37:56Z

+    "schemaVersion": "action-proposal.v1",
+    "proposalId": "ap_merge_12",
+    "intent": "squash_merge",
+    "target": { "kind": "github.pull_request", "locator": "github.com/bytefolk/roleweave/pull/12" },


[P1] 把目标版本绑定进 ActionProposal。上面的不变量和校验函数依赖 targetDigest 来生成幂等键并在目标变化时失效，但 proposal 的 target 只有 kind/locator；外层 BusinessObjectRef 的 digest/targetVersion 没有成为 proposal 字段，也没有被 approval 或 idempotencyKey 引用。执行器因此无法证明批准的是当前 PR head。请在 action-proposal.v1 中显式携带 targetDigest/targetVersion，并将它绑定到 approval、幂等键和 receipt/readback。

PeterGuy326 · 2026-09-18T03:37:56Z

+      "head_sha_unchanged"
+    ],
+    "permissionScope": "contents:write",
+    "approval": { "required": true, "approvalId": "cap_merge_1", "state": "granted" },


[P1] 把 approval 绑定到提案和授权主体。canRun 要求有效 permission/approval，但示例只有 approvalId 与 state，没有 approver principal、proposalId/targetDigest、授予时间、过期/撤销语义或 capability grant。这样一个 granted approval 可能被重放到另一个 proposal/target。请补齐字段并定义校验与失效规则。

PeterGuy326 · 2026-09-18T03:37:56Z

+见 ADR-0009 表格。附加字段约定：
+
+- 所有 ref 带 `workspaceId`（或等价 scope）与 `asOf` 时间。  
+- digest 使用 `sha256:<hex>`。  


[P2] 统一 digest 示例格式。后面的示例使用 sha256:1111、sha256:aaaa、sha:deadbeef，既不是完整 SHA-256，也和这里约定的 sha256: 不一致。请使用 64-hex 示例或显式标注 placeholder，否则实现/fixture 校验会遇到不一致的规范。

waterbro-8 · 2026-09-19T05:42:26Z

Cleanup after 胡奕舟 2026-09-19 09:21「你们的 pr 清理一下」。

R1 docs PR (ADR-0009 + trusted-execution-v1.md). PeterGuy326 CHANGES_REQUESTED P1s (bind targetDigest/targetVersion into ActionProposal; bind approval to proposal+principal) were implemented in landed roleweave #344 R2 (merge SHA ecc0294bde26dba6dd0d2f3f6f6d123d03842ca0). This branch is still CONFLICTING with main.

Closing as superseded. If ADR-0009 still needs to land as a separate doc, open a follow-up against current main — do not revive this dirty head.

roleweave docs(platform): record trusted execution semantic contract R1 (#328) #346: closed as superseded by docs(platform): record Ontology Runtime R2 contract for trusted execution (#328) #344
roleweave docs(platform): record Ontology Runtime R2 contract for trusted execution (#328) #344: docs(platform): record Ontology Runtime R2 contract for trusted execution (#328) #344
roleweave feat(platform): establish the portable Ontology Runtime and trusted execution contract #328: remains OPEN for product AC

docs(platform): record trusted execution semantic contract R1 (#328)

c5c4786

Freeze the glossary, state-machine invariants, GitHub-ops technical proof, and reconciliation with #327, #143, and workflow-handoff-v1. No runtime change until this decision is accepted.

waterbro-8 mentioned this pull request Sep 18, 2026

feat(platform): establish the portable Ontology Runtime and trusted execution contract #328

Open

waterbro-8 requested a review from PeterGuy326 September 18, 2026 03:18

This was referenced Sep 18, 2026

docs(memory): record RoleWeave memory-plane R1 design (#327) #345

Merged

feat(memory): define the RoleWeave memory plane for bounded context, archival, and multi-agent recall #327

Open

PeterGuy326 requested changes Sep 18, 2026

View reviewed changes

PeterGuy326 mentioned this pull request Sep 18, 2026

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

Merged

waterbro-8 closed this Sep 19, 2026

Navigation Menu

Repository navigation

docs(platform): record trusted execution semantic contract R1 (#328) - #346

docs(platform): record trusted execution semantic contract R1 (#328)#346
waterbro-8 wants to merge 1 commit into
mainfrom
docs/issue-328-trusted-execution-r1

waterbro-8 commented Sep 18, 2026

Uh oh!

waterbro-8 commented Sep 18, 2026

Uh oh!

waterbro-8 commented Sep 18, 2026

Uh oh!

PeterGuy326 left a comment

Uh oh!

PeterGuy326 Sep 18, 2026

Uh oh!

PeterGuy326 Sep 18, 2026

Uh oh!

PeterGuy326 Sep 18, 2026

Uh oh!

waterbro-8 commented Sep 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

waterbro-8 commented Sep 18, 2026

Summary

Test plan

Uh oh!

waterbro-8 commented Sep 18, 2026

Uh oh!

waterbro-8 commented Sep 18, 2026

自验结果（文档 PR，对照 #328）

CI：红，不能当绿

对照 #328

合并

Uh oh!

PeterGuy326 left a comment

Choose a reason for hiding this comment

Uh oh!

PeterGuy326 Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

PeterGuy326 Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

PeterGuy326 Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

waterbro-8 commented Sep 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants