fix(AR-004): make the channel byte counter measure the payload

`kpn::ChannelDataSize<T>` is what a channel reports as bytes pushed, and its
primary template returns `sizeof(T)`. It was never specialised in this repo —
only in a KPN example — so every message type reported its header size. Each
of them is a few vectors and a `cv::Mat` header owning megabytes on the heap,
so a message carrying a full decoded frame was reported at roughly 200 bytes
against 5.9 MB at 1080p. Four orders of magnitude.

That is not a cosmetic stat. It is the one instrument for choosing channel
capacities against a memory ceiling — the open half of AR-004 — and anyone
who read the MB/s column to size a channel was reading fiction. The gap could
not be measured with the tool that exists to measure it.

Every message embeds `Frame source`, so this is not confined to the
crop-carrying channels: the full decoded image rides the whole chain, and the
byte figure now says so.

Two things worth stating about what the number means. `cv::Mat` is
reference-counted, so one frame referenced from several messages is counted
once per reference — an upper bound on distinct bytes, and the right bound for
"what would this channel keep alive if nothing else held it", which is the
question a capacity answers. And an eof sentinel carries no image, so it costs
only its header and is not charged for one.

Declared against a forward declaration of the primary template rather than by
including <kpn/channel.hpp>, so the message definitions keep no dependency on
the framework carrying them, and any translation unit that can see these types
also sees their sizes — which is what stops one channel being instantiated
with the default while another gets the specialisation.

Verified in both directions: with the specialisations removed, three of the
five cases fail, `SceneAnnotation` reporting 40 bytes against the 37,632 its
single 112x112 crop occupies. 145/145 with them.

No behaviour change — this only corrects what is reported. Choosing capacities
against the corrected numbers is the next commit.

TRACES: AR-004 | SR-002

tests/CMakeLists.txt

