@botiverse/k-carrier 0.1.0

package/harness/src/artifact/downloadHolesMutations.ts

@@ -0,0 +1,170 @@
+/**
+ * M1 download-hole mutation downloads/key-builders — the wrong behaviors
+ * each tooth's negative control must catch (the 8 L0 fixes, one tooth
+ * per hole). Each stub is the OLD implementation the fix replaced, so a
+ * tooth going green on the real core and red under the stub proves the
+ * assertion has teeth. Kept separate from downloadHoles.ts for the budget.
+ */
+import { createHash } from "node:crypto";
+import { ArtifactError } from "../../../core/src/artifact/errors.ts";
+import type { Release } from "../../../core/src/artifact/source.ts";
+import { type Clock, systemClock } from "../../../core/src/clock.ts";
+
+export interface StubDownloadOpts {
+  clock?: Clock;
+  timeoutMs?: number;
+  stallTimeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  onProgress?: (downloaded: number, total: number) => void;
+}
+
+/** Mutation ①: the deadline is only SIGNALLED, never raced — a fetch that
+ * ignores AbortSignal outlives every timeout. */
+export async function signalOnlyDownload(release: Release, opts: StubDownloadOpts = {}): Promise<Uint8Array> {
+  const clock = opts.clock ?? systemClock;
+  const timeoutMs = opts.timeoutMs ?? 10000;
+  const controller = new AbortController();
+  const cancel = timeoutMs > 0 ? clock.after(timeoutMs, () => controller.abort()) : undefined;
+  try {
+    const res = await (opts.fetchImpl ?? fetch)(release.url, { signal: controller.signal });
+    if (!res.ok) throw new ArtifactError("DOWNLOAD_FAILED", `GET ${release.url} -> HTTP ${res.status}`);
+    return new Uint8Array(await res.arrayBuffer());
+  } finally {
+    cancel?.();
+  }
+}
+
+/** Mutation ②: naive `${platform}-${arch}` — under Rosetta the process arch
+ * lies about the hardware, so the machine is pinned to the wrong target. */
+export function naivePlatformKey(platform: string, arch: string): string {
+  return `${platform}-${arch}`;
+}
+
+/** Mutation ②: the hardware probe is consulted on EVERY platform lookup,
+ * not just darwin+x64. */
+export function probeEverywherePlatformKey(platform: string, arch: string, probe: () => boolean): string {
+  return `${platform}-${probe() ? "arm64" : arch}`;
+}
+
+/** Mutation ④(resume): a no-body response is treated as an empty prefix —
+ * the resume path hides the cause behind the sha256 mismatch. */
+export async function emptyPrefixDownload(release: Release, opts: StubDownloadOpts = {}): Promise<Uint8Array> {
+  const res = await (opts.fetchImpl ?? fetch)(release.url);
+  if (!res.ok) throw new ArtifactError("DOWNLOAD_FAILED", `GET ${release.url} -> HTTP ${res.status}`);
+  if (!res.body) return new Uint8Array(0); // the wrong behavior: an "empty prefix", no error
+  return new Uint8Array(await res.arrayBuffer());
+}
+
+/** Mutation ③④⑥: one opaque `arrayBuffer()` await — no chunk boundaries,
+ * so no progress, no stall detection, no error classification. The total
+ * timeout is SIGNALLED (the pre-fix behavior): an abort on a wedged server
+ * comes back as a bare AbortError, never a classified DOWNLOAD_FAILED. */
+export async function arrayBufferDownload(release: Release, opts: StubDownloadOpts = {}): Promise<Uint8Array> {
+  const clock = opts.clock ?? systemClock;
+  const timeoutMs = opts.timeoutMs ?? 10000;
+  const controller = new AbortController();
+  const cancel = timeoutMs > 0 ? clock.after(timeoutMs, () => controller.abort()) : undefined;
+  try {
+    const res = await (opts.fetchImpl ?? fetch)(release.url, { signal: controller.signal });
+    if (!res.ok) throw new ArtifactError("DOWNLOAD_FAILED", `GET ${release.url} -> HTTP ${res.status}`);
+    return new Uint8Array(await res.arrayBuffer());
+  } finally {
+    cancel?.();
+  }
+}
+
+async function streamRaw(
+  release: Release,
+  opts: StubDownloadOpts,
+  armOnce: (clock: Clock, fire: () => void) => void,
+): Promise<Uint8Array> {
+  const clock = opts.clock ?? systemClock;
+  const timeoutMs = opts.timeoutMs ?? 0;
+  const controller = new AbortController();
+  let fired = false;
+  const fire = (): void => {
+    fired = true;
+    controller.abort();
+  };
+  if (timeoutMs > 0) clock.after(timeoutMs, fire);
+  armOnce(clock, fire);
+  const res = await (opts.fetchImpl ?? fetch)(release.url, { signal: controller.signal });
+  if (!res.ok) throw new ArtifactError("DOWNLOAD_FAILED", `GET ${release.url} -> HTTP ${res.status}`);
+  if (!res.body) throw new ArtifactError("DOWNLOAD_FAILED", `response has no readable body: ${release.url}`);
+  const reader = res.body.getReader();
+  const parts: Uint8Array[] = [];
+  let got = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value === undefined) continue;
+      parts.push(value);
+      got += value.byteLength;
+      opts.onProgress?.(got, release.size);
+    }
+  } catch (err) {
+    if (fired) throw new ArtifactError("DOWNLOAD_FAILED", `download timed out: ${release.url}`, { cause: err });
+    throw err;
+  }
+  const all = new Uint8Array(got);
+  let at = 0;
+  for (const part of parts) {
+    all.set(part, at);
+    at += part.byteLength;
+  }
+  return all;
+}
+
+/** Mutation ⑤a: the stall budget is armed ONCE — a total timeout that kills
+ * a slow-but-progressing download. */
+export async function totalTimeoutDownload(release: Release, opts: StubDownloadOpts = {}): Promise<Uint8Array> {
+  return streamRaw(release, opts, (clock, fire) => {
+    const budget = (opts.stallTimeoutMs ?? 0) > 0 ? opts.stallTimeoutMs! : opts.timeoutMs ?? 0;
+    if (budget > 0) clock.after(budget, fire);
+  });
+}
+
+/** Mutation ⑤b: no stall budget at all — a wedged connection holds for the
+ * total timeout and the failure never names the stall. */
+export async function noStallDownload(release: Release, opts: StubDownloadOpts = {}): Promise<Uint8Array> {
+  return streamRaw(release, opts, () => {});
+}
+
+/** Mutation ⑦: the stall error always says "awaiting response", even for a
+ * stall that happened mid-body — the reader looks at the wrong end. */
+export async function wrongPhaseDownload(release: Release, opts: StubDownloadOpts = {}): Promise<Uint8Array> {
+  const clock = opts.clock ?? systemClock;
+  const stall = opts.stallTimeoutMs ?? 0;
+  const controller = new AbortController();
+  let fired = false;
+  const fire = (): void => {
+    fired = true;
+    controller.abort();
+  };
+  if (stall > 0) clock.after(stall, fire);
+  const res = await (opts.fetchImpl ?? fetch)(release.url, { signal: controller.signal });
+  if (!res.ok) throw new ArtifactError("DOWNLOAD_FAILED", `GET ${release.url} -> HTTP ${res.status}`);
+  if (!res.body) throw new ArtifactError("DOWNLOAD_FAILED", `response has no readable body: ${release.url}`);
+  const reader = res.body.getReader();
+  try {
+    for (;;) {
+      const { done } = await reader.read();
+      if (done) break;
+    }
+  } catch (err) {
+    if (fired) {
+      throw new ArtifactError(
+        "DOWNLOAD_FAILED",
+        `download stalled: nothing received for ${stall}ms (awaiting response): ${release.url}`,
+        { cause: err },
+      );
+    }
+    throw err;
+  }
+  return new Uint8Array(0);
+}
+
+export function sha256Hex(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}

