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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -40,7 +40,41 @@ interface PromptSection {
40
40
  * Defaults to insertion order.
41
41
  */
42
42
  weight?: number;
43
+ /**
44
+ * alpha.29+ — declares the section's semantic kind so kgauto can apply
45
+ * model-aware rewrites at compile time. Default `'arbitrary'` (when
46
+ * unset) for full back-compat — pre-alpha.29 sections continue working
47
+ * unchanged.
48
+ *
49
+ * alpha.29 ships rewrites for `tool_call_contract` only. Other kinds are
50
+ * type-accepted but pass through. alpha.30+ will add rewrites for
51
+ * `narration_contract`, `role_intro`, etc.
52
+ *
53
+ * See `translator.ts` for the rewrite engine that consumes this field.
54
+ */
55
+ kind?: SectionKind;
43
56
  }
57
+ /**
58
+ * alpha.29+ — semantic kind tag for a `PromptSection`. The translator
59
+ * (`v2/src/translator.ts`) consumes this to apply model-aware rewrites at
60
+ * compile time. CLOSED union; future kinds extend it explicitly in named
61
+ * alpha releases.
62
+ *
63
+ * alpha.29 ships rewrites for `tool_call_contract` only. Other kinds are
64
+ * type-accepted but pass through.
65
+ *
66
+ * - `role_intro` — "You are a helpful assistant", persona blocks
67
+ * - `tool_call_contract` — tool-use rules ("call X then Y"); the alpha.29
68
+ * translator rewrites this for models with a
69
+ * sequential-tool cliff on the active archetype
70
+ * - `narration_contract` — output-format rules ("don't narrate your steps");
71
+ * alpha.30+ candidate
72
+ * - `user_turn` — when sections carry user content rather than
73
+ * system context (rare)
74
+ * - `reference` — supporting reference data the model may consult
75
+ * - `arbitrary` — explicit pass-through (default when unset)
76
+ */
77
+ type SectionKind = 'role_intro' | 'tool_call_contract' | 'narration_contract' | 'user_turn' | 'reference' | 'arbitrary';
44
78
  interface ToolDefinition {
45
79
  name: string;
46
80
  description?: string;
@@ -262,6 +296,18 @@ type CompiledRequest = {
262
296
  }>;
263
297
  tools?: unknown[];
264
298
  max_tokens?: number;
299
+ /**
300
+ * alpha.29 — emitted only when the translator's wire-overrides set
301
+ * `parallelToolCalls = false`. Shape per Anthropic Messages API docs:
302
+ * `{ type: 'auto', disable_parallel_tool_use: true }`. kgauto defaults
303
+ * to omitting `tool_choice` entirely (Anthropic defaults to auto + parallel),
304
+ * so this field's presence signals an explicit override.
305
+ */
306
+ tool_choice?: {
307
+ type: 'auto' | 'any' | 'tool' | 'none';
308
+ disable_parallel_tool_use?: boolean;
309
+ name?: string;
310
+ };
265
311
  } | {
266
312
  provider: 'google';
267
313
  model: string;
@@ -288,6 +334,12 @@ type CompiledRequest = {
288
334
  tools?: unknown[];
289
335
  response_format?: unknown;
290
336
  reasoning_effort?: string;
337
+ /**
338
+ * alpha.29 — emitted only when the translator's wire-overrides set
339
+ * `parallelToolCalls = false`. OpenAI defaults parallel_tool_calls=true
340
+ * server-side; we explicit-set to false only when overriding.
341
+ */
342
+ parallel_tool_calls?: boolean;
291
343
  } | {
292
344
  provider: 'deepseek';
293
345
  model: string;
@@ -346,6 +398,90 @@ interface BestPracticeAdvisory {
346
398
  * - `'architecture-change'` — the issue isn't fixable at the kgauto layer
347
399
  */
348
400
  recommendationType?: 'model-swap' | 'prompt-fix' | 'caching-fix' | 'no-ai-needed' | 'tier-down' | 'architecture-change';
401
+ /**
402
+ * alpha.28 — when a rule wants to surface a specific structural adaptation
403
+ * (not just a swap or a prompt fix), it attaches the adapter shape here.
404
+ * Shape is the canonical {@link Adapter} discriminated union defined in
405
+ * this module; `compatibility.ts` re-exports it so
406
+ * `getModelCompatibility()` and `BestPracticeAdvisory.suggestedAdaptation`
407
+ * share one source of truth.
408
+ *
409
+ * Today fired by `archetype-perf-floor-breach` (alpha.28) when a
410
+ * documented adapter exists for the chosen model's archetype cliff.
411
+ * Absent on rules without a structural adapter (caching-off-on-claude,
412
+ * tool-bloat, etc.) and on the `reject` branch of
413
+ * `archetype-perf-floor-breach` where no adapter would help.
414
+ *
415
+ * CLOSED discriminated union (R3 from consultation doc) — future adapter
416
+ * parameters extend the union in `compatibility.ts` in named alpha
417
+ * releases. No `| string` escape hatch; consumer code can write
418
+ * exhaustive `switch (suggestedAdaptation.parameter)`.
419
+ *
420
+ * Phase 2 cross-builder coherence: Builder A's
421
+ * `AdvisoryRecord.suggestedAdaptation` (in `glassbox-routes/types.ts`)
422
+ * MUST type to the same union. Phase 2 integration verifies.
423
+ */
424
+ suggestedAdaptation?: Adapter;
425
+ }
426
+ /**
427
+ * alpha.28 — adapter shape attached to advisories and returned by
428
+ * `getModelCompatibility()`. A CLOSED discriminated union: future adapter
429
+ * parameters extend it explicitly in named alpha releases. NO `| string`
430
+ * escape hatch — consumer policy code SHOULD write exhaustive
431
+ * `switch (adapter.parameter)` and rely on the compiler to flag
432
+ * "I added a new adapter parameter and forgot to update consumer policy."
433
+ *
434
+ * Defined here (in `ir.ts`, the foundational types module) and re-exported
435
+ * from `compatibility.ts` for ergonomic consumer imports. Anchoring it
436
+ * here avoids the import cycle that would form if both files tried to be
437
+ * the source of truth (ir.ts → compatibility.ts → profiles.ts → ir.ts).
438
+ *
439
+ * alpha.28 variants:
440
+ * - `{ parameter: 'toolOrchestration'; value: 'sequential'; consequence }`
441
+ * Lifts DeepSeek V4-family on `hunt` from the sequential-tool cliff
442
+ * (L-040). `consequence` is consumer-renderable plain English.
443
+ *
444
+ * Future alpha releases will add e.g. `parallelToolCalls`, `maxTools`,
445
+ * `thinkingBudget` (per tt-intel-Cairn priority list).
446
+ */
447
+ type Adapter = {
448
+ parameter: 'toolOrchestration';
449
+ value: 'sequential';
450
+ consequence: string;
451
+ };
452
+ /**
453
+ * alpha.29+ — record of a single section rewrite fired by the translator at
454
+ * compile time. Surfaces on `CompileResult.sectionRewritesApplied` and (in
455
+ * scrubbed wire form, without original/transformed text) on
456
+ * `TraceDetail.sectionRewritesApplied` for Glass-Box Coaching-card rendering.
457
+ *
458
+ * `originalText` / `transformedText` stay package-internal — they may carry
459
+ * consumer PII. The wire-shape variant (`TraceSectionRewrite` in
460
+ * `glassbox-routes/types.ts`) carries only `summary` for renderer use.
461
+ */
462
+ interface SectionRewrite {
463
+ /** Stable id of the `PromptSection` that was rewritten. */
464
+ sectionId: string;
465
+ /** The `kind` discriminator that matched the rewrite rule. */
466
+ kind: SectionKind;
467
+ /**
468
+ * Stable identifier of the rule that fired (e.g.
469
+ * `'sequential-tool-cliff-below-floor'`). Future rules add named ids; the
470
+ * brain aggregates by this value for cross-app learning.
471
+ */
472
+ rule: string;
473
+ /** The section's text BEFORE the rewrite fired. */
474
+ originalText: string;
475
+ /** The text the translator emitted into the IR for this section. */
476
+ transformedText: string;
477
+ /**
478
+ * Wire-level overrides emitted alongside the text rewrite. Merged into
479
+ * `CompileResult.wireOverrides` by `applySectionRewrites`. alpha.29 ships
480
+ * `parallelToolCalls`; the union extends as more wire-overrides surface.
481
+ */
482
+ wireOverrides?: {
483
+ parallelToolCalls?: boolean;
484
+ };
349
485
  }
350
486
  interface CompileResult {
351
487
  /** Unique handle for this call — pass to record() to correlate the outcome. */
@@ -369,6 +505,29 @@ interface CompileResult {
369
505
  * array when no rules fired. alpha.6 Phase 1.
370
506
  */
371
507
  advisories: BestPracticeAdvisory[];
508
+ /**
509
+ * alpha.29+ — per-section rewrites applied by the translator at compile
510
+ * time. Empty array means no rewrites fired (or pre-alpha.29 behavior —
511
+ * all sections default `kind: 'arbitrary'`, which is pass-through).
512
+ *
513
+ * Surfaces to:
514
+ * - Glass-Box Coaching card (via `TraceDetail.sectionRewritesApplied`,
515
+ * scrubbed of original/transformed text)
516
+ * - brain `compile_outcomes.section_rewrites_applied` (migration 019)
517
+ * for cross-app learning
518
+ */
519
+ sectionRewritesApplied: SectionRewrite[];
520
+ /**
521
+ * alpha.29+ — wire-level overrides emitted by translator rewrites. The
522
+ * provider lowering pass threads these through to the wire request before
523
+ * emit. Today only `parallelToolCalls: boolean`; the type extends as more
524
+ * wire-overrides surface.
525
+ *
526
+ * Undefined when no rewrite emitted overrides — the common case.
527
+ */
528
+ wireOverrides?: {
529
+ parallelToolCalls?: boolean;
530
+ };
372
531
  /** Diagnostics for caller-side logging. */
373
532
  diagnostics: {
374
533
  sectionsKept: number;
@@ -695,6 +854,41 @@ interface RecordInput {
695
854
  * Empty array / undefined → no second POST fires.
696
855
  */
697
856
  advisories?: BestPracticeAdvisory[];
857
+ /**
858
+ * alpha.28 — Glass-Box renderer substrate fields (migration 018).
859
+ *
860
+ * All optional. When omitted, brain stores NULL and the renderer falls
861
+ * back to "—" / hidden rows. Library callers (`call.ts`) populate what
862
+ * they observe; adapter / SDK consumers can populate the rest from their
863
+ * own provider response surface.
864
+ */
865
+ /**
866
+ * Provider finish reason. Captured from NormalizedResponse.finishReason
867
+ * (Anthropic `stop_reason`, Google `finishReason`, OpenAI `finish_reason`).
868
+ * Lower-case canonicalization is the brain's job; consumers can pass
869
+ * raw provider strings.
870
+ */
871
+ finishReason?: string;
872
+ /**
873
+ * End-to-end wall-clock latency in ms. Distinct from `latencyMs` only
874
+ * insofar as `latencyMs` was the historical name for the same metric;
875
+ * `totalMs` is the new column on `compile_outcomes` (migration 018).
876
+ * When omitted, brain mirrors `latency_ms`.
877
+ */
878
+ totalMs?: number;
879
+ /** Tools kept after the tool-relevance pass. */
880
+ toolsCount?: number;
881
+ /** Number of history messages at compile time. */
882
+ historyDepth?: number;
883
+ /** Rendered system prompt size in characters. */
884
+ systemPromptChars?: number;
885
+ /** Model originally targeted when a fallback fired. */
886
+ fellOverFrom?: string;
887
+ /**
888
+ * Why the fallback fired. Closed set mirroring CallResult.fallbackReason —
889
+ * keep in sync with the wire-contract enum (TraceDetail.fallbackReason).
890
+ */
891
+ fallbackReason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
698
892
  }
699
893
  /**
700
894
  * alpha.20 Entry 4: kinds of consumer-declared outcomes feeding the quality
@@ -834,4 +1028,4 @@ interface PerAxisMetrics {
834
1028
  /** Per-axis metrics keyed by model — used for chain-comparison views. */
835
1029
  type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
836
1030
 
837
- 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 };
1031
+ 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 SectionRewrite as S, 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 SectionKind as u, type ToolDefinition as v };
@@ -40,7 +40,41 @@ interface PromptSection {
40
40
  * Defaults to insertion order.
41
41
  */
42
42
  weight?: number;
43
+ /**
44
+ * alpha.29+ — declares the section's semantic kind so kgauto can apply
45
+ * model-aware rewrites at compile time. Default `'arbitrary'` (when
46
+ * unset) for full back-compat — pre-alpha.29 sections continue working
47
+ * unchanged.
48
+ *
49
+ * alpha.29 ships rewrites for `tool_call_contract` only. Other kinds are
50
+ * type-accepted but pass through. alpha.30+ will add rewrites for
51
+ * `narration_contract`, `role_intro`, etc.
52
+ *
53
+ * See `translator.ts` for the rewrite engine that consumes this field.
54
+ */
55
+ kind?: SectionKind;
43
56
  }
57
+ /**
58
+ * alpha.29+ — semantic kind tag for a `PromptSection`. The translator
59
+ * (`v2/src/translator.ts`) consumes this to apply model-aware rewrites at
60
+ * compile time. CLOSED union; future kinds extend it explicitly in named
61
+ * alpha releases.
62
+ *
63
+ * alpha.29 ships rewrites for `tool_call_contract` only. Other kinds are
64
+ * type-accepted but pass through.
65
+ *
66
+ * - `role_intro` — "You are a helpful assistant", persona blocks
67
+ * - `tool_call_contract` — tool-use rules ("call X then Y"); the alpha.29
68
+ * translator rewrites this for models with a
69
+ * sequential-tool cliff on the active archetype
70
+ * - `narration_contract` — output-format rules ("don't narrate your steps");
71
+ * alpha.30+ candidate
72
+ * - `user_turn` — when sections carry user content rather than
73
+ * system context (rare)
74
+ * - `reference` — supporting reference data the model may consult
75
+ * - `arbitrary` — explicit pass-through (default when unset)
76
+ */
77
+ type SectionKind = 'role_intro' | 'tool_call_contract' | 'narration_contract' | 'user_turn' | 'reference' | 'arbitrary';
44
78
  interface ToolDefinition {
45
79
  name: string;
46
80
  description?: string;
@@ -262,6 +296,18 @@ type CompiledRequest = {
262
296
  }>;
263
297
  tools?: unknown[];
264
298
  max_tokens?: number;
299
+ /**
300
+ * alpha.29 — emitted only when the translator's wire-overrides set
301
+ * `parallelToolCalls = false`. Shape per Anthropic Messages API docs:
302
+ * `{ type: 'auto', disable_parallel_tool_use: true }`. kgauto defaults
303
+ * to omitting `tool_choice` entirely (Anthropic defaults to auto + parallel),
304
+ * so this field's presence signals an explicit override.
305
+ */
306
+ tool_choice?: {
307
+ type: 'auto' | 'any' | 'tool' | 'none';
308
+ disable_parallel_tool_use?: boolean;
309
+ name?: string;
310
+ };
265
311
  } | {
266
312
  provider: 'google';
267
313
  model: string;
@@ -288,6 +334,12 @@ type CompiledRequest = {
288
334
  tools?: unknown[];
289
335
  response_format?: unknown;
290
336
  reasoning_effort?: string;
337
+ /**
338
+ * alpha.29 — emitted only when the translator's wire-overrides set
339
+ * `parallelToolCalls = false`. OpenAI defaults parallel_tool_calls=true
340
+ * server-side; we explicit-set to false only when overriding.
341
+ */
342
+ parallel_tool_calls?: boolean;
291
343
  } | {
292
344
  provider: 'deepseek';
293
345
  model: string;
@@ -346,6 +398,90 @@ interface BestPracticeAdvisory {
346
398
  * - `'architecture-change'` — the issue isn't fixable at the kgauto layer
347
399
  */
348
400
  recommendationType?: 'model-swap' | 'prompt-fix' | 'caching-fix' | 'no-ai-needed' | 'tier-down' | 'architecture-change';
401
+ /**
402
+ * alpha.28 — when a rule wants to surface a specific structural adaptation
403
+ * (not just a swap or a prompt fix), it attaches the adapter shape here.
404
+ * Shape is the canonical {@link Adapter} discriminated union defined in
405
+ * this module; `compatibility.ts` re-exports it so
406
+ * `getModelCompatibility()` and `BestPracticeAdvisory.suggestedAdaptation`
407
+ * share one source of truth.
408
+ *
409
+ * Today fired by `archetype-perf-floor-breach` (alpha.28) when a
410
+ * documented adapter exists for the chosen model's archetype cliff.
411
+ * Absent on rules without a structural adapter (caching-off-on-claude,
412
+ * tool-bloat, etc.) and on the `reject` branch of
413
+ * `archetype-perf-floor-breach` where no adapter would help.
414
+ *
415
+ * CLOSED discriminated union (R3 from consultation doc) — future adapter
416
+ * parameters extend the union in `compatibility.ts` in named alpha
417
+ * releases. No `| string` escape hatch; consumer code can write
418
+ * exhaustive `switch (suggestedAdaptation.parameter)`.
419
+ *
420
+ * Phase 2 cross-builder coherence: Builder A's
421
+ * `AdvisoryRecord.suggestedAdaptation` (in `glassbox-routes/types.ts`)
422
+ * MUST type to the same union. Phase 2 integration verifies.
423
+ */
424
+ suggestedAdaptation?: Adapter;
425
+ }
426
+ /**
427
+ * alpha.28 — adapter shape attached to advisories and returned by
428
+ * `getModelCompatibility()`. A CLOSED discriminated union: future adapter
429
+ * parameters extend it explicitly in named alpha releases. NO `| string`
430
+ * escape hatch — consumer policy code SHOULD write exhaustive
431
+ * `switch (adapter.parameter)` and rely on the compiler to flag
432
+ * "I added a new adapter parameter and forgot to update consumer policy."
433
+ *
434
+ * Defined here (in `ir.ts`, the foundational types module) and re-exported
435
+ * from `compatibility.ts` for ergonomic consumer imports. Anchoring it
436
+ * here avoids the import cycle that would form if both files tried to be
437
+ * the source of truth (ir.ts → compatibility.ts → profiles.ts → ir.ts).
438
+ *
439
+ * alpha.28 variants:
440
+ * - `{ parameter: 'toolOrchestration'; value: 'sequential'; consequence }`
441
+ * Lifts DeepSeek V4-family on `hunt` from the sequential-tool cliff
442
+ * (L-040). `consequence` is consumer-renderable plain English.
443
+ *
444
+ * Future alpha releases will add e.g. `parallelToolCalls`, `maxTools`,
445
+ * `thinkingBudget` (per tt-intel-Cairn priority list).
446
+ */
447
+ type Adapter = {
448
+ parameter: 'toolOrchestration';
449
+ value: 'sequential';
450
+ consequence: string;
451
+ };
452
+ /**
453
+ * alpha.29+ — record of a single section rewrite fired by the translator at
454
+ * compile time. Surfaces on `CompileResult.sectionRewritesApplied` and (in
455
+ * scrubbed wire form, without original/transformed text) on
456
+ * `TraceDetail.sectionRewritesApplied` for Glass-Box Coaching-card rendering.
457
+ *
458
+ * `originalText` / `transformedText` stay package-internal — they may carry
459
+ * consumer PII. The wire-shape variant (`TraceSectionRewrite` in
460
+ * `glassbox-routes/types.ts`) carries only `summary` for renderer use.
461
+ */
462
+ interface SectionRewrite {
463
+ /** Stable id of the `PromptSection` that was rewritten. */
464
+ sectionId: string;
465
+ /** The `kind` discriminator that matched the rewrite rule. */
466
+ kind: SectionKind;
467
+ /**
468
+ * Stable identifier of the rule that fired (e.g.
469
+ * `'sequential-tool-cliff-below-floor'`). Future rules add named ids; the
470
+ * brain aggregates by this value for cross-app learning.
471
+ */
472
+ rule: string;
473
+ /** The section's text BEFORE the rewrite fired. */
474
+ originalText: string;
475
+ /** The text the translator emitted into the IR for this section. */
476
+ transformedText: string;
477
+ /**
478
+ * Wire-level overrides emitted alongside the text rewrite. Merged into
479
+ * `CompileResult.wireOverrides` by `applySectionRewrites`. alpha.29 ships
480
+ * `parallelToolCalls`; the union extends as more wire-overrides surface.
481
+ */
482
+ wireOverrides?: {
483
+ parallelToolCalls?: boolean;
484
+ };
349
485
  }
350
486
  interface CompileResult {
351
487
  /** Unique handle for this call — pass to record() to correlate the outcome. */
@@ -369,6 +505,29 @@ interface CompileResult {
369
505
  * array when no rules fired. alpha.6 Phase 1.
370
506
  */
371
507
  advisories: BestPracticeAdvisory[];
508
+ /**
509
+ * alpha.29+ — per-section rewrites applied by the translator at compile
510
+ * time. Empty array means no rewrites fired (or pre-alpha.29 behavior —
511
+ * all sections default `kind: 'arbitrary'`, which is pass-through).
512
+ *
513
+ * Surfaces to:
514
+ * - Glass-Box Coaching card (via `TraceDetail.sectionRewritesApplied`,
515
+ * scrubbed of original/transformed text)
516
+ * - brain `compile_outcomes.section_rewrites_applied` (migration 019)
517
+ * for cross-app learning
518
+ */
519
+ sectionRewritesApplied: SectionRewrite[];
520
+ /**
521
+ * alpha.29+ — wire-level overrides emitted by translator rewrites. The
522
+ * provider lowering pass threads these through to the wire request before
523
+ * emit. Today only `parallelToolCalls: boolean`; the type extends as more
524
+ * wire-overrides surface.
525
+ *
526
+ * Undefined when no rewrite emitted overrides — the common case.
527
+ */
528
+ wireOverrides?: {
529
+ parallelToolCalls?: boolean;
530
+ };
372
531
  /** Diagnostics for caller-side logging. */
373
532
  diagnostics: {
374
533
  sectionsKept: number;
@@ -695,6 +854,41 @@ interface RecordInput {
695
854
  * Empty array / undefined → no second POST fires.
696
855
  */
697
856
  advisories?: BestPracticeAdvisory[];
857
+ /**
858
+ * alpha.28 — Glass-Box renderer substrate fields (migration 018).
859
+ *
860
+ * All optional. When omitted, brain stores NULL and the renderer falls
861
+ * back to "—" / hidden rows. Library callers (`call.ts`) populate what
862
+ * they observe; adapter / SDK consumers can populate the rest from their
863
+ * own provider response surface.
864
+ */
865
+ /**
866
+ * Provider finish reason. Captured from NormalizedResponse.finishReason
867
+ * (Anthropic `stop_reason`, Google `finishReason`, OpenAI `finish_reason`).
868
+ * Lower-case canonicalization is the brain's job; consumers can pass
869
+ * raw provider strings.
870
+ */
871
+ finishReason?: string;
872
+ /**
873
+ * End-to-end wall-clock latency in ms. Distinct from `latencyMs` only
874
+ * insofar as `latencyMs` was the historical name for the same metric;
875
+ * `totalMs` is the new column on `compile_outcomes` (migration 018).
876
+ * When omitted, brain mirrors `latency_ms`.
877
+ */
878
+ totalMs?: number;
879
+ /** Tools kept after the tool-relevance pass. */
880
+ toolsCount?: number;
881
+ /** Number of history messages at compile time. */
882
+ historyDepth?: number;
883
+ /** Rendered system prompt size in characters. */
884
+ systemPromptChars?: number;
885
+ /** Model originally targeted when a fallback fired. */
886
+ fellOverFrom?: string;
887
+ /**
888
+ * Why the fallback fired. Closed set mirroring CallResult.fallbackReason —
889
+ * keep in sync with the wire-contract enum (TraceDetail.fallbackReason).
890
+ */
891
+ fallbackReason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
698
892
  }
699
893
  /**
700
894
  * alpha.20 Entry 4: kinds of consumer-declared outcomes feeding the quality
@@ -834,4 +1028,4 @@ interface PerAxisMetrics {
834
1028
  /** Per-axis metrics keyed by model — used for chain-comparison views. */
835
1029
  type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
836
1030
 
837
- 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 };
1031
+ 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 SectionRewrite as S, 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 SectionKind as u, type ToolDefinition as v };
@@ -1,4 +1,4 @@
1
- import { i as Provider } from './ir-B9zqlwjH.mjs';
1
+ import { j as Provider } from './ir-De2AQtlr.mjs';
2
2
  import { IntentArchetypeName } from './dialect.mjs';
3
3
 
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { i as Provider } from './ir-B_XX2LAO.js';
1
+ import { j as Provider } from './ir-BIAT9gJk.js';
2
2
  import { IntentArchetypeName } from './dialect.js';
3
3
 
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { o as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, k as CallAttempt } from './ir-B9zqlwjH.mjs';
1
+ import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-De2AQtlr.mjs';
2
2
 
3
3
  /**
4
4
  * Glass-Box observability types (alpha.17).
@@ -1,4 +1,4 @@
1
- import { o as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, k as CallAttempt } from './ir-B_XX2LAO.js';
1
+ import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-BIAT9gJk.js';
2
2
 
3
3
  /**
4
4
  * Glass-Box observability types (alpha.17).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warmdrift/kgauto-compiler",
3
- "version": "2.0.0-alpha.27",
3
+ "version": "2.0.0-alpha.29",
4
4
  "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",