[kahrendt]

Summary

The pairing record store allocated on the heap after start(): each record held its psk_id and server_id as 43-character std::strings, the record and dirty-slot vectors grew on the protocol task, and every flush built a vector of string-keyed, vector-backed blobs. That last one also runs after every playback handoff to another paired server, which rewrites the order blob. Part of Sendspin/backlog#92; the pairing exchange itself (CPace, the PRS, pairing notes) follows in a separate PR.

No public API change: SendspinPairingRecord and the persistence codec keep their signatures.

Change

• Records are held internally as PairingRecord (new private src/pairing_record.h) with IdText ids and a PSK wiped on destruction; the store, PairingOutcome and the connection's pending record use it. Its encoder, encode_pairing_record_into(), shares one layout helper with the public encode_pairing_record(), so the two cannot diverge. The fallible psk_id_for() returns std::optional<IdText>.
• The flush takes the owed slots as a bitset under the lock, then encodes each write under the lock into one stack buffer and saves it outside, so a slow NVS commit still never holds the mutex the protocol task needs. Slot writes now go out in slot order; a slot changed mid-flush may be written twice.
• records_ is reserved to max_records_ at construction (about 123 B of internal RAM per record, noted in the integration guide), and a re-pair at capacity retires the old record before inserting, so the store never holds cap + 1.

Tests

• sendspin_alloc_tests gains a playback-handoff flush window and a server/unpair flush window, both 0 (were 2 and 4), and a pairing_psk pairing window at 4 (was 11; what remains is the pairing note list and the listener's std::string arguments).
• ChangesAfterConstructionKeepTheReservedRecords pins that records_ never reallocates; the cap table's ceiling row checks the 255-byte order blob.
• Mutants caught: a std::vector order blob (fails both flush windows), dropping the reserve, inserting before the retire at re-pair, and a move-assigned reorder at load.

Stack (ESP-IDF 5.5.4, esp32): the protocol task measures 6,544 B at -Os and 6,688 B at -Og bounded, 5,920 / 6,144 reachable, under the unchanged 7,168 B default. The main-loop flush frame is 384 B at -Os, on the consumer's own task.

[Copilot]

🟡 Changes recommended

The zeroization suite lacks a PairingRecord destructor test, leaving erasure of its stored and pending long-term keys unverified.

3 open issues

• Add PairingRecord to PSK zeroization test · New
• Document RAM reservation in max_pairing_records header comment · New
• Use id_text helper for test PSK identifier · New

What changed in this PR

Reduces heap allocation in pairing-record storage and persistence, supporting the library’s embedded memory constraints without changing the public API or persistence format.

Changes:

• Introduces inline-ID pairing records and reserves record storage to the configured capacity.
• Replaces heap-backed flush batches with a bitset and reusable stack buffer, keeping persistence calls outside the mutex.
• Adds allocation and capacity regression coverage and updates memory and stack documentation.

File	Description
tools/​stack_usage/​README.md	Updates measured protocol-task stack bounds.
tests/​test_record_store.cpp	Adds capacity and storage-stability checks; adapts record handling.
tests/​test_pairing_state_machine.cpp	Adapts pending-record setup to PairingRecord.
tests/​test_noise_transport.cpp	Converts handshake fixture records to the internal type.
tests/​test_noise_rehandshake.cpp	Converts re-handshake fixture records to the internal type.
tests/​test_encrypted_lifecycle.cpp	Adapts eviction and unpair scenarios.
tests/​test_allocations.cpp	Adds handoff, unpair, and pairing allocation windows.
tests/​loopback_connection.h	Adapts loopback record setup.
tests/​CMakeLists.txt	Clarifies the white-box storage-address check rationale.
src/​record_store.h	Defines bounded dirty-slot tracking and reusable write-buffer helpers.
src/​record_store.cpp	Reserves storage, retires before insertion, and encodes writes individually.
src/​persistence_codec.cpp	Shares the encoding layout between public and internal records.
src/​pairing_record.h	Adds inline-ID records with destruction-time key wiping.
src/​crypto/​keys.h	Declares inline results for fallible PSK-ID derivation.
src/​crypto/​keys.cpp	Encodes fallible PSK-ID results without a heap-backed string.
src/​connection.h	Stores pending pairings using the internal record type.
src/​connection_manager_pairing.cpp	Passes inline records into pending pairing state.
src/​client_dispatch.cpp	Passes finalized records through the revised store interface.
docs/​internals.md	Updates the allocation model for records and flushes.
docs/​integration-guide.md	Documents reserved RAM per configured record.
CLAUDE.md	Documents the expanded allocation-test windows.

_{Review effort: Max}