feat(store): futures::Stream bridge for owning-output lending streams

[joeldsouzax]

Summary

PR2 of the dual-track stream refactor (plan: cheerful-yawning-hopper). Adds a feature-gated bridge from the GAT lending EventStream into futures_core::Stream so consumers can opt in to the futures ecosystem when they want owning output.

• New futures-bridge feature gates an optional futures-core dep.
• New OwnedEventStream<M> sub-trait witnesses "Item<'a> is an owned value" via a concrete OwnedItem associated type. Mirrors PR1's BaseEventStream pattern, which sidesteps the HRTB-on-GAT type equality issue on stable Rust. Implemented for Map and TryMap only — not for raw cursors (their Item<'a> borrows from the cursor). To bridge a raw cursor, chain .map(...) / .try_map(...) first so the per-event materialization is named at the call site.
• New IntoStream<S, M> implements futures_core::Stream via a hand-rolled state machine (Idle / Pending / Done) that box-pins each next() future. The unfold pattern moves the cursor into the future and returns it back — sidestepping self-referential lifetimes. The box-pin is the per-event allocation the plan calls out as explicit and opt-in.
• EventStreamExt::into_stream() is the entry point (also feature-gated).
• Hakari: futures-core excluded from workspace-hack unification (.config/hakari.toml) so the "feature off → dep absent from dep tree" guarantee holds workspace-wide, not just for published consumers.

Filter (deferred from PR1 per its deviation log) is untouched; remains a follow-up.

Open design point resolved

The plan listed three options for the "OwnedItem marker shape" — separate trait, 'static bound, or Clone + Send + 'static. Picked the trait route (OwnedEventStream) for symmetry with PR1's BaseEventStream. The 'static bound is insufficient on its own because futures::Stream::Item is a single concrete type and we still need a named associated type to plug into it; HRTB type equality (for<'a> Item<'a> = T) is blocked by the GAT's where Self: 'a clause leaking Self: 'static into the HRTB. Full reasoning in the deviation log.

Test plan

• nix flake check passes (all 8 checks).
• cargo test -p nexus-store --features futures-bridge --test futures_bridge_tests — 7 tests pass:
  • Sequence/Protocol: try_map → into_stream → try_collect yields all items in order
  • Sequence/Protocol: map → into_stream yields owned closure outputs wrapped in Ok(...)
  • Lifecycle: empty lending stream → empty futures stream
  • Lifecycle: bridge is fused after exhaustion (None keeps returning None)
  • Defensive Boundary: underlying-stream error propagates once then bridge terminates
  • Defensive Boundary: try_map closure error short-circuits identically
  • Send/spawn: bridge is driveable from tokio::spawn
• Static assertion: IntoStream<TryMap<VecStream, ..>, ()>: Send.
• cargo tree -p nexus-store --no-default-features --edges normal shows zero futures crates (hakari exclude in place).
• cargo tree -p nexus-store --features futures-bridge confirms futures-core IS present when the feature is on.

Files

• Cargo.toml — workspace deps: futures = "0.3" (dev-dep), futures-core = "0.3" (default-features = false).
• .config/hakari.toml — [final-excludes] block excluding futures-core from workspace-hack unification.
• crates/nexus-store/Cargo.toml — futures-bridge feature → dep:futures-core; futures workspace dev-dep; dev-dep enables futures-bridge.
• crates/nexus-store/src/stream/owned.rs (new) — OwnedEventStream sub-trait + IntoStream bridge.
• crates/nexus-store/src/stream/mod.rs — feature-gated re-export.
• crates/nexus-store/src/stream/cursor.rs — feature-gated EventStreamExt::into_stream() method.
• crates/nexus-store/src/lib.rs — feature-gated re-export.
• crates/nexus-store/tests/futures_bridge_tests.rs (new) — 7 tests covering the 4-category matrix.
• crates/workspace-hack/Cargo.toml — hakari output (regenerated).

Plan / deviation log

• Plan: /Users/joel/.claude/plans/cheerful-yawning-hopper.md
• Deviation log: /Users/joel/.claude/plans/cheerful-yawning-hopper-deviations.md — four new entries for PR2 (OwnedEventStream choice, futures-core-only impl, hakari exclude, module naming).

🤖 Generated with Claude Code