@warmdrift/kgauto-compiler 2.0.0-alpha.83 → 2.0.0-alpha.86

package/dist/index.mjs

@@ -19,7 +19,7 @@ import {
   LIBRARY_VERSION,
   createKeyHealthRoute,
   keyFingerprint
-} from "./chunk-QEFIAAE7.mjs";
+} from "./chunk-V4T2CBRI.mjs";
 import {
   ABSOLUTE_FLOOR,
   ARCHETYPE_FLOOR_DEFAULT,
@@ -27,6 +27,7 @@ import {
   COST_RANKING_REFERENCE_SHAPE,
   MEASURED_GROUNDING_MIN_N,
   PROVIDER_ENV_KEYS,
+  canonicalPolicySet,
   chainProviderSpread,
   configureBrainQuery,
   createBrainQueryCache,
@@ -52,9 +53,10 @@ import {
   loadArchetypePerfFromBrain,
   loadArchetypePerfNFromBrain,
   loadChainsFromBrain,
+  policySetHas,
   readBrainReadEnv,
   resolveProviderKey
-} from "./chunk-XPD4I3Q5.mjs";
+} from "./chunk-QDWOMQYN.mjs";
 import {
   ALIASES,
   LATENCY_TIER_MS,
@@ -64,8 +66,9 @@ import {
   getProfile,
   latencyTierOf,
   profilesByProvider,
+  resolveModelAlias,
   tryGetProfile
-} from "./chunk-VVRDFE6T.mjs";
+} from "./chunk-2MQIVVEU.mjs";
 import {
   emitAdvisoryFired,
   emitCompileDone,
@@ -680,9 +683,12 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
     if (!triggered) continue;
     switch (cliff.action) {
       case "drop_to_top_relevant": {
-        const targetCount = Math.min(
-          Math.floor(cliff.threshold * 0.75),
-          Math.max(1, Math.floor((nextIR.tools?.length ?? 0) / 2))
+        const targetCount = Math.max(
+          1,
+          Math.min(
+            Math.floor(cliff.threshold * 0.75),
+            Math.floor((nextIR.tools?.length ?? 0) / 2)
+          )
         );
         if (nextIR.tools && nextIR.tools.length > targetCount) {
           const intent = nextIR.intent.archetype;
@@ -767,8 +773,8 @@ function effectiveConventions(profile) {
 function passScoreTargets(ir, opts) {
   const constraints = ir.constraints ?? {};
   const policy = opts.policy ?? {};
-  const blockedSet = new Set(policy.blockedModels ?? []);
-  const preferredSet = new Set(policy.preferredModels ?? []);
+  const blockedSet = canonicalPolicySet(policy.blockedModels);
+  const preferredSet = canonicalPolicySet(policy.preferredModels);
   const scores = [];
   const policyMutations = [];
   const rawPromotion = opts.promotion;
@@ -791,7 +797,7 @@ function passScoreTargets(ir, opts) {
       continue;
     }
     const reasons = [];
-    if (blockedSet.has(modelId)) {
+    if (policySetHas(blockedSet, modelId)) {
       reasons.push(`blocked_by_policy (consumer gated this model \u2014 see CompilePolicy.blockedModels)`);
     }
     if (opts.estimatedInputTokens > profile.maxContextTokens * 0.9) {
@@ -821,7 +827,7 @@ function passScoreTargets(ir, opts) {
     const qualityScore = Math.max(0, baseQuality - qualityPenalty);
     const callerOrderBoost = (modelIds.length - modelIds.indexOf(modelId)) * 0.1;
     const costPenalty = estimatedCostUsd * 5;
-    const preferredBoost = preferredSet.has(modelId) ? 0.5 : 0;
+    const preferredBoost = policySetHas(preferredSet, modelId) ? 0.5 : 0;
     let latencyPenalty = 0;
     const maxLatencyMs = constraints.maxLatencyMs;
     if (typeof maxLatencyMs === "number" && maxLatencyMs > 0) {
@@ -878,7 +884,7 @@ function passScoreTargets(ir, opts) {
         description: `Model ${modelId} excluded \u2014 estimated cost $${estimatedCostUsd.toFixed(4)} exceeds policy ceiling $${policy.maxCostPerCallUsd.toFixed(4)}`
       });
     }
-    if (preferredSet.has(modelId) && reasons.length === 0) {
+    if (policySetHas(preferredSet, modelId) && reasons.length === 0) {
       policyMutations.push({
         id: `policy-preferred-${modelId}`,
         source: "compile_policy",
@@ -1892,6 +1898,40 @@ function defaultOnError3(err) {
     err
   );
 }
+function prefetchPromotions(appId) {
+  const rt = runtime3;
+  if (!rt || !appId) return void 0;
+  let snap = snapshots3.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots3.set(appId, snap);
+  }
+  if (snap.expiresAt > Date.now()) return void 0;
+  const inflight = pendingRefreshes3.get(appId);
+  if (inflight) return inflight;
+  if (snap.refreshing) return void 0;
+  snap.refreshing = true;
+  void asyncRefresh3(rt, appId);
+  return pendingRefreshes3.get(appId);
+}
+async function awaitPromotionsReady(appId, timeoutMs) {
+  if (!runtime3 || !appId) return;
+  const pending = prefetchPromotions(appId) ?? pendingRefreshes3.get(appId);
+  if (!(timeoutMs > 0)) return;
+  if (!pending) return;
+  let timer;
+  try {
+    await Promise.race([
+      pending,
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+      })
+    ]);
+  } catch {
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 function _testResetPromotions() {
   runtime3 = void 0;
   snapshots3.clear();
@@ -2361,6 +2401,92 @@ function advisorRuleCrossFamilyFit(ctx) {
   ];
 }
 
+// src/advisor-rules/blocked-model-drift.ts
+var BLOCKED_MODEL_NOT_IN_ROSTER_CODE = "blocked-model-not-in-roster";
+var BLOCKED_MODEL_FAMILY_SIBLING_SERVED_CODE = "blocked-model-family-sibling-served";
+var DOCS_URL = "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories";
+function familyOf2(modelId, profile) {
+  return profile?.family ?? deriveFamilyFromModelId(modelId);
+}
+function isOnTheWayOut(status) {
+  return status === "legacy" || status === "deprecated";
+}
+function advisorRuleBlockedModelDrift(ctx) {
+  const blocked = ctx.policy?.blockedModels;
+  if (!blocked || blocked.length === 0) return [];
+  const resolve = ctx.resolveProfile ?? tryGetProfile;
+  const out = [];
+  const entries = [...new Set(blocked)].sort();
+  const selectedProfile = resolve(ctx.selectedModelId);
+  const selectedFamily = familyOf2(ctx.selectedModelId, selectedProfile);
+  const orphans = entries.filter((e) => resolve(e) === void 0);
+  if (orphans.length > 0) {
+    const list = orphans.map((o) => `\`${o}\``).join(", ");
+    const plural = orphans.length === 1 ? "entry" : "entries";
+    const verb = orphans.length === 1 ? "matches" : "match";
+    out.push({
+      level: "warn",
+      code: BLOCKED_MODEL_NOT_IN_ROSTER_CODE,
+      message: `CompilePolicy.blockedModels ${plural} ${list} ${verb} no model in the current roster, so ${orphans.length === 1 ? "it is" : "they are"} inert \u2014 \`blockedModels\` is matched by exact model id, and nothing kgauto can select carries ${orphans.length === 1 ? "that id" : "those ids"}. The block will never fire.`,
+      suggestion: `Check for a typo, or for an id that was retired from the roster since the block was written. This is how a block goes quiet without an error: tt-intel (2026-07-29) carried \`KGAUTO_BLOCKED_MODELS="claude-sonnet-4-6"\` across a roster retarget and the block stopped covering the traffic they believed it covered. Resolve the intended model id against the live roster \u2014 \`getRecommendedPrimary({ family, fallback })\` returns the id the family currently resolves to \u2014 and block that id, or drop the entry if it is no longer needed.`,
+      docsUrl: DOCS_URL
+    });
+  }
+  if (selectedFamily !== null) {
+    const siblings = entries.filter((e) => {
+      if (resolveModelAlias(e) === resolveModelAlias(ctx.selectedModelId)) return false;
+      const p = resolve(e);
+      if (familyOf2(e, p) !== selectedFamily) return false;
+      if (p && selectedProfile && p.provider !== selectedProfile.provider) {
+        return false;
+      }
+      return true;
+    });
+    if (siblings.length > 0) {
+      const list = siblings.map((s) => `\`${s}\``).join(", ");
+      const plural = siblings.length === 1 ? "" : "s";
+      const retargetShaped = siblings.some((s) => {
+        const p = resolve(s);
+        return isOnTheWayOut(p?.status) && selectedProfile?.status === "current";
+      });
+      const retargetNote = retargetShaped ? ` The blocked id${plural} ${siblings.length === 1 ? "is" : "are"} legacy/deprecated while \`${ctx.selectedModelId}\` is current \u2014 that is the signature of a roster lifecycle move rather than a deliberate per-generation block, so this is more likely to be drift than intent.` : "";
+      out.push({
+        level: "warn",
+        code: BLOCKED_MODEL_FAMILY_SIBLING_SERVED_CODE,
+        message: `\`${ctx.selectedModelId}\` was selected for this call. It is in the same family (\`${selectedFamily}\`) as blocked entr${siblings.length === 1 ? "y" : "ies"} ${list}, but its exact id differs \u2014 and \`CompilePolicy.blockedModels\` matches by exact id, so the block does not cover it.${retargetNote}`,
+        suggestion: `Two readings, and kgauto cannot tell them apart: (1) intentional \u2014 you meant to gate that specific id and \`${ctx.selectedModelId}\` is fine, in which case nothing needs doing and you can filter this code; (2) drift \u2014 you meant to gate the family, and a roster change moved traffic to a sibling your block never named. This happened to tt-intel: when the \`claude-sonnet\` family primary retargeted from \`claude-sonnet-4-6\` to \`claude-sonnet-5\`, their literal-id gate stopped matching the family's routed traffic (their fix was local family resolution). If you meant the family, add \`${ctx.selectedModelId}\` to \`blockedModels\` \u2014 kgauto deliberately does NOT widen exact-id blocks into family globs, because that would silently change what every existing block covers.`,
+        docsUrl: DOCS_URL
+      });
+    }
+  }
+  return out;
+}
+
+// src/advisor-rules/preferred-blocked-overlap.ts
+var PREFERRED_MODEL_BLOCKED_CODE = "preferred-model-blocked";
+var DOCS_URL2 = "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories";
+function advisorRulePreferredBlockedOverlap(ctx) {
+  const preferred = ctx.policy?.preferredModels;
+  const blocked = ctx.policy?.blockedModels;
+  if (!preferred?.length || !blocked?.length) return [];
+  const blockedSet = canonicalPolicySet(blocked);
+  const deadPins = [...new Set(preferred)].filter((p) => policySetHas(blockedSet, p)).sort();
+  if (deadPins.length === 0) return [];
+  const list = deadPins.map((p) => `\`${p}\``).join(", ");
+  const one = deadPins.length === 1;
+  const preferredSet = canonicalPolicySet(preferred);
+  const servedIsPinned = policySetHas(preferredSet, ctx.selectedModelId);
+  return [
+    {
+      level: "warn",
+      code: PREFERRED_MODEL_BLOCKED_CODE,
+      message: `CompilePolicy.preferredModels entr${one ? "y" : "ies"} ${list} ${one ? "is" : "are"} also in \`blockedModels\` (matched canonically, aliases included). A blocked model is hard-rejected before preference boosts apply, so ${one ? "this pin" : "these pins"} can never serve. ` + (servedIsPinned ? `This call was served by \`${ctx.selectedModelId}\`, which is itself a live pin \u2014 the dead entr${one ? "y is" : "ies are"} latent, not currently rerouting traffic.` : `Substitution is your steady state: this call landed on \`${ctx.selectedModelId}\`, which you did not pin.`),
+      suggestion: `Two readings, and kgauto cannot tell them apart: (1) intentional \u2014 your spend gate deliberately outranks the pin, in which case nothing needs doing and you can filter this code; (2) misconfiguration \u2014 the pin and the block were written at different times and the overlap is an accident. tt-intel hit reading (2) on 2026-08-01: a summarize site pinned \`claude-sonnet\` while \`KGAUTO_BLOCKED_MODELS\` carried the same family, and every call silently substituted a reasoning model whose reasoning burn exceeded the site's \`maxOutputTokens\` \u2014 100% empty payloads under HTTP 200. If the block should win, remove the pin so the policy says what it does. If the pin should win, remove ${one ? "the blocking entry" : "the blocking entries"} or re-scope the block to the exact ids you mean. Check what the substitute costs at your input shape while you are here \u2014 a spend gate that lands traffic on a pricier model than the one it blocked is a cost inversion, not a saving.`,
+      docsUrl: DOCS_URL2
+    }
+  ];
+}
+
 // src/advisor.ts
 var QUALITY_FLOOR_FOR_RECOMMENDATION = 6;
 var TIER_DOWN_COST_RATIO = 0.5;
@@ -2379,6 +2505,18 @@ function runAdvisor(ir, result, profile, policy, phase2) {
   out.push(...detectToolBloat(ir, result));
   out.push(...detectHistoryUncached(ir, profile));
   out.push(...detectSingleModelArray(ir, policy));
+  out.push(
+    ...advisorRuleBlockedModelDrift({
+      policy,
+      selectedModelId: profile.id
+    })
+  );
+  out.push(
+    ...advisorRulePreferredBlockedOverlap({
+      policy,
+      selectedModelId: profile.id
+    })
+  );
   if (policy?.posture !== "locked") {
     out.push(...detectCostMismatchedArchetype(ir, profile, phase2));
     out.push(...detectModelStaleEvidence(ir, profile));
@@ -2490,18 +2628,27 @@ function detectHistoryUncached(ir, profile) {
 function detectSingleModelArray(ir, policy) {
   if (ir.models.length !== 1) return [];
   if (policy?.posture === "locked") return [];
-  const only = ir.models[0];
+  const entry = ir.models[0];
+  const only = typeof entry === "string" ? entry : `family:${entry.family}`;
+  const blocked = canonicalPolicySet(policy?.blockedModels);
+  let alternatives = [];
+  try {
+    alternatives = getDefaultFallbackChain({
+      archetype: ir.intent.archetype,
+      primary: only,
+      posture: "preferred",
+      policy
+    }).filter((id) => resolveModelAlias(id) !== resolveModelAlias(only)).filter((id) => !policySetHas(blocked, id)).filter((id) => getModelCompatibility(id, { archetype: ir.intent.archetype }).status !== "reject");
+  } catch {
+  }
+  const hasAlternative = alternatives.length > 0;
+  const remedy = "Widen the chain AND pin your primary: `compile({ ...ir, models: getDefaultFallbackChain({ archetype: ir.intent.archetype, primary: '" + only + "', posture: 'preferred' }) }, { policy: { preferredModels: ['" + only + "'] } })`. The chain is a CANDIDATE SET \u2014 compile() scores it and does not honour its order, so without the `preferredModels` pin the extra entries can retarget your primary (and with it your cost profile). With the pin, `" + only + "` stays primary and the added entries serve only as the safety net. Note `posture` has no effect once `primary` is passed. If you gate models by spend, re-verify `policy.blockedModels` against the widened set before shipping. If single-model is intentional (compliance/brand promise), set `policy.posture = 'locked'` to silence this rule.";
   return [
     {
-      level: "warn",
+      level: hasAlternative ? "critical" : "warn",
       code: "single-model-array",
-      message: `\`ir.models\` has length 1 (only "${only}") and posture is not 'locked'. A single-model chain has no safety net \u2014 the first 429 / 5xx / cliff hits the user as a failure. Master plan \xA71.2 closes the reliability gap with a 2-step minimum.`,
-      // alpha.80: `posture: 'preferred'` keeps the consumer's current model at
-      // position 0 and is therefore cost-neutral; `'open'` re-picks the
-      // primary and is NOT. This rule is about reliability, not cost, so both
-      // stay on offer — but the cost consequence of the second is now stated,
-      // since a reliability fix should not silently become a repricing.
-      suggestion: "Use `getDefaultFallbackChain({ archetype: ir.intent.archetype, primary: '" + only + "', posture: 'preferred' })` for a user-anchored chain \u2014 this keeps `" + only + "` as your primary and only adds fallbacks, so your cost profile is unchanged. `getDefaultFallbackChain({ archetype, posture: 'open' })` instead lets the library pick the PRIMARY, ordered by archetype performance rather than cost \u2014 check what it returns before adopting it. If single-model is intentional (compliance/brand promise), set `policy.posture = 'locked'` to silence this rule.",
+      message: hasAlternative ? `\`ir.models\` has length 1 (only "${only}") for archetype "${ir.intent.archetype}" and posture is not 'locked'. A single-model chain has no safety net \u2014 the first 429 / 5xx / cliff hits the user as a failure \u2014 and a compatible, non-blocked alternative exists in the roster today (${alternatives[0]}), so this is critical: the missing safety net is adoptable now.` : `\`ir.models\` has length 1 (only "${only}") for archetype "${ir.intent.archetype}" and posture is not 'locked'. A single-model chain has no safety net \u2014 the first 429 / 5xx / cliff hits the user as a failure. No compatible non-blocked alternative is visible in the roster for this archetype, so this stays a warning.`,
+      suggestion: remedy,
       docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#single-model-array"
     }
   ];
@@ -3055,6 +3202,15 @@ function compile(ir, opts = {}) {
       sectionRewritesApplied
     }
   );
+  if (ir["policy"] !== void 0 && opts.policy === void 0) {
+    rawAdvisories.push({
+      level: "critical",
+      code: "policy-in-ir-ignored",
+      message: "The IR passed to compile() carries a `policy` field. `policy` belongs in the SECOND argument \u2014 `compile(ir, { policy })` \u2014 and inside the IR it is an unknown field that is completely ignored. If that policy names blockedModels, no block is being enforced on this call.",
+      suggestion: "Move it: `compile(ir, { policy: { ... } })`. If you also configure policy correctly elsewhere on this path, remove the IR copy so the next reader is not misled.",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#public-api"
+    });
+  }
   const advisories = rawAdvisories.map((a) => ({
     ...a,
     kgautoRequestId: handle,
@@ -3281,6 +3437,12 @@ function configureBrain(config) {
       fetchImpl: config.fetchImpl ?? fetch,
       onError: config.onError
     });
+    if (config.appId) {
+      try {
+        void prefetchPromotions(config.appId);
+      } catch {
+      }
+    }
   } else {
     configurePromotionsBrain(void 0);
   }
@@ -3652,6 +3814,7 @@ function buildPayload(input, reg) {
     latency_ms: input.latencyMs,
     success: input.success,
     empty_response: input.emptyResponse ?? input.tokensOut === 0,
+    source: input.source,
     error_type: input.errorType,
     tools_called: input.toolsCalled,
     oracle_score: input.oracleScore?.score,
@@ -4750,7 +4913,11 @@ async function call(ir, opts = {}) {
       )
     })
   );
-  await awaitMeasuredFailureReady(ir.appId, resolveGateWarmupMs(opts));
+  const warmupMs = resolveGateWarmupMs(opts);
+  await Promise.all([
+    awaitMeasuredFailureReady(ir.appId, warmupMs),
+    awaitPromotionsReady(ir.appId, warmupMs)
+  ]);
   const initial = compileAndRegister(ir, opts);
   safeEmit(
     () => emitCompileDone(traceId, ir.appId, {
@@ -4790,6 +4957,7 @@ async function call(ir, opts = {}) {
       const latencyMs2 = Date.now() - start;
       await record({
         handle: initial.handle,
+        source: opts.source,
         tokensIn: 0,
         tokensOut: 0,
         latencyMs: latencyMs2,
@@ -4824,11 +4992,11 @@ async function call(ir, opts = {}) {
   }
   let policyBlockedFiltered;
   if (opts.policy?.blockedModels && opts.policy.blockedModels.length > 0) {
-    const blocked = new Set(opts.policy.blockedModels);
+    const blocked = canonicalPolicySet(opts.policy.blockedModels);
     const filtered = [];
     const dropped = [];
     for (const t of targetsToTry) {
-      if (blocked.has(t)) {
+      if (policySetHas(blocked, t)) {
         dropped.push(t);
       } else {
         filtered.push(t);
@@ -4842,6 +5010,7 @@ async function call(ir, opts = {}) {
       const latencyMs2 = Date.now() - start;
       await record({
         handle: initial.handle,
+        source: opts.source,
         tokensIn: 0,
         tokensOut: 0,
         latencyMs: latencyMs2,
@@ -4868,10 +5037,18 @@ async function call(ir, opts = {}) {
   const failedProviders = /* @__PURE__ */ new Map();
   const sameModelRetryEnabled = opts.sameModelRetry ?? isSameModelRetryEnabledFromEnv();
   let retriedSameModel = false;
+  const pushAttempt = (attempt) => {
+    attempts.push(attempt);
+    if (attempt.status === "success") return;
+    try {
+      opts.onFailedAttempt?.(attempt);
+    } catch {
+    }
+  };
   for (let i = 0; i < targetsToTry.length; i++) {
     const targetModel = targetsToTry[i];
     if (opts.abortSignal?.aborted) {
-      attempts.push({
+      pushAttempt({
         model: targetModel,
         status: "terminal",
         errorCode: "aborted",
@@ -4882,7 +5059,7 @@ async function call(ir, opts = {}) {
     const targetProfile = tryGetProfile(targetModel);
     const providerFailReason = targetProfile ? failedProviders.get(targetProfile.provider) : void 0;
     if (targetProfile && providerFailReason && !opts.noFallback) {
-      attempts.push({
+      pushAttempt({
         model: targetModel,
         status: "terminal",
         errorCode: `${providerFailReason}_inferred`,
@@ -4901,7 +5078,7 @@ async function call(ir, opts = {}) {
           opts
         );
       } catch (err) {
-        attempts.push({
+        pushAttempt({
           model: targetModel,
           status: "terminal",
           errorCode: "compile_error",
@@ -4939,7 +5116,7 @@ async function call(ir, opts = {}) {
     }
     if (!validated.ok && isStructuredContractViolation(validated.errorCode) && sameModelRetryEnabled && !retriedSameModel && !retrySuppressionNote) {
       retriedSameModel = true;
-      attempts.push({
+      pushAttempt({
         model: targetModel,
         status: validated.errorType,
         errorCode: validated.errorCode,
@@ -4954,7 +5131,7 @@ async function call(ir, opts = {}) {
       servedByRetry = true;
     }
     if (validated.ok) {
-      attempts.push({
+      pushAttempt({
         model: targetModel,
         status: "success",
         ...servedByRetry ? { sameModelRetry: true } : {}
@@ -4975,6 +5152,7 @@ async function call(ir, opts = {}) {
       const goldenShapeKey = goldenRate > 0 ? peekRegisteredShapeKey(initial.handle) : void 0;
       await record({
         handle: initial.handle,
+        source: opts.source,
         tokensIn: validated.response.tokens.input,
         tokensOut: validated.response.tokens.output,
         latencyMs: latencyMs2,
@@ -5072,7 +5250,7 @@ async function call(ir, opts = {}) {
         advisories: activeCompile.advisories
       };
     }
-    attempts.push({
+    pushAttempt({
       model: targetModel,
       status: validated.errorType,
       errorCode: validated.errorCode,
@@ -5097,6 +5275,7 @@ async function call(ir, opts = {}) {
   const latencyMs = Date.now() - start;
   await record({
     handle: initial.handle,
+    source: opts.source,
     tokensIn: lastErr?.tokens?.input ?? 0,
     tokensOut: lastErr?.tokens?.output ?? 0,
     latencyMs,
@@ -7216,6 +7395,8 @@ export {
   ALT_STRATEGY_IDS,
   ARCHETYPE_FAMILY_FITS,
   ARCHETYPE_FLOOR_DEFAULT,
+  BLOCKED_MODEL_FAMILY_SIBLING_SERVED_CODE,
+  BLOCKED_MODEL_NOT_IN_ROSTER_CODE,
   BRAIN_READ_ENV_NAMES,
   BURST_SPAN_MS,
   COACH_CFG,
@@ -7259,6 +7440,7 @@ export {
   applySectionRewrites,
   attachCacheControlToStreamTextInput,
   awaitMeasuredFailureReady,
+  awaitPromotionsReady,
   brainHealth,
   bucketContext,
   bucketHistory,
@@ -7345,6 +7527,7 @@ export {
   peekBrainDeadLetter,
   planDecomposition,
   prefetchMeasuredFailure,
+  prefetchPromotions,
   probeShadow,
   profileToRow,
   profilesByProvider,
@@ -7357,6 +7540,7 @@ export {
   resetTokenizer,
   resolveConventionsForProfile,
   resolveGoldenCaptureRate,
+  resolveModelAlias,
   resolvePricingAt,
   resolveProviderKey,
   rowToAdvisory,

package/dist/{ir-D4S9R816.d.mts → ir-5TJLAYKR.d.mts}

@@ -305,6 +305,17 @@ interface CompilePolicy {
      * Model IDs the consumer has gated. Compile() will never select these.
      * Use for: cost caps, account-level rate limits, "this model is broken
      * for our workload" decisions.
+     *
+     * Matching is by EXACT id after alias resolution (alpha.85): an alias
+     * and its canonical id are the same model, so blocking either blocks
+     * both (`deepseek-chat` ≡ `deepseek-v4-flash`). Matching does NOT widen
+     * to family siblings — blocking `deepseek-v4-flash` says nothing about
+     * `deepseek-v4-pro` — and a bare family key (`'deepseek'`,
+     * `'claude-sonnet'`) is INERT: it matches no model and no warning fires
+     * today. To gate a family, list its concrete ids. Beware roster
+     * retargets: when a family primary moves to a new id, a literal-id
+     * block does not follow it (tt-intel s113 built consumer-side family
+     * resolution for exactly this).
      */
     blockedModels?: string[];
     /**
@@ -1073,6 +1084,51 @@ interface ShadowProbeConfig {
     skipSlowTierInSync?: boolean;
 }
 interface CallOptions {
+    /**
+     * alpha.86 — self-mark for synthetic callers (canaries, smokes, eval
+     * replays, probes). Passed through to every outcome row this call
+     * records, including failure rows. OMIT for real traffic. See
+     * {@link OutcomeSource}.
+     */
+    source?: OutcomeSource;
+    /**
+     * alpha.84 — fires once per FAILED attempt during the fallback walk, before
+     * the walk continues. IC-Cairn's filing, 2026-07-29.
+     *
+     * ## The gap this closes
+     *
+     * `call()` records exactly ONE outcome row per call. An attempt that fails
+     * and then walks to a successful fallback survives only as
+     * `fellOverFrom`/`fallbackReason` metadata ON the success row — so a
+     * `call()`-only consumer's corpus contains **no failure rows at all**, by
+     * construction, no matter how carefully they wired `record()`.
+     *
+     * That is not hypothetical. kgauto's own `corpus-implausible-success`
+     * detector fired on inspire-central and told them to "wire record() on the
+     * FAILURE path" — which they had already done, in five places. Measured:
+     * 89 rows, 0 failure rows, 2 fellover-bearing. **The detector demanded
+     * output the API could not produce.** Streaming consumers have had
+     * `onFailedAttempt` since alpha.48 via `streamWithFallover`; `call()`
+     * consumers had nothing. This restores parity.
+     *
+     * ## Contract
+     *
+     * Fires for every attempt whose `status` is `'retryable'` or `'terminal'`,
+     * including skipped ones (`*_inferred`, `aborted`) — a skip is a real
+     * datum about the chain, not an absence. Never fires for `'success'`.
+     *
+     * Called synchronously and **its throw is swallowed**: a consumer's
+     * telemetry bug must never take down the call it is observing. It is a
+     * notification, not a hook that can veto or alter the walk.
+     *
+     * Typical use — emit a failure row per attempt so the corpus can contain
+     * failures at all:
+     *
+     *   call(ir, { onFailedAttempt: (a) => void recordOutcome({
+     *     ...base, success: false, errorType: a.errorCode, model: a.model,
+     *   }) })
+     */
+    onFailedAttempt?: (attempt: CallAttempt) => void;
     /** Forwarded to compile(). */
     policy?: CompilePolicy;
     /**
@@ -1409,9 +1465,34 @@ interface OracleScore {
     /** Free-form explanation for debugging. */
     rationale?: string;
 }
+/**
+ * alpha.86 — who originated an outcome row (migration 056).
+ *
+ * Absent/undefined means ORGANIC: a real consumer call on behalf of a real
+ * user. Consumers change nothing. Synthetic writers — canaries, smoke
+ * gates, eval replays, probe harnesses — self-mark, so liveness and volume
+ * rules can compute over consumer-originated rows only.
+ *
+ * The incident this closes (cost-watch 2026-08-06 → 08-08): playbacksam's
+ * daily canary wrote exactly 8 rows/day for 13 straight days while PB's
+ * organic traffic was near-zero, and the liveness rule scored PB the
+ * healthiest consumer in the portfolio. On 08-08 EVERY row the brain
+ * received in 24h was canary, and no rule could say so — distinguishing a
+ * replay from real traffic took a hand-reconstructed time-window +
+ * token-fingerprint argument, three mornings running. A consumer whose
+ * only rows are written by kgauto's own machinery is dark, not healthy;
+ * this column is what lets a rule print that sentence.
+ */
+type OutcomeSource = 'canary' | 'smoke' | 'eval' | 'probe' | 'synthetic';
 interface RecordInput {
     /** Handle from CompileResult. */
     handle: string;
+    /**
+     * alpha.86 — self-mark for synthetic writers (migration 056). OMIT for
+     * real traffic; never write an explicit "organic" value. See
+     * {@link OutcomeSource}.
+     */
+    source?: OutcomeSource;
     /** Actual tokens consumed (post-call). */
     tokensIn: number;
     tokensOut: number;

package/dist/{ir-Cx9hJj0B.d.ts → ir-C1zmvAh6.d.ts}

@@ -305,6 +305,17 @@ interface CompilePolicy {
      * Model IDs the consumer has gated. Compile() will never select these.
      * Use for: cost caps, account-level rate limits, "this model is broken
      * for our workload" decisions.
+     *
+     * Matching is by EXACT id after alias resolution (alpha.85): an alias
+     * and its canonical id are the same model, so blocking either blocks
+     * both (`deepseek-chat` ≡ `deepseek-v4-flash`). Matching does NOT widen
+     * to family siblings — blocking `deepseek-v4-flash` says nothing about
+     * `deepseek-v4-pro` — and a bare family key (`'deepseek'`,
+     * `'claude-sonnet'`) is INERT: it matches no model and no warning fires
+     * today. To gate a family, list its concrete ids. Beware roster
+     * retargets: when a family primary moves to a new id, a literal-id
+     * block does not follow it (tt-intel s113 built consumer-side family
+     * resolution for exactly this).
      */
     blockedModels?: string[];
     /**
@@ -1073,6 +1084,51 @@ interface ShadowProbeConfig {
     skipSlowTierInSync?: boolean;
 }
 interface CallOptions {
+    /**
+     * alpha.86 — self-mark for synthetic callers (canaries, smokes, eval
+     * replays, probes). Passed through to every outcome row this call
+     * records, including failure rows. OMIT for real traffic. See
+     * {@link OutcomeSource}.
+     */
+    source?: OutcomeSource;
+    /**
+     * alpha.84 — fires once per FAILED attempt during the fallback walk, before
+     * the walk continues. IC-Cairn's filing, 2026-07-29.
+     *
+     * ## The gap this closes
+     *
+     * `call()` records exactly ONE outcome row per call. An attempt that fails
+     * and then walks to a successful fallback survives only as
+     * `fellOverFrom`/`fallbackReason` metadata ON the success row — so a
+     * `call()`-only consumer's corpus contains **no failure rows at all**, by
+     * construction, no matter how carefully they wired `record()`.
+     *
+     * That is not hypothetical. kgauto's own `corpus-implausible-success`
+     * detector fired on inspire-central and told them to "wire record() on the
+     * FAILURE path" — which they had already done, in five places. Measured:
+     * 89 rows, 0 failure rows, 2 fellover-bearing. **The detector demanded
+     * output the API could not produce.** Streaming consumers have had
+     * `onFailedAttempt` since alpha.48 via `streamWithFallover`; `call()`
+     * consumers had nothing. This restores parity.
+     *
+     * ## Contract
+     *
+     * Fires for every attempt whose `status` is `'retryable'` or `'terminal'`,
+     * including skipped ones (`*_inferred`, `aborted`) — a skip is a real
+     * datum about the chain, not an absence. Never fires for `'success'`.
+     *
+     * Called synchronously and **its throw is swallowed**: a consumer's
+     * telemetry bug must never take down the call it is observing. It is a
+     * notification, not a hook that can veto or alter the walk.
+     *
+     * Typical use — emit a failure row per attempt so the corpus can contain
+     * failures at all:
+     *
+     *   call(ir, { onFailedAttempt: (a) => void recordOutcome({
+     *     ...base, success: false, errorType: a.errorCode, model: a.model,
+     *   }) })
+     */
+    onFailedAttempt?: (attempt: CallAttempt) => void;
     /** Forwarded to compile(). */
     policy?: CompilePolicy;
     /**
@@ -1409,9 +1465,34 @@ interface OracleScore {
     /** Free-form explanation for debugging. */
     rationale?: string;
 }
+/**
+ * alpha.86 — who originated an outcome row (migration 056).
+ *
+ * Absent/undefined means ORGANIC: a real consumer call on behalf of a real
+ * user. Consumers change nothing. Synthetic writers — canaries, smoke
+ * gates, eval replays, probe harnesses — self-mark, so liveness and volume
+ * rules can compute over consumer-originated rows only.
+ *
+ * The incident this closes (cost-watch 2026-08-06 → 08-08): playbacksam's
+ * daily canary wrote exactly 8 rows/day for 13 straight days while PB's
+ * organic traffic was near-zero, and the liveness rule scored PB the
+ * healthiest consumer in the portfolio. On 08-08 EVERY row the brain
+ * received in 24h was canary, and no rule could say so — distinguishing a
+ * replay from real traffic took a hand-reconstructed time-window +
+ * token-fingerprint argument, three mornings running. A consumer whose
+ * only rows are written by kgauto's own machinery is dark, not healthy;
+ * this column is what lets a rule print that sentence.
+ */
+type OutcomeSource = 'canary' | 'smoke' | 'eval' | 'probe' | 'synthetic';
 interface RecordInput {
     /** Handle from CompileResult. */
     handle: string;
+    /**
+     * alpha.86 — self-mark for synthetic writers (migration 056). OMIT for
+     * real traffic; never write an explicit "organic" value. See
+     * {@link OutcomeSource}.
+     */
+    source?: OutcomeSource;
     /** Actual tokens consumed (post-call). */
     tokensIn: number;
     tokensOut: number;