@botiverse/k-carrier 0.1.0

package/core/src/createUpgrader.ts

@@ -0,0 +1,300 @@
+/**
+ * createUpgrader — the one construction every entrypoint uses.
+ *
+ * Order of gates: lock -> ownership -> source -> policy -> compat ->
+ * download -> engine. Everything before the engine can only produce `held`
+ * or `up-to-date`: nothing on disk has changed. A refusal is cheap; a
+ * rollback is rare, not routine.
+ */
+import type { Upgrader, UpgraderConfig, UpgradeOutcome, ProvenanceIdentity } from "./upgrader.ts";
+import { phaseAtRest, type TxnState } from "./txn/state.ts";
+import type { Release } from "./artifact/source.ts";
+import type { ProcessEvidence } from "./lifecycle/hostAdapter.ts";
+import { UpgradeEngine } from "./txn/engine.ts";
+import { fileEffects, materializeArtifact } from "./txn/fileEffects.ts";
+import { acquireUpgradeLock } from "./txn/lock.ts";
+import { downloadVerified } from "./artifact/download.ts";
+import { ArtifactError } from "./artifact/errors.ts";
+import * as path from "node:path";
+import { systemClock, type Clock } from "./clock.ts";
+import { buildSurfaceAllowlist, evaluateLifecycleConvergence } from "./converge/lifecycle.ts";
+import type { ReadbackSurface, PredicateResult } from "./converge/predicates.ts";
+import { platformOpsFor } from "./platform/index.ts";
+import type { UpgradeProgress } from "./progress.ts";
+import { slotArtifactPath } from "./txn/fileEffects.ts";
+import { recordReconcile, type ProvenanceJournal } from "./provenance/journal.ts";
+import { finishUpgradeOutcome } from "./upgrade/outcome.ts";
+import { retireReason } from "./upgrade/retire.ts";
+import { buildStatusReport, type StatusReport } from "./status/report.ts";
+import { persistReport, loadLastReport, type ReportRead } from "./status/reportStore.ts";
+
+export interface CreateUpgraderOptions extends UpgraderConfig {
+  clock?: Clock;
+  /** Reports who owns this install; default: we own it. */
+  installOwnership?: () => "self" | "managed-elsewhere";
+  /** Optional host semantic gate; a string result refuses the transition. */
+  checkCompatibility?: (from: string, to: string) => Promise<string | null>;
+  /**
+   * Progress for a host that wants to show something while this runs.
+   *
+   * Without it, a long upgrade is indistinguishable from a hung one, and the
+   * user's remedy for "hung" is to kill the process mid-transaction. Purely
+   * observational: never awaited for control flow, and a throwing sink must
+   * not fail the upgrade.
+   */
+  onProgress?: (progress: UpgradeProgress) => void;
+  /**
+   * The OS-lifecycle read-back surfaces the app's platform adapter
+   * declares (host_lifecycle_converged, design-v1 §L3). Each surface is
+   * read during readback; convergence requires it to reference the
+   * artifact being promoted. Surfaces NOT declared here are refused —
+   * an app can only vouch for surfaces it actually ships.
+   */
+  lifecycleSurfaces?: ReadbackSurface[];
+  /**
+   * M6 provenance journal (L5): every reconcile that reaches the transaction
+   * records WHO drove it (who/carrier/version), write-ahead. Local
+   * auto-updates use `provenanceIdentity` (default: the local operator).
+   */
+  provenance?: ProvenanceJournal;
+  /** Identity recorded for reconciles that carry none (local auto-update). */
+  provenanceIdentity?: ProvenanceIdentity;
+}
+
+export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
+  const clock = opts.clock ?? systemClock;
+  const effects = fileEffects(opts.stateDir);
+  const ownership = opts.installOwnership ?? ((): "self" => "self");
+
+  // The last predicate evidence, captured for the promote report (the
+  // engine only carries pass/fail; the report needs the real results).
+  let lastEvidence: ProcessEvidence | null = null;
+  let lastLifecycle: PredicateResult | null = null;
+  /** The report state of the last promote (status + retirement read it). */
+  let lastReport: ReportRead | null = null;
+  let reportLoaded = false;
+  /** Load the persisted report once — a restart must not erase a real observation. */
+  async function currentReport(): Promise<ReportRead> {
+    if (!reportLoaded) {
+      lastReport = await loadLastReport(opts.stateDir);
+      reportLoaded = true;
+    }
+    return lastReport ?? { kind: "genesis" };
+  }
+
+  const engine = new UpgradeEngine({
+    effects,
+    host: opts.host,
+    clock,
+    evaluatePredicates: async (evidence: ProcessEvidence, targetVersion: string) => {
+      lastEvidence = evidence;
+      if (evidence.version !== targetVersion) {
+        return `live process reports ${evidence.version}, expected ${targetVersion}`;
+      }
+      if (opts.lifecycleSurfaces && opts.lifecycleSurfaces.length > 0) {
+        // host_lifecycle_converged: every declared surface must read back
+        // the artifact being promoted (projection ban: metadata cannot).
+        const allowlist = buildSurfaceAllowlist(
+          opts.lifecycleSurfaces.map((surface) => ({
+            surface,
+            expectedTarget: slotArtifactPath(opts.stateDir, "experiment"),
+          })),
+        );
+        const result = await evaluateLifecycleConvergence(allowlist, clock.nowMs());
+        lastLifecycle = result;
+        if (!result.passed) {
+          return `lifecycle surface ${result.source} did not converge: ${JSON.stringify(result.detail)}`;
+        }
+      }
+      return null;
+    },
+  });
+
+  async function readState(): Promise<TxnState> {
+    const slots = await effects.slots.slotVersions();
+    const intents = (await effects.journal.readAll()).map((e) => e.intent);
+    return {
+      phase: intents.at(-1) ?? "idle",
+      stableVersion: slots.stable ?? "0.0.0",
+      experimentVersion: slots.experiment,
+      rollbackReason: null,
+    };
+  }
+
+  /** Report a stage. Observational only: a broken sink cannot break upgrades. */
+  function reportStage(progress: UpgradeProgress): void {
+    try {
+      opts.onProgress?.(progress);
+    } catch {
+      // a host's progress bar must never be able to fail an upgrade
+    }
+  }
+
+  async function notify(kind: Parameters<UpgraderConfig["notificationSink"]>[0]["kind"], detail: Record<string, string>): Promise<void> {
+    await opts.notificationSink({ kind, detail });
+  }
+
+  /** Gates 1-7. `consented` = the user approved THIS version (the confirm was
+   * shown and answered) — the policy gate is skipped, everything else stands. */
+  async function run(
+    pick: (current: string) => Promise<Release | null>,
+    consented = false,
+    provenance: ProvenanceIdentity | null = null,
+  ): Promise<UpgradeOutcome> {
+    const owner = ownership();
+    if (owner === "managed-elsewhere") {
+      await notify("held", { reason: "managed-elsewhere" });
+      return { result: "held", reason: "this install is managed by another manager; it does not upgrade itself" };
+    }
+
+    const lock = await acquireUpgradeLock(opts.stateDir, clock.nowMs());
+    try {
+      await engine.recover(); // finish or undo anything a previous crash left
+
+      const current = (await readState()).stableVersion;
+      reportStage({ stage: "checking" });
+      let release: Release | null;
+      try {
+        release = await pick(current);
+      } catch (err) {
+        // Consent is to a SPECIFIC version: if the source can no longer
+        // serve it (the publisher moved on), the approval is void — a typed
+        // refusal, never a silent switch to whatever is current now.
+        if (consented && err instanceof ArtifactError && err.code === "PINNED_VERSION_MISMATCH") {
+          await notify("held", { reason: "consented-version-unavailable", version: current });
+          return {
+            result: "held",
+            reason: `the approved version is no longer served; nothing was installed`,
+          };
+        }
+        throw err;
+      }
+      if (release === null) return { result: "up-to-date" };
+
+      if (!consented && opts.policy === "notify-only") {
+        await notify("held", { reason: "notify-only", version: release.version });
+        return { result: "held", reason: `policy is notify-only; ${release.version} is available` };
+      }
+      if (!consented && opts.policy === "confirm") {
+        await notify("confirm-request", { version: release.version, current });
+        return { result: "held", reason: `policy requires confirmation before upgrading to ${release.version}` };
+      }
+
+      if (opts.checkCompatibility) {
+        const refusal = await opts.checkCompatibility(current, release.version);
+        if (refusal !== null) {
+          await notify("held", { reason: "incompatible", detail: refusal });
+          return { result: "held", reason: `incompatible: ${refusal}` };
+        }
+      }
+
+      // Resume support: an interrupted download (process death
+      // mid-fetch) leaves its prefix in stateDir/incoming and the next
+      // attempt continues via Range instead of restarting from zero.
+      reportStage({ stage: "downloading", version: release.version });
+      const bytes = await downloadVerified(release, {
+        clock,
+        resumeDir: path.join(opts.stateDir, "incoming"),
+        onProgress: (downloaded, total) =>
+          reportStage({ stage: "downloading", version: release.version, downloaded, total }),
+      });
+      reportStage({ stage: "verifying", version: release.version });
+
+      reportStage({ stage: "staging", version: release.version });
+      const bytesRef = await materializeArtifact(opts.stateDir, bytes);
+
+      // M6 provenance: record WHO drove this reconcile, write-ahead of the txn.
+      if (opts.provenance) {
+        await recordReconcile(opts.provenance, provenance ?? opts.provenanceIdentity, release.version);
+      }
+
+      reportStage({ stage: "handing-over", version: release.version });
+      const outcome = await engine.upgrade({ version: release.version, bytesRef });
+      const finished = await finishUpgradeOutcome(outcome, {
+        notify,
+        reportStage,
+        targetVersion: release.version,
+        declaredSurfaces: (opts.lifecycleSurfaces ?? []).length,
+        nowMs: clock.nowMs(),
+        evidence: lastEvidence,
+        lifecycle: lastLifecycle,
+      });
+      if (finished.report !== null) {
+        lastReport = { kind: "observed", report: finished.report };
+        reportLoaded = true;
+        await persistReport(opts.stateDir, finished.report);
+      }
+      return finished.outcome;
+    } finally {
+      await lock.release();
+    }
+  }
+
+  return {
+    async check(): Promise<{ current: string; target: string | null }> {
+      const current = (await readState()).stableVersion;
+      const release = await opts.source.checkForUpdate({
+        currentVersion: current,
+        platformKey: platformOpsFor().platformKey(),
+      });
+      return { current, target: release?.version ?? null };
+    },
+
+    async upgrade(): Promise<UpgradeOutcome> {
+      return run(async (current) =>
+        opts.source.checkForUpdate({ currentVersion: current, platformKey: platformOpsFor().platformKey() }),
+      );
+    },
+
+    async upgradeTo(version: string, opts2?: { consented?: boolean; provenance?: ProvenanceIdentity }): Promise<UpgradeOutcome> {
+      return run(
+        async (current) =>
+          opts.source.fetchRelease(version, {
+            currentVersion: current,
+            platformKey: platformOpsFor().platformKey(),
+          }),
+        opts2?.consented === true,
+        opts2?.provenance ?? null,
+      );
+    },
+
+    async retireLegacyManager(): Promise<"retired" | { held: string }> {
+      return retireReason(await currentReport());
+    },
+
+    async rollback(reason: string): Promise<"rolled-back" | { held: string }> {
+      const lock = await acquireUpgradeLock(opts.stateDir, clock.nowMs());
+      try {
+        // Gate on the action's nature: settling K's own in-flight
+        // transaction is ALWAYS allowed (a held mid-transaction is a
+        // brick); only NEW modification of a machine AT REST managed
+        // elsewhere is refused.
+        const last = (await effects.journal.readAll()).at(-1)?.intent;
+        const inFlight = last !== undefined && !phaseAtRest(last);
+        if (!inFlight && ownership() === "managed-elsewhere") {
+          await notify("held", { reason: "managed-elsewhere" });
+          return { held: "this install is managed by another manager; it does not roll itself back" };
+        }
+        await engine.recover();
+        await effects.slots.clearExperiment();
+        await notify("rolled-back", { reason });
+        return "rolled-back";
+      } finally {
+        await lock.release();
+      }
+    },
+
+    async state(): Promise<TxnState> {
+      return readState();
+    },
+
+    async status(): Promise<StatusReport> {
+      return buildStatusReport({
+        state: await readState(),
+        lastReport: await currentReport(),
+        policy: opts.policy,
+        provenance: opts.provenance ? await opts.provenance.read() : null,
+      });
+    },
+  };
+}

