@botiverse/k-carrier 0.1.0

package/harness/src/fake-host/checks.ts

@@ -0,0 +1,188 @@
+/**
+ * fake-host acceptance checks — run bodies of the fake-host teeth
+ * (registered in teeth/fakeHost.ts), and the contract subset the
+ * `k-harness --adapter` mode reuses. Each throws on violation.
+ *
+ * Every check runs the NORMAL HostAdapter contract with faults OFF; a fault
+ * switch turned ON must turn the check red (the tooth "catches" the fault),
+ * and with the switch OFF the tooth is green — proving the tooth tests the
+ * fault, not the norm (harness-design §1.1).
+ *
+ * The ledger equivalence (incl. after rollback) is the decidable form of
+ * the managed profile's "session preservation": quiesce parks a
+ * deterministic counter+checksum ledger durably, resume must reproduce it
+ * byte-for-byte.
+ *
+ * Checks accept an injected host (adapter mode): the ledger checks need
+ * the workload driver (doWork/ledger/ledgerState); an adapter without one
+ * gets those checks marked na by the runner.
+ */
+import assert from "node:assert/strict";
+import * as path from "node:path";
+import { type ToothContext } from "../teeth/registry.ts";
+import { InprocFakeHost, type FakeHostFaults, type HostDriver, type InprocFakeHostOptions } from "./inproc.ts";
+import { VirtualClock } from "../scenario/virtualClock.ts";
+
+export interface ContractCheckOptions {
+  /** Fault switches for the default InprocFakeHost. Ignored when host is injected. */
+  faults?: FakeHostFaults;
+  /** Inject a host (adapter mode); default: fresh InprocFakeHost. */
+  host?: HostDriver;
+}
+
+function hostFor(ctx: ToothContext, opts: ContractCheckOptions): HostDriver {
+  if (opts.host) return opts.host;
+  const init: InprocFakeHostOptions = { stateDir: path.join(ctx.sandboxDir, "host") };
+  if (opts.faults !== undefined) init.faults = opts.faults;
+  return new InprocFakeHost(init);
+}
+
+/** Whether the host exposes the workload driver the ledger checks need. */
+export function hasWorkloadDriver(host: HostDriver): boolean {
+  return (
+    typeof host.doWork === "function" &&
+    typeof host.ledger === "function" &&
+    typeof host.ledgerState === "function"
+  );
+}
+
+export async function checkLedgerEquivalence(
+  ctx: ToothContext,
+  opts: ContractCheckOptions = {},
+): Promise<void> {
+  const host = hostFor(ctx, opts);
+  if (!hasWorkloadDriver(host)) throw new Error("ledger-equivalence requires a workload driver");
+  await host.start("stable");
+  await host.doWork!(3);
+  await host.quiesce();
+  const parked = await host.ledger!();
+  // A parked workload must not mutate the session.
+  await assert.rejects(host.doWork!(1), /parked/, "quiesced workload must not mutate the session");
+  await host.resume();
+  assert.deepEqual(
+    await host.ledger!(),
+    parked,
+    "ledger must be byte-identical across quiesce↔resume",
+  );
+  // Session continues from the parked counter.
+  await host.doWork!(1);
+  assert.equal(
+    (await host.ledgerState!()).counter,
+    4,
+    "resumed session must continue from the parked counter",
+  );
+}
+
+export async function checkLedgerEquivalenceAfterRollback(
+  ctx: ToothContext,
+  opts: ContractCheckOptions = {},
+): Promise<void> {
+  const host = hostFor(ctx, opts);
+  if (!hasWorkloadDriver(host)) {
+    throw new Error("ledger-equivalence-after-rollback requires a workload driver");
+  }
+  await host.start("stable");
+  await host.doWork!(2);
+  await host.quiesce();
+  const parked = await host.ledger!();
+  // Handover to the experiment slot, then roll back to stable.
+  await host.stop("stable");
+  await host.start("experiment");
+  const probe = await host.healthProbe();
+  assert.equal(probe.version, "2.0.0", "experiment slot must report its own version");
+  await host.stop("experiment");
+  await host.start("stable");
+  await host.resume();
+  assert.deepEqual(
+    await host.ledger!(),
+    parked,
+    "rolled-back resume must restore the parked ledger byte-for-byte",
+  );
+  await host.doWork!(1);
+  assert.equal(
+    (await host.ledgerState!()).counter,
+    3,
+    "session must continue after rolled-back resume",
+  );
+}
+
+export async function checkQuiesceCompletes(
+  ctx: ToothContext,
+  opts: ContractCheckOptions = {},
+): Promise<void> {
+  const host = hostFor(ctx, opts);
+  await host.start("stable");
+  await host.doWork?.(1);
+  await host.quiesce(); // fail-on-quiesce throws here -> red
+  assert.equal(host.parked, true);
+}
+
+export async function checkStopCompletes(
+  ctx: ToothContext,
+  opts: ContractCheckOptions = {},
+): Promise<void> {
+  const injected = opts.host;
+  if (injected) {
+    // Adapter mode has no clock-window semantics: stop must simply settle.
+    await injected.start("stable");
+    await injected.stop("stable");
+    return;
+  }
+  const clock = new VirtualClock();
+  const init: InprocFakeHostOptions = {
+    stateDir: path.join(ctx.sandboxDir, "host"),
+    clock,
+  };
+  if (opts.faults !== undefined) init.faults = opts.faults;
+  const host = new InprocFakeHost(init);
+  await host.start("stable");
+  let done = false;
+  const p = host.stop("stable").then(() => {
+    done = true;
+  });
+  await Promise.resolve(); // let an immediate stop settle
+  clock.advance(1000); // the scenario window; a hanging stop stays pending
+  if (done) await p; // surface rejection only when it resolved
+  assert.equal(done, true, "stop must complete within the window");
+}
+
+export async function checkProbeVersionMatchesSlot(
+  ctx: ToothContext,
+  opts: ContractCheckOptions = {},
+): Promise<void> {
+  const host = hostFor(ctx, opts);
+  await host.start("stable");
+  const stableProbe = await host.healthProbe();
+  assert.equal(stableProbe.version, "1.0.0", "probe must report the stable slot's version");
+  await host.stop("stable");
+  await host.start("experiment");
+  const expProbe = await host.healthProbe();
+  assert.equal(expProbe.version, "2.0.0", "probe must report the experiment slot's version");
+}
+
+export async function checkProbeBindsCurrentIncarnation(
+  ctx: ToothContext,
+  opts: ContractCheckOptions = {},
+): Promise<void> {
+  const host = hostFor(ctx, opts);
+  await host.start("stable");
+  const first = await host.healthProbe();
+  await host.stop("stable");
+  await host.start("stable"); // new incarnation
+  const second = await host.healthProbe();
+  assert.notEqual(
+    second.startId,
+    first.startId,
+    "a new incarnation must have a fresh startId (anti-fake-green)",
+  );
+  assert.equal(second.startId, host.startId, "probe must report the CURRENT startId");
+}
+
+export async function checkStartCompletes(
+  ctx: ToothContext,
+  opts: ContractCheckOptions = {},
+): Promise<void> {
+  const host = hostFor(ctx, opts);
+  await host.start("stable"); // crash-during-start throws here -> red
+  assert.equal(host.running, "stable");
+}

