arah2/routing/test/maintainer-scripts.test.mjs

#!/usr/bin/env node
/*
 * maintainer-scripts.test.mjs — structural + offline behavioral pins for the
 * routing maintainer toolchain (Phase 08.1 plan 02).
 * -----------------------------------------------------------------------------
 * The build and measurement scripts are MAINTAINER-TIME tools — the full
 * build needs the Overpass network and minutes of compute (D-09), so this
 * suite pins them the way rollout.test.mjs pins the upload/Worker pair:
 * mechanically, from source shape plus the ONE offline surface (--check on
 * the committed ARG3 fixture). A pin here is enforced, not customary.
 *
 *   BS*  build-road-graph.mjs — the CH preprocessing stage (plan 02 task 1):
 *        zero landmark/ALT tokens in code, ONE contractGraph call feeding
 *        the `ch:` encode input, the full measured-stats print block
 *        (D-08/D-09: bytes, witness counts, wall-clock — never a payload
 *        ceiling), the unchanged 1-80 MB D-01 envelope, and `--check`
 *        decoding the committed fixture green with CH facts.
 *   MG*  the measurement gates (plan 02 task 2): the frozen constants stay
 *        pinned exactly once each (the constant-mirror law) and the
 *        decode-failure wording honestly names ARG3.
 *
 * Comment-strip shape = the plan's own verify gate: drop block-comment
 * CONTINUATION lines (leading `*`) and whole-line `//` comments; anything
 * else — code, string literals, block-comment OPENING lines — counts.
 */
