@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/_lib/paired_stats.ts

@@ -0,0 +1,245 @@
+/**
+ * Paired binary statistics — the exact test and its effect size.
+ *
+ * Extracted from `bench_ab_v2_stats.ts` and re-exported there, so every existing
+ * importer is unchanged. The move is not cosmetic: that file sits above the
+ * 1500-line ceiling `check_source_size_budget` charges, so lines added to it are
+ * paid back by extraction rather than by raising a baseline.
+ *
+ * `mcnemar_exact` is the shape `_lib/paired_verdict.ts` generalises — a binomial
+ * over DISCORDANT pairs only, which is the whole point: a concordant pair
+ * carries no information about direction and must not dilute the count. This one
+ * is two-sided (its callers ask whether the arms differ); `paired_verdict`'s is
+ * one-sided (it asks whether the treatment is better). They are kept apart for
+ * that reason rather than merged into a flag.
+ */
+
+/** Exact binomial coefficient via BigInt, so a large n cannot drift. */
+function comb(n: number, k: number): number {
+    if (k < 0 || k > n) return 0;
+    let num = 1n;
+    let den = 1n;
+    const kk = BigInt(Math.min(k, n - k));
+    for (let i = 0n; i < kk; i += 1n) {
+        num *= BigInt(n) - i;
+        den *= i + 1n;
+    }
+    return Number(num / den);
+}
+
+export function mcnemar_exact(b: number, c: number): number {
+    // Two-sided exact McNemar p-value (binomial on discordant pairs).
+    const n = b + c;
+    if (n === 0) {
+        return 1.0;
+    }
+    const k = Math.min(b, c);
+    let tail = 0;
+    for (let i = 0; i <= k; i += 1) {
+        tail += comb(n, i);
+    }
+    tail = tail * 0.5 ** n;
+    return Math.min(1.0, 2.0 * tail);
+}
+
+export function cohens_h(p1: number, p2: number): number {
+    return (
+        2 * Math.asin(Math.sqrt(Math.max(0, Math.min(1, p1)))) -
+        2 * Math.asin(Math.sqrt(Math.max(0, Math.min(1, p2))))
+    );
+}
+
+/** Python `round(x)` (no ndigits) → int, round-half-to-even. */
+export function _pyRoundNoArg(x: number): number {
+    if (!Number.isFinite(x)) return x;
+    const floor = Math.floor(x);
+    const frac = x - floor;
+    if (frac < 0.5) return floor;
+    if (frac > 0.5) return floor + 1;
+    return floor % 2 === 0 ? floor : floor + 1;
+}
+
+/** Python `round(x, ndigits)` — round-half-to-even on the exact double. */
+export function _pyRound(value: number, ndigits: number): number {
+    if (!Number.isFinite(value) || value === 0) {
+        return value;
+    }
+    const neg = value < 0;
+    const abs = Math.abs(value);
+    const exact = abs.toFixed(40);
+    const dot = exact.indexOf('.');
+    const intPart = dot === -1 ? exact : exact.slice(0, dot);
+    const fracPart = dot === -1 ? '' : exact.slice(dot + 1);
+    const keepFrac = fracPart.slice(0, ndigits).padEnd(ndigits, '0');
+    const rest = fracPart.slice(ndigits);
+    const scaledStr = (intPart + keepFrac).replace(/^0+(?=\d)/, '');
+    let scaled = BigInt(scaledStr === '' ? '0' : scaledStr);
+    if (rest.length > 0) {
+        const firstRest = rest.charCodeAt(0) - 48;
+        const hasMore = /[1-9]/.test(rest.slice(1));
+        if (firstRest > 5 || (firstRest === 5 && hasMore)) {
+            scaled += 1n;
+        } else if (firstRest === 5 && !hasMore) {
+            if (scaled % 2n === 1n) {
+                scaled += 1n;
+            }
+        }
+    }
+    const factor = 10 ** ndigits;
+    const result = Number(scaled) / factor;
+    return neg ? -result : result;
+}
+
+// CPython's `m_erf` (Modules/mathmodule.c): a Maclaurin series for |x| < 1.5
+// and 1 - erfc for larger |x|; `m_erfc` uses a continued-fraction expansion.
+// Ported verbatim so `_phi(z)` matches python3 to full double precision.
+
+const _ERF_SERIES_CUTOFF = 1.5;
+const _ERF_SERIES_TERMS = 25;
+const _ERFC_CONTFRAC_CUTOFF = 30.0;
+const _ERFC_CONTFRAC_TERMS = 50;
+const _SQRTPI = 1.772453850905516027298167483341145182798;
+
+function _m_erf_series(x: number): number {
+    // erf(x) = 2/sqrt(pi) * x * sum_{k>=0} (-x^2)^k / (k! (2k+1))
+    let x2 = x * x;
+    let acc = 0.0;
+    let fk = _ERF_SERIES_TERMS + 0.5;
+    for (let i = 0; i < _ERF_SERIES_TERMS; i += 1) {
+        acc = 2.0 + (x2 * acc) / fk;
+        fk -= 1.0;
+    }
+    return (acc * x * Math.exp(-x2)) / _SQRTPI;
+}
+
+function _m_erfc_contfrac(x: number): number {
+    if (x >= _ERFC_CONTFRAC_CUTOFF) {
+        return 0.0;
+    }
+    const x2 = x * x;
+    let a = 0.0;
+    let da = 0.5;
+    let p = 1.0;
+    let p_last = 0.0;
+    let q = da + x2;
+    let q_last = 1.0;
+    for (let i = 0; i < _ERFC_CONTFRAC_TERMS; i += 1) {
+        a += da;
+        da += 2.0;
+        const b = da + x2;
+        const temp_p = b * p - a * p_last;
+        p_last = p;
+        p = temp_p;
+        const temp_q = b * q - a * q_last;
+        q_last = q;
+        q = temp_q;
+    }
+    return (((p / q) * x) * Math.exp(-x2)) / _SQRTPI;
+}
+
+function _erf(x: number): number {
+    if (Number.isNaN(x)) {
+        return x;
+    }
+    const absx = Math.abs(x);
+    if (absx < _ERF_SERIES_CUTOFF) {
+        return _m_erf_series(x);
+    }
+    const cf = _m_erfc_contfrac(absx);
+    return x > 0.0 ? 1.0 - cf : cf - 1.0;
+}
+
+/** Python `math.comb(n, k)` — exact non-negative integer (BigInt → Number). */
+function _comb(n: number, k: number): number {
+    if (k < 0 || k > n) {
+        return 0;
+    }
+    let kk = BigInt(Math.min(k, n - k));
+    if (kk === 0n) {
+        return 1;
+    }
+    const N = BigInt(n);
+    let result = 1n;
+    let i = 0n;
+    while (i < kk) {
+        result = (result * (N - i)) / (i + 1n);
+        i += 1n;
+    }
+    return Number(result);
+}
+
+function _phi(z: number): number {
+    // Standard-normal CDF via erf.
+    return 0.5 * (1.0 + _erf(z / Math.sqrt(2.0)));
+}
+
+
+interface WilcoxonResult {
+    n: number;
+    W_plus: number; // PyFloat-flagged at dump for the rounded case
+    W_minus: number;
+    p: number;
+    rank_biserial: number;
+}
+
+export function wilcoxon(diffs: number[]): WilcoxonResult {
+    // Wilcoxon signed-rank on paired differences (treatment - baseline).
+    // Returns W+, W-, normal-approx two-sided p (continuity-corrected), and
+    // rank-biserial effect size. Zeros are dropped.
+    const nz = diffs.filter((d) => Math.abs(d) > 1e-9);
+    const n = nz.length;
+    if (n === 0) {
+        return { n: 0, W_plus: 0, W_minus: 0, p: 1.0, rank_biserial: 0.0 };
+    }
+    // order = sorted(range(n), key=lambda i: abs(nz[i])) — stable sort.
+    const order = Array.from({ length: n }, (_, i) => i).sort((x, y) => {
+        const ax = Math.abs(nz[x] as number);
+        const ay = Math.abs(nz[y] as number);
+        return ax < ay ? -1 : ax > ay ? 1 : x - y; // stable on tie
+    });
+    const ranks: number[] = new Array(n).fill(0.0);
+    let i = 0;
+    while (i < n) {
+        let j = i;
+        while (j + 1 < n && Math.abs(nz[order[j + 1] as number] as number) === Math.abs(nz[order[i] as number] as number)) {
+            j += 1;
+        }
+        const avg = (i + 1 + j + 1) / 2.0; // average rank for ties (1-based)
+        for (let k = i; k <= j; k += 1) {
+            ranks[order[k] as number] = avg;
+        }
+        i = j + 1;
+    }
+    let w_plus = 0.0;
+    let w_minus = 0.0;
+    for (let idx = 0; idx < n; idx += 1) {
+        if ((nz[idx] as number) > 0) {
+            w_plus += ranks[idx] as number;
+        } else if ((nz[idx] as number) < 0) {
+            w_minus += ranks[idx] as number;
+        }
+    }
+    const total = w_plus + w_minus;
+    const rb = total ? (w_plus - w_minus) / total : 0.0;
+    // Normal approximation (ok-ish for n>=10; for small n it's conservative —
+    // we surface n so the reader can weight it).
+    const mean = (n * (n + 1)) / 4.0;
+    const sd = Math.sqrt((n * (n + 1) * (2 * n + 1)) / 24.0);
+    const w = Math.min(w_plus, w_minus);
+    let p: number;
+    if (sd === 0) {
+        p = 1.0;
+    } else {
+        const z = (w - mean + 0.5) / sd;
+        p = Math.min(1.0, 2.0 * _phi(z));
+    }
+    return {
+        n,
+        // W_plus / W_minus are not surfaced in JSON/markdown (compare() drops
+        // them), so plain numbers suffice; p / rank_biserial are floats.
+        W_plus: _pyRound(w_plus, 1),
+        W_minus: _pyRound(w_minus, 1),
+        p: _pyRound(p, 4),
+        rank_biserial: _pyRound(rb, 4),
+    };
+}