package/harness/src/fake-host/daemon-entry.ts

@@ -0,0 +1,39 @@
+/**
+ * Real fake-daemon process entry (harness-design §1.1).
+ *
+ * Spawned as an actual OS process so kill -9, dual-run detection and probe
+ * liveness are tested against process reality — mocked crashes test nothing.
+ * Writes a pid/startId file for out-of-band liveness inspection and answers
+ * probes over a tiny line protocol on stdin/stdout.
+ */
+import { writeFileSync } from "node:fs";
+
+const version = process.env["K_FAKE_VERSION"] ?? "0.0.0";
+const slot = process.env["K_FAKE_SLOT"] ?? "stable";
+const evidenceFile = process.env["K_FAKE_EVIDENCE_FILE"];
+// startId must be unique per incarnation: pid alone is reusable by the OS.
+const startId = `${process.pid}-${process.hrtime.bigint().toString(36)}`;
+
+if (evidenceFile !== undefined) {
+  writeFileSync(evidenceFile, JSON.stringify({ version, slot, pid: process.pid, startId }));
+}
+
+process.stdout.write(`ready ${JSON.stringify({ version, slot, pid: process.pid, startId })}\n`);
+
+process.stdin.on("data", (chunk: Buffer) => {
+  for (const line of chunk.toString("utf8").split("\n")) {
+    const cmd = line.trim();
+    if (cmd === "probe") {
+      process.stdout.write(`evidence ${JSON.stringify({ version, pid: process.pid, startId })}\n`);
+    } else if (cmd === "exit") {
+      process.exit(0);
+    } else if (cmd === "hang") {
+      // Simulates a host that never completes an operation; the harness must
+      // time out and kill rather than wait forever.
+      setInterval(() => {}, 1 << 30);
+    }
+  }
+});
+
+// Keep the process alive until told otherwise.
+setInterval(() => {}, 1 << 30);

