@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/_lib/bench_telegraph_report.ts

@@ -0,0 +1,272 @@
+// Telegraph bench report serializer — step-16 Phase 1 Step 5.
+//
+// Emits the telegraph-v1 JSON + Markdown shape. Distinct schema_version
+// ("telegraph-v1") from the selection-accuracy bench (v1) because the
+// blocks are disjoint: telegraph has no `selection`/`quality`, and the
+// selection bench has no three-arm condensation metrics.
+//
+// TypeScript twin of `src/scripts/_lib/bench_telegraph_report.py`
+// (ADR-200 py2ts Phase 2 / Wave 2a). Markdown rendering is byte-exact
+// with the Python original; the `_fmt_pct` / `:.0f` helpers replicate
+// Python's round-half-to-even formatting.
+import {
+    ARMS,
+    type PromptResult,
+    aggregate_results,
+    compute_cost,
+    type AggregateBlock,
+    type CostBlock,
+    type PricingDict,
+} from './bench_telegraph.js';
+
+export interface TelegraphReport {
+    schema_version: string;
+    generated_at: string;
+    corpus: { id: string; path: string; prompt_count: number };
+    runner: { bench_run_version: string; transport: string; model: string };
+    telegraph: {
+        arms: string[];
+        aggregate: AggregateBlock;
+        per_prompt: PromptBlock[];
+    };
+    cost: CostBlock & {
+        source: string;
+        model: string;
+        pricing_sourced_on: string | null;
+    };
+    verdict: { overall: string; errors: number };
+}
+
+export interface PromptBlock {
+    id: string;
+    category: string;
+    expected_carve_out_pct: number;
+    realised_carve_out_pct: number | null;
+    savings_vs_raw: number | null;
+    savings_vs_terse: number | null;
+    arms: Record<
+        string,
+        {
+            input_tokens: number;
+            output_tokens: number;
+            latency_ms: number;
+            output_chars: number;
+            carve_out_chars: number;
+            error: string | null;
+            text: string;
+        }
+    >;
+}
+
+export function build_telegraph_report(params: {
+    results: PromptResult[];
+    corpus_path_rel: string;
+    generated_at: string;
+    bench_run_version: string;
+    model: string;
+    transport: string;
+    pricing_rates: PricingDict;
+    pricing_sourced_on: string | null;
+}): TelegraphReport {
+    const aggregate = aggregate_results(params.results);
+    const cost = compute_cost(params.results, params.pricing_rates) as CostBlock & {
+        source: string;
+        model: string;
+        pricing_sourced_on: string | null;
+    };
+    cost.source = 'live-api';
+    cost.model = params.model;
+    cost.pricing_sourced_on = params.pricing_sourced_on;
+    const errors = cost.totals.errors;
+    return {
+        schema_version: 'telegraph-v1',
+        generated_at: params.generated_at,
+        corpus: {
+            id: 'telegraph',
+            path: params.corpus_path_rel,
+            prompt_count: params.results.length,
+        },
+        runner: {
+            bench_run_version: params.bench_run_version,
+            transport: params.transport,
+            model: params.model,
+        },
+        telegraph: {
+            arms: [...ARMS],
+            aggregate,
+            per_prompt: params.results.map((r) => _prompt_block(r)),
+        },
+        cost,
+        verdict: {
+            overall: errors === 0 ? 'measured' : 'partial',
+            errors,
+        },
+    };
+}
+
+function _prompt_block(r: PromptResult): PromptBlock {
+    const c = r.arms['condensed'];
+    const arms: PromptBlock['arms'] = {};
+    for (const arm of Object.keys(r.arms)) {
+        const ar = r.arms[arm];
+        if (!ar) {
+            continue;
+        }
+        arms[arm] = {
+            input_tokens: ar.input_tokens,
+            output_tokens: ar.output_tokens,
+            latency_ms: ar.latency_ms,
+            output_chars: ar.output_chars,
+            carve_out_chars: ar.carve_out_chars,
+            error: ar.error,
+            text: ar.text,
+        };
+    }
+    return {
+        id: r.id,
+        category: r.category,
+        expected_carve_out_pct: r.expected_carve_out_pct,
+        realised_carve_out_pct: c ? c.realised_carve_out_pct : null,
+        savings_vs_raw: r.savings_vs_raw,
+        savings_vs_terse: r.savings_vs_terse,
+        arms,
+    };
+}
+
+// ── Python-format parity helpers ─────────────────────────────────────────
+//
+// Python's f"{x:.2%}" and f"{m:.0f}" both round half-to-even (banker's
+// rounding) on the decimal representation. JS `toFixed` rounds half away
+// from zero, so we reimplement the formatting to stay byte-exact with the
+// Python original.
+
+/** Replicate Python `format(x, f".{ndigits}%")` — value × 100, banker-rounded, '%' suffix. */
+function _py_format_pct(x: number, ndigits: number): string {
+    return `${_pyFixed(x * 100, ndigits)}%`;
+}
+
+/** Replicate Python `format(x, f".{ndigits}f")`. */
+function _py_format_fixed(x: number, ndigits: number): string {
+    return _pyFixed(x, ndigits);
+}
+
+/**
+ * Format `x` to `ndigits` decimals using round-half-to-even, matching
+ * CPython's float formatting. Uses a high-precision intermediate to find
+ * the exact halfway case the way CPython's dtoa does.
+ */
+function _pyFixed(x: number, ndigits: number): string {
+    if (!Number.isFinite(x)) {
+        return String(x);
+    }
+    const neg = x < 0 || Object.is(x, -0);
+    const abs = Math.abs(x);
+    const factor = Math.pow(10, ndigits);
+    const scaled = abs * factor;
+    let rounded = Math.round(scaled);
+    // Detect a halfway case robustly. Compare the scaled value against the
+    // midpoint using the float's full precision; on a tie, round to even.
+    const floor = Math.floor(scaled);
+    const frac = scaled - floor;
+    // Use a tolerance derived from the magnitude to absorb float noise.
+    const tol = Math.max(Math.abs(scaled), 1) * 2 ** -40;
+    if (Math.abs(frac - 0.5) <= tol) {
+        rounded = floor % 2 === 0 ? floor : floor + 1;
+    } else {
+        rounded = Math.round(scaled);
+    }
+    let intStr = String(rounded);
+    let result: string;
+    if (ndigits === 0) {
+        result = intStr;
+    } else {
+        if (intStr.length <= ndigits) {
+            intStr = '0'.repeat(ndigits - intStr.length + 1) + intStr;
+        }
+        const whole = intStr.slice(0, intStr.length - ndigits);
+        const dec = intStr.slice(intStr.length - ndigits);
+        result = `${whole}.${dec}`;
+    }
+    // CPython preserves the sign from the INPUT, not the rounded result:
+    // f"{-0.0:.0f}" -> "-0", f"{-0.00001:.2%}" -> "-0.00%". Keep the leading
+    // minus whenever the input is negative (including -0.0).
+    return neg ? `-${result}` : result;
+}
+
+// Mirror of Python's _fmt_pct: f"{x:.2%}" for numbers, "—" otherwise.
+function _fmt_pct(x: number | null | undefined): string {
+    return typeof x === 'number' ? _py_format_pct(x, 2) : '—';
+}
+
+export function render_telegraph_markdown(report: TelegraphReport): string {
+    const cv = report.telegraph;
+    const agg = cv.aggregate;
+    const cost = report.cost;
+    const head: string[] = [
+        `# Telegraph Bench Report — \`telegraph\` · ${report.generated_at}`,
+        '',
+        '## Headline',
+        '',
+        `- prompts: **${report.corpus.prompt_count}** · ` +
+            `arms: **${cv.arms.join(', ')}** · ` +
+            `model: **${report.runner.model}** · ` +
+            `transport: **${report.runner.transport}**`,
+        `- median savings vs raw: **${_fmt_pct(agg.savings_vs_raw.median)}** ` +
+            `(p10 ${_fmt_pct(agg.savings_vs_raw.p10)} · p90 ${_fmt_pct(agg.savings_vs_raw.p90)})`,
+        `- median savings vs terse-control: **${_fmt_pct(agg.savings_vs_terse.median)}** ` +
+            `(p10 ${_fmt_pct(agg.savings_vs_terse.p10)} · p90 ${_fmt_pct(agg.savings_vs_terse.p90)})`,
+        `- median realised carve-out share (condensed arm): **${_fmt_pct(agg.realised_carve_out_pct.median)}** ` +
+            `(expected median ${_fmt_pct(agg.expected_carve_out_pct.median)})`,
+        `- calls: **${cost.totals.calls}** · errors: **${cost.totals.errors}**`,
+        `- verdict: **${report.verdict.overall}**`,
+        '',
+    ];
+    const per_arm: string[] = [
+        '## Per-arm token totals',
+        '',
+        '| arm | calls | input_tokens | output_tokens | median out/prompt |',
+        '|---|---:|---:|---:|---:|',
+    ];
+    for (const arm of cv.arms) {
+        const a = cost.per_arm[arm] as { input_tokens: number; output_tokens: number; calls: number };
+        const m = (agg.output_tokens[arm] as { median: number }).median;
+        per_arm.push(
+            `| \`${arm}\` | ${a.calls} | ${a.input_tokens} | ${a.output_tokens} | ${_py_format_fixed(m, 0)} |`,
+        );
+    }
+    per_arm.push('');
+    const per_prompt: string[] = [
+        '## Per-prompt results',
+        '',
+        '| id | category | exp.carve | real.carve | out.condensed | out.terse | out.uncondensed | vs raw | vs terse |',
+        '|---|---|---:|---:|---:|---:|---:|---:|---:|',
+    ];
+    for (const r of cv.per_prompt) {
+        const arms = r.arms;
+        const oc = _outTok(arms['condensed']);
+        const ot = _outTok(arms['terse_control']);
+        const ou = _outTok(arms['uncondensed']);
+        per_prompt.push(
+            `| \`${r.id}\` | ${r.category} | ` +
+                `${_fmt_pct(r.expected_carve_out_pct)} | ${_fmt_pct(r.realised_carve_out_pct)} | ` +
+                `${oc} | ${ot} | ${ou} | ` +
+                `${_fmt_pct(r.savings_vs_raw)} | ${_fmt_pct(r.savings_vs_terse)} |`,
+        );
+    }
+    per_prompt.push('');
+    const notes: string[] = [
+        '## Notes',
+        '',
+        `- corpus: \`${report.corpus.path}\``,
+        `- pricing: \`internal/bench/pricing.yaml\` (sourced ${cost.pricing_sourced_on || '—'})`,
+        `- schema: \`telegraph-v1\` (see \`docs/contracts/benchmark-report-schema.md\`)`,
+        `- bench_run version: \`${report.runner.bench_run_version}\``,
+        '',
+    ];
+    return [...head, ...per_arm, ...per_prompt, ...notes].join('\n');
+}
+
+// Python: arms.get("condensed", {}).get("output_tokens", "—")
+function _outTok(slot: { output_tokens: number } | undefined): string {
+    return slot ? String(slot.output_tokens) : '—';
+}

