amicus 4.7.1 → 4.8.0

package/src/council/ledger-join.js

@@ -0,0 +1,284 @@
+// src/council/ledger-join.js
+'use strict';
+
+/**
+ * @module council/ledger-join
+ * How ONE pair group resolves into ONE ledger row's fields: which of its
+ * runStats rows may decide `role`/`conformance` (SI-17's normalise), which
+ * street-cred rows are its own (the seat-aware join, T3.3), and — since v4.8
+ * SI-18 — which of the alias's raised findings are its own. Split out of
+ * ./ledger at v4.8 T3.3, on the same seam T3.0 used for ./ledger-stats: that
+ * split took the READ half out, this one takes the JOIN SEMANTICS out, and
+ * `buildLedgerRows` keeps only the row assembly. Both dependencies run one way
+ * (ledger.js -> ledger-join.js / ledger-stats.js) and neither can cycle.
+ *
+ * ⚠️ REQUIRE-FREE by design — the ./seats · ./run-stats-entry · ./peer-split
+ * precedent. Nothing here reads the filesystem or the config dir.
+ * ⚠️ NOT re-exported from ./ledger: none of the four is used outside the row
+ * build, so adding them to that module's export list would only risk the
+ * AUTO:modules truncation its own comment warns about. Tests import them here.
+ *
+ * ⚠️ FIVE named mutants guard these, alongside LEDGERALIAS on ledger.js's
+ * join key. Each mutation and its MEASURED red set is recorded with the rest:
+ * tests/council/street-cred-mutants.js :: CHAIRWINS guards benchLegs, while
+ * tests/council/street-cred-mutants.js :: CREDALIAS guards WHETHER the seat
+ * lookup can ever win, tests/council/street-cred-mutants.js :: ANYSEATED
+ * (v4.8 follow-up) guards HOW COMPLETE a group's seats must be before it does,
+ * tests/council/street-cred-mutants.js :: ALIASLASTWINS guards how the lookup
+ * combines what it finds, and tests/council/street-cred-mutants.js ::
+ * FINDINGALIAS (v4.8 SI-18) guards splitFindingsBySeat the same wholesale way.
+ * RE-RUN them, never renumber them.
+ */
+
+/**
+ * v4.8 T3.3 — SI-17's NORMALISE, per owner ruling R4 ("normalise before the
+ * ledger join, inside Phase 3 — works on all paths including the two
+ * hand-assembled `appendRun` ones a preflight guard cannot reach"). It lives on
+ * the WRITE path — here, called from ledger.js :: buildLedgerRows — for exactly
+ * that reason: `cli-handlers-council.js` and `mcp-server.js` copy `meta`
+ * verbatim out of user JSON, and the documented `amicus council tally` shape
+ * PUTS THE CHAIR ON THE BENCH. Both re-read 2026-08-20: docs/council.md's
+ * `## Worked example` meta block is `models ["deepseek","gpt"]` with
+ * `chair "deepseek"`, and tests/council/fixtures/av-receiver-input.js is
+ * `models ["deepseek","gpt","mistral"]` with the same chair. There it is the
+ * normal case rather than an edge — though neither of those two carries a
+ * `role: 'chair'` runStats row, so neither is what this function changes.
+ *
+ * A `role: 'chair'` row is the CHAIR SYNTHESIS leg. That is a different
+ * contract from a bench review — prose plus a VERDICT line, not findings JSON —
+ * so its `conformance` and `role` describe a different job from the seat row it
+ * shares an alias and a resolution with. MEASURED at BASE `b341b273` on
+ * `--models ds,gpt --chair ds`, both legs resolving to `v/ds`:
+ *
+ *   bench UNSTRUCTURED + chair clean  ->  role 'chair', conformance 'unstructured'
+ *   bench clean + chair UNSTRUCTURED  ->  role 'chair', conformance 'unstructured'
+ *   the same bench with the chair OFF it -> role 'council', conformance 'clean'
+ *
+ * The two directions are INDISTINGUISHABLE in the persisted row, and neither
+ * agrees with the off-bench control for the same bench leg — in an append-only
+ * file that is never migrated. Normalising means the bench leg decides both
+ * fields whenever the group holds one, so a seat's ledger identity no longer
+ * depends on whether that model also chaired.
+ *
+ * `wasChair` is NOT normalised away: it is a fact about the run rather than
+ * about a contract, it stays any-wins over the WHOLE group (T15), and it is the
+ * one thing the chair row legitimately contributes to a bench seat's row.
+ * A group holding ONLY chair rows — the split-resolution chair leg of T16, a
+ * give-up row — is unchanged: there is no bench leg to prefer, so the chair row
+ * still decides both fields and nothing is lost.
+ *
+ * ⚠️ ON A MIXED GROUP SOMETHING IS LOST, AND IT IS NOT `wasChair`. The chair
+ * leg's `conformance` no longer reaches the ledger AT ALL there, so a BROKEN
+ * chair synthesis by a model that also sat on the bench becomes invisible to
+ * the lifetime histogram; only `wasChair: true` records that it chaired.
+ * MEASURED end to end through appendRun -> ledger-stats.js ::
+ * deriveReliability, on `--models ds,gpt --chair ds` with a CLEAN bench leg and
+ * an UNSTRUCTURED chair leg, both resolving to `v/ds`:
+ *
+ *   b341b273 : conformance { unstructured: 1 }
+ *   after    : conformance { clean: 1 }
+ *
+ * That is the intended direction — the bench leg's own contract outcome is what
+ * a bench seat's row should report, and the old value was the chair's outcome
+ * wearing the seat's name — but it is a REAL loss of signal, not a relabelling,
+ * and no other surface picks it up. It is disclosed here rather than repaired:
+ * recording a chair leg's conformance in its own right would mean giving the
+ * chair its own ledger identity, which changes the row SET and is out of this
+ * task's scope. FILED for the owner to rule on, not decided here.
+ * @param {Array<object>} group one pair group's runStats rows
+ * @returns {Array<object>} the rows that may decide `role` and `conformance`
+ */
+function benchLegs(group) {
+  const bench = group.filter(r => r.role !== 'chair');
+  return bench.length ? bench : group;
+}
+
+/** Mean of the numeric values of `field` across `rows`; null when none is numeric. */
+function meanCred(rows, field) {
+  const nums = rows.map(r => r[field]).filter(v => typeof v === 'number');
+  return nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : null;
+}
+
+/**
+ * v4.8 T3.3 — the street-cred join, seat-aware. THE HAZARD THIS EXISTS FOR:
+ * `new Map(streetCred.map(s => [s.model, s]))` is last-wins by alias. At BASE
+ * `b341b273` that was a genuine no-op — measured on bench `['a','a','b']`, the
+ * two twin rows were BYTE-IDENTICAL (3 rows in, `Map` size 2: one dropped, but
+ * LOSSLESSLY). The moment `street-cred.js :: rankPositions` is seat-keyed those
+ * rows DIVERGE, and the same silent drop starts losing a real seat's numbers
+ * into an append-only file. That is why the two halves shipped in ONE commit
+ * (controller ruling ledger C-1) and why no intermediate tree may hold one
+ * without the other.
+ *
+ * TWO LOOKUPS, TRIED IN THAT ORDER, because the two sides are indexed by
+ * INDEPENDENT producers and either can be seated without the other:
+ *   1. the group's own seats, named by `runStats[].seat` (emit-when-DIFFERENT),
+ *      resolved through `sc` — which holds ONLY the seated street-cred rows —
+ *      and ONLY when EVERY row in the group resolves this way;
+ *   2. failing that (including a PARTIAL resolution), every street-cred row
+ *      carrying this ALIAS.
+ *
+ * ⚠️ (1) IS ALL-OR-NOTHING. v4.8 follow-up (2026-08-21), council finding 3 on
+ * PR #176, reproduced at BASE `13cd0a2d`: this function used to take lookup
+ * (1) the moment ANY of the group's seats resolved through `sc`, discarding
+ * the numbers of any OTHER row in the SAME group whose seat did not resolve.
+ * A MIXED group — one seated row, one not — then read NARROWER than a group
+ * with NO seat information at all, which falls straight to (2)'s alias mean.
+ * Partial seat information produced a narrower read than no information,
+ * which is backwards — the mirror image of fix round 1's defect just above.
+ * MEASURED on a two-row `a` group, seat A resolving to peersOnly 1 and seat B
+ * — same alias, unresolvable through `sc` — to peersOnly 5:
+ *
+ *   before : MIXED group (A seated, B not)   peersOnly 1   (A alone)
+ *            NEITHER seated                  peersOnly 3   (mean of A, B)
+ *   after  : MIXED group (A seated, B not)   peersOnly 3   (== neither seated)
+ *
+ * FIX: lookup (1) now requires EVERY row's seat to resolve in `sc` —
+ * `ids.length > 0 && ids.every(id => id && sc.has(id))`. Anything short of
+ * that — one row unseated, one row seated to an id `sc` does not hold, or an
+ * empty group — falls through to (2), the same alias mean a fully-unseated
+ * group already read. ⚠️ `ids.length > 0` is load-bearing on its own:
+ * `[].every(...)` is vacuously `true` in JavaScript, so without that guard an
+ * EMPTY group would count as "fully identified", resolve through an empty
+ * `ids` to an empty seated array, and return `{}` (via the `!rows.length`
+ * guard below) instead of falling through to the alias mean the empty-group
+ * case already relied on. Killed by the named mutant
+ * tests/council/street-cred-mutants.js :: ANYSEATED, which reverts the gate
+ * to its pre-fix "any resolves" form and reproduces the MIXED regression
+ * above; CREDALIAS (below the function) is the narrower mutant forcing the
+ * seat lookup to never win AT ALL, fully-seated groups included.
+ *
+ * ⚠️ WHY (2) IS A FILTER AND NOT AN ALIAS KEY IN `sc`. Fix round 1, Important 1
+ * — this function REGRESSED that quadrant and the regression was measured, not
+ * argued. When the street-cred rows are seated and the runStats rows are NOT,
+ * an alias-keyed map holds no entry for the alias at all, so the old
+ * `sc.get(model) || {}` resolved to `{}` and the row persisted NULL street
+ * cred. MEASURED on one hand-assembled record driven through the real
+ * `tally()` -> `buildLedgerRows()`, bench `['a','a','b']` with `meta.seats` and
+ * no `runStats[].seat`:
+ *
+ *   b341b273 : ledger row a  withSelf 2.667  peersOnly 3
+ *   46719a7f : ledger row a  withSelf null   peersOnly null
+ *
+ * That quadrant is not exotic: mcp-tools.js :: amicus_council_tally declares
+ * `meta.seats` while its `runStats` is `z.array(z.record(z.any()))`, so nothing
+ * asks that caller for a seat on a runStats row, and cli-handlers-council.js
+ * passes user JSON through verbatim. Both then `appendRun` into a file that is
+ * never migrated, and ledger-stats.js :: deriveReliability filters
+ * `typeof v === 'number'`, so a null drops the run out of
+ * `avgStreetCredPeersOnly` — the value run-chair.js :: pickFallbackChair ranks
+ * on. This is precisely the hand-assembled path owner ruling R4 puts in scope.
+ *
+ * ⚠️ THE MEAN IS THE FALLBACK, NOT A LAST-WINS ALIAS KEY, and the two are
+ * DISTINGUISHABLE only on input BASE could never produce. At `b341b273`
+ * `computeStreetCred` was `models.map(m => f(m, judgePos))` — deterministic in
+ * `m` — so two rows sharing an alias were always byte-identical, and a mean
+ * across them equals the last-wins value exactly. VERIFIED BY BRUTE FORCE at
+ * BASE over 4374 cases (every 3-slot bench over three aliases x two judges x
+ * nine order shapes each, strict and tied, under two judge-name pairs), which
+ * produced 3402 duplicated-alias groups: ZERO had rows that differ. So the mean
+ * is byte-identical to BASE on every shape BASE could produce, and is the honest
+ * answer on the two shapes it cannot: seated rows that genuinely diverge, and
+ * hand-assembled input that hands us two differing rows under one alias — where
+ * last-wins would silently discard one, which is the whole defect class this
+ * task exists to close. Pinned by ledger.test.js T12b, "the alias fallback
+ * MEANS its rows, it does not take the last one", and killed by the named
+ * mutant tests/council/street-cred-mutants.js :: ALIASLASTWINS.
+ *
+ * ⚠️ A group can cover MORE THAN ONE SEAT — two twins that resolved to the same
+ * executable are one (alias, resolvedModel) pair — and a ledger row has ONE
+ * street-cred slot. The row SET is not this task's to change (`meta.models`
+ * stays the driver, and PR4b's emission order is one row per pair group), so
+ * with one slot the choice is between dropping seats and combining them. The
+ * mean is the only combination that reads every seat and still returns a lone
+ * seat's own number unchanged.
+ * ⚠️ It is NOT weight-preserving, and saying otherwise would be the easy wrong
+ * claim: ledger-stats.js :: deriveReliability averages ROWS, so N seats folded
+ * into one row count once where N separate rows would count N times. That
+ * matters only when the aggregate mixes this group with other rows or other
+ * runs — and it is still strictly better than today, which reads exactly one of
+ * the N and discards the others without saying so.
+ * @param {Map<string, object>} sc the SEATED street-cred rows, keyed by seat id
+ * @param {Array<object>} group one pair group's runStats rows
+ * @param {string} model the block's alias
+ * @param {Array<object>} streetCred the record's street-cred rows, for (2)
+ */
+function credFor(sc, group, model, streetCred) {
+  // Named mutant "ANYSEATED": revert this gate to its pre-fix "any resolves"
+  // form —
+  //   const seated = [...new Set(group.map(r => r.seat).filter(Boolean))]
+  //     .map(id => sc.get(id)).filter(Boolean);
+  //   const rows = seated.length ? seated : (streetCred || []).filter(...);
+  // tests/council/street-cred-mutants.js :: ANYSEATED.
+  const ids = group.map(r => r.seat);
+  const fully = ids.length > 0 && ids.every(id => id && sc.has(id));
+  // Named mutant "CREDALIAS": force `fully` to never be true, so the seat
+  // lookup can never win even on a genuinely fully-seated group —
+  //   const rows = fully ? [...] : fallback;  ->  const rows = false ? [...] : fallback;
+  // tests/council/street-cred-mutants.js :: CREDALIAS.
+  const rows = fully ? [...new Set(ids)].map(id => sc.get(id))
+    : (streetCred || []).filter(s => s && s.model === model);
+  if (!rows.length) { return {}; }
+  return { withSelf: meanCred(rows, 'withSelf'), peersOnly: meanCred(rows, 'peersOnly') };
+}
+
+/**
+ * v4.8 SI-18 — the FINDINGS attribution, seat-aware. THE HAZARD THIS EXISTS
+ * FOR: ledger.js used to compute `findings.filter(f => f.raiser === model)`
+ * once per alias and hand the WHOLE result to the block's FIRST pair group
+ * (R4b-2's concentration), regardless of how many pair groups PR4b's fan-out
+ * gave that alias. On a twin bench whose two seats resolve to DIFFERENT
+ * executables — already two separate rows since PR4b — every finding still
+ * landed on the first row and the second read 0 and null rates; on a twin
+ * bench sharing ONE executable, the single row combined both seats' findings
+ * with no way to tell them apart. `findings[].raiserSeat` (tally.js:114-115,
+ * emit-when-DIFFERENT from `raiser`) has named the seat that actually raised
+ * each finding since v4.8 PR3 Task 5 (anonymize.js :: toGlobalFindings); this
+ * join simply never read it. That is the half T3.3's seat-aware `credFor`,
+ * just above, did not close.
+ *
+ * PER-FINDING, NOT PER-GROUP MEAN. Unlike `credFor`'s street-cred numbers, a
+ * finding is a discrete item with exactly one true home, not a value to
+ * average away. A finding whose `raiserSeat` names a seat exactly one pair
+ * group's own runStats rows carry (seat ids are unique within an alias's own
+ * table, so at most one group can ever match) is credited to THAT group. The
+ * row SET itself never moves — PR4b's (alias, resolvedModel) pairing is
+ * unchanged; only which existing row a finding's numbers land on can.
+ *
+ * THE FALLBACK IS R4b-2, NARROWED, NOT REPLACED. A finding that cannot be
+ * resolved to a specific group — `raiserSeat` absent (every pre-seat
+ * document, every hand-assembled one), or present but matching no group's own
+ * seat (the asymmetric quadrant tally.js's own comment names: both
+ * hand-assembled `appendRun` callers can seed `meta.seats` — and so
+ * `streetCred` — without ever being asked for a seat on a `runStats` row, so
+ * a document can carry `raiserSeat` while no runStats row anywhere carries
+ * `.seat`) — still concentrates on the block's FIRST pair group, exactly as
+ * R4b-2 always has. So: a document with no seat channel at all leaves every
+ * finding unresolved, landing exactly where it always did; a document with a
+ * full seat channel splits findings precisely across the rows PR4b's fan-out
+ * already produces, and only a genuinely unattributable finding still falls
+ * back to the anchor. On the single-row case — twins sharing one executable —
+ * every seat's findings resolve to the SAME (only) group, so they combine
+ * there exactly as they do today: the row SET, not the attribution rule, is
+ * what limits how far apart two twins' numbers can land.
+ * @param {Array<Array<object>>} groups this alias's pair groups' runStats
+ *   rows, in emission order (ledger.js's `groups.map(([, group]) => group)`)
+ * @param {Array<object>} raised this alias's raised findings
+ *   (`findings.filter(f => f.raiser === model)`)
+ * @returns {Array<Array<object>>} one findings array per group, same length
+ *   and order as `groups`; group 0 additionally absorbs every finding no
+ *   group's own seats could place
+ */
+function splitFindingsBySeat(groups, raised) {
+  const seatSets = groups.map(group => new Set(group.map(r => r.seat).filter(Boolean)));
+  const mine = groups.map(() => []);
+  const leftover = [];
+  for (const f of raised) {
+    const idx = f.raiserSeat ? seatSets.findIndex(s => s.has(f.raiserSeat)) : -1;
+    (idx === -1 ? leftover : mine[idx]).push(f);
+  }
+  if (mine.length) { mine[0] = mine[0].concat(leftover); }
+  return mine;
+}
+
+module.exports = { benchLegs, credFor, splitFindingsBySeat, meanCred };

