docs(win32-process): point ABI verification to its owner

2026-08-29 04:26:38 +00:00 · 2026-08-20 19:17:03 +08:00
parent 6d9bc90532
commit ff7a5a042c
6 changed files with 26 additions and 6 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-windows-acl/README.md
-README.md: c31f6452815c5629b49c302ebec408da1f0f4803
-README.zh.md: c6a87075875d3424b47121e32d8465a752149c89
+README.md: 91172cc0b2fcab1daceb75f7c02f3eecc679bab1
+README.zh.md: 0e8435e3d1a27a2868f97d6af4ce9e66953e8a26
@@ -62,7 +62,7 @@ The `AclSandbox` class (explicit private `tempDir` + `tempWriteSid`, or `tempDir

 ## Header verification

-All constants, signatures, and struct layouts were verified against the Windows headers on the development machine (MinGW `winnt.h` / `accctrl.h` / `aclapi.h` / `securitybaseapi.h` / `sddl.h` / `processthreadsapi.h` / `fileapi.h` / `namedpipeapi.h` / `synchapi.h` / `winbase.h`) and are cross-checked at runtime by [`verify/abi-probe.cpp`](verify/abi-probe.cpp) (sizes, offsets, enum values, static asserts):
+The sandbox-owned SID, ACL, token, file, and lock constants and layouts were verified against the Windows headers on the development machine (MinGW `winnt.h` / `accctrl.h` / `aclapi.h` / `securitybaseapi.h` / `sddl.h` / `fileapi.h`) and are cross-checked by [`verify/abi-probe.cpp`](verify/abi-probe.cpp). The shared process, stdio, and Job ABI is owned and verified by [`@deepseek-ai/dsh-win32-process`](../../subprocess/win32-process/README.md#header-verification).

 ```sh
 g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp -ladvapi32 && ./abi-probe.exe
@@ -64,7 +64,7 @@ Authenticated Users 在**两种**列表中都不存在——WMI 命名空间安

 ## 头部验证

-所有常量、签名与结构体布局都在开发机上对照 Windows 头文件（MinGW `winnt.h` / `accctrl.h` / `aclapi.h` / `securitybaseapi.h` / `sddl.h` / `processthreadsapi.h` / `fileapi.h` / `namedpipeapi.h` / `synchapi.h` / `winbase.h`）验证过，并在运行时由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp)（大小、偏移、枚举值、静态断言）交叉检查：
+sandbox 自有的 SID、ACL、token、文件与锁常量和布局均已在开发机上对照 Windows 头文件（MinGW `winnt.h` / `accctrl.h` / `aclapi.h` / `securitybaseapi.h` / `sddl.h` / `fileapi.h`）验证，并由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 交叉检查。共享的 process、stdio 与 Job ABI 由 [`@deepseek-ai/dsh-win32-process`](../../subprocess/win32-process/README.md#header-verification) 归属并验证。

 ```sh
 g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp -ladvapi32 && ./abi-probe.exe
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subprocess/win32-process/README.md
-README.md: 0005416bdfac6101090a3dc87defd71e15ec7537
-README.zh.md: 2c505ea5a1ec2fe2a930eca035b8a64ca3d4ba4f
+README.md: fcc6ad9cb5ca99ac55c817ef796c20751efffacc
+README.zh.md: fbf37823b409f743818b1425192070a5c90f3932
@@ -14,6 +14,16 @@ Low-level Win32 process library consumed by the Windows ACL sandbox. It owns the

 The Windows ACL sandbox adds SID, DACL, grant, workspace, and public child policy above these primitives.

+## Header verification
+
+The process, stdio, and Job constants, signatures, and layouts are checked against the MinGW Windows headers by [`verify/abi-probe.cpp`](verify/abi-probe.cpp):
+
+```sh
+g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe
+```
+
+The Koffi struct definitions also assert their sizes at module load, so a header or layout mismatch fails before native process creation.
+
 ## Model Experience

 ### Process primitives
@@ -14,6 +14,16 @@

 Windows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公共 child policy。

+## 头部验证
+
+process、stdio 与 Job 的常量、签名和布局由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 对照 MinGW Windows 头文件检查：
+
+```sh
+g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe
+```
+
+Koffi 结构体定义还会在模块加载时断言自身大小，因此头文件或布局不匹配会在创建 native process 前失败。
+
 ## Model Experience

 ### 进程原语