package/src/scripts/_lib/paired_verdict.ts

@@ -0,0 +1,226 @@
+/**
+ * Paired verdicts decided by DIRECTION, never by magnitude.
+ *
+ * `road-to-skill-ecosystem-eval-integrity` Phase 2. The defect this replaces was
+ * proved by exhaustive comparison rather than argued: weighting a paired
+ * confidence interval by per-trial magnitude disagrees with the exact test on
+ * twelve records up to ten trials, and it is the PERMISSIVE side in every one of
+ * them. The visible symptom is the opposite of what "permissive" suggests, which
+ * is why it went unnoticed — an artifact that won every trial still failed five
+ * consecutive runs, because a handful of large opposite-direction deltas
+ * outweighed a clean sweep of small ones.
+ *
+ * The fix is not a better interval. It is to stop asking the question magnitude
+ * answers. A paired comparison asks *did this help more often than it hurt*, and
+ * the exact test for that reads the DISCORDANT trials only: a pair where both
+ * arms tie carries no information about direction and must not dilute the count.
+ *
+ * ── What magnitude is still for ─────────────────────────────────────────────
+ * Triage, and nothing else. {@link PairedVerdict.magnitude_mean} is retained and
+ * reported so a human can see whether a directional win is worth anything, and
+ * every renderer that prints it must say it decides nothing. A number in a
+ * report with no stated role gets read as a criterion by the next person.
+ */
+
+/** The four outcomes. `underpowered` is deliberately not a kind of pass. */
+export type PairedVerdictKind = 'pass' | 'regression' | 'no-change' | 'underpowered';
+
+export interface PairedVerdict {
+    kind: PairedVerdictKind;
+    /** Trials where the arms differed. Concordant pairs are excluded by design. */
+    discordant: number;
+    /** Discordant trials favouring the treatment. */
+    wins: number;
+    /** Discordant trials favouring the control. */
+    losses: number;
+    /** One-sided exact p in the observed direction. */
+    p: number;
+    /** Mean signed delta over ALL trials. Triage only — decides nothing. */
+    magnitude_mean: number | null;
+    /** True when `discordant` sits exactly on the derived floor. */
+    at_floor: boolean;
+    /** Why this verdict, in one sentence a report can print verbatim. */
+    reason: string;
+}
+
+/**
+ * Significance level. 0.05 is the convention every sibling gate in this tree
+ * already applies (`bench_ab_size_claim.ALPHA`), and changing it here would make
+ * two verdicts in one report answer to different bars.
+ */
+export const ALPHA = 0.05;
+
+/**
+ * Minimum discordant trials, DERIVED from the test rather than chosen.
+ *
+ * The one-sided exact sign test over `n` discordant trials has a smallest
+ * attainable p of `0.5 ** n` — the probability of a perfect sweep. A pass at
+ * `ALPHA` is therefore arithmetically impossible until `0.5 ** n <= ALPHA`:
+ *
+ *   n=1 → 0.5      n=2 → 0.25     n=3 → 0.125
+ *   n=4 → 0.0625   n=5 → 0.03125  ← first n that can clear 0.05
+ *
+ * So the floor is **5**, and it is a fact about the test, not a preference. A
+ * specification with fewer discordant trials cannot pass however good the
+ * artifact is, which is why {@link decidePairedVerdict} returns `underpowered`
+ * there instead of `no-change`: the two look identical in a table and have
+ * opposite remedies — one says run more trials, the other says stop.
+ *
+ * Recomputed by {@link deriveMinDiscordant} rather than hardcoded, so a future
+ * change to ALPHA moves the floor with it instead of leaving a stale constant.
+ */
+export function deriveMinDiscordant(alpha: number = ALPHA): number {
+    let n = 1;
+    while (0.5 ** n > alpha && n < 64) n += 1;
+    return n;
+}
+
+export const MIN_DISCORDANT = deriveMinDiscordant();
+
+/** Binomial coefficient, exact via BigInt so large n cannot drift. */
+function comb(n: number, k: number): number {
+    if (k < 0 || k > n) return 0;
+    let num = 1n;
+    let den = 1n;
+    const kk = BigInt(Math.min(k, n - k));
+    for (let i = 0n; i < kk; i += 1n) {
+        num *= BigInt(n) - i;
+        den *= i + 1n;
+    }
+    return Number(num / den);
+}
+
+/**
+ * One-sided exact sign test over discordant trials.
+ *
+ * `P(X >= wins)` under a fair coin on `discordant` trials — the probability of
+ * seeing at least this many wins if direction were noise. One-sided because the
+ * question a verdict asks is directional: *is the treatment better*, not *do the
+ * arms differ*. A two-sided p answers the second and is twice as hard to clear
+ * for the first, which is a bar nobody chose.
+ */
+export function exactOneSidedP(wins: number, discordant: number): number {
+    if (discordant <= 0) return 1;
+    let tail = 0;
+    for (let i = wins; i <= discordant; i += 1) tail += comb(discordant, i);
+    return Math.min(1, tail * 0.5 ** discordant);
+}
+
+export interface PairedInput {
+    /** One signed delta per trial. Positive favours the treatment. */
+    deltas: readonly number[];
+    /** Deltas within this of zero are ties and are excluded as concordant. */
+    tieEpsilon?: number;
+    alpha?: number;
+}
+
+/**
+ * Decide a paired comparison from direction alone.
+ *
+ * Ties are dropped BEFORE anything is counted, which is the half a
+ * magnitude-weighted interval gets wrong: a tie has zero magnitude, so it
+ * contributes nothing to the mean while still inflating `n` and narrowing the
+ * interval. Dropping it makes the sample honest about how much evidence there
+ * actually is.
+ */
+export function decidePairedVerdict(input: PairedInput): PairedVerdict {
+    const alpha = input.alpha ?? ALPHA;
+    const eps = input.tieEpsilon ?? 0;
+    const floor = deriveMinDiscordant(alpha);
+    const wins = input.deltas.filter((d) => d > eps).length;
+    const losses = input.deltas.filter((d) => d < -eps).length;
+    const discordant = wins + losses;
+    const magnitude_mean =
+        input.deltas.length === 0
+            ? null
+            : input.deltas.reduce((a, b) => a + b, 0) / input.deltas.length;
+    const at_floor = discordant === floor;
+
+    if (discordant < floor) {
+        return {
+            kind: 'underpowered',
+            discordant,
+            wins,
+            losses,
+            p: 1,
+            magnitude_mean,
+            at_floor: false,
+            reason:
+                `${String(discordant)} discordant trial(s) is below the derived floor of ` +
+                `${String(floor)}: the smallest attainable one-sided p is ${(0.5 ** discordant).toFixed(4)}, ` +
+                `so no result here can clear ${String(alpha)}. This is NOT a null result — it is an ` +
+                'absent measurement, and it belongs in no pass-rate denominator.',
+        };
+    }
+
+    const favoured = wins >= losses ? wins : losses;
+    const p = exactOneSidedP(favoured, discordant);
+    if (p > alpha) {
+        return {
+            kind: 'no-change',
+            discordant,
+            wins,
+            losses,
+            p,
+            magnitude_mean,
+            at_floor,
+            reason:
+                `${String(wins)}/${String(discordant)} discordant trials favour the treatment ` +
+                `(one-sided exact p=${p.toFixed(4)}); the direction is not distinguishable from noise at ${String(alpha)}.`,
+        };
+    }
+    return {
+        kind: wins >= losses ? 'pass' : 'regression',
+        discordant,
+        wins,
+        losses,
+        p,
+        magnitude_mean,
+        at_floor,
+        reason:
+            `${String(wins)}/${String(discordant)} discordant trials favour the ` +
+            `${wins >= losses ? 'treatment' : 'control'} (one-sided exact p=${p.toFixed(4)}).`,
+    };
+}
+
+/**
+ * The warning a specification earns by sitting EXACTLY on the derived floor.
+ *
+ * At the floor, `0.5 ** n` equals or barely clears alpha, so a pass requires a
+ * PERFECT sweep — one trial going the other way makes the result arithmetically
+ * unreachable before the run starts. That is a specification defect rather than
+ * a result, and it is invisible in the output: the run simply fails. Observed as
+ * five specifications raised to exactly the floor all failing, four of them
+ * decided before the run began.
+ *
+ * Returns `null` when there is nothing to warn about, so a caller can print it
+ * unconditionally.
+ */
+export function floorWarning(v: PairedVerdict, alpha: number = ALPHA): string | null {
+    if (!v.at_floor) return null;
+    return (
+        `specification sits exactly on the derived discordant floor (${String(v.discordant)}): ` +
+        `a pass needs every trial to agree, because one dissent moves p to ` +
+        `${exactOneSidedP(v.discordant - 1, v.discordant).toFixed(4)} against a bar of ${String(alpha)}. ` +
+        'Raise the trial count rather than the expectation.'
+    );
+}
+
+/**
+ * Pass rate over a set of verdicts, with `underpowered` excluded.
+ *
+ * Exported as the ONLY sanctioned way to compute one, because the exclusion is
+ * the whole point and an inline `filter(v => v.kind === 'pass').length / all.length`
+ * silently reinstates the defect. Returns `null` when nothing is decidable —
+ * a rate over an empty denominator is a fabricated number, not a zero.
+ */
+export function passRate(verdicts: readonly PairedVerdict[]): { rate: number; decided: number; excluded: number } | null {
+    const decidable = verdicts.filter((v) => v.kind !== 'underpowered');
+    const excluded = verdicts.length - decidable.length;
+    if (decidable.length === 0) return null;
+    return {
+        rate: decidable.filter((v) => v.kind === 'pass').length / decidable.length,
+        decided: decidable.length,
+        excluded,
+    };
+}

