Add evolver core types

gitnexus/src/core/evolver/index.ts

@@ -0,0 +1 @@
+export * from './types.js';

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<string, unknown>;
+  nextState: Record<string, unknown>;
+}
+
+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;
+}

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');
+  });
+});