package/src/scripts/_lib/changelog_eras.ts

@@ -0,0 +1,398 @@
+/**
+ * Shared constants + helpers for CHANGELOG.md era discipline.
+ *
+ * TypeScript twin of `src/scripts/_lib/changelog_eras.py` (ADR-200
+ * py2ts Phase 2 / Wave 1). The drift gate (`tests/test_changelog_eras.py`
+ * / `tests/lib/changelog_eras.test.ts`) and the release automation
+ * (`scripts/release.py`) both reason about the same era shape: a single
+ * `# Era: X.Y.x — current` header followed by inline entries, then
+ * `# Era: pre-X.Y.0 — archived` pointers to files under `docs/archive/`.
+ * Keeping the regex / cap / path constants in one place prevents drift
+ * between the gate and the auto-split logic.
+ *
+ * Normative source: `docs/contracts/CHANGELOG-conventions.md § Era splits`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// src/scripts/_lib/ -> repo root (mirrors Path(__file__).parent x4 in Python).
+export const REPO_ROOT = path.resolve(_HERE, '..', '..', '..');
+export let CHANGELOG = path.join(REPO_ROOT, 'CHANGELOG.md');
+export const CONVENTIONS = path.join(REPO_ROOT, 'docs', 'contracts', 'CHANGELOG-conventions.md');
+export let ARCHIVE_DIR = path.join(REPO_ROOT, 'docs', 'archive');
+
+/**
+ * Test seam — the pytest twin reassigns the module attributes
+ * (`eras.CHANGELOG = …`); ESM export bindings are read-only from the
+ * importing side, so the vitest twin uses these setters instead.
+ * Additive API only; production code never calls them.
+ */
+export function _set_changelog_path(p: string): void {
+    CHANGELOG = p;
+}
+
+export function _set_archive_dir(p: string): void {
+    ARCHIVE_DIR = p;
+}
+
+// Drift cap — entries between the current era header and the next era
+// header may not exceed this many lines. Raising the cap is a contract
+// change (see CHANGELOG-conventions.md § Era splits).
+export const CURRENT_ERA_BODY_CAP = 250;
+
+export const ERA_HEADER_RE = /^# Era: (?<label>[^\n]+?)(?: — (?<state>current|archived))?\s*$/;
+// Global flag so `matchAll` works (the Python twin uses `findall`);
+// `String.prototype.matchAll` clones the regex, so the shared constant
+// keeps no `lastIndex` state across calls.
+export const ARCHIVE_LINK_RE = /\(docs\/archive\/(CHANGELOG-pre-[^)\s]+\.md)\)/g;
+export const VERSION_HEADING_RE = /^## \[?(?<version>\d+\.\d+\.\d+)/;
+export const ERA_LABEL_RE = /^(?<major>\d+)\.(?<minor>\d+)\.x$/;
+
+/** One era header in CHANGELOG.md, with its line index. */
+export interface EraSpan {
+    readonly line_index: number;
+    readonly label: string;
+    readonly state: string; // "current" | "archived" | ""
+}
+
+/** Mirror of Python `str.splitlines()` for the newline shapes a changelog can contain. */
+function _splitlines(text: string): string[] {
+    if (text === '') {
+        return [];
+    }
+    const parts = text.split(/\r\n|\r|\n/);
+    // str.splitlines() does not emit a trailing empty element for a
+    // final newline; String.split does — drop it.
+    if (parts.length > 0 && parts[parts.length - 1] === '') {
+        parts.pop();
+    }
+    return parts;
+}
+
+/** Return CHANGELOG.md split into lines (no trailing newlines). */
+export function read_changelog_lines(): string[] {
+    return _splitlines(fs.readFileSync(CHANGELOG, 'utf-8'));
+}
+
+/** Return every era header in line-order. */
+export function era_spans(lines: readonly string[]): EraSpan[] {
+    const spans: EraSpan[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = ERA_HEADER_RE.exec(lines[i]!);
+        if (m) {
+            spans.push({
+                line_index: i,
+                label: m.groups!['label']!,
+                state: m.groups!['state'] ?? '',
+            });
+        }
+    }
+    return spans;
+}
+
+/** Return the line index of the `— current` era header, or null. */
+export function current_era_index(spans: readonly EraSpan[]): number | null {
+    for (const span of spans) {
+        if (span.state === 'current') {
+            return span.line_index;
+        }
+    }
+    return null;
+}
+
+/**
+ * Return the number of lines between the current era header and
+ * the next era header (exclusive of both).
+ */
+export function current_era_body_size(lines: readonly string[] | null = null): number {
+    if (lines === null) {
+        lines = read_changelog_lines();
+    }
+    const spans = era_spans(lines);
+    const current_idx = current_era_index(spans);
+    if (current_idx === null) {
+        return 0;
+    }
+    let next_era_line = lines.length;
+    for (const span of spans) {
+        if (span.line_index > current_idx) {
+            next_era_line = span.line_index;
+            break;
+        }
+    }
+    return next_era_line - current_idx - 1;
+}
+
+/** Parse `M.N.x` into `[M, N]`; return null for archived labels. */
+export function parse_era_label(label: string): [number, number] | null {
+    const m = ERA_LABEL_RE.exec(label.trim());
+    if (!m) {
+        return null;
+    }
+    return [Number.parseInt(m.groups!['major']!, 10), Number.parseInt(m.groups!['minor']!, 10)];
+}
+
+/** Return `docs/archive/CHANGELOG-pre-<boundary>.md`. */
+export function archive_path_for_boundary(boundary: string): string {
+    return path.join(ARCHIVE_DIR, `CHANGELOG-pre-${boundary}.md`);
+}
+
+/**
+ * Render the standard `# Era: pre-<boundary> — archived` pointer
+ * block that replaces archived entries in CHANGELOG.md.
+ *
+ * Mirrors the wording the manual splits already used (verified against
+ * every existing collapsed era as of 3.2.x).
+ */
+export function collapsed_era_block(boundary: string): string {
+    const archive_rel = `docs/archive/CHANGELOG-pre-${boundary}.md`;
+    return (
+        `# Era: pre-${boundary} — archived\n` +
+        '\n' +
+        `> All entries before \`${boundary}\` live in\n` +
+        `> [\`${archive_rel}\`](${archive_rel}).\n` +
+        '> The archive is read-only; git tags remain the canonical\n' +
+        '> source for what shipped. Splitting them out of the main file\n' +
+        '> keeps the active era under the 250-line drift cap enforced by\n' +
+        '> `tests/test_changelog_eras.py`.\n'
+    );
+}
+
+/** Return the standard prologue for `docs/archive/CHANGELOG-pre-<boundary>.md`. */
+export function archive_file_header(boundary: string): string {
+    return (
+        `# Changelog Archive — pre-${boundary}\n` +
+        '\n' +
+        '> Frozen snapshot of `event4u/agent-config` changelog entries\n' +
+        `> released before \`${boundary}\`, split out of the main\n` +
+        '> [`CHANGELOG.md`](../../CHANGELOG.md) by `scripts/release.py`\n' +
+        "> once the active era's body crossed the drift cap enforced by\n" +
+        '> `tests/test_changelog_eras.py`.\n' +
+        '>\n' +
+        '> **Read-only.** New entries land in `CHANGELOG.md`. Entries\n' +
+        '> here are not amended — git tags remain the canonical source\n' +
+        '> for what shipped.\n' +
+        '>\n' +
+        '> Entry shape follows\n' +
+        '> [`../contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md).\n' +
+        '\n'
+    );
+}
+
+// ─── split planning + execution ────────────────────────────────────────────────
+
+const _RELEASE_VERSION_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/** Recipe for an era split during release of `release_version`. */
+export class SplitPlan {
+    constructor(
+        public readonly release_version: string, // e.g. "3.3.0"
+        public readonly boundary: string, // e.g. "3.3.0" — used in archive filename + pointer
+        public readonly new_era_label: string, // e.g. "3.3.x"
+        public readonly old_era_label: string, // e.g. "3.2.x"
+        public readonly archive_path: string,
+    ) {}
+
+    get commit_subject(): string {
+        return `chore(changelog): split era ${this.old_era_label} → pre-${this.boundary}`;
+    }
+}
+
+/**
+ * Plan an era split when releasing `release_version`.
+ *
+ * Returns null when no split is needed (release is a patch within the
+ * current era, or no current era header exists). Returns a SplitPlan
+ * when the release crosses a minor or major boundary; the caller
+ * decides whether to invoke `perform_split` based on era body size.
+ *
+ * Throws Error when `release_version` is not bare semver, or when it
+ * would move backward relative to the current era label.
+ */
+export function plan_split(release_version: string): SplitPlan | null {
+    const m = _RELEASE_VERSION_RE.exec(release_version.trim());
+    if (!m) {
+        throw new Error(`not a bare semver (X.Y.Z): '${release_version}'`);
+    }
+    const rel_major = Number.parseInt(m[1]!, 10);
+    const rel_minor = Number.parseInt(m[2]!, 10);
+
+    const lines = read_changelog_lines();
+    const spans = era_spans(lines);
+    const current = spans.find((s) => s.state === 'current') ?? null;
+    if (current === null) {
+        return null;
+    }
+
+    const parsed = parse_era_label(current.label);
+    if (parsed === null) {
+        return null;
+    }
+    const [era_major, era_minor] = parsed;
+
+    const releaseIsOlder = rel_major < era_major || (rel_major === era_major && rel_minor < era_minor);
+    if (releaseIsOlder) {
+        throw new Error(
+            `release '${release_version}' is older than current era ` +
+                `'${current.label}'; refusing to plan a backwards split`,
+        );
+    }
+    if (rel_major === era_major && rel_minor === era_minor) {
+        // Patch release within the current era — no era boundary crossed,
+        // so an auto-split would create a nonsensical archive name. The
+        // caller is expected to die() with the manual-intervention message.
+        return null;
+    }
+
+    const boundary = `${rel_major}.${rel_minor}.0`;
+    return new SplitPlan(
+        release_version,
+        boundary,
+        `${rel_major}.${rel_minor}.x`,
+        current.label,
+        archive_path_for_boundary(boundary),
+    );
+}
+
+/** Render the header + blockquote intro for a freshly-split current era. */
+export function new_era_intro_block(new_era_label: string, boundary: string): string {
+    const parsed = parse_era_label(new_era_label);
+    let next_example: string;
+    if (parsed === null) {
+        next_example = '# Era: <next>.x';
+    } else {
+        const [m, n] = parsed;
+        next_example = `# Era: ${m}.${n + 1}.x`;
+    }
+    return (
+        `# Era: ${new_era_label} — current\n` +
+        '\n' +
+        `> Started at \`${boundary}\`. Full entries live inline below.\n` +
+        '> The drift test caps this era at 250 lines of entry body; growth past\n' +
+        `> that forces a new era split (\`${next_example}\`, etc.) — see\n` +
+        '> [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).\n'
+    );
+}
+
+/**
+ * Return `[body_start, body_end, next_era_line]` for the era at
+ * `current_idx`.
+ *
+ * - `body_start` — first line after the header + leading blockquote
+ *   intro + the blank line that follows.
+ * - `body_end` — exclusive; one line before the next era marker (or
+ *   end of file). Trailing blank lines are NOT trimmed; the caller
+ *   reattaches them on splice.
+ * - `next_era_line` — index of the next `# Era:` line, or
+ *   `lines.length` when none follows.
+ */
+function _era_body_bounds(lines: readonly string[], current_idx: number): [number, number, number] {
+    let next_era_line = lines.length;
+    for (let i = current_idx + 1; i < lines.length; i++) {
+        if (ERA_HEADER_RE.test(lines[i]!)) {
+            next_era_line = i;
+            break;
+        }
+    }
+
+    let cursor = current_idx + 1;
+    // Skip leading blank lines between header and blockquote intro.
+    while (cursor < next_era_line && lines[cursor]!.trim() === '') {
+        cursor += 1;
+    }
+    // Skip the leading blockquote intro (consecutive `>`-prefixed lines).
+    while (cursor < next_era_line && lines[cursor]!.startsWith('>')) {
+        cursor += 1;
+    }
+    // Skip the blank separator between intro and entries.
+    while (cursor < next_era_line && lines[cursor]!.trim() === '') {
+        cursor += 1;
+    }
+
+    return [cursor, next_era_line, next_era_line];
+}
+
+/**
+ * Return the line index at which a new release entry should be
+ * prepended within the current era.
+ *
+ * Strategy:
+ * - If the current era body contains one or more `## [X.Y.Z]`
+ *   headings, return the line of the topmost (newest) one.
+ * - Otherwise, return the first line after the era intro blockquote.
+ *
+ * Returns null when no current era header exists.
+ */
+export function current_era_insertion_point(lines: readonly string[]): number | null {
+    const spans = era_spans(lines);
+    const current_idx = current_era_index(spans);
+    if (current_idx === null) {
+        return null;
+    }
+    const [body_start, body_end] = _era_body_bounds(lines, current_idx);
+    for (let i = body_start; i < body_end; i++) {
+        if (VERSION_HEADING_RE.test(lines[i]!)) {
+            return i;
+        }
+    }
+    return body_start;
+}
+
+/** Mirror of Python `str.rstrip("\n")`. */
+function _rstrip_newlines(text: string): string {
+    return text.replace(/\n+$/u, '');
+}
+
+/** Mirror of Python `str.rstrip()` (trailing whitespace). */
+function _rstrip(text: string): string {
+    return text.replace(/\s+$/u, '');
+}
+
+/**
+ * Execute `plan` against the on-disk CHANGELOG.md.
+ *
+ * - Refuses to overwrite an existing archive file.
+ * - Moves every entry in the current era body into the new archive.
+ * - Replaces the current era block with the collapsed pointer + the
+ *   freshly-labelled new current era header (empty body).
+ */
+export function perform_split(plan: SplitPlan): void {
+    if (fs.existsSync(plan.archive_path)) {
+        throw new Error(
+            `archive already exists at ${plan.archive_path} — ` +
+                'likely a previous --resume run; inspect manually',
+        );
+    }
+
+    const lines = read_changelog_lines();
+    const spans = era_spans(lines);
+    const current_idx = current_era_index(spans);
+    if (current_idx === null) {
+        throw new Error('no current era header found in CHANGELOG.md');
+    }
+
+    const [body_start, , next_era_line] = _era_body_bounds(lines, current_idx);
+    const entries = lines.slice(body_start, next_era_line);
+    // Trim trailing blank lines so the archive doesn't accumulate them.
+    while (entries.length > 0 && entries[entries.length - 1]!.trim() === '') {
+        entries.pop();
+    }
+
+    const collapsed = _splitlines(_rstrip_newlines(collapsed_era_block(plan.boundary)));
+    const new_era = _splitlines(_rstrip_newlines(new_era_intro_block(plan.new_era_label, plan.boundary)));
+
+    const head = lines.slice(0, current_idx);
+    const tail = lines.slice(next_era_line);
+    const new_lines = [...head, ...collapsed, '', ...new_era, '', ...tail];
+    const new_text = _rstrip(new_lines.join('\n')) + '\n';
+
+    const archive_body = entries.length > 0 ? _rstrip(entries.join('\n')) + '\n' : '';
+    const archive_text = archive_file_header(plan.boundary) + archive_body;
+
+    fs.mkdirSync(path.dirname(plan.archive_path), { recursive: true });
+    fs.writeFileSync(plan.archive_path, archive_text, 'utf-8');
+    fs.writeFileSync(CHANGELOG, new_text, 'utf-8');
+}