# ADR-059: The pool family kernel — one taxonomy, capability tiers, species as data

**Status: accepted** (2026-09-22, reviewed with the run-order amendment below). Basis: the touch-point survey
of 2026-09-22 (eight family enum definitions across the workspace) and the
roadmap drivers — LFJ (Trader Joe) binned-liquidity pools and
SushiSwap-V4/PancakeSwap-V4 manager species. Predecessors: ADR-014 (pool
registry projections), ADR-019 (strategy vs engine), ADR-040 (enum state
machines), ADR-043 (metric-label closure), ADR-058 (strategy crate split).

## Context

Two pool families ship today (V2/V3 plus a partially built V4), a third
arrives soon in two shapes: a genuinely new structure (LFJ binned
liquidity) and new species of an existing structure (Sushi/Pancake V4
manager deployments). The codebase already holds the ingredients of a
general answer — `degenbot-pools` `Structure`/`Identity` with its
structure-times-fork split, `ClSlotLayout`-parameterized fork storage,
the shared V3/V4 concentrated-liquidity solve dispatch, the V4 executor
opcodes (0x40-0x42) with golden-pinned shapes, and the address-keyed
registration gate. What it does not have is any force making these
agree. Eight separately maintained family enum definitions exist, each at a
different granularity with no compile-time relationship:

| Vocabulary | Home | Arms |
|---|---|---|
| `PoolFamily` | `degenbot-simulation/src/sim/evm/journal_pools.rs` | extraction (V2Pair/V3/V4PoolManager) |
| `PoolFamily` | `degenbot-bot/src/bot_core/pool_builder/builder.rs` | registration probes (V2/V3/Balancer/Curve) |
| `PoolFamily` | `degenbot-pool-updater/src/fetch.rs` | event decode (V2/AerodromeV2/V3/V4) |
| `Structure`/`Identity` | `degenbot-pools/src/pool.rs` | state model (3 structures, per-fork variants) |
| `RegisteredPoolFamily` | `degenbot-pools/src/registry.rs` | address-keyed readers (7, V4 missing) |
| `HopType` | `degenbot-solvers/src/mixed/mod.rs` | solve dispatch (7 families) |
| `PoolKind` | `degenbot-pathfinding/src/graph.rs` | discovery graph (V2/V3/V4 only) |
| `LaneFamily` | `degenbot-strategy/src/backrun_engine.rs` | backrun lanes (V2/V3 only) |

The strategy arms draw different amounts from this set: settlement
(arb_engine) solves 7 families and composes V4; the backrun arm is
V2/V3-only end to end, with V4 extraction stopping at a `v4_unsupported`
observe. In the 2026-09-22 survey, fork knowledge was additionally
duplicated as per-language constants (Rust
`V3_FAMILIES`/`v2_v3_subclass_table`/`V3_VARIANT_TABLES`, Python SQLAlchemy
subclasses, trackers, two byte-compared deployments.json copies). Adding
LFJ by hand across these surfaces was counted in the survey at ~14 Rust
regions plus 6 Python ones; adding a V4 species touches fewer but includes
a structural gap (deployments are factory-keyed, V4 managers are not) and
the backrun arm's absent V4 capability.

**Current status:** the Python pathfinding and operator surfaces now use
typed `PoolKind`. CPBCNS retired the Python SQLAlchemy ORM side, so the ORM
subclasses named above are historical survey context rather than current
duplication.

The on-chain executor contract is a hard floor no abstraction removes:
compose can only emit opcodes `cmd_executor` embeds. LFJ needs new
opcodes and shapes; the kernel's job is to make that fact explicit,
not to hide it.

## Decision

### D1 — `degenbot-pools` is the taxonomy of record

`Structure`, `Identity` (variant + DexName), `PoolEntry`, and the
concentrated-liquidity pool traits are the single definition of "what a
pool is". Every other vocabulary (`PoolKind`, `HopType`, `LaneFamily`,
journal `PoolFamily`, builder `PoolFamily`, updater `PoolFamily`,
`RegisteredPoolFamily`) becomes a **projection of the taxonomy** with a
defined mapping from `Structure`/variant, not an independent enumeration.
A projection may lag the taxonomy (a family present in the taxonomy but
unsupported by that tier belongs on that tier's capability list, D2),
but may not define a family inconsistently with it. The office term for
a projected family is one the tier admits it cannot express.

### D2 — Families are a trait stack with explicit capabilities

A family is a contract over the pipeline tiers it can serve:

- `extract`: journal/storage decode of touched state into typed posts
  (slot layout, event shapes, tick/bin data)
- `admit`: typed posts into the workspace (`PoolEntry` arm, spec-bound
  registration, verdict caching on refusal)
- `discover`: graph participation (edge payload, liquidity ranking,
  anchors)
- `compose`: executor opcode(s) + grammar shape emission

Each tier records a `FamilyCapabilities` verdict — partial support is an
explicit, observable state (continuing the `v4_unsupported` observe
pattern), never a silent no-op or a guessed decode (ADR-014's
no-guessing rule preserved). A tier that gets ahead of its contract
(e.g. extraction for V4 shipped before admission) carries the burden of
the truthful observe reason, which is exactly what the frame pipeline
already does.

### D3 — Species (forks and manager deployments) are data

A fork that differs from its family only in identifiers (table name,
factory, init codehash, manager address, chain scope, fee denominator,
storage-layout id) is a **species entry in a single manifest**, not a new
type. The manifest is single-sourced and consumed by both the Rust core
and the Python driver (DB subclass identity strings, tracker
construction, deployments). Adding a species is a manifest entry plus a
Python model/table row where the species has its own DB subclass table.
The separately-maintained constants (`V3_FAMILIES`,
`v2_v3_subclass_table`, `V3_VARIANT_TABLES`, `resolve_static_config`,
Python `_POOL_VERSION_MAP` inputs, dual deployments.json) collapse into
or derive from the manifest.

Behavior that genuinely diverges (a fork with different storage slots or
event shapes — cf. `v3_pancakeswap_*`) remains typed code, defaulted by
the manifest's layout reference so a vanilla fork ships with zero
overrides.

### D4 — The discovery graph is family-generic over species

Graph edges stay `(token0, token1, pool, kind)` at the connectivity
layer; `kind` projects from the taxonomy (D1). Binned pools are
("token-pair, count-existence") edges for connectivity and liquidity
ranking — bin granularity is an extraction/solver concern, not a graph
concern. V4 manager species key their known-poolId sets through the
connector index per manager, which today is the concrete gap for the
backrun arm (`V4PoolSet` is empty-from-nowhere, so V4 extraction
currently decodes nothing).

### D5 — Compose capabilities name their executor ceiling

A family's `compose` capability is bounded by and named after the
executor opcodes it can emit. The 2-byte V4 fee cap (`V4_FEE_ENCODER_MAX`)
is the model: the contract's encoding limits are admission-side rules,
not post-hoc blockers. LFJ's composer work is a new opcode family plus
at least one grammar shape, golden-pinned like `two_hop_seed_v4`. No
family is `compose`-capable until executor support is deployed and the
bytecode files in `contracts/` are updated to match.

### D6 — Dispatch is at tier boundaries; hot loops stay monomorphic

The kernel resolves a family once (at registration or frame admission)
and hands downstream tiers monomorphic enum/sum data. No `dyn` trait
dispatch enters the solver workspace, the walk, or the path search.
Metric vocabulary stays closed (ADR-043): family projection into labels
only through the reviewed allowlist mechanism, and only where a
combinatorial set is provably small ("families participate" not
"species participate").

### D7 — Two arms, one taxonomy, no capability-hiding

Settlement and backrun arms remain free to support different tier
subsets, but the difference is represented in the family's capability
list per arm — not discovered by which code path happens to be wired.
"Backrun supports V4" is a future state of the backrun arm's capability
list reachable without touching family definitions in other tiers.

### D8 — Declared-unsupported is loud, never silent

A family on the roadmap (LFJ binned liquidity) or a species row in the
DB whose family a tier does not admit must surface as a typed, reason-
coded observation at the tier where support stops — the same
truthfulness D2 demands of partial capability, applied to
intentionally-absent capability. Concretely: a touched address matching
a registry row (`pools`/`managed_pools` kind) outside the tier's
supported set observes with a stable "family-unsupported" reason naming
the kind, instead of falling out of the descriptor map as an unexplained
no-candidate. Adding a family to the database must produce observable
frames, not silence.

## Non-goals

- No open-world registry: the closed, reviewable species list stays
  (reputational cost of an accidental family is higher than the friction
  of editing a list).
- No Python-side trait machinery: the Python driver consumes the
  manifest and the registry; it does not grow its own family
  abstractions past what the FFI surface already provides.
- No backfill of `PoolKind`/`HopType` gaps for Curve/Balancer/Solidly
  into the backrun arm — the capability lists start truthfully at
  today's actual coverage.
- No behavior change during the retrofit (E1): V2/V3/V4 paths must stay
  bit-identical, guarded by the existing suites.

## Epic order (summary)

1. **E1 — Kernel retrofit.** Landing D1/D2 as code in `degenbot-pools`
   + projections at every existing vocabulary, V2/V3/V4 behavior
   unchanged, `just test-rust` + pytest green. Includes the
   `RegisteredPoolFamily` V4 arm (a straight bug-shape hole).
2. **E2 — V4 species.** Manifest lands; Sushi/Pancake V4 manager entries;
   backrun V4 capability (connector poolId feed — admission composing,
   composing capability rides the existing opcodes/shapes).
3. **E3 — LFJ.** First new structure through the kernel, top to bottom:
   DB, decoders, `PoolEntry` arm, solve branch, profit envelope for bin
   ladders, executor opcode + shapes, Python surface. This epic is the
   kernel's acceptance test — a new family lands and the diff is
   bounded, reviewable, and free of scattered edits.

Each epic is ergo-planned separately; E1's task bodies carry the survey's
file inventory as their working checklists.

**Run-order amendment** (2026-09-22 review): the V4 backrun wiring epic
(ergo `L77LS2`) precedes and informs E1. Wiring V4 through the existing
seams — the same way V3 is wired today — exposes exactly where seam
placement hurts, and that evidence finalizes the E1 kernel contracts
before they harden. Retrofitting the kernel first would erase the signal.
Two integration markers ride the V4 epic: (a) every new seam it cuts is
annotated as a kernel hook point (a doc comment naming the D-ruling it
becomes), and (b) the D8 loud marker lands in the same descriptor seam,
so a planned-but-unsolved family (LFJ) is observably rejected the
moment its rows appear in the DB. LFJ remains E3, planned — no
taxonomy arm until its implementation epic.

## Consequences

- The eight-vocabulary survey becomes the checklist for making each
  vocabulary a projection — measurable completion criterion, not a
  judgement call.
- New-family onboarding cost becomes linear in genuinely-new behavior
  (one module per tier where the family diverges from defaults) rather
  than coincident with framework surgery.
- Cross-language drift moves from "difficult to notice" to "manifest
  parity check", one test/CI gate instead of two files to update in
  lockstep.
- The executor contract keeps its veto: capability claims that outrun
  `cmd_executor` are structurally impossible to express (D5), keeping
  the "registry that governs" property understood during design.
- A new vocabulary can no longer be introduced without touching the
  projection map — that friction is deliberate and leans on the
  cardinality/closure discipline of ADR-043 for good hygiene.

## Open questions

- LFJ profit envelope: does the staircase bound fold into the existing
  `profit_envelope` machinery with a new piece type, or does it need a
  sibling module? (E3 design question, not blocking.)
- Manifest format and home: TOML in `degenbot-pools` (Rust parses at
  compile time, Python reads the same file), or the existing
  deployments.json extended? Leaning toward TOML beside the taxonomy,
  with deployments.json becoming a generated projection — to be settled
  in E2 design.
- Whether the backrun arm's `zfo`-lane shape admits V4 paths without a
  new lane kind (bridge to the `two_hop_v4_led` shape vocabulary is the
  existing precedent of reuse).
- Exact placement of the Python manifest consumption boundary (which
  of `_POOL_VERSION_MAP` inputs / trackers / pool models read it before
  codegen is on the table).