@warmdrift/kgauto-compiler 2.0.0-alpha.18 → 2.0.0-alpha.20

package/dist/glassbox/index.d.mts

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

package/dist/glassbox/index.d.ts

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

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

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-DWF6mPGg.mjs';
-import '../ir-C3P4gDt0.mjs';
+import { G as GlassboxEvent } from '../types-BYj1Kl2m.mjs';
+import '../ir-DTMbSnyE.mjs';
 import '../dialect.mjs';
 
 /**

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

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-xeklorHU.js';
-import '../ir-CFHU3BUT.js';
+import { G as GlassboxEvent } from '../types-CwtaDaWN.js';
+import '../ir-CsTU4cMB.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/index.js

@@ -25,8 +25,6 @@ __export(glassbox_routes_exports, {
 module.exports = __toCommonJS(glassbox_routes_exports);
 
 // src/glassbox-routes/auth.ts
-var import_node_buffer = require("buffer");
-var import_node_crypto = require("crypto");
 var JSON_HEADERS = { "Content-Type": "application/json" };
 function jsonError(status, code) {
   return new Response(JSON.stringify({ error: code }), {
@@ -36,10 +34,11 @@ function jsonError(status, code) {
 }
 function tokensEqual(a, b) {
   if (a.length !== b.length) return false;
-  const ab = import_node_buffer.Buffer.from(a, "utf8");
-  const bb = import_node_buffer.Buffer.from(b, "utf8");
-  if (ab.length !== bb.length) return false;
-  return (0, import_node_crypto.timingSafeEqual)(ab, bb);
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
 }
 function checkAuth(req, config) {
   const authHeader = req.headers.get("Authorization") ?? "";

package/dist/glassbox-routes/index.mjs

@@ -4,8 +4,6 @@ import {
 import "../chunk-NUTC7NUC.mjs";
 
 // src/glassbox-routes/auth.ts
-import { Buffer } from "buffer";
-import { timingSafeEqual } from "crypto";
 var JSON_HEADERS = { "Content-Type": "application/json" };
 function jsonError(status, code) {
   return new Response(JSON.stringify({ error: code }), {
@@ -15,10 +13,11 @@ function jsonError(status, code) {
 }
 function tokensEqual(a, b) {
   if (a.length !== b.length) return false;
-  const ab = Buffer.from(a, "utf8");
-  const bb = Buffer.from(b, "utf8");
-  if (ab.length !== bb.length) return false;
-  return timingSafeEqual(ab, bb);
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
 }
 function checkAuth(req, config) {
   const authHeader = req.headers.get("Authorization") ?? "";

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, R as RecordInput, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory, f as Provider } from './ir-C3P4gDt0.mjs';
-export { g as CallAttempt, h as CallError, i as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, j as MutationApplied, k as NormalizedTokens, l as PromptSection, T as ToolCall, m as ToolDefinition } from './ir-C3P4gDt0.mjs';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Provider } from './ir-DTMbSnyE.mjs';
+export { i as CallAttempt, j as CallError, k as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, l as MutationApplied, m as NormalizedTokens, n as OutcomeKind, o as PromptSection, T as ToolCall, p as ToolDefinition } from './ir-DTMbSnyE.mjs';
 import { ModelProfile } from './profiles.mjs';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
@@ -198,7 +198,30 @@ interface OutcomePayload {
     ttft_ms?: number;
     history_cacheable_tokens?: number;
     history_tokens_at_compile?: number;
+    /**
+     * Mirrors `ir.constraints.toolOrchestration` from compile time. NULL when
+     * the consumer hadn't adopted the constraint (pre-alpha.20). Powers
+     * per-mode model-perf queries on the brain (the L-040 parallel-tool
+     * cliff lumps DeepSeek sequential perf with parallel without this).
+     */
+    tool_orchestration?: 'parallel' | 'sequential' | 'either' | null;
 }
+/**
+ * alpha.20 Entry 4: record a quality outcome for a previously-compiled call.
+ *
+ * Fires after the consumer's UX surfaces an approve/reject event (e.g., user
+ * clicks Approve on a hunt result). Joins to the original `compile_outcomes`
+ * row via outcomeId — enables per-(model, archetype) approve-rate measurement
+ * once N ≥ 10 outcomes accumulate.
+ *
+ * Fire-and-forget by default (matches record() semantics). Set BrainConfig.sync
+ * = true for runtime contexts that can't tolerate fire-and-forget teardown
+ * (Vercel Edge, Cloudflare Workers, AWS Lambda) — see L-086.
+ *
+ * Returns OutcomeResult with ok: false + stable reason on persistence
+ * failure. Never throws.
+ */
+declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -475,6 +498,23 @@ interface GetDefaultFallbackChainOpts {
      * legacy unfiltered behavior — preserves alpha.9 callers byte-for-byte.
      */
     reachability?: ReachabilityOpts;
+    /**
+     * alpha.20 E3: consumer-declared tool-orchestration shape. Currently
+     * only affects `archetype: 'hunt'`, where 'sequential' swaps the
+     * parallel-tool-tier-0 chain (Flash → Pro → Sonnet → Haiku) for a
+     * DeepSeek-tier-0 chain (V4-Pro → Flash → Sonnet) — DeepSeek's L-040
+     * parallel-tool cliff doesn't apply when the consumer commits to
+     * single-step orchestration.
+     *
+     * Other archetypes are NOT mode-aware in this release — they ship the
+     * same chain regardless of toolOrchestration. Future versions may
+     * extend mode-awareness to ask/generate/etc. when brain evidence
+     * supports it.
+     *
+     * Default (omitted or 'either'): parallel chain. Back-compat with all
+     * pre-alpha.20 callers.
+     */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
 }
 declare function getDefaultFallbackChain(opts: GetDefaultFallbackChainOpts): string[];
 /**
@@ -718,4 +758,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, type ArchetypePerfMap, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getArchetypePerfScore, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ApiKeys, type AppOracle, type ArchetypePerfMap, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getArchetypePerfScore, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, R as RecordInput, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory, f as Provider } from './ir-CFHU3BUT.js';
-export { g as CallAttempt, h as CallError, i as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, j as MutationApplied, k as NormalizedTokens, l as PromptSection, T as ToolCall, m as ToolDefinition } from './ir-CFHU3BUT.js';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Provider } from './ir-CsTU4cMB.js';
+export { i as CallAttempt, j as CallError, k as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, l as MutationApplied, m as NormalizedTokens, n as OutcomeKind, o as PromptSection, T as ToolCall, p as ToolDefinition } from './ir-CsTU4cMB.js';
 import { ModelProfile } from './profiles.js';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.js';
 import { IntentArchetypeName } from './dialect.js';
@@ -198,7 +198,30 @@ interface OutcomePayload {
     ttft_ms?: number;
     history_cacheable_tokens?: number;
     history_tokens_at_compile?: number;
+    /**
+     * Mirrors `ir.constraints.toolOrchestration` from compile time. NULL when
+     * the consumer hadn't adopted the constraint (pre-alpha.20). Powers
+     * per-mode model-perf queries on the brain (the L-040 parallel-tool
+     * cliff lumps DeepSeek sequential perf with parallel without this).
+     */
+    tool_orchestration?: 'parallel' | 'sequential' | 'either' | null;
 }
