@botiverse/k-carrier 0.1.6 → 0.1.8

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,7 +7,7 @@
  * rollback is rare, not routine.
  */
 import type { Upgrader, UpgraderConfig, UpgradeOutcome, ProvenanceIdentity } from "./upgrader.ts";
-import { phaseAtRest, type TxnState } from "./txn/state.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 } from "./txn/fileEffects.ts";
@@ -26,6 +26,8 @@ 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";
+import { quarantineState } from "./quarantine.ts";
 
 export interface CreateUpgraderOptions extends UpgraderConfig {
   clock?: Clock;
@@ -58,6 +60,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 {
@@ -111,12 +119,35 @@ 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,
-    };
+    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 });
+      }
+      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);
@@ -142,6 +173,9 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
       },
       ...(opts.provenance ? { provenanceJournal: opts.provenance } : {}),
       ...(opts.provenanceIdentity ? { provenanceIdentity: opts.provenanceIdentity } : {}),
+      ...(opts.artifactTransferPolicy
+        ? { artifactTransferPolicy: opts.artifactTransferPolicy }
+        : {}),
     }, request);
 
   return {
@@ -234,5 +268,7 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
         await lock.release();
       }
     },
+
+    quarantineState: (options) => quarantineState(opts.stateDir, options),
   };
 }

package/core/src/index.ts

@@ -14,10 +14,12 @@ export * from "./bootstrap.ts";
 // NotificationEvent.
 export * from "./upgrader.ts";
 export * from "./operation.ts";
+export * from "./quarantine.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

