@botiverse/k-carrier 0.1.0

package/harness/src/crash/enumerate.ts

@@ -0,0 +1,66 @@
+/**
+ * Crash-point enumerator (harness-design §1.4) — the load-bearing piece.
+ *
+ * Coverage is GENERATED from the engine's transition table, never hand-listed.
+ * For every transition we crash at each durability-relevant instant:
+ *
+ *   before-journal : intent not yet durable -> recovery must see the OLD phase
+ *   after-journal  : intent durable, action NOT done -> recovery must finish or undo
+ *   after-action   : action done, before the next intent -> same obligation
+ *
+ * "after-journal" is the interesting one: it is precisely the window where a
+ * naive implementation loses track of what it was doing. Enumeration makes it
+ * impossible to forget, and the completeness tooth makes it impossible to add
+ * a transition without covering it.
+ */
+import { TRANSITIONS, type Transition } from "../../../core/src/txn/transitions.ts";
+
+export type CrashInstant = "before-journal" | "after-journal" | "after-action";
+
+export const CRASH_INSTANTS: readonly CrashInstant[] = [
+  "before-journal",
+  "after-journal",
+  "after-action",
+];
+
+export interface CrashPoint {
+  /** Stable id, e.g. "staged->handing-over@after-journal". */
+  id: string;
+  transition: Transition;
+  instant: CrashInstant;
+}
+
+/** The full matrix: every transition x every crash instant. */
+export function enumerateCrashPoints(
+  transitions: readonly Transition[] = TRANSITIONS,
+): CrashPoint[] {
+  const points: CrashPoint[] = [];
+  for (const transition of transitions) {
+    for (const instant of CRASH_INSTANTS) {
+      points.push({
+        id: `${transition.from}->${transition.to}@${instant}`,
+        transition,
+        instant,
+      });
+    }
+  }
+  return points;
+}
+
+/**
+ * Completeness accounting: the matrix must cover every transition in the
+ * table. Returns transitions that have no crash point (should always be
+ * empty; the tooth asserts it).
+ */
+export function uncoveredTransitions(
+  points: readonly CrashPoint[],
+  transitions: readonly Transition[] = TRANSITIONS,
+): Transition[] {
+  const covered = new Set(points.map((p) => `${p.transition.from}->${p.transition.to}`));
+  return transitions.filter((t) => !covered.has(`${t.from}->${t.to}`));
+}
+
+/** Crash points whose instant is not one of the declared instants (guards typos). */
+export function malformedPoints(points: readonly CrashPoint[]): CrashPoint[] {
+  return points.filter((p) => !CRASH_INSTANTS.includes(p.instant));
+}

package/harness/src/crash/runner.ts

@@ -0,0 +1,162 @@
+/**
+ * Crash runner — drives the REAL engine to an enumerated crash point, kills
+ * it there, then runs recovery on a fresh engine over the same durable state
+ * and asserts the invariants (harness-design §1.4).
+ *
+ * "Kill" is modelled by throwing from inside the effect at the chosen
+ * instant: the engine's in-memory state dies, only journaled/durable state
+ * survives — exactly what a kill -9 leaves behind. (The real-process tier
+ * repeats this against a spawned daemon; the logic tier runs every point
+ * cheaply and deterministically.)
+ */
+import { UpgradeEngine, type EngineDeps } from "../../../core/src/txn/engine.ts";
+import type { JournalEntry, TxnPhase } from "../../../core/src/txn/state.ts";
+import type { Slot, ProcessEvidence } from "../../../core/src/lifecycle/hostAdapter.ts";
+import { checkInvariants, type Violation, type WorldSnapshot } from "../../../core/src/invariants.ts";
+import type { CrashPoint } from "./enumerate.ts";
+
+class SimulatedCrash extends Error {
+  constructor(pointId: string) {
+    super(`simulated crash at ${pointId}`);
+    this.name = "SimulatedCrash";
+  }
+}
+
+interface DurableWorld {
+  journal: JournalEntry[];
+  slots: { stable: string | null; experiment: string | null };
+}
+
+export interface CrashRunResult {
+  point: CrashPoint;
+  crashed: boolean;
+  violationsAtCrash: Violation[];
+  violationsAfterRecovery: Violation[];
+  finalPhase: TxnPhase;
+}
+
+function snapshot(world: DurableWorld, live: WorldSnapshot["liveProcesses"]): WorldSnapshot {
+  const intents = world.journal.map((e) => e.intent);
+  return {
+    phase: intents.at(-1) ?? "idle",
+    slots: { ...world.slots },
+    liveProcesses: live,
+    journalIntents: intents,
+  };
+}
+
+/**
+ * Run one crash point end to end.
+ * targetPhase/instant decide where the injected failure fires.
+ */
+export async function runCrashPoint(point: CrashPoint): Promise<CrashRunResult> {
+  // Durable state survives the crash; in-memory engine state does not.
+  const world: DurableWorld = { journal: [], slots: { stable: "1.0.0", experiment: null } };
+  let live: WorldSnapshot["liveProcesses"] = [
+    { slot: "stable", pid: 100, startId: "s-100", version: "1.0.0" },
+  ];
+  let crashed = false;
+  let startCounter = 100;
+
+  const targetIntent = point.transition.to;
+  // A crash point on a rollback edge can only fire if the run actually
+  // rolls back, so drive predicates to refuse for those points.
+  const rollbackScenario = point.transition.to === "rolled-back";
+  const shouldCrash = (instant: CrashPoint["instant"], intent: TxnPhase): boolean =>
+    !crashed && intent === targetIntent && instant === point.instant;
+
+  const makeDeps = (armed: boolean): EngineDeps => ({
+    effects: {
+      journal: {
+        appendAndSync: async (entry) => {
+          if (armed && shouldCrash("before-journal", entry.intent)) {
+            crashed = true;
+            throw new SimulatedCrash(point.id);
+          }
+          world.journal.push(entry);
+          if (armed && shouldCrash("after-journal", entry.intent)) {
+            crashed = true;
+            throw new SimulatedCrash(point.id);
+          }
+        },
+        readAll: async () => [...world.journal],
+      },
+      slots: {
+        stageExperiment: async (a) => {
+          world.slots.experiment = a.version;
+          maybeCrashAfterAction("staged");
+        },
+        slotVersions: async () => ({ ...world.slots }),
+        promoteExperiment: async () => {
+          // Production slot adapters promise idempotent redo: terminal
+          // recovery may call promote again after the experiment was already
+          // moved into stable. The crash model must preserve that contract or
+          // it manufactures a brick by assigning null to stable on replay.
+          if (world.slots.experiment !== null) {
+            world.slots.stable = world.slots.experiment;
+            world.slots.experiment = null;
+          }
+          maybeCrashAfterAction("promoted");
+        },
+        clearExperiment: async () => {
+          world.slots.experiment = null;
+        },
+      },
+    },
+    host: {
+      quiesce: async () => {},
+      stop: async () => {
+        live = [];
+      },
+      start: async (slot: Slot) => {
+        startCounter += 1;
+        const version = world.slots[slot];
+        live = version === null ? [] : [{ slot, pid: startCounter, startId: `s-${startCounter}`, version }];
+        maybeCrashAfterAction(slot === "experiment" ? "handing-over" : "rolled-back");
+      },
+      healthProbe: async (): Promise<ProcessEvidence> => {
+        const p = live.at(0);
+        if (!p) throw new Error("no live process to probe");
+        const evidence = { version: p.version, pid: p.pid, startId: p.startId };
+        maybeCrashAfterAction("running-experiment");
+        return evidence;
+      },
+      resume: async () => {},
+    },
+    clock: { nowMs: () => world.journal.length, after: () => () => {} },
+    evaluatePredicates: async () => {
+      maybeCrashAfterAction("readback");
+      // Rollback edges are only reachable when predicates refuse; the
+      // scenario is chosen by the crash point being exercised.
+      return rollbackScenario ? "predicates refused (scenario)" : null;
+    },
+  });
+
+  function maybeCrashAfterAction(intent: TxnPhase): void {
+    if (shouldCrash("after-action", intent)) {
+      crashed = true;
+      throw new SimulatedCrash(point.id);
+    }
+  }
+
+  // Phase 1: run until the injected crash (or completion).
+  try {
+    await new UpgradeEngine(makeDeps(true)).upgrade({ version: "2.0.0", bytesRef: "ref" });
+  } catch (err) {
+    if (!(err instanceof SimulatedCrash)) throw err;
+  }
+  const violationsAtCrash = checkInvariants(snapshot(world, live));
+
+  // Phase 2: fresh process over the same durable state -> recover.
+  const recovered = new UpgradeEngine(makeDeps(false));
+  await recovered.recover();
+  const after = snapshot(world, live);
+
+  return {
+    point,
+    crashed,
+    violationsAtCrash,
+    violationsAfterRecovery: checkInvariants(after),
+    finalPhase: after.phase,
+  };
+}

