@warmdrift/kgauto-compiler 2.0.0-alpha.39 → 2.0.0-alpha.41

package/dist/glassbox/index.d.mts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-f7idIVsm.mjs';
-export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-f7idIVsm.mjs';
-import '../ir-BiZSAVCJ.mjs';
+import { G as GlassboxEvent } from '../types-MkiWUPM8.mjs';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-MkiWUPM8.mjs';
+import '../ir-D_kgJcaV.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox/index.d.ts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-CsFP-H-U.js';
-export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-CsFP-H-U.js';
-import '../ir-CZ9Ng96k.js';
+import { G as GlassboxEvent } from '../types-DigtHnEt.js';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-DigtHnEt.js';
+import '../ir-DYpvUSEw.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/format.d.mts

@@ -1,5 +1,5 @@
-import { T as TraceHealth } from '../types-kzYpX7wB.mjs';
-import '../ir-BiZSAVCJ.mjs';
+import { T as TraceHealth } from '../types-CYY769Ls.mjs';
+import '../ir-D_kgJcaV.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox-routes/format.d.ts

@@ -1,5 +1,5 @@
-import { T as TraceHealth } from '../types-HEl2tS4P.js';
-import '../ir-CZ9Ng96k.js';
+import { T as TraceHealth } from '../types-C8gOJ7hV.js';
+import '../ir-DYpvUSEw.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/index.d.mts

@@ -1,7 +1,7 @@
-import { G as GlassboxEvent } from '../types-f7idIVsm.mjs';
-import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-kzYpX7wB.mjs';
-export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-kzYpX7wB.mjs';
-import '../ir-BiZSAVCJ.mjs';
+import { G as GlassboxEvent } from '../types-MkiWUPM8.mjs';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-CYY769Ls.mjs';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-CYY769Ls.mjs';
+import '../ir-D_kgJcaV.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox-routes/index.d.ts