+/**
+ * alpha.20 Entry 4: record a quality outcome for a previously-compiled call.
+ *
+ * Fires after the consumer's UX surfaces an approve/reject event (e.g., user
+ * clicks Approve on a hunt result). Joins to the original `compile_outcomes`
+ * row via outcomeId — enables per-(model, archetype) approve-rate measurement
+ * once N ≥ 10 outcomes accumulate.
+ *
+ * Fire-and-forget by default (matches record() semantics). Set BrainConfig.sync
+ * = true for runtime contexts that can't tolerate fire-and-forget teardown
+ * (Vercel Edge, Cloudflare Workers, AWS Lambda) — see L-086.
+ *
+ * Returns OutcomeResult with ok: false + stable reason on persistence
+ * failure. Never throws.
+ */
+declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -475,6 +498,23 @@ interface GetDefaultFallbackChainOpts {
      * legacy unfiltered behavior — preserves alpha.9 callers byte-for-byte.
      */
     reachability?: ReachabilityOpts;
+    /**
+     * alpha.20 E3: consumer-declared tool-orchestration shape. Currently
+     * only affects `archetype: 'hunt'`, where 'sequential' swaps the
+     * parallel-tool-tier-0 chain (Flash → Pro → Sonnet → Haiku) for a
+     * DeepSeek-tier-0 chain (V4-Pro → Flash → Sonnet) — DeepSeek's L-040
+     * parallel-tool cliff doesn't apply when the consumer commits to
+     * single-step orchestration.
+     *
+     * Other archetypes are NOT mode-aware in this release — they ship the
+     * same chain regardless of toolOrchestration. Future versions may
+     * extend mode-awareness to ask/generate/etc. when brain evidence
+     * supports it.
+     *
+     * Default (omitted or 'either'): parallel chain. Back-compat with all
+     * pre-alpha.20 callers.
+     */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
 }
 declare function getDefaultFallbackChain(opts: GetDefaultFallbackChainOpts): string[];
 /**
@@ -718,4 +758,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, type ArchetypePerfMap, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getArchetypePerfScore, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ApiKeys, type AppOracle, type ArchetypePerfMap, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getArchetypePerfScore, getDefaultFallbackChain, getReachabilityDiagnostic, getStarterChain, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

package/dist/index.js

@@ -56,6 +56,7 @@ __export(index_exports, {
   profileToRow: () => profileToRow,
   profilesByProvider: () => profilesByProvider,
   record: () => record,
+  recordOutcome: () => recordOutcome,
   resetTokenizer: () => resetTokenizer,
   resolvePricingAt: () => resolvePricingAt,
   resolveProviderKey: () => resolveProviderKey,
@@ -337,7 +338,11 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
   const mutations = [];
   const hints = { qualityWarning: [] };
   let nextIR = ir;
+  const sequentialMode = nextIR.constraints?.toolOrchestration === "sequential";
   for (const cliff of profile.cliffs) {
+    if (sequentialMode && cliff.reason.includes("L-040")) {
+      continue;
+    }
     let triggered = false;
     switch (cliff.metric) {
       case "input_tokens":
@@ -2087,8 +2092,19 @@ function compile(ir, opts = {}) {
     cacheableTokens: lowered.diagnostics.cacheableTokens,
     estimatedCacheSavingsUsd: lowered.diagnostics.estimatedCacheSavingsUsd,
     historyCacheableTokens: lowered.diagnostics.historyCacheableTokens,
-    historyTokensTotal: compressed.historyTokensTotal
+    historyTokensTotal: compressed.historyTokensTotal,
+    // alpha.20 E3: mirror the consumer's declared mode for Glass-Box +
+    // brain observability. Undefined when not declared (pre-alpha.20).
+    toolOrchestration: ir.constraints?.toolOrchestration
   };
+  if (ir.intent.archetype === "hunt" && ir.constraints?.toolOrchestration === "sequential") {
+    accumulatedMutations.push({
+      id: "sequential-mode-chain-selected",
+      source: "tool_orchestration",
+      passName: "compile",
+      description: "ir.constraints.toolOrchestration='sequential' selected the DeepSeek-tier-0 hunt chain overlay (L-040 parallel-tool cliff doesn't apply at single-step granularity)."
+    });
+  }
   const advisories = runAdvisor(
     ir,
     {
@@ -2352,7 +2368,9 @@ function registerCompile(appId, archetype, ir, result) {
     mutationsApplied: result.mutationsApplied.map((m) => m.id),
     startedAt: Date.now(),
     historyCacheableTokens: result.diagnostics.historyCacheableTokens,
-    historyTokensTotal: result.diagnostics.historyTokensTotal
+    historyTokensTotal: result.diagnostics.historyTokensTotal,
+    // alpha.20 E3: capture consumer's declared mode for the brain payload.
+    toolOrchestration: result.diagnostics.toolOrchestration
   });
 }
 async function record(input) {
@@ -2365,11 +2383,22 @@ async function record(input) {
   const config = activeConfig;
   const fetchFn = config.fetchImpl ?? fetch;
   const send = async () => {
+    let outcomeId;
     try {
       const res = await fetchFn(`${config.endpoint}/outcomes`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
+          // alpha.20: request the inserted row back so we can JOIN advisories
+          // to it via outcome_id. PostgREST returns the row when
+          // `Prefer: return=representation` is set; proxies that pass the
+          // header through (the recommended `const row = { ...body }` shape
+          // from OutcomePayload's forward-compat rule) will surface
+          // the row id. Proxies that don't (legacy / hand-rolled shapes)
+          // simply produce no parseable id → secondary advisory POST is
+          // skipped silently. Best-effort — primary outcome row is the
+          // load-bearing write.
+          Prefer: "return=representation",
           ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
         },
         body: JSON.stringify(payload)
@@ -2378,6 +2407,29 @@ async function record(input) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(`brain ${res.status}: ${text}`);
       }
+      outcomeId = await tryExtractOutcomeId(res);
+    } catch (err) {
+      (config.onError ?? defaultOnError2)(err);
+      return;
+    }
+    const advisories = input.advisories;
+    if (!advisories || advisories.length === 0) return;
+    if (outcomeId === void 0) return;
+    try {
+      const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
+      const res = await fetchFn(`${config.endpoint}/compile_outcome_advisories`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Prefer: "return=minimal",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(advisoryPayload)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        throw new Error(`brain advisories ${res.status}: ${text}`);
+      }
     } catch (err) {
       (config.onError ?? defaultOnError2)(err);
     }
@@ -2427,7 +2479,12 @@ function buildPayload(input, reg) {
     cost_usd_actual: costUsdActual,
     ttft_ms: input.ttftMs,
     history_cacheable_tokens: reg?.historyCacheableTokens,
-    history_tokens_at_compile: reg?.historyTokensTotal
+    history_tokens_at_compile: reg?.historyTokensTotal,
+    // alpha.20 E3: mirror consumer's declared tool-orchestration mode so
+    // the brain can measure per-mode model perf separately (DeepSeek in
+    // sequential vs parallel mode is two different stories — L-040).
+    // Null when consumer hadn't adopted the constraint yet.
+    tool_orchestration: reg?.toolOrchestration ?? null
   };
 }
 function computeCostUsd(modelId, tokensIn, tokensOut) {
@@ -2444,6 +2501,77 @@ function computeCostUsd(modelId, tokensIn, tokensOut) {
   const outUsd = tokensOut / 1e6 * profile.costOutputPer1m;
   return Math.round((inUsd + outUsd) * 1e6) / 1e6;
 }
+async function tryExtractOutcomeId(res) {
+  try {
+    const ct = res.headers?.get?.("content-type") ?? "";
+    if (ct && !ct.includes("application/json")) return void 0;
+    if (typeof res.json !== "function") return void 0;
+    const body = await res.json();
+    if (Array.isArray(body) && body.length > 0) {
+      const first = body[0];
+      const id = first?.id;
+      if (typeof id === "number") return id;
+    } else if (body && typeof body === "object") {
+      const id = body.id;
+      if (typeof id === "number") return id;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function buildAdvisoryRow(outcomeId, a) {
+  return {
+    outcome_id: outcomeId,
+    code: a.code,
+    level: a.level,
+    message: a.message,
+    ...a.recommendationType ? { recommendation_type: a.recommendationType } : {},
+    ...a.suggestion ? { suggestion: a.suggestion } : {},
+    ...a.docsUrl ? { docs_url: a.docsUrl } : {}
+  };
+}
+async function recordOutcome(input) {
+  if (!activeConfig) {
+    return { ok: false, reason: "brain_not_configured" };
+  }
+  const config = activeConfig;
+  const fetchFn = config.fetchImpl ?? fetch;
+  const payload = {
+    outcome_id: input.outcomeId,
+    outcome: input.outcome,
+    rating: input.rating ?? null,
+    reason: input.reason ?? null,
+    observed_confidence: input.observedConfidence ?? null
+  };
+  const send = async () => {
+    try {
+      const res = await fetchFn(`${config.endpoint}/compile_outcome_quality`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        const err = new Error(`brain ${res.status}: ${text}`);
+        (config.onError ?? defaultOnError2)(err);
+        return { ok: false, reason: "persistence_failed" };
+      }
+      return { ok: true };
+    } catch (err) {
+      (config.onError ?? defaultOnError2)(err);
+      return { ok: false, reason: "persistence_failed" };
+    }
+  };
+  if (config.sync) {
+    return send();
+  }
+  void send();
+  return { ok: true };
+}
 
 // src/ir.ts
 var CallError = class extends Error {
@@ -2823,7 +2951,10 @@ var STARTER_CHAINS = {
   ],
   // Parallel-tool throughput champion (Flash, L-040). Tier 1 cross-provider
   // Pro; tier 2 Sonnet (quality safety net for blocked-Flash case); tier 3
-  // Haiku (reduced tool budget — cliff at 16 fires).
+  // Haiku (reduced tool budget — cliff at 16 fires). This is the
+  // `toolOrchestration: 'parallel'` (default) hunt chain. The sequential
+  // variant lives in STARTER_CHAINS_BY_MODE.hunt.sequential below — see
+  // alpha.20 E3 / interfaces/kgauto.md `sequential-agentic-hunt-mode`.
   hunt: [
     "gemini-2.5-flash",
     "gemini-2.5-pro",
@@ -2847,15 +2978,37 @@ var STARTER_CHAINS = {
     "gemini-2.5-flash-lite"
   ]
 };
+var STARTER_CHAINS_BY_MODE = {
+  hunt: {
+    sequential: [
+      // V4-Pro: cheap + good reasoning at single-step granularity; no
+      // L-040 cliff applies when consumer commits to sequential.
+      "deepseek-v4-pro",
+      // V4-Flash: cheapest viable; sibling-provider fallback.
+      "deepseek-v4-flash",
+      // Cross-provider safety net — Sonnet handles sequential agentic loops
+      // cleanly; Pro as third-provider tail when no DeepSeek key reachable.
+      "claude-sonnet-4-6",
+      "gemini-2.5-pro"
+    ]
+  }
+};
+function resolveStarterForMode(archetype, toolOrchestration, allChains) {
+  if (toolOrchestration === "sequential") {
+    const overlay = STARTER_CHAINS_BY_MODE[archetype]?.sequential;
+    if (overlay) return [...overlay];
+  }
+  return allChains[archetype];
+}
 function getDefaultFallbackChain(opts) {
-  const { archetype, primary, maxDepth = 3, policy, reachability } = opts;
+  const { archetype, primary, maxDepth = 3, policy, reachability, toolOrchestration } = opts;
   if (maxDepth < 1) {
     throw new Error(
       `getDefaultFallbackChain: maxDepth must be >= 1, got ${maxDepth}`
     );
   }
   const allChains = loadChainsFromBrain();
-  const starter = allChains[archetype];
+  const starter = resolveStarterForMode(archetype, toolOrchestration, allChains);
   if (!starter) {
     throw new Error(
       `getDefaultFallbackChain: unknown archetype "${archetype}". Known: ${Object.keys(allChains).join(", ")}`
@@ -3832,6 +3985,7 @@ function compile2(ir, opts) {
   profileToRow,
   profilesByProvider,
   record,
+  recordOutcome,
   resetTokenizer,
   resolvePricingAt,
   resolveProviderKey,

package/dist/index.mjs

@@ -215,7 +215,11 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
   const mutations = [];
   const hints = { qualityWarning: [] };
   let nextIR = ir;
+  const sequentialMode = nextIR.constraints?.toolOrchestration === "sequential";
   for (const cliff of profile.cliffs) {
+    if (sequentialMode && cliff.reason.includes("L-040")) {
+      continue;
+    }
     let triggered = false;
     switch (cliff.metric) {
       case "input_tokens":
@@ -891,8 +895,19 @@ function compile(ir, opts = {}) {
     cacheableTokens: lowered.diagnostics.cacheableTokens,
     estimatedCacheSavingsUsd: lowered.diagnostics.estimatedCacheSavingsUsd,
     historyCacheableTokens: lowered.diagnostics.historyCacheableTokens,
-    historyTokensTotal: compressed.historyTokensTotal
+    historyTokensTotal: compressed.historyTokensTotal,
+    // alpha.20 E3: mirror the consumer's declared mode for Glass-Box +
+    // brain observability. Undefined when not declared (pre-alpha.20).
+    toolOrchestration: ir.constraints?.toolOrchestration
   };
+  if (ir.intent.archetype === "hunt" && ir.constraints?.toolOrchestration === "sequential") {
+    accumulatedMutations.push({
+      id: "sequential-mode-chain-selected",
+      source: "tool_orchestration",
+      passName: "compile",
+      description: "ir.constraints.toolOrchestration='sequential' selected the DeepSeek-tier-0 hunt chain overlay (L-040 parallel-tool cliff doesn't apply at single-step granularity)."
+    });
+  }
   const advisories = runAdvisor(
     ir,
     {
@@ -1156,7 +1171,9 @@ function registerCompile(appId, archetype, ir, result) {
     mutationsApplied: result.mutationsApplied.map((m) => m.id),
     startedAt: Date.now(),
     historyCacheableTokens: result.diagnostics.historyCacheableTokens,
-    historyTokensTotal: result.diagnostics.historyTokensTotal
+    historyTokensTotal: result.diagnostics.historyTokensTotal,
+    // alpha.20 E3: capture consumer's declared mode for the brain payload.
+    toolOrchestration: result.diagnostics.toolOrchestration
   });
 }
 async function record(input) {
@@ -1169,11 +1186,22 @@ async function record(input) {
   const config = activeConfig;
   const fetchFn = config.fetchImpl ?? fetch;
   const send = async () => {
+    let outcomeId;
     try {
       const res = await fetchFn(`${config.endpoint}/outcomes`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
+          // alpha.20: request the inserted row back so we can JOIN advisories
+          // to it via outcome_id. PostgREST returns the row when
+          // `Prefer: return=representation` is set; proxies that pass the
+          // header through (the recommended `const row = { ...body }` shape
+          // from OutcomePayload's forward-compat rule) will surface
+          // the row id. Proxies that don't (legacy / hand-rolled shapes)
+          // simply produce no parseable id → secondary advisory POST is
+          // skipped silently. Best-effort — primary outcome row is the
+          // load-bearing write.
+          Prefer: "return=representation",
           ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
         },
         body: JSON.stringify(payload)
@@ -1182,6 +1210,29 @@ async function record(input) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(`brain ${res.status}: ${text}`);
       }
+      outcomeId = await tryExtractOutcomeId(res);
+    } catch (err) {
+      (config.onError ?? defaultOnError2)(err);
+      return;
+    }
+    const advisories = input.advisories;
+    if (!advisories || advisories.length === 0) return;
+    if (outcomeId === void 0) return;
+    try {
+      const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
+      const res = await fetchFn(`${config.endpoint}/compile_outcome_advisories`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Prefer: "return=minimal",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(advisoryPayload)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        throw new Error(`brain advisories ${res.status}: ${text}`);
+      }
     } catch (err) {
       (config.onError ?? defaultOnError2)(err);
     }
@@ -1231,7 +1282,12 @@ function buildPayload(input, reg) {
     cost_usd_actual: costUsdActual,
     ttft_ms: input.ttftMs,
     history_cacheable_tokens: reg?.historyCacheableTokens,
-    history_tokens_at_compile: reg?.historyTokensTotal
+    history_tokens_at_compile: reg?.historyTokensTotal,
+    // alpha.20 E3: mirror consumer's declared tool-orchestration mode so
+    // the brain can measure per-mode model perf separately (DeepSeek in
+    // sequential vs parallel mode is two different stories — L-040).
+    // Null when consumer hadn't adopted the constraint yet.
+    tool_orchestration: reg?.toolOrchestration ?? null
   };
 }
 function computeCostUsd(modelId, tokensIn, tokensOut) {
@@ -1248,6 +1304,77 @@ function computeCostUsd(modelId, tokensIn, tokensOut) {
   const outUsd = tokensOut / 1e6 * profile.costOutputPer1m;
   return Math.round((inUsd + outUsd) * 1e6) / 1e6;
 }
+async function tryExtractOutcomeId(res) {
+  try {
+    const ct = res.headers?.get?.("content-type") ?? "";
+    if (ct && !ct.includes("application/json")) return void 0;
+    if (typeof res.json !== "function") return void 0;
+    const body = await res.json();
+    if (Array.isArray(body) && body.length > 0) {
+      const first = body[0];
+      const id = first?.id;
+      if (typeof id === "number") return id;
+    } else if (body && typeof body === "object") {
+      const id = body.id;
+      if (typeof id === "number") return id;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function buildAdvisoryRow(outcomeId, a) {
+  return {
+    outcome_id: outcomeId,
+    code: a.code,
+    level: a.level,
+    message: a.message,
+    ...a.recommendationType ? { recommendation_type: a.recommendationType } : {},
+    ...a.suggestion ? { suggestion: a.suggestion } : {},
+    ...a.docsUrl ? { docs_url: a.docsUrl } : {}
+  };
+}
+async function recordOutcome(input) {
+  if (!activeConfig) {
+    return { ok: false, reason: "brain_not_configured" };
+  }
+  const config = activeConfig;
+  const fetchFn = config.fetchImpl ?? fetch;
+  const payload = {
+    outcome_id: input.outcomeId,
+    outcome: input.outcome,
+    rating: input.rating ?? null,
+    reason: input.reason ?? null,
+    observed_confidence: input.observedConfidence ?? null
+  };
+  const send = async () => {
+    try {
+      const res = await fetchFn(`${config.endpoint}/compile_outcome_quality`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        const err = new Error(`brain ${res.status}: ${text}`);
+        (config.onError ?? defaultOnError2)(err);
+        return { ok: false, reason: "persistence_failed" };
+      }
+      return { ok: true };
+    } catch (err) {
+      (config.onError ?? defaultOnError2)(err);
+      return { ok: false, reason: "persistence_failed" };
+    }
+  };
+  if (config.sync) {
+    return send();
+  }
+  void send();
+  return { ok: true };
+}
 
 // src/ir.ts
 var CallError = class extends Error {
@@ -1627,7 +1754,10 @@ var STARTER_CHAINS = {
   ],
   // Parallel-tool throughput champion (Flash, L-040). Tier 1 cross-provider
   // Pro; tier 2 Sonnet (quality safety net for blocked-Flash case); tier 3
-  // Haiku (reduced tool budget — cliff at 16 fires).
+  // Haiku (reduced tool budget — cliff at 16 fires). This is the
+  // `toolOrchestration: 'parallel'` (default) hunt chain. The sequential
+  // variant lives in STARTER_CHAINS_BY_MODE.hunt.sequential below — see
+  // alpha.20 E3 / interfaces/kgauto.md `sequential-agentic-hunt-mode`.
   hunt: [
     "gemini-2.5-flash",
     "gemini-2.5-pro",
@@ -1651,15 +1781,37 @@ var STARTER_CHAINS = {
     "gemini-2.5-flash-lite"
   ]
 };
+var STARTER_CHAINS_BY_MODE = {
+  hunt: {
+    sequential: [
+      // V4-Pro: cheap + good reasoning at single-step granularity; no
+      // L-040 cliff applies when consumer commits to sequential.
+      "deepseek-v4-pro",
+      // V4-Flash: cheapest viable; sibling-provider fallback.
+      "deepseek-v4-flash",
+      // Cross-provider safety net — Sonnet handles sequential agentic loops
+      // cleanly; Pro as third-provider tail when no DeepSeek key reachable.
+      "claude-sonnet-4-6",
+      "gemini-2.5-pro"
+    ]
+  }
+};
+function resolveStarterForMode(archetype, toolOrchestration, allChains) {
+  if (toolOrchestration === "sequential") {
+    const overlay = STARTER_CHAINS_BY_MODE[archetype]?.sequential;
+    if (overlay) return [...overlay];
+  }
+  return allChains[archetype];
+}
 function getDefaultFallbackChain(opts) {
-  const { archetype, primary, maxDepth = 3, policy, reachability } = opts;
+  const { archetype, primary, maxDepth = 3, policy, reachability, toolOrchestration } = opts;
   if (maxDepth < 1) {
     throw new Error(
       `getDefaultFallbackChain: maxDepth must be >= 1, got ${maxDepth}`
     );
   }
   const allChains = loadChainsFromBrain();
-  const starter = allChains[archetype];
+  const starter = resolveStarterForMode(archetype, toolOrchestration, allChains);
   if (!starter) {
     throw new Error(
       `getDefaultFallbackChain: unknown archetype "${archetype}". Known: ${Object.keys(allChains).join(", ")}`
@@ -2347,6 +2499,7 @@ export {
   profileToRow,
   profilesByProvider,
   record,
+  recordOutcome,
   resetTokenizer,
   resolvePricingAt,
   resolveProviderKey,

package/dist/{ir-CFHU3BUT.d.ts → ir-CsTU4cMB.d.ts}

@@ -90,6 +90,29 @@ interface Constraints {
     maxResponseWords?: number;
     /** Override target model selection — if set, compiler uses this instead of routing. */
     forceModel?: string;
