@botiverse/k-carrier 0.1.0

package/core/src/liveness.ts

@@ -0,0 +1,80 @@
+/**
+ * Liveness and progress — deliberately NOT in invariants.ts.
+ *
+ * Everything in the safety set there is satisfied by a host that does nothing
+ * at all: a DEAD service violates none of them (never-bricked judges slots,
+ * live-process-matches-slot is vacuous with nothing alive, the rest read
+ * journals). Safety therefore cannot say an updater works. These two functions
+ * are what says it, and they are judged over time rather than over one
+ * snapshot, which is exactly why they do not fit the Invariant shape.
+ */
+import type { TxnPhase } from "./txn/state.ts";
+import type { WorldSnapshot, InvariantResult, HostAssumption } from "./invariants.ts";
+
+/**
+ * LIVENESS (progress), deliberately separate from the safety set above.
+ *
+ * Every safety invariant here is satisfiable by doing nothing at all, so
+ * safety alone cannot say an updater works. This is the minimal progress
+ * property: a transaction that started must reach a terminal phase within a
+ * bounded number of steps — never parked in `staged`/`readback` forever.
+ */
+export function reachesTerminalWithin(
+  phaseTrace: readonly TxnPhase[],
+  maxSteps: number,
+): InvariantResult {
+  const terminal = new Set<TxnPhase>(["idle", "promoted", "rolled-back"]);
+  const last = phaseTrace.at(-1);
+  if (last !== undefined && terminal.has(last)) return null;
+  return phaseTrace.length >= maxSteps
+    ? `transaction still in ${last ?? "unknown"} after ${phaseTrace.length} steps (limit ${maxSteps}) — no progress to a terminal phase`
+    : null;
+}
+
+/**
+ * PROGRESS, and the reason it cannot be a plain invariant.
+ *
+ * Every safety invariant above is satisfied by a host with NO live process:
+ * `never-bricked` is about slots (its own description says so),
+ * `live-process-matches-slot` is vacuous when nothing is live, and the journal
+ * ones only look at journals. So a service that is simply DEAD passes the
+ * entire safety set — which is the "doing nothing satisfies safety" hole, in
+ * our own code.
+ *
+ * What an adopter actually needs promised (once session
+ * preservation was ruled out): *you always come back*. That is a liveness
+ * property, and it needs two things a single snapshot cannot give:
+ *   - TIME: right after a terminal phase nothing is live yet; starting takes a
+ *     moment. Judging one instant would fail a healthy upgrade.
+ *   - OBSERVATION: it must be checkable from outside, from the same status
+ *     readback anyone else can take — not from our internal logs.
+ *
+ * So it is expressed over a sequence of observed snapshots: once the
+ * transaction is terminal, some later observation within the budget must show
+ * a live incarnation running the stable slot's version.
+ */
+export const SERVICE_SETTLES_LIVE_ASSUMES: readonly HostAssumption[] = ["resident-service"];
+
+export function serviceSettlesLive(
+  observations: readonly WorldSnapshot[],
+  maxObservations: number,
+): InvariantResult {
+  const terminal = new Set<TxnPhase>(["idle", "promoted", "rolled-back"]);
+  const firstTerminal = observations.findIndex((s) => terminal.has(s.phase));
+  if (firstTerminal === -1) return null; // still in flight: reachesTerminalWithin judges that
+  const after = observations.slice(firstTerminal, firstTerminal + maxObservations);
+  for (const s of after) {
+    const expected = s.slots.stable;
+    if (expected === null) continue;
+    if (s.liveProcesses.some((p) => p.version === expected)) return null;
+  }
+  const last = after.at(-1);
+  const seen =
+    last === undefined || last.liveProcesses.length === 0
+      ? "nothing live"
+      : last.liveProcesses.map((p) => p.version).join(", ");
+  return (
+    `transaction settled at ${observations[firstTerminal]!.phase} but no live process reports the ` +
+    `stable version ${last?.slots.stable ?? "unknown"} within ${maxObservations} observations (saw: ${seen})`
+  );
+}

package/core/src/platform/README.md

