@botiverse/k-carrier 0.1.7 → 0.2.0

package/docs/prior-art/external-runner-research.md

@@ -0,0 +1,49 @@
+# External installer research
+
+The 2026-09-06 survey asked whether install, self-update and remote upgrade could
+share an external executor without introducing another permanent service.
+These are source-reading observations and K design inferences, not results from
+running those products. Moving upstream links are not a frozen comparison.
+
+## Rustup: a thin bootstrap and replaceable installer
+
+[rustup-init.sh](https://github.com/rust-lang/rustup/blob/main/rustup-init.sh)
+selects a platform download and runs the installer. The shell does not implement
+Rust installation. [Self-update](https://github.com/rust-lang/rustup/blob/main/src/cli/self_update.rs)
+also obtains an installer executable; the helper has a release version and may
+remain until a later invocation cleans it up.
+
+[Unix replacement](https://github.com/rust-lang/rustup/blob/main/src/cli/self_update/unix.rs)
+and [Windows replacement](https://github.com/rust-lang/rustup/blob/main/src/cli/self_update/windows.rs)
+handle different execution/deletion constraints. A different PID alone does not
+prove that an updater can survive stopping a service or replace a running Windows
+executable safely.
+
+**K decision:** share an independently runnable installer across entrypoints.
+Keep its persistent state, runtime, trust and recovery ownership explicit.
+
+## Tailscale: installation and service readiness are separate
+
+The surveyed Linux binary path in
+[clientupdate.go](https://github.com/tailscale/tailscale/blob/main/clientupdate/clientupdate.go)
+attempts a service restart separately and reports when bytes were updated but
+restart failed. Platform/package-specific paths respect the installation owner.
+This observation does not establish whether other paths have rollback.
+
+**K decision:** successful installation is insufficient for service promotion.
+Probe the live process and defer installations owned by another manager.
+
+## Datadog: reuse slots, not a second control plane
+
+The [earlier survey](design-influences.md) informed K's stable/experiment slots.
+The published [Windows installer test interface](https://pkg.go.dev/github.com/DataDog/datadog-agent/test/new-e2e/tests/installer/windows)
+distinguishes direct install from starting, promoting and stopping experiments.
+The follow-up did not verify all current installer internals.
+
+**K decision:** retain the existing transaction, lock, journal and host adapter.
+A disposable runner can use them without a permanent installer service or a
+parallel remote-job database. Recovery and archived receipts remain local.
+
+The resulting [design](../design.md) specifies a built installer, a bounded
+request protocol and an external controller. Product data compatibility,
+platform packaging and remote authorization remain product responsibilities.

package/docs/reference.md

@@ -0,0 +1,209 @@
+# K reference
+
+Normative wire formats, exit codes, budgets and on-disk layout. This document
+is a contract: it states what K does and requires, not why. For the
+reasoning, read the [design](design.md); for a narrative, the
+[guide](guide.md).
+
+## Protocol v1
+
+One JSON request on stdin, one response on stdout, then exit. Logs go to
+stderr. Decoded input is bounded to 16,384 JavaScript string code units.
+Unknown fields, actions or protocol versions, invalid ids or targets, and a
+nonboolean `consented` are rejected before the adapter factory runs.
+
+Request ids and target strings are nonempty, trimmed strings of at most 256
+code units.
+
+### Requests
+
+```json
+{"protocolVersion":1,"action":"upgrade","id":"job-123","targetVersion":"2.0.0","consented":true}
+{"protocolVersion":1,"action":"recover"}
+{"protocolVersion":1,"action":"recover","expected":{"id":"job-123","targetVersion":"2.0.0"}}
+{"protocolVersion":1,"action":"status"}
+```
+
+`consented` records approval already obtained by an authenticated caller. It
+is not authorization from an untrusted client. Ownership and compatibility
+checks still apply.
+
+`expected` binds automated recovery to one operation. The binding is checked
+under the lock before any controller action. Missing or mismatched history
+refuses recovery. A completed original operation replays its result even when
+newer work is pending. An operator `recover` without `expected` runs once
+against the current unfinished operation.
+
+### Actions and exit codes
+
+| Action | Effect | Exit code |
+|---|---|---|
+| `upgrade` | Install the exact requested version; a mismatched source result is rejected | 0 promoted or up-to-date; 1 failure or rollback; 2 held; 3 unresolved |
+| `recover` | Settle persisted work under the same lock; never starts a new upgrade | 0 successful or no recorded outcome; 1 recorded failure or rollback; 2 held receipt; 3 unresolved |
+| `status` | Read the current receipt without lifecycle calls | 0 readable, including `genesis`; 1 unreadable |
+
+### Responses
+
+Execution replies carry `protocolVersion`, `action`, `result`, `exitCode`,
+`operation` and `error`. Input rejection or adapter-construction failure may
+return only `protocolVersion`, `result`, `exitCode` and `error`. Termination
+can leave no complete response; inspect persistent state and recover.
+
+`operation.kind` is `observed` (with the operation record), `genesis` (no
+operation recorded) or `unreadable`.
+
+Rules:
+
+- A successful upgrade completion must match the request id and target.
+- Exceptions cannot manufacture a rollback receipt.
+- `status` exit 0 means readable; it does not prove current health.
+- `recover` can return `result: "recovered"` with exit 1 after restoring
+  stable and recording a rolled-back upgrade.
+- A supervisor that cannot settle returns `result: "recovery-required"`, exit
+  3, and a `recoveryFile` path.
+
+## Receipts and retries
+
+`operation.json` holds the current operation. Before starting another, K
+archives a terminal receipt at `receipts/<sha256(operation-id)>.json` under
+the same lock. Archived receipts have no automatic garbage collection.
+
+- An id binds to one target. A same-id terminal retry returns the current or
+  archived result without repeating lifecycle effects; a different target for
+  the same id is rejected.
+- Recovery settles the interrupted operation, so retrying its id returns
+  that outcome.
+- A new attempt, including one after a policy hold, needs a new id.
+- Replayed results are historical, not live observations.
+- Receipt retention is independent of transport delivery.
+- Unreadable records refuse operations; missing history cannot be
+  reconstructed.
+- `status` reads the current receipt only. There is no by-id status or
+  archive-list action.
+
+## Supervisor budgets
+
+| Budget | Default | Option |
+|---|---|---|
+| Worker execution | 10 minutes | `executionTimeoutMs` |
+| Each recovery attempt | 2 minutes | `recoveryTimeoutMs` |
+| Recovery attempts | 2 | `recoveryAttempts` (0 to 10) |
+| Total | execution + 2 × recovery (14 minutes) | `totalTimeoutMs` |
+| Exit observation after termination | 1 second | fixed |
+
+All budgets are positive integers. Artifact acquisition has separate transfer
+budgets derived from the artifact size (`artifactTransferPolicy`). An
+unconfirmed worker exit forbids takeover. Exhaustion preserves state and
+returns exit 3 with a recovery file; it never reports success.
+
+## Engine host-call budget
+
+Every host call, including fence, readback, resume and recovery, has a
+positive budget, default 120 seconds (`hostCallBudgetMs`). A call whose
+effect is uncertain raises `HostCallUncertain`; the worker retains its lock
+until it exits. Bundled workers exit after flushing their response. An
+in-process caller that receives `HostCallUncertain` must also exit rather
+than reuse that worker.
+
+## Command controller protocol
+
+`createCommandHost({stateDir, command, timeoutMs?})` runs an external
+controller via argv, without a shell.
+
+Request on stdin:
+
+```json
+{"protocolVersion":1,"action":"fence"}
+{"protocolVersion":1,"action":"quiesce"}
+{"protocolVersion":1,"action":"stop","slot":"stable","artifactPath":"<stateDir>/slots/stable/artifact.bin"}
+{"protocolVersion":1,"action":"start","slot":"experiment","artifactPath":"<stateDir>/slots/experiment/artifact.bin"}
+{"protocolVersion":1,"action":"probe"}
+{"protocolVersion":1,"action":"resume"}
+```
+
+Response on stdout:
+
+```json
+{"protocolVersion":1,"ok":true}
+{"protocolVersion":1,"ok":true,"evidence":{"version":"2.0.0","pid":4242,"startId":"..."}}
+```
+
+Rules:
+
+- Output is bounded to 64 KiB. Each call has a positive timeout, default 30
+  seconds.
+- A controller must do nothing without a complete request.
+- `probe` evidence must come from one live service instance. The controller
+  process's own pid is invalid evidence.
+- Reported errors exclude arbitrary stderr.
+- Before delivering a command, the host durably records the controller pid in
+  a unique file under `controllers/`. Recovery waits for recorded controllers
+  to exit, then calls `fence`. Failure or timeout there prevents lifecycle
+  replay. The recorded pid is never used to kill an arbitrary process; pid
+  reuse or inaccessible identity yields a conservative unresolved result.
+- `fence` acknowledgement is a product contract. K cannot infer it from
+  process exit. A fire-and-forget `stop` cannot establish termination.
+
+## Lock protocol
+
+`upgrade.lock` has one live owner per state directory. Unique process-owned
+contender entries serialize creation and reclamation, including the
+partial-write window. Only entries of provably dead owners are reclaimed. Pid
+reuse conservatively refuses acquisition; age never proves that a live owner
+is dead. The protocol requires local atomic file creation and coherent
+directory reads. It is not a distributed or NFS lock.
+
+## State directory layout
+
+```text
+<stateDir>/
+  upgrade.lock            live owner
+  upgrade.lock.claims/    contender entries
+  journal.jsonl           append-only write-ahead phase record, fsync'd per line
+  operation.json          current operation receipt
+  receipts/<sha256(id)>.json
+  slots/stable/artifact.bin
+  slots/stable/VERSION
+  slots/experiment/artifact.bin
+  slots/experiment/VERSION
+  incoming/               staging for verified downloads before slot placement
+  controllers/            recorded controller pids
+```
+
+Each slot holds one `artifact.bin` and its `VERSION`. Package layouts and
+additional install hooks need a product contract. Application data belongs
+outside the slots. `status` reads `operation.json` without taking the lock.
+
+Journal entries are `{seq, timestampMs, intent, detail}`. The `handing-over`
+entry's `detail.priorStartId` records the incarnation probed before the
+upgrade touched anything; it is absent when nothing was live. Renames and
+journal appends fsync the containing directory on POSIX. Slot publication
+also syncs the copied artifact, VERSION file and staging directory first.
+A failed directory sync stops the operation. Windows directory sync is a
+no-op and provides no equivalent power-loss durability guarantee.
+
+## Supervisor scratch layout
+
+```text
+<scratchDir>/k-runner-<random>/
+  runner.mjs | runner.bin   verified runner (mode 0700)
+  recovery.json             invocation descriptor: file, interpreter, sha256, size, recover request
+```
+
+`recovery.json` is an invocation descriptor, not a transaction log. It is
+removed after settlement and retained on an unresolved result.
+`resumeRunner(path)` re-verifies the runner against the recorded hash before
+executing it.
+
+## Release metadata
+
+```json
+{"version":"2.0.0","url":"https://.../service","sha256":"<hex>","size":123456,
+ "gzip":{"url":"https://.../service.gz","sha256":"<hex>","size":45678}}
+```
+
+`sha256` and `size` always describe the installed bytes. When `gzip` is
+present K downloads and verifies the compressed object, bounds
+decompression, then verifies the canonical size and hash. Failure of a
+selected gzip object is terminal; K does not fall back to the canonical URL.
+Resume offsets refer to the compressed object.

package/docs/test-plan.md

@@ -1,100 +1,97 @@
-# K (k-carrier) 测试计划 v1
+# Test plan
 
-> 跑在 `harness-design.md` 设计的测试框架上；harness 先于功能层（executable-spec 顺序），本计划的每颗齿都进 harness 的 teeth 注册表。
+Use this plan to validate the [external runner design](design.md). The
+[harness guide](harness-design.md) explains test structure and fault coverage.
 
-对应 design v1.2 §3 的教义，这里是**可执行计划**：按里程碑排、每格给"测什么 / 怎么算过 / 必须会红的例子(must-red)"。规矩承自 mutation-runner 契约：**每颗齿声明时同时声明它的 must-red；全绿或全红都不发结论；先跑已知红/已知绿自验，harness 自己不合格不准验别人。**
+## Run the checks
 
-里程碑与 profile 绑定：**每个里程碑的出口 = 对应 example demo 变绿**（没绿 demo 就没那档的支持 claim）。
+Node 24 and the repository's pinned pnpm are required.
 
----
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+pnpm test:runner
+node harness/src/cli.ts --list
+node harness/src/cli.ts sim
+node harness/src/cli.ts sim --seed 42 --json
+```
 
-## M0 — harness 自举（先于一切功能层）
+`pnpm check` includes typechecking, lint, ratchets and all Node tests.
+`test:runner` is a focused alternative when iterating on the external boundary,
+not an extra requirement after the full suite. `--list` lists registered harness
+checks; protocol and real-runner Node tests also contribute coverage.
 
-| 测什么 | 怎么算过 | must-red |
-|---|---|---|
-| fake-host（实现 HostAdapter 的最小假宿主，带可注入故障开关） | 五方法可被编排调用、故障开关能让任一方法定点失败 | 关掉故障开关注入 ⇒ 对应齿必须转绿（证明齿测的是故障不是常态） |
-| fake 静态 server（manifest+工件，认 Range，可篡改） | 正常链路可走通 | 篡改任一字节 ⇒ 下游校验齿红 |
-| **harness 自验**（mutation 契约 §自验承重墙） | 内置已知红/已知绿样例各≥1 + **1 个对抗样例**（结构过 fixture、违真 oracle） | 对抗样例被判 EFFECTIVE ⇒ harness 不上线 |
-| profile 分档执行器 | `--profile swap|daemon|managed` 只跑该档齿集 | cli 档误跑 L2 齿 ⇒ 计划红（档界齿） |
-
-## M1 — L1 事务 + L0 工件（出口：`examples/swap-tool` 绿 = cli 档成立）
-
-| 测什么 | 怎么算过 | must-red |
-|---|---|---|
-| 状态机合法迁移 | 7 相全部合法路径逐条走通 | 非法迁移（如 idle→readback）被拒 |
-| **崩溃注入矩阵**（承重） | **迁移边×kill 点由脚本枚举生成**（禁手列）；每点 kill -9 → 重启后 = 恢复 stable 或完成迁移 | 任一点出现双跑（两 incarnation 同活）或砖（起不来）⇒ 红；**journal 写后动作前的窗口必须被覆盖** |
-| journal 性质 | append-only、意图先于动作（WAL）、重放幂等 | 乱序/覆写 journal ⇒ 重放拒绝 |
-| 回滚对称性 | rolled-back 后 stable 完整可跑、experiment 槽清空、原因入 journal | 回滚后 experiment 残留可执行 ⇒ 红 |
-| config 同轨 | 配置 experiment/promote/rollback 走同一状态机 | config 绕过状态机直写 ⇒ 红 |
-| L0 校验+原子换 | sha256 不符拒装；换字节原子（半写不可见）；Windows 运行中自替换 | 篡改工件 ⇒ 拒；swap 中途 kill ⇒ 旧字节完好 |
-| cli 档端到端 | swap-tool demo：升级→下次运行是新版；`held/rolled-back/up-to-date` 四态出口都可构造 | — |
-
-已落地齿以 `k-harness --list` 为准——本文件**不手抄齿名**（手抄清单是 `--list` 的副本，只会漂向'少列一颗'；ratchet 7 只能查'写下来的存在'，查不了'该写的没写'）。逐颗齿（层/档/must-red/定义位置）直接 `k-harness --list`。 本层判据形状：篡改工件 ⇒ 拒装；原子换（半写不可见、中途 kill 旧字节完好）；未知平台/指名版本 ⇒ 拒；cli 档闭环（真升级 → 下次运行新版本 → state promoted）；坏版本 ⇒ 自动回滚 + 旧可用 + experiment 清空；下载中途死 ⇒ Range 续传 + 全量验证。**下载层 8 洞**（L0 接入方挖出，每洞一齿）：deadline **竞速**而非仅信号（注入不理会 AbortSignal 的 fetch 也必须超时）；Rosetta 下 platform key **问硬件**（x64 Node 在 arm64 硬件选 arm64 target，探针只在 darwin+x64 被问）；无 resumeDir 进度也必须动（单调收尾到全量）；无 body 响应**两臂**（内存 + resume）都报 typed "no readable body"、绝不当作空前缀；静默被限界不是总时长（慢而正常存活、卡死点名 stall）；主动放弃的 stall 是 typed DOWNLOAD_FAILED 点名原因；mid-body 的 stall 说 mid-body。
-
-## M2 — L0.5 供应链：**不做**
-
-L0.5 已于 2026-08-06 移除（决定：不支持签名）。K 只验完整性（sha256 +
-size），不验来源真实性；原两级签名链、`m2.*` 四颗齿与 harness 的测试密钥链一并
-删除。留一个没人接的签名接口比没有更糟——接入方会以为来路已经有人管了。理由，
-以及它与 OS 代码签名的区别，见 `docs/design-v1.md` §L0.5。
-
-**防回滚不在这层**：manifest 版本低于当前且非 pinned ⇒ 默认拒，这是 L0 的
-`source-fails-closed` 管的，与签名无关。
-
-## M3 — L2 生命周期 + L3 收敛（出口：`examples/service-daemon` 绿 = daemon 档成立）
-
-| 测什么 | 怎么算过 | must-red |
-|---|---|---|
-| **HostAdapter 契约一致性套件**（对任意 adapter 可跑，接入方复用） | quiesce↔resume 状态等价（含 **rolled-back 后 resume**）；probe 证据同进程（pid+startId） | resume 后负载状态漂移 ⇒ 红；probe 返回缓存/文件拼的证据 ⇒ 红（换 pid 不换 startId 的假 probe 必须被抓） |
-| 交接顺序 | journal 意图→交接→新进程自证→才清旧，顺序断言 | 颠倒任两步 ⇒ 红 |
-| `binary_at_target` | same-PID probe：version+startId 绑同一 incarnation | 旧进程活着报新版本号 ⇒ 不绿（same-PID 就绪核反假绿） |
-| `host_lifecycle_converged` | 点名面读回一致；**面在 allowlist 才可作证** | 用不可读面（模拟 System Events 类）自称 same-source ⇒ 拒 |
-| **禁投影齿** | version/channel/升级次数灌真值、谓词面造假 ⇒ 必须不绿 | 任一元数据字段能把谓词转绿 ⇒ 红（version⊥state 实测教训） |
-| fail-closed 退役序 | 未过 host_lifecycle_converged 前退旧管理器 ⇒ 拒 + typed HOLD | 强行退役路径存在 ⇒ 红 |
-| ownership 检测 | 受管标记存在 ⇒ `held: managed-elsewhere`（typed、指向管理者） | 受管副本完成自升 ⇒ 红 |
-
-已落地齿以 `k-harness --list` 为准——本文件**不手抄齿名**（手抄清单是 `--list` 的副本，只会漂向'少列一颗'；ratchet 7 只能查'写下来的存在'，查不了'该写的没写'）。逐颗齿（层/档/must-red/定义位置）直接 `k-harness --list`。 本层判据形状：quiesce↔resume 账本逐字节等价（含回滚后 resume）；probe 证据**绑定活化身**（探针说谎/报旧 startId ⇒ 红）；每开关故障关掉齿必须绿；service 升级两种宿主形状（spawn 自起 / respawn 交给 owner）——真停旧、真起新、旧 pid 验证死、新化身 fresh startId；坏版本 ⇒ 旧版**真的拉回来在跑**（不是槽位回退）；卡死 driver ⇒ 宿主调用预算超时 → 锁释放 → successor 凭**证据**（v2 + fresh startId）判交接完成，凭标志不恢复。`host_lifecycle_converged` / 禁投影 / 退役序 → M5 齿。
-
-## M4 — L4 同意与通知
-
-| 测什么 | 怎么算过 | must-red |
-|---|---|---|
-| 策略门 | confirm 未答 ⇒ 零副作用；notify-only ⇒ 只通知不动 | confirm 前有任何盘面写 ⇒ 红 |
-| **通知可验齿**（Hipp 判据原样） | 构造真实失败（迁移写失败/readback 不一致）⇒ sink **真收到**结构化事件 | 删通知调用 ⇒ 此齿必须红；"代码调用了通知"但 sink 没收到 ⇒ 红 |
-
-已落地齿以 `k-harness --list` 为准——本文件**不手抄齿名**（手抄清单是 `--list` 的副本，只会漂向'少列一颗'；ratchet 7 只能查'写下来的存在'，查不了'该写的没写'）。逐颗齿（层/档/must-red/定义位置）直接 `k-harness --list`。 本层判据形状：confirm 未答 ⇒ **磁盘零副作用**（无 journal/slots/incoming，不是"没 promote"是"没 staged"）；同意只装**当初同意的那个版本**（中途服务器换版 ⇒ 拒装，不装"当前版"）；notify-only 通知带**真能装的那个版本** + 零副作用。
-
-## M5 — platform 适配器 + managed 档（出口：`examples/hosted-service` 绿）
-
-| 测什么 | 怎么算过 | must-red |
-|---|---|---|
-| mac/linux/windows 适配器 | 各平台读回面 allowlist 注册齐 + CI 矩阵跑（linux 真跑；mac/win 至少接口级+Testbed 真机轮） | 未注册面被引用 ⇒ 拒 |
-| managed 端到端 | hosted-service demo：带活"会话"的完整升级→会话保留断言→回滚路径同样保留 | 升级后会话丢失/回滚后会话丢失 ⇒ 红 |
-| ownership 迁移场景 | **DEFERRED（v0 只假设官方 installer 安装，不做 deb/RPM 接管）**——PM 装的副本走 ownership 检测 → `held: managed-elsewhere` 即为正确终态（有齿，M3）；接管(adopt)留给将来需要时再立项 | —（deferred） |
-
-已落地齿以 `k-harness --list` 为准——本文件**不手抄齿名**（手抄清单是 `--list` 的副本，只会漂向'少列一颗'；ratchet 7 只能查'写下来的存在'，查不了'该写的没写'）。逐颗齿（层/档/must-red/定义位置）直接 `k-harness --list`。 本层判据形状：**面在 allowlist 才可作证**（未注册面被引用 ⇒ typed UNREGISTERED_SURFACE 拒）；读回新工件路径才 promote（读回旧路径仍 promote ⇒ 红）；**禁投影**——版本串/元数据永远不能绿收敛谓词；**退役序**——未过收敛前 `retireLegacyManager()` 是 typed HOLD（无条件退役 ⇒ 红）。`ConvergenceReport.hostLifecycleConverged` 为 `PredicateResult | null`——**未声明面 = null = 从未被观测 = 不等于通过**（沉默不能当证据花）。
-
-## M6 — L5 drive（可选层，最后）
+## Acceptance criteria
 
-| 测什么 | 怎么算过 | must-red |
+| Area | Required behavior | Failure that must be detected |
 |---|---|---|
-| 远程命令过策略门 | drive 的 stage/promote/rollback 全部经 L4 | drive 绕过 confirm 直接动 ⇒ 红（设备主人永远赢） |
-| 状态上报 | {stable, experiment, 两谓词, 策略} 与本地读回一致 | 上报值可与本地不一致 ⇒ 红 |
-| provenance journal | forward-only 记 reconcile 来路；**"已记录"与 NOT_OBSERVED 机制上不可合并** | 存量机被计入"已记录" ⇒ 红 |
-
-**已落地齿**（三包全合，main 296 绿 / 56 齿）：以 `k-harness --list` 为准，本文件不手抄（手抄是 `--list` 的副本，只会漂向少列一颗）。本层判据形状：
-- provenance：journal **三态** genesis/observed/unreadable（只有 ENOENT 是 genesis；unreadable 上 append 拒——截断视图绝不能重发 seq）；记录 {who, carrier, when, version} **写前**（回滚的 reconcile 也留痕，证明写前）；聚合把 genesis 与 NOT_OBSERVED 机械分离（"没数据"≠"没记录"）。
-- status：机器自报是**读回不是发明**；谓词带**版本戳 join key**（真结论贴错版本比造假更难看出）；跨重启持久化（"观测过、只是我重启了"≠"从没观测过"）；读不了 ≠ 从没有（第三态）。
-- drive + 政策门：服务器下发的命令和本地升级走**同一套门**；**ownership 门画在动作性质上**——settle 在飞事务永远允许（在飞 + ownership 翻转必须收敛，不许 held——held 在开了头的机器上是砖），只有"休息态 + managed-elsewhere"的新改装才 typed held（三个终态 idle/promoted/rolled-back 都断言）；已 promote 版本的 push-rollback 在 confirm 下必须 HOLD（安全方向是字节安全不是权威）；K 自己的 in-transaction 自动回滚**绝不问同意**（配对互相控制）。
-
-## 跨里程碑（一直在跑）
-
-- **跨版本矩阵**：`STATE_FORMAT_VERSION` 升档后旧 core 读新状态 ⇒ fail-closed 拒 + 指引；新 core 收养旧布局 ⇒ 无损；混合窗口显式建模。
-- **mutation-runner**（Lincan 工具就绪即接）：对本计划全部齿跑变异；换说法+整段删两变体默认；杀不掉先排除"没杀对"再删守卫。
-- **断言纪律标注**：每个测试文件头标 `@invariant` 或 `@baseline(failure-condition: ...)`；CI 检查无标注的 implementation-locking 断言（OS-supervisor 退役设计 二分的机械化）。
-- **真机轮**（Testbed）：每里程碑收口跑一轮真机抽样；个人真机仅 consent 后读回抽样。
-- **DST**（§1.45，已实现）：`k-harness sim` 在 PR/profile 门跑固定 smoke seeds；`DST Nightly` 从 workflow run id 起跑 50,000 个顺序 seed。每个 journal/slot/host/predicate effect 后跑共享 invariant；失败自动留下 seed + transcript hash + `k-harness sim --seed X --json` 重放命令，并进入失败语料库后转成枚举矩阵固定格。
-- **时间戳锚定断言**（借 Datadog）：scenario receipt 的事件断言一律"标记之后发生了 X"（取 marker → assert-since），防旧事件/上一场景残留冒充新证据。
-
-## 完成定义
-计划本身的验收 = **三个 example demo 全绿 + M0 harness 自验含对抗样例 + 崩溃矩阵零人工枚举**。任何"支持 X"的 README claim 若无对应绿齿，按"没绿 demo 就没 claim"规则视为未支持。
+| Runner acquisition | Verify runner size/hash before execution; preserve exit result and clean scratch code | Corrupt runner executes or worker failure becomes success |
+| Request boundary | Validate wire version, fields, id, target and consent before loading the adapter | Invalid input reaches trusted product code |
+| Ownership and policy | New upgrades respect installation owner, approved target and compatibility | Another manager's install is changed or the selected version changes after consent |
+| Product acquisition | Verify exact target bytes; bound stalled transfers and validate resumed content | Corrupt, truncated or mismatched bytes reach staging |
+| Transaction | Journal intent before effects; serialize operations; retain a recoverable stable slot | Conflicting writers, illegal transitions or loss of the fallback |
+| Service transition | Stop old instance, start candidate, check live identity/version and declared lifecycle surfaces | Cached evidence, stale instance or wrong target authorizes promotion |
+| Failure recovery | Roll back before durable promote intent; replay commit after it | A live candidate alone is treated as a committed transaction |
+| Retry and receipts | Same id/target replays the recorded result; different target is rejected | Retry repeats lifecycle effects or rewrites an earlier result |
+| Controller boundary | Enforce call budgets and validate response shape | Hung/failed command or malformed probe reports success |
+| Workloads and data | Test the product's promised quiesce/resume and migration behavior | Rollback restores bytes but loses promised workload state |
+| Observation | Preserve unreadable/absent/observed distinctions; report actual outcome | Missing data becomes success, or historical success is presented as current health |
+
+The real-runner suite builds a runner and controls a separate service with no K
+import. It covers successful upgrade, wrong-version rollback, concurrent-worker
+refusal, worker death between stop and start, offline recovery and receipt replay.
+Generated crash cases and seeded simulation cover mechanism-level interleavings.
+Neither establishes exhaustive OS failure or physical power-cut coverage.
+
+## Transaction completion release gate
+
+The Linux process tests in `core/src/launcher/supervise.test.ts` exercise these
+cases with a built worker and live service. `core/src/txn/lock.test.ts` races eight
+real processes against a stale lock; engine tests cover every recovery call budget.
+Whole-invocation loss is simulated by killing supervisor and worker, not by a
+physical power cut. Product OS startup triggers remain separate acceptance.
+
+| Scenario | Required result |
+|---|---|
+| Worker exits without a durable outcome | Supervisor invokes recovery and returns the settled result, not launch success |
+| Upgrade or recovery call hangs | Bounded execution; fence outstanding effects before any replacement worker |
+| Worker dies but a controller action survives | No takeover until the remaining writer is stopped or safely fenced |
+| Another installer starts during recovery | One state writer; original operation stays bound across retries |
+| A newer operation completes before the old supervisor resumes | Old supervisor reads/replays its own result and never recovers or mutates the newer operation |
+| Recovery repeatedly fails | Finite attempts and elapsed time; explicit unresolved result, retained state and executable recovery path |
+| Installer starts with unfinished work | Settle it before accepting new work; do not silently retry the failed target |
+| Crash during terminal reporting or cleanup | Recorded result is replayable; cleanup cannot erase required recovery state |
+| Whole machine or supervisor stops | Next installer invocation restores consistency; product OS startup trigger tested separately |
+
+Use real worker/controller processes for timeout and takeover cases, including
+late effects and competing invocations. Keep generated journal-fault tests for
+transaction ordering. Run both successful settlement and deliberately failed
+recovery so an implementation that always returns success cannot pass.
+
+## Maintaining test quality
+
+- Pair success cases with failures that exercise the intended boundary.
+- Keep check registrations and their known-green/known-red tests aligned.
+- Test process identity and termination using real processes where those are the claim.
+- Keep fixtures isolated and clean up servers, child processes and temporary state.
+- Use `pnpm ratchet` to check prohibited core shortcuts, assertion declarations,
+  registered-check coverage and cited source paths.
+
+For larger deterministic runs, use
+`node harness/src/cli.ts sim --start-seed 1 --seeds 50000`.
+The [nightly workflow](../.github/workflows/dst-nightly.yml) runs an expanded seed
+set and retains failures in `.k-harness/sim-failures.json`. Replay the reported
+seed before turning a discovered failure into a fixed regression case.
+
+## Product and platform acceptance
+
+The [CI workflow](../.github/workflows/ci.yml) gates Linux and macOS checks;
+Windows is informational while the harness port remains incomplete. A green
+framework suite does not certify a product's platform support.
+
+Before shipping an installer, test its actual packaging, installation ownership,
+first-install baseline, running-service upgrade, bad-candidate rollback, recovery
+while offline, workload/data preservation, and survival outside the application's
+service unit. Verify cloud reconnection separately if the product promises it.
+K does not supply a universal fresh-install procedure, a signed distribution
+service, reversible data migrations or automatic recovery after a machine reboot.

package/harness/src/adapter/releaseKnob.ts

@@ -9,7 +9,7 @@
 import assert from "node:assert/strict";
 import { type ToothContext } from "../teeth/registry.ts";
 import { serveRelease } from "../artifact/m1.ts";
-import { PLAIN_DAEMON_SOURCE } from "../../../examples/service-daemon/source.ts";
+import { PLAIN_DAEMON_SOURCE } from "../fixtures/serviceSource.ts";
 import {
   makeUpgrader,
   releaseSourceFor,

package/harness/src/adapter/serviceChecks.ts

@@ -6,7 +6,7 @@
  * HostAdapter responsibilities + the app-declared lifecycle surfaces — no
  * test backdoors (transparency §1.8).
  *
- * These drive createUpgrader in-process (the library plane) against the
+ * These drive createRunner in-process (the library plane) against the
  * adapter's host + a real fake-server release.
  *
  * The release is the ADOPTER'S app when they supply `releaseSource`, and the
@@ -21,7 +21,7 @@
 import assert from "node:assert/strict";
 import * as path from "node:path";
 import { type ToothContext } from "../teeth/registry.ts";
-import { createUpgrader } from "../../../core/src/createUpgrader.ts";
+import { createRunner } from "../../../core/src/createRunner.ts";
 import { staticManifestSource } from "../../../core/src/artifact/staticManifestSource.ts";
 import type { HostAdapter } from "../../../core/src/lifecycle/hostAdapter.ts";
 import type { HostDriver } from "../fake-host/inproc.ts";
@@ -29,7 +29,7 @@ import type { ReadbackSurface } from "../../../core/src/converge/predicates.ts";
 import { slotArtifactPath } from "../../../core/src/txn/fileEffects.ts";
 import { processAlive } from "../fake-host/daemon.ts";
 import { serveRelease } from "../artifact/m1.ts";
-import { PLAIN_DAEMON_SOURCE } from "../../../examples/service-daemon/source.ts";
+import { PLAIN_DAEMON_SOURCE } from "../fixtures/serviceSource.ts";
 
 /** The adopter module's factory contract for the service tier. */
 export type ServiceAdapterFactory = (stateDir: string) => HostDriver & {
@@ -59,7 +59,7 @@ export function releaseSourceFor(adapter: { releaseSource?: () => string }): str
 }
 
 export function makeUpgrader(ctx: ToothContext, adapter: HostAdapter, baseUrl: string, surfaces?: ReadbackSurface[]) {
-  const opts: import("../../../core/src/createUpgrader.ts").CreateUpgraderOptions = {
+  const opts: import("../../../core/src/createRunner.ts").RunnerOptions = {
     host: adapter,
     source: staticManifestSource({ baseUrl }),
     policy: "auto",
@@ -67,7 +67,7 @@ export function makeUpgrader(ctx: ToothContext, adapter: HostAdapter, baseUrl: s
     stateDir: stateDir(ctx),
   };
   if (surfaces !== undefined) opts.lifecycleSurfaces = surfaces;
-  return createUpgrader(opts);
+  return createRunner(opts);
 }
 
 /** The running successor's evidence, read through the adapter's probe. */

package/harness/src/artifact/m1.ts

@@ -1,6 +1,6 @@
 /**
  * M1 exit checks — the swap-tool demo runs a REAL upgrade through core's
- * Upgrader (createUpgrader facade): end-to-end promotion with state
+ * Upgrader (createRunner facade): end-to-end promotion with state
  * assertions read via upgrader.state() (never internal files), and
  * automatic rollback of a version that fails to start.
  */
@@ -14,18 +14,18 @@ import { currentPlatformKey } from "../../../core/src/artifact/staticManifestSou
 import { FakeServer } from "../fake-server/server.ts";
 import { ArtifactFactory } from "../artifact-factory/factory.ts";
 import { runCommand } from "../artifact-factory/run.ts";
-import { CLI_TOOL_SOURCE } from "../../../examples/swap-tool/source.ts";
+import { CLI_TOOL_SOURCE } from "../fixtures/cliToolSource.ts";
 
-/** The swap-tool demo's @botiverse/k-carrier wiring (createUpgrader module URL). */
-export function coreUpgraderUrl(): string {
-  return pathToFileURL(path.join(import.meta.dirname, "../../../core/src/createUpgrader.ts")).href;
+/** The swap-tool demo's @botiverse/k-carrier wiring (createRunner module URL). */
+export function runnerFactoryUrl(): string {
+  return pathToFileURL(path.join(import.meta.dirname, "../../../core/src/createRunner.ts")).href;
 }
 
 export function swapToolEnv(ctx: ToothContext, baseUrl: string): Record<string, string> {
   return {
     K_RELEASE_BASE: baseUrl,
     K_STATE_DIR: path.join(ctx.sandboxDir, "state"),
-    K_CORE_UPGRADER: coreUpgraderUrl(),
+    K_CORE_UPGRADER: runnerFactoryUrl(),
   };
 }
 
@@ -62,9 +62,9 @@ export async function buildSwapTool(ctx: ToothContext): Promise<string> {
 export async function readState(env: Record<string, string>): Promise<TxnState> {
   const coreSrcUrl = new URL(".", env.K_CORE_UPGRADER).href;
   const script = [
-    `const { createUpgrader } = await import(${JSON.stringify(env.K_CORE_UPGRADER)});`,
+    `const { createRunner } = await import(${JSON.stringify(env.K_CORE_UPGRADER)});`,
     `const { staticManifestSource } = await import(${JSON.stringify(new URL("artifact/staticManifestSource.ts", coreSrcUrl).href)});`,
-    `const u = createUpgrader({`,
+    `const u = createRunner({`,
     `  host: { quiesce: async () => {}, stop: async () => {}, start: async () => {}, healthProbe: async () => ({ version: "x", pid: 0, startId: "x" }), resume: async () => {} },`,
     `  source: staticManifestSource({ baseUrl: ${JSON.stringify("http://127.0.0.1:1")} }),`,
     `  policy: "auto", notificationSink: async () => {},`,

package/harness/src/artifact/m1Resume.ts

@@ -13,7 +13,7 @@ import { currentPlatformKey, parseManifest } from "../../../core/src/artifact/st
 import { downloadVerified, partialPathFor } from "../../../core/src/artifact/download.ts";
 import { FakeServer } from "../fake-server/server.ts";
 import { MANIFEST_FILE, sha256Hex } from "../fake-server/manifest.ts";
-import { coreUpgraderUrl } from "./m1.ts";
+import { runnerFactoryUrl } from "./m1.ts";
 
 // ---------------------------------------------------------------------------
 // m1.download-resumes-after-kill (断点续传)
@@ -59,7 +59,7 @@ export async function checkDownloadResumesAfterKill(
     };
 
     const resumeDir = path.join(ctx.sandboxDir, "incoming");
-    const coreUrl = coreUpgraderUrl();
+    const coreUrl = runnerFactoryUrl();
     const coreSrc = new URL(".", coreUrl).href;
     const dlScript = [
       `const { downloadVerified, partialPathFor } = await import(${JSON.stringify(new URL("artifact/download.ts", coreSrc).href)});`,