@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/_lib/harness_evolution_guards.ts

@@ -0,0 +1,229 @@
+/**
+ * Pre-registered guards for the governed harness-evolution programme.
+ *
+ * `road-to-governed-harness-evolution` Phase 0, steps 0.4, 0.5 and 0.6. All
+ * three are PRE-REGISTRATION: the runner they guard does not exist yet (Phases
+ * 1-7 are unbuilt), and that is the point — a budget invariant written after
+ * the first run is a description of what was spent, and a leakage abort written
+ * after the first leak is a post-mortem.
+ *
+ * The three guards, and the failure each exists to make impossible:
+ *
+ *   0.4 EVALUATOR TRUST BOUNDARY. The parent design named which fields are
+ *       proposer-visible and which are evaluator-private, and stopped at the
+ *       naming. A declared boundary that nothing checks is a boundary that
+ *       holds until the first convenient exception. {@link discloseToProposer}
+ *       refuses a holdout field and records every field it did release.
+ *
+ *   0.5 BUDGET INVARIANT. Candidate count, trial repetitions and a spend
+ *       ceiling, fixed BEFORE the run and aborting rather than truncating. A
+ *       truncated run yields `underpowered`, which `paired_verdict` refuses to
+ *       call a pass (`_lib/paired_verdict.ts:26`) and which a reader mistakes
+ *       for one.
+ *
+ *   0.6 EPISTEMIC STOP CONDITIONS. A spend cap stops on cost; most of the
+ *       reasons to stop are about VALIDITY. Each condition below carries a
+ *       detector or is explicitly marked model-carried — never implied to be
+ *       checked when it is not.
+ *
+ * Nothing here spends, fetches, or writes. The guards are pure functions over
+ * declared state so a future runner can call them before it does any of those.
+ */
+
+/**
+ * What a field may be shown to.
+ *
+ * `holdout` is the load-bearing member: it names a value whose disclosure
+ * INVALIDATES the run rather than merely leaking information, which is why
+ * {@link discloseToProposer} aborts on it instead of redacting.
+ */
+export type VisibilityClass =
+    /** The proposer may read it. Candidate text, public metric names, the task. */
+    | 'proposer-visible'
+    /** The evaluator reads it; the proposer never does. Per-trial raw scores. */
+    | 'evaluator-private'
+    /** Sealed-partition truth. Disclosure invalidates the run, not just the trial. */
+    | 'holdout';
+
+/** One observation field and the boundary it sits behind. */
+export interface FieldVisibility {
+    readonly field: string;
+    readonly visibility: VisibilityClass;
+}
+
+/** A field released to a proposer, with the class it was released under. */
+export interface DisclosureRecord {
+    readonly field: string;
+    readonly visibility: VisibilityClass;
+}
+
+export class HoldoutLeakError extends Error {
+    readonly field: string;
+    constructor(field: string) {
+        super(
+            `holdout leakage: field '${field}' is class 'holdout' and reached proposer context. ` +
+                'The run is INVALID, not degraded — a proposer that has seen sealed truth cannot ' +
+                'be evaluated against it, and no later stage can undo that. Abort, do not redact.',
+        );
+        this.name = 'HoldoutLeakError';
+        this.field = field;
+    }
+}
+
+/**
+ * Release an observation to a proposer, recording every field released.
+ *
+ * Fails CLOSED on an undeclared field: a field with no `visibility_class` is
+ * treated as `holdout`, because the alternative — defaulting to visible —
+ * makes forgetting to classify a new field silently equivalent to publishing
+ * it. Step 0.4's whole subject is that a declared boundary nothing checks is
+ * not a boundary.
+ *
+ * @throws {HoldoutLeakError} on the first holdout or undeclared field.
+ */
+export function discloseToProposer(
+    observation: Readonly<Record<string, unknown>>,
+    schema: readonly FieldVisibility[],
+    log: DisclosureRecord[],
+): Record<string, unknown> {
+    const byField = new Map(schema.map((f) => [f.field, f.visibility]));
+    const out: Record<string, unknown> = {};
+    for (const field of Object.keys(observation)) {
+        const visibility = byField.get(field) ?? 'holdout';
+        if (visibility === 'holdout') throw new HoldoutLeakError(field);
+        if (visibility !== 'proposer-visible') continue;
+        log.push({ field, visibility });
+        out[field] = observation[field];
+    }
+    return out;
+}
+
+/** The budget fixed before a run. Every field is a ceiling, never a target. */
+export interface RunBudget {
+    readonly maxCandidates: number;
+    readonly maxTrialsPerCandidate: number;
+    /** Spend ceiling in whole cents, so no float ever decides an abort. */
+    readonly maxSpendCents: number;
+}
+
+/** What a run intends to do, as declared before it starts. */
+export interface RunPlan {
+    readonly candidates: number;
+    readonly trialsPerCandidate: number;
+    readonly estimatedSpendCents: number;
+}
+
+export class BudgetExceededError extends Error {
+    readonly dimension: 'candidates' | 'trials' | 'spend';
+    constructor(dimension: 'candidates' | 'trials' | 'spend', planned: number, ceiling: number) {
+        super(
+            `budget invariant: planned ${dimension} ${String(planned)} exceeds the pre-registered ` +
+                `ceiling ${String(ceiling)}. ABORTING BEFORE THE RUN, not truncating it — a ` +
+                'truncated run yields `underpowered`, which paired_verdict refuses to call a pass ' +
+                'and which a reader mistakes for one.',
+        );
+        this.name = 'BudgetExceededError';
+        this.dimension = dimension;
+    }
+}
+
+/**
+ * Check a plan against the pre-registered budget, BEFORE anything is spent.
+ *
+ * The order is deliberate — candidates, then trials, then spend. The first two
+ * are free to check and the third is the one an operator argues about; failing
+ * on a countable dimension first makes the message actionable without any
+ * pricing discussion.
+ *
+ * @throws {BudgetExceededError} on the first dimension over its ceiling.
+ */
+export function assertWithinBudget(plan: RunPlan, budget: RunBudget): void {
+    if (plan.candidates > budget.maxCandidates) {
+        throw new BudgetExceededError('candidates', plan.candidates, budget.maxCandidates);
+    }
+    if (plan.trialsPerCandidate > budget.maxTrialsPerCandidate) {
+        throw new BudgetExceededError('trials', plan.trialsPerCandidate, budget.maxTrialsPerCandidate);
+    }
+    if (plan.estimatedSpendCents > budget.maxSpendCents) {
+        throw new BudgetExceededError('spend', plan.estimatedSpendCents, budget.maxSpendCents);
+    }
+}
+
+/**
+ * A stop condition, and whether anything actually checks it.
+ *
+ * `detector: null` means MODEL-CARRIED and is written out rather than left to
+ * inference. This repository's own records name the coverage-inflation failure
+ * — a condition listed as if it were enforced when nothing enforces it — often
+ * enough that the honest field is cheaper than the audit that finds it later.
+ */
+export interface StopCondition {
+    readonly id: string;
+    readonly why: string;
+    /** The exported detector's name, or `null` for model-carried. */
+    readonly detector: string | null;
+}
+
+/**
+ * The four epistemic stop conditions, from the roadmap's step 0.6.
+ *
+ * Both parent designs carried eight or nine stop conditions; the master
+ * compressed them into the budget cap. A spend cap stops on COST, and these
+ * stop on VALIDITY — stopping with INDETERMINATE is a valid result, and an
+ * honest null is a success when it prevents unnecessary architecture.
+ */
+export const STOP_CONDITIONS: readonly StopCondition[] = [
+    {
+        id: 'holdout-underpowered',
+        why: 'the sealed partition no longer carries enough discordant trials for the exact sign test to resolve, so every verdict it produces is `underpowered` by construction',
+        detector: 'holdoutUnderpowered',
+    },
+    {
+        id: 'evaluator-leakage',
+        why: 'a holdout field reached proposer context; the run is invalid rather than degraded, and no later stage can undo it',
+        detector: 'discloseToProposer',
+    },
+    {
+        id: 'diversity-collapse',
+        why: 'the candidate set has collapsed to semantic duplicates, so the trials measure sampling noise rather than a difference between candidates',
+        detector: 'diversityCollapsed',
+    },
+    {
+        id: 'cross-component-interference',
+        why: 'two components changed in one run and credit cannot be assigned to either',
+        // Honest null: deciding whether two changes interfere needs a causal
+        // model of the components, and this programme has none. Marked
+        // model-carried rather than given a detector that would pattern-match
+        // on file paths and report confidence it does not have.
+        detector: null,
+    },
+];
+
+/**
+ * Has the candidate set collapsed to semantic duplicates?
+ *
+ * Deterministic and deliberately crude: normalise, then count DISTINCT
+ * candidates. Below `minDistinct` the set is collapsed. No embedding, no model
+ * call — a detector that needs a model to decide whether to stop a model run is
+ * a detector that can fail in the same way as the thing it watches.
+ *
+ * Normalisation is case- and whitespace-folding only. Two candidates differing
+ * by a synonym read as distinct here, which UNDER-detects; that direction is
+ * chosen on purpose, because a false stop discards a valid run while a missed
+ * stop is caught by the verdict coming back `no-change`.
+ */
+export function diversityCollapsed(candidates: readonly string[], minDistinct = 2): boolean {
+    const normalised = new Set(candidates.map((c) => c.trim().toLowerCase().replace(/\s+/g, ' ')));
+    return normalised.size < minDistinct;
+}
+
+/**
+ * Is the holdout partition too small for the exact sign test to resolve?
+ *
+ * Mirrors `paired_verdict`'s own floor rather than restating a number:
+ * `MIN_DISCORDANT` there is DERIVED from the exact test at ALPHA, not chosen,
+ * so a second hard-coded constant here would be a fork of a derivation.
+ */
+export function holdoutUnderpowered(discordantTrials: number, minDiscordant: number): boolean {
+    return discordantTrials < minDiscordant;
+}

