@botiverse/k-carrier 0.1.7 → 0.2.0

package/harness/src/fixtures/cliToolSource.ts

@@ -0,0 +1,166 @@
+/** Internal byte-replacement fixture driven by the harness.
+ * Version/behavior placeholders are stamped by ArtifactFactory. The self-upgrade
+ * command exercises core mechanisms; it is not a product integration API.
+ * K_CORE_UPGRADER supplies the file URL of core/src/createRunner.ts.
+ */
+export const CLI_TOOL_SOURCE = `#!/usr/bin/env node
+// Internal swap-tool fixture built by ArtifactFactory.
+// self upgrade runs through core's Upgrader; --probe is the headless
+// start check the swap-profile host uses to verify new bytes.
+"use strict";
+const VERSION = "__K_VERSION__";
+const BEHAVIOR = "__K_BEHAVIOR__";
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const RELEASE_BASE = process.env.K_RELEASE_BASE;
+const STATE_DIR = process.env.K_STATE_DIR ?? path.join(path.dirname(process.argv[1]), "state");
+const CORE_UPGRADER = process.env.K_CORE_UPGRADER;
+const args = process.argv.slice(2);
+const startId = process.pid + "-" + process.hrtime.bigint().toString(36);
+// Synchronous writes: process.exit() can truncate buffered pipe writes,
+// and the black-box assertions read stdout as evidence.
+
+if (args[0] === "--probe") {
+  // headless start check used by the swap-profile host during an upgrade
+  fs.writeSync(1, VERSION + "\\n");
+  process.exit(BEHAVIOR === "crash-on-start" ? 1 : 0);
+}
+if (args[0] === "greet") {
+  fs.writeSync(1, "Hello, " + (args[1] ?? "world") + "! (v" + VERSION + ")\\n");
+  process.exit(0);
+}
+if (args[0] === "--version") {
+  fs.writeSync(1, VERSION + "\\n");
+  process.exit(0);
+}
+if (args[0] === "confirm" && args[1] === "upgrade") {
+  confirmUpgrade(args[2]).catch((e) => { fs.writeSync(2, String(e) + "\\n"); process.exit(5); });
+} else if (args[0] === "self" && args[1] === "upgrade") {
+  selfUpgrade().catch((e) => { fs.writeSync(2, String(e) + "\\n"); process.exit(5); });
+} else {
+  switch (BEHAVIOR) {
+    case "crash-on-start": fs.writeSync(2, "swap-tool crashed\\n"); process.exit(1); break;
+    case "hang-on-quiesce": fs.writeSync(1, "swap-tool " + VERSION + "\\n"); setInterval(() => {}, 2147483647); break;
+    case "ok":
+    default: fs.writeSync(1, "swap-tool " + VERSION + "\\n"); process.exit(0); break;
+  }
+}
+
+async function selfUpgrade() {
+  if (!RELEASE_BASE) { fs.writeSync(2, "K_RELEASE_BASE not set\\n"); process.exit(2); }
+  if (!CORE_UPGRADER) { fs.writeSync(2, "K_CORE_UPGRADER not set (the example's @k-carrier/core wiring)\\n"); process.exit(2); }
+  const coreSrcUrl = new URL(".", CORE_UPGRADER).href;
+  const { createRunner } = await import(CORE_UPGRADER);
+  const { staticManifestSource } = await import(new URL("artifact/staticManifestSource.ts", coreSrcUrl).href);
+  const { atomicWriteFile } = await import(new URL("artifact/swap.ts", coreSrcUrl).href);
+  const { slotArtifactPath } = await import(new URL("txn/fileEffects.ts", coreSrcUrl).href);
+
+  // swap profile: the app IS the process. The probe verifies the
+  // experiment's bytes actually start (headless --probe run); a new
+  // version that fails to start makes the transaction roll back.
+  const host = {
+    async quiesce() {},
+    async stop() {},
+    async start() {},
+    async healthProbe() {
+      const experiment = path.join(STATE_DIR, "slots", "experiment", "artifact.bin");
+      if (fs.existsSync(experiment)) {
+        const r = spawnSync(process.execPath, [experiment, "--probe"], { encoding: "utf8", timeout: 5000 });
+        if (r.status !== 0) {
+          throw new Error("experiment artifact failed to start (status " + r.status + ")");
+        }
+        // The evidence belongs to the process that answered: the headless
+        // probe run, a fresh incarnation each time.
+        return { version: r.stdout.trim(), pid: r.pid, startId: r.pid + "-" + process.hrtime.bigint().toString(36) };
+      }
+      return { version: VERSION, pid: process.pid, startId };
+    },
+    async resume() {},
+  };
+
+  // K verifies integrity (sha256) but not authenticity: it does not check who
+  // produced these bytes (design-v1 §L0.5). For a real product that decision
+  // belongs to the adopter, in code like this one -- never to an option on the
+  // source and never to a field in the manifest, which is served by the very
+  // party such a check would exist to distrust.
+  const source = staticManifestSource({ baseUrl: RELEASE_BASE });
+
+  const upgrader = createRunner({
+    host,
+    source,
+    policy: process.env.K_POLICY ?? "auto",
+    notificationSink: async (ev) => {
+      const ver = ev.detail.version !== undefined ? " v" + ev.detail.version : "";
+      const reason = ev.detail.reason !== undefined ? ": " + ev.detail.reason : "";
+      fs.writeSync(2, "notify " + ev.kind + ver + reason + "\\n");
+    },
+    stateDir: STATE_DIR,
+  });
+
+  const outcome = await upgrader.upgrade();
+  await finish(outcome, upgrader, { slotArtifactPath, atomicWriteFile });
+}
+
+/** Continue a policy=confirm flow AFTER the user approved the offered
+ * version: the consent WAS the gate; the version stays bound (the source
+ * must still serve it, or the continuation refuses). */
+async function confirmUpgrade(version) {
+  if (!version) { fs.writeSync(2, "confirm upgrade <version>\\n"); process.exit(2); }
+  if (!RELEASE_BASE) { fs.writeSync(2, "K_RELEASE_BASE not set\\n"); process.exit(2); }
+  if (!CORE_UPGRADER) { fs.writeSync(2, "K_CORE_UPGRADER not set (the example's @k-carrier/core wiring)\\n"); process.exit(2); }
+  const coreSrcUrl = new URL(".", CORE_UPGRADER).href;
+  const { createRunner } = await import(CORE_UPGRADER);
+  const { staticManifestSource } = await import(new URL("artifact/staticManifestSource.ts", coreSrcUrl).href);
+  const { atomicWriteFile } = await import(new URL("artifact/swap.ts", coreSrcUrl).href);
+  const { slotArtifactPath } = await import(new URL("txn/fileEffects.ts", coreSrcUrl).href);
+  const host = {
+    async quiesce() {},
+    async stop() {},
+    async start() {},
+    async healthProbe() {
+      const experiment = path.join(STATE_DIR, "slots", "experiment", "artifact.bin");
+      if (fs.existsSync(experiment)) {
+        const r = spawnSync(process.execPath, [experiment, "--probe"], { encoding: "utf8", timeout: 5000 });
+        if (r.status !== 0) throw new Error("experiment artifact failed to start");
+        return { version: r.stdout.trim(), pid: r.pid, startId: r.pid + "-" + process.hrtime.bigint().toString(36) };
+      }
+      return { version: VERSION, pid: process.pid, startId };
+    },
+    async resume() {},
+  };
+  const upgrader = createRunner({
+    host,
+    source: staticManifestSource({ baseUrl: RELEASE_BASE }),
+    policy: "confirm",
+    notificationSink: async (ev) => {
+      const ver = ev.detail.version !== undefined ? " v" + ev.detail.version : "";
+      fs.writeSync(2, "notify " + ev.kind + ver + "\\n");
+    },
+    stateDir: STATE_DIR,
+  });
+  const outcome = await upgrader.upgradeTo(version, { consented: true });
+  await finish(outcome, upgrader, { slotArtifactPath, atomicWriteFile });
+}
+
+async function finish(outcome, upgrader, helpers) {
+  if (outcome.result === "promoted") {
+    // install step: swap the promoted slot's bytes over ourselves
+    const promoted = fs.readFileSync(helpers.slotArtifactPath(STATE_DIR, "stable"));
+    await helpers.atomicWriteFile(process.argv[1], promoted);
+    const st = await upgrader.state();
+    fs.writeSync(1, "upgraded to " + st.stableVersion + "\\n");
+    process.exit(0);
+  }
+  if (outcome.result === "rolled-back") {
+    fs.writeSync(1, "rolled back: " + outcome.reason + "\\n");
+    process.exit(1);
+  }
+  if (outcome.result === "held") {
+    fs.writeSync(1, "held: " + outcome.reason + "\\n");
+    process.exit(0);
+  }
+  fs.writeSync(1, "up to date\\n");
+  process.exit(0);
+}
+`;

