Skip to content

v0.9.0-alpha

This alpha release packages the changes landed after v0.8.4-alpha.

Use it if you need true multi-objective evolution, independent islands with controlled migration, one-command multi-process workers, evaluator-guided in-job rework, or portable repository embedding caches.

Highlights

  • MAP-Elites cells now hold bounded Pareto fronts over every configured objective and its explicit max/min direction. Scalar admission and the single-champion-per-cell archive have been removed.
  • Every configured island has independent PCA and archive state, fair seed and normal scheduling, and optional persisted cross-island donor migration.
  • loreley worker --processes N starts a spawn-based native Dramatiq process pool from one command. Worker base clones and job worktrees stay isolated across processes.
  • Candidate-owned evaluation failures can trigger bounded evaluator-guided coding rework inside the same job. Failed attempts remain diagnostic artifacts; only the final passing candidate is published.
  • Repository embedding caches can be attested and imported across compatible databases through explicit manifests and fail-closed compatibility checks.
  • Kilo execution now binds each run to its job worktree, honors separate planning and coding timeouts, and validates usage-session directory provenance.
  • Evolution commit summaries can inherit the worker provider, use a dedicated provider, use global OpenAI-compatible settings, or be disabled.

Upgrade Notes

Database migration required

This release bumps INSTANCE_SCHEMA_VERSION from 13 to 15. Take a PostgreSQL backup before upgrading a non-disposable database, then run:

uv run loreley db migrate
uv run loreley db validate

The native chain first adds schema version 14 embedding-cache manifests. Schema version 15 then replaces the incomplete scalar archive with multi-island Pareto storage, backfills missing result hashes from persisted candidate commits, and marks durable successful jobs for reingestion.

The v15 migration intentionally discards the old scalar archive because it cannot reconstruct Pareto membership from incomplete scalar state. Candidate commits and successful jobs remain available for reingestion.

When DB_AUTO_MIGRATE=true, API, scheduler, and worker startup run the same migration chain automatically. Run the explicit commands first when you want a controlled backup-and-validate window.

One-time configuration conversion

Legacy scalar and default-island settings are no longer accepted at runtime. Convert an existing env file once:

uv run python tools/migrate_v15_config.py .env --output .env.v15

Review the generated MAPELITES_OBJECTIVES and MAPELITES_ISLANDS JSON, then replace the old env file before startup. The converter preserves a blank legacy default-island override as the historical main island.

At minimum, review these new settings:

  • MAPELITES_OBJECTIVES
  • MAPELITES_ISLANDS
  • MAPELITES_PARETO_FRONT_MAX_SIZE
  • MAPELITES_PARETO_EPSILON
  • MAPELITES_MIGRATION_INTERVAL_JOBS

Archive and import boundary changes

  • Import MapElitesManager from loreley.core.map_elites.manager; the old re-export shim is removed.
  • Only configured islands participate in scheduling, status, API, and archive reads. Persisted but unconfigured island IDs are not discovered at runtime.
  • The ribs dependency and obsolete scalar archive fields are removed.
  • The first objective is only the primary operational projection used by status, baselines, and the convenience branch. Pareto admission always uses the complete ordered objective vector.

Worker and evaluator changes

  • Use loreley worker --processes N instead of opening several worker commands.
  • Current Kilo support requires kilo run --dir; older CLIs fail preflight rather than running without worktree isolation.
  • Planning and coding Kilo phases now honor WORKER_PLANNING_TIMEOUT_SECONDS and WORKER_CODING_TIMEOUT_SECONDS.
  • New repair-pool jobs are no longer scheduled. Evaluator-guided in-job rework is the supported retry path for candidate-owned evaluation failures.

Embedding-cache reuse

Use loreley embedding-cache attest on a source database and loreley embedding-cache import only after the manifest compatibility check passes. Import is rejected for missing or incompatible manifests, invalid source rows, fingerprint mismatches, or a non-empty target cache without a manifest.

Repository-state embedding also skips pathological cleaned lines and oversized chunks before calling the embedding provider, with separate bounded diagnostic counters for each skip reason.

Reliability Fixes

  • Retryable failed ingestion remains pending through its bounded five-attempt budget; exhausted results become terminal instead of blocking scheduler shutdown forever.
  • Seed readiness does not create duplicate probes while a failed ingestion is backing off.
  • Scheduler shutdown drains pending result ingestion before creating the final branch or exiting.
  • Migration cadence uses persisted per-island job counts instead of process lifetime or global counts.
  • Constant objectives do not receive arbitrary crowding-distance boundaries.
  • Archive updates restore durable island state after transaction rollback.
  • Worker repository change detection notices edits to already-dirty tracked or untracked files and rejects unsafe cleanup paths.
  • Empty campaigns terminate cleanly when no candidate is retained.
  • Kilo timeout usage recovery and explicit pricing rules preserve bounded cost evidence without turning telemetry failures into worker failures.

Validation

  • PostgreSQL-enabled release validation: 866 passed, 0 failed, 0 skipped in 44.17 seconds.
  • Statement coverage: 82.72%; branch coverage: 57.38%.
  • The same deterministic eight-job workload improved from 25.702 seconds at one process to 8.452 seconds at four processes: 3.041x job-window speedup and 1.970x wall-time speedup, with no duplicate jobs.
  • An eight-job island run split work 4/4 and persisted one donor in each direction.
  • The selected Kilo plus gpt-5.4-mini campaign completed 4/4 end-to-end jobs and improved the example objective from 0.25 to 2.5.
  • Cremona full-signal comparison: 0 new and 0 worsened structural-debt signals, with 22 resolved.
  • uv build, strict MkDocs, lock validation, compileall, JSON/tar integrity, credential scans, and git diff --check pass.

The experiment report and machine-readable evidence are in 2026-07-26-v15-experimental-validation.md.

Included Pull Requests

  • #42: evaluator-guided in-loop rework.
  • #43: hardened worker repository change detection and cleanup.
  • #44: portable repository embedding caches.
  • #45: oversized repository embedding input filters.
  • #46: Kilo worktree isolation.
  • #47: commit summarizer provider selection.
  • #48: Kilo planning and coding timeout settings.
  • #49: multi-island Pareto evolution and native parallel workers.
  • Replace scalar archive admission with bounded multi-objective Pareto fronts.
  • Add independent islands, persisted migration provenance, and one-command native worker parallelism.
  • Add a native schema 13-to-15 migration and a one-time v15 config converter.
  • Add evaluator-guided in-job rework, portable embedding caches, and stricter worker/Kilo isolation.