delvewright_dsl/

metrics.rs

//! The metrics standard (spec-0049 §2) — pipeline stage 0.
//!
//! One machine-readable table, engine-owned data, in two halves whose epistemic
//! status differs and is recorded per entry:
//!
//! * **Player metrics** — facts of pinned Minecraft Java 1.21.11. Not chosen,
//!   so not calibratable: walking a level cannot make a player 0.7 blocks wide.
//! * **Building metrics** — standards this project fixes. Every one carries
//!   [`BuildingEntry::calibrated`], `false` until the metrics gym's walk
//!   (spec-0049 §2.3) rules on it.
//!
//! # Why this module is in `delvewright-dsl`
//!
//! It is the crate every other one already reaches: `schem`, `grammar`, `admit`,
//! `compiler` and `render` all resolve it. A metrics module that the navigation
//! model imports but the render layer cannot would be one authority for some
//! consumers and a copy for the rest, which is the shape this table exists to
//! end. It is also the crate that owns [`crate::diagnostic`], and the stage-3
//! and stage-4 documents whose names resolve into this table are validated here.
//!
//! # One authority, structurally
//!
//! The player half is not a second table that agrees with the navigation model —
//! it **is** the navigation model's constants. `compiler::nav` imports
//! [`MAX_AUTO_STEP_16`], [`MAX_JUMP_RISE_16`] and [`FULL_16`] from here;
//! `compiler::crosshair`, `compiler::render_plan`, `compiler::view::viewer` and
//! `compiler::combat` import the body constants they used to declare. There is
//! one definition of each number in the workspace and the export re-serializes
//! it, so a player metric cannot drift from the model that proves routes.
//!
//! What that replaced is worth recording, because it is the defect this table
//! was written against rather than a hypothetical: the player eye height was
//! declared four times (`compiler::render_plan`, `compiler::view::viewer`,
//! `compiler::creator` in milli-blocks, `render::occupancy` in `f32`) and the
//! body width twice, each a literal `0.6` or `1.62` with its own doc comment
//! saying it was vanilla's. Nothing related them, so nothing could have gone red
//! had one moved.
//!
//! # Provenance is recorded per entry
//!
//! [`Provenance`] says where a number came from, and the four values are
//! deliberately not interchangeable: an [`Provenance::EngineConstant`] cannot
//! drift because there is nothing to drift from, a [`Provenance::VanillaRule`] is
//! a claim about the game this repository has **not** measured on a running
//! server, a [`Provenance::Derived`] carries its arithmetic in its note, and a
//! [`Provenance::Provisional`] is a seed for the gym and is not a standard yet.
//! Dressing the last as one of the first three is the failure this field exists
//! to make impossible to commit silently.
//!
//! # A provisional value cannot be consumed quietly
//!
//! [`BuildingEntry::value`] is the only way to read a building metric's number,
//! and it takes `&mut `[`Reads`]. So a verdict that rests on an uncalibrated
//! standard has, by construction, recorded that it did, and [`Metrics::notice`]
//! turns that ledger into `DW0813`. The obligation lives in the signature, not
//! in a line of documentation somebody has to remember.
//!
//! The residual, named rather than implied: a caller that constructs its own
//! [`Reads`], reads through it and drops it has bypassed the notice. That is a
//! deliberate act and not the omission the rule exists to catch — nothing
//! *forgets* to thread a ledger it had to construct.
//!
//! On the campaign path it is closed rather than merely narrow.
//! [`crate::validate::validate_campaign_with`] constructs **one** ledger and
//! threads it through the stage-3 and stage-4 checks together, so every building
//! metric either of them rests a verdict on lands in the ledger the notice
//! reads. There is no second ledger for a read to disappear into.

use std::collections::{BTreeMap, BTreeSet};

use serde::Serialize;

use crate::diagnostic::{Diagnostic, DwCode, ExitTier};

/// `DW0812`: a document names a metrics entry the table does not define — a
/// `size_class`, an `opening` or a `pitch` that resolves to nothing.
pub const DW_METRIC_UNKNOWN: DwCode = DwCode::new("DW0812", ExitTier::Build);

/// `DW0813`: a verdict rests on a standard the gym has not walked.
///
/// This rule asks the campaign for nothing at all. It reports a property of the
/// ENGINE's own table — that some number a check just used is a seed rather than
/// a standard — so no campaign could adopt its way out of it. It is a warning
/// (exit 0) for the same reason: a provisional number is still a number,
/// the check still refuses, and what the line adds is that the green rests on
/// something nobody has walked.
pub const DW_METRIC_PROVISIONAL: DwCode = DwCode::new("DW0813", ExitTier::Build).about_the_engine();

// ---------------------------------------------------------------------------
// The player half — the one definition of each constant in this workspace.
// ---------------------------------------------------------------------------

/// The table's own revision. Bumped whenever the exported JSON changes by a
/// single byte **from a version that has merged**, which
/// `crates/dsl/tests/metrics.rs` enforces against a committed digest: a consumer
/// that pins a version is pinning values, and values that move under a fixed
/// version are the drift the pin was bought to prevent.
///
/// The qualifier is a scope, not an escape hatch, and the difference is worth
/// the sentence: the harm exists only where something could already have pinned
/// the number, so a branch still authoring the version it introduces has nothing
/// to break. It is also not a claim anybody makes about their own change —
/// whether a version has merged is a fact of `origin/main`.
///
/// No document declares a metrics version and no surface is gated by one. What
/// it needs is that the number cannot stand still while the table moves, and
/// that is the digest test.
pub const METRICS_VERSION: u32 = 3;

/// Player collision-box width in blocks (`0.6 × 0.6 × 1.8` standing).
pub const PLAYER_WIDTH: f64 = 0.6;

/// Player collision-box height in blocks, standing.
pub const PLAYER_HEIGHT: f64 = 1.8;

/// Player collision-box height in blocks, crouched.
pub const PLAYER_CROUCHED_HEIGHT: f64 = 1.5;

/// Player eye height above the floor of the cell the body stands in.
pub const PLAYER_EYE_HEIGHT: f64 = 1.62;

/// Player maximum health, in half-heart damage points.
pub const PLAYER_MAX_HEALTH: f64 = 20.0;

/// The largest rise, in sixteenths of a block, a walker crosses **without
/// jumping** — vanilla's player `maxUpStep` is 0.6 blocks, and 9/16 = 0.5625 is
/// the largest sixteenth under it (10/16 = 0.625 already needs a jump). A rise
/// within this budget needs no headroom above the *source* cell: the player walks
/// straight up onto a slab or a path edge.
pub const MAX_AUTO_STEP_16: i64 = 9;

/// The largest rise a walker can reach **by jumping**, in sixteenths. A vanilla
/// player's jump apex is ≈1.2522 blocks, so a surface 20/16 = 1.25 up is
/// reachable and 21/16 = 1.3125 is not. This is the bound that makes the
/// **1.5-block** slab-to-full-block step-up the impossible move it is.
pub const MAX_JUMP_RISE_16: i64 = 20;

/// A full block's height in sixteenths.
pub const FULL_16: i64 = 16;

// One number, one definition: a full block is 16/16 here and in the collision
// table this feeds, and this refuses to compile the day the two drift. It is
// asserted on this side because `blockshape` must compile knowing nothing about
// the crate around it — the prefab generators are a separate workspace and reach
// it through `prefab-invariants`, which re-exports it.
const _: () = assert!(crate::blockshape::FULL_HEIGHT_16 as i64 == FULL_16);

/// What a walker has to do to gain a given rise — the engine's ONE answer, and
/// the reason it is here rather than in either walk.
///
/// Two walks ask this question of two different object classes. The compiler's
/// navigation model asks it of an assembled world, where a floor has a real
/// collision top and a body has a footprint; `delvec::schem`'s walk asks it of a
/// box of cells with a passability answer for each, which is what a grammar
/// expansion, a structure template read off disk and a reassembled zone all are.
/// The rule belongs to neither walk: it is a fact about the pinned game's body,
/// and this crate is where the three numbers it is written in terms of already
/// live — so the rule lives beside them, and both walks read one answer.
///
/// The two callers still measure the rise differently, and that is a difference
/// of **measurement**, never of rule: a box of cells with no collision heights
/// can only read a rise as whole cells, which over-states every partial-block
/// step and therefore only ever refuses. The rise is the input; this is the rule.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Rise {
    /// Inside [`MAX_AUTO_STEP_16`]: the body walks straight up, never leaves the
    /// ground, and needs no room over its head.
    Walk,
    /// Past the auto-step budget and inside [`MAX_JUMP_RISE_16`]: the body jumps,
    /// so the cell its head sweeps through must be clear or it head-bonks.
    Jump,
    /// Past the jump apex. No player makes this step.
    Beyond,
}

/// Classify a rise between two standing surfaces, in sixteenths. Negative and
/// zero rises are [`Rise::Walk`] — stepping down and walking level ask nothing
/// of the ceiling.
#[must_use]
pub fn classify_rise_16(rise_16: i64) -> Rise {
    if rise_16 <= MAX_AUTO_STEP_16 {
        Rise::Walk
    } else if rise_16 <= MAX_JUMP_RISE_16 {
        Rise::Jump
    } else {
        Rise::Beyond
    }
}

/// Can a body make this step? `head_clear` answers *is the cell the head sweeps
/// through clear at the source* — it is consulted only for a [`Rise::Jump`], so a
/// caller may compute it lazily.
///
/// This predicate is the whole of the step rule. A walk that answers "can a body
/// get from here to there" without going through it is a second opinion, and the
/// two this engine had disagreed by exactly this term: one of them omitted the
/// head sweep, so it connected a full-block rise under a two-course ceiling that
/// the other refuses, and the gate that admits a prefab proved its **positive**
/// reachability claim over the looser of the two.
#[must_use]
pub fn step_allowed(rise_16: i64, head_clear: impl FnOnce() -> bool) -> bool {
    match classify_rise_16(rise_16) {
        Rise::Walk => true,
        Rise::Jump => head_clear(),
        Rise::Beyond => false,
    }
}