+    /**
+     * alpha.20: consumer-declared tool-orchestration shape for this call.
+     * - 'parallel': model may fire multiple tool calls per step (current
+     *   default behavior; the L-040 cliff applies — DeepSeek's
+     *   `tool_count >= 1` cliff trims tools because parallel-tool throughput
+     *   collapses to sequential semantics).
+     * - 'sequential': consumer commits to one tool call per step (the agentic
+     *   loop pattern). DeepSeek V4-Flash + V4-Pro can compete cleanly in
+     *   this mode — the L-040 cliff is silenced and the hunt chain shifts
+     *   to a DeepSeek-tier-1 ordering.
+     * - 'either': consumer doesn't care; library picks the parallel chain
+     *   (status-quo default) and may upgrade to brain-driven per-mode perf
+     *   selection in a future release.
+     *
+     * Affects:
+     *   - Chain composition for `archetype: 'hunt'` (see
+     *     `getDefaultFallbackChain` and `STARTER_CHAINS_BY_MODE`).
+     *   - L-040 cliff in `passApplyCliffs` (silent when 'sequential').
+     *
+     * Default (when undefined): equivalent to 'parallel' for back-compat
+     * with every pre-alpha.20 caller.
+     */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
 }
 /**
  * Cache marker policy for the messages array (history + currentTurn).
@@ -308,6 +331,21 @@ interface BestPracticeAdvisory {
     suggestion?: string;
     /** Optional: link to docs anchor for more context. */
     docsUrl?: string;
