AdeAtlas

Seam Explorer

Legal attachment points for new work. External inputs reduce to canonical BLUE types before entering authoritative pipelines; closed surfaces stay closed. Use this to answer "where may I add a new mini-protocol / operator file type / era — without creating a second authority?"

Ingress pipelines — 4

N2N inbound wire (received blocks/headers/txs/rollbacks — the LIVE --mode node feed) — carried, unchanged in shape

Surface: N2N inbound wire (TCP + mux + handshake; ChainSync RollForward / RollBackward + BlockFetch + the tx-submission2 grammar)
Reduces to: AdmissionPeerEvent (RED, ade_runtime::admission::wire_pump) → NodeSyncItem { Block { peer, bytes } | RollBack(Point) } (RED, ade_node::node_sync; PEER-TAGGED, DC-NODE-34) → BLUE DecodedBlock (ade_codec) → BLUE BlockVerdict (ade_ledger::block_validity)
Pipeline (fixed; steps cannot be reordered):
  1. mux frame decode                          (BLUE ade_network::mux::frame — single authority)
  2. session reassembly / segmentation         (GREEN ade_network::session — one DeliverPeerFrame per complete CBOR item)
  3. tag-24 unwrap                              (BLUE ade_codec::unwrap_tag24 — the SOLE tag-24 authority; CN-WIRE-12)
  4. AdmissionPeerEvent emission                (RED wire_pump — Block / TipUpdate / RollBackward {peer, point, tip} / Disconnected; the keep-alive client emits NONE — DC-PUMP-01/03)
  5. fair per-peer merge                        (GREEN ade_node::fair_merge — deterministic round-robin; N-AO S8 / DC-PUMP-04)
  6. peer-tagged NodeSyncItem                   (RED node_sync — DC-NODE-34 threads the origin peer through)
  7. classify_receive → resolve_disposition     (GREEN-by-fn — Admit | NeedsForkChoice | RollbackFollow; DC-NODE-23/24)
  8a. (Admit)          bounded inbound fold → BLUE decode + block_validity → pump_block durable admit  (DC-MEM-07 fold fronts mempool_ingress; DC-NODE-05/12)
  8b. (NeedsForkChoice) per-peer candidate aggregation → select_best_chain → S4 prove-then-commit (N-AO; §2)
  8c. (RollbackFollow) admit_rollback (S5 admissibility) → materialize_rolled_back_state (eta0-overlaid) + commit_rollback (DC-NODE-25/26/29, T-REC-06)
Cross-surface state sharing: the per-peer wire-pump lanes share one deterministic fair-merge cursor (N-AO S8); the rollback target is bound to the durable ChainDb stored slot+hash (DC-NODE-29), never peer-supplied.

argv (closed mode set + the public ade <group> <action> subcommand sugar)

Surface: argv
Reduces to: Cli / Mode (closed: WireOnly | Admission | KeyGenKes | Produce | Node | MithrilSnapshotFetch) — ade_node::cli
Pipeline: parse → closed Mode dispatch in main() → per-mode driver
Cross-surface state sharing: none (a CLI flag set is a CLOSED allow-list, mirrored by ci_check_node_path_fidelity.sh).

operator file ingress (KES skey / opcert / Shelley genesis / seed dump / recovered-anchor sidecar / v6 seed-epoch sidecar / manifest-bound cert-state / native-Mithril V2 LedgerDB state+tables)

Surface: operator files
Reduces to: KesSecret / OperationalCert / ConwayGenesisConfig / canonical seed entries / SeedEpochConsensusInputs (v6) / RecoveredAnchorPoint / the manifest-bound cert-state / (native Mithril) BLUE CertState + Word64 UTxOState — via the single RED parsers in ade_runtime / the BLUE decoders in ade_ledger (each fail-closed)
Pipeline: read bytes → RED parser / native BLUE decoder → canonical BLUE type → bootstrap_initial_state (the single lifecycle owner; CN-NODE-01)
Cross-surface state sharing: the recovered seed-epoch eta0 sidecar is read once by bootstrap and overlaid onto BOTH the WarmStart and rollback-materialize chain_dep (T-REC-04 / T-REC-06); the v6 sidecar's security_param drives the shared sidecar_freeze_rsw helper on BOTH the recovery replay and the forward live-loop schedule (DC-EPOCH-16)

Mithril snapshot acquisition (ade mithril snapshot fetch) — a network fetch that reduces to a purely-local verified directory

Surface: ade mithril snapshot fetch --network <preview|preprod> [--certificate <hash>]
Reduces to: a local verified-snapshot directory (state / tables laid out where `ade node run --snapshot-dir` expects) + manifest.json + a compact receipt — NOT authority
Pipeline (RED ade_node::mithril_fetch; the ONLY step that talks to Mithril):
  1. resolve the committed NetworkProfile + Mithril aggregator/keys for --network  (closed 2-network registry; §3)
  2. download (or reuse) a Mithril cardano-db snapshot with --include-ancillary
  3. derive the certified point NATIVELY from the snapshot's ledger state (decode_ledgerdb_tip → slot + header hash; NO frozen cardano-node)
  4. lay out state/tables + emit manifest.json + receipt
Cross-surface state sharing: none at fetch time. `ade node run` then consumes the local directory through the UNCHANGED native composition — the network fetch grants BYTES, not truth; the certified point + the manifest binding are what the BLUE decoders verify.

Closed registries — frozen, version-gated changes only

RegistryLocationChange rule
EpochAccumulator

ade_ledger::epoch_accumulator (BLUE)

apply_selected_block is the ONE transition; the accumulator is LedgerState MINUS UTxO PLUS the two-buffer model, carrying NO UTxO map (ci_check_epoch_accumulator_no_utxo.sh). A new epoch effect = a DC-EPOCH-19/21 strengthening on apply_selected_block + a NEWEPOCH-order test; never a second boundary evaluator.
META_TABLE

ade_runtime::chaindb::epoch_accumulator_store (RED store, BLUE-derivable content)

Single-blob store + epoch-indexed leadership. New work attaches via the methods (seal_bootstrap / advance / reset_to_bootstrap / verify_ready_at / verify_advanced_through / is_complete), NOT by widening the table/key set. New marker = a DC-EPOCH-20 strengthening + ci_check_epoch_accumulator_recovery.sh.
FrozenLeadershipPoolDistr

