@warmdrift/kgauto-compiler 2.0.0-alpha.47 → 2.0.0-alpha.49

package/README.md

@@ -89,6 +89,37 @@ await record({
 });
 ```
 
+### `probeShadow()` — measure a swap candidate from an AI-SDK route (alpha.48)
+
+`call()` runs a full-IR shadow probe internally (`shadowProbe` option). AI-SDK consumers who drive `streamText()` themselves never call `call()`, so they reach the same probe via the standalone `probeShadow()` export — fire it from `onFinish`, passing the served leg you already have, wrapped in `waitUntil()`/`after()` so it never blocks the response.
+
+```ts
+import { probeShadow, configureBrain } from '@warmdrift/kgauto-compiler';
+import { after } from 'next/server'; // or the platform's waitUntil()
+
+configureBrain({ endpoint: 'https://your-app.com/api/kgauto/v2', apiKey: '...' });
+
+const t0 = Date.now();
+const result = streamText({
+  model, system, messages,
+  onFinish: ({ text, usage }) => {
+    after(() => probeShadow(ir, {
+      served: {
+        model: servedModelId,
+        responseText: text,
+        tokensIn: usage.promptTokens,
+        tokensOut: usage.completionTokens,
+        latencyMs: Date.now() - t0,
+      },
+      candidates: ['deepseek-v4-pro'], // what you'd consider swapping to
+      sampleRate: 0.05,                // pin 1 for a dogfood window
+    }));
+  },
+});
+```
+
+kgauto runs each candidate on the **same IR** and persists a `probe_outcomes` row (`replay_source='inline-full-ir'`, `prompt_fidelity=1.0`, both latency legs). Phase 1 is `judge:'off'` — rows accumulate for an offline verdict rollup; inline Opus judging is Phase 2. Fire-and-forget: never throws into your `onFinish`.
+
 ## Structured advisories API (alpha.29+)
 
 kgauto's compile-time advisories (`caching-off-on-claude`, `tool-bloat`,

package/dist/index.d.mts

@@ -102,6 +102,70 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
  * exhausted without success.
  */
 declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
+/** Served-side result the AI-SDK consumer already holds from streamText. */
+interface ProbeShadowServed {
+    /** Model id that actually served the user (becomes `current_model` on the row). */
+    model: string;
+    /** The served response text (stored as a preview; never the prompt). */
+    responseText: string;
+    /** Served prompt tokens (AI SDK `usage.promptTokens`). */
+    tokensIn: number;
+    /** Served completion tokens (AI SDK `usage.completionTokens`). */
+    tokensOut: number;
+    /** The user's actual wait in ms (alpha.46 served-latency axis). */
+    latencyMs: number;
+}
+/** Options for the standalone {@link probeShadow} export. */
+interface ProbeShadowOptions {
+    /** The served leg the consumer supplies; kgauto runs the candidate leg. */
+    served: ProbeShadowServed;
+    /** Model id(s)/family alias(es) to shadow-test against the served model. */
+    candidates: string | string[];
+    /** Probability [0,1] a given call fires a probe. Default 0.05; pin 1 for dogfood. */
+    sampleRate?: number;
+    /** Phase 1 = 'off' (offline rollup). 'opus' inline judge is Phase 2. Default 'off'. */
+    judge?: 'off' | 'opus';
+    /** Override API keys (defaults: process.env). Gates candidate reachability. */
+    apiKeys?: ApiKeys;
+    /** Override fetch (for tests / custom transport). */
+    fetchImpl?: typeof fetch;
+    /** Provider-specific request fields shallow-merged into the candidate request. */
+    providerOverrides?: ProviderOverrides;
+    /** Forwarded to compile() for the candidate run (match the served-side compile). */
+    policy?: CompilePolicy;
+    toolRelevanceThreshold?: number;
+    compressHistoryAfter?: number;
+}
+/**
+ * s54 — standalone full-IR shadow probe for AI-SDK consumers (tt-intel hunt, IC
+ * chat) that own their own streamText round-trip and never call call(). Fire it
+ * from the streamText `onFinish` callback, wrapped in the platform's
+ * `waitUntil()` / `after()`, so it runs after the response is flushed — no
+ * blocking, no `sync:true`, no teardown race (cleaner than call()'s in-process
+ * fire-and-forget for Edge runtimes; L-086).
+ *
+ * Runs the SAME candidate loop as the call()-inline probe ({@link
+ * runProbeCandidates}): same gates (sample, self-skip, G4 judge-self,
+ * reachability, G6), same fidelity=1.0 full-IR rows, same alpha.46 latency
+ * capture. The consumer supplies the served leg it already has; kgauto runs the
+ * candidate(s) and writes the `probe_outcomes` row.
+ *
+ * Requires `configureBrain()` to have been called (same as call()).
+ * Fire-and-forget: never throws into the caller.
+ *
+ * @example
+ * const result = streamText({ model, system, messages,
+ *   onFinish: ({ text, usage }) => {
+ *     after(() => probeShadow(ir, {
+ *       served: { model: servedModelId, responseText: text,
+ *                 tokensIn: usage.promptTokens, tokensOut: usage.completionTokens,
+ *                 latencyMs: Date.now() - t0 },
+ *       candidates: ['deepseek-v4-pro'], sampleRate: 0.05,
+ *     }));
+ *   },
+ * });
+ */
+declare function probeShadow(ir: PromptIR, opts: ProbeShadowOptions): Promise<void>;
 
 /**
  * alpha.33 — AI-SDK streamText helpers.
@@ -1780,6 +1844,10 @@ interface ModelBrainRow {
     active?: boolean;
     /** alpha.41 — model-family tag (migration 024 column). */
     family?: string | null;
+    /** alpha.49 — explicit latency bucket (migration 028 column). */
+    latency_tier?: string | null;
+    /** alpha.49 — per-archetype prompt-shape conventions (migration 028 column). */
+    archetype_conventions?: ArchetypeConvention[] | null;
 }
 interface ProfileToRowOptions {
     /** e.g. `'2.0.0-alpha.12'` — leave undefined to omit from row. */
@@ -2195,4 +2263,4 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, 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, PRODUCER_OWNED_RULE_CODES, 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 ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, 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, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

package/dist/index.d.ts

@@ -102,6 +102,70 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
  * exhausted without success.
  */
 declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
+/** Served-side result the AI-SDK consumer already holds from streamText. */
+interface ProbeShadowServed {
+    /** Model id that actually served the user (becomes `current_model` on the row). */
+    model: string;
+    /** The served response text (stored as a preview; never the prompt). */
+    responseText: string;
+    /** Served prompt tokens (AI SDK `usage.promptTokens`). */
+    tokensIn: number;
+    /** Served completion tokens (AI SDK `usage.completionTokens`). */
+    tokensOut: number;
+    /** The user's actual wait in ms (alpha.46 served-latency axis). */
+    latencyMs: number;
+}
+/** Options for the standalone {@link probeShadow} export. */
+interface ProbeShadowOptions {
+    /** The served leg the consumer supplies; kgauto runs the candidate leg. */
+    served: ProbeShadowServed;
+    /** Model id(s)/family alias(es) to shadow-test against the served model. */
+    candidates: string | string[];
+    /** Probability [0,1] a given call fires a probe. Default 0.05; pin 1 for dogfood. */
+    sampleRate?: number;
+    /** Phase 1 = 'off' (offline rollup). 'opus' inline judge is Phase 2. Default 'off'. */
+    judge?: 'off' | 'opus';
+    /** Override API keys (defaults: process.env). Gates candidate reachability. */
+    apiKeys?: ApiKeys;
+    /** Override fetch (for tests / custom transport). */
+    fetchImpl?: typeof fetch;
+    /** Provider-specific request fields shallow-merged into the candidate request. */
+    providerOverrides?: ProviderOverrides;
+    /** Forwarded to compile() for the candidate run (match the served-side compile). */
+    policy?: CompilePolicy;
+    toolRelevanceThreshold?: number;
+    compressHistoryAfter?: number;
+}
+/**
+ * s54 — standalone full-IR shadow probe for AI-SDK consumers (tt-intel hunt, IC
+ * chat) that own their own streamText round-trip and never call call(). Fire it
+ * from the streamText `onFinish` callback, wrapped in the platform's
+ * `waitUntil()` / `after()`, so it runs after the response is flushed — no
+ * blocking, no `sync:true`, no teardown race (cleaner than call()'s in-process
+ * fire-and-forget for Edge runtimes; L-086).
+ *
+ * Runs the SAME candidate loop as the call()-inline probe ({@link
+ * runProbeCandidates}): same gates (sample, self-skip, G4 judge-self,
+ * reachability, G6), same fidelity=1.0 full-IR rows, same alpha.46 latency
+ * capture. The consumer supplies the served leg it already has; kgauto runs the
+ * candidate(s) and writes the `probe_outcomes` row.
+ *
+ * Requires `configureBrain()` to have been called (same as call()).
+ * Fire-and-forget: never throws into the caller.
+ *
+ * @example
+ * const result = streamText({ model, system, messages,
+ *   onFinish: ({ text, usage }) => {
+ *     after(() => probeShadow(ir, {
+ *       served: { model: servedModelId, responseText: text,
+ *                 tokensIn: usage.promptTokens, tokensOut: usage.completionTokens,
+ *                 latencyMs: Date.now() - t0 },
+ *       candidates: ['deepseek-v4-pro'], sampleRate: 0.05,
+ *     }));
+ *   },
+ * });
+ */
+declare function probeShadow(ir: PromptIR, opts: ProbeShadowOptions): Promise<void>;
 
 /**
  * alpha.33 — AI-SDK streamText helpers.
@@ -1780,6 +1844,10 @@ interface ModelBrainRow {
     active?: boolean;
     /** alpha.41 — model-family tag (migration 024 column). */
     family?: string | null;
+    /** alpha.49 — explicit latency bucket (migration 028 column). */
+    latency_tier?: string | null;
+    /** alpha.49 — per-archetype prompt-shape conventions (migration 028 column). */
+    archetype_conventions?: ArchetypeConvention[] | null;
 }
 interface ProfileToRowOptions {
     /** e.g. `'2.0.0-alpha.12'` — leave undefined to omit from row. */
@@ -2195,4 +2263,4 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, 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, PRODUCER_OWNED_RULE_CODES, 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 ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, 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, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

package/dist/index.js

@@ -88,6 +88,7 @@ __export(index_exports, {
   markAdvisoryResolved: () => markAdvisoryResolved,
   markExclusionFindingHandled: () => markExclusionFindingHandled,
   markPromoteReadyHandled: () => markPromoteReadyHandled,
+  probeShadow: () => probeShadow,
   profileToRow: () => profileToRow,
   profilesByProvider: () => profilesByProvider,
   readBrainReadEnv: () => readBrainReadEnv,
@@ -1586,6 +1587,9 @@ function rowToProfile(row) {
     if (row.lowering !== void 0 && row.lowering !== null && (typeof row.lowering !== "object" || Array.isArray(row.lowering))) {
       return null;
     }
+    if (row.archetype_conventions !== void 0 && row.archetype_conventions !== null && !Array.isArray(row.archetype_conventions)) {
+      return null;
+    }
     return {
       id: row.model_id,
       provider: row.provider,
@@ -1612,12 +1616,21 @@ function rowToProfile(row) {
       // resolution time (see family-resolution.ts, G1).
       family: row.family ?? void 0,
       versionAdded: row.version_added ?? void 0,
-      active: row.active ?? void 0
+      active: row.active ?? void 0,
+      // alpha.49 — executable-knowledge fields (migration 028). Invalid
+      // latency_tier → undefined (latencyTierOf derives from tags; not
+      // safety-critical). archetype_conventions already array-validated above.
+      latencyTier: normalizeLatencyTier(row.latency_tier),
+      archetypeConventions: row.archetype_conventions ?? void 0
     };
   } catch {
     return null;
   }
 }
+var VALID_LATENCY_TIERS = /* @__PURE__ */ new Set(["fast", "medium", "slow"]);
+function normalizeLatencyTier(v) {
+  return typeof v === "string" && VALID_LATENCY_TIERS.has(v) ? v : void 0;
+}
 function profileToRow(profile, opts = {}) {
   const row = {
     model_id: profile.id,
@@ -1643,7 +1656,12 @@ function profileToRow(profile, opts = {}) {
     // alpha.41 — round-trip family + version_added when present on profile.
     // version_added is operator-controlled via opts; profile-side value is
     // used only when opts didn't override.
-    family: profile.family ?? null
+    family: profile.family ?? null,
+    // alpha.49 — round-trip the executable-knowledge fields (migration 028)
+    // so a reseed from bundled profiles makes the latency lever + schema
+    // conventions live warm. Closes the silently-dropped-field gap.
+    latency_tier: profile.latencyTier ?? null,
+    archetype_conventions: profile.archetypeConventions ?? null
   };
   if (opts.verifiedAgainstDocs !== void 0) {
     row.verified_against_docs = opts.verifiedAgainstDocs;
@@ -2388,6 +2406,17 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
 }
 var LATENCY_OVERAGE_WEIGHT = 0.6;
 var LATENCY_PENALTY_CAP = 1;
+var QUALITY_GATE_PENALTY = 4;
+function effectiveConventions(profile) {
+  const own = profile.archetypeConventions ?? [];
+  if (own.length > 0) return own;
+  const family = profile.family ?? deriveFamilyFromModelId(profile.id);
+  if (!family) return [];
+  const repId = familyRepId(family);
+  if (!repId || repId === profile.id) return [];
+  const rep = tryGetProfile(repId);
+  return rep?.archetypeConventions ?? [];
+}
 function passScoreTargets(ir, opts) {
   const constraints = ir.constraints ?? {};
   const policy = opts.policy ?? {};
@@ -2452,7 +2481,14 @@ function passScoreTargets(ir, opts) {
         latencyPenalty = Math.min(LATENCY_OVERAGE_WEIGHT * overage, LATENCY_PENALTY_CAP);
       }
     }
-    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty;
+    let qualityGatePenalty = 0;
+    if (constraints.structuredOutput) {
+      const schemaWeak = effectiveConventions(profile).some(
+        (c) => c.archetype === ir.intent.archetype && c.structuredOutputHint === "avoid"
+      );
+      if (schemaWeak) qualityGatePenalty = QUALITY_GATE_PENALTY;
+    }
+    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty - qualityGatePenalty;
     scores.push({
       modelId,
       estimatedCostUsd,
@@ -2494,6 +2530,14 @@ function passScoreTargets(ir, opts) {
         description: `Model ${modelId} rank down ${latencyPenalty.toFixed(2)} \u2014 latency tier '${tier}' (~${LATENCY_TIER_MS[tier]}ms) exceeds constraints.maxLatencyMs (${maxLatencyMs}ms)`
       });
     }
+    if (qualityGatePenalty > 0) {
+      policyMutations.push({
+        id: `quality-gate-structured-${modelId}`,
+        source: "quality_gate",
+        passName: "score_targets",
+        description: `Model ${modelId} gated below the quality floor for archetype '${ir.intent.archetype}' \u2014 declared structuredOutput + kgauto convention flags it schema-weak for this contract (structuredOutputHint:'avoid'). Down-ranked out of leadership; retained as graceful fallback only.`
+      });
+    }
   }
   return { value: scores, mutations: policyMutations };
 }
@@ -6157,16 +6201,15 @@ function hashForProbe(s) {
   for (let i = 0; i < s.length; i++) h = (h << 5) - h + s.charCodeAt(i) | 0;
   return `h${(h >>> 0).toString(16)}`;
 }
-async function runShadowProbe(args) {
+async function runProbeCandidates(args) {
   try {
-    const cfg = args.opts.shadowProbe;
-    if (!shouldSampleProbe(cfg.sampleRate ?? 0.05)) return;
-    const candidates = normalizeProbeCandidates(cfg.candidates);
+    if (!shouldSampleProbe(args.cfg.sampleRate ?? 0.05)) return;
+    const candidates = normalizeProbeCandidates(args.cfg.candidates);
     const promptHash = hashForProbe(args.ir.currentTurn?.content ?? "");
     for (const candidate of candidates) {
       if (candidate === args.servedModel) continue;
       if (deriveFamilyFromModelId(candidate) === "claude-opus") continue;
-      if (!isModelReachable(candidate, { apiKeys: args.opts.apiKeys })) continue;
+      if (!isModelReachable(candidate, { apiKeys: args.exec.apiKeys })) continue;
       try {
         const candCompile = compileAndRegister(
           {
@@ -6174,13 +6217,13 @@ async function runShadowProbe(args) {
             models: args.ir.models.includes(candidate) ? args.ir.models : [candidate, ...args.ir.models],
             constraints: { ...args.ir.constraints ?? {}, forceModel: candidate }
           },
-          args.opts
+          args.exec
         );
         const candStart = Date.now();
         const exec = await execute(candCompile.request, {
-          apiKeys: args.opts.apiKeys,
-          fetchImpl: args.opts.fetchImpl,
-          providerOverrides: args.opts.providerOverrides
+          apiKeys: args.exec.apiKeys,
+          fetchImpl: args.exec.fetchImpl,
+          providerOverrides: args.exec.providerOverrides
         });
         const candidateLatencyMs = Date.now() - candStart;
         if (!exec.ok) continue;
@@ -6209,6 +6252,54 @@ async function runShadowProbe(args) {
   } catch {
   }
 }
+async function runShadowProbe(args) {
+  const cfg = args.opts.shadowProbe;
+  if (!cfg) return;
+  await runProbeCandidates({
+    ir: args.ir,
+    cfg,
+    servedModel: args.servedModel,
+    servedResponse: args.servedResponse,
+    servedLatencyMs: args.servedLatencyMs,
+    // CallOptions is a structural superset of ProbeExecOpts.
+    exec: args.opts
+  });
+}
+async function probeShadow(ir, opts) {
+  try {
+    const servedResponse = {
+      text: opts.served.responseText,
+      structuredOutput: null,
+      toolCalls: [],
+      tokens: {
+        input: opts.served.tokensIn,
+        output: opts.served.tokensOut,
+        total: opts.served.tokensIn + opts.served.tokensOut
+      },
+      raw: null
+    };
+    await runProbeCandidates({
+      ir,
+      cfg: {
+        candidates: opts.candidates,
+        sampleRate: opts.sampleRate,
+        judge: opts.judge ?? "off"
+      },
+      servedModel: opts.served.model,
+      servedResponse,
+      servedLatencyMs: opts.served.latencyMs,
+      exec: {
+        policy: opts.policy,
+        toolRelevanceThreshold: opts.toolRelevanceThreshold,
+        compressHistoryAfter: opts.compressHistoryAfter,
+        apiKeys: opts.apiKeys,
+        fetchImpl: opts.fetchImpl,
+        providerOverrides: opts.providerOverrides
+      }
+    });
+  } catch {
+  }
+}
 function validateStructuredContract(exec, ir) {
   if (!ir.constraints?.structuredOutput) {
     return { ok: true, response: exec.response };
@@ -6795,6 +6886,7 @@ function compile2(ir, opts) {
   markAdvisoryResolved,
   markExclusionFindingHandled,
   markPromoteReadyHandled,
+  probeShadow,
   profileToRow,
   profilesByProvider,
   readBrainReadEnv,

package/dist/index.mjs

@@ -76,6 +76,9 @@ function rowToProfile(row) {
     if (row.lowering !== void 0 && row.lowering !== null && (typeof row.lowering !== "object" || Array.isArray(row.lowering))) {
       return null;
     }
+    if (row.archetype_conventions !== void 0 && row.archetype_conventions !== null && !Array.isArray(row.archetype_conventions)) {
+      return null;
+    }
     return {
       id: row.model_id,
       provider: row.provider,
@@ -102,12 +105,21 @@ function rowToProfile(row) {
       // resolution time (see family-resolution.ts, G1).
       family: row.family ?? void 0,
       versionAdded: row.version_added ?? void 0,
-      active: row.active ?? void 0
+      active: row.active ?? void 0,
+      // alpha.49 — executable-knowledge fields (migration 028). Invalid
+      // latency_tier → undefined (latencyTierOf derives from tags; not
+      // safety-critical). archetype_conventions already array-validated above.
+      latencyTier: normalizeLatencyTier(row.latency_tier),
+      archetypeConventions: row.archetype_conventions ?? void 0
     };
   } catch {
     return null;
   }
 }
+var VALID_LATENCY_TIERS = /* @__PURE__ */ new Set(["fast", "medium", "slow"]);
+function normalizeLatencyTier(v) {
+  return typeof v === "string" && VALID_LATENCY_TIERS.has(v) ? v : void 0;
+}
 function profileToRow(profile, opts = {}) {
   const row = {
     model_id: profile.id,
@@ -133,7 +145,12 @@ function profileToRow(profile, opts = {}) {
     // alpha.41 — round-trip family + version_added when present on profile.
     // version_added is operator-controlled via opts; profile-side value is
     // used only when opts didn't override.
-    family: profile.family ?? null
+    family: profile.family ?? null,
+    // alpha.49 — round-trip the executable-knowledge fields (migration 028)
+    // so a reseed from bundled profiles makes the latency lever + schema
+    // conventions live warm. Closes the silently-dropped-field gap.
+    latency_tier: profile.latencyTier ?? null,
+    archetype_conventions: profile.archetypeConventions ?? null
   };
   if (opts.verifiedAgainstDocs !== void 0) {
     row.verified_against_docs = opts.verifiedAgainstDocs;
@@ -714,6 +731,17 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
 }
 var LATENCY_OVERAGE_WEIGHT = 0.6;
 var LATENCY_PENALTY_CAP = 1;
+var QUALITY_GATE_PENALTY = 4;
+function effectiveConventions(profile) {
+  const own = profile.archetypeConventions ?? [];
+  if (own.length > 0) return own;
+  const family = profile.family ?? deriveFamilyFromModelId(profile.id);
+  if (!family) return [];
+  const repId = familyRepId(family);
+  if (!repId || repId === profile.id) return [];
+  const rep = tryGetProfile(repId);
+  return rep?.archetypeConventions ?? [];
+}
 function passScoreTargets(ir, opts) {
   const constraints = ir.constraints ?? {};
   const policy = opts.policy ?? {};
@@ -778,7 +806,14 @@ function passScoreTargets(ir, opts) {
         latencyPenalty = Math.min(LATENCY_OVERAGE_WEIGHT * overage, LATENCY_PENALTY_CAP);
       }
     }
-    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty;
+    let qualityGatePenalty = 0;
+    if (constraints.structuredOutput) {
+      const schemaWeak = effectiveConventions(profile).some(
+        (c) => c.archetype === ir.intent.archetype && c.structuredOutputHint === "avoid"
+      );
+      if (schemaWeak) qualityGatePenalty = QUALITY_GATE_PENALTY;
+    }
+    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty - qualityGatePenalty;
     scores.push({
       modelId,
       estimatedCostUsd,
@@ -820,6 +855,14 @@ function passScoreTargets(ir, opts) {
         description: `Model ${modelId} rank down ${latencyPenalty.toFixed(2)} \u2014 latency tier '${tier}' (~${LATENCY_TIER_MS[tier]}ms) exceeds constraints.maxLatencyMs (${maxLatencyMs}ms)`
       });
     }
+    if (qualityGatePenalty > 0) {
+      policyMutations.push({
+        id: `quality-gate-structured-${modelId}`,
+        source: "quality_gate",
+        passName: "score_targets",
+        description: `Model ${modelId} gated below the quality floor for archetype '${ir.intent.archetype}' \u2014 declared structuredOutput + kgauto convention flags it schema-weak for this contract (structuredOutputHint:'avoid'). Down-ranked out of leadership; retained as graceful fallback only.`
+      });
+    }
   }
   return { value: scores, mutations: policyMutations };
 }
@@ -3768,16 +3811,15 @@ function hashForProbe(s) {
   for (let i = 0; i < s.length; i++) h = (h << 5) - h + s.charCodeAt(i) | 0;
   return `h${(h >>> 0).toString(16)}`;
 }
-async function runShadowProbe(args) {
+async function runProbeCandidates(args) {
   try {
-    const cfg = args.opts.shadowProbe;
-    if (!shouldSampleProbe(cfg.sampleRate ?? 0.05)) return;
-    const candidates = normalizeProbeCandidates(cfg.candidates);
+    if (!shouldSampleProbe(args.cfg.sampleRate ?? 0.05)) return;
+    const candidates = normalizeProbeCandidates(args.cfg.candidates);
     const promptHash = hashForProbe(args.ir.currentTurn?.content ?? "");
     for (const candidate of candidates) {
       if (candidate === args.servedModel) continue;
       if (deriveFamilyFromModelId(candidate) === "claude-opus") continue;
-      if (!isModelReachable(candidate, { apiKeys: args.opts.apiKeys })) continue;
+      if (!isModelReachable(candidate, { apiKeys: args.exec.apiKeys })) continue;
       try {
         const candCompile = compileAndRegister(
           {
@@ -3785,13 +3827,13 @@ async function runShadowProbe(args) {
             models: args.ir.models.includes(candidate) ? args.ir.models : [candidate, ...args.ir.models],
             constraints: { ...args.ir.constraints ?? {}, forceModel: candidate }
           },
-          args.opts
+          args.exec
         );
         const candStart = Date.now();
         const exec = await execute(candCompile.request, {
-          apiKeys: args.opts.apiKeys,
-          fetchImpl: args.opts.fetchImpl,
-          providerOverrides: args.opts.providerOverrides
+          apiKeys: args.exec.apiKeys,
+          fetchImpl: args.exec.fetchImpl,
+          providerOverrides: args.exec.providerOverrides
         });
         const candidateLatencyMs = Date.now() - candStart;
         if (!exec.ok) continue;
@@ -3820,6 +3862,54 @@ async function runShadowProbe(args) {
   } catch {
   }
 }
+async function runShadowProbe(args) {
+  const cfg = args.opts.shadowProbe;
+  if (!cfg) return;
+  await runProbeCandidates({
+    ir: args.ir,
+    cfg,
+    servedModel: args.servedModel,
+    servedResponse: args.servedResponse,
+    servedLatencyMs: args.servedLatencyMs,
+    // CallOptions is a structural superset of ProbeExecOpts.
+    exec: args.opts
+  });
+}
+async function probeShadow(ir, opts) {
+  try {
+    const servedResponse = {
+      text: opts.served.responseText,
+      structuredOutput: null,
+      toolCalls: [],
+      tokens: {
+        input: opts.served.tokensIn,
+        output: opts.served.tokensOut,
+        total: opts.served.tokensIn + opts.served.tokensOut
+      },
+      raw: null
+    };
+    await runProbeCandidates({
+      ir,
+      cfg: {
+        candidates: opts.candidates,
+        sampleRate: opts.sampleRate,
+        judge: opts.judge ?? "off"
+      },
+      servedModel: opts.served.model,
+      servedResponse,
+      servedLatencyMs: opts.served.latencyMs,
+      exec: {
+        policy: opts.policy,
+        toolRelevanceThreshold: opts.toolRelevanceThreshold,
+        compressHistoryAfter: opts.compressHistoryAfter,
+        apiKeys: opts.apiKeys,
+        fetchImpl: opts.fetchImpl,
+        providerOverrides: opts.providerOverrides
+      }
+    });
+  } catch {
+  }
+}
 function validateStructuredContract(exec, ir) {
   if (!ir.constraints?.structuredOutput) {
     return { ok: true, response: exec.response };
@@ -4405,6 +4495,7 @@ export {
   markAdvisoryResolved,
   markExclusionFindingHandled,
   markPromoteReadyHandled,
+  probeShadow,
   profileToRow,
   profilesByProvider,
   readBrainReadEnv,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.47",
+  "version": "2.0.0-alpha.49",
   "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",