package/core/src/drive/README.md

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

package/core/src/index.ts

@@ -0,0 +1,17 @@
+// Public API of @botiverse/k-carrier.
+//
+// This barrel is the single supported entry point for the core framework;
+// deep imports into ./core/src/** are internal and not part of the public API.
+
+// The upgrader factory and its configuration.
+export * from "./createUpgrader.ts";
+
+// Core types: Upgrader, UpgraderConfig, UpgradeOutcome, ProvenanceIdentity,
+// NotificationEvent.
+export * from "./upgrader.ts";
+
+// The host boundary an adopter implements: HostAdapter, Slot, ProcessEvidence.
+export * from "./lifecycle/hostAdapter.ts";
+
+// The built-in invariants and their types (WorldSnapshot, Invariant, ...).
+export * from "./invariants.ts";

package/core/src/invariants.ts

@@ -0,0 +1,243 @@
+/**
+ * Invariants — K's shared, executable vocabulary of "what must always be
+ * true", exported as a library rather than buried in K's own tests.
+ *
+ * One definition, three consumers:
+ *   1. K's harness teeth (assert after scripted steps)
+ *   2. the deterministic simulator (assert after EVERY effect, every seed)
+ *   3. adopters — in their own tests and simulations, alongside their own
+ *      app invariants registered in the same shape
+ *
+ * Why this shape: an invariant is a pure predicate over an observable
+ * snapshot. It never reaches into internals, so the same check works
+ * in-process, in simulation, and black-box against `status --json`.
+ * Returning a *reason string* (not a boolean) means a violation explains
+ * itself wherever it fires — including from a seed replay hours later.
+ *
+ * ---------------------------------------------------------------------------
+ * SCOPE — what "the service" means here, stated so nothing is assumed:
+ *
+ *   K reasons about exactly ONE service identity per Upgrader: the process(es)
+ *   its HostAdapter starts and stops. It is NOT a process supervisor for the
+ *   machine and knows nothing about other processes that happen to run the
+ *   same binary.
+ *
+ *   - swap profile: concurrent old-version processes are NORMAL (think many
+ *     open CLI sessions). They are not K-managed, so no invariant here says
+ *     anything about them. `never-dual-run` is vacuous in this profile rather
+ *     than accidentally satisfied.
+ *   - service / hosted: exactly one live incarnation of that identity, which
+ *     is what `never-dual-run` constrains.
+ *
+ *   PROCESS MODEL (v0, declared rather than inferable from call order):
+ *     EXCLUSIVE HANDOFF. At most one incarnation of the K-managed identity is
+ *     alive at a time; a handoff is quiesce -> stop(old) -> start(new) -> prove.
+ *     There is a downtime window by construction, and K makes it short rather
+ *     than pretending it does not exist.
+ *
+ *     Zero-downtime overlap (start new, drain old, then stop old) is a
+ *     DIFFERENT process model, not a flag on this one: it has a legitimate
+ *     "both alive" state, needs a drain contract instead of quiesce, and
+ *     changes which invariants hold. It is NOT implemented (ruled niche for
+ *     v0). Anything claiming K supports it would be claiming a guarantee K
+ *     does not make.
+ *
+ *   OUT OF SCOPE for v0 (deliberately, not by oversight): one binary running
+ *   several instances with different arguments. One Upgrader owns one service
+ *   identity; run one Upgrader per instance (separate stateDir), or have the
+ *   adapter treat the whole set as a single identity. K does not orchestrate
+ *   across instances, and no invariant here should be read as if it did.
+ * ---------------------------------------------------------------------------
+ */
+import type { TxnPhase } from "./txn/state.ts";
+
+/** What an invariant is allowed to see. Mirrors `status --json`. */
+export interface WorldSnapshot {
+  phase: TxnPhase;
+  slots: { stable: string | null; experiment: string | null };
+  /** Live service incarnations observed right now. */
+  liveProcesses: Array<{ slot: "stable" | "experiment"; pid: number; startId: string; version: string }>;
+  /** Journal intents in append order. */
+  journalIntents: TxnPhase[];
+  /**
+   * Opaque, comparable digest of host workload state (sessions/jobs).
+   * Hosts that preserve workloads across upgrade emit a stable digest.
+   */
+  workloadDigest?: string;
+  /**
+   * startId of the incarnation that was live BEFORE the current transition.
+   * Present in real status readbacks; lets oracles prove a restart actually
+   * happened rather than trusting a version string (the same-PID-readiness family).
+   */
+  priorIncarnationStartId?: string;
+  /** Who owns this install: ourselves, or an external manager (PM/injector)? */
+  installOwnership?: "self" | "managed-elsewhere";
+}
+
+/** null = holds; string = why it was violated (shown to humans and in seed replays). */
+export type InvariantResult = string | null;
+
+/**
+ * What the HOST must do for a conditional guarantee to hold (assume-guarantee).
+ * The left side of "if the app satisfies A, K guarantees G" — the app's
+ * responsibility, verifiable by the harness against its adapter. Closed set:
+ * if you need a new one, it is a design decision, not a free-text note.
+ */
+export type HostAssumption =
+  | "quiesce-resume-inverse"        // parked workloads are unchanged while parked
+  | "probe-from-live-process"       // evidence comes from the running process, not files
+  | "compatibility-declared"        // checkCompatibility is implemented and correct
+  | "data-format-backward-compatible" // version N can read what N+1 wrote
+  | "exclusive-handoff"             // one live incarnation at a time: stop old, then start new
+  | "resident-service";             // the host runs a process that is supposed to BE alive
+
+export interface Invariant<S = WorldSnapshot> {
+  id: string;
+  description: string;
+  /**
+   * Empty/absent = K guarantees this UNCONDITIONALLY.
+   * Non-empty = K guarantees it only if the host satisfies these assumptions.
+   * This is how an adopter tells, from the library alone, which guarantees are
+   * ours and which depend on their own code.
+   */
+  assumes?: readonly HostAssumption[];
+  check: (snapshot: S) => InvariantResult;
+}
+
+/**
+ * Never two live incarnations OF THE SERVICE IDENTITY K MANAGES.
+ * Says nothing about other processes running the same binary (see SCOPE):
+ * in the swap profile liveProcesses is empty, so this is vacuous by design.
+ */
+export const neverDualRun: Invariant = {
+  id: "k.never-dual-run",
+  description:
+    "at most one live incarnation of the K-managed service identity (vacuous in the swap profile)",
+  // NOT a universal truth about upgrades — it holds under K's declared process
+  // model (exclusive handoff). An app that starts the new incarnation before
+  // draining the old one is not violating a law of nature; it is running a
+  // model K does not implement (see PROCESS MODEL below).
+  assumes: ["exclusive-handoff"],
+  check: (s) =>
+    s.liveProcesses.length > 1
+      ? `${s.liveProcesses.length} live incarnations: ${s.liveProcesses
+          .map((p) => `${p.slot}#${p.pid}@${p.version}`)
+          .join(", ")}`
+      : null,
+};
+
+/**
+ * Never a host with nothing runnable. Concerns the SLOTS (bytes on disk), not
+ * whether a process is currently up: a stopped service with intact stable
+ * bytes is not bricked.
+ */
+export const neverBricked: Invariant = {
+  id: "k.never-bricked",
+  description: "at least one slot always holds runnable bytes (about slots, not liveness)",
+  check: (s) =>
+    s.slots.stable === null && s.slots.experiment === null
+      ? "both slots empty — nothing left to run"
+      : null,
+};
+
+/**
+ * A live incarnation's version matches the slot it was started from.
+ * Only constrains processes K started; slots reporting null are ignored.
+ */
+export const liveProcessMatchesSlot: Invariant = {
+  id: "k.live-process-matches-slot",
+  description: "a live incarnation's version matches the slot it was started from",
+  check: (s) => {
+    for (const p of s.liveProcesses) {
+      const slotVersion = s.slots[p.slot];
+      if (slotVersion !== null && slotVersion !== p.version) {
+        return `${p.slot} slot holds ${slotVersion} but a live process reports ${p.version}`;
+      }
+    }
+    return null;
+  },
+};
+
+/** Intent is journaled before the phase is entered (WAL ordering). */
+export const journalPrecedesPhase: Invariant = {
+  id: "k.journal-precedes-phase",
+  description: "the current phase was journaled before being entered",
+  check: (s) =>
+    s.phase !== "idle" && !s.journalIntents.includes(s.phase)
+      ? `phase ${s.phase} entered with no journal entry for it`
+      : null,
+};
+
+/**
+ * After promote/rollback the experiment slot is cleared. This is about the
+ * TRANSACTION's own bookkeeping, not about whether a restart has happened yet.
+ */
+export const terminalLeavesNoExperiment: Invariant = {
+  id: "k.terminal-leaves-no-experiment",
+  description: "after promote/rollback the experiment slot is cleared",
+  check: (s) =>
+    (s.phase === "promoted" || s.phase === "rolled-back") && s.slots.experiment !== null
+      ? `phase ${s.phase} but experiment slot still holds ${s.slots.experiment}`
+      : null,
+};
+
+/** A copy owned by another manager never upgrades itself. */
+export const managedCopyNeverSelfUpgrades: Invariant = {
+  id: "k.managed-copy-never-self-upgrades",
+  description: "an install owned by an external manager performs no upgrade of its own",
+  check: (s) =>
+    s.installOwnership === "managed-elsewhere" && s.phase !== "idle"
+      ? `install is managed elsewhere but a transaction reached phase ${s.phase}`
+      : null,
+};
+
+/** The built-in set. Adopters concat their own app invariants. */
+export const BUILT_IN_INVARIANTS: readonly Invariant[] = [
+  neverDualRun,
+  neverBricked,
+  liveProcessMatchesSlot,
+  journalPrecedesPhase,
+  terminalLeavesNoExperiment,
+  managedCopyNeverSelfUpgrades,
+];
+
+/**
+ * Deliberately NOT snapshot invariants — stated here so their absence is a
+ * decision, not an oversight:
+ *  - "no side effect before consent" and "every reconcile is journaled" are
+ *    properties of an EVENT SEQUENCE, not of a single state. Forcing them into
+ *    a snapshot predicate would require smuggling history into the snapshot;
+ *    they are teeth over a scenario trace instead (policy/provenance teeth).
+ */
+
+export interface Violation {
+  invariantId: string;
+  reason: string;
+}
+
+/** Check a snapshot against a set; returns every violation (not just the first). */
+export function checkInvariants(
+  snapshot: WorldSnapshot,
+  invariants: readonly Invariant[] = BUILT_IN_INVARIANTS,
+): Violation[] {
+  const out: Violation[] = [];
+  for (const inv of invariants) {
+    const reason = inv.check(snapshot);
+    if (reason !== null) out.push({ invariantId: inv.id, reason });
+  }
+  return out;
+}
+
+/**
+ * Workload preservation across a transition. Kept separate because it
+ * compares two snapshots rather than judging one — hosts that declare a
+ * workloadDigest get this for free, in upgrade AND rollback paths.
+ */
+export const WORKLOAD_PRESERVED_ASSUMES: readonly HostAssumption[] = ["quiesce-resume-inverse"];
+
+export function workloadPreserved(before: WorldSnapshot, after: WorldSnapshot): InvariantResult {
+  if (before.workloadDigest === undefined || after.workloadDigest === undefined) return null;
+  return before.workloadDigest === after.workloadDigest
+    ? null
+    : `workload digest changed across the transition: ${before.workloadDigest} -> ${after.workloadDigest}`;
+}

package/core/src/lifecycle/hostAdapter.ts

@@ -0,0 +1,77 @@
+/**
+ * HostAdapter is the entire surface a host service must implement to be
+ * upgraded by K. The core calls ONLY this interface — it never knows
+ * host internals. This is the mechanical guarantee behind "any daemon can
+ * use this", and the harness's fake host implements exactly this.
+ *
+ * Contract highlights:
+ *  - quiesce(): workloads (sessions, agents, jobs) must be safely pausable
+ *    and durably parked; state before quiesce() and after resume() must be
+ *    equivalent — including when resume() happens on the ROLLED-BACK slot.
+ *  - healthProbe(): evidence must be bound to one live process (same-PID /
+ *    startId), never assembled from files or caches. A probe that cannot
+ *    prove which process answered is not a probe.
+ *  - start(): may return BEFORE the process exists. Some hosts cannot start
+ *    themselves at all -- a service that is replaced by exiting, letting its
+ *    supervisor respawn it from the new bytes, is started by that supervisor,
+ *    asynchronously. So start() means "the successor has been asked for",
+ *    never "the successor is running": only healthProbe() can say that.
+ *
+ * A consequence worth stating, because it decides who finishes an upgrade:
+ * on such hosts the process driving the transaction DIES on the success path.
+ * The successor finds a journal that stops mid-handover -- indistinguishable
+ * from a crash -- and K resolves it by EVIDENCE (a live process reporting the
+ * experiment version from a different incarnation), never by a flag saying the
+ * restart was planned. A crash could set that flag just as easily.
+ */
+export interface HostAdapter {
+  /** Park all hosted workloads durably. Idempotent. */
+  quiesce(): Promise<void>;
+
+  /** Stop the resident service process tree for the given slot. */
+  stop(slot: Slot): Promise<void>;
+
+  /** Start the resident service from the given slot's binaries. */
+  start(slot: Slot): Promise<void>;
+
+  /**
+   * Probe the LIVE process. Returned evidence must all come from the same
+   * process instance (pid + startId bind the answer to one incarnation).
+   */
+  healthProbe(): Promise<ProcessEvidence>;
+
+  /** Resume workloads parked by quiesce(). Must also work after rollback. */
+  resume(): Promise<void>;
+}
+
+/**
+ * A SLOT is a place on disk that holds one version's bytes — not a channel,
+ * not a release track, not a feature flag.
+ *
+ * K keeps exactly two so that installing never destroys the thing that
+ * currently works:
+ *
+ *   stable      the version you are running and can always fall back to
+ *   experiment  the version being tried right now; discarded if it fails
+ *
+ * "Promote" means the experiment's bytes become the stable ones; "roll back"
+ * means the experiment is thrown away and stable was never touched. That is
+ * the whole reason the transaction can be safe: the fallback is not
+ * reconstructed after a failure, it was never disturbed.
+ *
+ * ⚠️ `stable` here is a POSITION, not the name of a release channel. If your
+ * product also has a channel called "stable" (ours does), they are unrelated:
+ * a channel says which stream you follow, a slot says which copy on disk.
+ */
+export type Slot = "stable" | "experiment";
+
+export interface ProcessEvidence {
+  /** Version string reported by the live process itself. */
+  version: string;
+  pid: number;
+  /**
+   * Monotonic per-incarnation identity (e.g. start timestamp + random),
+   * so evidence cannot be satisfied by a pid reused by another process.
+   */
+  startId: string;
+}