@botiverse/k-carrier 0.1.6 → 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,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,7 @@ 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;
@@ -58,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 {
@@ -111,12 +118,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 +172,9 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
       },
       ...(opts.provenance ? { provenanceJournal: opts.provenance } : {}),
       ...(opts.provenanceIdentity ? { provenanceIdentity: opts.provenanceIdentity } : {}),
+      ...(opts.artifactTransferPolicy
+        ? { artifactTransferPolicy: opts.artifactTransferPolicy }
+        : {}),
     }, request);
 
   return {

package/core/src/index.ts

@@ -18,6 +18,7 @@ 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

@@ -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/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/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.

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.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": {