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

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
 
@@ -203,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)
@@ -216,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
 
@@ -306,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.js

@@ -27,7 +27,11 @@ var SEGMENT_TO_TABLE = {
   outcomes: "compile_outcomes",
   compile_outcome_advisories: "compile_outcome_advisories",
   compile_outcome_quality: "compile_outcome_quality",
-  probe_outcomes: "probe_outcomes"
+  probe_outcomes: "probe_outcomes",
+  // alpha.62 (eval spine): golden-set capture. Only receives rows when the
+  // consumer has explicitly opted in via KGAUTO_GOLDEN_CAPTURE — the segment
+  // existing here does not by itself store anything.
+  golden_irs: "kgauto_golden_irs"
 };
 var KNOWN_SEGMENTS = Object.keys(SEGMENT_TO_TABLE);
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/brain-proxy.mjs

@@ -1,6 +1,6 @@
 import {
   createBrainForwardRoutes
-} from "./chunk-IUWFML6Z.mjs";
+} from "./chunk-65ZMX5OT.mjs";
 export {
   createBrainForwardRoutes
 };

package/dist/{chunk-5TI6PNSK.mjs → chunk-3KQAID63.mjs}

@@ -45,6 +45,11 @@ var INTENT_ARCHETYPES = {
     name: "transform",
     description: "Change format or style while preserving content",
     examples: ["markdown \u2192 html", "formal \u2192 casual", "translate"]
+  },
+  judge: {
+    name: "judge",
+    description: "Pairwise comparison of two candidate outputs for the same input",
+    examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"]
   }
 };
 var ALL_ARCHETYPES = Object.keys(INTENT_ARCHETYPES);

package/dist/{chunk-IUWFML6Z.mjs → chunk-65ZMX5OT.mjs}

@@ -3,7 +3,11 @@ var SEGMENT_TO_TABLE = {
   outcomes: "compile_outcomes",
   compile_outcome_advisories: "compile_outcome_advisories",
   compile_outcome_quality: "compile_outcome_quality",
-  probe_outcomes: "probe_outcomes"
+  probe_outcomes: "probe_outcomes",
+  // alpha.62 (eval spine): golden-set capture. Only receives rows when the
+  // consumer has explicitly opted in via KGAUTO_GOLDEN_CAPTURE — the segment
+  // existing here does not by itself store anything.
+  golden_irs: "kgauto_golden_irs"
 };
 var KNOWN_SEGMENTS = Object.keys(SEGMENT_TO_TABLE);
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/{chunk-RQ3BUUB6.mjs → chunk-ABFXMO73.mjs}

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

package/dist/{chunk-IIMPJZNH.mjs → chunk-YZRPNSSQ.mjs}

@@ -333,6 +333,16 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
     { id: "gpt-5.5", grounding: "judgment", reason: "alpha.16: third-provider frontier-tier floor (archetypePerf=9)" }
   ],
+  // alpha.62 (eval spine) — pairwise output comparison. Same reasoning-floor
+  // posture as critique (a verdict from a weak judge is worse than no
+  // verdict); tier 0 anchored on the CURRENT opus (4-8, s64 roster). Strict
+  // JSON output, so every tier declares native structured output.
+  judge: [
+    { id: "claude-opus-4-8", grounding: "judgment", reason: "Highest reasoning bar for pairwise verdicts \u2014 current opus (s64 roster)" },
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Same-provider walk-down on 429" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
+    { id: "gpt-5.5", grounding: "judgment", reason: "Third-provider frontier-tier floor" }
+  ],
   // Reasoning matters — Sonnet primary; walk UP to Opus on 429.
   plan: [
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reasoning + cost balance \u2014 engineer pick" },

package/dist/dialect.d.mts

@@ -12,8 +12,15 @@
  * The brain learns by `(archetype, model, shape)` tuples. Apps that declare
  * the same tuple inherit each other's mutations.
  *
- * v1 is intentionally small (9 archetypes, 5 shape dimensions). New entries
- * arrive in v2/v3 from real usage signals — never speculatively.
+ * v1 is intentionally small (10 archetypes, 5 shape dimensions). New entries
+ * arrive from real usage signals — never speculatively.
+ *
+ * Versioning note (alpha.62): `judge` was added as an ADDITIVE 10th entry
+ * under dialect-v1 rather than bumping to v2. Bumping the version string
+ * would fragment every existing learning key (`v1::…` → `v2::…`) for a
+ * purely additive vocabulary change; existing keys are untouched and judge
+ * keys are new, so no collision is possible. A v2 bump is reserved for
+ * changes that alter the MEANING of existing entries or the shape hash.
  */
 declare const DIALECT_VERSION: "v1";
 declare const INTENT_ARCHETYPES: {
@@ -62,6 +69,11 @@ declare const INTENT_ARCHETYPES: {
         readonly description: "Change format or style while preserving content";
         readonly examples: ["markdown → html", "formal → casual", "translate"];
     };
+    readonly judge: {
+        readonly name: "judge";
+        readonly description: "Pairwise comparison of two candidate outputs for the same input";
+        readonly examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"];
+    };
 };
 type IntentArchetypeName = keyof typeof INTENT_ARCHETYPES;
 declare const ALL_ARCHETYPES: IntentArchetypeName[];

package/dist/dialect.d.ts

@@ -12,8 +12,15 @@
  * The brain learns by `(archetype, model, shape)` tuples. Apps that declare
  * the same tuple inherit each other's mutations.
  *
- * v1 is intentionally small (9 archetypes, 5 shape dimensions). New entries
- * arrive in v2/v3 from real usage signals — never speculatively.
+ * v1 is intentionally small (10 archetypes, 5 shape dimensions). New entries
+ * arrive from real usage signals — never speculatively.
+ *
+ * Versioning note (alpha.62): `judge` was added as an ADDITIVE 10th entry
+ * under dialect-v1 rather than bumping to v2. Bumping the version string
+ * would fragment every existing learning key (`v1::…` → `v2::…`) for a
+ * purely additive vocabulary change; existing keys are untouched and judge
+ * keys are new, so no collision is possible. A v2 bump is reserved for
+ * changes that alter the MEANING of existing entries or the shape hash.
  */
 declare const DIALECT_VERSION: "v1";
 declare const INTENT_ARCHETYPES: {
@@ -62,6 +69,11 @@ declare const INTENT_ARCHETYPES: {
         readonly description: "Change format or style while preserving content";
         readonly examples: ["markdown → html", "formal → casual", "translate"];
     };
+    readonly judge: {
+        readonly name: "judge";
+        readonly description: "Pairwise comparison of two candidate outputs for the same input";
+        readonly examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"];
+    };
 };
 type IntentArchetypeName = keyof typeof INTENT_ARCHETYPES;
 declare const ALL_ARCHETYPES: IntentArchetypeName[];

package/dist/dialect.js

@@ -77,6 +77,11 @@ var INTENT_ARCHETYPES = {
     name: "transform",
     description: "Change format or style while preserving content",
     examples: ["markdown \u2192 html", "formal \u2192 casual", "translate"]
+  },
+  judge: {
+    name: "judge",
+    description: "Pairwise comparison of two candidate outputs for the same input",
+    examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"]
   }
 };
 var ALL_ARCHETYPES = Object.keys(INTENT_ARCHETYPES);

package/dist/dialect.mjs

@@ -8,7 +8,7 @@ import {
   hashShape,
   isArchetype,
   learningKey
-} from "./chunk-5TI6PNSK.mjs";
+} from "./chunk-3KQAID63.mjs";
 export {
   ALL_ARCHETYPES,
   DIALECT_VERSION,

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-axAX1Bg0.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-axAX1Bg0.mjs';
+import '../ir-B2dRyJXO.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-C-Wp7HpI.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-C-Wp7HpI.js';
+import '../ir-ClU56aBc.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-CSDweZsl.mjs';
+import '../ir-B2dRyJXO.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-ByN3r0_7.js';
+import '../ir-ClU56aBc.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-axAX1Bg0.mjs';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-CSDweZsl.mjs';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-CSDweZsl.mjs';
+import '../ir-B2dRyJXO.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-C-Wp7HpI.js';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-ByN3r0_7.js';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-ByN3r0_7.js';
+import '../ir-ClU56aBc.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/index.js

@@ -1650,6 +1650,16 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
     { id: "gpt-5.5", grounding: "judgment", reason: "alpha.16: third-provider frontier-tier floor (archetypePerf=9)" }
   ],
+  // alpha.62 (eval spine) — pairwise output comparison. Same reasoning-floor
+  // posture as critique (a verdict from a weak judge is worse than no
+  // verdict); tier 0 anchored on the CURRENT opus (4-8, s64 roster). Strict
+  // JSON output, so every tier declares native structured output.
+  judge: [
+    { id: "claude-opus-4-8", grounding: "judgment", reason: "Highest reasoning bar for pairwise verdicts \u2014 current opus (s64 roster)" },
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Same-provider walk-down on 429" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
+    { id: "gpt-5.5", grounding: "judgment", reason: "Third-provider frontier-tier floor" }
+  ],
   // Reasoning matters — Sonnet primary; walk UP to Opus on 429.
   plan: [
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reasoning + cost balance \u2014 engineer pick" },

package/dist/glassbox-routes/index.mjs

@@ -1,7 +1,7 @@
 import {
   ARCHETYPE_FLOOR_DEFAULT,
   getDefaultFallbackChain
-} from "../chunk-IIMPJZNH.mjs";
+} from "../chunk-YZRPNSSQ.mjs";
 import {
   tryGetProfile
 } from "../chunk-QKXTMVCT.mjs";

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-CSDweZsl.mjs';
+import '../../ir-B2dRyJXO.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-ByN3r0_7.js';
+import '../../ir-ClU56aBc.js';
 import '../../dialect.js';
 
 /**