package/src/council/ledger-stats.js

@@ -0,0 +1,100 @@
+// src/council/ledger-stats.js
+'use strict';
+// The ledger READ/aggregate half: readRows, avg, countRuns, deriveReliability,
+// buildStatsDoc, and LEDGER_FILE. Moved verbatim from ledger.js@f207538c:192-274
+// (LEDGER_FILE was ledger.js@f207538c:15) — v4.8 Phase 3 T3.0 size-gate split,
+// zero behavior. REQUIRE-FREE of ./ledger by design: this is the leaf the WRITE
+// half (buildLedgerRows/appendRun, which stay in ledger.js) depends on, so the
+// dependency runs one way (ledger.js -> ledger-stats.js) and cannot cycle.
+// ledger.js re-exports all six, so no import path in the tree moved.
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('../utils/config');
+
+const LEDGER_FILE = 'council-ledger.jsonl';
+
+function readRows(dir) {
+  const file = path.join(dir, LEDGER_FILE);
+  if (!fs.existsSync(file)) { return []; }
+  return fs.readFileSync(file, 'utf-8').split('\n').map(l => l.trim()).filter(Boolean)
+    .map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+function avg(nums) { return nums.length ? nums.reduce((s, x) => s + x, 0) / nums.length : null; }
+
+/**
+ * v4.8 PR4b (R4b-1): `runs` counts distinct council RUNS, not ledger rows. One
+ * run on `--models a,a` is one appearance, not two — and that was true of every
+ * bench where one executable served more than one seat, pre-PR4b rows included
+ * (history self-corrects; the append-only file never blends two counting units).
+ *
+ * ⚠️ Spell the predicate literally: only a NON-EMPTY STRING runId is an
+ * identity. `runId: ''` is persistable and reaches disk verbatim on the
+ * hand-assembled tally path, and `runId: 0` is the mirror hazard — under a
+ * bare `if (r.runId)` or an `'runId' in r` both would silently collapse a
+ * whole history into ONE run, permanently, in a file that is never migrated.
+ * Anything that is not a non-empty string counts individually.
+ */
+function countRuns(rows) {
+  const ids = new Set();
+  let unkeyed = 0;
+  for (const r of rows) {
+    if (typeof r.runId === 'string' && r.runId) { ids.add(r.runId); } else { unkeyed += 1; }
+  }
+  return ids.size + unkeyed;
+}
+
+/**
+ * Aggregate the ledger per model. peersOnly nulls excluded; lowN flags < 3 runs
+ * (v4.8 PR4b R4b-1: `runs` is DISTINCT runIds — see countRuns).
+ * v4.7 GOA-7 D10: groups by `row.resolvedModel || row.model` — v2 rows segment
+ * by the executable id that actually served; rows without a resolvedModel
+ * (pre-v2 history, leg-less rows, hand-assembled tally input) stay alias-keyed
+ * with `legacy: true`. `aliases` lists every row-level `model` (alias) observed
+ * for the group, most recently observed FIRST — ledger append order is the only
+ * recency signal (`date` is day-granular, free-form on the MCP path), so
+ * aliases[0] is the launch-preferred name (pickFallbackChair, D11).
+ * Version-blind by design: schemaVersion is never read (legacy-read, R2).
+ */
+function deriveReliability(opts = {}) {
+  const dir = opts.dir || getConfigDir();
+  const byKey = new Map();
+  for (const row of readRows(dir)) {
+    const key = row.resolvedModel || row.model;
+    if (!byKey.has(key)) { byKey.set(key, []); }
+    byKey.get(key).push(row);
+  }
+  return [...byKey.entries()].map(([model, rows]) => {
+    const peers = rows.map(r => r.streetCredPeersOnly).filter(v => typeof v === 'number');
+    const confirms = rows.map(r => r.confirmRate).filter(v => typeof v === 'number');
+    const facts = rows.map(r => r.factErrorRate).filter(v => typeof v === 'number');
+    const conformance = rows.reduce((acc, r) => { acc[r.conformance] = (acc[r.conformance] || 0) + 1; return acc; }, {});
+    const lastSeen = new Map();
+    rows.forEach((r, i) => { lastSeen.set(r.model, i); });
+    const aliases = [...lastSeen.entries()].sort((a, b) => b[1] - a[1]).map(([m]) => m);
+    const runs = countRuns(rows);
+    return {
+      model, runs, lowN: runs < 3,
+      avgStreetCredPeersOnly: avg(peers),
+      lifetimeConfirmRate: avg(confirms),
+      lifetimeFactErrorRate: avg(facts),
+      conformance,
+      aliases,
+      ...(rows.every(r => !r.resolvedModel) ? { legacy: true } : {}),
+    };
+  });
+}
+
+/**
+ * v4.0 §7: wrap the deriveReliability() rows in the council v2 envelope —
+ * THE one sanctioned breaking shape change (`council stats --json` used to
+ * emit the bare array). Human rendering keeps consuming the bare rows.
+ * @param {Array<object>} models deriveReliability() output
+ * @returns {{schemaVersion: number, type: 'council-stats', models: Array<object>}}
+ */
+function buildStatsDoc(models) {
+  const { COUNCIL_SCHEMA_VERSION } = require('./tally');
+  return { schemaVersion: COUNCIL_SCHEMA_VERSION, type: 'council-stats', models };
+}
+
+module.exports = { LEDGER_FILE, readRows, avg, countRuns, deriveReliability, buildStatsDoc };