/// **How far a body can jump**, per rise: for each whole-block rise from `+1`
/// down to the deepest survivable fall, the widest gap of air columns a body
/// crosses along one cardinal axis and lands, by any control it has — walking
/// or sprinting, the jump pressed on any tick — from a runway no longer than
/// its own launch cell.
///
/// Measured, not derived: `tools/spike-jump-arc/simulate.mjs` drives the
/// pinned game's movement code (prismarine-physics, the stack the harness bot
/// and the live jump spike both run) over the live spike's rig with the runway
/// as a variable, takes the minimum over runways of 1, 2, 3, 4, 6 and 10
/// cells, and its `--check` mode reproduces every landed/missed verdict of the
/// live spike (`docs/notes/jump-arc-model.md` §2, 14 of 14). The live spike's
/// narrower figures (sprint 3 flat, 2 at `+1`) are what a bot does **on cue**
/// with its jump pressed before the edge; these are what a body **can** do with
/// the jump pressed on the last supported tick, which is the question "can a
/// player get in there" asks.
///
/// Monotone: a deeper landing never admits a narrower gap.
pub const JUMP_REACH: [(i64, u32); 24] = [
    (1, 3),
    (0, 4),
    (-1, 4),
    (-2, 4),
    (-3, 5),
    (-4, 5),
    (-5, 6),
    (-6, 6),
    (-7, 6),
    (-8, 6),
    (-9, 7),
    (-10, 7),
    (-11, 7),
    (-12, 7),
    (-13, 7),
    (-14, 8),
    (-15, 8),
    (-16, 8),
    (-17, 8),
    (-18, 9),
    (-19, 9),
    (-20, 9),
    (-21, 9),
    (-22, 9),
];

/// **How high a body afloat climbs out**, in whole cells above the top water
/// cell it floats in: a ledge whose standing cell is at most this far above that
/// cell is one a swimmer pressing into it gets onto; one higher is a wall.
///
/// Measured with the same instrument as [`JUMP_REACH`]:
/// `tools/spike-jump-arc/simulate.mjs --water` floats a body in a three-deep
/// pool of source water beside a ledge and holds forward and jump, walking and
/// sprinting. A ledge standing one cell over the top water cell (its top block
/// flush with the water's) is climbed; two cells over is not. What lifts the
/// body is the water branch of the player's travel: pressed into a wall with
/// room 0.6 above, it gets a 0.3 upward impulse (`outOfLiquidImpulse` in the
/// harness's physics). It is the same relationship an `ocean` world's walk
/// plane keeps with its sea, one block above it.
pub const WATER_CLIMB_OUT_RISE: i32 = 1;

/// The widest gap [`JUMP_REACH`] admits for a rise measured in sixteenths, or
/// `None` when no jump makes it: past [`MAX_JUMP_RISE_16`] upward, or deeper than
/// [`unarmoured_survivable_fall_blocks`] downward (a body that lands there is
/// dead, and a dead body is not standing anywhere).
///
/// A rise between two table rows reads the **shallower** row — a positive
/// partial rise reads `+1`, a drop of 1.5 reads `-1` — which admits the smaller
/// gap, so a partial block can only ever narrow what this says a body reaches.
#[must_use]
pub fn jump_max_gap(rise_16: i64) -> Option<u32> {
    if rise_16 > MAX_JUMP_RISE_16 {
        return None;
    }
    if rise_16 < -(unarmoured_survivable_fall_blocks() as i64) * FULL_16 {
        return None;
    }
    // Round toward zero rise: +0.25 reads +1, -1.5 reads -1.
    let row = if rise_16 > 0 {
        1
    } else {
        -((-rise_16) / FULL_16)
    };
    JUMP_REACH.iter().find(|(r, _)| *r == row).map(|(_, g)| *g)
}

/// **Does the selector volume of the inclusive block box `lo..=hi` reach a body
/// standing anywhere in `cell`?**
///
/// Vanilla's `@a[x=lo.x,dx=hi.x-lo.x,…]` builds the AABB `[lo, hi + 1]` on each
/// axis — `EntitySelectorParser::createAabb` adds the block's own extent on the
/// positive side, which is why `dx=0` still selects a whole block column — and
/// keeps every entity whose own box **intersects** it. A standing body is
/// [`PLAYER_WIDTH`] square about its position and [`PLAYER_HEIGHT`] tall from its
/// feet, so a volume matches bodies whose FEET CELL it does not contain: half a
/// width past every horizontal face, and a course below the bottom layer where
/// only the head is inside.
///
/// This is the **generous** reading of that test — *could any body standing in
/// this cell be matched* — because every caller uses it to keep a body OUT. A
/// cell it clears is one no body standing in it can be selected from; a cell it
/// reports is one some body standing in it can. Horizontally the whole cell of
/// positions counts, since nothing makes a walking player stop at a cell centre
/// and a pathfinder routinely parks one flush against a face.
///
/// The comparison is non-strict where vanilla's `AABB.intersects` is strict, so
/// a body that exactly TOUCHES a face counts here and does not on the server.
/// That is the same hair of generosity `bodyInVolume` takes in the harness, kept
/// identical on purpose so the two sides cannot answer differently about a cell,
/// and it costs one layer: a body whose feet sit exactly on the volume's ceiling
/// is reported and is not really killed. Generous is the safe direction for a
/// rule that keeps bodies out, and being the SAME on both sides matters more
/// than the layer.
///
/// A consequence worth stating rather than leaving to be discovered: horizontally
/// the shell is one cell wide for any body narrower than two blocks, so
/// [`PLAYER_WIDTH`] does not decide it — the sweep over the cell's own positions
/// does. [`PLAYER_HEIGHT`] does decide the vertical shell.
///
/// The engine's other reader of the same vanilla rule is
/// `compiler::reach::ReachCompletion::possibly_completes_from`, which asks it of
/// one stated body position rather than of a cell of them; the harness's is
/// `bodyInVolume` in `harness/src/death-loop.ts`.
///
/// Here rather than in `delvec` for the reason [`step_allowed`] is here: the body
/// is this table's, and a second copy of the arithmetic beside it is what this
/// module exists to stop.
#[must_use]
pub fn selector_reaches_body_in_cell(lo: [i32; 3], hi: [i32; 3], cell: [i32; 3]) -> bool {
    let half = PLAYER_WIDTH / 2.0;
    // The extreme reach of a body standing anywhere in `cell`: horizontally every
    // position of the cell, each carrying half a width past itself; vertically the
    // feet on the cell floor and the head PLAYER_HEIGHT above them.
    let body_lo = [
        f64::from(cell[0]) - half,
        f64::from(cell[1]),
        f64::from(cell[2]) - half,
    ];
    let body_hi = [
        f64::from(cell[0]) + 1.0 + half,
        f64::from(cell[1]) + PLAYER_HEIGHT,
        f64::from(cell[2]) + 1.0 + half,
    ];
    (0..3).all(|i| body_lo[i] <= f64::from(hi[i]) + 1.0 && body_hi[i] >= f64::from(lo[i]))
}

/// Ticks a jumping player spends off the ground, apex to landing included.
pub const JUMP_AIRBORNE_TICKS: f64 = 12.0;

/// Player walking speed on the flat, in blocks per second (not sprinting).
pub const WALK_SPEED_BLOCKS_PER_SECOND: f64 = 4.317;

/// Player sprinting speed on the flat, in blocks per second [cited — Minecraft
/// Wiki, *Sprinting*: "around 5.612 meters/second, which is 30 percent faster
/// than the normal walking speed of around 4.317 m/s"]. The reach a `darkness`
/// grant owes the blind-reach proof is taken at this speed, because darkness,
/// unlike blindness, does not forbid the sprint (spec-0085 §6.2).
pub const SPRINT_SPEED_BLOCKS_PER_SECOND: f64 = 5.612;

/// The wiki page [`SPRINT_SPEED_BLOCKS_PER_SECOND`] is read from.
pub const SPRINT_SPEED_PAGE: &str = "Sprinting";

/// Server ticks per second.
pub const TICKS_PER_SECOND: f64 = 20.0;

/// The fastest horizontal displacement a body makes in one tick without an
/// item, in blocks: sprint-jumping with the jump held (spec-0086 §2.1).
///
/// Measured by `tools/spike-seamless-loop/` (the bot's own physics,
/// prismarine-physics at the harness pin, on the pinned server): walking
/// `0.2159`, sprinting `0.2806`, sprint-jumping `0.5878`. It is the bound a
/// loop's horizontal slab is held to — a one-tick poll catches every crossing
/// whose fastest tick is under the slab's thickness plus the body's reach.
pub const POLL_HORIZONTAL_BLOCKS_PER_TICK: f64 = 0.5878;

/// The speed a falling body approaches, in blocks per tick (spec-0086 §2.1):
/// the fixed point `k·g / (1 − k)` of the fall law `v′ = k·(v + g)` with
/// `k = 0.980`, `g = 0.080`, fitted over 87 consecutive per-tick pairs of one
/// 184-block drop.
///
/// Measured by `tools/spike-seamless-loop/` with the same physics. It is the
/// bound a loop's vertical slab is held to, the limit rather than the fastest
/// tick one fall happened to reach (`3.333`): a one-cell slab caught 9 of 10
/// drops and a three-cell slab 10 of 10.
pub const POLL_FALL_BLOCKS_PER_TICK: f64 = 3.92;

/// The fall distance in blocks below which vanilla deals no fall damage: damage
/// is `ceil(distance − 3)` points, so a 3-block fall is free and a 4-block fall
/// costs one.
pub const FALL_DAMAGE_ONSET_BLOCKS: f64 = 3.0;

/// Ticks a walking player spends crossing one block on the flat.
///
/// Derived rather than stored, because both operands are facts and nothing
/// downstream decides a route on this number — it is the pacing denominator.
#[must_use]
pub fn walk_ticks_per_block() -> f64 {
    TICKS_PER_SECOND / WALK_SPEED_BLOCKS_PER_SECOND
}

/// The largest fall an unarmoured player at full health survives, in blocks.
///
/// `ceil(d − 3) < 20` holds up to `d = 22`, which lands on one half-heart; 23
/// blocks deals 20 and kills. Derived from [`FALL_DAMAGE_ONSET_BLOCKS`] and
/// [`PLAYER_MAX_HEALTH`] so that moving either moves this, and it exists so the
/// designed-drop policy beside it has a physical ceiling to be **tighter than**
/// rather than a number chosen next to nothing.
#[must_use]
pub fn unarmoured_survivable_fall_blocks() -> f64 {
    (FALL_DAMAGE_ONSET_BLOCKS + PLAYER_MAX_HEALTH - 1.0).floor()
}

/// Horizontal cells a standing body needs to pass: `ceil(0.6)`.
#[must_use]
pub fn passable_width_cells() -> u32 {
    PLAYER_WIDTH.ceil() as u32
}