ade_ledger::frozen_leadership (BLUE)

Outer array(6) [version, target_leadership_epoch, source_slot, source_hash, source_checkpoint_commitment, pools-map]; per-pool array(2) [active_stake, vrf_keyhash]. to_pool_distr_view reads stake+VRF DIRECTLY, never from active params. New field = a schema bump (v7) + a canonical_hash/golden bump + a DC-EPOCH-25 strengthening (ci_check_frozen_leadership_authority.sh).
RollbackPoint

ade_ledger::rollback::admission (BLUE)

admit_rollback is pure/total/fail-closed; the k-bound is a BLOCK count (cardano SecurityParam); an inadmissible target (split lineage / deeper than immutable tip−k / below the sealed anchor) is a typed error, never a silent rematerialization. New reject = a strengthening + the S5 gate.
ReducedBoundaryProjection

ade_ledger::reduced_boundary (BLUE)

A ReducedBoundaryProjection is NOT a LedgerState, cannot be widened / serialized-as-accumulator / fingerprinted as authority. A new reduced-plane arm = a strengthening + ci_check_reduced_boundary_plane.sh / ci_check_trusted_replay_boundary.sh; never widen the reduced projection into an authoritative type.
BootstrapRewardUpdate

ade_ledger::bootstrap_reward_update (BLUE)

Snapshot-bound, manifest-committed, applied exactly ONCE window-end. New field = a strengthening + ci_check_bootstrap_rupd_{fee_reduction,window_end}.sh.
SeedEpochConsensusInputs

ade_ledger::seed_consensus_inputs (BLUE)

The decode gates the schema VERSION before the outer arity — a v5 array(13) store surfaces the TYPED UnknownVersion { expected: 6, found: 5 } (re-bootstrap-to-upgrade), never a corruption-reading Structural. All fields required at construction (no Default). A new durable field = the next version + FIELDS_OUTER bump + a DC-CINPUT-06/DC-EPOCH-16 strengthening (ci_check_eview_seed_sidecar_v4.sh and successors); a pre-v6 store is a precedented typed reimport.
NetworkProfile

ade_node::bootstrap_export (RED reviewed constants)

An unknown identity FAILS CLOSED ("the registry is closed (preview|preprod)"). Carries reviewed per-network constants (magic, genesis hash, ASC, epoch length, security_param, max_lovelace_supply), never operator-supplied. Adding a network = a reviewed entry + a test, not a runtime/config extension.
MithrilProfile

ade_node::mithril_fetch (RED)

resolve_mithril_profile(network) resolves committed aggregator/keys; the certified point is derived NATIVELY (decode_ledgerdb_tip), no frozen node. New error = a strengthening; the acquisition grants bytes, not authority.
ReducedGovernanceProjection

ade_ledger Conway gov + ade_ledger::cred (BLUE)

Exactly one committee/governance interpretation per epoch; enactment atomic; the credential discriminant routed through the ONE ade_ledger::cred chokepoint. New governance effect = a boundary-authority strengthening + ci_check_{conway_deposit_params_bootstrap,gov_proposal_capture}.sh.
Mode

ade_node::cli (RED)

A CLOSED allow-list mirrored by ci_check_node_path_fidelity.sh. The public ade <group> <action> subcommand is sugar over this set, not a new mode. New mode = a reviewed variant + the path-fidelity allow-list.
WalEntry

ade_ledger::wal::event (BLUE)

The accumulator + frozen leadership persist in their OWN redb stores, NOT new WAL tags — the WAL sum is byte-stable this span. A new durable forward-step = the next free tag + canonical encode/decode + a versioned WAL change + a replay corpus. Never widen an existing variant.
EpochConsensusView

ade_ledger::{reduced_epoch_view, reduced_utxo, stake_ref, reduced_aggregate, bootstrap_manifest, reduced_snapshot} + ade_runtime::chaindb::reduced_utxo_checkpoint

The carried EVIEW/Mithril closed surfaces — the bound leadership-complete view, the reduced-checkpoint layout, the era-gated classification, the v2 manifest. New field/variant = the matching DC-EVIEW-*/DC-EPOCH-11 strengthening + gate.
LedgerDbStateError

ade_ledger / ade_runtime / ade_node::{epoch_*, native_firstrun}

Fail-closed, no best-effort. New variant = the matching DC-MITHRIL-* / DC-EPOCH-* strengthening + gate.
OutputAssetQuantity

ade_types / ade_ledger / ade_crypto / ade_runtime / ade_node / ade_network / ade_codec

The carried closed domains, unchanged in shape. Every non-Adopted/non-Admitted path fail-closed; the wire grammars real-capture-locked.

Extensible registries — open within constraints

RegistryLocationExtension rule
BranchBodySource

ade_node::fork_switch (RED)

The ONE LIVE Box<dyn …> extension point — BYTE-ONLY, never adoption authority. Impls: NullBranchBodySource (fail-closed fence) + PrefetchedBranchBodies (live BlockFetch RequestRange bytes). A new impl MUST NOT short-circuit prevalidate_branch. BlockFetch transports bytes; it does not grant truth.
DC-EVIEW-01

ade_runtime::chaindb::{utxo_anchor, utxo_key, transient_epoch_view, reduced_utxo_checkpoint, epoch_accumulator_store} (RED)

#![allow(dead_code)] on the LIVE follow/forge UTxO path; REUSED as the EVIEW transient substrate, the durable reduced checkpoint, and the durable accumulator store — each a PURE storage substitution, deliberately NOT a UtxoStore, fixed-width key never for hashing/IDs/fingerprints, one write-txn per block + reconcile-or-halt on recovery. When "B" (LIVE-LEDGER-APPLY / track_utxo=true on the live path) wires the UTxO backend it obeys the same rules. None of these durable stores is a fallback authority — each is rematerialized by replay or fails closed. Fenced by ci_check_utxo_disk_{anchor,key}.sh, ci_check_transient_view_{no_fallback,not_live,memory_ceiling}.sh, ci_check_eview_live_checkpoint.sh, ci_check_epoch_accumulator_{no_utxo,recovery}.sh. See §7.
Mempool tx admission (sorted, deduplicated)

ade_ledger::mempool (BLUE)

