principles-disciple 1.7.6 → 1.7.8

package/dist/core/promotion-gate.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Promotion Gate — Checkpoint Promotion State Machine and Gate Logic
+ * ==================================================================
+ *
+ * PURPOSE: Control when a checkpoint can advance from training → shadow → promotion.
+ * Training success alone is not enough — a checkpoint must prove it improves
+ * bounded worker behavior under the existing offline benchmark and does not
+ * regress runtime safety signals.
+ *
+ * PROMOTION STATES:
+ *   - rejected:         The checkpoint must not be routed
+ *   - candidate_only:  The checkpoint is valid but not yet ready for shadow
+ *   - shadow_ready:   The checkpoint may enter controlled shadow rollout
+ *   - promotable:     The checkpoint may replace the active checkpoint
+ *
+ * STATE TRANSITIONS:
+ *   training_completed
+ *       ↓
+ *   candidate_only  ←── (eval attached, lineage complete)
+ *       ↓
+ *   shadow_ready   ←── (positive delta, safe constraints)
+ *       ↓
+ *   promotable      ←── (shadow window passed, orchestrator review passed)
+ *       ↓
+ *   deployed
+ *
+ * PRIMARY OBJECTIVE:
+ *   maximize reduced_prompt_holdout_delta
+ *
+ * CONSTRAINT METRICS (must all pass for promotion):
+ *   - arbiterRejectRate <= baseline + allowedMargin
+ *   - executabilityRejectRate <= baseline + allowedMargin
+ *   - reviewedSubsetQuality >= baseline
+ *   - routingScopeNotExpanded == true
+ *
+ * DESIGN CONSTRAINTS:
+ *   - No automatic promotion without explicit gate approval
+ *   - Orchestrator review remains mandatory for all promotions
+ *   - Rollback path must be always available
+ *   - First rollout limited to `local-reader` only
+ */
+import { type TrainableWorkerProfile } from './external-training-contract.js';
+/**
+ * Candidate delta must exceed this to enter shadow_ready.
+ */
+export declare const DEFAULT_MIN_DELTA = 0.05;
+/**
+ * Default allowed margin for constraint metrics.
+ * Constraint metrics can regress by at most this amount.
+ */
+export declare const DEFAULT_ALLOWED_MARGIN = 0.05;
+/**
+ * Minimum shadow window duration in milliseconds.
+ * A checkpoint must remain in shadow_ready for at least this duration
+ * before it can be promoted to promotable.
+ *
+ * Phase 7 default: 1 hour (3600000 ms)
+ * This gives time for real-world feedback before full promotion.
+ */
+export declare const MIN_SHADOW_WINDOW_MS: number;
+/**
+ * Promotion states for a checkpoint.
+ */
+export type PromotionState = 'rejected' | 'candidate_only' | 'shadow_ready' | 'promotable';
+/**
+ * Constraint metrics for promotion gate.
+ */
+export interface PromotionConstraints {
+    arbiterRejectRate: number;
+    executabilityRejectRate: number;
+    reviewedSubsetQuality: number;
+    routingScopeNotExpanded: boolean;
+}
+/**
+ * Baseline metrics for comparison.
+ */
+export interface BaselineMetrics {
+    arbiterRejectRate: number;
+    executabilityRejectRate: number;
+    reviewedSubsetQuality: number;
+}
+/**
+ * A promotion record — tracks the state and lineage of a promoted checkpoint.
+ */
+export interface PromotionRecord {
+    /** Unique identifier for this promotion record */
+    promotionId: string;
+    /** Checkpoint being promoted */
+    checkpointId: string;
+    /** Current promotion state */
+    state: PromotionState;
+    /** Worker profile this promotion targets */
+    targetProfile: TrainableWorkerProfile;
+    /** Target model family */
+    targetModelFamily: string;
+    /** Reduced-prompt holdout delta (primary objective) */
+    reducedPromptDelta: number;
+    /** Constraint metrics at time of promotion */
+    constraintMetrics: PromotionConstraints;
+    /** Baseline metrics used for comparison */
+    baselineMetrics: BaselineMetrics;
+    /** Whether orchestrator review was passed */
+    orchestratorReviewPassed: boolean;
+    /** Human review note (if any) */
+    reviewNote?: string;
+    /** ISO-8601 timestamp when state last changed */
+    stateChangedAt: string;
+    /** ISO-8601 timestamp when promotion record was created */
+    createdAt: string;
+    /** ISO-8601 timestamp when shadow window opened (if applicable) */
+    shadowStartedAt?: string;
+    /** ISO-8601 timestamp when promotable was achieved */
+    promotableAt?: string;
+    /** Previous promotion record ID (for rollback chain) */
+    previousPromotionId?: string;
+}
+/**
+ * The complete promotion registry.
+ */
+export interface PromotionRegistry {
+    promotions: PromotionRecord[];
+}
+/**
+ * Result of evaluating the promotion gate.
+ */
+export interface PromotionGateResult {
+    /** Whether the checkpoint passes the gate */
+    passes: boolean;
+    /** The promotion state if passed */
+    suggestedState?: PromotionState;
+    /** Reasons for rejection (if not passed) */
+    blockers: string[];
+    /** Details about each constraint check */
+    constraintChecks: {
+        constraint: string;
+        actual: number;
+        baseline: number;
+        threshold: number;
+        passed: boolean;
+        /** Source of the evidence: 'shadow' (real runtime) or 'eval-proxy' (fallback) */
+        source?: 'shadow' | 'eval-proxy';
+    }[];
+    /** Primary objective (delta) check */
+    deltaCheck: {
+        actual: number;
+        threshold: number;
+        passed: boolean;
+    };
+}
+/**
+ * Parameters for evaluating the promotion gate.
+ */
+export interface EvaluateGateParams {
+    /** Checkpoint ID to evaluate */
+    checkpointId: string;
+    /** Target worker profile */
+    targetProfile: TrainableWorkerProfile;
+    /** Baseline metrics for comparison */
+    baselineMetrics: BaselineMetrics;
+    /** Minimum delta threshold for positive signal */
+    minDelta?: number;
+    /** Allowed margin for constraint metrics */
+    allowedMargin?: number;
+}
+/**
+ * Evaluate whether a checkpoint passes the promotion gate.
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Evaluation parameters
+ * @returns PromotionGateResult with pass/fail and details
+ *
+ * FAIL-CLOSED: Returns { passes: false } if:
+ *   - No eval attached to checkpoint
+ *   - Delta is negative or below threshold
+ *   - Any constraint metric regresses beyond allowed margin
+ *   - Profile is not in allowed rollout list
+ */
+export declare function evaluatePromotionGate(stateDir: string, params: EvaluateGateParams): PromotionGateResult;
+/**
+ * Parameters for advancing promotion state.
+ */
+export interface AdvancePromotionParams {
+    /** Checkpoint ID to promote */
+    checkpointId: string;
+    /** Target worker profile */
+    targetProfile: TrainableWorkerProfile;
+    /** Baseline metrics for comparison */
+    baselineMetrics: BaselineMetrics;
+    /** Orchestrator review passed (required for promotable) */
+    orchestratorReviewPassed?: boolean;
+    /** Human review note */
+    reviewNote?: string;
+    /** Minimum delta threshold */
+    minDelta?: number;
+    /** Allowed margin for constraints */
+    allowedMargin?: number;
+}
+/**
+ * Advance a checkpoint's promotion state.
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Advancement parameters
+ * @returns The updated PromotionRecord
+ *
+ * @throws Error if gate evaluation fails
+ * @throws Error if state transition is not allowed
+ */
+export declare function advancePromotion(stateDir: string, params: AdvancePromotionParams): PromotionRecord;
+/**
+ * Get the current promotion state for a checkpoint.
+ */
+export declare function getPromotionState(stateDir: string, checkpointId: string): PromotionState | null;
+/**
+ * Get the promotion record for a checkpoint.
+ */
+export declare function getPromotionRecord(stateDir: string, checkpointId: string): PromotionRecord | null;
+/**
+ * List promotions by state.
+ */
+export declare function listPromotionsByState(stateDir: string, state: PromotionState): PromotionRecord[];
+/**
+ * List all promotions for a profile.
+ */
+export declare function listPromotionsForProfile(stateDir: string, targetProfile: TrainableWorkerProfile): PromotionRecord[];
+/**
+ * Reject a checkpoint, preventing it from being promoted.
+ *
+ * @param stateDir - Workspace state directory
+ * @param checkpointId - Checkpoint to reject
+ * @param reason - Reason for rejection
+ * @returns The updated PromotionRecord
+ */
+export declare function rejectCheckpoint(stateDir: string, checkpointId: string, reason: string): PromotionRecord;
+/**
+ * Default baseline metrics for Phase 7.
+ * These represent the "acceptable" thresholds that new checkpoints must meet.
+ */
+export declare const DEFAULT_BASELINE_METRICS: BaselineMetrics;