@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/_lib/evaluator_promotion.ts

@@ -1,225 +0,0 @@
-/**
- * Evaluator promotion — a new evaluator earns its seat by cross-grading, or it
- * does not get one.
- *
- * `road-to-governed-harness-evolution` Phase 4, step 4.7.
- *
- * > *Reuse the discrimination and hygiene machinery. `eval_publication`'s
- * > `PlantedItem` for plants, `judge_hygiene` for order-swap. Add the
- * > evaluator-promotion procedure the master omitted: an old and a new
- * > evaluator must cross-grade frozen candidate sets, and evaluator promotion
- * > itself requires discrimination plants.*
- * > verify: **a planted candidate the control arm also satisfies is reported as
- * > a discrimination deficit, not as a win; an evaluator change with no
- * > cross-grade is refused.**
- *
- * ## Reuse, not reimplementation
- *
- * Risk 1 on this roadmap is a parallel rebuild of machinery that already
- * exists, committed four times by the source proposals. So nothing here scores
- * a plant, classifies an assertion, or decides a paired verdict:
- * {@link reportPlants} delegates to `eval_publication.discriminationDeficit`
- * and {@link assertEvaluatorPromotable} delegates to
- * `judge_hygiene.auditAssertions`. What this module adds is the one thing
- * neither has: the REFUSAL that turns an evaluator swap into a gated event.
- *
- * ## Why a satisfied plant can be a deficit rather than a win
- *
- * A plant exists to be recoverable only via the behaviour under test. If the
- * control arm also satisfies it, then the item measured general competence and
- * the treatment's success over it is not evidence about the treatment — the two
- * arms scored the same for different-looking reasons. Counting it as a win is
- * the exact inflation `eval_publication`'s header describes, so
- * {@link reportPlants} moves it into `discrimination_deficits` and, critically,
- * strips its `requires_artifact_behaviour` flag before handing the set to
- * `discriminationDeficit` — otherwise a fixture set whose every discriminating
- * plant turned out to be non-discriminating in practice would still pass the
- * pre-run check on its declared intent.
- *
- * ## Order-swap is carried as a declared property, and refused when absent
- *
- * `judge_hygiene`'s header records that blinding and the order-swap are already
- * met upstream by `check_quality_regression.evaluatePair`, which judges every
- * pair in both orders and resolves a flip to `inconsistent`. This module does
- * not re-implement that; it requires the cross-grade to DECLARE that it ran
- * that way ({@link CrossGrade.order_swapped}) and refuses the promotion when it
- * did not. That is an honest boundary: the property is asserted by the caller
- * and checked here, not observed here.
- */
-import { discriminationDeficit, type PlantedItem } from './eval_publication.js';
-import { auditAssertions, type AssertionObservation } from './judge_hygiene.js';
-
-/** One plant, and what each arm actually did with it. */
-export interface PlantOutcome {
-    item: PlantedItem;
-    treatment_satisfied: boolean;
-    control_satisfied: boolean;
-}
-
-export interface DiscriminationDeficitFinding {
-    id: string;
-    reason: string;
-}
-
-export interface PlantReport {
-    /** Plants the treatment satisfied and the control did not. The measurement. */
-    wins: readonly string[];
-    /** Plants the control also satisfied. Never wins, whatever the treatment did. */
-    discrimination_deficits: readonly DiscriminationDeficitFinding[];
-    /**
-     * The set-level verdict from `eval_publication.discriminationDeficit`, run
-     * over the EFFECTIVE set (observed, not declared). Non-null means the set
-     * cannot adjudicate at all.
-     */
-    set_deficit: string | null;
-}
-
-/** Classify every plant outcome. See the header for why a shared satisfaction is a deficit. */
-export function reportPlants(outcomes: readonly PlantOutcome[]): PlantReport {
-    const wins: string[] = [];
-    const deficits: DiscriminationDeficitFinding[] = [];
-    const effective: PlantedItem[] = [];
-
-    for (const o of outcomes) {
-        if (o.control_satisfied) {
-            deficits.push({
-                id: o.item.id,
-                reason:
-                    `the control arm also satisfied '${o.item.id}', so it measures general ` +
-                    'competence rather than the behaviour under test — a discrimination deficit, not a win',
-            });
-            effective.push({ id: o.item.id, requires_artifact_behaviour: false });
-            continue;
-        }
-        effective.push({ id: o.item.id, requires_artifact_behaviour: o.item.requires_artifact_behaviour });
-        if (o.treatment_satisfied && o.item.requires_artifact_behaviour) {
-            wins.push(o.item.id);
-        }
-    }
-
-    return {
-        wins,
-        discrimination_deficits: deficits,
-        set_deficit: discriminationDeficit(effective),
-    };
-}
-
-/** The frozen candidate set both evaluators must grade. Frozen means: named and enumerated. */
-export interface FrozenCandidateSet {
-    id: string;
-    candidate_ids: readonly string[];
-}
-
-export interface CrossGrade {
-    from_evaluator: string;
-    to_evaluator: string;
-    /** Must equal the change's frozen set id — a cross-grade of some other set proves nothing. */
-    frozen_set_id: string;
-    /** Candidate ids the OLD evaluator graded. */
-    graded_by_from: readonly string[];
-    /** Candidate ids the NEW evaluator graded. */
-    graded_by_to: readonly string[];
-    /**
-     * Declared by the caller: every pair was judged in both orders upstream
-     * (`check_quality_regression.evaluatePair`). See the header — asserted, not
-     * observed here.
-     */
-    order_swapped: boolean;
-    /** Rubric assertions used by the grading, audited via `judge_hygiene`. */
-    assertions: readonly AssertionObservation[];
-}
-
-export interface EvaluatorChange {
-    from: string;
-    to: string;
-    frozen_set: FrozenCandidateSet;
-    /** `null` is the case step 4.7 names: an evaluator change with no cross-grade. */
-    cross_grade: CrossGrade | null;
-    /** Discrimination plants. Evaluator promotion requires them, per step 4.7. */
-    plants: readonly PlantOutcome[];
-}
-
-export class EvaluatorPromotionRefused extends Error {
-    readonly reasons: readonly string[];
-    constructor(reasons: readonly string[]) {
-        super(`evaluator promotion refused: ${reasons.join('; ')}`);
-        this.name = 'EvaluatorPromotionRefused';
-        this.reasons = reasons;
-    }
-}
-
-function missing(required: readonly string[], graded: readonly string[]): string[] {
-    const seen = new Set(graded);
-    return required.filter((id) => !seen.has(id));
-}
-
-/**
- * Throw {@link EvaluatorPromotionRefused} unless every condition holds.
- *
- * Fail-closed by construction: the function has no permissive path and no
- * option object that could relax one. A caller who wants to promote an
- * evaluator without a cross-grade has to delete this call, which is visible in
- * a diff, rather than pass a flag, which is not.
- */
-export function assertEvaluatorPromotable(change: EvaluatorChange): void {
-    const reasons: string[] = [];
-    const cg = change.cross_grade;
-
-    if (cg === null) {
-        reasons.push(
-            `no cross-grade between '${change.from}' and '${change.to}' — an evaluator change ` +
-                'without one has no evidence that the two agree on anything',
-        );
-    } else {
-        if (cg.frozen_set_id !== change.frozen_set.id) {
-            reasons.push(
-                `the cross-grade names frozen set '${cg.frozen_set_id}' but the change is over ` +
-                    `'${change.frozen_set.id}'`,
-            );
-        }
-        if (cg.from_evaluator !== change.from || cg.to_evaluator !== change.to) {
-            reasons.push(
-                `the cross-grade is between '${cg.from_evaluator}' and '${cg.to_evaluator}', ` +
-                    `not between '${change.from}' and '${change.to}'`,
-            );
-        }
-        const missFrom = missing(change.frozen_set.candidate_ids, cg.graded_by_from);
-        const missTo = missing(change.frozen_set.candidate_ids, cg.graded_by_to);
-        if (missFrom.length > 0) {
-            reasons.push(`'${change.from}' did not grade: ${missFrom.join(', ')}`);
-        }
-        if (missTo.length > 0) {
-            reasons.push(`'${change.to}' did not grade: ${missTo.join(', ')}`);
-        }
-        if (!cg.order_swapped) {
-            reasons.push('the cross-grade did not declare the order-swap, so a position bias is unexcluded');
-        }
-        const audit = auditAssertions(cg.assertions);
-        const alwaysPass = audit.findings.filter((f) => f.verdict === 'non-discriminating-always-pass');
-        if (alwaysPass.length > 0) {
-            reasons.push(
-                `${String(alwaysPass.length)} assertion(s) pass in both arms and narrow nothing: ` +
-                    alwaysPass.map((f) => f.id).join(', '),
-            );
-        }
-    }
-
-    if (change.plants.length === 0) {
-        reasons.push('evaluator promotion requires discrimination plants and this change carries none');
-    } else {
-        const report = reportPlants(change.plants);
-        if (report.set_deficit !== null) {
-            reasons.push(`plants cannot discriminate: ${report.set_deficit}`);
-        }
-        if (report.discrimination_deficits.length > 0) {
-            reasons.push(
-                `${String(report.discrimination_deficits.length)} plant(s) were also satisfied by the control arm: ` +
-                    report.discrimination_deficits.map((d) => d.id).join(', '),
-            );
-        }
-    }
-
-    if (reasons.length > 0) {
-        throw new EvaluatorPromotionRefused(reasons);
-    }
-}

