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

package/dist/{chunk-XJZRDGHF.mjs → chunk-6MSJQCAP.mjs}

@@ -1,6 +1,6 @@
 import {
   tryGetProfile
-} from "./chunk-JQGRWJZO.mjs";
+} from "./chunk-ZHUD3I52.mjs";
 
 // src/brain-query.ts
 var FRESH_SNAPSHOT = {
@@ -313,6 +313,16 @@ function getReachabilityDiagnostic(opts = {}) {
   }
   return out;
 }
+function readBrainReadEnv(envSource = defaultEnv()) {
+  const endpoint = readKeyValue(envSource.KGAUTO_V2_BRAIN_SUPABASE_URL) ?? readKeyValue(envSource.KGAUTO_V2_BRAIN_URL);
+  const jwt = readKeyValue(envSource.KGAUTO_V2_BRAIN_JWT) ?? readKeyValue(envSource.GLASSBOX_BRAIN_JWT);
+  const anonKey = readKeyValue(envSource.KGAUTO_V2_BRAIN_ANON_KEY);
+  const missingEnv = [];
+  if (!endpoint) missingEnv.push("KGAUTO_V2_BRAIN_SUPABASE_URL");
+  if (!jwt) missingEnv.push("KGAUTO_V2_BRAIN_JWT");
+  if (!anonKey) missingEnv.push("KGAUTO_V2_BRAIN_ANON_KEY");
+  return { endpoint, jwt, anonKey, missingEnv };
+}
 
 // src/fallback.ts
 var STARTER_CHAINS_GROUNDED = {
@@ -670,6 +680,7 @@ export {
   isProviderReachable,
   isModelReachable,
   getReachabilityDiagnostic,
+  readBrainReadEnv,
   loadChainsFromBrain,
   getDefaultFallbackChain,
   getStarterChain,

package/dist/{chunk-JQGRWJZO.mjs → chunk-ZHUD3I52.mjs}

@@ -562,7 +562,21 @@ var PROFILES_RAW = [
       critique: 4,
       hunt: 4
       // sequential tool calls only — L-040
-    }
+    },
+    // alpha.43 — family-level conventions for the `deepseek-chat` family
+    // (V4-Flash + future non-thinking-mode members). V4-Flash struggles
+    // with summarize-archetype + structured-output: 3 of 4 schema-attempted
+    // PB calls (2026-05-18 + 2026-05-22) hit `structured_output_parse_failed`.
+    // Surface the friction at compile time so consumers either drop the
+    // schema or route to a more schema-reliable family.
+    archetypeConventions: [
+      {
+        archetype: "summarize",
+        structuredOutputHint: "avoid",
+        cliffWarning: "deepseek-chat family schema compliance on summarize is weak (3 of 4 schema-attempted PB calls hit structured_output_parse_failed). Consider routing summarize+structured-output to a different family (claude-sonnet, gemini-pro, openai-gpt-5.4) or dropping the schema for free-text summaries.",
+        reason: "Brain evidence: PB compile_outcomes 2026-05-18 + 2026-05-22, error_type=structured_output_parse_failed on deepseek-v4-flash + summarize archetype."
+      }
+    ]
   },
   {
     id: "deepseek-v4-pro",
@@ -613,7 +627,51 @@ var PROFILES_RAW = [
       transform: 6,
       hunt: 4
       // sequential tools — same as V4-Flash
-    }
+    },
+    // alpha.43 — family-level conventions for the `deepseek-reasoner` family
+    // (V4-Pro is the family rep; future thinking-mode members inherit).
+    //
+    // The decisive-archetype suffix is the load-bearing piece: 2026-05-28
+    // first real V4-Pro probe on tt-intel/classify (exclusion-finding ID 20)
+    // showed 8/10 judge rationales citing "candidate hedges and fails to
+    // commit to a single classification" or "candidate refuses to pick
+    // among the labels." Without the forcing-function suffix, every
+    // reasoner probe on classify/extract/ask verdicts stay-excluded for
+    // model-behavior reasons (epistemic humility is reasoner-shaped),
+    // NOT quality reasons. The suffix re-shapes the contract so the model
+    // is asked for what it's actually being measured on.
+    //
+    // The hunt-archetype cliffWarning is the L-040 architectural reading
+    // surfaced at compile time. Reasoners produce sequential reasoning
+    // chains by design; hunt archetypes with 3+ parallel tools lose
+    // substantial throughput (L-040 + L-041). The L-040 cliff in the
+    // `cliffs` array already trims to top-relevant tools; this warning
+    // tells the consumer the family is wrong for the shape so they can
+    // route to gemini-flash (parallel-strong) instead of accepting trimmed
+    // throughput silently.
+    archetypeConventions: [
+      {
+        archetype: "classify",
+        promptSuffix: "\n\nOutput exactly one classification label. Do not hedge, do not add preamble, do not explain your reasoning. If uncertain, pick the most likely label and commit to it.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: 2026-05-28 V4-Pro probe on tt-intel/classify (exclusion-finding ID 20, brain probe_outcomes); 8 of 10 judge rationales cited hedging or refusal-to-commit. Forcing-function suffix converts reasoner output to decisive labels."
+      },
+      {
+        archetype: "extract",
+        promptSuffix: "\n\nOutput exactly the requested structured fields. Do not hedge, do not add preamble, do not explain your reasoning. If a field is unknown, emit the field with a null/empty value and commit to that \u2014 do not refuse to extract.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: same family failure shape as classify (exclusion-finding ID 20, 2026-05-28). Forcing-function suffix asks for commitment instead of epistemic-humility hedging."
+      },
+      {
+        archetype: "ask",
+        promptSuffix: "\n\nAnswer the question directly. Do not hedge, do not add preamble, do not explain your reasoning unless explicitly asked. If uncertain, give your best answer and commit to it.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: same family failure shape as classify (exclusion-finding ID 20, 2026-05-28). Forcing-function suffix asks for commitment instead of epistemic-humility hedging."
+      },
+      {
+        archetype: "hunt",
+        whenToolCountAtLeast: 3,
+        cliffWarning: "Reasoners (deepseek-reasoner family) produce sequential reasoning chains by design; hunt archetypes with 3+ parallel tools lose substantial throughput. Consider gemini-flash family (parallel-strong) instead \u2014 see L-040 / L-041.",
+        reason: "L-040 + L-041 architectural reading; 2026-05-28 V4-Pro probe evidence (exclusion-finding ID 20) confirms reasoner-family hunt fit is structurally weak."
+      }
+    ]
   },
   // ── OpenAI ──
   // alpha.16 (2026-05-17): close the half-supported provider gap. env.ts

