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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Adapter, i as PerAxisMetrics, j as Provider, k as ChainEntry, G as Grounding } from './ir-5W0efxt9.js';
-export { l as CallAttempt, m as CallError, n as ChainWithGrounding, o as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, p as MutationApplied, q as NormalizedTokens, r as OutcomeKind, s as PerAxisMetricsByModel, t as PromptSection, T as ToolCall, u as ToolDefinition } from './ir-5W0efxt9.js';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SectionRewrite, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Adapter, i as PerAxisMetrics, j as Provider, k as ChainEntry, G as Grounding } from './ir-BIAT9gJk.js';
+export { l as CallAttempt, m as CallError, n as ChainWithGrounding, o as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, p as MutationApplied, q as NormalizedTokens, r as OutcomeKind, s as PerAxisMetricsByModel, t as PromptSection, u as SectionKind, T as ToolCall, v as ToolDefinition } from './ir-BIAT9gJk.js';
 import { ModelProfile } from './profiles.js';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.js';
 import { IntentArchetypeName } from './dialect.js';
@@ -94,16 +94,6 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
  */
 declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
 
-/**
- * Brain client — fire-and-forget telemetry to the central kgauto Supabase.
- *
- * The brain is the centralized learning store. Apps POST outcomes here;
- * mutations flow back through a separate pull (in v2.1).
- *
- * Design: never blocks the caller. Failures are silent (logged via optional
- * onError hook). Uses fetch() — works in Node 18+, Edge runtimes, and browsers.
- */
-
 /**
  * alpha.11 — opt-in nested config for brain-query mode (chains / archetype
  * perf / pricing / models registry). Enabled by default when endpoint is
@@ -212,6 +202,13 @@ interface OutcomePayload {
     system_prompt_chars?: number;
     fell_over_from?: string;
     fallback_reason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
+    /**
+     * Per-call SectionRewrite[] captured at compile time. Omitted (sent as
+     * undefined → stored NULL) when no rewrites fired. Powers cross-app
+     * learning aggregates ("rule X fired N times on (app, model, archetype),
+     * downstream outcome quality lifted by M points").
+     */
+    section_rewrites_applied?: SectionRewrite[] | null;
 }
 /**
  * alpha.20 Entry 4: record a quality outcome for a previously-compiled call.
@@ -349,6 +346,17 @@ type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | '
 interface RunAdvisorPhase2Context {
     fallbackChain: string[];
     profileResolver?: (id: string) => ModelProfile | undefined;
+    /**
+     * alpha.29 — translator rewrites that fired this compile. When a rewrite
+     * cleared the cliff (e.g. `tool_call_contract` → sequential-tool preamble
+     * + `parallelToolCalls: false`), the matching cliff advisor
+     * (`archetype-perf-floor-breach`) MUST suppress for the same call. Without
+     * suppression both fire — the advisory contradicts the rewrite ("cliff is
+     * unaddressed" vs "we just addressed it").
+     *
+     * Empty array / undefined → no suppression (alpha.28 behavior preserved).
+     */
+    sectionRewritesApplied?: SectionRewrite[];
 }
 /**
  * Run all phased rules and return collected advisories. Order is fixed so
@@ -365,6 +373,277 @@ interface RunAdvisorPhase2Context {
  */
 declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
 
