refactor(ops): add OpCtx with send_and_await primitive (#1454 phase 2a)

[iduartgomez]

Problem

Phase 1 of the async-transaction refactor (#1454, PR #3802) wired the pending_op_result callback hook in handle_pure_network_message_v1 for every op variant, giving us a round-trip primitive that can send a NetMessage and await a reply keyed by the same Transaction. But the only caller of that primitive was OpManager::notify_op_execution, a private helper marked #[allow(dead_code)] with a FIXME, and there was no ergonomic path for a future op task to get at it. Phase 2b (SUBSCRIBE migration, separate PR) needs a per-transaction execution context to hand to the task function it spawns — hence OpCtx.

Solution

Introduce OpCtx as dormant scaffolding with exactly one method (send_and_await) built directly on top of Phase 1's round-trip. The full target API from the design doc (spawn_sub, per-tx inbox, WS notify fanout, OpRegistry, and a new Operation trait) is deferred until a concrete consumer needs it — matches Phase 1's "ship exactly what's needed, document constraints loudly, wait for a real caller" shape.

What ships

• New file crates/core/src/operations/op_ctx.rs with:
  • OpCtx { tx, op_execution_sender } — Send, not Clone, one owner per transaction
  • OpCtx::new (crate-private constructor)
  • OpCtx::tx() accessor
  • OpCtx::send_and_await(&mut self, msg) — the round-trip primitive
  • Compile-time Send assertion
  • Three #[tokio::test] tests (happy path, dropped reply sender, closed executor channel)
• OpManager::op_ctx(&self, tx: Transaction) -> OpCtx factory in op_state_manager.rs
• pub(crate) mod op_ctx; + re-export in operations.rs, matching the existing visited_peers::VisitedPeers pattern

What this deletes

• OpManager::notify_op_execution (previously ~40 lines at op_state_manager.rs:701-745). Its body moves verbatim into OpCtx::send_and_await; its "Scaffolding reach" and "Deadlock risk" doc sections are preserved there and expanded with four new sections (see below).
• Three unused #[allow(dead_code)]-gated accessor methods on EventLoopNotificationsReceiver / EventLoopNotificationsSender (notifications_receiver(), op_execution_receiver(), op_execution_sender()). A crate-wide grep confirmed zero callers — the fields are pub(crate) and callers destructure them directly per the pattern at op_state_manager.rs:2166-2170. The fields themselves stay; only the dead method wrappers are removed.

Design decisions that deviate from a naive literal read of the design doc

• &mut self on send_and_await, not self by value. This leaves ctx.tx() available after the call and matches the Rev 3 sketch. The single-use-per-tx constraint is documented in prose rather than compile-enforced.
• OpCtx is pub(crate), not pub. Nothing outside this crate has a legitimate use today.
• OpCtx holds the op_execution_sender directly, not Arc<OpManager>. This was the decisive call for testability: OpManager::new requires NodeConfig + ContractHandlerChannel + ConnectionManager + NetEventRegister + BackgroundTaskMonitor + result_router_tx and there is no test constructor. The sender-only shape lets the tests wire event_loop_notification_channel() directly, following the existing pattern at op_state_manager.rs:2155-2207.

Doc comment expansions on send_and_await (beyond the Phase 1 preserved sections)

• Single-use per Transaction — Phase 1's callback fires at most once per tx because the completed / under_progress dedup sets suppress subsequent dispatches. A second send_and_await on the same tx will hang on response_receiver.recv(). Callers needing retries must use a fresh Transaction per attempt. This is a known constraint Phase 2b's planner must work around.
• Where to call this — must run from an op task (e.g., GlobalExecutor::spawn), not from inside the main event loop or a priority_select arm, because the internal .send().await on a bounded channel can block.
• Terminal reply, not success reply — Ok(reply) may carry a non-success terminal (e.g., SubscribeMsg::Response::NotFound). Callers inspect the reply to decide what happened.
• Errors — OpError::NotificationError on send failure or receiver hang-up.

Dead code — OpCtx, its impl block, and OpManager::op_ctx carry #[allow(dead_code)] with a Phase 2b removal note until the first production caller lands. This mirrors how Phase 1 left the attribute on notify_op_execution until Phase 2a became its first caller.

Testing

• cargo fmt --check — clean
• cargo clippy -p freenet --all-targets --features bench -- -D warnings (pre-commit hook invocation, stricter than CI) — clean
• cargo clippy --locked -- -D warnings (CI invocation) — clean
• cargo test -p freenet --lib op_ctx — 3/3 passed
• cargo test -p freenet --lib --features bench — 2125 passed, 0 failed, 16 ignored (full library suite)

The three new unit tests follow the op_state_manager.rs:2155-2207 pattern — wire event_loop_notification_channel() directly, destructure EventLoopNotificationsReceiver, spawn a synthetic executor that mirrors what the real pipeline would do. No OpManager is constructed (there's no test constructor). Each test wraps send_and_await in a 1-second tokio::time::timeout as a defensive guard so a future regression into a hang fails fast rather than stalling CI.

Fixes

Partial progress on #1454. This is Phase 2a of the phased rollout in the design doc (§5). Does not close the tracking issue. Upcoming phases:

• Phase 2b: Migrate SUBSCRIBE's client-initiated path onto OpCtx (activates the first production caller, drops the #[allow(dead_code)] attrs)
• Phase 2.5: Port PUT-completion → SUBSCRIBE sub-op hand-off
• Phase 2c: Migrate CONNECT (schedule TBD)
• Phases 3–6: GET/PUT streaming, UPDATE broadcast, OpManager DashMap removal, docs/rules sweep

See the design doc in the body of #1454 (Rev 3), specifically §3 "Phase 2a minimum surface" for the target API and the Errata "Rev 2 → Rev 3" section for the phasing rationale.

[github-actions]

Rule Review: No blocking issues found

Rules checked: git-workflow.md, code-style.md, testing.md, operations.md
Files reviewed: 6 (node.rs, network_bridge.rs, op_state_manager.rs, operations.rs, op_ctx.rs [new], simulation_integration.rs)

Warnings

None.

Info

• op_ctx.rs:342 — tx() is declared pub on a pub(crate) struct; pub(crate) would be consistent with the struct visibility and new(). (code-style.md)

• op_ctx.rs:447 — response_receiver.recv().await has no timeout, which the # Deadlock risk doc section explicitly documents and defers to Phase 2b. Since there are no production callers yet this is a well-controlled deferral, but the first production caller in Phase 2b must add a tokio::time::timeout wrapper before using this path in a real op task. (code-style.md — "use tokio::time::timeout() instead")

Notes on what's clean

• New op_ctx.rs module uses foo.rs layout (not mod.rs) ✓
• No .unwrap() in production code; tests use .expect() with messages ✓
• All four tests cover happy path, both error paths, and the single-use-per-tx constraint — solid edge-case coverage ✓
• Push-before-send invariant is documented in the # Push-before-send section of send_and_await ✓
• Dead executor methods removed cleanly from network_bridge.rs without leaving stale #[allow(dead_code)] ✓
• Doc comments updated across all affected call sites to reference OpCtx::send_and_await instead of deleted notify_op_execution ✓
• This is a refactor: PR (not fix:), so no regression test requirement ✓

---

Rule review against .claude/rules/. WARNING findings block merge.