feat: add referenceTimestamp to ConsumerContext to prevent clock drif…

[nil-malh]

📝 Description

Adds the ktestify-core groundwork needed to support multi-row DataTable-driven producer/consumer steps in ktestify-cucumber without reintroducing the offset-skew problem raised in the original discussion.

Two independent, composable additions:

1. TopicUtils.assertSingleTopic(List<Topic>) (new TopicMismatchException) ,a transport-agnostic guard rail that asserts a list of resolved Topics all point to the same physical topic (namespaced name + type). Any caller driving one physical operation (producer send, consumer fetch) from multiple DataTable rows can reuse this to reject mixed-topic input before doing any work, instead of silently acting on the first row or partially completing.
2. ConsumerContext.referenceTimestamp (nullable Long, epoch ms), when set, KafkaRecordFetcher.calculateDeltaTime() uses it as "now" instead of calling System.currentTimeMillis() live at seek time. This lets a caller capture "now" once and reuse it across several sequential fetches, so their consumerDeltaTime seek windows are computed identically instead of drifting apart as earlier fetches take time to complete.

Neither change alters existing behavior when unused: referenceTimestamp defaults to null (live clock, same as before), and TopicUtils is a new opt-in utility with no existing call sites in this module.

This is the core-side dependency for the ktestify-cucumber fix to issue #38, the ktestify-cucumber PR builds ConsumerContext/ProducerContext for each DataTable row using these two primitives.

Resolves #38

---

🔄 Type of Change

• ✨ New feature — non-breaking change that adds functionality

---

✅ Pre-Merge Checklist

Code Quality

• My code follows the Palantir Java Format style (passes mvn spotless:check)
• I have added or updated Javadoc on public types and methods

Tests

• I have added unit tests that cover the new / changed behaviour
• All existing and new tests pass locally (mvn verify)
• JaCoCo line coverage ≥ 70 % is maintained
• Tests using Testcontainers are isolated and do not leave containers running

Licensing

• Apache 2.0 license header has been added to every new source file (using spotless)

[github-actions]

📋 Unreleased Changelog Preview

This is what the next release notes will look like based on commits in this PR.

Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

♻️ Refactoring

• Remove date content-sniffing and implement type-driven date comparison — @nil-malh

✨ Features

• Switched to centralised GH Actions — @nil-malh

• Enhance deepEquals method to support dot-notation for excluded keys — @nil-malh

• Add referenceTimestamp to ConsumerContext to prevent clock drift in fetches

---

Generated by git-cliff

---

🔄 Run #136 · Thu, 06 Aug 2026 11:42:31 GMT

[github-actions]

✅ Test Results

	Metric	Count
✅	Passed	682
❌	Failed	0
⏭️	Skipped	0
📊	Total	682

✅ Coverage

	Type	Coverage	Covered / Total
📏	Lines	83.5%	1780 / 2131
🌿	Branches	73.1%	556 / 761
🔧	Methods	84.2%	372 / 442

---

🔄 CI run #155 · Thu, 06 Aug 2026 11:45:43 GMT