+    /**
+     * alpha.20 — actionable category for routing/dashboard surfacing. When set,
+     * the brain persists this as `recommendation_type` on
+     * `compile_outcome_advisories` so consumers can filter "show me all
+     * client-side issues that are caching-fix recommendations." Optional;
+     * absent on legacy or uncategorized rules.
+     *
+     * - `'model-swap'`          — swap to a different model fixes this
+     * - `'prompt-fix'`          — restructure prompt (sections, tools, format)
+     * - `'caching-fix'`         — add cache markers (system or history)
+     * - `'no-ai-needed'`        — the call shouldn't be using an AI model
+     * - `'tier-down'`           — current model is overkill for this archetype
+     * - `'architecture-change'` — the issue isn't fixable at the kgauto layer
+     */
+    recommendationType?: 'model-swap' | 'prompt-fix' | 'caching-fix' | 'no-ai-needed' | 'tier-down' | 'architecture-change';
 }
 interface CompileResult {
     /** Unique handle for this call — pass to record() to correlate the outcome. */
@@ -359,6 +397,14 @@ interface CompileResult {
          * 0 when history is empty. alpha.7.
          */
         historyTokensTotal: number;
+        /**
+         * alpha.20 E3. Consumer-declared tool-orchestration mode for this call,
+         * mirrored from `ir.constraints.toolOrchestration` for downstream
+         * observability (Glass-Box panel, brain telemetry, advisor logs).
+         * Undefined when the consumer hadn't adopted the constraint yet —
+         * treat as 'parallel' equivalent for back-compat.
+         */
+        toolOrchestration?: 'parallel' | 'sequential' | 'either';
     };
 }
 /**
@@ -634,6 +680,66 @@ interface RecordInput {
      * surfaces it. Distinct from `latencyMs` (end-to-end wall clock).
      */
     ttftMs?: number;
