@mochi.js/core 0.3.0 → 0.6.0

package/README.md

@@ -10,28 +10,32 @@ bun add @mochi.js/core
 import { mochi } from "@mochi.js/core";
 
 const session = await mochi.launch({
-  profile: "mac-m2-chrome-stable",
+  profile: "linux-chrome-stable",
   seed: "user-12345",
 });
 
 const page = await session.newPage();
 await page.goto("https://example.com");
-await page.humanClick("#submit");
+await page.humanClick("a");
 await session.close();
 ```
 
 ## Status
 
-**v0.0.1 — claim release.** The surface above is the contract; the implementation lands incrementally per the project roadmap. Calling `mochi.launch()` at v0.0.1 throws `NotImplementedError` with a pointer to the repo.
+`v0.4.x` (v0.2 wave-4 surfaces). `mochi.launch()` is fully wired: pipe-mode CDP transport, relational `(profile, seed)` Matrix, JIT-friendly inject delivered via `Fetch.fulfillRequest` body splice (with `Page.addScriptToEvaluateOnNewDocument({ runImmediately: true, worldName: "" })` as the `about:blank` / `data:` fallback), behavioral synth, and JA4-coherent `session.fetch` via Rust+wreq.
 
-The full surface lands in phases 0.1 → 1.0. Watch the repo for v0.1 (CDP transport) and v1.0 (the production release).
+The full [v0.1.4 → v0.2] surface lands as additive minor bumps. See [`CHANGELOG.md`](https://github.com/0xchasercat/mochi/blob/main/CHANGELOG.md).
 
 ## What this package gives you
 
-- `mochi.launch(opts)` — spawn a Chromium-for-Testing instance with a relationally-locked fingerprint matrix derived from `(profile, seed)`.
+- `mochi.launch(opts)` — spawn a Chromium-for-Testing instance with a relationally-locked fingerprint matrix derived from `(profile, seed)`. Options include `proxy`, `headless`, `binary`, `timeout`, `geoConsistency` (IP/TZ/locale exit reconciliation), and `challenges` (Turnstile auto-click).
 - `Session` and `Page` — the runtime objects you drive.
-- `page.humanClick / humanType / humanScroll` — biomechanically-shaped input synthesis.
-- `session.fetch` — out-of-band requests with profile-matching JA3/JA4 via the Rust+wreq backend.
+- `page.humanClick / humanType / humanScroll` — biomechanically-shaped input synthesis (Bezier + Fitts + Gaussian jitter).
+- `session.fetch` — out-of-band requests with profile-matching JA3/JA4/H2 via the Rust+wreq backend.
+- `page.screenshot(opts?)` — PNG / JPEG / WebP via CDP `Page.captureScreenshot`. Options: `format`, `quality`, `fullPage`, `clip`, `omitBackground`, `encoding`. Element-bounded capture (`{ element: handle }`) is deferred — see <https://mochijs.com/docs/reference/limits>.
+- `session.cookies.{save,load}(path, { pattern? })` — JSON cookie jar with version header + regex domain filter. Round-trips losslessly via `Storage.getCookies` / `Storage.setCookies`.
+- `page.localStorage.{get,set}` and `page.sessionStorage.{get,set}` — direct `DOMStorage` CDP access, frame-scoped (defaults to current main-frame origin; pass `{ origin }` for cross-origin).
+- `page.grantAllPermissions(opts?)` — wraps `Browser.grantPermissions` with the full `ALL_BROWSER_PERMISSIONS` descriptor list.
 
 All of this is the single import. No mixing Patchright + a fingerprint injector + a Turnstile clicker. mochi solves it once.
 
@@ -39,8 +43,8 @@ All of this is the single import. No mixing Patchright + a fingerprint injector
 
 - **Bun-only.** No Node fallback. Engines: `bun >= 1.1`.
 - **Stock Chromium.** No patched fork. Works against [Chromium-for-Testing](https://googlechromelabs.github.io/chrome-for-testing/), pinned and downloadable via `mochi browsers install`.
-- **Relational locking.** Every fingerprint surface (canvas, WebGL, audio, fonts, timing) derives from a single `(profile, seed)` pair. No Frankenstein fingerprints.
-- **Zero-jitter spoofing.** TurboFan-friendly proxies installed via `Page.addScriptToEvaluateOnNewDocument(runImmediately:true)` before any page script. No async round-trips when a WAF probes.
+- **Relational locking.** Every fingerprint surface (canvas, WebGL, audio, fonts, timing) derives from a single `(profile, seed)` pair. No Frankenstein fingerprints. Audio + canvas digests are byte-exact via precomputed per-(profile, sample-rate) blobs (R-047 / R-048).
+- **Zero-jitter spoofing.** TurboFan-friendly proxies installed before any page script. Init-script delivery via `Fetch.fulfillRequest` body splice closes the source-attribution leak that bare `addScriptToEvaluateOnNewDocument` would otherwise carry.
 
 ## License
 
@@ -50,4 +54,9 @@ MIT.
 
 - [Repo](https://github.com/0xchasercat/mochi)
 - [PLAN.md](https://github.com/0xchasercat/mochi/blob/main/PLAN.md) — the full design contract
-- [Limits](https://github.com/0xchasercat/mochi/blob/main/docs/limits.md) — what the JS-only ceiling honestly does and doesn't cover
+
+## Documentation
+
+- Package reference: <https://mochijs.com/docs/api/core>
+- Concept deep-dive: <https://mochijs.com/docs/concepts/stealth-philosophy>
+- Cookbook: <https://mochijs.com/docs/guides/pick-a-scenario>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mochi.js/core",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Bun-native browser automation framework — relational fingerprint locking, zero-jitter injection, behavioral playback. The primary entry point.",
   "license": "MIT",
   "type": "module",
@@ -49,10 +49,10 @@
     "build": "echo 'no build step yet — Bun consumes src/ directly'"
   },
   "dependencies": {
-    "@mochi.js/behavioral": "^0.1.3",
+    "@mochi.js/behavioral": "^0.1.4",
     "@mochi.js/challenges": "^0.2.1",
-    "@mochi.js/consistency": "^0.1.2",
-    "@mochi.js/inject": "^0.2.1",
+    "@mochi.js/consistency": "^0.1.3",
+    "@mochi.js/inject": "^0.3.0",
     "@mochi.js/net": "^0.1.1"
   },
   "publishConfig": {

package/src/__tests__/cookies-jar.test.ts

@@ -0,0 +1,361 @@
+/**
+ * Unit tests for the {@link Session.cookies} jar surface (task 0257):
+ *
+ *   - `cookies.get()`         → `Storage.getCookies` round-trip with optional
+ *                               url-host filter.
+ *   - `cookies.set(cookies)`  → `Storage.setCookies` round-trip.
+ *   - `cookies.save(path)`    → JSON file with the {@link CookieJarFile}
+ *                               header (`version`, `savedAt`, `mochiVersion`,
+ *                               `pattern`, `count`) and the filtered cookies
+ *                               array.
+ *   - `cookies.load(path)`    → reads the file, validates the version, and
+ *                               replays via `Storage.setCookies`.
+ *
+ * Round-trip property: `save → load → get` returns a set equal to what
+ * `get` originally returned (modulo the regex filter). We verify the wire
+ * shape too — the saved JSON is the contract test's reference shape.
+ *
+ * No real Chromium process is spawned; we drive `Session` against a fake
+ * `ChromiumProcess` whose pipe reader/writer let us observe every CDP
+ * request sent and inject canned responses.
+ *
+ * @see tasks/0257-dx-cluster-cookies-storage-permissions.md
+ * @see docs/audits/nodriver.md (LOW finding 2 — pickle → JSON port)
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deriveMatrix, type ProfileV1 } from "@mochi.js/consistency";
+import type { PipeReader, PipeWriter } from "../cdp/transport";
+import type { Cookie } from "../page";
+import type { ChromiumProcess } from "../proc";
+import { COOKIE_JAR_FORMAT_VERSION, type CookieJarFile, Session } from "../session";
+
+interface FakeBrowser {
+  process: ChromiumProcess;
+  written: Array<{ id?: number; method?: string; params?: unknown; sessionId?: string }>;
+  push(obj: unknown): void;
+  autoRespond(methodPredicate: (m: string) => boolean, result: unknown): void;
+}
+
+function makeFakeBrowser(): FakeBrowser {
+  const written: FakeBrowser["written"] = [];
+  let pumpController: ReadableStreamDefaultController<Uint8Array> | null = null;
+  const stream = new ReadableStream<Uint8Array>({
+    start(c) {
+      pumpController = c;
+    },
+  });
+  const enc = new TextEncoder();
+  const dec = new TextDecoder();
+  const autoResponders: Array<{ pred: (m: string) => boolean; result: unknown }> = [];
+
+  const reader: PipeReader = { getReader: () => stream.getReader() };
+
+  const push = (obj: unknown): void => {
+    const bytes = enc.encode(JSON.stringify(obj));
+    const out = new Uint8Array(bytes.length + 1);
+    out.set(bytes, 0);
+    out[bytes.length] = 0;
+    pumpController?.enqueue(out);
+  };
+
+  const writer: PipeWriter = {
+    write: (chunk) => {
+      const last = chunk[chunk.length - 1] === 0 ? chunk.length - 1 : chunk.length;
+      const json = dec.decode(chunk.subarray(0, last));
+      try {
+        const parsed = JSON.parse(json) as {
+          id?: number;
+          method?: string;
+          params?: unknown;
+          sessionId?: string;
+        };
+        written.push(parsed);
+        if (typeof parsed.method === "string" && typeof parsed.id === "number") {
+          const r = autoResponders.find((a) => a.pred(parsed.method ?? ""));
+          if (r) {
+            queueMicrotask(() => push({ id: parsed.id, result: r.result }));
+          }
+        }
+      } catch {
+        // ignore
+      }
+    },
+    flush: () => undefined,
+    end: () => undefined,
+  };
+
+  let resolveExit: ((code: number) => void) | undefined;
+  const exited = new Promise<number>((res) => {
+    resolveExit = res;
+  });
+  let killed = false;
+  const proc: ChromiumProcess = {
+    userDataDir: "/tmp/fake-mochi-cookies-test",
+    pid: 0,
+    exited,
+    reader,
+    writer,
+    close: async () => {
+      if (killed) return;
+      killed = true;
+      try {
+        pumpController?.close();
+      } catch {
+        // ignore
+      }
+      resolveExit?.(0);
+    },
+  };
+
+  return {
+    process: proc,
+    written,
+    push,
+    autoRespond(pred, result) {
+      autoResponders.push({ pred, result });
+    },
+  };
+}
+
+const TEST_PROFILE: ProfileV1 = {
+  id: "cookies-jar-fixture",
+  version: "0.0.0-test",
+  engine: "chromium",
+  browser: { name: "chrome", channel: "stable", minVersion: "131", maxVersion: "133" },
+  os: { name: "macos", version: "14", arch: "arm64" },
+  device: {
+    vendor: "Apple",
+    model: "Mac14,2",
+    cpuFamily: "apple-silicon-m2",
+    cores: 8,
+    memoryGB: 16,
+  },
+  display: { width: 1728, height: 1117, dpr: 2, colorDepth: 30, pixelDepth: 30 },
+  gpu: {
+    vendor: "Apple Inc.",
+    renderer: "Apple M2",
+    webglUnmaskedVendor: "Apple Inc.",
+    webglUnmaskedRenderer: "Apple M2",
+    webglMaxTextureSize: 16384,
+    webglMaxColorAttachments: 8,
+    webglExtensions: [],
+  },
+  audio: { contextSampleRate: 48000, audioWorkletLatency: 0.005, destinationMaxChannelCount: 2 },
+  fonts: { family: "macos-baseline", list: ["Helvetica"] },
+  timezone: "America/Los_Angeles",
+  locale: "en-US",
+  languages: ["en-US", "en"],
+  behavior: { hand: "right", tremor: 0.18, wpm: 60, scrollStyle: "smooth" },
+  wreqPreset: "chrome_131_macos",
+  userAgent: "Mozilla/5.0 (cookies-test)",
+  uaCh: {},
+  entropyBudget: { fixed: [], perSeed: [] },
+};
+
+const SAMPLE_COOKIES: Cookie[] = [
+  {
+    name: "session_id",
+    value: "abc",
+    domain: ".example.com",
+    path: "/",
+    expires: 1_800_000_000,
+    size: 12,
+    httpOnly: true,
+    secure: true,
+    session: false,
+    sameSite: "Lax",
+  },
+  {
+    name: "consent",
+    value: "1",
+    domain: "tracker.io",
+    path: "/",
+    expires: 1_900_000_000,
+    size: 4,
+    httpOnly: false,
+    secure: true,
+    session: false,
+  },
+  {
+    name: "ab_test",
+    value: "B",
+    domain: ".example.com",
+    path: "/",
+    expires: -1,
+    size: 5,
+    httpOnly: false,
+    secure: false,
+    session: true,
+  },
+];
+
+describe("Session.cookies (task 0257)", () => {
+  let fake: FakeBrowser;
+  let session: Session;
+  let tmpFile: string;
+
+  beforeEach(() => {
+    fake = makeFakeBrowser();
+    fake.autoRespond((m) => m === "Target.setAutoAttach", {});
+    const matrix = deriveMatrix(TEST_PROFILE, "cookies-test");
+    session = new Session({
+      proc: fake.process,
+      matrix,
+      seed: "cookies-test",
+      bypassInject: true,
+    });
+    tmpFile = join(
+      tmpdir(),
+      `mochi-cookies-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+    );
+  });
+
+  afterEach(async () => {
+    try {
+      await session.close();
+    } catch {
+      // ignore
+    }
+    try {
+      rmSync(tmpFile, { force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  it("get() returns Storage.getCookies result verbatim when no filter", async () => {
+    fake.autoRespond((m) => m === "Storage.getCookies", { cookies: SAMPLE_COOKIES });
+    const got = await session.cookies.get();
+    expect(got).toEqual(SAMPLE_COOKIES);
+    const call = fake.written.find((w) => w.method === "Storage.getCookies");
+    expect(call).toBeDefined();
+  });
+
+  it("get({ url }) filters by hostname", async () => {
+    fake.autoRespond((m) => m === "Storage.getCookies", { cookies: SAMPLE_COOKIES });
+    const got = await session.cookies.get({ url: "https://example.com/path" });
+    // .example.com matches "example.com" (endsWith on either direction).
+    const names = got.map((c) => c.name).sort();
+    expect(names).toEqual(["ab_test", "session_id"]);
+  });
+
+  it("set(cookies) sends Storage.setCookies with the full array", async () => {
+    fake.autoRespond((m) => m === "Storage.setCookies", {});
+    await session.cookies.set(SAMPLE_COOKIES);
+    const call = fake.written.find((w) => w.method === "Storage.setCookies");
+    expect(call).toBeDefined();
+    expect(call?.params).toEqual({ cookies: SAMPLE_COOKIES });
+  });
+
+  it("save() writes JSON with the version header + filtered cookies", async () => {
+    fake.autoRespond((m) => m === "Storage.getCookies", { cookies: SAMPLE_COOKIES });
+    await session.cookies.save(tmpFile);
+    const text = await Bun.file(tmpFile).text();
+    const parsed = JSON.parse(text) as CookieJarFile;
+    expect(parsed.version).toBe(COOKIE_JAR_FORMAT_VERSION);
+    expect(typeof parsed.savedAt).toBe("string");
+    expect(parsed.savedAt.endsWith("Z")).toBe(true);
+    expect(typeof parsed.mochiVersion).toBe("string");
+    expect(parsed.pattern).toBe(".*");
+    expect(parsed.count).toBe(SAMPLE_COOKIES.length);
+    expect(parsed.cookies).toEqual(SAMPLE_COOKIES);
+  });
+
+  it("save({ pattern }) only writes matching domains", async () => {
+    fake.autoRespond((m) => m === "Storage.getCookies", { cookies: SAMPLE_COOKIES });
+    await session.cookies.save(tmpFile, { pattern: /example\.com$/ });
+    const parsed = JSON.parse(await Bun.file(tmpFile).text()) as CookieJarFile;
+    expect(parsed.pattern).toBe("example\\.com$");
+    expect(parsed.count).toBe(2);
+    expect(parsed.cookies.every((c) => c.domain.endsWith("example.com"))).toBe(true);
+  });
+
+  it("load() round-trips: file contents replay via Storage.setCookies", async () => {
+    // Stage: save once, then forget the in-memory state and load it back.
+    fake.autoRespond((m) => m === "Storage.getCookies", { cookies: SAMPLE_COOKIES });
+    fake.autoRespond((m) => m === "Storage.setCookies", {});
+    await session.cookies.save(tmpFile);
+
+    await session.cookies.load(tmpFile);
+    const setCall = fake.written.find((w) => w.method === "Storage.setCookies");
+    expect(setCall).toBeDefined();
+    expect(setCall?.params).toEqual({ cookies: SAMPLE_COOKIES });
+  });
+
+  it("load({ pattern }) skips cookies that don't match", async () => {
+    fake.autoRespond((m) => m === "Storage.getCookies", { cookies: SAMPLE_COOKIES });
+    fake.autoRespond((m) => m === "Storage.setCookies", {});
+    await session.cookies.save(tmpFile);
+
+    await session.cookies.load(tmpFile, { pattern: /tracker/ });
+    const setCall = fake.written.find((w) => w.method === "Storage.setCookies");
+    expect(setCall).toBeDefined();
+    const params = setCall?.params as { cookies: Cookie[] };
+    expect(params.cookies.length).toBe(1);
+    expect(params.cookies[0]?.domain).toBe("tracker.io");
+  });
+
+  it("load() throws when the file is missing", async () => {
+    let threw = false;
+    try {
+      await session.cookies.load(`${tmpFile}-missing`);
+    } catch (err) {
+      threw = true;
+      expect(String(err)).toContain("file not found");
+    }
+    expect(threw).toBe(true);
+  });
+
+  it("load() throws on version mismatch", async () => {
+    const bad = {
+      version: 999,
+      savedAt: "2026-05-09T00:00:00Z",
+      mochiVersion: "x",
+      pattern: ".*",
+      count: 0,
+      cookies: [],
+    };
+    await Bun.write(tmpFile, JSON.stringify(bad));
+    let threw = false;
+    try {
+      await session.cookies.load(tmpFile);
+    } catch (err) {
+      threw = true;
+      expect(String(err)).toContain("version");
+    }
+    expect(threw).toBe(true);
+  });
+
+  it("load() throws on malformed JSON", async () => {
+    await Bun.write(tmpFile, "not json {");
+    let threw = false;
+    try {
+      await session.cookies.load(tmpFile);
+    } catch (err) {
+      threw = true;
+      expect(String(err)).toContain("not valid JSON");
+    }
+    expect(threw).toBe(true);
+  });
+
+  it("save() then load() is idempotent on the saved set", async () => {
+    fake.autoRespond((m) => m === "Storage.getCookies", { cookies: SAMPLE_COOKIES });
+    fake.autoRespond((m) => m === "Storage.setCookies", {});
+    await session.cookies.save(tmpFile);
+
+    // Load once.
+    await session.cookies.load(tmpFile);
+    const calls1 = fake.written.filter((w) => w.method === "Storage.setCookies");
+    expect(calls1.length).toBe(1);
+
+    // Load again — same wire shape.
+    await session.cookies.load(tmpFile);
+    const calls2 = fake.written.filter((w) => w.method === "Storage.setCookies");
+    expect(calls2.length).toBe(2);
+    expect(calls2[0]?.params).toEqual(calls2[1]?.params);
+  });
+});

package/src/__tests__/default-profile.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Unit tests for the host-OS profile auto-pick (task 0272).
+ *
+ * Three layers under test:
+ *
+ *   1. {@link resolveDefaultProfileForHost} — the pure mapping table.
+ *      `(platform, arch)` in, `ProfileId | null` out. No I/O, no globals.
+ *   2. {@link defaultProfileForHost} — the live wrapper that reads
+ *      `process.platform` / `process.arch`. Verified by stubbing the
+ *      `process` properties and asserting the same table holds.
+ *   3. The launcher's failure-mode diagnostic (`unsupportedHostMessage`):
+ *      lists the six explicit profile IDs verbatim and points at the
+ *      choose-your-profile guide URL. Format is pinned by task 0272 — the
+ *      docs + LLM-context blocks reference these strings.
+ *
+ * The "explicit `profile:` always wins" half of the success criteria is
+ * exercised against the launcher's `resolveProfileSource` resolver via the
+ * exported `defaultProfileForHost` introspection helper. We do NOT spawn
+ * Chromium here — the goal is to lock the decisions against regressions
+ * without taking the cost of a real launch. Mirrors the
+ * `proc-linux-server.test.ts` pattern (task 0258).
+ *
+ * @see packages/core/src/default-profile.ts
+ * @see tasks/0271-the-linux-os-thesis.md (strategic thesis + production evidence)
+ * @see tasks/0272-host-os-profile-auto-default.md (engineering brief)
+ */
+
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  defaultProfileForHost,
+  EXPLICIT_PROFILE_IDS,
+  resolveDefaultProfileForHost,
+  unsupportedHostMessage,
+} from "../default-profile";
+
+describe("resolveDefaultProfileForHost — pure mapping table (task 0272)", () => {
+  it("linux/x64 → linux-chrome-stable", () => {
+    expect(resolveDefaultProfileForHost("linux", "x64")).toBe("linux-chrome-stable");
+  });
+
+  it("darwin/arm64 → mac-m4-chrome-stable", () => {
+    expect(resolveDefaultProfileForHost("darwin", "arm64")).toBe("mac-m4-chrome-stable");
+  });
+
+  it("darwin/x64 → mac-chrome-stable", () => {
+    expect(resolveDefaultProfileForHost("darwin", "x64")).toBe("mac-chrome-stable");
+  });
+
+  it("win32/x64 → windows-chrome-stable", () => {
+    expect(resolveDefaultProfileForHost("win32", "x64")).toBe("windows-chrome-stable");
+  });
+
+  it("linux/arm64 → null (no Linux arm64 capture today)", () => {
+    expect(resolveDefaultProfileForHost("linux", "arm64")).toBeNull();
+  });
+
+  it("freebsd/x64 → null (unsupported platform)", () => {
+    // `freebsd` is a valid `NodeJS.Platform`. Confirms the resolver fails
+    // closed rather than silently routing to a Linux profile.
+    expect(resolveDefaultProfileForHost("freebsd", "x64")).toBeNull();
+  });
+
+  it("win32/arm64 → null (no Windows arm64 capture today)", () => {
+    expect(resolveDefaultProfileForHost("win32", "arm64")).toBeNull();
+  });
+
+  it("openbsd/x64 → null (unsupported platform — fail closed)", () => {
+    expect(resolveDefaultProfileForHost("openbsd", "x64")).toBeNull();
+  });
+
+  it("returns one of the six real-device profile IDs on every supported host", () => {
+    // Cross-check: every value the resolver can return MUST be in the
+    // EXPLICIT_PROFILE_IDS list — that's the list the unsupported-host
+    // diagnostic surfaces, and a resolver that picks an id outside that
+    // list would create a documentation drift on the failure path.
+    const supported: Array<[NodeJS.Platform, string]> = [
+      ["linux", "x64"],
+      ["darwin", "arm64"],
+      ["darwin", "x64"],
+      ["win32", "x64"],
+    ];
+    for (const [platform, arch] of supported) {
+      const id = resolveDefaultProfileForHost(platform, arch);
+      expect(id).not.toBeNull();
+      expect(EXPLICIT_PROFILE_IDS).toContain(id as (typeof EXPLICIT_PROFILE_IDS)[number]);
+    }
+  });
+});
+
+describe("defaultProfileForHost — live wrapper (task 0272)", () => {
+  // Stub `process.platform` / `process.arch` so the live wrapper exercises
+  // the same table as the pure resolver. `Object.defineProperty` is the
+  // standard Bun-test pattern (matches `proc-linux-server.test.ts`).
+  const ORIG_PLATFORM = process.platform;
+  const ORIG_ARCH = process.arch;
+
+  function stub(platform: NodeJS.Platform, arch: string) {
+    Object.defineProperty(process, "platform", { value: platform, configurable: true });
+    Object.defineProperty(process, "arch", { value: arch, configurable: true });
+  }
+
+  afterEach(() => {
+    Object.defineProperty(process, "platform", { value: ORIG_PLATFORM, configurable: true });
+    Object.defineProperty(process, "arch", { value: ORIG_ARCH, configurable: true });
+  });
+
+  it("reads (process.platform, process.arch) and returns the mapped id", () => {
+    stub("linux", "x64");
+    expect(defaultProfileForHost()).toBe("linux-chrome-stable");
+
+    stub("darwin", "arm64");
+    expect(defaultProfileForHost()).toBe("mac-m4-chrome-stable");
+
+    stub("darwin", "x64");
+    expect(defaultProfileForHost()).toBe("mac-chrome-stable");
+
+    stub("win32", "x64");
+    expect(defaultProfileForHost()).toBe("windows-chrome-stable");
+  });
+
+  it("returns null on unsupported hosts (linux arm64, freebsd)", () => {
+    stub("linux", "arm64");
+    expect(defaultProfileForHost()).toBeNull();
+
+    stub("freebsd", "x64");
+    expect(defaultProfileForHost()).toBeNull();
+  });
+});
+
+describe("unsupportedHostMessage — failure-mode diagnostic (task 0272)", () => {
+  it("names the host platform + arch verbatim", () => {
+    const msg = unsupportedHostMessage("freebsd", "x64");
+    expect(msg).toContain("platform=freebsd");
+    expect(msg).toContain("arch=x64");
+  });
+
+  it("lists every explicit profile id (six total)", () => {
+    const msg = unsupportedHostMessage("linux", "arm64");
+    for (const id of EXPLICIT_PROFILE_IDS) {
+      expect(msg).toContain(id);
+    }
+    expect(EXPLICIT_PROFILE_IDS.length).toBe(6);
+  });
+
+  it("points at the choose-your-profile guide URL", () => {
+    const msg = unsupportedHostMessage("openbsd", "x64");
+    expect(msg).toContain("https://mochijs.com/docs/guides/choose-your-profile");
+  });
+
+  it("uses the [mochi] launch: prefix so users grep the right log", () => {
+    const msg = unsupportedHostMessage("linux", "arm64");
+    expect(msg.startsWith("[mochi] launch:")).toBe(true);
+  });
+});
+
+describe("introspection contract — defaultProfileForHost is pure (task 0272)", () => {
+  it("returns the same value on repeated calls (no caching, no mutation)", () => {
+    // The launcher consults this helper at every launch; pinning purity
+    // here means a downstream `console.log(mochi.defaultProfileForHost())`
+    // is always safe and does not influence subsequent launches.
+    const a = defaultProfileForHost();
+    const b = defaultProfileForHost();
+    expect(a).toBe(b);
+  });
+
+  it("EXPLICIT_PROFILE_IDS lists exactly the six real-device profiles", () => {
+    // The unsupported-host diagnostic surfaces this list verbatim; the
+    // README LLM-context block + the task 0272 brief reference these IDs
+    // by name. Pin the membership here so a docs/code drift surfaces.
+    expect(new Set(EXPLICIT_PROFILE_IDS)).toEqual(
+      new Set([
+        "mac-m4-chrome-stable",
+        "mac-chrome-stable",
+        "mac-chrome-beta",
+        "windows-chrome-stable",
+        "linux-chrome-stable",
+        "mac-brave-stable",
+      ]),
+    );
+  });
+});