@botiverse/k-carrier 0.1.8 → 0.2.0

package/core/src/txn/engine.ts

@@ -7,6 +7,8 @@
  *  - Crash anywhere -> recover() lands on stable-running or completes the
  *    transition, decided by journal replay. Never dual-run, never bricked.
  *  - Promote only after the caller-supplied predicate evaluation passed.
+ *  - Readback is bound to a NEW incarnation: the startId probed before
+ *    handover is journaled, and evidence carrying it again is refused.
  *  - Rollback is always available until promote; its reason is journaled.
  */
 import type { HostAdapter, ProcessEvidence } from "../lifecycle/hostAdapter.ts";
@@ -14,7 +16,7 @@ import type { TxnEffects } from "./effects.ts";
 import type { JournalEntry, TxnPhase } from "./state.ts";
 import { STATE_FORMAT_VERSION } from "./state.ts";
 import type { Clock } from "../clock.ts";
-import { HostCallTimeout, DEFAULT_HOST_CALL_BUDGET_MS } from "./hostCallBudget.ts";
+import { HostCallTimeout, HostCallUncertain, DEFAULT_HOST_CALL_BUDGET_MS } from "./hostCallBudget.ts";
 
 
 export interface EngineDeps {
@@ -53,6 +55,8 @@ export class UpgradeEngine {
   private seq = 0;
 
   constructor(deps: EngineDeps) {
+    const budget = deps.hostCallBudgetMs ?? DEFAULT_HOST_CALL_BUDGET_MS;
+    if (!Number.isSafeInteger(budget) || budget <= 0 || budget > 2_147_483_647) throw new Error("invalid host call budget");
     this.deps = deps;
   }
 
@@ -71,6 +75,7 @@ export class UpgradeEngine {
    * Must be called before upgrade() on every process start.
    */
   async recover(): Promise<void> {
+    if (this.deps.host.fence) await this.withBudget("fence", () => this.deps.host.fence!());
     const entries = await this.deps.effects.journal.readAll();
     const last = entries.at(-1);
     this.seq = (last?.seq ?? -1) + 1;
@@ -89,16 +94,16 @@ export class UpgradeEngine {
         // resume is part of the terminal action too. A crash after promote()
         // but before resume() used to leave the service alive and its hosted
         // work permanently parked; DST found this exact effect boundary.
-        await this.deps.host.resume();
+        await this.withBudget("resume", () => this.deps.host.resume());
         return;
       case "rolled-back":
         // The terminal journal entry is WAL intent, not proof that the host
         // restore ran. Redo the whole idempotent rollback action: a crash
         // immediately after journaling `rolled-back` may still have the
         // experiment process live and workloads parked.
-        await this.deps.host.stop("experiment");
-        await this.deps.host.start("stable");
-        await this.deps.host.resume();
+        await this.withBudget("stop", () => this.deps.host.stop("experiment"));
+        await this.withBudget("start", () => this.deps.host.start("stable"));
+        await this.withBudget("resume", () => this.deps.host.resume());
         await this.deps.effects.slots.clearExperiment();
         return;
       case "staged":
@@ -108,15 +113,8 @@ export class UpgradeEngine {
       case "handing-over":
       case "running-experiment":
       case "readback": {
-        // We may have died with the experiment (partially) live -- or the
-        // handover succeeded and killed the process that was driving it.
-        // EVIDENCE decides, never a "this restart was planned" flag: a flag is
-        // a claim the crash path could make just as easily.
-        if (version !== null && (await this.handoverSucceeded(last, version))) {
-          await this.finishHandover(version);
-          return;
-        }
-        // Fail closed: stop whatever runs, restore stable, resume workloads.
+        // Runner death before the commit intent always undoes the attempt.
+        // A healthy candidate does not authorize a successor to commit it.
         await this.rollbackTo(`crash during ${last.intent}` + (version ? ` (experiment ${version})` : ""));
         return;
       }
@@ -134,20 +132,23 @@ export class UpgradeEngine {
     const versions = await this.deps.effects.slots.slotVersions();
     if (versions.stable === target.version) return { result: "up-to-date" };
 
+    // Record the incarnation this upgrade replaces, before anything on disk
+    // changes. A failed probe provides no usable baseline; it does not prove
+    // the service is stopped. The controller must still confirm stop before
+    // start. An uncertain probe is let out, as for the readback probe below.
+    let prior: ProcessEvidence | null = null;
+    try {
+      prior = await this.withBudget("healthProbe", () => this.deps.host.healthProbe());
+    } catch (err) {
+      if (err instanceof HostCallUncertain) throw err;
+      prior = null;
+    }
+
     await this.journal("staged", { version: target.version });
     await this.deps.effects.slots.stageExperiment(target);
 
-    // Who is handing over. Recorded BEFORE the handover because on some hosts
-    // this very process does not survive it: a service that is replaced by
-    // exiting (its supervisor respawns it from the new bytes) dies here on the
-    // SUCCESS path, and the successor -- not us -- finishes the transaction.
-    // Without this identity the successor cannot tell "the handover worked"
-    // from "we crashed mid-handover", because both leave the same journal.
-    const priorStartId = await this.probeStartId();
-    await this.journal("handing-over", {
-      version: target.version,
-      ...(priorStartId === null ? {} : { priorStartId }),
-    });
+    // The external runner survives normal service replacement.
+    await this.journal("handing-over", { version: target.version, ...(prior ? { priorStartId: prior.startId } : {}) });
     await this.withBudget("quiesce", () => this.deps.host.quiesce());
     await this.withBudget("stop", () => this.deps.host.stop("stable"));
     await this.withBudget("start", () => this.deps.host.start("experiment"));
@@ -164,69 +165,36 @@ export class UpgradeEngine {
       // how a stuck upgrade becomes two live incarnations. Let it out; the
       // journal keeps the in-flight phase and the next start resolves it from
       // evidence.
-      if (err instanceof HostCallTimeout) throw err;
+      if (err instanceof HostCallUncertain) throw err;
       return this.rollbackOutcome(`experiment probe failed: ${(err as Error).message}`);
     }
 
     await this.journal("readback", { version: target.version });
-    const refusal = await this.deps.evaluatePredicates(evidence, target.version);
+    // The same startId after stop/start means the old process answered: it
+    // was never stopped, or the probe served cached evidence. A version
+    // string alone cannot tell those apart; the incarnation identity can.
+    if (prior !== null && evidence.startId === prior.startId) {
+      return this.rollbackOutcome(
+        `live process is still the pre-upgrade incarnation (startId ${evidence.startId}); the old service was not replaced`,
+      );
+    }
+    const refusal = await this.withBudget("readback", () => this.deps.evaluatePredicates(evidence, target.version));
     if (refusal !== null) {
       return this.rollbackOutcome(`predicates refused: ${refusal}`);
     }
 
     await this.journal("promoted", { version: target.version });
     await this.deps.effects.slots.promoteExperiment();
-    await this.deps.host.resume();
+    await this.withBudget("resume", () => this.deps.host.resume());
     return { result: "promoted", version: target.version };
   }
 
-  /**
-   * Did the handover actually happen? True only when a live process reports
-   * the EXPERIMENT version from a DIFFERENT incarnation than the one that
-   * journaled the handover. Same incarnation answering => nothing was
-   * replaced, whatever it claims about its version.
-   */
-  private async handoverSucceeded(last: JournalEntry, experimentVersion: string): Promise<boolean> {
-    const priorStartId = last.detail.priorStartId;
-    // No recorded identity (older journal, or a host whose probe was
-    // unavailable) => we cannot prove a successor exists => fail closed.
-    if (priorStartId === undefined) return false;
-    let evidence: ProcessEvidence;
-    try {
-      evidence = await this.withBudget("healthProbe", () => this.deps.host.healthProbe());
-    } catch {
-      return false; // nothing alive to vouch for the handover
-    }
-    return evidence.version === experimentVersion && evidence.startId !== priorStartId;
-  }
-
-  /** Finish a transaction whose handover outlived the process that began it. */
-  private async finishHandover(experimentVersion: string): Promise<void> {
-    let evidence: ProcessEvidence;
-    try {
-      evidence = await this.withBudget("healthProbe", () => this.deps.host.healthProbe());
-    } catch (err) {
-      if (err instanceof HostCallTimeout) throw err; // same rule: do not act on a wedged host
-      await this.rollbackTo(`successor probe failed: ${(err as Error).message}`);
-      return;
-    }
-    await this.journal("readback", { version: experimentVersion });
-    const refusal = await this.deps.evaluatePredicates(evidence, experimentVersion);
-    if (refusal !== null) {
-      await this.rollbackTo(`predicates refused after handover: ${refusal}`);
-      return;
-    }
-    await this.journal("promoted", { version: experimentVersion });
-    await this.deps.effects.slots.promoteExperiment();
-    await this.deps.host.resume();
-  }
-
   /**
    * Bound a host call. On expiry we do NOT pretend the call failed cleanly:
    * a pending promise cannot be cancelled in JS, so the host may still be
    * mid-operation. The transaction gives up instead of issuing further host
    * calls it cannot reason about, and the journal records why. Recovery is
-   * the next process start, which probes for evidence and decides from facts.
+   * the next process start, which replays the durable commit or restores stable.
    */
   private async withBudget<T>(label: string, call: () => Promise<T>): Promise<T> {
     const budgetMs = this.deps.hostCallBudgetMs ?? DEFAULT_HOST_CALL_BUDGET_MS;
@@ -245,18 +213,6 @@ export class UpgradeEngine {
     }
   }
 
-  /** Best-effort identity of the live process; null when nothing answers. */
-  private async probeStartId(): Promise<string | null> {
-    try {
-      // Budgeted like every other host call: found by the wedged-host test,
-      // which hung HERE -- an unbounded probe before the handover is the same
-      // trap one line earlier.
-      return (await this.withBudget("healthProbe", () => this.deps.host.healthProbe())).startId;
-    } catch {
-      return null;
-    }
-  }
-
   private async rollbackOutcome(reason: string): Promise<EngineOutcome> {
     await this.rollbackTo(reason);
     return { result: "rolled-back", reason };
@@ -266,9 +222,9 @@ export class UpgradeEngine {
     await this.journal("rolled-back", { reason });
     if (!opts.skipHostRestart) {
       // Stop whatever may be running (either slot), restore stable, resume.
-      await this.deps.host.stop("experiment");
-      await this.deps.host.start("stable");
-      await this.deps.host.resume();
+      await this.withBudget("stop", () => this.deps.host.stop("experiment"));
+      await this.withBudget("start", () => this.deps.host.start("stable"));
+      await this.withBudget("resume", () => this.deps.host.resume());
     }
     await this.deps.effects.slots.clearExperiment();
   }

package/core/src/txn/fileEffects.ts

@@ -38,6 +38,9 @@ export function fileJournalStore(stateDir: string): JournalStore {
       } finally {
         await fh.close();
       }
+      // The first append creates the file; its directory entry is only
+      // durable once the parent is fsync'd. Cheap enough to do every time.
+      await platformOpsFor().syncDirectory(stateDir);
     },
     async readAll(): Promise<JournalEntry[]> {
       let text: string;
@@ -80,6 +83,13 @@ export function fileSlotStore(stateDir: string): SlotStore {
       // bytesRef is a path to the verified bytes the caller downloaded.
       await fs.copyFile(artifact.bytesRef, path.join(staging, ARTIFACT_FILE));
       await fs.writeFile(path.join(staging, VERSION_FILE), artifact.version);
+      // Flush copied bytes, version metadata and their names before publication.
+      // Syncing only the parent after rename does not persist file contents.
+      for (const name of [ARTIFACT_FILE, VERSION_FILE]) {
+        const handle = await fs.open(path.join(staging, name), "r+");
+        try { await handle.sync(); } finally { await handle.close(); }
+      }
+      await platformOpsFor().syncDirectory(staging);
       // Publish the slot atomically: a half-written experiment must never be
       // visible as a stageable slot.
       await fs.rm(dir, { recursive: true, force: true });
@@ -95,7 +105,11 @@ export function fileSlotStore(stateDir: string): SlotStore {
       const stable = slotDir(stateDir, "stable");
       if ((await readVersion("experiment")) === null) return; // idempotent redo
       await fs.rm(`${stable}.old`, { recursive: true, force: true });
-      await platformOpsFor().renamePath(stable, `${stable}.old`).catch(() => {});
+      const stableExists = await fs.stat(stable).then(() => true, (error: NodeJS.ErrnoException) => {
+        if (error.code === "ENOENT") return false; // replay after the first rename
+        throw error;
+      });
+      if (stableExists) await platformOpsFor().renamePath(stable, `${stable}.old`);
       await platformOpsFor().renamePath(experiment, stable);
       await fs.rm(`${stable}.old`, { recursive: true, force: true });
     },

package/core/src/txn/hostCallBudget.ts

@@ -15,8 +15,11 @@
  */
 export const DEFAULT_HOST_CALL_BUDGET_MS = 120_000;
 
+import { HostCallUncertain } from "./hostCallUncertain.ts";
+export { HostCallUncertain } from "./hostCallUncertain.ts";
+
 /** A host call exceeded its budget: the host is wedged, not merely failing. */
-export class HostCallTimeout extends Error {
+export class HostCallTimeout extends HostCallUncertain {
   readonly call: string;
   readonly budgetMs: number;
   constructor(call: string, budgetMs: number) {

package/core/src/txn/hostCallUncertain.ts

@@ -0,0 +1,2 @@
+/** An effect may still execute; retain transaction ownership until worker exit. */
+export class HostCallUncertain extends Error {}

package/core/src/txn/lock.ts

@@ -17,6 +17,7 @@
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { platformOpsFor } from "../platform/index.ts";
 
 /** Bounded retries: an unclaimable lock is a typed failure, never a hang. */
@@ -53,46 +54,89 @@ export async function acquireUpgradeLock(stateDir: string, nowMs: number): Promi
   await fs.mkdir(stateDir, { recursive: true });
   const ops = platformOpsFor();
 
-  const record: LockRecord = { pid: process.pid, acquiredAtMs: nowMs };
-  let attempts = 0;
-  for (;;) {
-    try {
-      // wx: fails if the file exists — the atomic "claim it" primitive.
-      const fh = await fs.open(lockPath, "wx");
+  // Unique contender directories are visible atomically, before inspecting the
+  // legacy lock file. Never unlink a live contender or reuse its path. This
+  // closes both the empty-file publication window and double stale-unlink race.
+  const claims = path.join(stateDir, "upgrade.lock.claims");
+  await fs.mkdir(claims, { recursive: true });
+  const name = `${process.pid}-${randomUUID()}`;
+  const claim = path.join(claims, name);
+  await fs.mkdir(claim);
+  const removeClaim = async (): Promise<void> => {
+    try { await fs.rmdir(claim); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  };
+  try {
+    for (const other of await fs.readdir(claims)) {
+      if (other === name) continue;
+      const pid = Number(other.split("-")[0]);
+      if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("UPGRADE_LOCK_UNREADABLE");
+      if (ops.isProcessAlive(pid)) throw new UpgradeLockError(pid);
+      await fs.rmdir(path.join(claims, other)).catch((error: NodeJS.ErrnoException) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+  } catch (error) {
+    await removeClaim();
+    throw error;
+  }
+  let acquired = false;
+  try {
+    const record: LockRecord = { pid: process.pid, acquiredAtMs: nowMs };
+    let attempts = 0;
+    for (;;) {
       try {
-        await fh.writeFile(JSON.stringify(record));
-      } finally {
-        await fh.close();
-      }
-      return {
-        async release() {
-          await fs.rm(lockPath, { force: true });
-        },
-      };
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
-      attempts += 1;
-      if (attempts > MAX_ATTEMPTS) {
-        // Never spin forever: a lock we can neither claim nor clear is a
-        // typed failure, not a hang. (Hangs hide bugs; failures report them.)
-        throw new Error(
-          `[UPGRADE_LOCK_UNRESOLVABLE] could not acquire or clear ${lockPath} after ${MAX_ATTEMPTS} attempts`,
-          { cause: err },
-        );
-      }
-      const holder = await readHolder(lockPath);
-      if (holder === "vanished") continue; // gone between open and read: retry
-      // A non-positive pid is never a real holder — and must NEVER reach
-      // process.kill, where pid<=0 addresses process GROUPS or every process.
-      if (holder !== "unreadable" && holder.pid > 0 && ops.isProcessAlive(holder.pid)) {
-        throw new UpgradeLockError(holder.pid);
+        // wx: fails if the file exists — the atomic "claim it" primitive.
+        const fh = await fs.open(lockPath, "wx");
+        try {
+          await fh.writeFile(JSON.stringify(record));
+        } finally {
+          await fh.close();
+        }
+        acquired = true;
+        let released = false;
+        return {
+          async release() {
+            if (released) return;
+            // Quarantine can move this entire state directory. A replacement
+            // directory at the same pathname belongs to a different owner.
+            try { await fs.stat(claim); }
+            catch (error) {
+              if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+              released = true;
+              return;
+            }
+            await fs.rm(lockPath, { force: true });
+            await removeClaim();
+            released = true;
+          },
+        };
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+        attempts += 1;
+        if (attempts > MAX_ATTEMPTS) {
+          // Never spin forever: a lock we can neither claim nor clear is a
+          // typed failure, not a hang. (Hangs hide bugs; failures report them.)
+          throw new Error(
+            `[UPGRADE_LOCK_UNRESOLVABLE] could not acquire or clear ${lockPath} after ${MAX_ATTEMPTS} attempts`,
+            { cause: err },
+          );
+        }
+        const holder = await readHolder(lockPath);
+        if (holder === "vanished") continue; // gone between open and read: retry
+        // A non-positive pid is never a real holder — and must NEVER reach
+        // process.kill, where pid<=0 addresses process GROUPS or every process.
+        if (holder !== "unreadable" && holder.pid > 0 && ops.isProcessAlive(holder.pid)) {
+          throw new UpgradeLockError(holder.pid);
+        }
+        // Holder is gone: its transaction died mid-flight. Recovery (journal
+        // replay) will decide what to do with the state; clear the lock and
+        // take it. The contender guard above serializes stale-file removal.
+        await fs.rm(lockPath, { force: true });
       }
-      // Holder is gone: its transaction died mid-flight. Recovery (journal
-      // replay) will decide what to do with the state; clear the lock and
-      // take it. Removing a specific stale file is safe to race — whoever
-      // wins the next `wx` owns the lock.
-      await fs.rm(lockPath, { force: true });
     }
+  } finally {
+    if (!acquired) await removeClaim();
   }
 }
 

package/core/src/txn/state.ts

@@ -124,7 +124,7 @@ export type TxnStateInput =
  *
  * The one place an inconsistent persisted world can slip in is the runtime
  * boundary that reads the journal and slots but only knows the phase at
- * runtime (see `createUpgrader.readState`); that boundary must decide the
+ * runtime (see `createRunner.readState`); that boundary must decide the
  * phase before calling this, failing closed if a phase is in flight but the
  * experiment slot is empty.
  */

package/core/src/upgrade/drive.ts

@@ -1,3 +1,4 @@
+import { HostCallUncertain } from "../txn/hostCallBudget.ts";
 import * as path from "node:path";
 import type { Release } from "../artifact/source.ts";
 import { downloadVerified } from "../artifact/download.ts";
@@ -14,7 +15,7 @@ import type { Clock } from "../clock.ts";
 import type { UpgradeProgress } from "../progress.ts";
 import type { ProcessEvidence } from "../lifecycle/hostAdapter.ts";
 import type { PredicateResult, ConvergenceReport } from "../converge/predicates.ts";
-import type { OperationDescriptor } from "../operation.ts";
+import { OperationReplay, loadArchivedOperation, type OperationDescriptor } from "../operation.ts";
 import type { OperationLifecycle } from "../operationLifecycle.ts";
 import type {
   NotificationEvent,
@@ -69,9 +70,28 @@ export async function driveUpgrade(
   }
 
   const lock = await acquireUpgradeLock(deps.stateDir, deps.clock.nowMs());
+  let releaseLock = true;
   try {
+    deps.operation.reset();
+    // Inspect under the transaction lock, before recovery or any new host action.
+    const latest = await deps.operation.read();
+    if (latest.kind === "unreadable") throw new Error(latest.reason);
+    const archived = request.operation ? await loadArchivedOperation(deps.stateDir, request.operation.id) : { kind: "genesis" as const };
+    if (archived.kind === "unreadable") throw new Error(archived.reason);
+    const prior = archived.kind === "observed" ? archived : latest;
+    if (request.operation && prior.kind === "observed" && prior.operation.id === request.operation.id) {
+      if (prior.operation.targetVersion !== request.targetVersionHint) {
+        throw new Error("OPERATION_ID_CONFLICT: request id is already bound to another version");
+      }
+      if (prior.operation.outcome !== null) throw new OperationReplay(prior.operation);
+    }
     await deps.engine.recover();
     await deps.operation.settleRecovery();
+    const recovered = await deps.operation.read();
+    if (request.operation && recovered.kind === "observed" &&
+        recovered.operation.id === request.operation.id && recovered.operation.outcome !== null) {
+      throw new OperationReplay(recovered.operation);
+    }
     const current = await deps.readStableVersion();
     await deps.operation.begin(
       request.operation ?? null,
@@ -97,6 +117,10 @@ export async function driveUpgrade(
       });
       throw error;
     }
+    if (release !== null && request.targetVersionHint !== undefined && release.version !== request.targetVersionHint) {
+      await deps.operation.transition({ phase: "failed", outcome: "failed", reason: "target-version-mismatch" });
+      throw new Error("PINNED_VERSION_MISMATCH: release source returned a different target");
+    }
     if (release === null) {
       await deps.operation.transition({ phase: "up-to-date", outcome: "up-to-date" });
       return { result: "up-to-date" };
@@ -182,7 +206,12 @@ export async function driveUpgrade(
         break;
     }
     return finished.outcome;
+  } catch (error) {
+    // A timed-out promise may still execute. Keep ownership until this worker
+    // exits; its successor must fence external controller effects as well.
+    if (error instanceof HostCallUncertain) releaseLock = false;
+    throw error;
   } finally {
-    await lock.release();
+    if (releaseLock) await lock.release();
   }
 }

package/core/src/upgrade/outcome.ts

@@ -1,7 +1,7 @@
 /**
  * finishUpgradeOutcome — the engine outcome becomes the facade outcome:
  * report the stage, notify the sink, build the convergence report
- * (promoted only), and return. Split out of createUpgrader so that file
+ * (promoted only), and return. Split out of createRunner so that file
  * stays under the line budget; the semantics are unchanged from the inline
  * version.
  */

package/core/src/upgrade/recover.ts

@@ -1,3 +1,5 @@
+import { HostCallUncertain } from "../txn/hostCallBudget.ts";
+import { loadOperation, loadArchivedOperation, OperationReplay } from "../operation.ts";
 import type { Clock } from "../clock.ts";
 import type { UpgradeEngine } from "../txn/engine.ts";
 import { acquireUpgradeLock } from "../txn/lock.ts";
@@ -8,12 +10,31 @@ export async function recoverUpgrade(
   clock: Clock,
   engine: UpgradeEngine,
   afterRecover?: () => Promise<void>,
+  expected?: { id: string; targetVersion: string },
 ): Promise<void> {
   const lock = await acquireUpgradeLock(stateDir, clock.nowMs());
+  let release = true;
   try {
+    const current = await loadOperation(stateDir);
+    if (current.kind === "unreadable") throw new Error(current.reason);
+    if (expected) {
+      const archived = await loadArchivedOperation(stateDir, expected.id);
+      if (archived.kind === "unreadable") throw new Error(archived.reason);
+      const prior = archived.kind === "observed" ? archived : current;
+      if (prior.kind !== "observed" || prior.operation.id !== expected.id) {
+        throw new Error("RECOVERY_OPERATION_NOT_FOUND");
+      }
+      if (prior.operation.targetVersion !== expected.targetVersion) throw new Error("OPERATION_ID_CONFLICT");
+      if (prior.operation.outcome !== null) throw new OperationReplay(prior.operation);
+    }
     await engine.recover();
     await afterRecover?.();
+  } catch (error) {
+    // A timed-out promise may still execute. Keep ownership until this worker
+    // exits; its successor must fence external controller effects as well.
+    if (error instanceof HostCallUncertain) release = false;
+    throw error;
   } finally {
-    await lock.release();
+    if (release) await lock.release();
   }
 }

package/core/src/upgrade/retire.ts

@@ -1,6 +1,6 @@
 /**
  * retireReason — the fail-closed retirement gate (M5, extracted from
- * createUpgrader for the line budget). The legacy lifecycle manager may be
+ * createRunner for the line budget). The legacy lifecycle manager may be
  * retired ONLY after host_lifecycle_converged passed on the last promote;
  * before that, retirement is refused with a typed HOLD — removing the old
  * supervisor without a converged replacement leaves the machine with

package/core/src/upgrader.ts

@@ -19,11 +19,9 @@ export interface ProvenanceIdentity {
 }
 
 /**
- * Upgrader is the single facade an application calls. Every entrypoint the
- * app exposes (daemon-internal auto-update, `myapp self upgrade`, install
- * script, remote drive) constructs the SAME Upgrader — one canonical
- * executor, so there is no entrypoint that "swaps bytes but skips
- * convergence" (the class of bug this framework exists to kill).
+ * Upgrader is the transaction facade constructed by createRunner
+ * inside the disposable runner. Application entry points submit runner
+ * requests; they do not construct an in-process upgrade engine.
  */
 export interface Upgrader {
   /**
@@ -35,7 +33,7 @@ export interface Upgrader {
    * recorded by K. Hosts should run this from a coordinator that survives
    * service replacement, because recovery may stop and restart the service.
    */
-  recover(): Promise<void>;
+  recover(expected?: { id: string; targetVersion: string }): Promise<void>;
 
   /**
    * Ask the release source whether this install should move, without moving
@@ -105,9 +103,6 @@ export interface Upgrader {
   /** K's single durable operation receipt; hosts project it, never mirror it. */
   operation(): Promise<OperationRead>;
 
-  /** Mark one exact terminal operation delivered by the host transport. */
-  acknowledgeOperation(operationId: string): Promise<"acknowledged" | "not-terminal" | "not-found" | "changed">;
-
   /** Atomically move quiesced K state to an audit-only fresh-install backup. */
   quarantineState(options: QuarantineOptions): Promise<QuarantineResult>;
 }