@warmdrift/kgauto-compiler 2.0.0-alpha.42 → 2.0.0-alpha.44

package/dist/{ir-BG70lg9b.d.mts → ir-DARjQnvZ.d.mts}

@@ -680,6 +680,20 @@ interface CompileResult {
          * empty. Matches `historyCacheMarkIndex` semantics on the history axis.
          */
         systemCacheMarkIndex?: number;
+        /**
+         * alpha.43. Cliff-style warnings surfaced by the convention pass
+         * (`passApplyConventions`) when the selected profile + archetype carry
+         * a `cliffWarning` whose preconditions are met. These are informational
+         * — they describe a structural mismatch between the call's shape and
+         * the chosen family (e.g. "reasoner family is wrong for parallel-tool
+         * hunt") so consumers can route differently next time.
+         *
+         * Empty array when no convention fired or no warnings surfaced.
+         * Separate from `cliff_guard` mutations in `mutationsApplied` — those
+         * are profile.cliffs[] runtime triggers; these are convention-level
+         * advisory text. Both can fire on the same call.
+         */
+        cliffWarnings: string[];
     };
     /**
      * alpha.33. Structured `system` for AI-SDK `streamText({ system })`
@@ -953,6 +967,19 @@ interface CallResult {
      * Always present on success. Additive, non-breaking.
      */
     traceId: string;
+    /**
+     * alpha.44. Best-practice advisories emitted by the compile that actually
+     * served the response (mirrors `CompileResult.advisories`; uses the SERVED
+     * compile on fallback, same as `mutationsApplied`). Empty array when no
+     * rules fired.
+     *
+     * Closes IC's `callForAgent` side-finding (2026-05-26): call() consumers
+     * (agent paths — sweep / dyad / session-title) previously had no way to
+     * `logAdvisories('[kgauto-v2 ...]', advisories)` like compile() consumers
+     * (chat / intake) do, because the advisories were consumed internally
+     * (trace events, brain record) but never returned. Additive, non-breaking.
+     */
+    advisories: BestPracticeAdvisory[];
 }
 /**
  * Thrown when call() exhausts the fallback chain without success.

package/dist/{ir-BmumS1Du.d.ts → ir-DAUBaPhd.d.ts}

@@ -680,6 +680,20 @@ interface CompileResult {
          * empty. Matches `historyCacheMarkIndex` semantics on the history axis.
          */
         systemCacheMarkIndex?: number;
+        /**
+         * alpha.43. Cliff-style warnings surfaced by the convention pass
+         * (`passApplyConventions`) when the selected profile + archetype carry
+         * a `cliffWarning` whose preconditions are met. These are informational
+         * — they describe a structural mismatch between the call's shape and
+         * the chosen family (e.g. "reasoner family is wrong for parallel-tool
+         * hunt") so consumers can route differently next time.
+         *
+         * Empty array when no convention fired or no warnings surfaced.
+         * Separate from `cliff_guard` mutations in `mutationsApplied` — those
+         * are profile.cliffs[] runtime triggers; these are convention-level
+         * advisory text. Both can fire on the same call.
+         */
+        cliffWarnings: string[];
     };
     /**
      * alpha.33. Structured `system` for AI-SDK `streamText({ system })`
@@ -953,6 +967,19 @@ interface CallResult {
      * Always present on success. Additive, non-breaking.
      */
     traceId: string;
+    /**
+     * alpha.44. Best-practice advisories emitted by the compile that actually
+     * served the response (mirrors `CompileResult.advisories`; uses the SERVED
+     * compile on fallback, same as `mutationsApplied`). Empty array when no
+     * rules fired.
+     *
+     * Closes IC's `callForAgent` side-finding (2026-05-26): call() consumers
+     * (agent paths — sweep / dyad / session-title) previously had no way to
+     * `logAdvisories('[kgauto-v2 ...]', advisories)` like compile() consumers
+     * (chat / intake) do, because the advisories were consumed internally
+     * (trace events, brain record) but never returned. Additive, non-breaking.
+     */
+    advisories: BestPracticeAdvisory[];
 }
 /**
  * Thrown when call() exhausts the fallback chain without success.

package/dist/profiles.d.mts

@@ -1,4 +1,4 @@
-import { k as Provider } from './ir-BG70lg9b.mjs';
+import { k as Provider } from './ir-DARjQnvZ.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**
@@ -32,6 +32,79 @@ interface CliffRule {
     /** Human-readable reason for digest reporting. */
     reason: string;
 }