New txs enter at runtime via the single mempool_ingress chokepoint (behind the bounded fold within MAX_INBOUND_ADMISSION_{BYTES,COUNT}); sort/dedup invariants preserved.
--peer

ade_node::cli (RED)

New peers added at runtime via the CLI flag → N pumps → the deterministic fair_merge (N-AO S8). A peer is a transport endpoint, never an authority.
Served-chain read projection

ade_runtime::network::served_chain_projection (RED)

Bounded read-only projection of the durable ChainDb; per-request cap MAX_SERVE_RANGE_BLOCKS = 256. A fixed bound, not openly extensible.

Frozen contracts

  • Wire format / encoding: Cardano-canonical CBOR via minicbor + the ade_codec canonical primitives — field order = wire order for hash-bearing structures; wire bytes are preserved, never re-encoded for hashing (ci_check_hash_uses_wire_bytes.sh). The native Mithril tables materialization embeds inline-datum / reference-script wire bytes VERBATIM (tag-24).

  • Tag-24 envelope: 0xd8 0x18 — the SOLE ade_codec::cbor::tag24::{wrap_tag24, unwrap_tag24} authority (CN-WIRE-08/12).

  • Hash algorithms: blake2b_256 / blake2b_224 (ade_crypto::blake2b) — immutable per version; the single body-hash recipe block_body_hash. EpochConsensusView::canonical_hash, FrozenLeadershipPoolDistr::canonical_hash, the accumulator blob commitment, and the native Mithril fingerprint_utxo_v2/manifest hashes all reuse blake2b_256.

  • The credential CBOR discriminant (array(2)[tag,hash28], tag 0 = KeyHash, tag 1 = ScriptHash) — FROZEN and consolidated in the ONE ade_ledger::cred function; every native-state decoder routes through it.

  • The v1 UTxO fingerprint (fingerprint_v1) is FROZEN; the UTxO canonical fingerprint is computed over canonical keys, never storage order, never the allocator (DC-MEM-05/06/10).

  • The header VRF / KES / DSIGN verification recipes (ade_crypto): Praos VRF draft-03, the Ade-owned Sum6KES, Ed25519. VRF strength is FROZEN. The rolling Praos nonce follow (DC-EPOCH-16) evolves the chain-dep nonce but does NOT touch the verify recipe.

  • select_best_chain (the DC-CONS-03 fork-choice contract): FROZEN — byte-unchanged across the span. The single selector.

  • The #![deny(unsafe_code)] workspace invariant — preserved with ZERO local allows in ade_node/BLUE/GREEN; the SOLE unsafe is quarantined in ade_mem_diag.

  • The durable WAL grammar is APPEND-ONLY and tag-frozen: WalEntry closed sum — tags 0/1/3/4, tag 2 reserved. Byte-stable this span (the accumulator + frozen leadership use their own redb stores, not new WAL tags).

  • The closed era enum CardanoEra (Byron=0 … Conway=7); the closed PrevHash = Genesis | Block(Hash32).

  • The output asset-quantity domain OutputAssetQuantity(u64) — non-negative Word64, canonical unsigned CBOR, checked add/sub only; type-incompatible with MintBurnQuantity(i64) (DC-LEDGER-VALUE-01).

  • The NetworkProfile constants are reviewed + frozen per network (preview k=432 / preprod k=2160, genesis hashes, epoch lengths, max_lovelace_supply) — never operator-supplied.

  • All 564 canonical types: existing wire formats frozen; new types may be added (the +56 this span — the accumulator, frozen leadership, reduced boundary, bootstrap reward update, cred, rollback-admission, Conway governance — are all closed-by-construction).

Version-gated

  • The seed-epoch sidecar is version-gated by an explicit schema version — SEED_CINPUT_SCHEMA_VERSION bumped v5 → v6 (FIELDS_OUTER 13 → 14, adding security_param) by LIVE-FORGE-HARDENING S2. Decode gates the VERSION before the arity, so an older array(13) v5 store surfaces the TYPED UnknownVersion (a precedented re-bootstrap-to-upgrade, not corruption). A new durable field = the next version + FIELDS_OUTER bump + a DC-CINPUT-06/DC-EPOCH-16 strengthening. Lineage: v1 → v2 (N-F-G-N eta0) → v3 (venue geometry) → v4 (consensus-profile hashes) → v5 (seed bootstrap point) → v6 (security_param).

  • The frozen-leadership object is version-gated — FROZEN_LEADERSHIP_SCHEMA_VERSION at v6 (S4-L2 added source_checkpoint_commitment so the promoted candidate authority is fully self-contained). A new binding field = a schema bump + a canonical_hash/golden bump + a DC-EPOCH-25 strengthening; the promotion path stays frozen-only.

  • The epoch-accumulator store schema is version-gated — the leadership_schema_version marker discriminates a leadership-certified store; the accumulator blob codec stays backward-decodable so the non-authority observe-only follow still reads existing stores. A new field = a strengthening + ci_check_epoch_accumulator_recovery.sh.

  • The bootstrap manifest is version-gated by an explicit domain byte — 0xB0 (v1, 142 bytes) → 0xB1 (v2, 174 bytes, adds the bound UTxO-seed hash). A new committed field = the next domain byte + a DC-EVIEW-09 strengthening.

  • The WalEntry sum is version-gated by APPEND-ONLY tag — a new durable forward-step = the next free tag + canonical encode/decode + a versioned WAL change + a replay-equivalence corpus. Never widen an existing variant; tag 2 stays reserved.

  • The MinUtxoRule is version-gated by era; the reduced-checkpoint redb layout is version-gated (a new table/META marker = a DC-EPOCH-11 strengthening); the v1→v2 UTxO-fingerprint cutover is an Ade-INTERNAL durable-replay contract (DC-MEM-10).

  • Canonical type schema additions (new fields appended; sort/dedup + version-byte invariants preserved); new fail-closed discriminants across the span require the matching gate + a DC-* strengthening.

  • New --mode node CLI flags / subcommands: must be path-PRESERVING and added to the ci_check_node_path_fidelity.sh allow-list (the ade node run / ade mithril snapshot fetch subcommands are ergonomic route-selectors, not path-altering wire surfaces).

  • New CI checks (existing checks may be TIGHTENED, never relaxed — the span added +17 net to 255).

  • There is NO EVIEW_ACTIVATION_ARMED version-gated contract — the const was REMOVED (ECA-1, DC-EPOCH-13); the live consensus behaviour is decided by the deterministic activation PREDICATE, automatically and state-keyed, never by a const/flag/env.