@@ -0,0 +1 @@
+# platform — see docs/design-v1.md for this layer's spec. Interfaces land here next.

package/core/src/platform/index.ts

@@ -0,0 +1,11 @@
+import type { PlatformOps } from "./ops.ts";
+import { posixOps } from "./posix.ts";
+import { windowsOps } from "./windows.ts";
+
+/** Pick the seam implementation for the host we are running on. */
+export function platformOpsFor(platform: NodeJS.Platform = process.platform): PlatformOps {
+  return platform === "win32" ? windowsOps : posixOps;
+}
+
+export type { PlatformOps } from "./ops.ts";
+export { PlatformUnsupportedError } from "./ops.ts";

package/core/src/platform/ops.ts

@@ -0,0 +1,53 @@
+/**
+ * PlatformOps — the seam where OS-shaped behaviour lives.
+ *
+ * Multi-platform from day 1, because these are not implementation details of
+ * one operation: the STEPS differ per OS.
+ *
+ *   swapExecutable  POSIX: write tmp -> fsync -> rename over the target.
+ *                   Windows: you cannot rename over a RUNNING .exe (file
+ *                   lock), so the running image must be moved aside first
+ *                   and the new bytes put in its place. Different sequence,
+ *                   not a different syscall.
+ *   isProcessAlive  POSIX: signal 0. Windows: no signals at all.
+ *   killProcess     POSIX: SIGKILL. Windows: TerminateProcess semantics.
+ *
+ * A ratchet keeps signal names / process.kill / rename out of the rest of
+ * core, so a POSIX assumption cannot quietly grow into the engine.
+ */
+export interface PlatformOps {
+  /**
+   * Replace an executable's bytes. Contract:
+   *  - crash-safe: a reader sees the old file or the whole new one, never half;
+   *  - PRESERVES the target's mode/permissions. A self-upgrading binary that
+   *    loses +x fails on its NEXT launch, far from the upgrade that caused it
+   *    (found in review: every self-upgrading binary hits this).
+   */
+  swapExecutable(filePath: string, data: Uint8Array): Promise<void>;
+  /** Does the OS still know this pid? */
+  isProcessAlive(pid: number): boolean;
+  /** Terminate without giving the process a chance to clean up (crash sim / teardown). */
+  killProcess(pid: number): void;
+  /** Mark a file executable where the concept exists; a no-op where it does not. */
+  makeExecutable(filePath: string): Promise<void>;
+  /**
+   * Move a path (file or directory) into place. Used to publish a slot
+   * atomically. Separate from swapExecutable because that one is about a
+   * RUNNING image; this one is plain state.
+   */
+  renamePath(from: string, to: string): Promise<void>;
+  /** Identifier used to select a manifest target, e.g. "linux-x64". */
+  platformKey(): string;
+}
+
+export class PlatformUnsupportedError extends Error {
+  readonly code = "PLATFORM_UNSUPPORTED";
+
+  constructor(operation: string, platform: string) {
+    super(
+      `[PLATFORM_UNSUPPORTED] ${operation} is not implemented for ${platform} yet — ` +
+        `K refuses to approximate it rather than corrupt an install`,
+    );
+    this.name = "PlatformUnsupportedError";
+  }
+}

package/core/src/platform/posix.ts

