@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/dist/retry/index.js

@@ -0,0 +1,156 @@
+/**
+ * Retry primitives with exponential backoff and optional jitter.
+ *
+ * Provides three usage modes:
+ *   - `retry(fn, opts)` — wrap an async call.
+ *   - `RetryContext` — manual control flow for granular retry logic.
+ *   - {@link ./presets.js} — 4 named configurations for common scenarios.
+ *
+ * Sleep is injectable via `RetryOptions.sleepFn` for deterministic tests.
+ * BaseError.retryable flag is honored by default presets (see ./presets.ts).
+ *
+ * @public @since 1.2.0
+ */
+import { RETRY_TRANSIENT } from "./presets.js";
+/**
+ * Thrown after all retry attempts have been exhausted.
+ * @public
+ */
+export class RetryExhaustedError extends Error {
+    attempts;
+    lastError;
+    constructor(attempts, lastError) {
+        const reason = lastError instanceof Error ? lastError.message : String(lastError);
+        super(`All ${attempts} retry attempts exhausted: ${reason}`);
+        this.name = "RetryExhaustedError";
+        this.attempts = attempts;
+        this.lastError = lastError;
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Compute the delay before retry `attempt` (0-indexed). Caps at `maxDelayMs`.
+ * Jitter, when enabled, adds a uniform-random ±25% offset.
+ *
+ * Visible for tests and for callers that need to inspect timing.
+ * @public
+ */
+export function calculateDelay(config, attempt) {
+    const raw = config.baseDelayMs * Math.pow(config.exponentialBase, attempt);
+    const capped = Math.min(raw, config.maxDelayMs);
+    if (!config.jitter)
+        return Math.max(0, capped);
+    const jitterRange = capped * 0.25;
+    const offset = (Math.random() * 2 - 1) * jitterRange;
+    return Math.max(0, capped + offset);
+}
+/**
+ * Decide whether to retry after `err` at 0-indexed `attempt`.
+ *
+ * Returns false on the final attempt (caller should throw exhaustion).
+ *
+ * @public
+ */
+export function shouldRetry(config, err, attempt) {
+    if (attempt >= config.maxAttempts - 1)
+        return false;
+    if (config.retryIf)
+        return config.retryIf(err);
+    if (config.retryOn && config.retryOn.length > 0) {
+        return config.retryOn.some((Ctor) => err instanceof Ctor);
+    }
+    return true;
+}
+/**
+ * Execute `fn` with retry and exponential backoff.
+ *
+ * @throws The non-retryable error as-is if `shouldRetry` returns false mid-loop.
+ * @throws {@link RetryExhaustedError} when all attempts have failed.
+ *
+ * @public
+ */
+export async function retry(fn, opts = {}) {
+    const config = opts.config ?? RETRY_TRANSIENT;
+    const sleep = opts.sleepFn ?? defaultSleep;
+    let lastError;
+    for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (!shouldRetry(config, err, attempt)) {
+                if (attempt >= config.maxAttempts - 1) {
+                    throw new RetryExhaustedError(config.maxAttempts, err);
+                }
+                throw err;
+            }
+            const delay = calculateDelay(config, attempt);
+            opts.onRetry?.(err, attempt, delay);
+            await sleep(delay);
+        }
+    }
+    throw new RetryExhaustedError(config.maxAttempts, lastError);
+}
+/**
+ * Manual retry control. Use when the operation doesn't fit a single `fn()` —
+ * e.g. when multiple endpoints are tried per attempt, or when partial state
+ * must be reset between tries.
+ *
+ * @example
+ * ```ts
+ * const ctx = new RetryContext({ config: RETRY_AGGRESSIVE });
+ * while (ctx.shouldContinue) {
+ *   try {
+ *     return await op();
+ *   } catch (err) {
+ *     await ctx.handleError(err);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export class RetryContext {
+    config;
+    sleep;
+    onRetry;
+    attemptCount = 0;
+    exhausted = false;
+    constructor(opts) {
+        this.config = opts.config;
+        this.sleep = opts.sleepFn ?? defaultSleep;
+        this.onRetry = opts.onRetry;
+    }
+    /** True while attempts remain and no non-retryable error has been thrown. */
+    get shouldContinue() {
+        return !this.exhausted && this.attemptCount < this.config.maxAttempts;
+    }
+    /** 0-indexed count of completed (failed) attempts. */
+    get attempt() {
+        return this.attemptCount;
+    }
+    /**
+     * Record an error and sleep before the next try.
+     *
+     * @throws The non-retryable error as-is.
+     * @throws {@link RetryExhaustedError} if attempts are exhausted.
+     */
+    async handleError(err) {
+        const failedAttempt = this.attemptCount;
+        this.attemptCount += 1;
+        if (this.attemptCount >= this.config.maxAttempts) {
+            this.exhausted = true;
+            throw new RetryExhaustedError(this.config.maxAttempts, err);
+        }
+        if (!shouldRetry(this.config, err, failedAttempt)) {
+            this.exhausted = true;
+            throw err;
+        }
+        const delay = calculateDelay(this.config, failedAttempt);
+        this.onRetry?.(err, failedAttempt, delay);
+        await this.sleep(delay);
+    }
+}
+export { RETRY_TRANSIENT, RETRY_AGGRESSIVE, RETRY_PATIENT, NO_RETRY, } from "./presets.js";
+//# sourceMappingURL=index.js.map

package/dist/retry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retry/index.ts"],"names":[],"mappings":"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"}

package/dist/retry/presets.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Named retry presets covering common scenarios.
+ *
+ * All presets honor a `retryable: boolean` flag on the thrown error when
+ * present (compatible with {@link ../errors.js#BaseError}). When the flag is
+ * absent, defaults fall back to: transient = retry, no_retry = no retry.
+ *
+ * @public @since 1.2.0
+ */
+import type { RetryConfig } from "./index.js";
+/**
+ * 3 attempts, 1s base, 10s cap, jitter on. Honors `retryable` flag (defaults
+ * to retry when absent). Use for short-lived network calls.
+ *
+ * @public
+ */
+export declare const RETRY_TRANSIENT: RetryConfig;
+/**
+ * 5 attempts, 500ms base, 30s cap, jitter on. Use for flaky external APIs
+ * where rapid recovery is plausible.
+ *
+ * @public
+ */
+export declare const RETRY_AGGRESSIVE: RetryConfig;
+/**
+ * 10 attempts, 2s base, 120s cap, jitter on. Use for long-recovery
+ * dependencies (database failover, restart-storm tolerant calls).
+ *
+ * @public
+ */
+export declare const RETRY_PATIENT: RetryConfig;
+/**
+ * Single attempt, no retry. Use as an explicit policy to disable retry at
+ * call sites without scattering booleans.
+ *
+ * @public
+ */
+export declare const NO_RETRY: RetryConfig;
+//# sourceMappingURL=presets.d.ts.map

package/dist/retry/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../src/retry/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAS9C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,WAO7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAM9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,WAM3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,WAMtB,CAAC"}

package/dist/retry/presets.js

@@ -0,0 +1,69 @@
+/**
+ * Named retry presets covering common scenarios.
+ *
+ * All presets honor a `retryable: boolean` flag on the thrown error when
+ * present (compatible with {@link ../errors.js#BaseError}). When the flag is
+ * absent, defaults fall back to: transient = retry, no_retry = no retry.
+ *
+ * @public @since 1.2.0
+ */
+function honorsRetryableFlag(err, defaultIfMissing) {
+    if (typeof err === "object" && err !== null && "retryable" in err) {
+        return err.retryable === true;
+    }
+    return defaultIfMissing;
+}
+/**
+ * 3 attempts, 1s base, 10s cap, jitter on. Honors `retryable` flag (defaults
+ * to retry when absent). Use for short-lived network calls.
+ *
+ * @public
+ */
+export const RETRY_TRANSIENT = {
+    maxAttempts: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10_000,
+    exponentialBase: 2.0,
+    jitter: true,
+    retryIf: (err) => honorsRetryableFlag(err, true),
+};
+/**
+ * 5 attempts, 500ms base, 30s cap, jitter on. Use for flaky external APIs
+ * where rapid recovery is plausible.
+ *
+ * @public
+ */
+export const RETRY_AGGRESSIVE = {
+    maxAttempts: 5,
+    baseDelayMs: 500,
+    maxDelayMs: 30_000,
+    exponentialBase: 2.0,
+    jitter: true,
+};
+/**
+ * 10 attempts, 2s base, 120s cap, jitter on. Use for long-recovery
+ * dependencies (database failover, restart-storm tolerant calls).
+ *
+ * @public
+ */
+export const RETRY_PATIENT = {
+    maxAttempts: 10,
+    baseDelayMs: 2000,
+    maxDelayMs: 120_000,
+    exponentialBase: 2.0,
+    jitter: true,
+};
+/**
+ * Single attempt, no retry. Use as an explicit policy to disable retry at
+ * call sites without scattering booleans.
+ *
+ * @public
+ */
+export const NO_RETRY = {
+    maxAttempts: 1,
+    baseDelayMs: 0,
+    maxDelayMs: 0,
+    exponentialBase: 2.0,
+    jitter: false,
+};
+//# sourceMappingURL=presets.js.map

package/dist/retry/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../src/retry/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,SAAS,mBAAmB,CAAC,GAAY,EAAE,gBAAyB;IAClE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,WAAW,IAAI,GAAG,EAAE,CAAC;QAClE,OAAQ,GAA8B,CAAC,SAAS,KAAK,IAAI,CAAC;IAC5D,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgB;IAC1C,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,MAAM;IAClB,eAAe,EAAE,GAAG;IACpB,MAAM,EAAE,IAAI;IACZ,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC;CACjD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAgB;IAC3C,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,MAAM;IAClB,eAAe,EAAE,GAAG;IACpB,MAAM,EAAE,IAAI;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAgB;IACxC,WAAW,EAAE,EAAE;IACf,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,OAAO;IACnB,eAAe,EAAE,GAAG;IACpB,MAAM,EAAE,IAAI;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAgB;IACnC,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,CAAC;IACd,UAAU,EAAE,CAAC;IACb,eAAe,EAAE,GAAG;IACpB,MAAM,EAAE,KAAK;CACd,CAAC"}

package/dist/skill-loop/ab-runner.d.ts

@@ -0,0 +1,67 @@
+/**
+ * src/skill-loop/ab-runner.ts
+ *
+ * A/B test runner with failure budgets for SkillCandidates.
+ *
+ * Invariants:
+ *   - Max 3 candidates simultaneously (4th is rejected).
+ *   - Traffic fraction cap: 10% per candidate.
+ *   - Rollback triggered when a candidate's mean score drops >5% vs incumbent.
+ *   - Winner declared when: p < 0.05 AND delta >= 10% AND no rollback triggered.
+ *
+ * Statistical significance uses the same Welch approach as evaluator.ts.
+ *
+ * @module skill-loop/ab-runner
+ */
+import type { SkillCandidate } from "./candidate.js";
+export interface ABConfig {
+    /** Maximum concurrent candidates. Hard cap: 3. */
+    maxCandidates: number;
+    /** Traffic fraction routed to each candidate. Hard cap: 0.10. */
+    trafficPct: number;
+    /** Rollback threshold: if candidate mean drops by this fraction vs incumbent. */
+    rollbackThresholdPct: number;
+}
+export interface ABSlot {
+    candidateId: string;
+    trafficFraction: number;
+    outcomes: number[];
+    rollbackTriggered: boolean;
+}
+export declare class ABRunner {
+    private readonly config;
+    private readonly slots;
+    private readonly candidates;
+    private readonly incumbentOutcomes;
+    constructor(config: ABConfig);
+    /**
+     * Register a new candidate for A/B testing.
+     *
+     * @returns true if added, false if maxCandidates already reached.
+     */
+    addCandidate(candidate: SkillCandidate): boolean;
+    /**
+     * Record an outcome score for a candidate or the incumbent.
+     *
+     * @param candidateId - Candidate ID or "incumbent".
+     * @param score       - Outcome score [0, 1].
+     */
+    recordOutcome(candidateId: string | "incumbent", score: number): void;
+    /**
+     * Returns true if the candidate's mean score has dropped >rollbackThresholdPct
+     * vs the incumbent mean.
+     */
+    shouldRollback(candidateId: string): boolean;
+    /**
+     * Return the winning candidate if statistical significance is established.
+     *
+     * Winner criteria:
+     *   - p < 0.05 (Welch's t-test vs incumbent)
+     *   - delta >= 10% vs incumbent mean
+     *   - rollback NOT triggered
+     *
+     * Returns null if no candidate meets all criteria.
+     */
+    getWinner(): SkillCandidate | null;
+}
+//# sourceMappingURL=ab-runner.d.ts.map

package/dist/skill-loop/ab-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ab-runner.d.ts","sourceRoot":"","sources":["../../src/skill-loop/ab-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAMrD,MAAM,WAAW,QAAQ;IACvB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,MAAM;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAuDD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;IAChE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgB;gBAEtC,MAAM,EAAE,QAAQ;IAS5B;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO;IAchD;;;;;OAKG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAgBrE;;;OAGG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAa5C;;;;;;;;;OASG;IACH,SAAS,IAAI,cAAc,GAAG,IAAI;CAqBnC"}

package/dist/skill-loop/ab-runner.js

@@ -0,0 +1,160 @@
+/**
+ * src/skill-loop/ab-runner.ts
+ *
+ * A/B test runner with failure budgets for SkillCandidates.
+ *
+ * Invariants:
+ *   - Max 3 candidates simultaneously (4th is rejected).
+ *   - Traffic fraction cap: 10% per candidate.
+ *   - Rollback triggered when a candidate's mean score drops >5% vs incumbent.
+ *   - Winner declared when: p < 0.05 AND delta >= 10% AND no rollback triggered.
+ *
+ * Statistical significance uses the same Welch approach as evaluator.ts.
+ *
+ * @module skill-loop/ab-runner
+ */
+// ---------------------------------------------------------------------------
+// Statistical helpers (inline — avoid circular dep with evaluator)
+// ---------------------------------------------------------------------------
+function mean(xs) {
+    if (xs.length === 0)
+        return 0;
+    return xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+function variance(xs, m) {
+    if (xs.length < 2)
+        return 0;
+    return xs.reduce((acc, x) => acc + (x - m) ** 2, 0) / (xs.length - 1);
+}
+function normalCdf(z) {
+    const t = 1 / (1 + 0.2316419 * z);
+    const d = 0.3989423 * Math.exp((-z * z) / 2);
+    const p = d *
+        t *
+        (0.3193815 +
+            t * (-0.3565638 + t * (1.7814779 + t * (-1.8212559 + t * 1.3302744))));
+    return 1 - p;
+}
+function welchPValue(a, b) {
+    const n1 = a.length;
+    const n2 = b.length;
+    if (n1 < 2 || n2 < 2)
+        return 1.0;
+    const m1 = mean(a);
+    const m2 = mean(b);
+    const v1 = variance(a, m1);
+    const v2 = variance(b, m2);
+    const se = Math.sqrt(v1 / n1 + v2 / n2);
+    if (se === 0)
+        return m1 === m2 ? 1.0 : 0.0;
+    const tStat = Math.abs((m1 - m2) / se);
+    const df = (v1 / n1 + v2 / n2) ** 2 /
+        ((v1 / n1) ** 2 / (n1 - 1) + (v2 / n2) ** 2 / (n2 - 1));
+    if (df >= 30) {
+        return Math.max(0, Math.min(1, 2 * (1 - normalCdf(tStat))));
+    }
+    // Conservative: approximate p via critical value at df ≈ 30 (t-crit = 2.042)
+    return tStat > 2.042 ? 0.04 : 0.1;
+}
+// ---------------------------------------------------------------------------
+// ABRunner
+// ---------------------------------------------------------------------------
+export class ABRunner {
+    config;
+    slots = new Map();
+    candidates = new Map();
+    incumbentOutcomes = [];
+    constructor(config) {
+        // Enforce hard caps
+        this.config = {
+            maxCandidates: Math.min(config.maxCandidates, 3),
+            trafficPct: Math.min(config.trafficPct, 0.1),
+            rollbackThresholdPct: config.rollbackThresholdPct,
+        };
+    }
+    /**
+     * Register a new candidate for A/B testing.
+     *
+     * @returns true if added, false if maxCandidates already reached.
+     */
+    addCandidate(candidate) {
+        if (this.slots.size >= this.config.maxCandidates) {
+            return false;
+        }
+        this.candidates.set(candidate.id, candidate);
+        this.slots.set(candidate.id, {
+            candidateId: candidate.id,
+            trafficFraction: this.config.trafficPct,
+            outcomes: [],
+            rollbackTriggered: false,
+        });
+        return true;
+    }
+    /**
+     * Record an outcome score for a candidate or the incumbent.
+     *
+     * @param candidateId - Candidate ID or "incumbent".
+     * @param score       - Outcome score [0, 1].
+     */
+    recordOutcome(candidateId, score) {
+        if (candidateId === "incumbent") {
+            this.incumbentOutcomes.push(score);
+            return;
+        }
+        const slot = this.slots.get(candidateId);
+        if (!slot)
+            return;
+        slot.outcomes.push(score);
+        // Check rollback condition after each new data point
+        if (!slot.rollbackTriggered && this.shouldRollback(candidateId)) {
+            slot.rollbackTriggered = true;
+        }
+    }
+    /**
+     * Returns true if the candidate's mean score has dropped >rollbackThresholdPct
+     * vs the incumbent mean.
+     */
+    shouldRollback(candidateId) {
+        const slot = this.slots.get(candidateId);
+        if (!slot || slot.outcomes.length === 0)
+            return false;
+        if (this.incumbentOutcomes.length === 0)
+            return false;
+        const candMean = mean(slot.outcomes);
+        const incMean = mean(this.incumbentOutcomes);
+        // Degradation: candidate is worse than incumbent by more than threshold
+        const degradation = incMean - candMean;
+        return degradation > this.config.rollbackThresholdPct;
+    }
+    /**
+     * Return the winning candidate if statistical significance is established.
+     *
+     * Winner criteria:
+     *   - p < 0.05 (Welch's t-test vs incumbent)
+     *   - delta >= 10% vs incumbent mean
+     *   - rollback NOT triggered
+     *
+     * Returns null if no candidate meets all criteria.
+     */
+    getWinner() {
+        if (this.incumbentOutcomes.length < 2)
+            return null;
+        const incMean = mean(this.incumbentOutcomes);
+        for (const [id, slot] of this.slots) {
+            if (slot.rollbackTriggered)
+                continue;
+            if (slot.outcomes.length < 2)
+                continue;
+            const candMean = mean(slot.outcomes);
+            const delta = candMean - incMean;
+            if (delta < 0.1)
+                continue;
+            const p = welchPValue(slot.outcomes, this.incumbentOutcomes);
+            if (p < 0.05) {
+                return this.candidates.get(id) ?? null;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=ab-runner.js.map

package/dist/skill-loop/ab-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ab-runner.js","sourceRoot":"","sources":["../../src/skill-loop/ab-runner.ts"],"names":[],"mappings":"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"}

package/dist/skill-loop/adoption.d.ts

@@ -0,0 +1,67 @@
+/**
+ * src/skill-loop/adoption.ts
+ *
+ * Skill adoption — auto-promote and deprecate logic gated by sign-off.
+ *
+ * Promotion conditions (ALL must hold):
+ *   1. EvalResult.pValue < 0.05  (statistical significance)
+ *   2. EvalResult.deltaVsIncumbent >= 0.10  (>=10% improvement)
+ *   3. A valid approved SignOffRecord exists for the candidateId
+ *
+ * Violation of condition 3 → throws PromotionWithoutSignOffError.
+ *
+ * Underperformers (deltaVsIncumbent < -0.05 OR pValue > 0.5) are
+ * automatically deprecated via deprecateUnderperformers().
+ *
+ * @module skill-loop/adoption
+ */
+import type { SkillCandidate } from "./candidate.js";
+import type { EvalResult } from "./evaluator.js";
+import type { SignOffRecord } from "./sign-off.js";
+export declare class PromotionWithoutSignOffError extends Error {
+    readonly candidateId: string;
+    constructor(candidateId: string);
+}
+export type AdoptionStatus = "promoted" | "rejected" | "deprecated" | "pending_signoff" | "insufficient_signal";
+export interface AdoptionRecord {
+    candidateId: string;
+    status: AdoptionStatus;
+    evalResult: EvalResult;
+    signOff: SignOffRecord | null;
+    promotedAt: Date | null;
+    deprecatedAt: Date | null;
+    reason: string;
+}
+/**
+ * Attempt to promote a candidate to production.
+ *
+ * @param candidate  - The skill candidate.
+ * @param evalResult - Evaluation result against the verifier set.
+ * @param signOff    - Approved sign-off record (must be decision === 'approved').
+ * @param nowDate    - Optional date override for deterministic testing.
+ *
+ * @throws PromotionWithoutSignOffError if signOff is null or not approved.
+ */
+export declare function promoteCandidate(candidate: SkillCandidate, evalResult: EvalResult, signOff: SignOffRecord | null, nowDate?: Date): AdoptionRecord;
+/**
+ * Reject a candidate explicitly (e.g. sign-off decision = rejected).
+ */
+export declare function rejectCandidate(candidate: SkillCandidate, evalResult: EvalResult, signOff: SignOffRecord | null, reason: string): AdoptionRecord;
+/**
+ * Automatically deprecate underperforming candidates from a pool.
+ *
+ * A candidate is an underperformer if:
+ *   - deltaVsIncumbent < -0.05 (degrades by more than 5%)
+ *   - OR (deltaVsIncumbent < 0 AND pValue > 0.5) — statistically noisy & negative
+ *
+ * Deprecation is automatic — no sign-off required (sign-off is only for promotion).
+ *
+ * @param candidates  - Pool of (candidate, evalResult) pairs to assess.
+ * @param nowDate     - Optional date override.
+ * @returns AdoptionRecords for every deprecated candidate.
+ */
+export declare function deprecateUnderperformers(candidates: Array<{
+    candidate: SkillCandidate;
+    evalResult: EvalResult;
+}>, nowDate?: Date): AdoptionRecord[];
+//# sourceMappingURL=adoption.d.ts.map

package/dist/skill-loop/adoption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adoption.d.ts","sourceRoot":"","sources":["../../src/skill-loop/adoption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMnD,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,WAAW,EAAE,MAAM;CAQhC;AAMD,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,UAAU,GACV,YAAY,GACZ,iBAAiB,GACjB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,aAAa,GAAG,IAAI,EAC7B,OAAO,CAAC,EAAE,IAAI,GACb,cAAc,CAmChB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,aAAa,GAAG,IAAI,EAC7B,MAAM,EAAE,MAAM,GACb,cAAc,CAUhB;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC,EACxE,OAAO,CAAC,EAAE,IAAI,GACb,cAAc,EAAE,CAyBlB"}