Skip to content

MAINTENANCE.md

Latest commit

 

History

History
48 lines (31 loc) · 2.42 KB

MAINTENANCE.md

File metadata and controls

48 lines (31 loc) · 2.42 KB

Maintenance & Design Decisions

Architecture Decisions

Why genome-level mutations exist alongside bytecode mutations

Bytecode mutations are fine-grained: change an opcode, patch a jump. They're analogous to point mutations in biology. But evolution also needs structural changes — duplicating useful code blocks, removing dead code, reorganizing loops. That's what genome-level mutations provide: a higher abstraction layer that can make bigger structural changes in a single step.

Why fitness is multiplicative

fitness = speed × confidence × trust — All three factors must be present. A fast but untrustworthy agent doesn't survive. A confident but slow agent gets outcompeted. This multiplicative formula ensures balanced optimization rather than fixating on a single metric.

Why rollback is snapshot-based (not diff-based)

Diffs are fragile with jump tables — changing one offset can invalidate multiple jumps. Snapshots are O(n) space but O(1) restore, and they're always correct. The max_bytecode_size limit (default 4096 bytes) keeps memory bounded.

Why mutation proposals are probabilistic

The mutation_rate parameter prevents over-eager modification. An agent that changes its own code every cycle is unstable. The rate allows tuning between cautious (low rate) and exploratory (high rate).

Safety Model

  1. Hard constraints (always enforced):

    • Max bytecode size
    • Valid jump targets
    • No empty bytecodes after mutation

  2. Soft constraints (policy-configurable):

    • Mutation rate
    • Trust requirement
    • Rollback threshold

  3. Post-hoc validation:

    • Fitness comparison → rollback if below threshold
    • Jump table consistency re-check after apply

Testing Strategy

  • 15 tests covering: proposal validity, apply+verify, rollback, fitness, competition, crossover, genome roundtrip, genome mutation, history, safety (broken jumps, size limits), policy enforcement, trend detection, confidence-gated rollback, empty bytecode rejection
  • Seeded RNG for deterministic test behavior
  • Tests use representative bytecode patterns (jumps, NOPs, decay instructions)

Future Directions

  • Speciation: Track distinct bytecode lineages and prevent convergence
  • Horizontal gene transfer: Share successful mutations between agents
  • Epigenetic marks: Metadata that modifies interpretation without changing bytecode
  • Fitness landscapes: Visualize and analyze the evolutionary terrain