package/harness/src/fake-host/daemon.ts

@@ -0,0 +1,159 @@
+/**
+ * Real-process fake host (harness-design §1.1, second form).
+ *
+ * Spawns daemon-entry.ts as a genuine OS process, so the properties that
+ * only exist in process reality are actually exercised:
+ *   - kill -9 (SIGKILL) really terminates; recovery faces real leftovers
+ *   - dual-run is detected by asking the OS, not by reading our own bookkeeping
+ *   - probe liveness is bound to a real pid + per-incarnation startId
+ *   - "verify dead" means the OS says gone, not that we sent a signal
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import path from "node:path";
+import type { HostAdapter, ProcessEvidence, Slot } from "../../../core/src/lifecycle/hostAdapter.ts";
+
+const ENTRY = path.join(import.meta.dirname, "daemon-entry.ts");
+
+interface Incarnation {
+  child: ChildProcess;
+  slot: Slot;
+  version: string;
+  pid: number;
+  startId: string;
+}
+
+export interface DaemonHostOptions {
+  /** Version each slot's "binary" reports when started. */
+  slotVersions: Record<Slot, string | null>;
+  /** Milliseconds before a start/probe is considered hung. */
+  timeoutMs?: number;
+  /** Extra env for spawned incarnations (e.g. the sandbox marker). */
+  env?: Record<string, string>;
+  /** Extra trailing argv for spawned incarnations (e.g. `argvMarker()` —
+   *  the command-line channel Windows' marker scan needs; daemon-entry
+   *  ignores unknown argv). */
+  markerArgs?: string[];
+}
+
+/** Does the OS still know this pid? (Signal 0 = existence check, no delivery.) */
+export function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export class DaemonFakeHost implements HostAdapter {
+  private current: Incarnation | null = null;
+  private readonly opts: DaemonHostOptions;
+  /** Every pid we ever started, for leak/dual-run auditing. */
+  readonly startedPids: number[] = [];
+
+  constructor(opts: DaemonHostOptions) {
+    this.opts = opts;
+  }
+
+  async quiesce(): Promise<void> {
+    // No workload ledger in the process tier; the in-proc host covers that.
+  }
+
+  async stop(_slot: Slot): Promise<void> {
+    const inc = this.current;
+    if (!inc) return;
+    this.current = null;
+    inc.child.kill("SIGKILL");
+    await this.waitUntilDead(inc.pid);
+  }
+
+  async start(slot: Slot): Promise<void> {
+    const version = this.opts.slotVersions[slot];
+    if (version === null) throw new Error(`slot ${slot} holds no version to start`);
+    const child = spawn(process.execPath, [ENTRY, ...(this.opts.markerArgs ?? [])], {
+      env: { ...process.env, ...this.opts.env, K_FAKE_VERSION: version, K_FAKE_SLOT: slot },
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+    const ready = await this.readLine(child, "ready", this.opts.timeoutMs ?? 5000);
+    const info = JSON.parse(ready) as { pid: number; startId: string };
+    this.current = { child, slot, version, pid: info.pid, startId: info.startId };
+    this.startedPids.push(info.pid);
+  }
+
+  async healthProbe(): Promise<ProcessEvidence> {
+    const inc = this.current;
+    if (!inc) throw new Error("no live incarnation to probe");
+    inc.child.stdin?.write("probe\n");
+    const line = await this.readLine(inc.child, "evidence", this.opts.timeoutMs ?? 5000);
+    return JSON.parse(line) as ProcessEvidence;
+  }
+
+  async resume(): Promise<void> {}
+
+  /** SIGKILL the live incarnation without any orderly shutdown (crash sim). */
+  async crash(): Promise<number | null> {
+    const inc = this.current;
+    if (!inc) return null;
+    this.current = null;
+    inc.child.kill("SIGKILL");
+    await this.waitUntilDead(inc.pid);
+    return inc.pid;
+  }
+
+  /** Teardown contract: kill everything we started and PROVE it is gone. */
+  async teardownVerifyDead(): Promise<{ killed: number[]; survivors: number[] }> {
+    await this.crash();
+    const survivors: number[] = [];
+    for (const pid of this.startedPids) {
+      if (processAlive(pid)) {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+          // already gone between the check and the signal
+        }
+        await this.waitUntilDead(pid, 2000).catch(() => survivors.push(pid));
+      }
+    }
+    return { killed: this.startedPids.filter((p) => !survivors.includes(p)), survivors };
+  }
+
+  /** Pids we started that the OS still reports alive (dual-run auditing). */
+  livePids(): number[] {
+    return this.startedPids.filter((pid) => processAlive(pid));
+  }
+
+  private async waitUntilDead(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 after ${timeoutMs}ms`);
+      await new Promise((r) => {
+        setTimeout(r, 10);
+      });
+    }
+  }
+
+  private readLine(child: ChildProcess, prefix: string, timeoutMs: number): Promise<string> {
+    return new Promise((resolve, reject) => {
+      let buffer = "";
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`timed out waiting for "${prefix}" from fake 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);
+    });
+  }
+}

