@warmdrift/kgauto-compiler 2.0.0-alpha.60 → 2.0.0-alpha.62

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-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 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-BC4uDL98.mjs';
-export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, r as MutationApplied, s as NormalizedTokens, t as OutcomeKind, u as PerAxisMetricsByModel, v as PromptSection, w as SectionKind, x as ShadowProbeConfig, T as ToolCall, y as ToolDefinition } from './ir-BC4uDL98.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 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-B2dRyJXO.mjs';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, F as FallbackReason, 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 parseGoldenCaptureRate, K as resolveGoldenCaptureRate, L as shouldCaptureGolden } from './ir-B2dRyJXO.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 { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.mjs';
@@ -440,6 +440,65 @@ interface BrainConfig {
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;
+interface BrainHealthSnapshot {
+    configState: 'configured' | 'not_configured';
+    /** Host of the configured endpoint (never the full URL — no secrets/paths). */
+    endpointHost?: string;
+    /** True when writes are awaited (BrainConfig.sync). */
+    sync: boolean;
+    /** Write POSTs attempted (all routes, primary + secondary). */
+    sent: number;
+    /** Write POSTs acknowledged 2xx without redirect. */
+    acked: number;
+    /** Write POSTs that failed (non-2xx, redirect, timeout, network throw). */
+    failed: number;
+    /** Subset of `failed` that failed the redirect check (middleware-drift class). */
+    redirected: number;
+    lastAckAt?: string;
+    lastFailureAt?: string;
+    /** Most recent failure message, truncated. */
+    lastFailure?: string;
+    deadLetterCount: number;
+}
+interface BrainDeadLetterEntry {
+    /** Brain route segment the payload was bound for. */
+    route: 'outcomes' | 'compile_outcome_quality' | 'probe_outcomes' | 'compile_outcome_advisories' | 'golden_irs';
+    /**
+     * Endpoint the payload was originally bound for. Flush replays ONLY entries
+     * matching the currently-configured endpoint — a reconfigure must never
+     * replay another brain's payloads into the new target (caught live by
+     * smoke-brain-timeout: a hung-socket test payload auto-flushed into the
+     * real brain after the smoke re-pointed configureBrain).
+     */
+    endpoint: string;
+    /** The exact JSON body that failed to land. */
+    payload: unknown;
+    failedAt: string;
+    /** Delivery attempts so far (1 = the original failed POST). */
+    attempts: number;
+    lastError: string;
+}
+/**
+ * Process-local brain write delivery ledger. `acked` is the only number that
+ * means "a row landed" — fire-and-forget callers that need delivery evidence
+ * read this (or set `BrainConfig.sync`). Cheap enough to attach to any debug
+ * or health surface the consumer already exposes.
+ */
+declare function brainHealth(): BrainHealthSnapshot;
+/** Read-only view of the pending dead-letter (for consumer-side persistence). */
+declare function peekBrainDeadLetter(): readonly BrainDeadLetterEntry[];
+/**
+ * Replay pending dead-letter payloads against the configured brain. Delivered
+ * entries are removed; failures increment `attempts` and entries are dropped
+ * after 3 total attempts (bounded — never an infinite retry, per the Redis
+ * DLQ rule). Safe to call any time; no-ops when unconfigured or already
+ * flushing. Also runs opportunistically after any successful write.
+ */
+declare function flushBrainDeadLetter(): Promise<{
+    attempted: number;
+    delivered: number;
+    remaining: number;
+}>;
 declare function record(input: RecordInput): Promise<void>;
 /**
  * Wire shape POSTed by `record()` to the brain proxy's `/outcomes` endpoint.
@@ -522,8 +581,10 @@ interface OutcomePayload {
  * = true for runtime contexts that can't tolerate fire-and-forget teardown
  * (Vercel Edge, Cloudflare Workers, AWS Lambda) — see L-086.
  *
- * Returns OutcomeResult with ok: false + stable reason on persistence
- * failure. Never throws.
+ * Returns (alpha.61): `{ok: true}` only when the POST was acknowledged 2xx
+ * (sync mode); `{ok: 'queued'}` in fire-and-forget mode (handed to the
+ * runtime, NOT acked — read `brainHealth()` for delivery evidence);
+ * `{ok: false, reason}` on known failure. Never throws.
  */
 declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
 /**
@@ -625,6 +686,193 @@ declare function buildShadowProbeRow(input: ShadowProbeRecordInput): {
  * `/probe_outcomes` the same way they forward `/outcomes`.
  */
 declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>;
+/**
+ * Golden-IR capture input. UNLIKE every other brain write, this row carries the
+ * RAW full PromptIR — an explicit, documented posture change from the s51
+ * "brain holds no raw consumer prompts" rule, gated on consumer opt-in
+ * (`KGAUTO_GOLDEN_CAPTURE` env / `CallOptions.goldenCapture`). The `consent`
+ * field records the provenance of that opt-in at capture time.
+ */
+interface GoldenIrRecordInput {
+    appId: string;
+    archetype: string;
+    /** hashShape() of the call at compile time (peek before record() pops). */
+    shapeKey?: string;
+    /** The full PromptIR, verbatim. Plain JSON by construction (ir.ts). */
+    ir: unknown;
+    incumbentModel: string;
+    incumbentOutput?: string;
+    incumbentLatencyMs?: number;
+    incumbentTokensIn?: number;
+    incumbentTokensOut?: number;
+    /** 'sampled' (capture flag fired on live traffic) | 'curated' (operator). */
+    source: 'sampled' | 'curated';
+    /** Consent provenance, e.g. 'KGAUTO_GOLDEN_CAPTURE=0.1 (consumer env opt-in)'. */
+    consent: string;
+    /** Optional link back to the compile handle of the captured call. */
+    outcomeHandle?: string;
+}
+/** Pure builder for the `kgauto_golden_irs` row (snake_case wire shape). */
+declare function buildGoldenIrRow(input: GoldenIrRecordInput): {
+    app_id: string;
+    intent_archetype: string;
+    shape_key: string | null;
+    ir: unknown;
+    incumbent_model: string;
+    incumbent_output: string | null;
+    incumbent_latency_ms: number | null;
+    incumbent_tokens_in: number | null;
+    incumbent_tokens_out: number | null;
+    source: 'sampled' | 'curated';
+    consent: string;
+    outcome_handle: string | null;
+};
+/**
+ * Persist one golden IR to `kgauto_golden_irs`. Same G1 write-leg discipline as
+ * every other brain route (redirect check, ledger, dead-letter); fire-and-forget
+ * by default, honors `BrainConfig.sync`. Never throws.
+ */
+declare function recordGoldenIr(input: GoldenIrRecordInput): Promise<void>;
+
+/**
+ * Golden-set eval engine (alpha.62, eval spine — design brief 2026-07-17).
+ *
+ * Implements the quality-floor-guarded model-swap contract:
+ *
+ *   > A model replaces another on a surface only by demonstrating
+ *   > same-or-better quality on that surface's real workload — never by
+ *   > price, recency, or judgment alone.
+ *
+ * One eval run: load the active golden set for (app, archetype), replay every
+ * IR on BOTH the incumbent and the candidate (fresh outputs on both sides —
+ * fair comparison, no stale stored output), apply mechanical hard floors,
+ * then a pairwise LLM judge (order-swapped to cancel position bias), and
+ * aggregate under the non-inferiority rule:
+ *
+ *   promote-ready  ⇔  wins-or-ties ≥ threshold (default 80%)
+ *                     AND zero hard-floor violations
+ *                     AND candidate p50 latency ≤ ratio × incumbent p50
+ *
+ * Evidence lands as brain rows: one `kgauto_golden_eval_runs` aggregate + one
+ * `probe_outcomes` row per case (`replay_source='golden-replay'`, full
+ * fidelity by construction) + an evidence-attached advisory on the consumer's
+ * advisory surface (trust-ladder Stage 1: eval runs, human clicks promote).
+ *
+ * Judging is PAIRWISE, not absolute — it operationalizes the quality-floor
+ * Common Pattern directly ("same or better, never less"). Each pair is judged
+ * twice with A/B order swapped; disagreement between the two orders is scored
+ * a tie (the honest reading of positional noise).
+ *
+ * This module is operator-grade: it talks to the brain via direct PostgREST
+ * with a service key (the watchers' convention), never through consumer
+ * proxies, and it deliberately does NOT call record() — eval traffic must not
+ * pollute compile_outcomes.
+ */
+
+/**
+ * What "better" means per archetype. Fed verbatim into the pairwise judge
+ * prompt. Kept deliberately short — the judge sees the full request, so the
+ * rubric only needs to name the failure modes that matter for the archetype.
+ */
+declare const JUDGE_RUBRICS: Record<string, string>;
+declare function rubricFor(archetype: string): string;
+/** Render the golden IR's request for the judge (system sections + user turn). */
+declare function renderIrForJudge(ir: PromptIR): string;
+declare function buildPairwiseJudgePrompt(args: {
+    archetype: string;
+    renderedInput: string;
+    outputA: string;
+    outputB: string;
+}): string;
+type PairwiseWinner = 'A' | 'B' | 'tie';
+/** Parse the judge's JSON verdict. Returns undefined when unparseable. */
+declare function parseJudgeVerdict(raw: string): {
+    winner: PairwiseWinner;
+    rationale?: string;
+} | undefined;
+/**
+ * Combine the two order-swapped verdicts into a case verdict. Both verdicts
+ * are expressed in incumbent/candidate terms BEFORE this call (the caller
+ * un-swaps run 2). Agreement → that verdict; disagreement → 'tied' (positional
+ * noise reads as a tie, never as a win).
+ */
+declare function combineOrderSwappedVerdicts(run1: 'candidate-better' | 'current-better' | 'tied', run2: 'candidate-better' | 'current-better' | 'tied'): 'candidate-better' | 'current-better' | 'tied';
+interface GoldenEvalOptions {
+    appId: string;
+    archetype: string;
+    candidateModel: string;
+    /**
+     * Incumbent to compare against. Default: the most frequent incumbent_model
+     * across the loaded golden set (the surface's de-facto leader).
+     */
+    incumbentModel?: string;
+    /** Judge model id. Default 'claude-opus-4-8' (judge chain tier 0). */
+    judgeModel?: string;
+    /** Max golden cases to load (newest first). Default 50. */
+    limit?: number;
+    /** Non-inferiority threshold on wins-or-ties. Default 0.8. */
+    winOrTieThreshold?: number;
+    /** Latency hard floor: candidate p50 ≤ ratio × incumbent p50. Default 3. */
+    latencyFloorRatio?: number;
+    /** Minimum judged cases for a non-inconclusive verdict. Default 5. */
+    minJudgeableCases?: number;
+    /** What fired the eval. Default 'manual' (Stage 1). */
+    triggerSource?: 'manual' | 'supply' | 'price' | 'demand';
+    /** Brain access — direct PostgREST (operator convention). */
+    supabaseUrl: string;
+    serviceKey: string;
+    /** Provider keys for the replay + judge calls. Default: process.env. */
+    apiKeys?: ApiKeys;
+    fetchImpl?: typeof fetch;
+    /** Replay + judge but write NOTHING to the brain. */
+    dryRun?: boolean;
+    onProgress?: (message: string) => void;
+}
+interface GoldenEvalCase {
+    goldenIrId: number;
+    verdict: 'candidate-better' | 'tied' | 'current-better' | 'inconclusive';
+    judgeRationale?: string;
+    /** Hard-floor violations on the candidate side for this case. */
+    floorViolations: Array<'empty' | 'schema' | 'candidate_error'>;
+    errorClass?: string;
+    incumbent?: {
+        latencyMs: number;
+        tokensIn: number;
+        tokensOut: number;
+        text: string;
+    };
+    candidate?: {
+        latencyMs: number;
+        tokensIn: number;
+        tokensOut: number;
+        text: string;
+    };
+    /** Case excluded from the denominator (incumbent replay/judge failed). */
+    excludedReason?: string;
+}
+interface GoldenEvalRunResult {
+    verdict: 'promote-ready' | 'not-inferior' | 'inconclusive';
+    runId?: number;
+    appId: string;
+    archetype: string;
+    incumbentModel: string;
+    candidateModel: string;
+    judgeModel: string;
+    nCases: number;
+    wins: number;
+    ties: number;
+    losses: number;
+    floorViolations: number;
+    floorDetail: Record<string, number>;
+    winOrTieRatio: number | null;
+    latencyRatio: number | null;
+    costIncumbentUsd: number | null;
+    costCandidateUsd: number | null;
+    advisoryOutcomeId?: number;
+    cases: GoldenEvalCase[];
+    notes: string[];
+}
+declare function runGoldenEval(opts: GoldenEvalOptions): Promise<GoldenEvalRunResult>;
 
 /**
  * alpha.60 — the library's own version, baked as a constant so Edge/Worker
@@ -639,7 +887,7 @@ declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>
  * 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.60";
+declare const LIBRARY_VERSION = "2.0.0-alpha.62";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -1825,7 +2073,7 @@ declare function getSequentialStarterChainWithGrounding(archetype: IntentArchety
  * Sync reader for the brain-driven chains map. Returns bundled
  * STARTER_CHAINS when brain-query is disabled, cold, or unreachable.
  */
-declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform", string[]>;
+declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform" | "judge", string[]>;
 
 /**
  * archetype-perf-brain — alpha.11 KG-12 adapter.
@@ -2428,4 +2676,4 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
  */
 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, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, Grounding, IntentArchetypeName, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+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, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, setTokenizer };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 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-B2h0GAEL.js';
-export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, r as MutationApplied, s as NormalizedTokens, t as OutcomeKind, u as PerAxisMetricsByModel, v as PromptSection, w as SectionKind, x as ShadowProbeConfig, T as ToolCall, y as ToolDefinition } from './ir-B2h0GAEL.js';
+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 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-ClU56aBc.js';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, F as FallbackReason, 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 parseGoldenCaptureRate, K as resolveGoldenCaptureRate, L as shouldCaptureGolden } from './ir-ClU56aBc.js';
 import { ModelProfile, ArchetypeConvention } from './profiles.js';
 export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.js';
 export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.js';
@@ -440,6 +440,65 @@ interface BrainConfig {
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;
+interface BrainHealthSnapshot {
+    configState: 'configured' | 'not_configured';
+    /** Host of the configured endpoint (never the full URL — no secrets/paths). */
+    endpointHost?: string;
+    /** True when writes are awaited (BrainConfig.sync). */
+    sync: boolean;
+    /** Write POSTs attempted (all routes, primary + secondary). */
+    sent: number;
+    /** Write POSTs acknowledged 2xx without redirect. */
+    acked: number;
+    /** Write POSTs that failed (non-2xx, redirect, timeout, network throw). */
+    failed: number;
+    /** Subset of `failed` that failed the redirect check (middleware-drift class). */
+    redirected: number;
+    lastAckAt?: string;
+    lastFailureAt?: string;
+    /** Most recent failure message, truncated. */
+    lastFailure?: string;
+    deadLetterCount: number;
+}
+interface BrainDeadLetterEntry {
+    /** Brain route segment the payload was bound for. */
+    route: 'outcomes' | 'compile_outcome_quality' | 'probe_outcomes' | 'compile_outcome_advisories' | 'golden_irs';
+    /**
+     * Endpoint the payload was originally bound for. Flush replays ONLY entries
+     * matching the currently-configured endpoint — a reconfigure must never
+     * replay another brain's payloads into the new target (caught live by
+     * smoke-brain-timeout: a hung-socket test payload auto-flushed into the
+     * real brain after the smoke re-pointed configureBrain).
+     */
+    endpoint: string;
+    /** The exact JSON body that failed to land. */
+    payload: unknown;
+    failedAt: string;
+    /** Delivery attempts so far (1 = the original failed POST). */
+    attempts: number;
+    lastError: string;
+}
+/**
+ * Process-local brain write delivery ledger. `acked` is the only number that
+ * means "a row landed" — fire-and-forget callers that need delivery evidence
+ * read this (or set `BrainConfig.sync`). Cheap enough to attach to any debug
+ * or health surface the consumer already exposes.
+ */
+declare function brainHealth(): BrainHealthSnapshot;
+/** Read-only view of the pending dead-letter (for consumer-side persistence). */
+declare function peekBrainDeadLetter(): readonly BrainDeadLetterEntry[];
+/**
+ * Replay pending dead-letter payloads against the configured brain. Delivered
+ * entries are removed; failures increment `attempts` and entries are dropped
+ * after 3 total attempts (bounded — never an infinite retry, per the Redis
+ * DLQ rule). Safe to call any time; no-ops when unconfigured or already
+ * flushing. Also runs opportunistically after any successful write.
+ */
+declare function flushBrainDeadLetter(): Promise<{
+    attempted: number;
+    delivered: number;
+    remaining: number;
+}>;
 declare function record(input: RecordInput): Promise<void>;
 /**
  * Wire shape POSTed by `record()` to the brain proxy's `/outcomes` endpoint.
@@ -522,8 +581,10 @@ interface OutcomePayload {
  * = true for runtime contexts that can't tolerate fire-and-forget teardown
  * (Vercel Edge, Cloudflare Workers, AWS Lambda) — see L-086.
  *
- * Returns OutcomeResult with ok: false + stable reason on persistence
- * failure. Never throws.
+ * Returns (alpha.61): `{ok: true}` only when the POST was acknowledged 2xx
+ * (sync mode); `{ok: 'queued'}` in fire-and-forget mode (handed to the
+ * runtime, NOT acked — read `brainHealth()` for delivery evidence);
+ * `{ok: false, reason}` on known failure. Never throws.
  */
 declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
 /**
@@ -625,6 +686,193 @@ declare function buildShadowProbeRow(input: ShadowProbeRecordInput): {
  * `/probe_outcomes` the same way they forward `/outcomes`.
  */
 declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>;
+/**
+ * Golden-IR capture input. UNLIKE every other brain write, this row carries the
+ * RAW full PromptIR — an explicit, documented posture change from the s51
+ * "brain holds no raw consumer prompts" rule, gated on consumer opt-in
+ * (`KGAUTO_GOLDEN_CAPTURE` env / `CallOptions.goldenCapture`). The `consent`
+ * field records the provenance of that opt-in at capture time.
+ */
+interface GoldenIrRecordInput {
+    appId: string;
+    archetype: string;
+    /** hashShape() of the call at compile time (peek before record() pops). */
+    shapeKey?: string;
+    /** The full PromptIR, verbatim. Plain JSON by construction (ir.ts). */
+    ir: unknown;
+    incumbentModel: string;
+    incumbentOutput?: string;
+    incumbentLatencyMs?: number;
+    incumbentTokensIn?: number;
+    incumbentTokensOut?: number;
+    /** 'sampled' (capture flag fired on live traffic) | 'curated' (operator). */
+    source: 'sampled' | 'curated';
+    /** Consent provenance, e.g. 'KGAUTO_GOLDEN_CAPTURE=0.1 (consumer env opt-in)'. */
+    consent: string;
+    /** Optional link back to the compile handle of the captured call. */
+    outcomeHandle?: string;
+}
+/** Pure builder for the `kgauto_golden_irs` row (snake_case wire shape). */
+declare function buildGoldenIrRow(input: GoldenIrRecordInput): {
+    app_id: string;
+    intent_archetype: string;
+    shape_key: string | null;
+    ir: unknown;
+    incumbent_model: string;
+    incumbent_output: string | null;
+    incumbent_latency_ms: number | null;
+    incumbent_tokens_in: number | null;
+    incumbent_tokens_out: number | null;
+    source: 'sampled' | 'curated';
+    consent: string;
+    outcome_handle: string | null;
+};
+/**
+ * Persist one golden IR to `kgauto_golden_irs`. Same G1 write-leg discipline as
+ * every other brain route (redirect check, ledger, dead-letter); fire-and-forget
+ * by default, honors `BrainConfig.sync`. Never throws.
+ */
+declare function recordGoldenIr(input: GoldenIrRecordInput): Promise<void>;
+
+/**
+ * Golden-set eval engine (alpha.62, eval spine — design brief 2026-07-17).
+ *
+ * Implements the quality-floor-guarded model-swap contract:
+ *
+ *   > A model replaces another on a surface only by demonstrating
+ *   > same-or-better quality on that surface's real workload — never by
+ *   > price, recency, or judgment alone.
+ *
+ * One eval run: load the active golden set for (app, archetype), replay every
+ * IR on BOTH the incumbent and the candidate (fresh outputs on both sides —
+ * fair comparison, no stale stored output), apply mechanical hard floors,
+ * then a pairwise LLM judge (order-swapped to cancel position bias), and
+ * aggregate under the non-inferiority rule:
+ *
+ *   promote-ready  ⇔  wins-or-ties ≥ threshold (default 80%)
+ *                     AND zero hard-floor violations
+ *                     AND candidate p50 latency ≤ ratio × incumbent p50
+ *
+ * Evidence lands as brain rows: one `kgauto_golden_eval_runs` aggregate + one
+ * `probe_outcomes` row per case (`replay_source='golden-replay'`, full
+ * fidelity by construction) + an evidence-attached advisory on the consumer's
+ * advisory surface (trust-ladder Stage 1: eval runs, human clicks promote).
+ *
+ * Judging is PAIRWISE, not absolute — it operationalizes the quality-floor
+ * Common Pattern directly ("same or better, never less"). Each pair is judged
+ * twice with A/B order swapped; disagreement between the two orders is scored
+ * a tie (the honest reading of positional noise).
+ *
+ * This module is operator-grade: it talks to the brain via direct PostgREST
+ * with a service key (the watchers' convention), never through consumer
+ * proxies, and it deliberately does NOT call record() — eval traffic must not
+ * pollute compile_outcomes.
+ */
+
+/**
+ * What "better" means per archetype. Fed verbatim into the pairwise judge
+ * prompt. Kept deliberately short — the judge sees the full request, so the
+ * rubric only needs to name the failure modes that matter for the archetype.
+ */
+declare const JUDGE_RUBRICS: Record<string, string>;
+declare function rubricFor(archetype: string): string;
+/** Render the golden IR's request for the judge (system sections + user turn). */
+declare function renderIrForJudge(ir: PromptIR): string;
+declare function buildPairwiseJudgePrompt(args: {
+    archetype: string;
+    renderedInput: string;
+    outputA: string;
+    outputB: string;
+}): string;
+type PairwiseWinner = 'A' | 'B' | 'tie';
+/** Parse the judge's JSON verdict. Returns undefined when unparseable. */
+declare function parseJudgeVerdict(raw: string): {
+    winner: PairwiseWinner;
+    rationale?: string;
+} | undefined;
+/**
+ * Combine the two order-swapped verdicts into a case verdict. Both verdicts
+ * are expressed in incumbent/candidate terms BEFORE this call (the caller
+ * un-swaps run 2). Agreement → that verdict; disagreement → 'tied' (positional
+ * noise reads as a tie, never as a win).
+ */
+declare function combineOrderSwappedVerdicts(run1: 'candidate-better' | 'current-better' | 'tied', run2: 'candidate-better' | 'current-better' | 'tied'): 'candidate-better' | 'current-better' | 'tied';
+interface GoldenEvalOptions {
+    appId: string;
+    archetype: string;
+    candidateModel: string;
+    /**
+     * Incumbent to compare against. Default: the most frequent incumbent_model
+     * across the loaded golden set (the surface's de-facto leader).
+     */
+    incumbentModel?: string;
+    /** Judge model id. Default 'claude-opus-4-8' (judge chain tier 0). */
+    judgeModel?: string;
+    /** Max golden cases to load (newest first). Default 50. */
+    limit?: number;
+    /** Non-inferiority threshold on wins-or-ties. Default 0.8. */
+    winOrTieThreshold?: number;
+    /** Latency hard floor: candidate p50 ≤ ratio × incumbent p50. Default 3. */
+    latencyFloorRatio?: number;
+    /** Minimum judged cases for a non-inconclusive verdict. Default 5. */
+    minJudgeableCases?: number;
+    /** What fired the eval. Default 'manual' (Stage 1). */
+    triggerSource?: 'manual' | 'supply' | 'price' | 'demand';
+    /** Brain access — direct PostgREST (operator convention). */
+    supabaseUrl: string;
+    serviceKey: string;
+    /** Provider keys for the replay + judge calls. Default: process.env. */
+    apiKeys?: ApiKeys;
+    fetchImpl?: typeof fetch;
+    /** Replay + judge but write NOTHING to the brain. */
+    dryRun?: boolean;
+    onProgress?: (message: string) => void;
+}
+interface GoldenEvalCase {
+    goldenIrId: number;
+    verdict: 'candidate-better' | 'tied' | 'current-better' | 'inconclusive';
+    judgeRationale?: string;
+    /** Hard-floor violations on the candidate side for this case. */
+    floorViolations: Array<'empty' | 'schema' | 'candidate_error'>;
+    errorClass?: string;
+    incumbent?: {
+        latencyMs: number;
+        tokensIn: number;
+        tokensOut: number;
+        text: string;
+    };
+    candidate?: {
+        latencyMs: number;
+        tokensIn: number;
+        tokensOut: number;
+        text: string;
+    };
+    /** Case excluded from the denominator (incumbent replay/judge failed). */
+    excludedReason?: string;
+}
+interface GoldenEvalRunResult {
+    verdict: 'promote-ready' | 'not-inferior' | 'inconclusive';
+    runId?: number;
+    appId: string;
+    archetype: string;
+    incumbentModel: string;
+    candidateModel: string;
+    judgeModel: string;
+    nCases: number;
+    wins: number;
+    ties: number;
+    losses: number;
+    floorViolations: number;
+    floorDetail: Record<string, number>;
+    winOrTieRatio: number | null;
+    latencyRatio: number | null;
+    costIncumbentUsd: number | null;
+    costCandidateUsd: number | null;
+    advisoryOutcomeId?: number;
+    cases: GoldenEvalCase[];
+    notes: string[];
+}
+declare function runGoldenEval(opts: GoldenEvalOptions): Promise<GoldenEvalRunResult>;
 
 /**
  * alpha.60 — the library's own version, baked as a constant so Edge/Worker
@@ -639,7 +887,7 @@ declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>
  * 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.60";
+declare const LIBRARY_VERSION = "2.0.0-alpha.62";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -1825,7 +2073,7 @@ declare function getSequentialStarterChainWithGrounding(archetype: IntentArchety
  * Sync reader for the brain-driven chains map. Returns bundled
  * STARTER_CHAINS when brain-query is disabled, cold, or unreachable.
  */
-declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform", string[]>;
+declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform" | "judge", string[]>;
 
 /**
  * archetype-perf-brain — alpha.11 KG-12 adapter.
@@ -2428,4 +2676,4 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
  */
 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, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, Grounding, IntentArchetypeName, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+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, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, setTokenizer };