@warmdrift/kgauto-compiler 2.0.0-alpha.20 → 2.0.0-alpha.22

package/dist/glassbox/index.d.mts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-BYj1Kl2m.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-BYj1Kl2m.mjs';
-import '../ir-DTMbSnyE.mjs';
+import { G as GlassboxEvent } from '../types-zk238uNL.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-zk238uNL.mjs';
+import '../ir-CruZBtpK.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox/index.d.ts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-CwtaDaWN.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-CwtaDaWN.js';
-import '../ir-CsTU4cMB.js';
+import { G as GlassboxEvent } from '../types-BiZKJU41.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-BiZKJU41.js';
+import '../ir-Wr5lc8Mi.js';
 import '../dialect.js';
 
 /**

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

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-BYj1Kl2m.mjs';
-import '../ir-DTMbSnyE.mjs';
+import { G as GlassboxEvent } from '../types-zk238uNL.mjs';
+import '../ir-CruZBtpK.mjs';
 import '../dialect.mjs';
 
 /**

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

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-CwtaDaWN.js';
-import '../ir-CsTU4cMB.js';
+import { G as GlassboxEvent } from '../types-BiZKJU41.js';
+import '../ir-Wr5lc8Mi.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, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Provider } from './ir-DTMbSnyE.mjs';
-export { i as CallAttempt, j as CallError, k as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, l as MutationApplied, m as NormalizedTokens, n as OutcomeKind, o as PromptSection, T as ToolCall, p as ToolDefinition } from './ir-DTMbSnyE.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, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Provider, i as ChainEntry, G as Grounding } from './ir-CruZBtpK.mjs';
+export { j as CallAttempt, k as CallError, l as ChainWithGrounding, m as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, n as MutationApplied, o as NormalizedTokens, p as OutcomeKind, q as PromptSection, T as ToolCall, r as ToolDefinition } from './ir-CruZBtpK.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';
@@ -326,14 +326,47 @@ declare function countTokens(text: string): number;
 
 /** Subset of CompileResult fields the advisor needs. */
 type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | 'diagnostics'>;
+/**
+ * Optional Phase 2 (alpha.22) context — fallback chain + a profile resolver
+ * for cross-model comparison. Three new rules
+ * (`cost-mismatched-archetype`, `model-stale-evidence`, `tier-down`) consume
+ * this to surface measurement-substrate signals (alpha.20 clean-attribution +
+ * alpha.21 grounding labels) as actionable consumer guidance.
+ *
+ * When `fallbackChain` is empty, rules 1 + 3 stay silent (nothing to
+ * compare against). When `profileResolver` is omitted, the rules degrade
+ * gracefully — they can still inspect the chosen profile but not chain
+ * alternatives. Rule 2 (`model-stale-evidence`) is independent of chain
+ * shape and works on the chosen model alone.
+ */
+interface RunAdvisorPhase2Context {
+    fallbackChain: string[];
+    profileResolver?: (id: string) => ModelProfile | undefined;
+}
 /**
  * Run all phased rules and return collected advisories. Order is fixed so
  * output is stable across runs. The `policy` argument is alpha.9 — the
  * `single-model-array` rule needs to know whether the consumer explicitly
  * declared `posture: 'locked'` (in which case single-model is intentional
  * and shouldn't warn).
+ *
+ * `phase2` is alpha.22 — gives the advisor access to the fallback chain +
+ * a profile resolver so the three new compile-time recommendation rules
+ * (`cost-mismatched-archetype`, `model-stale-evidence`, `tier-down`) can
+ * compare the chosen model against in-chain alternatives. Optional for
+ * backward compatibility with consumers calling `runAdvisor()` directly.
+ */
+declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
+
+/**
+ * alpha.22 — sync introspection: is brain-query mode active for a given
+ * table? Used by the advisor (`model-stale-evidence` rule) to decide
+ * whether a `judgment`-grounded chosen model is a measurement gap worth
+ * surfacing. Returns false on cold start, when configureBrain() was never
+ * called, or when the consumer explicitly opted the table out via
+ * `BrainConfig.brainQuery.<table> = false`.
  */
-declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy): BestPracticeAdvisory[];
+declare function isBrainQueryActiveFor(table: string): boolean;
 
 /**
  * env.ts — provider env-key resolution + reachability predicates.
@@ -516,6 +549,17 @@ interface GetDefaultFallbackChainOpts {
      */
     toolOrchestration?: 'parallel' | 'sequential' | 'either';
 }
+/**
+ * Returns the fallback chain for an archetype as a plain `string[]` of
+ * model ids.
+ *
+ * @deprecated since alpha.21 — prefer
+ * {@link getDefaultFallbackChainWithGrounding}, which returns the same chain
+ * shape with a `grounding` label on every entry (measured / capability-fact /
+ * judgment). The string[] return is preserved indefinitely for back-compat —
+ * no functional change in alpha.21. Existing callers don't need to migrate
+ * unless they want to surface the grounding gap to users.
+ */
 declare function getDefaultFallbackChain(opts: GetDefaultFallbackChainOpts): string[];
 /**
  * Returns a shallow copy of the hand-curated starter chain for an archetype.
@@ -527,6 +571,50 @@ declare function getStarterChain(archetype: IntentArchetypeName): string[];
  * Useful for the `digest.mjs` readout and consumer audits.
  */
 declare function getAllStarterChains(): Record<IntentArchetypeName, string[]>;
+/**
+ * alpha.20 E3 introspection — returns the sequential-mode overlay for an
+ * archetype, or `undefined` when no overlay is registered (the archetype
+ * is mode-agnostic and reuses `STARTER_CHAINS[archetype]`).
+ *
+ * Useful for tests + the `scripts/digest.mjs` operator readout to surface
+ * the mode-aware chains.
+ */
+declare function getSequentialStarterChain(archetype: IntentArchetypeName): string[] | undefined;
+/**
+ * alpha.21 (s78 Entry 1) — returns the fallback chain as `ChainEntry[]`,
+ * with a `grounding` label on every position.
+ *
+ * Same selection logic as {@link getDefaultFallbackChain} (primary anchoring,
+ * blockedModels filter, dedupe, reachability filter, maxDepth cap) — the
+ * only difference is the return shape: each position is a `ChainEntry`
+ * carrying `{ id, grounding, reason?, n? }` instead of a bare string.
+ *
+ * Use this when surfacing the chain to consumers who care WHY each entry
+ * sits where it sits — Glass-Box panels, operator dashboards, eval
+ * scaffolding deciding which entries deserve measurement priority.
+ *
+ * Returns `[]` when filtering empties the chain (same semantics as the
+ * string variant) — consumer decides what to do.
+ */
+declare function getDefaultFallbackChainWithGrounding(opts: GetDefaultFallbackChainOpts): ChainEntry[];
+/**
+ * alpha.21 introspection — returns the grounded starter chain for an
+ * archetype (no primary anchoring, no policy filtering, no maxDepth cap).
+ * Use this when you want the raw, hand-curated grounded chain — every
+ * entry carries a `grounding` label and optional reason/n.
+ */
+declare function getStarterChainWithGrounding(archetype: IntentArchetypeName): ChainEntry[];
+/**
+ * alpha.21 introspection — all grounded starter chains keyed by archetype.
+ * Useful for the `digest.mjs` readout and consumer audits that want to
+ * surface the grounding gap across the entire chain table.
+ */
+declare function getAllStarterChainsWithGrounding(): Record<IntentArchetypeName, ChainEntry[]>;
+/**
+ * alpha.21 introspection — sequential-mode overlay with grounding labels,
+ * or `undefined` when no overlay is registered for the archetype.
+ */
+declare function getSequentialStarterChainWithGrounding(archetype: IntentArchetypeName): ChainEntry[] | undefined;
 
 /**
  * chains-brain — alpha.11 KG-11 adapter.
@@ -563,6 +651,13 @@ declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "s
  */
 
 type ArchetypePerfMap = Map<string, Partial<Record<IntentArchetypeName, number>>>;
