fix(cdc): null-key ordering checks, zero stale_after, epoch event times, replay_risk docs

[kevincostner17]

Summary

Fixes four fd.cdc_profile bugs:

• Null CDC keys are now ordering-checked (cdc_profile skips ordering/lateness checks for rows whose key is null #325). The per-key running watermark grouped with the default dropna=True, so rows with a null key were never classified as out_of_order or late. Grouping now uses dropna=False, so null-key rows form one group of their own. A new missing_key warning reports how many rows have a null key. The trust penalty formula is unchanged.
• stale_after=0 no longer raises ZeroDivisionError (cdc_profile raises ZeroDivisionError when stale_after is zero #326). The freshness penalty is age / stale_after. At zero it now takes the limit of that formula: 1.0 for any positive age and 0.0 otherwise, which matches the stale defect. A negative stale_after raises ValueError.
• Integer epoch event times are read in the right unit (cdc_profile reads integer epoch event times (e.g. ts_ms) as nanoseconds, giving 1970 dates #327). Numeric event-time columns such as Debezium ts_ms were read as nanoseconds, giving 1970 dates. They now use the shared parse_timestamps helper (added in fix(timeseries): epoch and mixed-offset timestamps, MAD zero-scale, stable anomaly columns, cdc tz #360), with the same unit guess as clean_timeseries. A new event_time_unit keyword ("s", "ms", "us", "ns") sets the unit explicitly.
• replay_risk docs match behaviour (cdc_profile replay_risk never fires for late-only batches, contrary to its docstring #328). Per the maintainer decision, the code is unchanged. The replay_threshold docstring now says at least one duplicate-key row is required, so late-only batches never raise replay_risk.

Behaviour changes: numeric event-time columns get a guessed epoch unit instead of always nanoseconds (small integers such as row numbers are read as seconds); key columns with nulls add a missing_key warning (no effect on passed or penalties); negative stale_after raises ValueError.

Tests

New tests/test_cdc_profile_fixes.py covering each issue's repro plus:

• null keys mixed with other keys, and a null-key row with an explicit watermark
• zero-age and negative stale_after
• all four epoch units, both guessed and explicit, plus float and nullable-integer columns
• invalid event_time_unit
• a test pinning the late-only replay_risk behaviour

Verification

• ruff check .: passes
• mypy src/freshdata: no issues
• Python 3.12 / pandas 2.3.3: 5061 passed, 6 skipped
• Python 3.9 / pandas 1.5.3: 5057 passed, 10 skipped

Closes #325
Closes #326
Closes #327
Closes #328

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 8e011cff-90c6-46d6-9cab-f3d1d0ce9f8c

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

FreshData benchmark report — performance

• freshdata: ?
• python: ?
• platform: ?

fixture	n_rows	n_cols	p50 s	p95 s	peak MB	repair %	false-repair %	preserve %	trust	monotonic	export %

Authored-code reduction (Metric 6)