@warmdrift/kgauto-compiler 2.0.0-alpha.63 → 2.0.0-alpha.65

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-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 { 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-9rrfI3yB.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-9rrfI3yB.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';
@@ -376,6 +376,14 @@ interface BrainQueryConfig {
      * advisory).
      */
     findingsExclusions?: boolean;
+    /**
+     * alpha.64 — hard opt-out of the surface-promotions fetch layer (Stage 2).
+     * Default true; only matters when consent (`BrainConfig.autoPromote` /
+     * `KGAUTO_AUTO_PROMOTE`) is present — without consent the layer is off
+     * regardless. Set `false` to disable the fetch even while consented
+     * (debug/emergency lever).
+     */
+    promotions?: boolean;
     /** SWR window in ms. Default 300_000 (5 min). */
     cacheTtlMs?: number;
     /** Override the GET URL when the read endpoint differs from the write one.
@@ -388,6 +396,13 @@ interface BrainQueryConfig {
      * Defaults to `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions`.
      */
     findingsEndpoint?: string;
+    /**
+     * alpha.64 — override the surface-promotions endpoint (Stage 2). Only
+     * consulted when the consumer opted in via `BrainConfig.autoPromote` /
+     * `KGAUTO_AUTO_PROMOTE`. Library appends `?app_id=X`. Defaults to
+     * `https://kgauto-dashboard.vercel.app/api/kgauto-v2/promotions`.
+     */
+    promotionsEndpoint?: string;
 }
 interface BrainConfig {
     /** Brain HTTP endpoint base URL (e.g., https://kgauto-brain.vercel.app/api). */
@@ -437,6 +452,27 @@ interface BrainConfig {
      * not affected.
      */
     timeoutMs?: number;
+    /**
+     * alpha.64 (Stage 2 of the eval trust ladder) — consent switch for the
+     * surface-promotion routing effect. Default OFF.
+     *
+     * When true (or when the `KGAUTO_AUTO_PROMOTE` env var is '1'/'true' and
+     * this field is left undefined — env-as-consent, the KGAUTO_GOLDEN_CAPTURE
+     * precedent; an explicit `false` here overrides the env), compile()
+     * consults the brain's active `kgauto_promotions` rows for this app and
+     * boosts the promoted model at scoring time. Promotions are written only
+     * by the automated golden-eval trigger after a promote-ready verdict on a
+     * price-dominant (cheaper) candidate, and every promotion sits behind the
+     * 7-day rollback guard (daily watcher auto-reverts on regression vs the
+     * frozen baseline).
+     *
+     * Not opted in ⇒ promotions have ZERO routing effect (they remain visible
+     * as advisories + dashboard rows). Consumer sovereignty is preserved even
+     * when opted in: `forceModel`, `policy.blockedModels`, and cost ceilings
+     * always win, and a non-empty `policy.preferredModels` defers the
+     * promotion entirely.
+     */
+    autoPromote?: boolean;
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;
@@ -887,7 +923,7 @@ declare function runGoldenEval(opts: GoldenEvalOptions): Promise<GoldenEvalRunRe
  * 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.63";
+declare const LIBRARY_VERSION = "2.0.0-alpha.65";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -1772,7 +1808,7 @@ declare function getPerAxisMetrics(opts: GetPerAxisMetricsOpts): Promise<PerAxis
  * no execute() handler, no env-var convention). Narrowing here keeps the
  * reachability check structurally honest.
  */
-type SupportedProvider = 'anthropic' | 'google' | 'openai' | 'deepseek';
+type SupportedProvider = 'anthropic' | 'google' | 'openai' | 'deepseek' | 'zai' | 'moonshot';
 /**
  * Per-provider env var names kgauto recognizes. Order doesn't matter —
  * first-present wins. Multiple names per provider supported because Google
@@ -2630,6 +2666,114 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
     reason: string;
 }>;
 
+/**
+ * promotions-brain — alpha.64 Stage-2 substrate.
+ *
+ * Per-tenant SWR cache for the `kgauto_promotions` table populated by the
+ * golden-eval trigger's auto-promote actor (Stage 2 of the eval trust
+ * ladder: auto-promote downswaps behind the 7-day rollback guard). Mirrors
+ * `promote-ready-brain.ts` shape where applicable; this is the read-side
+ * substrate for the compile-time promotion boost in `passScoreTargets`.
+ *
+ * Design contract:
+ *   command-center/advisory/kgauto/2026-07-18_stage2-auto-promote-design.md
+ *
+ * Consent posture: the routing effect is OPT-IN, default OFF. The cache is
+ * only activated by `configureBrain()` when the consumer opted in via
+ * `BrainConfig.autoPromote: true` or the `KGAUTO_AUTO_PROMOTE` env var
+ * (config field wins when both are present — mirror of the
+ * `KGAUTO_GOLDEN_CAPTURE` env-as-consent precedent). Not opted in ⇒ this
+ * module never fetches and `getApplicablePromotion` returns undefined ⇒
+ * zero behavior change anywhere in compile().
+ *
+ * Architecture (mirror of promote-ready-brain):
+ *   - Sync API surface: `getApplicablePromotion({ appId, archetype })`
+ *     returns immediately. First call returns undefined (cold) and fires an
+ *     async refresh; subsequent calls within TTL return brain data.
+ *   - Per-appId snapshot; one fetch per appId per TTL window.
+ *   - Tolerant: brain down / misconfigured / unexpected shape → undefined.
+ *     Never throws. Warns once per process.
+ *
+ * A rollback (`status='rolled_back'` PATCHed by the promotion-guard
+ * watcher) drops the row from the endpoint's `status=active` filter, so
+ * routing reverts within one TTL window — the mechanism the 7-day guard's
+ * auto-revert rests on.
+ */
+
+/**
+ * One active surface promotion, camelCase-mapped at the boundary from the
+ * snake_case endpoint row (typed-boundary-transformer convention).
+ */
+interface PromotionRow {
+    /** Brain row id — cited in the `promotion-applied` mutation for Glass-Box. */
+    id: number;
+    /** Intent archetype the promotion applies to. */
+    archetype: string;
+    /** The model this surface now routes to. */
+    promotedModel: string;
+    /** The model it replaced (the eval's incumbent). */
+    incumbentModel: string;
+    /** The promote-ready kgauto_golden_eval_runs row this rests on. */
+    evalRunId: number | null;
+    /**
+     * Evidence-supersedes-judgment: skip the alpha.49 schema-weak
+     * quality-gate penalty for the promoted model on this surface (the eval
+     * measured the schema floor holding on real workload).
+     */
+    suppressQualityGate: boolean;
+    /** ISO timestamp the promotion went active. */
+    promotedAt: string;
+}
+interface PromotionsRuntime {
+    /** Endpoint base URL. The library appends `?app_id=<id>`. */
+    endpoint: string;
+    /** Stale-while-revalidate window in ms. */
+    ttlMs: number;
+    /** Pluggable fetch. */
+    fetchImpl: typeof fetch;
+    /** Optional warn hook. */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Default endpoint hosted on the kgauto-dashboard. Serves `status='active'`
+ * kgauto_promotions rows for one app_id. Mirrors the findings convention.
+ */
+declare const DEFAULT_PROMOTIONS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/promotions";
+/**
+ * True when the KGAUTO_AUTO_PROMOTE env var opts this process in.
+ * Accepted truthy forms: '1', 'true' (case-insensitive). Everything else —
+ * unset, '', '0', 'false' — is OFF. Read at configureBrain() time, not per
+ * call.
+ */
+declare function isAutoPromoteEnabledFromEnv(envSource?: Record<string, string | undefined>): boolean;
+/**
+ * Wire (or rewire) the runtime. Pass undefined to disable. Resets all
+ * snapshots. Called from `configureBrain()` ONLY when the consumer opted in.
+ */
+declare function configurePromotionsBrain(rt: PromotionsRuntime | undefined): void;
+/** Sync introspection — is the promotions brain active (i.e. opted in)? */
+declare function isPromotionsBrainActive(): boolean;
+interface GetApplicablePromotionOpts {
+    /** App id to read promotions for. Required. */
+    appId: string;
+    /** Archetype of the compile in flight. Required. */
+    archetype: IntentArchetypeName | string;
+}
+/**
+ * Sync reader. Returns the active promotion for `(appId, archetype)` or
+ * undefined. First call returns undefined and triggers async refresh;
+ * subsequent calls within TTL return brain data. The brain enforces one
+ * active promotion per surface (partial unique index), so at most one row
+ * matches.
+ *
+ * NEVER throws. Not configured / brain down / cold → undefined.
+ */
+declare function getApplicablePromotion(opts: GetApplicablePromotionOpts): PromotionRow | undefined;
+/** Reset module state. Tests must call between cases. */
+declare function _testResetPromotions(): void;
+/** Wait for any in-flight refresh to settle. */
+declare function _testWaitForPromotionsRefresh(): Promise<void>;
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -2676,4 +2820,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 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 };
+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, DEFAULT_PROMOTIONS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, 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, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, _testResetPromotions, _testWaitForPromotionsRefresh, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configurePromotionsBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isPromotionsBrainActive, 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-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 { 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-Dx_UXPfP.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-Dx_UXPfP.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';
@@ -376,6 +376,14 @@ interface BrainQueryConfig {
      * advisory).
      */
     findingsExclusions?: boolean;
+    /**
+     * alpha.64 — hard opt-out of the surface-promotions fetch layer (Stage 2).
+     * Default true; only matters when consent (`BrainConfig.autoPromote` /
+     * `KGAUTO_AUTO_PROMOTE`) is present — without consent the layer is off
+     * regardless. Set `false` to disable the fetch even while consented
+     * (debug/emergency lever).
+     */
+    promotions?: boolean;
     /** SWR window in ms. Default 300_000 (5 min). */
     cacheTtlMs?: number;
     /** Override the GET URL when the read endpoint differs from the write one.
@@ -388,6 +396,13 @@ interface BrainQueryConfig {
      * Defaults to `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions`.
      */
     findingsEndpoint?: string;
+    /**
+     * alpha.64 — override the surface-promotions endpoint (Stage 2). Only
+     * consulted when the consumer opted in via `BrainConfig.autoPromote` /
+     * `KGAUTO_AUTO_PROMOTE`. Library appends `?app_id=X`. Defaults to
+     * `https://kgauto-dashboard.vercel.app/api/kgauto-v2/promotions`.
+     */
+    promotionsEndpoint?: string;
 }
 interface BrainConfig {
     /** Brain HTTP endpoint base URL (e.g., https://kgauto-brain.vercel.app/api). */
@@ -437,6 +452,27 @@ interface BrainConfig {
      * not affected.
      */
     timeoutMs?: number;
+    /**
+     * alpha.64 (Stage 2 of the eval trust ladder) — consent switch for the
+     * surface-promotion routing effect. Default OFF.
+     *
+     * When true (or when the `KGAUTO_AUTO_PROMOTE` env var is '1'/'true' and
+     * this field is left undefined — env-as-consent, the KGAUTO_GOLDEN_CAPTURE
+     * precedent; an explicit `false` here overrides the env), compile()
+     * consults the brain's active `kgauto_promotions` rows for this app and
+     * boosts the promoted model at scoring time. Promotions are written only
+     * by the automated golden-eval trigger after a promote-ready verdict on a
+     * price-dominant (cheaper) candidate, and every promotion sits behind the
+     * 7-day rollback guard (daily watcher auto-reverts on regression vs the
+     * frozen baseline).
+     *
+     * Not opted in ⇒ promotions have ZERO routing effect (they remain visible
+     * as advisories + dashboard rows). Consumer sovereignty is preserved even
+     * when opted in: `forceModel`, `policy.blockedModels`, and cost ceilings
+     * always win, and a non-empty `policy.preferredModels` defers the
+     * promotion entirely.
+     */
+    autoPromote?: boolean;
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;
@@ -887,7 +923,7 @@ declare function runGoldenEval(opts: GoldenEvalOptions): Promise<GoldenEvalRunRe
  * 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.63";
+declare const LIBRARY_VERSION = "2.0.0-alpha.65";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -1772,7 +1808,7 @@ declare function getPerAxisMetrics(opts: GetPerAxisMetricsOpts): Promise<PerAxis
  * no execute() handler, no env-var convention). Narrowing here keeps the
  * reachability check structurally honest.
  */
-type SupportedProvider = 'anthropic' | 'google' | 'openai' | 'deepseek';
+type SupportedProvider = 'anthropic' | 'google' | 'openai' | 'deepseek' | 'zai' | 'moonshot';
 /**
  * Per-provider env var names kgauto recognizes. Order doesn't matter —
  * first-present wins. Multiple names per provider supported because Google
@@ -2630,6 +2666,114 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
     reason: string;
 }>;
 
+/**
+ * promotions-brain — alpha.64 Stage-2 substrate.
+ *
+ * Per-tenant SWR cache for the `kgauto_promotions` table populated by the
+ * golden-eval trigger's auto-promote actor (Stage 2 of the eval trust
+ * ladder: auto-promote downswaps behind the 7-day rollback guard). Mirrors
+ * `promote-ready-brain.ts` shape where applicable; this is the read-side
+ * substrate for the compile-time promotion boost in `passScoreTargets`.
+ *
+ * Design contract:
+ *   command-center/advisory/kgauto/2026-07-18_stage2-auto-promote-design.md
+ *
+ * Consent posture: the routing effect is OPT-IN, default OFF. The cache is
+ * only activated by `configureBrain()` when the consumer opted in via
+ * `BrainConfig.autoPromote: true` or the `KGAUTO_AUTO_PROMOTE` env var
+ * (config field wins when both are present — mirror of the
+ * `KGAUTO_GOLDEN_CAPTURE` env-as-consent precedent). Not opted in ⇒ this
+ * module never fetches and `getApplicablePromotion` returns undefined ⇒
+ * zero behavior change anywhere in compile().
+ *
+ * Architecture (mirror of promote-ready-brain):
+ *   - Sync API surface: `getApplicablePromotion({ appId, archetype })`
+ *     returns immediately. First call returns undefined (cold) and fires an
+ *     async refresh; subsequent calls within TTL return brain data.
+ *   - Per-appId snapshot; one fetch per appId per TTL window.
+ *   - Tolerant: brain down / misconfigured / unexpected shape → undefined.
+ *     Never throws. Warns once per process.
+ *
+ * A rollback (`status='rolled_back'` PATCHed by the promotion-guard
+ * watcher) drops the row from the endpoint's `status=active` filter, so
+ * routing reverts within one TTL window — the mechanism the 7-day guard's
+ * auto-revert rests on.
+ */
+
+/**
+ * One active surface promotion, camelCase-mapped at the boundary from the
+ * snake_case endpoint row (typed-boundary-transformer convention).
+ */
+interface PromotionRow {
+    /** Brain row id — cited in the `promotion-applied` mutation for Glass-Box. */
+    id: number;
+    /** Intent archetype the promotion applies to. */
+    archetype: string;
+    /** The model this surface now routes to. */
+    promotedModel: string;
+    /** The model it replaced (the eval's incumbent). */
+    incumbentModel: string;
+    /** The promote-ready kgauto_golden_eval_runs row this rests on. */
+    evalRunId: number | null;
+    /**
+     * Evidence-supersedes-judgment: skip the alpha.49 schema-weak
+     * quality-gate penalty for the promoted model on this surface (the eval
+     * measured the schema floor holding on real workload).
+     */
+    suppressQualityGate: boolean;
+    /** ISO timestamp the promotion went active. */
+    promotedAt: string;
+}
+interface PromotionsRuntime {
+    /** Endpoint base URL. The library appends `?app_id=<id>`. */
+    endpoint: string;
+    /** Stale-while-revalidate window in ms. */
+    ttlMs: number;
+    /** Pluggable fetch. */
+    fetchImpl: typeof fetch;
+    /** Optional warn hook. */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Default endpoint hosted on the kgauto-dashboard. Serves `status='active'`
+ * kgauto_promotions rows for one app_id. Mirrors the findings convention.
+ */
+declare const DEFAULT_PROMOTIONS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/promotions";
+/**
+ * True when the KGAUTO_AUTO_PROMOTE env var opts this process in.
+ * Accepted truthy forms: '1', 'true' (case-insensitive). Everything else —
+ * unset, '', '0', 'false' — is OFF. Read at configureBrain() time, not per
+ * call.
+ */
+declare function isAutoPromoteEnabledFromEnv(envSource?: Record<string, string | undefined>): boolean;
+/**
+ * Wire (or rewire) the runtime. Pass undefined to disable. Resets all
+ * snapshots. Called from `configureBrain()` ONLY when the consumer opted in.
+ */
+declare function configurePromotionsBrain(rt: PromotionsRuntime | undefined): void;
+/** Sync introspection — is the promotions brain active (i.e. opted in)? */
+declare function isPromotionsBrainActive(): boolean;
+interface GetApplicablePromotionOpts {
+    /** App id to read promotions for. Required. */
+    appId: string;
+    /** Archetype of the compile in flight. Required. */
+    archetype: IntentArchetypeName | string;
+}
+/**
+ * Sync reader. Returns the active promotion for `(appId, archetype)` or
+ * undefined. First call returns undefined and triggers async refresh;
+ * subsequent calls within TTL return brain data. The brain enforces one
+ * active promotion per surface (partial unique index), so at most one row
+ * matches.
+ *
+ * NEVER throws. Not configured / brain down / cold → undefined.
+ */
+declare function getApplicablePromotion(opts: GetApplicablePromotionOpts): PromotionRow | undefined;
+/** Reset module state. Tests must call between cases. */
+declare function _testResetPromotions(): void;
+/** Wait for any in-flight refresh to settle. */
+declare function _testWaitForPromotionsRefresh(): Promise<void>;
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -2676,4 +2820,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 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 };
+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, DEFAULT_PROMOTIONS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, 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, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, _testResetPromotions, _testWaitForPromotionsRefresh, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configurePromotionsBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isPromotionsBrainActive, 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 };