package/harness/src/artifact/m1.ts

@@ -0,0 +1,204 @@
+/**
+ * M1 exit checks — the swap-tool demo runs a REAL upgrade through core's
+ * Upgrader (createUpgrader facade): end-to-end promotion with state
+ * assertions read via upgrader.state() (never internal files), and
+ * automatic rollback of a version that fails to start.
+ */
+import assert from "node:assert/strict";
+import * as path from "node:path";
+import { promises as fs } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { type ToothContext } from "../teeth/registry.ts";
+import type { TxnState } from "../../../core/src/txn/state.ts";
+import { currentPlatformKey } from "../../../core/src/artifact/staticManifestSource.ts";
+import { FakeServer } from "../fake-server/server.ts";
+import { ArtifactFactory } from "../artifact-factory/factory.ts";
+import { runCommand } from "../artifact-factory/run.ts";
+import { CLI_TOOL_SOURCE } from "../../../examples/swap-tool/source.ts";
+
+/** The swap-tool demo's @botiverse/k-carrier wiring (createUpgrader module URL). */
+export function coreUpgraderUrl(): string {
+  return pathToFileURL(path.join(import.meta.dirname, "../../../core/src/createUpgrader.ts")).href;
+}
+
+export function swapToolEnv(ctx: ToothContext, baseUrl: string): Record<string, string> {
+  return {
+    K_RELEASE_BASE: baseUrl,
+    K_STATE_DIR: path.join(ctx.sandboxDir, "state"),
+    K_CORE_UPGRADER: coreUpgraderUrl(),
+  };
+}
+
+/** Build the swap-tool demo binary (v1.0.0, ok) into <sandbox>/app. */
+export async function buildSwapTool(ctx: ToothContext): Promise<string> {
+  const factory = new ArtifactFactory({
+    cacheDir: path.join(ctx.sandboxDir, "cache"),
+    demoSource: CLI_TOOL_SOURCE,
+  });
+  const buildServer = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "build") });
+  await buildServer.start();
+  try {
+    const rel = await factory.makeRelease({
+      version: "1.0.0",
+      behavior: "ok",
+      store: buildServer.store,
+      platform: currentPlatformKey(),
+    });
+    const appDir = path.join(ctx.sandboxDir, "app");
+    await fs.mkdir(appDir, { recursive: true });
+    const binPath = path.join(appDir, "swap-tool");
+    await fs.writeFile(binPath, rel.artifactBytes, { mode: 0o755 });
+    await fs.writeFile(
+      path.join(appDir, "k.target.ts"),
+      `export default { version: ["--version"], selfUpgrade: ["self", "upgrade"] };\n`,
+    );
+    return binPath;
+  } finally {
+    await buildServer.stop();
+  }
+}
+
+/** Read the transaction state through the PUBLIC API (upgrader.state()). */
+export async function readState(env: Record<string, string>): Promise<TxnState> {
+  const coreSrcUrl = new URL(".", env.K_CORE_UPGRADER).href;
+  const script = [
+    `const { createUpgrader } = await import(${JSON.stringify(env.K_CORE_UPGRADER)});`,
+    `const { staticManifestSource } = await import(${JSON.stringify(new URL("artifact/staticManifestSource.ts", coreSrcUrl).href)});`,
+    `const u = createUpgrader({`,
+    `  host: { quiesce: async () => {}, stop: async () => {}, start: async () => {}, healthProbe: async () => ({ version: "x", pid: 0, startId: "x" }), resume: async () => {} },`,
+    `  source: staticManifestSource({ baseUrl: ${JSON.stringify("http://127.0.0.1:1")} }),`,
+    `  policy: "auto", notificationSink: async () => {},`,
+    `  stateDir: ${JSON.stringify(env.K_STATE_DIR)},`,
+    `});`,
+    `process.stdout.write(JSON.stringify(await u.state()));`,
+  ].join("\n");
+  const r = await runCommand(process.execPath, ["--input-type=module", "-e", script], { timeoutMs: 30000 });
+  if (r.code !== 0) throw new Error(`state() read failed: ${r.stderr.trim()}`);
+  return JSON.parse(r.stdout) as TxnState;
+}
+
+/** Serve a release on a fresh fake-server (seed or target). */
+export async function serveRelease(
+  ctx: ToothContext,
+  opts: {
+    version: string;
+    behavior: "ok" | "crash-on-start";
+    name: string;
+    /** The demo source the release is stamped from. Default: swap-tool. */
+    source?: string;
+  },
+): Promise<FakeServer> {
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, `serve-${opts.name}`) });
+  await server.start();
+  const factory = new ArtifactFactory({
+    cacheDir: path.join(ctx.sandboxDir, `cache-${opts.name}`),
+    demoSource: opts.source ?? CLI_TOOL_SOURCE,
+  });
+  const release = {
+    version: opts.version,
+    behavior: opts.behavior,
+    store: server.store,
+    platform: currentPlatformKey(),
+  };
+  await factory.makeRelease(release);
+  return server;
+}
+
+/**
+ * M1 exit tooth ①: the swap-tool does a REAL upgrade through core's
+ * Upgrader — seed stable 1.0.0, serve 2.0.0, self upgrade, next run
+ * reports 2.0.0, and upgrader.state() shows the transaction committed
+ * (phase promoted, stable 2.0.0, experiment cleared).
+ */
+export async function checkSwapToolUpgradeLoop(
+  ctx: ToothContext,
+  opts: { serveBadVersion?: boolean } = {},
+): Promise<void> {
+  const binPath = await buildSwapTool(ctx);
+  const seed = await serveRelease(ctx, { version: "1.0.0", behavior: "ok", name: "seed" });
+  const target = await serveRelease(ctx, {
+    version: "2.0.0",
+    behavior: opts.serveBadVersion ? "crash-on-start" : "ok",
+    name: "target",
+  });
+  try {
+    // seed: a real first upgrade lands stable 1.0.0
+    const seedEnv = swapToolEnv(ctx, seed.url);
+    const seedRun = await runCommand(binPath, ["self", "upgrade"], { env: seedEnv, timeoutMs: 30000 });
+    assert.equal(seedRun.code, 0, `seed upgrade must exit 0 (${seedRun.stderr.trim()})`);
+    const seeded = await readState(seedEnv);
+    assert.equal(seeded.stableVersion, "1.0.0", "seed upgrade must land stable 1.0.0");
+
+    // the real upgrade to the served version
+    const targetEnv = swapToolEnv(ctx, target.url);
+    const up = await runCommand(binPath, ["self", "upgrade"], { env: targetEnv, timeoutMs: 30000 });
+    assert.equal(
+      up.code,
+      0,
+      `self upgrade must exit 0 (${up.stderr.trim()}; serveBadVersion mutation => RED)`,
+    );
+
+    const v = await runCommand(binPath, ["--version"], { timeoutMs: 30000 });
+    assert.equal(v.code, 0);
+    assert.equal(
+      v.stdout.trim(),
+      "2.0.0",
+      "next run must report the served version (serveBadVersion mutation => RED)",
+    );
+
+    // transaction committed: read via upgrader.state(), never internal files
+    const state = await readState(targetEnv);
+    assert.equal(state.stableVersion, "2.0.0", "stable slot must hold the new version");
+    assert.equal(state.experimentVersion, null, "experiment slot must be cleared after promote");
+    assert.equal(state.phase, "promoted", "journal must end at promoted");
+  } finally {
+    await seed.stop();
+    await target.stop();
+  }
+}
+
+/**
+ * M1 exit tooth ②: a bad version rolls back — serve 2.0.0
+ * crash-on-start, self upgrade must end rolled-back, the OLD version stays
+ * usable, and the experiment slot is cleared.
+ */
+export async function checkSwapToolRollback(
+  ctx: ToothContext,
+  opts: { serveGoodVersion?: boolean } = {},
+): Promise<void> {
+  const binPath = await buildSwapTool(ctx);
+  const seed = await serveRelease(ctx, { version: "1.0.0", behavior: "ok", name: "seed" });
+  const target = await serveRelease(ctx, {
+    version: "2.0.0",
+    behavior: opts.serveGoodVersion ? "ok" : "crash-on-start",
+    name: "target",
+  });
+  try {
+    const seedEnv = swapToolEnv(ctx, seed.url);
+    const seedRun = await runCommand(binPath, ["self", "upgrade"], { env: seedEnv, timeoutMs: 30000 });
+    assert.equal(seedRun.code, 0, `seed upgrade must exit 0 (${seedRun.stderr.trim()})`);
+
+    const targetEnv = swapToolEnv(ctx, target.url);
+    const up = await runCommand(binPath, ["self", "upgrade"], { env: targetEnv, timeoutMs: 30000 });
+
+    const state = await readState(targetEnv);
+    if (opts.serveGoodVersion) {
+      // mutation: a GOOD version is served — it promotes, so the rollback
+      // expectation must go RED
+      assert.equal(state.phase, "rolled-back", "a bad version must roll back (good version => RED)");
+      return;
+    }
+    assert.equal(up.code, 1, `upgrade to a bad version must exit non-zero (${up.stderr.trim()})`);
+    assert.equal(state.phase, "rolled-back", "journal must end at rolled-back");
+    assert.equal(state.stableVersion, "1.0.0", "stable must still hold the old version");
+    assert.equal(state.experimentVersion, null, "experiment slot must be cleared");
+
+    // the old version stays usable
+    const v = await runCommand(binPath, ["--version"], { timeoutMs: 30000 });
+    assert.equal(v.code, 0);
+    assert.equal(v.stdout.trim(), "1.0.0", "the old binary must still run after rollback");
+  } finally {
+    await seed.stop();
+    await target.stop();
+  }
+}

