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

package/dist/{ir-B_XX2LAO.d.ts → ir-5W0efxt9.d.ts}

@@ -346,7 +346,57 @@ interface BestPracticeAdvisory {
      * - `'architecture-change'` — the issue isn't fixable at the kgauto layer
      */
     recommendationType?: 'model-swap' | 'prompt-fix' | 'caching-fix' | 'no-ai-needed' | 'tier-down' | 'architecture-change';
+    /**
+     * alpha.28 — when a rule wants to surface a specific structural adaptation
+     * (not just a swap or a prompt fix), it attaches the adapter shape here.
+     * Shape is the canonical {@link Adapter} discriminated union defined in
+     * this module; `compatibility.ts` re-exports it so
+     * `getModelCompatibility()` and `BestPracticeAdvisory.suggestedAdaptation`
+     * share one source of truth.
+     *
+     * Today fired by `archetype-perf-floor-breach` (alpha.28) when a
+     * documented adapter exists for the chosen model's archetype cliff.
+     * Absent on rules without a structural adapter (caching-off-on-claude,
+     * tool-bloat, etc.) and on the `reject` branch of
+     * `archetype-perf-floor-breach` where no adapter would help.
+     *
+     * CLOSED discriminated union (R3 from consultation doc) — future adapter
+     * parameters extend the union in `compatibility.ts` in named alpha
+     * releases. No `| string` escape hatch; consumer code can write
+     * exhaustive `switch (suggestedAdaptation.parameter)`.
+     *
+     * Phase 2 cross-builder coherence: Builder A's
+     * `AdvisoryRecord.suggestedAdaptation` (in `glassbox-routes/types.ts`)
+     * MUST type to the same union. Phase 2 integration verifies.
+     */
+    suggestedAdaptation?: Adapter;
 }
+/**
+ * alpha.28 — adapter shape attached to advisories and returned by
+ * `getModelCompatibility()`. A CLOSED discriminated union: future adapter
+ * parameters extend it explicitly in named alpha releases. NO `| string`
+ * escape hatch — consumer policy code SHOULD write exhaustive
+ * `switch (adapter.parameter)` and rely on the compiler to flag
+ * "I added a new adapter parameter and forgot to update consumer policy."
+ *
+ * Defined here (in `ir.ts`, the foundational types module) and re-exported
+ * from `compatibility.ts` for ergonomic consumer imports. Anchoring it
+ * here avoids the import cycle that would form if both files tried to be
+ * the source of truth (ir.ts → compatibility.ts → profiles.ts → ir.ts).
+ *
+ * alpha.28 variants:
+ *   - `{ parameter: 'toolOrchestration'; value: 'sequential'; consequence }`
+ *     Lifts DeepSeek V4-family on `hunt` from the sequential-tool cliff
+ *     (L-040). `consequence` is consumer-renderable plain English.
+ *
+ * Future alpha releases will add e.g. `parallelToolCalls`, `maxTools`,
+ * `thinkingBudget` (per tt-intel-Cairn priority list).
+ */
+type Adapter = {
+    parameter: 'toolOrchestration';
+    value: 'sequential';
+    consequence: string;
+};
 interface CompileResult {
     /** Unique handle for this call — pass to record() to correlate the outcome. */
     handle: string;
@@ -695,6 +745,41 @@ interface RecordInput {
      * Empty array / undefined → no second POST fires.
      */
     advisories?: BestPracticeAdvisory[];
+    /**
+     * alpha.28 — Glass-Box renderer substrate fields (migration 018).
+     *
+     * All optional. When omitted, brain stores NULL and the renderer falls
+     * back to "—" / hidden rows. Library callers (`call.ts`) populate what
+     * they observe; adapter / SDK consumers can populate the rest from their
+     * own provider response surface.
+     */
+    /**
+     * Provider finish reason. Captured from NormalizedResponse.finishReason
+     * (Anthropic `stop_reason`, Google `finishReason`, OpenAI `finish_reason`).
+     * Lower-case canonicalization is the brain's job; consumers can pass
+     * raw provider strings.
+     */
+    finishReason?: string;
+    /**
+     * End-to-end wall-clock latency in ms. Distinct from `latencyMs` only
+     * insofar as `latencyMs` was the historical name for the same metric;
+     * `totalMs` is the new column on `compile_outcomes` (migration 018).
+     * When omitted, brain mirrors `latency_ms`.
+     */
+    totalMs?: number;
+    /** Tools kept after the tool-relevance pass. */
+    toolsCount?: number;
+    /** Number of history messages at compile time. */
+    historyDepth?: number;
+    /** Rendered system prompt size in characters. */
+    systemPromptChars?: number;
+    /** Model originally targeted when a fallback fired. */
+    fellOverFrom?: string;
+    /**
+     * Why the fallback fired. Closed set mirroring CallResult.fallbackReason —
+     * keep in sync with the wire-contract enum (TraceDetail.fallbackReason).
+     */
+    fallbackReason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
 }
 /**
  * alpha.20 Entry 4: kinds of consumer-declared outcomes feeding the quality
@@ -834,4 +919,4 @@ interface PerAxisMetrics {
 /** Per-axis metrics keyed by model — used for chain-comparison views. */
 type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type PerAxisMetrics as h, type Provider as i, type ChainEntry as j, type CallAttempt as k, CallError as l, type ChainWithGrounding as m, type Constraints as n, type MutationApplied as o, type NormalizedTokens as p, type OutcomeKind as q, type PerAxisMetricsByModel as r, type PromptSection as s, type ToolDefinition as t };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Adapter as h, type PerAxisMetrics as i, type Provider as j, type ChainEntry as k, type CallAttempt as l, CallError as m, type ChainWithGrounding as n, type Constraints as o, type MutationApplied as p, type NormalizedTokens as q, type OutcomeKind as r, type PerAxisMetricsByModel as s, type PromptSection as t, type ToolDefinition as u };

