[petesramek]

Description

Layer 4 of the TinyLink remediation sequence (stacked on layer 3, petesramek-payload-type-safety). Replaces every direct ++_stats.* in the engine with the saturating Stats::increment(TelemetryEvent) API, and adds tracking of whether a valid application sequence has been received so sendAck() cannot acknowledge a frame that was never accepted.

Closes #

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactor / code quality improvement
• CI / build / tooling change

Changes

Files: src/TinyLink.h, test/test_tinylink/test_main.cpp, CHANGELOG.md.

• All 14 direct counter increments now call _stats.increment(TelemetryEvent::X) (PacketReceived, CobsDecodeFailed, ChecksumMismatch, PacketLengthMismatch, PayloadSizeMismatch, PacketEncodeFailed, CobsEncodeFailed, InterByteTimeout, AckTimeout, ReceiveOverflow, UnexpectedMessageType, UnexpectedSequence, InvalidAckResult, InvalidHandshake). Counters saturate at UINT32_MAX.
• New private _hasReceivedSequence. Set when an application frame is accepted; sendAck() returns false without writing while it is unset.
• Stays valid across callback delivery, read(), flush().
• Invalidated by: construction, reset(), begin(), a valid peer handshake Request (peer restart; the old frame is stale), and an unsupported-version handshake (Incompatible).
• Rejected frames (before connection, wrong payload size) do not validate the sequence.

Public behavior changes

• sendAck() now returns false (nothing written) until an application frame is accepted, and again after the invalidating transitions above.
• Counters no longer wrap (previously unreachable in practice, now guaranteed).

Checklist

• I have read the Contributing Guidelines.
• My branch is up-to-date with the target branch.
• My changes compile without errors or warnings on the affected platform(s).
• I have added or updated tests to cover my changes.
• All existing tests pass (pio test -e native).
• I have updated relevant documentation (README, inline comments, etc.).
• My commit messages follow the Conventional Commits format. (first commit does not; second does)
• I have added a CHANGELOG.md entry under [Unreleased].

Testing Done

pio test -e native on Windows: 121 test cases, 121 succeeded (111 existing + 10 new).

New tests: testEngineCountersSaturateAtMaximumInsteadOfWrapping, testSendAckReturnsFalseBeforeAnyApplicationFrameIsAccepted, testRejectedApplicationFramesDoNotValidateAckSequence, testAckSequenceRemainsValidAfterCallbackDelivery, ...AfterRead, ...AfterFlush, testResetInvalidatesAckSequence, testBeginInvalidatesAckSequence, testPeerHandshakeRequestInvalidatesAckSequence, testIncompatibleHandshakeInvalidatesAckSequence. Construction is covered by the first. Existing testSendAckPropagatesFailedAndPartialWrites and testClosedTransportRejectsWritesAndDoesNotBlockRecovery now accept an application frame first so they still exercise write failures.

Assumptions and limitations

• Lifecycle decision: only transitions that end or restart the current session invalidate the sequence (begin(), peer handshake request, Incompatible). A handshake Response, ACK timeout and log frames do not.
• The saturation test preloads counters through a test-only friend struct TinyLinkStatsAccess declared in TinyLink; no public/private state is exposed to users. It drives 12 of 14 events through the engine; PacketEncodeFailed and CobsEncodeFailed are unreachable with valid payload sizes, so they rely on the shared Stats::increment mapping (covered in test_stats).
• CI compile checks for non-native platforms were not run locally.