@warmdrift/kgauto-compiler 2.0.0-alpha.7 → 2.0.0-alpha.71

package/README.md

@@ -1,28 +1,49 @@
-# @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*. What DOES ship as of
+alpha.62 is the eval spine (Stage 1 of that architecture): golden-set capture,
+a pairwise judge, and a non-inferiority eval whose verdict lands as evidence
+on the advisory surface — the eval runs, a human clicks promote. Automatic
+promotion (Stages 2–3) returns to this README when it is 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
 
@@ -89,6 +110,101 @@ await record({
 });
 ```
 
+### `probeShadow()` — measure a swap candidate from an AI-SDK route (alpha.48)
+
+`call()` runs a full-IR shadow probe internally (`shadowProbe` option). AI-SDK consumers who drive `streamText()` themselves never call `call()`, so they reach the same probe via the standalone `probeShadow()` export — fire it from `onFinish`, passing the served leg you already have, wrapped in `waitUntil()`/`after()` so it never blocks the response.
+
+```ts
+import { probeShadow, configureBrain } from '@warmdrift/kgauto-compiler';
+import { after } from 'next/server'; // or the platform's waitUntil()
+
+configureBrain({ endpoint: 'https://your-app.com/api/kgauto/v2', apiKey: '...' });
+
+const t0 = Date.now();
+const result = streamText({
+  model, system, messages,
+  onFinish: ({ text, usage }) => {
+    after(() => probeShadow(ir, {
+      served: {
+        model: servedModelId,
+        responseText: text,
+        tokensIn: usage.promptTokens,
+        tokensOut: usage.completionTokens,
+        latencyMs: Date.now() - t0,
+      },
+      candidates: ['deepseek-v4-pro'], // what you'd consider swapping to
+      sampleRate: 0.05,                // pin 1 for a dogfood window
+    }));
+  },
+});
+```
+
+kgauto runs each candidate on the **same IR** and persists a `probe_outcomes` row (`replay_source='inline-full-ir'`, `prompt_fidelity=1.0`, both latency legs). Phase 1 is `judge:'off'` — rows accumulate for an offline verdict rollup; inline Opus judging is Phase 2. Fire-and-forget: never throws into your `onFinish`.
+
+#### Sync-mode latency protection (`call()` + `BrainConfig.sync`)
+
+A `probeShadow()` consumer fires from `after()`, so the probe is always off the user-facing path — slow candidates are fine there (it's the right place to evaluate a slow reasoner). But a **`call()`-inline** consumer that sets `BrainConfig.sync: true` (PB-class Edge routes, so the brain write reliably lands before teardown — L-086) *awaits* the probe, putting the candidate's latency on the user's critical path. A `latency_tier='slow'` candidate (deepseek-v4-pro ~78–84s) then blows the route's time budget and the user sees an empty response. Two knobs on `shadowProbe` protect the sync path — **both are no-ops off the critical path** (non-sync `call()` and every `probeShadow()` consumer):
+
+```ts
+await call(ir, {
+  shadowProbe: {
+    candidates: ['deepseek-v4-pro'],
+    sampleRate: 1,
+    maxLatencyMs: 15000,        // default 15000. Sync-mode budget: if the probe
+                                // overruns, abort the candidate, return the served
+                                // response NOW, record outcome='aborted_latency_budget'.
+    skipSlowTierInSync: true,   // default true. Don't even START a latency_tier='slow'
+                                // candidate inline; record outcome='skipped_slow_tier_sync'.
+  },
+});
+```
+
+Aborted/skipped probes write a **diagnostic** `probe_outcomes` row (`outcome != 'completed'`, no candidate response, no verdict) so the offline rollup can tell "tried but too slow" from "never armed." A verdict rollup must filter `outcome='completed'`.
+
+**The deeper rule: inline shadow-probe = FAST candidates only.** To evaluate a *slow* reasoner, use the offline/async probe path (the Phase-2 batch direction, off the response entirely) or `probeShadow()` from `after()` — never the inline sync probe.
+
+## Structured advisories API (alpha.29+)
+
+kgauto's compile-time advisories (`caching-off-on-claude`, `tool-bloat`,
+`archetype-perf-floor-breach`, etc.) used to vanish after the consumer read
+the compile result. alpha.29 ships a structured query + resolution surface
+so Admin UIs can render "what's open right now?" without log-scraping.
+
+```ts
+import {
+  getActionableAdvisories,
+  markAdvisoryResolved,
+} from '@warmdrift/kgauto-compiler';
+
+// Query open advisories for this app
+const open = await getActionableAdvisories({
+  appId: 'playbacksam',
+  brainEndpoint: process.env.KGAUTO_BRAIN_ENDPOINT!,
+  brainJwt: process.env.KGAUTO_BRAIN_JWT!,
+  brainAnonKey: process.env.KGAUTO_BRAIN_ANON_KEY!,
+});
+
+for (const a of open) {
+  console.log(`[${a.severity}] ${a.rule} — ${a.observationCount} firings since ${a.openedAt}`);
+  console.log(`  ${a.message}`);
+  if (a.suggestedFix?.docsLink) console.log(`  ↳ ${a.suggestedFix.docsLink}`);
+}
+
+// After the operator fixes the issue, mark it resolved:
+const r = await markAdvisoryResolved({
+  id: open[0].id,
+  resolutionNote: 'wired historyCachePolicy in compile() — PR #99',
+  brainEndpoint: process.env.KGAUTO_BRAIN_ENDPOINT!,
+  brainJwt: process.env.KGAUTO_BRAIN_JWT!,
+  brainAnonKey: process.env.KGAUTO_BRAIN_ANON_KEY!,
+});
+if (!r.ok) console.error(r.reason);
+```
+
+The view enforces server-side auto-resolution: advisories with no firing
+in the last 14 days flip to `status='resolved'` automatically; the next
+firing reopens the rule with a fresh stable `id`.
+
 ## Architecture
 
 ```
@@ -108,10 +224,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)
@@ -121,12 +237,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
 
@@ -211,29 +325,45 @@ For staging without a dedicated brain, point consumers at the same Supabase
 they already use — the schema is identical and migration to a dedicated brain
 is a `pg_dump` away.
 
+## Golden-set eval (alpha.62 — Stage 1, shipped)
+
+The eval-driven quality-floor-guarded swap architecture (specced 2026-07-17
+after an adversarial promise review) began shipping in alpha.62:
+
+- **Capture:** set `KGAUTO_GOLDEN_CAPTURE=0.1` on a consumer and successful
+  `call()`s sample their full IR + served output into a per-surface replay
+  corpus. Explicit opt-in — golden rows carry raw prompts (documented posture
+  change; consent provenance on every row; reads strictly app-scoped). Or
+  hand-curate with `scripts/seed-golden-set.mjs`.
+- **Eval:** `scripts/run-golden-eval.mjs --app X --archetype Y --candidate M`
+  replays the corpus on incumbent AND candidate (fresh outputs both sides),
+  applies mechanical hard floors (empty / schema / candidate-error / latency),
+  and runs an order-swapped pairwise judge (`judge` archetype, per-archetype
+  rubrics). Non-inferiority rule: wins-or-ties ≥ 80% + zero floor violations
+  → `promote-ready`.
+- **Evidence:** every run lands as brain rows (`kgauto_golden_eval_runs` +
+  per-case `probe_outcomes` `golden-replay` rows) and a `golden-eval-verdict`
+  advisory on the consumer's advisory surface.
+
 ## 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.
+Stages 2–3 of the trust ladder (auto-promote downswaps behind a 7-day
+rollback guard, then upswaps) and trigger wiring (model-release-watch /
+price-truth-watch / live-telemetry drift → auto-eval), then the same harness
+pointed at compile variants (Tier D). 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/brain-proxy.d.mts

@@ -0,0 +1,113 @@
+/**
+ * `@warmdrift/kgauto-compiler/brain-proxy` — consumer brain-forward factory.
+ *
+ * ## Why this exists (the 4-consumer silent-drop class, 2026-07-06 s62)
+ *
+ * The library's `record()` / `recordOutcome()` / `recordShadowProbe()` /
+ * advisory paths all POST to a consumer-hosted proxy that forwards the row to
+ * the shared Supabase brain (the consumer holds the service-role key; kgauto's
+ * library never sees it). Every consumer hand-rolled that proxy layer — and a
+ * 4-consumer audit found every one silently broken in a *different* shape:
+ *
+ *   - tt-intelligence: middleware blocked 2 of 3 routes — server-to-server
+ *     POSTs 307-redirected to /login (missing public-path allowlist entry).
+ *   - inspire-central: the `/outcomes` proxy carried a column whitelist frozen
+ *     at alpha.7 that stripped `fell_over_from` / `fallback_reason`
+ *     (migration 018 columns) — Glass-Box fallback telemetry silently NULL.
+ *   - playbacksam: the `/probe_outcomes` whitelist would strip alpha.53's
+ *     `error_class` — every future migration column drops on the floor.
+ *   - global-expansion: mounted 1 of 4 routes — advisory POSTs 404 silently.
+ *
+ * Same L-142 / L-117 silent-drop family, four independent shapes, all in the
+ * layer consumers hand-roll. This factory kills the *class*: kgauto owns the
+ * forward handler, the consumer mounts ONE catch-all route. No column
+ * whitelist — the body is forwarded verbatim (`{ ...body }`), so any future
+ * migration column passes through untouched. One middleware/public-path entry
+ * (`/api/kgauto/v2/`) covers all four segments, which structurally prevents
+ * the tt-intel middleware-drift failure.
+ *
+ * ## Mounting recipes
+ *
+ * ### (a) Next.js app-router catch-all — ONE file, ONE middleware entry
+ *
+ *   // app/api/kgauto/v2/[segment]/route.ts
+ *   import { createBrainForwardRoutes } from '@warmdrift/kgauto-compiler/brain-proxy';
+ *   const routes = createBrainForwardRoutes({
+ *     ingestSecret: process.env.KGAUTO_INGEST_SECRET!,
+ *     brainUrl:     process.env.KGAUTO_BRAIN_URL!,      // https://xxxx.supabase.co
+ *     serviceKey:   process.env.KGAUTO_BRAIN_SERVICE_KEY!,
+ *   });
+ *   export const POST = (req: Request, { params }: { params: { segment: string } }) =>
+ *     routes.handle(req, params.segment);
+ *
+ *   // middleware.ts — ONE public-path entry covers ALL four segments.
+ *   // This is the structural fix for the tt-intel drift: you cannot mount
+ *   // 3-of-4 routes and forget the 4th, because the catch-all is one file
+ *   // and the allowlist is one prefix.
+ *   const PUBLIC_PATHS = [ ...  '/api/kgauto/v2/' ];
+ *
+ * ### (b) Plain Vercel edge function, per segment
+ *
+ *   // api/kgauto/probe_outcomes.ts
+ *   export const config = { runtime: 'edge' };
+ *   const routes = createBrainForwardRoutes({ ...  });
+ *   export default (req: Request) => routes.handle(req, 'probe_outcomes');
+ *
+ * The library appends the segment path to the consumer's `endpoint`, so the
+ * consumer's `KGAUTO_V2_BRAIN_URL` (the value passed to `configureBrain`)
+ * must be the base that resolves to `.../api/kgauto/v2` — i.e. the last path
+ * segment of each library POST (`outcomes`, `probe_outcomes`, …) is what
+ * `handle()` receives as `segment`.
+ *
+ * ## Prefer-header relay (alpha.56)
+ *
+ * `record()` sends `Prefer: return=representation` on its `/outcomes` POST and
+ * parses the inserted row id from the PROXY's response to fire the secondary
+ * `compile_outcome_advisories` POST. alpha.54/.55 hardcoded
+ * `Prefer: return=minimal` toward the brain and returned `{ok:true}` — so the
+ * id-parse found nothing and the advisory secondary silently never fired for
+ * factory-mounted consumers (PB + GE convergent finding, 2026-07-06). The
+ * factory now honors a caller `Prefer: return=representation` header: it is
+ * forwarded to the brain and the brain's response body (the inserted row(s))
+ * is relayed verbatim on success. Callers that don't send the header keep the
+ * `return=minimal` + `{ok:true}` behavior.
+ *
+ * ## Quality-segment handle resolution (alpha.55)
+ *
+ * `recordOutcome()` sends `outcome_id` as `CompileResult.handle` (a string),
+ * but `compile_outcome_quality.outcome_id` is a BIGINT FK →
+ * `compile_outcomes(id)`. A verbatim forward would 400 every handle-shaped
+ * verdict (tt-intel + IC convergent finding, 2026-07-06). On the
+ * `compile_outcome_quality` segment the factory resolves non-numeric
+ * `outcome_id` values to their BIGINT row ids via
+ * `compile_outcomes?handle=eq.<v>` (latest row wins) before forwarding.
+ * Numeric ids pass through untouched; an unresolvable handle returns
+ * `404 handle_not_found` so the library's route-404 observability names the
+ * failure instead of the brain's opaque FK error.
+ */
+interface BrainForwardConfig {
+    /** Bearer token consumers' callers must present (usually KGAUTO_INGEST_SECRET). */
+    ingestSecret: string;
+    /** Brain Supabase project URL (e.g. https://xxxx.supabase.co). */
+    brainUrl: string;
+    /** Brain service-role key (server-side only). */
+    serviceKey: string;
+    /** Optional fetch impl for tests. */
+    fetchImpl?: typeof fetch;
+}
+interface BrainForwardRoutes {
+    /**
+     * Web-standard handler. `segment` is the last path segment of the library's
+     * POST URL (e.g. 'outcomes', 'probe_outcomes'). In a Next.js catch-all this
+     * is `params.segment`. Never throws — every error path returns a `Response`.
+     */
+    handle(req: Request, segment: string): Promise<Response>;
+    /**
+     * The path segments this factory serves. Consumers can use it for route
+     * generation, allowlist construction, or tests.
+     */
+    segments: readonly string[];
+}
+declare function createBrainForwardRoutes(config: BrainForwardConfig): BrainForwardRoutes;
+
+export { type BrainForwardConfig, type BrainForwardRoutes, createBrainForwardRoutes };

