@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/_lib/capture_rate.ts

@@ -0,0 +1,319 @@
+/**
+ * capture_rate — the measurement itself: numerator ÷ denominator, reported with
+ * a 95 % Wilson score interval, judged on the LOWER bound.
+ *
+ * `road-to-supervised-telemetry-collector` step 1.2 item 9 and step 1.3 fixed
+ * the decision rule before any number existed, so it could not be chosen after:
+ *
+ * > Capture rate = numerator ÷ denominator, both as defined above, reported with
+ * > a **95 % Wilson score interval**. The target in 1.3 is met when the **lower
+ * > bound** of that interval is at or above the target — not the point estimate.
+ *
+ * > **≥ 90 % capture**, read as the lower bound of the 95 % Wilson interval,
+ * > over the **21-day window** and **≥ 2,000 eligible dispatches across ≥ 5
+ * > machines**.
+ *
+ * This module computes that, and nothing else. It does not decide, does not
+ * enable anything, and does not read the clock — the window boundaries are
+ * inputs, because a measurement module that reads `Date.now()` cannot be tested
+ * against a fixed window.
+ *
+ * ## Why it exists before the window does
+ *
+ * AI council, 2026-08-30 (DEGRADED — 1 of 2 seats; `openai` absent,
+ * `os_error: ENOBUFS`), on the disposition of Phase 6: the seat chose option (d)
+ * and made this a **prerequisite checkpoint between Phase 5 and Phase 6** rather
+ * than a substitute for 6.1 —
+ *
+ * > The synthetic test is a checkpoint, not a Phase 6 step. It answers "does the
+ * > instrument work?" before asking "what does it measure?"
+ *
+ * So: seeded opportunities and captures, an asserted ratio, an asserted Wilson
+ * bound, the minimum-sample boundary, malformed input, and duplicate
+ * suppression — all verifiable with zero elapsed days. **It proves the
+ * instrument. It claims nothing about the field measurement**, which needs 21
+ * days that no run can compress.
+ *
+ * ## NO PRODUCTION CALLER, and that is the honest state rather than an omission
+ *
+ * `judgeCapture`, `judgeEnablement` and `readOpportunities`' window parameter
+ * are called from tests and from nothing else (R2 round-4 finding 12). The
+ * consumer is Phase 6, which is parked: 6.1 needs a 21-day window, 6.2 reads
+ * these verdicts, and neither has run. Naming it here because this module's own
+ * argument — that the two halves of the ratio must age on the same clock — reads
+ * as if something computed the ratio today, and nothing does.
+ *
+ * It is deliberately NOT the same class as the two no-caller defects this
+ * change fixed. `spoolRecord` and `terminateCollector` had consumers that were
+ * supposed to exist and did not; these have a consumer that is scheduled and
+ * blocked, which is why the roadmap leaves AC-10 unchecked rather than claiming
+ * the instrument is in use.
+ */
+
+/** The confidence level the decision rule fixes. Not a parameter — 1.2 item 9 names it. */
+export const WILSON_Z = 1.959963984540054; // two-sided 95 %
+
+/** The target from 1.3, as a proportion. Read as a LOWER bound, never a point estimate. */
+export const CAPTURE_TARGET = 0.9;
+
+/** Minimum sample from 1.2 items 7–8. Below this the reading is not eligible at all. */
+export const MINIMUM_SAMPLE = 2_000;
+export const MINIMUM_MACHINES = 5;
+
+/**
+ * No single machine may contribute more than this share of the denominator.
+ *
+ * The third sample constraint from 1.2 item 7, dropped by the first
+ * implementation (R2 round-5 finding 7) with its reason attached: *"a rate
+ * measured on one machine measures that machine's supervisor, not the
+ * population's"*. `MINIMUM_SAMPLE` and `MINIMUM_MACHINES` are both satisfiable
+ * by 1,996 dispatches from one machine and one apiece from four others.
+ */
+export const MAX_MACHINE_SHARE = 0.4;
+export const WINDOW_DAYS = 21;
+
+export interface Interval {
+    readonly lower: number;
+    readonly upper: number;
+}
+
+/**
+ * The Wilson score interval for a binomial proportion.
+ *
+ * Wilson rather than the normal approximation because the normal one is wrong
+ * exactly where this measurement lives: near a proportion of 1, it produces an
+ * upper bound above 1 and a spuriously narrow interval. At `n = 0` there is no
+ * proportion to estimate, and the honest interval is the whole range `[0, 1]` —
+ * NOT `[0, 0]`, which would read as "we measured zero capture" rather than "we
+ * measured nothing".
+ */
+export function wilsonInterval(successes: number, trials: number, z: number = WILSON_Z): Interval {
+    if (!Number.isInteger(successes) || !Number.isInteger(trials)) {
+        throw new TypeError('wilsonInterval: counts must be integers');
+    }
+    if (successes < 0 || trials < 0 || successes > trials) {
+        throw new RangeError(
+            `wilsonInterval: impossible counts (${successes} of ${trials})`,
+        );
+    }
+    if (trials === 0) return Object.freeze({ lower: 0, upper: 1 });
+
+    const p = successes / trials;
+    const z2 = z * z;
+    const denominator = 1 + z2 / trials;
+    const centre = p + z2 / (2 * trials);
+    const spread = z * Math.sqrt((p * (1 - p) + z2 / (4 * trials)) / trials);
+    return Object.freeze({
+        lower: Math.max(0, (centre - spread) / denominator),
+        upper: Math.min(1, (centre + spread) / denominator),
+    });
+}
+
+export interface CaptureReading {
+    /** Records that reached the store, de-duplicated. */
+    readonly numerator: number;
+    /** Dispatch opportunities recorded by the independent writer. */
+    readonly denominator: number;
+    /**
+     * Distinct machines contributing to the denominator.
+     *
+     * **NOT derivable from the denominator artifact as it ships**, and saying so
+     * is the honest form (R2 round-5 finding 8). `recordOpportunity` writes
+     * `date\tevent\tplatform` with no machine identifier, so the only place a
+     * machine id exists is the STORE — the numerator. Counting the floor there
+     * biases it in the same direction as everything else this module warns
+     * about: a machine that captured nothing contributes zero and the
+     * population looks smaller than it is.
+     *
+     * The field is therefore an INPUT the caller must supply from somewhere
+     * that knows, and Phase 6 is where that caller is built. Closing it means
+     * either a machine column on the opportunity line — which is a schema
+     * change and a privacy question, since a machine id beside a date is the
+     * fingerprint `FIELD_PURPOSE` argues against — or an out-of-band count.
+     * Neither is decided here.
+     */
+    readonly machines: number;
+    /**
+     * The largest single machine's share of the denominator, 0..1.
+     *
+     * Same provenance problem as `machines`, same honest treatment: supplied by
+     * the caller, `null` when unknown. `null` is INELIGIBLE rather than
+     * passing — an unmeasured concentration is not a satisfied one.
+     */
+    // `| undefined` explicitly: `exactOptionalPropertyTypes` is on, so an
+    // optional property does NOT implicitly accept `undefined` — and a caller
+    // that has not measured the share is exactly the case this field exists to
+    // report as ineligible.
+    readonly maxMachineShare?: number | null | undefined;
+    /** Whole days elapsed in the observation window. */
+    readonly windowDays: number;
+}
+
+export type EligibilityFailure =
+    | 'window-too-short'
+    | 'sample-too-small'
+    | 'too-few-machines'
+    | 'numerator-exceeds-denominator'
+    /** One machine contributes more than {@link MAX_MACHINE_SHARE} of the denominator. */
+    | 'machine-concentration'
+    /**
+     * A count that is negative, fractional, or not a number at all.
+     *
+     * Its own member rather than a shared "impossible" bucket, because the
+     * remedy differs: `numerator-exceeds-denominator` is a counting bug in the
+     * two writers, `malformed-counts` is a corrupt reading. Before this existed
+     * such a reading fell straight through to `wilsonInterval` and CRASHED —
+     * the one class of bad input this module's three-valued design was built to
+     * report rather than throw on (R2 finding 15).
+     */
+    | 'malformed-counts';
+
+export interface CaptureVerdict {
+    /** Point estimate. `null` when the denominator is 0 — a ratio, not a zero. */
+    readonly rate: number | null;
+    readonly interval: Interval;
+    /** Whether the reading may be judged against the target at all. */
+    readonly eligible: boolean;
+    /** Why not. Empty when eligible. */
+    readonly ineligibleBecause: readonly EligibilityFailure[];
+    /**
+     * `true` / `false` only when eligible; `null` when the reading cannot be
+     * judged. A three-valued verdict, because "not eligible" collapsed to
+     * `false` reads as a MISS — and a miss triggers 6.3's decision record for a
+     * measurement that never happened.
+     */
+    readonly meetsTarget: boolean | null;
+}
+
+/**
+ * Judge a reading against the 1.3 target.
+ *
+ * Eligibility is checked BEFORE the comparison and reported separately, because
+ * the two questions have different consequences: an ineligible reading means
+ * keep observing, a miss means run 6.3. Collapsing them is how a 200-dispatch
+ * sample becomes a recorded failure.
+ */
+export function judgeCapture(
+    reading: CaptureReading,
+    target: number = CAPTURE_TARGET,
+): CaptureVerdict {
+    const failures: EligibilityFailure[] = [];
+
+    // Checked FIRST, and it is the guard that keeps `wilsonInterval` from
+    // raising: that function throws on a negative or fractional count, by
+    // design, and a judge that propagates the throw cannot report anything.
+    const countsAreSane =
+        Number.isInteger(reading.numerator)
+        && Number.isInteger(reading.denominator)
+        && reading.numerator >= 0
+        && reading.denominator >= 0;
+    if (!countsAreSane) failures.push('malformed-counts');
+    else if (reading.numerator > reading.denominator) {
+        failures.push('numerator-exceeds-denominator');
+    }
+    if (!Number.isFinite(reading.windowDays) || reading.windowDays < WINDOW_DAYS) {
+        failures.push('window-too-short');
+    }
+    if (!Number.isFinite(reading.denominator) || reading.denominator < MINIMUM_SAMPLE) {
+        failures.push('sample-too-small');
+    }
+    if (!Number.isFinite(reading.machines) || reading.machines < MINIMUM_MACHINES) {
+        failures.push('too-few-machines');
+    }
+    const share = reading.maxMachineShare;
+    if (share === undefined || share === null || !Number.isFinite(share) || share > MAX_MACHINE_SHARE) {
+        failures.push('machine-concentration');
+    }
+
+    const uncomputable =
+        failures.includes('numerator-exceeds-denominator') || failures.includes('malformed-counts');
+    const interval = uncomputable
+        ? Object.freeze({ lower: 0, upper: 1 })
+        : wilsonInterval(reading.numerator, reading.denominator);
+    const rate =
+        uncomputable || reading.denominator === 0
+            ? null
+            : reading.numerator / reading.denominator;
+    const eligible = failures.length === 0;
+
+    return Object.freeze({
+        rate,
+        interval,
+        eligible,
+        ineligibleBecause: Object.freeze(failures),
+        // The lower bound, never the point estimate. A point estimate that
+        // clears the target on a sample whose interval straddles it has not
+        // cleared it, and 1.2 item 9 fixed that before the number existed.
+        meetsTarget: eligible ? interval.lower >= target : null,
+    });
+}
+
+/**
+ * The six readings 6.2 requires, as a type that cannot be partially filled.
+ *
+ * Every field is required and `null` is a legal value meaning **not recorded**.
+ * That is the shape the step demands — *"a missing reading blocks the flip"* —
+ * and an optional field would let a caller omit one and still typecheck.
+ *
+ * The type is not the enforcement, though, and treating it as such was a defect:
+ * {@link judgeEnablement} accepts only a literal `true`, so a key absent at
+ * RUNTIME blocks the flip exactly like an explicit `null`. A compile-time
+ * guarantee does not survive `JSON.parse` or a cast, and these readings are
+ * precisely the kind of object that arrives through both.
+ */
+export interface EnablementReadings {
+    readonly captureTargetMet: boolean | null;
+    readonly lifecycleGreenOnEveryPlatform: boolean | null;
+    readonly resourceBudgetsMet: boolean | null;
+    readonly noPrivacyOrIntegrityIncident: boolean | null;
+    readonly staticModeCompatible: boolean | null;
+    readonly windowAndSampleSatisfied: boolean | null;
+}
+
+export const ENABLEMENT_READING_NAMES = [
+    'captureTargetMet',
+    'lifecycleGreenOnEveryPlatform',
+    'resourceBudgetsMet',
+    'noPrivacyOrIntegrityIncident',
+    'staticModeCompatible',
+    'windowAndSampleSatisfied',
+] as const;
+
+export interface EnablementVerdict {
+    readonly flip: boolean;
+    /** Readings that are `null`. A missing reading blocks, and is not a failure. */
+    readonly missing: readonly string[];
+    /** Readings that are `false`. */
+    readonly failed: readonly string[];
+}
+
+/**
+ * Decide whether the default may flip.
+ *
+ * Missing and failed are reported separately for the same reason eligibility is
+ * separate above: "we did not look" and "we looked and it was bad" call for
+ * different actions, and one of them is 6.3.
+ */
+export function judgeEnablement(readings: EnablementReadings): EnablementVerdict {
+    const missing: string[] = [];
+    const failed: string[] = [];
+    for (const name of ENABLEMENT_READING_NAMES) {
+        const value = readings[name];
+        // ACCEPT ONLY `true` (R2 round-3 finding 4). The first version tested
+        // `=== null` then `=== false`, so a key that was ABSENT at runtime was
+        // neither and still yielded `flip: true`. The type made omission a
+        // compile error and these readings are exactly the kind of object
+        // assembled from JSON or a cast — including in this module's own tests —
+        // so the guarantee held everywhere except where it mattered. The step's
+        // rule is "a missing reading blocks the flip", and only a positive test
+        // for `true` implements it.
+        if (value === true) continue;
+        if (value === false) failed.push(name);
+        else missing.push(name);
+    }
+    return Object.freeze({
+        flip: missing.length === 0 && failed.length === 0,
+        missing: Object.freeze(missing),
+        failed: Object.freeze(failed),
+    });
+}