package/harness/src/fixtures/externalCrashAdapter.ts

@@ -0,0 +1,19 @@
+/** Fixture: pause the external runner AFTER stop completed, before start. */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { createOptions } from "../../../examples/external-service/adapter.ts";
+import { createRunner } from "../../../core/src/index.ts";
+export default function create() {
+  const options = createOptions();
+  const stop = options.host.stop;
+  options.host.stop = async (slot) => {
+    await stop(slot);
+    const dir = path.dirname(options.stateDir);
+    if (slot === "stable" && await fs.stat(path.join(dir, "pause")).then(() => true, () => false)) {
+      await fs.writeFile(path.join(dir, "stopped"), String(process.pid));
+      for (;;) await sleep(100);
+    }
+  };
+  return createRunner(options);
+}

package/harness/src/fixtures/managedHost.ts

@@ -0,0 +1,100 @@
+/** Internal host fixture for session ledger preservation and live probe checks.
+ * This deliberately uses the harness HostDriver contract; it is not a product
+ * integration example. See examples/external-service for application wiring.
+ */
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import type { ProcessEvidence, Slot } from "../../../core/src/lifecycle/hostAdapter.ts";
+import type { HostDriver, LedgerState } from "../fake-host/inproc.ts";
+
+const SESSION_FILE = "session.bin";
+
+export function createManagedHost(stateDir: string): HostDriver {
+  let counter = 0;
+  let checksum: Uint8Array = createHash("sha256").update("hosted-service-v1").digest();
+  let runningSlot: Slot | null = null;
+  let parked = false;
+  let incarnation = 0;
+  let currentStartId: string | null = null;
+
+  const sessionBytes = (): Uint8Array => {
+    const out = new Uint8Array(8 + 32);
+    new DataView(out.buffer).setBigUint64(0, BigInt(counter), false);
+    out.set(checksum, 8);
+    return out;
+  };
+
+  const writeSession = async (): Promise<void> => {
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.writeFile(path.join(stateDir, SESSION_FILE), sessionBytes());
+  };
+
+  return {
+    async quiesce() {
+      if (parked) return; // idempotent
+      if (!runningSlot) throw new Error("quiesce: no running slot");
+      parked = true;
+      await writeSession(); // durable park
+    },
+    async stop(slot: Slot) {
+      if (runningSlot !== slot) throw new Error(`stop: ${slot} is not the running slot`);
+      runningSlot = null;
+    },
+    async start(slot: Slot) {
+      if (runningSlot !== null) throw new Error(`start: ${runningSlot} already running`);
+      runningSlot = slot;
+      incarnation += 1;
+      currentStartId = `managed-inc:${incarnation}`;
+    },
+    async healthProbe(): Promise<ProcessEvidence> {
+      if (!runningSlot) throw new Error("probe: no running slot");
+      if (!currentStartId) throw new Error("probe: no startId");
+      return {
+        version: runningSlot === "stable" ? "1.0.0" : "2.0.0",
+        pid: process.pid,
+        startId: currentStartId,
+      };
+    },
+    async resume() {
+      if (!parked) throw new Error("resume: not quiesced");
+      parked = false;
+      // restore the session state from the parked file, byte-for-byte
+      const raw = new Uint8Array(await fs.readFile(path.join(stateDir, SESSION_FILE)));
+      counter = Number(new DataView(raw.buffer, raw.byteOffset, raw.byteLength).getBigUint64(0, false));
+      checksum = raw.slice(8);
+    },
+    get running(): Slot | null {
+      return runningSlot;
+    },
+    get parked(): boolean {
+      return parked;
+    },
+    get startId(): string | null {
+      return currentStartId;
+    },
+    async doWork(n: number) {
+      if (parked) throw new Error("sessions are parked (quiesced)");
+      if (!runningSlot) throw new Error("doWork: no running slot");
+      for (let i = 0; i < n; i++) {
+        counter += 1;
+        checksum = createHash("sha256").update(be64(counter)).update(checksum).digest();
+      }
+      await writeSession();
+    },
+    async ledger(): Promise<Uint8Array> {
+      return new Uint8Array(await fs.readFile(path.join(stateDir, SESSION_FILE)));
+    },
+    async ledgerState(): Promise<LedgerState> {
+      return { counter, checksum };
+    },
+  };
+}
+
+function be64(n: number): Uint8Array {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, BigInt(n), false);
+  return out;
+}
+
+export default createManagedHost;

