Derived ranking keys, local: related / count / sum and the type chain (nxf 6j6v.x0wf)

[cabcookie]

Stacked on #47 (which stacks on #46). Merge those first; until then this diff also shows their commits.

What

The local cut of docs/specs/derived-ranking-keys.md (spec e354, §11 cut 1). A per-type order ([ranking.next.<type>], [ranking.list.<type>], and the [ranking.list] default order) can now hold derived keys alongside field keys:

{ related = "parent", type = "project", of = "rank", nulls = "last" }
{ related = "contributes_to", type = "goal", of = { field = "order" }, pick = "min", nulls = "last" }
{ count = "children", type = "action", status = ["open", "in_progress"], dir = "desc" }
{ sum = [ { count = "mentioned_by", type = "project" },
          { count = "mentioned_by", type = "action", label = "waiting", status = ["open", "in_progress"] } ], dir = "desc" }

• Load-time validation (spec §7): these are refused, each error naming its key. A key that mixes kinds or names none. An unknown edge kind or direction. A part the kind does not take (pick/of on a count, nulls on a count/sum, status/label on related, derived parts on a field key, precedence on a derived key, dir/nulls inside of). An undeclared type, status or of field (custom fields are allowed and checked against on). of = "rank" on a type with no declared order. A cycle in the type chain, across both sections, with the cycle named. Unknown parts such as weight fail at parse.
• Bottom-up, once per query (spec §4/§5): read::derived::compute makes one edge pass (Store::present_edges_of_kinds), plus the reverse mentions through q29p's read::mentioners_of (spec §11: one implementation), plus one bulk read of the neighbours (and their labels/custom fields only when a key needs them). It then walks the chain leaves first, with one sort and a dense rank per type, and stores the values the comparator reads. Cost O(E + N log N). A plugin with no derived keys pays nothing.
• TypeRank carries the values, so next (inside the tiers) and list --sort rank share one comparator.

Readings of the spec, recorded in its new §12 (each is the owner's to confirm)

1. of = "rank" reads the asking section's per-type order, else the other section's. §8 needs this: persons ranked by list read the rank of projects that only next ranks. Such a list query takes next's candidates at a reference time. That is ListQuery::now / read::list_at, and the CLI and MCP fill it from the clock only for such a plugin. Without one, the query answers validation.
2. A list rank's scope is the live, unarchived items of the type, whatever the query filters by. next's scope is its candidates before filters.
3. "Dense rank": items equal on every key share a rank. The id orders the sort, never the rank.
4. Only live neighbours count: deleted ones drop, closed and archived ones count. This is mentioners_of's rule.
5. Derived keys are refused in the [ranking.next] default order, which also ranks blocked and the lanes' --sort rank.
6. An untyped related … of = "rank" in a per-type order is a self-cycle, and the error asks for the neighbour's type.
7. read::next_active (the store-free path) refuses a plugin whose [ranking.next] has derived keys, until 1c5s.
8. §8's sum example is not valid TOML 1.0: an inline table cannot break a line outside its arrays.

Facade

facade: breaking. RankKey gains the derived parts, becomes #[non_exhaustive], and refuses unknown parts. Build one in code with RankKey::field_key. Additive: CountPart, OfField, Pick, RankOf, RankSpec::has_derived, ListQuery::now, read::list_at, and in core Store::present_edges_of_kinds / EdgeReadStats (plus Hash on EdgeKind). Fold revisions and the fold-ddb index are untouched.

Tests

• plugin::tests: each refusal, both cycle shapes, the spec's §8 orders, and the cross-section rank source.
• crates/facade/tests/derived_ranking.rs: the §8 chain at the Engine seam (next_query, list_query, filters, paging). Then each kind over hand-built boards, determinism under shuffled edge order, the store-free refusal, and a query-shape ratio guard in the xn8s style: edge and item reads are identical at 12 and 60 projects, with one pass per query.
• Core: present_edges_of_kinds and its counter.
• Run locally, all green: the facade lib (142), next_rank_per_type, next_query, list_query, mentioned_by, read, derived_ranking, core store::tests, cli list, cargo xtask docs check, cargo xtask changelog check origin/main, cargo fmt --check.
• No CLI black-box test covers derived keys: the nxf binary links only the bundled plugins, and they declare none. The spec's differential test against graph::Board belongs to 1c5s.

Docs: the plugin guide (EN/DE) has a new "Declaring a ranking" section, commands.md (EN/DE) points to it, and the spec gains §12 plus a note in the tiers spec.

🤖 Generated with Claude Code

https://claude.ai/code/session_016q5uMUkZJQW4fckJoA3FME

[cabcookie]

Contained in #49, which folds #46, #47 and #48 plus the review mitigation and was merged in one squash.