Evolve

Point kern evolve at any codebase. An LLM finds repeating patterns KERN can't express. It proposes new nodes. You approve. The language grows.

The loop

kern evolve:discover src/ --recursive

kern evolve:review-v4

kern myfile.kern

kern evolve:test

How discovery works

1. Smart sampling — clusters files by directory, picks 3-5 representative files per cluster. Never sends the whole codebase.
2. LLM analysis — each batch includes source files + the full list of existing KERN nodes. The LLM identifies what's missing.
3. Frequency filter — only patterns appearing 3+ times survive. No one-off suggestions.
4. 9-step validation — schema, keyword collision, parse, codegen compile, codegen run, TypeScript syntax, golden diff, dedup.

Example: full lifecycle

# 1. Discover patterns in a codebase
kern evolve:discover src/ --recursive
#  → Found 3 candidates: cache-layer (12x), api-validator (8x), event-bus (5x)

# 2. Review proposals
kern evolve:review-v4
#  → Split-view UI for each proposal
#  → Approve cache-layer, reject api-validator

# 3. Use it in .kern files — it's a real node now
#    cache-layer name=userCache backend=redis ttl=3600
#      entry name=profile key="user:{id}"
#      invalidate on=userUpdate

# 4. Compile — offline, no LLM needed
kern dev kern/ --outdir=app/

# 5. Need Vue target?
kern evolve:backfill cache-layer --target=vue

# 6. Test evolved nodes in CI
kern evolve:test

# 7. After months of stability — promote to core
kern evolve:promote cache-layer

Commands

evolve:discover flags

• --recursive — scan subdirectories
• --provider=openai|anthropic|ollama — LLM provider (auto-detected from env)
• --max-tokens=N — token budget cap (default: 100,000)

evolve:review-v4 flags

• --approve=<id> — approve and graduate a proposal
• --reject=<id> — reject and discard
• --detail=<id> — show full codegen source, props, instances

Compile flags

• --verify — check SHA256 hashes on evolved node codegen (recommended for CI)

Security

File structure

Graduated nodes live in .kern/evolved/ in your project root:

.kern/evolved/
├── manifest.json              # Registry of all graduated nodes
├── cache-layer/
│   ├── definition.json        # Props, childTypes, reason, metadata
│   ├── codegen.js             # Pre-compiled generator (sandboxed)
│   ├── codegen.ts             # Original TypeScript source
│   ├── template.kern          # Golden KERN input
│   ├── expected-output.ts     # Golden TS output
│   └── targets/               # Optional target-specific overrides
│       ├── express.js
│       └── vue.js

Validation pipeline

Every proposal passes 9 checks before it can be approved:

TypeScript validation uses ts.transpileModule for real syntax checking. On failure at steps 3-7, the system feeds errors back to the LLM for automatic retry (max 2).

Cost controls

• Incremental — only scans changed files by default (git diff since last run).
• Token budget — --max-tokens=100000 aborts with summary if exceeded.
• Local LLM — --provider=ollama for cost-free local discovery.
• Smart sampling — max 5 files per directory cluster. Never sends the whole codebase.

Node lifecycle

discover → validate → stage → review → graduate → compile → test
                                                         ↓
                                               (months of use)
                                                         ↓
                                                      promote → core

• Graduate — writes to .kern/evolved/, available immediately.
• Rollback — moves to .trash/, recoverable with restore.
• Prune — auto-removes nodes unused for 90 days.
• Migrate — when KERN upgrades add a core type that collides with your evolved node.
• Promote — when stable, outputs steps to add the node to KERN's core codegen.