@event4u/agent-config 14.14.0 → 14.15.0

package/src/scripts/_lib/branch_convergence.ts

@@ -0,0 +1,186 @@
+/**
+ * Per-target branch-convergence policy — does the DEFAULT branch belong in the
+ * integration set when a PR targets something else?
+ *
+ * Decided by AI council on 2026-09-03 (`anthropic/claude-sonnet-4-5` +
+ * `openai/codex-default`) for the `cascade-default-inclusion-policy` blocker of
+ * `road-to-cascading-base-integration`. Both seats independently rejected the
+ * two offered answers — always-include, and include-past-a-commit-distance —
+ * and named the same third one: an explicit per-target policy read from
+ * repository intent. A commit-distance threshold was refused by both as an
+ * unmeasured constant.
+ *
+ * The load-bearing property is WHERE the policy is read from, and both seats
+ * called it non-negotiable: **the resolved PR target commit SHA, and nothing
+ * else.** Reading it from the PR head, the checkout, or an unpinned branch name
+ * lets a reviewed change edit its own acceptance criteria — the confused-deputy
+ * bypass. One seat: *"I would block any implementation reading policy from PR
+ * head, checkout state, or unpinned branch name."* So this module takes a
+ * `targetSha` it never resolves itself and a reader that can only answer at a
+ * SHA; there is deliberately no filesystem access anywhere in it.
+ *
+ * ── Where the policy file lives, and why it is NOT `.agent-settings.yml` ──
+ *
+ * The council's specification named `.agent-settings.yml`, section
+ * `branchConvergence`, on the premise that it is a committed file. In this
+ * repository, and in every consumer this package installs into, it is not:
+ * `.gitignore:317` ignores it here, and `src/config/gitignore-block.txt:56`
+ * writes that same ignore into every consumer's managed block. `git show
+ * <sha>:.agent-settings.yml` therefore returns nothing at every SHA in every
+ * repository this ships to, which would make the policy permanently unreadable
+ * and the feature dead on arrival.
+ *
+ * A SHA-pinned read requires a TRACKED file. The architecture the council
+ * specified is kept byte for byte — same section name, same shape, same
+ * exclusive read from the target SHA — and only the path moves, to a tracked
+ * repo-root file. If `.agent-settings.yml` ever becomes tracked, the
+ * `branchConvergence:` section moves across unchanged.
+ *
+ * Deferred by explicit council instruction and not to be added without
+ * reopening that decision: globs, pattern precedence, inheritance, configurable
+ * reason strings, and any repository-wide fallback policy.
+ */
+import { parse as parseYaml } from 'yaml';
+
+/** The tracked, SHA-readable file the policy is read from. */
+export const POLICY_PATH = '.branch-convergence.yml';
+
+/** The only two answers a target may give. Closed by council instruction. */
+export type DefaultBranchPolicy = 'include' | 'exclude';
+
+export interface BranchConvergenceTarget {
+    readonly defaultBranch: DefaultBranchPolicy;
+}
+
+export interface BranchConvergencePolicy {
+    readonly enabled: boolean;
+    /** Keyed by EXACT target branch name (`release/1.x`), never a pattern. */
+    readonly targets: Readonly<Record<string, BranchConvergenceTarget>>;
+}
+
+/**
+ * Read one path at one commit. Returns `null` when the path does not exist at
+ * that commit — which is a real answer, not an error.
+ *
+ * The signature takes the SHA FIRST and offers no way to ask for the working
+ * tree. That is the trust boundary expressed in a type: a caller cannot
+ * accidentally read the PR head, because there is no argument for it.
+ */
+export type ShaFileReader = (sha: string, repoPath: string) => string | null;
+
+/** The target is not the default branch and no exact entry names it. */
+export class MissingBranchConvergencePolicy extends Error {
+    readonly target: string;
+    constructor(target: string) {
+        super(`MissingBranchConvergencePolicy(target="${target}")`);
+        this.name = 'MissingBranchConvergencePolicy';
+        this.target = target;
+    }
+}
+
+/** The policy exists at the target SHA but does not validate. */
+export class InvalidBranchConvergencePolicy extends Error {
+    constructor(detail: string) {
+        super(`InvalidBranchConvergencePolicy: ${detail}`);
+        this.name = 'InvalidBranchConvergencePolicy';
+    }
+}
+
+/** The PR target names no commit the server will report. Fails closed. */
+export class UnresolvableTargetSha extends Error {
+    readonly target: string;
+    constructor(target: string) {
+        super(`UnresolvableTargetSha(target="${target}")`);
+        this.name = 'UnresolvableTargetSha';
+        this.target = target;
+    }
+}
+
+const TARGET_KEYS = new Set(['defaultBranch']);
+const ROOT_KEYS = new Set(['enabled', 'targets']);
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Parse and validate the `branchConvergence` section of a policy document.
+ *
+ * Exported separately from the SHA read so the VALIDATION is testable without a
+ * git object, for the same reason `classifyConflicts` is pure in
+ * `sync_pr_branch.ts`: the rejection of a malformed policy is the useful part,
+ * and a validator only reachable through a git call is a validator nobody
+ * covers.
+ *
+ * Duplicate keys are rejected by the YAML parser itself (`uniqueKeys` is on by
+ * default in `yaml` v2), so a target named twice is a parse failure rather than
+ * a silent last-wins.
+ */
+export function parseBranchConvergencePolicy(text: string): BranchConvergencePolicy | null {
+    let doc: unknown;
+    try {
+        doc = parseYaml(text);
+    } catch (exc) {
+        throw new InvalidBranchConvergencePolicy(exc instanceof Error ? exc.message : String(exc));
+    }
+    if (!isPlainObject(doc)) {
+        return null;
+    }
+    const section = doc['branchConvergence'];
+    if (section === undefined) {
+        return null;
+    }
+    if (!isPlainObject(section)) {
+        throw new InvalidBranchConvergencePolicy('`branchConvergence` is not a mapping');
+    }
+    for (const k of Object.keys(section)) {
+        if (!ROOT_KEYS.has(k)) {
+            throw new InvalidBranchConvergencePolicy(`unknown field \`branchConvergence.${k}\``);
+        }
+    }
+    const enabled = section['enabled'];
+    if (typeof enabled !== 'boolean') {
+        throw new InvalidBranchConvergencePolicy('`enabled` must be true or false');
+    }
+    const rawTargets = section['targets'] ?? {};
+    if (!isPlainObject(rawTargets)) {
+        throw new InvalidBranchConvergencePolicy('`targets` must be a mapping');
+    }
+    const targets: Record<string, BranchConvergenceTarget> = {};
+    for (const [name, entry] of Object.entries(rawTargets)) {
+        if (!isPlainObject(entry)) {
+            throw new InvalidBranchConvergencePolicy(`\`targets.${name}\` is not a mapping`);
+        }
+        for (const k of Object.keys(entry)) {
+            if (!TARGET_KEYS.has(k)) {
+                throw new InvalidBranchConvergencePolicy(`unknown field \`targets.${name}.${k}\``);
+            }
+        }
+        const v = entry['defaultBranch'];
+        if (v !== 'include' && v !== 'exclude') {
+            throw new InvalidBranchConvergencePolicy(
+                `\`targets.${name}.defaultBranch\` must be include or exclude, got ${JSON.stringify(v)}`,
+            );
+        }
+        targets[name] = { defaultBranch: v };
+    }
+    return { enabled, targets };
+}
+
+/**
+ * The policy as the PR TARGET carries it, at the target's own commit.
+ *
+ * `null` means the file does not exist at that commit. That is not an error
+ * here — it becomes `MissingBranchConvergencePolicy` one layer up, and only for
+ * a target that actually needs an entry.
+ */
+export function loadPolicyAtSha(targetSha: string, read: ShaFileReader): BranchConvergencePolicy | null {
+    if (!/^[0-9a-f]{7,40}$/.test(targetSha)) {
+        throw new InvalidBranchConvergencePolicy(`\`targetSha\` is not a commit id: ${JSON.stringify(targetSha)}`);
+    }
+    const text = read(targetSha, POLICY_PATH);
+    if (text === null) {
+        return null;
+    }
+    return parseBranchConvergencePolicy(text);
+}

