fix(api): Stash Notecard "err" message into allocator-backed storage

The Api singleton thunk path captures Notecard error strings into a caller-stack `detail::NcErrorCapture` whose `view()` returned a pointer into its own `buf[64]`. Generated `execute()` then constructed `ApiResult<...>(ErrorInfo{..., nc_err_.view()})` whose `ErrorMessage` held that pointer — undefined behavior the moment execute() returned and the stack frame was reused. Reading `result.error().message` after a Notecard error returned silently truncated bytes or random heap contents. The non-singleton path doesn't have the bug because it routes through `streaming_attempt`'s `pool.intern(err)` (allocator-backed, heap-leaked, durable).

Adds `Notecard::stash_nc_err(string_view)` and the matching `StaticNotecard::stash_nc_err(string_view)` that copy the bytes into the configured allocator (one allocation per Notecard error, never freed — same lifetime model as `StringPool::intern`). Adds an optional `durable_ptr` field to `NcErrorCapture` whose `view()` prefers the durable pointer when set. The api.hpp.j2 thunks call `stash_nc_err` after `execute_void`/`execute_generic_with_body` returns and route the durable pointer back through `set_durable`, so the generated code needs no change — `nc_err_.view()` just starts returning durable bytes automatically.

Avoids fixed-size buffers entirely: arena allocators pay only for the messages they actually receive, and zero-allocator builds get `nullptr` and fall back to the original (still-dangling) buf-pointer path — no worse than before, no extra RAM consumed.

NOTE_MINIMAL gates the entire stash mechanism out — the durable_ptr field, set_durable(), the view() branch, stash_nc_err() itself, and the thunk's call to it all collapse to the original code. AVR-class targets (which set NOTE_MINIMAL) typically branch on `result.error().code` and ignore the textual message; the +250 B of flash for the durable-copy logic isn't worth it there. AVR sizes verified at baseline post-change (avr-notecpp / direct / raw / multistack all unchanged).

Test impact: the streaming-error tests that previously failed under NOTE_SINGLETON=1 (e.g. `streaming: void endpoint with Notecard error`, `streaming: Notecard error response propagates`) now pass because `rsp.error().message == "<text>"` reads stable bytes. Failure count in the singleton-only build drops from 73 to 65; the remaining 65 are unrelated pre-existing limitations of singleton mode (GenericResponseSink can't dispatch array fields; thunk path doesn't inject request IDs).

Also documents the rationale for the existing `binary_ctrl_buf_[256]` fixed-size buffer in Notecard, since it's the same pattern this fix deliberately avoided.

Author: m-mcgowan

src/note/api.hpp

