feat(notecard): Exclusive() + keep_ready() operation-session guards

Two independent RAII guards an app holds across a group of requests: exclusive() holds the (recursive) request lock so the group is atomic against other threads; keep_ready() holds the RTX/CTX readiness scope so the card is asserted-ready once for the whole group instead of per request. Both are no-ops when their seam is unset. Inner requests nest via the recursive lock / op_depth_ counter.

Mirrored on StaticNotecard<Stack, Lock>: ExclusiveSession reuses the StaticNcOpGuard path (zero-cost for NullLock), ReadySession reuses StaticNcTxnOpGuard (gated by NOTE_TXN_HANDSHAKE). AVR baselines unchanged (+0 flash, +0 RAM on all four envs).

Tests: threaded exclusive() group test (5 runs, 0 violations, TSan-clean) and keep_ready() coalescing test (start/stop fires once not twice across a two-request group). StaticNotecard smoke tests added for both guards. Full suite 2123/2123 passes.

Author: m-mcgowan

src/note/notecard.hpp

@@ -963,6 +963,132 @@ class Notecard {
         return p;
     }
 
+    // ── Operation-session guards ──────────────────────────────────────────
+    //
+    // Two independent RAII guards an app holds across a GROUP of requests.
+    //
+    // exclusive() — holds the recursive request lock for the guard's lifetime
+    //   so a group of requests is atomic against other threads (exclusion only).
+    //   Inner run_operation() calls re-acquire the lock harmlessly (recursive).
+    //   No-op when no request lock is configured.
+    //
+    // keep_ready() — holds the RTX/CTX readiness scope (op_depth_ /
+    //   begin_operation / end_operation) for the guard's lifetime so the card
+    //   is asserted-ready once for the whole group instead of per request
+    //   (readiness only). Inner run_operation() calls see op_depth_ > 0 and
+    //   skip begin_operation. When NOTE_TXN_HANDSHAKE is off, returns a trivial
+    //   empty guard with no op_depth_ touch. No-op when no transport is set.
+    //
+    // Both guards: non-copyable, non-movable. C++17 guaranteed copy elision
+    // (NRVO) makes `auto g = nc.exclusive();` work without any copy or move.
+    //
+    // The two guards are INDEPENDENT — an app may use either, both, or neither.
+    // exclusive() = exclusion; keep_ready() = readiness. They compose correctly:
+    //
+    //     auto ex = nc.exclusive();   // lock the group
+    //     auto kr = nc.keep_ready();  // hold RTX-ready for the group
+    //     nc.execute(req1);
+    //     nc.execute(req2);
+
+    /// RAII guard returned by exclusive(). Holds the recursive request lock
+    /// for its lifetime; non-copyable, non-movable.
+    struct ExclusiveSession {
+        ExclusiveSession(const ExclusiveSession&)            = delete;
+        ExclusiveSession& operator=(const ExclusiveSession&) = delete;
+        ExclusiveSession(ExclusiveSession&&)                 = delete;
+        ExclusiveSession& operator=(ExclusiveSession&&)      = delete;
+
+        ~ExclusiveSession() {
+            if (lock_) lock_->unlock();
+        }
+    private:
+        friend class Notecard;
+        explicit ExclusiveSession(IBusLock* lock) : lock_(lock) {
+            if (lock_) lock_->lock();
+        }
+        IBusLock* lock_;
+    };
+
+    /// RAII guard returned by keep_ready(). Holds the RTX/CTX readiness scope
+    /// (op_depth_ / begin_operation / end_operation) for its lifetime so the
+    /// card is asserted-ready once for the whole group; non-copyable, non-movable.
+    /// When NOTE_TXN_HANDSHAKE is off this is a trivial empty struct.
+    struct ReadySession {
+        ReadySession(const ReadySession&)            = delete;
+        ReadySession& operator=(const ReadySession&) = delete;
+        ReadySession(ReadySession&&)                 = delete;
+        ReadySession& operator=(ReadySession&&)      = delete;
+
+#if NOTE_TXN_HANDSHAKE
+        ~ReadySession() {
+            if (outermost_ && nc_->transport_) nc_->transport_->end_operation();
+            --nc_->op_depth_;
+        }
+#else
+        ~ReadySession() = default;
+#endif
+
+    private:
+        friend class Notecard;
+#if NOTE_TXN_HANDSHAKE
+        explicit ReadySession(Notecard* nc)
+            : nc_(nc)
+            , outermost_(nc_->op_depth_++ == 0)
+        {
+            if (outermost_ && nc_->transport_)
+                nc_->transport_->begin_operation(nc_->default_timeout_ms_);
+        }
+        Notecard* nc_;
+        bool outermost_;
+#else
+        explicit ReadySession(Notecard*) {}
+#endif
+    };
+
+    /// Hold the recursive request lock across a group of requests, making the
+    /// group atomic against other threads (exclusion only — does NOT affect
+    /// the RTX/CTX readiness scope).
+    ///
+    /// The request lock must be set via set_request_lock() and must be
+    /// recursive (see set_request_lock docs). When no lock is configured this
+    /// is a no-op. Inner run_operation() calls within the guard re-acquire the
+    /// lock on the same thread harmlessly (recursive re-entry); other threads
+    /// block on the lock for the lifetime of the guard.
+    ///
+    ///     auto ex = nc.exclusive();   // lock held here
+    ///     nc.execute(req1);           // inner lock re-acquire: no-op (recursive)
+    ///     nc.execute(req2);           // still inside the exclusive group
+    ///                                 // ex destructs → lock released
+    ///
+    /// Note: exclusive() = exclusion only. To hold RTX readiness across the
+    /// group as well, combine with keep_ready() (the two are independent).
+    [[nodiscard]] ExclusiveSession exclusive() {
+        return ExclusiveSession{request_lock_};
+    }
+
+    /// Hold the RTX/CTX readiness scope across a group of requests so the
+    /// card is asserted-ready once for the whole group instead of per request
+    /// (readiness only — does NOT acquire the request lock).
+    ///
+    /// When NOTE_TXN_HANDSHAKE is enabled, the guard calls begin_operation()
+    /// on the outermost entry and end_operation() on destruction. Inner
+    /// run_operation() calls see op_depth_ > 0 and skip begin_operation —
+    /// the card stays asserted-ready for all requests in the group.
+    ///
+    /// When NOTE_TXN_HANDSHAKE is off (the default for AVR/minimal builds)
+    /// this returns a trivial empty guard with no op_depth_ touch.
+    ///
+    ///     auto kr = nc.keep_ready();  // begin_operation once (RTX asserted)
+    ///     nc.execute(req1);           // op_depth_ > 0 → no inner begin_operation
+    ///     nc.execute(req2);           // same
+    ///                                 // kr destructs → end_operation (RTX released)
+    ///
+    /// Note: keep_ready() = readiness only. To atomically exclude other threads
+    /// as well, combine with exclusive() (the two are independent).
+    [[nodiscard]] ReadySession keep_ready() {
+        return ReadySession{this};
+    }
+
     /// Operation gate. Acquires the operation lock (if any) before doing
     /// anything else, so that cross-thread exclusion is immediate: a second
     /// thread entering any operation blocks here until the first thread's