package/src/scripts/_lib/file_slicer.ts

@@ -1,117 +0,0 @@
-/**
- * Deterministic document slicer for oversized knowledge ingest
- * (road-to-retrieval-substrate-hardening B8).
- *
- * Splits a large markdown document into bounded slices at the cleanest
- * available boundary — heading > paragraph (blank line) > line — while
- * guaranteeing three invariants a downstream re-assembler can rely on:
- *
- *   1. GAP-FREE + NON-OVERLAPPING — slices cover contiguous line ranges over
- *      the whole document, in order.
- *   2. CONCAT == ORIGINAL — joining every slice's `text` in order reproduces
- *      the input byte-for-byte (slices are exact offset ranges).
- *   3. PARENTED — every slice carries its source `parentPath` (when given) and
- *      its `[startLine, endLine)` range, so a chunk can point home.
- *
- * Deterministic: identical input + budget → identical slices.
- */
-
-export interface Slice {
-    parentPath: string | null;
-    index: number;
-    startLine: number; // 0-based, inclusive
-    endLine: number; // 0-based, exclusive
-    text: string;
-}
-
-/** Default per-slice character budget. */
-export const DEFAULT_MAX_CHARS = 2000;
-
-function _lineStartOffsets(text: string): number[] {
-    const starts = [0];
-    for (let i = 0; i < text.length; i++) {
-        if (text[i] === '\n') starts.push(i + 1);
-    }
-    return starts; // one entry per line; starts[k] = offset where line k begins
-}
-
-function _isHeading(line: string): boolean {
-    return /^#{1,6}\s/.test(line);
-}
-function _isBlank(line: string): boolean {
-    return line.trim() === '';
-}
-
-/**
- * Slice `text` into ≤ `maxChars` pieces (best-effort — a single over-long line
- * is emitted whole rather than split mid-line, preserving invariant 2).
- * `parentPath` is stamped on every slice.
- */
-export function sliceDocument(
-    text: string,
-    opts: { maxChars?: number; parentPath?: string } = {},
-): Slice[] {
-    const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
-    const parentPath = opts.parentPath ?? null;
-    if (text === '') return [];
-
-    const starts = _lineStartOffsets(text);
-    const nLines = starts.length;
-    // lineAt(k) = the raw text of line k INCLUDING its trailing newline (if any).
-    const lineEnd = (k: number): number => (k + 1 < nLines ? starts[k + 1]! : text.length);
-    const lines: string[] = [];
-    for (let k = 0; k < nLines; k++) lines.push(text.slice(starts[k]!, lineEnd(k)));
-
-    const slices: Slice[] = [];
-    let sliceStartLine = 0;
-    let idx = 0;
-    const flush = (endLine: number): void => {
-        if (endLine <= sliceStartLine) return;
-        const from = starts[sliceStartLine]!;
-        const to = endLine < nLines ? starts[endLine]! : text.length;
-        slices.push({ parentPath, index: idx++, startLine: sliceStartLine, endLine, text: text.slice(from, to) });
-        sliceStartLine = endLine;
-    };
-
-    let curChars = 0;
-    for (let k = 0; k < nLines; k++) {
-        const lineLen = lines[k]!.length;
-        const wouldExceed = curChars + lineLen > maxChars && k > sliceStartLine;
-        // Cut BEFORE a heading that opens a new section (clean boundary), or
-        // when the budget would overflow — preferring a preceding blank line.
-        const headingBoundary = _isHeading(lines[k]!) && k > sliceStartLine;
-        if (headingBoundary || wouldExceed) {
-            // Prefer to end the previous slice at the last blank line in-range,
-            // so a slice ends on a paragraph boundary when one is available.
-            let cut = k;
-            if (wouldExceed && !headingBoundary) {
-                for (let b = k - 1; b > sliceStartLine; b--) {
-                    if (_isBlank(lines[b]!)) {
-                        cut = b + 1;
-                        break;
-                    }
-                }
-            }
-            flush(cut);
-            curChars = 0;
-            for (let j = sliceStartLine; j <= k; j++) curChars += lines[j]!.length;
-        } else {
-            curChars += lineLen;
-        }
-    }
-    flush(nLines);
-    return slices;
-}
-
-/** True iff the slices reproduce `text` exactly, gap-free and non-overlapping. */
-export function verifySlices(text: string, slices: readonly Slice[]): boolean {
-    if (slices.length === 0) return text === '';
-    let expectedLine = 0;
-    const parts: string[] = [];
-    for (const s of slices) {
-        if (s.startLine !== expectedLine) return false; // gap or overlap
-        expectedLine = s.endLine;
-        parts.push(s.text);
-    }
-    return parts.join('') === text;
-}