package/src/scripts/_lib/carrier_status.ts

@@ -0,0 +1,118 @@
+/**
+ * The `status: carrier` predicate, and the reasoning five readers share.
+ *
+ * A carrier is a roadmap whose job is to hold obligations deferred out of a
+ * parent that is already archived. Every item in it has an unmet resumption
+ * trigger, and it has no `## Phase` headings, so it is skipped wherever a draft
+ * is: the dashboard, `/roadmap:process-*`, the trackability check and the plan
+ * risk register. It differs from a draft in what it costs to remove — a draft
+ * may be deleted freely, a carrier may not.
+ *
+ * This module exists because the predicate had two implementations within one
+ * change and five callers within one week. Two implementations of one frontmatter
+ * test drift, and the one nobody runs locally drifts first — the same
+ * memory-twin failure this repository has already recorded against a fixture
+ * corpus. One test, one place, and the reasoning above lives beside it rather
+ * than being restated in each caller.
+ *
+ * The read is frontmatter-scoped on purpose. A fenced `status: carrier` inside a
+ * roadmap that documents the syntax is not a declaration, and a body-wide match
+ * turned exactly that into a hard failure before a review caught it.
+ */
+
+/** The frontmatter values that mean "not schedulable work, and not disposable". */
+export const CARRIER_VALUES: ReadonlySet<string> = new Set(['carrier']);
+
+/** The leading `---\n…\n---` block, or null when the text carries none. */
+export function frontmatterBlock(text: string): string | null {
+    const m = /^---\n([\s\S]*?)\n---/.exec(text);
+    return m === null ? null : (m[1] ?? '');
+}
+
+/** True when `text`'s FRONTMATTER declares one of {@link CARRIER_VALUES}. */
+export function declaresCarrier(text: string | null | undefined): boolean {
+    if (text === null || text === undefined) {
+        return false;
+    }
+    const fm = frontmatterBlock(text);
+    if (fm === null) {
+        return false;
+    }
+    const m = /^status:[ \t]*([A-Za-z-]+)[ \t]*$/m.exec(fm);
+    return m !== null && CARRIER_VALUES.has((m[1] ?? '').toLowerCase());
+}
+
+/**
+ * Count the top-level roadmaps in `roadmapRoot` that declare themselves carriers.
+ *
+ * Lives here rather than in the estate gate because it is the same fact as the
+ * predicate above, read over a directory instead of a string, and the gate that
+ * needs it is already at its source-size ceiling.
+ *
+ * @param isCandidate the caller's own roadmap-filename test, so this module does
+ *        not acquire a second opinion about what counts as a roadmap.
+ */
+export function countDeclaredCarriers(
+    roadmapRoot: string,
+    isCandidate: (name: string) => boolean,
+    fsLike: {
+        readdirSync: (p: string) => string[];
+        statSync: (p: string) => { isFile: () => boolean };
+        readFileSync: (p: string, enc: 'utf-8') => string;
+    },
+    join: (...parts: string[]) => string,
+): number {
+    let names: string[];
+    try {
+        names = fsLike.readdirSync(roadmapRoot);
+    } catch {
+        return 0;
+    }
+    let n = 0;
+    for (const name of names) {
+        if (!name.endsWith('.md') || !isCandidate(name)) {
+            continue;
+        }
+        const abs = join(roadmapRoot, name);
+        try {
+            if (!fsLike.statSync(abs).isFile()) {
+                continue;
+            }
+            if (declaresCarrier(fsLike.readFileSync(abs, 'utf-8'))) {
+                n += 1;
+            }
+        } catch {
+            continue;
+        }
+    }
+    return n;
+}
+
+/**
+ * Fixture design — why two of the estate self-test cases are shaped as they are.
+ *
+ * The reasoning behind two of `check_estate_count`'s self-test cases, kept here
+ * because the gate that holds them is at its source-size ceiling and because
+ * both facts are about the carrier status rather than about that gate.
+ *
+ * **The deletion case's addition is a DRAFT, and that is the whole design.**
+ * A carrier holds obligations lifted out of an already-archived parent, so
+ * paying an offset for removing one rewards the loss: the deletion buys nothing
+ * and the addition stays unpaid. With an *ordinary* addition the growth half and
+ * the unpaid half coincide — growth iff `n > a`, unpaid iff `n > a` — so the
+ * case rejected on two independent grounds and stayed red with the carrier
+ * branch reverted, asserting nothing about the feature it named. A draft is
+ * invisible to `collect()`, so the count half cannot move and only the offset
+ * scoring decides.
+ *
+ * **The count case asserts the flip BACK, not the flip TO.** A reclassification
+ * is not a disposal in either direction, but the flip *to* carrier cannot be
+ * asserted by exit code: it lowers the count, a count below the floor is a
+ * drawdown, and a drawdown is free whichever way carriers are counted. Its
+ * consequence is assertable — with carriers uncounted the flip lowers the floor,
+ * so flipping the same file back reads as growth and must be paid for. That is
+ * the fixture's state, with the carrier already in the base tree, and it rejects
+ * with the carrier term removed from the count. The neutrality of the forward
+ * flip is asserted directly in `check_estate_count.test.ts`, where a count is
+ * readable.
+ */