package/dist/{ir-B9zqlwjH.d.mts → ir-MXCJA8L7.d.mts}

@@ -346,7 +346,57 @@ interface BestPracticeAdvisory {
      * - `'architecture-change'` — the issue isn't fixable at the kgauto layer
      */
     recommendationType?: 'model-swap' | 'prompt-fix' | 'caching-fix' | 'no-ai-needed' | 'tier-down' | 'architecture-change';
+    /**
+     * alpha.28 — when a rule wants to surface a specific structural adaptation
+     * (not just a swap or a prompt fix), it attaches the adapter shape here.
+     * Shape is the canonical {@link Adapter} discriminated union defined in
+     * this module; `compatibility.ts` re-exports it so
+     * `getModelCompatibility()` and `BestPracticeAdvisory.suggestedAdaptation`
+     * share one source of truth.
+     *
+     * Today fired by `archetype-perf-floor-breach` (alpha.28) when a
+     * documented adapter exists for the chosen model's archetype cliff.
+     * Absent on rules without a structural adapter (caching-off-on-claude,
+     * tool-bloat, etc.) and on the `reject` branch of
+     * `archetype-perf-floor-breach` where no adapter would help.
+     *
+     * CLOSED discriminated union (R3 from consultation doc) — future adapter
+     * parameters extend the union in `compatibility.ts` in named alpha
+     * releases. No `| string` escape hatch; consumer code can write
+     * exhaustive `switch (suggestedAdaptation.parameter)`.
+     *
+     * Phase 2 cross-builder coherence: Builder A's
+     * `AdvisoryRecord.suggestedAdaptation` (in `glassbox-routes/types.ts`)
+     * MUST type to the same union. Phase 2 integration verifies.
+     */
+    suggestedAdaptation?: Adapter;
 }