Candidate & not-yet-wired seams — declared follow-ons, NOT closed

2. Data-Only vs. Authoritative Layers

For every domain where a tooling/transport layer and an authoritative layer coexist, the boundary is named. The compilation/enforcement chokepoint never moves.

Domain: self-sustaining epoch evolution — the EPOCH ACCUMULATOR (RED durable cache vs. BLUE transition authority) (LIVE-LEDGER-EPOCH-TRANSITION; DC-EPOCH-19/20/21)

Layer Module Color Role
The single ledger-transition authority (self-sustaining) ade_ledger::epoch_accumulator::{EpochAccumulator, apply_selected_block, LedgerTransitionError} BLUE apply_selected_block(prior, block_bytes, ctx) -> next | LedgerTransitionError — total, deterministic, replay-equivalent (same inputs ⇒ byte-identical EpochAccumulator). Boundary transitions come FIRST, one per crossed boundary, in cardano NEWEPOCH order. The accumulator is LedgerState MINUS the full UTxO, PLUS the two-buffer block-production model. Reproduces cardano's NEWEPOCH (POOLREAP single-canonical, DC-EPOCH-21).
Durable accumulator store (RED cache of a BLUE-derivable value) ade_runtime::chaindb::epoch_accumulator_store (redb META_TABLE "epoch_acc_meta": last_advanced_slot / seed_slot / complete / leadership_schema_version + CURRENT_LEADERSHIP_BY_EPOCH: TableDefinition<u64,&[u8]>) RED store / BLUE-derivable content A SINGLE-BLOB store (current accumulator blob + LAST_SLOT, immutable sealed bootstrap blob + SEED_SLOT). Reconstructible by folding apply_selected_block over the durable selected chain (DC-EPOCH-20 rematerialization) — a lost/corrupt store is rebuilt by replay, never authority on its own. seal_bootstrap writes the completeness marker LAST (a SIGKILL before it leaves is_complete() == false); advance writes blob + LAST_SLOT in ONE redb commit (never a torn blob/slot pair); a reorg is reset_to_bootstrap + forward replay, never an ad hoc inverse mutation. verify_advanced_through / verify_ready_at fail closed on a lagging / wrong-lineage / overshot store.
Accumulator advance (RED orchestration of the proven transform) ade_runtime::chaindb::epoch_accumulator_advance RED Sequences apply_selected_block over the durable selected chain in lockstep with the WAL AdmitBlock tail; never a parallel reimplementation.
Bootstrap reward update (the seed+2 replay input) ade_ledger::bootstrap_reward_update::BootstrapRewardUpdate BLUE The snapshot-bound, manifest-committed replay INPUT that lets a native-Mithril-bootstrapped node reproduce cardano's epoch-boundary reward distribution at the FIRST post-bootstrap replay-derived authority (seed+2) WITHOUT persisting a mutated "post-RUPD seed" (DC-EPOCH-18). Applied exactly ONCE, window-end (DC-EPOCH-23, the CE-3d fee-buffer / deltaF residual).

Rule: New self-sustaining-ledger work adds RED durable caches + advance orchestration AROUND the UNCHANGED BLUE apply_selected_block. The accumulator MUST carry only the non-UTxO facts (the large stake-bearing UTxO substrate stays in the disk-backed reduced checkpoint; ci_check_epoch_accumulator_no_utxo.sh); it MUST be rematerializable by replay (a lost store is rebuilt, never a fallback authority; ci_check_epoch_accumulator_recovery.sh); one write-txn per advance + reconcile-or-halt on recovery; the boundary transition reproduces cardano NEWEPOCH order. The transition authority never moves — no second epoch-boundary evaluator.

Domain: sealed leadership authority — FROZEN LEADERSHIP (the S4 authority flip; BLUE self-contained object) (LIVE-LEDGER-EPOCH-TRANSITION S4; DC-EPOCH-25)

Layer Module Color Role
The SOLE forward leadership authority ade_ledger::frozen_leadership::{FrozenLeadershipPoolDistr, LeadershipPoolEntry, FrozenLeadershipError} (FROZEN_LEADERSHIP_SCHEMA_VERSION = 6) BLUE Cardano's leadership PoolDistr (nesPd) captured self-contained: per-pool (active_stake, vrf_keyhash) FROZEN at a cardano SNAP boundary + (v6/S4-L2) source_checkpoint_commitment. to_pool_distr_view(asc) -> PoolDistrView reads stake + VRF DIRECTLY from it — never from active cert_state.pool.pools, the go snapshot, future_pools, or the retiring map (leadership includes zero-stake registered AND retired/POOLREAP'd pools whose VRF is absent from active state). Constructors: from_seed_epoch_consensus_inputs / from_boundary_snapshot / from_mark_pool_distr; canonical_hash + encode/decode_frozen_leadership.
Epoch-indexed frozen-leadership store ade_runtime::chaindb::epoch_accumulator_store CURRENT_LEADERSHIP_BY_EPOCH (u64 → blob) + leadership_schema_version marker RED store / BLUE content The durable, epoch-indexed, promotion-certified leadership objects, written ATOMICALLY with each accumulator advance. Promotion reads THIS by target epoch, never a live-checkpoint lookup or seed-window replay.
Rollback-admission recovery rail (S5) ade_ledger::rollback::admission::{admit_rollback, RollbackPoint, RollbackAdmissionError} BLUE Pure + total + fail-closed: before recovery rematerializes the accumulator + reduced checkpoint by reset_to_bootstrap + re-fold of a canonical prefix, the rollback target must be ADMISSIBLE (not a split lineage, not deeper than the immutable point tip−k, not below the sealed anchor). The last recovery safety rail before S4 promotes the accumulator to leadership authority. NOT fork-choice — it admits/rejects ONE target, it does not select among competing forks.

