@warmdrift/kgauto-compiler 2.0.0-alpha.19 → 2.0.0-alpha.21

package/dist/glassbox/index.d.mts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-DWF6mPGg.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-DWF6mPGg.mjs';
-import '../ir-C3P4gDt0.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-xeklorHU.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-xeklorHU.js';
-import '../ir-CFHU3BUT.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-DWF6mPGg.mjs';
-import '../ir-C3P4gDt0.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-xeklorHU.js';
-import '../ir-CFHU3BUT.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, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory, f as Provider } from './ir-C3P4gDt0.mjs';
-export { g as CallAttempt, h as CallError, i as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, j as MutationApplied, k as NormalizedTokens, l as PromptSection, T as ToolCall, m as ToolDefinition } from './ir-C3P4gDt0.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';
@@ -198,7 +198,30 @@ interface OutcomePayload {
     ttft_ms?: number;
     history_cacheable_tokens?: number;
     history_tokens_at_compile?: number;
+    /**
+     * Mirrors `ir.constraints.toolOrchestration` from compile time. NULL when
+     * the consumer hadn't adopted the constraint (pre-alpha.20). Powers
+     * per-mode model-perf queries on the brain (the L-040 parallel-tool
+     * cliff lumps DeepSeek sequential perf with parallel without this).
+     */
+    tool_orchestration?: 'parallel' | 'sequential' | 'either' | null;
 }
+/**
+ * alpha.20 Entry 4: record a quality outcome for a previously-compiled call.
+ *
+ * Fires after the consumer's UX surfaces an approve/reject event (e.g., user
+ * clicks Approve on a hunt result). Joins to the original `compile_outcomes`
+ * row via outcomeId — enables per-(model, archetype) approve-rate measurement
+ * once N ≥ 10 outcomes accumulate.
+ *
+ * Fire-and-forget by default (matches record() semantics). Set BrainConfig.sync
+ * = true for runtime contexts that can't tolerate fire-and-forget teardown
+ * (Vercel Edge, Cloudflare Workers, AWS Lambda) — see L-086.
+ *
+ * Returns OutcomeResult with ok: false + stable reason on persistence
+ * failure. Never throws.
+ */
+declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -475,7 +498,35 @@ interface GetDefaultFallbackChainOpts {
      * legacy unfiltered behavior — preserves alpha.9 callers byte-for-byte.
      */
     reachability?: ReachabilityOpts;
+    /**
+     * alpha.20 E3: consumer-declared tool-orchestration shape. Currently
+     * only affects `archetype: 'hunt'`, where 'sequential' swaps the
+     * parallel-tool-tier-0 chain (Flash → Pro → Sonnet → Haiku) for a
+     * DeepSeek-tier-0 chain (V4-Pro → Flash → Sonnet) — DeepSeek's L-040
+     * parallel-tool cliff doesn't apply when the consumer commits to
+     * single-step orchestration.
+     *
+     * Other archetypes are NOT mode-aware in this release — they ship the
+     * same chain regardless of toolOrchestration. Future versions may
+     * extend mode-awareness to ask/generate/etc. when brain evidence
+     * supports it.
+     *
+     * Default (omitted or 'either'): parallel chain. Back-compat with all
+     * pre-alpha.20 callers.
+     */
+    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.
@@ -487,6 +538,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.
@@ -523,6 +618,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
@@ -530,11 +632,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.
@@ -718,4 +870,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, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getArchetypePerfScore, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, 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 SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, 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, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory, f as Provider } from './ir-CFHU3BUT.js';
-export { g as CallAttempt, h as CallError, i as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, j as MutationApplied, k as NormalizedTokens, l as PromptSection, T as ToolCall, m as ToolDefinition } from './ir-CFHU3BUT.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';
@@ -198,7 +198,30 @@ interface OutcomePayload {
     ttft_ms?: number;
     history_cacheable_tokens?: number;
     history_tokens_at_compile?: number;
+    /**
+     * Mirrors `ir.constraints.toolOrchestration` from compile time. NULL when
+     * the consumer hadn't adopted the constraint (pre-alpha.20). Powers
+     * per-mode model-perf queries on the brain (the L-040 parallel-tool
+     * cliff lumps DeepSeek sequential perf with parallel without this).
+     */
+    tool_orchestration?: 'parallel' | 'sequential' | 'either' | null;
 }
+/**
+ * alpha.20 Entry 4: record a quality outcome for a previously-compiled call.
+ *
+ * Fires after the consumer's UX surfaces an approve/reject event (e.g., user
+ * clicks Approve on a hunt result). Joins to the original `compile_outcomes`
+ * row via outcomeId — enables per-(model, archetype) approve-rate measurement
+ * once N ≥ 10 outcomes accumulate.
+ *
+ * Fire-and-forget by default (matches record() semantics). Set BrainConfig.sync
+ * = true for runtime contexts that can't tolerate fire-and-forget teardown
+ * (Vercel Edge, Cloudflare Workers, AWS Lambda) — see L-086.
+ *
+ * Returns OutcomeResult with ok: false + stable reason on persistence
+ * failure. Never throws.
+ */
+declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -475,7 +498,35 @@ interface GetDefaultFallbackChainOpts {
      * legacy unfiltered behavior — preserves alpha.9 callers byte-for-byte.
      */
     reachability?: ReachabilityOpts;
+    /**
+     * alpha.20 E3: consumer-declared tool-orchestration shape. Currently
+     * only affects `archetype: 'hunt'`, where 'sequential' swaps the
+     * parallel-tool-tier-0 chain (Flash → Pro → Sonnet → Haiku) for a
+     * DeepSeek-tier-0 chain (V4-Pro → Flash → Sonnet) — DeepSeek's L-040
+     * parallel-tool cliff doesn't apply when the consumer commits to
+     * single-step orchestration.
+     *
+     * Other archetypes are NOT mode-aware in this release — they ship the
+     * same chain regardless of toolOrchestration. Future versions may
+     * extend mode-awareness to ask/generate/etc. when brain evidence
+     * supports it.
+     *
+     * Default (omitted or 'either'): parallel chain. Back-compat with all
+     * pre-alpha.20 callers.
+     */
+    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.
@@ -487,6 +538,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.
@@ -523,6 +618,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
@@ -530,11 +632,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.
@@ -718,4 +870,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, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getArchetypePerfScore, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, 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 SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };