@warmdrift/kgauto-compiler 2.0.0-alpha.82 → 2.0.0-alpha.85

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, B as BestPracticeAdvisory, F as FallbackReason, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-D4S9R816.mjs';
-export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, r as GoldenCaptureOptions, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, s as MutationApplied, t as NormalizedTokens, u as OutcomeKind, v as PerAxisMetricsByModel, w as PromptSection, x as SectionKind, y as ShadowProbeConfig, T as ToolCall, z as ToolDefinition, D as captureGoldenIr, J as hasMutation, K as mutationId, L as parseGoldenCaptureRate, Q as resolveGoldenCaptureRate, U as shouldCaptureGolden } from './ir-D4S9R816.mjs';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, B as BestPracticeAdvisory, F as FallbackReason, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-JUoybVM-.mjs';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, r as GoldenCaptureOptions, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, s as MutationApplied, t as NormalizedTokens, u as OutcomeKind, v as PerAxisMetricsByModel, w as PromptSection, x as SectionKind, y as ShadowProbeConfig, T as ToolCall, z as ToolDefinition, D as captureGoldenIr, J as hasMutation, K as mutationId, L as parseGoldenCaptureRate, Q as resolveGoldenCaptureRate, U as shouldCaptureGolden } from './ir-JUoybVM-.mjs';
 import { ModelProfile, ArchetypeConvention } from './profiles.mjs';
-export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.mjs';
+export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, resolveModelAlias, tryGetProfile } from './profiles.mjs';
 export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.mjs';
 export { KEY_FINGERPRINT_DOMAIN, KEY_FINGERPRINT_LENGTH, KeyHealthConfig, KeyHealthProvider, KeyHealthResponseBody, KeyHealthResult, KeyHealthRoute, createKeyHealthRoute, keyFingerprint } from './key-health.mjs';
 import { IntentArchetypeName, OutputMode } from './dialect.mjs';
@@ -965,7 +965,11 @@ type GoldenEvalAxis = 'model' | 'strategy';
  * measurable against its exact frozen bytes. The `-alt` wording is
  * EVAL-ONLY: it exists to attribute a v1 loss to wording vs mechanism
  * (§6) and never ships in a production compile. */