package/dist/brain-proxy.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `@warmdrift/kgauto-compiler/brain-proxy` — consumer brain-forward factory.
+ *
+ * ## Why this exists (the 4-consumer silent-drop class, 2026-07-06 s62)
+ *
+ * The library's `record()` / `recordOutcome()` / `recordShadowProbe()` /
+ * advisory paths all POST to a consumer-hosted proxy that forwards the row to
+ * the shared Supabase brain (the consumer holds the service-role key; kgauto's
+ * library never sees it). Every consumer hand-rolled that proxy layer — and a
+ * 4-consumer audit found every one silently broken in a *different* shape:
+ *
+ *   - tt-intelligence: middleware blocked 2 of 3 routes — server-to-server
+ *     POSTs 307-redirected to /login (missing public-path allowlist entry).
+ *   - inspire-central: the `/outcomes` proxy carried a column whitelist frozen
+ *     at alpha.7 that stripped `fell_over_from` / `fallback_reason`
+ *     (migration 018 columns) — Glass-Box fallback telemetry silently NULL.
+ *   - playbacksam: the `/probe_outcomes` whitelist would strip alpha.53's
+ *     `error_class` — every future migration column drops on the floor.
+ *   - global-expansion: mounted 1 of 4 routes — advisory POSTs 404 silently.
+ *
+ * Same L-142 / L-117 silent-drop family, four independent shapes, all in the
+ * layer consumers hand-roll. This factory kills the *class*: kgauto owns the
+ * forward handler, the consumer mounts ONE catch-all route. No column
+ * whitelist — the body is forwarded verbatim (`{ ...body }`), so any future
+ * migration column passes through untouched. One middleware/public-path entry
+ * (`/api/kgauto/v2/`) covers all four segments, which structurally prevents
+ * the tt-intel middleware-drift failure.
+ *
+ * ## Mounting recipes
+ *
+ * ### (a) Next.js app-router catch-all — ONE file, ONE middleware entry
+ *
+ *   // app/api/kgauto/v2/[segment]/route.ts
+ *   import { createBrainForwardRoutes } from '@warmdrift/kgauto-compiler/brain-proxy';
+ *   const routes = createBrainForwardRoutes({
+ *     ingestSecret: process.env.KGAUTO_INGEST_SECRET!,
+ *     brainUrl:     process.env.KGAUTO_BRAIN_URL!,      // https://xxxx.supabase.co
+ *     serviceKey:   process.env.KGAUTO_BRAIN_SERVICE_KEY!,
+ *   });
+ *   export const POST = (req: Request, { params }: { params: { segment: string } }) =>
+ *     routes.handle(req, params.segment);
+ *
+ *   // middleware.ts — ONE public-path entry covers ALL four segments.
+ *   // This is the structural fix for the tt-intel drift: you cannot mount
+ *   // 3-of-4 routes and forget the 4th, because the catch-all is one file
+ *   // and the allowlist is one prefix.
+ *   const PUBLIC_PATHS = [ ...  '/api/kgauto/v2/' ];
+ *
+ * ### (b) Plain Vercel edge function, per segment
+ *
+ *   // api/kgauto/probe_outcomes.ts
+ *   export const config = { runtime: 'edge' };
+ *   const routes = createBrainForwardRoutes({ ...  });
+ *   export default (req: Request) => routes.handle(req, 'probe_outcomes');
+ *
+ * The library appends the segment path to the consumer's `endpoint`, so the
+ * consumer's `KGAUTO_V2_BRAIN_URL` (the value passed to `configureBrain`)
+ * must be the base that resolves to `.../api/kgauto/v2` — i.e. the last path
+ * segment of each library POST (`outcomes`, `probe_outcomes`, …) is what
+ * `handle()` receives as `segment`.
+ *
+ * ## Prefer-header relay (alpha.56)
+ *
+ * `record()` sends `Prefer: return=representation` on its `/outcomes` POST and
+ * parses the inserted row id from the PROXY's response to fire the secondary
+ * `compile_outcome_advisories` POST. alpha.54/.55 hardcoded
+ * `Prefer: return=minimal` toward the brain and returned `{ok:true}` — so the
+ * id-parse found nothing and the advisory secondary silently never fired for
+ * factory-mounted consumers (PB + GE convergent finding, 2026-07-06). The
+ * factory now honors a caller `Prefer: return=representation` header: it is
+ * forwarded to the brain and the brain's response body (the inserted row(s))
+ * is relayed verbatim on success. Callers that don't send the header keep the
+ * `return=minimal` + `{ok:true}` behavior.
+ *
+ * ## Quality-segment handle resolution (alpha.55)
+ *
+ * `recordOutcome()` sends `outcome_id` as `CompileResult.handle` (a string),
+ * but `compile_outcome_quality.outcome_id` is a BIGINT FK →
+ * `compile_outcomes(id)`. A verbatim forward would 400 every handle-shaped
+ * verdict (tt-intel + IC convergent finding, 2026-07-06). On the
+ * `compile_outcome_quality` segment the factory resolves non-numeric
+ * `outcome_id` values to their BIGINT row ids via
+ * `compile_outcomes?handle=eq.<v>` (latest row wins) before forwarding.
+ * Numeric ids pass through untouched; an unresolvable handle returns
+ * `404 handle_not_found` so the library's route-404 observability names the
+ * failure instead of the brain's opaque FK error.
+ */
+interface BrainForwardConfig {
+    /** Bearer token consumers' callers must present (usually KGAUTO_INGEST_SECRET). */
+    ingestSecret: string;
+    /** Brain Supabase project URL (e.g. https://xxxx.supabase.co). */
+    brainUrl: string;
+    /** Brain service-role key (server-side only). */
+    serviceKey: string;
+    /** Optional fetch impl for tests. */
+    fetchImpl?: typeof fetch;
+}
+interface BrainForwardRoutes {
+    /**
+     * Web-standard handler. `segment` is the last path segment of the library's
+     * POST URL (e.g. 'outcomes', 'probe_outcomes'). In a Next.js catch-all this
+     * is `params.segment`. Never throws — every error path returns a `Response`.
+     */
+    handle(req: Request, segment: string): Promise<Response>;
+    /**
+     * The path segments this factory serves. Consumers can use it for route
+     * generation, allowlist construction, or tests.
+     */
+    segments: readonly string[];
+}
+declare function createBrainForwardRoutes(config: BrainForwardConfig): BrainForwardRoutes;
+
+export { type BrainForwardConfig, type BrainForwardRoutes, createBrainForwardRoutes };