package/src/scripts/_lib/cascade_stage_enumeration.ts

@@ -0,0 +1,92 @@
+/**
+ * The twelve-stage evaluation cascade, DERIVED rather than enumerated by hand.
+ *
+ * `road-to-governed-evidence-production` step 1.2. E9 (2026-08-30) decided the
+ * ARITY — twelve — and enumerated the stages nowhere. The 2026-08-31 council
+ * round that was asked for the enumeration returned `REVISE`, and the reason it
+ * gave is the reason this module exists rather than a constant list: running the
+ * same seat twice produced two materially different twelves — different names,
+ * different order, a different placement of the statistical stage.
+ *
+ * **So the enumeration is not proposed. It is computed.** Two committed arrays
+ * and one stated ordering rule determine it, and re-running the computation over
+ * the same tree cannot yield a different answer. Nobody's judgement is in the
+ * output, which is what "settled" has to mean after two judgements disagreed.
+ *
+ * ## The ordering rule
+ *
+ * Stages are ordered by the EVIDENCE each one needs — the `CascadeInput` field
+ * it reads — and within a class by source order. The classes, cheapest evidence
+ * first:
+ *
+ * | Rank | Class | Evidence it needs | `CascadeInput` field |
+ * |---|---|---|---|
+ * | 0 | `record`      | the candidate record alone           | `raw` |
+ * | 1 | `plan`        | the run plan and the budget ceiling  | `plan`, `budget` |
+ * | 2 | `peers`       | the sibling candidates of this run   | `peers` |
+ * | 3 | `receipt`     | an activation receipt                | `receipt` |
+ * | 4 | `measurement` | measured trials                      | `rows`, `vector` |
+ *
+ * The rule is not a preference. It is the cascade's own cheapest-first,
+ * abort-on-first-failure discipline restated over evidence rather than over
+ * cost: a stage may not run before the evidence it depends on could exist, and a
+ * candidate that fails a cheap-evidence stage must never consume the expensive
+ * evidence. `docs/contracts/activation-receipt-trust-boundary.md` EC-2 is the
+ * receipt row of exactly this table.
+ *
+ * ## What is NOT decided here
+ *
+ * The rung SEMANTICS — what `delivered` means, what observes it — belong to
+ * `_lib/activation_ladder.ts`, and the `REVISE` verdict's condition on them was
+ * discharged by the trust-boundary and evidence-cost contract, not by this file.
+ * This module settles the enumeration and its order, and nothing else.
+ */
+
+import { CASCADE_STAGES, type StageId } from './evaluation_cascade.js';
+import { RECEIPT_STAGES } from './activation_ladder.js';
+
+/** What evidence a stage needs. The ordering key. */
+export const EVIDENCE_CLASSES = ['record', 'plan', 'peers', 'receipt', 'measurement'] as const;
+export type EvidenceClass = (typeof EVIDENCE_CLASSES)[number];
+
+/**
+ * The evidence class of each DETERMINISTIC prefix stage.
+ *
+ * Written out because it is a fact about `runCascade`'s body — which
+ * `CascadeInput` field each stage reads — and a fact about code cannot be
+ * derived from a list of names. It is not unchecked: the companion test asserts
+ * this order against the order in which `runCascade` first touches each input
+ * field, so a stage that starts reading a different field reds here rather than
+ * quietly reordering the enumeration.
+ */
+export const PREFIX_EVIDENCE_CLASS: Readonly<Record<string, EvidenceClass>> = {
+    'schema-validity': 'record',
+    'path-ownership': 'record',
+    'holdout-disclosure': 'record',
+    budget: 'plan',
+    'near-duplicate': 'peers',
+    'metric-verdict': 'measurement',
+};
+
+/** The evidence class of any stage. Receipt stages are uniformly `receipt`. */
+export function evidenceClass(stage: StageId): EvidenceClass {
+    if ((RECEIPT_STAGES as readonly string[]).includes(stage)) return 'receipt';
+    const c = PREFIX_EVIDENCE_CLASS[stage];
+    if (c === undefined) throw new Error(`no evidence class declared for stage '${stage}'`);
+    return c;
+}
+
+/**
+ * The committed twelve, in order.
+ *
+ * Route A of step 1.2's reproduction: the two committed arrays, sorted by
+ * evidence class, stable within a class. `Array.prototype.sort` is specified as
+ * stable since ES2019, which is what makes "within a class, source order" a
+ * property of the language rather than of an implementation.
+ */
+export const TWELVE_STAGES: readonly StageId[] = [...CASCADE_STAGES, ...RECEIPT_STAGES].sort(
+    (a, b) => EVIDENCE_CLASSES.indexOf(evidenceClass(a)) - EVIDENCE_CLASSES.indexOf(evidenceClass(b)),
+);
+
+/** The arity E9 decided. Stated so a drift from twelve is a named failure. */
+export const DECIDED_ARITY = 12;