+/**
+ * alpha.28 — adapter shape attached to advisories and returned by
+ * `getModelCompatibility()`. A CLOSED discriminated union: future adapter
+ * parameters extend it explicitly in named alpha releases. NO `| string`
+ * escape hatch — consumer policy code SHOULD write exhaustive
+ * `switch (adapter.parameter)` and rely on the compiler to flag
+ * "I added a new adapter parameter and forgot to update consumer policy."
+ *
+ * Defined here (in `ir.ts`, the foundational types module) and re-exported
+ * from `compatibility.ts` for ergonomic consumer imports. Anchoring it
+ * here avoids the import cycle that would form if both files tried to be
+ * the source of truth (ir.ts → compatibility.ts → profiles.ts → ir.ts).
+ *
+ * alpha.28 variants:
+ *   - `{ parameter: 'toolOrchestration'; value: 'sequential'; consequence }`
+ *     Lifts DeepSeek V4-family on `hunt` from the sequential-tool cliff
+ *     (L-040). `consequence` is consumer-renderable plain English.
+ *
+ * Future alpha releases will add e.g. `parallelToolCalls`, `maxTools`,
+ * `thinkingBudget` (per tt-intel-Cairn priority list).
+ */
+type Adapter = {
+    parameter: 'toolOrchestration';
+    value: 'sequential';
+    consequence: string;
+};
 interface CompileResult {
     /** Unique handle for this call — pass to record() to correlate the outcome. */
     handle: string;
@@ -695,6 +745,41 @@ interface RecordInput {
      * Empty array / undefined → no second POST fires.
      */
     advisories?: BestPracticeAdvisory[];
+    /**
+     * alpha.28 — Glass-Box renderer substrate fields (migration 018).
+     *
+     * All optional. When omitted, brain stores NULL and the renderer falls
+     * back to "—" / hidden rows. Library callers (`call.ts`) populate what
+     * they observe; adapter / SDK consumers can populate the rest from their
+     * own provider response surface.
+     */
+    /**
+     * Provider finish reason. Captured from NormalizedResponse.finishReason
+     * (Anthropic `stop_reason`, Google `finishReason`, OpenAI `finish_reason`).
+     * Lower-case canonicalization is the brain's job; consumers can pass
+     * raw provider strings.
+     */
+    finishReason?: string;
+    /**
+     * End-to-end wall-clock latency in ms. Distinct from `latencyMs` only
+     * insofar as `latencyMs` was the historical name for the same metric;
+     * `totalMs` is the new column on `compile_outcomes` (migration 018).
+     * When omitted, brain mirrors `latency_ms`.
+     */
+    totalMs?: number;
+    /** Tools kept after the tool-relevance pass. */
+    toolsCount?: number;
+    /** Number of history messages at compile time. */
+    historyDepth?: number;
+    /** Rendered system prompt size in characters. */
+    systemPromptChars?: number;
+    /** Model originally targeted when a fallback fired. */
+    fellOverFrom?: string;
+    /**
+     * Why the fallback fired. Closed set mirroring CallResult.fallbackReason —
+     * keep in sync with the wire-contract enum (TraceDetail.fallbackReason).
+     */
+    fallbackReason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
 }
 /**
  * alpha.20 Entry 4: kinds of consumer-declared outcomes feeding the quality
@@ -834,4 +919,4 @@ interface PerAxisMetrics {
 /** Per-axis metrics keyed by model — used for chain-comparison views. */
 type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type PerAxisMetrics as h, type Provider as i, type ChainEntry as j, type CallAttempt as k, CallError as l, type ChainWithGrounding as m, type Constraints as n, type MutationApplied as o, type NormalizedTokens as p, type OutcomeKind as q, type PerAxisMetricsByModel as r, type PromptSection as s, type ToolDefinition as t };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Adapter as h, type PerAxisMetrics as i, type Provider as j, type ChainEntry as k, type CallAttempt as l, CallError as m, type ChainWithGrounding as n, type Constraints as o, type MutationApplied as p, type NormalizedTokens as q, type OutcomeKind as r, type PerAxisMetricsByModel as s, type PromptSection as t, type ToolDefinition as u };

package/dist/profiles.d.mts

@@ -1,4 +1,4 @@
-import { i as Provider } from './ir-B9zqlwjH.mjs';
+import { j as Provider } from './ir-MXCJA8L7.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**

package/dist/profiles.d.ts

@@ -1,4 +1,4 @@
-import { i as Provider } from './ir-B_XX2LAO.js';
+import { j as Provider } from './ir-5W0efxt9.js';
 import { IntentArchetypeName } from './dialect.js';
 
 /**

package/dist/{types-bt0aVJb8.d.ts → types-CiZ9HLIU.d.ts}

@@ -1,4 +1,4 @@
-import { o as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, k as CallAttempt } from './ir-B_XX2LAO.js';
+import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-5W0efxt9.js';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-o9etg93a.d.mts → types-sDZQzPM6.d.mts}

@@ -1,4 +1,4 @@
-import { o as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, k as CallAttempt } from './ir-B9zqlwjH.mjs';
+import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-MXCJA8L7.mjs';
 
 /**
  * Glass-Box observability types (alpha.17).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.27",
+  "version": "2.0.0-alpha.28",
   "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",