package/harness/src/fixtures/serviceSource.ts

@@ -0,0 +1,181 @@
+/** Internal service fixture: an external driver owns upgrade/recovery.
+ * The resident role only serves probe/exit and never runs K.
+ */
+export const PLAIN_DAEMON_SOURCE = `#!/usr/bin/env node
+// Internal service fixture built by ArtifactFactory.
+"use strict";
+const VERSION = "__K_VERSION__";
+const BEHAVIOR = "__K_BEHAVIOR__";
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const RELEASE_BASE = process.env.K_RELEASE_BASE;
+const STATE_DIR = process.env.K_STATE_DIR ?? path.join(path.dirname(process.argv[1]), "state");
+const CORE_UPGRADER = process.env.K_CORE_UPGRADER;
+const args = process.argv.slice(2);
+const startId = process.pid + "-" + process.hrtime.bigint().toString(36);
+const INCARNATION_FILE = path.join(STATE_DIR, "incarnation.json");
+
+function wsync(s, m) { fs.writeSync(s, m + "\\n"); }
+function readIncarnation() {
+  try { return JSON.parse(fs.readFileSync(INCARNATION_FILE, "utf8")); } catch { return null; }
+}
+function writeIncarnation() {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  fs.writeFileSync(INCARNATION_FILE, JSON.stringify({ version: VERSION, pid: process.pid, startId }));
+}
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+async function waitDead(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (processAlive(pid)) {
+    if (Date.now() > deadline) throw new Error("pid " + pid + " still alive after " + timeoutMs + "ms");
+    await sleep(10);
+  }
+}
+function readLine(child, prefix, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    const timer = setTimeout(() => { cleanup(); reject(new Error("timed out waiting for \\"" + prefix + "\\" from service")); }, timeoutMs);
+    const onData = (chunk) => {
+      buffer += chunk.toString("utf8");
+      // Only COMPLETE lines (newline-terminated) are protocol messages; a
+      // partial chunk must never be mistaken for a full one (truncated JSON).
+      for (;;) {
+        const nl = buffer.indexOf("\\n");
+        if (nl === -1) break;
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        if (line.startsWith(prefix + " ")) {
+          cleanup();
+          resolve(line.slice(prefix.length + 1));
+          return;
+        }
+      }
+    };
+    const cleanup = () => { clearTimeout(timer); child.stdout?.off("data", onData); };
+    child.stdout?.on("data", onData);
+  });
+}
+/** Wait for the ready line; null if the child died or never became ready. */
+async function tryReady(child, timeoutMs) {
+  try { return JSON.parse(await readLine(child, "ready", timeoutMs)); }
+  catch { return null; }
+}
+
+(async () => {
+  if (args[0] === "--version") {
+    wsync(1, VERSION);
+    process.exit(0);
+  }
+  if (args[0] === "self" && (args[1] === "upgrade" || args[1] === "recover")) {
+    try {
+      await selfUpgrade();
+    } catch (e) {
+      wsync(2, String(e));
+      process.exit(5);
+    }
+    return;
+  }
+  // ---- SERVICE role ----
+  if (BEHAVIOR === "crash-on-start") { wsync(2, "service-daemon crashed"); process.exit(1); }
+  writeIncarnation();
+  wsync(1, "ready " + JSON.stringify({ version: VERSION, pid: process.pid, startId }));
+  process.stdin.on("data", (chunk) => {
+    for (const line of chunk.toString("utf8").split("\\n")) {
+      const cmd = line.trim();
+      if (cmd === "probe") {
+        wsync(1, "evidence " + JSON.stringify({ version: VERSION, pid: process.pid, startId }));
+      } else if (cmd === "exit") {
+        process.exit(0);
+      }
+    }
+  });
+  setInterval(() => {}, 1 << 30);
+})();
+
+async function selfUpgrade() {
+  if (!RELEASE_BASE) { wsync(2, "K_RELEASE_BASE not set"); process.exit(2); }
+  if (!CORE_UPGRADER) { wsync(2, "K_CORE_UPGRADER not set"); process.exit(2); }
+  const coreSrcUrl = new URL(".", CORE_UPGRADER).href;
+  const { createRunner } = await import(CORE_UPGRADER);
+  const { staticManifestSource } = await import(new URL("artifact/staticManifestSource.ts", coreSrcUrl).href);
+
+  // The external driver starts and probes each replacement itself.
+  let requested = false;
+  let successor = null;
+  const host = {
+    async quiesce() {}, // service profile hosts no workloads
+    async stop() {
+      if (process.env.K_STUCK_DRIVER === "1") {
+        // Force a host-call timeout; a fresh external driver owns recovery.
+        await new Promise(() => {});
+      }
+      const inc = readIncarnation();
+      if (inc && inc.pid !== process.pid) {
+        try { process.kill(inc.pid, "SIGKILL"); } catch { /* already gone */ }
+        await waitDead(inc.pid, 5000);
+      }
+    },
+    async start(slot) {
+      requested = true;
+      const artifact = path.join(STATE_DIR, "slots", slot, "artifact.bin");
+      if (!fs.existsSync(artifact)) throw new Error("slot " + slot + " has no artifact");
+      const child = spawn(process.execPath, [artifact], {
+        env: { ...process.env, K_STATE_DIR: STATE_DIR },
+        stdio: ["pipe", "pipe", "ignore"],
+        detached: true,
+      });
+      child.unref(); // the service outlives the driver
+      const info = await tryReady(child, 5000);
+      successor = info === null ? null : { child, ...info };
+    },
+    async healthProbe() {
+      if (requested) {
+        // the successor must answer; silence or a dead child is a failure
+        if (successor === null || successor.child.exitCode !== null) {
+          throw new Error("no live successor to probe");
+        }
+        successor.child.stdin.write("probe\\n");
+        const line = await readLine(successor.child, "evidence", 5000);
+        return JSON.parse(line);
+      }
+      const inc = readIncarnation();
+      if (!inc) throw new Error("no registered service to probe");
+      return inc; // the app's own record of the incarnation being replaced
+    },
+    async resume() {},
+  };
+
+  const upgrader = createRunner({
+    host,
+    source: staticManifestSource({ baseUrl: RELEASE_BASE }),
+    policy: "auto",
+    notificationSink: async (ev) => {
+      const reason = ev.detail.reason !== undefined ? ": " + ev.detail.reason : "";
+      wsync(2, "notify " + ev.kind + reason);
+    },
+    stateDir: STATE_DIR,
+  });
+
+  if (args[1] === "recover") { await upgrader.recover(); process.exit(0); }
+  const outcome = await upgrader.upgrade();
+  if (outcome.result === "promoted") {
+    const st = await upgrader.state();
+    wsync(1, "upgraded to " + st.stableVersion);
+    process.exit(0);
+  }
+  if (outcome.result === "rolled-back") {
+    wsync(1, "rolled back: " + outcome.reason);
+    process.exit(1);
+  }
+  if (outcome.result === "held") {
+    wsync(1, "held: " + outcome.reason);
+    process.exit(0);
+  }
+  wsync(1, "up to date");
+  process.exit(0);
+}
+`;

