134 lines
4.6 KiB
TypeScript
134 lines
4.6 KiB
TypeScript
/**
|
||
* GEPA Faza 1 — cost governance + super-linear projection tracker.
|
||
*
|
||
* Per launch decision §A.7 + manifest v7 §cost_governance.
|
||
*
|
||
* Halt triggers (any single triggers immediate halt + PM ratify):
|
||
* - Cumulative spend > $80 (internal halt)
|
||
* - Cumulative spend > $100 (hard cap)
|
||
* - Mid-run actual exceeds projection by >30% (super-linear sub-rule per brief §6.7)
|
||
*
|
||
* Audit cadence: every 20 evaluations.
|
||
*
|
||
* Cost projection methodology: 1.5× baseline token count per candidate
|
||
* (encodes mutation overhead since GEPA candidates may grow prompts).
|
||
*/
|
||
|
||
/** Hard cap (immediate halt on breach). */
|
||
export const HARD_CAP_USD = 100.00;
|
||
|
||
/** Internal halt threshold (halt + PM ratify before proceeding). */
|
||
export const INTERNAL_HALT_USD = 80.00;
|
||
|
||
/** Super-linear projection multiplier per brief §6.7. */
|
||
export const SUPER_LINEAR_MULTIPLIER = 1.5;
|
||
|
||
/** Mid-run halt threshold: actual exceeds projection by this fraction. */
|
||
export const SUPER_LINEAR_OVERAGE_THRESHOLD = 0.30;
|
||
|
||
/** Audit cadence (every N evaluations). */
|
||
export const AUDIT_CADENCE_EVAL_COUNT = 20;
|
||
|
||
export type HaltReason =
|
||
| 'NONE'
|
||
| 'INTERNAL_HALT_USD_BREACH'
|
||
| 'HARD_CAP_USD_BREACH'
|
||
| 'SUPER_LINEAR_PROJECTION_BREACH';
|
||
|
||
export interface CostTrackerState {
|
||
cumulativeUsd: number;
|
||
evaluationCount: number;
|
||
/** Per-evaluation projection used for super-linear check (1.5× baseline median). */
|
||
projectionPerEvalUsd: number;
|
||
}
|
||
|
||
export interface HaltCheckResult {
|
||
haltReason: HaltReason;
|
||
cumulativeUsd: number;
|
||
expectedAtThisCount: number;
|
||
overageFraction: number;
|
||
message: string;
|
||
}
|
||
|
||
/** Create a new cost tracker state with the per-evaluation projection. */
|
||
export function createCostTracker(baselineMedianCostPerEvalUsd: number): CostTrackerState {
|
||
return {
|
||
cumulativeUsd: 0,
|
||
evaluationCount: 0,
|
||
projectionPerEvalUsd: baselineMedianCostPerEvalUsd * SUPER_LINEAR_MULTIPLIER,
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Record an evaluation cost and return updated state (immutable update).
|
||
* Per coding-style.md: never mutate, always return new copy.
|
||
*/
|
||
export function recordEvaluation(state: CostTrackerState, evalCostUsd: number): CostTrackerState {
|
||
return {
|
||
...state,
|
||
cumulativeUsd: state.cumulativeUsd + evalCostUsd,
|
||
evaluationCount: state.evaluationCount + 1,
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Check halt triggers against current state.
|
||
*
|
||
* Returns NONE if all checks pass; otherwise returns the first triggered
|
||
* halt reason with diagnostic context.
|
||
*
|
||
* Order of precedence (most severe first):
|
||
* 1. HARD_CAP_USD_BREACH ($100 breach)
|
||
* 2. INTERNAL_HALT_USD_BREACH ($80 breach)
|
||
* 3. SUPER_LINEAR_PROJECTION_BREACH (actual > 1.30 × expected at current eval count)
|
||
*/
|
||
export function checkHaltTriggers(state: CostTrackerState): HaltCheckResult {
|
||
const expectedAtThisCount = state.projectionPerEvalUsd * state.evaluationCount;
|
||
const overageFraction =
|
||
expectedAtThisCount > 0 ? (state.cumulativeUsd - expectedAtThisCount) / expectedAtThisCount : 0;
|
||
|
||
if (state.cumulativeUsd > HARD_CAP_USD) {
|
||
return {
|
||
haltReason: 'HARD_CAP_USD_BREACH',
|
||
cumulativeUsd: state.cumulativeUsd,
|
||
expectedAtThisCount,
|
||
overageFraction,
|
||
message: `HARD CAP BREACH: $${state.cumulativeUsd.toFixed(2)} > $${HARD_CAP_USD} cap`,
|
||
};
|
||
}
|
||
|
||
if (state.cumulativeUsd > INTERNAL_HALT_USD) {
|
||
return {
|
||
haltReason: 'INTERNAL_HALT_USD_BREACH',
|
||
cumulativeUsd: state.cumulativeUsd,
|
||
expectedAtThisCount,
|
||
overageFraction,
|
||
message: `INTERNAL HALT: $${state.cumulativeUsd.toFixed(2)} > $${INTERNAL_HALT_USD} internal halt — PM ratify before proceeding`,
|
||
};
|
||
}
|
||
|
||
// Super-linear check requires at least 1 eval to have meaningful expected value.
|
||
if (state.evaluationCount > 0 && overageFraction > SUPER_LINEAR_OVERAGE_THRESHOLD) {
|
||
return {
|
||
haltReason: 'SUPER_LINEAR_PROJECTION_BREACH',
|
||
cumulativeUsd: state.cumulativeUsd,
|
||
expectedAtThisCount,
|
||
overageFraction,
|
||
message: `SUPER-LINEAR BREACH: actual $${state.cumulativeUsd.toFixed(2)} exceeds expected $${expectedAtThisCount.toFixed(2)} by ${(overageFraction * 100).toFixed(1)}% (>${(SUPER_LINEAR_OVERAGE_THRESHOLD * 100).toFixed(0)}% threshold)`,
|
||
};
|
||
}
|
||
|
||
return {
|
||
haltReason: 'NONE',
|
||
cumulativeUsd: state.cumulativeUsd,
|
||
expectedAtThisCount,
|
||
overageFraction,
|
||
message: `OK: $${state.cumulativeUsd.toFixed(2)} cumulative; expected $${expectedAtThisCount.toFixed(2)}; ${(overageFraction * 100).toFixed(1)}% overage`,
|
||
};
|
||
}
|
||
|
||
/** Whether the current eval count is on an audit cadence boundary. */
|
||
export function shouldAudit(state: CostTrackerState): boolean {
|
||
return state.evaluationCount > 0 && state.evaluationCount % AUDIT_CADENCE_EVAL_COUNT === 0;
|
||
}
|