create-principles-disciple 1.89.0 → 1.91.0

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

@@ -1,243 +0,0 @@
-/**
- * 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;
-    };
-    evidenceSummary: {
-        evidenceMode: 'shadow' | 'eval-proxy' | 'mixed';
-        shadowSampleCount: number;
-        deltaSource: 'eval';
-    };
-}
-/**
- * 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;