/// Vertical cells a standing body needs to pass: `ceil(1.8)`.
///
/// This is a **player** metric and the spec's building half listed it, which is
/// the correction worth naming: the width and clearance at which a body can pass
/// at all are functions of the collision box, so no walk can change them and
/// `calibrated` would mean nothing on them. What the gym calibrates is the
/// *designed* minimum — a way class's `min_width` and `min_clearance` — which is
/// a comfort judgement and can never be chosen below this floor —
/// [`Metrics::self_check`] is what holds it there, over every way class the
/// table defines rather than over the two entries that used to stand alone.
#[must_use]
pub fn passable_clearance_cells() -> u32 {
    PLAYER_HEIGHT.ceil() as u32
}

// ---------------------------------------------------------------------------
// A body has a width — the one answer to "does this body meet this volume"
// ---------------------------------------------------------------------------

/// A body's standing collision box: `width × height × width`, centred
/// horizontally on the body's position and rising from its feet.
///
/// It lives here for the reason [`step_allowed`] does. Three consumers ask the
/// same geometric question of the same object class — the routing model asks
/// which cells a walker may occupy beside a killing volume, the posted-place
/// proof asks whether a body seated at a declared cell is inside one, and the
/// emitter formats the runtime selector that decides both at play time — and a
/// question with three answers is a question three gates can disagree about.
/// The disagreement was not hypothetical: every proof reasoned in whole cells
/// while the runtime selected on hitbox intersection, so the engine routed a
/// player along a cell whose occupant the volume kills, chose that same cell as
/// the "safe" lip a stake stands on, and reported both green.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Body {
    /// Collision-box width and depth, in blocks.
    pub width: f64,
    /// Collision-box height, in blocks.
    pub height: f64,
}

impl Body {
    /// The player's own body, from the constants above rather than from a
    /// second pair of literals.
    pub const PLAYER: Body = Body {
        width: PLAYER_WIDTH,
        height: PLAYER_HEIGHT,
    };

    /// A body of the given standing hitbox.
    #[must_use]
    pub fn new(width: f64, height: f64) -> Body {
        Body { width, height }
    }

    /// Half the width — the reach of the box either side of the body's own
    /// position.
    #[must_use]
    pub fn half_width(&self) -> f64 {
        self.width / 2.0
    }
}

/// The world-space AABB vanilla builds from a box selector over the inclusive
/// cell box `lo..=hi`.
///
/// **This is a fact about the game, and it is what the emitter writes.** A box
/// selector is spelled `x=lo,dx=hi-lo,…` (`emit::box_selector_args`), and
/// vanilla's `EntitySelectorParser` turns `x`/`dx` into the half-open span
/// `[x, x+dx+1]` — which is why `dx=0` selects the whole of one block rather
/// than a plane. So the inclusive cell box `lo..=hi` is the world volume
/// `[lo, hi+1]`, and an entity is selected when its **hitbox intersects** it,
/// never when the cell it stands in is one of the box's cells.
///
/// Stated as a [`Provenance::VanillaRule`] would be: this repository has not
/// measured the parser, but it has measured the consequence — bodies whose feet
/// cell lies outside a declared volume are killed by it, at the two faces this
/// arithmetic predicts.
#[must_use]
pub fn selection_aabb(lo: [i32; 3], hi: [i32; 3]) -> ([f64; 3], [f64; 3]) {
    (
        [lo[0] as f64, lo[1] as f64, lo[2] as f64],
        [hi[0] as f64 + 1.0, hi[1] as f64 + 1.0, hi[2] as f64 + 1.0],
    )
}

/// Does a body standing with its feet at `feet` meet the volume `lo..=hi`?
///
/// `feet` is the position vanilla keeps for an entity: the horizontal centre of
/// its collision box, at the box's base. So the body occupies
/// `[x ± w/2] × [y, y + h] × [z ± w/2]`, and the answer is whether that
/// intersects [`selection_aabb`]. The comparison is strict on both sides, as
/// vanilla's `AABB::intersects` is: a body whose face exactly touches the
/// volume's face is not inside it.
///
/// This is the **exact** reading, for a body whose position is known — a summon
/// writes literal coordinates, and `compiler::nav::cell_center` is the one place
/// that says which coordinates a body seated on a cell gets. For a body that may
/// stand anywhere within a cell, ask [`cell_can_meet_volume`] instead.
#[must_use]
pub fn body_meets_volume(feet: [f64; 3], body: Body, lo: [i32; 3], hi: [i32; 3]) -> bool {
    let (vlo, vhi) = selection_aabb(lo, hi);
    let half = body.half_width();
    let blo = [feet[0] - half, feet[1], feet[2] - half];
    let bhi = [feet[0] + half, feet[1] + body.height, feet[2] + half];
    (0..3).all(|i| blo[i] < vhi[i] && bhi[i] > vlo[i])
}

/// **The inclusive cell box a body of these dimensions must keep out of** — the
/// cells from which its hitbox can reach the volume `lo..=hi`.
///
/// A walker's cell does not fix its position: a body whose feet block is `c`
/// stands anywhere in `[c, c+1)` horizontally, so its box spans
/// `[c - w/2, c + 1 + w/2)`. The cells that can meet the volume are therefore
/// the volume's own, widened by however many cells half a width reaches into —
/// one, for every body in the engine's dims table, and the derivation rather
/// than the constant is what is written here so a wider body widens it.
///
/// Vertically the body's feet sit at the cell's own floor and it rises `height`
/// blocks, so the box reaches `ceil(height)` cells down from the volume's floor
/// and not at all above its ceiling: standing **on top** of a volume is safe,
/// standing under one with your head in it is not.
///
/// The direction is deliberate and is the opposite of
/// `compiler::reach::ReachCompletion::certainly_completes_from`, which asks the
/// same geometry about a volume that GRANTS something and so demands the certain
/// case. Here the volume kills, so the refusal takes the possible case: a
/// generous rule is safe for a reward and unsound for a hazard.
#[must_use]
pub fn keep_out_box(body: Body, lo: [i32; 3], hi: [i32; 3]) -> ([i32; 3], [i32; 3]) {
    let half = body.half_width();
    let mut out_lo = [0i32; 3];
    let mut out_hi = [0i32; 3];
    for i in [0usize, 2] {
        // `c + 1 + half > lo` for some c, and `c - half < hi + 1`.
        out_lo[i] = (lo[i] as f64 - 1.0 - half).floor() as i32 + 1;
        out_hi[i] = (hi[i] as f64 + 1.0 + half).ceil() as i32 - 1;
    }
    // `c + height > lo_y` (feet at the cell floor), and `c <= hi_y` — a body
    // whose feet are at `hi_y + 1` starts exactly where the volume ends.
    out_lo[1] = (lo[1] as f64 - body.height).floor() as i32 + 1;
    out_hi[1] = hi[1];
    (out_lo, out_hi)
}

/// Can a body whose feet block is `cell` meet the volume `lo..=hi` from **some**
/// position inside that cell? The refusing reading — see [`keep_out_box`].
#[must_use]
pub fn cell_can_meet_volume(cell: [i32; 3], body: Body, lo: [i32; 3], hi: [i32; 3]) -> bool {
    let (klo, khi) = keep_out_box(body, lo, hi);
    (0..3).all(|i| klo[i] <= cell[i] && cell[i] <= khi[i])
}

// ---------------------------------------------------------------------------
// Entry shapes
// ---------------------------------------------------------------------------

/// Where a number came from. The four are not interchangeable — see the module
/// docs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum Provenance {
    /// The number **is** a constant this module defines and the rest of the
    /// workspace imports. One definition, so nothing to drift from.
    EngineConstant,
    /// A stated rule of pinned Minecraft Java 1.21.11 that no engine constant
    /// held before this table, and that this repository has **not** measured on
    /// a running server. The note names the rule so the claim is checkable.
    VanillaRule,
    /// Computed from other entries; the note carries the arithmetic.
    Derived,
    /// A seed for the metrics gym's calibration walk. Chosen, not established.
    Provisional,
}

/// A named opening in the standard seam set, in cells.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct Opening {
    /// Clear width, in cells.
    pub width: u32,
    /// Clear height, in cells.
    pub height: u32,
}

/// A named stair-pitch standard: a rise:run pattern together with the vanilla
/// blocks that realize it, and the per-step rise the realization actually
/// presents to a walking body.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct Pitch {
    /// Blocks of rise per `run` blocks of horizontal travel.
    pub rise: u32,
    /// Blocks of horizontal travel per `rise` blocks of rise.
    pub run: u32,
    /// The rise in sixteenths that one realized tread presents. A stair block
    /// offers its lower half first, so a 1:1 stair run steps 8/16 twice per
    /// block of rise rather than 16/16 once; a slab ramp steps 8/16 as well.
    /// This is the number [`Metrics::self_check`] holds under the walk-up
    /// budget, which is what makes "standard pitch" mean *walked*, not merely
    /// *legal*.
    pub step_16: i64,
    /// The vanilla realization, named so the derivation above is checkable
    /// against blocks rather than asserted.
    pub realization: &'static str,
}

/// A rung of the size-class ladder — the vocabulary a layout-graph node declares
/// and a site-plan box is judged against.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct SizeClass {
    /// Smallest interior footprint, `[x, z]` in cells, inclusive.
    pub min_footprint: [u32; 2],
    /// Largest interior footprint, `[x, z]` in cells, inclusive.
    pub max_footprint: [u32; 2],
    /// Least interior clearance, in cells.
    pub min_clearance: u32,
    /// Nominal blocks of route a body walks crossing a place of this class —
    /// the per-leg length the pacing projection sums over a critical path
    /// (spec-0049 §3.3).
    ///
    /// The code that reads it is not named here on purpose: a `DW` number in a
    /// source comment is a code as far as `tools/ci/check-dw-codes.py` is
    /// concerned, and one whose check lands two rounds from now has no catalog
    /// row to match, so naming it early reds the docs job on a rule nothing has
    /// written yet.
    pub nominal_traverse_blocks: u32,
}