Rule: Past the bootstrap bridge (candidate >= seed+2), the promoted candidate leadership MUST be read SOLELY from a promotion-certified, epoch-indexed FrozenLeadershipPoolDistr — never a seed-window replay, a bootstrap re-materialization, a live-checkpoint shortcut, or a fabricated (zero) checkpoint commitment (ci_check_frozen_promotion_no_seed_window.sh; the retired window-replay seed+2 ceiling is GONE — every boundary past the bridge crosses through the frozen object). Warm-start recovery re-deriving the seed+2 twin is a DISTINCT S5-guarded recovery identity check (ci_check_frozen_recovery_no_seed_window.sh). Deriving leadership from go + active params is a DISPROVEN hypothesis, not an optimization target. admit_rollback fails closed on any inadmissible target — never a silent rematerialization from an inadmissible prefix.

Domain: reduced validation boundary plane — a typed NON-authority (RVBP) (REDUCED-VALIDATION-BOUNDARY-PLANE P1; I-RVB-1)

Layer Module Color Role
The SOLE authoritative boundary ade_ledger::rules::apply_epoch_boundary_with_registrations (RUPD-applied rewards, pots, mark/set/go, governance/pparam enactment) BLUE REQUIRES point-bound BoundaryBaseStake. Unchanged — the SOLE producer of authoritative epoch effects.
The reduced follower's honest non-authority ade_ledger::reduced_boundary::{ReducedBoundaryProjection, ReducedEpochProgress, ReducedBlockWindow, ReducedCertProjection (closed: Unavailable), ReducedGovernanceProjection (closed: Unavailable)} BLUE When a track_utxo=false follower reaches a Conway boundary it lacks the authoritative inputs, so it produces a ReducedBoundaryProjection: epoch/slot progression + block-window rollover ONLY. Everything authoritative is UNAVAILABLE.

Rule (I-RVB-1): The two results are DISTINCT, non-interchangeable types — a ReducedBoundaryProjection is not a LedgerState, cannot be widened into one, cannot be serialized as an accumulator snapshot, and cannot be fingerprinted as full authority (ci_check_reduced_boundary_plane.sh / ci_check_trusted_replay_boundary.sh). A reduced follower NEVER builds a reward-only stub mark (proven to leak into recovery persistence + WAL fingerprints); it emits the reduced projection and defers authoritative epoch effects to a full-authority path.

Domain: Conway governance — ratify-then-enact + deposit-expiry refund (BLUE authority; the CE-3d closures) (CONWAY-; DC-GOV-01, T-EPOCH-01, CN-EPOCH-01..04, DC-EPOCH-24)*

Layer Module Color Role
Boundary governance authority ade_ledger Conway ratify-then-enact + the boundary deposit-expiry-refund evaluator BLUE Exactly ONE authoritative committee + governance interpretation per epoch (T-EPOCH-01); effects activate only at protocol-defined epoch boundaries (CN-EPOCH-01); enactment is atomic (full effects in the SAME boundary).
Governance-deposit-expiry refund (negative proof) DC-GOV-01 evaluator BLUE Ade refunds a removed governance proposal's deposit to its return account at expiry — the −500B CE-3d governance-refund gap closure.
Snapshot pool-set inclusion (CE-3d) DC-EPOCH-24 — snapshot pool-set = cardano ssActiveStake NonZero membership BLUE The per-epoch stake snapshot pool-set matches cardano's ssActiveStake NonZero membership; POOLREAP is single-canonical (ci_check_snapshot_pool_set_inclusion.sh / ci_check_poolreap_single_canonical.sh).
Credential-discriminant chokepoint ade_ledger::cred (the ONE array(2)[tag,hash28] → KeyHash(0)/ScriptHash(1) function) BLUE EVERY native-state CBOR decoder (ledgerdb_state, snapshot::cert_state, snapshot::gov_state) maps (tag, hash28) through this ONE function so the convention cannot drift between decoders (a flipped discriminant silently mislabels ~every delegator → per-pool stake collapse → the cross-epoch leader schedule rejects valid blocks).

Rule: New governance work adds BLUE enactment logic at the boundary authority + the corresponding decode support routed through ade_ledger::cred. Enactment is atomic (no split effects); exactly one interpretation per epoch; future decisions may not leak into present validation, nor later states retroactively reinterpret prior checkpoints (CN-EPOCH-04). The reduced plane produces NO governance authority (ReducedGovernanceProjection::Unavailable).

Domain: native Mithril first-run continuity + the closed NetworkProfile registry (RED acquisition / GREEN assembly vs. BLUE decoders + authority) (MITHRIL-FIRST-RUN-CONTINUITY; native Mithril DC-MITHRIL-01..07 carried)

Layer Module Color Role
Mithril acquisition (the ONLY Mithril talker) ade_node::mithril_fetch::{MithrilProfile, resolve_mithril_profile, FetchError, run_mithril_snapshot_fetch} RED ade mithril snapshot fetch downloads a verified Mithril cardano-db snapshot, derives the certified point NATIVELY (decode_ledgerdb_tip — slot + header hash, NO frozen node), and lays out a purely-local verified directory + manifest.json. ade node run then consumes the local dir; the fetch grants BYTES, not truth.
Closed network-profile registry ade_node::bootstrap_export::{NetworkProfile, resolve_network_profile} RED (reviewed constants) resolve_network_profile(network) is a CLOSED enumeration: preview (magic 2, k=432, epoch 86400) | preprod (magic 1, k=2160, epoch 432000) | else fail-closed "the registry is closed (preview|preprod)". Carries reviewed per-network constants (genesis hash, ASC, epoch length, security_param, max_lovelace_supply), never operator-supplied; verify_live_magic / verify_epoch fail-closed before export. Adding a network = a reviewed entry here + a test.
Native decoders + single bootstrap authority (carried) ade_ledger::{ledgerdb_state, ledgerdb_tables, mithril_utxo_materialize, bootstrap_manifest} (BLUE) → ade_runtime::{mithril_native_assembly, bootstrap::bootstrap_initial_state} (GREEN pure assembly / RED persist) BLUE / GREEN / RED Unchanged — the raw V2 LedgerDB CBOR is reduced to canonical CertState + Word64 UTxOState, bound to ONE manifest point (verify_utxo_binding terminal on mismatch); the persist funnels through the single bootstrap_initial_state (no bootable partial authority on an interrupted import).

Rule: New network support = a reviewed NetworkProfile entry (closed registry) + a test; the profile constants (incl. security_param) are durable, reviewed, never operator-supplied. The Mithril fetch is the ONLY Mithril talker; ade node run consumes a purely-local verified directory through the UNCHANGED native composition. The native route FORBIDS the cardano-cli / JSON seed.