+    /**
+     * alpha.20 — advisories fired at compile() time. Persisted to the brain's
+     * `compile_outcome_advisories` sibling table via a second POST that fires
+     * AFTER the primary outcome insert succeeds. Best-effort: a failed
+     * advisory POST is logged via onError but does NOT throw or roll back the
+     * primary outcome row.
+     *
+     * Pass `result.advisories` from the CompileResult directly. The brain
+     * uses these to compute the `empty_rate_clean` comparator (rows with
+     * zero advisories fired) so consumers can distinguish "model is bad"
+     * from "client sent a bloated/uncached/malformed request."
+     *
+     * Empty array / undefined → no second POST fires.
+     */
+    advisories?: BestPracticeAdvisory[];
+}
+/**
+ * alpha.20 Entry 4: kinds of consumer-declared outcomes feeding the quality
+ * loop. Surfaces in `recordOutcome()` as the verdict the consumer's UX is
+ * forwarding to the brain.
+ *
+ *   - `approved`  user explicitly approved (thumbs up, "looks good", accepted)
+ *   - `rejected`  user explicitly rejected (thumbs down, "redo", discarded)
+ *   - `partial`   accepted with edits or partial use (mixed signal)
+ *   - `engaged`   user engaged with the output (copy/scroll/dwell)
+ *   - `abandoned` user abandoned the response (closed, navigated away)
+ *   - `unknown`   verdict could not be inferred — recorded for completeness
+ */
+type OutcomeKind = 'approved' | 'rejected' | 'partial' | 'engaged' | 'abandoned' | 'unknown';
+/**
+ * Input to `recordOutcome()` — consumer's verdict on a previously-compiled
+ * call. Joins to the original `compile_outcomes` row via outcomeId,
+ * enabling per-(model, archetype) approve-rate measurement once N ≥ 10
+ * outcomes accumulate.
+ */
+interface RecordOutcomeInput {
+    /** Joins to compile_outcomes.id. Returned by compile() via CompileResult.outcomeId. */
+    outcomeId: number | string;
+    /** What did the user / system do with this output? */
+    outcome: OutcomeKind;
+    /** Optional 1-5 user rating (e.g., thumbs up/down with intensity, NPS-style). */
+    rating?: 1 | 2 | 3 | 4 | 5;
+    /** Optional free-text reason (e.g., user-typed feedback, system-inferred cause). */
+    reason?: string;
+    /**
+     * Optional model-reported confidence at compile time (0..1). Used for
+     * Brier-score calibration in later phases (alpha.21+) — pair this with
+     * the actual `outcome` to compute calibration error.
+     */
+    observedConfidence?: number;
+}
+/**
+ * Return shape of `recordOutcome()`. Never throws — persistence failures
+ * surface as `ok: false` with a stable `reason` string.
+ */
+interface OutcomeResult {
+    /** True when the POST landed (2xx). False when brain not configured or POST failed. */
+    ok: boolean;
+    /** Stable reason code when ok=false. One of: 'brain_not_configured' | 'persistence_failed'. */
+    reason?: string;
 }
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OracleScore as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type Provider as f, type CallAttempt as g, CallError as h, type Constraints as i, type MutationApplied as j, type NormalizedTokens as k, type PromptSection as l, type ToolDefinition as m };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Provider as h, type CallAttempt as i, CallError as j, type Constraints as k, type MutationApplied as l, type NormalizedTokens as m, type OutcomeKind as n, type PromptSection as o, type ToolDefinition as p };

package/dist/{ir-C3P4gDt0.d.mts → ir-DTMbSnyE.d.mts}

@@ -90,6 +90,29 @@ interface Constraints {
     maxResponseWords?: number;
     /** Override target model selection — if set, compiler uses this instead of routing. */
     forceModel?: string;
+    /**
+     * alpha.20: consumer-declared tool-orchestration shape for this call.
+     * - 'parallel': model may fire multiple tool calls per step (current
+     *   default behavior; the L-040 cliff applies — DeepSeek's
+     *   `tool_count >= 1` cliff trims tools because parallel-tool throughput
+     *   collapses to sequential semantics).
+     * - 'sequential': consumer commits to one tool call per step (the agentic
+     *   loop pattern). DeepSeek V4-Flash + V4-Pro can compete cleanly in
+     *   this mode — the L-040 cliff is silenced and the hunt chain shifts
+     *   to a DeepSeek-tier-1 ordering.
+     * - 'either': consumer doesn't care; library picks the parallel chain
+     *   (status-quo default) and may upgrade to brain-driven per-mode perf
+     *   selection in a future release.
+     *
+     * Affects:
+     *   - Chain composition for `archetype: 'hunt'` (see
+     *     `getDefaultFallbackChain` and `STARTER_CHAINS_BY_MODE`).
+     *   - L-040 cliff in `passApplyCliffs` (silent when 'sequential').
+     *
+     * Default (when undefined): equivalent to 'parallel' for back-compat
+     * with every pre-alpha.20 caller.
+     */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
 }
 /**
  * Cache marker policy for the messages array (history + currentTurn).
@@ -308,6 +331,21 @@ interface BestPracticeAdvisory {
     suggestion?: string;
     /** Optional: link to docs anchor for more context. */
     docsUrl?: string;
