serverAppConfigs/scripts/axe-measurements.py

#!/usr/bin/env python3
"""Destroy measurement ledgers in the surviving pages.

Point of use (AGENTS.md → Documentation Policy): a rate/throughput figure for
anything not running and not being compared is destroyed, not filed. This pass
deletes

  1. any section whose heading is a bench/throughput/rate/ladder/verdict ledger,
  2. any table row or standalone bullet that REPORTS a rate (`123.4 t/s`,
     `tok/s`, `ms/token`, `TTFT`, acceptance %, `llama-bench`, a bench arm),

and it never touches a shape number (ctx, slots, MiB budgets, ports) or a bullet
under a *Laws* / *Wire contract* / *Rollback* heading, where the sentence is the
payload and the number is decoration. Dry run by default; `--apply` writes.

Usage: axe-measurements.py [--apply] [--verbose]
"""
import pathlib
import re
import sys

VAULT = pathlib.Path("serverAppConfigs-docs")
RATE = re.compile(
    r"\d[\d,.]*\s*(t/s|tok/s|tokens?/s|tok s|tps|ms/token|µs/token|GB/s|GiB/s)\b|"
    r"\b(llama-bench|bench (arm|ladder|window)|decode ladder|prefill ladder)\b|"
    r"\bacceptance (rate|of)\b|\bdraft_n\b|\bttft\b|\bServer-Timing\b",
    re.I,
)
# A heading is a ledger only when the noun LEDS it and nothing instructional
# follows: `## Throughput` yes, `## 6. The context ladder (find the max bootable
# window by measurement)` no — that one is the method, which is point-of-use.
LEDGER_HEAD = re.compile(
    r"^#{2,4}\s+(?:\d+[.) ]\s*)?(bench(es|mark|marks)?|throughput|results?|timings?|"
    r"measured (figures|numbers|results|rates|rates)|rates|verdict|acceptance|ladder)"
    r"\b[^|]{0,40}$",
    re.I,
)
INSTRUCTIONAL = re.compile(r"how|why|law|policy|method|procedure|find|by measurement|execution|flip|checklist", re.I)
PROTECTED = re.compile(
    r"^#{2,4}\s+.*(law|wire|rollback|contract|shape|eras|files|health|see also|related|"
    r"boot|preflight|environment)",
    re.I,
)
def blank_rate_cells(text):
    """Kill throughput COLUMNS wherever they appear: a cell that reports a rate
    becomes an em-dash, so the row keeps whatever else it records (the payload
    name, the reason, the rollback) and loses only the dead number."""
    out = []
    for line in text.split("\n"):
        st = line.strip()
        if st.startswith("|") and st.endswith("|") and RATE.search(line):
            cells = line.split("|")
            for i, c in enumerate(cells):
                if RATE.search(c):
                    cells[i] = " — "
            line = "|".join(cells)
        out.append(line)
    return "\n".join(out)


def collapse_eras(text):
    """One Eras row per era is fleet law; the NUMBERS in the old rows are not.
    Keep the current era verbatim, fold everything older into one row that says
    the numbers were destroyed and where the rollback actually lives (git)."""
    lines = text.split("\n")
    out = []
    in_eras = False
    ncol = 0
    folded = 0
    for line in lines:
        if line.startswith("#"):
            in_eras = bool(re.match(r"^#{2,4}\s+.*eras\b", line, re.I))
            if folded:
                out.append("| " + " | ".join(
                    [f"≤ 2026-09 — {folded} earlier eras: payloads, shapes and every measured "
                         "number destroyed 2026-10-19 as obsolete"] + ["—"] * max(0, ncol - 1)))
                folded = 0
            out.append(line)
            continue
        st = line.strip()
        if in_eras and st.startswith("|"):
            cells = [c.strip() for c in st.strip("|").split("|")]
            if set("".join(cells)) <= set(":- "):
                ncol = len(cells)
                out.append(line)
                continue
            if ncol == 0:
                ncol = len(cells)
            if re.search(r"2026-1[01]|current|active|running", st, re.I):
                out.append(line)
            else:
                folded += 1
            continue
        if folded and not st.startswith("|"):
            out.append("| " + " | ".join(
                [f"≤ 2026-09 — {folded} earlier eras: payloads, shapes and every measured number "
                     "destroyed 2026-10-19 as obsolete"] + ["—"] * max(0, ncol - 1)))
            folded = 0
            ncol = 0
        out.append(line)
    if folded:
        out.append("| " + " | ".join(
            [f"≤ 2026-09 — {folded} earlier eras destroyed 2026-10-19"] + ["—"] * max(0, ncol - 1)))
    return "\n".join(out)


def main(argv):
    apply = "--apply" in argv
    verbose = "--verbose" in argv
    total_lines = 0
    pages = 0
    for page in sorted(VAULT.rglob("*.md")):
        s = str(page)
        if ".AGENTTRASH" in s or ".obsidian" in s:
            continue
        text = page.read_text(errors="replace")
        before = len(text.split("\n"))
        if s.startswith("serverAppConfigs-docs/LLM/"):
            text = collapse_eras(blank_rate_cells(text))
        lines = text.split("\n")
        out = []
        skip = False
        under_protected = False
        cut = 0
        for line in lines:
            if line.startswith("#"):
                under_protected = bool(PROTECTED.search(line))
                skip = (bool(LEDGER_HEAD.match(line)) and not under_protected
                        and not INSTRUCTIONAL.search(line))
                if skip:
                    cut += 1
                    continue
            if skip:
                cut += 1
                continue
            stripped = line.strip()
            out.append(line)
            if under_protected:
                # Eras rows are the rollback record, Law bullets are the payload:
                # the number is decoration inside them, and the row/bullet is not
                # a ledger entry. Leave the whole section alone.
                continue
            if stripped.startswith(("|", "-", "*")) and RATE.search(line):
                # Destroy only when the line EXISTS to report a number: a table
                # row, or a bullet whose verb is measurement.
                if stripped.startswith("|") or re.search(
                        r"\b(measured|measures|bench|benched|ran at|runs at|clocked|hit|"
                        r"landed at|came in at|peak|peaks at|sustained|wall.clock)\b", line, re.I):
                    out.pop()
                    cut += 1
        final = re.sub(r"\n{3,}", "\n\n", "\n".join(out))
        saved = before - len(final.split("\n"))
        if saved or cut:
            pages += 1
            total_lines += max(saved, cut)
            print(f"  {s.replace('serverAppConfigs-docs/', '')}: -{max(saved, cut)}")
            if apply:
                page.write_text(final.rstrip("\n") + "\n")
    print(f"{'APPLIED' if apply else 'dry run'}: {pages} pages, {total_lines} lines of ledger")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))