Domain: native cross-epoch stake/consensus view + AUTOMATIC activation (ECA; carried) (EPOCH-CONTINUITY-ACTIVATION; DC-EPOCH-05..17, DC-EVIEW-11)

Layer Module Color Role
Single stake/ledger authority (UNTOUCHED) ade_ledger::rules epoch boundary + apply_block_with_verdicts BLUE The EpochConsensusView is a PURE PROJECTION of it — no second stake computation.
Bound, leadership-complete next-epoch view ade_ledger::reduced_epoch_view::{EpochConsensusView, ViewBindings, consensus_profile_commitment} BLUE Carries the per-pool VRF keyhash half (DC-EVIEW-07); matches(&ViewBindings) + verify_canonical_hash is the INERT gate.
Forecast-horizon crossing (NEW) the relay loop's EraSchedule forecast horizon ⟺ durable N+1 authority promotion (DC-EPOCH-15) RED glue / BLUE detector The forecast horizon and the durable N+1 authority promotion are kept coincident (ci_check_eview_forecast_crossing.sh).
Rolling Praos chain-dep nonce (NEW, strengthened) ade_core::consensus::{nonce, praos_state, header_validate} + ade_node::node_sync (DC-EPOCH-16) BLUE transition / RED driver One indivisible BLUE nonce transition per validated followed header; the candidate freezes at firstSlotNextEpoch − ceil(4k/f); the boundary tick combines + rotates with NO reset. security_param sources the freeze window from the durable v6 sidecar (LIVE-FORGE-HARDENING S2).
Activation orchestration + predicate (AUTOMATIC, carried) ade_node::{epoch_wire, epoch_source_window, epoch_candidate, epoch_activate, epoch_activation, epoch_rebind} RED glue / GREEN-pure predicate The ONLY gate is the pure activation_predicate over canonical durable state — NO flag (DC-EPOCH-13). One-way ActiveEpochView Seed→Promoted, atomic in place (DC-EPOCH-14).
Durable activation marker ade_ledger::wal::event::WalEntry::EpochConsensusViewActivated (TAG 4) BLUE The durable proof of activation; explicit idempotence; never advances the fingerprint chain. WAL sum unchanged (tags 0/1/3/4).

Rule (carried): The EpochConsensusView stays a PURE PROJECTION; the activation candidate is reproducible from canonical DURABLE inputs ALONE (no peer/network/CLI/cache/env/wall-clock); activation is AUTOMATIC and DETERMINISTIC — the deterministic PREDICATE is the only gate; track_utxo=true stays inside the transient window.

Domain: native Mithril bootstrap decoders / value-param / MEM / fork-choice SELECT / participant follow-forge (carried verbatim)

These carried domains are unchanged in shape this span. Each: the RED tooling/transport layer parses/packs/moves bytes; the BLUE authority enforces; the chokepoint never moves.

  • Native Mithril V2 decoders → canonical authority (DC-MITHRIL-01..07): ledgerdb_state / ledgerdb_tables / mithril_utxo_materialize reduce diagnostic CBOR to BLUE CertState + Word64 UTxOState, bound to one manifest point; the v2 BootstrapManifest (0xB1, 174 bytes) binds separately-typed seed + cert-state + UTxO-seed by blake2b hash; persist funnels through bootstrap_initial_state.
  • Era-faithful value/param (DC-LEDGER-VALUE-01 / DC-LEDGER-PARAMS-01): OutputAssetQuantity(u64) vs MintBurnQuantity(i64); MinUtxoRule = LegacyAbsoluteMin(Coin) | PerByte(Coin).
  • MEM-OPT-UTXO-DISK / MEM-OPT-OPS / MEM-MEASURE: the BLUE fingerprint (fingerprint = fingerprint_v2, fingerprint_v1 FROZEN) + UtxoSetCommitment + the owned UtxoStore/UtxoMembership seam + OverlayUtxo; the DORMANT/REUSED redb backend; StaticUtxoFp/UtxoFpCache (exit-35 fail-closed); the ade_mem_diag unsafe-quarantine; the bounded inbound-admission fold + observe-only memory evidence.
  • Live multi-candidate fork-choice SELECT + adopt (N-AO): ade_core::consensus::fork_choice::select_best_chain (byte-unchanged, sole DC-CONS-03); prove-then-commit via fork_switch::prevalidate_branch; adopt via materialize_rolled_back_state / commit_rollback / pump_block.
  • Participant follow-forge + tx-submission2 + eta0 overlay: forge base = the AO-selected durable tip; mempool_ingress the single admission chokepoint; PraosChainDepState::overlay_recovered_eta0 the SOLE eta0-overlay site.

5. Module Addition Rules

How new modules (and authority surfaces) enter the workspace.

Color Naming convention Build-config flags May depend on MUST NOT depend on
BLUE crate prefixes ade_codec / ade_types / ade_crypto / ade_core / ade_ledger / ade_plutus; plus the 9 BLUE ade_network submodule paths // Core Contract: banner; #![deny(unsafe_code, clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::float_arithmetic)]; no cfg(feature) semantic gates (ci_check_no_semantic_cfg.sh) Other BLUE modules (downward only); ade_crypto::utxo_set_commitment (BLUE→BLUE) Any RED/GREEN crate; ade_runtime/ade_node/ade_core_interop/ade_mem_diag; std runtime I/O; tokio/async (ci_check_no_async_in_blue.sh); pallas_* outside ade_plutus; mimalloc (DC-MEM-06); redb / any storage backend (BLUE never holds a storage backend — the epoch accumulator, frozen leadership, reduced boundary, and native decoders live in ade_ledger; the redb accumulator/reduced/checkpoint STORES live in RED ade_runtime; ci_check_utxo_lookup_owned.sh)
GREEN ade_testkit (whole crate); GREEN-by-content sub-trees inside RED/BLUE crates carry a //! GREEN … banner + the BLUE deny attributes (e.g. the seed-consensus merge/importer pure halves; the native-Mithril assemble_native_mithril_seed + cert_state_extract; the EVIEW pure activation predicate / decide_epoch_rebind) same deny attributes; purity CI gate per sub-tree BLUE modules RED modules in non-test deps; nondeterminism (wall-clock / rand / float / HashMap — the pure pieces use BTreeMap/BTreeSet); letting an RSS / owned-footprint magnitude enter a fingerprint/verdict (OP-MEM-01/02); the transition contracts + activation predicate MUST stay PURE (replay-equivalent, re-derivable across crash/restart)
RED ade_runtime, ade_node, ade_core_interop, ade_mem_diag, ade_network::mux::transport //! RED … banner; tokio/std/I/O allowed; key custody confined to ProducerShell; the Clock seam is the SOLE wall-clock observation; rss_sampler is the SOLE /proc reader; ade_mem_diag is the SOLE crate without #![deny(unsafe_code)] Any module — (RED is the leaf) — except ade_mem_diag takes NO workspace dep and no BLUE/GREEN crate may depend on it. The redb accumulator/reduced/checkpoint stores + the epoch_* orchestration + the native-Mithril persist + mithril_fetch/bootstrap_export are RED glue; they MUST NOT supply candidate/authority contents from peer/network/CLI/cache/wall-clock (DC-EPOCH-08/20/DC-MITHRIL-03); the durable stores are rematerialized by replay, never fallback authority; track_utxo=true is confined to the transient window; the native route FORBIDS the cardano-cli / JSON seed.