@@ -0,0 +1,99 @@
+/**
+ * POSIX implementation of the platform seam (linux, darwin).
+ * The only place in core allowed to name rename/signals.
+ */
+import { execFileSync } from "node:child_process";
+import { promises as fs } from "node:fs";
+import type { PlatformOps } from "./ops.ts";
+
+async function atomicReplace(filePath: string, data: Uint8Array): Promise<void> {
+  const tmpPath = `${filePath}.tmp`;
+  try {
+    // Preserve the target's mode across the swap: a self-replacing
+    // executable must stay executable (a leftover tmp from a previous
+    // crash must not dictate the new file's permissions either).
+    let mode: number | undefined;
+    try {
+      mode = (await fs.stat(filePath)).mode;
+    } catch {
+      // target does not exist yet: default permissions
+    }
+    const fh = await fs.open(tmpPath, "w");
+    try {
+      if (mode !== undefined) await fh.chmod(mode & 0o777);
+      await fh.writeFile(data);
+      await fh.sync(); // durable before the rename makes it visible
+    } finally {
+      await fh.close();
+    }
+    // Atomic on POSIX: a reader sees either the old file or the whole new one.
+    await fs.rename(tmpPath, filePath);
+  } catch (err) {
+    await fs.unlink(tmpPath).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Does this Mac have arm64 hardware, whatever this process is running as?
+ *
+ * Untestable on a non-Mac, so it is one line delegating to the OS while the
+ * DECISION it feeds lives in `platformKeyFor`, which is pure and pinned.
+ */
+function hardwareSupportsDarwinArm64(): boolean {
+  try {
+    return (
+      execFileSync("/usr/sbin/sysctl", ["-in", "hw.optional.arm64"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim() === "1"
+    );
+  } catch {
+    return false; // not a Mac, sysctl missing, or no such key
+  }
+}
+
+/**
+ * Which manifest target this machine should be served.
+ *
+ * The one non-obvious case is Rosetta: an x64 Node on Apple Silicon reports
+ * `process.arch === "x64"`, so the naive `platform-arch` picks the x64 target
+ * FOREVER. The machine never moves to the native build, and an adopter who
+ * publishes arm64 sees it silently ignored on exactly the hardware it is for.
+ * Nothing errors -- the wrong artifact is a perfectly valid artifact.
+ *
+ * So on darwin+x64 we ask the HARDWARE, not the process.
+ */
+export function platformKeyFor(
+  platform: string,
+  processArch: string,
+  supportsDarwinArm64: () => boolean,
+): string {
+  const arch =
+    platform === "darwin" && processArch === "x64" && supportsDarwinArm64() ? "arm64" : processArch;
+  return `${platform}-${arch}`;
+}
+
+export const posixOps: PlatformOps = {
+  swapExecutable: atomicReplace,
+  isProcessAlive(pid) {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  killProcess(pid) {
+    process.kill(pid, "SIGKILL");
+  },
+  async renamePath(from, to) {
+    await fs.rename(from, to);
+  },
+  async makeExecutable(filePath) {
+    await fs.chmod(filePath, 0o755);
+  },
+  platformKey() {
+    return platformKeyFor(process.platform, process.arch, hardwareSupportsDarwinArm64);
+  },
+};

package/core/src/platform/windows.ts

@@ -0,0 +1,73 @@
+/**
+ * Windows implementation of the platform seam.
+ *
+ * The swap sequence differs from POSIX because a RUNNING .exe is
+ * NTFS-locked: it can be RENAMED (moved aside) but not deleted or
+ * overwritten in place. So the swap is move-aside → place-new →
+ * pending-delete — the shape prior-art.md documents from Tailscale's
+ * Windows updater. The aside file stays until the old process exits; the
+ * next successful swap removes it.
+ *
+ * Process ops use `process.kill` like POSIX, but on Windows the semantics
+ * are libuv's: signal 0 is OpenProcess + GetExitCodeProcess (an existence
+ * check — the honest "is it alive" question, since Windows has no signals)
+ * and SIGKILL is TerminateProcess. There is no signal delivery, so there is
+ * nothing a process could catch or ignore.
+ */
+import { promises as fs } from "node:fs";
+import type { PlatformOps } from "./ops.ts";
+
+async function swapExecutable(filePath: string, data: Uint8Array): Promise<void> {
+  const tmpPath = `${filePath}.tmp`;
+  const asidePath = `${filePath}.old`;
+  const fh = await fs.open(tmpPath, "w");
+  try {
+    await fh.writeFile(data);
+    await fh.sync(); // durable before it becomes visible at the real path
+  } finally {
+    await fh.close();
+  }
+  try {
+    // Move the running image aside. Renaming a locked .exe is allowed on
+    // Windows; deleting or overwriting it is not.
+    await fs.rename(filePath, asidePath);
+  } catch (err) {
+    // First install (or a previous swap already moved it): no old image.
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+  // Place the new image at the canonical path. The old name is now free, so
+  // a plain move works — the target does not exist.
+  await fs.rename(tmpPath, filePath);
+  // Best-effort: the aside may be the still-running old image (locked until
+  // the process exits). A leftover is removed by the next swap.
+  await fs.rm(asidePath, { force: true }).catch(() => {});
+}
+
+export const windowsOps: PlatformOps = {
+  swapExecutable,
+  isProcessAlive(pid) {
+    // libuv maps signal 0 to an OpenProcess + GetExitCodeProcess existence
+    // check on Windows — the honest liveness question, not a signal.
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  killProcess(pid) {
+    // libuv maps SIGKILL to TerminateProcess: no cleanup, no escape.
+    process.kill(pid, "SIGKILL");
+  },
+  async renamePath(from, to) {
+    // Plain state moves DO work on Windows (unlike replacing a running .exe).
+    await fs.rename(from, to);
+  },
+  async makeExecutable() {
+    // No executable bit on Windows; nothing to do (a real no-op).
+    await Promise.resolve();
+  },
+  platformKey() {
+    return `${process.platform}-${process.arch}`;
+  },
+};

package/core/src/policy/README.md

@@ -0,0 +1 @@
+# policy — see docs/design-v1.md for this layer's spec. Interfaces land here next.

package/core/src/progress.ts

@@ -0,0 +1,54 @@
+/**
+ * Upgrade progress: what stage we are in, and how far the download got.
+ *
+ * WHY THIS IS NOT UI SUGAR. Between "start upgrading" and "done" there can be
+ * a 150MB download, a file swap, a process restart and a probe — minutes on a
+ * slow machine. With no signal, **"slow" and "hung" look identical from
+ * outside**, so a user kills it, and a kill lands in the middle of a
+ * transaction, which is the worst possible moment.
+ *
+ * The stages are NOT new vocabulary: they are the transaction's own phases,
+ * exposed. If a stage here ever disagrees with the state machine, the state
+ * machine is right and this is a bug.
+ */
+import type { TxnPhase } from "./txn/state.ts";
+
+export type UpgradeStage =
+  | "checking"      // asking the source what we should be on
+  | "downloading"   // fetching bytes (carries downloaded/total when known)
+  | "verifying"     // sha256 + size on the assembled artifact
+  | "staging"       // writing the experiment slot
+  | "handing-over"  // quiesce, stop, start — the live process changes
+  | "probing"       // asking the new incarnation to prove itself
+  | "promoted"      // experiment became stable
+  | "rolled-back";  // experiment discarded, stable untouched
+
+export interface UpgradeProgress {
+  stage: UpgradeStage;
+  /** Target version, once the source has told us. */
+  version?: string;
+  /**
+   * Bytes fetched so far and the expected total, when the stage is
+   * `downloading`.
+   *
+   * ⚠️ RESUME: `downloaded` counts bytes ON DISK, including a partial from a
+   * previous attempt — not bytes fetched this attempt. Otherwise a resumed
+   * download would show the bar jumping backwards to 0%, which reads as "it
+   * restarted" to the one person the number exists for.
+   */
+  downloaded?: number;
+  total?: number;
+}
+
+/** Map a journalled phase onto the stage a user should see. */
+export function stageForPhase(phase: TxnPhase): UpgradeStage | null {
+  switch (phase) {
+    case "staged": return "staging";
+    case "handing-over": return "handing-over";
+    case "running-experiment":
+    case "readback": return "probing";
+    case "promoted": return "promoted";
+    case "rolled-back": return "rolled-back";
+    default: return null; // idle: nothing in flight, nothing to report
+  }
+}

package/core/src/provenance/journal.ts

@@ -0,0 +1,216 @@
+/**
+ * Provenance journal (M6, L5) — WHO reconciled this machine, forward-only.
+ *
+ * Every reconcile that reaches the upgrade transaction appends an entry
+ * {who, carrier, when, version} WRITE-AHEAD of the action, mirroring the
+ * txn journal's intent-before-action discipline. A machine that never had
+ * the machinery is GENESIS — permanently NOT_OBSERVED and mechanically
+ * distinct from "observed with zero reconciles": no-data is not no-problem.
+ *
+ * Forward-only invariants (each is a harness tooth):
+ *  - appends only ever add a line; a seq at or below the last one is a
+ *    typed refusal (PROVENANCE_SEQ_REWRITE) — provenance is not rewritable
+ *  - a torn final line (crash mid-append) is dropped; earlier lines stand;
+ *    a parse failure in a MIDDLE line is corruption: the history is
+ *    UNREADABLE, never a short one — appending on it is refused, so one bad
+ *    line can never re-open the seq (the rewrite-under-a-truncated-view
+ *    attack)
+ *  - only ENOENT is genesis: an unreadable journal (EACCES/EISDIR/EIO,
+ *    corruption) is a THIRD state, and aggregation must never fold it into
+ *    "recorded" OR into "not observed"
+ *  - `version` (the artifact version the reconcile drove) is recorded —
+ *    K removed the channel concept; the record is who/carrier/version
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import type { Clock } from "../clock.ts";
+
+const PROVENANCE_FILE = "provenance.jsonl";
+
+export interface ProvenanceEntry {
+  /** Monotonic, file order = history order. */
+  seq: number;
+  /** The driving identity (server/operator) of this reconcile. */
+  who: string;
+  /** The carrier channel the command travelled on. */
+  carrier: string;
+  /** Clock-provided timestamp; core never touches Date.now directly. */
+  when: number;
+  /** The artifact version this reconcile drove (channel is gone from K). */
+  version: string;
+}
+
+/**
+ * Three states, and the distinction is the whole point:
+ *  - genesis: no journal file — the machine never had the machinery. The
+ *    value is NOT_OBSERVED, not "zero reconciles".
+ *  - observed: the machinery exists; entries may be zero (reconciled never).
+ *  - unreadable: the journal exists but cannot be read (EACCES/EISDIR/EIO)
+ *    or is corrupt (middle-line parse failure). This is NOT genesis — "I
+ *    cannot see the data" and "there is no data" are different buckets.
+ */
+export type ProvenanceRead =
+  | { kind: "genesis" }
+  | { kind: "observed"; entries: ProvenanceEntry[] }
+  | { kind: "unreadable"; reason: string };
+
+export type ProvenanceErrorCode = "PROVENANCE_SEQ_REWRITE" | "PROVENANCE_HISTORY_UNREADABLE";
+
+/** The journal's single error type: a code plus a human reason.
+ * - PROVENANCE_SEQ_REWRITE: an explicit seq at or below the last one —
+ *   provenance is forward-only and does not rewrite history.
+ * - PROVENANCE_HISTORY_UNREADABLE: the journal exists but cannot be read
+ *   (EACCES/EISDIR/EIO) or is corrupt (middle-line parse failure). Appending
+ *   on top of an unreadable history would GUESS the next seq, and a guessed
+ *   seq is how history becomes rewritable — so append refuses. */
+export class ProvenanceError extends Error {
+  readonly code: ProvenanceErrorCode;
+
+  constructor(code: ProvenanceErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = "ProvenanceError";
+    this.code = code;
+  }
+}
+
+export interface ProvenanceJournal {
+  /**
+   * Append one entry. `when` and `seq` come from the journal (clock +
+   * history); the caller supplies who/carrier/version. An explicit seq at
+   * or below the last one is refused. An unreadable/corrupt history refuses
+   * ANY append — never append on top of a view that may be truncated.
+   */
+  append(entry: { who: string; carrier: string; version: string }, explicitSeq?: number): Promise<ProvenanceEntry>;
+  read(): Promise<ProvenanceRead>;
+}
+
+export function fileProvenanceJournal(stateDir: string, clock: Clock): ProvenanceJournal {
+  const filePath = path.join(stateDir, PROVENANCE_FILE);
+
+  /** Read the raw file. Throws ProvenanceHistoryUnreadableError when the
+   * journal exists but cannot be read or is corrupt. */
+  async function readRaw(): Promise<{ exists: boolean; entries: ProvenanceEntry[] }> {
+    let text: string;
+    try {
+      text = await fs.readFile(filePath, "utf8");
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") return { exists: false, entries: [] };
+      throw new ProvenanceError("PROVENANCE_HISTORY_UNREADABLE", 
+        `cannot read ${PROVENANCE_FILE} (${code ?? (err as Error).message}); ` +
+          `unreadable is NOT genesis — the machine had the machinery and its record is hidden, not absent`,
+      );
+    }
+    const lines = text.split("\n").filter((l) => l.trim());
+    const entries: ProvenanceEntry[] = [];
+    for (let i = 0; i < lines.length; i += 1) {
+      try {
+        entries.push(JSON.parse(lines[i]!) as ProvenanceEntry);
+      } catch {
+        // Only the LAST non-empty line may be torn (crash mid-append). A
+        // middle-line failure is corruption: everything after it is
+        // unverifiable, and reading a truncated history as the truth is how
+        // the seq gets re-issued.
+        if (i < lines.length - 1) {
+          throw new ProvenanceError("PROVENANCE_HISTORY_UNREADABLE", 
+            `corrupt entry at line ${i + 1} (middle of the journal); history unreadable ≠ history short`,
+          );
+        }
+        break;
+      }
+    }
+    return { exists: true, entries };
+  }
+
+  return {
+    async append(entry, explicitSeq) {
+      await fs.mkdir(stateDir, { recursive: true });
+      const { exists, entries } = await readRaw();
+      const lastSeq = exists ? (entries.at(-1)?.seq ?? -1) : -1;
+      const seq = explicitSeq ?? lastSeq + 1;
+      if (seq <= lastSeq) {
+        throw new ProvenanceError("PROVENANCE_SEQ_REWRITE", `seq ${seq} <= last ${lastSeq}; provenance is forward-only and does not rewrite history`);
+      }
+      const full: ProvenanceEntry = {
+        seq,
+        who: entry.who,
+        carrier: entry.carrier,
+        when: clock.nowMs(),
+        version: entry.version,
+      };
+      const fh = await fs.open(filePath, "a");
+      try {
+        await fh.writeFile(`${JSON.stringify(full)}\n`);
+        await fh.sync(); // durable BEFORE the action it records: same promise as the txn WAL
+      } finally {
+        await fh.close();
+      }
+      return full;
+    },
+    async read() {
+      try {
+        const { exists, entries } = await readRaw();
+        return exists ? { kind: "observed" as const, entries } : { kind: "genesis" as const };
+      } catch (err) {
+        if (err instanceof ProvenanceError) {
+          return { kind: "unreadable" as const, reason: err.message };
+        }
+        throw err;
+      }
+    },
+  };
+}
+
+export interface ProvenanceSummary {
+  /** Machines with an observed journal (any entry count). */
+  recorded: number;
+  /** Total entries across recorded machines. */
+  reconciles: number;
+  /** Machines with NO journal (genesis). MUST never be folded into recorded. */
+  notObserved: number;
+  /** Machines whose journal exists but cannot be read. NEVER recorded, and
+   * NEVER notObserved — "I didn't see it" is not "it isn't there". */
+  unreadable: number;
+}
+
+/**
+ * Record one reconcile in the journal (used by createUpgrader before the
+ * transaction). The VERSION comes from the release the reconcile drove —
+ * the journal records what was attempted, not the caller's claim. Identity
+ * defaults to the local operator.
+ */
+export async function recordReconcile(
+  journal: ProvenanceJournal,
+  identity: { who: string; carrier: string } | null | undefined,
+  version: string,
+): Promise<void> {
+  const id = identity ?? { who: "local", carrier: "auto" };
+  await journal.append({ who: id.who, carrier: id.carrier, version });
+}
+
+/**
+ * Fleet aggregation of per-machine reads. The mechanical guards:
+ *  - a genesis read counts in notObserved, never in recorded
+ *  - an unreadable read counts in unreadable, never in recorded and never
+ *    in notObserved
+ * "No data" and "zero data" are different buckets, and "can't see" is a
+ * third — any caller that merges them is the downgrade this module exists
+ * to prevent.
+ */
+export function summarizeProvenance(reads: readonly ProvenanceRead[]): ProvenanceSummary {
+  let recorded = 0;
+  let reconciles = 0;
+  let notObserved = 0;
+  let unreadable = 0;
+  for (const read of reads) {
+    if (read.kind === "genesis") {
+      notObserved += 1;
+    } else if (read.kind === "unreadable") {
+      unreadable += 1;
+    } else {
+      recorded += 1;
+      reconciles += read.entries.length;
+    }
+  }
+  return { recorded, reconciles, notObserved, unreadable };
+}

package/core/src/status/report.ts

@@ -0,0 +1,76 @@
+/**
+ * Status report (M6, L5) — the fleet read-back surface: what a machine
+ * reports about itself is a READ-BACK, never an invention.
+ *
+ * Every field comes from the live sources at the moment of the call:
+ *  - phase / stable / experiment: the txn state (slots + journal intent)
+ *  - predicates: the last REAL convergence report's results — a machine
+ *    that has never observed a promote reports `null` (NOT_OBSERVED), NOT
+ *    `passed: true`. "never observed" has its own value (the M5 rule extended
+ *    to the fleet surface: silence cannot be spent as evidence).
+ *  - policy: the configured policy, verbatim.
+ *  - provenance: the journal's read (genesis / observed / unreadable), or
+ *    null when the app never wired a journal.
+ */
+import type { TxnState } from "../txn/state.ts";
+import type { PredicateResult } from "../converge/predicates.ts";
+import type { ProvenanceRead } from "../provenance/journal.ts";
+import type { ReportRead } from "./reportStore.ts";
+
+/**
+ * The predicates' state — three shapes, mechanically distinct:
+ *  - genesis: no report was ever written. The machine NEVER OBSERVED a
+ *    promote — NOT_OBSERVED, never a fabricated pass.
+ *  - unreadable: a report exists but cannot be read (EACCES/corrupt). The
+ *    machine DID observe; its record is hidden, not absent. "I cannot see
+ *    the data" is not "there is no data".
+ *  - observed: the last real report, verbatim — `version` is the JOIN KEY
+ *    (consumers join on it, never on the current stable/experiment: a real
+ *    conclusion about 2.0.0 read as 3.0.0's is worse than a fake).
+ */
+export type StatusPredicates =
+  | { kind: "genesis" }
+  | { kind: "unreadable"; reason: string }
+  | {
+      kind: "observed";
+      version: string;
+      binaryAtTarget: PredicateResult;
+      hostLifecycleConverged: PredicateResult | null;
+    };
+
+export interface StatusReport {
+  phase: TxnState["phase"];
+  stable: string;
+  experiment: string | null;
+  predicates: StatusPredicates;
+  policy: "auto" | "confirm" | "notify-only";
+  /** The provenance journal read; null = the app never wired a journal. */
+  provenance: ProvenanceRead | null;
+}
+
+export function buildStatusReport(input: {
+  state: TxnState;
+  lastReport: ReportRead;
+  policy: "auto" | "confirm" | "notify-only";
+  provenance: ProvenanceRead | null;
+}): StatusReport {
+  return {
+    phase: input.state.phase,
+    stable: input.state.stableVersion,
+    experiment: input.state.experimentVersion,
+    predicates: reportPredicates(input.lastReport),
+    policy: input.policy,
+    provenance: input.provenance,
+  };
+}
+
+function reportPredicates(read: ReportRead): StatusPredicates {
+  if (read.kind === "genesis") return { kind: "genesis" };
+  if (read.kind === "unreadable") return { kind: "unreadable", reason: read.reason };
+  return {
+    kind: "observed",
+    version: read.report.version,
+    binaryAtTarget: read.report.binaryAtTarget,
+    hostLifecycleConverged: read.report.hostLifecycleConverged,
+  };
+}