src/note/static_notecard.hpp

@@ -406,6 +406,70 @@ class StaticNotecard : private Lock {
                                           timeout_ms);
     }
 
+    // ── Operation-session guards ──────────────────────────────────────────
+    //
+    // Mirror of Notecard::exclusive() / Notecard::keep_ready().
+    // See the Notecard counterparts for the full usage documentation.
+    //
+    // StaticNotecard differences:
+    //   exclusive(): the lock is the EBO base class `Lock`. A `NullLock`
+    //     base produces a zero-cost no-op guard (no lock/unlock calls and
+    //     no stored pointer — the specialization has no members).
+    //   keep_ready(): gated by NOTE_TXN_HANDSHAKE exactly like the
+    //     polymorphic version; trivial empty guard when the flag is off.
+
+    /// RAII guard returned by exclusive(). Holds the compile-time lock for
+    /// its lifetime; non-copyable, non-movable. Zero-cost when Lock=NullLock
+    /// (the NullLock specialization of StaticNcOpGuard has no members and
+    /// trivial ctor/dtor, so the entire guard is eliminated by the compiler).
+    struct ExclusiveSession {
+        ExclusiveSession(const ExclusiveSession&)            = delete;
+        ExclusiveSession& operator=(const ExclusiveSession&) = delete;
+        ExclusiveSession(ExclusiveSession&&)                 = delete;
+        ExclusiveSession& operator=(ExclusiveSession&&)      = delete;
+        ~ExclusiveSession() = default;
+
+    private:
+        friend class StaticNotecard;
+        using OpGuard = detail::StaticNcOpGuard<Lock>;
+        OpGuard guard_;
+        explicit ExclusiveSession(Lock* lock) : guard_(lock) {}
+    };
+
+    /// RAII guard returned by keep_ready(). Holds the RTX/CTX readiness
+    /// scope for its lifetime; non-copyable, non-movable. Trivial empty
+    /// guard when NOTE_TXN_HANDSHAKE is off.
+    struct ReadySession {
+        ReadySession(const ReadySession&)            = delete;
+        ReadySession& operator=(const ReadySession&) = delete;
+        ReadySession(ReadySession&&)                 = delete;
+        ReadySession& operator=(ReadySession&&)      = delete;
+        ~ReadySession() = default;
+
+    private:
+        friend class StaticNotecard;
+#if NOTE_TXN_HANDSHAKE
+        using TxnGuard = detail::StaticNcTxnOpGuard<Stack, Lock>;
+        TxnGuard guard_;
+        explicit ReadySession(StaticNotecard& nc) : guard_(nc) {}
+#else
+        explicit ReadySession(StaticNotecard&) {}
+#endif
+    };
+
+    /// Hold the compile-time lock across a group of requests (exclusion only).
+    /// Zero-cost no-op when Lock=NullLock. See Notecard::exclusive() for details.
+    [[nodiscard]] ExclusiveSession exclusive() {
+        return ExclusiveSession{static_cast<Lock*>(this)};
+    }
+
+    /// Hold the RTX/CTX readiness scope across a group of requests (readiness
+    /// only). Zero-cost no-op when NOTE_TXN_HANDSHAKE is off. See
+    /// Notecard::keep_ready() for details.
+    [[nodiscard]] ReadySession keep_ready() {
+        return ReadySession{*this};
+    }
+
     /// One-shot `echo` connectivity probe. Mirror of `Notecard::ping()` —
     /// see the description there for the wire shape, timing, error
     /// semantics, and the meaning of `seed_fn`. The two implementations