From 8535f678ac1acf221ff09dc4aae492285102a725 Mon Sep 17 00:00:00 2001 From: Trae AI Date: Mon, 25 May 2026 23:34:09 +0800 Subject: [PATCH] Add evolver core types --- gitnexus/src/core/evolver/index.ts | 1 + gitnexus/src/core/evolver/types.ts | 262 +++++++++++++++++++++++ gitnexus/test/unit/evolver/types.test.ts | 95 ++++++++ 3 files changed, 358 insertions(+) create mode 100644 gitnexus/src/core/evolver/index.ts create mode 100644 gitnexus/src/core/evolver/types.ts create mode 100644 gitnexus/test/unit/evolver/types.test.ts diff --git a/gitnexus/src/core/evolver/index.ts b/gitnexus/src/core/evolver/index.ts new file mode 100644 index 000000000..d4702960d --- /dev/null +++ b/gitnexus/src/core/evolver/index.ts @@ -0,0 +1 @@ +export * from './types.js'; diff --git a/gitnexus/src/core/evolver/types.ts b/gitnexus/src/core/evolver/types.ts new file mode 100644 index 000000000..db7842722 --- /dev/null +++ b/gitnexus/src/core/evolver/types.ts @@ -0,0 +1,262 @@ +export const EVOLVER_MUTATION_TYPES = ['parameter', 'algorithm', 'structure'] as const; + +export type MutationType = (typeof EVOLVER_MUTATION_TYPES)[number]; + +export type MetricDirection = 'increase' | 'decrease'; + +export type RiskLevel = 'low' | 'medium' | 'high'; + +export type EvaluationVerdict = 'promote' | 'reject' | 'needs-review'; + +export type GateDecisionValue = 'allow' | 'reject' | 'needs-review'; + +export type CorrectionActionType = + | 'retry' + | 'rollback-parameters' + | 'disable-variant' + | 'request-structure-review' + | 'reduce-budget' + | 'freeze-promotion' + | 'stop-plan'; + +export interface MetricTarget { + metricId: string; + direction: MetricDirection; + minDelta?: number; + maxRegression?: number; + targetValue?: number; +} + +export interface EvolutionConstraint { + id: string; + description: string; + severity: RiskLevel; +} + +export interface GoalSpec { + id: string; + name: string; + objective: string; + priority: number; + targetMetrics: MetricTarget[]; + constraints: EvolutionConstraint[]; + stopConditions: string[]; +} + +export interface EnvironmentSignal { + id: string; + kind: 'performance' | 'error' | 'dependency' | 'data' | 'resource' | 'safety'; + description: string; + severity: RiskLevel; + observedAt: string; +} + +export interface MetricReading { + metricId: string; + value: number; + capturedAt: string; +} + +export interface ErrorEvent { + id: string; + type: + | 'temporary-failure' + | 'parameter-degradation' + | 'algorithm-regression' + | 'structure-risk' + | 'resource-exhaustion' + | 'evaluation-distortion' + | 'safety-boundary-triggered'; + message: string; + occurredAt: string; + variantId?: string; +} + +export interface ResourceUsage { + durationMs: number; + computeUnits: number; + apiCostUsd: number; + storageBytes: number; +} + +export interface EnvironmentSnapshot { + id: string; + capturedAt: string; + signals: EnvironmentSignal[]; + performance: MetricReading[]; + errors: ErrorEvent[]; + resourceUsage: ResourceUsage; +} + +export interface BaselineProfile { + id: string; + goalId: string; + capturedAt: string; + metrics: MetricReading[]; + resourceUsage: ResourceUsage; +} + +export interface EvolutionTarget { + id: string; + kind: 'parameter-set' | 'algorithm-policy' | 'module-structure'; + description: string; +} + +export interface ResourceBudget { + maxDurationMs: number; + maxComputeUnits: number; + maxApiCostUsd: number; + maxStorageBytes: number; + maxConcurrency: number; + maxHighRiskVariants: number; +} + +export interface EvolutionPlan { + id: string; + goalId: string; + hypothesis: string; + targetObject: EvolutionTarget; + allowedMutationTypes: MutationType[]; + evaluationProtocolId: string; + resourceBudget: ResourceBudget; +} + +export interface ParameterPatchOperation { + op: 'setParameter'; + path: string; + previousValue: unknown; + nextValue: unknown; +} + +export interface AlgorithmPatchOperation { + op: 'selectAlgorithm'; + policyId: string; + previousAlgorithm: string; + nextAlgorithm: string; +} + +export interface StructurePatchOperation { + op: 'proposeStructureChange'; + planPath: string; + summary: string; +} + +export type VariantPatchOperation = + | ParameterPatchOperation + | AlgorithmPatchOperation + | StructurePatchOperation; + +export interface VariantPatch { + operations: VariantPatchOperation[]; +} + +export interface MetricExpectation { + metricId: string; + expectedDelta: number; + direction: MetricDirection; +} + +export interface RollbackPlan { + strategy: 'restore-previous-parameters' | 'disable-candidate' | 'manual-review-required'; + operations: VariantPatchOperation[]; +} + +export interface VariantProvenance { + source: string; + reference: string; + capturedAt: string; +} + +export interface VariantSpec { + id: string; + planId: string; + mutationType: MutationType; + description: string; + patch: VariantPatch; + expectedGain: MetricExpectation[]; + riskLevel: RiskLevel; + rollbackPlan: RollbackPlan; + provenance: VariantProvenance[]; +} + +export interface TrialResult { + id: string; + variantId: string; + protocolId: string; + metrics: MetricReading[]; + resourceUsage: ResourceUsage; + errors: ErrorEvent[]; + completedAt: string; +} + +export interface MetricDelta { + metricId: string; + baselineValue: number; + candidateValue: number; + delta: number; + direction: MetricDirection; + passed: boolean; +} + +export interface RegressionFinding { + metricId: string; + baselineValue: number; + candidateValue: number; + regressionAmount: number; + limit: number; +} + +export interface SafetyFinding { + id: string; + severity: RiskLevel; + message: string; +} + +export interface EvaluationReport { + id: string; + variantId: string; + baselineId: string; + metricDeltas: MetricDelta[]; + regressions: RegressionFinding[]; + resourceCost: ResourceUsage; + safetyFindings: SafetyFinding[]; + verdict: EvaluationVerdict; +} + +export interface GateDecision { + id: string; + variantId: string; + reportId: string; + decision: GateDecisionValue; + reasons: string[]; + decidedAt: string; +} + +export interface PromotionRecord { + id: string; + variantId: string; + gateDecisionId: string; + appliedAt: string; + rollbackPlan: RollbackPlan; + previousState: Record; + nextState: Record; +} + +export interface CorrectionAction { + id: string; + errorEventId: string; + type: CorrectionActionType; + reason: string; + createdAt: string; + variantId?: string; +} + +export interface EvolutionMemoryRecord { + id: string; + goalId?: string; + variantId?: string; + kind: 'variant' | 'trial' | 'evaluation' | 'gate' | 'promotion' | 'correction'; + summary: string; + createdAt: string; + payload: unknown; +} diff --git a/gitnexus/test/unit/evolver/types.test.ts b/gitnexus/test/unit/evolver/types.test.ts new file mode 100644 index 000000000..87ff8f3f1 --- /dev/null +++ b/gitnexus/test/unit/evolver/types.test.ts @@ -0,0 +1,95 @@ +import { describe, expect, it } from 'vitest'; +import { + EVOLVER_MUTATION_TYPES, + type EvaluationReport, + type GateDecision, + type MutationType, + type VariantSpec, +} from '../../../src/core/evolver/index.js'; + +describe('evolver core types', () => { + it('supports a fully typed promotable parameter variant', () => { + const mutationType: MutationType = 'parameter'; + const variant: VariantSpec = { + id: 'variant-plan-1-parameter', + planId: 'plan-1', + mutationType, + description: 'Increase retrieval topK from 5 to 8', + patch: { + operations: [ + { + op: 'setParameter', + path: 'retrieval.topK', + previousValue: 5, + nextValue: 8, + }, + ], + }, + expectedGain: [ + { + metricId: 'task_success_rate', + expectedDelta: 0.08, + direction: 'increase', + }, + ], + riskLevel: 'low', + rollbackPlan: { + strategy: 'restore-previous-parameters', + operations: [ + { + op: 'setParameter', + path: 'retrieval.topK', + previousValue: 8, + nextValue: 5, + }, + ], + }, + provenance: [ + { + source: 'synthetic-benchmark', + reference: 'benchmark/run-1', + capturedAt: '2026-05-25T00:00:00.000Z', + }, + ], + }; + + const report: EvaluationReport = { + id: 'report-1', + variantId: variant.id, + baselineId: 'baseline-1', + metricDeltas: [ + { + metricId: 'task_success_rate', + baselineValue: 0.72, + candidateValue: 0.81, + delta: 0.09, + direction: 'increase', + passed: true, + }, + ], + regressions: [], + resourceCost: { + durationMs: 120, + computeUnits: 1, + apiCostUsd: 0, + storageBytes: 256, + }, + safetyFindings: [], + verdict: 'promote', + }; + + const gate: GateDecision = { + id: 'gate-1', + variantId: variant.id, + reportId: report.id, + decision: 'allow', + reasons: ['parameter variant passed metrics, budget, safety, and rollback checks'], + decidedAt: '2026-05-25T00:00:01.000Z', + }; + + expect(EVOLVER_MUTATION_TYPES).toEqual(['parameter', 'algorithm', 'structure']); + expect(variant.mutationType).toBe('parameter'); + expect(report.verdict).toBe('promote'); + expect(gate.decision).toBe('allow'); + }); +});