[kahrendt]

Many sendspin-cpp client cases in the conformance matrix fail because the adapter cannot see the messages the library exchanges: received audio hashes, raw chunk frames, and the protocol-baseline trace. This adds an opt-in plaintext trace, mirroring sendspin-server-cpp's ServerConfig::trace.

Change

• SENDSPIN_ENABLE_MESSAGE_TRACE: a host-only CMake option, off by default, with no Kconfig entry. With it off, the build is unchanged, ESP included.
• SendspinClientConfig::message_trace receives a SendspinTracedMessage for every message on the protocol task. Each one carries:
  • connection id, direction and stamp
  • the plaintext: inbound after decryption and reassembly, outbound before encryption (each fragment on its own), plus the cleartext handshake
  • audio_bytes: for a player audio chunk, the encoded audio it carries
• The pairing secrets a client sends (long_term_psk, wrapped_psk, wrapped_nonce_B) read "<redacted>".
• MessageTracer (src/message_trace.h) is owned per connection. The trace points are gated inline in connection.cpp and in NoiseTransport::encrypt_in_place().
• The gate is listed in CLAUDE.md, conventions.md, internals.md and the house-patterns skill. integration-guide.md documents the option.
• CI's test and TSan jobs build with the trace on; the build and no-opus jobs leave it off.

Notes

• Once this lands, the conformance adapter (adapters/sendspin-cpp/client/main.cpp in Sendspin/conformance) needs updating to turn the option on and read the trace.

Tests

• End-to-end against the fake encrypted server, read only through the trace. It asserts:
  • the exact opening sequence from client/init to server/activate, with the transport JSON readable
  • an audio chunk's audio_bytes
  • a single connection id, and stamps on the client clock
• A redaction table whose secret rows are built by the real pairing formatters, with control rows: a message without secrets and a binary message reach the trace unchanged and uncopied.
• Not covered by any test: inbound reassembly and outbound fragmentation.

[Copilot]

🟡 Changes recommended

Redaction tests bypass the real serializers, and normative threading documentation still contradicts the callback contract.

2 open findings

• Use pairing formatters in secret redaction tests · New
• Document message_trace as a main-loop threading exception · New

What changed in this PR

Adds a host-only plaintext protocol trace for conformance tooling.

Changes:

• Introduces per-connection tracing with pairing-secret redaction.
• Traces cleartext and encrypted transport messages.
• Adds tests, CI coverage, build gates, and documentation.

File	Description
include/​sendspin/​config.h	Defines the public trace API and config callback.
src/​message_trace.h	Declares the per-connection tracer.
src/​message_trace.cpp	Implements tracing, timestamps, audio sizing, and redaction.
src/​connection.h	Owns and configures each connection’s tracer.
src/​connection.cpp	Traces inbound and cleartext outbound messages.
src/​connection_manager.cpp	Installs configured tracing on new connections.
src/​noise_transport.h	Adds tracer integration to encrypted transport.
src/​noise_transport.cpp	Traces frames before encryption.
CMakeLists.txt	Adds the host-only build option.
cmake/​sources.cmake	Defines the optional trace source set.
tests/​test_message_trace.cpp	Tests tracing, audio metadata, and redaction.
tests/​CMakeLists.txt	Conditionally includes trace tests.
.github/​workflows/​ci.yml	Enables tracing in sanitizer test jobs.
docs/​integration-guide.md	Documents usage, fields, and threading.
docs/​internals.md	Documents trace architecture and gating.
docs/​conventions.md	Records allowed compile-gate locations.
CLAUDE.md	Updates architecture and build guidance.
.claude/​skills/​house-patterns/​SKILL.md	Updates repository review guidance.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The pass-through controls neither fully assert unchanged bytes nor follow the required control-row labeling convention.

0 open findings

2 resolved since last review

• Use pairing formatters in secret redaction tests
• Document message_trace as a main-loop threading exception

Previously missed (2)

In code that hasn't changed since last review

Verify unchanged secret bytes, not just pointer and length

tests/​test_message_trace.cpp:244

The no-secret controls only verify that the pointer was not copied; they do not verify the claimed unchanged bytes. A regression that reports the original pointer with a truncated plaintext_len would still pass, so also compare the captured value with row.sent.

Label redaction table accepting rows as Control

tests/​test_message_trace.cpp:221

These are the accepting controls for the redaction table, but they are not labeled as such. The repository’s testing convention requires accepting rows to be visibly marked Control: so a failure cannot be mistaken for a rejection case; rename both control rows accordingly.

🧠 Review effort: Balanced