package/src/scripts/_lib/legacy_boundary_map.ts

@@ -1,228 +0,0 @@
-/**
- * A per-path legacy/modern verdict for a half-migrated repository.
- *
- * `road-to-consumer-repo-reality` Phase 4, step 4.1. Incremental replacement of
- * a legacy system alongside the system it replaces is a named, published
- * migration pattern; the artifact that pattern needs and nobody produces is a
- * decidable answer to *"which conventions hold HERE"*.
- *
- * Current guidance says to respect existing patterns and to keep diffs minimal.
- * Neither is decidable without this: in a tree that is two-fifths namespaced,
- * strict-typed, PSR-shaped code and three-fifths an older include-and-dispatch
- * module system, "the existing pattern" is not a property of the repository.
- *
- * A MIXED VERDICT IS NOT A REFUSAL TO DECIDE. That is the step's own wording and
- * it is the hardest requirement here: a verdict that says only "mixed" leaves
- * the caller exactly where it started. So a mixed file reports WHICH convention
- * governs WHICH REGION, by line range, and `conventionAt(verdict, line)` answers
- * the only question an editor actually has — *what must my edit at this point
- * follow?*
- *
- * WHAT THIS MAY AND MAY NOT ENCODE. The phase states the trap in its own body:
- * 4.2 and 4.3 were each observed in exactly one tree, so what may be encoded is
- * the QUESTION, never the particular mechanism that tree happened to use. 4.1 is
- * not in that category — namespaces, strict-type declarations and PSR-4
- * autoloading are language-level and specification-level facts, not one
- * repository's arrangement — but the same restraint is applied anyway: the
- * signals below are all language constructs, and none is a project-specific
- * naming convention, directory layout or framework marker.
- *
- * PER PATH, NEVER PER REPOSITORY. A repository-wide verdict is the thing that
- * makes this artifact useless: the whole point is that the answer differs by
- * file, and inside a file by region.
- */
-import * as fs from 'node:fs';
-
-/** Which convention governs. `unknown` is returned rather than guessed. */
-export type Convention = 'modern' | 'legacy' | 'mixed' | 'unknown';
-
-/** A contiguous run of lines governed by one convention. */
-export interface Region {
-    /** 1-indexed, inclusive. */
-    startLine: number;
-    /** 1-indexed, inclusive. */
-    endLine: number;
-    convention: 'modern' | 'legacy';
-    /** The construct that decided it. Never empty. */
-    signal: string;
-}
-
-export interface PathVerdict {
-    /** The path as given. */
-    path: string;
-    convention: Convention;
-    /**
-     * Populated for EVERY verdict that is not `unknown`, including a
-     * single-convention file — a caller should not need two code paths.
-     */
-    regions: Region[];
-    /**
-     * A single foreign signal inside an otherwise uniform file — one `$GLOBALS`
-     * read in a namespaced class, one class-like declaration in an
-     * include-and-dispatch file. Reported as a POINT and deliberately not as a
-     * region: a lone signal says something true about ITS line and nothing about
-     * the lines after it, and letting it open a region made every line to the end
-     * of the file inherit a convention it does not have.
-     */
-    foreignPoints: { line: number; convention: 'modern' | 'legacy'; signal: string }[];
-    /** One sentence naming what decided it. Never empty. */
-    reason: string;
-}
-
-/**
- * Signals, as language constructs only.
- *
- * `modern` markers are things the older include-and-dispatch style cannot
- * express; `legacy` markers are things the namespaced style does not use. A line
- * matching neither is inherited from the enclosing region rather than guessed —
- * most lines in any file carry no signal at all.
- */
-const MODERN: readonly { re: RegExp; signal: string }[] = [
-    { re: /^\s*declare\s*\(\s*strict_types\s*=\s*1\s*\)/, signal: 'declare(strict_types=1)' },
-    { re: /^\s*namespace\s+[A-Za-z_]/, signal: 'namespace declaration' },
-    { re: /^\s*use\s+[A-Za-z_][A-Za-z0-9_]*\\/, signal: 'namespaced use statement' },
-    { re: /^\s*(?:final\s+|abstract\s+)?(?:readonly\s+)?(?:class|interface|trait|enum)\s+/, signal: 'class-like declaration' },
-];
-
-const LEGACY: readonly { re: RegExp; signal: string }[] = [
-    { re: /^\s*(?:require|include)(?:_once)?\s*[\s(]/, signal: 'require/include' },
-    { re: /^\s*global\s+\$/, signal: 'global statement' },
-    { re: /\$GLOBALS\s*\[/, signal: '$GLOBALS access' },
-    { re: /^\s*function\s+[a-z][A-Za-z0-9_]*\s*\(/, signal: 'unnamespaced snake/camel function' },
-];
-
-/**
- * Requiring the Composer autoloader is the MODERN ecosystem's own bootstrap, not
- * the include-and-dispatch pattern. Without this exception the canonical PSR-4
- * entry point — `require __DIR__ . '/../vendor/autoload.php';` — makes every
- * modern application's front controller come back `mixed`, which is the single
- * most common file shape in the ecosystem this module is meant to classify.
- */
-const AUTOLOAD_REQUIRE = /vendor\/autoload\.php/;
-
-/**
- * A line that is only a comment carries no convention. `// never touch
- * $GLOBALS['x']` is advice ABOUT legacy code, and reading it as legacy code
- * flips the region a reader is standing in. Block-comment interiors are not
- * tracked — that needs a lexer — so only whole-line `//`, `#` and `*`
- * continuations are skipped.
- */
-const COMMENT_ONLY = /^\s*(?:\/\/|#|\*|\/\*)/;
-
-function _signalFor(line: string): { convention: 'modern' | 'legacy'; signal: string } | null {
-    if (COMMENT_ONLY.test(line)) return null;
-    for (const { re, signal } of MODERN) if (re.test(line)) return { convention: 'modern', signal };
-    if (AUTOLOAD_REQUIRE.test(line)) return null;
-    for (const { re, signal } of LEGACY) if (re.test(line)) return { convention: 'legacy', signal };
-    return null;
-}
-
-/**
- * Classify one file's text into regions.
- *
- * A signal starts a region that runs until the next signal of the OTHER
- * convention. Lines before the first signal belong to the first region, so every
- * line of a classified file is covered — a caller asking about line 1 of a file
- * whose first signal is on line 3 gets an answer rather than a hole.
- */
-export function classifyText(pathName: string, text: string): PathVerdict {
-    const lines = text.split('\n');
-    const hits: { line: number; convention: 'modern' | 'legacy'; signal: string }[] = [];
-    for (let i = 0; i < lines.length; i += 1) {
-        const hit = _signalFor(lines[i] ?? '');
-        if (hit !== null) hits.push({ line: i + 1, ...hit });
-    }
-
-    // A lone signal of one convention, against two or more of the other, is a
-    // POINT rather than a region boundary. Two is the threshold because one
-    // occurrence is as likely to be an artifact — a legacy global read inside a
-    // modern service, a single class declaration in an old dispatch file — as a
-    // statement about the surrounding code.
-    const counts = { modern: 0, legacy: 0 };
-    for (const h of hits) counts[h.convention] += 1;
-    const isolated: 'modern' | 'legacy' | null =
-        counts.modern === 1 && counts.legacy >= 2 ? 'modern'
-        : counts.legacy === 1 && counts.modern >= 2 ? 'legacy'
-        : null;
-    const foreignPoints = isolated === null ? [] : hits.filter((h) => h.convention === isolated);
-    const structural = isolated === null ? hits : hits.filter((h) => h.convention !== isolated);
-
-    const regions: Region[] = [];
-    for (const hit of structural) {
-        const i = hit.line - 1;
-        const last = regions[regions.length - 1];
-        if (last !== undefined && last.convention === hit.convention) {
-            last.endLine = i + 1;
-            continue;
-        }
-        regions.push({ startLine: i + 1, endLine: i + 1, convention: hit.convention, signal: hit.signal });
-    }
-
-    if (regions.length === 0) {
-        return {
-            path: pathName,
-            convention: 'unknown',
-            regions: [],
-            foreignPoints,
-            reason: 'no convention signal found — neither a namespaced construct nor an include-and-dispatch one',
-        };
-    }
-
-    // Extend each region to meet the next, and the first back to line 1, so the
-    // whole file is covered and `conventionAt` never returns a hole.
-    const first = regions[0] as Region;
-    first.startLine = 1;
-    for (let i = 0; i < regions.length - 1; i += 1) {
-        (regions[i] as Region).endLine = (regions[i + 1] as Region).startLine - 1;
-    }
-    (regions[regions.length - 1] as Region).endLine = Math.max(lines.length, 1);
-
-    const kinds = new Set(regions.map((r) => r.convention));
-    if (kinds.size === 1) {
-        const only = [...kinds][0] as 'modern' | 'legacy';
-        return {
-            path: pathName,
-            convention: only,
-            regions,
-            foreignPoints,
-            reason:
-                `every structural signal in this file is ${only} (${regions.map((r) => r.signal).join(', ')})` +
-                (foreignPoints.length === 0
-                    ? ''
-                    : `. One isolated ${isolated} signal at L${foreignPoints.map((f) => f.line).join(', L')} ` +
-                      `(${foreignPoints.map((f) => f.signal).join(', ')}) — true of that line, not of the lines after it`),
-        };
-    }
-    return {
-        path: pathName,
-        convention: 'mixed',
-        regions,
-        foreignPoints,
-        reason:
-            `both conventions appear in this file, in ${regions.length} regions. ` +
-            regions.map((r) => `L${r.startLine}-${r.endLine} ${r.convention} (${r.signal})`).join('; ') +
-            '. An edit follows the convention of the region it lands in, not the file as a whole.',
-    };
-}
-
-/** Read and classify one file. An unreadable file is `unknown`, never guessed. */
-export function classifyPath(absPath: string, displayPath = absPath): PathVerdict {
-    try {
-        return classifyText(displayPath, fs.readFileSync(absPath, 'utf8'));
-    } catch {
-        return { path: displayPath, convention: 'unknown', regions: [], foreignPoints: [], reason: 'unreadable' };
-    }
-}
-
-/**
- * The only question an editor actually has: what must an edit at THIS line
- * follow? Returns `null` when the file carries no signal at all — which is a
- * real answer, and different from "modern by default".
- */
-export function conventionAt(verdict: PathVerdict, line: number): 'modern' | 'legacy' | null {
-    for (const f of verdict.foreignPoints) if (f.line === line) return f.convention;
-    for (const r of verdict.regions) {
-        if (line >= r.startLine && line <= r.endLine) return r.convention;
-    }
-    return null;
-}