package/harness/src/artifact/m1Resume.ts

@@ -0,0 +1,141 @@
+/**
+ * m1.download-resumes-after-kill (断点续传): a process that dies
+ * mid-download must not restart from zero. The partial prefix survives, the
+ * next attempt resumes via a Range request, and the FULL assembled bytes
+ * verify. Real kill, real resume, real server.
+ */
+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 { type ToothContext } from "../teeth/registry.ts";
+import { currentPlatformKey, parseManifest } from "../../../core/src/artifact/staticManifestSource.ts";
+import { downloadVerified, partialPathFor } from "../../../core/src/artifact/download.ts";
+import { FakeServer } from "../fake-server/server.ts";
+import { MANIFEST_FILE, sha256Hex } from "../fake-server/manifest.ts";
+import { coreUpgraderUrl } from "./m1.ts";
+
+// ---------------------------------------------------------------------------
+// m1.download-resumes-after-kill (断点续传)
+// ---------------------------------------------------------------------------
+
+/**
+ * A process that dies mid-download must not restart from zero: the partial
+ * prefix survives, the next attempt resumes via a Range request, and the
+ * FULL assembled bytes verify. Real kill, real resume, real server.
+ */
+export async function checkDownloadResumesAfterKill(
+  ctx: ToothContext,
+  opts: { skipResume?: boolean } = {},
+): Promise<void> {
+  const platform = currentPlatformKey();
+  const server = new FakeServer({
+    storeDir: path.join(ctx.sandboxDir, "store"),
+    // slow enough that a kill lands mid-download deterministically
+    throttle: { bytesPerTick: 4096, tickMs: 5 },
+  });
+  await server.start();
+  try {
+    // a real-ish sized artifact (2MB) so the kill window is comfortable;
+    // published via the store directly (the factory stamps the tiny demo)
+    const big = new Uint8Array(2 * 1024 * 1024);
+    for (let i = 0; i < big.length; i++) big[i] = i % 251;
+    await server.store.publish({
+      version: "1.0.0",
+      artifacts: { "big-1.0.0.bin": big },
+      platform,
+    });
+    const manifest = parseManifest(
+      new TextDecoder().decode(await server.store.readFile(MANIFEST_FILE)),
+    );
+    const target = manifest.targets[platform];
+    assert.ok(target);
+    const url = `${server.url}/${target.file}`;
+    const release = {
+      version: "1.0.0",
+      url,
+      sha256: target.sha256,
+      size: target.size,
+    };
+
+    const resumeDir = path.join(ctx.sandboxDir, "incoming");
+    const coreUrl = coreUpgraderUrl();
+    const coreSrc = new URL(".", coreUrl).href;
+    const dlScript = [
+      `const { downloadVerified, partialPathFor } = await import(${JSON.stringify(new URL("artifact/download.ts", coreSrc).href)});`,
+      `const { promises: fs } = await import("node:fs");`,
+      `const url = ${JSON.stringify(url)};`,
+      `const dir = ${JSON.stringify(resumeDir)};`,
+      `const release = ${JSON.stringify(release)};`,
+      `const bytes = await downloadVerified(release, { resumeDir: dir, timeoutMs: 60000 });`,
+      `await fs.writeFile(process.env.K_DL_OUT, bytes);`,
+      `process.exit(0);`,
+    ].join("\n");
+
+    // First downloader: kill it mid-download (after the partial has bytes).
+    const child = spawn(process.execPath, ["--input-type=module", "-e", dlScript], {
+      env: { ...process.env, K_DL_OUT: path.join(ctx.sandboxDir, "first.bin") },
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+    let childErr = "";
+    child.stderr.on("data", (d: Buffer) => {
+      childErr += String(d);
+    });
+    const partialPath = partialPathFor(resumeDir, url);
+    await waitForFileGrow(partialPath, 1024 * 1024, 20000).catch((err) => {
+      throw new Error(`${(err as Error).message} (child stderr: ${childErr.trim()})`);
+    });
+    child.kill("SIGKILL");
+    await waitForExit(child);
+    const partialSize = (await fs.stat(partialPath)).size;
+    assert.ok(partialSize > 0 && partialSize < release.size, "the kill must land mid-download");
+
+    if (opts.skipResume) {
+      // mutation: a FRESH resumeDir — no partial, so no Range request; the
+      // resume assertion must go RED
+      const freshDir = path.join(ctx.sandboxDir, "incoming-fresh");
+      const bytes = await downloadVerified(release, { resumeDir: freshDir, timeoutMs: 60000 });
+      assert.equal(bytes.length, release.size);
+      assert.ok(
+        server.requestLog.some((r) => r.url === target.file && r.range !== null),
+        "the resume must issue a Range request (skipResume mutation => RED)",
+      );
+      return;
+    }
+
+    // Second downloader (in-process): resumes from the partial via Range.
+    const before = server.requestLog.length;
+    const bytes = await downloadVerified(release, { resumeDir, timeoutMs: 60000 });
+    assert.equal(bytes.length, release.size, "the resumed download must assemble the FULL bytes");
+    assert.equal(sha256Hex(bytes), release.sha256, "the assembled bytes must verify");
+    const rangeReq = server.requestLog.slice(before).find((r) => r.url === target.file && r.range !== null);
+    assert.ok(rangeReq, "the resume must issue a Range request");
+    assert.equal(rangeReq!.range, `bytes=${partialSize}-`, "the Range must start at the partial size");
+  } finally {
+    await server.stop();
+  }
+}
+
+async function waitForFileGrow(p: string, minBytes: number, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      const size = (await fs.stat(p)).size;
+      if (size >= minBytes) return;
+    } catch {
+      // not yet
+    }
+    if (Date.now() > deadline) throw new Error(`file ${p} never grew to ${minBytes} bytes`);
+    await new Promise((r) => {
+      setTimeout(r, 10);
+    });
+  }
+}
+
+async function waitForExit(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  await new Promise<void>((resolve) => {
+    child.once("exit", () => resolve());
+  });
+}
+