Skip to content

docs(architecture): reconcile Windows sandbox RFC bilingual pair #5338

Description

@daierenao

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:

  1. 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.
  2. Set counterpart both 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 set counterpart. This PR matches those 6 and closes parity check 8 (links resolve to the counterpart language). It is not a repo-wide metadata mandate.
  3. translation_status stays synced in this PR. The bilingual standard names synced / needs-update / source-only but does not define when synced holds. This PR proposes that synced means semantic parity checks 1–8 pass on the pair. Please confirm that bar; the standard does not already require it.
  4. Align last_verified and body Updated to the PR open date (both files, same day). Do not change the §6.5 heading date 2026-08-24 (preview-slice snapshot).
  5. 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 synced from 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).
  • counterpart missing → 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 roadmap(windows): make Windows a supported platform #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 counterpart present both ways in sibling ./ form.
  • translation_status: synced under the proposed bar (checks 1–8 on the full pair); last_verified and body Updated equal the PR open date.
  • skills/maka-architecture-docs/references/bilingual-standard.md semantic parity checks 1–8 (manual, full pair).
  • npm run check:asf-headers
  • Do not treat check:architecture as 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 fix(windows): let Glob skip nested junctions #3952's Glob / nested-junction contract).
  • Filling §6.3 / §6.4 for line-count parity.
  • Splitting counterpart into a second PR.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions