@warmdrift/kgauto-compiler 2.0.0-alpha.27 → 2.0.0-alpha.29

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

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-o9etg93a.mjs';
-import '../ir-B9zqlwjH.mjs';
+import { G as GlassboxEvent } from '../types-BjrIFPGe.mjs';
+import { h as Adapter, u as SectionKind } from '../ir-De2AQtlr.mjs';
 import '../dialect.mjs';
 
 /**
@@ -30,11 +30,122 @@ interface TraceSummary {
     tokensOut: number;
     estimatedCostUsd: number;
 }
+
+interface AdvisoryRecord {
+    level: 'info' | 'warn' | 'critical';
+    /** Stable advisory identifier, e.g. "caching-off-on-claude". */
+    code: string;
+    /** Consumer-renderable message — no internal jargon ("L-040", "R3" etc.). */
+    message: string;
+    /** Optional secondary one-liner. Renders below `message` in italics. */
+    suggestion?: string;
+    /** Deep link to the relevant section of `interfaces/kgauto.md` or docs. */
+    docsUrl?: string;
+    /**
+     * alpha.28+ — closed-union adaptation hint surfaced by the advisor when
+     * the advisory can be auto-mitigated by a config knob. Renderer surfaces
+     * as `→ try toolOrchestration: 'sequential'` on the advisory row.
+     *
+     * MUST stay byte-identical to Builder C's
+     * `BestPracticeAdvisory.suggestedAdaptation` shape (verified at Phase 2
+     * integration; the Adapter type itself is the contract).
+     */
+    suggestedAdaptation?: Adapter;
+}
+/**
+ * Cost-equivalent alternative the chain could have served. Computed at
+ * detail-view time by `computeCounterfactuals()` against the served row's
+ * observed token counts + archetype + cache state. Up to 2 entries, sorted
+ * cheapest first.
+ */
+interface TraceCounterfactual {
+    modelId: string;
+    estimatedCostUsd: number;
+    /** servedCostUsd - estimatedCostUsd (always > 0; only ≥10% savings kept). */
+    savingsUsd: number;
+    /** 0-100. */
+    savingsPercent: number;
+    /** Plain-English rationale tying archetype + perf score. */
+    reason: string;
+}
+/**
+ * Derived axis-health tri-state for the three Glass-Box dots
+ * (input-ratio · cache · fallback). Renderer reads; transformer computes.
+ *
+ * Thresholds (locked in design contract Phase 0):
+ *   - inputRatio: green ≤ 0.65 · yellow 0.65–0.85 · red > 0.85
+ *   - cache (only when historyCacheableTokens > 1000):
+ *       green if inputCacheHitRatio ≥ 0.5
+ *       yellow if 0.1 ≤ inputCacheHitRatio < 0.5
+ *       red if inputCacheHitRatio < 0.1
+ *       na if historyCacheableTokens ≤ 1000
+ *   - fallback: red iff fellOverFrom !== undefined && fellOverFrom !== target
+ */
+interface TraceHealth {
+    inputRatioStatus: 'green' | 'yellow' | 'red';
+    cacheStatus: 'green' | 'yellow' | 'red' | 'na';
+    fallbackStatus: 'green' | 'red';
+}
+/**
+ * alpha.29+ — wire-boundary representation of a translator section-rewrite.
+ *
+ * Distinct from the package-internal `SectionRewrite` type in `ir.ts`: this
+ * shape drops `originalText` + `transformedText` because those may carry
+ * consumer PII. The renderer shows the `rule` + `summary` only. Full text
+ * stays on `compile_outcomes.section_rewrites_applied` (Supabase row), gated
+ * by RLS for brain-side cross-app learning.
+ */
+interface TraceSectionRewrite {
+    /** Stable id of the rewritten section. */
+    sectionId: string;
+    /** Section-kind discriminator that triggered the rewrite. */
+    kind: SectionKind;
+    /** Stable rule identifier (e.g. `'sequential-tool-cliff-below-floor'`). */
+    rule: string;
+    /**
+     * Plain-English one-liner describing what fired and why. Renderer surfaces
+     * this on the Coaching card; no internal jargon ("L-040", "below floor").
+     */
+    summary: string;
+}
 interface TraceDetail extends TraceSummary {
-    mutationsApplied: unknown[];
-    advisories: unknown[];
-    rawRequest?: unknown;
-    rawResponse?: unknown;
+    mutationsApplied: string[];
+    advisories: AdvisoryRecord[];
+    rawRequest?: string;
+    rawResponse?: string;
+    /** Set when consumer passed a forceModel / fallback fired. */
+    requestedModel?: string;
+    /** Provider finish reason — 'stop' / 'max_tokens' / 'tool_use' / etc. */
+    finishReason?: string;
+    /** Time to first token (ms); populated when provider surfaces it. */
+    ttftMs?: number;
+    /** End-to-end wall-clock (ms); from migration 018. */
+    totalMs?: number;
+    /** Tools kept after relevance pass. */
+    toolsCount?: number;
+    /** Number of history messages at compile time. */
+    historyDepth?: number;
+    /** Rendered system prompt size in characters. */
+    systemPromptChars?: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    historyCacheableTokens: number;
+    /** Derived: cacheReadInputTokens / max(tokensIn, 1). 0-1. */
+    inputCacheHitRatio: number;
+    fellOverFrom?: string;
+    fallbackReason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
+    /** Up to 2 alternatives. Empty array (not undefined) when none qualify. */
+    counterfactuals?: TraceCounterfactual[];
+    /** Undefined when 7d volume < 5/day (insufficient data). */
+    projectedDailyCostUsd?: number;
+    /**
+     * alpha.29+ — translator activity for this trace. Empty array (not
+     * undefined) when no rewrites fired or pre-019 row. Surfaced in the
+     * Glass-Box Coaching card as synthetic info-level rows. PII-safe by
+     * construction: only sectionId + kind + rule + summary cross the wire.
+     */
+    sectionRewritesApplied: TraceSectionRewrite[];
+    health: TraceHealth;
 }
 
 /**

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

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-bt0aVJb8.js';
-import '../ir-B_XX2LAO.js';
+import { G as GlassboxEvent } from '../types-D_JAhCv4.js';
+import { h as Adapter, u as SectionKind } from '../ir-BIAT9gJk.js';
 import '../dialect.js';
 
 /**
@@ -30,11 +30,122 @@ interface TraceSummary {
     tokensOut: number;
     estimatedCostUsd: number;
 }
+
+interface AdvisoryRecord {
+    level: 'info' | 'warn' | 'critical';
+    /** Stable advisory identifier, e.g. "caching-off-on-claude". */
+    code: string;
+    /** Consumer-renderable message — no internal jargon ("L-040", "R3" etc.). */
+    message: string;
+    /** Optional secondary one-liner. Renders below `message` in italics. */
+    suggestion?: string;
+    /** Deep link to the relevant section of `interfaces/kgauto.md` or docs. */
+    docsUrl?: string;
+    /**
+     * alpha.28+ — closed-union adaptation hint surfaced by the advisor when
+     * the advisory can be auto-mitigated by a config knob. Renderer surfaces
+     * as `→ try toolOrchestration: 'sequential'` on the advisory row.
+     *
+     * MUST stay byte-identical to Builder C's
+     * `BestPracticeAdvisory.suggestedAdaptation` shape (verified at Phase 2
+     * integration; the Adapter type itself is the contract).
+     */
+    suggestedAdaptation?: Adapter;
+}
+/**
+ * Cost-equivalent alternative the chain could have served. Computed at
+ * detail-view time by `computeCounterfactuals()` against the served row's
+ * observed token counts + archetype + cache state. Up to 2 entries, sorted
+ * cheapest first.
+ */
+interface TraceCounterfactual {
+    modelId: string;
+    estimatedCostUsd: number;
+    /** servedCostUsd - estimatedCostUsd (always > 0; only ≥10% savings kept). */
+    savingsUsd: number;
+    /** 0-100. */
+    savingsPercent: number;
+    /** Plain-English rationale tying archetype + perf score. */
+    reason: string;
+}
+/**
+ * Derived axis-health tri-state for the three Glass-Box dots
+ * (input-ratio · cache · fallback). Renderer reads; transformer computes.
+ *
+ * Thresholds (locked in design contract Phase 0):
+ *   - inputRatio: green ≤ 0.65 · yellow 0.65–0.85 · red > 0.85
+ *   - cache (only when historyCacheableTokens > 1000):
+ *       green if inputCacheHitRatio ≥ 0.5
+ *       yellow if 0.1 ≤ inputCacheHitRatio < 0.5
+ *       red if inputCacheHitRatio < 0.1
+ *       na if historyCacheableTokens ≤ 1000
+ *   - fallback: red iff fellOverFrom !== undefined && fellOverFrom !== target
+ */
+interface TraceHealth {
+    inputRatioStatus: 'green' | 'yellow' | 'red';
+    cacheStatus: 'green' | 'yellow' | 'red' | 'na';
+    fallbackStatus: 'green' | 'red';
+}
+/**
+ * alpha.29+ — wire-boundary representation of a translator section-rewrite.
+ *
+ * Distinct from the package-internal `SectionRewrite` type in `ir.ts`: this
+ * shape drops `originalText` + `transformedText` because those may carry
+ * consumer PII. The renderer shows the `rule` + `summary` only. Full text
+ * stays on `compile_outcomes.section_rewrites_applied` (Supabase row), gated
+ * by RLS for brain-side cross-app learning.
+ */
+interface TraceSectionRewrite {
+    /** Stable id of the rewritten section. */
+    sectionId: string;
+    /** Section-kind discriminator that triggered the rewrite. */
+    kind: SectionKind;
+    /** Stable rule identifier (e.g. `'sequential-tool-cliff-below-floor'`). */
+    rule: string;
+    /**
+     * Plain-English one-liner describing what fired and why. Renderer surfaces
+     * this on the Coaching card; no internal jargon ("L-040", "below floor").
+     */
+    summary: string;
+}
 interface TraceDetail extends TraceSummary {
-    mutationsApplied: unknown[];
-    advisories: unknown[];
-    rawRequest?: unknown;
-    rawResponse?: unknown;
+    mutationsApplied: string[];
+    advisories: AdvisoryRecord[];
+    rawRequest?: string;
+    rawResponse?: string;
+    /** Set when consumer passed a forceModel / fallback fired. */
+    requestedModel?: string;
+    /** Provider finish reason — 'stop' / 'max_tokens' / 'tool_use' / etc. */
+    finishReason?: string;
+    /** Time to first token (ms); populated when provider surfaces it. */
+    ttftMs?: number;
+    /** End-to-end wall-clock (ms); from migration 018. */
+    totalMs?: number;
+    /** Tools kept after relevance pass. */
+    toolsCount?: number;
+    /** Number of history messages at compile time. */
+    historyDepth?: number;
+    /** Rendered system prompt size in characters. */
+    systemPromptChars?: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    historyCacheableTokens: number;
+    /** Derived: cacheReadInputTokens / max(tokensIn, 1). 0-1. */
+    inputCacheHitRatio: number;
+    fellOverFrom?: string;
+    fallbackReason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
+    /** Up to 2 alternatives. Empty array (not undefined) when none qualify. */
+    counterfactuals?: TraceCounterfactual[];
+    /** Undefined when 7d volume < 5/day (insufficient data). */
+    projectedDailyCostUsd?: number;
+    /**
+     * alpha.29+ — translator activity for this trace. Empty array (not
+     * undefined) when no rewrites fired or pre-019 row. Surfaced in the
+     * Glass-Box Coaching card as synthetic info-level rows. PII-safe by
+     * construction: only sectionId + kind + rule + summary cross the wire.
+     */
+    sectionRewritesApplied: TraceSectionRewrite[];
+    health: TraceHealth;
 }
 
 /**