/// A **way class** — the vocabulary a layout-graph node declares for a place
/// whose footprint is bounded in one axis and free in the other: a road, a
/// causeway, a corridor, a duct (spec-0053 §3).
///
/// # Why it is a second kind of classification and not a rung
///
/// The size-class ladder classifies a place by both horizontal extents at once,
/// and that is what it is for. A route has no second extent to classify: a cut
/// ledge one body wide climbing a whole seaward face is 4 by 90, and for any
/// rung to admit it that rung would have to span 4..90 on an axis — a class in
/// which an alcove and an expanse are the same thing has stopped classifying.
/// The failure is by KIND, not by margin, which is why no calibration of the
/// ladder reaches it.
///
/// # What it bounds, and what it deliberately does not
///
/// A way class bounds the **cross-section** — the axis a body feels walking it
/// — and says nothing whatever about the run. A route's length is per-campaign
/// geometry, not a standard: a village lane, a canyon rim trail, a ship's
/// gangway and a mine gallery are the same class of thing at four wildly
/// different lengths, and a `max_length` here would be this month's map wearing
/// a standard's clothes. The run is *measured*, into pacing, and is never
/// compared against anything (spec-0053 §7).
///
/// The elongation demand a way-classed box must satisfy is therefore
/// **structural rather than a constant**: the run must exceed
/// [`Self::max_width`], which is exactly what a room cannot supply. A square box
/// can never qualify, because its "run" equals its width and one number cannot
/// both be `<= max_width` and exceed it. That is what makes "declare it a way to
/// escape the ladder" refused by the object's own shape rather than by a rule
/// the author could satisfy by choosing differently.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct WayClass {
    /// Narrowest cross-section, in cells, inclusive. Never below the physical
    /// passable width — [`Metrics::self_check`] holds it there.
    pub min_width: u32,
    /// Widest cross-section, in cells, inclusive. Doubles as the elongation
    /// floor: a way-classed box's run must **exceed** this.
    pub max_width: u32,
    /// Least interior clearance, in cells.
    pub min_clearance: u32,
}

/// The kit grid: the quantum box extents are multiples of, and the datum
/// convention that fixes what a declared `y` means.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct Grid {
    /// The footprint quantum `q`, in blocks.
    pub quantum: u32,
    /// The axes extents are quantized on. Vertical extent is not quantized:
    /// storey heights are their own entries and a box's height follows them.
    pub axes: [&'static str; 2],
    /// What a box's declared datum `y` names. `floor-surface`: the walk plane is
    /// at `y`, and whatever stands in the box later puts its own floor there.
    pub datum: &'static str,
}

/// One entry's value. `untagged`, so the export reads as the number or object it
/// is rather than as a wrapper a consumer has to unpick.
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(untagged)]
pub enum MetricValue {
    /// A count of cells, blocks or ticks.
    Count(u32),
    /// A measurement that is not a whole number of anything.
    Number(f64),
    /// A yes/no fact.
    Flag(bool),
    /// A named seam opening.
    Opening(Opening),
    /// A named stair pitch.
    Pitch(Pitch),
    /// A rung of the size-class ladder.
    SizeClass(SizeClass),
    /// A way class — a route's cross-section.
    WayClass(WayClass),
    /// The kit grid.
    Grid(Grid),
}

/// One player metric: a fact of the pinned game.
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct PlayerEntry {
    /// The value.
    pub value: MetricValue,
    /// What the value counts (`blocks`, `sixteenths`, `ticks`, …), or `none`.
    pub unit: &'static str,
    /// Where the number came from.
    pub provenance: Provenance,
    /// One sentence: the constant this **is**, the vanilla rule it states, or
    /// the arithmetic it was derived by.
    pub note: &'static str,
}

/// One building metric: a standard this project fixes.
///
/// The value is deliberately not a public field. [`BuildingEntry::value`] is the
/// only way to read it and it takes `&mut `[`Reads`], so nothing can rest a
/// verdict on an uncalibrated standard without saying that it did.
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct BuildingEntry {
    /// The entry's own key, carried so a read records itself without the caller
    /// having to repeat the name it looked up under.
    key: &'static str,
    value: MetricValue,
    /// What the value counts, or `none`.
    pub unit: &'static str,
    /// Where the number came from. Orthogonal to `calibrated`: a pitch's
    /// geometry can be derived from vanilla blocks while the judgement that it
    /// is *the* standard is still unwalked.
    pub provenance: Provenance,
    /// Whether the metrics gym's walk has ruled on this value. `false` on every
    /// entry at this version.
    pub calibrated: bool,
    /// One sentence: what the number is for and what the gym is being asked to
    /// decide about it.
    pub note: &'static str,
}

impl BuildingEntry {
    /// Read the value, recording the read.
    ///
    /// The `&mut `[`Reads`] is the whole mechanism: [`Metrics::notice`] reports
    /// exactly the uncalibrated entries a run actually consumed, so `DW0813`
    /// cannot be forgotten by a check that reads one and can never fire over a
    /// standard nothing looked at.
    #[must_use]
    pub fn value(&self, reads: &mut Reads) -> &MetricValue {
        reads.record(self);
        &self.value
    }

    /// The value with no read recorded — for rendering the table, never for
    /// deciding anything.
    ///
    /// Reachable only inside this crate, and used at exactly one site: the
    /// export, which reports the table rather than resting a verdict on it. A
    /// serialization is not a verdict, and counting it as one would put every
    /// entry in every `DW0813` line and make the code mean nothing.
    pub(crate) fn value_for_display(&self) -> &MetricValue {
        &self.value
    }

    /// The entry's key.
    #[must_use]
    pub fn key(&self) -> &'static str {
        self.key
    }
}

/// The building metrics a run's verdicts have read.
///
/// Deterministic (ADR-0006): a `BTreeSet` of `&'static str`, so the order a
/// `DW0813` line names them in is the table's own order and not the order the
/// checks happened to run in.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Reads {
    read: BTreeSet<&'static str>,
    provisional: BTreeSet<&'static str>,
}

impl Reads {
    /// A ledger nothing has read through yet.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    fn record(&mut self, entry: &BuildingEntry) {
        self.read.insert(entry.key);
        if !entry.calibrated {
            self.provisional.insert(entry.key);
        }
    }

    /// How many building metrics this run's verdicts read, and how many of those
    /// the gym has not walked.
    #[must_use]
    pub fn binding(&self) -> ReadBinding {
        ReadBinding {
            read: self.read.len(),
            provisional: self.provisional.len(),
        }
    }

    /// The uncalibrated entries read, in table order.
    #[must_use]
    pub fn provisional(&self) -> Vec<&'static str> {
        self.provisional.iter().copied().collect()
    }

    /// Every entry read, in table order.
    ///
    /// The metrics gym's coverage numerator: an entry the gym's construction
    /// never read is an entry no bay was built from, so a walk of the gym cannot
    /// rule on it. Taking it from the same ledger the reads are recorded in is
    /// what stops the gym's own coverage claim being a list somebody maintains
    /// beside the generator.
    #[must_use]
    pub fn read(&self) -> BTreeSet<&'static str> {
        self.read.clone()
    }
}

/// What a run's building-metric reads bound to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct ReadBinding {
    /// Building metrics read.
    pub read: usize,
    /// Of those, entries whose `calibrated` is false.
    pub provisional: usize,
}

/// A name a document wrote that this table does not define — `DW0812`'s payload.
///
/// It carries the defined set as well as the bad name, because the author's next
/// action is choosing a real one and a refusal that only says *no* sends them to
/// read the compiler.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownMetric {
    /// The kind of entry the document was naming (`size class`, `opening`, …).
    pub kind: &'static str,
    /// The same kind, plural — carried rather than derived, because three of the
    /// six nouns end in a sibilant and `{kind}s` is wrong for them.
    pub kind_plural: &'static str,
    /// The name it wrote.
    pub named: String,
    /// Every name this table does define of that kind, in table order.
    pub defined: Vec<&'static str>,
}

impl UnknownMetric {
    /// The `DW0812` refusal, located by the caller.
    #[must_use]
    pub fn diagnostic(&self, stage: &str, path: &str) -> Diagnostic {
        let defined = if self.defined.is_empty() {
            "nothing".to_string()
        } else {
            self.defined.join(", ")
        };
        Diagnostic::error(
            DW_METRIC_UNKNOWN,
            stage,
            path,
            format!(
                "the metrics table defines no {kind} called `{named}`. The table is \
                 the single authority for this vocabulary, so a name it does not \
                 define cannot compile and no check downstream has to cope with one. \
                 Defined {plural}: {defined}. Run `delvec metrics` for the whole \
                 table, including what each entry is for.",
                kind = self.kind,
                plural = self.kind_plural,
                named = self.named,
            ),
        )
    }
}

// ---------------------------------------------------------------------------
// The table
// ---------------------------------------------------------------------------

/// The metrics standard, as exported and as read.
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct Metrics {
    /// The table's revision.
    pub metrics_version: u32,
    /// The Minecraft version the player half states facts about.
    pub mc_version: &'static str,
    /// Facts of the pinned game, in key order.
    pub player: BTreeMap<&'static str, PlayerEntry>,
    /// Standards this project fixes, in key order.
    pub building: BTreeMap<&'static str, BuildingEntry>,
}

/// Kinds of building entry a document can name, for [`Metrics::resolve`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MetricKind {
    /// A seam opening (`opening.<name>`).
    Opening,
    /// A stair pitch (`pitch.<name>`).
    Pitch,
    /// A rung of the size-class ladder (`size-class.<name>`).
    SizeClass,
    /// A way class (`way-class.<name>`) — the second kind of place
    /// classification (spec-0053 §3). A [`MetricKind`] rather than a lookup of
    /// its own for the reason [`Metrics::resolve`] gives: this is a name a
    /// DOCUMENT writes, so it goes through the one path from a name to an entry
    /// and a name the table does not define is `DW0812` here exactly as it is
    /// for a size class.
    WayClass,
    /// A storey height (`storey.<name>`).
    Storey,
    /// A pacing coefficient (`pacing.<name>`) — blocks of route per minute of
    /// play. Named like the rest of the vocabulary rather than reached by a
    /// second lookup, because [`Metrics::resolve`] is the ONE path from a name
    /// to an entry and a coefficient read any other way would be a second
    /// authority (spec-0049 §2.2). No campaign document names one; the pacing
    /// projection does.
    Pacing,
}

impl MetricKind {
    /// The key prefix entries of this kind carry.
    #[must_use]
    pub fn prefix(self) -> &'static str {
        match self {
            MetricKind::Opening => "opening.",
            MetricKind::Pitch => "pitch.",
            MetricKind::SizeClass => "size-class.",
            MetricKind::WayClass => "way-class.",
            MetricKind::Storey => "storey.",
            MetricKind::Pacing => "pacing.",
        }
    }

    /// What the kind is called in a refusal, **plural**.
    ///
    /// A fact about the kind rather than an `s` appended where a message needed
    /// one: three of the six nouns end in a sibilant, so `{noun}s` reads
    /// `size classs`, `stair pitchs` and `way classs`. Written out here, a kind
    /// added later cannot inherit that by default — it has to answer.
    #[must_use]
    pub fn plural(self) -> &'static str {
        match self {
            MetricKind::Opening => "seam openings",
            MetricKind::Pitch => "stair pitches",
            MetricKind::SizeClass => "size classes",
            MetricKind::WayClass => "way classes",
            MetricKind::Storey => "storey heights",
            MetricKind::Pacing => "pacing coefficients",
        }
    }

    /// What the kind is called in a refusal.
    #[must_use]
    pub fn noun(self) -> &'static str {
        match self {
            MetricKind::Opening => "seam opening",
            MetricKind::Pitch => "stair pitch",
            MetricKind::SizeClass => "size class",
            MetricKind::WayClass => "way class",
            MetricKind::Storey => "storey height",
            MetricKind::Pacing => "pacing coefficient",
        }
    }
}

