From 3c509d48c92de1f58e2503bf8da1196dcf341874 Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Fri, 31 Jul 2026 21:04:28 +0200 Subject: [PATCH] =?UTF-8?q?feat(core/abi):=20report=5Fphase=20earns=20its?= =?UTF-8?q?=20version=20=E2=80=94=20C=20ABI=2013=20->=2014?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `punktfunk_connection_report_phase` (fa822744, coherence tail 1d31e4c5) and the `PUNKTFUNK_CLIENT_CAP_PHASE_LOCK` mirror const (7cf71dd2) grew the embeddable C surface without moving ABI_VERSION. Every prior additive entry in that doc list bumped it — v3's wake_on_lan, v5's next_rumble2, v8's clipboard block, v13's send_pen — precisely so an embedder can ask punktfunk_abi_version() whether the function it wants to link is there. Left at 13, the one number that answers that question said "no report_phase" about a core that has one. The header was already regenerated with both symbols, so it carried the new surface under the old number; the regen here changes exactly the #define and its doc block and nothing else, which also confirms the committed header was otherwise current. Additive and capability-gated: the host arms on report receipt, the wire grows only PhaseReport (0x32) — a control message an old host never reads — and a strict-prefix append on the 0xCF host-timing tail, so WIRE_VERSION stays 2. No in-tree caller compares ABI_VERSION against a literal; mgmt/tests.rs asserts against the symbol. Verified: cargo build -p punktfunk-core regenerates include/punktfunk_core.h to exactly this diff; punktfunk-core lib suite 134/134; rustfmt clean. The C ABI harness cannot run on this Mac (`ld: library 'opus' not found`, the documented pre-existing local linker gap) — CI's Linux leg is the gate for it. --- crates/punktfunk-core/src/lib.rs | 8 +++++++- include/punktfunk_core.h | 8 +++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/crates/punktfunk-core/src/lib.rs b/crates/punktfunk-core/src/lib.rs index ae25c961..c482a017 100644 --- a/crates/punktfunk-core/src/lib.rs +++ b/crates/punktfunk-core/src/lib.rs @@ -114,7 +114,13 @@ pub use stats::Stats; /// v13: added `punktfunk_connection_send_pen` — the stylus wire plane /// (design/pen-tablet-input.md): a client sends `RICH_PEN` sample batches once the host /// advertises `HOST_CAP_PEN`. Additive and capability-gated, so [`WIRE_VERSION`] is unchanged. -pub const ABI_VERSION: u32 = 13; +/// v14: added `punktfunk_connection_report_phase` + the `PUNKTFUNK_CLIENT_CAP_PHASE_LOCK` mirror +/// — the phase-locked capture reporter (design/phase-locked-capture.md): a client that advertises +/// the cap reports its next display latch (already converted to host clock), the panel period, an +/// uncertainty and the circular arrival-lead statistic the host's controller steers on. Additive; +/// the wire grows only a new control message (`PhaseReport`, 0x32) an old host never reads and a +/// strict-prefix append on the 0xCF host-timing tail, so [`WIRE_VERSION`] is unchanged. +pub const ABI_VERSION: u32 = 14; /// The punktfunk/1 **wire** version — what `Hello`/`Welcome` carry and hosts equality-check. /// Deliberately its own constant: [`ABI_VERSION`] tracks the embeddable **C surface** diff --git a/include/punktfunk_core.h b/include/punktfunk_core.h index fd52a333..2bc5d07e 100644 --- a/include/punktfunk_core.h +++ b/include/punktfunk_core.h @@ -52,7 +52,13 @@ // v13: added `punktfunk_connection_send_pen` — the stylus wire plane // (design/pen-tablet-input.md): a client sends `RICH_PEN` sample batches once the host // advertises `HOST_CAP_PEN`. Additive and capability-gated, so [`WIRE_VERSION`] is unchanged. -#define ABI_VERSION 13 +// v14: added `punktfunk_connection_report_phase` + the `PUNKTFUNK_CLIENT_CAP_PHASE_LOCK` mirror +// — the phase-locked capture reporter (design/phase-locked-capture.md): a client that advertises +// the cap reports its next display latch (already converted to host clock), the panel period, an +// uncertainty and the circular arrival-lead statistic the host's controller steers on. Additive; +// the wire grows only a new control message (`PhaseReport`, 0x32) an old host never reads and a +// strict-prefix append on the 0xCF host-timing tail, so [`WIRE_VERSION`] is unchanged. +#define ABI_VERSION 14 // The punktfunk/1 **wire** version — what `Hello`/`Welcome` carry and hosts equality-check. // Deliberately its own constant: [`ABI_VERSION`] tracks the embeddable **C surface**