sandbox-runtime

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sandbox Runtime

Layer: Practice

このSkillは主にConstitutionの Mutable Ownership Safety と Organizational Continuity をruntime boundaryへmaterializeするcurrent Practiceである。

特定sandbox/provider自体を要求するのではなく、taskに必要なfilesystem/process/network/credential/service-state separationのguaranteeを要求する。

実装用mutable workspaceとverification環境を同一視しない。ADR-0020のVerification Executorは、sourceをauthoringしない限りimplementation worker用worktree/sandbox topologyを要求せず、検証対象artifact identityとenvironment ownershipを別contractで扱う。

Layer: 实践

本 Skill 是当前的 Practice，主要将 Constitution 中的 Mutable Ownership Safety 和 Organizational Continuity 具体落实到 runtime boundary。

它并非要求特定的 sandbox/provider，而是要求为 task 提供所需的 filesystem/process/network/credential/service-state separation 保证。

不要将实现用的 mutable workspace 与验证环境等同视。ADR-0020 的 Verification Executor 不会要求 implementation worker 使用 worktree/sandbox topology，除非其对 source 进行 authoring；它通过独立的 contract 处理待验证 artifact 的 identity 与 environment ownership。

Current practice guarantees

当前实践保证

1 implementation worker = 1 isolated workspace/runtime。
mutable runtime stateはworker間で共有しない。
同一内部portは使用してよい。host公開port / preview routeはruntime側で一意化する。
host Docker socket、root-equivalent host capability、master credentialをworkerへ渡さない。
immutable/cacheable stateのみ共有する。
provider差はadapterへ閉じ込め、project semanticsを変えない。
Worktrunkはworkspace/worktree lifecycle adapterであり、sandbox/runtime isolation boundaryとして扱わない。
```
security-audit
```
がtarget-controlled codeを実行する場合も本Skillのnetwork / environment / writable state / resource isolationを満たす。必要controlをenforceできない環境ではhost executionへfallbackせず
```
needs_validation
```
とする。

1 个 implementation worker = 1 个隔离的 workspace/runtime。
mutable runtime state 不在 worker 之间共享。
可以使用相同的内部 port。host 公开的 port/preview route 由 runtime 侧唯一化。
不向 worker 传递 host Docker socket、root-equivalent host capability 或 master credential。
仅共享 immutable/cacheable state。
将 provider 差异封闭在 adapter 内，不改变 project semantics。
Worktrunk 是 workspace/worktree lifecycle adapter，不应将其视为 sandbox/runtime isolation boundary。
即使
```
security-audit
```
执行 target-controlled code，本 Skill 的 network/environment/writable state/resource isolation 要求仍然适用。在无法强制实施必要 control 的环境中，不得 fallback 至 host execution，而应标记为
```
needs_validation
```
。

Isolate

隔离范围

最低限:

repository checkout
process boundary
network / port mapping
writable filesystem
DB / Redis / queue
application local state
test artifacts
mutable build output

最低要求：

repository checkout
process boundary
network/port mapping
writable filesystem
DB/Redis/queue
application local state
test artifacts
mutable build output

macOS

Apple Silicon
```
arm64
```
を第一級targetとして扱う。
binary / dependency / container imageのarm64対応を確認する。
x86_64 emulationを暗黙前提にしない。
portable Web/backend taskは原則Linux sandboxで実行する。
Apple-native toolingが必要なtaskだけmacOS-native workerを許可する。
Docker Desktopを必須にしない。

将 Apple Silicon
```
arm64
```
作为第一优先 target。
确认 binary/dependency/container image 对 arm64 的支持情况。
不应隐式依赖 x86_64 emulation。
可移植的 Web/backend task 原则上在 Linux sandbox 中执行。
仅当 task 必须使用 Apple-native tooling 时，才允许使用 macOS-native worker。
不强制要求 Docker Desktop。

Windows + WSL2

Linux-oriented repoはWSL Linux filesystemを優先する。
```
/mnt/c
```
等を高頻度build/watchの標準workspaceにしない。
WSL自体をworker isolationとみなさない。
permission / symlink / executable bit / line ending差を検証する。
port forwardingはSupervisor/runtime側で抽象化する。
WSL/Linuxでlocal worktreeを複数扱う場合は
```
worktree-workflow
```
Skillを適用し、worktree pathはLinux filesystemを優先する。

对于面向 Linux 的 repo，优先使用 WSL Linux filesystem。
不应将
```
/mnt/c
```
等路径作为高频 build/watch 的标准 workspace。
不应将 WSL 本身视为 worker isolation。
验证 permission/symlink/executable bit/line ending 差异。
port forwarding 应在 Supervisor/runtime 侧进行抽象。
在 WSL/Linux 中处理多个 local worktree 时，应应用
```
worktree-workflow
```
Skill，并优先将 worktree path 放在 Linux filesystem 上。

Worktrunk integration

Worktrunk 集成

WSL/Linuxのlocal workspace materializationではWorktrunkをpreferred frontendとしてよい。

shared project hookはproject-local
```
.config/wt.toml
```
へ置く。
shared hostへ公開するdev serverは、実際のframework/runtimeが許すport overrideへ
```
{{ branch | hash_port }}
```
を接続してdeterministically割り当てる。
```
hash_port
```
自体をuniqueness proofとせず、startup時のbind conflictを検出する。
long-running local processは適切なら
```
wt step tether -- <command>
```
でworktree lifecycleへ結び付ける。
container/sandbox内部portは同一値のままでよく、
```
hash_port
```
は必要なhost-published portへ適用する。
DB / Redis / queue / socket / container name等のmutable stateは別途runtime adapterで一意化する。必要ならWorktrunkのdeterministic template valueをidentifierへ利用してよい。
```
wt merge main
```
等をGitHub delivery policyの代替integration pathとして使わない。

詳細な操作は

worktree-workflow

Skillに置き、このSkillではisolation semanticsをcanonicalに保つ。

在 WSL/Linux 中实现 local workspace materialization 时，可以优先使用 Worktrunk 作为 frontend。

将 shared project hook 放在 project-local 的
```
.config/wt.toml
```
中。
对于公开到 shared host 的 dev server，应将
```
{{ branch | hash_port }}
```
连接到 framework/runtime 实际允许的 port override，以 deterministic 方式分配。不要将
```
hash_port
```
本身视为 uniqueness proof，而应在 startup 时检测 bind conflict。
如有必要，应通过
```
wt step tether -- <command>
```
将 long-running local process 绑定到 worktree lifecycle。
container/sandbox 内部 port 可以保持相同值，仅将
```
hash_port
```
应用于需要公开到 host 的 port。
DB/Redis/queue/socket/container name 等 mutable state 应由独立的 runtime adapter 进行唯一化。必要时，可以将 Worktrunk 的 deterministic template value 用于 identifier。
不要将
```
wt merge main
```
等操作用作 GitHub delivery policy 的替代 integration path。

详细操作应放在

worktree-workflow

Skill 中，本 Skill 则负责将 isolation semantics 保持为 canonical。

Verification-only native environments

仅用于验证的原生环境

Windows native / macOS native / GUI application / physical device / installed application / CI等でworktreeを作れない、または作ることが検証対象を歪める場合は、verification-only executorとして扱える。

優先materialization:

immutable package / installed artifact / image digest / deployment revision
clean dedicated checkout
disposable clone / snapshot
unavoidable場合のみexclusive leaseを取ったsingleton checkout

verification executorは最低限、candidate identity、environment identity、procedure、result、evidence artifact、source mutation有無を記録する。

singleton environmentはparallelizeを要求しない。exclusive lease / serialization / queue等でMutable Ownership Safetyを満たす。

unexpectedなtracked source/config mutationが生じた場合、そのままcurrent candidateのverification evidenceとして採用しない。expected behaviorとしてmutation自体を検証する場合を除き、clean candidateで再実行する。

verification中にfix実装へ移る場合は、新しいmutable Worker attemptとして切り替える。

如果无法为 Windows native、macOS native、GUI application、physical device、installed application 或 CI 等环境创建 worktree，或者创建 worktree 会扭曲验证对象，则可以将其作为 verification-only executor 处理。

materialization 的优先顺序：

immutable package/installed artifact/image digest/deployment revision
clean dedicated checkout
disposable clone/snapshot
仅在不可避免时，使用取得 exclusive lease 的 singleton checkout

verification executor 至少需要记录 candidate identity、environment identity、procedure、result、evidence artifact，以及是否发生 source mutation。

singleton environment 不要求支持 parallelize。通过 exclusive lease/serialization/queue 等方式满足 Mutable Ownership Safety。

如果出现意外的 tracked source/config mutation，则不得直接将其作为当前 candidate 的 verification evidence。除非 mutation 本身就是要验证的 expected behavior，否则应在 clean candidate 上重新执行。

如果 verification 期间需要转入 fix 实现，应切换为新的 mutable Worker attempt。

Portability

可移植性

Apple Silicon localとx86_64 CI/remoteが混在する場合、architecture-sensitive dependency install/build/testを検証する。

当 Apple Silicon local 与 x86_64 CI/remote 混合使用时，应验证 architecture-sensitive dependency 的安装、构建和测试过程。

Reproducibility target

可复现性目标

text

clone
-> bootstrap
-> sandbox create
-> dependency install
-> migrate / seed
-> app/test start
-> validation

text

clone
-> bootstrap
-> sandbox create
-> dependency install
-> migrate / seed
-> app/test start
-> validation

Refinement criteria

优化标准

別runtime/provider/native agent environmentへ置換する場合、変更surfaceに必要な次のguaranteeを比較する。

writable mutable state isolation
process/service namespace safety
network policy
credential boundary
resource/lifecycle cleanup
durable result extraction / recovery
snapshotの永続性、suspend / resume、provider喪失時の復旧、remote artifactの耐久性（create / destroyの費用だけで比べない）

同等以上ならprovider implementationは自由に置換できる。単なるworktree分離をruntime isolationのproofとして扱わない。

当替换为其他 runtime/provider/native agent environment 时，应比较变更范围所需的以下 guarantees。

writable mutable state isolation
process/service namespace safety
network policy
credential boundary
resource/lifecycle cleanup
durable result extraction/recovery
snapshot 的持久性、suspend/resume、provider 丢失时的恢复，以及 remote artifact 的耐久性（不能只比较 create/destroy 的成本）

如果新环境达到同等或更高标准，即可自由替换 provider implementation。不要仅凭 worktree separation 就将其视为 runtime isolation 的 proof。