fn player(
    value: MetricValue,
    unit: &'static str,
    provenance: Provenance,
    note: &'static str,
) -> PlayerEntry {
    PlayerEntry {
        value,
        unit,
        provenance,
        note,
    }
}

fn building(
    key: &'static str,
    value: MetricValue,
    unit: &'static str,
    provenance: Provenance,
    note: &'static str,
) -> (&'static str, BuildingEntry) {
    (
        key,
        BuildingEntry {
            key,
            value,
            unit,
            provenance,
            // Every entry lands uncalibrated. The gym walk flips it, one entry
            // at a time, and that walk is the only thing that may.
            calibrated: false,
            note,
        },
    )
}

impl Metrics {
    /// The table.
    ///
    /// Rebuilt per call rather than held in a `static`, because the values are a
    /// handful of maps and a `static` would need interior mutability the moment
    /// the gym's walk starts flipping `calibrated`. Deterministic by
    /// construction: `BTreeMap`, no clock, no environment.
    #[must_use]
    pub fn table() -> Self {
        let player_entries: Vec<(&'static str, PlayerEntry)> = vec![
            (
                "body.width",
                player(
                    MetricValue::Number(PLAYER_WIDTH),
                    "blocks",
                    Provenance::EngineConstant,
                    "The standing collision box is 0.6 wide; `dsl::metrics::PLAYER_WIDTH` \
                     is the definition `compiler::nav`'s entity dims table and \
                     `compiler::crosshair` both import.",
                ),
            ),
            (
                "body.height",
                player(
                    MetricValue::Number(PLAYER_HEIGHT),
                    "blocks",
                    Provenance::EngineConstant,
                    "The standing collision box is 1.8 tall; the same definition the \
                     entity dims table reads for `minecraft:player`.",
                ),
            ),
            (
                "body.crouched-height",
                player(
                    MetricValue::Number(PLAYER_CROUCHED_HEIGHT),
                    "blocks",
                    Provenance::VanillaRule,
                    "A sneaking player's collision box is 1.5 tall, which is what lets a \
                     body pass under a cell a standing one cannot. No engine constant \
                     held this before the table, and nothing in this workspace has \
                     measured it on a running server.",
                ),
            ),
            (
                "body.eye-height",
                player(
                    MetricValue::Number(PLAYER_EYE_HEIGHT),
                    "blocks",
                    Provenance::EngineConstant,
                    "The eye sits 1.62 above the floor of the cell the body stands in. \
                     This is the definition the render plan, the viewer page and the \
                     creator overlay all import, having each declared their own before.",
                ),
            ),
            (
                "body.max-health",
                player(
                    MetricValue::Number(PLAYER_MAX_HEALTH),
                    "half-hearts",
                    Provenance::EngineConstant,
                    "Twenty points of health, the definition `compiler::combat` imports \
                     for its winnability arithmetic.",
                ),
            ),
            (
                "step.walk-up",
                player(
                    MetricValue::Count(MAX_AUTO_STEP_16 as u32),
                    "sixteenths",
                    Provenance::EngineConstant,
                    "The largest rise a walker crosses without jumping: vanilla's player \
                     `maxUpStep` is 0.6 blocks and 9/16 is the largest sixteenth under \
                     it. `compiler::nav` imports this as its step rule's walk-up budget.",
                ),
            ),
            (
                "step.jump-rise",
                player(
                    MetricValue::Count(MAX_JUMP_RISE_16 as u32),
                    "sixteenths",
                    Provenance::EngineConstant,
                    "The largest rise a walker reaches by jumping: the apex is ≈1.2522 \
                     blocks, so 20/16 is reachable and 21/16 is not. `compiler::nav` \
                     imports this, and it is why a slab-to-full-block step-up of 1.5 is \
                     the impossible move it is.",
                ),
            ),
            (
                "step.block",
                player(
                    MetricValue::Count(FULL_16 as u32),
                    "sixteenths",
                    Provenance::EngineConstant,
                    "A full block in the sixteenths the step rule is denominated in, so \
                     that no comparison in the navigation model is a float.",
                ),
            ),
            (
                "jump.airborne",
                player(
                    MetricValue::Number(JUMP_AIRBORNE_TICKS),
                    "ticks",
                    Provenance::VanillaRule,
                    "A jump is airborne about twelve ticks, apex to landing. This was \
                     prose in the navigation model's elevation-weight derivation and \
                     nothing could read it; the table is where it becomes data.",
                ),
            ),
            (
                "walk.speed",
                player(
                    MetricValue::Number(WALK_SPEED_BLOCKS_PER_SECOND),
                    "blocks/second",
                    Provenance::VanillaRule,
                    "A walking player covers 4.317 blocks a second on the flat; \
                     sprinting is faster and is not the pacing basis, because a route \
                     nobody has learnt is walked.",
                ),
            ),
            (
                "sprint.speed",
                player(
                    MetricValue::Number(SPRINT_SPEED_BLOCKS_PER_SECOND),
                    "blocks/second",
                    Provenance::VanillaRule,
                    "A sprinting player covers 5.612 blocks a second on the flat (the \
                     wiki's Sprinting page). Not a pacing basis; it is how far a body can \
                     carry itself under a darkness grant, which leaves the sprint, in the \
                     blind-reach proof.",
                ),
            ),
            (
                "walk.ticks-per-block",
                player(
                    MetricValue::Number(walk_ticks_per_block()),
                    "ticks",
                    Provenance::Derived,
                    "Twenty ticks a second over 4.317 blocks a second. Against the \
                     twelve airborne ticks of a jump this is what makes a block of \
                     climb cost about two and a half blocks of walking, which is where \
                     the navigation model's elevation weight of two comes from.",
                ),
            ),
            (
                "fluid.passable",
                player(
                    MetricValue::Flag(false),
                    "none",
                    Provenance::VanillaRule,
                    "Water and lava are impassable to every proof in this engine and are \
                     never floor either: a body cannot stand on a fluid surface, so the \
                     two sets are disjoint and both gate standability. Marked as a rule \
                     rather than an engine constant deliberately — the navigation model \
                     encodes this as the SHAPE of its occupancy sets and not as a shared \
                     `const`, so there is no single definition for this row to be, and \
                     claiming otherwise would be the overclaim the provenance field \
                     exists to prevent.",
                ),
            ),
            (
                "fall.damage-onset",
                player(
                    MetricValue::Number(FALL_DAMAGE_ONSET_BLOCKS),
                    "blocks",
                    Provenance::VanillaRule,
                    "Fall damage is `ceil(distance − 3)` points, so a three-block fall is \
                     free and a four-block fall costs one. Stated from the vanilla \
                     damage rule; this repository has not measured it on a running \
                     server.",
                ),
            ),
            (
                "fall.unarmoured-survivable",
                player(
                    MetricValue::Number(unarmoured_survivable_fall_blocks()),
                    "blocks",
                    Provenance::Derived,
                    "`ceil(distance − 3) < 20` holds up to 22 blocks, which lands a \
                     full-health unarmoured body on one half-heart; 23 deals twenty and \
                     kills. The survivable ceiling is a function of health and armour, \
                     and this is its unarmoured, full-health case — the physical bound \
                     the designed-drop policy is deliberately tighter than.",
                ),
            ),
            (
                "passable.width",
                player(
                    MetricValue::Count(passable_width_cells()),
                    "cells",
                    Provenance::Derived,
                    "`ceil(0.6)`: one cell is the narrowest a standing body fits \
                     through. This is a fact, not a standard — no walk can change it, \
                     and it is the floor the designed corridor minimum may never be \
                     chosen below.",
                ),
            ),
            (
                "passable.clearance",
                player(
                    MetricValue::Count(passable_clearance_cells()),
                    "cells",
                    Provenance::Derived,
                    "`ceil(1.8)`: two cells is the lowest a standing body passes under. \
                     Like the width beside it this is a fact rather than a standard, \
                     which is why neither carries a calibration flag.",
                ),
            ),
        ];

        let building_entries: Vec<(&'static str, BuildingEntry)> = vec![
            building(
                "grid",
                MetricValue::Grid(Grid {
                    quantum: 4,
                    axes: ["x", "z"],
                    datum: "floor-surface",
                }),
                "blocks",
                Provenance::Provisional,
                "The footprint quantum every site-plan box's horizontal extents are \
                 multiples of, and the datum convention: a box's floor SURFACE is at \
                 its declared y, and whatever stands in the box later puts its walk \
                 plane there. Four is a seed and nothing in the existing piece library \
                 argues for it — the cave tileset is odd on every axis and the keep \
                 tileset is even but not quartered — so what the gym is being asked is \
                 whether a quantum this fine buys anything a coarser one would not.",
            ),
            building(
                "way-class.corridor",
                MetricValue::WayClass(WayClass {
                    min_width: 2,
                    max_width: 4,
                    min_clearance: 3,
                }),
                "cells",
                Provenance::Provisional,
                "The narrow way: a passage, a duct, a gallery cut through rock. Its \
                 `min_width` and `min_clearance` ARE the two numbers this table used to \
                 publish as `corridor.min-width` and `corridor.min-clearance` — one \
                 cell is passable and reads as a crawlspace, two lets two bodies pass, \
                 and two blocks of clearance puts the ceiling on the walker's head — and \
                 they are fields here rather than entries of their own so that there is \
                 one authority for the narrow way rather than a class beside two loose \
                 numbers nothing could spell. The gym walks widths one, two and three \
                 and clearances two, three and four. It is also asked a question that \
                 could not be posed while these numbers were unreachable: the kit \
                 quantum beside them is 4 and every box extent is a multiple of it, so \
                 the narrowest way any plan can currently DRAW is four cells, and the \
                 walk decides whether the floor moves up or the quantum moves down.",
            ),
            building(
                "way-class.road",
                MetricValue::WayClass(WayClass {
                    min_width: 4,
                    max_width: 16,
                    min_clearance: 6,
                }),
                "cells",
                Provenance::Provisional,
                "The broad way: a village lane, a causeway, a quay, a ledge cut across a \
                 cliff face. Wide enough that a party walks it abreast and something can \
                 come the other way, which is the difference from the corridor beside it \
                 and is what the walk is being asked to place. The clearance seed is \
                 higher than the corridor's because a way this wide reads as roofless \
                 even when it is not, and a low ceiling over a broad floor is the one \
                 combination that reads as a mistake.",
            ),
            building(
                "opening.door",
                MetricValue::Opening(Opening {
                    width: 1,
                    height: 2,
                }),
                "cells",
                Provenance::Provisional,
                "The narrow seam: one body at a time, the size of a vanilla door. Seeded \
                 at the smallest opening a standing body passes, so the gym is deciding \
                 whether the tightest legal seam is one anybody wants to walk.",
            ),
            building(
                "opening.arch",
                MetricValue::Opening(Opening {
                    width: 2,
                    height: 3,
                }),
                "cells",
                Provenance::Provisional,
                "The ordinary seam between two interior places: two abreast, headroom \
                 over both.",
            ),
            building(
                "opening.passage",
                MetricValue::Opening(Opening {
                    width: 3,
                    height: 3,
                }),
                "cells",
                Provenance::Derived,
                "The three-by-three doorway the existing jigsaw socket conventions \
                 already standardize on — `cave:socket` and `tk:socket` are both this \
                 opening, so the prefab library has been built against it for as long \
                 as it has existed. Derived from that convention rather than chosen \
                 here, and still uncalibrated: what the gym decides is whether the \
                 convention is right, not what it is.",
            ),
            building(
                "opening.gateway",
                MetricValue::Opening(Opening {
                    width: 5,
                    height: 5,
                }),
                "cells",
                Provenance::Provisional,
                "The broad seam a thing of scenery scale passes: a cart, a barge, a \
                 processional. Seeded wide enough to read as an event from inside the \
                 place it opens onto, which is the judgement the walk is for.",
            ),
            building(
                "pitch.stair",
                MetricValue::Pitch(Pitch {
                    rise: 1,
                    run: 1,
                    step_16: 8,
                    realization: "minecraft:*_stairs",
                }),
                "none",
                Provenance::Derived,
                "One block of rise per block of run, realized in stair blocks. The \
                 geometry is vanilla's: a stair offers its lower half first, so the \
                 body walks two eight-sixteenth steps per block of rise and never \
                 jumps. What is uncalibrated is the comfort judgement — whether a climb \
                 this steep is one a player wants to make repeatedly.",
            ),
            building(
                "pitch.ramp",
                MetricValue::Pitch(Pitch {
                    rise: 1,
                    run: 2,
                    step_16: 8,
                    realization: "minecraft:*_slab + full block",
                }),
                "none",
                Provenance::Derived,
                "One block of rise per two of run, realized as a bottom slab then a full \
                 block. Same eight-sixteenth tread as the stair and half the pitch, so \
                 it is the gentle standard; the run it costs is what the gym weighs it \
                 on.",
            ),
            building(
                "storey.low",
                MetricValue::Count(5),
                "blocks",
                Provenance::Derived,
                "Floor course, three cells of interior clearance, ceiling course. Taken \
                 from the existing cave tileset, every passage and room of which is five \
                 blocks tall, so this is the storey the shipped library already has \
                 rather than a number invented here.",
            ),
            building(
                "storey.standard",
                MetricValue::Count(8),
                "blocks",
                Provenance::Provisional,
                "The storey an interior room of consequence gets: six cells of clearance \
                 between courses. A seed, and the walk is what says whether a room this \
                 tall reads as generous or merely as far away.",
            ),
            building(
                "storey.hall",
                MetricValue::Count(14),
                "blocks",
                Provenance::Provisional,
                "The storey a hall gets, where the height itself is the effect. The seed \
                 is deliberately at the point where volume starts costing walking time \
                 for nothing, because that is the trade the walk has to judge.",
            ),
            building(
                "size-class.alcove",
                MetricValue::SizeClass(SizeClass {
                    min_footprint: [4, 4],
                    max_footprint: [8, 8],
                    min_clearance: 3,
                    nominal_traverse_blocks: 6,
                }),
                "cells",
                Provenance::Provisional,
                "A place a body stands in rather than crosses: a shrine, a landing, a \
                 cell. The smallest rung of the ladder, and the whole ladder's bounds \
                 are seeds — what the walk fixes is where one class stops feeling like \
                 the next.",
            ),
            building(
                "size-class.room",
                MetricValue::SizeClass(SizeClass {
                    min_footprint: [8, 8],
                    max_footprint: [16, 16],
                    min_clearance: 4,
                    nominal_traverse_blocks: 12,
                }),
                "cells",
                Provenance::Provisional,
                "A place with a purpose and something in it: a guardroom, a chapel, a \
                 workshop.",
            ),
            building(
                "size-class.hall",
                MetricValue::SizeClass(SizeClass {
                    min_footprint: [16, 16],
                    max_footprint: [32, 32],
                    min_clearance: 8,
                    nominal_traverse_blocks: 24,
                }),
                "cells",
                Provenance::Provisional,
                "A place a fight or a crowd fits in, and the smallest rung whose height \
                 is doing work of its own.",
            ),
            building(
                "size-class.arena",
                MetricValue::SizeClass(SizeClass {
                    min_footprint: [32, 32],
                    max_footprint: [64, 64],
                    min_clearance: 12,
                    nominal_traverse_blocks: 48,
                }),
                "cells",
                Provenance::Provisional,
                "A place built around one encounter, with room to retreat and re-approach.",
            ),
            building(
                "size-class.expanse",
                MetricValue::SizeClass(SizeClass {
                    min_footprint: [64, 64],
                    max_footprint: [128, 128],
                    min_clearance: 16,
                    nominal_traverse_blocks: 96,
                }),
                "cells",
                Provenance::Provisional,
                "A shore, a valley floor, a cavern — a place whose job is that crossing \
                 it takes time. The rung most at risk of being a big empty room, which \
                 is what the walk is watching for.",
            ),
            building(
                "drop.max-designed-rise",
                MetricValue::Count(5),
                "blocks",
                Provenance::Provisional,
                "The deepest fall a designed one-way drop edge may declare. A policy \
                 cap, not a physical one: the unarmoured survivable fall beside it in \
                 the player half is 22 blocks, and this is far tighter on purpose, \
                 because a drop is a topology decision and should not also be a health \
                 decision. Five costs two of twenty at full health, which is the seed \
                 the walk argues with.",
            ),
            building(
                "pacing.route-blocks-per-minute",
                MetricValue::Count(60),
                "blocks/minute",
                Provenance::Provisional,
                "Blocks of route a party gets through per minute of play, once looking, \
                 fighting and backtracking are in it. Carried with NO THRESHOLD \
                 anywhere until the first walked blockout and the first full playtest \
                 calibrate it: a threshold on a number this uncertain would be defending \
                 nothing. Its upper bound is the pure-walk figure beside it, which no \
                 party achieves.",
            ),
            building(
                "pacing.walk-only-blocks-per-minute",
                MetricValue::Count((WALK_SPEED_BLOCKS_PER_SECOND * 60.0) as u32),
                "blocks/minute",
                Provenance::Derived,
                "Walking speed times sixty: what a body covers doing nothing but \
                 walking in a straight line. It exists so the route coefficient above \
                 has a ceiling that is a fact rather than another guess, and so the \
                 ratio between them is the thing the playtest actually measures.",
            ),
        ];

        Metrics {
            metrics_version: METRICS_VERSION,
            mc_version: crate::blocks::MC_VERSION,
            player: player_entries.into_iter().collect(),
            building: building_entries.into_iter().collect(),
        }
    }

