autor3search-typescript 0.1.0

package/dist/discover/benchmarks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmarks.js","sourceRoot":"","sources":["../../src/discover/benchmarks.ts"],"names":[],"mappings":"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"}

package/dist/discover/files.d.ts

@@ -0,0 +1,23 @@
+export type FileKind = 'test' | 'bench' | 'runner-config' | 'source';
+/**
+ * Classifies a repo-relative path.
+ *
+ * Matching is on dot-delimited segments of the basename, not substrings:
+ * `benchmarks.ts` and `testing.ts` are ordinary source, and treating them as
+ * frozen would quietly make real source un-editable.
+ */
+export declare function classify(rel: string): FileKind;
+/** Every regular file in the repository, repo-relative with POSIX separators. */
+export declare function walkRepo(root: string): Promise<string[]>;
+/**
+ * Every symlink in the repository (whatever it points to), repo-relative
+ * with POSIX separators, not followed.
+ *
+ * Exists for `gitx/git.ts`'s `changedFiles`: an untracked symlink is
+ * invisible to `walkRepo` by design (see above) but is exactly what Node
+ * and `tsc` resolve at measure time, so the scope/clean-tree gates must see
+ * it as a change even though the ordinary file walk never will.
+ */
+export declare function listSymlinks(root: string): Promise<string[]>;
+/** Every file that must be frozen at baseline. */
+export declare function freezableFiles(root: string): Promise<string[]>;

package/dist/discover/files.js

@@ -0,0 +1,82 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+/** Directories never walked: build output, dependencies, VCS and tool caches. */
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', 'out']);
+const SCRIPT_EXT = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+const RUNNER_CONFIG = /^(?:vitest|jest|vite)\.config\.(?:[cm]?[jt]s)$/;
+/**
+ * Classifies a repo-relative path.
+ *
+ * Matching is on dot-delimited segments of the basename, not substrings:
+ * `benchmarks.ts` and `testing.ts` are ordinary source, and treating them as
+ * frozen would quietly make real source un-editable.
+ */
+export function classify(rel) {
+    const base = path.posix.basename(rel);
+    if (RUNNER_CONFIG.test(base))
+        return 'runner-config';
+    if (!SCRIPT_EXT.test(base))
+        return 'source';
+    const parts = base.split('.');
+    // parts: name, [qualifier], ext
+    const qualifier = parts.length >= 3 ? parts[parts.length - 2] : undefined;
+    if (qualifier === 'test' || qualifier === 'spec')
+        return 'test';
+    if (qualifier === 'bench')
+        return 'bench';
+    return 'source';
+}
+/**
+ * Walks the repository once, collecting regular files and symlinks
+ * separately. Shared by `walkRepo` and `listSymlinks` so the two never
+ * silently diverge on which directories are skipped.
+ */
+async function walkAll(root) {
+    const files = [];
+    const symlinks = [];
+    async function walk(dir) {
+        const entries = await readdir(path.join(root, dir), { withFileTypes: true });
+        for (const e of entries) {
+            const rel = dir === '' ? e.name : `${dir}/${e.name}`;
+            if (e.isSymbolicLink()) {
+                // Recorded, never followed: a symlink is never walked INTO
+                // (whether it points to a file or a directory), so its target's
+                // contents never appear in `files` regardless of where they live.
+                symlinks.push(rel);
+                continue;
+            }
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name) || e.name.startsWith('.'))
+                    continue;
+                await walk(rel);
+            }
+            else if (e.isFile()) {
+                files.push(rel);
+            }
+        }
+    }
+    await walk('');
+    return { files: files.sort(), symlinks: symlinks.sort() };
+}
+/** Every regular file in the repository, repo-relative with POSIX separators. */
+export async function walkRepo(root) {
+    return (await walkAll(root)).files;
+}
+/**
+ * Every symlink in the repository (whatever it points to), repo-relative
+ * with POSIX separators, not followed.
+ *
+ * Exists for `gitx/git.ts`'s `changedFiles`: an untracked symlink is
+ * invisible to `walkRepo` by design (see above) but is exactly what Node
+ * and `tsc` resolve at measure time, so the scope/clean-tree gates must see
+ * it as a change even though the ordinary file walk never will.
+ */
+export async function listSymlinks(root) {
+    return (await walkAll(root)).symlinks;
+}
+/** Every file that must be frozen at baseline. */
+export async function freezableFiles(root) {
+    const all = await walkRepo(root);
+    return all.filter((f) => classify(f) !== 'source');
+}
+//# sourceMappingURL=files.js.map

package/dist/discover/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/discover/files.ts"],"names":[],"mappings":"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"}

package/dist/doctor/doctor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * One diagnostic result. `doctor` never fails a run on any of these -- it
+ * only ever reports, so `ok` is advice, not a gate.
+ */
+export interface Check {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+/** Pure so the boundary (21 vs. 22 vs. 23) is testable without spawning Node. */
+export declare function nodeVersionVerdict(version: string): Check;
+/** Pure threshold logic, so the 2 GB floor is testable without a real tiny filesystem. */
+export declare function diskSpaceVerdict(freeBytes: number, dir: string): Check;
+/**
+ * Exported (and parameterized on `dir`) so a test can point it at a path
+ * that certainly does not exist and assert it degrades instead of
+ * throwing, per the brief's own suggested test.
+ */
+export declare function checkDiskSpace(dir: string): Promise<Check>;
+/**
+ * Parses `pmset -g batt` output. Pure and exported so the parsing logic is
+ * testable with fixture strings, independent of this machine's actual
+ * power state.
+ */
+export declare function pmsetBatteryVerdict(stdout: string): Check;
+/**
+ * Reads the documented Linux sysfs shape: under `dir`, each `BAT<n>`
+ * entry has a `status` file containing `Charging`, `Discharging`,
+ * `Full`, etc. Exported and parameterized on `dir` so the shape can be
+ * exercised with a fixture directory on any platform -- this project's
+ * dev machine is macOS, so this has been verified only against a
+ * fabricated fixture, never a real Linux kernel.
+ */
+export declare function checkOnBatteryLinux(dir: string): Promise<Check>;
+/** Pure so "performance" vs. anything else is testable without a real sysfs file. */
+export declare function cpuGovernorVerdict(governor: string): Check;
+/**
+ * Reads one sysfs file at a caller-supplied path, so both the "missing
+ * file" fallback and the parsing of a real value can be tested with a
+ * fixture on any platform. This project's dev machine is macOS, so the
+ * fixture-based tests are the only verification this has had -- it has
+ * never run against a real Linux kernel's cpufreq sysfs tree.
+ */
+export declare function checkCpuGovernorAt(governorPath: string): Promise<Check>;
+/**
+ * Pure so the core-count-relative comparison is testable directly: a raw
+ * load of 4 means opposite things on a 4-core and a 64-core machine, so
+ * the check is expressed as a fraction of capacity, not a bare number.
+ */
+export declare function loadAverageVerdict(load1: number, cores: number): Check;
+/**
+ * Runs every diagnostic. Total by construction: each probe already
+ * degrades a missing file or absent command to `ok: true`, and `safe`
+ * catches anything that still escapes. Never rejects, on any platform.
+ */
+export declare function runChecks(): Promise<Check[]>;

package/dist/doctor/doctor.js

@@ -0,0 +1,255 @@
+import { readFile, readdir, statfs } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { ok as execOk, run } from '../runner/exec.js';
+import { stateHome } from '../state/home.js';
+const MIN_NODE_MAJOR = 22;
+const GIB = 1024 ** 3;
+const MIN_FREE_GIB = 2;
+/** 1-minute load average at or above this fraction of core count counts as "busy". */
+const BUSY_LOAD_RATIO = 0.8;
+const PROBE_TIMEOUT_MS = 5_000;
+/**
+ * The shared shape every probe falls back to when its platform-specific
+ * mechanism is missing or unreadable: `ok: true` (this is advice, not a
+ * failure of the machine) with a detail that says plainly why no real
+ * measurement was possible, so the user can tell "checked and fine" apart
+ * from "could not check."
+ */
+function notAvailable(name, reason) {
+    return { name, ok: true, detail: `not available on this platform: ${reason}` };
+}
+// ---------------------------------------------------------------------------
+// Node version
+// ---------------------------------------------------------------------------
+/** Pure so the boundary (21 vs. 22 vs. 23) is testable without spawning Node. */
+export function nodeVersionVerdict(version) {
+    const major = Number(version.replace(/^v/, '').split('.')[0]);
+    const okVal = Number.isFinite(major) && major >= MIN_NODE_MAJOR;
+    return {
+        name: 'node-version',
+        ok: okVal,
+        detail: okVal
+            ? `Node ${version} meets the minimum (>=${MIN_NODE_MAJOR}).`
+            : `Node ${version} is below the minimum (>=${MIN_NODE_MAJOR}); upgrade before trusting timing comparisons -- older runtimes differ in JIT and GC behavior in ways that show up as noise between baseline and candidate.`,
+    };
+}
+function checkNodeVersion() {
+    return nodeVersionVerdict(process.version);
+}
+// ---------------------------------------------------------------------------
+// Free disk space
+// ---------------------------------------------------------------------------
+/** Pure threshold logic, so the 2 GB floor is testable without a real tiny filesystem. */
+export function diskSpaceVerdict(freeBytes, dir) {
+    const freeGb = freeBytes / GIB;
+    const okVal = freeGb >= MIN_FREE_GIB;
+    return {
+        name: 'disk-space',
+        ok: okVal,
+        detail: okVal
+            ? `${freeGb.toFixed(1)} GB free at ${dir}.`
+            : `${freeGb.toFixed(1)} GB free at ${dir}, below the ${MIN_FREE_GIB} GB floor; a worktree plus its own node_modules will not fit comfortably. Free up space before an unattended run.`,
+    };
+}
+/**
+ * Exported (and parameterized on `dir`) so a test can point it at a path
+ * that certainly does not exist and assert it degrades instead of
+ * throwing, per the brief's own suggested test.
+ */
+export async function checkDiskSpace(dir) {
+    try {
+        const stats = await statfs(dir);
+        return diskSpaceVerdict(stats.bavail * stats.bsize, dir);
+    }
+    catch (e) {
+        return notAvailable('disk-space', `could not read free space at ${dir}: ${e.message}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// On battery
+// ---------------------------------------------------------------------------
+/**
+ * Parses `pmset -g batt` output. Pure and exported so the parsing logic is
+ * testable with fixture strings, independent of this machine's actual
+ * power state.
+ */
+export function pmsetBatteryVerdict(stdout) {
+    const onBattery = /Battery Power/.test(stdout);
+    return {
+        name: 'on-battery',
+        ok: !onBattery,
+        detail: onBattery
+            ? 'Running on battery power; macOS scales CPU frequency down aggressively off AC. Plug in before an unattended measurement run.'
+            : 'Running on AC power.',
+    };
+}
+async function checkOnBatteryMac() {
+    const r = await run('pmset', ['-g', 'batt'], { cwd: os.tmpdir(), timeoutMs: PROBE_TIMEOUT_MS });
+    if (!execOk(r))
+        return notAvailable('on-battery', 'pmset did not run on this machine');
+    return pmsetBatteryVerdict(r.stdout);
+}
+/**
+ * Reads the documented Linux sysfs shape: under `dir`, each `BAT<n>`
+ * entry has a `status` file containing `Charging`, `Discharging`,
+ * `Full`, etc. Exported and parameterized on `dir` so the shape can be
+ * exercised with a fixture directory on any platform -- this project's
+ * dev machine is macOS, so this has been verified only against a
+ * fabricated fixture, never a real Linux kernel.
+ */
+export async function checkOnBatteryLinux(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (e) {
+        return notAvailable('on-battery', `${dir} unreadable: ${e.message}`);
+    }
+    const batteries = entries.filter((e) => e.startsWith('BAT'));
+    if (batteries.length === 0) {
+        return { name: 'on-battery', ok: true, detail: 'No battery present (desktop or VM); nothing to check.' };
+    }
+    const statuses = await Promise.all(batteries.map(async (b) => {
+        try {
+            return (await readFile(path.join(dir, b, 'status'), 'utf8')).trim();
+        }
+        catch {
+            return 'unknown';
+        }
+    }));
+    const discharging = statuses.some((s) => s.toLowerCase() === 'discharging');
+    return {
+        name: 'on-battery',
+        ok: !discharging,
+        detail: discharging
+            ? `On battery (${statuses.join(', ')}); frequency scaling on battery invites noise. Plug in before an unattended measurement run.`
+            : `On AC power (${statuses.join(', ')}).`,
+    };
+}
+async function checkOnBattery() {
+    if (process.platform === 'darwin')
+        return checkOnBatteryMac();
+    if (process.platform === 'linux')
+        return checkOnBatteryLinux('/sys/class/power_supply');
+    return notAvailable('on-battery', `no battery probe for platform "${process.platform}"`);
+}
+// ---------------------------------------------------------------------------
+// CPU frequency scaling governor (Linux)
+// ---------------------------------------------------------------------------
+/** Pure so "performance" vs. anything else is testable without a real sysfs file. */
+export function cpuGovernorVerdict(governor) {
+    const okVal = governor === 'performance';
+    return {
+        name: 'cpu-governor',
+        ok: okVal,
+        detail: okVal
+            ? 'cpu0 scaling governor is "performance".'
+            : `cpu0 scaling governor is "${governor}", not "performance"; frequency ramps mid-benchmark add noise between rounds. Consider "cpupower frequency-set -g performance" before measuring.`,
+    };
+}
+/**
+ * Reads one sysfs file at a caller-supplied path, so both the "missing
+ * file" fallback and the parsing of a real value can be tested with a
+ * fixture on any platform. This project's dev machine is macOS, so the
+ * fixture-based tests are the only verification this has had -- it has
+ * never run against a real Linux kernel's cpufreq sysfs tree.
+ */
+export async function checkCpuGovernorAt(governorPath) {
+    try {
+        const governor = (await readFile(governorPath, 'utf8')).trim();
+        return cpuGovernorVerdict(governor);
+    }
+    catch (e) {
+        return notAvailable('cpu-governor', `scaling_governor unreadable: ${e.message}`);
+    }
+}
+async function checkCpuGovernor() {
+    if (process.platform !== 'linux') {
+        return notAvailable('cpu-governor', `scaling_governor is Linux-only (platform "${process.platform}")`);
+    }
+    return checkCpuGovernorAt('/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor');
+}
+// ---------------------------------------------------------------------------
+// Thermal / chip-family risk -- informational only, never a pass/fail
+// ---------------------------------------------------------------------------
+/**
+ * There is no portable, reliable API to read "currently throttled" --
+ * macOS's own `pmset -g therm` reports nothing useful on Apple Silicon
+ * (confirmed empirically on this machine: "No thermal warning level has
+ * been recorded" even under load), which is exactly the kind of probe
+ * that always returns "ok" for lack of a real measurement the brief warns
+ * against shipping. Instead this reports the chip and, on Apple Silicon,
+ * the one thing that is both true and actionable: heterogeneous P/E cores
+ * make single-run timings noisy regardless of thermal state. Always
+ * `ok: true` -- explicitly informational, not a verdict.
+ */
+function checkThermalRisk() {
+    const cpus = os.cpus();
+    const model = cpus[0]?.model.trim() ?? 'unknown CPU';
+    const isAppleSilicon = process.platform === 'darwin' && process.arch === 'arm64';
+    const detail = isAppleSilicon
+        ? `${model}, ${cpus.length} logical cores. Apple Silicon's P/E-core scheduler can place the same benchmark on a fast performance core in one run and a slow efficiency core in the next, adding variance unrelated to any code change -- expect to need more rounds than on a uniform-core machine. Informational only, not a pass/fail check.`
+        : `${model}, ${cpus.length} logical cores. Sustained back-to-back runs can trigger thermal throttling on any laptop chip; watch for timings drifting worse over a long session. Informational only, not a pass/fail check.`;
+    return { name: 'thermal-risk', ok: true, detail };
+}
+// ---------------------------------------------------------------------------
+// Load average relative to core count
+// ---------------------------------------------------------------------------
+/**
+ * Pure so the core-count-relative comparison is testable directly: a raw
+ * load of 4 means opposite things on a 4-core and a 64-core machine, so
+ * the check is expressed as a fraction of capacity, not a bare number.
+ */
+export function loadAverageVerdict(load1, cores) {
+    const ratio = load1 / cores;
+    const pct = (ratio * 100).toFixed(0);
+    const okVal = ratio < BUSY_LOAD_RATIO;
+    return {
+        name: 'load-average',
+        ok: okVal,
+        detail: okVal
+            ? `1-minute load average ${load1.toFixed(2)} across ${cores} core(s) (~${pct}% of capacity).`
+            : `1-minute load average ${load1.toFixed(2)} across ${cores} core(s) (~${pct}% of capacity) -- this machine is already busy. A competing process is exactly what turns a no-op change into a false KEEP or DISCARD; consider waiting or closing other work.`,
+    };
+}
+function checkLoadAverage() {
+    if (process.platform === 'win32') {
+        // Node documents os.loadavg() as always [0, 0, 0] on Windows.
+        return notAvailable('load-average', 'Windows does not report a load average (Node always returns 0)');
+    }
+    const [load1] = os.loadavg();
+    const cores = os.cpus().length || 1;
+    return loadAverageVerdict(load1 ?? 0, cores);
+}
+/**
+ * Wraps every probe individually so a bug in one check's own logic (not
+ * just a missing file the probe already anticipates) still cannot take
+ * down `runChecks` as a whole. Each probe already degrades known failure
+ * modes to `notAvailable`; this is the outer safety net for the unknown
+ * ones, which is why `runChecks` can promise it never throws.
+ */
+async function safe(name, probe) {
+    try {
+        return await probe();
+    }
+    catch (e) {
+        return notAvailable(name, `probe threw unexpectedly: ${e.message}`);
+    }
+}
+/**
+ * Runs every diagnostic. Total by construction: each probe already
+ * degrades a missing file or absent command to `ok: true`, and `safe`
+ * catches anything that still escapes. Never rejects, on any platform.
+ */
+export async function runChecks() {
+    return Promise.all([
+        safe('node-version', () => checkNodeVersion()),
+        safe('disk-space', () => checkDiskSpace(stateHome())),
+        safe('on-battery', () => checkOnBattery()),
+        safe('cpu-governor', () => checkCpuGovernor()),
+        safe('thermal-risk', () => checkThermalRisk()),
+        safe('load-average', () => checkLoadAverage()),
+    ]);
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/doctor/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAY5C,MAAM,cAAc,GAAG,EAAE,CAAA;AACzB,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,CAAA;AACrB,MAAM,YAAY,GAAG,CAAC,CAAA;AACtB,sFAAsF;AACtF,MAAM,eAAe,GAAG,GAAG,CAAA;AAC3B,MAAM,gBAAgB,GAAG,KAAK,CAAA;AAE9B;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,MAAc;IAChD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,mCAAmC,MAAM,EAAE,EAAE,CAAA;AAChF,CAAC;AAED,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,iFAAiF;AACjF,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,cAAc,CAAA;IAC/D,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,KAAK;YACX,CAAC,CAAC,QAAQ,OAAO,yBAAyB,cAAc,IAAI;YAC5D,CAAC,CAAC,QAAQ,OAAO,4BAA4B,cAAc,6JAA6J;KAC3N,CAAA;AACH,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO,kBAAkB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;AAC5C,CAAC;AAED,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,0FAA0F;AAC1F,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,GAAW;IAC7D,MAAM,MAAM,GAAG,SAAS,GAAG,GAAG,CAAA;IAC9B,MAAM,KAAK,GAAG,MAAM,IAAI,YAAY,CAAA;IACpC,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,KAAK;YACX,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,GAAG,GAAG;YAC3C,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,GAAG,eAAe,YAAY,mHAAmH;KACzL,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC9C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAA;QAC/B,OAAO,gBAAgB,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAC1D,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,YAAY,CAAC,YAAY,EAAE,gCAAgC,GAAG,KAAM,CAAW,CAAC,OAAO,EAAE,CAAC,CAAA;IACnG,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC9C,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,EAAE,EAAE,CAAC,SAAS;QACd,MAAM,EAAE,SAAS;YACf,CAAC,CAAC,8HAA8H;YAChI,CAAC,CAAC,sBAAsB;KAC3B,CAAA;AACH,CAAC;AAED,KAAK,UAAU,iBAAiB;IAC9B,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC,CAAA;IAC/F,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAAE,OAAO,YAAY,CAAC,YAAY,EAAE,mCAAmC,CAAC,CAAA;IACtF,OAAO,mBAAmB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAW;IACnD,IAAI,OAAiB,CAAA;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;IAC9B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,YAAY,CAAC,YAAY,EAAE,GAAG,GAAG,gBAAiB,CAAW,CAAC,OAAO,EAAE,CAAC,CAAA;IACjF,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAA;IAC5D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,uDAAuD,EAAE,CAAA;IAC1G,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAChC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QACxB,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC,CAAC,CACH,CAAA;IACD,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,aAAa,CAAC,CAAA;IAC3E,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,EAAE,EAAE,CAAC,WAAW;QAChB,MAAM,EAAE,WAAW;YACjB,CAAC,CAAC,eAAe,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,8FAA8F;YAClI,CAAC,CAAC,gBAAgB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;KAC5C,CAAA;AACH,CAAC;AAED,KAAK,UAAU,cAAc;IAC3B,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,iBAAiB,EAAE,CAAA;IAC7D,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,mBAAmB,CAAC,yBAAyB,CAAC,CAAA;IACvF,OAAO,YAAY,CAAC,YAAY,EAAE,kCAAkC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAA;AAC1F,CAAC;AAED,8EAA8E;AAC9E,yCAAyC;AACzC,8EAA8E;AAE9E,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,MAAM,KAAK,GAAG,QAAQ,KAAK,aAAa,CAAA;IACxC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,KAAK;YACX,CAAC,CAAC,yCAAyC;YAC3C,CAAC,CAAC,6BAA6B,QAAQ,kJAAkJ;KAC5L,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,YAAoB;IAC3D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,CAAC,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC9D,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAA;IACrC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,YAAY,CAAC,cAAc,EAAE,gCAAiC,CAAW,CAAC,OAAO,EAAE,CAAC,CAAA;IAC7F,CAAC;AACH,CAAC;AAED,KAAK,UAAU,gBAAgB;IAC7B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,YAAY,CAAC,cAAc,EAAE,6CAA6C,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAA;IACxG,CAAC;IACD,OAAO,kBAAkB,CAAC,uDAAuD,CAAC,CAAA;AACpF,CAAC;AAED,8EAA8E;AAC9E,sEAAsE;AACtE,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,SAAS,gBAAgB;IACvB,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,EAAE,CAAA;IACtB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,aAAa,CAAA;IACpD,MAAM,cAAc,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,CAAA;IAChF,MAAM,MAAM,GAAG,cAAc;QAC3B,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,qTAAqT;QAC/U,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,iMAAiM,CAAA;IAC7N,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;AACnD,CAAC;AAED,8EAA8E;AAC9E,sCAAsC;AACtC,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,KAAa;IAC7D,MAAM,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;IAC3B,MAAM,GAAG,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IACpC,MAAM,KAAK,GAAG,KAAK,GAAG,eAAe,CAAA;IACrC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,KAAK;YACX,CAAC,CAAC,yBAAyB,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,KAAK,cAAc,GAAG,iBAAiB;YAC7F,CAAC,CAAC,yBAAyB,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,KAAK,cAAc,GAAG,gLAAgL;KAC/P,CAAA;AACH,CAAC;AAED,SAAS,gBAAgB;IACvB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,8DAA8D;QAC9D,OAAO,YAAY,CAAC,cAAc,EAAE,gEAAgE,CAAC,CAAA;IACvG,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAA;IAC5B,MAAM,KAAK,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,CAAA;IACnC,OAAO,kBAAkB,CAAC,KAAK,IAAI,CAAC,EAAE,KAAK,CAAC,CAAA;AAC9C,CAAC;AAQD;;;;;;GAMG;AACH,KAAK,UAAU,IAAI,CAAC,IAAY,EAAE,KAAY;IAC5C,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,EAAE,CAAA;IACtB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,YAAY,CAAC,IAAI,EAAE,6BAA8B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAA;IAChF,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,OAAO,OAAO,CAAC,GAAG,CAAC;QACjB,IAAI,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC;QAC9C,IAAI,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC,CAAC;QACrD,IAAI,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC;QAC1C,IAAI,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC;QAC9C,IAAI,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC;QAC9C,IAAI,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC;KAC/C,CAAC,CAAA;AACJ,CAAC"}

package/dist/freeze/freeze.d.ts

@@ -0,0 +1,23 @@
+import { type Manifest } from './manifest.js';
+export declare function buildManifest(root: string, rels: string[]): Promise<Manifest>;
+/** Copies every listed file into destDir, preserving relative layout. */
+export declare function snapshot(root: string, rels: string[], destDir: string): Promise<Manifest>;
+/**
+ * Restores every manifest entry into the repository, returning the paths that
+ * actually differed. Edits are erased rather than argued about.
+ */
+export declare function restore(root: string, srcDir: string, manifest: Manifest): Promise<string[]>;
+/**
+ * Candidate test or bench files absent from the manifest.
+ *
+ * This is what closes "add an easier benchmark": a file that looks like a
+ * benchmark but was not frozen at baseline is rejected, not measured.
+ *
+ * The task brief's draft signature carried a leading `repoRoot` parameter.
+ * It was genuinely dead: every comparison here is against manifest keys and
+ * `unfreeze` entries, which are already repo-relative, so no filesystem
+ * lookup was ever performed against it. Removed rather than kept as an
+ * underscore-prefixed parameter, after confirming no other task's call site
+ * depends on the four-argument form.
+ */
+export declare function findUnmanifested(candidates: string[], manifest: Manifest, unfreeze: string[]): string[];

package/dist/freeze/freeze.js

@@ -0,0 +1,107 @@
+import { copyFile, lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { hashString } from './manifest.js';
+import { assertSafeRelPath } from './safepath.js';
+/**
+ * Throws if `rel` inside `root` is a symlink.
+ *
+ * Both directions matter, for different reasons. `buildManifest`/`snapshot`
+ * `readFile` the path directly, so an unguarded symlink there would freeze
+ * (and copy into the snapshot dir) whatever it points at, leaking content
+ * from outside the repository. `restore`'s write path unlinks before
+ * writing (see below), which happens to stop a naive "symlink to a
+ * differing file" attack — but not the more patient one: point the link at
+ * a file whose bytes already match the frozen content, so `restore` sees no
+ * difference and leaves the live symlink in place, then edit the link's
+ * target *after* restore has already run and "approved" the path. Without
+ * this check that swap is invisible: a later test run reads straight
+ * through the symlink to whatever the agent put there last. This check
+ * refuses the path outright, so no symlink survives a restore regardless of
+ * whether its current content happens to match.
+ *
+ * A missing path is not an error here: `buildManifest` immediately follows
+ * this with a `readFile` that throws its own (loud) ENOENT for a baseline
+ * file that vanished, and `restore` legitimately expects the agent to have
+ * deleted a frozen file — that is one of the two things it must repair.
+ */
+async function assertNotSymlink(root, rel) {
+    const abs = path.join(root, rel);
+    try {
+        const st = await lstat(abs);
+        if (st.isSymbolicLink()) {
+            throw new Error(`refusing to touch ${rel}: it is a symlink, and following it would read or write outside the repository`);
+        }
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+}
+export async function buildManifest(root, rels) {
+    const files = {};
+    for (const rel of rels.slice().sort()) {
+        assertSafeRelPath(rel);
+        await assertNotSymlink(root, rel);
+        files[rel] = hashString(await readFile(path.join(root, rel), 'utf8'));
+    }
+    return { files };
+}
+/** Copies every listed file into destDir, preserving relative layout. */
+export async function snapshot(root, rels, destDir) {
+    const manifest = await buildManifest(root, rels);
+    for (const rel of Object.keys(manifest.files)) {
+        const dest = path.join(destDir, rel);
+        await mkdir(path.dirname(dest), { recursive: true });
+        await copyFile(path.join(root, rel), dest);
+    }
+    return manifest;
+}
+/**
+ * Restores every manifest entry into the repository, returning the paths that
+ * actually differed. Edits are erased rather than argued about.
+ */
+export async function restore(root, srcDir, manifest) {
+    const changed = [];
+    for (const rel of Object.keys(manifest.files).sort()) {
+        assertSafeRelPath(rel);
+        await assertNotSymlink(root, rel);
+        const abs = path.join(root, rel);
+        const want = await readFile(path.join(srcDir, rel), 'utf8');
+        let have = null;
+        try {
+            have = await readFile(abs, 'utf8');
+        }
+        catch {
+            have = null;
+        }
+        if (have === want)
+            continue;
+        await mkdir(path.dirname(abs), { recursive: true });
+        // rm first so a read-only leftover cannot deflect the write, and so a
+        // symlink that slipped past assertNotSymlink's lstat by a race is
+        // unlinked (not followed) rather than written through.
+        await rm(abs, { force: true });
+        await writeFile(abs, want);
+        changed.push(rel);
+    }
+    return changed;
+}
+/**
+ * Candidate test or bench files absent from the manifest.
+ *
+ * This is what closes "add an easier benchmark": a file that looks like a
+ * benchmark but was not frozen at baseline is rejected, not measured.
+ *
+ * The task brief's draft signature carried a leading `repoRoot` parameter.
+ * It was genuinely dead: every comparison here is against manifest keys and
+ * `unfreeze` entries, which are already repo-relative, so no filesystem
+ * lookup was ever performed against it. Removed rather than kept as an
+ * underscore-prefixed parameter, after confirming no other task's call site
+ * depends on the four-argument form.
+ */
+export function findUnmanifested(candidates, manifest, unfreeze) {
+    const allowed = new Set([...Object.keys(manifest.files), ...unfreeze]);
+    return candidates.filter((c) => !allowed.has(c)).sort();
+}
+//# sourceMappingURL=freeze.js.map

package/dist/freeze/freeze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freeze.js","sourceRoot":"","sources":["../../src/freeze/freeze.ts"],"names":[],"mappings":"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"}

package/dist/freeze/manifest.d.ts

@@ -0,0 +1,6 @@
+/** Repo-relative path -> SHA-256 hex of its content at baseline. */
+export interface Manifest {
+    files: Record<string, string>;
+}
+export declare function hashString(s: string): string;
+export declare function hashFile(abs: string): Promise<string>;

package/dist/freeze/manifest.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+export function hashString(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+export async function hashFile(abs) {
+    return hashString(await readFile(abs, 'utf8'));
+}
+//# sourceMappingURL=manifest.js.map

package/dist/freeze/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/freeze/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAO3C,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACrD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAW;IACxC,OAAO,UAAU,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAA;AAChD,CAAC"}

package/dist/freeze/safepath.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Refuses any path that could escape the repository root.
+ *
+ * The agent controls the repository, so a manifest entry or a discovered path
+ * is untrusted input. Normalising first defeats `src/../../x`, which looks
+ * innocent until it is resolved.
+ */
+export declare function assertSafeRelPath(p: string): void;

package/dist/freeze/safepath.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+/**
+ * Refuses any path that could escape the repository root.
+ *
+ * The agent controls the repository, so a manifest entry or a discovered path
+ * is untrusted input. Normalising first defeats `src/../../x`, which looks
+ * innocent until it is resolved.
+ */
+export function assertSafeRelPath(p) {
+    if (p === '' || p === '.')
+        throw new Error('unsafe path: empty');
+    if (p.includes('\\'))
+        throw new Error(`unsafe path: backslash in ${JSON.stringify(p)}`);
+    if (path.posix.isAbsolute(p) || /^[A-Za-z]:/.test(p)) {
+        throw new Error(`unsafe path: absolute ${JSON.stringify(p)}`);
+    }
+    const normalized = path.posix.normalize(p);
+    if (normalized === '..' || normalized.startsWith('../')) {
+        throw new Error(`unsafe path: parent traversal in ${JSON.stringify(p)}`);
+    }
+}
+//# sourceMappingURL=safepath.js.map

package/dist/freeze/safepath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safepath.js","sourceRoot":"","sources":["../../src/freeze/safepath.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAA;IAChE,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACvF,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAC/D,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;IAC1C,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,oCAAoC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAC1E,CAAC;AACH,CAAC"}