@@ -1,7 +1,7 @@
-import { G as GlassboxEvent } from '../types-CsFP-H-U.js';
-import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-HEl2tS4P.js';
-export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-HEl2tS4P.js';
-import '../ir-CZ9Ng96k.js';
+import { G as GlassboxEvent } from '../types-DigtHnEt.js';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-C8gOJ7hV.js';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-C8gOJ7hV.js';
+import '../ir-DYpvUSEw.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/react/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { a as TraceDetail } from '../../types-kzYpX7wB.mjs';
-import '../../ir-BiZSAVCJ.mjs';
+import { a as TraceDetail } from '../../types-CYY769Ls.mjs';
+import '../../ir-D_kgJcaV.mjs';
 import '../../dialect.mjs';
 
 /**

package/dist/glassbox-routes/react/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { a as TraceDetail } from '../../types-HEl2tS4P.js';
-import '../../ir-CZ9Ng96k.js';
+import { a as TraceDetail } from '../../types-C8gOJ7hV.js';
+import '../../ir-DYpvUSEw.js';
 import '../../dialect.js';
 
 /**

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, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-BiZSAVCJ.mjs';
-export { m as CallAttempt, n as CallError, o as ChainWithGrounding, p as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, q as MutationApplied, r as NormalizedTokens, s as OutcomeKind, t as PerAxisMetricsByModel, u as PromptSection, v as SectionKind, T as ToolCall, w as ToolDefinition } from './ir-BiZSAVCJ.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, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-D_kgJcaV.mjs';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, r as MutationApplied, s as NormalizedTokens, t as OutcomeKind, u as PerAxisMetricsByModel, v as PromptSection, w as SectionKind, T as ToolCall, x as ToolDefinition } from './ir-D_kgJcaV.mjs';
 import { ModelProfile } from './profiles.mjs';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
@@ -1515,6 +1515,8 @@ interface ModelBrainRow {
     version_added?: string;
     version_removed?: string | null;
     active?: boolean;
+    /** alpha.41 — model-family tag (migration 024 column). */
+    family?: string | null;
 }
 interface ProfileToRowOptions {
     /** e.g. `'2.0.0-alpha.12'` — leave undefined to omit from row. */
@@ -1655,6 +1657,235 @@ interface GetExclusionFindingsOpts {
  */
 declare function getStaleExclusionFindings(opts: GetExclusionFindingsOpts): ExclusionFindingRow[];
 
+/**
+ * Family resolution — alpha.41.
+ *
+ * "I want the latest Opus" → kgauto picks the current+active model in the
+ * `claude-opus` family. Closes the loop where consumer code carries hardcoded
+ * `claude-opus-4-6` literals long after `claude-opus-4-7` ships and goes
+ * current — the s47 trigger (IC's `generate` chain still routing 43 calls to
+ * legacy 4-6 in production).
+ *
+ * Two surfaces:
+ *   - `getRecommendedPrimary({ family, ..., fallback })` — public, sync,
+ *     used at IR-construction time when the consumer wants a literal id back
+ *     (with a fallback floor for cold-start brain).
+ *   - `resolveFamilyEntry({ family, archetype?, appId? })` — internal,
+ *     called from compile() when an IR's `models[]` entry is shaped
+ *     `{ family: string }`. Throws `FamilyResolutionError` on failure.
+ *
+ * Both routes share the same algorithm (locked in the alpha.41 Phase 0
+ * design contract); they differ only in the fallback ergonomics. The
+ * public route accepts a required `fallback: string`; the IR route throws.
+ *
+ * Pure resolution. No network. No async. Brain-registry reads go through
+ * the existing SWR cache (`loadModelsFromBrain` from `models-brain.ts`) —
+ * cold-start returns bundled profiles, which still resolve via the
+ * `deriveFamilyFromModelId` fallback when the brain row's `family` column
+ * is null (G1 contract: graceful pre-migration behavior).
+ *
+ * @see command-center/advisory/kgauto/2026-05-26_alpha-41-model-family-aliases-and-promotion-probe-watcher.md
+ */
+
+interface GetRecommendedPrimaryOptions {
+    /**
+     * Family tag (e.g. `'claude-opus'`, `'gemini-flash'`). See the Phase 0
+     * design contract's family taxonomy table for the locked initial set;
+     * extensible via brain migrations.
+     */
+    family: string;
+    /**
+     * Optional archetype gate. When provided, candidates must clear
+     * {@link ARCHETYPE_FLOOR_DEFAULT} on `archetypePerf[archetype]`. Also used
+     * as the primary sort key (DESC) when multiple candidates qualify.
+     */
+    archetype?: IntentArchetypeName;
+    /**
+     * Optional consumer-app id. When provided, candidates matching a
+     * `stay-excluded` finding for `(appId, archetype)` in the
+     * exclusion-findings cache (alpha.38 substrate) are filtered out.
+     */
+    appId?: string;
+    /**
+     * Consumer-posture tag. `'locked'` short-circuits resolution and returns
+     * the literal `fallback` unconditionally — useful for compliance /
+     * contract / brand-promise flows where the consumer doesn't want kgauto
+     * picking the model on their behalf.
+     */
+    posture?: 'preferred' | 'open' | 'locked';
+    /**
+     * Last-resort literal model id. REQUIRED. Returned when (a) brain
+     * registry is cold / no candidates exist, (b) `posture === 'locked'`,
+     * (c) every candidate was filtered out by archetype / exclusion gates.
+     *
+     * The fallback is NOT validated against the family — kgauto trusts the
+     * consumer to pass a meaningful floor. The contract intent is "even when
+     * everything below is on fire, you still get a model id back."
+     */
+    fallback: string;
+}
+/**
+ * Thrown by `resolveFamilyEntry` (the internal compile-time twin) when a
+ * `{ family: string }` IR entry can't resolve to any current+active model.
+ * Surfaces with the family string + a one-line cause so consumer error
+ * handling can distinguish "you typo'd the family tag" from "brain is cold
+ * and nothing matches."
+ *
+ * The public `getRecommendedPrimary` does NOT throw — it returns
+ * `fallback` instead.
+ */
+declare class FamilyResolutionError extends Error {
+    readonly family: string;
+    readonly cause: string;
+    constructor(family: string, cause: string);
+}
+/**
+ * Deterministic model_id → family inference. Pure function; no brain
+ * lookup. Used as the runtime fallback when a brain row's `family` column
+ * is null (pre-migration 024) and as the canonical mapping that migration
+ * 024's CASE statement mirrors.
+ *
+ * Returns null for unrecognized ids — caller must handle (typically by
+ * skipping the row in family resolution).
+ *
+ * Order matters: more specific patterns first (e.g. `flash-lite` before
+ * `flash`; `pro` before `chat`). The brain-side CASE statement uses the
+ * same priority.
+ */
+declare function deriveFamilyFromModelId(modelId: string): string | null;
+/**
+ * Public sync resolver. Pure (modulo brain snapshot read). Returns the
+ * literal model id of the best candidate, or `fallback` when resolution
+ * yields nothing.
+ */
+declare function getRecommendedPrimary(opts: GetRecommendedPrimaryOptions): string;
+
+/**
+ * promote-ready-brain — alpha.41 substrate.
+ *
+ * Per-tenant SWR cache for the `promote_ready_findings` table populated by
+ * the autonomous `promotion-probe-watcher` (Mode 2). Mirrors
+ * `exclusion-findings-brain.ts` shape byte-for-byte where applicable; this
+ * is the read-side substrate for the compile-time `promote-ready` advisor
+ * rule.
+ *
+ * Architecture (mirror of exclusion-findings-brain):
+ *
+ * - **Sync API surface.** `getPromoteReadyFindings({ appId, archetype,
+ *   family })` returns `PromoteReadyFindingRow[]` immediately. First call
+ *   returns the bundled fallback (empty array); async refresh fires in
+ *   background; subsequent calls within TTL return brain data.
+ *
+ * - **Per-appId snapshot.** Each appId gets its own cache entry. One fetch
+ *   per appId per TTL window. Tests reset between cases via
+ *   `_testResetPromoteReadyFindings()`.
+ *
+ * - **Tolerant.** Brain down / endpoint misconfigured / unexpected shape →
+ *   silent bundled fallback (empty array). Never throws. Warns once per
+ *   process per error to avoid log spam.
+ *
+ * - **Opt-in.** Activation gated on `configurePromoteReadyBrain()` having
+ *   been called with a runtime. The public `configureBrain()` in brain.ts
+ *   wires this up automatically when
+ *   `BrainConfig.brainQuery.findingsPromoteReady !== false`.
+ *
+ * Plus: `markPromoteReadyHandled` — direct PostgREST PATCH against the
+ * brain (no kgauto proxy). Mirrors `markExclusionFindingHandled` shape
+ * byte-for-byte. Idempotent on `resolved_at=is.null` filter.
+ *
+ * Default endpoint:
+ *   `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/promote-ready`
+ *   The route accepts `?app_id=X` and returns a JSON array of findings
+ *   for that app filtered to `resolved_at IS NULL`.
+ */
+
+/**
+ * Shape of one row from the `promote_ready_findings` cache table. Mirrors
+ * the snake_case JSONB returned by the brain endpoint, mapped to camelCase
+ * at the boundary (rowToFinding) so the in-memory shape stays consistent
+ * with the rest of the library.
+ */
+interface PromoteReadyFindingRow {
+    /** Intent archetype the finding applies to. */
+    archetype: string;
+    /** Model family (e.g. 'claude-opus', 'gemini-flash'). */
+    family: string;
+    /** The candidate model that the probe validated. */
+    candidateModel: string;
+    /** The current production model the candidate was compared against. */
+    currentModel: string;
+    /** Sample size of the probe run (typically 10). */
+    sampleN: number;
+    /** Fraction of probes where the judge verdict was 'candidate-better' or
+     *  'tied'. 0.000 to 1.000. */
+    judgePassRate: number;
+    /** Mean judge score across the probe sample. 1.00 to 5.00. */
+    judgeAvgScore: number;
+    /** Signed cost delta as a fraction (negative = candidate is cheaper).
+     *  Null when pricing data was incomplete at probe time. */
+    costDeltaPct: number | null;
+    /** ISO timestamp of detection (when the probe wrote the row). */
+    detectedAt: string;
+}
+/**
+ * Resolution sources supported by alpha.41 `markPromoteReadyHandled`. The
+ * three values map to the three CHECK-constrained resolution values on
+ * `promote_ready_findings.resolution`:
+ *
+ * - `'promoted'`         — consumer migrated to the candidate model. Strong
+ *                          positive signal; the probe was right.
+ * - `'declined'`         — consumer evaluated and chose not to promote.
+ *                          Strong negative signal; revisit only on new
+ *                          family entries or material score swings.
+ * - `'still-evaluating'` — consumer acknowledges the finding but defers
+ *                          the decision. Acknowledges-without-deciding;
+ *                          finding silences this cycle but next probe may
+ *                          re-surface.
+ */
+type PromoteReadyResolution = 'promoted' | 'declined' | 'still-evaluating';
+interface MarkPromoteReadyHandledOptions {
+    /** App id the finding belongs to. Required (RLS scopes writes by this). */
+    appId: string;
+    /** Archetype the finding applies to (e.g. 'hunt', 'classify'). */
+    archetype: IntentArchetypeName | string;
+    /** Model family the finding applies to (e.g. 'claude-opus'). */
+    family: string;
+    /** Resolution semantics — see `PromoteReadyResolution`. */
+    resolution: PromoteReadyResolution;
+    /** Optional free-form note explaining the decision. */
+    resolutionNote?: string;
+    /** Brain Supabase URL base (e.g. `https://<project>.supabase.co`). */
+    brainEndpoint: string;
+    /** Consumer-scoped JWT carrying the `app_id` claim. */
+    brainJwt: string;
+    /** Supabase anon key for the `apikey` header. */
+    brainAnonKey: string;
+    /** Injected fetch for tests. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Mark a probe-validated promote-ready finding as handled. Returns an
+ * `ok/reason` envelope matching `markExclusionFindingHandled`.
+ *
+ * Idempotent: if no row matches the (app_id, archetype, family) tuple
+ * (already resolved, never existed, watcher not yet UPSERTed), PostgREST
+ * returns 200/204 with zero affected rows and we return `{ ok: true }`.
+ *
+ * Reasons surfaced on failure:
+ *   - `app_id_required` / `archetype_required` / `family_required`
+ *   - `resolution_invalid` — not one of the three documented values
+ *   - `brain_auth_misconfig` — 401/403
+ *   - `brain_unavailable` — 5xx
+ *   - `network_error:<message>` — fetch threw
+ *   - `patch_failed:<status>` — anything else non-2xx
+ */
+declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -1701,4 +1932,4 @@ declare function getStaleExclusionFindings(opts: GetExclusionFindingsOpts): Excl
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, deriveFamilyFromModelId, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, 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, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-CZ9Ng96k.js';
-export { m as CallAttempt, n as CallError, o as ChainWithGrounding, p as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, q as MutationApplied, r as NormalizedTokens, s as OutcomeKind, t as PerAxisMetricsByModel, u as PromptSection, v as SectionKind, T as ToolCall, w as ToolDefinition } from './ir-CZ9Ng96k.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, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-DYpvUSEw.js';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, r as MutationApplied, s as NormalizedTokens, t as OutcomeKind, u as PerAxisMetricsByModel, v as PromptSection, w as SectionKind, T as ToolCall, x as ToolDefinition } from './ir-DYpvUSEw.js';
 import { ModelProfile } from './profiles.js';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.js';
 import { IntentArchetypeName } from './dialect.js';
@@ -1515,6 +1515,8 @@ interface ModelBrainRow {
     version_added?: string;
     version_removed?: string | null;
     active?: boolean;
+    /** alpha.41 — model-family tag (migration 024 column). */
+    family?: string | null;
 }
 interface ProfileToRowOptions {
     /** e.g. `'2.0.0-alpha.12'` — leave undefined to omit from row. */
@@ -1655,6 +1657,235 @@ interface GetExclusionFindingsOpts {
  */
 declare function getStaleExclusionFindings(opts: GetExclusionFindingsOpts): ExclusionFindingRow[];
 
+/**
+ * Family resolution — alpha.41.
+ *
+ * "I want the latest Opus" → kgauto picks the current+active model in the
+ * `claude-opus` family. Closes the loop where consumer code carries hardcoded
+ * `claude-opus-4-6` literals long after `claude-opus-4-7` ships and goes
+ * current — the s47 trigger (IC's `generate` chain still routing 43 calls to
+ * legacy 4-6 in production).
+ *
+ * Two surfaces:
+ *   - `getRecommendedPrimary({ family, ..., fallback })` — public, sync,
+ *     used at IR-construction time when the consumer wants a literal id back
+ *     (with a fallback floor for cold-start brain).
+ *   - `resolveFamilyEntry({ family, archetype?, appId? })` — internal,
+ *     called from compile() when an IR's `models[]` entry is shaped
+ *     `{ family: string }`. Throws `FamilyResolutionError` on failure.
+ *
+ * Both routes share the same algorithm (locked in the alpha.41 Phase 0
+ * design contract); they differ only in the fallback ergonomics. The
+ * public route accepts a required `fallback: string`; the IR route throws.
+ *
+ * Pure resolution. No network. No async. Brain-registry reads go through
+ * the existing SWR cache (`loadModelsFromBrain` from `models-brain.ts`) —
+ * cold-start returns bundled profiles, which still resolve via the
+ * `deriveFamilyFromModelId` fallback when the brain row's `family` column
+ * is null (G1 contract: graceful pre-migration behavior).
+ *
+ * @see command-center/advisory/kgauto/2026-05-26_alpha-41-model-family-aliases-and-promotion-probe-watcher.md
+ */
+
+interface GetRecommendedPrimaryOptions {
+    /**
+     * Family tag (e.g. `'claude-opus'`, `'gemini-flash'`). See the Phase 0
+     * design contract's family taxonomy table for the locked initial set;
+     * extensible via brain migrations.
+     */
+    family: string;
+    /**
+     * Optional archetype gate. When provided, candidates must clear
+     * {@link ARCHETYPE_FLOOR_DEFAULT} on `archetypePerf[archetype]`. Also used
+     * as the primary sort key (DESC) when multiple candidates qualify.
+     */
+    archetype?: IntentArchetypeName;
+    /**
+     * Optional consumer-app id. When provided, candidates matching a
+     * `stay-excluded` finding for `(appId, archetype)` in the
+     * exclusion-findings cache (alpha.38 substrate) are filtered out.
+     */
+    appId?: string;
+    /**
+     * Consumer-posture tag. `'locked'` short-circuits resolution and returns
+     * the literal `fallback` unconditionally — useful for compliance /
+     * contract / brand-promise flows where the consumer doesn't want kgauto
+     * picking the model on their behalf.
+     */
+    posture?: 'preferred' | 'open' | 'locked';
+    /**
+     * Last-resort literal model id. REQUIRED. Returned when (a) brain
+     * registry is cold / no candidates exist, (b) `posture === 'locked'`,
+     * (c) every candidate was filtered out by archetype / exclusion gates.
+     *
+     * The fallback is NOT validated against the family — kgauto trusts the
+     * consumer to pass a meaningful floor. The contract intent is "even when
+     * everything below is on fire, you still get a model id back."
+     */
+    fallback: string;
+}
+/**
+ * Thrown by `resolveFamilyEntry` (the internal compile-time twin) when a
+ * `{ family: string }` IR entry can't resolve to any current+active model.
+ * Surfaces with the family string + a one-line cause so consumer error
+ * handling can distinguish "you typo'd the family tag" from "brain is cold
+ * and nothing matches."
+ *
+ * The public `getRecommendedPrimary` does NOT throw — it returns
+ * `fallback` instead.
+ */
+declare class FamilyResolutionError extends Error {
+    readonly family: string;
+    readonly cause: string;
+    constructor(family: string, cause: string);
+}
+/**
+ * Deterministic model_id → family inference. Pure function; no brain
+ * lookup. Used as the runtime fallback when a brain row's `family` column
+ * is null (pre-migration 024) and as the canonical mapping that migration
+ * 024's CASE statement mirrors.
+ *
+ * Returns null for unrecognized ids — caller must handle (typically by
+ * skipping the row in family resolution).
+ *
+ * Order matters: more specific patterns first (e.g. `flash-lite` before
+ * `flash`; `pro` before `chat`). The brain-side CASE statement uses the
+ * same priority.
+ */
+declare function deriveFamilyFromModelId(modelId: string): string | null;
+/**
+ * Public sync resolver. Pure (modulo brain snapshot read). Returns the
+ * literal model id of the best candidate, or `fallback` when resolution
+ * yields nothing.
+ */
+declare function getRecommendedPrimary(opts: GetRecommendedPrimaryOptions): string;
+
+/**
+ * promote-ready-brain — alpha.41 substrate.
+ *
+ * Per-tenant SWR cache for the `promote_ready_findings` table populated by
+ * the autonomous `promotion-probe-watcher` (Mode 2). Mirrors
+ * `exclusion-findings-brain.ts` shape byte-for-byte where applicable; this
+ * is the read-side substrate for the compile-time `promote-ready` advisor
+ * rule.
+ *
+ * Architecture (mirror of exclusion-findings-brain):
+ *
+ * - **Sync API surface.** `getPromoteReadyFindings({ appId, archetype,
+ *   family })` returns `PromoteReadyFindingRow[]` immediately. First call
+ *   returns the bundled fallback (empty array); async refresh fires in
+ *   background; subsequent calls within TTL return brain data.
+ *
+ * - **Per-appId snapshot.** Each appId gets its own cache entry. One fetch
+ *   per appId per TTL window. Tests reset between cases via
+ *   `_testResetPromoteReadyFindings()`.
+ *
+ * - **Tolerant.** Brain down / endpoint misconfigured / unexpected shape →
+ *   silent bundled fallback (empty array). Never throws. Warns once per
+ *   process per error to avoid log spam.
+ *
+ * - **Opt-in.** Activation gated on `configurePromoteReadyBrain()` having
+ *   been called with a runtime. The public `configureBrain()` in brain.ts
+ *   wires this up automatically when
+ *   `BrainConfig.brainQuery.findingsPromoteReady !== false`.
+ *
+ * Plus: `markPromoteReadyHandled` — direct PostgREST PATCH against the
+ * brain (no kgauto proxy). Mirrors `markExclusionFindingHandled` shape
+ * byte-for-byte. Idempotent on `resolved_at=is.null` filter.
+ *
+ * Default endpoint:
+ *   `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/promote-ready`
+ *   The route accepts `?app_id=X` and returns a JSON array of findings
+ *   for that app filtered to `resolved_at IS NULL`.
+ */
+
+/**
+ * Shape of one row from the `promote_ready_findings` cache table. Mirrors
+ * the snake_case JSONB returned by the brain endpoint, mapped to camelCase
+ * at the boundary (rowToFinding) so the in-memory shape stays consistent
+ * with the rest of the library.
+ */
+interface PromoteReadyFindingRow {
+    /** Intent archetype the finding applies to. */
+    archetype: string;
+    /** Model family (e.g. 'claude-opus', 'gemini-flash'). */
+    family: string;
+    /** The candidate model that the probe validated. */
+    candidateModel: string;
+    /** The current production model the candidate was compared against. */
+    currentModel: string;
+    /** Sample size of the probe run (typically 10). */
+    sampleN: number;
+    /** Fraction of probes where the judge verdict was 'candidate-better' or
+     *  'tied'. 0.000 to 1.000. */
+    judgePassRate: number;
+    /** Mean judge score across the probe sample. 1.00 to 5.00. */
+    judgeAvgScore: number;
+    /** Signed cost delta as a fraction (negative = candidate is cheaper).
+     *  Null when pricing data was incomplete at probe time. */
+    costDeltaPct: number | null;
+    /** ISO timestamp of detection (when the probe wrote the row). */
+    detectedAt: string;
+}
+/**
+ * Resolution sources supported by alpha.41 `markPromoteReadyHandled`. The
+ * three values map to the three CHECK-constrained resolution values on
+ * `promote_ready_findings.resolution`:
+ *
+ * - `'promoted'`         — consumer migrated to the candidate model. Strong
+ *                          positive signal; the probe was right.
+ * - `'declined'`         — consumer evaluated and chose not to promote.
+ *                          Strong negative signal; revisit only on new
+ *                          family entries or material score swings.
+ * - `'still-evaluating'` — consumer acknowledges the finding but defers
+ *                          the decision. Acknowledges-without-deciding;
+ *                          finding silences this cycle but next probe may
+ *                          re-surface.
+ */
+type PromoteReadyResolution = 'promoted' | 'declined' | 'still-evaluating';
+interface MarkPromoteReadyHandledOptions {
+    /** App id the finding belongs to. Required (RLS scopes writes by this). */
+    appId: string;
+    /** Archetype the finding applies to (e.g. 'hunt', 'classify'). */
+    archetype: IntentArchetypeName | string;
+    /** Model family the finding applies to (e.g. 'claude-opus'). */
+    family: string;
+    /** Resolution semantics — see `PromoteReadyResolution`. */
+    resolution: PromoteReadyResolution;
+    /** Optional free-form note explaining the decision. */
+    resolutionNote?: string;
+    /** Brain Supabase URL base (e.g. `https://<project>.supabase.co`). */
+    brainEndpoint: string;
+    /** Consumer-scoped JWT carrying the `app_id` claim. */
+    brainJwt: string;
+    /** Supabase anon key for the `apikey` header. */
+    brainAnonKey: string;
+    /** Injected fetch for tests. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Mark a probe-validated promote-ready finding as handled. Returns an
+ * `ok/reason` envelope matching `markExclusionFindingHandled`.
+ *
+ * Idempotent: if no row matches the (app_id, archetype, family) tuple
+ * (already resolved, never existed, watcher not yet UPSERTed), PostgREST
+ * returns 200/204 with zero affected rows and we return `{ ok: true }`.
+ *
+ * Reasons surfaced on failure:
+ *   - `app_id_required` / `archetype_required` / `family_required`
+ *   - `resolution_invalid` — not one of the three documented values
+ *   - `brain_auth_misconfig` — 401/403
+ *   - `brain_unavailable` — 5xx
+ *   - `network_error:<message>` — fetch threw
+ *   - `patch_failed:<status>` — anything else non-2xx
+ */
+declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -1701,4 +1932,4 @@ declare function getStaleExclusionFindings(opts: GetExclusionFindingsOpts): Excl
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, deriveFamilyFromModelId, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };