@botiverse/k-carrier 0.1.0

package/docs/harness-design.md

@@ -0,0 +1,170 @@
+# 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 供真床。

package/docs/integration.md

@@ -0,0 +1,326 @@
+# Integrating K into your application
+
+A from-zero guide. If you already know updaters, skim §2 (concepts) and jump
+to your profile in §3.
+
+## 0. The premise (read this first)
+
+**K assumes restarting your service is not expensive.** It guarantees you
+**come back up** — not that you never went down. A short interruption during a
+version change is accepted by design; what K refuses to accept is an upgrade
+that leaves you unrunnable, half-migrated, or claiming success it cannot prove.
+
+If you need strict continuous availability, **K is the wrong tool** — better
+said here than discovered from behaviour later.
+
+## 1. What problem does K solve? (plain words)
+
+Making a program update itself sounds trivial — download the new version,
+replace the file. For a simple CLI tool, it almost is. It stops being trivial
+the moment your program is a **service that keeps running**:
+
+- You must swap the binary **under a live process** and hand control to the
+  new version without dropping what it was doing.
+- If the new version is broken, you need a way **back** — and "the machine
+  crashed halfway through" must never leave the user with nothing runnable.
+- "It updated" is easy to *claim* and surprisingly hard to *prove*. A version
+  string can say `2.0` while the old process is still running, or while the
+  OS still auto-starts the old copy at boot. (This exact failure — new
+  version number, old behavior — is the production incident K grew out of.)
+- On a **person's own machine** (not a company server), you also can't just
+  change things silently: the owner decides whether upgrades are automatic,
+  confirmed, or notify-only.
+
+K packages the solutions to all of these as a library, so an app adopts them
+instead of re-discovering the failure modes one incident at a time.
+
+## 2. The concepts, in one paragraph each
+
+**Release source** — the one place K asks *your* product two questions:
+"what should this install be on?" (`checkForUpdate`) and "give me exactly
+this version" (`fetchRelease`). K holds **no versioning policy of its own** —
+what your streams are called ("stable", "nightly", "lts-2024"), which version
+counts as newest, whether you use semver or dates, and long-term pinning all
+live inside your source. A ready-made `staticManifestSource({ baseUrl })` covers
+the common case (static host, semver, no automatic downgrade) as *one policy*,
+not as a rule of the framework.
+
+**Two slots: `stable` and `experiment`** — K never overwrites your only copy.
+The running, trusted version sits in the *stable* slot. A new version is
+downloaded into the *experiment* slot and run **as a trial**. Only after it
+proves itself is it *promoted* to stable; if anything fails, K *rolls back*
+to the untouched stable copy. Think blue/green deployment, on one machine.
+
+**Journal** — before K does anything (download, stop, swap, promote), it
+writes what it is *about* to do to an append-only log, then does it. If the
+machine dies mid-upgrade, the next start replays the journal and either
+finishes the job or rolls back — decided by the log, not by guesswork. This
+is why "kill it at any moment" is a test we run, not a fear.
+
+**HostAdapter** — the small interface *you* implement so K can drive *your*
+service without knowing anything about it: pause your workloads
+(`quiesce`), stop/start the service, report health from the live process,
+resume workloads. It's the entire integration surface — K core contains
+zero concepts from any particular app.
+
+**Predicates (proof of upgrade)** — instead of trusting a version string, K
+checks two facts and calls the upgrade done only when both hold:
+`binary_at_target` ("the *live process* — same PID that answered — reports
+the new version") and `host_lifecycle_converged` ("OS-level state like
+launch-at-login was written AND read back consistent from its one true
+source"). Metadata like version fields or channel names is *banned* as
+evidence — it has been wrong in the wild.
+
+**Policy** — who decides an upgrade happens: `auto` (just do it),
+`confirm` (ask the owner first), `notify-only` (tell, don't act). On
+personal devices the owner always wins; even server-pushed upgrades pass
+this gate.
+
+**Install ownership** — if your binary was installed by something else (an
+OS package manager, or a parent service that injects its own copy), that
+manager owns upgrades. K detects this and refuses to self-upgrade a managed
+copy — returning a typed `held: managed-elsewhere` instead of silently
+creating a version mismatch.
+
+## 3. Adoption: two process models, plus capabilities you opt into
+
+A profile is a **process model**, and the model is defined by one number:
+**how many live incarnations K itself manages.**
+
+| Profile | K-managed live processes | Who hands over | Examples |
+|---|---|---|---|
+| **`swap`** | **0** | nobody — new bytes take effect on the next start | a one-shot CLI, `rustup`, **and a long-running interactive session like Claude Code** |
+| **`service`** | **1** (briefly 0 mid-handover) | K stops the old, starts the new, and proves it | a resident daemon, Raft Computer |
+
+That a quick CLI and an hours-long agent session share a profile is surprising
+at first and correct on reflection: **neither has a process K hands over.**
+Several old-version processes may keep running in the `swap` model — normal,
+and invisible to K.
+
+There is **no third model**. OS lifecycle convergence
+and fleet drive are **capabilities** you opt into on top of `service`; bundling
+them into a "profile" confused *what your app does* with *what K does*, and
+what your app does is none of K's business.
+
+```ts
+// a service that also wants its sessions preserved and its OS lifecycle proven
+createUpgrader({ host, source, policy: "auto", /* ... */ });
+// capabilities are declared by implementing the corresponding host duties:
+//   named readback surfaces        -> lifecycle-convergence
+//   attach the drive module        -> fleet-drive
+```
+
+## 3.5 Responsibility boundary: what K guarantees vs what you must
+
+K guarantees **mechanical** properties. It cannot guarantee your
+application's **semantic** compatibility across versions — and being clear
+about that line is part of the contract.
+
+| K guarantees (mechanically, with teeth) | You must guarantee (K can't see it) |
+|---|---|
+| the transition itself: never two incarnations live, never an unbootable host, crash at any step recovers | that version N+1 can *read* what version N wrote (your data, DB schema, caches) |
+| the artifact is byte-complete (sha256 + size) — **authenticity is NOT checked; see §Trust** | that N+1 speaks a protocol your server still accepts (and N does too, if you may roll back) |
+| the *binary* is restorable — rollback returns the exact bytes that were running | that rolling the binary back is *meaningful* — **K restores your binary, not your data**. If N+1 migrated the user's database, rolling back to N leaves N facing N+1-shaped data |
+| proof the new version is actually live and OS lifecycle converged | what `quiesce` must park durably, and what `resume` must bring back |
+| the owner's consent policy is honored | whether this upgrade is *safe to offer* at all (feature flags, in-flight work, licence state) |
+
+**The sharpest case is rollback**, and it is the same trap as downgrade:
+a rollback that restores the binary while leaving forward-migrated data
+behind is not a rollback, it's a new failure. K refuses to pretend
+otherwise — which is why it gives you a place to say so:
+
+### Declare it, and K enforces it for you
+
+Rather than leaving compatibility as a documentation promise, declare it —
+K turns your declaration into a mechanical gate:
+
+```ts
+class MyHost implements HostAdapter {
+  // Optional. Called BEFORE staging and BEFORE promote.
+  // Return a refusal string to stop the transition; null to allow.
+  async checkCompatibility(from: string, to: string): Promise<string | null> {
+    if (schemaGeneration(to) > schemaGeneration(from) && !hasDownMigration(to, from)) {
+      return `no down-migration from schema ${to} to ${from}`;
+    }
+    return null;
+  }
+}
+```
+
+- Refusing at **stage** time means the upgrade never starts (typed
+  `held: incompatible`).
+- Refusing at **promote** time means K rolls back instead of committing.
+- Not implementing it is allowed — then compatibility is entirely your
+  out-of-band responsibility, and K says so in `status --json`
+  (`compatibility: "undeclared"`), so nobody mistakes silence for a
+  guarantee.
+
+### Invariants are shipped, not hidden
+
+K's guarantees exist as an **exported invariant library** (`core/src/invariants.ts`),
+not as private test assertions. One definition, three consumers: K's own
+teeth, the deterministic simulator (checked after *every* effect, on every
+seed), and **your** tests — plus any app invariants you write in the same
+shape:
+
+```ts
+import { BUILT_IN_INVARIANTS, checkInvariants, type Invariant } from "@botiverse/k-carrier";
+
+const myAppInvariant: Invariant = {
+  id: "myapp.no-orphaned-jobs",
+  description: "no job is left claimed by a dead worker",
+  check: (s) => (orphanCount(s) > 0 ? `${orphanCount(s)} orphaned jobs` : null),
+};
+
+const violations = checkInvariants(snapshot, [...BUILT_IN_INVARIANTS, myAppInvariant]);
+```
+
+An invariant is a pure predicate over an observable snapshot (the same
+shape `status --json` emits), so the identical check runs in-process, in
+simulation, and black-box against a real binary. Violations return a
+*reason*, so a failure explains itself even when a simulator replays it
+from a seed hours later. Your invariants ride the simulator's seeded fault
+injection for free — that is the practical answer to "who guarantees my
+semantics": **you state them, K's machinery exercises them.**
+
+Rule of thumb: **K owns the mechanics of the transition; you own the meaning
+of the versions.** Where you can express the meaning as a predicate, hand it
+to K and it becomes enforced rather than hoped for.
+
+## 4. The boundary in one picture
+
+```
+            YOUR APP                    |              K CORE
+                                        |
+  daemon ──┐                            |   ┌─ artifact (download/resume/verify/swap)
+  CLI `myapp self upgrade` ──┤ construct|   ├─ (no signature client — see §Trust)
+  install script ──┘    the same        |   ├─ txn (two-slot + journal + state machine)
+                        ┌────────────┐  |   ├─ lifecycle (handoff orchestration)
+                        │  Upgrader  │──┼──►├─ converge (predicates + readback)
+                        └────────────┘  |   ├─ policy (consent/notify gating)
+  your HostAdapter ◄────────────────────┼───┤
+  your notificationSink ◄───────────────┼───┤
+  your onProgress ◄─────────────────────┼───┘  (calls back into your code only)
+```
+
+One rule regardless of profile: **every entrypoint constructs the same
+Upgrader.** Your daemon's auto-update loop, your CLI subcommand, your
+install script — same object, same path. This kills the bug class where one
+entrypoint upgrades correctly and another silently doesn't.
+
+## 4.5 Showing progress
+
+Pass `onProgress` and K reports where an upgrade is:
+
+```ts
+createUpgrader({
+  ...,
+  onProgress: (p) => {
+    // p.stage: checking | downloading | verifying | staging
+    //        | handing-over | probing | promoted | rolled-back
+    // p.downloaded / p.total: bytes, present during `downloading` only
+    render(p);
+  },
+});
+```
+
+Three things worth knowing before you draw a bar with it:
+
+- **Only `downloading` has a denominator.** Every other stage reports a
+  stage and nothing else, because K does not know how long staging or
+  probing will take and will not invent a number.
+- **`downloaded` counts bytes on disk, not bytes fetched this attempt.** A
+  resumed download starts at the size of the partial file. That is deliberate:
+  a bar that restarts from zero after a network blip reads as "it lost my
+  download".
+- **Your sink cannot fail the upgrade.** K calls it inside a `try`/`catch`
+  and discards anything it throws. An observation surface must never become
+  a failure mode — if your renderer breaks, the upgrade still completes.
+
+The stages are not a parallel state machine: they are derived from the L1
+transaction phases (`stageForPhase`), so a progress display can never show a
+state the transaction does not have.
+
+## 5. Publishing releases
+
+If you use the built-in `staticManifestSource`, its layout is:
+
+```
+<baseUrl>/manifest.json          version, per-target {file, sha256, size}
+<baseUrl>/<artifact>             the binaries
+```
+
+Root private keys stay offline; root public keys are compiled into your app.
+Any static file host works — there is no server-side logic.
+
+**This layout belongs to that source, not to K.** Publishing from a private
+API, date-stamped paths, or an OCI registry means writing your own
+`ReleaseSource`; K only ever learns `{ version, url, sha256, size }` and never
+parses a manifest itself. Multiple streams are usually one base URL each
+(`.../stable`, `.../nightly`), which also keeps their blast radius separate.
+
+### Trust: what K checks, and what it does not
+
+**K verifies integrity, not authenticity.** It checks `sha256` + `size` on the
+assembled bytes. It does **not** verify who produced them: there is no
+signature chain and no trust root (removed 2026-08-06 — `docs/design-v1.md`
+§L0.5 has the decision).
+
+A digest is not a signature. `sha256` proves the bytes you received are the
+bytes the manifest described — but the manifest comes from the same place the
+bytes do, so a source serving malicious bytes will serve a matching digest for
+them just as happily.
+
+⚠️ **So this is yours to think about, not K's:**
+
+| Threat | Covered by K? |
+|--------|---------------|
+| corruption in transit | ✅ (and your HTTPS already covers it) |
+| a wrong artifact on your CDN — leaked publish credentials, misconfigured bucket, poisoned pipeline | ❌ **not covered** — the check passes and every client installs |
+
+**OS code signing is a different guarantee, not a substitute.** Authenticode /
+codesign / notarization answer "is this program signed by a recognisable
+vendor", enforced by the OS on the install paths it controls. A distribution
+signature answers "**is this the exact artifact we published**", enforced by
+your app before the bytes reach a slot. If you ship through an app store or a
+platform installer you get some of the former for free; if you ship a plain
+binary from a CDN, as the example host does, you get neither automatically.
+
+If you need authenticity today, do it in your own `ReleaseSource`: verify
+before returning the `Release`, and refuse rather than return unverified bytes.
+⚠️ And if you build it, remember the trap this project already hit: **"accept
+unsigned" may only be declared by YOUR code, never by a field in the manifest**
+— the manifest is served by the very party a signature chain exists to distrust.
+
+## 6. Testing your integration
+
+Three beliefs shape how K is tested — knowing them explains what the harness
+will and won't do with your app (full design: `harness-design.md`):
+
+1. **Test like a user.** The primary tests spawn your *real binary* and drive
+   it through its *CLI commands*, asserting from outside (exit codes, files,
+   what version actually runs next). Library-level tests are the exception,
+   not the rule — a green that only exists inside an import is not proof.
+2. **The tests are the spec.** Every guarantee K claims (never dual-run,
+   never bricked, sessions survive rollback…) exists as a registered tooth
+   with a declared way to make it fail. A claim without a runnable red case
+   doesn't count — that includes profile support ("K supports CLIs" is
+   backed by a runnable example, not a sentence).
+3. **No test backdoors.** K core contains zero test-awareness — no test
+   modes, no "skip verification" flags. Everything the harness uses is a
+   product surface you also get (status command, injected clock, config).
+   So passing the harness means the *shipping* code path works, not a
+   test-shaped variant of it.
+
+Run the harness against **your** adapter, at your profile:
+
+```
+k-harness --profile service --adapter ./dist/myHost.js
+```
+
+Same teeth K tests itself with, tiered to your profile: crash-injection per
+state-machine edge, quiesce/resume equivalence (including post-rollback),
+probe liveness, predicate readback. Green here means your integration honors
+the contract — it is the same bar the built-in examples must pass
+(`examples/`: one runnable app per profile; a profile without a green
+example has no support claim).

package/docs/prior-art.md

@@ -0,0 +1,150 @@
+# Prior art: how k-carrier relates to Tailscale and Datadog updaters
+
+This document is the design-rationale and license-defense record behind the
+`NOTICE` file. k-carrier's architecture was informed by studying two mature,
+unrelated self-updating systems. **Only architectural concepts were studied; no
+source code was copied**, and the implementation here is original. This note
+records what each project does, what k-carrier deliberately reuses, and where it
+does something neither project attempts.
+
+Both projects were read first-hand from their upstream `main` branches:
+
+- **Tailscale** — `tailscale/tailscale`: `clientupdate/` (`clientupdate.go`,
+  `clientupdate_windows.go`, `clientupdate_downloads.go`) and
+  `clientupdate/distsign/` (`distsign.go`).
+- **Datadog** — `DataDog/datadog-agent`: `pkg/fleet/installer/`
+  (`installer.go`, `oci/`, `packages/`, `db/`) and `pkg/fleet/daemon/`
+  (`daemon.go`, `remote_config.go`, `local_api.go`, `task_db.go`).
+
+## Tailscale `clientupdate`
+
+- **Single package, dual entry point.** One `clientupdate` package is shared by
+  the `tailscaled` daemon and the `tailscale` CLI — a single canonical executor
+  reached from two binaries.
+- **Track model.** stable / unstable / release-candidate; the minor version's
+  parity selects the track; a `Confirm(newVersion)` callback gates the upgrade.
+- **Platform matrix = "defer to whoever owns the install."** A dispatch table
+  routes apt / dnf-yum / apk / Synology / QNAP / FreeBSD pkg each to its native
+  package manager; macOS GUI builds go through Sparkle; the Mac App Store build
+  cannot self-update; Arch only prints guidance (it respects pacman's
+  ownership). Every branch carries a `canAutoUpdate` flag.
+- **Bare-binary line (Linux).** require-root → resolve version → confirm →
+  download + verify a tarball → unpack over the install → restart via the
+  service manager.
+- **Windows.** MSI plus a self-copy trick (copy the running executable to a temp
+  path and run the installer from there to avoid self-locking) + Authenticode
+  verification + a re-entry environment variable.
+- **`distsign` signing (the strongest supply-chain idea).** A two-tier Ed25519
+  scheme: offline root keys are compiled into the client and sign rotating
+  signing keys, which in turn sign the distributed files; the server is just
+  static files (`$file` + `$file.sig`); signing keys are fetched dynamically
+  before each download; root rotation ships a new client.
+
+**What Tailscale does *not* do** (and k-carrier does): the restart is
+best-effort — on failure it prints "please restart manually" rather than
+failing closed; there is no post-upgrade read-back (the restart command
+returning is treated as success, with no probe of the new daemon's version); and
+there is no rollback (the old binary is simply overwritten).
+
+## Datadog fleet installer
+
+- **A self-managing package manager.** It installs and uninstalls packages,
+  including the installer itself — the installer is one of the managed packages.
+- **Two-slot upgrade transaction (the core idea k-carrier reuses).** Each
+  package keeps a `{Stable, Experiment}` pair of slots: `InstallExperiment`
+  stages the new version in the experiment slot (with pre/post start hooks), then
+  either `PromoteExperiment` (make it the new stable) or `RemoveExperiment`
+  (roll back to stable). **Upgrade is a blue/green transaction with rollback**,
+  and slot state is readable back. Configuration changes flow through the same
+  experiment / promote / rollback machinery.
+- **Daemon drive plane.** A remote-config channel pushes a catalog and upgrade
+  tasks; the daemon executes them; a task database records the work; `GetState`
+  reads back `{Stable, Experiment}` per package — so a fleet's "who is on what
+  version / mid-experiment" is observable. The local API is a unix socket /
+  named pipe.
+- **Distribution = OCI images**, content-addressed by digest (layers verified by
+  digest).
+- It explicitly sequences self-teardown (on Linux a pre-stop step would kill its
+  own process, so it removes the experiment before stopping).
+
+## Dimension-by-dimension
+
+| Dimension | Tailscale | Datadog | k-carrier |
+|---|---|---|---|
+| Executor shape | single package, dual entry ✅ | standalone installer + daemon drive | one core, shared by multiple entry points — the Tailscale shape |
+| Upgrade transaction / rollback | ❌ overwrite, no rollback | ★ two-slot + promote/rollback | fail-closed + rollback — the Datadog model |
+| Post-upgrade read-back | ❌ (restart = success) | `GetState` per package | convergence read-back with a version probe — stricter predicate layer |
+| Fleet observability | ❌ | ★ remote-config + task-db + state | server-push + read-back drive plane — the Datadog shape |
+| Channels / pinning | track + confirm | catalog + remote config | latest / alpha / pinned channel file |
+| Signing / supply chain | ★ two-tier offline-root Ed25519 | OCI digest addressing | **integrity-only today (sha256 + size); no signing implemented** — distsign studied as a future key layer |
+| Service handoff | Windows self-copy trick | explicit self-kill sequencing | detached service handoff **with in-flight workload/session preservation** |
+| OS-supervisor convergence | ❌ (native per-platform services) | ❌ | supervisor retirement + login-item migration + read-back |
+| Generic framework | ❌ coupled to Tailscale | ❌ coupled to Datadog's package ecosystem | generic core + a thin host shell |
+
+## The three concepts k-carrier reuses
+
+1. **Core transaction — from Datadog's two slots.** k-carrier's upgrade is a
+   `stable` / `experiment` pair with promote / rollback, which naturally gives
+   fail-closed behavior, rollback, and read-back state.
+2. **Executor shape — from Tailscale's single package.** One core reached from
+   several entry points (daemon / CLI / installer), rather than duplicated logic.
+3. **Supply-chain layer — from Tailscale's `distsign`.** The two-tier
+   offline-root Ed25519 idea is the intended future key layer over the existing
+   content-addressed distribution. **It is a studied concept, not present in this
+   repository** — k-carrier currently verifies artifact integrity by sha256 +
+   size only.
+
+## Why k-carrier exists (the gap)
+
+The two projects sit at opposite ends of a spectrum. Tailscale is a system
+service on mostly *personal* devices, so it is deferential to install ownership
+(package-manager routing, confirm callbacks, Arch's print-only path). Datadog
+manages *fleet* servers/nodes an organization operates, so it can push central
+remote-config and read the fleet back (the machines have no "personal will").
+
+k-carrier targets **a managed service running on a personal device**, which is
+the *union*, not a midpoint: it wants Datadog's management capabilities
+(transaction / rollback / read-back / remote drive / fleet observability) **and**
+Tailscale's device-respect (consent / notification / ownership deference), plus
+capabilities neither project has — **preserving the host's in-flight workload and
+sessions across the swap, and an un-fakeable convergence read-back**. This union
+is strictly harder than either project's problem, which is the cleanest
+explanation for why no off-the-shelf framework fits: nobody has needed exactly
+this superset. That gap is k-carrier's reason to exist as a generic core.
+
+**Layer 0 is a commodity.** Fetching, verifying, and atomically swapping a
+binary is already solved by self-update libraries (e.g. Rust `self_update`, Go
+`selfupdate`), and by the updaters shipped with CLI agents — because a CLI has no
+long-running service to hand off. k-carrier's Layer 0 looks like those and could
+even sit on top of one; its value is entirely in the layers above (transaction,
+handoff, read-back), which is exactly the list that separates a CLI self-updater
+from a managed-service carrier.
+
+## Licenses
+
+Tailscale is **BSD-3-Clause** and the Datadog agent is **Apache-2.0** — both
+permissive. k-carrier borrows concepts only and copies no code; the signing idea
+is described from the concept and would be written independently if implemented.
+k-carrier itself is released under **Apache-2.0** (see `LICENSE` and `NOTICE`).
+
+## Test-design influences
+
+- **Tailscale is unit-only, zero e2e.** Its tests are pure-function / file
+  operations (sources.list rewriting as table-driven byte-in/byte-out, repo
+  track edits, version parsing, tarball unpack, the confirm callback) plus key
+  rotation and a local-server download test. There are no upgrade-e2e, handoff,
+  crash, or rollback tests — **the test shape mirrors the design's gaps**: with
+  no rollback or read-back, nothing needs an e2e. k-carrier borrows the
+  table-driven pure-function style for its platform adapters.
+- **Datadog has real-VM e2e.** e2e runs on freshly provisioned cloud VMs (real
+  systemd / package managers), with a `host.State()` full-snapshot assertion,
+  journald timestamp anchoring (`LastJournaldTimestamp()` → "assert X happened
+  *after* the marker", an event-shaped oracle that stops stale events from
+  passing as new evidence), ownership-migration scenarios, and failure suites.
+  It is slow and expensive. k-carrier borrows the timestamp-anchored assertion
+  and the ownership-migration scenario.
+- **What neither has** (and k-carrier's harness adds): a crash-injection matrix,
+  adversarial self-verification, a mutation contract, a black-box zero-integration
+  mode, and a teeth registry with registration discipline. Tailscale's unit-only
+  suite restates the lesson: **the test shape follows the design — a design with
+  no rollback or read-back never demands tests for them.**