Skip to content

docs(architecture): rewrite Runtime Host and define Peer Mesh contracts - #5110

Merged
M4n5ter merged 1 commit into
mainfrom
docs/runtime-host-peer-architecture
Sep 9, 2026
Merged

docs(architecture): rewrite Runtime Host and define Peer Mesh contracts#5110
M4n5ter merged 1 commit into
mainfrom
docs/runtime-host-peer-architecture

Conversation

@M4n5ter

@M4n5ter M4n5ter commented Sep 9, 2026

Copy link
Copy Markdown
Member
English

Summary

Rewrite the Runtime Host architecture contract and add a separate Peer Mesh contract, both in Chinese and English. The previous Host document omitted native Peer streams, Guest mounts, request-level tool composition, cooperative handoff, and distinct idle/drain residency; its transport and lifetime descriptions no longer matched the implementation.

Document authority and identity boundaries, durable versus process-local state, admission and recovery transitions, failure behavior, resource budgets, trade-offs, and source/test entry points. Include the current reconnect diagnostic and deployment-lock contracts, distinguish experimental networking from unsupported future capabilities, and link both documents from the architecture overview and documentation index.

Verified against 09c73430c, including the newer quit-admission and connection-teardown behavior. Refs #5101; that fix merged before this documentation follow-up was ready.

Verification

  • Checked all local source/document links, counterpart metadata, matching section structure, source-reference parity, and bilingual technical claims.
  • Rendered and visually inspected all six Mermaid diagrams (three shared designs across the language counterparts).
  • npm run lint, npm run format:check, staged whitespace, ASF header and protocol-epoch checks passed.
  • Documentation only; no executable code changed and no additional runtime tests were run. Linked tests identify contract coverage, not a claim of real-world NAT or Windows validation.

AI use

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: OpenAI Codex — source review, architecture writing, translation and document verification. The commit includes a Generated-by trailer.

Checklist

  • Tests cover the change and fail without it — documentation checks listed above; runtime tests are not applicable to this diff
  • Lint, format, typecheck and the affected suites pass locally — lint/format and document checks passed; no typecheck or runtime-suite changes

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No
简体中文

Summary / 概述

彻底重写 Runtime Host 架构契约,新增独立的 Peer Mesh 架构契约,均提供中英文版本。旧 Host 文档遗漏了 native Peer stream、Guest mount、请求级工具组合、协作式 handoff 和 idle/drain 驻留区别,传输与生命周期描述已落后于实现。

文档定义 authority 与身份边界、持久/进程内状态、准入和恢复转换、失败行为、资源预算、设计取舍,以及源码和测试入口。补充当前的重连诊断与部署锁契约,区分实验性网络实现和未提供的未来能力,并更新总架构与文档索引。

核对基线为 09c73430c,包含后续合入的退出准入和连接 teardown 行为。关联 #5101;该修复在本次文档完成前已合并,因此另开后续 PR。

Verification / 验证

  • 检查全部本地源码/文档链接、对译元数据、章节结构、源码引用一致性与双语技术语义。
  • 六幅 Mermaid 图均已渲染并目视检查,覆盖三种中英文共用设计。
  • lint、format:check、暂存区空白、ASF header 和协议 epoch 检查通过。
  • 纯文档变更,没有修改可执行代码,也未额外运行 Runtime 测试。链接的测试说明契约覆盖入口,不代表实机 NAT 或 Windows 验证。

AI use / AI 使用

  • 生成式工具没有实质性贡献
  • 生成式工具有实质性贡献

工具及范围:OpenAI Codex,参与源码核对、架构写作、翻译和文档验证;提交包含 Generated-by 标记。

Checklist / 检查项

  • 测试覆盖变更,且在没有修复时失败——此处为上述文档检查,Runtime 测试不适用于该 diff
  • Lint、格式、类型检查和相关测试均在本地通过——已执行 lint/格式与文档检查;无类型或 Runtime 测试变更

本 PR 是否改变行为?

  • 是,已在概述中说明

@github-actions github-actions Bot added the effort/XL Under 2500 readable lines label Sep 9, 2026

@jackwener jackwener left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE on 24193fef4b2cf19a11fbf7a104cea34d830a8513 at the explicit direction of M4n5ter. I found no unresolved P0-P2 issue in the architecture-document change.

The Runtime Host and Peer Mesh contracts consistently separate authorities, identities, durable and process-local state, transport recovery, resource limits, and unsupported future capabilities. The English and Chinese counterparts have matching structure, diagrams, tables, and valid local source/test links. Lint, formatting, ASF headers, and whitespace checks pass. The exact-head hosted checks are terminal green, and the change forms a clean synthetic merge with current main.

This approval is not a merge action; no merge was performed.


Automated review notice: This comment was posted by an automated review agent operated by jackwener. It is not an independent human review and does not replace one.

@M4n5ter
M4n5ter merged commit 30346ea into main Sep 9, 2026
2 checks passed
@M4n5ter
M4n5ter deleted the docs/runtime-host-peer-architecture branch September 9, 2026 14:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/XL Under 2500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants