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

package/dist/{chunk-ZU62HRWK.mjs → chunk-DGPYLFDG.mjs}

@@ -1,5 +1,5 @@
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.63";
+var LIBRARY_VERSION = "2.0.0-alpha.64";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/index.d.mts

@@ -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.64";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -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

@@ -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.64";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -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.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   ARCHETYPE_FLOOR_DEFAULT: () => ARCHETYPE_FLOOR_DEFAULT,
   CallError: () => CallError,
   DEFAULT_FINDINGS_ENDPOINT: () => DEFAULT_FINDINGS_ENDPOINT,
+  DEFAULT_PROMOTIONS_ENDPOINT: () => DEFAULT_PROMOTIONS_ENDPOINT,
   DIALECT_VERSION: () => DIALECT_VERSION,
   FamilyResolutionError: () => FamilyResolutionError,
   INTENT_ARCHETYPES: () => INTENT_ARCHETYPES,
@@ -38,6 +39,8 @@ __export(index_exports, {
   PROVIDER_ENV_KEYS: () => PROVIDER_ENV_KEYS,
   RULE_SEQUENTIAL_TOOL_CLIFF: () => RULE_SEQUENTIAL_TOOL_CLIFF,
   TRANSLATOR_FLOOR: () => TRANSLATOR_FLOOR,
+  _testResetPromotions: () => _testResetPromotions,
+  _testWaitForPromotionsRefresh: () => _testWaitForPromotionsRefresh,
   allProfiles: () => allProfiles,
   applyArchetypeConvention: () => applyArchetypeConvention,
   applySectionRewrites: () => applySectionRewrites,
@@ -57,6 +60,7 @@ __export(index_exports, {
   compile: () => compile2,
   compileForAISDKv6: () => compileForAISDKv6,
   configureBrain: () => configureBrain,
+  configurePromotionsBrain: () => configurePromotionsBrain,
   countTokens: () => countTokens,
   createBrainForwardRoutes: () => createBrainForwardRoutes,
   createKeyHealthRoute: () => createKeyHealthRoute,
@@ -68,6 +72,7 @@ __export(index_exports, {
   getActionableAdvisories: () => getActionableAdvisories,
   getAllStarterChains: () => getAllStarterChains,
   getAllStarterChainsWithGrounding: () => getAllStarterChainsWithGrounding,
+  getApplicablePromotion: () => getApplicablePromotion,
   getArchetypePerfScore: () => getArchetypePerfScore,
   getDefaultFallbackChain: () => getDefaultFallbackChain,
   getDefaultFallbackChainWithGrounding: () => getDefaultFallbackChainWithGrounding,
@@ -83,10 +88,12 @@ __export(index_exports, {
   getStarterChainWithGrounding: () => getStarterChainWithGrounding,
   hashShape: () => hashShape,
   isArchetype: () => isArchetype,
+  isAutoPromoteEnabledFromEnv: () => isAutoPromoteEnabledFromEnv,
   isBrainQueryActiveFor: () => isBrainQueryActiveFor,
   isBrainSync: () => isBrainSync,
   isExclusionFindingsBrainActive: () => isExclusionFindingsBrainActive,
   isModelReachable: () => isModelReachable,
+  isPromotionsBrainActive: () => isPromotionsBrainActive,
   isProviderReachable: () => isProviderReachable,
   latencyTierOf: () => latencyTierOf,
   learningKey: () => learningKey,
@@ -2602,6 +2609,7 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
 var LATENCY_OVERAGE_WEIGHT = 0.6;
 var LATENCY_PENALTY_CAP = 1;
 var QUALITY_GATE_PENALTY = 4;
+var PROMOTION_BOOST = 5;
 function effectiveConventions(profile) {
   const own = profile.archetypeConventions ?? [];
   if (own.length > 0) return own;
@@ -2619,6 +2627,9 @@ function passScoreTargets(ir, opts) {
   const preferredSet = new Set(policy.preferredModels ?? []);
   const scores = [];
   const policyMutations = [];
+  const rawPromotion = opts.promotion;
+  const promotionDeferred = rawPromotion !== void 0 && (policy.preferredModels?.length ?? 0) > 0;
+  const promotion = promotionDeferred ? void 0 : rawPromotion;
   const modelIds = ir.models.filter((m) => typeof m === "string");
   for (const modelId of modelIds) {
     let profile;
@@ -2683,7 +2694,12 @@ function passScoreTargets(ir, opts) {
       );
       if (schemaWeak) qualityGatePenalty = QUALITY_GATE_PENALTY;
     }
-    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty - qualityGatePenalty;
+    const isPromoted = promotion?.promotedModel === modelId;
+    if (isPromoted && promotion.suppressQualityGate) {
+      qualityGatePenalty = 0;
+    }
+    const promotionBoost = isPromoted ? PROMOTION_BOOST : 0;
+    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty - qualityGatePenalty + promotionBoost;
     scores.push({
       modelId,
       estimatedCostUsd,
@@ -2733,6 +2749,22 @@ function passScoreTargets(ir, opts) {
         description: `Model ${modelId} gated below the quality floor for archetype '${ir.intent.archetype}' \u2014 declared structuredOutput + kgauto convention flags it schema-weak for this contract (structuredOutputHint:'avoid'). Down-ranked out of leadership; retained as graceful fallback only.`
       });
     }
+    if (isPromoted && reasons.length === 0) {
+      policyMutations.push({
+        id: `promotion-applied-${modelId}`,
+        source: "surface_promotion",
+        passName: "score_targets",
+        description: `Model ${modelId} boosted to surface leadership by active promotion #${promotion.id} (golden-eval run ${promotion.evalRunId ?? "n/a"}, Stage 2 auto-promote, 7-day rollback guard)` + (promotion.suppressQualityGate ? " \u2014 schema-weak quality gate suppressed for this tuple (eval measured the floor holding on real workload)" : "")
+      });
+    }
+  }
+  if (promotionDeferred && rawPromotion && modelIds.includes(rawPromotion.promotedModel)) {
+    policyMutations.push({
+      id: `promotion-deferred-consumer-preference-${rawPromotion.promotedModel}`,
+      source: "surface_promotion",
+      passName: "score_targets",
+      description: `Active promotion #${rawPromotion.id} for ${rawPromotion.promotedModel} deferred \u2014 CompilePolicy.preferredModels is declared and explicit consumer preference outranks brain evidence.`
+    });
   }
   return { value: scores, mutations: policyMutations };
 }
@@ -4121,6 +4153,130 @@ ${originalText}`;
   return { rewrittenIR, rewrites };
 }
 
+// src/promotions-brain.ts
+function isRawPromotionRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return (typeof r.id === "number" || typeof r.id === "string") && typeof r.intent_archetype === "string" && typeof r.promoted_model === "string" && typeof r.incumbent_model === "string";
+}
+function coerceId(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "string") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+function mapRowsToPromotions(rows) {
+  const out = [];
+  for (const row of rows) {
+    if (!isRawPromotionRow(row)) continue;
+    const id = coerceId(row.id);
+    if (id === null) continue;
+    out.push({
+      id,
+      archetype: row.intent_archetype,
+      promotedModel: row.promoted_model,
+      incumbentModel: row.incumbent_model,
+      evalRunId: coerceId(row.eval_run_id ?? null),
+      suppressQualityGate: row.suppress_quality_gate === true,
+      promotedAt: typeof row.promoted_at === "string" ? row.promoted_at : ""
+    });
+  }
+  return out;
+}
+var snapshots4 = /* @__PURE__ */ new Map();
+var runtime5;
+var warnedOnce4 = false;
+var DEFAULT_PROMOTIONS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/promotions";
+function isAutoPromoteEnabledFromEnv(envSource) {
+  const env = envSource ?? (typeof process !== "undefined" && process.env ? process.env : {});
+  const raw = (env.KGAUTO_AUTO_PROMOTE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true";
+}
+function configurePromotionsBrain(rt) {
+  runtime5 = rt;
+  snapshots4.clear();
+  warnedOnce4 = false;
+}
+function isPromotionsBrainActive() {
+  return runtime5 !== void 0;
+}
+function getApplicablePromotion(opts) {
+  const rt = runtime5;
+  if (!rt) return void 0;
+  const appId = opts.appId;
+  if (!appId || !opts.archetype) return void 0;
+  let snap = snapshots4.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots4.set(appId, snap);
+  }
+  const now = Date.now();
+  const stale = snap.expiresAt <= now;
+  if (stale && !snap.refreshing) {
+    snap.refreshing = true;
+    void asyncRefresh5(rt, appId);
+  }
+  return snap.data.find((p) => p.archetype === opts.archetype);
+}
+var pendingRefreshes4 = /* @__PURE__ */ new Map();
+async function asyncRefresh5(rt, appId) {
+  const promise = doRefresh5(rt, appId);
+  pendingRefreshes4.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes4.get(appId) === promise) {
+      pendingRefreshes4.delete(appId);
+    }
+  }
+}
+async function doRefresh5(rt, appId) {
+  const url = `${rt.endpoint}?app_id=${encodeURIComponent(appId)}`;
+  let snap = snapshots4.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots4.set(appId, snap);
+  }
+  try {
+    const res = await rt.fetchImpl(url, { method: "GET" });
+    if (!res.ok) {
+      throw new Error(`promotions ${res.status}: ${res.statusText}`);
+    }
+    const body = await res.json();
+    if (runtime5 !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToPromotions(body) : [];
+    snap.data = rows;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    snap.refreshing = false;
+  } catch (err) {
+    if (runtime5 !== rt) return;
+    snap.refreshing = false;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    if (!warnedOnce4) {
+      warnedOnce4 = true;
+      (rt.onError ?? defaultOnError5)(err);
+    }
+  }
+}
+function defaultOnError5(err) {
+  console.warn(
+    "[kgauto] promotions fetch failed (promotion boost inactive until next refresh):",
+    err
+  );
+}
+function _testResetPromotions() {
+  runtime5 = void 0;
+  snapshots4.clear();
+  pendingRefreshes4 = /* @__PURE__ */ new Map();
+  warnedOnce4 = false;
+}
+async function _testWaitForPromotionsRefresh() {
+  const pending = Array.from(pendingRefreshes4.values());
+  if (pending.length > 0) await Promise.all(pending);
+}
+
 // src/compile.ts
 var counter = 0;
 function makeHandle() {
@@ -4147,11 +4303,22 @@ function compile(ir, opts = {}) {
     ...toolFiltered.mutations,
     ...compressed.mutations
   ];
+  const activePromotion = getApplicablePromotion({
+    appId: ir.appId,
+    archetype: ir.intent.archetype
+  });
+  const promotion = activePromotion ? {
+    id: activePromotion.id,
+    promotedModel: activePromotion.promotedModel,
+    evalRunId: activePromotion.evalRunId,
+    suppressQualityGate: activePromotion.suppressQualityGate
+  } : void 0;
   const inputTokens = estimateInputTokens(workingIR);
   const scores = passScoreTargets(workingIR, {
     estimatedInputTokens: inputTokens,
     profilesById: resolver,
-    policy: opts.policy
+    policy: opts.policy,
+    promotion
   });
   accumulatedMutations.push(...scores.mutations);
   const target = pickTarget(workingIR, scores.value);
@@ -4483,11 +4650,23 @@ function configureBrain(config) {
   } else {
     configureExclusionFindingsBrain(void 0);
   }
+  const promotionsConsent = config.autoPromote ?? isAutoPromoteEnabledFromEnv();
+  if (promotionsConsent && bq.promotions !== false) {
+    configurePromotionsBrain({
+      endpoint: bq.promotionsEndpoint ?? DEFAULT_PROMOTIONS_ENDPOINT,
+      ttlMs: bq.cacheTtlMs ?? 3e5,
+      fetchImpl: config.fetchImpl ?? fetch,
+      onError: config.onError
+    });
+  } else {
+    configurePromotionsBrain(void 0);
+  }
 }
 function clearBrain() {
   activeConfig = void 0;
   configureBrainQuery(void 0);
   configureExclusionFindingsBrain(void 0);
+  configurePromotionsBrain(void 0);
 }
 var DEAD_LETTER_MAX_ENTRIES = 50;
 var DEAD_LETTER_MAX_ATTEMPTS = 3;
@@ -4604,7 +4783,7 @@ async function flushBrainDeadLetter() {
         if (entry.attempts >= DEAD_LETTER_MAX_ATTEMPTS) {
           const idx = deadLetter.indexOf(entry);
           if (idx !== -1) deadLetter.splice(idx, 1);
-          (config.onError ?? defaultOnError5)(
+          (config.onError ?? defaultOnError6)(
             new Error(
               `brain dead-letter: dropping ${entry.route} payload after ${entry.attempts} attempts \u2014 last error: ${entry.lastError}`
             )
@@ -4754,7 +4933,7 @@ async function record(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("outcomes", config.endpoint, payload, err);
-      (config.onError ?? defaultOnError5)(err);
+      (config.onError ?? defaultOnError6)(err);
       return;
     }
     maybeAutoFlush();
@@ -4782,7 +4961,7 @@ async function record(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("compile_outcome_advisories", config.endpoint, advisoryPayload, err);
-      (config.onError ?? defaultOnError5)(err);
+      (config.onError ?? defaultOnError6)(err);
     }
   };
   if (config.sync) {
@@ -4791,7 +4970,7 @@ async function record(input) {
     void send();
   }
 }
-function defaultOnError5(err) {
+function defaultOnError6(err) {
   console.warn("[kgauto] brain record failed:", err);
 }
 function describeBrainWriteFailure(status, route, body) {
@@ -4943,7 +5122,7 @@ async function recordOutcome(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("compile_outcome_quality", config.endpoint, payload, err);
-      (config.onError ?? defaultOnError5)(err);
+      (config.onError ?? defaultOnError6)(err);
       return { ok: false, reason: "persistence_failed" };
     }
   };
@@ -5014,7 +5193,7 @@ async function recordShadowProbe(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("probe_outcomes", config.endpoint, row, err);
-      (config.onError ?? defaultOnError5)(err);
+      (config.onError ?? defaultOnError6)(err);
     }
   };
   if (config.sync) {
@@ -5069,7 +5248,7 @@ async function recordGoldenIr(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("golden_irs", config.endpoint, row, err);
-      (config.onError ?? defaultOnError5)(err);
+      (config.onError ?? defaultOnError6)(err);
     }
   };
   if (config.sync) {
@@ -7769,7 +7948,7 @@ function createBrainForwardRoutes(config) {
 }
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.63";
+var LIBRARY_VERSION = "2.0.0-alpha.64";
 
 // src/key-health.ts
 var JSON_HEADERS2 = { "Content-Type": "application/json" };
@@ -8389,6 +8568,7 @@ function compile2(ir, opts) {
   ARCHETYPE_FLOOR_DEFAULT,
   CallError,
   DEFAULT_FINDINGS_ENDPOINT,
+  DEFAULT_PROMOTIONS_ENDPOINT,
   DIALECT_VERSION,
   FamilyResolutionError,
   INTENT_ARCHETYPES,
@@ -8400,6 +8580,8 @@ function compile2(ir, opts) {
   PROVIDER_ENV_KEYS,
   RULE_SEQUENTIAL_TOOL_CLIFF,
   TRANSLATOR_FLOOR,
+  _testResetPromotions,
+  _testWaitForPromotionsRefresh,
   allProfiles,
   applyArchetypeConvention,
   applySectionRewrites,
@@ -8419,6 +8601,7 @@ function compile2(ir, opts) {
   compile,
   compileForAISDKv6,
   configureBrain,
+  configurePromotionsBrain,
   countTokens,
   createBrainForwardRoutes,
   createKeyHealthRoute,
@@ -8430,6 +8613,7 @@ function compile2(ir, opts) {
   getActionableAdvisories,
   getAllStarterChains,
   getAllStarterChainsWithGrounding,
+  getApplicablePromotion,
   getArchetypePerfScore,
   getDefaultFallbackChain,
   getDefaultFallbackChainWithGrounding,
@@ -8445,10 +8629,12 @@ function compile2(ir, opts) {
   getStarterChainWithGrounding,
   hashShape,
   isArchetype,
+  isAutoPromoteEnabledFromEnv,
   isBrainQueryActiveFor,
   isBrainSync,
   isExclusionFindingsBrainActive,
   isModelReachable,
+  isPromotionsBrainActive,
   isProviderReachable,
   latencyTierOf,
   learningKey,

package/dist/index.mjs

@@ -15,7 +15,7 @@ import {
 import {
   LIBRARY_VERSION,
   createKeyHealthRoute
-} from "./chunk-ZU62HRWK.mjs";
+} from "./chunk-DGPYLFDG.mjs";
 import {
   ABSOLUTE_FLOOR,
   ARCHETYPE_FLOOR_DEFAULT,
@@ -739,6 +739,7 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
 var LATENCY_OVERAGE_WEIGHT = 0.6;
 var LATENCY_PENALTY_CAP = 1;
 var QUALITY_GATE_PENALTY = 4;
+var PROMOTION_BOOST = 5;
 function effectiveConventions(profile) {
   const own = profile.archetypeConventions ?? [];
   if (own.length > 0) return own;
@@ -756,6 +757,9 @@ function passScoreTargets(ir, opts) {
   const preferredSet = new Set(policy.preferredModels ?? []);
   const scores = [];
   const policyMutations = [];
+  const rawPromotion = opts.promotion;
+  const promotionDeferred = rawPromotion !== void 0 && (policy.preferredModels?.length ?? 0) > 0;
+  const promotion = promotionDeferred ? void 0 : rawPromotion;
   const modelIds = ir.models.filter((m) => typeof m === "string");
   for (const modelId of modelIds) {
     let profile;
@@ -820,7 +824,12 @@ function passScoreTargets(ir, opts) {
       );
       if (schemaWeak) qualityGatePenalty = QUALITY_GATE_PENALTY;
     }
-    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty - qualityGatePenalty;
+    const isPromoted = promotion?.promotedModel === modelId;
+    if (isPromoted && promotion.suppressQualityGate) {
+      qualityGatePenalty = 0;
+    }
+    const promotionBoost = isPromoted ? PROMOTION_BOOST : 0;
+    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty - qualityGatePenalty + promotionBoost;
     scores.push({
       modelId,
       estimatedCostUsd,
@@ -870,6 +879,22 @@ function passScoreTargets(ir, opts) {
         description: `Model ${modelId} gated below the quality floor for archetype '${ir.intent.archetype}' \u2014 declared structuredOutput + kgauto convention flags it schema-weak for this contract (structuredOutputHint:'avoid'). Down-ranked out of leadership; retained as graceful fallback only.`
       });
     }
+    if (isPromoted && reasons.length === 0) {
+      policyMutations.push({
+        id: `promotion-applied-${modelId}`,
+        source: "surface_promotion",
+        passName: "score_targets",
+        description: `Model ${modelId} boosted to surface leadership by active promotion #${promotion.id} (golden-eval run ${promotion.evalRunId ?? "n/a"}, Stage 2 auto-promote, 7-day rollback guard)` + (promotion.suppressQualityGate ? " \u2014 schema-weak quality gate suppressed for this tuple (eval measured the floor holding on real workload)" : "")
+      });
+    }
+  }
+  if (promotionDeferred && rawPromotion && modelIds.includes(rawPromotion.promotedModel)) {
+    policyMutations.push({
+      id: `promotion-deferred-consumer-preference-${rawPromotion.promotedModel}`,
+      source: "surface_promotion",
+      passName: "score_targets",
+      description: `Active promotion #${rawPromotion.id} for ${rawPromotion.promotedModel} deferred \u2014 CompilePolicy.preferredModels is declared and explicit consumer preference outranks brain evidence.`
+    });
   }
   return { value: scores, mutations: policyMutations };
 }
@@ -2258,6 +2283,130 @@ ${originalText}`;
   return { rewrittenIR, rewrites };
 }
 
+// src/promotions-brain.ts
+function isRawPromotionRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return (typeof r.id === "number" || typeof r.id === "string") && typeof r.intent_archetype === "string" && typeof r.promoted_model === "string" && typeof r.incumbent_model === "string";
+}
+function coerceId(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "string") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+function mapRowsToPromotions(rows) {
+  const out = [];
+  for (const row of rows) {
+    if (!isRawPromotionRow(row)) continue;
+    const id = coerceId(row.id);
+    if (id === null) continue;
+    out.push({
+      id,
+      archetype: row.intent_archetype,
+      promotedModel: row.promoted_model,
+      incumbentModel: row.incumbent_model,
+      evalRunId: coerceId(row.eval_run_id ?? null),
+      suppressQualityGate: row.suppress_quality_gate === true,
+      promotedAt: typeof row.promoted_at === "string" ? row.promoted_at : ""
+    });
+  }
+  return out;
+}
+var snapshots4 = /* @__PURE__ */ new Map();
+var runtime4;
+var warnedOnce4 = false;
+var DEFAULT_PROMOTIONS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/promotions";
+function isAutoPromoteEnabledFromEnv(envSource) {
+  const env = envSource ?? (typeof process !== "undefined" && process.env ? process.env : {});
+  const raw = (env.KGAUTO_AUTO_PROMOTE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true";
+}
+function configurePromotionsBrain(rt) {
+  runtime4 = rt;
+  snapshots4.clear();
+  warnedOnce4 = false;
+}
+function isPromotionsBrainActive() {
+  return runtime4 !== void 0;
+}
+function getApplicablePromotion(opts) {
+  const rt = runtime4;
+  if (!rt) return void 0;
+  const appId = opts.appId;
+  if (!appId || !opts.archetype) return void 0;
+  let snap = snapshots4.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots4.set(appId, snap);
+  }
+  const now = Date.now();
+  const stale = snap.expiresAt <= now;
+  if (stale && !snap.refreshing) {
+    snap.refreshing = true;
+    void asyncRefresh4(rt, appId);
+  }
+  return snap.data.find((p) => p.archetype === opts.archetype);
+}
+var pendingRefreshes4 = /* @__PURE__ */ new Map();
+async function asyncRefresh4(rt, appId) {
+  const promise = doRefresh4(rt, appId);
+  pendingRefreshes4.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes4.get(appId) === promise) {
+      pendingRefreshes4.delete(appId);
+    }
+  }
+}
+async function doRefresh4(rt, appId) {
+  const url = `${rt.endpoint}?app_id=${encodeURIComponent(appId)}`;
+  let snap = snapshots4.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots4.set(appId, snap);
+  }
+  try {
+    const res = await rt.fetchImpl(url, { method: "GET" });
+    if (!res.ok) {
+      throw new Error(`promotions ${res.status}: ${res.statusText}`);
+    }
+    const body = await res.json();
+    if (runtime4 !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToPromotions(body) : [];
+    snap.data = rows;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    snap.refreshing = false;
+  } catch (err) {
+    if (runtime4 !== rt) return;
+    snap.refreshing = false;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    if (!warnedOnce4) {
+      warnedOnce4 = true;
+      (rt.onError ?? defaultOnError4)(err);
+    }
+  }
+}
+function defaultOnError4(err) {
+  console.warn(
+    "[kgauto] promotions fetch failed (promotion boost inactive until next refresh):",
+    err
+  );
+}
+function _testResetPromotions() {
+  runtime4 = void 0;
+  snapshots4.clear();
+  pendingRefreshes4 = /* @__PURE__ */ new Map();
+  warnedOnce4 = false;
+}
+async function _testWaitForPromotionsRefresh() {
+  const pending = Array.from(pendingRefreshes4.values());
+  if (pending.length > 0) await Promise.all(pending);
+}
+
 // src/compile.ts
 var counter = 0;
 function makeHandle() {
@@ -2284,11 +2433,22 @@ function compile(ir, opts = {}) {
     ...toolFiltered.mutations,
     ...compressed.mutations
   ];
+  const activePromotion = getApplicablePromotion({
+    appId: ir.appId,
+    archetype: ir.intent.archetype
+  });
+  const promotion = activePromotion ? {
+    id: activePromotion.id,
+    promotedModel: activePromotion.promotedModel,
+    evalRunId: activePromotion.evalRunId,
+    suppressQualityGate: activePromotion.suppressQualityGate
+  } : void 0;
   const inputTokens = estimateInputTokens(workingIR);
   const scores = passScoreTargets(workingIR, {
     estimatedInputTokens: inputTokens,
     profilesById: resolver,
-    policy: opts.policy
+    policy: opts.policy,
+    promotion
   });
   accumulatedMutations.push(...scores.mutations);
   const target = pickTarget(workingIR, scores.value);
@@ -2620,11 +2780,23 @@ function configureBrain(config) {
   } else {
     configureExclusionFindingsBrain(void 0);
   }
+  const promotionsConsent = config.autoPromote ?? isAutoPromoteEnabledFromEnv();
+  if (promotionsConsent && bq.promotions !== false) {
+    configurePromotionsBrain({
+      endpoint: bq.promotionsEndpoint ?? DEFAULT_PROMOTIONS_ENDPOINT,
+      ttlMs: bq.cacheTtlMs ?? 3e5,
+      fetchImpl: config.fetchImpl ?? fetch,
+      onError: config.onError
+    });
+  } else {
+    configurePromotionsBrain(void 0);
+  }
 }
 function clearBrain() {
   activeConfig = void 0;
   configureBrainQuery(void 0);
   configureExclusionFindingsBrain(void 0);
+  configurePromotionsBrain(void 0);
 }
 var DEAD_LETTER_MAX_ENTRIES = 50;
 var DEAD_LETTER_MAX_ATTEMPTS = 3;
@@ -2741,7 +2913,7 @@ async function flushBrainDeadLetter() {
         if (entry.attempts >= DEAD_LETTER_MAX_ATTEMPTS) {
           const idx = deadLetter.indexOf(entry);
           if (idx !== -1) deadLetter.splice(idx, 1);
-          (config.onError ?? defaultOnError4)(
+          (config.onError ?? defaultOnError5)(
             new Error(
               `brain dead-letter: dropping ${entry.route} payload after ${entry.attempts} attempts \u2014 last error: ${entry.lastError}`
             )
@@ -2891,7 +3063,7 @@ async function record(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("outcomes", config.endpoint, payload, err);
-      (config.onError ?? defaultOnError4)(err);
+      (config.onError ?? defaultOnError5)(err);
       return;
     }
     maybeAutoFlush();
@@ -2919,7 +3091,7 @@ async function record(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("compile_outcome_advisories", config.endpoint, advisoryPayload, err);
-      (config.onError ?? defaultOnError4)(err);
+      (config.onError ?? defaultOnError5)(err);
     }
   };
   if (config.sync) {
@@ -2928,7 +3100,7 @@ async function record(input) {
     void send();
   }
 }
-function defaultOnError4(err) {
+function defaultOnError5(err) {
   console.warn("[kgauto] brain record failed:", err);
 }
 function describeBrainWriteFailure(status, route, body) {
@@ -3080,7 +3252,7 @@ async function recordOutcome(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("compile_outcome_quality", config.endpoint, payload, err);
-      (config.onError ?? defaultOnError4)(err);
+      (config.onError ?? defaultOnError5)(err);
       return { ok: false, reason: "persistence_failed" };
     }
   };
@@ -3151,7 +3323,7 @@ async function recordShadowProbe(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("probe_outcomes", config.endpoint, row, err);
-      (config.onError ?? defaultOnError4)(err);
+      (config.onError ?? defaultOnError5)(err);
     }
   };
   if (config.sync) {
@@ -3206,7 +3378,7 @@ async function recordGoldenIr(input) {
     } catch (err) {
       noteFailure(err);
       pushDeadLetter("golden_irs", config.endpoint, row, err);
-      (config.onError ?? defaultOnError4)(err);
+      (config.onError ?? defaultOnError5)(err);
     }
   };
   if (config.sync) {
@@ -5448,6 +5620,7 @@ export {
   ARCHETYPE_FLOOR_DEFAULT,
   CallError,
   DEFAULT_FINDINGS_ENDPOINT,
+  DEFAULT_PROMOTIONS_ENDPOINT,
   DIALECT_VERSION,
   FamilyResolutionError,
   INTENT_ARCHETYPES,
@@ -5459,6 +5632,8 @@ export {
   PROVIDER_ENV_KEYS,
   RULE_SEQUENTIAL_TOOL_CLIFF,
   TRANSLATOR_FLOOR,
+  _testResetPromotions,
+  _testWaitForPromotionsRefresh,
   allProfiles,
   applyArchetypeConvention,
   applySectionRewrites,
@@ -5478,6 +5653,7 @@ export {
   compile2 as compile,
   compileForAISDKv6,
   configureBrain,
+  configurePromotionsBrain,
   countTokens,
   createBrainForwardRoutes,
   createKeyHealthRoute,
@@ -5489,6 +5665,7 @@ export {
   getActionableAdvisories,
   getAllStarterChains,
   getAllStarterChainsWithGrounding,
+  getApplicablePromotion,
   getArchetypePerfScore,
   getDefaultFallbackChain,
   getDefaultFallbackChainWithGrounding,
@@ -5504,10 +5681,12 @@ export {
   getStarterChainWithGrounding,
   hashShape,
   isArchetype,
+  isAutoPromoteEnabledFromEnv,
   isBrainQueryActiveFor,
   isBrainSync,
   isExclusionFindingsBrainActive,
   isModelReachable,
+  isPromotionsBrainActive,
   isProviderReachable,
   latencyTierOf,
   learningKey,

package/dist/key-health.js

@@ -25,7 +25,7 @@ __export(key_health_exports, {
 module.exports = __toCommonJS(key_health_exports);
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.63";
+var LIBRARY_VERSION = "2.0.0-alpha.64";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/key-health.mjs

@@ -1,6 +1,6 @@
 import {
   createKeyHealthRoute
-} from "./chunk-ZU62HRWK.mjs";
+} from "./chunk-DGPYLFDG.mjs";
 export {
   createKeyHealthRoute
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.63",
+  "version": "2.0.0-alpha.64",
   "description": "Prompt compiler with executable provider knowledge for multi-model AI apps: normalized multi-provider transport with fallback chains, compile-time cliff guards, a curated model registry, and a telemetry flight recorder. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",