@warmdrift/kgauto-compiler 2.0.0-alpha.9 → 2.0.0-alpha.90

package/dist/profiles.d.ts

@@ -1,2 +1,352 @@
-export { f as ALIASES, g as CacheStrategy, j as CliffRule, L as LoweringSpec, M as ModelProfile, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-BYVOc1eW.js';
-import './dialect.js';
+import { l as Provider } from './ir-CTx026t0.js';
+import { IntentArchetypeName } from './dialect.js';
+
+/**
+ * Model profiles — executable knowledge about each provider/model.
+ *
+ * Unlike v1 which carried `known_failures` as prose strings, v2 makes them
+ * executable: cliffs trigger guards, lowering describes the wire format,
+ * recovery handlers describe what to do after specific failures.
+ *
+ * Each profile is the answer to "if I want to call THIS model with THIS
+ * shape of work, what does it need from me, and what should I do when it
+ * fails?"
+ */
+
+type StructuredOutputCapability = 'native' | 'grammar' | 'none';
+type SystemPromptMode = 'inline' | 'separate' | 'as_developer' | 'unsupported';
+type CacheStrategy = 'cache_control' | 'cachedContent' | 'unsupported';
+interface CliffRule {
+    /** What metric triggers this cliff. */
+    metric: 'input_tokens' | 'tool_count' | 'history_turns' | 'thinking_with_short_output';
+    /** Threshold — meaning depends on metric. */
+    threshold: number;
+    /** What action to take when triggered. */
+    action: 'downgrade_quality_warning' | 'drop_to_top_relevant' | 'force_thinking_budget_zero' | 'force_terse_output' | 'escalate_target' | 'strip_tools'
+    /**
+     * alpha.78 — apply the band-dominating QUALITY_GATE_PENALTY (same lever
+     * as the alpha.49 schema-weak gate) when the IR declares
+     * structuredOutput and the metric crosses threshold. For models whose
+     * declared structured-output support is MEASURED not to hold above an
+     * input size on an archetype — evidence-shaped, unlike the archetype-
+     * wide `structuredOutputHint: 'avoid'`. Only meaningful with
+     * `metric: 'input_tokens'` (+ usually `whenIntent`).
+     */
+     | 'quality_gate_structured';
+    /**
+     * Optional: only fire this cliff when the IR's intent.archetype matches.
+     * Used for archetype-specific failure modes (e.g. Gemini Flash returns
+     * empty when summarize is offered tools).
+     */
+    whenIntent?: IntentArchetypeName;
+    /** 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';
+    /** Action: retry with adjusted params, or escalate to next fallback. */
+    action: 'retry_with_params' | 'escalate' | 'log_only';
+    /** When action=retry_with_params, the param adjustments to apply. */
+    retryParams?: Record<string, unknown>;
+    /** Max retries with this rule. */
+    maxRetries?: number;
+    /** Human-readable reason for digest reporting. */
+    reason: string;
+}
+interface LoweringSpec {
+    /** Where the system prompt goes. */
+    system: {
+        mode: SystemPromptMode;
+        field?: string;
+    };
+    /** Cache strategy + parameters. */
+    cache: {
+        strategy: CacheStrategy;
+        /** Min tokens before caching is worth it (provider rules). */
+        minTokens?: number;
+        /** Discount factor on cached input (0.1 = 10% of normal price). */
+        discount?: number;
+        /** TTL hint in seconds. */
+        ttlSeconds?: number;
+    };
+    /** Tool format identifier — see lower.ts for supported formats. */
+    tools?: {
+        format: 'anthropic' | 'google' | 'openai' | 'deepseek';
+    };
+    /** Thinking config — present iff this model has a thinking knob. */
+    thinking?: {
+        /** Field path on the request. */
+        field: string;
+        /** Default value when caller hasn't specified. */
+        default?: number | 'auto' | 'off';
+    };
+}
+/**
+ * Coarse latency bucket for a model. alpha.47 — the third swap axis
+ * (cost / quality / SPEED). We bucket rather than store per-model ms because
+ * served latency varies with token count; honest precision is the tier, not a
+ * false-precise number. See {@link LATENCY_TIER_MS} for the representative ms
+ * each tier maps to when compared against `constraints.maxLatencyMs`.
+ */
+type LatencyTier = 'fast' | 'medium' | 'slow';
+interface ModelProfile {
+    id: string;
+    provider: Provider;
+    status: 'current' | 'preview' | 'legacy';
+    maxContextTokens: number;
+    maxOutputTokens: number;
+    maxTools: number;
+    parallelToolCalls: boolean;
+    structuredOutput: StructuredOutputCapability;
+    systemPromptMode: SystemPromptMode;
+    streaming: boolean;
+    cliffs: CliffRule[];
+    costInputPer1m: number;
+    costOutputPer1m: number;
+    lowering: LoweringSpec;
+    recovery: RecoveryRule[];
+    strengths: string[];
+    weaknesses: string[];
+    /**
+     * alpha.47 — explicit latency bucket. OPTIONAL: when unset, `latencyTierOf`
+     * derives it from the tags above (`weaknesses` includes `'latency'` → slow,
+     * `strengths` includes `'speed'` → fast, else medium). Set this explicitly
+     * ONLY when measured evidence contradicts the tag derivation — e.g.
+     * `deepseek-v4-flash` carries no `'latency'` weakness yet measures ~20s
+     * (alpha.46 shadow-probe). Carry provenance in an inline comment when you
+     * override, same discipline as capability data (step zero / L-081).
+     */
+    latencyTier?: LatencyTier;
+    notes?: string;
+    verifiedAgainstDocs?: string;
+    /**
+     * Hand-curated per-archetype performance score on a 0-10 scale.
+     *
+     *   10 = frontier on this archetype (e.g. Opus 4.7 on critique)
+     *    8 = strong second tier (Sonnet on plan, Pro on extract)
+     *    7 = competent (Haiku on classify, Flash on hunt)
+     *    5 = acceptable for tolerant archetypes (Flash-Lite on classify)
+     *    3 = degraded (Flash on critique, DeepSeek on hunt)
+     *
+     * Missing archetypes default to `5` (no data, neutral). Each non-default
+     * value should carry a one-line rationale in the profile's note or inline
+     * comment citing brain evidence, family prior, or "starter hypothesis —
+     * verify with telemetry."
+     *
+     * Source today: hand-curated from master plan §3.3 + §6.2 starter tables.
+     * Source tomorrow (alpha.10+): brain `archetype_model_evidence` view.
+     *
+     * Anti-hallucination guardrail (master plan §2.5): when the watcher's
+     * `--audit-fields` flag flags a profile stale (>90 days since
+     * verifiedAgainstDocs), the archetypePerf values get re-audited
+     * alongside capability fields. AI-trained intuition is NOT a valid
+     * source — only docs or brain evidence.
+     *
+     * alpha.9.
+     */
+    archetypePerf?: Partial<Record<IntentArchetypeName, number>>;
+    /**
+     * alpha.41 — model-family identifier (e.g. `'claude-opus'`,
+     * `'gemini-flash'`). Reads through from `kgauto_models.family` (migration
+     * 024). When unset on a brain row, runtime falls back to
+     * `deriveFamilyFromModelId(model.id)` (see `family-resolution.ts`).
+     *
+     * Used by `getRecommendedPrimary({ family, ... })` and the IR-level
+     * `{ family: string }` chain entry resolution at compile time.
+     */
+    family?: string;
+    /**
+     * alpha.41 — version string of the kgauto release that first introduced
+     * this profile (e.g. `'2.0.0-alpha.36'`). Threaded through from the brain
+     * row's `version_added` column. Family-resolution sorts candidates by
+     * `version_added DESC` (lexicographic) as the secondary tiebreaker after
+     * `archetypePerf[archetype]`. Undefined on bundled profiles (no brain
+     * row).
+     */
+    versionAdded?: string;
+    /**
+     * alpha.41 — whether the brain row is `active = TRUE`. False or undefined
+     * means the model is retired / not actively served (kgauto_models row
+     * exists but won't be selected by family resolution). Bundled profiles
+     * default to `true` when not threaded through (every PROFILES_RAW entry
+     * 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[];
+    /**
+     * alpha.87 — true ONLY on profiles synthesized by
+     * `onUnprofiledModel: 'best-effort'`. Lets compile() (and any consumer)
+     * distinguish "kgauto knows this model" from "kgauto is winging it with
+     * borrowed wire mechanics" on every call, not just the one that
+     * triggered synthesis. Never set on bundled, brain, or
+     * `registerProfiles()` entries.
+     */
+    bestEffort?: true;
+}
+/**
+ * Representative p50 latency (ms) per tier. Coarse on purpose — used only to
+ * compare a model against `constraints.maxLatencyMs`, never reported as a
+ * per-model number. Grounded: alpha.46 shadow-probe measured
+ * `deepseek-v4-flash` at 20485ms and `deepseek-v4-pro` at 47722ms (2026-06-03),
+ * both bucket `slow`; gemini-2.5-flash / haiku-4-5 serve in single-digit
+ * seconds → `fast`; mid-tier (sonnet, gemini-pro) → `medium`. Phase 2 can swap
+ * these buckets for measured per-(archetype,model) p50 from
+ * `compile_outcomes.latency_ms` once enough served rows accumulate.
+ */
+declare const LATENCY_TIER_MS: Record<LatencyTier, number>;
+/**
+ * Resolve a model's latency tier. Explicit `profile.latencyTier` wins;
+ * otherwise derive from the tags already on the profile so we don't maintain a
+ * second source of truth that can silently disagree (L-073 family):
+ *   - `weaknesses` includes `'latency'` → `'slow'`
+ *   - `strengths` includes `'speed'`    → `'fast'`
+ *   - else                              → `'medium'`
+ */
+declare function latencyTierOf(profile: ModelProfile): LatencyTier;
+declare const ALIASES: Record<string, string>;
+interface ProfileBrainHook {
+    getProfile?: (canonicalId: string) => ModelProfile | undefined;
+    resolveAlias?: (id: string) => string | undefined;
+}
+/** @internal — called by models-brain.ts at module load. */
+declare function _setProfileBrainHook(hook: ProfileBrainHook): void;
+/**
+ * Register consumer-supplied profiles. They take precedence over both
+ * brain-curated and bundled profiles for the same id (explicit > learned >
+ * shipped — see block comment above for the tradeoff). Re-registering an
+ * id overwrites the previous consumer entry, including any best-effort
+ * synthesized profile.
+ */
+declare function registerProfiles(profiles: readonly ModelProfile[]): void;
+/** @internal — test hook. */
+declare function _testClearConsumerProfiles(): void;
+/** Provider inference for best-effort mode — id prefix conventions only. */
+declare function inferProviderFromId(id: string): Provider | undefined;
+/**
+ * alpha.87 — best-effort profile synthesis for unprofiled ids (opt-in via
+ * `CompilePolicy.onUnprofiledModel: 'best-effort'`; the default posture
+ * stays refuse). Returns undefined when the provider cannot be inferred
+ * from the id or kgauto ships no donor profile for that provider — in
+ * both cases the caller falls back to the standard refusal, which names
+ * `registerProfiles()` as the informed path.
+ *
+ * What a synthesized profile is: the inferred provider's wire mechanics
+ * (LoweringSpec / systemPromptMode / streaming are provider-wide, borrowed
+ * from a current bundled profile of that provider) around deliberately
+ * conservative capability claims — no cliffs, no recovery, no measured
+ * knowledge, `structuredOutput: 'none'`, sequential tools, modest output
+ * budget, and **cost 0 because cost is UNKNOWN** (cost gates and cost
+ * attribution are meaningless for this model; the compile carries a loud
+ * warning saying exactly that). It is registered into the consumer index
+ * on first synthesis so every later lookup in the process (fallback walk,
+ * passes, telemetry) sees one consistent object.
+ */
+declare function bestEffortProfile(id: string): ModelProfile | undefined;
+/**
+ * Resolve a model id to its canonical form (alias → canonical, unknown ids
+ * returned unchanged). This is the same resolution `getProfile` applies, so
+ * any code comparing model ids against a policy list (blockedModels,
+ * preferredModels) must compare canonical forms on BOTH sides — an alias and
+ * its canonical are the same model, and a raw-string comparison lets one
+ * evade a policy naming the other (alpha.85, tt-intel s119 spend-gate leak).
+ */
+declare function resolveModelAlias(id: string): string;
+declare function getProfile(id: string): ModelProfile;
+declare function tryGetProfile(id: string): ModelProfile | undefined;
+declare function allProfiles(): readonly ModelProfile[];
+/** @internal — bundled-only access for adapters that need a non-brain
+ *  fallback baseline (avoids a brain → profiles → brain re-entry). */
+declare function allProfilesRaw(): readonly ModelProfile[];
+declare function profilesByProvider(provider: Provider): readonly ModelProfile[];
+
+export { ALIASES, type ArchetypeConvention, type CacheStrategy, type CliffRule, LATENCY_TIER_MS, type LatencyTier, type LoweringSpec, type ModelProfile, type RecoveryRule, type StructuredOutputCapability, type SystemPromptMode, _setProfileBrainHook, _testClearConsumerProfiles, allProfiles, allProfilesRaw, bestEffortProfile, getProfile, inferProviderFromId, latencyTierOf, profilesByProvider, registerProfiles, resolveModelAlias, tryGetProfile };