package/harness/src/fixtures/supervisedAdapter.ts

@@ -0,0 +1,57 @@
+/** Fault injection around real production host calls; used only by process tests. */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { createOptions } from "../../../examples/external-service/adapter.ts";
+import { createRunner } from "../../../core/src/index.ts";
+const hang = async (): Promise<never> => { for (;;) await sleep(100); };
+export default function create() {
+  const options = createOptions();
+  const dir = path.dirname(options.stateDir);
+  const faultPath = path.join(dir, "fault");
+  const fault = () => fs.readFile(faultPath, "utf8").catch(() => "");
+  const stop = options.host.stop;
+  options.host.stop = async (slot) => {
+    if (slot === "stable" && await fault() === "external-controller") {
+      await fs.writeFile(path.join(dir, "needs-controller"), String(process.pid));
+      return hang();
+    }
+    await stop(slot);
+    const mode = await fault();
+    if (slot === "stable" && ["stop-crash", "stop-hang", "recovery-hang"].includes(mode)) {
+      await fs.writeFile(path.join(dir, "stopped"), String(process.pid));
+      if (mode === "stop-hang") return hang();
+      process.exit(77);
+    }
+  };
+  let attempting = false;
+  const resume = options.host.resume;
+  options.host.resume = async () => {
+    if (attempting && await fault() === "resume-once") {
+      await fs.unlink(faultPath);
+      await fs.writeFile(path.join(dir, "resuming"), String(process.pid));
+      return hang();
+    }
+    return resume();
+  };
+  const fence = options.host.fence!;
+  options.host.fence = async () => {
+    await fs.writeFile(path.join(dir, "fence-attempt"), String(process.pid));
+    if (await fault() === "recovery-hang" && await fs.stat(path.join(dir, "stopped")).then(() => true, () => false)) return hang();
+    return fence();
+  };
+  const fetch = options.source.fetchRelease;
+  options.source.fetchRelease = async (version) => {
+    attempting = true;
+    await fs.appendFile(path.join(dir, "fetches"), `${version}\n`);
+    return fetch(version);
+  };
+  const runner = createRunner(options);
+  const upgradeTo = runner.upgradeTo;
+  runner.upgradeTo = async (...args) => {
+    const outcome = await upgradeTo(...args);
+    if (await fault() === "report-crash") { await fs.unlink(faultPath); process.exit(78); }
+    return outcome;
+  };
+  return runner;
+}