package/dist/glassbox/index.d.mts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-MkiWUPM8.mjs';
-export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-MkiWUPM8.mjs';
-import '../ir-D_kgJcaV.mjs';
+import { G as GlassboxEvent } from '../types-acFM2-iZ.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-acFM2-iZ.mjs';
+import '../ir-CSgyol5D.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox/index.d.ts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-DigtHnEt.js';
-export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-DigtHnEt.js';
-import '../ir-DYpvUSEw.js';
+import { G as GlassboxEvent } from '../types-_1tcDEqa.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-_1tcDEqa.js';
+import '../ir-MN9bGclm.js';
 import '../dialect.js';
 
 /**

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

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

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

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

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

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

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

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

package/dist/glassbox-routes/index.js

@@ -627,7 +627,21 @@ var PROFILES_RAW = [
       critique: 4,
       hunt: 4
       // sequential tool calls only — L-040
-    }
+    },
+    // alpha.43 — family-level conventions for the `deepseek-chat` family
+    // (V4-Flash + future non-thinking-mode members). V4-Flash struggles
+    // with summarize-archetype + structured-output: 3 of 4 schema-attempted
+    // PB calls (2026-05-18 + 2026-05-22) hit `structured_output_parse_failed`.
+    // Surface the friction at compile time so consumers either drop the
+    // schema or route to a more schema-reliable family.
+    archetypeConventions: [
+      {
+        archetype: "summarize",
+        structuredOutputHint: "avoid",
+        cliffWarning: "deepseek-chat family schema compliance on summarize is weak (3 of 4 schema-attempted PB calls hit structured_output_parse_failed). Consider routing summarize+structured-output to a different family (claude-sonnet, gemini-pro, openai-gpt-5.4) or dropping the schema for free-text summaries.",
+        reason: "Brain evidence: PB compile_outcomes 2026-05-18 + 2026-05-22, error_type=structured_output_parse_failed on deepseek-v4-flash + summarize archetype."
+      }
+    ]
   },
   {
     id: "deepseek-v4-pro",
@@ -678,7 +692,51 @@ var PROFILES_RAW = [
       transform: 6,
       hunt: 4
       // sequential tools — same as V4-Flash
-    }
+    },
+    // alpha.43 — family-level conventions for the `deepseek-reasoner` family
+    // (V4-Pro is the family rep; future thinking-mode members inherit).
+    //
+    // The decisive-archetype suffix is the load-bearing piece: 2026-05-28
+    // first real V4-Pro probe on tt-intel/classify (exclusion-finding ID 20)
+    // showed 8/10 judge rationales citing "candidate hedges and fails to
+    // commit to a single classification" or "candidate refuses to pick
+    // among the labels." Without the forcing-function suffix, every
+    // reasoner probe on classify/extract/ask verdicts stay-excluded for
+    // model-behavior reasons (epistemic humility is reasoner-shaped),
+    // NOT quality reasons. The suffix re-shapes the contract so the model
+    // is asked for what it's actually being measured on.
+    //
+    // The hunt-archetype cliffWarning is the L-040 architectural reading
+    // surfaced at compile time. Reasoners produce sequential reasoning
+    // chains by design; hunt archetypes with 3+ parallel tools lose
+    // substantial throughput (L-040 + L-041). The L-040 cliff in the
+    // `cliffs` array already trims to top-relevant tools; this warning
+    // tells the consumer the family is wrong for the shape so they can
+    // route to gemini-flash (parallel-strong) instead of accepting trimmed
+    // throughput silently.
+    archetypeConventions: [
+      {
+        archetype: "classify",
+        promptSuffix: "\n\nOutput exactly one classification label. Do not hedge, do not add preamble, do not explain your reasoning. If uncertain, pick the most likely label and commit to it.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: 2026-05-28 V4-Pro probe on tt-intel/classify (exclusion-finding ID 20, brain probe_outcomes); 8 of 10 judge rationales cited hedging or refusal-to-commit. Forcing-function suffix converts reasoner output to decisive labels."
+      },
+      {
+        archetype: "extract",
+        promptSuffix: "\n\nOutput exactly the requested structured fields. Do not hedge, do not add preamble, do not explain your reasoning. If a field is unknown, emit the field with a null/empty value and commit to that \u2014 do not refuse to extract.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: same family failure shape as classify (exclusion-finding ID 20, 2026-05-28). Forcing-function suffix asks for commitment instead of epistemic-humility hedging."
+      },
+      {
+        archetype: "ask",
+        promptSuffix: "\n\nAnswer the question directly. Do not hedge, do not add preamble, do not explain your reasoning unless explicitly asked. If uncertain, give your best answer and commit to it.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: same family failure shape as classify (exclusion-finding ID 20, 2026-05-28). Forcing-function suffix asks for commitment instead of epistemic-humility hedging."
+      },
+      {
+        archetype: "hunt",
+        whenToolCountAtLeast: 3,
+        cliffWarning: "Reasoners (deepseek-reasoner family) produce sequential reasoning chains by design; hunt archetypes with 3+ parallel tools lose substantial throughput. Consider gemini-flash family (parallel-strong) instead \u2014 see L-040 / L-041.",
+        reason: "L-040 + L-041 architectural reading; 2026-05-28 V4-Pro probe evidence (exclusion-finding ID 20) confirms reasoner-family hunt fit is structurally weak."
+      }
+    ]
   },
   // ── OpenAI ──
   // alpha.16 (2026-05-17): close the half-supported provider gap. env.ts

package/dist/glassbox-routes/index.mjs

@@ -1,10 +1,10 @@
 import {
   ARCHETYPE_FLOOR_DEFAULT,
   getDefaultFallbackChain
-} from "../chunk-XJZRDGHF.mjs";
+} from "../chunk-6MSJQCAP.mjs";
 import {
   tryGetProfile
-} from "../chunk-JQGRWJZO.mjs";
+} from "../chunk-ZHUD3I52.mjs";
 import {
   subscribe,
   subscribeApp

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

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

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

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

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-D_kgJcaV.mjs';
-export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, r as MutationApplied, s as NormalizedTokens, t as OutcomeKind, u as PerAxisMetricsByModel, v as PromptSection, w as SectionKind, T as ToolCall, x as ToolDefinition } from './ir-D_kgJcaV.mjs';
-import { ModelProfile } from './profiles.mjs';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-CSgyol5D.mjs';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, r as MutationApplied, s as NormalizedTokens, t as OutcomeKind, u as PerAxisMetricsByModel, v as PromptSection, w as SectionKind, T as ToolCall, x as ToolDefinition } from './ir-CSgyol5D.mjs';
+import { ModelProfile, ArchetypeConvention } from './profiles.mjs';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.mjs';
@@ -387,6 +387,34 @@ interface LLMJudgeOptions {
  */
 declare function buildLLMJudge(opts: LLMJudgeOptions): AppOracle;
 
