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

package/dist/glassbox/index.d.mts

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

package/dist/glassbox/index.d.ts

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

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

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

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

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-BiZKJU41.js';
-import '../ir-Wr5lc8Mi.js';
+import { G as GlassboxEvent } from '../types-DiWBWvxg.js';
+import '../ir-B_XX2LAO.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, 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 { 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 PerAxisMetrics, i as Provider, j as ChainEntry, G as Grounding } from './ir-B9zqlwjH.mjs';
+export { k as CallAttempt, l as CallError, m as ChainWithGrounding, n as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, o as MutationApplied, p as NormalizedTokens, q as OutcomeKind, r as PerAxisMetricsByModel, s as PromptSection, T as ToolCall, t as ToolDefinition } from './ir-B9zqlwjH.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,87 @@ 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 isBrainQueryActiveFor(table: string): boolean;
+interface GetPerAxisMetricsOpts {
+    /** App id to filter on. Required. */
+    appId: string;
+    /** Intent archetype to filter on. Required. */
+    archetype: string;
+    /** Canonical model id to filter on. Required. */
+    model: string;
+    /**
+     * Window in days. Default 30. Only rows with
+     * `created_at > now() - windowDays` are counted.
+     */
+    windowDays?: number;
+    /**
+     * Consumer-declared quality floor (0..1 oracle/approve-rate scale).
+     * When set, the response's `qualityFloorMet` is true/false; when omitted,
+     * `qualityFloorMet` is null (no floor declared, no judgment).
+     */
+    qualityFloor?: number;
+    /** Pluggable fetch (tests inject mock). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /**
+     * PostgREST base endpoint (e.g. `https://kgauto-brain.vercel.app/api`).
+     * When omitted, falls back to the active configureBrainQuery runtime's
+     * endpoint. Returns null when neither is set.
+     */
+    endpoint?: string;
+    /** Bearer token. Forwarded as `Authorization: Bearer ${apiKey}`. */
+    apiKey?: string;
+}
+/**
+ * Call the `get_per_axis_metrics` RPC and return the typed result.
+ *
+ * Returns null when:
+ *   - no endpoint provided AND no configureBrainQuery runtime active
+ *   - RPC returns empty / null / unexpected shape
+ *   - brain unreachable / fetch throws / HTTP error
+ *
+ * Never throws — operator-facing query, must not blow up the caller.
  */
-declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy): BestPracticeAdvisory[];
+declare function getPerAxisMetrics(opts: GetPerAxisMetricsOpts): Promise<PerAxisMetrics | null>;
 
 /**
  * env.ts — provider env-key resolution + reachability predicates.
@@ -870,4 +943,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-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 };
+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, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, 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, getPerAxisMetrics, 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, 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 { 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 PerAxisMetrics, i as Provider, j as ChainEntry, G as Grounding } from './ir-B_XX2LAO.js';
+export { k as CallAttempt, l as CallError, m as ChainWithGrounding, n as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, o as MutationApplied, p as NormalizedTokens, q as OutcomeKind, r as PerAxisMetricsByModel, s as PromptSection, T as ToolCall, t as ToolDefinition } from './ir-B_XX2LAO.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,87 @@ 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 isBrainQueryActiveFor(table: string): boolean;
+interface GetPerAxisMetricsOpts {
+    /** App id to filter on. Required. */
+    appId: string;
+    /** Intent archetype to filter on. Required. */
+    archetype: string;
+    /** Canonical model id to filter on. Required. */
+    model: string;
+    /**
+     * Window in days. Default 30. Only rows with
+     * `created_at > now() - windowDays` are counted.
+     */
+    windowDays?: number;
+    /**
+     * Consumer-declared quality floor (0..1 oracle/approve-rate scale).
+     * When set, the response's `qualityFloorMet` is true/false; when omitted,
+     * `qualityFloorMet` is null (no floor declared, no judgment).
+     */
+    qualityFloor?: number;
+    /** Pluggable fetch (tests inject mock). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /**
+     * PostgREST base endpoint (e.g. `https://kgauto-brain.vercel.app/api`).
+     * When omitted, falls back to the active configureBrainQuery runtime's
+     * endpoint. Returns null when neither is set.
+     */
+    endpoint?: string;
+    /** Bearer token. Forwarded as `Authorization: Bearer ${apiKey}`. */
+    apiKey?: string;
+}
+/**
+ * Call the `get_per_axis_metrics` RPC and return the typed result.
+ *
+ * Returns null when:
+ *   - no endpoint provided AND no configureBrainQuery runtime active
+ *   - RPC returns empty / null / unexpected shape
+ *   - brain unreachable / fetch throws / HTTP error
+ *
+ * Never throws — operator-facing query, must not blow up the caller.
  */
-declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy): BestPracticeAdvisory[];
+declare function getPerAxisMetrics(opts: GetPerAxisMetricsOpts): Promise<PerAxisMetrics | null>;
 
 /**
  * env.ts — provider env-key resolution + reachability predicates.
@@ -870,4 +943,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-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 };
+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, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, 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, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };