feat(quality): flag adj_factor that decreases between consecutive dates

[StackOverFlow11]

Why

The user made daily ex-dividend backtest correctness the top priority. Auditing it surfaced a defect class the quality layer had no check for.

tushare's cumulative adjustment factor grows with each corporate action — it has no mechanism to shrink. front_adjust multiplies raw prices by it, so a published decrease propagates straight into every downstream return.

A real instance existed and was found by hand: 920627.BJ oscillates between two factor values, giving alternating −57.27% / +134.04% steps (1/(1−0.572723)−1 = +134.04% — the two tails are the same event). I briefly mistook that +134% tail for a genuine corporate-action distribution before tracing it to one defective series. A frame-level check would have named it immediately.

Scope of the defect in the real cache

Full 5562-symbol cache, date-sorted and deduplicated. Only five symbols carry any change worse than −2%:

symbol	rows	worst	in an evaluated universe?
920627.BJ	171	−57.2723%	no (BSE)
920130.BJ	2	−51.2457%	no (BSE)
000545.SZ	1	−6.0643%	no
002898.SZ	1	−2.6299%	no
000998.SZ	1	−2.6360%	yes — CSI500

The one in-universe case is 000998.SZ, 2023-06-01: factor 11.267 → 10.970 (−2.64%) with the raw close moving +1.228% — no matching price discontinuity, and not a cache fetch boundary, so it is a defect in what tushare publishes rather than a caching artifact. Exposure is 1 pair out of ≈1.2M in the CSI500 window, so nothing is restated. But that was luck, not detection.

Full investigation: tmp/design/FINDING_adj_factor_seam_2026-07-21.md (the vintage-seam hypothesis was tested and rejected — 960 adjacent-day pairs straddle a fetch boundary, only 12 show any factor change, all positive, all on the annual ex-dividend peak, all with matching raw-price discontinuities).

Why the threshold is 2% and not zero

tushare rounds the published factor, so ex-dates routinely carry basis-point negative steps. Measured over CSI500 2021-07 → 2026-06: 1264 of 6932 factor changes (18.23%) are negative, and essentially all lie between −0.0008% and −0.08%. Those are rounding, not corruption. A zero threshold would emit 1264 findings and bury the five real ones.

Behaviour

WARNING, report-only — consistent with the rest of D3. It never filters a panel, repairs a value, or touches front_adjust or cache coverage. Wired into run_adj_factor_checks alongside the existing duplicate-key and positivity checks.

Verification

Against the real cache (three defective shards + two clean ones, 7191 rows):

1 finding(s): 0 hard / 1 warning / 0 info.
- [warning] adj_factor / decreasing_adj_factor: count=174
  examples: {000998.SZ, 2023-06-01, -0.02636}; {920130.BJ, 2023-03-31, -0.512457};
            {920627.BJ, 2021-01-07, -0.567923}; ...

174 matches the hand scan exactly (176 across all five symbols, minus the two not loaded here). The clean names contribute nothing.

Mutation evidence (each actually run):

mutation	test that dies
threshold 0.02 → 0.0	test_rounding_scale_negative_steps_are_not_flagged
per-symbol grouping removed	test_decreasing_adj_factor_does_not_bleed_across_symbols
date sort removed	test_decreasing_adj_factor_sorts_by_date_before_differencing

Gates

pytest 1734 passed (1728 baseline + 6) · ruff clean · phase0 ic_mean=0.9600, annual_return=0.8408 · secret scan 0