autor3search-typescript 0.1.1 → 0.1.2

package/README.md

@@ -63,17 +63,13 @@ Two things worth knowing before you start it:
   Limitations below for how much run-to-run noise a JS runtime can add even on an
   idle machine.
 
-## What you get back
+## The idea
 
-An unattended loop that, commit by commit:
-
-- measures the agent's candidate against a frozen baseline with real, repeated, interleaved timing rounds and a rank-sum significance test — not a single before/after number;
-- restores any test, spec or benchmark file the agent edited before running it, so a weakened test can never manufacture a KEEP;
-- refuses (FAILs) a change that touches `package.json`, a lockfile, `tsconfig.json`, or a file outside the declared `scope`, before anything is even measured;
-- refuses a change that adds a new test/bench file the baseline never saw, closing "add an easier benchmark";
-- appends one row per experiment to `results.tsv`, and reports a cumulative, compounding speedup across the whole run.
+You do not edit TypeScript to tune performance. You edit `program.md` — the
+instructions that drive your agent. The agent edits the TypeScript. The harness
+holds the metric, and the agent cannot reach it.
 
-## Who owns what
+### Who owns what
 
 | | you edit | the agent edits |
 |---|---|---|
@@ -87,6 +83,16 @@ An unattended loop that, commit by commit:
 
 The measurement state — baselines, locks, stop requests — lives outside the repository entirely (see "Where run state lives" below). If the agent could write any of it, it could grade its own work.
 
+### What you get back
+
+An unattended loop that, commit by commit:
+
+- measures the agent's candidate against a frozen baseline with real, repeated, interleaved timing rounds and a rank-sum significance test — not a single before/after number;
+- restores any test, spec or benchmark file the agent edited before running it, so a weakened test can never manufacture a KEEP;
+- refuses (FAILs) a change that touches `package.json`, a lockfile, `tsconfig.json`, or a file outside the declared `scope`, before anything is even measured;
+- refuses a change that adds a new test/bench file the baseline never saw, closing "add an easier benchmark";
+- appends one row per experiment to `results.tsv`, and reports a cumulative, compounding speedup across the whole run.
+
 ## Quick start
 
 ```bash
@@ -104,7 +110,7 @@ To install from `main` ahead of a release instead of the last published version,
 `npm install --save-dev g4lb/autor3search-typescript` — the GitHub form works too,
 just builds the tool on the way in instead of using a prebuilt tarball.
 
-## Watching and stopping a run
+## Watching a run, and stopping it
 
 ```bash
 npx autor3search-typescript status -tag <tag>   # branch, commits, worktree, experiment counts, in-flight eval — read-only
@@ -127,14 +133,15 @@ npx autor3search-typescript stop -tag <tag> -clear   # cancel a pending stop
 | `stop` | Ask the agent to stop after its current experiment; `-clear` cancels, `-force` also signals the running eval |
 | `report` | Summarize `results.tsv`: counts by status, cumulative speedup, largest individual wins |
 | `profile` | Run the declared benchmarks under Node's CPU profiler and print the hottest functions |
+| `version` | Print which build of the harness this is, and the Node runtime measuring with it |
 
 Every command accepts a leading `-C <dir>` to run as if invoked from `<dir>` (its git repository root is resolved from there).
 
-## Where run state lives
+### Where run state lives
 
 Everything the verdict depends on — the frozen manifest, the baseline record, the eval lock, stop requests — lives under the OS cache directory (`~/Library/Caches` on macOS, `$XDG_CACHE_HOME` or `~/.cache` on Linux, `%LOCALAPPDATA%` on Windows), keyed by the repository's own canonical path and the `-tag` you chose, never inside the repository itself. `results.tsv` and `run.log` also live in the repository but are gitignored and untracked — plain, human-readable output, not gated artifacts. `.autor3search/config.yaml` is the one exception: `init` writes `.autor3search/*` to `.gitignore` with a `!.autor3search/config.yaml` negation, so the run configuration itself is committed to version history (a KEEP has to stay reproducible and auditable later), while only its hash — not its content — is what the gate chain actually trusts; a hand-edit to it fails the next `eval` rather than silently loosening it.
 
-## The worked example
+## Worked example
 
 This is one real, unmodified run of this tool against the demo fixture shipped in `testdata/demo/`: a `countWords` function whose hot loop rebuilds a whole new array on every character —
 