@@ -28,6 +28,7 @@ add_executable(sae_tests
     test_embedding_dump.cpp
     test_audio_signature.cpp
     test_benchmark.cpp
+    test_channel_bytes.cpp
     ${CMAKE_SOURCE_DIR}/src/backends/gemm_backend.cpp
     ${CMAKE_SOURCE_DIR}/src/gallery/gallery_store.cpp
     ${CMAKE_SOURCE_DIR}/src/audio_signature.cpp

tests/test_channel_bytes.cpp

@@ -0,0 +1,109 @@
+// Channel byte accounting for the pipeline message types.
+//
+// TRACES: AR-004 | SR-002
+//
+// kpn::ChannelDataSize<T> is what a channel reports as bytes pushed, and its
+// primary template returns sizeof(T). Every message type here is a handful of
+// vectors and a cv::Mat header owning megabytes on the heap, so unspecialised
+// the diagnostics reported ~200 bytes for a message carrying a full decoded
+// frame — off by four orders of magnitude at 1080p.
+//
+// That is the instrument for choosing channel capacities against a memory
+// ceiling, which is the open half of AR-004. These cases assert it measures the
+// payload rather than the header, because a stat that is quietly wrong is worse
+// than no stat: it was read as evidence.
+#include <catch2/catch_test_macros.hpp>
+
+#include <kpn/channel.hpp>
+
+#include "types.hpp"
+
+namespace {
+
+Frame frame_with_image(int w, int h) {
+    Frame f;
+    f.image = cv::Mat(h, w, CV_8UC3, cv::Scalar(0, 0, 0));
+    f.timestamp_sec = 1.0;
+    return f;
+}
+
+}  // namespace
+
+TEST_CASE("frame bytes count the decoded image, not the header", "[channel_bytes]") {
+    const Frame f = frame_with_image(1920, 1080);
+    const std::size_t got = kpn::ChannelDataSize<Frame>::bytes(f);
+
+    // 1920 * 1080 * 3 = 6,220,800 payload bytes.
+    REQUIRE(got >= 1920u * 1080u * 3u);
+    // The header is a rounding error next to it; this is the assertion that
+    // fails on the unspecialised default.
+    CHECK(got > 100u * sizeof(Frame));
+}
+
+TEST_CASE("an empty frame costs only its header", "[channel_bytes]") {
+    // The eof sentinel carries no image, and must not be charged for one.
+    Frame eof;
+    eof.eof = true;
+    CHECK(kpn::ChannelDataSize<Frame>::bytes(eof) == sizeof(Frame));
+}
+
+TEST_CASE("crops and embeddings are counted on top of the frame", "[channel_bytes]") {
+    // The case AR-003 created: a crowd frame occupies one slot exactly as an
+    // empty one does, and only the byte figure distinguishes them.
+    EmbeddedSceneFrame v;
+    v.source = frame_with_image(640, 360);
+    const std::size_t bare = kpn::ChannelDataSize<EmbeddedSceneFrame>::bytes(v);
+
+    constexpr int kFaces = 60;
+    for (int i = 0; i < kFaces; ++i) {
+        v.faces.push_back({});
+        v.crops.emplace_back(112, 112, CV_8UC3, cv::Scalar(0, 0, 0));
+        v.embeddings.emplace_back();
+    }
+    const std::size_t crowded = kpn::ChannelDataSize<EmbeddedSceneFrame>::bytes(v);
+
+    // 60 crops at 112*112*3 = 2,257,920 bytes, plus 60 * 2 KiB of embeddings.
+    CHECK(crowded - bare >= kFaces * (112u * 112u * 3u + sizeof(Embedding)));
+    // And the crowd frame really is the multiple of the empty one that the
+    // item-count capacity cannot see: 640x360x3 is ~691 KB, the crops ~2.26 MB.
+    CHECK(crowded > 3 * bare);
+}
+
+TEST_CASE("every message type on a channel measures its payload", "[channel_bytes]") {
+    // A specialisation missing for any one of these silently reverts that
+    // channel to sizeof(T), which is exactly how this went unnoticed.
+    const Frame f = frame_with_image(320, 240);
+    const std::size_t img = 320u * 240u * 3u;
+
+    SceneFrame sf;        sf.source = f;
+    AlignedSceneFrame af; af.source = f;
+    EmbeddedSceneFrame ef; ef.source = f;
+    TrackedSceneFrame tf; tf.source = f;
+    MatchedSceneFrame mf; mf.source = f;
+
+    CHECK(kpn::ChannelDataSize<SceneFrame>::bytes(sf)         >= img);
+    CHECK(kpn::ChannelDataSize<AlignedSceneFrame>::bytes(af)  >= img);
+    CHECK(kpn::ChannelDataSize<EmbeddedSceneFrame>::bytes(ef) >= img);
+    CHECK(kpn::ChannelDataSize<TrackedSceneFrame>::bytes(tf)  >= img);
+    CHECK(kpn::ChannelDataSize<MatchedSceneFrame>::bytes(mf)  >= img);
+
+    // SceneAnnotation carries no source frame — only the actors it identified,
+    // each with its own crop.
+    SceneAnnotation sa;
+    sa.visible_actors.push_back({});
+    sa.visible_actors.back().crop = cv::Mat(112, 112, CV_8UC3, cv::Scalar(0, 0, 0));
+    CHECK(kpn::ChannelDataSize<SceneAnnotation>::bytes(sa) >= 112u * 112u * 3u);
+}
+
+TEST_CASE("a shared image is charged to each message holding it", "[channel_bytes]") {
+    // cv::Mat is reference-counted, so a frame referenced from several messages
+    // is counted once per reference. The sum is an upper bound on distinct
+    // bytes, and the right bound for "what would this channel keep alive if
+    // nothing else held it" — which is the question a capacity answers.
+    const Frame f = frame_with_image(320, 240);
+    SceneFrame a; a.source = f;
+    SceneFrame b; b.source = f;   // shares the same pixel buffer
+
+    CHECK(kpn::ChannelDataSize<SceneFrame>::bytes(a)
+          == kpn::ChannelDataSize<SceneFrame>::bytes(b));
+}