@botiverse/k-carrier 0.1.8 → 0.2.0

package/docs/design.md

@@ -0,0 +1,173 @@
+# K design
+
+This document is the normative contract for K's execution model, transaction,
+supervision and controller boundary. It states obligations; it does not
+explain them. Read [how an upgrade works](guide.md) first for the narrative
+and vocabulary, and the [reference](reference.md) for wire formats, exit
+codes, budgets and file layout.
+
+## Execution and trust
+
+```mermaid
+flowchart LR
+  Entry[Bootstrap / CLI / remote control] --> Supervisor[Verify and launch runner]
+  Supervisor --> Worker[K + product adapter]
+  Worker --> State[Lock / journal / slots / receipts]
+  Worker --> Controller[Product lifecycle controller]
+  Controller --> App[Application]
+```
+
+- The runner and its runtime live outside the application slots and service
+  unit. Stopping the application must leave the worker alive. A child
+  process can still belong to a systemd cgroup or Windows job; the publisher
+  must arrange isolation.
+- The supervisor retains recovery code until settlement. Installation state
+  persists. An OS hook or operator must restart installation after reboot.
+- The adapter is fixed at build time. Requests select an action and a target
+  version, never code, commands or download URLs.
+- The publisher authenticates distribution metadata and caller authority. K
+  checks artifact SHA-256 and size; these checks do not establish publisher
+  identity. See [packaging](integration.md#distribute-a-built-installer).
+
+## Components
+
+Paths are relative to `core/src/`.
+
+| Component | Responsibility |
+|---|---|
+| `launcher/` | Acquire, verify, execute and clean runner code; supervise recovery |
+| `protocol/` | Validate the bounded request/response contract |
+| `runner/` | Serve stdin/stdout, execute requests and map outcomes to exit codes |
+| `createRunner.ts` | Assemble source, host, policy and transaction state |
+| `lifecycle/` | Stop/start/probe the application, including command-based control |
+| `artifact/`, `txn/`, `converge/` | Verified acquisition, durable transactions and readiness predicates |
+
+`createRunner(options)` constructs the transaction interface. `serveRunner(factory)`
+serves it in the runner process. `launchRunner({release, request, scratchDir,
+interpreter?})` verifies and supervises a worker, writes one final response and
+returns its exit code. `superviseRunner` returns the same result as data,
+including any retained `recoveryFile`. `resumeRunner(recoveryFile)` verifies
+that retained runner and performs operation-bound recovery without
+distribution access.
+
+## Transaction and recovery
+
+Each installation has one lock, stable and experiment executable slots, and a
+journal. K stages verified candidate bytes, quiesces work, stops the old
+service, starts the candidate and evaluates live readiness. Passing candidates
+are promoted; failed candidates restore stable. Application data belongs
+outside the slots.
+
+The phases are `idle`, `staged`, `handing-over`, `running-experiment`,
+`readback`, `promoted` and `rolled-back`. Intent is journaled before effects.
+Recovery takes the same lock and uses existing slot bytes without release
+lookup:
+
+- Before durable promote intent: restore stable.
+- After durable promote intent: replay commit idempotently.
+
+A running candidate alone does not authorize commit. Corrupt or unknown state,
+and another live lock owner, prevent conflicting operations. Filesystem
+durability and controller behavior determine the real platform guarantees.
+
+## Transaction completion
+
+**Required for the initial release.** Every started operation has an owner
+that waits for a durable terminal result or explicitly reports unresolved
+recovery. An installer invocation must first settle unfinished work before
+admitting a new upgrade. Recovering an interrupted operation does not retry
+its requested upgrade.
+
+The supervisor:
+
+- runs outside the application service unit;
+- retains the verified runner while the operation is active;
+- enforces execution and recovery budgets ([values](reference.md#supervisor-budgets));
+- starts a recovery worker after an abnormal exit;
+- stops supervising after completion or an explicit unresolved result.
+
+Recovery attempts and total elapsed time are bounded. Exhaustion preserves
+state and provides a recovery command rather than reporting success.
+
+Before starting a successor, the supervisor must observe the prior worker
+exit. The recovery worker then takes the lock and fences outstanding
+controller effects before replaying lifecycle actions. An expired deadline
+alone is insufficient; an unconfirmed exit forbids takeover.
+
+Recovery must bind to the original operation id under K's transaction lock.
+If another operation has since run, recovery inspects or replays the original
+result without modifying the newer operation. Recovery reuses the existing
+journal and receipts; supervision does not create another transaction log.
+
+Cleanup follows settlement: persist the outcome, release owned resources,
+then remove disposable code. Never delete slots, a live owner's lock, or
+recovery logs to make an interrupted operation appear complete. If recovery
+remains unresolved, preserve the evidence and a verified means to invoke it
+again. Installer startup handles leftover work; machine reboot still requires
+an OS hook or operator to start the installer.
+
+Every engine host call has a positive budget. Uncertain effects retain the
+worker's lock until it exits. Bundled workers exit after flushing their
+response; custom in-process callers must also exit on `HostCallUncertain`
+rather than reuse that worker.
+
+The lock is a local filesystem protocol requiring atomic creation and
+coherent directory reads ([details](reference.md#lock-protocol)). It is not a
+distributed or NFS lock. Operation ids, receipt archival and replay rules are
+in the [reference](reference.md#receipts-and-retries).
+
+## Host control contract
+
+`createRunner` requires a HostAdapter. Its operations and the controller's
+obligations:
+
+| Operation | Controller obligation |
+|---|---|
+| fence | Drain or fence previous controller effects; required when effects can outlive the worker |
+| quiesce | Stop admission and durably park promised workloads; repeated calls safe |
+| stop | Stop the specified slot's service and confirm termination |
+| start | Start the selected artifact idempotently, without creating duplicate residents |
+| healthProbe | Return version, pid and startId from one ready live instance |
+| resume | Restore parked work on either candidate or rolled-back stable |
+
+- The controller must work while the old application is down.
+- `start` returning does not establish readiness; the probe does.
+- K probes once before handover and records that incarnation's `startId`
+  with the handing-over intent. Readback evidence carrying the same
+  `startId` is refused and rolls back: the old service was not replaced.
+- `start` must not execute the artifact in place inside the slot on
+  Windows; promotion renames slot directories and a running executable locks
+  its directory. Copy or hard-link to a runtime path outside the slots.
+- A stateless service satisfies `quiesce` and `resume` by acknowledging. The
+  obligations apply to workloads the product promises to preserve.
+- Adapters with no effects surviving their worker may omit `fence`. All
+  other adapters must supply it and test it against their real service
+  manager. `createCommandHost` always delivers `fence`; a command controller
+  that queues nothing acknowledges it.
+- If OS lifecycle surfaces are declared, K also requires them to reference
+  the promoted artifact before retiring their previous manager. Undeclared
+  surfaces are not observed.
+
+`createCommandHost` runs an external controller via argv without a shell,
+records the controller pid durably before each call, and drains recorded
+controllers before `fence` during recovery. Wire format, bounds and pid
+handling are in the [reference](reference.md#command-controller-protocol).
+The recorded pid is never used to kill an arbitrary process. `fence`
+acknowledgement is a product contract, not something K infers from process
+exit. Fire-and-forget stop cannot establish termination.
+
+## Product responsibilities
+
+The adapter defines release lookup, installation ownership, consent,
+notification and compatibility policy. Package-manager-owned installations
+defer to their owner. K restores executables; products provide data-migration
+compatibility, backup and restore, and any promised workload continuity.
+Service upgrades can interrupt availability. Remote authorization,
+distribution channels and cloud reconnection belong to the product
+integration.
+
+Use the [integration guide](integration.md) and
+[service example](../examples/external-service/README.md) to build an
+installer. The [test plan](test-plan.md) describes framework and product
+acceptance; [prior art](prior-art/design-influences.md) records design
+influences.

package/docs/guide.md

@@ -0,0 +1,196 @@
+# How an upgrade works
+
+This is the narrative walkthrough of K's mechanism: which processes exist,
+what happens in what order, what breaks, and how to read the result. It is
+written to be read once, top to bottom. It is **not** the contract; where it
+and the [design](design.md) or [reference](reference.md) disagree, they win.
+
+For what K is for and whether you need it, read the [README](../README.md).
+For how to build and ship an installer, read the
+[integration guide](integration.md). Terms are defined where they first
+appear in bold; this document is the vocabulary the other documents use.
+
+## The pieces
+
+```mermaid
+flowchart LR
+  B[Bootstrap<br/>install.sh / self upgrade] -->|request| S[Supervisor<br/>launchRunner]
+  S -->|verify, spawn| W[Worker<br/>K + adapter]
+  W --> D[(State directory<br/>lock · journal · slots · receipts)]
+  W -->|fence · quiesce · stop<br/>start · probe · resume| C[Controller]
+  C --> A[Application]
+```
+
+- The **bootstrap** is your `install.sh`, or the `self upgrade` command inside
+  your application. It downloads and verifies the installer, launches it,
+  and relays the exit code. It contains no upgrade logic.
+- The **installer** is what you ship. It has two halves. The **supervisor**
+  is a temporary process that acquires and verifies the runner, executes it
+  and, if it dies, runs bounded recovery. The **runner** is K plus your
+  adapter bundled into one executable; it serves one request and exits. A
+  running runner is a **worker**.
+- The **adapter** is your trusted code, fixed at build time: where releases
+  come from, whether an upgrade may proceed, and how to reach the controller.
+- The **controller** is your program that actually stops, starts and probes
+  the application. The adapter can call it directly or through `createCommandHost`.
+- The **state directory** holds the lock, the journal, two **slots** and the
+  receipts. Recovery uses this state together with a compatible runner, its
+  runtime and the product controller; it does not need release distribution.
+
+The runner and the controller live outside the application's service unit.
+That is the whole point: stopping the application must not stop the thing
+that is upgrading it.
+
+The slots are **stable** and **experiment**; these are positions
+on disk, not release channels, so a product channel also called "stable" is
+unrelated. *Hands*, mentioned in the integration guide, is the release
+platform K's authors publish with; K does not depend on it.
+
+## One upgrade, start to finish
+
+```mermaid
+sequenceDiagram
+  participant B as Bootstrap
+  participant S as Supervisor
+  participant W as Worker
+  participant C as Controller
+  participant A as Application
+  B->>S: upgrade id=job-1 target=2.0.0
+  S->>S: download runner, check sha256 + size
+  S->>W: spawn, request on stdin
+  W->>W: take upgrade.lock, inspect operation identity
+  W->>C: fence previous controller effects
+  W->>W: settle leftovers, begin requested operation
+  W->>W: fetch release, verify bytes
+  Note over W: journal: staged intent
+  W->>W: write experiment slot
+  Note over W: journal: handing-over intent
+  W->>C: quiesce
+  C->>A: park work
+  W->>C: stop stable
+  C->>A: terminate, confirm exit
+  W->>C: start experiment
+  C->>A: launch candidate
+  W->>C: healthProbe
+  C-->>W: version 2.0.0, pid, startId
+  Note over W: journal: readback ok → promote intent
+  W->>W: experiment becomes stable
+  W->>C: resume
+  Note over W: persist promoted operation receipt
+  W-->>S: {result: promoted}, exit 0
+  S-->>B: exit 0
+```
+
+In words:
+
+1. The bootstrap asks the supervisor for one operation: an id and a target
+   version. The id is what everything else binds to.
+2. The supervisor downloads the runner, checks its hash and size, writes it
+   to scratch space and runs it with the request on stdin.
+3. The worker takes the installation lock. If an earlier operation was left
+   unfinished, it settles that first. The same id replays its result; a new
+   id may proceed only after recovery succeeds.
+4. It asks your release source for exactly the target version, verifies the
+   bytes, and writes them into the *experiment* slot. Nothing running has
+   changed yet.
+5. It asks the controller to quiesce (park in-flight work) and to stop the
+   current service, and waits for confirmation that the old process is gone.
+6. It asks the controller to start the candidate from the experiment slot,
+   then probes it. The probe must come from one live process and report the
+   expected version with a pid and a **startId**. K probed once before
+   stopping the old service and journaled that startId; if the same one
+   comes back now, the old process was never replaced and the upgrade rolls
+   back.
+7. Only now does the worker write **promote intent** to the journal. That
+   line is the point of no return: before it, the safe move is always to put
+   the old version back; after it, the safe move is always to finish the
+   promotion.
+8. Experiment becomes stable. The controller resumes parked work. The
+   receipt is persisted in `operation.json`; it is archived before a later
+   operation begins. The worker prints its response and exits 0.
+
+The transaction journal phases are, in order: `idle`,
+`staged`, `handing-over`, `running-experiment`, `readback`, and then either
+`promoted` or `rolled-back`. Operation receipts additionally track stages such as
+`downloading` and policy outcomes such as `held`.
+
+## When something goes wrong
+
+### The candidate is bad
+
+It does not start, it reports the wrong version, or it never passes the probe.
+The worker stops it, starts stable again, resumes parked work, and records
+`rolled-back`. Exit code 1. The stable bytes were never touched. This is the
+routine failure and the one K is built around.
+
+### The worker dies
+
+A crash, a kill, or a budget timeout. The supervisor:
+
+1. terminates a timed-out worker and waits for its observed exit; a deadline
+   alone does not permit takeover;
+2. starts a recovery worker bound to the same operation id;
+3. that worker takes the transaction lock, checks the operation identity,
+   and asks the controller to **fence** before replaying lifecycle effects.
+   Fencing ensures actions queued by the earlier worker cannot land later.
+   An already terminal original operation simply replays its receipt.
+
+Recovery does not need the network and does not guess. It reads the journal:
+
+```mermaid
+flowchart LR
+  idle --> staged --> ho[handing-over] --> re[running-experiment] --> rb[readback]
+  rb -->|promote intent| promoted
+  rb -.-> rolledback[rolled-back]
+  subgraph before [before promote intent: restore stable]
+    staged
+    ho
+    re
+    rb
+  end
+  subgraph after [after promote intent: replay commit]
+    promoted
+  end
+```
+
+Before promote intent, recovery restores stable. After it, recovery replays
+the commit. Both are idempotent, so a crash *during* recovery is handled the
+same way next time. Recovery never starts a new upgrade, even if the original
+request was an upgrade.
+
+Attempts and elapsed time are bounded. If recovery does not settle within
+those bounds, the supervisor exits 3, leaves the verified runner and a
+`recovery.json` in scratch space, and prints where. Later, `resumeRunner` on
+that file retries the same recovery offline.
+
+### Everything dies
+
+Power loss, reboot, or the whole invocation killed. The state directory
+survives. The next installer invocation, whether from `install.sh`, from
+`self upgrade`, or from an operator, settles the unfinished operation before
+it accepts new work. K does not install a permanent watchdog, so *something*
+has to run the installer again: your product's OS startup hook, or a person.
+
+## Reading the result
+
+Every run prints one JSON response on stdout and returns an exit code.
+Inspect both. The short version:
+
+| Exit | Meaning | What to do |
+|---|---|---|
+| 0 | Successful upgrade outcome; readable status or recovery with no recorded outcome | Check the action and receipt |
+| 1 | Rolled back, or failed before any change | Read `operation.operation.outcome` and the reason |
+| 2 | Held by policy, ownership or compatibility | Nothing changed; a new attempt needs a new id |
+| 3 | Unresolved | Keep the recovery file and run recovery |
+
+Two things surprise people. First, a `recover` action that successfully
+restored stable after a bad candidate exits **1**, because the recorded
+outcome is a rolled-back upgrade. That is the honest answer. Second, `status`
+reads the last receipt, not the live service; it can say `genesis` (no
+operation ever recorded) on a machine that is running fine.
+
+The exact response shape and every exit code are in the
+[reference](reference.md#protocol-v1).
+
+What each step asks of your controller, and how to package and ship the
+result, is the [integration guide](integration.md).

package/docs/harness-design.md

@@ -1,170 +1,75 @@
-# K 测试框架（harness）设计 v1
-
-08-05：测试框架要**提前设计成完整的一块**，不是随层补测试。本文是 harness 的架构设计；`test-plan.md` 是跑在它上面的计划。
-
-## 0. 定位：harness = 框架的可执行规格（executable spec）
-
-顺序反转：**先有 harness，后有功能层**。每个功能层落地的定义 = "它让 harness 里预先写好的那组齿从 RED 变 GREEN"。测试不是功能的附件，是功能的规格。三个推论：
-1. M0（harness 自举）先于一切层实现；
-2. **不允许 harness 外的 ad-hoc 测试**——新齿必须进 registry（否则齿的 must-red/分档/自验纪律管不到它）；
-3. harness 只吃 core 的公共 API + HostAdapter ⇒ 它同时是 **API 的第一个消费者**（dogfood：API 不好用，harness 先痛）。
-
-## 1. 组件架构
-
-```
-harness/
-├─ fake-host/        假宿主（两种形态）
-│   ├─ inproc.ts     进程内 HostAdapter 实现（快速单元级）
-│   └─ daemon.ts     可 spawn 的真进程假 daemon（kill -9 是真的）
-├─ fake-server/      本地静态发布服务器 + 篡改 API
-├─ artifact-factory/ 版本工件工厂（一次构建多次盖戳 + behavior 旋钮）
-├─ scenario/         场景运行器（隔离沙箱 + 虚拟时钟）
-├─ crash/            崩溃注入编排器（枚举生成，禁手列）
-├─ teeth/            齿注册表 + 分档 + 自验
-└─ cli.ts            `k-harness` 入口（含 --adapter 接入方模式）
-```
-
-### 1.1 fake-host（假宿主）
-- **两形态**：`inproc`（进程内实现，跑快速逻辑齿）+ `process`（编译成真二进制、真 spawn、真 PID/startId —— kill -9、双跑检测、probe 活性都必须在真进程上验，mock 验不了崩溃）。
-- **故障注入开关**（per 方法）：`fail-on-quiesce / hang-on-stop / wrong-version-probe / stale-startId-probe / crash-during-start ...`——每颗齿测"故障被抓"，开关关掉齿必须转绿（证明齿测的是故障不是常态）。
-- **虚拟负载账本**：假宿主维护一个确定性"会话状态"文件（计数器+校验和）；`quiesce↔resume` 等价断言 = 账本逐字节比对（**含 rolled-back 后 resume**）。这是"会话保留"的可机械判定形态。
-
-### 1.2 fake-server（假发布端）
-- 本地静态文件服务 + manifest 构造器（含 Range 续传——不认 Range 的桩会让"续传"悄悄退化成普通下载）。
-- **篡改 API**：`corruptByte(file, offset) / swapFiles / serveOlderVersion / dropFile` —— 完整性齿全部走"真篡改→真拒绝"，不 mock 校验函数。判据是 sha256：K 验完整性不验来源（design-v1 §L0.5），所以篡改的判据也只能是"服务的字节还对不对得上 manifest 的摘要"。
-
-### 1.3 scenario（场景运行器）
-- **一场景一沙箱**：独立 temp stateDir + 独立 fake-server 端口 → 全部并行安全、可重复。
-- **虚拟时钟注入**：core 的超时/重试全走注入 clock（框架级 clock seam —— 我们 web 侧 clock-ratchet 的同款纪律），场景可快进；无真实 sleep。
-- 场景 = 声明式脚本（步骤 + 期望 outcome + 期望 journal 尾部），跑完输出结构化 receipt（给 CI 和人两用）。
-
-### 1.4 crash（崩溃注入编排器，承重件）
-- **覆盖面由代码生成**：从 core 导入状态机迁移表，自动枚举 `迁移边 × kill 点`（每个动作的 journal-写前/写后至少两点）→ 生成场景矩阵。**手列 kill 点非法**。
-- **完备性齿**：core 新增一个 phase/迁移而矩阵没覆盖 ⇒ harness 自身 RED（枚举器数量对账）。防"加了状态忘了测崩溃"。
-- 每格断言同一组不变式：重启后 = 恢复 stable 或完成迁移；**永不双跑**（真进程存活探测）；**永不砖**（stable 可再启动）；journal 可重放。
-
-### 1.45 DST：确定性模拟测试（与崩溃矩阵互补）
-
-**实现状态：已落地。** 入口为 `k-harness sim`；实现位于
-`harness/src/sim/`，三颗注册齿为 `sim.seed-replay-identical`、
-`sim.smoke-invariants`、`sim.fault-surface-covered`。
-
-**两条腿**：崩溃矩阵 = **枚举穷举**（在它的粒度上完备，给保证）；DST = **种子随机深探**（FoundationDB/TigerBeetle 手法，找枚举想不到的交错，给发现）。
-
-- **前提（对 txn 引擎的架构约束，写引擎前就定）**：L1 引擎 = **纯状态机 + Effects 接口**——journal append/fsync、槽操作、宿主调用、时钟全部经注入的 effects 层，引擎本体零直接 IO/时间/随机。这**不是**测试后门（§1.8 自洽）：effects 层就是平台适配器的天然挂点（各平台 fsync/swap 本来就不同实现），是产品级抽象。
-- **模拟器**：SimEffects = 内存盘（可模拟 partial write / fsync 丢失 / 重排）+ VirtualClock + **种子 PRNG 故障调度器**（在任意 effect 点注入 crash/fail/delay，按种子决定）。跑 N 千个种子 × 每种子一条完整升级/回滚剧本 → 断言同一组不变式（永不双跑/永不砖/journal 可重放/谓词诚实）。
-- **可复现**：任何失败 = 一个种子号，`k-harness sim --seed X` 逐字节重放。**失败种子沉淀为枚举矩阵的新固定格**（发现→保证的转化管道）。
-- **跑法**：PR 门跑固定 smoke 种子集（快、确定）；夜跑扩大随机种子量；语料库（历史失败种子）永久保留。
-  - PR/本地：`k-harness sim`（固定、评审可见的 smoke seeds）。
-  - 单种子重放：`k-harness sim --seed X --json`（同 seed receipt 逐字节相同）。
-  - 扩量：`k-harness sim --start-seed X --seeds N`；nightly 默认 50,000 seeds。
-  - 失败自动原子合并进 `.k-harness/sim-failures.json`，workflow 保存为 artifact；记录含 seed、失败原因、transcript SHA-256 与一条可直接运行的 replay command。
-- 范围诚实：DST 覆盖 txn/converge 的逻辑交错；真进程/真 OS 面（信号、真 fsync 语义）仍归崩溃矩阵与真机轮——**模拟不替代真进程层，两者叠加**。
-
-### 1.5 teeth（齿注册表）
-每颗齿是一条注册记录，声明即纪律（缺任一字段注册失败）：
-```ts
-registerTooth({
-  id: "txn.no-dual-run",
-  profiles: ["service", "hosted"],          // 分档
-  kind: "invariant",                        // 或 { kind: "baseline", failureCondition: "..." }
-  mustRed: [                                // mutation 契约：≥1 条，且答得出"不被我抓还会被谁抓"
-    { mutate: "skip journal fsync before handover", caughtOnlyBy: "this" },
-  ],
-  run: async (ctx) => { ... },
-});
-```
-- **分档执行**：`--profile swap|daemon|managed` 选齿集；cli 档误挂 L2 齿 ⇒ 注册期报错（档界齿）。
-- **断言二分机械化**：`kind` 必填 invariant 或 baseline-带失效条件；CI 扫无标注断言（断言纪律的执行器）。
-- **mutation-runner 对接**：registry 导出齿清单 + must-red 表，Lincan 的 runner 直接消费（未变异 baseline 0 失败 / 每齿变异必红 / 全红也不发结论）。
-
-### 1.6 自验（M0 出口，harness 的上岗证）
-harness 判定别人之前先判自己，三样本缺一不可：
-- **known-green**：正确实现走完整升级 → 必须全绿；
-- **known-red**：注入一个已知故障 → 对应齿必须红、且只红该红的；
-- **对抗样本**：**结构上能过齿的检查、但违反真实 oracle** 的假实现（例：probe 换 pid 不换 startId 报新版本；quiesce 把账本备份再恢复伪装等价）→ 必须被抓。对抗样本清单随齿长（每次真实逃逸事后加一条）。
-自验不过 ⇒ harness 拒绝运行任何评审（exit 非零 + typed 原因）。
-
-### 1.7 接入方模式（`k-harness --profile X --adapter path`）
-同一套齿对**外部真 adapter** 跑合规子集（不跑需要故障开关的齿，跑契约齿：quiesce↔resume 等价、probe 活性、ownership 响应）。绿 = 接入方契约达标；这也是 examples 三 demo 的验收方式——**demo 和接入方走同一道门**。
-
-## 1.75 两个测试平面：黑盒优先（08-05："就像启动一个 CLI、跑它的命令"）
-
-harness 有两个平面，**默认用外面那个**：
-
-- **黑盒平面（主平面）**：spawn **真实打包好的二进制**，只通过它的命令行驱动（`mytool self upgrade` / `mytool status`），从外面断言：exit code、输出、盘上文件、进程状态、下次运行的版本。**就是用户的用法** —— 它顺带真正验证了"每个入口构造同一 Upgrader"这类 claim（library 平面验不了打包/入口接线）。examples 三 demo 都是真 CLI，端到端齿全在这层写。
-- **library 平面（辅助）**：import core API 直驱 Upgrader——只留给黑盒够不着的内部齿（如 journal 重放细节）。
-
-**规则：能在黑盒层表达的齿必须写在黑盒层**；library 层是例外、要说明为什么外面够不着。（同我们 symptom-layer 教义：用户层的红是最不可伪造的 oracle。）
-
-接入方黑盒模式随之而来：`k-harness --profile swap --bin ./mytool` —— **零代码集成**：给你的真二进制，harness 起 fake-server、跑你的升级命令、断言下次运行版本/回滚/held。比 `--adapter` 还轻（cli 档接入方连 adapter 都不用给）。
-
-## 1.76 黑盒 CLI 契约（08-05："需要定义查版本子命令、状态 predicate 之类"）
-
-黑盒平面要从外面问二进制三类问题，因此有一个**小的 CLI 契约** —— 但它是"声明"不是"每家自己发明"：
-
-**① core 白送命令实现**（app 只做一行接线）：
-- `versionCommand()` → 打印二进制自身版本（cli 档够用）；
-- `statusCommand()` → **问活进程**（走宿主 socket，同 same-PID 纪律）输出机读 JSON：`{ProcessEvidence, TxnState, ConvergenceReport}` —— 就是 core 已有的三个类型，不另造 schema；
-- `selfUpgradeCommand()` → 包装 `upgrader.upgrade()`，outcome 四态按结构化输出。
-
-**② app 声明命令名**（K 不规定你的 CLI 长相，但声明是**必须的**——harness 不猜命令，缺声明立即 typed FAIL）：二进制旁边放一个 `k.target.ts`（或 `--target <path>`），default export typed `BlackBoxTarget`，命令名全部显式声明：
-```ts
-import type { BlackBoxTarget } from "@k-carrier/harness";
-
-export default {
-  version: ["--version"],
-  status: ["k-status", "--json"],      // 可选
-  selfUpgrade: ["self", "upgrade"],
-  env: { K_RELEASE_BASE: "..." },       // 可选
-} satisfies BlackBoxTarget;
-```
-`k-harness --bin ./mytool` 动态 import 它来驱动（node 原生跑 TS，不用 build）。**没有 `k.target.ts` = 立即 typed FAIL（`BLACKBOX_TARGET_REQUIRED`），不探测、不猜**——猜对了省一行配置，猜错了给出的是一个可信的错误结论（不确定时要求显式声明，不替用户发明规矩）。
-
-**③ 与透明性原则自洽**：这些不是测试后门，是**产品本来就该有的面**（用户和 support 一样需要 `status --json`）——harness 只是恰好消费它们。cli 档最小契约 = `version` + `selfUpgrade` 两条；daemon/managed 档 + `status`（活进程 JSON）。
-
-**齿**：契约自身可验 —— `k.target.ts` 声明的命令跑不通 / status 输出不合 schema ⇒ 黑盒验收直接 FAIL（typed，不进齿评审）；缺 target 文件 ⇒ 必 FAIL 且信息可操作（齿 `blackbox.missing-target-fails`）。
-
-## 1.77 版本工件工厂 + 清场（08-05："准备相应版本的二进制？删除清空？"）
-
-**① artifact-factory（升级测试需要"同一个 app 的 vX 和 vY"）**：
-- `makeRelease({version, behavior})` → 产出**盖了版本戳的真二进制** + manifest，落到 fake-server。实现 = **一次构建、多次盖戳**（构建 demo 源码一次，post-build 往二进制里注入版本串——与真 SEA 嵌版本同型，快且真实；不用"版本写在旁边文件"那种假形态）。
-- `behavior` 旋钮让某个"新版本"**故意坏**：`crash-on-start / wrong-probe / hang-on-quiesce ...` —— 回滚齿、known-red、对抗样本的 fixture 都从这来（"升到坏版本→自动回滚→stable 完好"整条链可黑盒复现）。
-- 内容寻址缓存（key = demo 源 hash × version × behavior），跨场景复用，不重复构建。
-
-**② 清场（teardown）**：
-- 沙箱边界即清场边界：install dir + stateDir + fake-server 存储全在场景沙箱内。teardown = **杀进程树并确认真死**（按沙箱标记 pgrep 复核零残留——僵尸 `__service` 是我们的真实产线教训，"发了 kill"≠"死了"）→ 删沙箱目录。崩溃场景故意留下的中间态也被同一动作清干净（一切都在沙箱里，所以 rm 恒有效）。
-- **越界写齿**：core 在任何场景中写沙箱外任何路径 ⇒ RED。这颗齿顺带保证了产品级卫生（升级器不污染全局 HOME/系统目录），也让"清空"永远可信——**能一键删干净，是因为先机械保证了它只写在自己地盘**。
-- 顺带的产品映射：沙箱清单 = 将来"干净卸载"要删的东西的权威地图（卸载功能本身另立，不在本期）。
-
-## 1.8 透明性原则（08-05：测试框架对升级框架透明）
-
-**core 对 harness 零感知，机械强制**：
-- **禁 test-conditional**：core 内不得存在 "if under test" 任何形态（环境变量开关/测试模式 flag/AllowUnsigned 之类后门）。CI ratchet 扫 core 源码（同我们 clock-ratchet 手法），出现即红。
-- harness 需要的一切必须走**产品级注入面**——这些面是产品本来就需要的，不是为测试开的：
-  - `HostAdapter`：产品 API 本体，fake-host 只是又一个 adapter；
-  - `releaseBase`：指向 localhost 是配置，不是测试感知；
-  - `clock`：时钟 seam 是正当的生产抽象（默认真时钟），不是测试后门；
-  - `stateDir`：本就按 app 配置。
-- 崩溃注入 = 对真进程 kill -9，零 core 配合；故障注入全在 fake-host（harness 侧代码）；对抗样本 = 假 adapter——全部外部。
-- **反向信号**：若某颗齿写不出来、除非给 core 开后门 ⇒ 判定为**公共 API 不足**（dogfood 信号），修 API 而不是开门。透明性由此与 forcing-function 同构：测试框架也只能是 core 的一个普通消费者。
-
-## 2. 关键设计决定（为什么这样）
-1. **真进程优先**：崩溃/双跑/probe 活性只在真 spawn 的假 daemon 上验——mock 崩溃 = 没测崩溃。inproc 只服务快速逻辑齿。
-2. **枚举生成覆盖面**：kill 矩阵、齿-档对账、断言标注扫描全由代码生成/校验，**人列清单在这三处非法**（人会漏，且漏的方向总是"看起来覆盖够了"）。
-3. **虚拟时钟 + 沙箱**：决定论优先；flaky 即 bug。
-4. **齿注册表是唯一入口**：declaration = 纪律载体（分档/must-red/二分标注都在注册时强制），绕开注册表的测试 CI 拒收。
-5. **对抗样本制度化**：自验含"骗过检查但违反 oracle"的样本，且逃逸事后必须沉淀为新对抗样本——今天 uninstall 设计 那套 BLIND 对抗采样的教训直接机械化。
-
-## 3. 实现顺序（M0 内部）
-1. teeth 注册表 + 分档执行器 + 二分标注检查（纯逻辑，先立规矩）；
-2. scenario 沙箱 + 虚拟时钟；
-3. fake-server（静态服务 + 篡改 API）；
-4. fake-host inproc → fake-host daemon（真进程）；
-5. crash 枚举器（吃 core 状态机表——此时 core 只需 `txn/state.ts` 的类型，已存在）；
-6. 自验三样本 → **M0 出口**。
-此后每个功能层（M1–M6）的落地 = 先在 registry 写该层的齿（RED）→ 实现层 → 齿转 GREEN。
-
-## 4. 边界
-- harness 不测 UI/产品语义（壳仓库自己的事）；只测 core 契约 + 接入方 adapter 合规。
-- 真机/平台矩阵（mac launchd、Windows 服务）走 Testbed 轮，harness 出可移植齿、Testbed 供真床。
+# Harness design
+
+The harness tests K's transaction mechanisms. The external runner tests exercise
+application integration. Neither replaces acceptance tests for a product's actual
+service manager, installer packaging and data.
+
+## Test layers
+
+| Layer | Implementation | Evidence |
+|---|---|---|
+| Mechanisms | Core unit tests, harness checks, injected effects | Locking, journal ordering, slots, policy, rollback and convergence |
+| Execution boundary | Protocol, launcher, runner and command-controller tests | Input rejection, verified runner execution, bounded calls, receipt and exit-code binding |
+| Real processes | `core/src/runner/process.test.ts` | A separate runner upgrades an application with no K dependency; another worker recovers after a crash |
+| Product acceptance | Product repository and target machines | Real service isolation, packaging, workload restoration and data compatibility |
+
+`pnpm test` runs the first three layers; `pnpm test:runner` selects the runner
+boundary and integration tests. Direct Node tests are not all registered harness
+checks, so `--list` is not the complete test inventory.
+
+## Components
+
+All paths below are under `harness/src/`.
+
+| Directory | Role |
+|---|---|
+| `fake-host/` | In-process hosts and spawned service processes with controllable faults |
+| `fake-server/` | Local artifact delivery, range requests and corrupted responses |
+| `artifact-factory/` | Runnable, version-stamped fixture artifacts with selectable failures |
+| `fixtures/` | Internal byte-replacement, service and workload-ledger fixtures |
+| `scenario/` | Isolated sandboxes and virtual time |
+| `crash/` | Transition-derived fault matrix and recovery assertions |
+| `sim/` | Seeded fault scheduling, invariant checks and replayable failure records |
+| `teeth/` | Named checks, selection and known-green/known-red tests |
+
+Core receives host, source, clock and effects through normal interfaces. It must
+not detect tests or gain test-only bypasses. Logical tests use virtual time;
+process/network tests use bounded waits and clean up their resources.
+
+## Registered checks
+
+A registered check (called a *tooth* in the code) declares its id, tested layers,
+profile, invariant or baseline failure condition, and a mutation that must fail.
+The registry rejects invalid declarations and duplicate ids. Known-green cases
+establish that correct behavior passes; known-red and adversarial cases establish
+that the check catches its intended failure. A declared mutation is not evidence
+that a separate mutation campaign has run.
+
+The harness profiles `swap` and `service` select mechanism checks. Internal
+fixtures invoke the engine directly; product examples use the external runner.
+
+`--adapter` runs the subset supported by a harness adapter's declared contract;
+it expects the harness driver interface, not an arbitrary product HostAdapter.
+`--bin` drives a fixture or binary through explicitly declared commands in
+`k.target.ts` (or `--target`). Missing command declarations fail; the harness does
+not infer CLI names. See `node harness/src/cli.ts --help` for current options.
+
+## Fault coverage and limits
+
+The crash enumerator crosses the transaction transition table with three points:
+before journal write, after journal write and after the action. The matrix uses
+injected effects and simulated crashes. Directed real-process tests separately
+kill a worker between stop and start and verify recovery. The generated matrix
+is not a claim that every point was tested with OS kills or physical power loss.
+
+Seeded simulation explores additional effect interleavings. Its receipts preserve
+the seed and transcript hash; failing seeds are saved for replay. Regressions
+should become fixed cases. Simulation does not establish filesystem durability,
+service-manager isolation or platform-specific executable replacement.
+
+Recovery uses the same contract at every layer: before durable promote intent,
+restore stable; after it, replay commit. Product controllers must also isolate
+unfinished asynchronous effects before retrying a timed-out operation.
+
+See the [test plan](test-plan.md) for commands and acceptance criteria, and the
+[design](design.md) for the transaction and wire contracts.