package/src/scripts/_lib/hook_effect_probe.ts

@@ -0,0 +1,141 @@
+/**
+ * Does any of this configuration take effect here?
+ * (`road-to-delivered-cost-truth` Phase 3.)
+ *
+ * `doctorShell` states its own scope: Node version, package-root resolution,
+ * whether the Bash dispatcher exists. That is an ENVIRONMENT probe. It cannot
+ * answer whether a bound hook actually fires on this host — which is the
+ * question that decides whether any of the configuration this suite ships is
+ * doing anything here.
+ *
+ * FIVE STATES, NOT FOUR. The roadmap named four binding states; both council
+ * seats (2026-08-28, 2/2, resolving `how-far-the-effect-probe-may-reach` as
+ * option (c)) split one of them, and the split is real:
+ *
+ *   effective        fired, and a deny would have been honoured
+ *   bound-discarded  fired, and the host discards its output
+ *   bound-not-fired  the manifest binds it, and no dispatch was observed
+ *   unbound          the manifest does not bind it on this host
+ *   unknown          it was not safe to probe
+ *
+ * `bound-not-fired` and `unknown` were one bucket in the four-state model, and
+ * collapsing them hides the difference between "the host ignored it" and "we
+ * declined to look".
+ *
+ * ELIGIBILITY IS MEASURED, NOT DECLARED. Option (c) as written restricts
+ * dispatch to concerns that DECLARE themselves side-effect free, and both seats
+ * then said the same thing from different directions: a self-declared property
+ * nothing verifies is a weak control this repository flags as a defect
+ * elsewhere, and the dispatch should be sandboxed even for declared-safe
+ * concerns. Taken together that makes the declaration redundant — so this module
+ * measures the property instead: run the concern against a scratch root, compare
+ * the tree before and after, and treat any write as ineligible. A concern that
+ * writes is reported `unknown`, which is the honest answer and never a success.
+ *
+ * `unknown` IS NEVER RENDERED AS `effective`. That is the one rule every seat
+ * stated independently, and it is what the three coverage metrics exist to keep
+ * visible: a report can be truthful about each concern and still mislead, if
+ * almost nothing was actually probed.
+ */
+
+export const PROBE_STATES = ['effective', 'bound-discarded', 'bound-not-fired', 'unbound', 'unknown'] as const;
+export type ProbeState = (typeof PROBE_STATES)[number];
+
+/** The verdict a whole host gets. */
+export const HOST_VERDICTS = ['effective', 'partial', 'inert', 'unknown'] as const;
+export type HostVerdict = (typeof HOST_VERDICTS)[number];
+
+export interface ConcernProbe {
+    concern: string;
+    slot: string;
+    state: ProbeState;
+    /** Always populated — for `unknown` it is the reason the probe declined. */
+    reason: string;
+    /** Did the sandbox observe a write? `null` when no dispatch was attempted. */
+    wrote_in_sandbox: boolean | null;
+}
+
+export interface Coverage {
+    /** dispatched / total — tests the control itself. */
+    dispatch_rate: number;
+    /** non-unknown / total — where an answer exists at all. */
+    known_state_rate: number;
+    /** (effective + bound-discarded) / total — actual observed confidence. */
+    verified_rate: number;
+}
+
+export interface HostReport {
+    host: string;
+    probes: ConcernProbe[];
+    coverage: Coverage;
+    verdict: HostVerdict;
+    /** For `partial`, the slots that are inert. Empty otherwise. */
+    inert_slots: string[];
+    reason: string;
+}
+
+function rate(n: number, d: number): number {
+    return d === 0 ? 0 : n / d;
+}
+
+export function coverageOf(probes: readonly ConcernProbe[]): Coverage {
+    const total = probes.length;
+    const dispatched = probes.filter((p) => p.wrote_in_sandbox !== null).length;
+    const known = probes.filter((p) => p.state !== 'unknown').length;
+    const verified = probes.filter((p) => p.state === 'effective' || p.state === 'bound-discarded').length;
+    return {
+        dispatch_rate: rate(dispatched, total),
+        known_state_rate: rate(known, total),
+        verified_rate: rate(verified, total),
+    };
+}
+
+/**
+ * One verdict for the host.
+ *
+ * The ordering is the honesty: `unknown` is checked BEFORE `effective`, so a run
+ * that could not establish anything can never present itself as a working
+ * configuration. A single `effective` among a hundred `unknown`s is `unknown`,
+ * not `partial` — because the hundred were not measured, and `partial` is a
+ * claim about what IS inert rather than about what was not looked at.
+ */
+export function hostVerdict(probes: readonly ConcernProbe[]): { verdict: HostVerdict; inert: string[]; reason: string } {
+    if (probes.length === 0) {
+        return { verdict: 'unknown', inert: [], reason: 'no concern is bound on this host, so there is nothing to probe' };
+    }
+    const known = probes.filter((p) => p.state !== 'unknown');
+    if (known.length === 0) {
+        return {
+            verdict: 'unknown',
+            inert: [],
+            reason: `none of the ${String(probes.length)} bound concern(s) could be probed safely — no state was established`,
+        };
+    }
+    const effective = known.filter((p) => p.state === 'effective');
+    const inertProbes = known.filter((p) => p.state === 'bound-discarded' || p.state === 'bound-not-fired' || p.state === 'unbound');
+    const inert = [...new Set(inertProbes.map((p) => p.slot))].sort();
+
+    if (effective.length === 0) {
+        return {
+            verdict: 'inert',
+            inert,
+            reason: `no probed concern reached the model on this host (${String(known.length)} of ${String(probes.length)} probed)`,
+        };
+    }
+    if (inertProbes.length === 0 && known.length === probes.length) {
+        return { verdict: 'effective', inert: [], reason: `every bound concern (${String(probes.length)}) took effect` };
+    }
+    return {
+        verdict: 'partial',
+        inert,
+        reason:
+            `${String(effective.length)} of ${String(probes.length)} bound concern(s) took effect; ` +
+            `inert slot(s): ${inert.length === 0 ? 'none' : inert.join(', ')}` +
+            (known.length < probes.length ? ` · ${String(probes.length - known.length)} could not be probed` : ''),
+    };
+}
+
+export function buildHostReport(host: string, probes: readonly ConcernProbe[]): HostReport {
+    const v = hostVerdict(probes);
+    return { host, probes: [...probes], coverage: coverageOf(probes), verdict: v.verdict, inert_slots: v.inert, reason: v.reason };
+}