+/**
+ * alpha.21: per-(model, archetype) row count map. Same shape as
+ * ArchetypePerfMap but stores brain row counts when the brain backs a
+ * placement. Undefined entries → no row count seen → score is the
+ * hand-curated cold-start prior (grounding='judgment').
+ */
+type ArchetypePerfNMap = Map<string, Partial<Record<IntentArchetypeName, number>>>;
 /**
  * Sync reader for the brain-driven archetypePerf map. Returns bundled
  * profile.archetypePerf data when brain-query is disabled, cold, or
@@ -570,11 +665,61 @@ type ArchetypePerfMap = Map<string, Partial<Record<IntentArchetypeName, number>>
  */
 declare const loadArchetypePerfFromBrain: () => ArchetypePerfMap;
 /**
- * Per-model accessor. Returns 5 (neutral) when no entry is found —
- * consistent with the master plan §3.3 "missing archetypes default to 5"
- * convention documented in profiles.ts ModelProfile.archetypePerf.
+ * alpha.21 — sync reader for the brain row-count map paired with
+ * archetype-perf. Returns empty map (no measured backing) on cold start /
+ * brain-down / unreachable — all `getArchetypePerfScore` calls then
+ * resolve to `grounding: 'judgment'`. When the brain table includes an
+ * `n` column on each row, this map mirrors those counts so consumers can
+ * see how many measurements back each score.
+ */
+declare const loadArchetypePerfNFromBrain: () => ArchetypePerfNMap;
+/**
+ * Threshold above which a brain row count counts as 'measured' grounding.
+ * Below this, the score is treated as 'judgment' (cold-start prior or
+ * not-yet-enough-evidence). Mirrors the alpha.20 `getCleanPerfScore`
+ * `minRows` default — same rule for consistency.
+ */
+declare const MEASURED_GROUNDING_MIN_N = 10;
+/**
+ * alpha.21 — return shape for the extended {@link getArchetypePerfScore}.
+ * Wraps the existing 0..10 score with:
+ *
+ *   - `n`: brain row count backing this score (0 when no measurement).
+ *   - `grounding`: derived label — 'measured' when n >= 10, else 'judgment'.
+ *
+ * The score itself is unchanged from pre-alpha.21 (numeric, 5 = neutral
+ * default). 'capability-fact' is NOT a perf-score grounding — capability
+ * decisions live on chain entries, not on perf scores.
+ */
+interface ArchetypePerfScoreResult {
+    /** 0..10 perf score. 5 = neutral default when no entry exists. */
+    score: number;
+    /**
+     * Brain row count backing this score. 0 when bundled (cold-start prior)
+     * or when the brain row didn't carry an `n` column.
+     */
+    n: number;
+    /**
+     * Provenance — 'measured' when `n >= 10`, else 'judgment'.
+     * Never 'capability-fact' (that label is reserved for chain-entry
+     * inclusion/exclusion decisions).
+     */
+    grounding: Grounding;
+}
+/**
+ * Per-model accessor with grounding (alpha.21). Returns 5 (neutral) when no
+ * entry is found — consistent with the master plan §3.3 "missing archetypes
+ * default to 5" convention documented in profiles.ts
+ * ModelProfile.archetypePerf.
+ *
+ * Backwards-compat note: pre-alpha.21 callers expected `number` here. The
+ * new return shape `{ score, n, grounding }` is a breaking shape change at
+ * the type level, but `.score` carries the legacy value. Callers reading
+ * `.score` field-by-field continue working; callers using the bare number
+ * arithmetically need to switch to `.score`. The migration is single-line
+ * (`const x = getArchetypePerfScore(...)` → `const x = getArchetypePerfScore(...).score`).
  */
