feat(store): phase-aware subscribe — Step on subscribe, decode composes (#250)

[joeldsouzax]

Resolves #250. Builds on #249 (now in main).

What & why

The catch-up→live boundary is what makes a subscription a subscription (a finite read has no such boundary). So subscribe/subscribe_all now yield Step<PersistedEnvelope> / Step<(AllPosition, PersistedEnvelope)> directly — the CaughtUp marker the live loop already detects rides all the way to the consumer, instead of being thrown away by raw subscribe and re-added by a separate subscribe_typed/cursor method.

Phase and decode are orthogonal axes, composed by combinators — never welded into a method name:

subscribe(&id, from)              -> Step<PersistedEnvelope>            // raw + phase
  .events()                       -> PersistedEnvelope                  // drop phase
  .events().decoded(codec)        -> Decoded<E>                         // typed, no phase (#249)
  .decoded(codec)                 -> Step<Decoded<E>>                   // typed + phase (projections)
  .events().for_each_decoded(..)  -> zero-copy borrowing fold (KERI/rkyv)

Consuming catch-up→live is now: match Step::CaughtUp / Step::Event(d) — no magic count-drain, no hand-rolled timeout_next, nexus-owned error.

Changes

• Step<T> (Event | CaughtUp) frozen two-variant phase marker + Step::map.
• StepStreamExt (.events() / .decoded()) reusing [freeze] Subscriptions force hand-decoding: no ergonomic typed view that reuses the configured codec #249's RawItem/Decoded/DecodeStreamError; Step<I> deliberately not a RawItem (CaughtUp has no envelope), so the two .decoded() methods are non-overlapping.
• subscribe/subscribe_all re-shaped onto the live_stepped core loop; internal events-only live filter deleted (its logic is now the public .events()).
• Example: end-to-end fjall persistence + live subscription + export/import round-trip #227 example migrated off the count-drain + timeout_next onto CaughtUp.
• ~44 events-only call sites across nexus-store/fjall/postgres + examples gain .events().

Breaking to raw subscribe + #249's .decoded() — both pre-freeze/experimental; the seam is fixed now because it is frozen forever at 1.0.

Tests (4 mandatory categories, three layers)

• phase_subscription_tests (end-to-end): exactly-one-CaughtUp across a 2600-event multi-chunk backlog (latch survives scan reopens); $all position-order replay; resume-from-checkpoint/head; .events() strip + composition; decode error never swallowed into a spurious CaughtUp; $all concurrency.
• step_stream_ext_tests (combinator isolation + proptest): pathological Step sequences, error-domain routing, tag preservation.
• nexus-fjall (real LSM adapter): CaughtUp survives close/reopen replay and >CATCHUP_CHUNK ScanCursor reopens.

🤖 Generated with Claude Code