@botiverse/k-carrier 0.1.5 → 0.1.6

package/core/src/createUpgrader.ts

@@ -8,26 +8,24 @@
  */
 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 { fileEffects } 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 type { ProvenanceJournal } from "./provenance/journal.ts";
 import { retireReason } from "./upgrade/retire.ts";
 import { buildStatusReport, type StatusReport } from "./status/report.ts";
 import { persistReport, loadLastReport, type ReportRead } from "./status/reportStore.ts";
 import { recoverUpgrade } from "./upgrade/recover.ts";
+import type { OperationDescriptor } from "./operation.ts";
+import { createOperationLifecycle } from "./operationLifecycle.ts";
+import { driveUpgrade } from "./upgrade/drive.ts";
 
 export interface CreateUpgraderOptions extends UpgraderConfig {
   clock?: Clock;
@@ -121,115 +119,36 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
     };
   }
 
-  /** 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 };
+  const operationLifecycle = createOperationLifecycle(opts.stateDir, clock, readState);
+  const drive = (request: Parameters<typeof driveUpgrade>[1]): Promise<UpgradeOutcome> =>
+    driveUpgrade({
+      stateDir: opts.stateDir,
+      clock,
+      engine,
+      operation: operationLifecycle,
+      ownership,
+      readStableVersion: async () => (await readState()).stableVersion,
+      policy: opts.policy,
+      notificationSink: opts.notificationSink,
+      ...(opts.onProgress ? { onProgress: opts.onProgress } : {}),
+      ...(opts.checkCompatibility ? { checkCompatibility: opts.checkCompatibility } : {}),
+      lifecycleSurfaceCount: (opts.lifecycleSurfaces ?? []).length,
+      evidence: () => lastEvidence,
+      lifecycle: () => lastLifecycle,
+      persistConvergenceReport: async (report) => {
+        lastReport = { kind: "observed", report };
         reportLoaded = true;
-        await persistReport(opts.stateDir, finished.report);
-      }
-      return finished.outcome;
-    } finally {
-      await lock.release();
-    }
-  }
+        await persistReport(opts.stateDir, report);
+      },
+      ...(opts.provenance ? { provenanceJournal: opts.provenance } : {}),
+      ...(opts.provenanceIdentity ? { provenanceIdentity: opts.provenanceIdentity } : {}),
+    }, request);
 
   return {
-    recover: () => recoverUpgrade(opts.stateDir, clock, engine),
+    recover: async () => {
+      operationLifecycle.reset();
+      await recoverUpgrade(opts.stateDir, clock, engine, operationLifecycle.settleRecovery);
+    },
 
     async check(): Promise<{ current: string; target: string | null }> {
       const current = (await readState()).stableVersion;
@@ -241,21 +160,29 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
     },
 
     async upgrade(): Promise<UpgradeOutcome> {
-      return run(async (current) =>
-        opts.source.checkForUpdate({ currentVersion: current, platformKey: platformOpsFor().platformKey() }),
-      );
+      return drive({
+        pick: 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, {
+    async upgradeTo(version: string, opts2?: {
+      consented?: boolean;
+      provenance?: ProvenanceIdentity;
+      operation?: OperationDescriptor;
+    }): Promise<UpgradeOutcome> {
+      return drive({
+        pick: async (current) => opts.source.fetchRelease(version, {
             currentVersion: current,
             platformKey: platformOpsFor().platformKey(),
-          }),
-        opts2?.consented === true,
-        opts2?.provenance ?? null,
-      );
+        }),
+        consented: opts2?.consented === true,
+        ...(opts2?.provenance ? { provenance: opts2.provenance } : {}),
+        ...(opts2?.operation ? { operation: opts2.operation } : {}),
+        targetVersionHint: version,
+      });
     },
 
     async retireLegacyManager(): Promise<"retired" | { held: string }> {
@@ -272,12 +199,12 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
         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" });
+          await opts.notificationSink({ kind: "held", detail: { 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 });
+        await opts.notificationSink({ kind: "rolled-back", detail: { reason } });
         return "rolled-back";
       } finally {
         await lock.release();
@@ -296,5 +223,16 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
         provenance: opts.provenance ? await opts.provenance.read() : null,
       });
     },
+
+    operation: operationLifecycle.read,
+
+    async acknowledgeOperation(operationId) {
+      const lock = await acquireUpgradeLock(opts.stateDir, clock.nowMs());
+      try {
+        return await operationLifecycle.acknowledge(operationId);
+      } finally {
+        await lock.release();
+      }
+    },
   };
 }

package/core/src/index.ts

@@ -13,6 +13,7 @@ export * from "./bootstrap.ts";
 // Core types: Upgrader, UpgraderConfig, UpgradeOutcome, ProvenanceIdentity,
 // NotificationEvent.
 export * from "./upgrader.ts";
+export * from "./operation.ts";
 
 // The release-source boundary applications implement and the durable
 // provenance journal they wire into createUpgrader.

package/core/src/operation.ts

@@ -0,0 +1,179 @@
+/**
+ * K-owned durable operation receipt.
+ *
+ * Hosts may project this record into their own UI or transport, but they do
+ * not maintain a second upgrade state machine. The operation receipt is the
+ * single durable answer to: what is running, which version was requested,
+ * what stable version can be restored, and whether the terminal receipt has
+ * already been acknowledged by the host transport.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { platformOpsFor } from "./platform/index.ts";
+import type { ProvenanceIdentity } from "./upgrader.ts";
+
+const OPERATION_FILE = "operation.json";
+export const OPERATION_FORMAT_VERSION = 1;
+
+export type OperationPhase =
+  | "checking"
+  | "downloading"
+  | "verifying"
+  | "staging"
+  | "handing-over"
+  | "probing"
+  | "recovering"
+  | "promoted"
+  | "rolled-back"
+  | "held"
+  | "up-to-date"
+  | "failed";
+
+export type OperationOutcome = "promoted" | "rolled-back" | "held" | "up-to-date" | "failed";
+
+const OPERATION_PHASES = new Set<OperationPhase>([
+  "checking",
+  "downloading",
+  "verifying",
+  "staging",
+  "handing-over",
+  "probing",
+  "recovering",
+  "promoted",
+  "rolled-back",
+  "held",
+  "up-to-date",
+  "failed",
+]);
+const OPERATION_OUTCOMES = new Set<OperationOutcome>([
+  "promoted",
+  "rolled-back",
+  "held",
+  "up-to-date",
+  "failed",
+]);
+
+export interface OperationDescriptor {
+  id: string;
+  startedAtMs: number;
+  provenance?: ProvenanceIdentity;
+  /** Opaque non-secret host correlation fields (for example server/request ids). */
+  metadata?: Record<string, string>;
+}
+
+export interface OperationRecord {
+  formatVersion: typeof OPERATION_FORMAT_VERSION;
+  id: string;
+  startedAtMs: number;
+  updatedAtMs: number;
+  fromVersion: string;
+  targetVersion: string;
+  /** The stable version that was current when this operation began. */
+  previousStableVersion: string;
+  phase: OperationPhase;
+  outcome: OperationOutcome | null;
+  reason: string | null;
+  provenance: ProvenanceIdentity | null;
+  metadata: Record<string, string>;
+  /** Host transport receipt, not a second transaction outcome. */
+  acknowledgedAtMs: number | null;
+}
+
+export type OperationRead =
+  | { kind: "genesis" }
+  | { kind: "observed"; operation: OperationRecord }
+  | { kind: "unreadable"; reason: string };
+
+function operationPath(stateDir: string): string {
+  return path.join(stateDir, OPERATION_FILE);
+}
+
+function validIdentity(value: unknown): value is ProvenanceIdentity {
+  return Boolean(
+    value
+    && typeof value === "object"
+    && typeof (value as ProvenanceIdentity).who === "string"
+    && typeof (value as ProvenanceIdentity).carrier === "string",
+  );
+}
+
+function parseOperation(text: string): OperationRecord {
+  const parsed = JSON.parse(text) as Partial<OperationRecord>;
+  if (
+    parsed.formatVersion !== OPERATION_FORMAT_VERSION
+    || typeof parsed.id !== "string"
+    || parsed.id.length === 0
+    || typeof parsed.startedAtMs !== "number"
+    || !Number.isFinite(parsed.startedAtMs)
+    || typeof parsed.updatedAtMs !== "number"
+    || !Number.isFinite(parsed.updatedAtMs)
+    || typeof parsed.fromVersion !== "string"
+    || typeof parsed.targetVersion !== "string"
+    || typeof parsed.previousStableVersion !== "string"
+    || typeof parsed.phase !== "string"
+    || !OPERATION_PHASES.has(parsed.phase as OperationPhase)
+    || !(parsed.outcome === null || (
+      typeof parsed.outcome === "string"
+      && OPERATION_OUTCOMES.has(parsed.outcome as OperationOutcome)
+    ))
+    || !(parsed.reason === null || typeof parsed.reason === "string")
+    || !(parsed.provenance === null || validIdentity(parsed.provenance))
+    || typeof parsed.metadata !== "object"
+    || parsed.metadata === null
+    || Array.isArray(parsed.metadata)
+    || Object.values(parsed.metadata).some((value) => typeof value !== "string")
+    || !(parsed.acknowledgedAtMs === null || typeof parsed.acknowledgedAtMs === "number")
+  ) {
+    throw new Error("operation record has an invalid shape");
+  }
+  return parsed as OperationRecord;
+}
+
+/** Atomic and durable replacement. K's upgrade lock serializes writers. */
+export async function persistOperation(stateDir: string, operation: OperationRecord): Promise<void> {
+  await fs.mkdir(stateDir, { recursive: true });
+  const target = operationPath(stateDir);
+  const tmp = `${target}.tmp`;
+  const fh = await fs.open(tmp, "w");
+  try {
+    await fh.writeFile(JSON.stringify(operation));
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await platformOpsFor().renamePath(tmp, target);
+}
+
+export async function loadOperation(stateDir: string): Promise<OperationRead> {
+  let text: string;
+  try {
+    text = await fs.readFile(operationPath(stateDir), "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { kind: "genesis" };
+    return { kind: "unreadable", reason: `cannot read ${OPERATION_FILE} (${code ?? (error as Error).message})` };
+  }
+  try {
+    return { kind: "observed", operation: parseOperation(text) };
+  } catch (error) {
+    return { kind: "unreadable", reason: `corrupt ${OPERATION_FILE}: ${(error as Error).message}` };
+  }
+}
+
+export async function acknowledgeOperation(
+  stateDir: string,
+  operationId: string,
+  acknowledgedAtMs: number,
+): Promise<"acknowledged" | "not-terminal" | "not-found" | "changed"> {
+  const current = await loadOperation(stateDir);
+  if (current.kind === "genesis") return "not-found";
+  if (current.kind === "unreadable") throw new Error(current.reason);
+  if (current.operation.id !== operationId) return "changed";
+  if (current.operation.outcome === null) return "not-terminal";
+  await persistOperation(stateDir, {
+    ...current.operation,
+    updatedAtMs: acknowledgedAtMs,
+    acknowledgedAtMs,
+  });
+  return "acknowledged";
+}

package/core/src/operationLifecycle.ts

@@ -0,0 +1,113 @@
+import type { Clock } from "./clock.ts";
+import { phaseAtRest, type TxnState } from "./txn/state.ts";
+import type { ProvenanceIdentity } from "./upgrader.ts";
+import {
+  acknowledgeOperation,
+  loadOperation,
+  persistOperation,
+  type OperationDescriptor,
+  type OperationOutcome,
+  type OperationPhase,
+  type OperationRead,
+  type OperationRecord,
+} from "./operation.ts";
+
+export interface OperationLifecycle {
+  begin(
+    descriptor: OperationDescriptor | null,
+    fromVersion: string,
+    targetVersion: string,
+    provenance: ProvenanceIdentity | null,
+  ): Promise<void>;
+  transition(input: {
+    phase: OperationPhase;
+    outcome?: OperationOutcome | null;
+    reason?: string | null;
+  }): Promise<void>;
+  settleRecovery(): Promise<void>;
+  reset(): void;
+  read(): Promise<OperationRead>;
+  acknowledge(operationId: string): Promise<"acknowledged" | "not-terminal" | "not-found" | "changed">;
+}
+
+export function createOperationLifecycle(
+  stateDir: string,
+  clock: Clock,
+  readState: () => Promise<TxnState>,
+): OperationLifecycle {
+  let record: OperationRecord | null = null;
+
+  const transition: OperationLifecycle["transition"] = async (input) => {
+    if (record === null) return;
+    record = {
+      ...record,
+      updatedAtMs: clock.nowMs(),
+      phase: input.phase,
+      outcome: input.outcome === undefined ? record.outcome : input.outcome,
+      reason: input.reason === undefined ? record.reason : input.reason,
+    };
+    await persistOperation(stateDir, record);
+  };
+
+  return {
+    async begin(descriptor, fromVersion, targetVersion, provenance) {
+      if (descriptor === null) return;
+      const existing = await loadOperation(stateDir);
+      if (existing.kind === "unreadable") throw new Error(existing.reason);
+      if (existing.kind === "observed" && existing.operation.id !== descriptor.id) {
+        if (existing.operation.outcome === null) {
+          throw new Error(`OPERATION_IN_PROGRESS: ${existing.operation.id}`);
+        }
+        if (existing.operation.acknowledgedAtMs === null) {
+          throw new Error(`OPERATION_RECEIPT_PENDING: ${existing.operation.id}`);
+        }
+      }
+      if (existing.kind === "observed" && existing.operation.id === descriptor.id) {
+        record = existing.operation;
+        return;
+      }
+      record = {
+        formatVersion: 1,
+        id: descriptor.id,
+        startedAtMs: descriptor.startedAtMs,
+        updatedAtMs: clock.nowMs(),
+        fromVersion,
+        targetVersion,
+        previousStableVersion: fromVersion,
+        phase: "checking",
+        outcome: null,
+        reason: null,
+        provenance: descriptor.provenance ?? provenance,
+        metadata: { ...descriptor.metadata },
+        acknowledgedAtMs: null,
+      };
+      await persistOperation(stateDir, record);
+    },
+
+    transition,
+
+    async settleRecovery() {
+      const observed = await loadOperation(stateDir);
+      if (observed.kind !== "observed" || observed.operation.outcome !== null) return;
+      record = observed.operation;
+      const state = await readState();
+      if (state.phase === "promoted" && state.stableVersion === record.targetVersion) {
+        await transition({ phase: "promoted", outcome: "promoted" });
+      } else if (phaseAtRest(state.phase)) {
+        await transition({
+          phase: "rolled-back",
+          outcome: "rolled-back",
+          reason: state.rollbackReason ?? `recovery settled at ${state.phase} with stable ${state.stableVersion}`,
+        });
+      }
+    },
+
+    reset() {
+      record = null;
+    },
+
+    read: () => loadOperation(stateDir),
+
+    acknowledge: (operationId) => acknowledgeOperation(stateDir, operationId, clock.nowMs()),
+  };
+}

package/core/src/upgrade/drive.ts

@@ -0,0 +1,177 @@
+import * as path from "node:path";
+import type { Release } from "../artifact/source.ts";
+import { downloadVerified } from "../artifact/download.ts";
+import { ArtifactError } from "../artifact/errors.ts";
+import { materializeArtifact } from "../txn/fileEffects.ts";
+import { acquireUpgradeLock } from "../txn/lock.ts";
+import type { UpgradeEngine, EngineOutcome } from "../txn/engine.ts";
+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 type { OperationLifecycle } from "../operationLifecycle.ts";
+import type {
+  NotificationEvent,
+  ProvenanceIdentity,
+  UpgradeOutcome,
+} from "../upgrader.ts";
+import type { ProvenanceJournal } from "../provenance/journal.ts";
+import { recordReconcile } from "../provenance/journal.ts";
+import { finishUpgradeOutcome } from "./outcome.ts";
+
+export interface UpgradeDriveDeps {
+  stateDir: string;
+  clock: Clock;
+  engine: UpgradeEngine;
+  operation: OperationLifecycle;
+  ownership: () => "self" | "managed-elsewhere";
+  readStableVersion: () => Promise<string>;
+  policy: "auto" | "confirm" | "notify-only";
+  notificationSink: (event: NotificationEvent) => Promise<void>;
+  onProgress?: (progress: UpgradeProgress) => void;
+  checkCompatibility?: (from: string, to: string) => Promise<string | null>;
+  lifecycleSurfaceCount: number;
+  evidence: () => ProcessEvidence | null;
+  lifecycle: () => PredicateResult | null;
+  persistConvergenceReport: (report: ConvergenceReport) => Promise<void>;
+  provenanceJournal?: ProvenanceJournal;
+  provenanceIdentity?: ProvenanceIdentity;
+}
+
+export interface UpgradeDriveRequest {
+  pick: (current: string) => Promise<Release | null>;
+  consented?: boolean;
+  provenance?: ProvenanceIdentity;
+  operation?: OperationDescriptor;
+  targetVersionHint?: string;
+}
+
+export async function driveUpgrade(
+  deps: UpgradeDriveDeps,
+  request: UpgradeDriveRequest,
+): Promise<UpgradeOutcome> {
+  const notify = (kind: NotificationEvent["kind"], detail: Record<string, string>) =>
+    deps.notificationSink({ kind, detail });
+  const progress = (value: UpgradeProgress): void => {
+    try { deps.onProgress?.(value); } catch { /* observation cannot fail an upgrade */ }
+  };
+  if (deps.ownership() === "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(deps.stateDir, deps.clock.nowMs());
+  try {
+    await deps.engine.recover();
+    await deps.operation.settleRecovery();
+    const current = await deps.readStableVersion();
+    await deps.operation.begin(
+      request.operation ?? null,
+      current,
+      request.targetVersionHint ?? current,
+      request.provenance ?? null,
+    );
+    progress({ stage: "checking" });
+
+    let release: Release | null;
+    try {
+      release = await request.pick(current);
+    } catch (error) {
+      if (request.consented && error instanceof ArtifactError && error.code === "PINNED_VERSION_MISMATCH") {
+        await deps.operation.transition({ phase: "held", outcome: "held", reason: "consented-version-unavailable" });
+        await notify("held", { reason: "consented-version-unavailable", version: current });
+        return { result: "held", reason: "the approved version is no longer served; nothing was installed" };
+      }
+      await deps.operation.transition({
+        phase: "failed",
+        outcome: "failed",
+        reason: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+    if (release === null) {
+      await deps.operation.transition({ phase: "up-to-date", outcome: "up-to-date" });
+      return { result: "up-to-date" };
+    }
+    if (!request.consented && deps.policy === "notify-only") {
+      await deps.operation.transition({ phase: "held", outcome: "held", reason: "notify-only" });
+      await notify("held", { reason: "notify-only", version: release.version });
+      return { result: "held", reason: `policy is notify-only; ${release.version} is available` };
+    }
+    if (!request.consented && deps.policy === "confirm") {
+      await deps.operation.transition({ phase: "held", outcome: "held", reason: "confirmation-required" });
+      await notify("confirm-request", { version: release.version, current });
+      return { result: "held", reason: `policy requires confirmation before upgrading to ${release.version}` };
+    }
+    const refusal = deps.checkCompatibility
+      ? await deps.checkCompatibility(current, release.version)
+      : null;
+    if (refusal !== null) {
+      await deps.operation.transition({ phase: "held", outcome: "held", reason: refusal });
+      await notify("held", { reason: "incompatible", detail: refusal });
+      return { result: "held", reason: `incompatible: ${refusal}` };
+    }
+
+    await deps.operation.transition({ phase: "downloading" });
+    progress({ stage: "downloading", version: release.version });
+    const bytes = await downloadVerified(release, {
+      clock: deps.clock,
+      resumeDir: path.join(deps.stateDir, "incoming"),
+      onProgress: (downloaded, total) =>
+        progress({ stage: "downloading", version: release.version, downloaded, total }),
+    });
+    await deps.operation.transition({ phase: "verifying" });
+    progress({ stage: "verifying", version: release.version });
+    await deps.operation.transition({ phase: "staging" });
+    progress({ stage: "staging", version: release.version });
+    const bytesRef = await materializeArtifact(deps.stateDir, bytes);
+    if (deps.provenanceJournal) {
+      await recordReconcile(
+        deps.provenanceJournal,
+        request.provenance ?? deps.provenanceIdentity,
+        release.version,
+      );
+    }
+
+    await deps.operation.transition({ phase: "handing-over" });
+    progress({ stage: "handing-over", version: release.version });
+    let engineOutcome: EngineOutcome;
+    try {
+      engineOutcome = await deps.engine.upgrade({ version: release.version, bytesRef });
+    } catch (error) {
+      await deps.operation.transition({
+        phase: "recovering",
+        reason: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+    const finished = await finishUpgradeOutcome(engineOutcome, {
+      notify,
+      reportStage: progress,
+      targetVersion: release.version,
+      declaredSurfaces: deps.lifecycleSurfaceCount,
+      nowMs: deps.clock.nowMs(),
+      evidence: deps.evidence(),
+      lifecycle: deps.lifecycle(),
+    });
+    if (finished.report !== null) await deps.persistConvergenceReport(finished.report);
+    switch (finished.outcome.result) {
+      case "promoted":
+        await deps.operation.transition({ phase: "promoted", outcome: "promoted" });
+        break;
+      case "rolled-back":
+        await deps.operation.transition({ phase: "rolled-back", outcome: "rolled-back", reason: finished.outcome.reason });
+        break;
+      case "held":
+        await deps.operation.transition({ phase: "held", outcome: "held", reason: finished.outcome.reason });
+        break;
+      case "up-to-date":
+        await deps.operation.transition({ phase: "up-to-date", outcome: "up-to-date" });
+        break;
+    }
+    return finished.outcome;
+  } finally {
+    await lock.release();
+  }
+}

package/core/src/upgrade/recover.ts

@@ -7,10 +7,12 @@ export async function recoverUpgrade(
   stateDir: string,
   clock: Clock,
   engine: UpgradeEngine,
+  afterRecover?: () => Promise<void>,
 ): Promise<void> {
   const lock = await acquireUpgradeLock(stateDir, clock.nowMs());
   try {
     await engine.recover();
+    await afterRecover?.();
   } finally {
     await lock.release();
   }

package/core/src/upgrader.ts

@@ -3,6 +3,7 @@ import type { TxnState } from "./txn/state.js";
 import type { ConvergenceReport } from "./converge/predicates.js";
 import type { StatusReport } from "./status/report.js";
 import type { ReleaseSource } from "./artifact/source.js";
+import type { OperationDescriptor, OperationRead } from "./operation.js";
 
 /**
  * Who drove a reconcile, recorded in the provenance journal (M6, L5).
@@ -62,7 +63,11 @@ export interface Upgrader {
    * silently installing whatever is current now. Consent is to a SPECIFIC
    * version, never to "the upgrade" as an event.
    */
-  upgradeTo(version: string, opts?: { consented?: boolean; provenance?: ProvenanceIdentity }): Promise<UpgradeOutcome>;
+  upgradeTo(version: string, opts?: {
+    consented?: boolean;
+    provenance?: ProvenanceIdentity;
+    operation?: OperationDescriptor;
+  }): Promise<UpgradeOutcome>;
 
   /**
    * Explicit rollback while an experiment is live (pre-promote).
@@ -95,6 +100,12 @@ export interface Upgrader {
    * are null (NOT_OBSERVED), never a fabricated pass.
    */
   status(): Promise<StatusReport>;
+
+  /** 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">;
 }
 
 export type UpgradeOutcome =

package/docs/integration.md

@@ -241,6 +241,35 @@ The stages are not a parallel state machine: they are derived from the L1
 transaction phases (`stageForPhase`), so a progress display can never show a
 state the transaction does not have.
 
+## 4.6 One durable operation receipt
+
+When a host detaches the transaction driver from the service it replaces,
+pass an exact operation descriptor to `upgradeTo`. K then owns the only
+durable operation state, including the previous stable version and terminal
+outcome:
+
+```ts
+await upgrader.upgradeTo("2.0.0", {
+  consented: true,
+  operation: {
+    id: requestId,
+    startedAtMs: Date.now(),
+    metadata: { originServerId }, // non-secret host correlation only
+  },
+});
+
+const receipt = await upgrader.operation();
+if (receipt.kind === "observed" && receipt.operation.outcome !== null) {
+  await deliver(receipt.operation);
+  await upgrader.acknowledgeOperation(receipt.operation.id);
+}
+```
+
+The host may project this receipt into UI or transport, but must not maintain
+a second pending/status/previous-version state machine. `recover()` settles an
+active receipt under K's upgrade lock before the host reads it again. A corrupt
+or future-version receipt is `unreadable`, never treated as genesis or success.
+
 ## 5. Publishing releases
 
 If you use the built-in `staticManifestSource`, its layout is:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/k-carrier",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "packageManager": "pnpm@11.18.0",
   "description": "A fail-closed upgrade carrier for long-running managed services: two-slot upgrade transactions (promote/rollback), host-driven quiesce/resume handoff, and post-upgrade convergence read-back.",
   "repository": {