import { strict as assert } from "node:assert";
import { spawnSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { test } from "./harness.mjs";

const here = path.dirname(fileURLToPath(import.meta.url)); // routing/test
const BUILD_SCRIPT = path.join(here, "..", "scripts", "build-road-graph.mjs");
const FIXTURE_BIN = path.join(here, "fixtures", "mini-graph.bin");

function readSrc(file) {
  return readFileSync(file, "utf8");
}

/** The plan-verify comment-strip shape (see the header): a token on a code
 *  line, a string literal, or a block-comment OPENING line counts. */
function stripCommentLines(src) {
  return src
    .split("\n")
    .filter((line) => !/^\s*\*/.test(line) && !/^\s*\/\//.test(line))
    .join("\n");
}

function countOccurrences(haystack, needle) {
  return haystack.split(needle).length - 1;
}

/* ————— BS — build-road-graph.mjs: the CH preprocessing stage ————— */

test("BS1 the build is landmark-free — no landmark/ALT-stage tokens survive comment stripping", () => {
  const code = stripCommentLines(readSrc(BUILD_SCRIPT));
  const hits = code.split("\n").filter((line) => line.includes("landmark"));
  assert.equal(hits.length, 0, `landmark tokens must be gone entirely, found ${hits.length}:\n${hits.join("\n")}`);
});

test("BS2 the build runs ONE contractGraph stage and encodes the ch block — never a landmarks field", () => {
  const code = stripCommentLines(readSrc(BUILD_SCRIPT));
  assert.ok(
    countOccurrences(code, "contractGraph(") >= 1,
    "the build must call contractGraph (the ONE CH construction authority)",
  );
  assert.ok(!code.includes("landmarks:"), "the encode input must carry ch:, never landmarks:");
  assert.ok(!code.includes("--landmarks"), "the --landmarks knob is deleted (D-05: no ALT preprocessing)");
});

test("BS3 the build prints the measured CH stats block — counts, witness numbers, CH bytes, wall-clock, total bytes", () => {
  const src = readSrc(BUILD_SCRIPT);
  for (const label of [
    "contracted nodes:",
    "shortcuts:",
    "witness searches:",
    "chRank bytes:",
    "shortcut bytes:",
    "build wall-clock:",
    "total binary:",
  ]) {
    assert.ok(src.includes(label), `the CH stats block must print "${label}" (D-08/D-09: measured, never hoped)`);
  }
});

test("BS4 the D-01 envelope constants are unchanged and single — the 1-80 MB gate stays, no new payload ceiling", () => {
  const src = readSrc(BUILD_SCRIPT);
  assert.equal(
    countOccurrences(src, "MIN_BINARY_BYTES = 1 * 1024 * 1024"),
    1,
    "the enforced 1 MB floor must appear exactly once, unchanged",
  );
  assert.equal(
    countOccurrences(src, "MAX_BINARY_BYTES = 80 * 1024 * 1024"),
    1,
    "the enforced 80 MB ceiling must appear exactly once, unchanged",
  );
});

test("BS5 --check decodes the committed ARG3 fixture green and prints CH facts — no landmark facts, no network", () => {
  const res = spawnSync(process.execPath, [BUILD_SCRIPT, "--check", FIXTURE_BIN], {
    encoding: "utf8",
    timeout: 30000,
  });
  assert.equal(res.status, 0, `--check on the committed fixture must exit 0 (stderr: ${res.stderr})`);
  const out = res.stdout ?? "";
  assert.match(out, /chShortcutCount: \d+/, "the ARG3 header field must print");
  assert.match(out, /shortcut ratio: [\d.]+ per node/, "the shortcut count/ratio must print");
  assert.match(out, /chRank length: \d+/, "the rank length must print");
  assert.ok(!/landmark/i.test(out), "--check prints CH facts, never landmark facts");
});

/* ————— MG — the measurement gates: frozen constants + honest ARG3 wording ————— */

const OPTIMALITY_SCRIPT = path.join(here, "..", "scripts", "measure-optimality-gate.mjs");
const SWEEP_SCRIPT = path.join(here, "..", "scripts", "measure-astar-oracle-sweep.mjs");
const CPU_SCRIPT = path.join(here, "..", "scripts", "measure-route-cpu.mjs");

test("MG1 the optimality gate keeps the frozen D-03 constants and honestly names ARG3 when the binary does not decode", () => {
  const src = readSrc(OPTIMALITY_SCRIPT);
  assert.equal(
    countOccurrences(src, "OPTIMALITY_EPSILON_PCT = 0.1"),
    1,
    "the ±0.1% epsilon mirror must appear exactly once, unchanged",
  );
  assert.equal(
    countOccurrences(src, "REQUIRED_BASELINE_ARG_VERSION = 1"),
    1,
    "the frozen pre-ALT record's argVersion pin must appear exactly once, unchanged",
  );
  const code = stripCommentLines(src);
  assert.ok(code.includes("ARG3"), "the decode-failure message must name ARG3 (the current binary's format)");
  assert.ok(code.includes("build-road-graph.mjs"), "the failure must name the rebuild command");
});

test("MG2 the oracle sweep keeps the seeded 200-pair symmetric-compare constants and honestly names ARG3", () => {
  const src = readSrc(SWEEP_SCRIPT);
  for (const [constant, occurrences] of [
    ["SWEEP_PAIR_COUNT = 200", 1],
    ["SWEEP_SEED = 0x08f1", 1],
    ["SWEEP_OVERSAMPLE_FACTOR = 3", 1],
    ["SWEEP_MIN_PAIR_KM = 12", 1],
    ["ORACLE_EPSILON_S = 1e-6", 1],
  ]) {
    assert.equal(countOccurrences(src, constant), occurrences, `"${constant}" must appear exactly ${occurrences} time(s), unchanged`);
  }
  const code = stripCommentLines(src);
  assert.ok(code.includes("ARG3"), "the decode-failure message must name ARG3 (the current binary's format)");
});

test("MG3 the CPU gate keeps the budget and sample constants exactly once — the 8 ms product budget is the binding pass bar", () => {
  const src = readSrc(CPU_SCRIPT);
  for (const [constant, occurrences] of [
    ["P95_BUDGET_MS = 8", 1],
    ["ROUTE_COUNT = 25", 1],
    ["SAMPLE_SEED = 0x06d4", 1],
    ["EXTENDED_PAIR_COUNT = 100", 1],
    ["EXTENDED_SEED = 0x08a1", 1],
  ]) {
    assert.equal(countOccurrences(src, constant), occurrences, `"${constant}" must appear exactly ${occurrences} time(s), unchanged`);
  }
});