@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/check_egress_mutations.ts

@@ -0,0 +1,239 @@
+#!/usr/bin/env tsx
+/**
+ * The egress engine's invariants survive no listed mutation
+ * (road-to-one-detector-and-the-senders-we-own 2.6).
+ *
+ * Every recipe under `src/config/egress-mutations/` names one engine module, a
+ * `find` text that must occur in it exactly once, its `replace`, and the
+ * invariant that must kill it. For each recipe the three engine modules
+ * (`egress_rules`, `egress_token`, `egress_text`) are copied into a scratch
+ * directory — never edited in place — and the invariant is run twice: on the
+ * unmutated copy, where it must hold, and on the mutated copy, where it must
+ * fail. A recipe whose mutation survives, whose `find` text is gone, or whose
+ * invariant fails on the unmutated engine fails the gate.
+ *
+ * Exit: 0 every mutation killed · 1 a mutation survived or a recipe is stale.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import type * as Rules from './_lib/egress_rules.js';
+import type * as Text from './_lib/egress_text.js';
+import type * as Token from './_lib/egress_token.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const GATE = 'check_egress_mutations';
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const RECIPE_DIR = 'src/config/egress-mutations';
+export const ENGINE_MODULES: readonly string[] = [
+    'src/scripts/_lib/egress_rules.ts',
+    'src/scripts/_lib/egress_token.ts',
+    'src/scripts/_lib/egress_text.ts',
+];
+
+export interface Recipe {
+    readonly mutation: string;
+    readonly module: string;
+    readonly find: string;
+    readonly replace: string;
+    readonly killed_by: string;
+}
+
+interface EngineMods {
+    readonly rules: typeof Rules;
+    readonly token: typeof Token;
+    readonly text: typeof Text;
+}
+
+// Built at runtime so no credential literal sits in this file.
+const PAT = ['ghp', 'Qw3Er5Ty7Ui9Op2As4Df6Gh8Jk1Lz3Xc5Vb7'].join('_');
+// The registry's own example IBAN, and the same digits under a wrong check pair.
+const IBAN_BODY = '370400440532013000';
+
+/** Each returns true when the invariant holds on the engine it is given. */
+export const INVARIANTS: Readonly<Record<string, (m: EngineMods) => boolean>> = {
+    'credential-outranks-identifier': (m) => {
+        const kept = m.rules.resolveOverlaps([
+            { rule: 'id', type: 'EMAIL', class: 'identifier', start: 0, end: 20, validated: true },
+            { rule: 'cred', type: 'TOKEN', class: 'credential', start: 5, end: 10, validated: false },
+        ]);
+        return kept.length === 1 && kept[0]?.class === 'credential';
+    },
+    'credential-token-never-restores': (m) => {
+        const scope = new m.token.TokenScope();
+        const out = m.token.replaceValues(`key ${PAT} here`, scope);
+        const tokens = m.token.parseTokens(out);
+        return tokens.length === 1 && tokens.every((t) => scope.resolve(out.slice(t.start, t.end)) === null);
+    },
+    'iban-checksum-refuses-a-wrong-check-digit': (m) => {
+        const wrong = `DE88${IBAN_BODY}`;
+        return (
+            m.rules.isValidIban(`DE89${IBAN_BODY}`) &&
+            !m.rules.isValidIban(wrong) &&
+            !m.rules.detect(`IBAN ${wrong}`).some((s) => s.type === 'IBAN')
+        );
+    },
+    'tally-carries-no-value': (m) => {
+        const tally = m.text.tallyText(`key ${PAT} here`);
+        return tally.found.length === 1 && !JSON.stringify(tally).includes(PAT);
+    },
+};
+
+export function readRecipes(root: string): Recipe[] {
+    const dir = path.join(root, RECIPE_DIR);
+    if (!fs.existsSync(dir)) return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.json'))
+        .sort()
+        .map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8')) as Recipe);
+}
+
+async function loadEngine(root: string, mutate?: Recipe): Promise<EngineMods> {
+    // The copies sit in one flat directory, so the engine's import closure must
+    // be exactly ENGINE_MODULES; a sibling import would not resolve there and
+    // would read as "invariant fails on the unmutated engine".
+    const copied = new Set(ENGINE_MODULES.map((rel) => path.basename(rel).replace(/\.ts$/, '.js')));
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'egress-mutation-'));
+    try {
+        for (const rel of ENGINE_MODULES) {
+            let src = fs.readFileSync(path.join(root, rel), 'utf-8');
+            for (const m of src.matchAll(/from\s+'(\.\.?\/[^']+)'/g)) {
+                const spec = m[1] as string;
+                if (!spec.startsWith('./') || !copied.has(spec.slice(2))) {
+                    throw new Error(`${rel} imports ${spec}, which is outside the copied engine modules — add it to ENGINE_MODULES`);
+                }
+            }
+            if (mutate !== undefined && rel === mutate.module) src = src.replace(mutate.find, () => mutate.replace);
+            fs.writeFileSync(path.join(tmp, path.basename(rel)), src);
+        }
+        const at = (name: string): string => pathToFileURL(path.join(tmp, name)).href;
+        return {
+            rules: (await import(at('egress_rules.ts'))) as EngineMods['rules'],
+            token: (await import(at('egress_token.ts'))) as EngineMods['token'],
+            text: (await import(at('egress_text.ts'))) as EngineMods['text'],
+        };
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+const holds = (inv: (m: EngineMods) => boolean, m: EngineMods): boolean => {
+    try {
+        return inv(m);
+    } catch {
+        return false;
+    }
+};
+
+/** One finding per recipe that does not do its job; empty when every mutation is killed. */
+export async function findSurvivors(root: string, recipes: readonly Recipe[]): Promise<string[]> {
+    const out: string[] = [];
+    for (const r of recipes) {
+        const inv = INVARIANTS[r.killed_by];
+        if (inv === undefined) {
+            out.push(`${r.mutation}: no invariant named ${r.killed_by}`);
+            continue;
+        }
+        if (!ENGINE_MODULES.includes(r.module)) {
+            out.push(`${r.mutation}: ${r.module} is not an engine module`);
+            continue;
+        }
+        const src = fs.readFileSync(path.join(root, r.module), 'utf-8');
+        if (src.split(r.find).length !== 2) {
+            out.push(`${r.mutation}: its find text does not occur exactly once in ${r.module} — the recipe is stale`);
+            continue;
+        }
+        if (!holds(inv, await loadEngine(root))) {
+            out.push(`${r.mutation}: ${r.killed_by} fails on the unmutated engine`);
+            continue;
+        }
+        if (holds(inv, await loadEngine(root, r))) out.push(`${r.mutation}: survived — ${r.killed_by} still holds`);
+    }
+    return out;
+}
+
+export async function check(root: string): Promise<number> {
+    const recipes = readRecipes(root);
+    reportScanned({ gate: GATE, scanned: recipes.length, units: 'mutation recipe(s)', roots: [RECIPE_DIR] });
+    const survivors = await findSurvivors(root, recipes);
+    if (survivors.length > 0) {
+        process.stderr.write(`❌  ${GATE}: a mutation of the egress engine was not killed:\n`);
+        for (const s of survivors) process.stderr.write(`  · ${s}\n`);
+        return 1;
+    }
+    process.stdout.write(`✅  ${GATE}: every mutation killed (${String(recipes.length)} recipe(s)).\n`);
+    return 0;
+}
+
+function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'egress-mutations-selftest-'));
+    const fixture = (name: string, recipes: readonly Recipe[]): string => {
+        const root = path.join(tmp, name);
+        for (const rel of ENGINE_MODULES) {
+            fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true });
+            fs.copyFileSync(path.join(REPO_ROOT, rel), path.join(root, rel));
+        }
+        fs.mkdirSync(path.join(root, RECIPE_DIR), { recursive: true });
+        recipes.forEach((r, i) => fs.writeFileSync(path.join(root, RECIPE_DIR, `${String(i)}.json`), JSON.stringify(r)));
+        return root;
+    };
+    const real = readRecipes(REPO_ROOT);
+    const first = real[0] as Recipe;
+    const run = (root: string): number => runGateCli(REPO_ROOT, 'src/scripts/check_egress_mutations.ts', ['--root', root], root);
+    try {
+        return runSelfTest({
+            gate: GATE,
+            minCases: 4,
+            minRejectCases: 3,
+            cases: [
+                {
+                    name: 'a mutation that changes nothing survives and is rejected',
+                    expect: 'reject',
+                    run: () => run(fixture('survivor', [{ ...first, mutation: 'noop', replace: first.find }])),
+                },
+                {
+                    name: 'a recipe whose find text is gone is rejected as stale',
+                    expect: 'reject',
+                    run: () => run(fixture('stale', [{ ...first, mutation: 'stale', find: 'no such text in the module' }])),
+                },
+                {
+                    name: 'a recipe naming no known invariant is rejected',
+                    expect: 'reject',
+                    run: () => run(fixture('unknown', [{ ...first, mutation: 'unknown', killed_by: 'no-such-invariant' }])),
+                },
+                {
+                    name: 'the committed recipes are all killed',
+                    expect: 'accept',
+                    run: () => run(fixture('real', real)),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export async function main(argv: readonly string[]): Promise<number> {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(`usage: ${GATE} [--root DIR] [--self-test]\n`);
+        return 0;
+    }
+    if (argv.includes('--self-test')) return selfTest();
+    const i = argv.indexOf('--root');
+    return check(i === -1 ? REPO_ROOT : (argv[i + 1] ?? REPO_ROOT));
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    main(process.argv.slice(2)).then(
+        (code) => process.exit(code),
+        (exc: unknown) => {
+            process.stderr.write(`${GATE}: ${String(exc)}\n`);
+            process.exit(2);
+        },
+    );
+}

package/src/scripts/check_enforcement_coverage.ts

@@ -414,11 +414,24 @@ export function strip_comments(src: string): string {
         .join('\n');
 }
 
-/** True when `base`/`stem` appears inside a quoted specifier — an invocation shape. */
+/**
+ * True when `base`/`stem` appears inside a quoted specifier — an invocation shape.
+ *
+ * This answers exactly what `/['"\`][^'"\`]*NEEDLE[^'"\`]*['"\`]/` answered —
+ * an occurrence with some quote character before it and some after it — without
+ * compiling two regexes per script per round over a body that reaches megabytes.
+ * That sweep was ~99 % of `build_proof`'s `render()` (88 s of 89 s locally,
+ * CPU profile 2026-10-21). The regex is kept as the oracle in
+ * `check_enforcement_coverage_mentions.test.ts`.
+ */
 export function mentions_as_code(haystack: string, base: string, stem: string): boolean {
+    const firsts = ["'", '"', '`'].map((q) => haystack.indexOf(q)).filter((i) => i !== -1);
+    if (firsts.length === 0) return false;
+    const first = Math.min(...firsts);
+    const last = Math.max(...["'", '"', '`'].map((q) => haystack.lastIndexOf(q)));
     for (const needle of [base, stem]) {
-        const q = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        if (new RegExp(`['"\`][^'"\`]*${q}[^'"\`]*['"\`]`).test(haystack)) return true;
+        const at = haystack.indexOf(needle, first + 1);
+        if (at !== -1 && at + needle.length <= last) return true;
     }
     return false;
 }

package/src/scripts/check_estate_count.ts

@@ -154,7 +154,7 @@ import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
 import { materialiseSubtree } from './_lib/base_tree.js';
 import { SKILLS_POSIX, measureSkillEstate } from './_lib/skill_estate.js';
 import { CONCERN_MANIFEST_POSIX, countConcerns } from './_lib/concern_estate.js';
-import { exemptionFindings, type ExemptionFinding } from './_lib/exemption_shape.js';
+import { exemptionFindings, unsearchedExemptions, type ExemptionFinding } from './_lib/exemption_shape.js';
 import { classifyDiff, growthClaims, type GrowthClaim, type OffsetLedger } from './_lib/estate_offsets.js';
 import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
 
@@ -344,6 +344,8 @@ export interface EstateVerdict {
      * another added file's. Empty on every change that adds no exemption.
      */
     exemptionFindings: ExemptionFinding[];
+    /** Added exemptions quoting no owner search — reported, never gating (council 2026-10-16). */
+    exemptionWarnings: ExemptionFinding[];
     /**
      * Roadmaps carrying an unscheduled status — REPORTED, never gated.
      *
@@ -793,6 +795,7 @@ export function evaluate(
         offsetSkipReason,
         unpaid,
         exemptionFindings: findings,
+        exemptionWarnings: offsets === null ? [] : unsearchedExemptions(offsets.exempt),
         draftRoadmaps: countDrafts(repoRoot),
         provisionalPromotion,
         // No floor is a FAILURE, not a skip, and it is the one place this gate
@@ -1412,6 +1415,18 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             );
         }
     }
+    for (const f of verdict.exemptionWarnings) {
+        process.stderr.write(
+            `⚠️  ${f.file}: estate_offset_exempt quotes no owner search (report-only).\n` +
+                `    reason: ${f.reason.slice(0, 160)}\n` +
+                '    Before a finding becomes a new file, search for the roadmap that already\n' +
+                '    owns it and quote the search in one clause: the command, what it searched\n' +
+                '    for, the whole tree as scope and an empty result, e.g. "a grep over\n' +
+                '    agents/roadmaps/{*,later,stubs} for <identifiers> returns nothing". If the\n' +
+                '    search finds an owner, land the finding there as a step and an `Arrivals:`\n' +
+                '    line instead. Added files only; this does not fail the gate.\n',
+        );
+    }
     ledger.report();
     if (verdict.withinBudget) {
         process.stdout.write(`✅  ${GATE}: estate within its ratchet.\n`);

package/src/scripts/check_finding_dispositions.ts

@@ -139,6 +139,13 @@ export interface Ledger {
     context_relation?: string;
     acceptance_status?: string;
     assurance?: string;
+    /**
+     * Repo-relative path to a committed owner directive that permits cutting
+     * this version although nothing reviewed it. A PATH rather than free text:
+     * free text is the reason string this field exists to stop being enough.
+     * See unreviewed_ledger_problem.
+     */
+    assurance_override?: string;
     reviewers?: string[];
     coverage?: unknown;
     /**
@@ -483,6 +490,110 @@ export function empty_ledger_problem(
 export type ReleaseStatus = 'released' | 'unreleased' | 'undeterminable';
 export type RemoteReleaseAnswer = 'released' | 'unreleased' | 'unavailable';
 
+/**
+ * A version named as a whole token: `16.4.1` does not occur in `16.4.10` or in
+ * `116.4.1`, which a substring test would accept.
+ */
+export function mentionsVersion(text: string, release: string): boolean {
+    const escaped = release.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?<![\\w.-])v?${escaped}(?![\\w-]|\\.\\d)`).test(text);
+}
+
+/** Where an `assurance_override` may point. Nothing outside it is accepted. */
+export const OWNER_DIRECTIVES_DIR = 'agents/evidence/owner-directives';
+
+/**
+ * A review that never ran is not a review, and a reason string is not one either.
+ *
+ * `empty_ledger_problem` above forced an empty ledger to SAY why it is empty. It
+ * could not ask whether the answer was acceptable, because any non-empty reason
+ * satisfies it — so a ledger declaring `assurance: unreviewed` beside a reason
+ * whose own first words are "NOT REVIEWED" cleared the cut. That is the state
+ * 16.4.0 shipped in: three self-review runs refused by the provider, nothing
+ * reviewed, and a release tagged anyway on the strength of the paragraph saying
+ * so. The paragraph was honest; what was missing was anything that read it.
+ *
+ * Two bounds keep this from reddening work it has no business reddening.
+ *
+ * SCOPED TO AN UNRELEASED VERSION. Backfilled ledgers for versions that already
+ * shipped carry `unreviewed` by design — that is what a backfill IS — and a
+ * version-blind refusal would red history nobody can go back and re-review. An
+ * `undeterminable` status passes for the same reason read from the other side:
+ * a checkout that cannot say whether a version shipped cannot say the ledger is
+ * a backfill either, and refusing there would turn a tagless clone into a
+ * blocked release. The cut itself runs where tags are complete.
+ *
+ * THE OVERRIDE IS A PATH, NOT A SENTENCE. It names a committed file under
+ * {@link OWNER_DIRECTIVES_DIR} whose text names the version — so the escape
+ * hatch leaves an artifact somebody signed, which a free-text field does not.
+ * `readDirective` is injected so both halves of that check are decidable
+ * offline, the way every signal in `releaseStatus` is.
+ */
+export function unreviewed_ledger_problem(
+    ledger: Pick<Ledger, 'findings' | 'assurance' | 'assurance_override'>,
+    release: string,
+    status: ReleaseStatus,
+    readDirective: (relPath: string) => string | null,
+): string | null {
+    if (ledger.findings.length > 0) {
+        return null;
+    }
+    if ((ledger.assurance ?? '').trim() !== 'unreviewed') {
+        return null;
+    }
+    const override = (ledger.assurance_override ?? '').trim();
+    // Checked before the status, and deliberately: an override pointing at
+    // nothing is wrong on a released version too, and a reader who wrote one
+    // is owed the reason rather than a silent pass.
+    if (override !== '') {
+        // Normalised first: a prefix test on the raw value admits
+        // `owner-directives/../../CHANGELOG.md`, which names any file at all.
+        const normalised = path.posix.normalize(override);
+        if (
+            normalised !== override
+            || override.split('/').includes('..')
+            || !override.startsWith(`${OWNER_DIRECTIVES_DIR}/`)
+        ) {
+            return (
+                `\`assurance_override\` is \`${override}\`, which is not under `
+                + `${OWNER_DIRECTIVES_DIR}/. The override names a committed owner directive, `
+                + 'never a sentence — a sentence is the reason string this field replaces.'
+            );
+        }
+        const text = readDirective(override);
+        if (text === null) {
+            return (
+                `\`assurance_override\` names ${override}, which is not committed. `
+                + 'Commit the directive, or remove the override and get the ledger reviewed.'
+            );
+        }
+        if (!mentionsVersion(text, release)) {
+            return (
+                `\`assurance_override\` names ${override}, whose text does not mention `
+                + `${release}. A directive permitting some other cut does not permit this one.`
+            );
+        }
+        return null;
+    }
+    if (status !== 'unreleased') {
+        return null;
+    }
+    return (
+        `the ledger declares \`assurance: unreviewed\` with no findings, so nothing reviewed `
+        + `${release} and this cut would ship a release that reviewed itself not at all.\n`
+        + '    Review it. The self-review gate resolves the local subscription CLI before any\n'
+        + '    metered key, so a review is usually one command away and needs no credit:\n'
+        + '        ./scripts-run src/scripts/self_review_gate --findings-out agents/runtime/release-findings.json\n'
+        + '    Then ingest what it reported:\n'
+        + '        ./scripts-run src/scripts/check_finding_dispositions --ingest '
+        + `agents/runtime/release-findings.json --release ${release}\n`
+        + '    If this cut must go out unreviewed, that is an owner decision and it leaves a\n'
+        + `    file: commit a directive under ${OWNER_DIRECTIVES_DIR}/ whose text names `
+        + `${release},\n`
+        + '    and set `assurance_override` to its path.'
+    );
+}
+
 /**
  * Pure core of the released-vs-unreleased discriminator. Every signal is
  * INJECTED, so both directions AND the degradation are testable offline. A
@@ -542,6 +653,21 @@ function _git(args: readonly string[]): { ok: boolean; out: string } {
     return { ok: r.status === 0, out: (r.stdout ?? '').trim() };
 }
 
+/**
+ * A file as committed at HEAD, or null. The working tree is not read: an
+ * uncommitted directive is exactly what the override's error calls "not
+ * committed", and only a regular blob counts — a symlink or submodule entry
+ * would let the path name content stored somewhere else.
+ */
+function readCommittedFile(rel: string): string | null {
+    const entry = _git(['ls-tree', 'HEAD', '--', rel]);
+    if (!entry.ok || !/^100(644|755) blob /.test(entry.out.trim())) {
+        return null;
+    }
+    const shown = _git(['show', `HEAD:${rel}`]);
+    return shown.ok ? shown.out : null;
+}
+
 /** This repository tags. A git failure is an empty list, i.e. not complete. */
 export function git_tags(): string[] {
     const r = _git(['tag', '--list']);
@@ -802,6 +928,27 @@ function main(argv: readonly string[]): number {
             );
             return 1;
         }
+        // And an explained empty ledger must say something a reader can accept.
+        // The status is resolved ONLY on the branch that reads it — a ledger
+        // with findings, one that is not `unreviewed`, and one already carrying
+        // an override all skip the tag probe, so the ordinary cut stays exactly
+        // as cheap as it was.
+        const needsStatus =
+            ledger.findings.length === 0
+            && (ledger.assurance ?? '').trim() === 'unreviewed'
+            && (ledger.assurance_override ?? '').trim() === '';
+        const unreviewedProblem = unreviewed_ledger_problem(
+            ledger,
+            release,
+            needsStatus ? resolve_release_status(release) : 'undeterminable',
+            (rel) => readCommittedFile(rel),
+        );
+        if (unreviewedProblem !== null) {
+            process.stderr.write(
+                `❌  ${path.relative(REPO_ROOT, ledgerPath)}: ${unreviewedProblem}\n`,
+            );
+            return 1;
+        }
     }
 
     // Scope declaration, not a scope guard. The ledger is written per release by