@botiverse/k-carrier 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,24 @@
+k-carrier
+Copyright 2026 Botiverse
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Design influences — concepts studied, no code copied
+-----------------------------------------------------
+k-carrier's design was informed by studying two mature, unrelated updaters.
+Only architectural concepts were borrowed; no source code was copied, and the
+implementation here is original.
+
+- Two-slot upgrade transaction (stable/experiment slots with promote/rollback)
+  and the "the installer is itself a managed package" fleet model are inspired
+  by Datadog's fleet installer (DataDog/datadog-agent, pkg/fleet). Concept only.
+
+- Static-file signed distribution (offline root keys + rotating signing keys)
+  was studied from Tailscale's distsign (tailscale/tailscale, clientupdate/
+  distsign). Concept only. NOTE: k-carrier does NOT currently implement
+  signature verification — it verifies artifact integrity via sha256 + size
+  only. No distsign / signing code is present in this repository.
+
+See docs/prior-art.md for the full analysis, including what each project does
+and where k-carrier deliberately differs (fail-closed restart, post-upgrade
+convergence read-back, and rollback).

package/README.md

@@ -0,0 +1,62 @@
+# K (k-carrier)
+
+**Self-upgrade framework for programs that must prove they came back up.**
+
+CLI self-update libraries stop at replacing bytes; fleet updaters assume a machine someone else administers. K covers what neither does: **an upgrade that is a transaction and can prove it happened** — two slots with rollback, crash-safe at every step, handoff of a live process with its workloads intact, and convergence proven from the live process and named OS surfaces (a version string is never accepted as proof). Consent and notification are built in, because on a machine someone owns personally, changing behaviour silently is not acceptable — but nothing here is limited to personal machines.
+
+**Two process models, defined by how many live incarnations K manages** — `swap` (**0**: K replaces bytes and touches no process; a one-shot CLI and an hours-long agent session are the same case) and `service` (**1**: K stops the old, starts the new, and proves it). OS lifecycle convergence and fleet drive are capabilities you opt into on top, not a third model. Proof is executable: a runnable example per case, and a claim without a green example does not exist.
+
+## Delivery and guarantee are different axes
+
+Most updaters are compared on one vague axis called "complexity". There are
+two, and they are independent:
+
+|                       | delivery — how hard is it to put the bytes in place | guarantee — what is promised afterwards |
+|-----------------------|---------------------------------------|-----------------------------|
+| `rustup self update`  | low: replace one file, exit           | low: none                   |
+| `electron-updater`    | **high**                              | low: none                   |
+| **K**                 | low: one binary                       | **high**: transaction, readback, rollback |
+
+Measured, not asserted: of electron-updater 6.8.9's ~4,200 lines, ~1,170 are
+per-platform installation (Squirrel.Mac, NSIS, deb/rpm/pacman, AppImage),
+~1,200 orchestration and policy, ~960 feed providers, and ~860 differential
+download. Downloading is not the hard part — **installing is, because
+installing is not yours to do**: you hand off to a system component with its
+own rules (Squirrel.Mac accepts only a URL, so the updater serves the file it
+already downloaded back to itself over a local HTTP server; NSIS may need
+elevation; dpkg needs root). Grep that codebase for rollback and you find none,
+and nothing checks health after the install.
+
+K deliberately does not compete on the delivery axis — platform packaging
+belongs to platform tools. It exists on the other one, and specifically for the
+consequence those tools all share and none of them handle: **because something
+else installs your bytes, something else replaces and restarts your process.**
+The process driving the upgrade dies on the *success* path, so the successor
+must be able to tell "the handover worked" from "we crashed" — by evidence,
+never by a flag saying the restart was planned.
+
+## Start here
+
+- **[`docs/integration.md`](docs/integration.md)** — from-zero guide: the problem in plain words, concept primer, tiered adoption with code.
+- [`docs/design-v1.md`](docs/design-v1.md) — full design: six layers, architecture, decision record.
+- [`docs/harness-design.md`](docs/harness-design.md) — the test framework, designed first: harness as executable spec (teeth registry, real-process crash injection, adversarial self-verification).
+- [`docs/test-plan.md`](docs/test-plan.md) — executable test plan (M0–M6, must-red per cell).
+- [`docs/prior-art.md`](docs/prior-art.md) — the source-level survey this design stands on (Tailscale / Datadog), and the license-defense record behind `NOTICE`.
+
+## Repo layout
+
+```
+core/       the framework — zero host-specific concepts (shells live in their
+            product's repo and consume core as a dependency)
+harness/    generic acceptance bed: fake-host daemon + profile-tiered teeth
+examples/   one runnable demo per profile (swap-tool / service-daemon / hosted-service)
+docs/       guides + design + test plan + prior art
+```
+
+**Platform support today:** Linux and macOS are implemented and gate CI.
+Windows platform operations (replacing a *running* .exe, process liveness) are
+deliberately unimplemented — they throw a typed `PLATFORM_UNSUPPORTED` rather
+than approximating POSIX behaviour and corrupting an install. The Windows CI
+job runs and reports, but does not gate, until those land.
+
+Status: incubating. TypeScript first. License: **Apache-2.0**.

