@tachikomagundam/abathur 0.1.0

package/dist/core/promote.js

@@ -0,0 +1,119 @@
+// promoteGeneration (todo 10): the human-only gate. Import policy: this module is
+// pulled in ONLY by src/commands/promote.ts — run-loop/evolve code must never reach
+// it (plan Must NOT: no auto-promote path importable by evolve modules; pinned by
+// src/test/promote.test.ts). Every fact comes from the LEDGER, never from worktree
+// contents or exit codes (todo-9 rule): a forged nominated row still has to survive
+// the independent sealed-path diff below before any ref or manifest moves.
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { ExitSignal, blocked, cannotAnswer } from "../exit.js";
+import { compileGlob } from "./glob.js";
+import { fastForwardIncumbent } from "./incumbent.js";
+import { buildManifest, kernelsDirOf, manifestPathFor, readManifestFile, serializeManifest, } from "./kernel.js";
+import { Ledger, ledgerPath } from "./ledger.js";
+import { gitOpts, requireSha } from "./genome-paths.js";
+import { snapshotCommit } from "./snapshot.js";
+import { tryGit } from "../util/git.js";
+import { decodeGenerationRecord } from "./evolve/run-bench.js";
+export const LEDGER_KIND_PROMOTE = "promote";
+/** Ledger/display-safe flattening of untrusted text (todo-8 sealMessage discipline). */
+function display(value, max = 96) {
+    const flat = value.replace(/[^ -~]/g, " ").replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+function short(sha) {
+    return sha.slice(0, 12);
+}
+function firstLine(text) {
+    return text.split("\n")[0]?.trim() ?? "";
+}
+/** Read the nomination from the ledger. Never from worktree files or exit codes. */
+function nominatedGeneration(record, shown) {
+    if (record.source !== "candidate") {
+        blocked(`promote: '${shown}' is an incumbent baseline row — only candidate generations are promotable`);
+    }
+    if (record.verdict === undefined) {
+        blocked(`promote: gen '${shown}' has no verdict in the ledger — cannot promote what the gate never judged`);
+    }
+    if (record.verdict !== "nominated") {
+        blocked(`promote: gen '${shown}' verdict is '${record.verdict}', not 'nominated' — refusing`);
+    }
+    if (record.commitSha === undefined) {
+        blocked(`promote: gen '${shown}' nominated row is missing its commitSha`);
+    }
+    return { commitSha: requireSha(record.commitSha, `promote: gen '${shown}' commit sha`), parent: record.headCommit };
+}
+/**
+ * Second, independent enforcement of the kernel boundary: git-diff the sealed gen
+ * range and cross every touched path against BOTH the spec's immutableGlobs and
+ * the config-home manifest's file set. Runs before any mutation; a hit blocks even
+ * when the ledger says nominated (tampered-ledger posture).
+ */
+async function sealedPathCheck(genId, nom, matchers, sealedPaths, cwd, opts) {
+    const run = await tryGit(["diff", "--name-only", "-z", nom.parent, nom.commitSha], gitOpts(opts, cwd));
+    if (!run.ok) {
+        blocked(`promote: cannot diff ${short(nom.parent)}..${short(nom.commitSha)} for gen '${genId}' in ${cwd}: ${firstLine(run.error.stderr)}`, "the ledger names a commit this repo does not contain — investigate before promoting");
+    }
+    const touched = run.stdout.split("\0").filter((p) => p.length > 0);
+    const hits = touched.filter((p) => sealedPaths.has(p) || matchers.some((re) => re.test(p)));
+    const unique = [...new Set(hits)].sort();
+    if (unique.length > 0) {
+        const shown = unique.slice(0, 10).map((p) => display(p, 200)).join(", ");
+        const more = unique.length > 10 ? ` (+${String(unique.length - 10)} more)` : "";
+        blocked(`promote: gen '${genId}' touches sealed paths: ${shown}${more} — ledger verdict 'nominated' is not sufficient; refusing`, "sealed kernel paths must not move inside a generation; cull it with `abathur tombstone`");
+    }
+}
+export async function promoteGeneration(req) {
+    const { entry, configDir } = req;
+    const repo = entry.spec.repoPath;
+    const shown = display(req.genId);
+    const opts = req.env === undefined ? {} : { env: req.env };
+    const ledger = Ledger.open(repo);
+    const records = ledger.readAll();
+    const genRows = records.filter((r) => r.kind === "generation_complete" && r.genId === req.genId);
+    const lastRow = genRows.at(-1);
+    if (lastRow === undefined) {
+        blocked(`promote: no generation_complete ledger row for gen '${shown}' of '${entry.label}'`, `state is read only from ${ledgerPath(repo)} — check candidates with \`abathur status ${entry.label}\``);
+    }
+    if (records.some((r) => r.kind === LEDGER_KIND_PROMOTE && r.genId === req.genId)) {
+        blocked(`promote: gen '${shown}' is already promoted (promote row in ledger) — nothing to do`);
+    }
+    const nom = nominatedGeneration(decodeGenerationRecord(lastRow), shown);
+    const manifestFile = manifestPathFor(configDir, entry.fingerprint);
+    let manifestEntries;
+    try {
+        manifestEntries = readManifestFile(manifestFile);
+    }
+    catch (cause) {
+        if (cause instanceof ExitSignal)
+            throw cause;
+        const message = cause instanceof Error ? cause.message : String(cause);
+        cannotAnswer(`promote: kernel manifest unreadable, refusing to gate: ${message}`);
+    }
+    const sealedPaths = new Set(manifestEntries.map((e) => e.path));
+    const matchers = entry.spec.kernel.immutableGlobs.map((glob) => compileGlob(glob));
+    await sealedPathCheck(req.genId, nom, matchers, sealedPaths, repo, opts);
+    const genome = { repoPath: repo, genomeFp: entry.fingerprint };
+    const ff = await fastForwardIncumbent(genome, nom.commitSha, opts);
+    // regeneration happens ONLY here, after the human-invoked diff passed:
+    // manifest reborn from the new incumbent's committed tree, not the worktree.
+    const snap = await snapshotCommit(genome, nom.commitSha, opts);
+    const fresh = buildManifest(snap.snapshotPath, entry.spec.kernel.immutableGlobs);
+    mkdirSync(kernelsDirOf(configDir), { recursive: true });
+    writeFileSync(manifestFile, serializeManifest(fresh), "utf8");
+    ledger.append({
+        kind: LEDGER_KIND_PROMOTE,
+        genId: req.genId,
+        data: { actor: "cli", genId: req.genId, from: ff.fromSha, to: ff.toSha },
+    });
+    return {
+        genId: req.genId,
+        fromSha: ff.fromSha,
+        toSha: ff.toSha,
+        lines: [
+            `promoted '${entry.label}' (${entry.fingerprint}): ${ff.fromSha === null ? "incumbent branch created" : short(ff.fromSha)} -> ${short(ff.toSha)} (gen ${shown})`,
+            `manifest: rewrote ${path.relative(process.cwd(), manifestFile) || manifestFile} from tree ${short(nom.commitSha)} (${String(fresh.length)} sealed ${fresh.length === 1 ? "entry" : "entries"})`,
+            `ledger: appended '${LEDGER_KIND_PROMOTE}' row (actor: cli) to ${ledgerPath(repo)}`,
+        ],
+    };
+}

package/dist/core/snapshot.js

@@ -0,0 +1,61 @@
+// snapshotCommit (todo 3): a READ-ONLY copy of a commit's tree for self-bench
+// (todo 11). Materialized as a tiny standalone repo (init + fetch of the exact
+// sha + detached checkout) so `git -C <snapshot> rev-parse HEAD^{tree}` answers
+// with the tree sha, then every write bit is stripped (files 0o444/0o555, dirs
+// 0o555). The copy is content-addressed and idempotent: re-snapshotting the
+// same sha returns the cached dir after an integrity check.
+import { mkdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { blocked } from "../exit.js";
+import { git, tryGit } from "../util/git.js";
+import { freezeTree, thawTree } from "../util/freeze.js";
+import { gitOpts, requireSha, snapshotsDir } from "./genome-paths.js";
+/** Thaw (if needed) then remove a frozen tree. Tolerates a vanished root. */
+export async function removeFrozenTree(target) {
+    try {
+        await thawTree(target);
+    }
+    catch (cause) {
+        // Already gone (ENOENT) — nothing to thaw; rm stays idempotent.
+        if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
+            throw cause;
+    }
+    await rm(target, { recursive: true, force: true });
+}
+async function treeOf(cwd, rev, opts) {
+    const run = await tryGit(["rev-parse", rev], gitOpts(opts, cwd));
+    return run.ok ? run.stdout.trim() : null;
+}
+/**
+ * Copy `commitSha`'s tree into <cache>/<genomeFp>/snapshots/<sha> and freeze it.
+ * Returns the snapshot path plus the commit's tree sha (verified equal to the
+ * snapshot's checked-out tree before returning).
+ */
+export async function snapshotCommit(genome, commitSha, opts = {}) {
+    const sha = requireSha(commitSha);
+    const env = opts.env ?? process.env;
+    const repo = path.resolve(genome.repoPath);
+    const repoTree = await treeOf(repo, `${sha}^{tree}`, opts);
+    if (repoTree === null) {
+        blocked(`worktree: commit ${sha} is not reachable in genome repo ${repo}`);
+    }
+    const snap = path.join(snapshotsDir(env, genome), sha);
+    if ((await stat(snap).catch(() => null)) !== null) {
+        const cached = await treeOf(snap, "HEAD^{tree}", opts);
+        if (cached === repoTree) {
+            return { snapshotPath: snap, commitSha: sha, treeSha: repoTree };
+        }
+        await removeFrozenTree(snap); // half-written or corrupted — rebuild
+    }
+    await mkdir(path.dirname(snap), { recursive: true });
+    await git(["init", "-q", snap], gitOpts(opts, repo));
+    await git(["fetch", "-q", repo, sha], gitOpts(opts, snap));
+    await git(["checkout", "-q", "--detach", "FETCH_HEAD"], gitOpts(opts, snap));
+    const snapTree = await treeOf(snap, "HEAD^{tree}", opts);
+    if (snapTree !== repoTree) {
+        await removeFrozenTree(snap);
+        blocked(`worktree: snapshot integrity mismatch at ${snap}`);
+    }
+    await freezeTree(snap);
+    return { snapshotPath: snap, commitSha: sha, treeSha: repoTree };
+}

package/dist/core/spec.js

@@ -0,0 +1,178 @@
+// GenomeSpec schema (todo 4, plan line 102) — the contract todos 5-9 consume, so the
+// field names below are load-bearing. Identity comes ONLY from the content
+// fingerprint: `label` is a free string and may repeat across distinct genomes.
+// Every bench.stats threshold is REQUIRED — an absent entry is an explicit config
+// error naming the key, mirroring the hr discipline (hr/configs/thresholds.yaml:32-34:
+// "missing entry = explicit config error", never a silent default).
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { cannotAnswer } from "../exit.js";
+import { parseJsonc } from "../jsonc.js";
+export const benchUnitSchema = z.strictObject({
+    id: z.string().min(1),
+    /** Path to the fixture/scenario file inside the genome repo. */
+    path: z.string().min(1),
+    split: z.enum(["train", "val"]),
+});
+/** Decision thresholds for the accept/indeterminate/reject gate — all mandatory. */
+export const benchStatsSchema = z.strictObject({
+    /** Half-width of the acceptance interval around an observed delta. */
+    halfWidth: z.number().positive(),
+    /** Smallest effect that can justify acceptance. */
+    minEffect: z.number().nonnegative(),
+    nReps: z.strictObject({
+        initial: z.number().int().positive(),
+        max: z.number().int().positive(),
+    }),
+});
+export const benchSchema = z
+    .strictObject({
+    type: z.enum(["toy", "opencode-fixture-scenarios"]),
+    units: z.array(benchUnitSchema).min(1),
+    seedCommand: z.string().min(1).optional(),
+    resetCommand: z.string().min(1).optional(),
+    runCommand: z.string().min(1),
+    graderCommand: z.string().min(1),
+    judgeCommand: z.string().min(1).optional(),
+    judgeModel: z.string().min(1).optional(),
+    agentModel: z.string().min(1).optional(),
+    timeoutS: z.number().int().positive(),
+    stats: benchStatsSchema,
+})
+    .superRefine((bench, context) => {
+    if (!bench.units.some((unit) => unit.split === "val")) {
+        context.addIssue({
+            code: "custom",
+            path: ["units"],
+            message: 'bench.units needs at least one split: "val" unit — validation splits are mandatory',
+        });
+    }
+    if (bench.type === "opencode-fixture-scenarios" && bench.agentModel === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["agentModel"],
+            message: 'bench.agentModel is required when bench.type is "opencode-fixture-scenarios"',
+        });
+    }
+    if (bench.judgeCommand !== undefined && bench.judgeModel === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["judgeModel"],
+            message: "bench.judgeModel is required when bench.judgeCommand is set",
+        });
+    }
+});
+/**
+ * Bundle section (todo 12, additive): machine-local literals that `bundle export`
+ * masks out of every manifest/patch/evidence/README member (placeholders
+ * <HOME>/<GENOME>/<MASKED-n>). HOME and the genome repoPath are ALWAYS masked by
+ * the exporter; entries here EXTEND that set — typically from the gitignored
+ * *.local.jsonc overlay, keeping the committed spec machine-independent.
+ */
+export const bundleSectionSchema = z.strictObject({
+    maskLiterals: z.array(z.string().min(1)),
+});
+export const genomeSpecSchema = z.strictObject({
+    /** Free-form identity; genomes are distinguished by fingerprint, never by label. */
+    label: z.string().min(1),
+    /** Genome repo root; registry + kernel manifests live structurally OUTSIDE it. */
+    repoPath: z.string().min(1),
+    bench: benchSchema,
+    budget: z.strictObject({
+        maxCandidates: z.number().int().positive(),
+        maxModelCalls: z.number().int().positive(),
+        maxTokens: z.number().int().positive(),
+        maxWallS: z.number().int().positive(),
+    }),
+    kernel: z.strictObject({
+        /** Sealed working-tree patterns; may only grow until a promote reseals. */
+        immutableGlobs: z.array(z.string().min(1)),
+    }),
+    requires: z
+        .array(z.strictObject({
+        cmd: z.string().min(1),
+        args: z.array(z.string()).optional(),
+        /** Exit code that counts as "engine present" for the one-shot probe. */
+        probeExit: z.number().int().nonnegative(),
+    }))
+        .optional(),
+    opencodeBinVersion: z.strictObject({ minVersion: z.string().min(1) }).optional(),
+    bundle: bundleSectionSchema.optional(),
+});
+function keyPathOf(path) {
+    return path.length === 0 ? "<root>" : path.map(String).join(".");
+}
+function formatIssue(issue) {
+    if (issue.code === "unrecognized_keys") {
+        const listed = issue.keys.map((key) => `"${key}"`).join(", ");
+        return `unknown ${issue.keys.length === 1 ? "key" : "keys"} ${listed} at "${keyPathOf(issue.path)}" — GenomeSpec is strict`;
+    }
+    return `invalid value at "${keyPathOf(issue.path)}": ${issue.message}`;
+}
+/** zod issues → one line per issue, each NAMING the offending key path (hr discipline). */
+export function formatZodIssues(issues) {
+    return issues.map(formatIssue);
+}
+export function errorText(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+// ------------------------------------------------ env-literal repo paths (todo 11)
+/**
+ * `${VAR}` repo-path literal: the abathur-self seed stores repoPath as the
+ * UNRESOLVED literal `${ABATHUR_SELF_REPO}` so the spec bytes — and therefore
+ * its content fingerprint and registry stem — stay machine-independent
+ * (graft matching requires identical specs across machines). The env var is
+ * resolved ONLY at FS boundaries, never inside the spec.
+ */
+const ENV_REPO_LITERAL = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/** True when the spec stores an unresolved `${VAR}` env literal (self-genome marker). */
+export function isEnvRepoLiteral(repoPath) {
+    return ENV_REPO_LITERAL.test(repoPath);
+}
+/** The literal itself when self, else null. */
+export function envRepoName(repoPath) {
+    const match = ENV_REPO_LITERAL.exec(repoPath);
+    return match?.[1] ?? null;
+}
+/**
+ * Resolve a spec repoPath to a filesystem path. Non-literals behave exactly as
+ * `path.resolve` before; `${VAR}` literals demand the env var to be set (missing
+ * or empty ⇒ clean exit 2 naming the variable — never a silently-created
+ * directory named `${ABATHUR_SELF_REPO}`).
+ */
+export function effectiveRepoPath(repoPath, env = process.env) {
+    const name = envRepoName(repoPath);
+    if (name === null)
+        return path.resolve(repoPath);
+    const value = env[name];
+    if (value === undefined || value.length === 0) {
+        cannotAnswer(`genome: repoPath literal '\${${name}}' requires env var ${name} to be set (absolute path to the harness repo)`, `export ${name}=/path/to/abathur before running genomes that reference the harness itself`);
+    }
+    return path.resolve(value);
+}
+/** Parse + strict-validate a GenomeSpec document; every failure is a clean exit 2. */
+export function parseGenomeSpecDocument(document, origin) {
+    const result = genomeSpecSchema.safeParse(document);
+    if (result.success)
+        return result.data;
+    cannotAnswer(`genome: invalid spec in ${origin}:\n  - ${formatZodIssues(result.error.issues).join("\n  - ")}`);
+}
+/** Read a `<file>.jsonc` GenomeSpec: malformed JSONC or schema violation ⇒ exit 2. */
+export function loadGenomeSpecFile(filePath) {
+    let source;
+    try {
+        source = readFileSync(filePath, "utf8");
+    }
+    catch {
+        return cannotAnswer(`genome: cannot read spec file ${filePath}`);
+    }
+    let document;
+    try {
+        document = parseJsonc(source);
+    }
+    catch (cause) {
+        return cannotAnswer(`genome: malformed JSONC in ${filePath}: ${errorText(cause)}`);
+    }
+    return parseGenomeSpecDocument(document, filePath);
+}

package/dist/core/stats-math.js

@@ -0,0 +1,102 @@
+// Student-t critical values, implemented from scratch (plan todo 7): the
+// dependency-free inverse-t via bisection on the regularized incomplete beta
+// (Numerical-Recipes-style Lanczos gamma + Lentz continued fraction) — a new
+// runtime dep is forbidden by the plan. Accuracy: |t − table| < 1e-3 for the
+// t-distribution rows checked in stats.test.ts (df=1..30, α=0.05).
+//
+// Split out of stats.ts (pure-LOC ceiling); stats.ts re-exports studentTQuantile
+// so consumers import it from "../core/stats.js" unchanged.
+const BISECTION_ITERATIONS = 60;
+const LANCZOS = [
+    0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313,
+    -176.61502916214059, 12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6,
+    1.5056327351493116e-7,
+];
+// Lanczos g=7 pairs with the 9 coefficients (c0..c8) above.
+const LANCZOS_G = 7;
+function logGamma(z) {
+    let x = z - 1;
+    let acc = LANCZOS[0];
+    for (let i = 1; i < LANCZOS.length; i++) {
+        acc += LANCZOS[i] / (x + i);
+    }
+    const t = x + LANCZOS_G + 0.5;
+    return 0.5 * Math.log(2 * Math.PI) + (x + 0.5) * Math.log(t) - t + Math.log(acc);
+}
+/** Continued fraction for the regularized incomplete beta (Lentz, NR 6.4.2). */
+function betacf(a, b, x) {
+    const MAXIT = 200;
+    const EPS = 3e-14;
+    const FPMIN = 1e-300;
+    const qab = a + b;
+    const qap = a + 1;
+    const qam = a - 1;
+    let c = 1;
+    let d = 1 - (qab * x) / qap;
+    if (Math.abs(d) < FPMIN)
+        d = FPMIN;
+    d = 1 / d;
+    let h = d;
+    for (let m = 1; m <= MAXIT; m++) {
+        const m2 = 2 * m;
+        let aa = (m * (b - m) * x) / ((qam + m2) * (a + m2));
+        d = 1 + aa * d;
+        if (Math.abs(d) < FPMIN)
+            d = FPMIN;
+        c = 1 + aa / c;
+        if (Math.abs(c) < FPMIN)
+            c = FPMIN;
+        d = 1 / d;
+        h *= d * c;
+        aa = (-(a + m) * (qab + m) * x) / ((a + m2) * (qap + m2));
+        d = 1 + aa * d;
+        if (Math.abs(d) < FPMIN)
+            d = FPMIN;
+        c = 1 + aa / c;
+        if (Math.abs(c) < FPMIN)
+            c = FPMIN;
+        d = 1 / d;
+        const del = d * c;
+        h *= del;
+        if (Math.abs(del - 1) < EPS)
+            break;
+    }
+    return h;
+}
+/** Regularized incomplete beta I_x(a, b), b=1/2 in every call here. */
+function betai(a, b, x) {
+    if (x <= 0)
+        return 0;
+    if (x >= 1)
+        return 1;
+    const front = Math.exp(logGamma(a + b) - logGamma(a) - logGamma(b) + a * Math.log(x) + b * Math.log(1 - x));
+    if (x < (a + 1) / (a + b + 2))
+        return (front * betacf(a, b, x)) / a;
+    return 1 - (front * betacf(b, a, 1 - x)) / b;
+}
+/**
+ * Two-sided Student-t critical value: the t such that P(|T| ≤ t) = 1 − alpha
+ * with T ~ t(df). Planned accuracy: matches t-table values to < 1e-3 for the
+ * checked rows (stats.test.ts). alpha in (0,1), df ≥ 1.
+ */
+export function studentTQuantile(alpha, df) {
+    if (!(alpha > 0 && alpha < 1))
+        throw new RangeError(`studentTQuantile: alpha=${String(alpha)} must be in (0, 1)`);
+    if (!(df >= 1))
+        throw new RangeError(`studentTQuantile: df=${String(df)} must be >= 1`);
+    // T ~ t(ν): P(T ≤ t) = 1 − ½·I_{ν/(ν+t²)}(ν/2, ½). For the two-sided critical
+    // value I_{ν/(ν+t²)}(ν/2, ½) = alpha ⇒ t = √(ν(1−z)/z) with z = ν/(ν+t²).
+    const a = df / 2;
+    const b = 0.5;
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < BISECTION_ITERATIONS; i++) {
+        const mid = (lo + hi) / 2;
+        if (betai(a, b, mid) < alpha)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const z = (lo + hi) / 2;
+    return Math.sqrt((df * (1 - z)) / z);
+}

package/dist/core/stats-pareto.js

@@ -0,0 +1,57 @@
+// Pareto-frontier ranking of complete generations (plan todo 7): the human-facing
+// rank list over (trainScore, tokens, wallS), deterministic per seed. Split out
+// of stats.ts (pure-LOC ceiling); stats.ts re-exports seededRandom, paretoFrontier
+// and the ParetoPoint type, so consumers import them from "../core/stats.js"
+// unchanged.
+/** mulberry32 — dependency-free deterministic PRNG for tie-breaks. */
+export function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function dominates(q, p) {
+    return q.trainScore >= p.trainScore && q.tokens <= p.tokens && q.wallS <= p.wallS && (q.trainScore > p.trainScore || q.tokens < p.tokens || q.wallS < p.wallS);
+}
+/**
+ * Non-dominated complete candidates, ranked for the human: trainScore desc,
+ * then tokens asc, then wallS asc; exact ties share a seeded rank order
+ * (same seed ⇒ same order). Budget-truncated generations never enter the set.
+ */
+export function paretoFrontier(points, seed = 1) {
+    const complete = points.filter((p) => p.complete);
+    const frontier = complete.filter((p) => !complete.some((q) => dominates(q, p)));
+    frontier.sort((a, b) => {
+        if (a.trainScore !== b.trainScore)
+            return b.trainScore - a.trainScore;
+        if (a.tokens !== b.tokens)
+            return a.tokens - b.tokens;
+        return a.wallS - b.wallS;
+    });
+    const rng = seededRandom(seed);
+    const ids = [];
+    let i = 0;
+    while (i < frontier.length) {
+        let j = i + 1;
+        while (j < frontier.length &&
+            frontier[j].trainScore === frontier[i].trainScore &&
+            frontier[j].tokens === frontier[i].tokens &&
+            frontier[j].wallS === frontier[i].wallS) {
+            j += 1;
+        }
+        const group = frontier.slice(i, j);
+        // Fisher–Yates shuffle: deterministic per seed.
+        for (let k = group.length - 1; k > 0; k--) {
+            const r = Math.floor(rng() * (k + 1));
+            [group[k], group[r]] = [group[r], group[k]];
+        }
+        for (const p of group)
+            ids.push(p.id);
+        i = j;
+    }
+    return ids;
+}