@@ -189,7 +196,18 @@ Each declared benchmark is measured `count` times per side (baseline and candida
 
 `count` below 4 is refused outright at config-load time: with fewer than 4 rounds per side, the exact rank-sum test cannot report `p < 0.05` no matter how large the true effect is, so every experiment would DISCARD regardless of what changed. The shipped default is 10.
 
-## Limitations — read this before trusting an overnight run
+### When the measurement cannot carry the verdict
+
+`eval` prints `WARNING:` lines above its verdict (and a `warnings` array in `--json`) when the statistics behind a result do not support reading it at face value. They never change the decision. Two matter:
+
+- **Too few rounds for a confidence interval.** At 95% confidence the median's interval needs at least 6 observations per side; below that it is unbounded.
+- **No KEEP was reachable.** The Mann-Whitney U test has a floor on the p-value it can produce for a given sample size — with `n` rounds per side the smallest attainable two-sided p is `2/C(2n,n)`, however far apart the two samples are. Rule 1 divides `ALPHA` by the number of benchmarks, so enough benchmarks push the corrected threshold below that floor and *every* experiment discards no matter what the agent does. The `count >= 4` floor cannot catch this: it does not know how many benchmarks a run will compare. The warning names the count to raise to, or says to compare fewer benchmarks when no count would clear it.
+
+`base_ns` is **not** fixed for the whole run. `baseline` pins two things that are kept deliberately separate: a FROZEN commit that the frozen tests and the scope gate always compare against (so an agent cannot expand what it may edit by banking experiments), and a MEASUREMENT commit — what `base_ns` is actually measured against — that starts equal to the frozen one and **advances to the candidate's own commit after every KEEP**. So `score` always answers "did *this* experiment help, compared to the last thing that was kept," never "is the tree better than when the run started." Without this, once one real improvement was kept, every later experiment — however useless — would keep comparing against that same stale starting point, and a no-op could coast to a KEEP on an earlier win it did not contribute to.
+
+One consequence: each kept `score` is only that experiment's own incremental contribution, so `report`'s cumulative speedup is the **product** of every kept score, not the latest one alone — successive real improvements compound the way percentage changes do.
+
+## Limitations
 
 **A KEEP is evidence, not proof.** Any fixed statistical threshold admits false positives; a KEEP means "this cleared the bar the config set," not "this change is definitely faster in production."
 
@@ -208,3 +226,26 @@ Each declared benchmark is measured `count` times per side (baseline and candida
 **`count` below 4 can never reach significance,** for the reason given under Scoring above, which is why it is refused at config-load time rather than silently producing a run that can only ever DISCARD.
 
 A performance tool that oversells its own certainty is worse than useless: it launders noise into a verdict a human then trusts. Every claim above is stated as plainly as it can be for exactly that reason.
+
+### Repos with no benchmarks
+
+`init` discovers benchmarks by scanning the repository for `*.bench.ts` files and looking for exported functions named `bench*`. If it finds none, it refuses to write `.autor3search/config.yaml` and exits with an error, rather than generating a config with an empty `benchmarks:` list that would silently optimize nothing.
+
+That refusal is deliberate: this tool has no other notion of "faster." The verdict — KEEP, DISCARD, FAIL, CRASH — is entirely a function of the declared benchmarks' timings across a baseline and a candidate. No benchmarks means no signal to gate on, at which point every candidate would either be rejected for no reason or accepted for no reason.
+
+To use `autor3search-typescript` on a repository like this:
+
+1. Write at least one benchmark covering the code you actually want made faster — a plain exported function in a `*.bench.ts` file:
+
+   ```ts
+   export function benchThing(): void {
+     thing()
+   }
+   ```
+
+2. Benchmark the right thing. A benchmark that exercises a cold path, a trivial helper, or a function nobody calls under load produces numbers that are entirely real and entirely useless — confident percentages attached to work that was never the bottleneck. Benchmark the function, loop, or request path that actually dominates the workload you care about, ideally informed by `profile` or a profile of the real program rather than a guess.
+3. Re-run `init` once the benchmark exists. It will pick it up and proceed normally.
+
+## License
+
+MIT © 2026 Gal Be

package/dist/cli/cmd-version.d.ts

@@ -0,0 +1,13 @@
+import type { RunCtx } from './runctx.js';
+/**
+ * Reports which build of the harness is running.
+ *
+ * Worth having for the same reason the Go sibling has it: a `results.tsv`
+ * row is only as reproducible as the harness that produced it, and "which
+ * version measured this" is otherwise unanswerable from an installed copy.
+ *
+ * Takes no flags, and says so rather than ignoring them -- a silently
+ * accepted typo here would be reported as a version by whatever script
+ * called it.
+ */
+export declare function cmdVersion(_ctx: RunCtx, argv: readonly string[]): Promise<number>;

package/dist/cli/cmd-version.js

@@ -0,0 +1,25 @@
+import { parseArgs } from 'node:util';
+import { formatVersion } from '../version.js';
+/**
+ * Reports which build of the harness is running.
+ *
+ * Worth having for the same reason the Go sibling has it: a `results.tsv`
+ * row is only as reproducible as the harness that produced it, and "which
+ * version measured this" is otherwise unanswerable from an installed copy.
+ *
+ * Takes no flags, and says so rather than ignoring them -- a silently
+ * accepted typo here would be reported as a version by whatever script
+ * called it.
+ */
+export async function cmdVersion(_ctx, argv) {
+    try {
+        parseArgs({ args: [...argv], options: {}, strict: true, allowPositionals: false });
+    }
+    catch {
+        process.stderr.write('error: version takes no arguments\n');
+        return 2;
+    }
+    process.stdout.write(formatVersion());
+    return 0;
+}
+//# sourceMappingURL=cmd-version.js.map

package/dist/cli/cmd-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmd-version.js","sourceRoot":"","sources":["../../src/cli/cmd-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAG7C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,IAAuB;IACpE,IAAI,CAAC;QACH,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,CAAA;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAA;QAC3D,OAAO,CAAC,CAAA;IACV,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,CAAA;IACrC,OAAO,CAAC,CAAA;AACV,CAAC"}

package/dist/cli/main.js

@@ -9,6 +9,7 @@ import { cmdProfile } from './cmd-profile.js';
 import { cmdReport } from './cmd-report.js';
 import { cmdStatus } from './cmd-status.js';
 import { cmdStop } from './cmd-stop.js';
+import { cmdVersion } from './cmd-version.js';
 import { resolveCtx, splitDashC } from './runctx.js';
 /**
  * The command table.
@@ -31,6 +32,7 @@ export const COMMANDS = {
     stop: cmdStop,
     report: cmdReport,
     profile: cmdProfile,
+    version: cmdVersion,
 };
 const HELP = `autor3search-typescript -- autonomous performance optimization for a TypeScript repository
 
@@ -45,11 +47,24 @@ Commands:
   stop      Ask the agent to stop after its current experiment; -clear cancels, -force also signals the running eval
   report    Summarize results.tsv: counts by status, cumulative speedup, largest individual wins
   profile   Run the declared benchmarks under Node's CPU profiler and print the hottest functions
+  version   Print which build of the harness this is, and the Node runtime measuring with it
 
 Global flags:
   -C <dir>  Run as if invoked from <dir> (resolves that directory's git repository root)
   --help    Print this message
 `;
+/**
+ * Stand-in context for the one command that must run outside a repository.
+ * Every field is a path `version` never touches; it exists only so the
+ * shared `(ctx, argv)` command signature holds without a `RunCtx | null`
+ * that all eight other commands would then have to narrow.
+ */
+const NO_REPO_CTX = {
+    repoRoot: '',
+    configPath: '',
+    resultsPath: '',
+    logPath: '',
+};
 function printHelp() {
     process.stdout.write(HELP);
 }
@@ -84,6 +99,14 @@ export async function main(argv) {
             printHelp();
             return 2;
         }
+        // `version` reports the harness's own identity, which has nothing to do
+        // with any repository -- and "which version is installed?" is asked most
+        // often from outside one. Resolving a RunCtx first would make it fail
+        // with "not inside a git repository", so it dispatches without one, the
+        // way `--help` does. Every other command genuinely needs the repo.
+        if (name === 'version') {
+            return await command(NO_REPO_CTX, commandArgv);
+        }
         const ctx = await resolveCtx(argv);
         return await command(ctx, commandArgv);
     }

package/dist/cli/main.js.map

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

package/dist/version.d.ts

@@ -1,2 +1,10 @@
-/** The published package version. Kept in step with package.json by hand. */
-export declare const VERSION = "0.1.0";
+export declare const VERSION: string;
+/**
+ * Build identity for `version`, mirroring the Go sibling's reasoning: a
+ * results.tsv row is only as reproducible as the harness that produced it,
+ * and "which version measured this" is otherwise unanswerable from an
+ * installed copy. Go reports its toolchain and GOOS/GOARCH; the Node
+ * equivalents are the runtime version and platform/arch, which also decide
+ * whether two measurements are even comparable.
+ */
+export declare function formatVersion(): string;

package/dist/version.js

@@ -1,3 +1,33 @@
-/** The published package version. Kept in step with package.json by hand. */
-export const VERSION = '0.1.0';
+import { createRequire } from 'node:module';
+/**
+ * The running package's version, read from the package.json that ships in
+ * the tarball rather than kept in step with it by hand.
+ *
+ * The hand-synced constant this replaces drifted on the very first release:
+ * it still said 0.1.0 after package.json moved to 0.1.1, and its only test
+ * asserted the constant matched a semver regex -- which it did, wrongly.
+ * Reading the real file makes that class of drift impossible.
+ *
+ * `../package.json` resolves from this module's own location, which is one
+ * directory below the package root both as `src/version.ts` under tsx and
+ * as `dist/version.js` when installed.
+ */
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+if (typeof pkg.version !== 'string' || pkg.version === '') {
+    throw new Error('package.json has no version field');
+}
+export const VERSION = pkg.version;
+/**
+ * Build identity for `version`, mirroring the Go sibling's reasoning: a
+ * results.tsv row is only as reproducible as the harness that produced it,
+ * and "which version measured this" is otherwise unanswerable from an
+ * installed copy. Go reports its toolchain and GOOS/GOARCH; the Node
+ * equivalents are the runtime version and platform/arch, which also decide
+ * whether two measurements are even comparable.
+ */
+export function formatVersion() {
+    return (`autor3search-typescript ${VERSION}\n` +
+        `running on ${process.version}, ${process.platform}/${process.arch}\n`);
+}
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC9C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAA0B,CAAA;AAE/D,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;IAC1D,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAA;AACtD,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAW,GAAG,CAAC,OAAO,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,CACL,2BAA2B,OAAO,IAAI;QACtC,cAAc,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,IAAI,CACvE,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autor3search-typescript",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Autonomous AI-driven performance optimization for any TypeScript repository.",
   "type": "module",
   "license": "MIT",