@event4u/agent-config 14.0.0 → 14.2.0

package/src/scripts/_lib/skill_catalogue_series.ts

@@ -409,3 +409,94 @@ export function formatPointableBare(
     }
     return lines.join('\n');
 }
+
+/* ------------------------------------------------------------------ *
+ * The delivery filter — what the runtime router must not name.
+ * ------------------------------------------------------------------ */
+
+/**
+ * The bare names one host is KNOWN to have delivered, or `null` when nothing
+ * about that host's per-entry delivery was ever enumerated.
+ *
+ * `joinPointableBare` above answers "how large is the D-4 divergence" for an
+ * operator report. This answers the runtime question the same log can settle:
+ * given this host, which skill names must a pointer line not name? It is the
+ * reducer `skill_route_hook` consumes, and it lives here rather than in that
+ * hook for one reason — every guard below is already argued in this module's
+ * prose, and a second reducer over the same log is how two readers start
+ * breaking the same tie in opposite directions (`_supersedes`, in the parent
+ * module, exists because that happened once and printed two drop counts for one
+ * host on one day).
+ *
+ * THE THREE-WAY DISTINCTION IS THE WHOLE POINT, and collapsing any two of them
+ * is the failure:
+ *
+ *   - **`null` — nothing was enumerated.** No record for this host, or none of
+ *     its records is a `per-entry` observation, or the latest one carries no
+ *     `bare_names` array. The consumer must fail OPEN: filtering on this would
+ *     be a zero inferred from silence, and a filter that quietly narrows on
+ *     missing data is worse than the divergence it treats.
+ *   - **An EMPTY set — enumerated, and nothing was bare.** A legitimate answer,
+ *     and behaviourally identical to `null` at today's only consumer. It is
+ *     still returned distinctly, because "measured clean" and "never measured"
+ *     are different facts and this module refuses to let them look alike.
+ *   - **A NON-EMPTY set — these names went dark.** The pointer must not name
+ *     them.
+ *
+ * A `budget-strip-and-drop` host is therefore always `null` here, never an
+ * empty set: it publishes no per-entry list at all, so its empty `bare_names`
+ * records that nothing was counted. That is the same skip `joinPointableBare`
+ * makes, for the same reason, and it is why a codex install gets no filtering
+ * rather than a filter that believes nothing was degraded.
+ *
+ * LATEST WINS, per host, by `observed_at` — the `latestPointableBarePerHost`
+ * tie-break rather than a union across the series. A union would let a
+ * superseded observation keep suppressing a skill the host now delivers fine,
+ * which is a filter that only ever narrows; the whole series is available to an
+ * operator report, and a runtime filter wants the current reading.
+ *
+ * `bare_names` is guarded with `Array.isArray`, and `observed_at` with a
+ * `typeof` check, because `readObservationLog` produces records by an unchecked
+ * `JSON.parse … as` over an append-only log with more than one producer — the
+ * same guard, for the same recorded reason, that `joinPointableBare` and
+ * `knownHostLimits` carry. Both guards resolve to `null`, never to an older
+ * reading: a malformed LATEST record means the current state is unknown, and
+ * falling back to a superseded one would be the stale-suppression failure this
+ * function's own tie-break exists to prevent.
+ */
+export function knownBareNames(
+    records: readonly ObservationRecord[],
+    host: string,
+): Set<string> | null {
+    // The latest record for the host decides, and the mode is read OFF that
+    // record rather than used to select it. R2 finding 2: filtering `per-entry`
+    // first meant a NEWER `budget-strip-and-drop` record could never supersede
+    // an older `per-entry` one, so a host that changed truncation mode kept
+    // being filtered against a bare set from before the change — the precise
+    // failure the LATEST-WINS paragraph above claims to prevent.
+    //
+    // `headlineRecordPerHost` rather than a fourth inline tie-break (R2 finding
+    // 7): this module already imports it, already defines
+    // `latestPointableBarePerHost`, and its own comment cites `_supersedes` as
+    // the reason duplicate reducers are dangerous. Restating the rule here would
+    // have meant the runtime filter silently not inheriting any precedence the
+    // parent adds later.
+    //
+    // The `observed_at` pre-filter is R2 finding 6, and it is a pre-filter
+    // rather than a change to `_supersedes` because that reducer is shared.
+    // `_supersedes` compares dates with `!==` then `>`, and BOTH
+    // `undefined > "2026-08-12"` and `"2026-08-12" > undefined` are false — so a
+    // record with a missing or non-string date, once it becomes the incumbent,
+    // can never be displaced by a well-formed later one. One malformed line in
+    // an append-only log with two producers would pin the filter to it forever.
+    // Feeding the shared reducer only well-dated records avoids that without
+    // changing behaviour for its other callers.
+    const dated = records.filter(
+        (record) => record.host === host && typeof record.observed_at === 'string',
+    );
+    const latest = headlineRecordPerHost(dated).get(host);
+    if (latest === undefined) return null;
+    if (truncationModeOf(latest) !== 'per-entry') return null;
+    if (!Array.isArray(latest.bare_names)) return null;
+    return new Set(latest.bare_names.filter((name): name is string => typeof name === 'string'));
+}