+    /**
+     * alpha.20 — actionable category for routing/dashboard surfacing. When set,
+     * the brain persists this as `recommendation_type` on
+     * `compile_outcome_advisories` so consumers can filter "show me all
+     * client-side issues that are caching-fix recommendations." Optional;
+     * absent on legacy or uncategorized rules.
+     *
+     * - `'model-swap'`          — swap to a different model fixes this
+     * - `'prompt-fix'`          — restructure prompt (sections, tools, format)
+     * - `'caching-fix'`         — add cache markers (system or history)
+     * - `'no-ai-needed'`        — the call shouldn't be using an AI model
+     * - `'tier-down'`           — current model is overkill for this archetype
+     * - `'architecture-change'` — the issue isn't fixable at the kgauto layer
+     */
+    recommendationType?: 'model-swap' | 'prompt-fix' | 'caching-fix' | 'no-ai-needed' | 'tier-down' | 'architecture-change';
 }
 interface CompileResult {
     /** Unique handle for this call — pass to record() to correlate the outcome. */
@@ -359,6 +397,14 @@ interface CompileResult {
          * 0 when history is empty. alpha.7.
          */
         historyTokensTotal: number;
+        /**
+         * alpha.20 E3. Consumer-declared tool-orchestration mode for this call,
+         * mirrored from `ir.constraints.toolOrchestration` for downstream
+         * observability (Glass-Box panel, brain telemetry, advisor logs).
+         * Undefined when the consumer hadn't adopted the constraint yet —
+         * treat as 'parallel' equivalent for back-compat.
+         */
+        toolOrchestration?: 'parallel' | 'sequential' | 'either';
     };
 }
 /**
@@ -634,6 +680,66 @@ interface RecordInput {
      * surfaces it. Distinct from `latencyMs` (end-to-end wall clock).
      */
     ttftMs?: number;
+    /**
+     * alpha.20 — advisories fired at compile() time. Persisted to the brain's
+     * `compile_outcome_advisories` sibling table via a second POST that fires
+     * AFTER the primary outcome insert succeeds. Best-effort: a failed
+     * advisory POST is logged via onError but does NOT throw or roll back the
+     * primary outcome row.
+     *
+     * Pass `result.advisories` from the CompileResult directly. The brain
+     * uses these to compute the `empty_rate_clean` comparator (rows with
+     * zero advisories fired) so consumers can distinguish "model is bad"
+     * from "client sent a bloated/uncached/malformed request."
+     *
+     * Empty array / undefined → no second POST fires.
+     */
+    advisories?: BestPracticeAdvisory[];
+}
+/**
+ * alpha.20 Entry 4: kinds of consumer-declared outcomes feeding the quality
+ * loop. Surfaces in `recordOutcome()` as the verdict the consumer's UX is
+ * forwarding to the brain.
+ *
+ *   - `approved`  user explicitly approved (thumbs up, "looks good", accepted)
+ *   - `rejected`  user explicitly rejected (thumbs down, "redo", discarded)
+ *   - `partial`   accepted with edits or partial use (mixed signal)
+ *   - `engaged`   user engaged with the output (copy/scroll/dwell)
+ *   - `abandoned` user abandoned the response (closed, navigated away)
+ *   - `unknown`   verdict could not be inferred — recorded for completeness
+ */
+type OutcomeKind = 'approved' | 'rejected' | 'partial' | 'engaged' | 'abandoned' | 'unknown';
+/**
+ * Input to `recordOutcome()` — consumer's verdict on a previously-compiled
+ * call. Joins to the original `compile_outcomes` row via outcomeId,
+ * enabling per-(model, archetype) approve-rate measurement once N ≥ 10
+ * outcomes accumulate.
+ */
+interface RecordOutcomeInput {
+    /** Joins to compile_outcomes.id. Returned by compile() via CompileResult.outcomeId. */
+    outcomeId: number | string;
+    /** What did the user / system do with this output? */
+    outcome: OutcomeKind;
+    /** Optional 1-5 user rating (e.g., thumbs up/down with intensity, NPS-style). */
+    rating?: 1 | 2 | 3 | 4 | 5;
+    /** Optional free-text reason (e.g., user-typed feedback, system-inferred cause). */
+    reason?: string;
+    /**
+     * Optional model-reported confidence at compile time (0..1). Used for
+     * Brier-score calibration in later phases (alpha.21+) — pair this with
+     * the actual `outcome` to compute calibration error.
+     */
+    observedConfidence?: number;
+}
+/**
+ * Return shape of `recordOutcome()`. Never throws — persistence failures
+ * surface as `ok: false` with a stable `reason` string.
+ */
+interface OutcomeResult {
+    /** True when the POST landed (2xx). False when brain not configured or POST failed. */
+    ok: boolean;
+    /** Stable reason code when ok=false. One of: 'brain_not_configured' | 'persistence_failed'. */
+    reason?: string;
 }
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OracleScore as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type Provider as f, type CallAttempt as g, CallError as h, type Constraints as i, type MutationApplied as j, type NormalizedTokens as k, type PromptSection as l, type ToolDefinition as m };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Provider as h, type CallAttempt as i, CallError as j, type Constraints as k, type MutationApplied as l, type NormalizedTokens as m, type OutcomeKind as n, type PromptSection as o, type ToolDefinition as p };

package/dist/profiles.d.mts

@@ -1,4 +1,4 @@
-import { f as Provider } from './ir-C3P4gDt0.mjs';
+import { h as Provider } from './ir-DTMbSnyE.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**

package/dist/profiles.d.ts

@@ -1,4 +1,4 @@
-import { f as Provider } from './ir-CFHU3BUT.js';
+import { h as Provider } from './ir-CsTU4cMB.js';
 import { IntentArchetypeName } from './dialect.js';
 
 /**

package/dist/{types-DWF6mPGg.d.mts → types-BYj1Kl2m.d.mts}

@@ -1,4 +1,4 @@
-import { j as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, g as CallAttempt } from './ir-C3P4gDt0.mjs';
+import { l as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, i as CallAttempt } from './ir-DTMbSnyE.mjs';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-xeklorHU.d.ts → types-CwtaDaWN.d.ts}

@@ -1,4 +1,4 @@
-import { j as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, g as CallAttempt } from './ir-CFHU3BUT.js';
+import { l as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, i as CallAttempt } from './ir-CsTU4cMB.js';
 
 /**
  * Glass-Box observability types (alpha.17).

package/package.json

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