+/**
+ * Translator primitive — alpha.29.
+ *
+ * Pure function. Walks `IR.sections`, matches each section's `kind` against
+ * the model + archetype + profile, and applies a model-aware rewrite when
+ * a rule fires. Returns the rewritten IR + the list of rewrites for
+ * `CompileResult.sectionRewritesApplied` and brain persistence.
+ *
+ * This is the s37 translator-framing eureka in code: kgauto graduates from
+ * "gate" (alpha.28's cliff advisor: "consumer must accept adapter") to
+ * "translator" (alpha.29: "consumer declared the section kind, kgauto
+ * applies the adapter at compile time without consumer-side branching").
+ *
+ * alpha.29 ships ONE rule:
+ *
+ *   tool_call_contract + profile.archetypePerf[archetype] < ARCHETYPE_FLOOR_DEFAULT
+ *     → prepend sequential-tool-pattern guidance
+ *     → emit wireOverrides: { parallelToolCalls: false }
+ *
+ * alpha.30+ will extend the rule table to `narration_contract`, `role_intro`,
+ * etc. Each new rule lands here as an explicit branch.
+ *
+ * **Interaction with the cliff advisor (alpha.28):** when this translator
+ * fires for a `tool_call_contract` section, the advisor's
+ * `archetype-perf-floor-breach` rule MUST suppress for the same call — the
+ * cliff was structurally cleared by the rewrite, not unaddressed. The
+ * suppression check lives in `advisor.ts` and consults the
+ * `CompileResult.sectionRewritesApplied` list.
+ *
+ * Design contract:
+ *   command-center/advisory/kgauto/2026-05-21_alpha-29-translator-and-advisories-api.md
+ */
+
+/**
+ * Re-export of `ARCHETYPE_FLOOR_DEFAULT` as the canonical "translator fires
+ * below this score" threshold. Same constant as the cliff advisor — the
+ * single threshold is shared (alpha.28's "below this, advisor warns"; alpha.29's
+ * "below this, translator AUTO-APPLIES the adapter").
+ */
+declare const TRANSLATOR_FLOOR = 6;
+/**
+ * Stable identifier of the alpha.29 sequential-tool rule. Surfaces on
+ * `SectionRewrite.rule` and in brain aggregates. Future rules extend this
+ * list; the brain learns per-rule effectiveness over time.
+ */
+declare const RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
+interface ApplySectionRewritesArgs {
+    ir: PromptIR;
+    profile: ModelProfile;
+    archetype: IntentArchetypeName;
+}
+interface ApplySectionRewritesResult {
+    /**
+     * IR with section.text fields possibly rewritten. When no rewrites fired,
+     * this is identical to the input IR (referentially distinct array but
+     * same section payloads).
+     */
+    rewrittenIR: PromptIR;
+    /**
+     * One entry per section the translator rewrote. Empty array when no
+     * rules fired. Order matches the corresponding section in
+     * `rewrittenIR.sections`.
+     */
+    rewrites: SectionRewrite[];
+}
+/**
+ * Pure function. Apply model-aware section rewrites to the IR at compile time.
+ *
+ * Discipline:
+ *   - Never mutates the input IR; returns a new IR with new sections array.
+ *   - Sections without a `kind` (or `kind === 'arbitrary'`) pass through
+ *     unchanged.
+ *   - Empty `sections` array → returns `{ rewrittenIR: ir, rewrites: [] }`.
+ *   - Missing `profile.archetypePerf` → no rewrite (defensive — treat the
+ *     model as un-classified rather than below-floor).
+ *   - Sections of the same `kind` are processed in array order; the rule
+ *     fires once per matching section (today every tool_call_contract
+ *     section gets the same prepend — multiple sections of the same kind
+ *     ARE supported but is an unusual consumer shape).
+ *
+ * @example
+ * ```ts
+ * import { applySectionRewrites } from '@warmdrift/kgauto-compiler';
+ * import { getProfile } from '@warmdrift/kgauto-compiler';
+ *
+ * const { rewrittenIR, rewrites } = applySectionRewrites({
+ *   ir,
+ *   profile: getProfile('deepseek-v4-pro'),
+ *   archetype: 'hunt',
+ * });
+ * if (rewrites.length > 0) console.log('translator fired:', rewrites);
+ * ```
+ */
+declare function applySectionRewrites(args: ApplySectionRewritesArgs): ApplySectionRewritesResult;
+
+/**
+ * advisories-api — structured advisories API (alpha.29 Workstream B).
+ *
+ * Closes the L-117 family bottleneck: kgauto's `result.advisories[]` (the
+ * compile-time warnings about caching-off, tool-bloat, archetype-perf-floor
+ * breaches, etc.) used to disappear after the consumer read the compile
+ * result. The s34 caching-off advisory pattern is the canonical failure: an
+ * advisory fired 100+ times in 24h on `generate::sonnet` at 99.4% empty
+ * rate, and nobody knew because there was no structured channel to surface
+ * "what's open right now?"
+ *
+ * Migration 020 ships the substrate: `compile_outcome_advisories` gains
+ * lifecycle columns (`resolved_at`, `resolution_source`, `resolution_note`)
+ * and the `actionable_advisories_v` view rolls per-firing rows into
+ * per-(app_id, code) tuples with deterministic stable ids + server-side
+ * auto-resolution.
+ *
+ * Public surface:
+ *   getActionableAdvisories({ appId, severity?, status?, brainEndpoint, brainJwt, brainAnonKey, fetch? })
+ *     → Promise<ActionableAdvisory[]>
+ *
+ *   markAdvisoryResolved({ id, resolutionNote?, brainEndpoint, brainJwt, brainAnonKey, fetch? })
+ *     → Promise<{ ok: true } | { ok: false; reason: string }>
+ *
+ * Both functions are pure I/O — no module-level state. The fetch wiring
+ * mirrors `createProxyHandler` in `glassbox-routes/proxy.ts`: scoped JWT in
+ * `Authorization: Bearer`, `apikey` header carries the anon key.
+ *
+ * The auto-resolution rule is enforced server-side in `actionable_advisories_v`:
+ *   • Latest firing > 14 days ago             → status='resolved' (auto-pruned)
+ *   • All firings have resolved_at set        → status='resolved' (consumer-marked)
+ *   • Otherwise                               → status='open'
+ *
+ * `markAdvisoryResolved` is the consumer override: "I fixed it; the next
+ * firing will reopen the rule, but until then it stays resolved."
+ */
+
+/**
+ * Severity of an advisory. Maps to the `level` column on
+ * `compile_outcome_advisories` (info | warn | critical).
+ */
+type AdvisorySeverity = 'info' | 'warn' | 'critical';
+/**
+ * Status of an advisory rollup.
+ *
+ * - `open` — at least one unresolved firing in the last 14 days
+ * - `resolved` — either auto-pruned (no firings >14d) or consumer-marked
+ * - `snoozed` — reserved for alpha.30+ (snooze-until-date); type-accepted
+ *   today but the view will never emit this value
+ */
+type AdvisoryStatus = 'open' | 'snoozed' | 'resolved';
+/**
+ * Source of resolution when status='resolved'.
+ *
+ * - `auto` — server-side rule auto-pruned (>14d since last firing)
+ * - `consumer-marked` — consumer called `markAdvisoryResolved`
+ * - `declined` — reserved (alpha.30+: consumer marked the suggestion
+ *   inapplicable; the advisor will still fire but UIs can hide it)
+ */
+type AdvisoryResolutionSource = 'auto' | 'consumer-marked' | 'declined';
+/**
+ * Suggested-fix metadata. `null` when the advisor has no actionable fix
+ * (info-level rules can be observational). When set, the consumer's
+ * Admin UI can render a one-click apply (alpha.30+) or surface the
+ * before/after diff inline.
+ */
+interface AdvisorySuggestedFix {
+    type: 'config-change' | 'one-liner' | 'env-var' | 'manual';
+    /** File:line hint if kgauto can infer (reserved — alpha.30+). */
+    siteHint?: string;
+    before?: string;
+    after?: string;
+    docsLink?: string;
+}
+/**
+ * Per-(app_id, code) advisory rollup. The `id` is stable across polls
+ * until the rule auto-resolves and re-opens (a new firing after the 14d
+ * boundary advances `opened_at` → new id). Treat id-changes as
+ * intentional "fresh re-open" signals.
+ *
+ * Wire-shape from `actionable_advisories_v`. The transformer maps the
+ * view's snake_case columns to camelCase. See `feedback_typed_boundary_transformers.md`
+ * (L-118) for the rationale.
+ */
+interface ActionableAdvisory {
+    id: string;
+    rule: string;
+    severity: AdvisorySeverity;
+    openedAt: string;
+    lastObservedAt: string;
+    observationCount: number;
+    appliesTo: {
+        archetype?: IntentArchetypeName;
+        model?: string;
+        callSiteHint?: string;
+    };
+    message: string;
+    suggestedFix: AdvisorySuggestedFix | null;
+    /** Reserved — always `false` in alpha.29. alpha.30+ ships actual auto-apply. */
+    autoApplicable: boolean;
+    status: AdvisoryStatus;
+    resolvedAt?: string;
+    resolutionSource?: AdvisoryResolutionSource;
+    resolutionNote?: string;
+}
+/**
+ * Filter + transport for `getActionableAdvisories`. The brain JWT must
+ * carry an `app_id` claim matching `opts.appId` — RLS enforces tenant
+ * isolation on the underlying table, so a mismatch silently returns [].
+ */
+interface GetActionableAdvisoriesOptions {
+    appId: string;
+    /** Severity filter; if omitted, all severities are returned. */
+    severity?: AdvisorySeverity;
+    /** Status filter; defaults to 'open'. Pass 'all' for the full set. */
+    status?: 'open' | 'snoozed' | 'resolved' | 'all';
+    brainEndpoint: string;
+    brainJwt: string;
+    brainAnonKey: string;
+    fetch?: typeof fetch;
+}
+interface MarkAdvisoryResolvedOptions {
+    /** Stable id from a prior `getActionableAdvisories` call. */
+    id: string;
+    resolutionNote?: string;
+    brainEndpoint: string;
+    brainJwt: string;
+    brainAnonKey: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Query the open advisory set for an app. Pulls from
+ * `actionable_advisories_v` (per-(app_id, code) rollup with stable ids
+ * + server-side auto-resolution).
+ *
+ * Default behavior (no status filter): returns only `status='open'`.
+ * Pass `status: 'all'` to see resolved + open together — useful for
+ * Admin UIs that show "recently fixed" badges.
+ *
+ * Fetch failures bubble out as thrown Errors. (`markAdvisoryResolved`
+ * uses the ok/reason envelope; this read path throws to match
+ * existing kgauto query semantics where the consumer can decide to
+ * retry or render an error state.)
+ */
+declare function getActionableAdvisories(opts: GetActionableAdvisoriesOptions): Promise<ActionableAdvisory[]>;
+/**
+ * Mark an advisory as consumer-resolved.
+ *
+ * Lookup strategy:
+ *   1. Query `actionable_advisories_v?id=eq.<id>` to find the (app_id, code)
+ *      tuple for this advisory.
+ *   2. PATCH the latest unresolved firing in `compile_outcome_advisories`
+ *      matching that tuple via the underlying outcome's app_id.
+ *
+ * The (app_id, code) lookup is necessary because `compile_outcome_advisories`
+ * has no `app_id` column — it inherits scope via the FK to compile_outcomes.
+ * PostgREST cannot PATCH with a JOIN predicate, so the markAdvisoryResolved
+ * path is a two-step round-trip. The cost is one extra GET per resolve call;
+ * acceptable because marks are low-frequency operator actions, not per-call
+ * hot path.
+ *
+ * Idempotent re-marks: if the advisory is already resolved (no unresolved
+ * firings match), the PATCH affects zero rows and the call still returns
+ * `ok: true`. The function returns `ok: false` only on transport / auth /
+ * lookup failures.
+ *
+ * Returns ok/reason envelope (vs throwing) because consumer Admin UIs
+ * typically want to render the failure inline rather than crash.
+ */
+declare function markAdvisoryResolved(opts: MarkAdvisoryResolvedOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+
 /**
  * Archetype-cliff compatibility — alpha.28 (tt-intel-Cairn ratified).
  *
@@ -1124,4 +1403,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, ARCHETYPE_FLOOR_DEFAULT, Adapter, ApiKeys, type AppOracle, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, TRANSLATOR_FLOOR, applySectionRewrites, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };