feat(core): derive geyser slot statuses from a per-slot lifecycle

[cds-amal]

1. What

This PR refactors #747 starting with its bones (the status set, warp handling, and wiring points) and moves the scattered emission sites behind one state machine, so the ordering guarantees are properties of the machine, not its call sites.

Every slot-status emission now comes from one transition relation, a per-slot lifecycle registry in surfnet/slot_lifecycle/:

• announce emits CreatedBank, produce emits Processed, and confirm emits Confirmed
• rooting is a threshold: root_through(r) roots every confirmed slot at or below r, in slot order, from the registry's own record
• a forward warp emits Dead for the abandoned open slot and CreatedBank for the destination; a backward warp is a reorg, emitting Dead for every rewritten slot, in slot order, before re-announcing the destination

Each transition requires its exact predecessor stage, so a status cannot be skipped or repeated within a bank. Block production follows lifecycle order (block data, then produce/confirm, then root, then announce the next slot), so consumers see every slot announced before its data and its data before confirmation. UpdateSlotStatus carries Agave's SlotStatus, since CreatedBank and Dead exist only there.

2. Consumer-visible changes

Both streams now derive from the same lifecycle, which makes a few wire-visible changes.

WS and geyser agree on lifecycle statuses

slotsUpdatesSubscribe now mirrors CreatedBank, OptimisticConfirmation, Root, and Dead from the same emission point as geyser. Warp statuses, which previously reached geyser only, now reach both.

Frozen stays with block production, which alone knows the block's transaction stats. Within a block, CreatedBank for the next slot therefore arrives after Frozen and OptimisticConfirmation, rather than between them.

Rooting follows the registry

A warp gap drains cleanly: every confirmed slot still roots.

After a persistent-mode restart, the fresh registry knows nothing about prior-run slots, so neither stream emits roots for them. Previously ws Root fired unconditionally while geyser Rooted did not.

CreatedBank carries the registry's parent

The parent is the highest slot on record below the new slot: the registry's chain tip. A warp destination therefore links to a real slot instead of slot - 1. If nothing below the destination remains on record, it is parentless.

Other statuses carry no parent, matching Agave's notifier.

Deep backward warps replace the timeline

A backward warp may land at or below the root line; time travel to the current epoch does exactly this. Those rooted slots have already left the registry, so the landing re-announces one with a parentless CreatedBank.

That is the discontinuity signal: a consumer that sees CreatedBank for a slot it previously saw rooted drops state at or above that slot and resyncs.

Time travel is a cheatcode, so calling it suspends the cross-timeline guarantees that rooted slots are final and slots increase. The per-bank guarantees still hold through the warp: announce before data, data before confirmation, statuses in order and once.

3. How the contract is checked

The lifecycle has an independent machine and spec, following the startup state machine's precedent:

• slot_lifecycle/mod.rs implements the machine
• slot_lifecycle/spec.rs encodes the transition table, one row per (state, event) cell; warp, root-through, and clear are set-level rules routed through those same cells

The machine never reads the spec, so the two remain independent encodings.

The machine matches the spec

An exhaustive sweep visits every reachable registry state across every event. For each transition, it compares the machine's emissions and successor state against the spec cell.

A totality test separately ensures that every (state, event) cell exists.

Production preserves the open-slot invariant

A second sweep drives the registry through production's call grammar: close a block, warp, reset.

At every reachable point, exactly one slot must be Announced, and it must be the open slot. This rules out both an orphaned announced slot and an open slot whose data could arrive before its announcement.

The wire contract is tested as consumers see it

SVM-level tests observe both streams and check the external guarantees: announce before data, data before confirmation, statuses in order and once per bank, and warp statuses mirrored to ws.

The docs come from the spec

The rustdoc table and edge diagram in slot-lifecycle.md render from the spec rows. A test flags stale generated blocks; cargo surfpool-update-slot-spec regenerates them. This is the startup spec's diagram pipeline, applied to the slot spec.

[greptile-apps]

Greptile Summary

The PR centralizes Geyser and WebSocket slot-status generation in a per-slot lifecycle registry.

• Adds ordered announce, produce, confirm, root, warp, and reset transitions.
• Routes block production, startup, and clock warps through the lifecycle.
• Adds an independent transition specification, exhaustive reachability tests, generated documentation, and diagram tooling.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains in the eligible follow-up review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
crates/core/src/surfnet/slot_lifecycle/mod.rs	Introduces the per-slot lifecycle registry and ordered transitions for normal progression, rooting, warps, and resets.
crates/core/src/surfnet/svm.rs	Integrates lifecycle emissions with block production, clock warps, Geyser plugins, and WebSocket slot-update subscribers.
crates/core/src/runloops/mod.rs	Moves startup lifecycle notifications before RPC binding and routes clock updates through the centralized warp helper.
crates/core/src/surfnet/slot_lifecycle/spec.rs	Defines an independent transition-table specification used as the lifecycle test oracle and documentation source.
crates/core/src/surfnet/slot_lifecycle/reachability_tests.rs	Exhaustively compares reachable machine states with the specification and checks the production open-slot invariant.
crates/core/build.rs	Generates rustdoc-ready lifecycle documentation by replacing Mermaid regions with checked-in SVG renderings.

_{Reviews (3): Last reviewed commit: "docs(core): the slot diagram as mermaid,..." | Re-trigger Greptile}