@@ -140,13 +140,43 @@ class Api {
 #if NOTE_SINGLETON
     // Static thunks — one copy each, shared by all endpoints via create_().
     // Eliminates per-type lambda instantiation in the factory methods.
+    //
+    // After execute(), if a Notecard "err" was captured, route the bytes
+    // through `stash_nc_err()` so they live in allocator-backed storage
+    // beyond the caller's stack. Generated `execute()` later builds an
+    // `ApiResult<...>(ErrorInfo{..., err.view()})` whose pointer would
+    // otherwise dangle the moment execute() returns. `stash_nc_err()`
+    // returns nullptr when no allocator is configured; the fallback to
+    // `NcErrorCapture::buf` is still dangling in that case, but no
+    // worse than before — and no fixed-size buffer is added for the
+    // common case.
+    //
+    // The stash call is skipped under NOTE_MINIMAL: AVR-class targets
+    // typically don't surface the textual error message (they branch on
+    // `result.error().code` and ignore the string), so the +250 bytes
+    // of flash for the durable-copy logic isn't worth it. The dangling
+    // `view()` quirk persists there, gated to that minimal build only.
     static Result<void> void_thunk_(void* p, string_view req, BuildFn fn, void* ctx, detail::NcErrorCapture& err) {
+#if NOTE_MINIMAL
         return static_cast<NcT*>(p)->execute_void(req, fn, ctx, err);
+#else
+        auto* nc = static_cast<NcT*>(p);
+        auto rv = nc->execute_void(req, fn, ctx, err);
+        err.set_durable(nc->stash_nc_err(err.view()));
+        return rv;
+#endif
     }
     static Result<void> generic_thunk_(void* p, string_view req, BuildFn fn, void* ctx,
             void* rsp, const FieldDesc* f, uint8_t n, detail::NcErrorCapture& err, bool& ex,
             void* body_ptr, BodyHandlerFactory body_factory) {
+#if NOTE_MINIMAL
         return static_cast<NcT*>(p)->execute_generic_with_body(req, fn, ctx, rsp, f, n, err, ex, body_ptr, body_factory);
+#else
+        auto* nc = static_cast<NcT*>(p);
+        auto rv = nc->execute_generic_with_body(req, fn, ctx, rsp, f, n, err, ex, body_ptr, body_factory);
+        err.set_durable(nc->stash_nc_err(err.view()));
+        return rv;
+#endif
     }
     static Result<void> send_thunk_(void* p, BuildFn fn, void* ctx) {
         return static_cast<NcT*>(p)->send_command(fn, ctx);

src/note/notecard.hpp

@@ -690,6 +690,29 @@ class Notecard {
 
     JsonBackend& backend() { return *backend_; }
 
+    /// Allocator-backed durable copy of a Notecard error message — used
+    /// by the Api singleton thunk path to give `NcErrorCapture::view()`
+    /// a pointer that outlives the caller-stack-allocated NcErrorCapture
+    /// frame. Without this, generated `execute()` returns an
+    /// `ApiResult<...>` whose `ErrorMessage` points into dead stack
+    /// memory by the time `result.error().message` is read.
+    ///
+    /// Allocates `sv.size()` bytes from the configured `alloc_` (one
+    /// allocation per Notecard error; never freed — same heap-leaked
+    /// pattern as `streaming_attempt`'s `pool.intern(err)` on the
+    /// non-singleton path). Returns `nullptr` if no allocator is
+    /// configured or the allocation fails — caller falls back to
+    /// `NcErrorCapture::buf` (still dangling past execute(), but at
+    /// least no fixed buffer is consumed for the rare no-allocator
+    /// build).
+    const char* stash_nc_err(string_view sv) {
+        if (sv.empty() || !alloc_.has_value()) return nullptr;
+        auto* p = static_cast<char*>(alloc_->allocate(sv.size()));
+        if (!p) return nullptr;
+        for (size_t i = 0; i < sv.size(); ++i) p[i] = sv[i];
+        return p;
+    }
+
 private:
     template<typename RequestT>
     ApiResult<typename RequestT::Response> do_binary_send(RequestT& req) {
@@ -1081,7 +1104,22 @@ class Notecard {
     std::optional<Allocator> alloc_;
     DebugListener debug_{};
     byte_span cobs_buf_{};          // optional external COBS working buffer
-    char binary_ctrl_buf_[256]{};   // buffer for binary control command responses
+    /// Synchronous-response buffer for binary-transfer control commands
+    /// (`{"req":"card.binary"}` status / `delete:true` reset). Fixed
+    /// 256 bytes because:
+    ///   - `do_binary_send`/`do_binary_receive` issue these queries
+    ///     synchronously and need somewhere to land the response before
+    ///     extracting `max`, `length`, `status` (MD5).
+    ///   - Sized to fit the largest realistic card.binary status reply
+    ///     (offset/length/cobs/max integers + a 32-byte MD5 + scaffolding).
+    ///     Smaller responses leave headroom; the builder doesn't grow.
+    ///   - Lives on the Notecard (not the request) so the binary-transfer
+    ///     orchestration helpers can stay non-template and avoid pulling
+    ///     in the full request type just for a status query.
+    /// Trade-off: 256 bytes per Notecard even for builds that never use
+    /// binary transfer. Acceptable on hosts/MCUs (Notecards are rarely
+    /// instantiated more than once); not used on AVR-class targets.
+    char binary_ctrl_buf_[256]{};
 #ifndef NOTE_RSP_BUF_SIZE
 #define NOTE_RSP_BUF_SIZE 1024
 #endif

src/note/protocol.hpp

@@ -89,14 +89,41 @@ struct NcErrorCapture {
     static constexpr size_t kMaxLen = 64;
     char buf[kMaxLen]{};
     size_t len = 0;
+#if !NOTE_MINIMAL
+    /// Optional pointer to a durable copy of the captured bytes — set by
+    /// the singleton thunk path via `Notecard::stash_nc_err(...)` so that
+    /// `view()` returns a string_view that outlives the local
+    /// NcErrorCapture frame. When nullptr, view() falls back to `buf`
+    /// (caller-stack lifetime, used by the StaticNotecard transact path
+    /// which captures bytes directly into `buf` during SAX dispatch).
+    /// Gated out under NOTE_MINIMAL: AVR-class targets accept the
+    /// dangling-view quirk in exchange for ~90 B less flash.
+    const char* durable_ptr = nullptr;
+#endif
 
     void capture(string_view v) {
         len = v.size() < kMaxLen ? v.size() : kMaxLen;
         for (size_t i = 0; i < len; ++i) buf[i] = v[i];
+#if !NOTE_MINIMAL
+        durable_ptr = nullptr;
+#endif
     }
 
+#if !NOTE_MINIMAL
+    /// Override view()'s pointer with allocator-backed bytes that outlive
+    /// this NcErrorCapture. `len` stays as the captured length. Caller is
+    /// responsible for keeping `data` alive — typically done by routing
+    /// through the Notecard's allocator via `stash_nc_err(...)`.
+    void set_durable(const char* data) { durable_ptr = data; }
+#endif
+
     bool empty() const { return len == 0; }
-    string_view view() const { return {buf, len}; }
+    string_view view() const {
+#if !NOTE_MINIMAL
+        if (durable_ptr) return {durable_ptr, len};
+#endif
+        return {buf, len};
+    }
 };
 
 /// ReceiveContext — wraps a SaxDispatch to intercept "err" and "crc" fields.

src/note/static_notecard.hpp

@@ -236,6 +236,27 @@ class StaticNotecard {
     /// Access the transport stack (e.g. for binary I/O).
     Stack& stack() { return stack_; }
 
+#if !NOTE_MINIMAL
+    /// Mirror of `Notecard::stash_nc_err` for the Api singleton-thunk
+    /// path. Allocates the bytes from the Notecard's configured
+    /// allocator (heap-leaked — same pattern as StringPool::intern; the
+    /// allocator's lifetime carries the bytes). No fixed buffer: arena
+    /// builds pay only for the messages they actually receive, and
+    /// zero-allocator builds get nullptr (caller falls back to the
+    /// caller-stack `NcErrorCapture::buf`, dangling past execute() —
+    /// the same lifetime quirk that existed before this fix).
+    /// Gated out under NOTE_MINIMAL: the singleton thunk on AVR-class
+    /// targets doesn't call this, so the function would otherwise sit
+    /// unused; gating ensures the linker doesn't accidentally retain it.
+    const char* stash_nc_err(string_view sv) {
+        if (sv.empty()) return nullptr;
+        auto* p = static_cast<char*>(alloc_.allocate(sv.size()));
+        if (!p) return nullptr;
+        for (size_t i = 0; i < sv.size(); ++i) p[i] = sv[i];
+        return p;
+    }
+#endif
+
     /// Non-template transact with retry. Wraps transact_dispatch in retry_loop.
     Result<void> transact_retried(BuildFn build_fn, void* build_ctx,
                                   SaxDispatch dispatch,

tools/codegen/templates/api.hpp.j2

@@ -80,13 +80,43 @@ public:
 #if NOTE_SINGLETON
     // Static thunks — one copy each, shared by all endpoints via create_().
     // Eliminates per-type lambda instantiation in the factory methods.
+    //
+    // After execute(), if a Notecard "err" was captured, route the bytes
+    // through `stash_nc_err()` so they live in allocator-backed storage
+    // beyond the caller's stack. Generated `execute()` later builds an
+    // `ApiResult<...>(ErrorInfo{..., err.view()})` whose pointer would
+    // otherwise dangle the moment execute() returns. `stash_nc_err()`
+    // returns nullptr when no allocator is configured; the fallback to
+    // `NcErrorCapture::buf` is still dangling in that case, but no
+    // worse than before — and no fixed-size buffer is added for the
+    // common case.
+    //
+    // The stash call is skipped under NOTE_MINIMAL: AVR-class targets
+    // typically don't surface the textual error message (they branch on
+    // `result.error().code` and ignore the string), so the +250 bytes
+    // of flash for the durable-copy logic isn't worth it. The dangling
+    // `view()` quirk persists there, gated to that minimal build only.
     static Result<void> void_thunk_(void* p, string_view req, BuildFn fn, void* ctx, detail::NcErrorCapture& err) {
+#if NOTE_MINIMAL
         return static_cast<NcT*>(p)->execute_void(req, fn, ctx, err);
+#else
+        auto* nc = static_cast<NcT*>(p);
+        auto rv = nc->execute_void(req, fn, ctx, err);
+        err.set_durable(nc->stash_nc_err(err.view()));
+        return rv;
+#endif
     }
     static Result<void> generic_thunk_(void* p, string_view req, BuildFn fn, void* ctx,
             void* rsp, const FieldDesc* f, uint8_t n, detail::NcErrorCapture& err, bool& ex,
             void* body_ptr, BodyHandlerFactory body_factory) {
+#if NOTE_MINIMAL
         return static_cast<NcT*>(p)->execute_generic_with_body(req, fn, ctx, rsp, f, n, err, ex, body_ptr, body_factory);
+#else
+        auto* nc = static_cast<NcT*>(p);
+        auto rv = nc->execute_generic_with_body(req, fn, ctx, rsp, f, n, err, ex, body_ptr, body_factory);
+        err.set_durable(nc->stash_nc_err(err.view()));
+        return rv;
+#endif
     }
     static Result<void> send_thunk_(void* p, BuildFn fn, void* ctx) {
         return static_cast<NcT*>(p)->send_command(fn, ctx);