package/src/scripts/build_archive_index.ts

@@ -45,6 +45,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 import { parse_frontmatter } from './validate_frontmatter.js';
 
@@ -217,12 +218,24 @@ export function archiveFiles(dir: string): string[] {
         .sort();
 }
 
-export function buildIndex(dir: string): ArchiveEntry[] {
-    return archiveFiles(dir).map((name) =>
+/**
+ * Build entries from an enumeration the CALLER already performed.
+ *
+ * Split out so the ledger's plan and the results can come from ONE walk. With
+ * two walks, a file created between them reports as a skip that never happened
+ * and a file deleted between them yields an entry that was never planned — the
+ * plan would describe a different directory state than the results.
+ */
+export function buildIndexFrom(dir: string, names: readonly string[]): ArchiveEntry[] {
+    return names.map((name) =>
         buildEntry(name.replace(/\.md$/, ''), fs.readFileSync(path.join(dir, name), 'utf8')),
     );
 }
 
+export function buildIndex(dir: string): ArchiveEntry[] {
+    return buildIndexFrom(dir, archiveFiles(dir));
+}
+
 /** Table-cell text: pipes escaped, newlines flattened, never empty. */
 function _cell(value: string | null): string {
     if (value === null) {
@@ -309,7 +322,44 @@ export function main(argv: readonly string[]): number {
     const quiet = argv.includes('--quiet');
     const dir = path.join(ROOT, ARCHIVE_REL);
 
-    const entries = buildIndex(dir);
+    // ONE walk feeds both the plan and the results.
+    //
+    // Planning the result set and completing it in the next statement would make
+    // `planned === completed, skipped=0` true by construction — an accounting
+    // line that can never report anything. Planning a SECOND walk is only
+    // marginally better: it describes a directory state the results did not come
+    // from. Enumerating once and passing that list into the builder makes the
+    // gap real — the natural future fix for an unreadable archive file is a
+    // `try/catch { continue }` in the builder, and that file then shows up here
+    // as a skip instead of vanishing.
+    //
+    // `not-extractable` is a real reading rather than a skip and therefore
+    // completes — but a frontmatter PARSE failure is swallowed by `_frontmatter`
+    // and zeroes title/verdict/status, which is a genuine per-target degrade the
+    // disposition tally cannot show. Both are visible here as the difference
+    // between the planned and completed sets.
+    const walked = archiveFiles(dir);
+    const entries = buildIndexFrom(dir, walked);
+    const planned = walked.map((f) => path.basename(f, '.md'));
+    const produced = new Set(entries.map((e) => e.slug));
+    const ledger = new GateLedger('build_archive_index');
+    ledger.plan(planned);
+    for (const slug of planned) {
+        // `check_did_not_run`, not `no_applicable_files`: the file IS one the
+        // check applies to — the entry build did not produce a reading for it.
+        if (produced.has(slug)) ledger.complete(slug);
+        else ledger.skip(slug, 'check_did_not_run');
+    }
+    // A produced entry outside the plan means the two sets came apart despite
+    // the single walk; the ledger would under-state the denominator silently.
+    const unplanned = [...produced].filter((s) => !planned.includes(s));
+    if (unplanned.length > 0) {
+        throw new Error(
+            `build_archive_index: ${String(unplanned.length)} entry/entries were produced but never ` +
+                `planned (${unplanned.slice(0, 5).join(', ')}) — the ledger denominator is wrong.`,
+        );
+    }
+
     try {
         reportScanned({
             gate: 'build_archive_index',
@@ -325,6 +375,15 @@ export function main(argv: readonly string[]): number {
         throw err;
     }
 
+    // Reported before the `--check` and write paths branch, so both publish the
+    // same accounting. NOT on all three: the earliest exit — `reportScanned`
+    // throwing `DeadScopeError` on an empty walk — returns above this line and
+    // reports nothing, which is the one exit where the accounting would say the
+    // most. Left as-is rather than papered over: the ledger has no targets to
+    // report there either, and moving it above the scope assertion would publish
+    // a plan for a root the assertion is about to reject.
+    ledger.report();
+
     const mdPath = path.join(dir, INDEX_MD);
     const jsonPath = path.join(dir, INDEX_JSON);
     const md = renderMarkdown(entries);

package/src/scripts/check_gate_coverage.ts

@@ -50,6 +50,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as yaml from 'js-yaml';
 import { checkRatchet } from './_lib/gate_baseline.js';
+import { GateLedger, type GateSkipReason } from './_lib/gate_ledger.js';
 import { runCountedProbe } from './_lib/counted_probe.js';
 import { listGateScripts } from './_lib/gate_population.js';
 import { describeOutcome, namesEstateInvalidatingError } from './_lib/gate_result.js';
@@ -187,6 +188,59 @@ export function parse_scanned(output: string): number | null {
   return m === null ? null : Number(m[1]);
 }
 
+/**
+ * Map a gate verdict onto its ledger outcome.
+ *
+ * Extracted and exported so the mapping can be PINNED — it was inline, and the
+ * completion review's three sharpest findings were all mis-mappings that a
+ * discrimination test would have caught in one line each.
+ *
+ * The split is INSPECTED vs NOT INSPECTED, never pass vs fail. `fail` counts
+ * into the ledger's `scanned=` (`report()` sets `checked = completed + failed`),
+ * so a target that could not be READ must never land there — that inflates the
+ * exact number the library exists to make trustworthy. This file's own comment
+ * already says a gate that could not MEASURE "is not a gate that found
+ * violations, and it is not a gate that passed either"; this agrees with it.
+ */
+export function ledgerOutcomeFor(
+  verdict: GateResult['verdict'],
+): 'complete' | 'fail' | GateSkipReason {
+  switch (verdict) {
+    case 'pending':
+      return 'disabled_by_configuration';
+    case 'unavailable':
+      // NOT `missing_credentials`. The only manifest row carrying
+      // `unavailable_exit` is unavailable for an unbuilt `site/dist`, and the
+      // skip sentence IS the audit surface — naming a credential would send the
+      // reader hunting an unset token instead of running the build.
+      return 'no_applicable_files';
+    case 'crashed':
+      // NOT `dead_scan_root` — a gate that threw has no dead root, and the skip
+      // sentence would send the reader to check a scan path that is fine. The
+      // vocabulary was extended rather than approximated, same reasoning as the
+      // `unavailable` case above.
+      return 'check_did_not_run';
+    case 'estate_invalid':
+      // Nothing was read here either. `crashed` still reds the build through
+      // this gate's own filter and `estate_invalid` deliberately does not, but
+      // neither belongs in the inspected count.
+      return 'dead_scan_root';
+    case 'silent':
+    case 'below_floor':
+      return 'fail';
+    case 'ok':
+      return 'complete';
+    default: {
+      // Exhaustiveness guard. A `Verdict` member added later must be classified
+      // deliberately: without this, a new member would silently count as
+      // INSPECTED and both the switch and its test would stay green —
+      // re-creating the over-report this function was extracted to pin.
+      const unhandled: never = verdict;
+      throw new Error(`ledgerOutcomeFor: unhandled verdict ${String(unhandled)}`);
+    }
+  }
+}
+
 /** Classify one gate's run against its declared floor. Pure — testable without
  * spawning anything. */
 export function classify(
@@ -323,6 +377,31 @@ export function main(argv: readonly string[]): number {
     return 0;
   }
 
+  // Per-target accounting over the manifest rows. The gate that audits gate
+  // coverage was itself unaudited.
+  //
+  // Stated precisely, because the obvious justification overstates it: this gate
+  // ALREADY prints counted `pending N · unavailable N` warnings, so those two
+  // classes were not invisible. What the ledger adds is that they are expressed
+  // in the estate-wide vocabulary every other adopter uses, so a reader
+  // comparing gates does not have to learn this one's private status names — and
+  // that `crashed` and `estate_invalid`, which had no counted line at all, stop
+  // being counted as inspected.
+  //
+  // Note the two numbers this produces in one run: the ledger's `scanned=` (what
+  // was inspected) and the contract line `scanned:` (manifest rows read). They
+  // differ by the skips and that is correct, but only the latter is what
+  // `SCANNED_RE` parses.
+  const ledger = new GateLedger('check_gate_coverage');
+  // Deduplicated on purpose. `load_manifest` does not check id uniqueness, and a
+  // copy-pasted row with a forgotten rename would otherwise make `plan()` throw
+  // an uncaught LedgerUsageError — surfacing a manifest mistake as a stack trace
+  // and Node's exit 1, which this file's own contract reads as "a gate is blind,
+  // collapsed, or silent" rather than as the exit 2 a malformed manifest earns.
+  // The duplicate still runs twice and still prints twice; only the accounting
+  // refuses to double-count it.
+  ledger.plan([...new Set(specs.map((s) => s.id))]);
+
   const results = specs.map((s) => {
     if (spec_is_pending(s)) {
       const { scanned, crashed } = probe_pending(s);
@@ -332,6 +411,20 @@ export function main(argv: readonly string[]): number {
     return classify(s, scanned, crashed, exit_code, output);
   });
 
+  // `recorded` pairs with the deduplicated plan above: a duplicated manifest id
+  // must be accounted once, and recording it twice would raise the same
+  // LedgerUsageError the dedupe exists to avoid.
+  const recorded = new Set<string>();
+  for (const r of results) {
+    if (recorded.has(r.id)) continue;
+    recorded.add(r.id);
+    const outcome = ledgerOutcomeFor(r.verdict);
+    if (outcome === 'complete') ledger.complete(r.id);
+    else if (outcome === 'fail') ledger.fail(r.id, r.message);
+    else ledger.skip(r.id, outcome);
+  }
+  ledger.report();
+
   if (wantJson) {
     process.stdout.write(`${JSON.stringify({ generated_by: 'check_gate_coverage', results }, null, 2)}\n`);
   } else {

package/src/scripts/check_pr_ci_current.ts

@@ -34,12 +34,29 @@
  * Exit codes (contract §6): 0 = current, or unobservable-and-said-so ·
  * 1 = the remote answered and the verdict is not about the branch head ·
  * 2 = internal error. `scanned:` is emitted on EVERY exit path.
+ *
+ * ## The per-target ledger, and the exemption that was withdrawn
+ *
+ * This gate first shipped with a `// ledger-exempt:` marker arguing it had "no
+ * target population to account for — a short-circuiting chain of 0-3 remote
+ * facts". Its completion review refuted that from the file itself: the check
+ * rows ARE a population, and the parse below **drops** every row whose `state`
+ * is not a string. A dropped row could be the failing one, so the gate could
+ * print *"green on its own head"* over a check it never read — the precise
+ * "absence of scanning looks like absence of findings" shape the ledger exists
+ * to count.
+ *
+ * The exemption's secondary claim was accurate — every `main()` exit already
+ * self-reports through `scanReport` with an explicit `allowEmpty` reason — and
+ * that is exactly why the first argument was easy to believe. It was still
+ * resting on the false half.
  */
 
 import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { reportScanned } from './_lib/scan_scope.js';
 
 const NETWORK_TIMEOUT_MS = 8_000;
@@ -117,6 +134,12 @@ export interface Facts {
     /** The head SHA the reported checks ran against. */
     checksHead: string | null;
     rows: readonly CheckRow[];
+    /**
+     * Names of check rows the parse DROPPED because their `state` was not a
+     * string. Carried out rather than swallowed: a dropped row could be the
+     * failing one, so it is a skip the ledger must count, not a non-event.
+     */
+    droppedRows?: readonly string[];
     /** Set when something could not be observed; forces the degrade path. */
     unobservable: string | null;
     /**
@@ -235,6 +258,51 @@ export function decide(f: Facts, opts: DecideOptions = {}): Verdict {
     };
 }
 
+/**
+ * Whether {@link decide} reached the check rows at all.
+ *
+ * Every branch above the row logic — unobservable, no open PR, behind/diverged,
+ * ahead — settles the verdict WITHOUT reading a single row state. Recording
+ * those rows as `complete` would publish `scanned=N` for a run that inspected
+ * none of them: the absence-of-scanning-reads-as-absence-of-findings inflation
+ * the ledger exists to count, in the gate that adopted it. Under `--pre-push`,
+ * `ahead` is the NORMAL state, so this is the common path, not the exotic one.
+ */
+export function rowsWereEvaluated(f: Facts): boolean {
+    if (f.unobservable !== null) return false;
+    if (f.pr === null) return false;
+    return f.relation !== 'behind' && f.relation !== 'diverged' && f.relation !== 'ahead';
+}
+
+/**
+ * Publish the row-level accounting for one run.
+ *
+ * Three populations, three outcomes: rows the parse dropped are skips (a dropped
+ * row could be the failing one), rows a row-reading verdict covered are
+ * completions, and rows the verdict never reached are out of scope for THIS run.
+ *
+ * The line is emitted even under `--quiet` — {@link GateLedger.report} writes
+ * unconditionally by design, so a `--quiet` run of this gate is one line louder
+ * than before. Stated here because it is a change to this gate's own contract.
+ */
+function reportRowLedger(f: Facts): void {
+    const ledger = new GateLedger('check_pr_ci_current');
+    const dropped = new Set(f.droppedRows ?? []);
+    // Duplicate check names are a normal remote condition — a cancelled re-run
+    // beside a live one, two workflows sharing a job name, or a dropped row
+    // whose name equals a kept row's. `plan` throws on a repeat, and this gate
+    // promises to degrade rather than block, so the plan is deduplicated.
+    const planned = [...new Set([...f.rows.map((r) => r.name), ...dropped])];
+    ledger.plan(planned);
+    const evaluated = rowsWereEvaluated(f);
+    for (const name of planned) {
+        if (dropped.has(name)) ledger.skip(name, 'not_applicable_kind');
+        else if (evaluated) ledger.complete(name);
+        else ledger.outOfScope(name, 'precondition_unmet');
+    }
+    ledger.report();
+}
+
 /**
  * Ancestry between the local tip and the PR head.
  *
@@ -261,7 +329,7 @@ export function relate(
 /** Gather the facts `decide` consumes. Every failure becomes `unobservable`. */
 export function gather(repo: string): Facts {
     const empty: Facts = {
-        pr: null, prHead: null, localHead: null, checksHead: null, rows: [], unobservable: null, relation: 'unknown',
+        pr: null, prHead: null, localHead: null, checksHead: null, rows: [], droppedRows: [], unobservable: null, relation: 'unknown',
     };
 
     const branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], repo);
@@ -296,9 +364,19 @@ export function gather(repo: string): Facts {
     // with parseable stdout is DATA, not an error. Treating it as unobservable
     // would make the gate blind in exactly the red case it exists for.
     let rows: CheckRow[] = [];
+    // A row whose `state` is not a string is DROPPED, and that drop is the one
+    // thing in this gate worth counting: a dropped row could be the failing one,
+    // and without accounting the gate prints "green on its own head" over a
+    // check it never read. `dropped` is surfaced by the caller through the
+    // ledger rather than swallowed here.
+    let dropped: string[] = [];
     if (checks.stdout.trim() !== '') {
         try {
-            rows = (JSON.parse(checks.stdout) as CheckRow[]).filter((r) => typeof r.state === 'string');
+            const parsed = JSON.parse(checks.stdout) as CheckRow[];
+            rows = parsed.filter((r) => typeof r.state === 'string');
+            dropped = parsed
+                .filter((r) => typeof r.state !== 'string')
+                .map((r, i) => (typeof r.name === 'string' ? r.name : `row-${String(i)}`));
         } catch {
             rows = [];
         }
@@ -329,6 +407,7 @@ export function gather(repo: string): Facts {
         localHead: localSha,
         checksHead: runsHead.ok && runsHead.stdout.trim() !== '' ? runsHead.stdout.trim() : null,
         rows,
+        droppedRows: dropped,
         unobservable: null,
         relation: relate(repo, localSha, prSha),
     };
@@ -374,7 +453,11 @@ export function main(argv?: readonly string[]): number {
 
     let verdict: Verdict;
     try {
-        verdict = decide(gather(repo), { prePush });
+        const facts = gather(repo);
+        // The verdict comes FIRST: whether the rows were inspected at all is a
+        // property of the verdict's path, not of the parse (see reportRowLedger).
+        verdict = decide(facts, { prePush });
+        reportRowLedger(facts);
     } catch (exc) {
         scanReport(0, 'internal error — nothing was compared');
         process.stderr.write(