-declare function getArchetypePerfScore(modelId: string, archetype: IntentArchetypeName): number;
+declare function getArchetypePerfScore(modelId: string, archetype: IntentArchetypeName): ArchetypePerfScoreResult;
 
 /**
  * pricing-brain — alpha.11 KG-13 adapter.
@@ -758,4 +903,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, type ArchetypePerfMap, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getArchetypePerfScore, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ApiKeys, type AppOracle, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, 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, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Provider } from './ir-CsTU4cMB.js';
-export { i as CallAttempt, j as CallError, k as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, l as MutationApplied, m as NormalizedTokens, n as OutcomeKind, o as PromptSection, T as ToolCall, p as ToolDefinition } from './ir-CsTU4cMB.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, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Provider, i as ChainEntry, G as Grounding } from './ir-Wr5lc8Mi.js';
+export { j as CallAttempt, k as CallError, l as ChainWithGrounding, m as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, n as MutationApplied, o as NormalizedTokens, p as OutcomeKind, q as PromptSection, T as ToolCall, r as ToolDefinition } from './ir-Wr5lc8Mi.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';
@@ -326,14 +326,47 @@ declare function countTokens(text: string): number;
 
 /** Subset of CompileResult fields the advisor needs. */
 type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | 'diagnostics'>;
+/**
+ * Optional Phase 2 (alpha.22) context — fallback chain + a profile resolver
+ * for cross-model comparison. Three new rules
+ * (`cost-mismatched-archetype`, `model-stale-evidence`, `tier-down`) consume
+ * this to surface measurement-substrate signals (alpha.20 clean-attribution +
+ * alpha.21 grounding labels) as actionable consumer guidance.
+ *
+ * When `fallbackChain` is empty, rules 1 + 3 stay silent (nothing to
+ * compare against). When `profileResolver` is omitted, the rules degrade
+ * gracefully — they can still inspect the chosen profile but not chain
+ * alternatives. Rule 2 (`model-stale-evidence`) is independent of chain
+ * shape and works on the chosen model alone.
+ */
+interface RunAdvisorPhase2Context {
+    fallbackChain: string[];
+    profileResolver?: (id: string) => ModelProfile | undefined;
+}
 /**
  * Run all phased rules and return collected advisories. Order is fixed so
  * output is stable across runs. The `policy` argument is alpha.9 — the
  * `single-model-array` rule needs to know whether the consumer explicitly
  * declared `posture: 'locked'` (in which case single-model is intentional
  * and shouldn't warn).
+ *
+ * `phase2` is alpha.22 — gives the advisor access to the fallback chain +
+ * a profile resolver so the three new compile-time recommendation rules
+ * (`cost-mismatched-archetype`, `model-stale-evidence`, `tier-down`) can
+ * compare the chosen model against in-chain alternatives. Optional for
+ * backward compatibility with consumers calling `runAdvisor()` directly.
+ */
+declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
+
+/**
+ * alpha.22 — sync introspection: is brain-query mode active for a given
+ * table? Used by the advisor (`model-stale-evidence` rule) to decide
+ * whether a `judgment`-grounded chosen model is a measurement gap worth
+ * surfacing. Returns false on cold start, when configureBrain() was never
+ * called, or when the consumer explicitly opted the table out via
+ * `BrainConfig.brainQuery.<table> = false`.
  */
-declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy): BestPracticeAdvisory[];
+declare function isBrainQueryActiveFor(table: string): boolean;
 
 /**
  * env.ts — provider env-key resolution + reachability predicates.
@@ -516,6 +549,17 @@ interface GetDefaultFallbackChainOpts {
      */
     toolOrchestration?: 'parallel' | 'sequential' | 'either';
 }
+/**
+ * Returns the fallback chain for an archetype as a plain `string[]` of
+ * model ids.
+ *
+ * @deprecated since alpha.21 — prefer
+ * {@link getDefaultFallbackChainWithGrounding}, which returns the same chain
+ * shape with a `grounding` label on every entry (measured / capability-fact /
+ * judgment). The string[] return is preserved indefinitely for back-compat —
+ * no functional change in alpha.21. Existing callers don't need to migrate
+ * unless they want to surface the grounding gap to users.
+ */
 declare function getDefaultFallbackChain(opts: GetDefaultFallbackChainOpts): string[];
 /**
  * Returns a shallow copy of the hand-curated starter chain for an archetype.
@@ -527,6 +571,50 @@ declare function getStarterChain(archetype: IntentArchetypeName): string[];
  * Useful for the `digest.mjs` readout and consumer audits.
  */
 declare function getAllStarterChains(): Record<IntentArchetypeName, string[]>;
+/**
+ * alpha.20 E3 introspection — returns the sequential-mode overlay for an
+ * archetype, or `undefined` when no overlay is registered (the archetype
+ * is mode-agnostic and reuses `STARTER_CHAINS[archetype]`).
+ *
+ * Useful for tests + the `scripts/digest.mjs` operator readout to surface
+ * the mode-aware chains.
+ */
+declare function getSequentialStarterChain(archetype: IntentArchetypeName): string[] | undefined;
+/**
+ * alpha.21 (s78 Entry 1) — returns the fallback chain as `ChainEntry[]`,
+ * with a `grounding` label on every position.
+ *
+ * Same selection logic as {@link getDefaultFallbackChain} (primary anchoring,
+ * blockedModels filter, dedupe, reachability filter, maxDepth cap) — the
+ * only difference is the return shape: each position is a `ChainEntry`
+ * carrying `{ id, grounding, reason?, n? }` instead of a bare string.
+ *
+ * Use this when surfacing the chain to consumers who care WHY each entry
+ * sits where it sits — Glass-Box panels, operator dashboards, eval
+ * scaffolding deciding which entries deserve measurement priority.
+ *
+ * Returns `[]` when filtering empties the chain (same semantics as the
+ * string variant) — consumer decides what to do.
+ */
+declare function getDefaultFallbackChainWithGrounding(opts: GetDefaultFallbackChainOpts): ChainEntry[];
+/**
+ * alpha.21 introspection — returns the grounded starter chain for an
+ * archetype (no primary anchoring, no policy filtering, no maxDepth cap).
+ * Use this when you want the raw, hand-curated grounded chain — every
+ * entry carries a `grounding` label and optional reason/n.
+ */
+declare function getStarterChainWithGrounding(archetype: IntentArchetypeName): ChainEntry[];
+/**
+ * alpha.21 introspection — all grounded starter chains keyed by archetype.
+ * Useful for the `digest.mjs` readout and consumer audits that want to
+ * surface the grounding gap across the entire chain table.
+ */
+declare function getAllStarterChainsWithGrounding(): Record<IntentArchetypeName, ChainEntry[]>;
+/**
+ * alpha.21 introspection — sequential-mode overlay with grounding labels,
+ * or `undefined` when no overlay is registered for the archetype.
+ */
+declare function getSequentialStarterChainWithGrounding(archetype: IntentArchetypeName): ChainEntry[] | undefined;
 
 /**
  * chains-brain — alpha.11 KG-11 adapter.
@@ -563,6 +651,13 @@ declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "s
  */
 
 type ArchetypePerfMap = Map<string, Partial<Record<IntentArchetypeName, number>>>;