package/src/scripts/_lib/context_observation.ts

@@ -0,0 +1,132 @@
+/**
+ * The situational-awareness fingerprint a run last OBSERVED, recorded where a
+ * stop-path concern can read it without spawning anything.
+ *
+ * `road-to-wired-instruments` Phase 2.1. The fingerprint itself is built by
+ * `roadmap_context.ts` from `origin/main` plus every open PR head — which costs
+ * a `gh` call, so it can only be taken by the probe and never by a hook on the
+ * Stop path, where a subprocess is a cost paid on every reply.
+ *
+ * Why a file, and why this comparison and not another:
+ * `run_checkpoint.RunCheckpoint.context_fingerprint` already had the right idea
+ * and no producer: `session_eol_hook` built its checkpoints without ever passing
+ * one, so the field was `null` in every checkpoint this package has ever
+ * written. A drift detector whose input is structurally always-null reports no
+ * drift, forever — the defect class this roadmap exists over, in the mechanism
+ * meant to catch it. This module is the missing producer, and it makes the
+ * value reachable from BOTH consumers: the checkpoint and the continuation
+ * ladder.
+ *
+ * The comparison the ladder makes is deliberately narrow: the fingerprint this
+ * run ENGAGED under, against the newest one the run itself has OBSERVED. It is
+ * not "has `origin/main` moved", which changes constantly and would halt every
+ * long run within a day (Risk 1 of the roadmap). Nothing is observed unless the
+ * run re-probes, so the rung cannot fire on repository traffic the run never
+ * looked at — it fires when the run looked, and what it saw had changed.
+ *
+ * Best-effort throughout. A failed write or an unreadable file is `null`, which
+ * reads as "not known" and never as "unchanged": an absent observation must
+ * never manufacture a halt, and must never assert the world stood still either.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { atomicWriteJson } from './loop_guards.js';
+
+export const CONTEXT_OBSERVATION_REL = path.join(
+    'agents',
+    'runtime',
+    'state',
+    'context-observation.json',
+);
+
+/**
+ * One probe's reading.
+ *
+ * NOT keyed on a roadmap, because the fingerprint is not scoped to one:
+ * `contextFingerprint(base_sha, open_prs)` takes the base ref and every open PR
+ * head and no roadmap at all. A per-roadmap file would key a repository-wide
+ * fact on something it does not depend on, and would then miss every observation
+ * taken by an unscoped `roadmap:context` run. `roadmap` is recorded as
+ * provenance — which invocation took the reading — never as a lookup key.
+ */
+export interface ContextObservation {
+    readonly schema_version: 1;
+    /** The roadmap the probe was scoped to, or `''` when it was unscoped. */
+    readonly roadmap: string;
+    /** `roadmap_context.contextFingerprint()` — compared, never parsed. */
+    readonly fingerprint: string;
+    /** ISO-8601 instant of the observation. */
+    readonly at: string;
+}
+
+/** The single observation file. */
+export function observationFile(repoRoot: string): string {
+    return path.join(repoRoot, CONTEXT_OBSERVATION_REL);
+}
+
+/**
+ * Record what the probe just saw. Returns whether the write landed.
+ *
+ * Never throws: this is called from a reporting command, and a command that
+ * fails because it could not write a diagnostic breadcrumb is worse than one
+ * whose breadcrumb is missing.
+ */
+export function recordContextObservation(
+    repoRoot: string,
+    scope: string,
+    fingerprint: string,
+    now: () => Date = () => new Date(),
+): boolean {
+    if (fingerprint.trim() === '') return false;
+    const obs: ContextObservation = {
+        schema_version: 1,
+        roadmap: scope,
+        fingerprint,
+        at: now().toISOString(),
+    };
+    try {
+        fs.mkdirSync(path.dirname(observationFile(repoRoot)), { recursive: true });
+    } catch {
+        return false;
+    }
+    return atomicWriteJson(observationFile(repoRoot), obs);
+}
+
+/** The newest recorded observation, or `null` when none reads. */
+export function readContextObservation(repoRoot: string): ContextObservation | null {
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(observationFile(repoRoot), 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+        const o = parsed as Record<string, unknown>;
+        if (typeof o['fingerprint'] !== 'string' || o['fingerprint'] === '') return null;
+        if (typeof o['at'] !== 'string') return null;
+        return {
+            schema_version: 1,
+            roadmap: typeof o['roadmap'] === 'string' ? o['roadmap'] : '',
+            fingerprint: o['fingerprint'],
+            at: o['at'],
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Has the plan premise moved?
+ *
+ * TRUE only when both sides are known AND differ. An unknown on either side is
+ * "not known", exactly as `run_checkpoint.verifyCheckpoint` treats `head` and
+ * `context_fingerprint`: a detector that reads "I could not tell" as "it moved"
+ * halts healthy runs, and one false alarm on a rung that ends a run costs more
+ * than a missed one, because it trains the operator to switch the rung off.
+ */
+export function premiseMoved(
+    claimed: string | null | undefined,
+    observed: string | null | undefined,
+): boolean {
+    if (claimed === null || claimed === undefined || claimed === '') return false;
+    if (observed === null || observed === undefined || observed === '') return false;
+    return claimed !== observed;
+}

package/src/scripts/_lib/continuation_ladder.ts

@@ -0,0 +1,188 @@
+/**
+ * The run-continuation termination ladder — the pure decision, on its own.
+ *
+ * Extracted from `hooks/run_continuation_hook.ts` by `road-to-wired-instruments`
+ * Phase 2, for two reasons and one constraint. The reasons: the ladder is a pure
+ * function over a state record and three numbers, and it is the surface Phase 2
+ * changes, so the rung under change gets a home where it can be read without
+ * 1,500 lines of I/O around it. The constraint: `check_source_size_budget` is a
+ * ratchet and the hook sits PAST the 1,500-line cap, where every added line is
+ * an added violation — so the phase pays for its additions by moving the code it
+ * is editing to a file under the cap, rather than by raising a baseline.
+ *
+ * `LadderState` is structural on purpose. The hook's `RunState` carries a dozen
+ * fields this decision has no business reading, and taking the whole record here
+ * would invert the dependency: a `_lib` module importing from a hook.
+ */
+
+import type { UnavailableDependency } from './loop_guards.js';
+import type { RunTerminalState } from './outcome_vocabularies.js';
+
+/** Iterations one run may spend before the cap ends it. */
+export const MAX_ITERATIONS = 25;
+/** Wall-clock a run may span before the clock ends it. */
+export const WALL_CLOCK_CAP_MS = 4 * 60 * 60 * 1000;
+/** Identical consecutive open-step readings that read as a stall. */
+export const STALL_WINDOW = 3;
+
+export type LadderAction =
+    | 'engage'
+    | 'complete'
+    | 'blocked'
+    | 'halt-max-iterations'
+    | 'halt-wall-clock'
+    | 'halt-stall'
+    | 'halt-dependency-unavailable'
+    | 'halt-premise-invalidated';
+
+/** The terminal rungs — the set `RunState.halted` may hold. */
+/**
+ * `halt-roadmap-absent` is deliberately NOT in this union and not in
+ * `LadderAction`. It is an event name the caller emits directly when the claimed
+ * roadmap is unreadable from the authoritative tree, and it CLEARS the state
+ * rather than stamping `halted` — widening the union would let `parseRecord`
+ * accept it as a `halted` value, which would mean a run whose budget was cleared
+ * also carried a halt stamp. The two are mutually exclusive by construction.
+ */
+export const HALT_ACTIONS: readonly LadderAction[] = [
+    'halt-max-iterations',
+    'halt-wall-clock',
+    'halt-stall',
+    // Phase 5.4. Checked BEFORE the counter rungs: a dependency the run cannot
+    // obtain is not something more iterations close, so consuming the budget
+    // against it is the waste the rung exists to stop.
+    'halt-dependency-unavailable',
+    // `road-to-wired-instruments` 2.2, and BEFORE the counter rungs for the same
+    // reason: a run whose plan premise moved does not become correct by running
+    // more iterations against the stale plan, and letting it cap out reports
+    // `exhausted` — a budget problem, whose remedy is a bigger budget — for what
+    // is actually a staleness problem, whose remedy is a re-probe.
+    'halt-premise-invalidated',
+];
+
+/**
+ * The subset of a run's state this decision reads. The hook's `RunState`
+ * satisfies it structurally; nothing here may widen beyond what the rungs use.
+ */
+export interface LadderState {
+    readonly halted?: LadderAction;
+    readonly iterations: number;
+    readonly started_at: string;
+    readonly history: readonly number[];
+}
+
+/**
+ * The run terminal state each ladder action reports, or `null` for the one
+ * action that is not terminal.
+ *
+ * This is a REAL crossing between two vocabularies, and the reason it exists at
+ * all is that a terminal state nothing produces is the defect this roadmap is
+ * named after. The ladder decides in its own words — the rung a reader of the
+ * ledger needs — and the run vocabulary is what a closing report must say
+ * (`contexts/execution/terminal-states.md`). Registered as a row in
+ * `outcome_vocabularies.CROSS_DOMAIN_MAPPINGS`, which is the one place a reader
+ * looks to learn a crossing exists.
+ *
+ * `halt-wall-clock` and `halt-max-iterations` both report `exhausted`: they are
+ * two budgets, and the contract's word covers "a declared budget ran out"
+ * without distinguishing which. `halt-dependency-unavailable` reports `blocked`
+ * — a thing that is absent, which is that state's own definition.
+ */
+export const TERMINAL_STATE_BY_ACTION: Readonly<Record<LadderAction, RunTerminalState | null>> = {
+    engage: null,
+    complete: 'success',
+    blocked: 'blocked',
+    'halt-max-iterations': 'exhausted',
+    'halt-wall-clock': 'exhausted',
+    'halt-stall': 'stagnated',
+    'halt-dependency-unavailable': 'blocked',
+    'halt-premise-invalidated': 'premise-invalidated',
+};
+
+/** The run terminal state for a ladder action; `null` while the run continues. */
+export function terminalStateFor(action: LadderAction): RunTerminalState | null {
+    return TERMINAL_STATE_BY_ACTION[action] ?? null;
+}
+
+/**
+ * The termination ladder, pure. `state` is the record BEFORE this stop;
+ * `openCount` is the scan of the claimed roadmap as it stands now.
+ */
+export function ladder(
+    state: LadderState,
+    openCount: number,
+    nowMs: number,
+    // No default: `= 0` would silently restore the complete-instead-of-blocked
+    // behaviour for any caller that omitted it.
+    blockedCount: number,
+    caps: { maxIterations: number; wallClockMs: number; stallWindow: number } = {
+        maxIterations: MAX_ITERATIONS,
+        wallClockMs: WALL_CLOCK_CAP_MS,
+        stallWindow: STALL_WINDOW,
+    },
+    // Phase 5.4. `null` when nothing unobtainable was detected. Optional so every
+    // existing caller and test keeps its meaning unchanged.
+    unavailable: UnavailableDependency | null = null,
+    // `road-to-wired-instruments` 2.1. TRUE only when the run's engaged-under
+    // fingerprint and its newest observation are BOTH known and differ — see
+    // `_lib/context_observation.premiseMoved`. Optional and defaulted false, so
+    // a caller that cannot observe the world decides exactly as it did before.
+    premiseInvalidated: boolean = false,
+): LadderAction {
+    // A halt is terminal for this run id. Checked BEFORE `complete` so a
+    // halted run whose roadmap later reads zero-open does not report a
+    // completion it never reached.
+    if (state.halted) return state.halted;
+    // `scanOpenSteps` EXCLUDES `blocked-by:` steps from `openCount`, so zero-open
+    // with blocked steps left is exhaustion of runnable work, not completion —
+    // ADR-235's own terminal outcome, and never a sixth halt.
+    if (openCount === 0) return blockedCount > 0 ? 'blocked' : 'complete';
+    // BEFORE the counter rungs, deliberately: a missing credential, an absent
+    // binary or an exhausted quota is not closed by iterating, so spending the
+    // budget on it converts a nameable blocker into an anonymous cap-out.
+    if (unavailable !== null) return 'halt-dependency-unavailable';
+    // 2.2 — also before the counter rungs, and AFTER the zero-open rungs: a run
+    // that has actually finished its scope reports `complete`, because a stale
+    // premise cannot un-finish work already done and verified. Everything below
+    // this line is a budget, and a budget is the wrong word for staleness.
+    if (premiseInvalidated) return 'halt-premise-invalidated';
+    if (state.iterations >= caps.maxIterations) return 'halt-max-iterations';
+    const started = Date.parse(state.started_at);
+    if (Number.isFinite(started) && nowMs - started >= caps.wallClockMs) {
+        return 'halt-wall-clock';
+    }
+    const tail = state.history.slice(-caps.stallWindow);
+    if (tail.length >= caps.stallWindow && tail.every((n) => n === openCount)) {
+        return 'halt-stall';
+    }
+    return 'engage';
+}
+
+/**
+ * Read a persisted `halted` stamp tolerantly.
+ *
+ * `road-to-wired-instruments` 2.3. `LadderAction` is the SECOND value domain
+ * this phase widened — the run-state file records the rung that ended a run —
+ * so it owes the same forward-compatibility answer the run vocabulary got. The
+ * previous reader accepted only members of `HALT_ACTIONS` and dropped anything
+ * else, which does not crash but downgrades a halt stamped by a newer build to
+ * NO HALT: the older binary then re-engages a run that was deliberately ended.
+ * Fail-open in the one direction a budget must not fail open.
+ *
+ * So an unrecognised `halt-`prefixed value is PRESERVED. That is safe by
+ * inspection of every consumer: `ladder` returns a stamp verbatim, and the
+ * caller's branches are equality tests against known names whose default is
+ * "allow this stop and write nothing" — the correct behaviour for a halt whose
+ * name this build cannot interpret. The old reader's docblock claimed such a
+ * value would "become an action no branch below handles"; that was never true
+ * for a halt-prefixed one, and the claim is corrected here rather than carried.
+ *
+ * Anything not `halt-`prefixed is still dropped: `engage`, `complete` and
+ * `blocked` are not stamps, and accepting one here would immortalise a state
+ * file that the terminal branches delete.
+ */
+export function parseHaltStamp(v: unknown): LadderAction | null {
+    if (typeof v !== 'string') return null;
+    if ((HALT_ACTIONS as readonly string[]).includes(v)) return v as LadderAction;
+    return v.startsWith('halt-') ? (v as LadderAction) : null;
+}

package/src/scripts/_lib/experiment_binding.ts

@@ -0,0 +1,95 @@
+/**
+ * The binding that joins an `evolution_lab run` to a frozen `ExperimentSpec`.
+ *
+ * `experiment_freeze.ts` sits between two mechanisms that both stop looking
+ * before the interesting window opens. `evolution_lab` fails closed on a
+ * holdout leak and on a budget breach, and both guards fire BEFORE the run
+ * starts. `corpus_manifest` pins the corpus as a capture taken at a moment and
+ * compared by a human running a verb. Neither watches the run while it happens,
+ * and `verbRun` has a real mid-run window: it walks the record set once to
+ * clone, then RE-READS every record from disk to evaluate it. A record
+ * rewritten between those two reads yields a run that cloned one thing and
+ * scored another, and every individual reading looks fine.
+ *
+ * This is the join, not a second pinning scheme: the five frozen elements are
+ * built from identities the run already carries — the cascade stage order, a
+ * digest of the record set, the promotion-evidence field set, the unmutated
+ * tree shape every clone is made from, and the protected surfaces each clone
+ * inherits. A freeze over invented identities freezes nothing, because nothing
+ * else in the process reads them.
+ *
+ * The digest is deliberately not persisted. A freeze whose scope is one process
+ * needs no store, and a stored digest immediately raises the question of who
+ * invalidates it.
+ */
+
+import * as crypto from 'node:crypto';
+
+import { WITH_SURFACES, target_shape_hash } from '../bench_ab_clone.js';
+import { CASCADE_STAGES } from './evaluation_cascade.js';
+import { PROMOTION_EVIDENCE_FIELDS } from './promotion_evidence.js';
+import type { ExperimentSpec } from './experiment_freeze.js';
+
+/**
+ * Identity of the evaluator: which stages, in which order.
+ *
+ * Order is part of the identity and is NOT sorted away. The cascade is a
+ * cheapest-first sequence whose whole economic claim is that an early stage
+ * aborts before an expensive one runs; two runs that scored the same candidates
+ * in a different stage order did not use the same evaluator.
+ */
+export function evaluatorIdentity(): string {
+    return `evaluation-cascade:${CASCADE_STAGES.join('>')}`;
+}
+
+/**
+ * Identity of the task the arms are scored against.
+ *
+ * Sorted, unlike the evaluator: the evidence fields are a SET a candidate must
+ * satisfy, and the order they happen to be declared in is not a property of the
+ * task.
+ */
+export function taskIdentity(): string {
+    return `promotion-evidence:${[...PROMOTION_EVIDENCE_FIELDS].sort().join('+')}`;
+}
+
+/**
+ * A digest over the record set actually being run.
+ *
+ * Takes `(path, bytes)` pairs rather than reading the files itself, so the
+ * caller decides what "the record set" is and this function stays pure. Sorted
+ * by path, because the order a directory happened to enumerate in is not a
+ * property of the corpus — the same argument `experiment_freeze` makes for
+ * fixtures.
+ */
+export function recordSetDigest(entries: ReadonlyArray<readonly [path: string, bytes: string]>): string {
+    const h = crypto.createHash('sha256');
+    for (const [p, bytes] of [...entries].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) {
+        h.update(`${p}\n`, 'utf-8');
+        h.update(crypto.createHash('sha256').update(bytes, 'utf-8').digest('hex'), 'utf-8');
+        h.update('\n', 'utf-8');
+    }
+    return `records:${h.digest('hex').slice(0, 32)}`;
+}
+
+/**
+ * Build the spec for one `evolution_lab run`.
+ *
+ * `readFile` is injected so the same construction is exercised in a test
+ * without a repository tree, and `baseline` is injected for the same reason —
+ * `target_shape_hash()` walks a fixture directory, which a unit test has no
+ * business depending on.
+ */
+export function buildRunSpec(
+    recordFiles: readonly string[],
+    readFile: (p: string) => string,
+    baseline: string = target_shape_hash(),
+): ExperimentSpec {
+    return {
+        evaluator: evaluatorIdentity(),
+        corpus: recordSetDigest(recordFiles.map((f) => [f, readFile(f)] as const)),
+        task: taskIdentity(),
+        baseline,
+        fixtures: [...WITH_SURFACES],
+    };
+}

package/src/scripts/_lib/ignored_blocker.ts

@@ -105,11 +105,18 @@ export interface JournalConsumptionRow {
  * cannot drift: if this string and {@link rowIsIgnoredBlocker} ever disagree,
  * the disagreement is visible in one file. It is a documented query shape, not
  * a live query — nothing in this module opens a database.
+ *
+ * The `IN` list is DERIVED from {@link NON_SUCCESS_STATES}, not written out.
+ * It used to be four hand-typed literals, and "kept beside the predicate so the
+ * two cannot drift" was true of the FILE and false of the LIST: when the run
+ * vocabulary gained a seventh state (`road-to-wired-instruments` 2.3) the
+ * predicate picked it up from the set and this string did not, so the same
+ * module answered its own question two ways. Co-location is not a binding.
  */
 export const IGNORED_BLOCKER_QUERY = `
 SELECT episode_id, state, suggestion
 FROM journal_events
-WHERE state IN ('blocked', 'approval-required', 'exhausted', 'stagnated')
+WHERE state IN (${[...NON_SUCCESS_STATES].map((s) => `'${s}'`).join(', ')})
   AND consumption IS NULL
 ORDER BY episode_id
 `.trim();

package/src/scripts/_lib/outcome_envelope.ts

@@ -23,7 +23,7 @@
 import type { RunTerminalState } from './outcome_vocabularies.js';
 
 /**
- * The six terminal states. Contract: `contexts/execution/terminal-states.md`.
+ * The run terminal states. Contract: `contexts/execution/terminal-states.md`.
  *
  * Alias of the registry's `RunTerminalState`. This module stays the public
  * surface — `runtime_journal.test.ts:212` pins the import path and `:215`
@@ -39,6 +39,11 @@ export const NON_SUCCESS_STATES: ReadonlySet<TerminalState> = new Set([
     'approval-required',
     'exhausted',
     'stagnated',
+    // A run that stopped because its plan premise moved owes the reader the
+    // same thing every other non-success state owes: what to do next. Here that
+    // is always "re-probe and re-plan", and leaving it out of this set would let
+    // an envelope report a halted run with no next action at all.
+    'premise-invalidated',
 ]);
 
 /**