@botiverse/k-carrier 0.1.5 → 0.1.7

package/core/src/artifact/download.ts

@@ -32,42 +32,9 @@ import { ArtifactError } from "./errors.ts";
 import type { Release } from "./source.ts";
 import { collectStream } from "./collectStream.ts";
 import { partialPathFor } from "./partialPath.ts";
+import type { DownloadOptions } from "./transferPolicy.ts";
 export { partialPathFor } from "./partialPath.ts";
-
-export interface DownloadOptions {
-  /**
-   * Byte progress. `downloaded` counts bytes ON DISK including any resumed
-   * prefix, so a resumed download never appears to restart at zero.
-   */
-  onProgress?: (downloaded: number, total: number) => void;
-  clock?: Clock;
-  /** Abort the download after this many ms (0 = no timeout). Default 10000. */
-  timeoutMs?: number;
-  /**
-   * Abort after this many ms with NO bytes arriving (0 = off). Default 0.
-   *
-   * Distinct from `timeoutMs`, and for large artifacts the more useful of the
-   * two: a total budget must either be big enough for the slowest acceptable
-   * download of a 150MB binary -- in which case a wedged connection holds for
-   * just as long -- or small enough to kill a slow one that was making steady
-   * progress. Bounding SILENCE instead follows liveness, so the limit does not
-   * have to encode a guess about size or bandwidth.
-   */
-  stallTimeoutMs?: number;
-  /**
-   * HTTP client for the artifact bytes. `staticManifestSource` already takes
-   * one; without the same seam here an adopter can point K at their own server
-   * for the MANIFEST but not for the BYTES, which is half a seam and surprising
-   * in exactly the place it matters (proxies, custom agents, and an adopter's
-   * own integration tests all need both).
-   */
-  fetchImpl?: typeof fetch;
-  /**
-   * Directory for partial-download state. When set, an interrupted download
-   * leaves its prefix here and the next attempt resumes via Range.
-   */
-  resumeDir?: string;
-}
+export type { DownloadOptions } from "./transferPolicy.ts";
 
 /** Fetch and verify one release's bytes, resuming from a partial if present. */
 export async function downloadVerified(
@@ -92,7 +59,9 @@ export async function downloadVerified(
 
   const bytes = await fetchAndAppend(
     url, partialPath, partialSize, clock, timeoutMs, opts.onProgress, release.size,
-    opts.stallTimeoutMs ?? 0, opts.fetchImpl ?? fetch,
+    opts.responseTimeoutMs ?? opts.stallTimeoutMs ?? 0,
+    opts.idleTimeoutMs ?? opts.stallTimeoutMs ?? 0,
+    opts.fetchImpl ?? fetch,
   );
 
   const sha = sha256Hex(bytes);
@@ -129,26 +98,24 @@ async function fetchAndAppend(
   timeoutMs: number,
   onProgress?: (downloaded: number, total: number) => void,
   total?: number,
-  stallTimeoutMs = 0,
+  responseTimeoutMs = 0,
+  idleTimeoutMs = 0,
   doFetch: typeof fetch = fetch,
 ): Promise<Uint8Array> {
   const controller = new AbortController();
-  // Rearmed on every chunk; fires only if the gap between chunks exceeds the
-  // budget. `stalled` records WHY we aborted, because the abort itself cannot
-  // say -- a stall and a total-timeout abort look identical at the signal.
-  let stalled = false;
-  let stallTimer: (() => void) | undefined;
+  // Body liveness is rearmed on every chunk. `timeoutKind` records WHY we
+  // aborted because the abort signal cannot distinguish the three budgets.
+  let timeoutKind: "overall" | "response" | "idle" | null = null;
+  let responseTimer: (() => void) | undefined;
+  let idleTimer: (() => void) | undefined;
   // Invoked when a deadline fires so the pending fetch cannot outlive it.
   let aborted: (() => void) | undefined;
-  // Which phase we were in when the deadline fired. Reporting "awaiting
-  // response" for a stall that happened mid-body sends the reader looking at
-  // the wrong end of the transfer.
-  let responded = false;
   const abortReason = (u: string): string =>
-    stalled
-      ? `download stalled: nothing received for ${stallTimeoutMs}ms ` +
-        `(${responded ? "mid-body" : "awaiting response"}): ${u}`
-      : `download timed out after ${timeoutMs}ms: ${u}`;
+    timeoutKind === "response"
+      ? `download response timed out after ${responseTimeoutMs}ms (awaiting response): ${u}`
+      : timeoutKind === "idle"
+        ? `download stalled: nothing received for ${idleTimeoutMs}ms (mid-body): ${u}`
+        : `download timed out after ${timeoutMs}ms: ${u}`;
   // Declared AFTER `aborted`: an immediate/virtual clock fires this callback
   // synchronously inside `clock.after`, so a timer created earlier would reach
   // `aborted` in its temporal dead zone. Real clocks hide that ordering; the
@@ -156,15 +123,25 @@ async function fetchAndAppend(
   const cancel =
     timeoutMs > 0
       ? clock.after(timeoutMs, () => {
+          timeoutKind = "overall";
           controller.abort();
           aborted?.();
         })
       : undefined;
-  const armStall = (): void => {
-    if (stallTimeoutMs <= 0) return;
-    stallTimer?.();
-    stallTimer = clock.after(stallTimeoutMs, () => {
-      stalled = true;
+  const armResponse = (): void => {
+    if (responseTimeoutMs <= 0) return;
+    responseTimer?.();
+    responseTimer = clock.after(responseTimeoutMs, () => {
+      timeoutKind = "response";
+      controller.abort();
+      aborted?.();
+    });
+  };
+  const armIdle = (): void => {
+    if (idleTimeoutMs <= 0) return;
+    idleTimer?.();
+    idleTimer = clock.after(idleTimeoutMs, () => {
+      timeoutKind = "idle";
       controller.abort();
       aborted?.();
     });
@@ -173,7 +150,7 @@ async function fetchAndAppend(
     const headers: Record<string, string> = {};
     if (partialSize > 0) headers["Range"] = `bytes=${partialSize}-`;
     let res: Response;
-    armStall(); // the response headers themselves must not hang forever
+    armResponse();
     try {
       // Race the abort, do not merely signal it. `AbortSignal` only works if the
       // fetch implementation honours it, and `fetchImpl` is an adopter-supplied
@@ -193,11 +170,7 @@ async function fetchAndAppend(
       const timedOut = controller.signal.aborted;
       throw new ArtifactError(
         "DOWNLOAD_FAILED",
-        stalled
-          ? `download stalled: nothing received for ${stallTimeoutMs}ms (awaiting response): ${url}`
-          : timedOut
-            ? `download timed out after ${timeoutMs}ms: ${url}`
-            : `fetch failed: ${url}`,
+        timedOut ? abortReason(url) : `fetch failed: ${url}`,
         { cause: err },
       );
     }
@@ -209,8 +182,9 @@ async function fetchAndAppend(
     // server that answers slowly and then streams normally is killed by a
     // deadline that started before the request was even answered -- and the
     // failure reports "awaiting response" while bytes were on their way.
-    responded = true;
-    armStall();
+    responseTimer?.();
+    responseTimer = undefined;
+    armIdle();
 
     if (partialPath === null) {
       // Stream even with nowhere to resume to. `res.arrayBuffer()` is one
@@ -219,7 +193,7 @@ async function fetchAndAppend(
       // silently had no byte progress and no stall detection at all, while
       // both looked configured.
       try {
-        return await collectStream(url, res.body, total, onProgress, armStall);
+        return await collectStream(url, res.body, total, onProgress, armIdle);
       } catch (err) {
         // Same classification as the resume path. Without this the in-memory
         // branch reported a bare stream error, so an abort we ourselves caused
@@ -248,10 +222,10 @@ async function fetchAndAppend(
       // reads as "it lost my download" to the person watching it.
       let onDisk = partialSize;
       onProgress?.(onDisk, total ?? 0);
-      armStall();
+      armIdle();
       await streamToFile(res.body, fh, (chunk) => {
         onDisk += chunk;
-        armStall();
+        armIdle();
         onProgress?.(onDisk, total ?? 0);
       });
       await fh.sync();
@@ -262,11 +236,7 @@ async function fetchAndAppend(
       const timedOut = controller.signal.aborted;
       throw new ArtifactError(
         "DOWNLOAD_FAILED",
-        stalled
-          ? `download stalled: nothing received for ${stallTimeoutMs}ms (mid-body): ${url}`
-          : timedOut
-            ? `download timed out after ${timeoutMs}ms: ${url}`
-            : `download interrupted: ${url}`,
+        timedOut ? abortReason(url) : `download interrupted: ${url}`,
         { cause: err },
       );
     } finally {
@@ -275,7 +245,8 @@ async function fetchAndAppend(
     return new Uint8Array(await fs.readFile(partialPath));
   } finally {
     cancel?.();
-    stallTimer?.();
+    responseTimer?.();
+    idleTimer?.();
   }
 }
 

package/core/src/artifact/transferPolicy.ts

@@ -0,0 +1,82 @@
+/**
+ * Production artifact-transfer budgets.
+ *
+ * Response latency, progress liveness, and total duration answer different
+ * questions. Keeping them separate prevents a healthy large transfer from
+ * being killed by the same deadline that bounds an unreachable server.
+ */
+import type { Clock } from "../clock.ts";
+
+export interface DownloadOptions {
+  /** Byte progress, including any prefix already present on disk. */
+  onProgress?: (downloaded: number, total: number) => void;
+  clock?: Clock;
+  /** Whole-download bound (0 = off). Legacy direct-call default is 10000. */
+  timeoutMs?: number;
+  /** Maximum wait for response headers (0 = off). */
+  responseTimeoutMs?: number;
+  /** Maximum silence between response-body chunks (0 = off). */
+  idleTimeoutMs?: number;
+  /** Legacy alias for both responseTimeoutMs and idleTimeoutMs. */
+  stallTimeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  /** Directory holding a resumable partial artifact. */
+  resumeDir?: string;
+}
+
+export interface ArtifactTransferPolicy {
+  /** Maximum wait for response headers. */
+  responseTimeoutMs: number;
+  /** Maximum silence between response-body chunks. */
+  idleTimeoutMs: number;
+  /** Slowest sustained body rate accepted when deriving the size budget. */
+  minimumBytesPerSecond: number;
+  /** Absolute ceiling even when the declared artifact is very large. */
+  maximumOverallTimeoutMs: number;
+}
+
+export interface ArtifactTransferTimeouts {
+  responseTimeoutMs: number;
+  idleTimeoutMs: number;
+  overallTimeoutMs: number;
+}
+
+export const DEFAULT_ARTIFACT_TRANSFER_POLICY: ArtifactTransferPolicy = {
+  responseTimeoutMs: 30_000,
+  idleTimeoutMs: 30_000,
+  minimumBytesPerSecond: 64 * 1024,
+  maximumOverallTimeoutMs: 30 * 60_000,
+};
+
+function requirePositiveInteger(name: string, value: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`ARTIFACT_TRANSFER_POLICY_INVALID: ${name} must be a positive safe integer`);
+  }
+}
+
+/** Derive the bounded total budget from the release authority's exact size. */
+export function artifactTransferTimeouts(
+  artifactSize: number,
+  policy: ArtifactTransferPolicy = DEFAULT_ARTIFACT_TRANSFER_POLICY,
+): ArtifactTransferTimeouts {
+  requirePositiveInteger("artifactSize", artifactSize);
+  requirePositiveInteger("responseTimeoutMs", policy.responseTimeoutMs);
+  requirePositiveInteger("idleTimeoutMs", policy.idleTimeoutMs);
+  requirePositiveInteger("minimumBytesPerSecond", policy.minimumBytesPerSecond);
+  requirePositiveInteger("maximumOverallTimeoutMs", policy.maximumOverallTimeoutMs);
+  if (policy.maximumOverallTimeoutMs < policy.responseTimeoutMs) {
+    throw new Error(
+      "ARTIFACT_TRANSFER_POLICY_INVALID: maximumOverallTimeoutMs must cover responseTimeoutMs",
+    );
+  }
+
+  const bodyBudgetMs = Math.ceil((artifactSize * 1_000) / policy.minimumBytesPerSecond);
+  return {
+    responseTimeoutMs: policy.responseTimeoutMs,
+    idleTimeoutMs: policy.idleTimeoutMs,
+    overallTimeoutMs: Math.min(
+      policy.maximumOverallTimeoutMs,
+      policy.responseTimeoutMs + bodyBudgetMs,
+    ),
+  };
+}

package/core/src/createUpgrader.ts

@@ -7,27 +7,26 @@
  * 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 { assertNever, buildTxnState, phaseAtRest, type TxnState } from "./txn/state.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";
+import type { ArtifactTransferPolicy } from "./artifact/transferPolicy.ts";
 
 export interface CreateUpgraderOptions extends UpgraderConfig {
   clock?: Clock;
@@ -60,6 +59,12 @@ export interface CreateUpgraderOptions extends UpgraderConfig {
   provenance?: ProvenanceJournal;
   /** Identity recorded for reconciles that carry none (local auto-update). */
   provenanceIdentity?: ProvenanceIdentity;
+  /**
+   * Independent response, idle, and size-derived total budgets for artifact
+   * bytes. Defaults are safe for Computer-sized binaries; adopters may make
+   * them stricter, but cannot disable every bound.
+   */
+  artifactTransferPolicy?: ArtifactTransferPolicy;
 }
 
 export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
@@ -113,123 +118,70 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
   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}` };
+    const phase = intents.at(-1) ?? "idle";
+    const stableVersion = slots.stable ?? "0.0.0";
+    const experimentVersion = slots.experiment;
+    switch (phase) {
+      case "idle":
+      case "promoted":
+        return buildTxnState({ phase, stableVersion });
+      case "rolled-back":
+        return buildTxnState({ phase, stableVersion });
+      case "staged":
+      case "handing-over":
+      case "running-experiment":
+      case "readback": {
+        // In-flight phases always carry an experiment. A persisted world that
+        // says an in-flight phase has an empty experiment slot is
+        // inconsistent, and we fail closed rather than fabricate a value that
+        // would be a type lie at this (the only runtime) boundary.
+        if (experimentVersion === null) {
+          throw new Error(
+            `TXN_STATE_INCONSISTENT: phase ${phase} is in-flight but the experiment slot is empty`,
+          );
         }
+        return buildTxnState({ phase, stableVersion, experimentVersion });
       }
-
-      // 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();
+      default:
+        // Matches phaseAtRest's exhaustive discipline: an unknown phase from a
+        // newer core is not silently reinterpreted.
+        return assertNever(phase);
     }
   }
 
+  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, report);
+      },
+      ...(opts.provenance ? { provenanceJournal: opts.provenance } : {}),
+      ...(opts.provenanceIdentity ? { provenanceIdentity: opts.provenanceIdentity } : {}),
+      ...(opts.artifactTransferPolicy
+        ? { artifactTransferPolicy: opts.artifactTransferPolicy }
+        : {}),
+    }, 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 +193,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 +232,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 +256,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,10 +13,12 @@ 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.
 export * from "./artifact/source.ts";
+export * from "./artifact/transferPolicy.ts";
 export * from "./provenance/journal.ts";
 
 // The host boundary an adopter implements: HostAdapter, Slot, ProcessEvidence.

package/core/src/operation.ts

@@ -0,0 +1,182 @@
+/**
+ * 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";
+  // Exact replay is idempotent. The first delivery time is part of the audit
+  // receipt; a retry must not rewrite it or manufacture a later delivery.
+  if (current.operation.acknowledgedAtMs !== null) return "acknowledged";
+  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/txn/state.ts

@@ -30,7 +30,7 @@ export type TxnPhase =
  * default, never the exclusion-list trap where every future terminal
  * phase silently becomes "in-flight" = allowed to modify.
  */
-function assertNever(x: never): never {
+export function assertNever(x: never): never {
   throw new Error(`unknown TxnPhase ${String(x)}; refusing to classify — a phase a newer core wrote must not be touched`);
 }
 
@@ -53,13 +53,34 @@ export function phaseAtRest(phase: TxnPhase): boolean {
   }
 }
 
-export interface TxnState {
-  phase: TxnPhase;
-  stableVersion: string;
-  experimentVersion: string | null;
-  /** Why the last rollback happened; null unless phase === "rolled-back". */
-  rollbackReason: string | null;
-}
+/**
+ * A discriminated union so that an "illegal" combination is not representable:
+ *
+ *  - terminal / at-rest phases (`idle`, `promoted`, `rolled-back`) NEVER carry
+ *    an experiment — an experiment slot that outlives a terminal phase is a
+ *    leaked transaction (k.terminal-leaves-no-experiment would fire at runtime;
+ *    here it is a compile error instead).
+ *  - in-flight phases (`staged`..`readback`) ALWAYS carry an experiment — that
+ *    is exactly what "in flight" means.
+ *  - only `rolled-back` may carry a `rollbackReason`.
+ *
+ * Construction must choose a member consistent with `phase`; a `switch` over
+ * `TxnState` narrows each member and forces every phase to make a decision
+ * (the same discipline as `phaseAtRest`, lifted to the whole record).
+ */
+export type TxnState =
+  | { phase: "idle"; stableVersion: string; experimentVersion: null; rollbackReason: null }
+  | {
+      phase: "staged" | "handing-over" | "running-experiment" | "readback";
+      stableVersion: string;
+      experimentVersion: string;
+      rollbackReason: null;
+    }
+  | { phase: "promoted"; stableVersion: string; experimentVersion: null; rollbackReason: null }
+  | { phase: "rolled-back"; stableVersion: string; experimentVersion: null; rollbackReason: string | null };
+
+/** The in-flight, experiment-carrying phases (a helper for exhaustive narrowing). */
+export const IN_FLIGHT_PHASES = ["staged", "handing-over", "running-experiment", "readback"] as const;
 
 /** Append-only, write-ahead journal entry. fsync'd before the action runs. */
 export interface JournalEntry {
@@ -75,3 +96,51 @@ export interface JournalEntry {
  * silently reinterpret. Encoded as a version field checked before replay.
  */
 export const STATE_FORMAT_VERSION = 1;
+
+/**
+ * The strongly-typed input to `buildTxnState`. The argument is itself a
+ * discriminated union over the phase, so an illegal input combination does
+ * not type-check: a terminal/at-rest phase simply cannot carry an experiment,
+ * only `rolled-back` may carry a reason, and an in-flight phase must carry
+ * one. This is the "impossible states" discipline applied to the constructor's
+ * arguments, not just its result.
+ */
+export type TxnStateInput =
+  | { phase: "idle" | "promoted"; stableVersion: string }
+  | { phase: "rolled-back"; stableVersion: string; rollbackReason?: string | null }
+  | {
+      phase: "staged" | "handing-over" | "running-experiment" | "readback";
+      stableVersion: string;
+      experimentVersion: string;
+    };
+
+/**
+ * Soundly construct a `TxnState` member from a discriminated input.
+ *
+ * The input type already forbids the illegal combinations (an in-flight phase
+ * cannot be given a missing experiment, a terminal phase cannot be given an
+ * experiment, only `rolled-back` may carry a reason), so the result is sound
+ * by construction — there is no per-phase coercion to get wrong here.
+ *
+ * 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
+ * phase before calling this, failing closed if a phase is in flight but the
+ * experiment slot is empty.
+ */
+export function buildTxnState(input: TxnStateInput): TxnState {
+  switch (input.phase) {
+    case "idle":
+    case "promoted":
+      return { phase: input.phase, stableVersion: input.stableVersion, experimentVersion: null, rollbackReason: null };
+    case "rolled-back":
+      return { phase: input.phase, stableVersion: input.stableVersion, experimentVersion: null, rollbackReason: input.rollbackReason ?? null };
+    case "staged":
+    case "handing-over":
+    case "running-experiment":
+    case "readback":
+      return { phase: input.phase, stableVersion: input.stableVersion, experimentVersion: input.experimentVersion, rollbackReason: null };
+    default:
+      return assertNever(input);
+  }
+}

package/core/src/upgrade/drive.ts

@@ -0,0 +1,188 @@
+import * as path from "node:path";
+import type { Release } from "../artifact/source.ts";
+import { downloadVerified } from "../artifact/download.ts";
+import {
+  artifactTransferTimeouts,
+  type ArtifactTransferPolicy,
+  type DownloadOptions,
+} from "../artifact/transferPolicy.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;
+  artifactTransferPolicy?: ArtifactTransferPolicy;
+  downloadArtifact?: (release: Release, opts: DownloadOptions) => Promise<Uint8Array>;
+}
+
+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 transfer = artifactTransferTimeouts(release.size, deps.artifactTransferPolicy);
+    const bytes = await (deps.downloadArtifact ?? downloadVerified)(release, {
+      clock: deps.clock,
+      resumeDir: path.join(deps.stateDir, "incoming"),
+      timeoutMs: transfer.overallTimeoutMs,
+      responseTimeoutMs: transfer.responseTimeoutMs,
+      idleTimeoutMs: transfer.idleTimeoutMs,
+      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

@@ -237,10 +237,62 @@ Three things worth knowing before you draw a bar with it:
   and discards anything it throws. An observation surface must never become
   a failure mode — if your renderer breaks, the upgrade still completes.
 
+Artifact transfer has three independent fail-closed budgets. Response headers
+must arrive promptly, body progress must not go silent, and the full transfer
+has a hard ceiling derived from the release source's declared byte size. The
+defaults accept a Computer-sized binary that takes longer than ten seconds
+while still bounding an unreachable server and a wedged mid-body stream. An
+adopter with stricter network requirements may provide all four policy fields:
+
+```ts
+createUpgrader({
+  ...,
+  artifactTransferPolicy: {
+    responseTimeoutMs: 20_000,
+    idleTimeoutMs: 30_000,
+    minimumBytesPerSecond: 128 * 1024,
+    maximumOverallTimeoutMs: 20 * 60_000,
+  },
+});
+```
+
+The total budget is `responseTimeoutMs + size / minimumBytesPerSecond`, capped
+by `maximumOverallTimeoutMs`. Invalid, zero, or effectively unbounded policies
+are rejected before the byte request starts.
+
 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/harness/src/artifact/downloadHoles.ts

@@ -39,7 +39,7 @@ function releaseFor(url: string): Release {
 async function serve(chunks: number, gapMs: number, hang = false, stallAfterFirst = false) {
   const server = http.createServer((_req, res) => {
     res.writeHead(200, { "Content-Length": String(BODY.length) });
-    if (hang) return; // headers sent, bytes never follow
+    if (hang) { res.flushHeaders(); return; } // headers sent, bytes never follow
     const size = Math.ceil(BODY.length / chunks);
     let sent = 0;
     const push = (): void => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/k-carrier",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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": {