@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/report_obligation_mechanism.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * Per rule: is the obligation already carried by a mechanism, and is there a
+ * slot that could carry it?
+ *
+ * Step 1.5 of `road-to-rule-triggers-and-links-that-hold`. It joins three
+ * instruments that already exist and had never been read together:
+ *
+ *   · `check_enforcement_coverage --json` — the only place `enforced_by` and
+ *     `obligation_frequency` are already resolved per rule, including what the
+ *     declaration resolves TO (a wired validator, a bound hook, nothing).
+ *   · `report_obligation_carriers` — how many artifacts restate the same
+ *     obligation, which is a different question from whether one enforces it.
+ *   · The `# obligation: line N` frontmatter marker — 107 of 121 rules carry
+ *     one and nothing in the tree reads it, so this is its first reader.
+ *
+ * **Two columns, and conflating them would be the error worth avoiding.**
+ * `carried` is measured: a gate either refuses or it does not.
+ * `slot_exists` is NECESSARY, NEVER SUFFICIENT — it says a host event fires at
+ * the obligation's own frequency, so a carrier could at least be bound. It
+ * does not say the obligation is decidable from what that event sees, which is
+ * the actual question and is not answerable by a join. A rule whose body says
+ * `instruction-only` has usually already answered it in the other direction,
+ * and that answer is reproduced rather than overridden.
+ *
+ * Report only. Moving an obligation out of prose is a per-rule change with its
+ * own review, which this roadmap's scope section says in as many words.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// ledger-exempt: a REPORTER, not a gate. Its only non-zero exit says an input
+// instrument could not be run, which is a statement about the walk.
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** Frequencies a host event is known to fire at — the `slot_exists` test. */
+const EVENT_BOUND_FREQUENCIES: ReadonlySet<string> = new Set([
+    'per-edit',
+    'per-file-write',
+    'per-commit',
+    'per-turn',
+    'per-session',
+    'per-event',
+    'per-task',
+]);
+
+/** Resolutions where something can actually refuse. */
+const REFUSING: ReadonlySet<string> = new Set(['validator', 'validator-local', 'test', 'hook']);
+
+export interface MechanismRow {
+    rule: string;
+    tier: string;
+    marker_line: number | null;
+    frequency: string;
+    declared: number;
+    effective: string;
+    /** `gate` · `observer` · `declared-gap` · `undeclared`. */
+    carried: string;
+    /** A host event is known to fire at this frequency. Necessary, not sufficient. */
+    slot_exists: boolean;
+    /** Artifacts restating this rule's obligations, per the carrier census. */
+    restatements: number;
+}
+
+/** `# obligation: line N` inside the frontmatter block. */
+export function markerLine(content: string): number | null {
+    if (!content.startsWith('---')) return null;
+    const end = content.indexOf('\n---', 3);
+    const block = end === -1 ? content : content.slice(0, end);
+    const m = /^#\s*obligation:\s*line\s+(\d+)\s*$/m.exec(block);
+    return m ? Number.parseInt(m[1] as string, 10) : null;
+}
+
+function run(root: string, script: string, args: readonly string[]): string {
+    return execFileSync(path.join(root, 'scripts-run'), [script, ...args], {
+        cwd: root,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+}
+
+interface CoverageRule {
+    id: string;
+    tier?: string;
+    declared?: string[];
+    effective?: string;
+    obligation_frequency?: string | null;
+}
+
+export function rows(root: string): MechanismRow[] {
+    const coverage = JSON.parse(run(root, 'src/scripts/check_enforcement_coverage', ['--json'])) as {
+        rules: CoverageRule[];
+    };
+
+    run(root, 'src/scripts/report_obligation_carriers', ['--top', '1']);
+    const carriersPath = path.join(root, 'agents', 'runtime', 'reports', 'obligation-carriers.json');
+    const restatements = new Map<string, number>();
+    if (!fs.existsSync(carriersPath)) {
+        // Not a degradation to absorb: `agents/runtime/` is gitignored, so a
+        // fresh checkout reaches this, and a silent fallback would publish a
+        // uniformly-zero Restatements column with nothing saying it is empty.
+        // Every other input failure in this script exits 1; so does this one.
+        throw new Error(
+            `report_obligation_carriers wrote no census at ${carriersPath} — the ` +
+                'Restatements column would read 0 for every rule without saying so',
+        );
+    }
+    {
+        const census = JSON.parse(fs.readFileSync(carriersPath, 'utf8')) as {
+            rows: { carriers: { path: string; cls: string }[] }[];
+        };
+        for (const r of census.rows) {
+            // A row is one obligation; it counts for every RULE that carries it.
+            for (const c of r.carriers) {
+                if (c.cls !== 'rule') continue;
+                const id = path.basename(c.path, '.md');
+                restatements.set(id, (restatements.get(id) ?? 0) + r.carriers.length - 1);
+            }
+        }
+    }
+
+    const out: MechanismRow[] = [];
+    for (const r of coverage.rules) {
+        const file = path.join(root, 'src', 'rules', `${r.id}.md`);
+        const content = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+        const declared = r.declared ?? [];
+        const effective = r.effective ?? 'none';
+        const frequency = r.obligation_frequency ?? '—';
+
+        let carried: string;
+        if (REFUSING.has(effective)) carried = 'gate';
+        else if (effective === 'observer') carried = 'observer';
+        else if (declared.length > 0) carried = 'declared-gap';
+        else carried = 'undeclared';
+
+        out.push({
+            rule: r.id,
+            tier: r.tier ?? '—',
+            marker_line: markerLine(content),
+            frequency,
+            declared: declared.length,
+            effective,
+            carried,
+            slot_exists: EVENT_BOUND_FREQUENCIES.has(frequency),
+            restatements: restatements.get(r.id) ?? 0,
+        });
+    }
+    out.sort((a, b) => a.rule.localeCompare(b.rule));
+    return out;
+}
+
+export function renderTable(data: readonly MechanismRow[]): string[] {
+    const L: string[] = [];
+    L.push('| Rule | Tier | Marker | Frequency | `enforced_by` | Resolves to | Carried | Slot exists | Restatements |');
+    L.push('|---|---|---:|---|---:|---|---|---|---:|');
+    for (const r of data) {
+        L.push(
+            `| \`${r.rule}\` | ${r.tier} | ${r.marker_line === null ? '—' : String(r.marker_line)} | ` +
+                `${r.frequency} | ${String(r.declared)} | \`${r.effective}\` | ${r.carried} | ` +
+                `${r.slot_exists ? 'yes' : 'no'} | ${String(r.restatements)} |`,
+        );
+    }
+    return L;
+}
+
+const USAGE = 'usage: report_obligation_mechanism [--root DIR] [--json | --table]\n';
+
+export function main(): number {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    for (const a of argv) {
+        if (a.startsWith('-') && !['--root', '--json', '--table'].includes(a)) {
+            process.stderr.write(`unknown argument: ${a}\n${USAGE}`);
+            return 2;
+        }
+    }
+    const i = argv.indexOf('--root');
+    const root = i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : process.cwd();
+
+    let data: MechanismRow[];
+    try {
+        data = rows(root);
+    } catch (e) {
+        process.stderr.write(`could not read an input instrument: ${String(e)}\n`);
+        return 1;
+    }
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+        return 0;
+    }
+    if (argv.includes('--table')) {
+        process.stdout.write(`${renderTable(data).join('\n')}\n`);
+        return 0;
+    }
+
+    const by = (k: string): number => data.filter((r) => r.carried === k).length;
+    const slotNoGate = data.filter((r) => r.carried !== 'gate' && r.slot_exists).length;
+    process.stdout.write(
+        `${String(data.length)} rule(s)\n` +
+            `  carried by a gate that can refuse: ${String(by('gate'))}\n` +
+            `  carried by an observer (fires, never refuses): ${String(by('observer'))}\n` +
+            `  declared gap (the rule says instruction-only / none): ${String(by('declared-gap'))}\n` +
+            `  no enforcement declaration at all: ${String(by('undeclared'))}\n` +
+            `  not gated, but a host event fires at the obligation's frequency: ${String(slotNoGate)}\n` +
+            `  carry no \`# obligation: line N\` marker: ${String(data.filter((r) => r.marker_line === null).length)}\n`,
+    );
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/report_obligation_writer_split.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env tsx
+/**
+ * report_obligation_writer_split — which kind of tree wrote the obligation rows.
+ *
+ * WHAT QUESTION THIS ANSWERS, AND WHY IT NEEDED A TOOL.
+ * `obligation-settle-shadow-bar` is pre-registered against the shadow rows under
+ * `agents/runtime/state/obligations/`, and its own clause (7) says that corpus is
+ * one machine's runtime state. Until the rows carried a writer, that sentence was
+ * the ONLY place the fact lived: a reader holding the ledgers could count rows and
+ * could not separate them, so a reading that cleared the floor would have been
+ * quotable as evidence about a population nobody had measured. This prints the
+ * separation, from the rows themselves.
+ *
+ * IT REACHES NO VERDICT, AND THAT IS THE DESIGN. A split is an input to the corpus
+ * decision held in `road-to-an-obligation-row-that-names-its-writer`, not the
+ * decision — the three options there (accept the one-machine corpus and amend the
+ * bar, widen it deliberately, or file the window `resolved-null`) are owner-
+ * reserved, and all three name arming as owner-reserved too. So this exits 0 on
+ * every path, prints counts, and says nothing about whether anything may be armed.
+ * A reporter that graded the corpus would be handing the arming discussion a
+ * verdict wearing a number's clothes.
+ *
+ * `absent` IS REPORTED APART FROM `unknown`, and the distinction is load-bearing.
+ * `unknown` is a row whose writer WAS resolved and came back unresolvable; `absent`
+ * is a row written before the field existed. Folding them together would let the
+ * whole pre-field corpus read as "we looked and could not tell", which is a
+ * stronger claim than "we had not started looking". The ledger's own `parseRows`
+ * maps both to `unknown` — correct for a consumer that only needs a role — so this
+ * reads the JSON directly rather than through it, and uses `isWriterRole` for the
+ * vocabulary so the two cannot drift.
+ *
+ * PRIVACY, at the precision the code holds. Output is counts, plus the SCAN ROOT,
+ * which the caller supplied and which is the one thing a reader needs in order to
+ * know what was measured. Nothing else crosses: no session id, no ledger filename,
+ * no rule id, no timestamp. The scan reads those and keeps none of them.
+ *
+ * WRITES NOTHING. It opens files for reading and creates no directory, not even
+ * the ledger directory it looks for. A missing directory is a reported state, not
+ * a thing to fix.
+ *
+ * Exit: 0 always, except a usage error (1). Advisory — it gates nothing.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { OBLIGATION_STATE_DIR, WRITER_ROLES, isWriterRole } from './_lib/obligations.js';
+
+/** The reported classes: the closed vocabulary, plus the pre-field case. */
+export const REPORTED_CLASSES = [...WRITER_ROLES, 'absent'] as const;
+export type ReportedClass = (typeof REPORTED_CLASSES)[number];
+
+/** The three row arrays a ledger carries, named as the file names them. */
+export const ROW_ARRAYS = ['delivered', 'discharged', 'shadow'] as const;
+export type RowArray = (typeof ROW_ARRAYS)[number];
+
+export type Tally = Record<ReportedClass, number>;
+
+export interface WriterSplit {
+    /** The directory scanned, echoed so a reader knows what was measured. */
+    readonly store: string;
+    /** `false` when the ledger directory does not exist at all. */
+    readonly storeExists: boolean;
+    /** Ledger files opened and parsed. */
+    readonly ledgers: number;
+    /** Files present but unreadable or unparseable — reported, never silently dropped. */
+    readonly unreadable: number;
+    /** Per row array, the split by writer class. */
+    readonly byArray: Record<RowArray, Tally>;
+    /** Every array folded together. */
+    readonly total: Tally;
+}
+
+function emptyTally(): Tally {
+    return { package: 0, consumer: 0, unknown: 0, absent: 0 };
+}
+
+/**
+ * Classify one row's writer field.
+ *
+ * A field that is missing entirely is `absent`. A field that is present but
+ * outside the closed vocabulary is `unknown`, matching `parseRows`: a corrupt
+ * provenance label degrades, it never deletes the record of a real row.
+ */
+export function classifyRow(row: unknown): ReportedClass {
+    if (typeof row !== 'object' || row === null) return 'absent';
+    if (!('writer' in row)) return 'absent';
+    const writer = (row as { writer: unknown }).writer;
+    return isWriterRole(writer) ? writer : 'unknown';
+}
+
+/** Tally one ledger's arrays into an accumulator. */
+function tallyLedger(doc: unknown, into: Record<RowArray, Tally>): void {
+    if (typeof doc !== 'object' || doc === null) return;
+    for (const name of ROW_ARRAYS) {
+        const rows = (doc as Record<string, unknown>)[name];
+        if (!Array.isArray(rows)) continue;
+        for (const row of rows) into[name][classifyRow(row)] += 1;
+    }
+}
+
+/**
+ * Read every ledger under `root` and split its rows by writer class.
+ *
+ * Opens files for reading only. A file that will not parse increments
+ * `unreadable` rather than being skipped in silence — a corpus with unreadable
+ * members is a different corpus from a clean one, and a reader deciding whether
+ * a sample floor is met needs to know which they have.
+ */
+export function readWriterSplit(root: string): WriterSplit {
+    const store = path.join(root, OBLIGATION_STATE_DIR);
+    const byArray: Record<RowArray, Tally> = {
+        delivered: emptyTally(),
+        discharged: emptyTally(),
+        shadow: emptyTally(),
+    };
+
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(store).filter((f) => f.endsWith('.json'));
+    } catch {
+        return { store, storeExists: false, ledgers: 0, unreadable: 0, byArray, total: emptyTally() };
+    }
+
+    let ledgers = 0;
+    let unreadable = 0;
+    for (const entry of entries) {
+        let doc: unknown;
+        try {
+            doc = JSON.parse(fs.readFileSync(path.join(store, entry), 'utf-8'));
+        } catch {
+            unreadable += 1;
+            continue;
+        }
+        ledgers += 1;
+        tallyLedger(doc, byArray);
+    }
+
+    const total = emptyTally();
+    for (const name of ROW_ARRAYS) {
+        for (const cls of REPORTED_CLASSES) total[cls] += byArray[name][cls];
+    }
+    return { store, storeExists: true, ledgers, unreadable, byArray, total };
+}
+
+const sum = (t: Tally): number => REPORTED_CLASSES.reduce((n, c) => n + t[c], 0);
+
+/**
+ * Render the split as text.
+ *
+ * The line a reader is most likely to quote is the shadow row, so it is named
+ * rather than left to be inferred from a table: the pre-registered bar counts
+ * shadow rows and nothing else, and a split over `delivered` answers a question
+ * the bar did not ask.
+ */
+export function render(split: WriterSplit): string {
+    const out: string[] = [];
+    out.push(`scanned: ${split.store}`);
+    if (!split.storeExists) {
+        out.push('  the ledger directory does not exist — nothing was measured.');
+        out.push('  This is not a reading of zero. It is the absence of a corpus.');
+        return `${out.join('\n')}\n`;
+    }
+    out.push(`  ledgers: ${split.ledgers}${split.unreadable > 0 ? `, unreadable: ${split.unreadable}` : ''}`);
+    if (split.ledgers === 0) {
+        out.push('  no ledger files — the directory exists and holds nothing.');
+        return `${out.join('\n')}\n`;
+    }
+
+    const width = Math.max(...ROW_ARRAYS.map((n) => n.length));
+    out.push('');
+    out.push(`${'rows'.padEnd(width)}  ${REPORTED_CLASSES.map((c) => c.padStart(9)).join('')}    total`);
+    for (const name of ROW_ARRAYS) {
+        const t = split.byArray[name];
+        const cells = REPORTED_CLASSES.map((c) => String(t[c]).padStart(9)).join('');
+        out.push(`${name.padEnd(width)}  ${cells}  ${String(sum(t)).padStart(7)}`);
+    }
+    const cells = REPORTED_CLASSES.map((c) => String(split.total[c]).padStart(9)).join('');
+    out.push(`${'all'.padEnd(width)}  ${cells}  ${String(sum(split.total)).padStart(7)}`);
+
+    out.push('');
+    out.push(
+        `shadow rows — the only array the pre-registered bar counts: ${sum(split.byArray.shadow)}`,
+    );
+    out.push(
+        '`absent` is a row written before the writer field existed; `unknown` is a row whose',
+    );
+    out.push('writer was resolved and came back unresolvable. They are not the same reading.');
+    out.push('');
+    out.push('This is a split, not a verdict. Whether the corpus is fit to read the bar off,');
+    out.push('and what follows for the detector, are owner decisions this tool does not make.');
+    return `${out.join('\n')}\n`;
+}
+
+/**
+ * Read one flag's value, refusing a flag whose value is missing.
+ *
+ * A flag present as the last argv element must be a usage error and never a
+ * silent fall back to the default. The same slip in a sibling reporter measured
+ * the DEFAULT corpus while printing what read as a settled number — a confident
+ * figure from a tree nobody asked for is worse than no figure at all.
+ */
+function argValue(argv: string[], flag: string, fallback: string): string {
+    const i = argv.indexOf(flag);
+    if (i === -1) return fallback;
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+        process.stderr.write(`report_obligation_writer_split: ${flag} needs a value\n`);
+        process.exit(1);
+    }
+    return value;
+}
+
+export function main(argv: string[]): number {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(
+            'usage: report_obligation_writer_split [--root <dir>] [--json]\n\n' +
+                '  --root <dir>  tree whose agents/runtime/state/obligations/ to read (default: cwd)\n' +
+                '  --json        emit the split as JSON instead of text\n\n' +
+                'Read-only. Writes nothing, gates nothing, exits 0.\n',
+        );
+        return 0;
+    }
+    const root = argValue(argv, '--root', process.cwd());
+    const split = readWriterSplit(root);
+    process.stdout.write(argv.includes('--json') ? `${JSON.stringify(split, null, 2)}\n` : render(split));
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(_HERE)) {
+    process.exit(main(process.argv.slice(2)));
+}