package/core/src/artifact/README.md

@@ -0,0 +1 @@
+# artifact — see docs/design-v1.md for this layer's spec. Interfaces land here next.

package/core/src/artifact/collectStream.ts

@@ -0,0 +1,49 @@
+/**
+ * Read a response body into memory while keeping chunk boundaries visible.
+ *
+ * Split out of download.ts for the line budget. The boundaries are the point:
+ * `res.arrayBuffer()` is one opaque await, so neither a stall timer nor a
+ * progress sink can observe anything through it.
+ */
+import { ArtifactError } from "./errors.ts";
+
+export async function collectStream(
+  url: string,
+  body: ReadableStream<Uint8Array> | null,
+  total: number | undefined,
+  onProgress: ((downloaded: number, total: number) => void) | undefined,
+  onChunk: () => void,
+): Promise<Uint8Array> {
+  // A response with no readable body is a failure to READ, not an empty
+  // download. Returning zero bytes here would hand the caller a valid-looking
+  // empty artifact whose only symptom is a sha256 mismatch against the digest
+  // of the empty string -- an error that describes the consequence and hides
+  // the cause. Same rule as everywhere else: the failure path must not produce
+  // the empty success value.
+  if (!body) {
+    throw new ArtifactError("DOWNLOAD_FAILED", `response has no readable body: ${url}`);
+  }
+  const parts: Uint8Array[] = [];
+  let got = 0;
+  onProgress?.(0, total ?? 0);
+  const reader = body.getReader();
+  {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value === undefined) continue;
+      parts.push(value);
+      got += value.byteLength;
+      onChunk();
+      onProgress?.(got, total ?? 0);
+    }
+  }
+  const all = new Uint8Array(got);
+  let at = 0;
+  for (const part of parts) {
+    all.set(part, at);
+    at += part.byteLength;
+  }
+  return all;
+}
+

package/core/src/artifact/download.ts

@@ -0,0 +1,300 @@
+/**
+ * L0 download + INTEGRITY only, with RESUME
+ * (断点续传 — computer's 150MB SEA case: a process that dies mid-download
+ * must not restart from zero).
+ *
+ * Streams the body to a partial file in `resumeDir` (keyed by the release
+ * URL); a later attempt resumes from it via `Range`. The FULL assembled bytes
+ * are verified against sha256 + size before being returned, so a corrupted
+ * partial is refused rather than trusted for having been "already downloaded".
+ * Interruptions leave the partial in place — that is the point; only a
+ * completed-but-invalid assembly deletes it. Time goes through the injected
+ * Clock, and the deadline is RACED rather than merely signalled (an injected
+ * fetch that ignores AbortSignal must not be able to outlive it).
+ *
+ * ⚠️ K verifies INTEGRITY, never AUTHENTICITY. sha256 + size prove the bytes
+ * are the ones the manifest described; they cannot prove WHO produced them,
+ * because the digest travels with the artifact from the same place. Signing
+ * (a trust root of our own) was implemented and then REMOVED on 2026-08-06 —
+ * see docs/design-v1.md §L0.5 for the decision and for why OS code signing
+ * (Authenticode / codesign) is a different guarantee, not a substitute.
+ *
+ * Consequence worth stating where it is used: if the release bucket itself
+ * serves wrong bytes — leaked CI credentials, a misconfigured bucket, a
+ * poisoned publish pipeline — this check passes and every client installs
+ * them.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { type Clock, systemClock } from "../clock.ts";
+import { ArtifactError } from "./errors.ts";
+import type { Release } from "./source.ts";
+import { collectStream } from "./collectStream.ts";
+import { partialPathFor } from "./partialPath.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;
+}
+
+/** Fetch and verify one release's bytes, resuming from a partial if present. */
+export async function downloadVerified(
+  release: Release,
+  opts: DownloadOptions = {},
+): Promise<Uint8Array> {
+  const url = release.url;
+  const clock = opts.clock ?? systemClock;
+  const timeoutMs = opts.timeoutMs ?? 10000;
+
+  const partialPath = opts.resumeDir ? partialPathFor(opts.resumeDir, url) : null;
+
+  let partialSize = 0;
+  if (partialPath) {
+    try {
+      partialSize = (await fs.stat(partialPath)).size;
+    } catch {
+      // no partial yet
+    }
+    if (partialSize >= release.size) partialSize = 0; // complete/over-long is not a resume point
+  }
+
+  const bytes = await fetchAndAppend(
+    url, partialPath, partialSize, clock, timeoutMs, opts.onProgress, release.size,
+    opts.stallTimeoutMs ?? 0, opts.fetchImpl ?? fetch,
+  );
+
+  const sha = sha256Hex(bytes);
+  if (sha !== release.sha256) {
+    // A completed-but-invalid assembly is useless and must not be resumed:
+    // delete the partial so the next attempt starts clean.
+    if (partialPath) await fs.rm(partialPath, { force: true }).catch(() => {});
+    throw new ArtifactError(
+      "SHA256_MISMATCH",
+      `sha256 of ${url} does not match the release (got ${sha.slice(0, 12)}…, expected ${release.sha256.slice(0, 12)}…)`,
+    );
+  }
+  if (bytes.length !== release.size) {
+    if (partialPath) await fs.rm(partialPath, { force: true }).catch(() => {});
+    throw new ArtifactError(
+      "SIZE_MISMATCH",
+      `size of ${url} (${bytes.length}) does not match manifest (${release.size})`,
+    );
+  }
+  return bytes;
+}
+
+/**
+ * Fetch and stream into the partial file (appending when resuming). On
+ * interruption the partial is left in place; the file handle is always
+ * closed. 206 = the server honored the Range; 200 = it ignored it (a fresh
+ * download, so the partial is discarded).
+ */
+async function fetchAndAppend(
+  url: string,
+  partialPath: string | null,
+  partialSize: number,
+  clock: Clock,
+  timeoutMs: number,
+  onProgress?: (downloaded: number, total: number) => void,
+  total?: number,
+  stallTimeoutMs = 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;
+  // 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}`;
+  // 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
+  // test clock does not.
+  const cancel =
+    timeoutMs > 0
+      ? clock.after(timeoutMs, () => {
+          controller.abort();
+          aborted?.();
+        })
+      : undefined;
+  const armStall = (): void => {
+    if (stallTimeoutMs <= 0) return;
+    stallTimer?.();
+    stallTimer = clock.after(stallTimeoutMs, () => {
+      stalled = true;
+      controller.abort();
+      aborted?.();
+    });
+  };
+  try {
+    const headers: Record<string, string> = {};
+    if (partialSize > 0) headers["Range"] = `bytes=${partialSize}-`;
+    let res: Response;
+    armStall(); // the response headers themselves must not hang forever
+    try {
+      // Race the abort, do not merely signal it. `AbortSignal` only works if the
+      // fetch implementation honours it, and `fetchImpl` is an adopter-supplied
+      // seam -- a custom client that ignores the signal would leave every
+      // timeout here silently inert, with no way to tell that from a fetch that
+      // is simply still working. The deadline has to be enforced by the side
+      // that promises it.
+      res = await Promise.race([
+        doFetch(url, { signal: controller.signal, headers }),
+        new Promise<never>((_, reject) => {
+          aborted = () => {
+            reject(new ArtifactError("DOWNLOAD_FAILED", abortReason(url)));
+          };
+        }),
+      ]);
+    } catch (err) {
+      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}`,
+        { cause: err },
+      );
+    }
+    if (!res.ok) {
+      throw new ArtifactError("DOWNLOAD_FAILED", `GET ${url} -> HTTP ${res.status}`);
+    }
+    // Headers arriving IS activity: the silence budget covers the gap until the
+    // next thing happens, and the response is that thing. Without this rearm a
+    // 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();
+
+    if (partialPath === null) {
+      // Stream even with nowhere to resume to. `res.arrayBuffer()` is one
+      // opaque await: no chunk boundaries, so neither the stall timer nor the
+      // progress sink can observe anything -- a download without a resumeDir
+      // 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);
+      } 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
+        // (stall or deadline) came back as an anonymous transport failure --
+        // the caller could not tell "we gave up on purpose" from "the network
+        // broke".
+        if (err instanceof ArtifactError) throw err;
+        throw new ArtifactError("DOWNLOAD_FAILED", abortReason(url), { cause: err });
+      }
+    }
+
+    // Resume semantics: only a 206 proves the server honored the Range.
+    if (partialSize > 0 && res.status !== 206) {
+      await fs.rm(partialPath, { force: true });
+      partialSize = 0;
+    }
+    await fs.mkdir(path.dirname(partialPath), { recursive: true });
+    const fh = await fs.open(partialPath, partialSize > 0 ? "a" : "w");
+    try {
+      // Same rule as the in-memory branch: no readable body is a failure to
+      // READ, not an empty download — never hide the cause behind a sha256 mismatch.
+      if (!res.body) {
+        throw new ArtifactError("DOWNLOAD_FAILED", `response has no readable body: ${url}`);
+      }
+      // Count from the resumed prefix, never from zero: a bar that restarts
+      // reads as "it lost my download" to the person watching it.
+      let onDisk = partialSize;
+      onProgress?.(onDisk, total ?? 0);
+      armStall();
+      await streamToFile(res.body, fh, (chunk) => {
+        onDisk += chunk;
+        armStall();
+        onProgress?.(onDisk, total ?? 0);
+      });
+      await fh.sync();
+    } catch (err) {
+      // A typed error we raised (no readable body) stays typed, like the
+      // in-memory branch; only genuine interruptions become "interrupted".
+      if (err instanceof ArtifactError) throw err;
+      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}`,
+        { cause: err },
+      );
+    } finally {
+      await fh.close();
+    }
+    return new Uint8Array(await fs.readFile(partialPath));
+  } finally {
+    cancel?.();
+    stallTimer?.();
+  }
+}
+
+async function streamToFile(
+  body: ReadableStream<Uint8Array>,
+  fh: Awaited<ReturnType<typeof fs.open>>,
+  onBytes?: (chunk: number) => void,
+): Promise<void> {
+  const reader = body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value !== undefined) {
+      await fh.write(value);
+      onBytes?.(value.byteLength);
+    }
+  }
+}
+
+function sha256Hex(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}

package/core/src/artifact/errors.ts

@@ -0,0 +1,24 @@
+/**
+ * L0 artifact layer errors — every failure is typed (fail-closed: an
+ * a refused release, a tampered artifact, a half-written swap all carry a
+ * machine-readable code, never a silent pass).
+ */
+export type ArtifactErrorCode =
+  | "UNREGISTERED_SURFACE"
+  | "MANIFEST_INVALID"
+  | "PINNED_VERSION_MISMATCH"
+  | "UNSUPPORTED_PLATFORM"
+  | "DOWNLOAD_FAILED"
+  | "SHA256_MISMATCH"
+  | "SIZE_MISMATCH"
+  | "SWAP_FAILED";
+
+export class ArtifactError extends Error {
+  readonly code: ArtifactErrorCode;
+
+  constructor(code: ArtifactErrorCode, message: string, options?: { cause?: unknown }) {
+    super(`[${code}] ${message}`, options);
+    this.name = "ArtifactError";
+    this.code = code;
+  }
+}