    /// Resolve a name a **document** wrote to its building entry.
    ///
    /// This is the **only** path from an authored name to an entry, and it is
    /// what makes the table the single authority rather than a suggestion: a
    /// name it does not define cannot be resolved, so it cannot compile, so no
    /// check downstream ever meets one.
    ///
    /// The other half of that guarantee is that no key string is spelled outside
    /// this module. The entries no document names — the kit grid, the designed-
    /// drop cap — are reached through the accessors below rather than by looking
    /// the key up in [`Metrics::building`], which is public so that a *reporter*
    /// can walk the whole table (`delvec metrics` counts it; the tests iterate
    /// it). Reporting is not resolution: a caller that walks every entry cannot
    /// name a wrong one, and a caller that wants ONE entry has an accessor and
    /// therefore no reason to type a key.
    ///
    /// # Errors
    ///
    /// [`UnknownMetric`], which the caller turns into `DW0812` with its own
    /// stage and path.
    pub fn resolve(&self, kind: MetricKind, named: &str) -> Result<&BuildingEntry, UnknownMetric> {
        let key = format!("{}{}", kind.prefix(), named);
        self.building
            .get(key.as_str())
            .ok_or_else(|| UnknownMetric {
                kind: kind.noun(),
                kind_plural: kind.plural(),
                named: named.to_string(),
                defined: self.names_of(kind),
            })
    }

    /// The kit grid — the quantum a site-plan box's footprint is a multiple of,
    /// and the datum convention that fixes what a declared floor `y` means.
    ///
    /// One of the entries **no document names**: an author writes a number, not
    /// the word `grid`, so it has no place in [`Metrics::resolve`]'s naming
    /// vocabulary and would need a [`MetricKind`] whose prefix is the empty
    /// string — which would make `names_of` return the whole table. An accessor
    /// instead, so the key string still lives here and nowhere else.
    ///
    /// `None` only if the table stopped defining it, which
    /// [`Metrics::self_check`] reports as an internal error.
    #[must_use]
    pub fn grid(&self, reads: &mut Reads) -> Option<Grid> {
        match self.building.get("grid")?.value(reads) {
            MetricValue::Grid(g) => Some(*g),
            _ => None,
        }
    }

    /// The deepest fall a **designed** one-way drop may declare, in blocks — a
    /// policy cap, deliberately tighter than the survivability fact in the
    /// player half. See [`Metrics::grid`] for why this is an accessor.
    #[must_use]
    pub fn max_designed_drop_blocks(&self, reads: &mut Reads) -> Option<u32> {
        match self.building.get("drop.max-designed-rise")?.value(reads) {
            MetricValue::Count(n) => Some(*n),
            _ => None,
        }
    }

    /// The **widest** standard opening in the table, in cells — the floor a
    /// contact seam's span must exceed (spec-0053 §4).
    ///
    /// Derived from the table rather than seeded, and that is the whole of why
    /// the floor is honest: anything at or under this width **could have been a
    /// portal**, so a doorway declared a contact to dodge the standard set is
    /// refused by its own width. A seeded floor would be a number an author
    /// could argue with; this one is a consequence of the standard set, and it
    /// moves when the standard set moves.
    ///
    /// It walks every opening rather than naming one, so a broader standard
    /// landing tomorrow raises the floor with no edit here — the failure mode a
    /// hand-named `opening.gateway` would have is that the floor silently stops
    /// being the broadest the day a broader one is added.
    ///
    /// `None` only if the table defines no opening at all, which
    /// [`Metrics::self_check`] reports as an internal error.
    #[must_use]
    pub fn broadest_opening_width(&self, reads: &mut Reads) -> Option<u32> {
        let mut widest: Option<u32> = None;
        for name in self.names_of(MetricKind::Opening) {
            let Ok(entry) = self.resolve(MetricKind::Opening, name) else {
                continue;
            };
            if let MetricValue::Opening(o) = entry.value(reads) {
                widest = Some(widest.map_or(o.width, |w: u32| w.max(o.width)));
            }
        }
        widest
    }

    /// Every name defined for a kind, in table order.
    #[must_use]
    pub fn names_of(&self, kind: MetricKind) -> Vec<&'static str> {
        self.building
            .keys()
            .filter_map(|k| k.strip_prefix(kind.prefix()))
            .collect()
    }

    /// The `DW0813` notice for a run, or `None` when no verdict rested on an
    /// unwalked standard.
    ///
    /// `None` at a zero binding is the calibrated end state and not a vacuity:
    /// the line's job is to say that a green rests on a seed, and once the gym
    /// has walked every entry a run reads there is nothing left for it to say.
    /// The distinguishable failure — a run that read NOTHING — is reported by
    /// [`Reads::binding`], which every caller states whether or not this returns
    /// a line.
    #[must_use]
    pub fn notice(&self, reads: &Reads, stage: &str) -> Option<Diagnostic> {
        let provisional = reads.provisional();
        if provisional.is_empty() {
            return None;
        }
        let binding = reads.binding();
        Some(Diagnostic::warning(
            DW_METRIC_PROVISIONAL,
            stage,
            "",
            format!(
                "{n} of the {read} building metric(s) this run read are provisional — the \
                 metrics gym has not walked them: {names}. The checks still ran and still \
                 refuse; what is unproven is the number they refused against.",
                n = binding.provisional,
                read = binding.read,
                names = provisional.join(", "),
            ),
        ))
    }

    /// Check the table against itself and against the player half.
    ///
    /// These are verdicts, and they read building metrics through a [`Reads`], so
    /// they are also what gives `DW0813` a live binding at this version: `delvec
    /// metrics` runs them, and the notice names the seeds the consistency verdict
    /// rested on. They are the reason the mechanism is demonstrable now rather
    /// than at the round that adds the documents.
    ///
    /// A violation is an **internal error**, not a diagnostic: the table is
    /// engine data, so an inconsistent one is a defect in this file and not in
    /// anybody's campaign, and there is no author to address a refusal to.
    #[must_use]
    pub fn self_check(&self) -> SelfCheck {
        let mut reads = Reads::new();
        let mut failures: Vec<String> = Vec::new();
        let mut checked = 0usize;

        let floor_w = u64::from(passable_width_cells());
        let floor_h = u64::from(passable_clearance_cells());

        // A place that is a route must be spellable at all. Zero way classes is
        // the state spec-0053 was written to end — the metrics gym reported
        // `corridor.min-width` and `corridor.min-clearance` unreachable because
        // no document could name a place that is not a box with a size class —
        // so an empty way vocabulary is an internal error rather than a table
        // that happens to be short one kind.
        checked += 1;
        if self.names_of(MetricKind::WayClass).is_empty() {
            failures.push(
                "the table defines no way class, so no document can state a place that is \
                 a route"
                    .to_string(),
            );
        }

        // The contact floor is derived from the standard opening set (spec-0053
        // §4), so an empty set would make that floor `None` and the refusal it
        // is the floor for unable to separate a doorway from a front.
        checked += 1;
        if self.broadest_opening_width(&mut reads).is_none() {
            failures.push(
                "the table defines no standard opening, so a contact seam's width floor — \
                 the width a front must exceed to be a front rather than a door — cannot \
                 be derived"
                    .to_string(),
            );
        }

        let quantum = match self.grid(&mut reads) {
            Some(g) => {
                checked += 1;
                if g.quantum == 0 {
                    failures.push("the kit grid's quantum is zero".to_string());
                }
                g.quantum
            }
            None => {
                failures.push("the table defines no kit `grid`".to_string());
                1
            }
        };

        for (key, entry) in &self.building {
            match entry.value(&mut reads) {
                MetricValue::Opening(o) => {
                    checked += 1;
                    if u64::from(o.width) < floor_w || u64::from(o.height) < floor_h {
                        failures.push(format!(
                            "`{key}` is {}×{}, which no standing body passes ({floor_w}×{floor_h} \
                             is the floor)",
                            o.width, o.height
                        ));
                    }
                }
                MetricValue::Pitch(p) => {
                    checked += 1;
                    if p.step_16 > MAX_AUTO_STEP_16 {
                        failures.push(format!(
                            "`{key}` presents a tread of {}/16, over the {MAX_AUTO_STEP_16}/16 \
                             walk-up budget, so it is climbed by jumping and is not a standard \
                             pitch",
                            p.step_16
                        ));
                    }
                    if p.rise == 0 || p.run == 0 {
                        failures.push(format!("`{key}` has a zero rise or run"));
                    }
                }
                MetricValue::SizeClass(c) => {
                    checked += 1;
                    for (axis, lo, hi) in [
                        ("x", c.min_footprint[0], c.max_footprint[0]),
                        ("z", c.min_footprint[1], c.max_footprint[1]),
                    ] {
                        if lo > hi {
                            failures
                                .push(format!("`{key}` has a {axis} minimum above its maximum"));
                        }
                        if lo % quantum != 0 || hi % quantum != 0 {
                            failures.push(format!(
                                "`{key}` bounds its {axis} footprint at {lo}..{hi}, which is not \
                                 on the kit grid's quantum of {quantum}"
                            ));
                        }
                    }
                    if u64::from(c.min_clearance) < floor_h {
                        failures.push(format!(
                            "`{key}` allows a clearance of {}, under the passable floor of \
                             {floor_h}",
                            c.min_clearance
                        ));
                    }
                    if c.nominal_traverse_blocks == 0 {
                        failures.push(format!("`{key}` has a nominal traverse of zero"));
                    }
                }
                MetricValue::WayClass(w) => {
                    checked += 1;
                    // The two floors the freestanding `corridor.min-*` entries
                    // used to be checked at, re-asserted here against every way
                    // class rather than against the one that inherited them: a
                    // designed minimum is a comfort judgement and a standard
                    // under the physical passable size would be a standard
                    // nothing can use, which is true of a road exactly as it is
                    // of a corridor.
                    if u64::from(w.min_width) < floor_w {
                        failures.push(format!(
                            "`{key}` allows a width of {}, under the `passable.width` floor of \
                             {floor_w}",
                            w.min_width
                        ));
                    }
                    if u64::from(w.min_clearance) < floor_h {
                        failures.push(format!(
                            "`{key}` allows a clearance of {}, under the `passable.clearance` \
                             floor of {floor_h}",
                            w.min_clearance
                        ));
                    }
                    if w.min_width > w.max_width {
                        failures.push(format!(
                            "`{key}` bounds its width at {}..{}, a minimum above its maximum",
                            w.min_width, w.max_width
                        ));
                    }
                    // `max_width` is the elongation floor as well as the widest
                    // cross-section, and a box's horizontal extents are
                    // multiples of the kit quantum (`DW0825`). A `max_width` off
                    // the quantum is therefore a bound no plan can draw a way
                    // AT, which makes the widest member of the class
                    // uninstantiable and the gym unable to rule on it. The
                    // narrow bound is deliberately NOT held to the quantum: the
                    // corridor's inherited floor of 2 sits under a quantum of 4
                    // and which of those two provisional numbers moves is the
                    // walk's to decide, not this file's.
                    if !w.max_width.is_multiple_of(quantum) {
                        failures.push(format!(
                            "`{key}` bounds its width at {}, which is not on the kit grid's \
                             quantum of {quantum}, so no box can be drawn at the widest member \
                             of the class",
                            w.max_width
                        ));
                    }
                }
                _ => {}
            }
        }

        for (key, floor) in [
            ("storey.low", floor_h + 2),
            ("storey.standard", floor_h + 2),
            ("storey.hall", floor_h + 2),
        ] {
            let Some(entry) = self.building.get(key) else {
                failures.push(format!("the table defines no `{key}`"));
                continue;
            };
            checked += 1;
            if let MetricValue::Count(n) = entry.value(&mut reads)
                && u64::from(*n) < floor
            {
                failures.push(format!(
                    "`{key}` is {n} blocks, which leaves no passable interior between a \
                     floor course and a ceiling course ({floor} is the floor)"
                ));
            }
        }

        // The policy cap is deliberately tighter than the physical one. A cap
        // that reached the survivability ceiling would not be a policy.
        if let Some(n) = self.max_designed_drop_blocks(&mut reads) {
            checked += 1;
            let physical = unarmoured_survivable_fall_blocks();
            if f64::from(n) >= physical {
                failures.push(format!(
                    "`drop.max-designed-rise` is {n} blocks, at or past the unarmoured \
                     survivable fall of {physical}, so it is not a policy cap at all"
                ));
            }
        }

        // A party cannot out-pace a body walking in a straight line.
        if let (Some(route), Some(walk)) = (
            self.building.get("pacing.route-blocks-per-minute"),
            self.building.get("pacing.walk-only-blocks-per-minute"),
        ) {
            checked += 1;
            if let (MetricValue::Count(r), MetricValue::Count(w)) =
                (route.value(&mut reads), walk.value(&mut reads))
                && r > w
            {
                failures.push(format!(
                    "`pacing.route-blocks-per-minute` is {r}, over the pure-walk ceiling of {w}"
                ));
            }
        }

        SelfCheck {
            binding: SelfCheckBinding {
                invariants: checked,
                entries: self.building.len(),
                reads: reads.binding(),
            },
            reads,
            failures,
        }
    }
}