package/harness/src/examples/checks.ts

@@ -0,0 +1,286 @@
+/**
+ * Examples acceptance checks — the run bodies of the demo teeth
+ * (registered in teeth/examples.ts). Each throws on violation.
+ *
+ * Each demo is the credential for its profile's support claim
+ * (examples/README.md: "if a profile has no green example, the claim does
+ * not exist"):
+ *  - swap-tool: black-box upgrade loop (L0/L0.5/L1') — version command,
+ *    self-upgrade swaps bytes, next run reports the served version;
+ *  - service-daemon: process-reality L2/L3 — real spawn, startId-bound
+ *    probe evidence, OS-confirmed stop, upgrade effective next spawn;
+ *  - hosted-service: adapter contract subset (§1.7) — session preservation
+ *    incl. after rollback + probe veracity/binding.
+ */
+import assert from "node:assert/strict";
+import * as path from "node:path";
+import { promises as fs } from "node:fs";
+import { spawn, type ChildProcess } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { type ToothContext } from "../teeth/registry.ts";
+import { ArtifactFactory, type Behavior } from "../artifact-factory/factory.ts";
+import { commandForArtifact, runCommand } from "../artifact-factory/run.ts";
+import { FakeServer } from "../fake-server/server.ts";
+import { sha256Hex } from "../fake-server/manifest.ts";
+import { processAlive } from "../fake-host/daemon.ts";
+import { currentPlatformKey } from "../../../core/src/artifact/staticManifestSource.ts";
+import {
+  checkLedgerEquivalence,
+  checkLedgerEquivalenceAfterRollback,
+  checkProbeVersionMatchesSlot,
+  checkProbeBindsCurrentIncarnation,
+} from "../fake-host/checks.ts";
+import type { HostDriver } from "../fake-host/inproc.ts";
+import { CLI_TOOL_SOURCE } from "../../../examples/swap-tool/source.ts";
+import { PLAIN_DAEMON_SOURCE } from "../../../examples/service-daemon/source.ts";
+
+const RELEASE_BASE_ENV = "K_RELEASE_BASE";
+
+/** The swap-tool's explicit target declaration (mirrors k.target.ts). */
+export const CLI_TOOL_TARGET_TS = `export default { version: ["--version"], selfUpgrade: ["self", "upgrade"] };
+`;
+
+async function buildDemoBinary(
+  ctx: ToothContext,
+  opts: { source: string; version: string; behavior: Behavior; name: string },
+): Promise<{ binPath: string }> {
+  const factory = new ArtifactFactory({
+    cacheDir: path.join(ctx.sandboxDir, "cache"),
+    demoSource: opts.source,
+  });
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "store") });
+  await server.start();
+  try {
+    const rel = await factory.makeRelease({
+      version: opts.version,
+      behavior: opts.behavior,
+      store: server.store,
+      platform: currentPlatformKey(),
+    });
+    const binDir = path.join(ctx.sandboxDir, "app");
+    await fs.mkdir(binDir, { recursive: true });
+    const binPath = path.join(binDir, opts.name);
+    await fs.writeFile(binPath, rel.artifactBytes, { mode: 0o755 });
+    return { binPath };
+  } finally {
+    await server.stop();
+  }
+}
+
+async function fileSha256(p: string): Promise<string> {
+  return sha256Hex(new Uint8Array(await fs.readFile(p)));
+}
+
+/** The swap-tool demo's @botiverse/k-carrier wiring (createUpgrader module URL). */
+function coreUpgraderUrl(): string {
+  return pathToFileURL(path.join(import.meta.dirname, "../../../core/src/createUpgrader.ts")).href;
+}
+
+// ---------------------------------------------------------------------------
+// swap-tool
+// ---------------------------------------------------------------------------
+
+export async function checkCliToolBlackbox(
+  ctx: ToothContext,
+  opts: { serveSameVersion?: boolean } = {},
+): Promise<void> {
+  const { binPath } = await buildDemoBinary(ctx, {
+    source: CLI_TOOL_SOURCE,
+    version: "1.0.0",
+    behavior: "ok",
+    name: "swap-tool",
+  });
+  await fs.writeFile(path.join(ctx.sandboxDir, "app", "k.target.ts"), CLI_TOOL_TARGET_TS);
+
+  // serve the target release
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "store2") });
+  await server.start();
+  const factory = new ArtifactFactory({
+    cacheDir: path.join(ctx.sandboxDir, "cache2"),
+    demoSource: CLI_TOOL_SOURCE,
+  });
+  try {
+    const targetVersion = opts.serveSameVersion ? "1.0.0" : "2.0.0";
+    await factory.makeRelease({ version: targetVersion, behavior: "ok", store: server.store, platform: currentPlatformKey() });
+
+    const before = await fileSha256(binPath);
+    const v1 = await runCommand(binPath, ["--version"]);
+    assert.equal(v1.code, 0, `version command must exit 0 (${v1.stderr.trim()})`);
+    assert.equal(v1.stdout.trim(), "1.0.0");
+
+    const up = await runCommand(binPath, ["self", "upgrade"], {
+      env: {
+        [RELEASE_BASE_ENV]: server.url,
+        K_CORE_UPGRADER: coreUpgraderUrl(),
+      },
+    });
+    assert.equal(up.code, 0, `self upgrade must exit 0 (${up.stderr.trim()})`);
+    const after = await fileSha256(binPath);
+    assert.notEqual(after, before, "self upgrade must change the binary bytes on disk");
+
+    const v2 = await runCommand(binPath, ["--version"]);
+    assert.equal(v2.code, 0);
+    assert.equal(v2.stdout.trim(), targetVersion, "next run must report the served version");
+
+    // the app's real command still works on the new version
+    const greet = await runCommand(binPath, ["greet", "K"]);
+    assert.equal(greet.code, 0);
+    assert.match(greet.stdout, new RegExp(`Hello, K! \\(v${targetVersion}\\)`));
+  } finally {
+    await server.stop();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// service-daemon
+// ---------------------------------------------------------------------------
+
+function readLine(child: ChildProcess, prefix: string, timeoutMs = 5000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`timed out waiting for "${prefix}" from service-daemon`));
+    }, timeoutMs);
+    const onData = (chunk: Buffer): void => {
+      buffer += chunk.toString("utf8");
+      for (const line of buffer.split("\n")) {
+        if (line.startsWith(`${prefix} `)) {
+          cleanup();
+          resolve(line.slice(prefix.length + 1));
+          return;
+        }
+      }
+    };
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      child.stdout?.off("data", onData);
+    };
+    child.stdout?.on("data", onData);
+  });
+}
+
+async function waitDead(pid: number, timeoutMs = 5000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (processAlive(pid)) {
+    if (Date.now() > deadline) throw new Error(`pid ${pid} still alive`);
+    await new Promise((r) => {
+      setTimeout(r, 10);
+    });
+  }
+}
+
+function spawnDaemon(binPath: string): { child: ChildProcess; pid: number } {
+  // Windows cannot spawn a shebang artifact directly (see commandForArtifact).
+  const routed = commandForArtifact(binPath, []);
+  const child = spawn(routed.cmd, routed.args, { stdio: ["pipe", "pipe", "ignore"] });
+  if (!child.pid) throw new Error("daemon did not get a pid");
+  return { child, pid: child.pid };
+}
+
+export async function checkPlainDaemonContract(
+  ctx: ToothContext,
+  opts: { behavior?: Behavior } = {},
+): Promise<void> {
+  const { binPath } = await buildDemoBinary(ctx, {
+    source: PLAIN_DAEMON_SOURCE,
+    version: "1.0.0",
+    behavior: opts.behavior ?? "ok",
+    name: "service-daemon",
+  });
+
+  // 1) process-reality lifecycle: spawn -> probe -> stop, OS-confirmed dead
+  const { child, pid } = spawnDaemon(binPath);
+  try {
+    const ready = JSON.parse(await readLine(child, "ready")) as {
+      version: string;
+      pid: number;
+      startId: string;
+    };
+    assert.equal(ready.version, "1.0.0");
+    assert.equal(ready.pid, pid);
+    assert.ok(processAlive(pid), "OS must report the daemon alive after start");
+
+    child.stdin?.write("probe\n");
+    const evidence = JSON.parse(await readLine(child, "evidence")) as {
+      version: string;
+      pid: number;
+      startId: string;
+    };
+    assert.equal(evidence.version, "1.0.0", "probe must report the running version");
+    assert.equal(evidence.pid, pid, "evidence must bind the live pid");
+    assert.equal(evidence.startId, ready.startId, "evidence must bind the current incarnation");
+
+    child.stdin?.write("exit\n");
+    await waitDead(pid);
+    assert.ok(!processAlive(pid), "stop must leave the daemon OS-dead");
+  } finally {
+    if (processAlive(pid)) child.kill("SIGKILL");
+  }
+
+  // 2) upgrade through core's Upgrader with the real service host: the new
+  // version becomes the RUNNING service (registered, alive), not a byte swap.
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "store2") });
+  await server.start();
+  const factory = new ArtifactFactory({
+    cacheDir: path.join(ctx.sandboxDir, "cache2"),
+    demoSource: PLAIN_DAEMON_SOURCE,
+  });
+  try {
+    await factory.makeRelease({
+      version: "2.0.0",
+      behavior: "ok",
+      store: server.store,
+      platform: currentPlatformKey(),
+    });
+    const stateDir = path.join(ctx.sandboxDir, "app", "state");
+    const up = await runCommand(binPath, ["self", "upgrade"], {
+      env: {
+        [RELEASE_BASE_ENV]: server.url,
+        K_CORE_UPGRADER: coreUpgraderUrl(),
+        K_STATE_DIR: stateDir,
+        K_HOST_SHAPE: "spawn",
+      },
+      timeoutMs: 30000,
+    });
+    assert.equal(up.code, 0, `self upgrade must exit 0 (${up.stderr.trim()})`);
+
+    // the running service is now the new version, registered and alive
+    const inc = JSON.parse(
+      await fs.readFile(path.join(stateDir, "incarnation.json"), "utf8"),
+    ) as { version: string; pid: number };
+    assert.equal(inc.version, "2.0.0", "the running service must be the new version");
+    assert.ok(processAlive(inc.pid), "the upgraded service must be alive");
+    try {
+      process.kill(inc.pid, "SIGKILL");
+    } catch {
+      // already gone
+    }
+    await waitDead(inc.pid);
+  } finally {
+    await server.stop();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// hosted-service
+// ---------------------------------------------------------------------------
+
+export async function checkManagedHostAdapter(
+  ctx: ToothContext,
+  opts: { hostOverride?: () => HostDriver } = {},
+): Promise<void> {
+  // Each contract check needs a FRESH host (checks leave it running);
+  // hostOverride is a factory so known-red can inject a broken host.
+  const makeHost = async (): Promise<HostDriver> =>
+    opts.hostOverride
+      ? opts.hostOverride()
+      : (await import("../../../examples/hosted-service/host.ts")).createManagedHost(
+          path.join(ctx.sandboxDir, "host"),
+        );
+  // the same contract subset k-harness --adapter runs (§1.7)
+  await checkLedgerEquivalence(ctx, { host: await makeHost() });
+  await checkLedgerEquivalenceAfterRollback(ctx, { host: await makeHost() });
+  await checkProbeVersionMatchesSlot(ctx, { host: await makeHost() });
+  await checkProbeBindsCurrentIncarnation(ctx, { host: await makeHost() });
+}