docs(architecture): reconcile Windows sandbox RFC bilingual pair
@daierenao is already working on this.
Since Sep 15, 2026.
Assessment
This issue has not been assessed yet.
Description
Claim
Part of A16 — Architecture documents (scavenger sweep 2026-09), scoped to one bilingual pair:
docs/architecture/windows-sandbox-rfc-v1.md(source, EN)docs/architecture/windows-sandbox-rfc-v1.zh-CN.md(counterpart)
A16's stated outcome on #4726 is "Reconcile or retire." This slice reconciles; it does not retire. The measured result is not one of the five product-code shapes (two implementations → one, N helpers → one, split a >2000-line module, delete dead code, lower a renderer debt counter). It is a document pair whose published claims and translation_status agree.
Cross-checked against open claims on #4726: A16 is unclaimed (existing claims are A6, T1, A15, A9). Search for "A16" on that thread returns only the area row. This slice does not cover the rest of docs/architecture/ (gitoxide contracts, resume ledger, Host architecture, and unpaired drafts stay on the board).
Serialization: #3952 is open and edits both RFC files (Glob / nested-junction policy; last activity 2026-09-01). This slice does not take that policy. It patches current main. If #3952 merges first, the PR rebases A–D onto it; if this PR merges first, #3952 rebases its RFC hunks.
After this issue is open, a claim comment will be posted on #4726 with the link.
The drift (measured)
At current main, both files declare translation_status: synced and last_verified: 2026-09-04. That status was set from heading lockstep, which is not a semantic check.
| Metric | EN | ZH |
|---|---|---|
| Lines | 546 | 384 |
| H2/H3 headings | 23 | 23 (same numbered outline) |
counterpart |
missing | missing |
| Body "Updated" | 2026-08-18 | 2026-08-18 |
Heading identity is already 1:1. The 546 vs 384 delta is density, not a missing section. The drift is four intra-section claim gaps.
last_verified: 2026-09-04 was set in #4800 (merged 2026-09-07), which marked synced from heading lockstep while the §6.5 close was already missing. Body "Updated: 2026-08-18" is older still.
Both files are linked from packages/runtime/src/sandbox/README.md and must not be retired.
Named ZH omissions (claim-level, not density)
A. EN §6.5 close; ZH stops one sentence earlier:
The lifecycle evidence for cancellation, parent-death, concurrency, process-drain, and residual ACL/state release tracked by W1 (§9) and Phase 4 (#2142) remains release evidence, not an assumption.
The W1 checklist already ticks cancel / parent-death tests in both languages. That is not a substitute: the omitted sentence is the status claim (release evidence, not an assumption).
B. EN §6.5 intro names the packaged Windows 11 x64 AppContainer backend and tracks remaining guarantees with Phase 4 in #2142. ZH intro has neither. (ZH never says Windows 11 anywhere; #2142 appears only in the document header / §1.)
C. EN §6.4: “OS version checks alone are insufficient.” ZH requires a real probe but never states that OS-version-only checks are insufficient. ZH’s implemented parenthetical already says “而非仅凭二进制存在” — that matches EN’s “rather than trusting file presence alone,” which is a different claim.
D. EN §6.5 deferred launcher bullet restates the Current/deferred split: digest already enforced in-broker; Authenticode signature/version deferred with Phase 3. ZH collapses this to “随 Phase 3 签名一并落地的 launcher signature/version 校验”. The split still exists in ZH §6.4; §6.5 alone under-claims.
EN is itself redundant here: §6.4 already states the split, and §6.5 restates it. Copying that restatement into ZH §6.5 is a deliberate choice, not “EN has it so ZH must.” §6.5 is the preview-status ledger reviewers use to see what ships vs what is deferred. A collapsed “随 Phase 3 签名一并落地” bullet under-claims the digest-already-enforced half in that ledger. ZH §6.4 stays dense; the ledger bullet is aligned.
§6.3 / §6.4 Chinese is denser but already carries the same Current vs deferred status tags for the implemented/later-gate parentheticals. This PR will not expand those sections for line-count parity.
The plan (one PR)
Source language stays EN. No AppContainer decision, W2/W3 guarantee, or threat-model change.
Patch only the two RFC files:
- Add ZH claims A–D (wording below). Strength must match EN: A remains “release evidence, not an assumption”; C remains a negation (“insufficient” / 不够); D keeps digest as Current and Authenticode as deferred.
- Set
counterpartboth ways, sibling./form:- EN:
counterpart: ./windows-sandbox-rfc-v1.zh-CN.md - ZH:
counterpart: ./windows-sandbox-rfc-v1.md
The bilingual standard says metadata is optional unless the project adopts it.docs/architecture/has 22 bilingual pairs; 6 already setcounterpart. This PR matches those 6 and closes parity check 8 (links resolve to the counterpart language). It is not a repo-wide metadata mandate.
- EN:
translation_statusstayssyncedin this PR. The bilingual standard namessynced/needs-update/source-onlybut does not define whensyncedholds. This PR proposes thatsyncedmeans semantic parity checks 1–8 pass on the pair. Please confirm that bar; the standard does not already require it.- Align
last_verifiedand body Updated to the PR open date (both files, same day). Do not change the §6.5 heading date2026-08-24(preview-slice snapshot). - Leave the ASF HTML license header block untouched.
Checks 1–8 apply to the whole pair, not to A–D in isolation. A full pass on current main found A–D as the complete claim-level deviations (status / strength / failure-completeness). Remaining quantity, diagram, title, and scope checks already match. If review finds another claim-level gap, it belongs in this PR.
Proposed ZH wording
C — §6.4 first bullet (insert before the implemented parenthetical; parenthetical unchanged):
- readiness 必须在生产 identity/token/Job/desktop/handle/filesystem/offline network 下启动真实 probe;仅凭 OS version check 不够。
B — §6.5 intro (keep existing (#3722) / (#3174) sentences; add Windows 11 x64 and Phase 4 #2142):
首个预览切片——打包的 Windows 11 x64 AppContainer 后端 [#2961](https://github.com/apache/maka/pull/2961) 已于 2026-08-17 合并,强制上述保证的一个子集。本节把文档与已交付代码对齐,使 RFC 不 overclaim:§6.3/§6.4 中尚未强制的保证在此显式标为后续门禁。标注 `(#3722)` 的条目(Runtime Host 父进程 wait handle、64 次 soak、恶意 child 矩阵)与标注 `(#3174)` 的条目(readiness probe 与 private desktop 放置)落在对应后续 PR,而非已合并的 #2961 切片;其余未标注条目由 #2961 当前强制。其余保证已设计但明确作为后续门禁暂缓,由 [#2142](https://github.com/apache/maka/issues/2142) 的 Phase 4 跟踪。
D — §6.5 deferred launcher bullet:
- readiness 时的 launcher signature/version 校验(§6.4)。每次启动的 request digest 已在 broker 内重算并强制;对照打包 metadata 校验 launcher 二进制的 Authenticode signature 与 version,随 Phase 3 签名一并暂缓。
A — §6.5 close (append; do not drop the fail-closed sentence):
暂缓收窄的是 readiness 丰富度与 desktop 层的 defense-in-depth,而非强制边界本身:backend 不可用、identity drift 或启动失败仍然 fail closed,受限 managed profile 也绝不回退到宿主执行。由 W1(§9)与 Phase 4(#2142)跟踪的 cancel、parent-death、并发、process-drain 以及残留 ACL/state 释放的生命周期证据,仍是发布证据,不是假设。
Measured result
- A bilingual pair that claimed
syncedfrom heading lockstep is reconciled to A16's "Reconcile or retire" (reconcile). - Named ZH claim gaps A–D are present in Chinese, at matching strength.
- The §6.5 lifecycle-evidence sentence exists in both languages (0 → 2).
counterpartmissing → present both ways (optional metadata, matching 6 existing pairs, for check 8).- Heading count stays 23 / 23; no new sections; no other
docs/architecture/files.
This is the sweep’s reconcile-a-drifted-counterpart result, not a rename, reformat, or RFC rewrite.
Verification
rg '^#{2,3} 'on both files → 23 headings, same numbered outline.- Chinese §6.5 contains the W1 / Phase 4 lifecycle-evidence sentence.
- Chinese §6.5 intro names Windows 11 x64 and Phase 4 #2142.
- Chinese §6.4 states that OS version checks alone are insufficient (
仅凭 OS version check 不够). - Chinese §6.5 deferred launcher bullet keeps the in-broker digest as Current and Authenticode as deferred.
- YAML
counterpartpresent both ways in sibling./form. translation_status: syncedunder the proposed bar (checks 1–8 on the full pair);last_verifiedand body Updated equal the PR open date.skills/maka-architecture-docs/references/bilingual-standard.mdsemantic parity checks 1–8 (manual, full pair).npm run check:asf-headers- Do not treat
check:architectureas this gate (that is the desktop renderer ratchet).
Non-goals
- Other A16 files.
- Retiring this pair or any other architecture document.
- Expanding RFC policy (including #3952's Glob / nested-junction contract).
- Filling §6.3 / §6.4 for line-count parity.
- Splitting
counterpartinto a second PR.
- Dominant language
- TypeScript
- Stars
- 5.6k
- Forks
- 518
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 684
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from apache/maka
-
Difficulty 1/5 Under an hour Newbie friendliness 92/100
-
Difficulty 4/5 3-5 days Newbie friendliness 58/100
-
Difficulty 3/5 1-2 days Newbie friendliness 65/100
-
Difficulty 5/5 Over a week Newbie friendliness 45/100
-
Desktop: task refresh fails with opaque persistence_failed; the real transcript error is discarded Open
Difficulty 4/5 3-5 days Newbie friendliness 48/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug clawsweeper:linked-pr-open clawsweeper:needs-live-repro clawsweeper:no-new-fix-pr impact:message-loss issue-rating: 🐚 platinum hermit P2 regression
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
fullcalendar/fullcalendar#8106 ·