package/src/scripts/_lib/prefix_stable_surfaces.ts

@@ -0,0 +1,123 @@
+/**
+ * The canonical prefix-stable surface set — one list, loaded by every gate
+ * that needs it, restated by none.
+ *
+ * WHAT A PREFIX-STABLE SURFACE IS
+ * -------------------------------
+ * Bytes that sit in the cached prompt prefix of every dispatch. Rewriting them
+ * mid-session invalidates the cache for the remainder of that session, so the
+ * next call pays the cache-WRITE rate over the whole prefix instead of the
+ * cache-READ rate. That is the cost this list exists to bound; it is not a
+ * correctness claim about the content.
+ *
+ * WHY THE LIST LIVES HERE AND NOT IN A GATE
+ * -----------------------------------------
+ * `check_preamble_payload_budget` measured these three buckets first and stated
+ * their roots twice inside its own file — once to drive the census, once as the
+ * `roots:` argument to the dead-scope guard. A second gate restating them a
+ * third time is the recorded drift shape this repository already pays for
+ * elsewhere: two lists describing one boundary diverge, and each gate then
+ * guards a set the other no longer measures. So the roots move here and both
+ * gates import them.
+ *
+ * SCOPE — decided, with the reopen condition recorded
+ * ---------------------------------------------------
+ * Council 2026-08-28 (2/2 convergent, anthropic + openai, 2 rounds) resolved
+ * `road-to-runtime-context-floors`'s `which-surfaces-are-prefix-stable` blocker
+ * as option (c): the declared set is the three buckets the payload budget
+ * already measures, and the widening to "every surface a hook can write that
+ * reaches standing context" is recorded as an explicit reopen condition rather
+ * than enumerated now. Enumerating carriers that do not exist would be
+ * enumerating a plan.
+ *
+ * REOPEN — see `docs/contracts/prefix-stable-surfaces.md` § Reopen condition.
+ * A change that lands a hook or resident-process carrier able to write standing
+ * context outside these three roots must add it here in the same change.
+ */
+
+export interface PrefixStableSurface {
+    /** Stable identifier; the mutation gate names it in its findings. */
+    id: string;
+    /** Repo-relative root. A directory root covers everything beneath it. */
+    root: string;
+    kind: 'dir' | 'file';
+    /** Human-readable bucket name, as the payload budget reports it. */
+    bucket: string;
+    /** Why these bytes are in the cached prefix. */
+    why: string;
+}
+
+/**
+ * The declared set. Order is the order the payload budget reports its buckets,
+ * so a reader comparing the two outputs sees the same sequence.
+ */
+export const PREFIX_STABLE_SURFACES: readonly PrefixStableSurface[] = [
+    {
+        id: 'project-scope-rules',
+        root: 'dist/agent-src/rules',
+        kind: 'dir',
+        bucket: 'project-scope rules',
+        why: 'Every always-loaded rule body is re-written into the preamble on every spawn.',
+    },
+    {
+        id: 'preloaded-skills-catalog',
+        root: 'dist/agent-src/skills',
+        kind: 'dir',
+        bucket: 'preloaded skills catalog',
+        why: 'Skill names and descriptions are catalogued into the preamble on every spawn.',
+    },
+    {
+        id: 'project-claude-md',
+        root: 'CLAUDE.md',
+        kind: 'file',
+        bucket: 'CLAUDE.md hierarchy (project only)',
+        why: 'The project half of the CLAUDE.md hierarchy is injected ahead of the first user turn.',
+    },
+    {
+        id: 'project-claude-local-md',
+        root: 'CLAUDE.local.md',
+        kind: 'file',
+        bucket: 'CLAUDE.md hierarchy (project only)',
+        why: 'The gitignored project-local override is injected on the same path as CLAUDE.md.',
+    },
+] as const;
+
+/**
+ * The re-arm events. A rebuilt prefix is expected and paid for once at each of
+ * these boundaries, so a write declared against one is not a mid-session
+ * mutation. Anything not listed here fires mid-session.
+ */
+export const RE_ARM_EVENTS: readonly string[] = ['session_start', 'pre_compact'] as const;
+
+/** Roots only, in declaration order — the shape `assertScanned` wants. */
+export function prefixStableRoots(): string[] {
+    return PREFIX_STABLE_SURFACES.map((s) => s.root);
+}
+
+/** Directory roots only — the shape the payload census walks. */
+export function prefixStableDirRoots(): string[] {
+    return PREFIX_STABLE_SURFACES.filter((s) => s.kind === 'dir').map((s) => s.root);
+}
+
+function normalise(p: string): string {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+/**
+ * Does `target` (a repo-relative path, or a path literal lifted out of source)
+ * resolve inside a declared surface? Returns the surface, or `null`.
+ *
+ * Deliberately substring-free: a literal must match a root exactly, or sit
+ * beneath a directory root at a path separator. `dist/agent-src/rules-backup`
+ * is NOT inside `dist/agent-src/rules`.
+ */
+export function surfaceFor(target: string): PrefixStableSurface | null {
+    const t = normalise(target);
+    if (t === '') return null;
+    for (const s of PREFIX_STABLE_SURFACES) {
+        const root = normalise(s.root);
+        if (t === root) return s;
+        if (s.kind === 'dir' && t.startsWith(root + '/')) return s;
+    }
+    return null;
+}

package/src/scripts/_lib/privacy_class.ts

@@ -0,0 +1,47 @@
+/**
+ * The privacy class an audit-log-v1 line declares about ITSELF.
+ *
+ * `docs/contracts/audit-log-v1.md` states a privacy floor in prose and, until
+ * 2026-08-30, named a test file that exists in no tree — so the floor was
+ * asserted and not enforced. Two things close that gap, and they are different
+ * mechanisms rather than one restated twice:
+ *
+ * 1. A COMPILE-TIME guard (`NoFreeForm`, applied to each producer's input type)
+ *    makes a field that *could* hold a body a build error. That is what stops
+ *    the leak.
+ * 2. This enum makes each line SAY what it carries. That is what lets a reader
+ *    decide whether a stream is safe to aggregate, export, or ship without
+ *    re-deriving the answer from the producer's source.
+ *
+ * The first without the second leaves every consumer inferring the class; the
+ * second without the first is a label with nothing behind it.
+ *
+ * One module rather than a literal per producer, per step 9.1's rule that an
+ * enum family appearing in more than one place gets exactly one definition —
+ * the duplicate-enum failure that gave this tree two outcome vocabularies.
+ */
+
+/**
+ * Ordered from least to most permissive. A reader may treat a lower class as
+ * satisfying any assertion made about a higher one; the reverse is never true.
+ */
+export const PRIVACY_CLASSES = [
+    /**
+     * Counts, enums, timestamps and opaque ids the package itself minted. No
+     * artefact names at all. The strictest class a line can declare.
+     */
+    'counts-only',
+    /**
+     * Everything `counts-only` allows, plus STABLE ARTEFACT IDS the package
+     * governs — rule ids, skill ids, task-class ids. Still no bodies, no paths,
+     * no user content, and no third-party identifiers. This is what both
+     * shipped producers emit, because both carry `rules_applied`.
+     */
+    'ids-only',
+] as const;
+
+export type PrivacyClass = (typeof PRIVACY_CLASSES)[number];
+
+export function isPrivacyClass(v: unknown): v is PrivacyClass {
+    return typeof v === 'string' && (PRIVACY_CLASSES as readonly string[]).includes(v);
+}