/// What [`Metrics::self_check`] examined and what it found.
#[derive(Debug, Clone, PartialEq)]
pub struct SelfCheck {
    /// The ledger the verdicts read through, for [`Metrics::notice`].
    pub reads: Reads,
    /// What the run bound to. Stated whether or not anything failed, because a
    /// check that examined nothing is a finding and not a pass.
    pub binding: SelfCheckBinding,
    /// Inconsistencies, each a whole sentence. Non-empty is an internal error.
    pub failures: Vec<String>,
}

/// [`Metrics::self_check`]'s binding count.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct SelfCheckBinding {
    /// Invariants evaluated.
    pub invariants: usize,
    /// Building entries in the table.
    pub entries: usize,
    /// What those invariants read.
    pub reads: ReadBinding,
}

/// The table rendered for export: every entry with its value, unit, provenance
/// and note, plus the halves' own counts.
///
/// Separate from [`Metrics`]'s own `Serialize` because the building half's value
/// is private — an export is the one consumer that reads a number without
/// resting a verdict on it.
#[must_use]
pub fn export(metrics: &Metrics) -> serde_json::Value {
    let mut player = serde_json::Map::new();
    for (k, e) in &metrics.player {
        player.insert((*k).to_string(), serde_json::json!(e));
    }
    let mut building = serde_json::Map::new();
    let mut uncalibrated = 0usize;
    for (k, e) in &metrics.building {
        if !e.calibrated {
            uncalibrated += 1;
        }
        building.insert(
            (*k).to_string(),
            serde_json::json!({
                "value": e.value_for_display(),
                "unit": e.unit,
                "provenance": e.provenance,
                "calibrated": e.calibrated,
                "note": e.note,
            }),
        );
    }
    serde_json::json!({
        "metrics_version": metrics.metrics_version,
        "mc_version": metrics.mc_version,
        "counts": {
            "player": metrics.player.len(),
            "building": metrics.building.len(),
            "uncalibrated": uncalibrated,
        },
        "player": player,
        "building": building,
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_table_is_consistent_with_itself_and_with_the_player_half() {
        let m = Metrics::table();
        let check = m.self_check();
        assert!(
            check.failures.is_empty(),
            "the shipped metrics table is inconsistent: {:?}",
            check.failures
        );
        assert!(
            check.binding.invariants > 0,
            "a self-check that evaluated nothing is vacuous, not a pass"
        );
    }

    #[test]
    fn every_building_entry_lands_uncalibrated() {
        let m = Metrics::table();
        assert!(!m.building.is_empty(), "the building half is empty");
        for (k, e) in &m.building {
            assert!(
                !e.calibrated,
                "`{k}` claims to be calibrated, but the metrics gym has not been walked"
            );
        }
    }

    #[test]
    fn a_verdict_that_reads_a_seed_raises_dw0813_naming_it() {
        let m = Metrics::table();
        let check = m.self_check();
        assert!(
            check.binding.reads.provisional > 0,
            "the self-check read no provisional entry, so DW0813 binds to nothing"
        );
        let d = m
            .notice(&check.reads, "metrics")
            .expect("a run that read a seed owes the notice");
        assert_eq!(d.code, "DW0813");
        assert_eq!(d.severity, crate::diagnostic::Severity::Warning);
        for name in check.reads.provisional() {
            assert!(
                d.message.contains(name),
                "the notice must name `{name}`, the seed a verdict rested on"
            );
        }
    }

    #[test]
    fn a_run_that_read_nothing_provisional_gets_no_notice() {
        let m = Metrics::table();
        let reads = Reads::new();
        assert!(m.notice(&reads, "metrics").is_none());
        assert_eq!(reads.binding().read, 0);
    }

    #[test]
    fn an_undefined_name_is_dw0812_and_names_what_is_defined() {
        let m = Metrics::table();
        let err = m
            .resolve(MetricKind::SizeClass, "cathedral")
            .expect_err("`cathedral` is not a size class");
        let d = err.diagnostic("layout-graph", "/nodes/0/size_class");
        assert_eq!(d.code, "DW0812");
        assert!(d.message.contains("cathedral"));
        assert!(d.message.contains("room"), "the defined set is named");
        assert_eq!(d.stage, "layout-graph");
        assert_eq!(d.path, "/nodes/0/size_class");
    }

    #[test]
    fn every_kind_resolves_at_least_one_defined_name() {
        let m = Metrics::table();
        for kind in [
            MetricKind::Opening,
            MetricKind::Pitch,
            MetricKind::SizeClass,
            MetricKind::Storey,
        ] {
            let names = m.names_of(kind);
            assert!(
                !names.is_empty(),
                "{} resolves nothing, so DW0812 would refuse every name",
                kind.noun()
            );
            for n in names {
                assert!(m.resolve(kind, n).is_ok(), "`{n}` does not resolve");
            }
        }
    }

    // --- a body has a width -------------------------------------------------

    /// The fact the whole rule rests on, written down where it can be checked: a
    /// box selector spelled `x=lo,dx=hi-lo` is the world volume `[lo, hi+1]`, so
    /// `dx=0` is one whole block and never a plane.
    #[test]
    fn a_box_selector_spans_the_whole_of_its_last_cell() {
        assert_eq!(
            selection_aabb([7, 63, 20], [11, 67, 24]),
            ([7.0, 63.0, 20.0], [12.0, 68.0, 25.0])
        );
        let (lo, hi) = selection_aabb([0, 0, 0], [0, 0, 0]);
        assert_eq!((lo, hi), ([0.0, 0.0, 0.0], [1.0, 1.0, 1.0]));
    }

    /// **The measurement this rule was written from.** A wave's spider, 1.4 wide,
    /// walked to `x = 12.59` beside a pit whose box ends at `x = 12.0` and was
    /// killed there — its hitbox reaches `11.89`. Its feet cell is 12, which is
    /// outside the box, so every cell-shaped reading in the engine called that
    /// position safe.
    #[test]
    fn a_body_beside_a_face_is_inside_the_volume_and_its_cell_is_not() {
        let west_pit = ([7, 63, 20], [11, 67, 24]);
        let spider = Body::new(1.4, 1.4);
        assert!(
            body_meets_volume([12.59, 65.0, 21.02], spider, west_pit.0, west_pit.1),
            "hitbox 11.89..13.29 against a box face at 12.0"
        );
        // The cell it stands in is not one of the volume's cells.
        assert!(!(west_pit.0[0]..=west_pit.1[0]).contains(&12));
        // A player at the same cell's CENTRE is clear of it — 12.2..12.8 — which
        // is why the seat rule and the walk rule are two different readings.
        assert!(!body_meets_volume(
            [12.5, 65.0, 21.5],
            Body::PLAYER,
            west_pit.0,
            west_pit.1
        ));
        // …and the walk rule refuses that cell anyway, because a walker does not
        // stand at cell centres.
        assert!(cell_can_meet_volume(
            [12, 65, 21],
            Body::PLAYER,
            west_pit.0,
            west_pit.1
        ));
    }

    /// The touching case is NOT an intersection, exactly as vanilla's own
    /// `AABB::intersects` is strict: a body standing on a volume's top face with
    /// its feet at the face is clear of it.
    #[test]
    fn a_face_that_exactly_touches_is_not_inside() {
        let v = ([0, 0, 0], [0, 0, 0]);
        assert!(!body_meets_volume([0.5, 1.0, 0.5], Body::PLAYER, v.0, v.1));
        assert!(body_meets_volume([0.5, 0.999, 0.5], Body::PLAYER, v.0, v.1));
    }

    /// The keep-out box is a DERIVATION, not a constant one: it widens with the
    /// body. Horizontally every body up to two blocks wide reaches exactly one
    /// cell (half a width can never cross two cell boundaries at once);
    /// vertically a body taller than two blocks reaches one cell further down
    /// than a player does, which is the only place the bodies in this engine's
    /// dims table differ.
    #[test]
    fn the_keep_out_box_widens_with_the_body() {
        let v = ([10, 60, 10], [12, 62, 12]);
        assert_eq!(
            keep_out_box(Body::PLAYER, v.0, v.1),
            ([9, 59, 9], [13, 62, 13])
        );
        // 1.4 wide: the same ring. Half a width is 0.7, which crosses one
        // boundary and not two.
        assert_eq!(
            keep_out_box(Body::new(1.4, 1.4), v.0, v.1),
            ([9, 59, 9], [13, 62, 13])
        );
        // 2.9 tall (a warden): one cell further DOWN, because its head reaches
        // into the volume from a cell a player's head does not.
        assert_eq!(
            keep_out_box(Body::new(0.9, 2.9), v.0, v.1),
            ([9, 58, 9], [13, 62, 13])
        );
        // Standing ON the volume's top cell is safe for every body: the feet
        // start where the volume ends.
        assert!(!cell_can_meet_volume(
            [11, 63, 11],
            Body::new(0.9, 2.9),
            v.0,
            v.1
        ));
    }

    #[test]
    fn the_derived_player_values_are_the_arithmetic_their_notes_claim() {
        assert!((walk_ticks_per_block() - 20.0 / 4.317).abs() < f64::EPSILON);
        assert!((walk_ticks_per_block() - 4.633).abs() < 0.001);
        assert_eq!(unarmoured_survivable_fall_blocks(), 22.0);
        assert_eq!(passable_width_cells(), 1);
        assert_eq!(passable_clearance_cells(), 2);
    }

    #[test]
    fn the_jump_reach_runs_from_the_apex_to_the_deepest_survivable_fall_and_never_narrows() {
        assert_eq!(JUMP_REACH.first().map(|r| r.0), Some(1));
        assert_eq!(
            JUMP_REACH.last().map(|r| r.0),
            Some(-(unarmoured_survivable_fall_blocks() as i64))
        );
        for w in JUMP_REACH.windows(2) {
            assert_eq!(w[1].0, w[0].0 - 1, "one row per whole block of rise");
            assert!(
                w[1].1 >= w[0].1,
                "a deeper landing never admits a narrower gap: {w:?}"
            );
        }
        assert_eq!(jump_max_gap(MAX_JUMP_RISE_16), Some(3));
        assert_eq!(jump_max_gap(MAX_JUMP_RISE_16 + 1), None);
        assert_eq!(jump_max_gap(0), Some(4));
        assert_eq!(jump_max_gap(-24), Some(4), "a drop of 1.5 reads the -1 row");
        assert_eq!(jump_max_gap(-22 * FULL_16), Some(9));
        assert_eq!(jump_max_gap(-22 * FULL_16 - 1), None);
    }
}