+/**
+ * alpha.43 — per-family-per-archetype prompt-shape convention.
+ *
+ * Cliffs are runtime warnings about model failure modes; conventions are
+ * compile-time prompt rewrites that head off those failure modes BEFORE the
+ * call leaves kgauto. The split: "this model hedges on classify" is a fact
+ * about the model (a convention); "this prompt is 80k tokens on a Flash
+ * profile" is a fact about the call (a cliff).
+ *
+ * Conventions live as data on profiles (NOT hardcoded in passes). The
+ * `passApplyConventions` pass walks each matching convention and applies
+ * its prefix/suffix/structured-output hint at compile time. Idempotent: if
+ * the prefix/suffix is already at the head/tail, the pass no-ops.
+ *
+ * Defaulting rule: set conventions on the FAMILY REPRESENTATIVE profile
+ * (e.g. deepseek-v4-pro is the family rep for the `deepseek-reasoner`
+ * family). Other family members inherit at compile time via the
+ * `family-resolution.deriveFamilyFromModelId` lookup. Model-specific
+ * overrides are rare; use them only when one model in a family genuinely
+ * diverges from the family default.
+ *
+ * Trigger that justified the substrate (2026-05-28): V4-Pro probe on
+ * tt-intel/classify (exclusion-finding ID 20) showed 8/10 judge rationales
+ * citing "candidate hedges and fails to commit to a single classification."
+ * Without a forcing-function suffix, every reasoner probe on a decisive
+ * archetype verdicts stay-excluded for reasoner-behavior reasons, not
+ * quality reasons. The convention substrate is the kgauto-side fix.
+ */
+interface ArchetypeConvention {
+    /** Intent archetype this convention applies to. */
+    archetype: IntentArchetypeName;
+    /**
+     * String prepended to the system prompt (after any existing system
+     * content). Use for forcing-functions, output-shape directives,
+     * anti-hedge framing. Omit if no prefix needed.
+     */
+    promptPrefix?: string;
+    /**
+     * String appended to the LAST user message in history (or to
+     * `currentTurn` when history is empty). Use for tail-anchored
+     * forcing-functions ("Output exactly one of: [...]"). Omit if no suffix
+     * needed.
+     */
+    promptSuffix?: string;
+    /**
+     * If 'enforce', kgauto warns (but does not block) when structuredOutput
+     * is NOT set and the model wants it. If 'avoid', kgauto warns when
+     * structuredOutput IS set and the model struggles with schema
+     * compliance. If omitted, no structured-output guidance.
+     */
+    structuredOutputHint?: 'enforce' | 'avoid';
+    /**
+     * Free-form cliff-style warning surfaced in
+     * `CompileResult.diagnostics.cliffWarnings` when the convention's
+     * preconditions are met but the consumer opted out of the convention
+     * (e.g. provided their own conflicting prompt-shape) — or when the
+     * convention can't be applied automatically (cliffWarning-only entries
+     * are pure diagnostics).
+     */
+    cliffWarning?: string;
+    /**
+     * Optional: only fire this convention's cliffWarning when the tool count
+     * is at least this threshold. Used for parallel-tool advisories on
+     * archetypes that don't otherwise carry a hard tool cap.
+     */
+    whenToolCountAtLeast?: number;
+    /**
+     * Brain-evidence-linked justification. Appears in mutations_applied
+     * trail + advisor rule messages. Same format as existing cliff.reason
+     * strings.
+     */
+    reason: string;
+}
 interface RecoveryRule {
     /** What signal triggers recovery. */
     signal: 'empty_response_after_tool' | 'empty_response' | 'malformed_function_call' | 'rate_limit' | 'model_not_found' | 'context_overflow';
@@ -145,6 +218,23 @@ interface ModelProfile {
      * is by definition the active source of truth at bundle time).
      */
     active?: boolean;
+    /**
+     * alpha.43 — per-archetype prompt-shape conventions. Applied at compile
+     * time by `passApplyConventions` (after model selection, before lower).
+     * When a convention's archetype matches the request's intent_archetype,
+     * the prefix + suffix are applied (idempotent if already present) and
+     * the structured-output / cliff-warning diagnostics surface.
+     *
+     * Conventions are FAMILY-LEVEL by default — set them on the family
+     * representative profile (e.g. `deepseek-v4-pro` for the
+     * `deepseek-reasoner` family) and other members inherit at compile time
+     * via the `family-resolution.deriveFamilyFromModelId` lookup. Model-
+     * specific overrides on a member profile take precedence over the
+     * family default for the same archetype.
+     *
+     * See `ArchetypeConvention` for field semantics.
+     */
+    archetypeConventions?: ArchetypeConvention[];
 }
 declare const ALIASES: Record<string, string>;
 interface ProfileBrainHook {
@@ -161,4 +251,4 @@ declare function allProfiles(): readonly ModelProfile[];
 declare function allProfilesRaw(): readonly ModelProfile[];
 declare function profilesByProvider(provider: Provider): readonly ModelProfile[];
 
-export { ALIASES, type CacheStrategy, type CliffRule, type LoweringSpec, type ModelProfile, type RecoveryRule, type StructuredOutputCapability, type SystemPromptMode, _setProfileBrainHook, allProfiles, allProfilesRaw, getProfile, profilesByProvider, tryGetProfile };
+export { ALIASES, type ArchetypeConvention, type CacheStrategy, type CliffRule, type LoweringSpec, type ModelProfile, type RecoveryRule, type StructuredOutputCapability, type SystemPromptMode, _setProfileBrainHook, allProfiles, allProfilesRaw, getProfile, profilesByProvider, tryGetProfile };

package/dist/profiles.d.ts

@@ -1,4 +1,4 @@
-import { k as Provider } from './ir-BmumS1Du.js';
+import { k as Provider } from './ir-DAUBaPhd.js';
 import { IntentArchetypeName } from './dialect.js';
 
 /**
@@ -32,6 +32,79 @@ interface CliffRule {
     /** Human-readable reason for digest reporting. */
     reason: string;
 }
+/**
+ * alpha.43 — per-family-per-archetype prompt-shape convention.
+ *
+ * Cliffs are runtime warnings about model failure modes; conventions are
+ * compile-time prompt rewrites that head off those failure modes BEFORE the
+ * call leaves kgauto. The split: "this model hedges on classify" is a fact
+ * about the model (a convention); "this prompt is 80k tokens on a Flash
+ * profile" is a fact about the call (a cliff).
+ *
+ * Conventions live as data on profiles (NOT hardcoded in passes). The
+ * `passApplyConventions` pass walks each matching convention and applies
+ * its prefix/suffix/structured-output hint at compile time. Idempotent: if
+ * the prefix/suffix is already at the head/tail, the pass no-ops.
+ *
+ * Defaulting rule: set conventions on the FAMILY REPRESENTATIVE profile
+ * (e.g. deepseek-v4-pro is the family rep for the `deepseek-reasoner`
+ * family). Other family members inherit at compile time via the
+ * `family-resolution.deriveFamilyFromModelId` lookup. Model-specific
+ * overrides are rare; use them only when one model in a family genuinely
+ * diverges from the family default.
+ *
+ * Trigger that justified the substrate (2026-05-28): V4-Pro probe on
+ * tt-intel/classify (exclusion-finding ID 20) showed 8/10 judge rationales
+ * citing "candidate hedges and fails to commit to a single classification."
+ * Without a forcing-function suffix, every reasoner probe on a decisive
+ * archetype verdicts stay-excluded for reasoner-behavior reasons, not
+ * quality reasons. The convention substrate is the kgauto-side fix.
+ */
+interface ArchetypeConvention {
+    /** Intent archetype this convention applies to. */
+    archetype: IntentArchetypeName;
+    /**
+     * String prepended to the system prompt (after any existing system
+     * content). Use for forcing-functions, output-shape directives,
+     * anti-hedge framing. Omit if no prefix needed.
+     */
+    promptPrefix?: string;
+    /**
+     * String appended to the LAST user message in history (or to
+     * `currentTurn` when history is empty). Use for tail-anchored
+     * forcing-functions ("Output exactly one of: [...]"). Omit if no suffix
+     * needed.
+     */
+    promptSuffix?: string;
+    /**
+     * If 'enforce', kgauto warns (but does not block) when structuredOutput
+     * is NOT set and the model wants it. If 'avoid', kgauto warns when
+     * structuredOutput IS set and the model struggles with schema
+     * compliance. If omitted, no structured-output guidance.
+     */
+    structuredOutputHint?: 'enforce' | 'avoid';
+    /**
+     * Free-form cliff-style warning surfaced in
+     * `CompileResult.diagnostics.cliffWarnings` when the convention's
+     * preconditions are met but the consumer opted out of the convention
+     * (e.g. provided their own conflicting prompt-shape) — or when the
+     * convention can't be applied automatically (cliffWarning-only entries
+     * are pure diagnostics).
+     */
+    cliffWarning?: string;
+    /**
+     * Optional: only fire this convention's cliffWarning when the tool count
+     * is at least this threshold. Used for parallel-tool advisories on
+     * archetypes that don't otherwise carry a hard tool cap.
+     */
+    whenToolCountAtLeast?: number;
+    /**
+     * Brain-evidence-linked justification. Appears in mutations_applied
+     * trail + advisor rule messages. Same format as existing cliff.reason
+     * strings.
+     */
+    reason: string;
+}
 interface RecoveryRule {
     /** What signal triggers recovery. */
     signal: 'empty_response_after_tool' | 'empty_response' | 'malformed_function_call' | 'rate_limit' | 'model_not_found' | 'context_overflow';
@@ -145,6 +218,23 @@ interface ModelProfile {
      * is by definition the active source of truth at bundle time).
      */
     active?: boolean;
+    /**
+     * alpha.43 — per-archetype prompt-shape conventions. Applied at compile
+     * time by `passApplyConventions` (after model selection, before lower).
+     * When a convention's archetype matches the request's intent_archetype,
+     * the prefix + suffix are applied (idempotent if already present) and
+     * the structured-output / cliff-warning diagnostics surface.
+     *
+     * Conventions are FAMILY-LEVEL by default — set them on the family
+     * representative profile (e.g. `deepseek-v4-pro` for the
+     * `deepseek-reasoner` family) and other members inherit at compile time
+     * via the `family-resolution.deriveFamilyFromModelId` lookup. Model-
+     * specific overrides on a member profile take precedence over the
+     * family default for the same archetype.
+     *
+     * See `ArchetypeConvention` for field semantics.
+     */
+    archetypeConventions?: ArchetypeConvention[];
 }
 declare const ALIASES: Record<string, string>;
 interface ProfileBrainHook {
@@ -161,4 +251,4 @@ declare function allProfiles(): readonly ModelProfile[];
 declare function allProfilesRaw(): readonly ModelProfile[];
 declare function profilesByProvider(provider: Provider): readonly ModelProfile[];
 
-export { ALIASES, type CacheStrategy, type CliffRule, type LoweringSpec, type ModelProfile, type RecoveryRule, type StructuredOutputCapability, type SystemPromptMode, _setProfileBrainHook, allProfiles, allProfilesRaw, getProfile, profilesByProvider, tryGetProfile };
+export { ALIASES, type ArchetypeConvention, type CacheStrategy, type CliffRule, type LoweringSpec, type ModelProfile, type RecoveryRule, type StructuredOutputCapability, type SystemPromptMode, _setProfileBrainHook, allProfiles, allProfilesRaw, getProfile, profilesByProvider, tryGetProfile };

package/dist/profiles.js

@@ -592,7 +592,21 @@ var PROFILES_RAW = [
       critique: 4,
       hunt: 4
       // sequential tool calls only — L-040
-    }
+    },
+    // alpha.43 — family-level conventions for the `deepseek-chat` family
+    // (V4-Flash + future non-thinking-mode members). V4-Flash struggles
+    // with summarize-archetype + structured-output: 3 of 4 schema-attempted
+    // PB calls (2026-05-18 + 2026-05-22) hit `structured_output_parse_failed`.
+    // Surface the friction at compile time so consumers either drop the
+    // schema or route to a more schema-reliable family.
+    archetypeConventions: [
+      {
+        archetype: "summarize",
+        structuredOutputHint: "avoid",
+        cliffWarning: "deepseek-chat family schema compliance on summarize is weak (3 of 4 schema-attempted PB calls hit structured_output_parse_failed). Consider routing summarize+structured-output to a different family (claude-sonnet, gemini-pro, openai-gpt-5.4) or dropping the schema for free-text summaries.",
+        reason: "Brain evidence: PB compile_outcomes 2026-05-18 + 2026-05-22, error_type=structured_output_parse_failed on deepseek-v4-flash + summarize archetype."
+      }
+    ]
   },
   {
     id: "deepseek-v4-pro",
@@ -643,7 +657,51 @@ var PROFILES_RAW = [
       transform: 6,
       hunt: 4
       // sequential tools — same as V4-Flash
-    }
+    },
+    // alpha.43 — family-level conventions for the `deepseek-reasoner` family
+    // (V4-Pro is the family rep; future thinking-mode members inherit).
+    //
+    // The decisive-archetype suffix is the load-bearing piece: 2026-05-28
+    // first real V4-Pro probe on tt-intel/classify (exclusion-finding ID 20)
+    // showed 8/10 judge rationales citing "candidate hedges and fails to
+    // commit to a single classification" or "candidate refuses to pick
+    // among the labels." Without the forcing-function suffix, every
+    // reasoner probe on classify/extract/ask verdicts stay-excluded for
+    // model-behavior reasons (epistemic humility is reasoner-shaped),
+    // NOT quality reasons. The suffix re-shapes the contract so the model
+    // is asked for what it's actually being measured on.
+    //
+    // The hunt-archetype cliffWarning is the L-040 architectural reading
+    // surfaced at compile time. Reasoners produce sequential reasoning
+    // chains by design; hunt archetypes with 3+ parallel tools lose
+    // substantial throughput (L-040 + L-041). The L-040 cliff in the
+    // `cliffs` array already trims to top-relevant tools; this warning
+    // tells the consumer the family is wrong for the shape so they can
+    // route to gemini-flash (parallel-strong) instead of accepting trimmed
+    // throughput silently.
+    archetypeConventions: [
+      {
+        archetype: "classify",
+        promptSuffix: "\n\nOutput exactly one classification label. Do not hedge, do not add preamble, do not explain your reasoning. If uncertain, pick the most likely label and commit to it.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: 2026-05-28 V4-Pro probe on tt-intel/classify (exclusion-finding ID 20, brain probe_outcomes); 8 of 10 judge rationales cited hedging or refusal-to-commit. Forcing-function suffix converts reasoner output to decisive labels."
+      },
+      {
+        archetype: "extract",
+        promptSuffix: "\n\nOutput exactly the requested structured fields. Do not hedge, do not add preamble, do not explain your reasoning. If a field is unknown, emit the field with a null/empty value and commit to that \u2014 do not refuse to extract.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: same family failure shape as classify (exclusion-finding ID 20, 2026-05-28). Forcing-function suffix asks for commitment instead of epistemic-humility hedging."
+      },
+      {
+        archetype: "ask",
+        promptSuffix: "\n\nAnswer the question directly. Do not hedge, do not add preamble, do not explain your reasoning unless explicitly asked. If uncertain, give your best answer and commit to it.",
+        reason: "Reasoners (deepseek-reasoner family) hedge on decisive-output archetypes by design. Evidence: same family failure shape as classify (exclusion-finding ID 20, 2026-05-28). Forcing-function suffix asks for commitment instead of epistemic-humility hedging."
+      },
+      {
+        archetype: "hunt",
+        whenToolCountAtLeast: 3,
+        cliffWarning: "Reasoners (deepseek-reasoner family) produce sequential reasoning chains by design; hunt archetypes with 3+ parallel tools lose substantial throughput. Consider gemini-flash family (parallel-strong) instead \u2014 see L-040 / L-041.",
+        reason: "L-040 + L-041 architectural reading; 2026-05-28 V4-Pro probe evidence (exclusion-finding ID 20) confirms reasoner-family hunt fit is structurally weak."
+      }
+    ]
   },
   // ── OpenAI ──
   // alpha.16 (2026-05-17): close the half-supported provider gap. env.ts

package/dist/profiles.mjs

@@ -6,7 +6,7 @@ import {
   getProfile,
   profilesByProvider,
   tryGetProfile
-} from "./chunk-JQGRWJZO.mjs";
+} from "./chunk-ZHUD3I52.mjs";
 export {
   ALIASES,
   _setProfileBrainHook,

package/dist/{types-eKKDeADI.d.mts → types-B5DzMhYm.d.mts}

@@ -1,4 +1,4 @@
-import { r as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-BG70lg9b.mjs';
+import { r as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-DARjQnvZ.mjs';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-Cs_hsBGm.d.ts → types-BDqNQxuX.d.ts}

@@ -1,4 +1,4 @@
-import { r as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-BmumS1Du.js';
+import { r as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-DAUBaPhd.js';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-kFsIDC_5.d.ts → types-CfVyRbCl.d.ts}

@@ -1,4 +1,4 @@
-import { i as Adapter, w as SectionKind } from './ir-BmumS1Du.js';
+import { i as Adapter, w as SectionKind } from './ir-DAUBaPhd.js';
 
 /**
  * Internal config + hook types for createGlassboxRoutes().

package/dist/{types-DIl0tCDX.d.mts → types-Rq_fywDq.d.mts}

@@ -1,4 +1,4 @@
-import { i as Adapter, w as SectionKind } from './ir-BG70lg9b.mjs';
+import { i as Adapter, w as SectionKind } from './ir-DARjQnvZ.mjs';
 
 /**
  * Internal config + hook types for createGlassboxRoutes().

package/package.json

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