-type GoldenEvalStrategyId = 'discipline-gates-v1' | 'discipline-gates-v1-alt';
+type GoldenEvalStrategyId = 'discipline-gates-v1' | 'discipline-gates-v1-alt' | 'discipline-gates-v1-alt-blind';
+/** Both re-wordings of v1. Dispatch keys on this, never on a string prefix,
+ * so adding a fourth arm is one edit rather than a grep. */
+declare const ALT_STRATEGY_IDS: readonly GoldenEvalStrategyId[];
+declare function isAltStrategy(id: GoldenEvalStrategyId | undefined): boolean;
 interface GoldenEvalOptions {
     appId: string;
     archetype: string;
@@ -1085,6 +1089,45 @@ declare function altGatesBlockFor(args: {
     outputMode: 'text' | 'json' | 'tool_call';
     hasTools: boolean;
 }): string;
+declare const ALT_BLIND_TOKEN_BUDGET_BREACH: {
+    readonly ceilingTokens: 264;
+    readonly measuredTokensTextWithTools: 285;
+    readonly note: string;
+};
+declare const DISCIPLINE_GATES_V1_ALT_BLIND_HEADER = "Before stating any conclusion, run this check:";
+/**
+ * The variant matrix — and this is the ONE place this seat's judgment enters
+ * the blind arm, so it is stated rather than buried.
+ *
+ * cc's instruction: adapt MECHANICALLY where the injection format demands it,
+ * note the diff, never edit semantics. Choosing which gates to drop per
+ * surface is a selection, not an edit — the bytes of every retained gate are
+ * untouched — but the selection is still mine, so:
+ *
+ *   NO TOOLS   drops `toolPredict`. Forced, not chosen: the string opens
+ *              "When using tools" and is literally inapplicable without them.
+ *              Mirrors v1 dropping its compressed-item bullet.
+ *   STRUCTURED drops `markAssumed` ONLY. It is the sole gate whose entire
+ *              function is text in the final answer ('mark anything unchecked
+ *              as "assumed"'), which a JSON/tool_call schema has no field for
+ *              and which would corrupt the parse.
+ *
+ * The judgment call worth flagging: v1 drops TWO bullets on structured
+ * surfaces, and a stricter reading would also drop `falsify` ("state in one
+ * line") and `deviation` ("say so explicitly"), since both demand output
+ * text. I kept them. Their output demand is incidental (and conditional, for
+ * `deviation`) while their primary effect is on reasoning before the answer
+ * exists — whereas v1's dropped pair (`label`, `gap`) are purely
+ * output-shaping. Dropping three of five would leave a two-gate arm that no
+ * longer tests the same mechanism, and an arm crippled by my formatting
+ * choice would read as a wording loss that was actually a scoping loss.
+ * If the structured surface shows anomalous results, this is the first
+ * thing to re-examine.
+ */
+declare function altBlindGatesBlockFor(args: {
+    outputMode: 'text' | 'json' | 'tool_call';
+    hasTools: boolean;
+}): string;
 /**
  * The alt arm injects its block DIRECTLY as an untagged section — it must
  * not carry `kind: 'discipline_contract'`, or the translator would prepend
@@ -1094,6 +1137,14 @@ declare function altGatesBlockFor(args: {
  * no-ops — the attribution is about WORDING, and everything else is held.
  */
 declare function withAltDisciplineContract(ir: PromptIR): PromptIR;
+/**
+ * Same injection contract as `withAltDisciplineContract` — untagged section,
+ * so the translator never prepends the v1 bytes on top and the arm measures
+ * exactly one wording. Same variant inputs, so the blind arm no-ops nowhere
+ * v1 fires and fires nowhere v1 no-ops; the comparison is about WORDING and
+ * everything else is held.
+ */
+declare function withAltBlindDisciplineContract(ir: PromptIR): PromptIR;
 declare function runGoldenEval(opts: GoldenEvalOptions): Promise<GoldenEvalRunResult>;
 /**
  * Aggregate outcome of one strategy run, in gates-on terms. 'loses' is the
@@ -1107,25 +1158,54 @@ declare function classifyStrategyOutcome(r: GoldenEvalRunResult): StrategyOutcom
  * recorded as a mechanism failure would let Factor B permanently disable a
  * real capability on evidence about one author's prose.
  *
- *   v1 vs off | alt vs off | attribution
- *   ----------+------------+----------------------------------------------
- *   wins      | (not run)  | mechanism-works — ship
- *   ties      | (not run)  | no-lift — inconclusive at this n, re-eval later
- *   loses     | wins       | wording-failure — do NOT disable the mechanism
- *   loses     | loses      | mechanism-failure — well-evidenced; Factor B may disable
- *   loses     | ties/inc.  | wording-inconclusive — no disable on ambiguity
+ * THREE arms since 2026-07-29. Both re-wordings run on a v1 loss, and a win
+ * by EITHER is enough to acquit the mechanism — the question "does some
+ * wording of this work?" is answered by one existence proof, so there is no
+ * reason to require agreement between the alts.
+ *
+ *   v1 vs off | alt / alt-blind vs off | attribution
+ *   ----------+------------------------+------------------------------------
+ *   wins      | (not run)              | mechanism-works — ship
+ *   ties      | (not run)              | no-lift — inconclusive at n, re-eval
+ *   loses     | either wins            | wording-failure — do NOT disable
+ *   loses     | BOTH lose              | mechanism-failure — Factor B may disable
+ *   loses     | neither wins, not both lose | wording-inconclusive — no disable
+ *
+ * The `mechanism-failure` cell is the one that changed character. It used to
+ * rest on two wordings by one author, so a shared blind spot (the principles
+ * being the wrong principles) was invisible and the verdict was hedged. The
+ * blind arm was authored by a context-free subagent with no knowledge of this
+ * repo, the experiment, or who was asking — so a both-lose verdict now spans
+ * independent authorship and is strong on its own terms. That is exactly the
+ * gap `STRATEGY_AUTHORSHIP_LIMITATION` was written to confess, which is why
+ * the limitation text is now conditional on whether the blind arm ran.
  */
 type StrategyAttribution = 'mechanism-works' | 'no-lift' | 'wording-failure' | 'mechanism-failure' | 'wording-inconclusive' | 'inconclusive';
 interface StrategyAttributionResult {
     attribution: StrategyAttribution;
     primary: GoldenEvalRunResult;
-    /** Present ONLY when the primary lost (the loss-triggered third arm). */
+    /** Present ONLY when the primary lost (the loss-triggered arms). */
     alt?: GoldenEvalRunResult;
+    /** The independently-authored arm. Present ONLY when the primary lost. */
+    altBlind?: GoldenEvalRunResult;
     /** The authorship limitation, restated on every result so no downstream
-     * reader can cite an attribution without it. */
+     * reader can cite an attribution without it. Which string this carries
+     * depends on whether the blind arm actually ran — see below. */
     limitation: string;
 }
+/**
+ * Carried when the blind arm did NOT run — i.e. v1 won or tied, so no
+ * re-wording was measured at all and any claim about wording is unevidenced.
+ */
 declare const STRATEGY_AUTHORSHIP_LIMITATION: string;
+/**
+ * Carried when both re-wording arms ran. The shared-author caveat is GONE by
+ * construction, and saying so is the point: the previous version of this
+ * string confessed a gap that has since been closed, and a stale confession
+ * is its own kind of false statement — a reader would discount a verdict
+ * that no longer deserves discounting.
+ */
+declare const STRATEGY_AUTHORSHIP_INDEPENDENT: string;
 /**
  * Run the strategy eval with loss-triggered wording attribution: v1 first;
  * the alt arm replays ONLY on a v1 loss (mirrors the engine's retry
@@ -1146,7 +1226,7 @@ declare function runStrategyEvalWithAttribution(opts: Omit<GoldenEvalOptions, 'a
  * guard in `tests/version.test.ts` fails the suite (and therefore
  * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
  */
-declare const LIBRARY_VERSION = "2.0.0-alpha.82";
+declare const LIBRARY_VERSION = "2.0.0-alpha.85";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -1565,6 +1645,218 @@ declare function deriveOwnership(code: string, selfDeclared?: 'consumer-actionab
  */
 declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
 
+/**
+ * promote-ready-brain — alpha.41 substrate.
+ *
+ * Per-tenant SWR cache for the `promote_ready_findings` table populated by
+ * the autonomous `promotion-probe-watcher` (Mode 2). Mirrors
+ * `exclusion-findings-brain.ts` shape byte-for-byte where applicable; this
+ * is the read-side substrate for the compile-time `promote-ready` advisor
+ * rule.
+ *
+ * Architecture (mirror of exclusion-findings-brain):
+ *
+ * - **Sync API surface.** `getPromoteReadyFindings({ appId, archetype,
+ *   family })` returns `PromoteReadyFindingRow[]` immediately. First call
+ *   returns the bundled fallback (empty array); async refresh fires in
+ *   background; subsequent calls within TTL return brain data.
+ *
+ * - **Per-appId snapshot.** Each appId gets its own cache entry. One fetch
+ *   per appId per TTL window. Tests reset between cases via
+ *   `_testResetPromoteReadyFindings()`.
+ *
+ * - **Tolerant.** Brain down / endpoint misconfigured / unexpected shape →
+ *   silent bundled fallback (empty array). Never throws. Warns once per
+ *   process per error to avoid log spam.
+ *
+ * - **Opt-in.** Activation gated on `configurePromoteReadyBrain()` having
+ *   been called with a runtime. The public `configureBrain()` in brain.ts
+ *   wires this up automatically when
+ *   `BrainConfig.brainQuery.findingsPromoteReady !== false`.
+ *
+ * Plus: `markPromoteReadyHandled` — direct PostgREST PATCH against the
+ * brain (no kgauto proxy). Mirrors `markExclusionFindingHandled` shape
+ * byte-for-byte. Idempotent on `resolved_at=is.null` filter.
+ *
+ * Default endpoint:
+ *   `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/promote-ready`
+ *   The route accepts `?app_id=X` and returns a JSON array of findings
+ *   for that app filtered to `resolved_at IS NULL`.
+ */
+
+/**
+ * Shape of one row from the `promote_ready_findings` cache table. Mirrors
+ * the snake_case JSONB returned by the brain endpoint, mapped to camelCase
+ * at the boundary (rowToFinding) so the in-memory shape stays consistent
+ * with the rest of the library.
+ */
+interface PromoteReadyFindingRow {
+    /** Intent archetype the finding applies to. */
+    archetype: string;
+    /** Model family (e.g. 'claude-opus', 'gemini-flash'). */
+    family: string;
+    /** The candidate model that the probe validated. */
+    candidateModel: string;
+    /** The current production model the candidate was compared against. */
+    currentModel: string;
+    /** Sample size of the probe run (typically 10). */
+    sampleN: number;
+    /** Fraction of probes where the judge verdict was 'candidate-better' or
+     *  'tied'. 0.000 to 1.000. */
+    judgePassRate: number;
+    /** Mean judge score across the probe sample. 1.00 to 5.00. */
+    judgeAvgScore: number;
+    /** Signed cost delta as a fraction (negative = candidate is cheaper).
+     *  Null when pricing data was incomplete at probe time. */
+    costDeltaPct: number | null;
+    /** ISO timestamp of detection (when the probe wrote the row). */
+    detectedAt: string;
+}
+/**
+ * Resolution sources supported by alpha.41 `markPromoteReadyHandled`. The
+ * three values map to the three CHECK-constrained resolution values on
+ * `promote_ready_findings.resolution`:
+ *
+ * - `'promoted'`         — consumer migrated to the candidate model. Strong
+ *                          positive signal; the probe was right.
+ * - `'declined'`         — consumer evaluated and chose not to promote.
+ *                          Strong negative signal; revisit only on new
+ *                          family entries or material score swings.
+ * - `'still-evaluating'` — consumer acknowledges the finding but defers
+ *                          the decision. Acknowledges-without-deciding;
+ *                          finding silences this cycle but next probe may
+ *                          re-surface.
+ */
+type PromoteReadyResolution = 'promoted' | 'declined' | 'still-evaluating';
+interface MarkPromoteReadyHandledOptions {
+    /** App id the finding belongs to. Required (RLS scopes writes by this). */
+    appId: string;
+    /** Archetype the finding applies to (e.g. 'hunt', 'classify'). */
+    archetype: IntentArchetypeName | string;
+    /** Model family the finding applies to (e.g. 'claude-opus'). */
+    family: string;
+    /** Resolution semantics — see `PromoteReadyResolution`. */
+    resolution: PromoteReadyResolution;
+    /** Optional free-form note explaining the decision. */
+    resolutionNote?: string;
+    /** Brain Supabase URL base (e.g. `https://<project>.supabase.co`). */
+    brainEndpoint: string;
+    /** Consumer-scoped JWT carrying the `app_id` claim. */
+    brainJwt: string;
+    /** Supabase anon key for the `apikey` header. */
+    brainAnonKey: string;
+    /** Injected fetch for tests. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Mark a probe-validated promote-ready finding as handled. Returns an
+ * `ok/reason` envelope matching `markExclusionFindingHandled`.
+ *
+ * Idempotent: if no row matches the (app_id, archetype, family) tuple
+ * (already resolved, never existed, watcher not yet UPSERTed), PostgREST
+ * returns 200/204 with zero affected rows and we return `{ ok: true }`.
+ *
+ * Reasons surfaced on failure:
+ *   - `app_id_required` / `archetype_required` / `family_required`
+ *   - `resolution_invalid` — not one of the three documented values
+ *   - `brain_auth_misconfig` — 401/403
+ *   - `brain_unavailable` — 5xx
+ *   - `network_error:<message>` — fetch threw
+ *   - `patch_failed:<status>` — anything else non-2xx
+ */
+declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+
+/**
+ * blocked-model-drift — advisor rule for the two ways a consumer's
+ * `CompilePolicy.blockedModels` can stop meaning what the consumer meant,
+ * without anything anywhere reporting a problem.
+ *
+ * ── The incidents this is grounded in (tt-intel s113 + s119) ─────────────
+ *
+ * (Correction, s83: an earlier draft cited "claude-sonnet-5 served 30% of
+ * tt-intel's ask traffic" as the motivating incident. That number was a
+ * FOSSIL — tt-intel's own L-188 traced all 11 calls to a 29-second burst
+ * from their own prior spend-gate experiment, fixed minutes later, and
+ * their block was in fact working. Do not resurrect it.)
+ *
+ * The real, verified incidents:
+ *
+ * 1. alpha.72 retargeted the curated `claude-sonnet` family primary from
+ *    `claude-sonnet-4-6` (now `legacy`) to `claude-sonnet-5` (now
+ *    `current`), and tt-intel's literal-id gate STOPPED MATCHING the
+ *    family's routed traffic — their s113 response was to build
+ *    consumer-side family→concrete-id resolution (`parseBlockedModels`)
+ *    before ids reach kgauto. Every consumer without that local machinery
+ *    is exposed to the same silent retarget: `blockedModels` is matched by
+ *    exact id, so a block written against yesterday's primary says nothing
+ *    about today's.
+ *
+ * 2. tt-intel s119 (2026-07-29 filing): a blocked model SERVED when an
+ *    unblocked ALIAS of it sat in the candidate set (`deepseek-chat` ≡
+ *    `deepseek-v4-flash`). That one was a kgauto correctness bug, fixed in
+ *    alpha.85 by canonical matching (`policy-match.ts`) — but it proved
+ *    the class: a block-list meaning drifts whenever the roster's id
+ *    surface moves under it, and no layer errors.
+ *
+ * ── What this rule is NOT ────────────────────────────────────────────────
+ *
+ * It does not change matching semantics. Exact-ID matching is arguably the
+ * correct contract: family-glob matching would silently widen every
+ * existing consumer's block-list, which is a breaking semantic change and
+ * not kgauto's to make unilaterally. The gap here is silence, not
+ * semantics — so the fix is a signal, not a behavior change. Selection is
+ * untouched; a consumer who blocked one exact id still gets exactly that
+ * id blocked and nothing else.
+ *
+ * ── The two branches ─────────────────────────────────────────────────────
+ *
+ * (a) `blocked-model-not-in-roster` — a `blockedModels` entry resolves to
+ *     no model in the current roster (after alias resolution). The block is
+ *     inert: it can never match anything. Causes are a typo, a model
+ *     retired out of the roster, or a stale env var carried forward. There
+ *     is no reading under which an entry matching nothing is what the
+ *     consumer wanted, so this is unambiguous.
+ *
+ * (b) `blocked-model-family-sibling-served` — the model selected for THIS
+ *     call is in the same family as a blocked entry but is a different
+ *     exact id. This is the tt-intel shape. Unlike (a) it IS ambiguous:
+ *     "block `claude-sonnet-4-6` specifically, `claude-sonnet-5` is fine"
+ *     is a legitimate and common intent. So the message states both
+ *     readings and says how to act on either. It escalates its wording —
+ *     not its level — when the blocked sibling is `legacy`/`deprecated` and
+ *     the served sibling is `current`, because that combination is the
+ *     signature of a roster lifecycle move rather than a deliberate
+ *     per-generation block.
+ *
+ * Both fire at `warn`, and both fire regardless of `policy.posture`.
+ * `posture: 'locked'` means "do not recommend models to me" — these are not
+ * recommendations, they are reports that the consumer's own declared
+ * constraint is not doing what its author expects. Same reasoning as the
+ * alpha.28 `archetype-perf-floor-breach` cliff advisor, which is also
+ * posture-independent because it reports a structural fact rather than a
+ * preference.
+ *
+ * Companion watcher: `v2/scripts/blocked-model-drift-watch.mjs` rolls the
+ * same two branches up across a consumer's recent traffic from the brain,
+ * so the signal survives a consumer who never reads `result.advisories[]`.
+ *
+ * L-073 family ("no errors = healthy"): as with DeepSeek's `deepseek-chat`
+ * compat alias and the alpha.47/.43 field-drop chain, nothing errored,
+ * nothing 404'd, latency did not move — and the cached intent was wrong for
+ * an unknown duration. The detection loop has to be built deliberately
+ * because the failure emits no natural signal.
+ */
+
+/** Stable rule code — branch (a). Written to `compile_outcome_advisories.code`. */
+declare const BLOCKED_MODEL_NOT_IN_ROSTER_CODE = "blocked-model-not-in-roster";
+/** Stable rule code — branch (b). Written to `compile_outcome_advisories.code`. */
+declare const BLOCKED_MODEL_FAMILY_SIBLING_SERVED_CODE = "blocked-model-family-sibling-served";
+
 /**
  * Translator primitive — alpha.31.
  *
@@ -1795,6 +2087,77 @@ interface AdvisorySuggestedFix {
  * view's snake_case columns to camelCase. See `feedback_typed_boundary_transformers.md`
  * (L-118) for the rationale.
  */
+/**
+ * The window of evidence a finding was computed from — migration 054.
+ *
+ * READ THE DISTINCTION BEFORE USING THIS. It is NOT `openedAt` /
+ * `lastObservedAt` / `observationCount`, which describe the ADVISORY (how
+ * long it has been firing, how many times the watcher ran and still saw the
+ * condition). This describes what the generator LOOKED AT.
+ *
+ * A daily cron that keeps firing on a single 29-second burst reports
+ * `observationCount: 11` spanning 11 days — the most standing-looking of
+ * standing conditions — while its evidence is one event from 11 days ago.
+ * Separating the two is the entire point.
+ *
+ * `null` when the generator did not state its window. Honest unknown; it
+ * must never be read as "not a burst". Compile-time library rules carry
+ * null legitimately — they fire on ONE call, so their evidence is the call
+ * in hand and there is no window to state.
+ */
+interface AdvisoryEvidenceWindow {
+    firstAt: string;
+    lastAt: string;
+    n: number;
+    /** `lastAt - firstAt`, precomputed so no caller re-derives it wrong. */
+    spanMs: number;
+    /**
+     * `true` when the evidence is clustered tightly enough to be ONE EVENT
+     * rather than a standing rate. See `classifyEvidenceWindow`.
+     */
+    isBurst: boolean;
+}
+/**
+ * Burst-vs-rate, computed rather than judged.
+ *
+ * Origin: tt-intel s118. A cost query showed `claude-sonnet-5` at 30% of
+ * their `ask` traffic and 80% of ask spend. Every number true, every
+ * mechanism check correct, and every correct check made them more certain
+ * the spend gate had regressed. All eleven calls sat in a 29-second window —
+ * their own prior experiment, fixed six minutes after the last one. Their
+ * formulation: **a cluster is an event, not a rate.**
+ *
+ * The rule, deliberately crude because a subtle one would need tuning per
+ * rule and would then be wrong per rule: evidence is a burst when it spans
+ * less than `BURST_SPAN_MS` (5 minutes). Multiple observations inside five
+ * minutes are one incident — a deploy, a retry storm, a test run, a
+ * benchmark — not a pattern of behavior over time.
+ *
+ * Two deliberate non-features:
+ *
+ * - **n is not in the test.** Two rows 4 minutes apart are as much a single
+ *   event as eleven are. Requiring a minimum n would let the smallest, least
+ *   evidenced findings skip the check.
+ * - **It does not try to detect fossils.** A burst is not necessarily stale;
+ *   it is merely not a rate. Only the consumer's own deploy log can turn
+ *   "one event" into "an event we already fixed", and this library cannot
+ *   see that. Claiming otherwise would be the same over-reach the rule
+ *   exists to correct.
+ */
+declare const BURST_SPAN_MS: number;
+declare function classifyEvidenceWindow(row: {
+    evidence_first_at?: string | null;
+    evidence_last_at?: string | null;
+    evidence_n?: number | null;
+}): AdvisoryEvidenceWindow | null;
+/** Human-readable span for advisory text. Terse by design — it sits inline. */
+declare function formatEvidenceSpan(spanMs: number): string;
+/**
+ * The sentence that travels with a burst-shaped finding. Written to be
+ * usable verbatim in advisory text, and to say what the library CAN claim
+ * (one event) rather than what it cannot (that the event is stale).
+ */
+declare function burstCaveat(w: AdvisoryEvidenceWindow): string;
 interface ActionableAdvisory {
     id: string;
     rule: string;
@@ -1802,6 +2165,18 @@ interface ActionableAdvisory {
     openedAt: string;
     lastObservedAt: string;
     observationCount: number;
+    /**
+     * Migration 054. `null` when the generator did not state a window — an
+     * honest unknown, NOT an assertion that the evidence is well-spread.
+     */
+    evidenceWindow: AdvisoryEvidenceWindow | null;
+    /**
+     * The severity the rule ASKED for, present only when this advisory's
+     * effective `severity` was downgraded because its evidence is burst-shaped.
+     * Kept so a consumer can see the downgrade happened rather than silently
+     * receiving a quieter advisory than the generator wrote.
+     */
+    severityBeforeBurstDowngrade?: AdvisorySeverity;
     appliesTo: {
         archetype?: IntentArchetypeName;
         model?: string;
@@ -1853,6 +2228,12 @@ interface MarkAdvisoryResolvedOptions {
     brainAnonKey?: string;
     fetch?: typeof fetch;
 }
+/**
+ * Map a single `actionable_advisories_v` row (snake_case, Postgres
+ * native) to the public `ActionableAdvisory` shape (camelCase). Single
+ * canonical mapping site for this boundary (L-118).
+ */
+declare function rowToAdvisory(row: Record<string, unknown>): ActionableAdvisory;
 /**
  * Query the open advisory set for an app. Pulls from
  * `actionable_advisories_v` (per-(app_id, code) rollup with stable ids
@@ -3072,132 +3453,6 @@ declare function deriveFamilyFromModelId(modelId: string): string | null;
  */
 declare function getRecommendedPrimary(opts: GetRecommendedPrimaryOptions): string;
 
-/**
- * promote-ready-brain — alpha.41 substrate.
- *
- * Per-tenant SWR cache for the `promote_ready_findings` table populated by
- * the autonomous `promotion-probe-watcher` (Mode 2). Mirrors
- * `exclusion-findings-brain.ts` shape byte-for-byte where applicable; this
- * is the read-side substrate for the compile-time `promote-ready` advisor
- * rule.
- *
- * Architecture (mirror of exclusion-findings-brain):
- *
- * - **Sync API surface.** `getPromoteReadyFindings({ appId, archetype,
- *   family })` returns `PromoteReadyFindingRow[]` immediately. First call
- *   returns the bundled fallback (empty array); async refresh fires in
- *   background; subsequent calls within TTL return brain data.
- *
- * - **Per-appId snapshot.** Each appId gets its own cache entry. One fetch
- *   per appId per TTL window. Tests reset between cases via
- *   `_testResetPromoteReadyFindings()`.
- *
- * - **Tolerant.** Brain down / endpoint misconfigured / unexpected shape →
- *   silent bundled fallback (empty array). Never throws. Warns once per
- *   process per error to avoid log spam.
- *
- * - **Opt-in.** Activation gated on `configurePromoteReadyBrain()` having
- *   been called with a runtime. The public `configureBrain()` in brain.ts
- *   wires this up automatically when
- *   `BrainConfig.brainQuery.findingsPromoteReady !== false`.
- *
- * Plus: `markPromoteReadyHandled` — direct PostgREST PATCH against the
- * brain (no kgauto proxy). Mirrors `markExclusionFindingHandled` shape
- * byte-for-byte. Idempotent on `resolved_at=is.null` filter.
- *
- * Default endpoint:
- *   `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/promote-ready`
- *   The route accepts `?app_id=X` and returns a JSON array of findings
- *   for that app filtered to `resolved_at IS NULL`.
- */
-
-/**
- * Shape of one row from the `promote_ready_findings` cache table. Mirrors
- * the snake_case JSONB returned by the brain endpoint, mapped to camelCase
- * at the boundary (rowToFinding) so the in-memory shape stays consistent
- * with the rest of the library.
- */
-interface PromoteReadyFindingRow {
-    /** Intent archetype the finding applies to. */
-    archetype: string;
-    /** Model family (e.g. 'claude-opus', 'gemini-flash'). */
-    family: string;
-    /** The candidate model that the probe validated. */
-    candidateModel: string;
-    /** The current production model the candidate was compared against. */
-    currentModel: string;
-    /** Sample size of the probe run (typically 10). */
-    sampleN: number;
-    /** Fraction of probes where the judge verdict was 'candidate-better' or
-     *  'tied'. 0.000 to 1.000. */
-    judgePassRate: number;
-    /** Mean judge score across the probe sample. 1.00 to 5.00. */
-    judgeAvgScore: number;
-    /** Signed cost delta as a fraction (negative = candidate is cheaper).
-     *  Null when pricing data was incomplete at probe time. */
-    costDeltaPct: number | null;
-    /** ISO timestamp of detection (when the probe wrote the row). */
-    detectedAt: string;
-}
-/**
- * Resolution sources supported by alpha.41 `markPromoteReadyHandled`. The
- * three values map to the three CHECK-constrained resolution values on
- * `promote_ready_findings.resolution`:
- *
- * - `'promoted'`         — consumer migrated to the candidate model. Strong
- *                          positive signal; the probe was right.
- * - `'declined'`         — consumer evaluated and chose not to promote.
- *                          Strong negative signal; revisit only on new
- *                          family entries or material score swings.
- * - `'still-evaluating'` — consumer acknowledges the finding but defers
- *                          the decision. Acknowledges-without-deciding;
- *                          finding silences this cycle but next probe may
- *                          re-surface.
- */
-type PromoteReadyResolution = 'promoted' | 'declined' | 'still-evaluating';
-interface MarkPromoteReadyHandledOptions {
-    /** App id the finding belongs to. Required (RLS scopes writes by this). */
-    appId: string;
-    /** Archetype the finding applies to (e.g. 'hunt', 'classify'). */
-    archetype: IntentArchetypeName | string;
-    /** Model family the finding applies to (e.g. 'claude-opus'). */
-    family: string;
-    /** Resolution semantics — see `PromoteReadyResolution`. */
-    resolution: PromoteReadyResolution;
-    /** Optional free-form note explaining the decision. */
-    resolutionNote?: string;
-    /** Brain Supabase URL base (e.g. `https://<project>.supabase.co`). */
-    brainEndpoint: string;
-    /** Consumer-scoped JWT carrying the `app_id` claim. */
-    brainJwt: string;
-    /** Supabase anon key for the `apikey` header. */
-    brainAnonKey: string;
-    /** Injected fetch for tests. Defaults to global fetch. */
-    fetch?: typeof fetch;
-}
-/**
- * Mark a probe-validated promote-ready finding as handled. Returns an
- * `ok/reason` envelope matching `markExclusionFindingHandled`.
- *
- * Idempotent: if no row matches the (app_id, archetype, family) tuple
- * (already resolved, never existed, watcher not yet UPSERTed), PostgREST
- * returns 200/204 with zero affected rows and we return `{ ok: true }`.
- *
- * Reasons surfaced on failure:
- *   - `app_id_required` / `archetype_required` / `family_required`
- *   - `resolution_invalid` — not one of the three documented values
- *   - `brain_auth_misconfig` — 401/403
- *   - `brain_unavailable` — 5xx
- *   - `network_error:<message>` — fetch threw
- *   - `patch_failed:<status>` — anything else non-2xx
- */
-declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions): Promise<{
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-}>;
-
 /**
  * promotions-brain — alpha.64 Stage-2 substrate.
  *
@@ -3760,4 +4015,4 @@ declare function planDecomposition(args: PlanDecompositionArgs): DecompositionPl
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BRAIN_READ_ENV_NAMES, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, COST_RANKING_REFERENCE_SHAPE, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type CreateDelegateOpts, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DELEGATE_TOOL_DEFINITION, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type DelegateHandle, type DelegateRefusalReason, type DelegateResult, type DelegateToolArgs, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FallbackReason, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, ROLLBACK_SUPPRESSION_WINDOW_DAYS, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, chainProviderSpread, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, createDelegate, deriveFamilyFromModelId, deriveOwnership, estimateChainCostUsd, estimateModelCostUsd, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecentRollback, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isDelegateEnabledFromEnv, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, mapMeasuredFailureRows, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ALT_BLIND_TOKEN_BUDGET_BREACH, ALT_STRATEGY_IDS, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryEvidenceWindow, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BLOCKED_MODEL_FAMILY_SIBLING_SERVED_CODE, BLOCKED_MODEL_NOT_IN_ROSTER_CODE, BRAIN_READ_ENV_NAMES, BURST_SPAN_MS, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, COST_RANKING_REFERENCE_SHAPE, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type CreateDelegateOpts, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DELEGATE_TOOL_DEFINITION, DISCIPLINE_GATES_V1_ALT_BLIND_HEADER, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type DelegateHandle, type DelegateRefusalReason, type DelegateResult, type DelegateToolArgs, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FallbackReason, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, ROLLBACK_SUPPRESSION_WINDOW_DAYS, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_INDEPENDENT, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altBlindGatesBlockFor, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, burstCaveat, call, chainProviderSpread, classifyEvidenceWindow, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, createDelegate, deriveFamilyFromModelId, deriveOwnership, estimateChainCostUsd, estimateModelCostUsd, execute, findBetterFit, flushBrainDeadLetter, formatEvidenceSpan, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecentRollback, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAltStrategy, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isDelegateEnabledFromEnv, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, mapMeasuredFailureRows, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rowToAdvisory, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltBlindDisciplineContract, withAltDisciplineContract, withDisciplineContract };