@@ -170,6 +170,9 @@ export async function acknowledgeOperation(
   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,

package/core/src/quarantine.ts

@@ -0,0 +1,167 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { loadOperation } from "./operation.ts";
+import { acquireUpgradeLock, type UpgradeLock } from "./txn/lock.ts";
+import { UpgradeLockError } from "./txn/lock.ts";
+import { platformOpsFor } from "./platform/index.ts";
+
+export type QuarantineResult =
+  | { status: "quarantined"; sourcePath: string; quarantinePath: string; operationId: string; timestampMs: number }
+  | { status: "already-quarantined"; sourcePath: string; quarantinePath: string; operationId: string; timestampMs: number }
+  | { status: "not-found"; sourcePath: string; quarantinePath: string; operationId: string; timestampMs: number };
+
+export type QuarantineErrorCode =
+  | "QUARANTINE_INVALID_DESTINATION"
+  | "QUARANTINE_DESTINATION_CONFLICT"
+  | "QUARANTINE_ACTIVE_OPERATION"
+  | "QUARANTINE_ACTIVE_LOCK"
+  | "QUARANTINE_STATE_UNREADABLE"
+  | "QUARANTINE_WRITE_FAILED";
+
+export class QuarantineError extends Error {
+  readonly code: QuarantineErrorCode;
+
+  constructor(code: QuarantineErrorCode, message: string, options?: { cause?: unknown }) {
+    super(`[${code}] ${message}`, options);
+    this.name = "QuarantineError";
+    this.code = code;
+  }
+}
+
+export interface QuarantineOptions {
+  /** Absolute destination. It must be outside stateDir and must not exist. */
+  destination: string;
+  /** Timestamp supplied by the host clock so the receipt is deterministic. */
+  timestampMs: number;
+  /** Host proof run while K's single-writer lock is held. */
+  assertActiveHandoff?: () => Promise<void>;
+}
+
+function assertDestination(stateDir: string, destination: string): void {
+  if (!path.isAbsolute(destination)) {
+    throw new QuarantineError("QUARANTINE_INVALID_DESTINATION", "destination must be absolute");
+  }
+  const source = path.resolve(stateDir);
+  const target = path.resolve(destination);
+  if (source === target || target.startsWith(`${source}${path.sep}`)) {
+    throw new QuarantineError("QUARANTINE_INVALID_DESTINATION", "destination must be outside stateDir");
+  }
+}
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+interface QuarantineReceipt {
+  formatVersion: 1;
+  kind: "k-fresh-install-quarantine";
+  sourcePath: string;
+  quarantinePath: string;
+  operationId: string;
+  timestampMs: number;
+}
+
+async function readReceipt(destination: string): Promise<QuarantineReceipt | null> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(path.join(destination, "fresh-install-quarantine.json"), "utf8")) as Partial<QuarantineReceipt>;
+    if (parsed.formatVersion !== 1 || parsed.kind !== "k-fresh-install-quarantine" || typeof parsed.sourcePath !== "string" || typeof parsed.quarantinePath !== "string" || typeof parsed.operationId !== "string" || typeof parsed.timestampMs !== "number") return null;
+    return parsed as QuarantineReceipt;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Move the complete K state directory to an audit-only quarantine.
+ *
+ * The state lock is acquired before the terminal check and the directory
+ * rename is one filesystem operation. The lock release is ownership-aware, so
+ * a new state directory created immediately after the rename cannot have its
+ * lock removed by the old holder. Active operations are never killed or
+ * silently detached; callers must first complete the host handoff contract.
+ */
+export async function quarantineState(stateDir: string, options: QuarantineOptions): Promise<QuarantineResult> {
+  assertDestination(stateDir, options.destination);
+  const timestampMs = options.timestampMs;
+  const sourcePath = path.resolve(stateDir);
+  const quarantinePath = path.resolve(options.destination);
+  const existingDestination = await exists(quarantinePath);
+  const existingOperation = await loadOperation(sourcePath);
+  const operationId = existingOperation.kind === "observed" ? existingOperation.operation.id : "genesis";
+
+  if (existingDestination) {
+    if (await exists(sourcePath)) {
+      throw new QuarantineError("QUARANTINE_DESTINATION_CONFLICT", `destination already exists: ${quarantinePath}`);
+    }
+    const receipt = await readReceipt(quarantinePath);
+    if (receipt === null) throw new QuarantineError("QUARANTINE_DESTINATION_CONFLICT", `destination has no valid quarantine receipt: ${quarantinePath}`);
+    return { status: "already-quarantined", sourcePath: receipt.sourcePath, quarantinePath: receipt.quarantinePath, operationId: receipt.operationId, timestampMs: receipt.timestampMs };
+  }
+  if (!(await exists(sourcePath))) {
+    return { status: "not-found", sourcePath, quarantinePath, operationId, timestampMs };
+  }
+
+  let lock: UpgradeLock | null = null;
+  try {
+    lock = await acquireUpgradeLock(sourcePath, timestampMs);
+    const operation = await loadOperation(sourcePath);
+    if (operation.kind === "unreadable") {
+      throw new QuarantineError("QUARANTINE_STATE_UNREADABLE", operation.reason);
+    }
+    if (operation.kind === "observed" && operation.operation.outcome === null) {
+      if (options.assertActiveHandoff === undefined) {
+        throw new QuarantineError(
+          "QUARANTINE_ACTIVE_OPERATION",
+          `operation ${operation.operation.id} is active; complete host handoff before quarantine`,
+        );
+      }
+      try {
+        await options.assertActiveHandoff();
+      } catch (error) {
+        throw new QuarantineError("QUARANTINE_ACTIVE_OPERATION", `active operation ${operation.operation.id} handoff was not proven`, { cause: error });
+      }
+    }
+    if (await exists(quarantinePath)) {
+      throw new QuarantineError("QUARANTINE_DESTINATION_CONFLICT", `destination already exists: ${quarantinePath}`);
+    }
+    await fs.mkdir(path.dirname(quarantinePath), { recursive: true });
+    const receipt: QuarantineReceipt = {
+      formatVersion: 1,
+      kind: "k-fresh-install-quarantine",
+      sourcePath,
+      quarantinePath,
+      operationId: operation.kind === "observed" ? operation.operation.id : "genesis",
+      timestampMs,
+    };
+    const receiptPath = path.join(sourcePath, "fresh-install-quarantine.json");
+    const fh = await fs.open(receiptPath, "w");
+    try {
+      await fh.writeFile(JSON.stringify(receipt));
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    await platformOpsFor().renamePath(sourcePath, quarantinePath);
+    return {
+      status: "quarantined",
+      sourcePath,
+      quarantinePath,
+      operationId: receipt.operationId,
+      timestampMs,
+    };
+  } catch (error) {
+    if (error instanceof QuarantineError) throw error;
+    if (error instanceof UpgradeLockError) {
+      throw new QuarantineError("QUARANTINE_ACTIVE_LOCK", error.message, { cause: error });
+    }
+    throw new QuarantineError("QUARANTINE_WRITE_FAILED", `could not quarantine ${sourcePath}`, { cause: error });
+  } finally {
+    await lock?.release();
+  }
+}

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

@@ -1,6 +1,11 @@
 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";
@@ -37,6 +42,8 @@ export interface UpgradeDriveDeps {
   persistConvergenceReport: (report: ConvergenceReport) => Promise<void>;
   provenanceJournal?: ProvenanceJournal;
   provenanceIdentity?: ProvenanceIdentity;
+  artifactTransferPolicy?: ArtifactTransferPolicy;
+  downloadArtifact?: (release: Release, opts: DownloadOptions) => Promise<Uint8Array>;
 }
 
 export interface UpgradeDriveRequest {
@@ -115,9 +122,13 @@ export async function driveUpgrade(
 
     await deps.operation.transition({ phase: "downloading" });
     progress({ stage: "downloading", version: release.version });
-    const bytes = await downloadVerified(release, {
+    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 }),
     });

package/core/src/upgrader.ts

@@ -4,6 +4,7 @@ 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";
+import type { QuarantineOptions, QuarantineResult } from "./quarantine.ts";
 
 /**
  * Who drove a reconcile, recorded in the provenance journal (M6, L5).
@@ -106,6 +107,9 @@ export interface Upgrader {
 
   /** 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>;
 }
 
 export type UpgradeOutcome =

package/docs/integration.md

@@ -237,6 +237,29 @@ 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.
@@ -263,6 +286,16 @@ if (receipt.kind === "observed" && receipt.operation.outcome !== null) {
   await deliver(receipt.operation);
   await upgrader.acknowledgeOperation(receipt.operation.id);
 }
+
+// Fresh-install hosts may quarantine a complete, quiesced K state atomically.
+// The destination must be an absolute path outside stateDir and the host must
+// supply its clock timestamp. Terminal receipts are moved without deletion;
+// active receipts require an in-lock host handoff proof.
+const backup = await upgrader.quarantineState({
+  destination: "/var/lib/myapp/k-quarantine/op-123-1700000000000",
+  timestampMs: 1700000000000,
+});
+// backup.quarantinePath is the durable, non-secret audit location.
 ```
 
 The host may project this receipt into UI or transport, but must not maintain

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.6",
+  "version": "0.1.8",
   "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": {