+/**
+ * Resolve the effective ArchetypeConvention[] for a given selected profile,
+ * walking family inheritance once. Model-specific entries on the selected
+ * profile take precedence over family-level entries for the same archetype.
+ *
+ * Pure; safe to call from any context (probe-watcher uses the same logic
+ * via `applyArchetypeConvention`).
+ */
+declare function resolveConventionsForProfile(profile: ModelProfile): ArchetypeConvention[];
+/**
+ * Pure helper: apply the matching ArchetypeConvention's suffix (and
+ * prefix, when meaningful) to a plain prompt-text string. Used by the
+ * exclusion-probe-watcher (`probeOne`) so probe calls carry the same
+ * forcing-function shape consumers see at compile time. Without this,
+ * every reasoner probe on a decisive archetype gets unfairly stay-excluded
+ * for hedging — as ID 20 demonstrated on 2026-05-28.
+ *
+ * Resolution: looks up the family-rep profile for `family` and reads its
+ * `archetypeConventions`. Returns the original text unchanged when no
+ * convention matches or when the suffix is already present.
+ *
+ * @param promptText raw user-prompt text (or prompt_preview from outcome)
+ * @param archetype  intent_archetype from the finding row
+ * @param family     family tag from deriveFamilyFromModelId / brain row
+ * @returns text with prefix/suffix applied (idempotent)
+ */
+declare function applyArchetypeConvention(promptText: string, archetype: string, family: string): string;
+
 /**
  * Tokenizer abstraction.
  *
@@ -410,6 +438,75 @@ declare function resetTokenizer(): void;
  */
 declare function countTokens(text: string): number;
 
+/**
+ * archetype-fits — alpha.43.
+ *
+ * Static table of "this archetype tends to be a better fit for this family"
+ * recommendations. Powers the `cross-family-fit-candidate` compile-time
+ * advisor (see `advisor-rules/cross-family-fit.ts`).
+ *
+ * Strategic framing (Sacha, 2026-05-28): "If we get better results and
+ * better price then we do. Even if volume is currently low, that's not an
+ * argument to not do it. Volume can increase quickly if tools is great to
+ * use, let's not create future bottlenecks because we could have wired in
+ * better solution at moment of knowing."
+ *
+ * The convention substrate (passApplyConventions) is the NEGATIVE side:
+ * make a family usable on archetypes it currently fails. This table is the
+ * POSITIVE side: actively surface that a different family is the better
+ * fit for the archetype's shape — even when current volume is low.
+ *
+ * Entries are added only when:
+ *   - the archetype's shape and the family's behavior have a clear
+ *     architectural fit (not vibes)
+ *   - real-world evidence (brain rows, probe outcomes, or published
+ *     benchmark) backs the claim, OR the reasoning is structurally so clear
+ *     that "wait for volume" would create a future bottleneck
+ *
+ * Alpha.43 ships two entries — `plan` and `critique`. Both fit the
+ * reasoner-family architectural read: plan is multi-step reasoning;
+ * critique rewards epistemic humility and explicit reasoning. Other
+ * archetype-family-fits ride later alphas as evidence accumulates.
+ *
+ * Anti-pattern: do NOT add archetype-family-fits for archetypes where the
+ * fit is unclear (summarize, classify, extract, hunt with parallel tools).
+ * The advisor only earns trust when its recommendations land.
+ */
+
+/**
+ * One archetype-family-fit recommendation. Read by the compile-time
+ * `cross-family-fit-candidate` advisor to decide when to surface a positive
+ * recommendation. The advisor pulls `costGuidance` verbatim into the
+ * advisory message.
+ */
+interface ArchetypeFamilyFit {
+    /** Intent archetype this fit applies to. */
+    archetype: IntentArchetypeName;
+    /** Family tag that fits the archetype better than alternatives. Matches the
+     *  same family taxonomy used by `family-resolution.deriveFamilyFromModelId`
+     *  (e.g. `'deepseek-reasoner'`, `'gemini-flash'`, `'claude-opus'`). */
+    betterFitFamily: string;
+    /** Architectural / evidentiary justification. Appears in the advisor's
+     *  internal logs and the advisory `evidence` payload, NOT verbatim in the
+     *  consumer-facing message. */
+    reason: string;
+    /** Cost-context clause surfaced VERBATIM in the consumer-facing advisory
+     *  message (e.g. "substantially cheaper at current pricing"). Keep
+     *  declarative; the advisor wraps this into the larger sentence. */
+    costGuidance: string;
+}
+/**
+ * Frozen registry. Add entries by extending the array. Order is irrelevant
+ * — the advisor filters by `(archetype, currentFamily)` independently.
+ */
+declare const ARCHETYPE_FAMILY_FITS: readonly ArchetypeFamilyFit[];
+/**
+ * Pure lookup: does `(archetype, currentFamily)` have a better-fit family?
+ * Returns the fit entry when the current family is NOT the better fit; null
+ * otherwise. Used by the advisor to decide whether to fire.
+ */
+declare function findBetterFit(archetype: string, currentFamily: string): ArchetypeFamilyFit | null;
+
 /**
  * Best-practice advisor — alpha.6 Phase 1.
  *
@@ -467,6 +564,31 @@ interface RunAdvisorPhase2Context {
      */
     sectionRewritesApplied?: SectionRewrite[];
 }
