@botiverse/k-carrier 0.1.0

package/harness/src/sim/record.ts

@@ -0,0 +1,76 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import type { SimulationResult } from "./run.ts";
+
+interface FailureRecord {
+  seed: number;
+  failure: string;
+  replay: string;
+  transcriptSha256: string;
+}
+
+interface FailureCorpus {
+  formatVersion: 1;
+  failures: FailureRecord[];
+}
+
+/**
+ * Atomically merge failures into a replay corpus. There are deliberately no
+ * timestamps: the same failure set produces the same bytes.
+ */
+export async function recordFailures(filePath: string, results: readonly SimulationResult[]): Promise<number> {
+  const failures = results.filter(
+    (result): result is SimulationResult & { failure: string } => result.failure !== null,
+  );
+  if (failures.length === 0) return 0;
+
+  let existing: FailureCorpus = { formatVersion: 1, failures: [] };
+  try {
+    const parsed = JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+    if (isFailureCorpus(parsed)) existing = parsed;
+    else throw new Error("existing failure corpus has an unsupported shape");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+
+  const byKey = new Map(
+    existing.failures.map((failure) => [`${failure.seed}:${failure.transcriptSha256}`, failure] as const),
+  );
+  for (const result of failures) {
+    const record: FailureRecord = {
+      seed: result.seed,
+      failure: result.failure,
+      replay: result.replay,
+      transcriptSha256: result.transcriptSha256,
+    };
+    byKey.set(`${record.seed}:${record.transcriptSha256}`, record);
+  }
+  const corpus: FailureCorpus = {
+    formatVersion: 1,
+    failures: [...byKey.values()].toSorted(
+      (left, right) => left.seed - right.seed || left.transcriptSha256.localeCompare(right.transcriptSha256),
+    ),
+  };
+
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.tmp-${process.pid}`;
+  await fs.writeFile(temporary, `${JSON.stringify(corpus, null, 2)}\n`, "utf8");
+  await fs.rename(temporary, filePath);
+  return failures.length;
+}
+
+function isFailureCorpus(value: unknown): value is FailureCorpus {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { formatVersion?: unknown; failures?: unknown };
+  if (candidate.formatVersion !== 1 || !Array.isArray(candidate.failures)) return false;
+  return candidate.failures.every((failure) => {
+    if (typeof failure !== "object" || failure === null) return false;
+    const item = failure as Partial<FailureRecord>;
+    return (
+      typeof item.seed === "number" &&
+      typeof item.failure === "string" &&
+      typeof item.replay === "string" &&
+      typeof item.transcriptSha256 === "string"
+    );
+  });
+}

package/harness/src/sim/run.ts

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import { UpgradeEngine } from "../../../core/src/txn/engine.ts";
+import type { WorldSnapshot } from "../../../core/src/invariants.ts";
+import { emptyCoverage, type FaultCoverage } from "./scheduler.ts";
+import { SimWorld, type SimulationMutation } from "./world.ts";
+import { SimulationError } from "./error.ts";
+
+export interface SimulationResult {
+  seed: number;
+  scenario: "promote" | "predicate-rollback";
+  mutation: SimulationMutation | null;
+  status: "pass" | "fail";
+  restarts: number;
+  effects: number;
+  coverage: FaultCoverage;
+  final: WorldSnapshot;
+  failure: string | null;
+  replay: string;
+  trace: string[];
+  transcriptSha256: string;
+}
+
+export interface SimulationBatch {
+  mode: "sim";
+  seeds: number[];
+  results: SimulationResult[];
+  coverage: FaultCoverage;
+  summary: { pass: number; fail: number; total: number };
+  result: "pass" | "fail";
+}
+
+export interface RunSimulationOptions {
+  mutation?: SimulationMutation;
+  maxRestarts?: number;
+  faults?: boolean;
+}
+
+const TARGET = { version: "2.0.0", bytesRef: "sha256:simulated-target" };
+
+export async function runSimulation(
+  seed: number,
+  opts: RunSimulationOptions = {},
+): Promise<SimulationResult> {
+  const normalizedSeed = seed >>> 0;
+  const world = new SimWorld({
+    seed: normalizedSeed,
+    ...(opts.mutation ? { mutation: opts.mutation } : {}),
+    ...(opts.faults === undefined ? {} : { faults: opts.faults }),
+  });
+  const predicateRefuses = normalizedSeed % 5 === 0;
+  const maxRestarts = opts.maxRestarts ?? 128;
+  let restarts = 0;
+  let failure: string | null = null;
+
+  for (; restarts <= maxRestarts; restarts++) {
+    const engine = new UpgradeEngine({
+      effects: world.effects,
+      host: world.host,
+      clock: world.clock,
+      evaluatePredicates: () => world.evaluatePredicates(predicateRefuses),
+    });
+    try {
+      await engine.recover();
+      if (world.currentPhase === "promoted" || world.currentPhase === "rolled-back") {
+        const problem = world.terminalProblem();
+        if (problem !== null) {
+          failure = `SIM_TERMINAL_NOT_SETTLED: ${problem}`;
+        }
+        break;
+      }
+
+      // Nothing durable began (for example a crash before the first journal
+      // fsync): retry the requested transaction. Once anything is durable,
+      // recover() owns the outcome and will settle it instead.
+      if (world.durableEntries.length === 0) {
+        await engine.upgrade(TARGET);
+      } else {
+        failure = `SIM_RECOVERY_STALLED: recovery returned in phase ${world.currentPhase}`;
+        break;
+      }
+
+      const problem = world.terminalProblem();
+      if (problem !== null) failure = `SIM_TERMINAL_NOT_SETTLED: ${problem}`;
+      break;
+    } catch (err) {
+      if (err instanceof SimulationError) {
+        if (err.kind === "invariant") {
+          failure = err.message;
+          break;
+        }
+        world.reboot(err.message);
+        continue;
+      }
+      failure = `SIM_UNEXPECTED: ${(err as Error).stack ?? String(err)}`;
+      break;
+    }
+  }
+
+  if (failure === null && !world.isSettled()) {
+    failure =
+      restarts > maxRestarts
+        ? `SIM_LIVENESS_BUDGET: did not settle within ${maxRestarts} restarts`
+        : `SIM_NOT_SETTLED: ${world.terminalProblem() ?? `phase ${world.currentPhase}`}`;
+  }
+
+  const base = {
+    seed: normalizedSeed,
+    scenario: predicateRefuses ? ("predicate-rollback" as const) : ("promote" as const),
+    mutation: opts.mutation ?? null,
+    status: failure === null ? ("pass" as const) : ("fail" as const),
+    restarts,
+    effects: world.trace.filter((line) => /^\d+:/.test(line)).length,
+    coverage: world.coverage,
+    final: world.snapshot(),
+    failure,
+    replay: `k-harness sim --seed ${normalizedSeed} --json`,
+    trace: [...world.trace],
+  };
+  const transcriptSha256 = createHash("sha256").update(JSON.stringify(base)).digest("hex");
+  return { ...base, transcriptSha256 };
+}
+
+export async function runSimulationBatch(seeds: readonly number[]): Promise<SimulationBatch> {
+  if (seeds.length === 0) throw new Error("SIM_EMPTY_SEED_SET: at least one seed is required");
+  const results: SimulationResult[] = [];
+  const coverage = emptyCoverage();
+  for (const seed of seeds) {
+    const result = await runSimulation(seed);
+    results.push(result);
+    for (const key of Object.keys(coverage) as Array<keyof FaultCoverage>) {
+      coverage[key] += result.coverage[key];
+    }
+  }
+  const pass = results.filter((result) => result.status === "pass").length;
+  const fail = results.length - pass;
+  return {
+    mode: "sim",
+    seeds: results.map((result) => result.seed),
+    results,
+    coverage,
+    summary: { pass, fail, total: results.length },
+    result: fail === 0 ? "pass" : "fail",
+  };
+}
+
+export function replayBytes(result: SimulationResult): string {
+  return JSON.stringify(result);
+}

package/harness/src/sim/scheduler.ts

@@ -0,0 +1,72 @@
+import { SeededPrng } from "./prng.ts";
+
+export type EffectKind =
+  | "journal-write"
+  | "journal-fsync"
+  | "journal-read"
+  | "slot-read"
+  | "slot-write"
+  | "host"
+  | "predicate";
+
+export type FaultDecision =
+  | "none"
+  | "delay"
+  | "crash-before"
+  | "crash-after"
+  | "fail-before"
+  | "partial-write"
+  | "reorder-volatile";
+
+/** Counts are part of every simulation receipt: coverage is observable. */
+export type FaultCoverage = Record<FaultDecision, number>;
+
+export function emptyCoverage(): FaultCoverage {
+  return {
+    none: 0,
+    delay: 0,
+    "crash-before": 0,
+    "crash-after": 0,
+    "fail-before": 0,
+    "partial-write": 0,
+    "reorder-volatile": 0,
+  };
+}
+
+/**
+ * Seeded fault scheduler. Every effect asks once; no effect is invisible to
+ * the schedule. Journal writes additionally expose partial/reordered volatile
+ * tails. Those tails are never allowed to cross a successful fsync barrier.
+ */
+export class FaultScheduler {
+  private readonly prng: SeededPrng;
+  private readonly enabled: boolean;
+  readonly coverage = emptyCoverage();
+
+  constructor(seed: number, enabled = true) {
+    this.prng = new SeededPrng(seed);
+    this.enabled = enabled;
+  }
+
+  decide(kind: EffectKind): FaultDecision {
+    if (!this.enabled) {
+      this.coverage.none += 1;
+      return "none";
+    }
+    const roll = this.prng.below(100);
+    let decision: FaultDecision;
+    if (kind === "journal-write" && roll < 5) decision = "partial-write";
+    else if (kind === "journal-write" && roll < 9) decision = "reorder-volatile";
+    else if (roll < 16) decision = "crash-before";
+    else if (roll < 23) decision = "crash-after";
+    else if (roll < 29) decision = "fail-before";
+    else if (roll < 39) decision = "delay";
+    else decision = "none";
+    this.coverage[decision] += 1;
+    return decision;
+  }
+
+  delayMs(): number {
+    return 1 + this.prng.below(50);
+  }
+}

package/harness/src/sim/world.ts

@@ -0,0 +1,284 @@
+import { checkInvariants, type WorldSnapshot } from "../../../core/src/invariants.ts";
+import type {
+  HostAdapter,
+  ProcessEvidence,
+  Slot,
+} from "../../../core/src/lifecycle/hostAdapter.ts";
+import type { TxnEffects } from "../../../core/src/txn/effects.ts";
+import type { JournalEntry, TxnPhase } from "../../../core/src/txn/state.ts";
+import type { FaultCoverage } from "./scheduler.ts";
+import { EffectRuntime } from "./effectRuntime.ts";
+import { SimulationError } from "./error.ts";
+
+export type SimulationMutation =
+  | "drop-journal-durability"
+  | "skip-stable-stop"
+  | "skip-terminal-resume";
+
+interface PendingJournalWrite {
+  entry: JournalEntry;
+  shape: "complete" | "partial" | "reordered";
+}
+
+interface LiveProcess {
+  slot: Slot;
+  pid: number;
+  startId: string;
+  version: string;
+}
+
+export interface SimWorldOptions {
+  seed: number;
+  mutation?: SimulationMutation;
+  faults?: boolean;
+}
+
+/**
+ * Persistent, in-memory machine used by DST. It implements the production
+ * seams rather than a second transaction engine: UpgradeEngine is still the
+ * thing being exercised.
+ */
+export class SimWorld {
+  readonly mutation: SimulationMutation | undefined;
+  private readonly runtime: EffectRuntime;
+
+  private readonly durableJournal: JournalEntry[] = [];
+  private pendingJournal: PendingJournalWrite | null = null;
+  private readonly slots: Record<Slot, string | null> = {
+    stable: "1.0.0",
+    experiment: null,
+  };
+  private live: LiveProcess[] = [
+    { slot: "stable", pid: 1000, startId: "incarnation-1", version: "1.0.0" },
+  ];
+  private phase: TxnPhase = "idle";
+  private quiesced = false;
+  private nextPid = 1001;
+  private nextIncarnation = 2;
+
+  constructor(opts: SimWorldOptions) {
+    this.mutation = opts.mutation;
+    this.runtime = new EffectRuntime(opts.seed, opts.faults ?? true, (name) =>
+      this.assertInvariants(name),
+    );
+  }
+
+  get coverage(): FaultCoverage {
+    return this.runtime.coverage;
+  }
+
+  get trace(): string[] {
+    return this.runtime.trace;
+  }
+
+  get currentPhase(): TxnPhase {
+    return this.phase;
+  }
+
+  get isQuiesced(): boolean {
+    return this.quiesced;
+  }
+
+  get durableEntries(): readonly JournalEntry[] {
+    return this.durableJournal;
+  }
+
+  get slotState(): Readonly<Record<Slot, string | null>> {
+    return this.slots;
+  }
+
+  get liveProcesses(): readonly LiveProcess[] {
+    return this.live;
+  }
+
+  get clock() {
+    return this.runtime.clock;
+  }
+
+  readonly effects: TxnEffects = {
+    journal: {
+      appendAndSync: async (entry) => {
+        await this.runtime.effect(
+          `journal.write.${entry.intent}`,
+          "journal-write",
+          () => {
+            this.pendingJournal = { entry: cloneEntry(entry), shape: "complete" };
+          },
+          {
+            partial: () => {
+              this.pendingJournal = { entry: cloneEntry(entry), shape: "partial" };
+            },
+            reorder: () => {
+              this.pendingJournal = { entry: cloneEntry(entry), shape: "reordered" };
+            },
+          },
+        );
+        await this.runtime.effect(`journal.fsync.${entry.intent}`, "journal-fsync", () => {
+          const pending = this.pendingJournal;
+          if (pending === null || pending.shape !== "complete") {
+            throw new SimulationError(
+              "effect-failure",
+              `journal.fsync.${entry.intent}`,
+              `SIM_EFFECT_FAIL: journal.fsync.${entry.intent}: volatile tail is ${pending?.shape ?? "missing"}; refusing to acknowledge fsync`,
+            );
+          }
+          if (this.mutation !== "drop-journal-durability") {
+            this.durableJournal.push(cloneEntry(pending.entry));
+            this.phaseAfterDurableIntent(pending.entry.intent);
+          }
+          this.pendingJournal = null;
+        });
+      },
+      readAll: async () =>
+        this.runtime.effect("journal.read-all", "journal-read", () =>
+          this.durableJournal.map(cloneEntry),
+        ),
+    },
+    slots: {
+      stageExperiment: async (artifact) => {
+        await this.runtime.effect("slots.stage-experiment", "slot-write", () => {
+          this.slots.experiment = artifact.version;
+          this.phase = "staged";
+        });
+      },
+      slotVersions: async () =>
+        this.runtime.effect("slots.read-versions", "slot-read", () => ({ ...this.slots })),
+      promoteExperiment: async () => {
+        await this.runtime.effect("slots.promote-experiment", "slot-write", () => {
+          if (this.slots.experiment !== null) {
+            this.slots.stable = this.slots.experiment;
+            this.slots.experiment = null;
+            this.live = this.live.map((process) =>
+              process.slot === "experiment" ? { ...process, slot: "stable" } : process,
+            );
+          }
+          this.phase = "promoted";
+        });
+      },
+      clearExperiment: async () => {
+        await this.runtime.effect("slots.clear-experiment", "slot-write", () => {
+          this.slots.experiment = null;
+          this.live = this.live.filter((process) => process.slot !== "experiment");
+          this.phase = "rolled-back";
+        });
+      },
+    },
+  };
+
+  readonly host: HostAdapter = {
+    quiesce: async () => {
+      await this.runtime.effect("host.quiesce", "host", () => {
+        this.quiesced = true;
+      });
+    },
+    stop: async (slot) => {
+      await this.runtime.effect(`host.stop.${slot}`, "host", () => {
+        if (slot === "stable" && this.mutation === "skip-stable-stop") return;
+        this.live = this.live.filter((process) => process.slot !== slot);
+      });
+    },
+    start: async (slot) => {
+      await this.runtime.effect(`host.start.${slot}`, "host", () => {
+        const version = this.slots[slot];
+        if (version === null) throw new Error(`cannot start empty ${slot} slot`);
+        if (this.live.some((process) => process.slot === slot)) return; // idempotent
+        this.live.push({
+          slot,
+          version,
+          pid: this.nextPid++,
+          startId: `incarnation-${this.nextIncarnation++}`,
+        });
+      });
+    },
+    healthProbe: async (): Promise<ProcessEvidence> =>
+      this.runtime.effect("host.health-probe", "host", () => {
+        if (this.live.length === 0) throw new Error("no live process");
+        const process = this.live.at(-1)!;
+        return {
+          version: process.version,
+          pid: process.pid,
+          startId: process.startId,
+        };
+      }),
+    resume: async () => {
+      await this.runtime.effect("host.resume", "host", () => {
+        if (this.mutation !== "skip-terminal-resume") this.quiesced = false;
+      });
+    },
+  };
+
+  async evaluatePredicates(refuse: boolean): Promise<string | null> {
+    return this.runtime.effect("predicate.evaluate", "predicate", () =>
+      refuse ? "seed selected the rollback scenario" : null,
+    );
+  }
+
+  /** A process crash discards every non-fsync'd fragment and pending timer. */
+  reboot(reason: string): void {
+    const tail = this.pendingJournal?.shape ?? "none";
+    this.runtime.reboot(reason, tail);
+    this.pendingJournal = null;
+    this.assertInvariants("reboot");
+  }
+
+  snapshot(): WorldSnapshot {
+    return {
+      phase: this.phase,
+      slots: { ...this.slots },
+      liveProcesses: this.live.map((process) => ({ ...process })),
+      journalIntents: this.durableJournal.map((entry) => entry.intent),
+      workloadDigest: "workload-v1",
+      priorIncarnationStartId: "incarnation-1",
+      installOwnership: "self",
+    };
+  }
+
+  isSettled(): boolean {
+    const terminal = this.phase === "promoted" || this.phase === "rolled-back";
+    if (!terminal || this.slots.experiment !== null || this.quiesced) return false;
+    return (
+      this.live.length === 1 &&
+      this.live[0]!.slot === "stable" &&
+      this.live[0]!.version === this.slots.stable
+    );
+  }
+
+  terminalProblem(): string | null {
+    if (this.phase !== "promoted" && this.phase !== "rolled-back") {
+      return `phase ${this.phase} is not terminal`;
+    }
+    if (this.slots.experiment !== null) return `terminal phase left experiment ${this.slots.experiment}`;
+    if (this.quiesced) return "terminal phase left workloads quiesced";
+    if (this.live.length !== 1) return `terminal phase has ${this.live.length} live processes`;
+    const live = this.live[0]!;
+    if (live.slot !== "stable" || live.version !== this.slots.stable) {
+      return `terminal live process is ${live.slot}@${live.version}, stable is ${this.slots.stable}`;
+    }
+    return null;
+  }
+
+  private phaseAfterDurableIntent(intent: TxnPhase): void {
+    // staged/promoted/rolled-back are intents whose named slot action has not
+    // happened yet. The other intents describe an entered control phase.
+    if (intent === "handing-over" || intent === "running-experiment" || intent === "readback") {
+      this.phase = intent;
+    }
+  }
+
+  private assertInvariants(effectName: string): void {
+    const violations = checkInvariants(this.snapshot());
+    if (violations.length > 0) {
+      throw new SimulationError(
+        "invariant",
+        effectName,
+        `SIM_INVARIANT: after ${effectName}: ${violations
+          .map((violation) => `${violation.invariantId}: ${violation.reason}`)
+          .join("; ")}`,
+      );
+    }
+  }
+}
+
+function cloneEntry(entry: JournalEntry): JournalEntry {
+  return { ...entry, detail: { ...entry.detail } };
+}

package/harness/src/target.ts

@@ -0,0 +1,86 @@
+/**
+ * Black-box target — code-defined command declarations (harness-design
+ * §1.76 ②; final ruling: NO zero-config defaults, NO
+ * convention probing).
+ *
+ * `k.target.ts` (or `--target <path>`) MUST exist next to the binary,
+ * default-exporting a BlackBoxTarget with ALL command names explicitly
+ * declared. Missing = an immediate typed FAIL (BLACKBOX_TARGET_REQUIRED)
+ * that tells the adopter what to declare — the harness never guesses
+ * (`--version` / `self upgrade` are not implied).
+ *
+ * A wrong shape is a COMPILE-TIME error on the adopter's side via
+ * `satisfies BlackBoxTarget`; the harness also validates at load because
+ * a target that skips `satisfies` is only catchable at runtime (reported
+ * to the author).
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export interface BlackBoxTarget {
+  /** Declared version command args. REQUIRED — no implicit default. */
+  version: string[];
+  /** Declared self-upgrade command args. REQUIRED — no implicit default. */
+  selfUpgrade: string[];
+  /** Declared status command args (daemon/managed contract). Optional. */
+  status?: string[];
+  /** Extra env for the commands (the adopter's config surface). */
+  env?: Record<string, string>;
+}
+
+export const TARGET_FILE = "k.target.ts";
+
+export interface LoadedTarget {
+  target: BlackBoxTarget;
+  /** Absolute path of the loaded target file. */
+  path: string;
+}
+
+export async function loadTarget(opts: {
+  binDir: string;
+  /** Explicit --target <path>; defaults to <binDir>/k.target.ts. */
+  explicitPath?: string;
+}): Promise<LoadedTarget> {
+  const targetPath = opts.explicitPath ?? path.join(opts.binDir, TARGET_FILE);
+  try {
+    await fs.access(targetPath);
+  } catch {
+    throw new Error(
+      opts.explicitPath
+        ? `BLACKBOX_TARGET_REQUIRED: --target file not found: ${targetPath}`
+        : `BLACKBOX_TARGET_REQUIRED: ${TARGET_FILE} must exist next to the binary (${opts.binDir}) — declare version + selfUpgrade commands explicitly; the harness does not guess`,
+    );
+  }
+
+  let mod: { default?: unknown };
+  try {
+    mod = (await import(pathToFileURL(targetPath).href)) as { default?: unknown };
+  } catch (err) {
+    throw new Error(`BLACKBOX_TARGET_INVALID: could not load ${targetPath}: ${(err as Error).message}`, {
+      cause: err,
+    });
+  }
+
+  const declared = mod.default;
+  if (typeof declared !== "object" || declared === null) {
+    throw new Error(
+      `BLACKBOX_TARGET_INVALID: ${targetPath} must default-export an object (BlackBoxTarget); got ${typeof declared} — write "satisfies BlackBoxTarget" to catch this at compile time`,
+    );
+  }
+  const t = declared as BlackBoxTarget;
+  if (!isStringArray(t.version) || t.version.length === 0) {
+    throw new Error(`BLACKBOX_TARGET_INVALID: ${targetPath} must declare version: string[] (BlackBoxTarget)`);
+  }
+  if (!isStringArray(t.selfUpgrade) || t.selfUpgrade.length === 0) {
+    throw new Error(`BLACKBOX_TARGET_INVALID: ${targetPath} must declare selfUpgrade: string[] (BlackBoxTarget)`);
+  }
+  if (t.status !== undefined && !isStringArray(t.status)) {
+    throw new Error(`BLACKBOX_TARGET_INVALID: ${targetPath} status must be string[] (BlackBoxTarget)`);
+  }
+  return { target: t, path: targetPath };
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}