+/**
+ * alpha.21: per-(model, archetype) row count map. Same shape as
+ * ArchetypePerfMap but stores brain row counts when the brain backs a
+ * placement. Undefined entries → no row count seen → score is the
+ * hand-curated cold-start prior (grounding='judgment').
+ */
+type ArchetypePerfNMap = Map<string, Partial<Record<IntentArchetypeName, number>>>;
 /**
  * Sync reader for the brain-driven archetypePerf map. Returns bundled
  * profile.archetypePerf data when brain-query is disabled, cold, or
@@ -570,11 +665,61 @@ type ArchetypePerfMap = Map<string, Partial<Record<IntentArchetypeName, number>>
  */
 declare const loadArchetypePerfFromBrain: () => ArchetypePerfMap;
 /**
- * Per-model accessor. Returns 5 (neutral) when no entry is found —
- * consistent with the master plan §3.3 "missing archetypes default to 5"
- * convention documented in profiles.ts ModelProfile.archetypePerf.
+ * alpha.21 — sync reader for the brain row-count map paired with
+ * archetype-perf. Returns empty map (no measured backing) on cold start /
+ * brain-down / unreachable — all `getArchetypePerfScore` calls then
+ * resolve to `grounding: 'judgment'`. When the brain table includes an
+ * `n` column on each row, this map mirrors those counts so consumers can
+ * see how many measurements back each score.
+ */
+declare const loadArchetypePerfNFromBrain: () => ArchetypePerfNMap;
+/**
+ * Threshold above which a brain row count counts as 'measured' grounding.
+ * Below this, the score is treated as 'judgment' (cold-start prior or
+ * not-yet-enough-evidence). Mirrors the alpha.20 `getCleanPerfScore`
+ * `minRows` default — same rule for consistency.
+ */
+declare const MEASURED_GROUNDING_MIN_N = 10;
+/**
+ * alpha.21 — return shape for the extended {@link getArchetypePerfScore}.
+ * Wraps the existing 0..10 score with:
+ *
+ *   - `n`: brain row count backing this score (0 when no measurement).
+ *   - `grounding`: derived label — 'measured' when n >= 10, else 'judgment'.
+ *
+ * The score itself is unchanged from pre-alpha.21 (numeric, 5 = neutral
+ * default). 'capability-fact' is NOT a perf-score grounding — capability
+ * decisions live on chain entries, not on perf scores.
+ */
+interface ArchetypePerfScoreResult {
+    /** 0..10 perf score. 5 = neutral default when no entry exists. */
+    score: number;
+    /**
+     * Brain row count backing this score. 0 when bundled (cold-start prior)
+     * or when the brain row didn't carry an `n` column.
+     */
+    n: number;
+    /**
+     * Provenance — 'measured' when `n >= 10`, else 'judgment'.
+     * Never 'capability-fact' (that label is reserved for chain-entry
+     * inclusion/exclusion decisions).
+     */
+    grounding: Grounding;
+}
+/**
+ * Per-model accessor with grounding (alpha.21). Returns 5 (neutral) when no
+ * entry is found — consistent with the master plan §3.3 "missing archetypes
+ * default to 5" convention documented in profiles.ts
+ * ModelProfile.archetypePerf.
+ *
+ * Backwards-compat note: pre-alpha.21 callers expected `number` here. The
+ * new return shape `{ score, n, grounding }` is a breaking shape change at
+ * the type level, but `.score` carries the legacy value. Callers reading
+ * `.score` field-by-field continue working; callers using the bare number
+ * arithmetically need to switch to `.score`. The migration is single-line
+ * (`const x = getArchetypePerfScore(...)` → `const x = getArchetypePerfScore(...).score`).
  */
-declare function getArchetypePerfScore(modelId: string, archetype: IntentArchetypeName): number;
+declare function getArchetypePerfScore(modelId: string, archetype: IntentArchetypeName): ArchetypePerfScoreResult;
 
 /**
  * pricing-brain — alpha.11 KG-13 adapter.
@@ -758,4 +903,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, type ArchetypePerfMap, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getArchetypePerfScore, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ApiKeys, type AppOracle, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };