@botiverse/k-carrier 0.1.0

package/harness/src/artifact/checks.ts

@@ -0,0 +1,232 @@
+/**
+ * L0 artifact acceptance checks — run bodies of the M1 artifact teeth
+ * (registered in teeth/artifact.ts). Each throws on violation.
+ *
+ * The checks consume core's public L0 API (dogfood: the harness is the
+ * first consumer) against the fake-server + artifact-factory + real
+ * processes:
+ *  - a tampered artifact is REFUSED (sha256) — real tamper -> real reject;
+ *  - a kill mid-swap leaves the OLD bytes intact (real process, real
+ *    SIGKILL — the atomicity contract lives in process reality);
+ *  - the release source fails closed instead of guessing.
+ */
+import assert from "node:assert/strict";
+import * as path from "node:path";
+import { promises as fs } from "node:fs";
+import { spawn, type ChildProcess } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { type ToothContext } from "../teeth/registry.ts";
+import { staticManifestSource } from "../../../core/src/artifact/staticManifestSource.ts";
+import type { ReleaseContext, ReleaseSource } from "../../../core/src/artifact/source.ts";
+import { parseManifest, currentPlatformKey } from "../../../core/src/artifact/staticManifestSource.ts";
+import { downloadVerified } from "../../../core/src/artifact/download.ts";
+import { atomicWriteFile } from "../../../core/src/artifact/swap.ts";
+import { FakeServer } from "../fake-server/server.ts";
+import { ArtifactFactory } from "../artifact-factory/factory.ts";
+import { MANIFEST_FILE } from "../fake-server/manifest.ts";
+import { processAlive } from "../fake-host/daemon.ts";
+
+// ---------------------------------------------------------------------------
+// tampered artifact => refuse install
+// ---------------------------------------------------------------------------
+
+export async function checkTamperedArtifactRefused(
+  ctx: ToothContext,
+  opts: { skipTamper?: boolean } = {},
+): Promise<void> {
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "store") });
+  await server.start();
+  const factory = new ArtifactFactory({ cacheDir: path.join(ctx.sandboxDir, "cache") });
+  try {
+    const platform = currentPlatformKey();
+    const rel = await factory.makeRelease({
+      version: "1.0.0",
+      behavior: "ok",
+      store: server.store,
+      platform,
+    });
+    const manifest = parseManifest(
+      new TextDecoder().decode(await server.store.readFile(MANIFEST_FILE)),
+    );
+    const target = manifest.targets[platform];
+    assert.ok(target, "release manifest must carry the current platform target");
+    if (!opts.skipTamper) {
+      await server.corruptByte(rel.artifactFile, 0);
+    }
+    // core's L0 consumer must refuse the (tampered) artifact
+    await assert.rejects(
+      downloadVerified({ version: "1.0.0", url: `${server.url.replace(/\/$/u, "")}/${target.file}`, sha256: target.sha256, size: target.size }, { timeoutMs: 5000 }),
+      /SHA256_MISMATCH/,
+      "a tampered artifact must be refused (skipTamper mutation => RED)",
+    );
+  } finally {
+    await server.stop();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// kill mid-swap => old bytes intact
+// ---------------------------------------------------------------------------
+
+const MID_SWAP_PAYLOAD_BYTES = 64 * 1024 * 1024; // 64MiB: long enough to catch mid-write
+
+export async function checkKillMidSwapPreservesOld(
+  ctx: ToothContext,
+  opts: { skipKill?: boolean } = {},
+): Promise<void> {
+  const targetPath = path.join(ctx.sandboxDir, "app.bin");
+  const oldBytes = new TextEncoder().encode("old-version-bytes");
+  await atomicWriteFile(targetPath, oldBytes);
+
+  const swapModuleUrl = pathToFileURL(
+    path.join(import.meta.dirname, "../../../core/src/artifact/swap.ts"),
+  ).href;
+  const script = [
+    `import { atomicWriteFile } from ${JSON.stringify(swapModuleUrl)};`,
+    `const fs = await import("node:fs");`,
+    `const data = new Uint8Array(${MID_SWAP_PAYLOAD_BYTES});`,
+    `data.fill(0x42);`,
+    `await atomicWriteFile(process.env.K_SWAP_TARGET, data);`,
+  ].join("\n");
+  const child = spawn(process.execPath, ["--input-type=module", "-e", script], {
+    env: { ...process.env, K_SWAP_TARGET: targetPath },
+    stdio: "ignore", // no pipes: a failed assertion must not degrade into a hang
+  });
+
+  try {
+    if (opts.skipKill) {
+      // mutation: the kill never lands — the swap completes, so the
+      // "old bytes intact" assertion must go RED
+      await waitForExit(child);
+      assert.ok(
+        await equalsFile(targetPath, oldBytes),
+        "kill mid-swap must leave the old bytes intact (no kill => RED)",
+      );
+      return;
+    }
+
+    // Wait for the temp file (created BEFORE any data is written).
+    await waitForFile(`${targetPath}.tmp`);
+    if (process.platform === "win32") {
+      // The deterministic mid-swap freeze needs SIGSTOP / a suspend
+      // primitive; Windows has no public one without native FFI, so the
+      // kill-exactly-before-rename assertions are POSIX-only. The swap
+      // completes and recovery below is what Windows verifies.
+      await waitForExit(child);
+    } else {
+      // Freeze the child mid-swap: the rename cannot have happened yet.
+      child.kill("SIGSTOP");
+      assert.ok(
+        await equalsFile(targetPath, oldBytes),
+        "the kill must land mid-swap (before the rename)",
+      );
+
+      // Real SIGKILL: the old bytes must be intact and complete.
+      child.kill("SIGKILL");
+      assert.ok(
+        await equalsFile(targetPath, oldBytes),
+        "kill mid-swap must leave the old bytes intact",
+      );
+    }
+
+    // Recovery: a subsequent swap succeeds (the leftover .tmp is truncated).
+    const recovered = new TextEncoder().encode("recovered");
+    await atomicWriteFile(targetPath, recovered);
+    assert.deepEqual(new Uint8Array(await fs.readFile(targetPath)), recovered);
+  } finally {
+    if (child.pid && processAlive(child.pid)) child.kill("SIGKILL");
+    await fs.rm(`${targetPath}.tmp`, { force: true }).catch(() => {});
+  }
+}
+
+// ---------------------------------------------------------------------------
+// source boundary => fail-closed
+// ---------------------------------------------------------------------------
+
+
+/**
+ * The source boundary must FAIL CLOSED rather than guess: an unsupported
+ * platform, and a named version this source cannot serve, are both refusals.
+ * (Version ORDER policy lives in the source, not in K — so this tooth pins
+ * refusal behaviour, not a versioning scheme.)
+ */
+export async function checkSourceFailsClosed(
+  _ctx: ToothContext,
+  makeSource: (served: string) => ReleaseSource = (served) =>
+    staticManifestSource({
+      baseUrl: "https://cdn.example/app",
+      fetchImpl: (async (url: string | URL | Request) => {
+        if (String(url).endsWith(".k-sig.json")) {
+          return new Response("not found", { status: 404 }); // no signature bundle
+        }
+        return new Response(
+          JSON.stringify({
+            version: served,
+            targets: { "linux-x64": { file: `app-${served}.bin`, sha256: "a".repeat(64), size: 1 } },
+          }),
+          { status: 200 },
+        );
+      }) as unknown as typeof fetch,
+    }),
+): Promise<void> {
+  const ctx: ReleaseContext = { currentVersion: "1.0.0", platformKey: "linux-x64" };
+  const source = makeSource("1.2.0");
+
+  // unknown platform => refusal, never a guessed target
+  await assert.rejects(
+    () => source.checkForUpdate({ ...ctx, platformKey: "sparc-solaris" }),
+    /UNSUPPORTED_PLATFORM/u,
+  );
+
+  // a named version this source does not serve => refusal
+  await assert.rejects(() => source.fetchRelease("9.9.9", ctx), /PINNED_VERSION_MISMATCH/u);
+
+  // and the happy path still resolves completely
+  const release = await source.checkForUpdate(ctx);
+  assert.ok(release, "a newer served version must produce a release");
+  assert.equal(release.version, "1.2.0");
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+async function waitForFile(p: string): Promise<void> {
+  const deadline = Date.now() + 10000;
+  for (;;) {
+    try {
+      await fs.access(p);
+      return;
+    } catch {
+      // not yet
+    }
+    if (Date.now() > deadline) throw new Error(`file ${p} never appeared`);
+    await new Promise((r) => {
+      setTimeout(r, 2);
+    });
+  }
+}
+
+async function equalsFile(p: string, expected: Uint8Array): Promise<boolean> {
+  try {
+    const got = new Uint8Array(await fs.readFile(p));
+    if (got.length !== expected.length) return false;
+    for (let i = 0; i < got.length; i++) {
+      if (got[i] !== expected[i]) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForExit(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  await new Promise<void>((resolve) => {
+    child.once("exit", () => resolve());
+  });
+}
+
+// ---------------------------------------------------------------------------
+// M1 exit: swap-tool end-to-end upgrade + rollback through core's Upgrader
+// ---------------------------------------------------------------------------

package/harness/src/artifact/downloadHoles.ts

@@ -0,0 +1,300 @@
+/**
+ * M1 download-hole acceptance checks — the 8 L0 fixes (486f299..3626b76),
+ * one tooth per hole. He wrote the unit tests; these are the RED-able
+ * acceptance surfaces: the same assertions as teeth, so the next regression
+ * is a red in the gate, not a silent unit-test removal.
+ *
+ * Holes: ① deadline raced not signalled; ② Rosetta arch lie; ③ progress
+ * absent without resumeDir; ④ empty body named as a read failure; ⑤ stall
+ * bounds silence (reset on activity); ⑥ in-memory errors classified;
+ * ⑦ stall phase named honestly; ⑧ stall timeout exists (⑤'s wedged case).
+ */
+import assert from "node:assert/strict";
+import * as http from "node:http";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { type ToothContext } from "../teeth/registry.ts";
+import { downloadVerified } from "../../../core/src/artifact/download.ts";
+import { platformKeyFor } from "../../../core/src/platform/posix.ts";
+import type { Release } from "../../../core/src/artifact/source.ts";
+import {
+  signalOnlyDownload,
+  naivePlatformKey,
+  probeEverywherePlatformKey,
+  arrayBufferDownload,
+  emptyPrefixDownload,
+  totalTimeoutDownload,
+  noStallDownload,
+  wrongPhaseDownload,
+} from "./downloadHolesMutations.ts";
+
+const BODY = new Uint8Array(4096).fill(7);
+
+function releaseFor(url: string): Release {
+  return { version: "1.0.0", url, sha256: createHash("sha256").update(BODY).digest("hex"), size: BODY.length };
+}
+
+/** A server that writes `chunks` pieces, waiting `gapMs` between each;
+ * `stallAfterFirst` sends headers + one chunk, then silence. */
+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
+    const size = Math.ceil(BODY.length / chunks);
+    let sent = 0;
+    const push = (): void => {
+      if (sent >= BODY.length) {
+        res.end();
+        return;
+      }
+      res.write(Buffer.from(BODY.subarray(sent, sent + size)));
+      sent += size;
+      if (stallAfterFirst && sent >= size) return; // headers + one chunk, then silence
+      setTimeout(push, gapMs);
+    };
+    push();
+  });
+  await new Promise<void>((r) => {
+    server.listen(0, "127.0.0.1", r);
+  });
+  const port = (server.address() as { port: number }).port;
+  return { url: `http://127.0.0.1:${port}/app.bin`, close: () => server.close() };
+}
+
+/** A 204 response: ok but with NO readable body. */
+async function serveNoBody() {
+  const server = http.createServer((_req, res) => {
+    res.writeHead(204);
+    res.end();
+  });
+  await new Promise<void>((r) => {
+    server.listen(0, "127.0.0.1", r);
+  });
+  const port = (server.address() as { port: number }).port;
+  return { url: `http://127.0.0.1:${port}/app.bin`, close: () => server.close() };
+}
+
+const neverSettles = (() => new Promise<Response>(() => {})) as unknown as typeof fetch;
+
+// ---------------------------------------------------------------------------
+// ① m1.download-timeout-enforced
+// ---------------------------------------------------------------------------
+
+export async function checkDownloadTimeoutEnforced(
+  ctx: ToothContext,
+  opts: { signalOnly?: boolean } = {},
+): Promise<void> {
+  const url = "http://127.0.0.1:1/app.bin"; // nothing listens; the fetch impl decides
+  if (opts.signalOnly) {
+    // mutation: the deadline is only signalled — a fetch that ignores the
+    // signal hangs forever. The bounded race lets the check fail instead of
+    // hanging the suite: the bound fires with a DIFFERENT message, so the
+    // /timed out after 150ms/ expectation does not match.
+    const bound = new Promise<never>((_, reject) => {
+      setTimeout(() => reject(new Error("bound")), 500);
+    });
+    await assert.rejects(
+      Promise.race([signalOnlyDownload(releaseFor(url), { timeoutMs: 150, fetchImpl: neverSettles }), bound]),
+      /timed out after 150ms/,
+      "the deadline must be enforced even when the fetch ignores the signal (signalOnly => RED)",
+    );
+    return;
+  }
+  await assert.rejects(
+    downloadVerified(releaseFor(url), { fetchImpl: neverSettles, timeoutMs: 150, stallTimeoutMs: 0 }),
+    /timed out after 150ms/,
+    "an uncooperative fetch must not be able to outlive the deadline",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ② m1.platform-key-native-arch
+// ---------------------------------------------------------------------------
+
+const yes = (): boolean => true;
+const no = (): boolean => false;
+
+export async function checkPlatformKeyNativeArch(
+  ctx: ToothContext,
+  opts: { naiveKey?: boolean; probeEverywhere?: boolean } = {},
+): Promise<void> {
+  const key = opts.naiveKey
+    ? naivePlatformKey
+    : opts.probeEverywhere
+      ? probeEverywherePlatformKey
+      : platformKeyFor;
+
+  assert.equal(key("linux", "x64", no), "linux-x64", "ordinary machines report platform-arch unchanged");
+  assert.equal(key("darwin", "arm64", yes), "darwin-arm64", "native arm64 reports arm64");
+  assert.equal(
+    key("darwin", "x64", yes),
+    "darwin-arm64",
+    "x64 Node on arm64 hardware must select the arm64 target — Rosetta lies about the machine (naiveKey => RED)",
+  );
+  assert.equal(
+    key("darwin", "x64", no),
+    "darwin-x64",
+    "a genuine Intel Mac still gets x64 — the hardware probe separates the two",
+  );
+  const calls: string[] = [];
+  const probe = (): boolean => {
+    calls.push("called");
+    return true;
+  };
+  key("linux", "x64", probe);
+  key("darwin", "arm64", probe);
+  key("win32", "x64", probe);
+  assert.deepEqual(
+    calls,
+    [],
+    "the hardware probe is consulted ONLY on darwin+x64 — it must not shell out on every platform lookup (probeEverywhere => RED)",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ③ m1.download-progress-without-resumedir
+// ---------------------------------------------------------------------------
+
+export async function checkDownloadProgressWithoutResumeDir(
+  ctx: ToothContext,
+  opts: { noProgress?: boolean } = {},
+): Promise<void> {
+  const s = await serve(4, 10);
+  try {
+    const seen: number[] = [];
+    const download = opts.noProgress ? arrayBufferDownload : downloadVerified;
+    await download(releaseFor(s.url), {
+      timeoutMs: 0,
+      onProgress: (downloaded) => seen.push(downloaded),
+    });
+    assert.ok(
+      seen.length > 1,
+      `expected progress readings with no resumeDir, got ${seen.length} — the bar must move (noProgress => RED)`,
+    );
+    assert.equal(seen.at(-1), BODY.length, "the last reading must be the full size");
+    for (let i = 1; i < seen.length; i += 1) {
+      assert.ok(seen[i]! >= seen[i - 1]!, "progress must be monotonic");
+    }
+  } finally {
+    s.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ④ m1.download-empty-body-named
+// ---------------------------------------------------------------------------
+
+export async function checkDownloadEmptyBodyNamed(
+  ctx: ToothContext,
+  opts: { returnEmptyBytes?: boolean; treatEmptyAsPrefix?: boolean } = {},
+): Promise<void> {
+  const s = await serveNoBody();
+  try {
+    // arm 1: the in-memory path (no resumeDir)
+    const download = opts.returnEmptyBytes ? arrayBufferDownload : downloadVerified;
+    await assert.rejects(
+      download(releaseFor(s.url), { timeoutMs: 0 }),
+      /no readable body/,
+      "a response with no readable body is a failure to READ, not an empty download — the error must name the cause, never a sha256 mismatch (returnEmptyBytes => RED)",
+    );
+    // arm 2: the RESUME path must name it too — a no-body response is never
+    // an empty prefix to continue from. This arm was added after review
+    // proved the first arm does not bite on the resume path.
+    const resumeDownload = opts.treatEmptyAsPrefix ? emptyPrefixDownload : downloadVerified;
+    await assert.rejects(
+      resumeDownload(releaseFor(s.url), { timeoutMs: 0, resumeDir: path.join(ctx.sandboxDir, "resume") }),
+      /no readable body/,
+      "the resume path must name a no-body response as a read failure, never treat it as an empty prefix (treatEmptyAsPrefix => RED)",
+    );
+  } finally {
+    s.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ⑤ m1.download-stall-bounds-silence (+⑧ the stall timeout exists)
+// ---------------------------------------------------------------------------
+
+export async function checkDownloadStallBoundsSilence(
+  ctx: ToothContext,
+  opts: { totalTimeout?: boolean; noStall?: boolean } = {},
+): Promise<void> {
+  // (a) a download that keeps making progress survives a stall budget
+  // shorter than its total time (8 chunks x 40ms ≈ 320ms > 150ms budget).
+  const slow = await serve(8, 40);
+  try {
+    const download = opts.totalTimeout ? totalTimeoutDownload : downloadVerified;
+    let completed = false;
+    try {
+      const bytes = await download(releaseFor(slow.url), { stallTimeoutMs: 150, timeoutMs: 0 });
+      completed = bytes.length === BODY.length;
+    } catch {
+      completed = false;
+    }
+    assert.ok(
+      completed,
+      "a slow-but-progressing download must survive a stall budget shorter than its total time — silence is bounded, not total duration (totalTimeout => RED)",
+    );
+  } finally {
+    slow.close();
+  }
+
+  // (b) a wedged download (headers, then silence) dies on the stall budget
+  // and names the stall. The finite total timeout is a backstop so a missing
+  // stall timer produces the total-timeout wording instead of a hang.
+  const wedged = await serve(1, 0, true);
+  try {
+    const download = opts.noStall ? noStallDownload : downloadVerified;
+    await assert.rejects(
+      download(releaseFor(wedged.url), { stallTimeoutMs: 200, timeoutMs: 3_000 }),
+      /stalled: nothing received for 200ms/,
+      "a wedged download must die on the STALL budget, not the total budget (noStall => RED)",
+    );
+  } finally {
+    wedged.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ⑥ m1.download-errors-classified
+// ---------------------------------------------------------------------------
+
+export async function checkDownloadErrorsClassified(
+  ctx: ToothContext,
+  opts: { unclassified?: boolean } = {},
+): Promise<void> {
+  const wedged = await serve(1, 0, true);
+  try {
+    // in-memory path (no resumeDir): a stall we caused must come back as a
+    // typed DOWNLOAD_FAILED naming the reason, never an anonymous stream error.
+    const download = opts.unclassified ? arrayBufferDownload : downloadVerified;
+    await assert.rejects(
+      download(releaseFor(wedged.url), { stallTimeoutMs: 200, timeoutMs: 3_000 }),
+      /stalled|timed out/,
+      "a stall the downloader itself caused must be reported as the stall, not as an anonymous transport failure (unclassified => RED)",
+    );
+  } finally {
+    wedged.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ⑦ m1.download-stall-phase-honest
+// ---------------------------------------------------------------------------
+
+export async function checkDownloadStallPhaseHonest(
+  ctx: ToothContext,
+  opts: { wrongPhase?: boolean } = {},
+): Promise<void> {
+  const mid = await serve(2, 0, false, true); // headers + one chunk, then silence
+  try {
+    const download = opts.wrongPhase ? wrongPhaseDownload : downloadVerified;
+    await assert.rejects(
+      download(releaseFor(mid.url), { stallTimeoutMs: 200, timeoutMs: 3_000 }),
+      /\(mid-body\)/,
+      "a stall that happened mid-body must say mid-body, not 'awaiting response' (wrongPhase => RED)",
+    );
+  } finally {
+    mid.close();
+  }
+}