@warmdrift/kgauto-compiler 2.0.0-alpha.5 → 2.0.0-alpha.52

package/README.md

@@ -1,4 +1,4 @@
-# @warmdrift/kgauto-compiler — v2.0.0-alpha.5
+# @warmdrift/kgauto-compiler — v2.0.0-alpha.6
 
 > Prompt compiler + central learning brain for multi-model AI apps.
 > **Swap models without rewriting prompts.**
@@ -18,8 +18,8 @@ mutations.
 - **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:** 180/180 passing
-- **Build:** clean (47KB ESM, 64KB CJS)
+- **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).
@@ -89,6 +89,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
 
 ```
@@ -154,6 +249,48 @@ The 5 prod empty-responses in tt-intelligence's `gemini-2.5-flash` dashboard
 calls? v2 catches those automatically — `expectedShortOutput` constraint plus
 the `force_thinking_budget_zero` cliff guard.
 
+## Tools
+
+Tools are first-class IR fields. The compiler's tool-relevance pass drops
+tools that don't apply to the current intent before lowering — saves
+context budget on every call.
+
+```ts
+const tools: ToolDefinition[] = [
+  {
+    name: 'web_search',
+    description: 'Search the public web',
+    parameters: { type: 'object', properties: { q: { type: 'string' } } },
+    relevanceByIntent: {
+      ask: 0.9,        // primary tool for ask
+      hunt: 0.9,
+      classify: 0.0,   // never useful for classification
+      summarize: 0.0,
+      extract: 0.1,
+    },
+  },
+  // ...
+];
+```
+
+Each tool declares per-intent relevance scores 0..1. The pass keeps tools
+where `relevanceByIntent[currentIntent] >= toolRelevanceThreshold` (default
+`0.2`). Missing entries default to neutral (`0.5`) — kept by default. Set
+explicit `0.0` to hard-exclude.
+
+Tool definitions eat ~350 tokens of context per tool (L-051), so trimming
+matters: 12 declared tools, only 3 relevant → 9 × 350 = 3150 tokens
+recovered per call.
+
+The `tool-bloat` advisory (alpha.6) fires when more than 10 tools survive
+the relevance pass on a short-output archetype (`classify`, `extract`,
+`summarize`, `transform`, `critique`) — those archetypes typically use
+≤3 tools, so a kept-count >10 indicates either missing `relevanceByIntent`
+or scores set too generously.
+
+DeepSeek profiles cap tools to 1 (sequential-only). Other providers
+inherit the count from the IR after the relevance pass.
+
 ## Brain provisioning
 
 1. Create a NEW Supabase project (suggested name: `kgauto-brain`)