[kahrendt]

Summary

server/state metadata still copied every string onto the heap through operator new, which aborts on ESPHome. Sendspin/spec#355 caps title, artist, album_artist and album at 255 bytes and artwork_url at 2048, so the text now lives in fixed blocks allocated at start() and a metadata state allocates nothing. Part of Sendspin/backlog#92.

Behaviour change: a value over its cap is cut at a UTF-8 boundary, with one warning per connection. METADATA_STRICT (in protocol.cpp, false for now) later turns that into a protocol error that closes the connection, as #256 staged for group_id.

Change

• Field opt-in: MetadataRoleConfig has one bool per text field (all true by default) and a buffer_location; add_metadata(MetadataRoleConfig config = {}) keeps the no-argument call. An unkept field is dropped at parse and takes no storage, e.g. {.artwork_url = false} saves 2,048 B per block.
• Three text blocks (9,204 B with every field, 3,060 B without the URL), PSRAM-preferring, allocated at start(): the slot's two places and the main loop's current state. A start() that cannot allocate them fails like artwork's.
• Hand-off: the protocol task copies an arrival's kept text into its slot place under the Inbox mutex (at most 3,068 B, the largest Inbox critical section). The main loop peeks at the timestamps, decides what is due with no lock held, and commits only if nothing arrived since; the public strings are filled from the current block outside the lock through ReservedText, reserved per kept field when the role is built.
• Scheduled states wait in the slot instead of on the main loop. ScheduledStateSlot (src/scheduled_state_slot.h) holds that protocol, and the color role now uses it too, with unchanged behaviour. One interleaving shifts: an arrival during a callback replaces a pending state that falls due in that same callback, the same outcome as the arrival landing just before the drain.

Tests

• Parse tables at both caps with Control: rows (cap, cap+1, 2/3/4-byte characters straddling it, lenient and strict) and a kept-fields table; an end-to-end check of kept and dropped fields.
• MetadataSlot.ThreeBlocksCarryEveryStateToTheListenerInOrder: a white-box table asserting after every step that the three blocks are a permutation, plus the delivered and pending titles, including a re-peek, cleanup, re-entrant stop() and restart. ScheduledStateSlot tests cover the decision table, generations, deciding with the Inbox mutex free and the slot's dirty bit.
• Alloc window for metadata states (an over-cap one, a scheduled one delivered later, one without text): 0. Mutants caught include a commit ignoring the sequence, a deadline decided under the lock, block aliasing, a missing re-peek, the same-tick loop removed and a settle/commit/reset polarity flip.
• Gaps: the strict close path and a failed block allocation at start() need a production seam.

Stack (ESP-IDF 5.5.4, esp32): protocol task 6,512 B -Os / 6,624 B -Og (was 6,544 / 6,688), within its 7,168 B default; every other task unchanged. tools/stack_usage/README.md updated.

[Copilot]

🟡 Changes recommended

Reentrant drains can commit stale metadata or deliver state early, while lifecycle-test callbacks can destroy their own executing closures before accessing captures, causing undefined behavior.

5 open issues

• Re-peek after nested drains by advancing the commit sequence · New
• Remove the live-clock deadline assertion from the test · New
• Keep the executing callback alive while invoking it · New
• Document metadata’s bounded-copy exception to the parsing contract · New
• Remove unreachable late-registration fallback and state · New

What changed in this PR

Replaces per-message metadata text allocations with fixed storage allocated at startup, improving embedded reliability while letting consumers omit unused text fields.

Changes:

• Adds MetadataRoleConfig field selection, memory placement, and UTF-8-safe text limits.
• Introduces three reusable text blocks and shared scheduled-state handling for metadata and color.
• Expands parser, lifecycle, and allocation tests; updates consumer and architecture documentation.

File	Description
tools/​stack_usage/​README.md	Updates measured protocol-task stack bounds.
tests/​test_role_deactivation.cpp	Adapts cleanup checks to scheduled slots.
tests/​test_protocol.cpp	Tests text caps, truncation, and field selection.
tests/​test_inbox.cpp	Tests scheduled-slot decisions, generations, and locking.
tests/​test_encrypted_lifecycle.cpp	Checks delivered fields, truncation, and pending metadata.
tests/​test_client_lifecycle.cpp	Exercises three-block ownership, teardown, and restart.
tests/​test_allocations.cpp	Adds zero-allocation checks for metadata states.
tests/​README.md	Documents expanded test coverage.
tests/​CMakeLists.txt	Configures and documents private test access.
src/​teardown_tracker.h	Shares generation checks with peek-based drains.
src/​scheduled_state_slot.h	Adds shared timestamp-based state storage and draining.
src/​protocol.cpp	Parses bounded metadata text without owning strings.
src/​protocol_messages.h	Defines metadata bounds, layouts, views, and outcomes.
src/​metadata_role.cpp	Implements reusable text storage and public-state filling.
src/​metadata_role_impl.h	Holds configuration, text blocks, and scheduled state.
src/​inbox.h	Adds persistent slot read and settle operations.
src/​controller_role_impl.h	Updates a comment distinguishing controller scheduling needs.
src/​connection.h	Tracks the once-per-connection truncation warning.
src/​color_role.cpp	Uses the shared scheduled-state drain.
src/​color_role_impl.h	Replaces held state with a scheduled slot.
src/​client.cpp	Allocates metadata blocks at startup and accepts configuration.
src/​client_dispatch.cpp	Dispatches metadata parsing and handles truncation or rejection.
include/​sendspin/​metadata_role.h	Updates construction and documents bounded text behavior.
include/​sendspin/​config.h	Adds metadata field and memory-placement settings.
include/​sendspin/​client.h	Exposes optional metadata configuration.
docs/​internals.md	Describes scheduling, text ownership, and memory flow.
docs/​integration-guide.md	Documents configuration, text limits, and storage costs.
docs/​conventions.md	Documents scheduled-slot generation handling.
CLAUDE.md	Updates architecture and allocation-test guidance.

_{Review effort: Max}