@warmdrift/kgauto-compiler 2.0.0-alpha.61 → 2.0.0-alpha.62

package/dist/{ir-DAKlQsVb.d.mts → ir-B2dRyJXO.d.mts}

@@ -1,17 +1,73 @@
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**
- * Intermediate Representation — the structured form of a prompt.
+ * Golden-set capture (alpha.62, eval spine — design brief 2026-07-17).
  *
- * Everything kgauto v2 does, it does on the IR. The IR is constructed by the
- * caller (or by `parse()` from a string-style prompt for backwards-compat),
- * transformed by the compiler passes, and lowered to a target-specific wire
- * request only at the very end.
+ * The eval-driven self-improvement contract needs a replay corpus: 20–50 real
+ * historical IRs per (app, archetype), stored WITH the incumbent's output.
+ * This module is the capture side — a sampling gate on call()'s success path
+ * that stores the full PromptIR + served response to `kgauto_golden_irs`.
  *
- * The IR carries STRUCTURE, not just text. Sections are first-class. Tools
- * carry per-intent relevance. History knows its turn-age. Constraints are
- * explicit. This is what lets passes do real work.
+ * ## Consent posture (s51 amendment, ratified 2026-07-17)
+ *
+ * Golden rows carry RAW prompts — a deliberate, documented departure from the
+ * s51 "brain holds no raw consumer prompts" rule. Capture is therefore
+ * strictly opt-in:
+ *
+ *   - `KGAUTO_GOLDEN_CAPTURE=0.1` in the consumer's environment (the env var
+ *     IS the consent act — the consumer's operator sets it knowingly), or
+ *   - `CallOptions.goldenCapture.sampleRate` in consumer code.
+ *
+ * Default is 0 (off): absent flag, empty string, non-finite, or ≤0 all mean
+ * "never capture". Every stored row records its consent provenance in the
+ * `consent` column. Reads are strictly app-scoped (RLS) — a consumer can only
+ * ever see its own raw prompts.
+ */
+
+/** Consumer-facing capture options (CallOptions.goldenCapture). */
+interface GoldenCaptureOptions {
+    /**
+     * Probability [0..1] that a successful call's IR + output is stored as a
+     * golden row. Overrides the KGAUTO_GOLDEN_CAPTURE env var when set.
+     */
+    sampleRate?: number;
+    /**
+     * Optional free-text appended to the stored consent provenance (e.g. a
+     * ticket ref or the operator who approved capture for this surface).
+     */
+    consentNote?: string;
+}
+/**
+ * Parse a capture-rate env value. Mirrors the consumer-side
+ * `parseShadowProbeRate` semantics playbacksam established: undefined, empty,
+ * or non-finite → 0 (default-OFF); result clamped to [0, 1].
+ */
+declare function parseGoldenCaptureRate(raw: string | undefined): number;
+/**
+ * Resolve the effective capture rate: explicit option wins; otherwise the
+ * KGAUTO_GOLDEN_CAPTURE env var (when a process env exists — Edge-safe).
  */
+declare function resolveGoldenCaptureRate(optRate?: number): number;
+/** Sampling gate. Injectable rng for tests (same shape as shouldSampleProbe). */
+declare function shouldCaptureGolden(rate: number, rng?: () => number): boolean;
+/** Everything call()'s success path has in scope when capture fires. */
+interface GoldenCaptureContext {
+    ir: PromptIR;
+    servedModel: string;
+    response: NormalizedResponse;
+    latencyMs: number;
+    handle: string;
+    /** Compile-time shape key (peeked before record() popped the registry). */
+    shapeKey?: string;
+    /** How the rate was resolved — recorded as consent provenance. */
+    consent: string;
+}
+/**
+ * Store one golden row from a live served call. Fire-and-forget discipline is
+ * recordGoldenIr()'s (dead-letter, ledger, honors BrainConfig.sync); this
+ * wrapper only shapes the row. Never throws.
+ */
+declare function captureGoldenIr(ctx: GoldenCaptureContext): Promise<void>;
 
 /**
  * A semantically-named section of the system prompt. Sections enable
@@ -969,6 +1025,15 @@ interface CallOptions {
      * without engaging streaming wire format).
      */
     noStream?: boolean;
+    /**
+     * alpha.62 (eval spine) — golden-set capture. When the resolved sample rate
+     * is > 0, a successful non-empty call's FULL PromptIR + served output is
+     * stored to the brain's `kgauto_golden_irs` replay corpus (raw prompt —
+     * explicit opt-in; see golden.ts consent posture). `sampleRate` here
+     * overrides the `KGAUTO_GOLDEN_CAPTURE` env var; when neither is set,
+     * capture never fires.
+     */
+    goldenCapture?: GoldenCaptureOptions;
 }
 interface CallAttempt {
     model: string;
@@ -1383,4 +1448,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 EffortLevel as E, 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 SystemModelMessage as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainModelEntry as o, type ChainWithGrounding as p, type Constraints as q, type MutationApplied as r, type NormalizedTokens as s, type OutcomeKind as t, type PerAxisMetricsByModel as u, type PromptSection as v, type SectionKind as w, type ShadowProbeConfig as x, type ToolDefinition as y };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, captureGoldenIr as D, type EffortLevel as E, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, parseGoldenCaptureRate as J, resolveGoldenCaptureRate as K, shouldCaptureGolden as L, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SystemModelMessage as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainModelEntry as o, type ChainWithGrounding as p, type Constraints as q, type GoldenCaptureOptions as r, type MutationApplied as s, type NormalizedTokens as t, type OutcomeKind as u, type PerAxisMetricsByModel as v, type PromptSection as w, type SectionKind as x, type ShadowProbeConfig as y, type ToolDefinition as z };

package/dist/{ir-DmUuJsWc.d.ts → ir-ClU56aBc.d.ts}

@@ -1,17 +1,73 @@
 import { IntentArchetypeName } from './dialect.js';
 
 /**
- * Intermediate Representation — the structured form of a prompt.
+ * Golden-set capture (alpha.62, eval spine — design brief 2026-07-17).
  *
- * Everything kgauto v2 does, it does on the IR. The IR is constructed by the
- * caller (or by `parse()` from a string-style prompt for backwards-compat),
- * transformed by the compiler passes, and lowered to a target-specific wire
- * request only at the very end.
+ * The eval-driven self-improvement contract needs a replay corpus: 20–50 real
+ * historical IRs per (app, archetype), stored WITH the incumbent's output.
+ * This module is the capture side — a sampling gate on call()'s success path
+ * that stores the full PromptIR + served response to `kgauto_golden_irs`.
  *
- * The IR carries STRUCTURE, not just text. Sections are first-class. Tools
- * carry per-intent relevance. History knows its turn-age. Constraints are
- * explicit. This is what lets passes do real work.
+ * ## Consent posture (s51 amendment, ratified 2026-07-17)
+ *
+ * Golden rows carry RAW prompts — a deliberate, documented departure from the
+ * s51 "brain holds no raw consumer prompts" rule. Capture is therefore
+ * strictly opt-in:
+ *
+ *   - `KGAUTO_GOLDEN_CAPTURE=0.1` in the consumer's environment (the env var
+ *     IS the consent act — the consumer's operator sets it knowingly), or
+ *   - `CallOptions.goldenCapture.sampleRate` in consumer code.
+ *
+ * Default is 0 (off): absent flag, empty string, non-finite, or ≤0 all mean
+ * "never capture". Every stored row records its consent provenance in the
+ * `consent` column. Reads are strictly app-scoped (RLS) — a consumer can only
+ * ever see its own raw prompts.
+ */
+
+/** Consumer-facing capture options (CallOptions.goldenCapture). */
+interface GoldenCaptureOptions {
+    /**
+     * Probability [0..1] that a successful call's IR + output is stored as a
+     * golden row. Overrides the KGAUTO_GOLDEN_CAPTURE env var when set.
+     */
+    sampleRate?: number;
+    /**
+     * Optional free-text appended to the stored consent provenance (e.g. a
+     * ticket ref or the operator who approved capture for this surface).
+     */
+    consentNote?: string;
+}
+/**
+ * Parse a capture-rate env value. Mirrors the consumer-side
+ * `parseShadowProbeRate` semantics playbacksam established: undefined, empty,
+ * or non-finite → 0 (default-OFF); result clamped to [0, 1].
+ */
+declare function parseGoldenCaptureRate(raw: string | undefined): number;
+/**
+ * Resolve the effective capture rate: explicit option wins; otherwise the
+ * KGAUTO_GOLDEN_CAPTURE env var (when a process env exists — Edge-safe).
  */