The span added NO new crate — it added BLUE / GREEN-by-content / RED source to existing crates — all color-correct:

  • NEW BLUE source (ade_ledger, the +55 canonical types) — epoch_accumulator (EpochAccumulator + apply_selected_block + LedgerTransitionError), frozen_leadership (FrozenLeadershipPoolDistr + LeadershipPoolEntry + FrozenLeadershipError), reduced_boundary (ReducedBoundaryProjection + ReducedCertProjection + ReducedGovernanceProjection), bootstrap_reward_update (BootstrapRewardUpdate), cred (the credential-discriminant chokepoint), rollback::admission (admit_rollback + RollbackAdmissionError), bootstrap_bridge, the Conway gov-state decode; ade_core +1 (the rolling-nonce reshape).
  • NEW RED source — ade_runtime::chaindb::{epoch_accumulator_store, epoch_accumulator_advance} (the durable accumulator + epoch-indexed frozen leadership store + advance); ade_node::{mithril_fetch (Mithril acquisition), bootstrap_export (NetworkProfile + RawConsensusInputs export), ops_log}.
  • RED wiring / tightening (existing modules) — ade_ledger::seed_consensus_inputs bumped to v6 (security_param, version-before-arity gate); ade_runtime::consensus_inputs::{importer, json} REQUIRE security_param (fail-closed MissingField, #[serde(default)] Option<u64> at parse); ade_node::cli added Mode::MithrilSnapshotFetch + the ade <group> <action> subcommand sugar; ade_node::node_lifecycle gained the accumulator-advance + frozen-leadership promotion + warm-start sidecar_freeze_rsw wiring.

The carried substrates — the EVIEW base BLUE/RED surfaces, the native Mithril decoders, the MEM-OPT-UTXO-DISK BLUE/RED surfaces, the ade_mem_diag quarantine, the MEM-OPT-OPS/MEM-MEASURE split-color sub-tree, the PHASE4-N-AO SELECT modules — are carried verbatim.

New module checklist

  1. Add to the Cargo workspace [workspace] members (the span added NO crate — all source additions to existing modules).
  2. Apply color-specific banner + lints (BLUE: // Core Contract: + deny attributes + no-semantic-cfg; GREEN: //! GREEN + deny attributes + purity gate; RED: //! RED). The reduced-checkpoint / accumulator-store banners read "GREEN cache" but their CONTENT is BLUE-DERIVABLE and rematerialized-by-replay — reconcile the banner wording at cluster close.
  3. ci_check_dependency_boundary.sh rejects forbidden cross-color imports (incl. any BLUE dep on redb/mimalloc/ade_mem_diag; the BLUE authorities in ade_ledger are consumed by the RED ade_runtime/ade_node stores, never the reverse); ci_check_module_headers.sh enforces the banner.
  4. New canonical types: structural-grep-counted from the BLUE trees; add round-trip tests (the +56 this span are ade_ledger/ade_core BLUE types; the RED epoch_accumulator_store / mithril_fetch / bootstrap_export orchestration types are not canonical-counted).
  5. A new selector / adoption / rollback / second-ledger-transition / second-leadership / second-boundary-evaluator / seed-window-forward-promotion / candidate-from-peer-or-CLI / cardano-cli-seed-on-the-native-route / operator-supplied-security_param / open-network-registry path is forbidden — route into the existing apply_selected_block / select_best_chain / pump_block / materialize_rolled_back_state / mempool_ingress / bootstrap_initial_state / to_pool_distr_view; the leadership authority is the frozen object; the accumulator is rematerialized by replay; the reduced boundary stays a typed non-authority; security_param is durable + reviewed; the network profile is closed.

CI gates that enforce the boundary (255 total)

Cross-cutting BLUE gates: ci_check_module_headers.sh, ci_check_forbidden_patterns.sh, ci_check_dependency_boundary.sh, ci_check_no_signing_in_blue.sh, ci_check_no_semantic_cfg.sh, ci_check_hash_uses_wire_bytes.sh, ci_check_ingress_chokepoints.sh, ci_check_pallas_quarantine.sh, ci_check_no_async_in_blue.sh. Self-sustaining-ledger gates (NEW): ci_check_epoch_accumulator_no_utxo.sh, ci_check_epoch_accumulator_recovery.sh, ci_check_frozen_leadership_authority.sh, ci_check_frozen_promotion_no_seed_window.sh, ci_check_frozen_recovery_no_seed_window.sh, ci_check_reduced_boundary_plane.sh, ci_check_trusted_replay_boundary.sh. CE-3d / governance gates (NEW): ci_check_bootstrap_rupd_fee_reduction.sh, ci_check_bootstrap_rupd_window_end.sh, ci_check_snapshot_pool_set_inclusion.sh, ci_check_poolreap_single_canonical.sh, ci_check_conway_deposit_params_bootstrap.sh, ci_check_gov_proposal_capture.sh. Nonce / boundary / native-firstrun gates (NEW): ci_check_praos_nonce_follow_evolution.sh, ci_check_boundary_aligned_mark_capture.sh, ci_check_eview_forecast_crossing.sh, ci_check_native_firstrun_reduced_checkpoint.sh. Carried: the ECA / native-Mithril / value / fork-choice / MEM / storage gates (ci_check_eview_*, ci_check_mithril_*, ci_check_native_firstrun_no_cli_seed.sh, ci_check_ledgerdb_*, ci_check_tables_to_utxostate.sh, ci_check_value_quantity_domain.sh, ci_check_no_density_in_fork_choice.sh, ci_check_chain_selection_arrival_order_independent.sh, ci_check_rollback_*, ci_check_utxo_*, ci_check_mem_*, ci_check_node_path_fidelity.sh).

6. Forbidden Patterns (per color)

Universal IDD prohibitions per color (from ~/.claude/methodology/idd.md Part IV):

  • BLUE: no clock, rand, raw HashMap/HashSet, float, env access, network/filesystem, async runtime, locale-dependent ops, OS-dependent ordering.
  • GREEN: no nondeterminism; no participation in authoritative outputs.
  • RED: no direct mutation of BLUE state; no unsafe construction of semantic types; no bypassing canonical validation.

Project-specific additions (Ade)

LIVE-LEDGER-EPOCH-TRANSITION — the self-sustaining ledger (DC-EPOCH-19/20/21, DC-EPOCH-25, S5):

  • apply_selected_block is the ONE ledger-transition authority — NO second epoch-boundary evaluator; boundary transitions come FIRST, in cardano NEWEPOCH order. The epoch accumulator carries NO UTxO map (the large stake-bearing substrate stays in the disk-backed reduced checkpoint; ci_check_epoch_accumulator_no_utxo.sh).
  • The durable accumulator store is a CACHE of a BLUE-derivable value — reconstructible by folding apply_selected_block over the durable selected chain; a lagging / wrong-lineage / overshot store fails closed (verify_advanced_through / verify_ready_at) and is never read as authority — recovery rematerializes it to the WAL tail; a reorg is reset_to_bootstrap + forward replay, never an ad hoc inverse mutation (DC-EPOCH-20).
  • Past the bootstrap bridge, leadership is read SOLELY from a promotion-certified, epoch-indexed FrozenLeadershipPoolDistr — NEVER a seed-window replay, a bootstrap re-materialization, a live-checkpoint shortcut, or a fabricated (zero) checkpoint commitment (ci_check_frozen_promotion_no_seed_window.sh). Deriving leadership from go + active params is DISPROVEN. Warm-start recovery re-deriving the seed+2 twin is a DISTINCT S5-guarded recovery identity check.
  • The rollback-admission guard admit_rollback fails closed on any inadmissible target (split lineage / deeper than immutable tip−k / below the sealed anchor) — never a silent rematerialization from an inadmissible prefix; it is NOT fork-choice.

REDUCED-VALIDATION-BOUNDARY-PLANE (I-RVB-1):

  • A ReducedBoundaryProjection is a typed NON-authority — it MUST NOT be widened into a LedgerState, serialized as an accumulator snapshot, or fingerprinted as full authority; a reduced follower NEVER builds a reward-only stub mark. The authoritative boundary (apply_epoch_boundary_*) remains the SOLE producer of RUPD-applied rewards, pots, mark/set/go, and governance enactment.

LIVE-FORGE-HARDENING — security_param + the network profile (DC-EPOCH-16):

  • security_param (k) is durable replay authority, never a fabricated default — the importer fail-closes with a typed MissingField when absent, and rejects k == 0 at ingress. k threads genesis securityParam → NativeGenesisConstants → LiveConsensusInputs{Raw,Canonical} → SeedEpochConsensusInputs (v6); warm-start derives RSW = ceil(4k/f) from the DURABLE store via the single BLUE praos_rsw_slots, with the restart-CLI RSW retained ONLY as a fail-closed cross-check.
  • The v6 seed-sidecar decoder gates the schema VERSION before the outer arity — an older array(13) v5 store surfaces the TYPED UnknownVersion (re-bootstrap-to-upgrade), never a corruption-reading Structural shape error.
  • The NetworkProfile registry is CLOSED (preview|preprod) — an unknown identity FAILS CLOSED; the per-network constants (incl. security_param) are reviewed + frozen, never operator-supplied. Adding a network is a reviewed source edit + a test.

CONWAY governance (DC-GOV-01, T-EPOCH-01, CN-EPOCH-01..04):

  • Enactment is atomic (full effects in the SAME boundary); exactly one committee/governance interpretation per epoch; effects activate only at protocol-defined epoch boundaries; future decisions may not leak into present validation nor later states reinterpret prior checkpoints.
  • The credential CBOR discriminant is defined ONCE in ade_ledger::cred (array(2)[tag,hash28], KeyHash=0/ScriptHash=1); no decoder may hand-roll a divergent discriminant.

NATIVE MITHRIL BOOTSTRAP + ECA + LEDGER VALUE/PARAM + MEM + N-AO (carried):

  • The raw cardano-node V2 LedgerDB CBOR is INPUT, never authority; the native tables→UTxOState materialization embeds datum/script bytes VERBATIM (tag-24), fails closed on any unsupported tag/address/non-ascending key, binds fingerprint_utxo_v2 to the one manifest point; the native route FORBIDS the cardano-cli / JSON seed; the persist funnels through the single bootstrap_initial_state.
  • The ONLY activation gate is the deterministic PREDICATE over canonical durable state — NO EVIEW_ACTIVATION_ARMED const / flag / env; the EpochConsensusView is a PURE PROJECTION; the activation candidate comes from canonical DURABLE state ALONE; ActiveEpochView is one-way Seed→Promoted, atomic.
  • OutputAssetQuantity is the non-negative Word64 output domain (never i64-cast / wrapped / conflated with MintBurnQuantity); MinUtxoRule variants (absolute-floor vs per-byte) are DISTINCT.
  • A storage / allocator / fingerprint-version change is NEVER a consensus or replay change; the UTxO fingerprint is over canonical keys, never storage order, never the allocator; the SOLE unsafe (mimalloc) lives ONLY in ade_mem_diag; an RSS magnitude MUST NOT enter a fingerprint/verdict.
  • No second chain selector; no RED-minted candidate summary reaches select_best_chain; NEVER commit a rollback until the replacement branch is fetched/linked/validated; pump_block stays the sole roll-forward durable admit; BranchBodySource carries BYTES only; the convergence/continuity evidence vocabulary is a CLOSED enum, observe-only.