Prepared Family v1：当前实现说明
范围与状态
本文绑定 agent-python-runtime commit 94fab78cb3f44d14f86d293287269b704b11d383、tree a4291f77e59d680f5ef1bd21e39b323afd5c5ecf。Prepared Family v1 在该 target 中已实现并显式 opt-in；它没有改写既有 RunRequest 或 MechanismSet，也没有形成默认产品路径。
一句话机制
一个 family 拥有一份 Host 验证并复制的 bounded numpycodec input，以及由 exact artifact/profile/ABI 绑定的 image identity。它创建有限个 fresh single-use runner；每个 runner 拥有自己的 Invocation、RunConfig snapshot、workspace 和 terminal state，需要 capability 时再附着自己的 Plan/Broker。两条 lane 复用 input identity/body；只有 private-COW 进一步共享 sealed image/page lineage，private-copy 会逐 Guest 重新 prepare。
Source owners
| 责任 | Source owner / symbols |
|---|---|
| Input validation 与 identity | runtime/engine/wazero/prepared_input.go: PreparedNumpyInput, NewPreparedNumpyInput, PreparedInputIdentity |
| Family identity、mode 与 preparation owner | runtime/engine/wazero/prepared_family.go: PreparedFamily, PreparedFamilyConfig, PrepareNumpyFamily |
| Member state machine | runtime/engine/wazero/prepared_lifecycle.go: preparedFamilyLifecycle, reserve, begin, finish, retire, close |
| Runner creation、Family Close、single-use wrapper 与 terminal record | runtime/engine/wazero/prepared_family_runner.go: NewRunner, PreparedFamily.Close, preparedFamilyRunner.Run, PreparedMemberRecord |
| Per-member Engine/Plan/Broker/workspace attachment | runtime/engine/wazero/prepared_family_runner.go: newMemberRunner; runtime/engine/wazero/engine.go |
| Subagent composition | runtime/engine/wazero/prepared_family_subagent.go: PreparedFamilyRunnerFactory; runtime/subagent/orchestrator.go |
| Binary Host→Guest preparation | runtime/engine/wazero/prepared_guest_transfer.go; guest/src/runtime.c: runtime_prepare_numpy_ndarray; guest/bootstrap/agent_runtime/__init__.py: _prepare_numpy_ndarray |
| Acceptance projection | runtime/engine/wazero/prepared_family_acceptance.go: PreparedFamilyAcceptanceReport, AcceptanceReport |
| Linux physical image | runtime/engine/wazero/cow_runtime_linux.go, cow_memory_linux.go |
Input 与 image boundary
NewPreparedNumpyInput 接受已验证 descriptor/body，复制 body 与 shape，并绑定 exact profile。V1 允许 numpycodec 的 bounded numeric/bool dtype、C-order、little/not-applicable endianness、rank/body limits。Input body 不进入 RunRequest、Broker JSON、trusted Python source、evidence、日志、Guest handle 或 filesystem path。
Family image identity 使用 pysolate.prepared-family-image.v1，绑定：
- artifact/manifest；
- profile ID 与 allowed/available/qualified import roots；
- deterministic profile 或
none； - memory limit pages 与 Guest preparation ABI；
- ndarray name、codec、dtype、shape、order、endianness、bytes、body/input digest。
Consumer timeout、request/response limits、grants、Broker、workspace 与 InvocationRef 刻意不进 image identity；它们逐 member 冻结。
Binary preparation ABI
Host 通过可选 export runtime_prepare_numpy_ndarray 分别写入 canonical descriptor 与 raw body，Guest C bridge 检查 pointer/length，再调用 Python _prepare_numpy_ndarray。Python 重新验证 schema/name/dtype/layout/length/digest，复制到私有 bytearray，并把 C-contiguous ndarray 放入 _prepared_globals。Staging pointer 不保留；重复 preparation 拒绝。
这条 ABI 取代了 historical fanout probe 将 body 编进 trusted Python source 的做法。Old artifact 因缺 export 而 fail closed。Family runner 还拒绝 caller supplied trustedPrepare，避免第二条注入路径。
Physical dispositions
private_copy：portable reference path。Family 保留 immutable Host body，每个 fresh Guest 单独通过 binary ABI prepare。private_cow：Experimental、Linux exact-artifact path。一份 sealed image 为每个 member 建立MAP_PRIVATEmapping；Family 持有 image，child Engine 不得关闭它。ordinary_fresh：mechanism-off control，不附着 family。unsupported：typed fail-closed blocker，不得伪装成 COW。
auto 仅在 exact COW eligibility 完整时选 private_cow，否则选 private_copy。显式 private_cow 失败不 downgrade。Private-copy 与 canonical COW preparation 都建立 _initialize → runtime_init({}) → runtime_prepare_numpy_ndarray 的输入状态；COW consumer 恢复 sealed Guest memory，不再注入 body。
Per-member authority 与 lifecycle
需要 capability 的 member 使用自己的 Plan/Broker；Plan object、Invocation/execution ID 和非空 workspace Ref 在 family lifetime 内唯一。不使用 capability 时 Plan/Broker 同时为空。Broker factory 必须绑定 exact Plan pointer、Plan digest 与 execution identity；内容等价的 Plan 也不能共享 mutable object。CapabilityGrants 等 mutable config 在 attachment 时 deep-copy。
Runner state：
new → running → terminal → closed总 consumer 与 active consumer 都有非零上限；实现硬上限为 1024。总数限制阻止创建更多 runner；active 限制在 Guest 前拒绝本次调用并保留 runner 为 new。真正开始后，Run 只能进入一次，第二次/并发执行在 Guest 前拒绝；success、Guest error、timeout、cancellation 与 trap 都消费 runner。Family Close 在 active member 存在时拒绝；随后使 unstarted runner 进入 closed_unrun，关闭 image/body/runtime resources，并保持 retry-safe/idempotent close。
Terminal record 只携带 family/input、member/Run/Invocation/execution、Plan/grants、physical disposition、outcome 与可选 final workspace digest。它不替代 capability receipt、workspace receipt 或 external reconciliation。
Evidence 与 non-claims
当前 target 有 contract、lifecycle、orchestrator、real-Guest private-copy 和 Linux COW tests；docs/prepared-family-v1.md 记录 deterministic local 与 exact Linux artifact-backed acceptance passed。Checked-in docs/examples/prepared-family-acceptance-v1.json 是 fixture declaration，覆盖三种 array、三类 program、fanout 0/1/2/4 和 terminal cases，但不是运行报告或性能证据。
因此可主张 bounded correctness、fresh-state、private mutation/workspace 和 authority separation。不能主张 arbitrary object family、scheduler、automatic retry、workspace merge、cross-platform COW、zero-copy、natural workload uplift 或 economic benefit。