+/**
+ * alpha.42 — rule codes whose advisories are positioned for kgauto (not
+ * the consumer) to act on. Used by `compile()` to default the `ownership`
+ * stamp on each advisory when the rule didn't self-declare. Consumer-side
+ * rules don't need to be listed — they default to `'consumer-actionable'`
+ * via fall-through.
+ *
+ *   - `model-stale-evidence`: kgauto's profile data is out of date; the
+ *     consumer can't fix that, kgauto needs to update profiles or refresh
+ *     archetypePerf scores.
+ *   - `promote-ready`: kgauto's promotion-probe-watcher detected a
+ *     candidate model worth promoting; consumer-side adoption is downstream
+ *     of kgauto adding it to the chain / family taxonomy.
+ *
+ * Frozen so consumers and tests can't mutate the global ownership map.
+ */
+declare const PRODUCER_OWNED_RULE_CODES: ReadonlySet<string>;
+/**
+ * alpha.42 — pure function used by `compile()` to decide ownership for an
+ * advisory. Rule-self-declared wins; falls back to the static map; defaults
+ * `consumer-actionable`. Exported so consumer-side code (or a Glass-Box
+ * renderer) can derive the same classification from a rule code alone
+ * without needing the advisory object.
+ */
+declare function deriveOwnership(code: string, selfDeclared?: 'consumer-actionable' | 'producer-owned'): 'consumer-actionable' | 'producer-owned';
 /**
  * Run all phased rules and return collected advisories. Order is fixed so
  * output is stable across runs. The `policy` argument is alpha.9 — the
@@ -1152,6 +1274,71 @@ interface ProviderReachability {
  * Does NOT log the key value itself — only the env var name that supplied it.
  */
 declare function getReachabilityDiagnostic(opts?: ReachabilityOpts): Record<SupportedProvider, ProviderReachability>;
+/**
+ * Brain-read env contract — canonical names + accepted fallbacks for the
+ * env vars kgauto's brain-read APIs need.
+ *
+ * Affected APIs: `getActionableAdvisories`, `markAdvisoryResolved`,
+ * `markExclusionFindingHandled`, `markPromoteReadyHandled`,
+ * `getStaleExclusionFindings`, and future brain-read surfaces. Each accepts
+ * `brainEndpoint`/`brainJwt`/`brainAnonKey` as call-site arguments; this
+ * helper centralizes resolution from the consumer's environment.
+ *
+ * Resolution order (first-truthy-trimmed wins):
+ *   endpoint = KGAUTO_V2_BRAIN_SUPABASE_URL ?? KGAUTO_V2_BRAIN_URL
+ *   jwt      = KGAUTO_V2_BRAIN_JWT          ?? GLASSBOX_BRAIN_JWT
+ *   anonKey  = KGAUTO_V2_BRAIN_ANON_KEY     (no fallback)
+ *
+ * Why fallbacks exist:
+ *
+ *   1. Pre-alpha.42, some consumers set `KGAUTO_V2_BRAIN_URL` pointing at
+ *      the kgauto-dashboard URL (write target). The canonical
+ *      `KGAUTO_V2_BRAIN_SUPABASE_URL` is the Supabase project URL (read
+ *      target — PostgREST against `/rest/v1/`). Until consumers split the
+ *      two names, the fallback grabs whichever URL is set. When BOTH are
+ *      set, canonical wins (the consumer has explicitly split).
+ *
+ *   2. The s33 Glass-Box ship provisioned `GLASSBOX_BRAIN_JWT` across all
+ *      consumers with the same `app_id` claim shape, signed by the same
+ *      JWT_SECRET. Reusing it for brain-read avoids re-minting + re-pasting
+ *      a second JWT per consumer per surface.
+ *
+ * `missingEnv` lists the CANONICAL names that aren't satisfied by either
+ * canonical OR fallback. Consumer policy: if `missingEnv.length > 0`,
+ * render `not_configured`; otherwise pass `endpoint`/`jwt`/`anonKey` to
+ * `getActionableAdvisories({ ... })` et al.
+ *
+ * Pre-trim semantics carry from `readKeyValue` — paste-newline-trap
+ * (L-060 / L-083 / L-108) closure extends to brain env vars.
+ *
+ * Filed by tt-intel-Cairn (s89, 2026-05-27) after the s89 actionable-
+ * advisories ref template hit `malformed brain response` on prod because
+ * the endpoint env var pointed at the kgauto-dashboard URL instead of the
+ * Supabase URL, AND because IC's ref template used a third env name
+ * (`KGAUTO_V2_BRAIN_ENDPOINT`) that was unset. Three distinct name shapes
+ * across two consumers — the durable closure is one canonical contract.
+ */
+interface BrainReadEnv {
+    /** Supabase project URL (PostgREST base). Undefined when neither canonical nor fallback is set. */
+    endpoint?: string;
+    /** JWT carrying `app_id` claim, signed by brain JWT_SECRET. Undefined when neither canonical nor fallback is set. */
+    jwt?: string;
+    /** Supabase anon (publishable) key. Undefined when not set. */
+    anonKey?: string;
+    /**
+     * Canonical names not satisfied by either canonical OR fallback. Subset
+     * (in order) of:
+     *   ['KGAUTO_V2_BRAIN_SUPABASE_URL', 'KGAUTO_V2_BRAIN_JWT', 'KGAUTO_V2_BRAIN_ANON_KEY']
+     * Consumer policy: render `not_configured` when length > 0.
+     */
+    missingEnv: string[];
+}
+/**
+ * Resolve brain-read env vars. Defaults to `process.env`; pass `envSource`
+ * for hermetic tests. Trims surrounding whitespace and treats
+ * empty-after-trim as unset (same shape as `resolveProviderKey`).
+ */
+declare function readBrainReadEnv(envSource?: Record<string, string | undefined>): BrainReadEnv;
 
 /**
  * getDefaultFallbackChain — the alpha.9 cascading ship.
@@ -1932,4 +2119,4 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, deriveFamilyFromModelId, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+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 SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, 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, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, profileToRow, readBrainReadEnv, record, recordOutcome, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };