@warmdrift/kgauto-compiler 2.0.0-alpha.60 → 2.0.0-alpha.61

package/README.md

@@ -1,28 +1,48 @@
-# @warmdrift/kgauto-compiler — v2.0.0-alpha.6
+# @warmdrift/kgauto-compiler — v2 (alpha)
 
-> Prompt compiler + central learning brain for multi-model AI apps.
+> Prompt compiler with executable provider knowledge for multi-model AI apps.
 > **Swap models without rewriting prompts.**
 
-Greenfield rewrite of `@warmdrift/kgauto` v1. v1 was a behavioral patcher
-with telemetry; v2 is a real prompt compiler with a self-improving learning
-layer designed for cross-app pollination.
-
-The "compiler" name is deliberate — every optimization is a pass on a
-structured Intermediate Representation (IR), not string surgery on a
-rendered prompt. This unlocks slicing, dedupe, intent-aware tool relevance,
-target-correct lowering with cache markers, and (in v2.1) outcome-driven
-mutations.
+What this package delivers today, and nothing it doesn't:
+
+- **A prompt compiler** — every optimization is a pass on a structured
+  Intermediate Representation (IR), not string surgery on a rendered prompt:
+  slicing, dedupe, intent-aware tool relevance, history compression,
+  target-correct lowering with cache markers.
+- **Executable provider knowledge** — model cliffs, lowering rules, and
+  recovery handlers as code that fires at compile time, curated against
+  provider docs with grounding labels. Seven-plus frontier model transitions
+  absorbed centrally with zero consumer prompt rewrites.
+- **Normalized multi-provider transport** — `call()` walks a fallback chain
+  across Anthropic / Google / OpenAI / DeepSeek with a provider-error
+  taxonomy (429 / 404 / 401-auth-walk / parse-fail / MAX_TOKENS), recompiling
+  per fallback target. (Scope: the `call()` path. Streaming consumers drive
+  their own wire and get compile-time guards, not transport resilience.)
+- **A flight recorder** — opt-in telemetry (`record()` / `probeShadow()` /
+  key-health) that has repeatedly caught real production defects: empty-response
+  cliffs, dead API keys, cache-miss regressions, silent model deprecations.
+- **A curated model registry** — capability + pricing data with verification
+  stamps, a release watcher, and price-truth test gates.
+
+**What it does not do (yet):** routing does not change itself from measured
+outcomes. There is no automatic learning loop in the shipped package — model
+promotion is evidence-*informed* but operator-*driven*. The eval-driven
+quality-floor-guarded swap architecture is specced (2026-07-17) and is the
+current engineering arc; the learning claims return to this README when they
+are code, not before.
+
+Greenfield rewrite of `@warmdrift/kgauto` v1 (a behavioral patcher with
+telemetry).
 
 ## Status
 
-- **Package:** alpha — coexists with v1 (`@warmdrift/kgauto@1.2.0`) under
-  the temporary name `@warmdrift/kgauto-compiler`. Renames to v2 final once
-  v1 is fully retired from production.
-- **Tests:** 201/201 passing
-- **Build:** clean (47KB ESM, 68KB CJS)
-- **Brain:** schema ready (see `brain/migrations/001_initial_schema.sql`);
-  awaiting dedicated Supabase provisioning.
-- **Mutation engine:** v2.1 (after enough outcome data accumulates).
+- **Package:** alpha — coexists with v1 (`@warmdrift/kgauto`) under the
+  temporary name `@warmdrift/kgauto-compiler`. Renames to v2 final once v1
+  is fully retired from production.
+- **Tests:** 1400+ passing (see CI for the current count)
+- **Brain:** live multi-tenant Supabase substrate (telemetry + curated
+  config tables), consumed by four production apps.
+- **Learning engine:** not shipped. See "What's next."
 
 ## Quickstart
 
@@ -203,10 +223,10 @@ APP (any consumer)
   └── kg.record(handle, outcome) ── async POST to brain
 
 BRAIN (centralized Supabase)
-  ├── compile_outcomes (multi-tenant from day 1)
-  ├── mutations (active rules — empty in v2.0; engine in v2.1)
-  ├── apps (consumer registry)
-  └── digest_runs (weekly summary audit trail)
+  ├── compile_outcomes (multi-tenant telemetry)
+  ├── probe_outcomes / compile_outcome_quality (shadow-probe + quality rows)
+  ├── kgauto_models / kgauto_chains / kgauto_pricing (curated config, operator-maintained)
+  └── apps (consumer registry)
 ```
 
 ## Dialect-v1 (cross-app vocabulary)
@@ -216,12 +236,10 @@ Apps tag every call with an **intent archetype** (`ask`, `hunt`, `classify`,
 compiler computes a **shape signature** (context bucket × tool count × history
 depth × output mode × examples flag).
 
-The `(archetype, model, shape)` tuple is the **learning key**. Apps that
-declare the same tuple inherit each other's mutations — even apps that have
-never seen each other's data.
-
-That's how *"what works for the dashboard, should be insights for the next
-dashboard"* becomes mechanical instead of aspirational.
+The `(archetype, model, shape)` tuple is the **learning key** — the shared
+grouping vocabulary for telemetry aggregation across apps. It is the
+substrate a future cross-app learning engine would key on; today it powers
+per-tuple cost/latency observability, nothing more.
 
 ## Profiles — executable model knowledge
 
@@ -308,27 +326,26 @@ is a `pg_dump` away.
 
 ## What's next
 
-- **v2.0.x:** real-app integrations (tt-intelligence, inspire-central,
-  playbacksam, inspirato/incantato). Brain accumulates outcome data.
-- **v2.1:** mutation engine. Shadow-test → statistical gate → promote → auto-rollback.
-- **v2.2:** weekly digest reporting back to the operator.
-- **v2.x:** dialect-v2 expanded with archetypes that emerge from real usage.
+The current arc (specced 2026-07-17, after an adversarial promise review)
+is **eval-driven quality-floor-guarded model swap**: golden sets of real
+IRs per consumer surface, a pairwise judge archetype, a non-inferiority
+promotion rule, and a rollback guard — evidence generated on demand instead
+of waiting for organic traffic volume that doesn't exist. A model replaces
+another on a surface only by demonstrating same-or-better quality on that
+surface's real workload. Each stage lands in this README **when it ships**,
+with its gate evidence — the promise follows the code.
 
 ## Why this exists
 
 The previous version (v1) treated prompts as opaque strings and could only
-*append* behavioral patches. It also tried to learn quality from structural
-signals (token counts) — but quality is semantic, not structural.
-
-v2 treats prompts as structured IR, makes every model-specific quirk
-*executable* (cliffs, lowering, recovery), and makes oracle scoring a
-first-class contract — so the brain learns from quality data, not its proxies.
-
-The whole point: every multi-model AI app needs a compiler. Building it
-inline ships one app's value. Building it portable with a shared brain
-ships every app's value to every other app.
-
-Communicating vessels — finally accurate to the name.
+*append* behavioral patches. v2 treats prompts as structured IR and makes
+every model-specific quirk *executable* (cliffs, lowering, recovery).
+
+The felt pain this solves is real and recurring: every frontier model
+release, deprecation, price change, or silent alias flip lands on every
+multi-model app at once. Building the absorption layer inline ships one
+app's fix. Building it portable — one compiler, one curated registry, one
+watcher set, one telemetry substrate — ships the fix to every app at once.
 
 ## License
 

package/dist/{chunk-RQ3BUUB6.mjs → chunk-3RMLZCUK.mjs}

@@ -1,5 +1,5 @@
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.60";
+var LIBRARY_VERSION = "2.0.0-alpha.61";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/glassbox/index.d.mts

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

package/dist/glassbox/index.d.ts

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

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

@@ -1,5 +1,5 @@
-import { T as TraceHealth } from '../types-B-pzBJKf.mjs';
-import '../ir-BC4uDL98.mjs';
+import { T as TraceHealth } from '../types-MRMBUqzY.mjs';
+import '../ir-DAKlQsVb.mjs';
 import '../dialect.mjs';
 
 /**

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

@@ -1,5 +1,5 @@
-import { T as TraceHealth } from '../types-CKuu7Clz.js';
-import '../ir-B2h0GAEL.js';
+import { T as TraceHealth } from '../types-B8X1Pyhx.js';
+import '../ir-DmUuJsWc.js';
 import '../dialect.js';
 
 /**

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

@@ -1,7 +1,7 @@
-import { G as GlassboxEvent } from '../types-CRy90cjp.mjs';
-import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-B-pzBJKf.mjs';
-export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-B-pzBJKf.mjs';
-import '../ir-BC4uDL98.mjs';
+import { G as GlassboxEvent } from '../types-CssWqd0X.mjs';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-MRMBUqzY.mjs';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-MRMBUqzY.mjs';
+import '../ir-DAKlQsVb.mjs';
 import '../dialect.mjs';
 
 /**

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

@@ -1,7 +1,7 @@
-import { G as GlassboxEvent } from '../types-CsB2YASc.js';
-import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-CKuu7Clz.js';
-export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-CKuu7Clz.js';
-import '../ir-B2h0GAEL.js';
+import { G as GlassboxEvent } from '../types-DR62iPcO.js';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-B8X1Pyhx.js';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-B8X1Pyhx.js';
+import '../ir-DmUuJsWc.js';
 import '../dialect.js';
 
 /**

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-B-pzBJKf.mjs';
-import '../../ir-BC4uDL98.mjs';
+import { a as TraceDetail } from '../../types-MRMBUqzY.mjs';
+import '../../ir-DAKlQsVb.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-CKuu7Clz.js';
-import '../../ir-B2h0GAEL.js';
+import { a as TraceDetail } from '../../types-B8X1Pyhx.js';
+import '../../ir-DmUuJsWc.js';
 import '../../dialect.js';
 
 /**

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, B as BestPracticeAdvisory, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-BC4uDL98.mjs';
-export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, 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, x as ShadowProbeConfig, T as ToolCall, y as ToolDefinition } from './ir-BC4uDL98.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, B as BestPracticeAdvisory, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-DAKlQsVb.mjs';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, 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, x as ShadowProbeConfig, T as ToolCall, y as ToolDefinition } from './ir-DAKlQsVb.mjs';
 import { ModelProfile, ArchetypeConvention } from './profiles.mjs';
 export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.mjs';
 export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.mjs';
@@ -440,6 +440,65 @@ interface BrainConfig {
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;
+interface BrainHealthSnapshot {
+    configState: 'configured' | 'not_configured';
+    /** Host of the configured endpoint (never the full URL — no secrets/paths). */
+    endpointHost?: string;
+    /** True when writes are awaited (BrainConfig.sync). */
+    sync: boolean;
+    /** Write POSTs attempted (all routes, primary + secondary). */
+    sent: number;
+    /** Write POSTs acknowledged 2xx without redirect. */
+    acked: number;
+    /** Write POSTs that failed (non-2xx, redirect, timeout, network throw). */
+    failed: number;
+    /** Subset of `failed` that failed the redirect check (middleware-drift class). */
+    redirected: number;
+    lastAckAt?: string;
+    lastFailureAt?: string;
+    /** Most recent failure message, truncated. */
+    lastFailure?: string;
+    deadLetterCount: number;
+}
+interface BrainDeadLetterEntry {
+    /** Brain route segment the payload was bound for. */
+    route: 'outcomes' | 'compile_outcome_quality' | 'probe_outcomes' | 'compile_outcome_advisories';
+    /**
+     * Endpoint the payload was originally bound for. Flush replays ONLY entries
+     * matching the currently-configured endpoint — a reconfigure must never
+     * replay another brain's payloads into the new target (caught live by
+     * smoke-brain-timeout: a hung-socket test payload auto-flushed into the
+     * real brain after the smoke re-pointed configureBrain).
+     */
+    endpoint: string;
+    /** The exact JSON body that failed to land. */
+    payload: unknown;
+    failedAt: string;
+    /** Delivery attempts so far (1 = the original failed POST). */
+    attempts: number;
+    lastError: string;
+}
+/**
+ * Process-local brain write delivery ledger. `acked` is the only number that
+ * means "a row landed" — fire-and-forget callers that need delivery evidence
+ * read this (or set `BrainConfig.sync`). Cheap enough to attach to any debug
+ * or health surface the consumer already exposes.
+ */
+declare function brainHealth(): BrainHealthSnapshot;
+/** Read-only view of the pending dead-letter (for consumer-side persistence). */
+declare function peekBrainDeadLetter(): readonly BrainDeadLetterEntry[];
+/**
+ * Replay pending dead-letter payloads against the configured brain. Delivered
+ * entries are removed; failures increment `attempts` and entries are dropped
+ * after 3 total attempts (bounded — never an infinite retry, per the Redis
+ * DLQ rule). Safe to call any time; no-ops when unconfigured or already
+ * flushing. Also runs opportunistically after any successful write.
+ */
+declare function flushBrainDeadLetter(): Promise<{
+    attempted: number;
+    delivered: number;
+    remaining: number;
+}>;
 declare function record(input: RecordInput): Promise<void>;
 /**
  * Wire shape POSTed by `record()` to the brain proxy's `/outcomes` endpoint.
@@ -522,8 +581,10 @@ interface OutcomePayload {
  * = 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.
+ * Returns (alpha.61): `{ok: true}` only when the POST was acknowledged 2xx
+ * (sync mode); `{ok: 'queued'}` in fire-and-forget mode (handed to the
+ * runtime, NOT acked — read `brainHealth()` for delivery evidence);
+ * `{ok: false, reason}` on known failure. Never throws.
  */
 declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
 /**
@@ -639,7 +700,7 @@ declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>
  * guard in `tests/version.test.ts` fails the suite (and therefore
  * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
  */
-declare const LIBRARY_VERSION = "2.0.0-alpha.60";
+declare const LIBRARY_VERSION = "2.0.0-alpha.61";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -2428,4 +2489,4 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, 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, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+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 BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, 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, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, brainHealth, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, peekBrainDeadLetter, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, 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, S as SystemModelMessage, e as CompileResult, B as BestPracticeAdvisory, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-B2h0GAEL.js';
-export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, 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, x as ShadowProbeConfig, T as ToolCall, y as ToolDefinition } from './ir-B2h0GAEL.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, S as SystemModelMessage, e as CompileResult, B as BestPracticeAdvisory, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-DmUuJsWc.js';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, 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, x as ShadowProbeConfig, T as ToolCall, y as ToolDefinition } from './ir-DmUuJsWc.js';
 import { ModelProfile, ArchetypeConvention } from './profiles.js';
 export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.js';
 export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.js';
@@ -440,6 +440,65 @@ interface BrainConfig {
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;
+interface BrainHealthSnapshot {
+    configState: 'configured' | 'not_configured';
+    /** Host of the configured endpoint (never the full URL — no secrets/paths). */
+    endpointHost?: string;
+    /** True when writes are awaited (BrainConfig.sync). */
+    sync: boolean;
+    /** Write POSTs attempted (all routes, primary + secondary). */
+    sent: number;
+    /** Write POSTs acknowledged 2xx without redirect. */
+    acked: number;
+    /** Write POSTs that failed (non-2xx, redirect, timeout, network throw). */
+    failed: number;
+    /** Subset of `failed` that failed the redirect check (middleware-drift class). */
+    redirected: number;
+    lastAckAt?: string;
+    lastFailureAt?: string;
+    /** Most recent failure message, truncated. */
+    lastFailure?: string;
+    deadLetterCount: number;
+}
+interface BrainDeadLetterEntry {
+    /** Brain route segment the payload was bound for. */
+    route: 'outcomes' | 'compile_outcome_quality' | 'probe_outcomes' | 'compile_outcome_advisories';
+    /**
+     * Endpoint the payload was originally bound for. Flush replays ONLY entries
+     * matching the currently-configured endpoint — a reconfigure must never
+     * replay another brain's payloads into the new target (caught live by
+     * smoke-brain-timeout: a hung-socket test payload auto-flushed into the
+     * real brain after the smoke re-pointed configureBrain).
+     */
+    endpoint: string;
+    /** The exact JSON body that failed to land. */
+    payload: unknown;
+    failedAt: string;
+    /** Delivery attempts so far (1 = the original failed POST). */
+    attempts: number;
+    lastError: string;
+}
+/**
+ * Process-local brain write delivery ledger. `acked` is the only number that
+ * means "a row landed" — fire-and-forget callers that need delivery evidence
+ * read this (or set `BrainConfig.sync`). Cheap enough to attach to any debug
+ * or health surface the consumer already exposes.
+ */
+declare function brainHealth(): BrainHealthSnapshot;
+/** Read-only view of the pending dead-letter (for consumer-side persistence). */
+declare function peekBrainDeadLetter(): readonly BrainDeadLetterEntry[];
+/**
+ * Replay pending dead-letter payloads against the configured brain. Delivered
+ * entries are removed; failures increment `attempts` and entries are dropped
+ * after 3 total attempts (bounded — never an infinite retry, per the Redis
+ * DLQ rule). Safe to call any time; no-ops when unconfigured or already
+ * flushing. Also runs opportunistically after any successful write.
+ */
+declare function flushBrainDeadLetter(): Promise<{
+    attempted: number;
+    delivered: number;
+    remaining: number;
+}>;
 declare function record(input: RecordInput): Promise<void>;
 /**
  * Wire shape POSTed by `record()` to the brain proxy's `/outcomes` endpoint.
@@ -522,8 +581,10 @@ interface OutcomePayload {
  * = 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.
+ * Returns (alpha.61): `{ok: true}` only when the POST was acknowledged 2xx
+ * (sync mode); `{ok: 'queued'}` in fire-and-forget mode (handed to the
+ * runtime, NOT acked — read `brainHealth()` for delivery evidence);
+ * `{ok: false, reason}` on known failure. Never throws.
  */
 declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
 /**
@@ -639,7 +700,7 @@ declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>
  * guard in `tests/version.test.ts` fails the suite (and therefore
  * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
  */
-declare const LIBRARY_VERSION = "2.0.0-alpha.60";
+declare const LIBRARY_VERSION = "2.0.0-alpha.61";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -2428,4 +2489,4 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, 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, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+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 BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, 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, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, brainHealth, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, peekBrainDeadLetter, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

package/dist/index.js

@@ -41,6 +41,7 @@ __export(index_exports, {
   applyArchetypeConvention: () => applyArchetypeConvention,
   applySectionRewrites: () => applySectionRewrites,
   attachCacheControlToStreamTextInput: () => attachCacheControlToStreamTextInput,
+  brainHealth: () => brainHealth,
   bucketContext: () => bucketContext,
   bucketHistory: () => bucketHistory,
   bucketToolCount: () => bucketToolCount,
@@ -58,6 +59,7 @@ __export(index_exports, {
   deriveOwnership: () => deriveOwnership,
   execute: () => execute,
   findBetterFit: () => findBetterFit,
+  flushBrainDeadLetter: () => flushBrainDeadLetter,
   getActionableAdvisories: () => getActionableAdvisories,
   getAllStarterChains: () => getAllStarterChains,
   getAllStarterChainsWithGrounding: () => getAllStarterChainsWithGrounding,
@@ -92,6 +94,7 @@ __export(index_exports, {
   markAdvisoryResolved: () => markAdvisoryResolved,
   markExclusionFindingHandled: () => markExclusionFindingHandled,
   markPromoteReadyHandled: () => markPromoteReadyHandled,
+  peekBrainDeadLetter: () => peekBrainDeadLetter,
   probeShadow: () => probeShadow,
   profileToRow: () => profileToRow,
   profilesByProvider: () => profilesByProvider,
@@ -4468,6 +4471,134 @@ function clearBrain() {
   configureBrainQuery(void 0);
   configureExclusionFindingsBrain(void 0);
 }
+var DEAD_LETTER_MAX_ENTRIES = 50;
+var DEAD_LETTER_MAX_ATTEMPTS = 3;
+var ledger = {
+  sent: 0,
+  acked: 0,
+  failed: 0,
+  redirected: 0,
+  lastAckAt: void 0,
+  lastFailureAt: void 0,
+  lastFailure: void 0
+};
+var deadLetter = [];
+var flushing = false;
+function noteSent() {
+  ledger.sent += 1;
+}
+function noteAck() {
+  ledger.acked += 1;
+  ledger.lastAckAt = (/* @__PURE__ */ new Date()).toISOString();
+}
+function noteFailure(err) {
+  ledger.failed += 1;
+  ledger.lastFailureAt = (/* @__PURE__ */ new Date()).toISOString();
+  const msg = err instanceof Error ? err.message : String(err);
+  ledger.lastFailure = msg.length > 300 ? `${msg.slice(0, 300)}\u2026` : msg;
+}
+function assertNotRedirected(res, route) {
+  if (!res.redirected) return;
+  ledger.redirected += 1;
+  throw new Error(
+    `brain ${route} POST was redirected to ${res.url} \u2014 the write did NOT land. Likely cause: consumer middleware (auth/login allowlist) intercepts the brain proxy path. Add your kgauto proxy routes to the middleware public paths (the 2026-07-02 tt-intel/IC middleware-drift class).`
+  );
+}
+function pushDeadLetter(route, endpoint, payload, err) {
+  if (deadLetter.length >= DEAD_LETTER_MAX_ENTRIES) deadLetter.shift();
+  deadLetter.push({
+    route,
+    endpoint,
+    payload,
+    failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    attempts: 1,
+    lastError: err instanceof Error ? err.message : String(err)
+  });
+}
+function maybeAutoFlush() {
+  if (deadLetter.length === 0 || flushing) return;
+  void flushBrainDeadLetter();
+}
+function brainHealth() {
+  let endpointHost;
+  if (activeConfig) {
+    try {
+      endpointHost = new URL(activeConfig.endpoint).host;
+    } catch {
+      endpointHost = void 0;
+    }
+  }
+  return {
+    configState: activeConfig ? "configured" : "not_configured",
+    endpointHost,
+    sync: activeConfig?.sync === true,
+    sent: ledger.sent,
+    acked: ledger.acked,
+    failed: ledger.failed,
+    redirected: ledger.redirected,
+    lastAckAt: ledger.lastAckAt,
+    lastFailureAt: ledger.lastFailureAt,
+    lastFailure: ledger.lastFailure,
+    deadLetterCount: deadLetter.length
+  };
+}
+function peekBrainDeadLetter() {
+  return deadLetter.slice();
+}
+async function flushBrainDeadLetter() {
+  if (!activeConfig || flushing || deadLetter.length === 0) {
+    return { attempted: 0, delivered: 0, remaining: deadLetter.length };
+  }
+  flushing = true;
+  const config = activeConfig;
+  const fetchFn = brainWriteFetch(config);
+  let attempted = 0;
+  let delivered = 0;
+  try {
+    const batch = deadLetter.filter((e) => e.endpoint === config.endpoint);
+    for (const entry of batch) {
+      attempted += 1;
+      noteSent();
+      try {
+        const res = await fetchFn(`${config.endpoint}/${entry.route}`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            // Replay never chains a secondary — minimal is correct for all routes.
+            Prefer: "return=minimal",
+            ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+          },
+          body: JSON.stringify(entry.payload)
+        });
+        assertNotRedirected(res, entry.route);
+        if (!res.ok) {
+          const text = await res.text().catch(() => "<no body>");
+          throw new Error(describeBrainWriteFailure(res.status, entry.route, text));
+        }
+        noteAck();
+        delivered += 1;
+        const idx = deadLetter.indexOf(entry);
+        if (idx !== -1) deadLetter.splice(idx, 1);
+      } catch (err) {
+        noteFailure(err);
+        entry.attempts += 1;
+        entry.lastError = err instanceof Error ? err.message : String(err);
+        if (entry.attempts >= DEAD_LETTER_MAX_ATTEMPTS) {
+          const idx = deadLetter.indexOf(entry);
+          if (idx !== -1) deadLetter.splice(idx, 1);
+          (config.onError ?? defaultOnError5)(
+            new Error(
+              `brain dead-letter: dropping ${entry.route} payload after ${entry.attempts} attempts \u2014 last error: ${entry.lastError}`
+            )
+          );
+        }
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+  return { attempted, delivered, remaining: deadLetter.length };
+}
 var compileRegistry = /* @__PURE__ */ new Map();
 var REGISTRY_MAX_ENTRIES = 1e4;
 function registerCompile(appId, archetype, ir, result) {
@@ -4575,6 +4706,7 @@ async function record(input) {
   const fetchFn = brainWriteFetch(config);
   const send = async () => {
     let outcomeId;
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/outcomes`, {
         method: "POST",
@@ -4594,20 +4726,26 @@ async function record(input) {
         },
         body: JSON.stringify(payload)
       });
+      assertNotRedirected(res, "outcomes");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(describeBrainWriteFailure(res.status, "outcomes", text));
       }
+      noteAck();
       outcomeId = await tryExtractOutcomeId(res);
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("outcomes", config.endpoint, payload, err);
       (config.onError ?? defaultOnError5)(err);
       return;
     }
+    maybeAutoFlush();
     const advisories = input.advisories ?? reg?.advisoriesFromCompile;
     if (!advisories || advisories.length === 0) return;
     if (outcomeId === void 0) return;
+    const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
+    noteSent();
     try {
-      const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
       const res = await fetchFn(`${config.endpoint}/compile_outcome_advisories`, {
         method: "POST",
         headers: {
@@ -4617,11 +4755,15 @@ async function record(input) {
         },
         body: JSON.stringify(advisoryPayload)
       });
+      assertNotRedirected(res, "compile_outcome_advisories");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(`brain advisories ${res.status}: ${text}`);
       }
+      noteAck();
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("compile_outcome_advisories", config.endpoint, advisoryPayload, err);
       (config.onError ?? defaultOnError5)(err);
     }
   };
@@ -4760,6 +4902,7 @@ async function recordOutcome(input) {
     observed_confidence: input.observedConfidence ?? null
   };
   const send = async () => {
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/compile_outcome_quality`, {
         method: "POST",
@@ -4769,16 +4912,19 @@ async function recordOutcome(input) {
         },
         body: JSON.stringify(payload)
       });
+      assertNotRedirected(res, "compile_outcome_quality");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
-        const err = new Error(
+        throw new Error(
           describeBrainWriteFailure(res.status, "compile_outcome_quality", text)
         );
-        (config.onError ?? defaultOnError5)(err);
-        return { ok: false, reason: "persistence_failed" };
       }
+      noteAck();
+      maybeAutoFlush();
       return { ok: true };
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("compile_outcome_quality", config.endpoint, payload, err);
       (config.onError ?? defaultOnError5)(err);
       return { ok: false, reason: "persistence_failed" };
     }
@@ -4787,7 +4933,7 @@ async function recordOutcome(input) {
     return send();
   }
   void send();
-  return { ok: true };
+  return { ok: "queued" };
 }
 function isBrainSync() {
   return activeConfig?.sync === true;
@@ -4829,6 +4975,7 @@ async function recordShadowProbe(input) {
   const fetchFn = brainWriteFetch(config);
   const row = buildShadowProbeRow(input);
   const send = async () => {
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/probe_outcomes`, {
         method: "POST",
@@ -4839,11 +4986,16 @@ async function recordShadowProbe(input) {
         },
         body: JSON.stringify(row)
       });
+      assertNotRedirected(res, "probe_outcomes");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(describeBrainWriteFailure(res.status, "probe_outcomes", text));
       }
+      noteAck();
+      maybeAutoFlush();
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("probe_outcomes", config.endpoint, row, err);
       (config.onError ?? defaultOnError5)(err);
     }
   };
@@ -6947,7 +7099,7 @@ function createBrainForwardRoutes(config) {
 }
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.60";
+var LIBRARY_VERSION = "2.0.0-alpha.61";
 
 // src/key-health.ts
 var JSON_HEADERS2 = { "Content-Type": "application/json" };
@@ -7581,6 +7733,7 @@ function compile2(ir, opts) {
   applyArchetypeConvention,
   applySectionRewrites,
   attachCacheControlToStreamTextInput,
+  brainHealth,
   bucketContext,
   bucketHistory,
   bucketToolCount,
@@ -7598,6 +7751,7 @@ function compile2(ir, opts) {
   deriveOwnership,
   execute,
   findBetterFit,
+  flushBrainDeadLetter,
   getActionableAdvisories,
   getAllStarterChains,
   getAllStarterChainsWithGrounding,
@@ -7632,6 +7786,7 @@ function compile2(ir, opts) {
   markAdvisoryResolved,
   markExclusionFindingHandled,
   markPromoteReadyHandled,
+  peekBrainDeadLetter,
   probeShadow,
   profileToRow,
   profilesByProvider,

package/dist/index.mjs

@@ -15,7 +15,7 @@ import {
 import {
   LIBRARY_VERSION,
   createKeyHealthRoute
-} from "./chunk-RQ3BUUB6.mjs";
+} from "./chunk-3RMLZCUK.mjs";
 import {
   ABSOLUTE_FLOOR,
   ARCHETYPE_FLOOR_DEFAULT,
@@ -2626,6 +2626,134 @@ function clearBrain() {
   configureBrainQuery(void 0);
   configureExclusionFindingsBrain(void 0);
 }
+var DEAD_LETTER_MAX_ENTRIES = 50;
+var DEAD_LETTER_MAX_ATTEMPTS = 3;
+var ledger = {
+  sent: 0,
+  acked: 0,
+  failed: 0,
+  redirected: 0,
+  lastAckAt: void 0,
+  lastFailureAt: void 0,
+  lastFailure: void 0
+};
+var deadLetter = [];
+var flushing = false;
+function noteSent() {
+  ledger.sent += 1;
+}
+function noteAck() {
+  ledger.acked += 1;
+  ledger.lastAckAt = (/* @__PURE__ */ new Date()).toISOString();
+}
+function noteFailure(err) {
+  ledger.failed += 1;
+  ledger.lastFailureAt = (/* @__PURE__ */ new Date()).toISOString();
+  const msg = err instanceof Error ? err.message : String(err);
+  ledger.lastFailure = msg.length > 300 ? `${msg.slice(0, 300)}\u2026` : msg;
+}
+function assertNotRedirected(res, route) {
+  if (!res.redirected) return;
+  ledger.redirected += 1;
+  throw new Error(
+    `brain ${route} POST was redirected to ${res.url} \u2014 the write did NOT land. Likely cause: consumer middleware (auth/login allowlist) intercepts the brain proxy path. Add your kgauto proxy routes to the middleware public paths (the 2026-07-02 tt-intel/IC middleware-drift class).`
+  );
+}
+function pushDeadLetter(route, endpoint, payload, err) {
+  if (deadLetter.length >= DEAD_LETTER_MAX_ENTRIES) deadLetter.shift();
+  deadLetter.push({
+    route,
+    endpoint,
+    payload,
+    failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    attempts: 1,
+    lastError: err instanceof Error ? err.message : String(err)
+  });
+}
+function maybeAutoFlush() {
+  if (deadLetter.length === 0 || flushing) return;
+  void flushBrainDeadLetter();
+}
+function brainHealth() {
+  let endpointHost;
+  if (activeConfig) {
+    try {
+      endpointHost = new URL(activeConfig.endpoint).host;
+    } catch {
+      endpointHost = void 0;
+    }
+  }
+  return {
+    configState: activeConfig ? "configured" : "not_configured",
+    endpointHost,
+    sync: activeConfig?.sync === true,
+    sent: ledger.sent,
+    acked: ledger.acked,
+    failed: ledger.failed,
+    redirected: ledger.redirected,
+    lastAckAt: ledger.lastAckAt,
+    lastFailureAt: ledger.lastFailureAt,
+    lastFailure: ledger.lastFailure,
+    deadLetterCount: deadLetter.length
+  };
+}
+function peekBrainDeadLetter() {
+  return deadLetter.slice();
+}
+async function flushBrainDeadLetter() {
+  if (!activeConfig || flushing || deadLetter.length === 0) {
+    return { attempted: 0, delivered: 0, remaining: deadLetter.length };
+  }
+  flushing = true;
+  const config = activeConfig;
+  const fetchFn = brainWriteFetch(config);
+  let attempted = 0;
+  let delivered = 0;
+  try {
+    const batch = deadLetter.filter((e) => e.endpoint === config.endpoint);
+    for (const entry of batch) {
+      attempted += 1;
+      noteSent();
+      try {
+        const res = await fetchFn(`${config.endpoint}/${entry.route}`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            // Replay never chains a secondary — minimal is correct for all routes.
+            Prefer: "return=minimal",
+            ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+          },
+          body: JSON.stringify(entry.payload)
+        });
+        assertNotRedirected(res, entry.route);
+        if (!res.ok) {
+          const text = await res.text().catch(() => "<no body>");
+          throw new Error(describeBrainWriteFailure(res.status, entry.route, text));
+        }
+        noteAck();
+        delivered += 1;
+        const idx = deadLetter.indexOf(entry);
+        if (idx !== -1) deadLetter.splice(idx, 1);
+      } catch (err) {
+        noteFailure(err);
+        entry.attempts += 1;
+        entry.lastError = err instanceof Error ? err.message : String(err);
+        if (entry.attempts >= DEAD_LETTER_MAX_ATTEMPTS) {
+          const idx = deadLetter.indexOf(entry);
+          if (idx !== -1) deadLetter.splice(idx, 1);
+          (config.onError ?? defaultOnError4)(
+            new Error(
+              `brain dead-letter: dropping ${entry.route} payload after ${entry.attempts} attempts \u2014 last error: ${entry.lastError}`
+            )
+          );
+        }
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+  return { attempted, delivered, remaining: deadLetter.length };
+}
 var compileRegistry = /* @__PURE__ */ new Map();
 var REGISTRY_MAX_ENTRIES = 1e4;
 function registerCompile(appId, archetype, ir, result) {
@@ -2733,6 +2861,7 @@ async function record(input) {
   const fetchFn = brainWriteFetch(config);
   const send = async () => {
     let outcomeId;
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/outcomes`, {
         method: "POST",
@@ -2752,20 +2881,26 @@ async function record(input) {
         },
         body: JSON.stringify(payload)
       });
+      assertNotRedirected(res, "outcomes");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(describeBrainWriteFailure(res.status, "outcomes", text));
       }
+      noteAck();
       outcomeId = await tryExtractOutcomeId(res);
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("outcomes", config.endpoint, payload, err);
       (config.onError ?? defaultOnError4)(err);
       return;
     }
+    maybeAutoFlush();
     const advisories = input.advisories ?? reg?.advisoriesFromCompile;
     if (!advisories || advisories.length === 0) return;
     if (outcomeId === void 0) return;
+    const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
+    noteSent();
     try {
-      const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
       const res = await fetchFn(`${config.endpoint}/compile_outcome_advisories`, {
         method: "POST",
         headers: {
@@ -2775,11 +2910,15 @@ async function record(input) {
         },
         body: JSON.stringify(advisoryPayload)
       });
+      assertNotRedirected(res, "compile_outcome_advisories");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(`brain advisories ${res.status}: ${text}`);
       }
+      noteAck();
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("compile_outcome_advisories", config.endpoint, advisoryPayload, err);
       (config.onError ?? defaultOnError4)(err);
     }
   };
@@ -2918,6 +3057,7 @@ async function recordOutcome(input) {
     observed_confidence: input.observedConfidence ?? null
   };
   const send = async () => {
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/compile_outcome_quality`, {
         method: "POST",
@@ -2927,16 +3067,19 @@ async function recordOutcome(input) {
         },
         body: JSON.stringify(payload)
       });
+      assertNotRedirected(res, "compile_outcome_quality");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
-        const err = new Error(
+        throw new Error(
           describeBrainWriteFailure(res.status, "compile_outcome_quality", text)
         );
-        (config.onError ?? defaultOnError4)(err);
-        return { ok: false, reason: "persistence_failed" };
       }
+      noteAck();
+      maybeAutoFlush();
       return { ok: true };
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("compile_outcome_quality", config.endpoint, payload, err);
       (config.onError ?? defaultOnError4)(err);
       return { ok: false, reason: "persistence_failed" };
     }
@@ -2945,7 +3088,7 @@ async function recordOutcome(input) {
     return send();
   }
   void send();
-  return { ok: true };
+  return { ok: "queued" };
 }
 function isBrainSync() {
   return activeConfig?.sync === true;
@@ -2987,6 +3130,7 @@ async function recordShadowProbe(input) {
   const fetchFn = brainWriteFetch(config);
   const row = buildShadowProbeRow(input);
   const send = async () => {
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/probe_outcomes`, {
         method: "POST",
@@ -2997,11 +3141,16 @@ async function recordShadowProbe(input) {
         },
         body: JSON.stringify(row)
       });
+      assertNotRedirected(res, "probe_outcomes");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(describeBrainWriteFailure(res.status, "probe_outcomes", text));
       }
+      noteAck();
+      maybeAutoFlush();
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("probe_outcomes", config.endpoint, row, err);
       (config.onError ?? defaultOnError4)(err);
     }
   };
@@ -4675,6 +4824,7 @@ export {
   applyArchetypeConvention,
   applySectionRewrites,
   attachCacheControlToStreamTextInput,
+  brainHealth,
   bucketContext,
   bucketHistory,
   bucketToolCount,
@@ -4692,6 +4842,7 @@ export {
   deriveOwnership,
   execute,
   findBetterFit,
+  flushBrainDeadLetter,
   getActionableAdvisories,
   getAllStarterChains,
   getAllStarterChainsWithGrounding,
@@ -4726,6 +4877,7 @@ export {
   markAdvisoryResolved,
   markExclusionFindingHandled,
   markPromoteReadyHandled,
+  peekBrainDeadLetter,
   probeShadow,
   profileToRow,
   profilesByProvider,

package/dist/{ir-BC4uDL98.d.mts → ir-DAKlQsVb.d.mts}

@@ -1277,8 +1277,16 @@ interface RecordOutcomeInput {
  * 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;
+    /**
+     * `true` — the POST was acknowledged 2xx (sync mode only).
+     * `'queued'` (alpha.61) — fire-and-forget mode: the write was handed to the
+     * runtime but NOT acknowledged; delivery is unknown at return time. Read
+     * `brainHealth()` or set `BrainConfig.sync` for delivery evidence.
+     * `false` — brain not configured, or the POST failed (sync mode).
+     * Both truthy values pass `if (result.ok)`; pre-alpha.61 code that treated
+     * the fire-and-forget `true` as an ack was reading a false signal.
+     */
+    ok: boolean | 'queued';
     /** Stable reason code when ok=false. One of: 'brain_not_configured' | 'persistence_failed'. */
     reason?: string;
 }

package/dist/{ir-B2h0GAEL.d.ts → ir-DmUuJsWc.d.ts}

@@ -1277,8 +1277,16 @@ interface RecordOutcomeInput {
  * 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;
+    /**
+     * `true` — the POST was acknowledged 2xx (sync mode only).
+     * `'queued'` (alpha.61) — fire-and-forget mode: the write was handed to the
+     * runtime but NOT acknowledged; delivery is unknown at return time. Read
+     * `brainHealth()` or set `BrainConfig.sync` for delivery evidence.
+     * `false` — brain not configured, or the POST failed (sync mode).
+     * Both truthy values pass `if (result.ok)`; pre-alpha.61 code that treated
+     * the fire-and-forget `true` as an ack was reading a false signal.
+     */
+    ok: boolean | 'queued';
     /** Stable reason code when ok=false. One of: 'brain_not_configured' | 'persistence_failed'. */
     reason?: string;
 }

package/dist/key-health.js

@@ -25,7 +25,7 @@ __export(key_health_exports, {
 module.exports = __toCommonJS(key_health_exports);
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.60";
+var LIBRARY_VERSION = "2.0.0-alpha.61";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/key-health.mjs

@@ -1,6 +1,6 @@
 import {
   createKeyHealthRoute
-} from "./chunk-RQ3BUUB6.mjs";
+} from "./chunk-3RMLZCUK.mjs";
 export {
   createKeyHealthRoute
 };

package/dist/profiles.d.mts

@@ -1,4 +1,4 @@
-import { k as Provider } from './ir-BC4uDL98.mjs';
+import { k as Provider } from './ir-DAKlQsVb.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**

package/dist/profiles.d.ts

@@ -1,4 +1,4 @@
-import { k as Provider } from './ir-B2h0GAEL.js';
+import { k as Provider } from './ir-DmUuJsWc.js';
 import { IntentArchetypeName } from './dialect.js';
 
 /**

package/dist/{types-CKuu7Clz.d.ts → types-B8X1Pyhx.d.ts}

@@ -1,4 +1,4 @@
-import { i as Adapter, w as SectionKind } from './ir-B2h0GAEL.js';
+import { i as Adapter, w as SectionKind } from './ir-DmUuJsWc.js';
 
 /**
  * Internal config + hook types for createGlassboxRoutes().

package/dist/{types-CRy90cjp.d.mts → types-CssWqd0X.d.mts}

@@ -1,4 +1,4 @@
-import { r as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-BC4uDL98.mjs';
+import { r as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-DAKlQsVb.mjs';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-CsB2YASc.d.ts → types-DR62iPcO.d.ts}

@@ -1,4 +1,4 @@
-import { r as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-B2h0GAEL.js';
+import { r as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-DmUuJsWc.js';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-B-pzBJKf.d.mts → types-MRMBUqzY.d.mts}

@@ -1,4 +1,4 @@
-import { i as Adapter, w as SectionKind } from './ir-BC4uDL98.mjs';
+import { i as Adapter, w as SectionKind } from './ir-DAKlQsVb.mjs';
 
 /**
  * Internal config + hook types for createGlassboxRoutes().

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.60",
-  "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
+  "version": "2.0.0-alpha.61",
+  "description": "Prompt compiler with executable provider knowledge for multi-model AI apps: normalized multi-provider transport with fallback chains, compile-time cliff guards, a curated model registry, and a telemetry flight recorder. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -73,7 +73,7 @@
     "gemini",
     "deepseek",
     "prompt-cache",
-    "self-improving"
+    "model-fallback"
   ],
   "license": "MIT",
   "peerDependencies": {