canary-test-cli 7.0.0 → 7.2.0

package/dist/engine/history/cli.js

@@ -5,7 +5,7 @@
  *
  * Follows the guardian CLI conventions (see `../cli-common.ts`): a
  * {@link createHistoryCommand} factory wired to an injectable {@link HistoryDeps}
- * (out/err sinks, env, a store factory), `CliExit` for business exits, and
+ * (out/err sinks, env, a store factory), `CliExitError` for business exits, and
  * `normalizeUsageExit` on every command so usage errors exit 2.
  *
  * Python->TS fidelity notes:
@@ -20,14 +20,22 @@
  *     no Python CLI test pinning them, so this port emits a simple aligned text
  *     table carrying the SAME cell content. `summary`/`push`/`migrate` are NOT
  *     tables and are reproduced byte-for-byte via picocolors stripping.
+ *
+ * `record` is NOT a port. It has no Python counterpart: nothing in either engine
+ * ever wrote the local store, which is why the whole `analyze` / `history`
+ * surface had only ever been exercised against synthetic fixtures (#538). Its
+ * conversion half lives in `run-recorder.ts`; it takes the async store contract
+ * per ADR 0013, so it writes local NDJSON or the remote store by configuration.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { Command, Option } from 'commander';
 import pc from 'picocolors';
-import { CliExit, jsonIndent2, normalizeUsageExit } from '../cli-common.js';
+import { CliExitError, jsonIndent2, normalizeUsageExit, } from '../cli-common.js';
 import { gateOutcome } from '../core/gate-result.js';
 import { makeRunId } from './schema.js';
 import { makeStore as realMakeStore } from './store.js';
+import { buildRunFromVitestReport, countReportResults, detectReportShape, RecordValidationError, } from './run-recorder.js';
+import { def } from '../util/coalesce.js';
 import { pyFloat } from '../util/round.js';
 const EM_DASH = '\u{2014}';
 const GEQ = '\u{2265}';
@@ -126,7 +134,7 @@ function renderTable(title, headers, rows, rightAlign) {
 async function pushCmd(historyFile, opts, deps) {
     if (!existsSync(historyFile)) {
         deps.out(`${pc.red('Not found:')} ${historyFile}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     const store = deps.makeStore(opts.dbUrl, historyFile);
     const records = [];
@@ -137,7 +145,7 @@ async function pushCmd(historyFile, opts, deps) {
     }
     if (records.length === 0) {
         deps.out(pc.yellow('No runs found in history file.'));
-        throw new CliExit(0);
+        throw new CliExitError(0);
     }
     const latest = { ...records[records.length - 1] };
     const testsRaw = latest['tests'] ?? [];
@@ -146,11 +154,188 @@ async function pushCmd(historyFile, opts, deps) {
     const results = testsRaw.map((t) => pick(t, RESULT_FIELDS));
     if (opts.dryRun) {
         deps.out(`${pc.cyan('dry-run:')} would push run ${pc.bold(run.run_id)} (${results.length} tests)`);
-        throw new CliExit(0);
+        throw new CliExitError(0);
     }
     await store.pushRun(run, results);
     deps.out(`${pc.green('Pushed')} run ${pc.bold(run.run_id)} (${results.length} tests)`);
 }
+/** The `flaky: 0` caveat, printed rather than buried in a source comment. */
+const FLAKY_VOCABULARY_NOTE = 'note: flaky=0 \u{2014} vitest reports no flaky status, so a test that was ' +
+    'retried and then passed is recorded as passed.';
+/** Read + parse the results file, or exit 1 having said which and why. */
+function readReport(resultsFile, deps) {
+    if (!existsSync(resultsFile)) {
+        deps.out(`${pc.red('Not found:')} ${resultsFile}`);
+        throw new CliExitError(1);
+    }
+    try {
+        return JSON.parse(readFileSync(resultsFile, 'utf-8'));
+    }
+    catch (err) {
+        // Loud, not silent: an unreadable report means this run recorded NOTHING,
+        // and a later `analyze` would abstain without ever saying why.
+        deps.out(`${pc.red('Could not be read:')} ${resultsFile} ` +
+            `(${err.message}) \u{2014} nothing was recorded.`);
+        throw new CliExitError(1);
+    }
+}
+/** The repo slug, or exit 2 -- never a hardcoded default (see #538). */
+function resolveRepo(opts, deps) {
+    const repo = def(opts.repo, deps.env['GITHUB_REPOSITORY']);
+    if (repo)
+        return repo;
+    // A hardcoded default repo slug is how a tool ends up filing one team's runs
+    // under another team's name. Usage error (exit 2), not a guess.
+    deps.out(`${pc.red('Missing --repo:')} the repo slug could not be inferred ` +
+        `(no GITHUB_REPOSITORY in the environment). Pass ` +
+        `--repo <owner>/<name>.`);
+    throw new CliExitError(2);
+}
+/**
+ * Resolve the run-level facts a runner's report cannot carry.
+ *
+ * Fallbacks go through `def()` rather than `??` chains: as a call it is not a
+ * decision point, which keeps this mapper under the arch gate's per-function
+ * complexity threshold (the same reason the store's row mappers use it).
+ */
+function recordContext(opts, deps) {
+    const runId = opts.runId;
+    return {
+        suite: opts.suite,
+        repo: resolveRepo(opts, deps),
+        branch: def(opts.branch, def(deps.env['GITHUB_REF_NAME'], 'local')),
+        commitSha: def(opts.commit, def(deps.env['GITHUB_SHA'], 'local')),
+        // `exactOptionalPropertyTypes`: an absent --run-id omits the key rather
+        // than setting it to undefined.
+        ...(runId === undefined ? {} : { runId }),
+        nowMs: Date.now(),
+    };
+}
+/**
+ * `record` is a GATE (ADR 0009): a zero-result report exits 3, because the
+ * caller is a CI step whose next command reads the store, and "the suite
+ * reported nothing" must not look like "the suite passed". #538.
+ */
+async function recordCmd(resultsFile, opts, deps) {
+    const parsed = readReport(resultsFile, deps);
+    if (detectReportShape(parsed) !== 'vitest') {
+        deps.out(`${pc.red('Unrecognized report:')} ${resultsFile} carries no ` +
+            `\`testResults\` array, so it is not a vitest --reporter=json report. ` +
+            `\`record\` reads vitest JSON today; Playwright JSON and JUnit XML ` +
+            `are not supported yet.`);
+        throw new CliExitError(1);
+    }
+    // The denominator first: a report with no results is an abstention whatever
+    // else is missing, and refusing it over an unresolvable --repo would report
+    // the wrong finding.
+    if (countReportResults(parsed) === 0) {
+        abstainOnEmptyReport(resultsFile, opts, deps);
+        return;
+    }
+    const ctx = recordContext(opts, deps);
+    let built;
+    try {
+        built = buildRunFromVitestReport(parsed, ctx);
+    }
+    catch (err) {
+        if (!(err instanceof RecordValidationError))
+            throw err;
+        deps.out(`${pc.red('Invalid results:')} ${err.message}. Nothing was recorded ` +
+            `\u{2014} a malformed record degrades every later read of the store.`);
+        throw new CliExitError(1);
+    }
+    const remote = opts.dbUrl ?? deps.env['CANARY_HISTORY_DB_URL'];
+    const storePath = opts.path ?? DEFAULT_HISTORY_FILE;
+    const target = remote ? 'the configured remote store' : storePath;
+    if (opts.dryRun) {
+        reportDryRun(built, target, opts, deps);
+        return;
+    }
+    if (remote && opts.path) {
+        deps.err(`note: --path is ignored while a db-url is configured; the run goes to ` +
+            `the remote store.`);
+    }
+    const store = deps.makeStore(opts.dbUrl, storePath);
+    const before = store.countRuns ? await store.countRuns() : null;
+    await store.pushRun(built.run, built.results);
+    const after = store.countRuns ? await store.countRuns() : null;
+    // `pushRun` skips a duplicate run_id SILENTLY (it is idempotent by design).
+    // For a CLI that is the wrong default: the caller believes it recorded a run.
+    if (before !== null && after === before) {
+        deps.out(`${pc.yellow('Already recorded:')} run_id ` +
+            `${pc.bold(built.run.run_id)} is already present in ${target}; ` +
+            `nothing was appended. Two runs of one suite at one commit inside the ` +
+            `same second collide \u{2014} pass --run-id to record a distinct run.`);
+        throw new CliExitError(1);
+    }
+    if (before === null) {
+        // Cannot verify is a finding, not a silence (#508).
+        deps.err(`note: this backend cannot report how many runs it holds, so a ` +
+            `duplicate run_id could not be verified \u{2014} the store skips ` +
+            `duplicates silently.`);
+    }
+    reportRecorded(built, target, opts, deps);
+}
+function abstainOnEmptyReport(resultsFile, opts, deps) {
+    const outcome = gateOutcome({ checked: 0, findings: [] }, 'gate');
+    const notice = `${outcome.summaryLine} ${resultsFile} carried zero test results, so ` +
+        `nothing was recorded \u{2014} an empty run is the denominator ` +
+        `collapsing, not a passing suite. Check that the runner wrote its report ` +
+        `(\`vitest --reporter=json --outputFile=<path>\`) and that the suite ran.`;
+    if (opts.json) {
+        deps.out(jsonIndent2({
+            suite: opts.suite,
+            checked: 0,
+            recorded: false,
+            abstained: true,
+        }));
+        deps.err(notice);
+    }
+    else {
+        deps.out(notice);
+    }
+    throw new CliExitError(outcome.exitCode);
+}
+/** The success payload/line. Shared shape so `--json` cannot drift from it. */
+function recordPayload(built, target, extra) {
+    const { run } = built;
+    return {
+        run_id: run.run_id,
+        suite: run.suite,
+        repo: run.repo,
+        target,
+        checked: built.results.length,
+        passed: run.passed,
+        failed: run.failed,
+        flaky: run.flaky,
+        skipped: run.skipped,
+        abstained: false,
+        ...extra,
+    };
+}
+function countsLine(built) {
+    const { run } = built;
+    return (`${built.results.length} result(s) for ${pc.bold(run.suite)} ` +
+        `(${run.passed} passed, ${run.failed} failed, ${run.skipped} skipped)`);
+}
+function reportDryRun(built, target, opts, deps) {
+    if (opts.json) {
+        deps.out(jsonIndent2(recordPayload(built, target, { recorded: false, dry_run: true })));
+        return;
+    }
+    deps.out(`${pc.cyan('dry-run:')} would record ${countsLine(built)} as ` +
+        `${pc.bold(built.run.run_id)} \u{2192} ${target}`);
+    deps.out(FLAKY_VOCABULARY_NOTE);
+}
+function reportRecorded(built, target, opts, deps) {
+    if (opts.json) {
+        deps.out(jsonIndent2(recordPayload(built, target, { recorded: true })));
+        return;
+    }
+    deps.out(`${pc.green('Recorded')} ${countsLine(built)} \u{2192} ${target}`);
+    deps.out(`run_id: ${built.run.run_id}`);
+    deps.out(FLAKY_VOCABULARY_NOTE);
+}
 async function flakyCmd(opts, deps) {
     const store = deps.makeStore(opts.dbUrl);
     if (await abstainOnEmptyHistory(store, deps, opts.json === true, 'flake rate')) {
@@ -241,7 +426,7 @@ async function summaryCmd(suite, opts, deps) {
 async function migrateCmd(file, opts, deps) {
     if (!existsSync(file)) {
         deps.out(`${pc.red('Not found:')} ${file}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     const store = deps.makeStore(opts.dbUrl);
     let migrated = 0;
@@ -313,6 +498,25 @@ export function createHistoryCommand(depsInit = {}) {
         .action(async (historyFile, opts) => {
         await pushCmd(historyFile, opts, deps);
     });
+    program
+        .command('record')
+        .description('Record a finished test run into the history store (vitest JSON).')
+        .argument('<results_file>', "Path to the runner's JSON report.")
+        .requiredOption('--suite <suite>', 'Suite name for this run (e.g. e2e).')
+        .option('--repo <repo>', 'GitHub repo slug (default: $GITHUB_REPOSITORY).')
+        .option('--branch <branch>', 'Branch name (default: $GITHUB_REF_NAME).')
+        .option('--commit <sha>', 'Commit SHA (default: $GITHUB_SHA).')
+        // No commander default: an explicitly-passed --path has to stay
+        // distinguishable from the fallback, so a db-url + --path combination can
+        // say that --path is unused instead of silently dropping it.
+        .option('--path <store>', `Local NDJSON store to append to (default: ${DEFAULT_HISTORY_FILE}).`)
+        .option('--run-id <id>', 'Run id (default: <suite>-<commit[:8]>-<epoch seconds>).')
+        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
+        .option('--dry-run', 'Show what would be recorded without writing.')
+        .option('--json')
+        .action(async (resultsFile, opts) => {
+        await recordCmd(resultsFile, opts, deps);
+    });
     program
         .command('flaky')
         .description('Show tests ranked by flake rate over the rolling window.')

package/dist/engine/history/ndjson-store.js

@@ -7,14 +7,18 @@
  *
  * Deviation from the Python reader (deliberate): where Python's `_read_all`
  * swallows any parse error and returns `[]`, this reader throws on malformed
- * JSON and on an explicit unrecognized `schema_version`, so a corrupt or
- * future-version history fails loudly rather than silently analysing nothing.
+ * JSON and on an unrecognized `schema_version`, so a corrupt or future-version
+ * history fails loudly rather than silently analysing nothing.
+ *
+ * Version resolution lives in `resolveSchemaVersion` (#701): rows written by
+ * this store carry their version, and a legacy unstamped row is read as the
+ * version it was written at rather than as "current".
  */
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { def } from '../util/coalesce.js';
 import { round1 } from '../util/round.js';
-import { SCHEMA_VERSION } from './record.js';
+import { SCHEMA_VERSION, resolveSchemaVersion } from './record.js';
 import { serializeLocalRecord } from './schema.js';
 export class NdjsonHistoryStore {
     path;
@@ -38,8 +42,8 @@ export class NdjsonHistoryStore {
             if (!line)
                 continue;
             const record = JSON.parse(line);
-            const version = record.schema_version;
-            if (version !== undefined && version !== SCHEMA_VERSION) {
+            const version = resolveSchemaVersion(record);
+            if (version !== SCHEMA_VERSION) {
                 throw new Error(`Unsupported history schema_version ${version} (expected ${SCHEMA_VERSION})`);
             }
             records.push(record);

package/dist/engine/history/record.js

@@ -4,11 +4,40 @@
  * Mirrors `agent/history/schema.py` (RunRecord + TestResult) as persisted, one
  * JSON object per line, in `test-results/reports/history-v2.jsonl`.
  *
- * The on-disk records written by the Python engine do NOT carry a per-record
- * version field (the "v2" lives in the filename). The reader therefore treats a
- * missing `schema_version` as the current version, but throws on an explicit
- * unrecognized one — a forward-compat guard, exercised by the store tests.
+ * Every row the store writes now carries its own `schema_version` (#701) — the
+ * version guard can only refuse data it can identify, and before the stamp the
+ * store's own history was the one thing it could never check.
+ *
+ * A row with no version is a **legacy row**, written before that stamp landed.
+ * It is resolved to `LEGACY_UNVERSIONED_SCHEMA_VERSION`, not to "current" — see
+ * `resolveSchemaVersion` for why the difference is load-bearing.
  */
-/** The schema version this reader understands. */
+/** The schema version this reader understands, and every writer stamps. */
 export const SCHEMA_VERSION = 2;
+/**
+ * The version an unstamped row was actually written at.
+ *
+ * **A frozen literal, never an alias of `SCHEMA_VERSION`.** Unversioned rows
+ * can only be v2: v2 is the sole version this store has ever had (the earlier
+ * "v1" lived in a differently-named file), and from #701 onward every row is
+ * stamped. So the value is a historical fact, not a default.
+ *
+ * Aliasing it to `SCHEMA_VERSION` would recreate the #701 bug on the day the
+ * version bumps: legacy v2 rows would be read as v3 and silently
+ * misinterpreted, which is precisely the guard's purpose to prevent.
+ */
+export const LEGACY_UNVERSIONED_SCHEMA_VERSION = 2;
+/**
+ * The version a record should be read as.
+ *
+ * Deliberately conservative: an unversioned row resolves to the version it was
+ * written at, so the next `SCHEMA_VERSION` bump makes the reader **refuse**
+ * legacy rows loudly rather than reinterpret them under new semantics. That
+ * bump therefore has to ship a migration (rewrite the file with a stamp, or add
+ * an explicit upgrade path) — which is the point. Today the two constants are
+ * equal, so this changes nothing observable; it only decides what happens next.
+ */
+export function resolveSchemaVersion(record) {
+    return record.schema_version ?? LEGACY_UNVERSIONED_SCHEMA_VERSION;
+}
 //# sourceMappingURL=record.js.map

package/dist/engine/history/run-recorder.js

@@ -0,0 +1,165 @@
+/**
+ * Turn a test runner's own report into a v2 history run (#538).
+ *
+ * `canary analyze` and `canary history` have always READ
+ * `test-results/reports/history-v2.jsonl`; until this module nothing in the
+ * product wrote it, so every consumer who wanted a flake report had to author
+ * the NDJSON by hand. This is the conversion half of `canary history record`;
+ * the CLI half lives in `cli.ts` and the append itself belongs to the store
+ * (`AsyncHistoryStore.pushRun`, per ADR 0013).
+ *
+ * Two deliberate limits, both of them data-honesty calls rather than laziness:
+ *
+ *   - **vitest `--reporter=json` only.** The shape is detected rather than
+ *     declared by flag, and an unrecognized shape is refused loudly. The
+ *     alternative -- reading an unknown document and finding zero tests in it --
+ *     is indistinguishable from a suite that genuinely ran nothing, which is
+ *     exactly the denominator collapse #508 exists to make visible. Playwright
+ *     JSON and JUnit XML are parsed elsewhere in the repo (canary-test-reporter,
+ *     canary-savant) but by self-contained skill CLIs the engine cannot import.
+ *   - **`flaky` is always 0.** Canary's status vocabulary is
+ *     passed/failed/flaky/skipped; vitest has no flaky status, so a test that
+ *     was retried and then passed arrives as `passed` and is invisible here.
+ *     Recorded as zero and SAID OUT LOUD by the command, because a reader who
+ *     takes `flaky: 0` for a clean fleet has been misled by the tool.
+ */
+import { makeRunId, serializeLocalRecord, } from './schema.js';
+/** Canary's per-test status vocabulary (the store's read side keys on these). */
+const RECORD_STATUSES = ['passed', 'failed', 'flaky', 'skipped'];
+/**
+ * A report that cannot be recorded without corrupting the store.
+ *
+ * Thrown BEFORE any append: `NdjsonHistoryStore.pushRun` writes one line and
+ * every later report divides by it, so a malformed record is not a local
+ * failure -- it silently degrades every future read of the file.
+ */
+export class RecordValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RecordValidationError';
+    }
+}
+/** Detect by shape, not by flag -- callers should not have to know the format. */
+export function detectReportShape(parsed) {
+    if (parsed === null || typeof parsed !== 'object')
+        return 'unknown';
+    const testResults = parsed.testResults;
+    return Array.isArray(testResults) ? 'vitest' : 'unknown';
+}
+/**
+ * How many per-test results the report carries -- the DENOMINATOR, available
+ * before any run-level fact is resolved.
+ *
+ * Separate from the conversion so `record` can abstain on an empty report
+ * before it starts complaining about a missing `--repo`: there is nothing to
+ * record either way, and the abstention is the finding worth reporting.
+ */
+export function countReportResults(parsed) {
+    const report = parsed;
+    let n = 0;
+    for (const file of report.testResults ?? []) {
+        n += file.assertionResults?.length ?? 0;
+    }
+    return n;
+}
+/** vitest status -> canary status. Anything not pass/fail is a skip. */
+function toCanaryStatus(status) {
+    if (status === 'passed')
+        return 'passed';
+    if (status === 'failed')
+        return 'failed';
+    return 'skipped';
+}
+function toResultRow(assertion, file, ids) {
+    const first = assertion.failureMessages?.[0];
+    return {
+        run_id: ids.runId,
+        suite: ids.suite,
+        repo: ids.repo,
+        // No `(unnamed)` fallback: the test name is the join key every later query
+        // groups on, so inventing one would merge unrelated tests into a single
+        // history. A nameless row is a validation failure instead.
+        test_name: assertion.fullName ?? assertion.title ?? '',
+        test_file: file.name ?? '',
+        status: toCanaryStatus(assertion.status),
+        duration_ms: Math.round(assertion.duration ?? 0),
+        ...(first === undefined
+            ? {}
+            : { error_text: String(first).slice(0, 2000) }),
+    };
+}
+/** Convert a parsed vitest JSON report into a run + its per-test rows. */
+export function buildRunFromVitestReport(parsed, ctx) {
+    const report = parsed;
+    const startedMs = typeof report.startTime === 'number' ? report.startTime : ctx.nowMs;
+    const epochSeconds = Math.floor(startedMs / 1000);
+    const runId = ctx.runId ?? makeRunId(ctx.suite, ctx.commitSha, epochSeconds);
+    const results = [];
+    for (const file of report.testResults ?? []) {
+        for (const assertion of file.assertionResults ?? []) {
+            results.push(toResultRow(assertion, file, {
+                runId,
+                suite: ctx.suite,
+                repo: ctx.repo,
+            }));
+        }
+    }
+    const count = (status) => results.filter((r) => r.status === status).length;
+    const run = {
+        run_id: runId,
+        suite: ctx.suite,
+        repo: ctx.repo,
+        branch: ctx.branch,
+        commit_sha: ctx.commitSha,
+        // The store's own timestamps use `+00:00` rather than `Z` (Python
+        // `datetime.isoformat()`), and `queryTimeline` sorts these as strings.
+        timestamp: new Date(startedMs).toISOString().replace('Z', '+00:00'),
+        total: results.length,
+        passed: count('passed'),
+        failed: count('failed'),
+        // See the module docstring: vitest has no flaky status to read.
+        flaky: 0,
+        skipped: count('skipped'),
+        duration_ms: results.reduce((n, r) => n + (r.duration_ms ?? 0), 0),
+    };
+    const built = { run, results };
+    validateBuiltRun(built);
+    return built;
+}
+/**
+ * Reject a run that would poison later reads, using the store's own serializer.
+ *
+ * Checked against `serializeLocalRecord` rather than against the input objects,
+ * because that is the exact shape the file receives -- a field lost or nulled
+ * during serialization is caught here rather than by whoever queries it next
+ * month.
+ */
+export function validateBuiltRun(built) {
+    const record = serializeLocalRecord(built.run, built.results);
+    for (const key of ['run_id', 'suite', 'repo', 'branch', 'commit_sha']) {
+        if (!record[key]) {
+            throw new RecordValidationError(`run field '${key}' is empty`);
+        }
+    }
+    const allowed = new Set(RECORD_STATUSES);
+    const rows = record['tests'];
+    for (const [index, row] of rows.entries()) {
+        if (!row['test_name']) {
+            throw new RecordValidationError(`result ${index} has no test name; the store has no key to join it on`);
+        }
+        if (!allowed.has(String(row['status']))) {
+            throw new RecordValidationError(`result ${index} ('${String(row['test_name'])}') has status ` +
+                `'${String(row['status'])}', which is outside ` +
+                `${RECORD_STATUSES.join('|')}`);
+        }
+    }
+    const { total, passed, failed, flaky, skipped } = built.run;
+    if (total !== rows.length) {
+        throw new RecordValidationError(`run total ${total} disagrees with ${rows.length} recorded result(s)`);
+    }
+    if (passed + failed + flaky + skipped !== total) {
+        throw new RecordValidationError(`status counts (${passed}/${failed}/${flaky}/${skipped}) do not sum to ` +
+            `the total of ${total}`);
+    }
+}
+//# sourceMappingURL=run-recorder.js.map

package/dist/engine/history/schema.js

@@ -1,13 +1,17 @@
 /**
  * Write-side schema for run-history records.
  *
- * Faithful TS port of `agent/history/schema.py`. `record.ts` holds the *read*
- * shapes (loose, as parsed from disk); this module holds the *write* inputs
- * (the dataclass field sets) and the serializers that turn them into the exact
- * dict shapes Python's `asdict()` produces — so a record written by TS is read
- * identically by the Python `LocalHistoryStore` (the write-seam proof).
+ * Originally a faithful TS port of `agent/history/schema.py`. `record.ts` holds
+ * the *read* shapes (loose, as parsed from disk); this module holds the *write*
+ * inputs (the dataclass field sets) and the serializers that produce the on-disk
+ * and remote-table shapes.
+ *
+ * The field sets still match what Python's `asdict()` produced, with one
+ * deliberate addition since the Python engine was retired at v6.0.0: the local
+ * record carries `schema_version` (#701). See `serializeLocalRecord`.
  */
 import { def } from '../util/coalesce.js';
+import { SCHEMA_VERSION } from './record.js';
 /** `{suite}-{commit[:8]}-{epoch}` — identical to Python `make_run_id`. */
 export function makeRunId(suite, commitSha, timestampEpoch) {
     return `${suite}-${commitSha.slice(0, 8)}-${timestampEpoch}`;
@@ -51,9 +55,23 @@ export function serializeTestResult(t) {
 }
 /**
  * The nested NDJSON line shape written by the local store: a serialized run
- * with its `tests` embedded (matches Python `LocalHistoryStore.push_run`).
+ * with its `tests` embedded.
+ *
+ * `schema_version` is stamped **here**, in the one serializer every local
+ * writer goes through, rather than at each call site (#701). A writer that has
+ * to remember the field is a writer that eventually forgets it — and an
+ * unstamped row is invisible to the reader's version guard, so the guard could
+ * never fire on the store's own history. Stamping by construction is what makes
+ * "every row is self-describing" a property instead of a convention.
+ *
+ * Deliberately absent from `serializeRun`/`serializeTestResult`: those map to
+ * the remote store's table columns, which have no such field.
  */
 export function serializeLocalRecord(run, results) {
-    return { ...serializeRun(run), tests: results.map(serializeTestResult) };
+    return {
+        schema_version: SCHEMA_VERSION,
+        ...serializeRun(run),
+        tests: results.map(serializeTestResult),
+    };
 }
 //# sourceMappingURL=schema.js.map

package/dist/engine/history/store.js

@@ -33,6 +33,15 @@ export class LocalAsyncAdapter {
     async countRuns() {
         return this.inner.countRuns();
     }
+    /**
+     * Forward the local store's raw-record access (#711). This is the only
+     * implementation of the optional `readAll` capability, and the analysis
+     * engine's spikes / common-failures / regression-candidates sections are
+     * reachable through it alone — see `AsyncHistoryStore.readAll`.
+     */
+    async readAll() {
+        return this.inner.readAll();
+    }
     async querySummary(suite, runs) {
         return this.inner.querySummary(suite, runs);
     }