package/harness/src/fake-host/inproc.ts

@@ -0,0 +1,256 @@
+/**
+ * inproc fake-host (harness-design §1.1 first half) — an IN-PROCESS
+ * HostAdapter implementation with per-method fault-injection switches and
+ * a deterministic virtual-load ledger.
+ *
+ * Virtual load ledger: the fake host simulates a hosted "session" as a
+ * deterministic state — a counter + rolling sha256 checksum — persisted
+ * to `<stateDir>/ledger.bin`. quiesce() durably parks it (fsync), resume()
+ * restores it; `quiesce↔resume` equivalence is the byte-for-byte ledger
+ * comparison, including resume after rollback. This is the decidable form
+ * of the managed profile's "session preservation" claim.
+ *
+ * Fault switches (per method, harness-design §1.1): fail-on-quiesce /
+ * hang-on-stop / wrong-version-probe / stale-startId-probe /
+ * crash-during-start. Teeth run the NORMAL contract with switches off
+ * (green) and must go RED with a switch on — proving the tooth tests the
+ * fault, not the norm.
+ *
+ * Time: the host touches time ONLY through the injected Clock (core's
+ * clock seam); hang-on-stop is a clock-scheduled far-future resolution so
+ * a scenario VirtualClock can detect it without real sleeps.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { type Clock, systemClock } from "../../../core/src/clock.ts";
+import type { HostAdapter, ProcessEvidence, Slot } from "../../../core/src/lifecycle/hostAdapter.ts";
+
+export interface FakeHostFaults {
+  /** quiesce() throws. */
+  failOnQuiesce?: boolean;
+  /** stop() never completes (clock-scheduled far-future). */
+  hangOnStop?: boolean;
+  /** healthProbe() reports a version different from the running slot's. */
+  wrongVersionProbe?: boolean;
+  /** healthProbe() reports a PREVIOUS incarnation's startId (fake-green). */
+  staleStartIdProbe?: boolean;
+  /** start() throws. */
+  crashDuringStart?: boolean;
+}
+
+export interface InprocFakeHostOptions {
+  /** Where the virtual-load ledger lives (inside the scenario sandbox). */
+  stateDir: string;
+  /** Clock seam; default real system clock. Scenarios inject VirtualClock. */
+  clock?: Clock;
+  faults?: FakeHostFaults;
+  /** Version of the binaries in each slot. */
+  versions?: { stable: string; experiment: string };
+}
+
+export const LEDGER_FILE = "ledger.bin";
+const LEDGER_PREFIX = "k-ledger-v1";
+const COUNTER_BYTES = 8;
+const CHECKSUM_BYTES = 32;
+const HANG_HORIZON_MS = 1e12;
+
+export interface LedgerState {
+  counter: number;
+  checksum: Uint8Array;
+}
+
+/**
+ * The harness-side driving surface a fake host (or adopter adapter, in
+ * --adapter mode) can expose beyond the plain HostAdapter contract: the
+ * lifecycle getters the contract checks assert on, and the workload
+ * driver the ledger-equivalence checks need. An adopter adapter that
+ * cannot drive a deterministic workload simply omits doWork/ledger and
+ * the ledger checks are marked na.
+ */
+export interface HostDriver extends HostAdapter {
+  /** Slot currently running, or null. */
+  readonly running: Slot | null;
+  /** Whether the workload is currently parked (quiesced). */
+  readonly parked: boolean;
+  /** StartId of the current incarnation (evidence binding key). */
+  readonly startId: string | null;
+  /** Simulate n units of hosted session activity (deterministic). */
+  doWork?(n: number): Promise<void>;
+  /** Current ledger bytes (durability view). */
+  ledger?(): Promise<Uint8Array>;
+  /** Parsed ledger state. */
+  ledgerState?(): Promise<LedgerState>;
+}
+
+export class InprocFakeHost implements HostDriver {
+  private readonly stateDir: string;
+  private readonly clock: Clock;
+  private readonly faults: FakeHostFaults;
+  private readonly versionBySlot: { stable: string; experiment: string };
+
+  private counter = 0;
+  private checksum: Uint8Array;
+  private runningSlot: Slot | null = null;
+  private quiesced = false;
+  private incarnation = 0;
+  private startIds: string[] = [];
+  private parkedLedger: Uint8Array | null = null;
+
+  constructor(opts: InprocFakeHostOptions) {
+    this.stateDir = opts.stateDir;
+    this.clock = opts.clock ?? systemClock;
+    this.faults = opts.faults ?? {};
+    this.versionBySlot = opts.versions ?? { stable: "1.0.0", experiment: "2.0.0" };
+    this.checksum = createHash("sha256").update(LEDGER_PREFIX).digest();
+  }
+
+  /** Slot currently running, or null. */
+  get running(): Slot | null {
+    return this.runningSlot;
+  }
+
+  /** Whether the workload is currently parked (quiesced). */
+  get parked(): boolean {
+    return this.quiesced;
+  }
+
+  /** StartId of the current incarnation (evidence binding key). */
+  get startId(): string | null {
+    const current = this.startIds.at(-1);
+    return current ?? null;
+  }
+
+  // -------------------------------------------------------------------------
+  // HostAdapter contract
+  // -------------------------------------------------------------------------
+
+  async quiesce(): Promise<void> {
+    if (this.faults.failOnQuiesce) throw new Error("fail-on-quiesce");
+    if (this.quiesced) return; // idempotent
+    if (!this.runningSlot) throw new Error("quiesce: no running slot");
+    this.quiesced = true;
+    // Durable park: flush the ledger (fsync) and keep the parked bytes.
+    await this.writeLedger();
+    this.parkedLedger = await this.readLedger();
+  }
+
+  async stop(slot: Slot): Promise<void> {
+    if (this.faults.hangOnStop) {
+      await new Promise<void>((resolve) => {
+        this.clock.after(HANG_HORIZON_MS, resolve);
+      });
+      return;
+    }
+    if (this.runningSlot !== slot) throw new Error(`stop: ${slot} is not the running slot`);
+    this.runningSlot = null;
+  }
+
+  async start(slot: Slot): Promise<void> {
+    if (this.faults.crashDuringStart) throw new Error("crash-during-start");
+    if (this.runningSlot !== null) throw new Error(`start: ${this.runningSlot} already running`);
+    this.runningSlot = slot;
+    this.incarnation += 1;
+    this.startIds.push(`inc:${this.incarnation}:${this.clock.nowMs()}`);
+  }
+
+  async healthProbe(): Promise<ProcessEvidence> {
+    const runningSlot = this.runningSlot;
+    if (!runningSlot) throw new Error("probe: no running slot");
+    const currentStartId = this.startIds.at(-1);
+    if (!currentStartId) throw new Error("probe: no startId for running incarnation");
+    const version = this.faults.wrongVersionProbe
+      ? "9.9.9"
+      : this.versionBySlot[runningSlot];
+    let startId = currentStartId;
+    if (this.faults.staleStartIdProbe) {
+      const previous = this.startIds.at(-2);
+      startId = previous ?? "stale-000";
+    }
+    return { version, pid: process.pid, startId };
+  }
+
+  async resume(): Promise<void> {
+    if (!this.quiesced) throw new Error("resume: not quiesced");
+    const parked = this.parkedLedger;
+    if (!parked) throw new Error("resume: no parked ledger");
+    const state = this.parseLedger(parked);
+    this.counter = state.counter;
+    this.checksum = state.checksum;
+    this.quiesced = false;
+    // Rewriting from the restored state must reproduce the parked bytes.
+    await this.writeLedger();
+  }
+
+  // -------------------------------------------------------------------------
+  // Harness-side workload driver
+  // -------------------------------------------------------------------------
+
+  /**
+   * Simulate `n` units of hosted session activity: counter increments and
+   * the checksum chains deterministically. Persisted to the ledger file.
+   * Refuses while parked — a quiesced workload must not mutate the session.
+   */
+  async doWork(n: number): Promise<void> {
+    if (this.quiesced) throw new Error("workload is parked (quiesced)");
+    if (!this.runningSlot) throw new Error("doWork: no running slot");
+    for (let i = 0; i < n; i++) {
+      this.counter += 1;
+      this.checksum = createHash("sha256").update(be64(this.counter)).update(this.checksum).digest();
+    }
+    await this.writeLedger();
+  }
+
+  /** Current ledger file bytes (what a durability check would read). */
+  async ledger(): Promise<Uint8Array> {
+    return this.readLedger();
+  }
+
+  /** Parsed ledger state (counter + checksum). */
+  async ledgerState(): Promise<LedgerState> {
+    return this.parseLedger(await this.readLedger());
+  }
+
+  // -------------------------------------------------------------------------
+  // Ledger persistence
+  // -------------------------------------------------------------------------
+
+  private ledgerBytes(): Uint8Array {
+    const out = new Uint8Array(COUNTER_BYTES + CHECKSUM_BYTES);
+    new DataView(out.buffer).setBigUint64(0, BigInt(this.counter), false);
+    out.set(this.checksum, COUNTER_BYTES);
+    return out;
+  }
+
+  private parseLedger(bytes: Uint8Array): LedgerState {
+    if (bytes.length !== COUNTER_BYTES + CHECKSUM_BYTES) {
+      throw new Error(`ledger corrupted: ${bytes.length} bytes`);
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const counter = Number(view.getBigUint64(0, false));
+    const checksum = bytes.slice(COUNTER_BYTES);
+    return { counter, checksum };
+  }
+
+  private async writeLedger(): Promise<void> {
+    await fs.mkdir(this.stateDir, { recursive: true });
+    const fh = await fs.open(path.join(this.stateDir, LEDGER_FILE), "w");
+    try {
+      await fh.writeFile(this.ledgerBytes());
+      await fh.sync(); // durable park at quiesce
+    } finally {
+      await fh.close();
+    }
+  }
+
+  private async readLedger(): Promise<Uint8Array> {
+    const raw = await fs.readFile(path.join(this.stateDir, LEDGER_FILE));
+    return new Uint8Array(raw);
+  }
+}
+
+function be64(n: number): Uint8Array {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, BigInt(n), false);
+  return out;
+}