---
artifact_kind: optimizer-card
artifact_name: map-elites
version: 1.0.0
owner: Nous · agreement-search team
last_reviewed: 2026-04-25
next_review: 2026-07-25
optimizer_kind: multi-objective
related_phase_179_tasks: [179.4.2.2]
---

# Optimizer Card — map-elites v1.0.0

## 1. Identity

- **Optimizer name:** map-elites
- **Algorithm family:** MAP-Elites (Mouret & Clune 2015) — quality- diversity
  search via behaviour-characterization grid.
- **Implementation source:** `libs/nous/agreement-search/src/map-elites.ts` with
  shared GA primitives in `ga-operators.ts`.
- **Intended use:** behaviour-diverse candidate exploration where the workbench
  surfaces structurally different agreement families along caller-defined
  behaviour axes (e.g., monetary-vs-restorative balance, immediate-vs-deferred
  payout, restitution share).

## 2. Scoring rule

- **Utility aggregation:** scalar fitness within each grid cell; caller-supplied
  (typically Nash product or weighted sum).
- **Fairness metrics reported:** caller-selected; `fairness-metrics.ts` attaches
  to each cell-elite.
- **Handling of hard constraints:** `filterCandidates` runs on every child
  before insertion.
- **Handling of uncertainty:** within-cell elite is selected by fitness; fitness
  can be posterior mean / LCB / Thompson per the caller.

## 3. Inputs

- **Candidate space:** sandboxed clause-mutator DSL.
- **Behaviour characterization:** caller-defined axes; the kernel discretizes
  them into a grid and keeps the highest-fitness candidate per cell.
- **Initial population / seeds:** §179.4.1.1 sources.
- **Time / iteration budget:** total iterations + cell-improvement patience.
- **Randomness:** seeded `mulberry32`.

## 4. Outputs

- **Accepted candidate contract:** the populated grid — one elite per occupied
  cell. The workbench renders this as a heatmap of agreement families
  (§179.4.3.1).
- **Pareto-frontier diagnostics:** cell-occupancy ratio, per-cell fitness,
  per-cell elite lineage.
- **Uncertainty propagation:** per-cell elite carries the same posterior detail
  nash-genetic / NSGA-II emit.

## 5. Evaluation

| Metric                          | Value                                | Evaluator card                                                      | Date       |
| ------------------------------- | ------------------------------------ | ------------------------------------------------------------------- | ---------- |
| Pareto-front coverage           | grid occupancy ≥ 60% on benchmark    | n/a — `map-elites.test.ts` integration                              | 2026-04-25 |
|                                 | scenarios                            |                                                                     |            |
| Diversity preservation          | structurally distinct elites by      | n/a — `map-elites.test.ts`                                          | 2026-04-25 |
|                                 | behaviour axis (asserted)            |                                                                     |            |
| Fairness (Nash / KS / max-min)  | per-cell metrics; gate runs against  | [fairness-suite](../evaluators/fairness-suite.md)                   | 2026-04-25 |
|                                 | §179.10.6 baseline                   |                                                                     |            |
| Regret vs oracle                | bounded by within-cell elite         | [baseline-benchmark-gate](../evaluators/baseline-benchmark-gate.md) | 2026-04-25 |
|                                 | selection                            |                                                                     |            |
| Specification-gaming resistance | `spec-gaming-audit.ts` runs per-cell | [fairness-suite](../evaluators/fairness-suite.md)                   | 2026-04-25 |
| Runtime (typical)               | seconds for ~50 clauses, 10×10 grid  | n/a — deterministic synchronous kernel                              | 2026-04-25 |
| Cost per run                    | $0 once preference fits cached       | n/a                                                                 | 2026-04-25 |

## 6. Known limitations

- Behaviour-axis design is the caller's responsibility; poorly chosen axes give
  a misleading diversity picture.
- Coarse grids miss family boundaries; fine grids waste compute on empty cells.
  The kernel reports occupancy so callers can iterate.
- Cells empty under `filterCandidates` failures are reported but not imputed.

## 7. Guardrails

- **Candidate safety gate:** `filterCandidates` on every child before cell
  insertion.
- **Clause static validation:** inside `filterCandidates`.
- **Redline separation:** hard constraints filtered before grid population.
- **No coercive heatmap:** `coercive-choice-audit.ts` runs on the rendered grid
  before the workbench shows it.

## 8. References

- `libs/nous/agreement-search/src/map-elites.ts`
- Mouret, Clune (2015), "Illuminating search spaces by mapping elites".
- `docs/research/bibliography.md` §quality-diversity