package/harness/src/scenario/processScan.ts

@@ -43,7 +43,9 @@ export function findPidsByMarkerToken(name: string, value: string): number[] {
     }
     return pids;
   }
-  const out = execFileSync("ps", ["eaxo", "pid=,command="], { encoding: "utf8" });
+  // `e` appends every process's environment; on a busy machine that exceeds
+  // execFileSync's 1 MiB default and fails with ENOBUFS. Same bound as Windows.
+  const out = execFileSync("ps", ["eaxo", "pid=,command="], { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
   const pids: number[] = [];
   for (const line of out.split("\n")) {
     if (!line.includes(token)) continue;

package/harness/src/scenario/sandbox.ts

@@ -134,8 +134,8 @@ const SANDBOX_DIR_PREFIX = "k-harness-";
 /**
  * The marker a process must carry to be found by this sandbox's teardown.
  *
- * Teeth often derive a NESTED context (e.g. `<sandbox>/respawn` per host
- * shape). Taking basename() of that nested dir yields "respawn", which no
+ * Teeth often derive a NESTED context (e.g. `<sandbox>/service` per host
+ * shape). Taking basename() of that nested dir yields "service", which no
  * teardown scan will ever match -- so the scan returns zero, the tooth reports
  * a clean teardown, and the leaked process is still running. The zero means
  * "the query matched nothing", not "nothing leaked". (Found 08-05 by looking

package/harness/src/teeth/artifact.ts

@@ -145,14 +145,14 @@ registerTooth({
 });
 
 registerTooth({
-  id: "m3.stuck-driver-evidence-recovery",
+  id: "m3.stuck-driver-rollback-recovery",
   profiles: ["service"],
   layers: ["L0", "L1", "L2", "L3"],
   kind: { kind: "invariant" },
   mustRed: [
     {
-      mutate: "the successor decides the handover by a flag, not by evidence (or never recovers at all)",
-      caughtOnlyBy: "this", // only this tooth wedges the driver and demands evidence-based recovery
+      mutate: "the external driver skips recovery and leaves interrupted work unresolved",
+      caughtOnlyBy: "this", // only this tooth wedges the driver and demands external rollback recovery
     },
   ],
   run: checkM3StuckDriverEvidence,

package/harness/src/teeth/examples.ts

@@ -1,6 +1,6 @@
 /**
  * Examples teeth — each demo is the credential for its profile's support
- * claim (examples/README.md). Registration site only; check bodies live in
+ * claim (harness/src/fixtures/README.md). Registration site only; check bodies live in
  * harness/src/examples/checks.ts.
  */
 import { registerTooth } from "./registry.ts";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@botiverse/k-carrier",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "packageManager": "pnpm@11.18.0",
-  "description": "A fail-closed upgrade carrier for long-running managed services: two-slot upgrade transactions (promote/rollback), host-driven quiesce/resume handoff, and post-upgrade convergence read-back.",
+  "description": "Reliable application upgrades run by an independent installer: two-slot transactions with promote/rollback, a durable journal, live readback, and bounded crash recovery for self-distributed services.",
   "repository": {
     "type": "git",
     "url": "https://github.com/botiverse/k-carrier"
@@ -37,10 +37,12 @@
     "lint": "oxlint --deny-warnings core harness examples",
     "ratchet": "bash scripts/ratchets.sh",
     "sim": "node harness/src/cli.ts sim",
-    "check": "pnpm typecheck && pnpm lint && pnpm ratchet && pnpm test"
+    "check": "pnpm typecheck && pnpm lint && pnpm ratchet && pnpm test",
+    "test:runner": "node --test --test-timeout=60000 \"core/src/runner/*.test.ts\" \"core/src/launcher/*.test.ts\" \"core/src/protocol/*.test.ts\" \"core/src/lifecycle/commandHost.test.ts\""
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
+    "esbuild": "0.28.2",
     "oxlint": "^1.0.0",
     "oxlint-tsgolint": "^7.0.2001",
     "typescript": "^5.6.0"