+declare function resolveGoldenCaptureRate(optRate?: number): number;
+/** Sampling gate. Injectable rng for tests (same shape as shouldSampleProbe). */
+declare function shouldCaptureGolden(rate: number, rng?: () => number): boolean;
+/** Everything call()'s success path has in scope when capture fires. */
+interface GoldenCaptureContext {
+    ir: PromptIR;
+    servedModel: string;
+    response: NormalizedResponse;
+    latencyMs: number;
+    handle: string;
+    /** Compile-time shape key (peeked before record() popped the registry). */
+    shapeKey?: string;
+    /** How the rate was resolved — recorded as consent provenance. */
+    consent: string;
+}
+/**
+ * Store one golden row from a live served call. Fire-and-forget discipline is
+ * recordGoldenIr()'s (dead-letter, ledger, honors BrainConfig.sync); this
+ * wrapper only shapes the row. Never throws.
+ */
+declare function captureGoldenIr(ctx: GoldenCaptureContext): Promise<void>;
 
 /**
  * A semantically-named section of the system prompt. Sections enable
@@ -969,6 +1025,15 @@ interface CallOptions {
      * without engaging streaming wire format).
      */
     noStream?: boolean;
+    /**
+     * alpha.62 (eval spine) — golden-set capture. When the resolved sample rate
+     * is > 0, a successful non-empty call's FULL PromptIR + served output is
+     * stored to the brain's `kgauto_golden_irs` replay corpus (raw prompt —
+     * explicit opt-in; see golden.ts consent posture). `sampleRate` here
+     * overrides the `KGAUTO_GOLDEN_CAPTURE` env var; when neither is set,
+     * capture never fires.
+     */
+    goldenCapture?: GoldenCaptureOptions;
 }
 interface CallAttempt {
     model: string;
@@ -1383,4 +1448,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 EffortLevel as E, 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 SystemModelMessage as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainModelEntry as o, type ChainWithGrounding as p, type Constraints as q, type MutationApplied as r, type NormalizedTokens as s, type OutcomeKind as t, type PerAxisMetricsByModel as u, type PromptSection as v, type SectionKind as w, type ShadowProbeConfig as x, type ToolDefinition as y };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, captureGoldenIr as D, type EffortLevel as E, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, parseGoldenCaptureRate as J, resolveGoldenCaptureRate as K, shouldCaptureGolden as L, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SystemModelMessage as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainModelEntry as o, type ChainWithGrounding as p, type Constraints as q, type GoldenCaptureOptions as r, type MutationApplied as s, type NormalizedTokens as t, type OutcomeKind as u, type PerAxisMetricsByModel as v, type PromptSection as w, type SectionKind as x, type ShadowProbeConfig as y, type ToolDefinition as z };

package/dist/key-health.js

@@ -25,7 +25,7 @@ __export(key_health_exports, {
 module.exports = __toCommonJS(key_health_exports);
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.61";
+var LIBRARY_VERSION = "2.0.0-alpha.62";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/key-health.mjs

@@ -1,6 +1,6 @@
 import {
   createKeyHealthRoute
-} from "./chunk-3RMLZCUK.mjs";
+} from "./chunk-ABFXMO73.mjs";
 export {
   createKeyHealthRoute
 };

package/dist/profiles.d.mts

@@ -1,4 +1,4 @@
-import { k as Provider } from './ir-DAKlQsVb.mjs';
+import { k as Provider } from './ir-B2dRyJXO.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**

package/dist/profiles.d.ts

@@ -1,4 +1,4 @@
-import { k as Provider } from './ir-DmUuJsWc.js';
+import { k as Provider } from './ir-ClU56aBc.js';
 import { IntentArchetypeName } from './dialect.js';
 
 /**

package/dist/{types-B8X1Pyhx.d.ts → types-ByN3r0_7.d.ts}

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

package/dist/{types-DR62iPcO.d.ts → types-C-Wp7HpI.d.ts}

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

package/dist/{types-MRMBUqzY.d.mts → types-CSDweZsl.d.mts}

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

package/dist/{types-CssWqd0X.d.mts → types-axAX1Bg0.d.mts}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.61",
+  "version": "2.0.0-alpha.62",
   "description": "Prompt compiler with executable provider knowledge for multi-model AI apps: normalized multi-provider transport with fallback chains, compile-time cliff guards, a curated model registry, and a telemetry flight recorder. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",