pit-adjuster 0.1.0__tar.gz

pit_adjuster-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pit Adjuster contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pit_adjuster-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: pit-adjuster
+Version: 0.1.0
+Summary: Point-in-time fixed-basis back-adjustment engine: adjustment factor chains, static forward-adjustment detection, snapshot equivalence checks.
+License-Expression: MIT
+Keywords: point-in-time,back-adjustment,hfq,qfq,corporate-actions,quant,pandas-free
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pit-adjuster
+
+Point-in-time fixed-basis back-adjustment engine for daily price history:
+rebuild prices so that **any day reads exactly what that day could have
+known** — plus drift detection for vendors that silently switch adjustment
+conventions. Python 3.11+, **zero dependencies**, Windows / Linux / macOS.
+
+![adjustment chain](https://img.shields.io/badge/deps-0-brightgreen)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+
+**Status:** v0.1 — alpha. The adjustment math is battle-tested inside a
+production research pipeline, but this standalone package is new: expect the
+CLI and schema to shift before v1.0.
+
+## Why this exists
+
+A-share (and most equity) history arrives from vendors in **current-vintage**
+adjusted form. Two silent dangers:
+
+1. **The convention itself is not point-in-time.** Prices you see today
+   embed every adjustment event that ever happened — including events that
+   were announced *after* a historical date. A backtest that uses them reads
+   the future.
+2. **Vendors switch conventions silently.** One day your data source starts
+   serving forward-adjusted prices where it served back-adjusted prices
+   yesterday. Nothing in the CSV changes shape; every historical signal
+   silently changes value.
+
+`pit-adjuster` rebuilds history from two ingredients — current-vintage
+forward-adjusted (qfq) bars plus a **point-in-time corporate-action archive**
+— into a fixed-basis back-adjusted (hfq) chain where each day's price depends
+only on events whose ex-date is on or before that day. Then it *checks*: did
+the rebuild invert the vendor chain correctly, and does the vendor chain
+still agree with live raw prices today?
+
+## Philosophy
+
+Price history must be reversible. A research pipeline that cannot prove its
+prices were knowable in the past is not doing backtesting — it is doing
+wishful thinking. `pit-adjuster` treats **look-ahead freedom as a
+verifiable property**, not a style preference:
+
+- **PIT principle** — every price, factor, and calibration depends only on
+  information available at that historical point. See
+  [Kelly et al., "Scaling Point-in-Time Language Models"](https://www.nber.org/papers/w35247)
+  (NBER w35247) and
+  [Look-Ahead-Bench](https://ar5iv.labs.arxiv.org/html/2601.13770)
+  (arXiv:2601.13770) for why the whole industry is converging on this.
+- **Look-ahead bias is measurable** — Daniel, Sornette & Wohrmann (2008),
+  ["Look-Ahead Benchmark Bias in Portfolio Performance Evaluation"](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=1289222)
+  (arXiv:0810.1922) quantify how ex-post benchmark construction inflates
+  performance. A vendor that silently swaps adjustment conventions is doing
+  exactly this, inside your price column.
+- **Formal ground** — Fonseca (2026),
+  ["Look-Ahead-Freedom as Temporal Non-Interference"](https://econpapers.repec.org/paper/arxpapers/2607.04958.htm)
+  (arXiv:2607.04958) proves look-ahead-freedom is *undecidable* in general
+  (Π⁰₁-hard when availability depends on data values), but admits a
+  **linear-time decidable type-effect system on the value-independent
+  fragment** — windowing, resampling, joins, PIT and vintage reads.
+
+**Honest boundary:** this package implements verifiable checks for the
+value-independent fragment of the problem (factor chains, ex-date ordering,
+snapshot equivalence, chain inversion). For the general value-dependent case
+we fall back to heuristic guards and say so explicitly — verifiability is
+claimed only where the theory allows it.
+
+## Quick start
+
+```bash
+# install from PyPI (once published)
+pip install pit-adjuster
+
+# or run without installing anything:
+#   PYTHONPATH=src python -m pit_adjuster --help
+
+# try it on synthetic data (builds a fake qfq history + action archive,
+# rebuilds to hfq, runs invert-check and drift-check)
+python examples/demo.py
+```
+
+Rebuild your own history:
+
+```bash
+padj rebuild \
+  --bars bars.json --actions actions.json \
+  --as-of 2026-08-11 --code 600000 --out hfq.json
+
+padj invert-check --bars hfq.json --actions actions.json --as-of 2026-08-11
+padj drift-check --bars hfq.json --actions actions.json \
+  --as-of 2026-08-11 --live live_closes.json
+```
+
+`padj rebuild` is the workhorse: it inverts the vendor qfq chain back to raw
+prices, then re-applies only events whose ex-date is on or before each bar
+date (fixed basis at the archive coverage start). Raw open/close are kept
+alongside adjusted prices so execution-level work can map back to nominal
+prices.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `rebuild` | Rebuild bars to fixed-basis hfq: `open/high/low/close` adjusted, `raw_open/raw_close` nominal, `adj_factor` cumulative multiplier, volume normalized to shares |
+| `invert-check` | Ex-date continuity sanity check: is `raw_{ex-1} × factor_e ≈ raw_ex`? Informational — real ex-dates carry overnight returns, so violations can be false positives |
+| `drift-check` | **Static forward-adjustment detection.** Compares inverted raw closes against live raw closes; divergence above tolerance is authoritative — a vendor chain that no longer matches the archive |
+| `snapshot-equivalence` | Compare two rebuilt outputs (e.g. old and new pipeline versions) date-by-date within tolerance — the "did anything change?" gate |
+| `version` | Print version |
+
+Global flags: `--help` on every subcommand; JSON outputs via `--out` where
+supported; everything else prints a human-readable summary.
+
+## Data model
+
+**Bars** — a JSON list of daily bars, each with at least `date` (ISO) and
+`close`; `open/high/low/volume/amount/turnover` are preserved through the
+rebuild:
+
+```json
+{"date": "2026-06-12", "open": 95.0, "high": 96.0, "low": 94.5, "close": 95.5, "volume": 1234500}
+```
+
+**Actions** — a point-in-time corporate-action archive, one record per
+event, with `ex_date`, `adjustment_factor` and `available_at`:
+
+```json
+{"ex_date": "2026-06-15", "adjustment_factor": 0.95, "available_at": "2026-06-14T18:00:00", "action_type": "cash_dividend_stock_distribution"}
+```
+
+Invalid records (missing ex-date, non-positive or non-finite factor) are
+dropped; only events with `ex_date <= as_of_date` participate. The schema
+lives in [schema/corporate-action.schema.json](schema/corporate-action.schema.json).
+
+## Adjustment math
+
+Standard A-share factor math (as documented by exchange reference-price
+rules):
+
+```
+factor_e = (prior_close - cash) / (prior_close * (1 + bonus + transfer))
+qfq_t    = raw_t * prod_{e: ex_date_e > t} factor_e
+hfq_t    = raw_t * prod_{e: ex_date_e <= t} (1 / factor_e)
+```
+
+`rebuild` inverts the vendor qfq chain back to raw prices, then applies the
+hfq chain with a fixed basis at the archive coverage start. **Key property
+(under test):** hfq and qfq yield identical adjusted *returns* for the same
+factor chain, while hfq additionally guarantees that a price at time `t` is
+untouched by events with ex-date after `t`.
+
+Volume normalization follows the A-share convention: most codes store volume
+in lots (×100 to shares); STAR-market codes (688/689 prefixes) store native
+shares. Both are parameterizable — see `--volume-to-shares` and the
+`native_share_prefixes` argument in `rebuild_bars`.
+
+## Verification model
+
+`pit-adjuster` never trusts its inputs:
+
+- `invert-check` — factor continuity at ex-dates (sanity, false-positive
+  tolerant)
+- `drift-check` — inverted raws vs live raws (authoritative divergence
+  detection; this is the "static forward-adjustment detector" — if a vendor
+  swaps conventions, this fires)
+- `snapshot-equivalence` — before/after equivalence of two rebuilds, the
+  reproducibility gate for pipeline migrations
+
+Every check is read-only. Nothing here trades, prices, or decides.
+
+## Development
+
+```bash
+python -m pip install -e . pytest
+python -m pytest
+```
+
+CI runs the full test suite on Ubuntu, Windows and macOS with Python 3.11 and
+3.12. Issues are handled on weekends; pull requests are welcome.
+
+## Related work
+
+- [Daniel, Sornette & Wohrmann (2008)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=1289222) — look-ahead benchmark bias, quantified
+- [Fonseca (2026)](https://econpapers.repec.org/paper/arxpapers/2607.04958.htm) — look-ahead-freedom as temporal non-interference (the verifiability boundary)
+- [Point-in-Time Backtesting: A Formal Bias Taxonomy](https://www.mdpi.com/2227-7390/14/12/2182) (Mathematics 2026, 14(12):2182)
+- [Kelly et al., Scaling Point-in-Time Language Models](https://www.nber.org/papers/w35247) (NBER w35247)
+- [Look-Ahead-Bench](https://ar5iv.labs.arxiv.org/html/2601.13770) (arXiv:2601.13770) — measuring look-ahead bias in PIT LLMs
+
+## License
+
+MIT

pit_adjuster-0.1.0/README.md

@@ -0,0 +1,189 @@
+# pit-adjuster
+
+Point-in-time fixed-basis back-adjustment engine for daily price history:
+rebuild prices so that **any day reads exactly what that day could have
+known** — plus drift detection for vendors that silently switch adjustment
+conventions. Python 3.11+, **zero dependencies**, Windows / Linux / macOS.
+
+![adjustment chain](https://img.shields.io/badge/deps-0-brightgreen)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+
+**Status:** v0.1 — alpha. The adjustment math is battle-tested inside a
+production research pipeline, but this standalone package is new: expect the
+CLI and schema to shift before v1.0.
+
+## Why this exists
+
+A-share (and most equity) history arrives from vendors in **current-vintage**
+adjusted form. Two silent dangers:
+
+1. **The convention itself is not point-in-time.** Prices you see today
+   embed every adjustment event that ever happened — including events that
+   were announced *after* a historical date. A backtest that uses them reads
+   the future.
+2. **Vendors switch conventions silently.** One day your data source starts
+   serving forward-adjusted prices where it served back-adjusted prices
+   yesterday. Nothing in the CSV changes shape; every historical signal
+   silently changes value.
+
+`pit-adjuster` rebuilds history from two ingredients — current-vintage
+forward-adjusted (qfq) bars plus a **point-in-time corporate-action archive**
+— into a fixed-basis back-adjusted (hfq) chain where each day's price depends
+only on events whose ex-date is on or before that day. Then it *checks*: did
+the rebuild invert the vendor chain correctly, and does the vendor chain
+still agree with live raw prices today?
+
+## Philosophy
+
+Price history must be reversible. A research pipeline that cannot prove its
+prices were knowable in the past is not doing backtesting — it is doing
+wishful thinking. `pit-adjuster` treats **look-ahead freedom as a
+verifiable property**, not a style preference:
+
+- **PIT principle** — every price, factor, and calibration depends only on
+  information available at that historical point. See
+  [Kelly et al., "Scaling Point-in-Time Language Models"](https://www.nber.org/papers/w35247)
+  (NBER w35247) and
+  [Look-Ahead-Bench](https://ar5iv.labs.arxiv.org/html/2601.13770)
+  (arXiv:2601.13770) for why the whole industry is converging on this.
+- **Look-ahead bias is measurable** — Daniel, Sornette & Wohrmann (2008),
+  ["Look-Ahead Benchmark Bias in Portfolio Performance Evaluation"](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=1289222)
+  (arXiv:0810.1922) quantify how ex-post benchmark construction inflates
+  performance. A vendor that silently swaps adjustment conventions is doing
+  exactly this, inside your price column.
+- **Formal ground** — Fonseca (2026),
+  ["Look-Ahead-Freedom as Temporal Non-Interference"](https://econpapers.repec.org/paper/arxpapers/2607.04958.htm)
+  (arXiv:2607.04958) proves look-ahead-freedom is *undecidable* in general
+  (Π⁰₁-hard when availability depends on data values), but admits a
+  **linear-time decidable type-effect system on the value-independent
+  fragment** — windowing, resampling, joins, PIT and vintage reads.
+
+**Honest boundary:** this package implements verifiable checks for the
+value-independent fragment of the problem (factor chains, ex-date ordering,
+snapshot equivalence, chain inversion). For the general value-dependent case
+we fall back to heuristic guards and say so explicitly — verifiability is
+claimed only where the theory allows it.
+
+## Quick start
+
+```bash
+# install from PyPI (once published)
+pip install pit-adjuster
+
+# or run without installing anything:
+#   PYTHONPATH=src python -m pit_adjuster --help
+
+# try it on synthetic data (builds a fake qfq history + action archive,
+# rebuilds to hfq, runs invert-check and drift-check)
+python examples/demo.py
+```
+
+Rebuild your own history:
+
+```bash
+padj rebuild \
+  --bars bars.json --actions actions.json \
+  --as-of 2026-08-11 --code 600000 --out hfq.json
+
+padj invert-check --bars hfq.json --actions actions.json --as-of 2026-08-11
+padj drift-check --bars hfq.json --actions actions.json \
+  --as-of 2026-08-11 --live live_closes.json
+```
+
+`padj rebuild` is the workhorse: it inverts the vendor qfq chain back to raw
+prices, then re-applies only events whose ex-date is on or before each bar
+date (fixed basis at the archive coverage start). Raw open/close are kept
+alongside adjusted prices so execution-level work can map back to nominal
+prices.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `rebuild` | Rebuild bars to fixed-basis hfq: `open/high/low/close` adjusted, `raw_open/raw_close` nominal, `adj_factor` cumulative multiplier, volume normalized to shares |
+| `invert-check` | Ex-date continuity sanity check: is `raw_{ex-1} × factor_e ≈ raw_ex`? Informational — real ex-dates carry overnight returns, so violations can be false positives |
+| `drift-check` | **Static forward-adjustment detection.** Compares inverted raw closes against live raw closes; divergence above tolerance is authoritative — a vendor chain that no longer matches the archive |
+| `snapshot-equivalence` | Compare two rebuilt outputs (e.g. old and new pipeline versions) date-by-date within tolerance — the "did anything change?" gate |
+| `version` | Print version |
+
+Global flags: `--help` on every subcommand; JSON outputs via `--out` where
+supported; everything else prints a human-readable summary.
+
+## Data model
+
+**Bars** — a JSON list of daily bars, each with at least `date` (ISO) and
+`close`; `open/high/low/volume/amount/turnover` are preserved through the
+rebuild:
+
+```json
+{"date": "2026-06-12", "open": 95.0, "high": 96.0, "low": 94.5, "close": 95.5, "volume": 1234500}
+```
+
+**Actions** — a point-in-time corporate-action archive, one record per
+event, with `ex_date`, `adjustment_factor` and `available_at`:
+
+```json
+{"ex_date": "2026-06-15", "adjustment_factor": 0.95, "available_at": "2026-06-14T18:00:00", "action_type": "cash_dividend_stock_distribution"}
+```
+
+Invalid records (missing ex-date, non-positive or non-finite factor) are
+dropped; only events with `ex_date <= as_of_date` participate. The schema
+lives in [schema/corporate-action.schema.json](schema/corporate-action.schema.json).
+
+## Adjustment math
+
+Standard A-share factor math (as documented by exchange reference-price
+rules):
+
+```
+factor_e = (prior_close - cash) / (prior_close * (1 + bonus + transfer))
+qfq_t    = raw_t * prod_{e: ex_date_e > t} factor_e
+hfq_t    = raw_t * prod_{e: ex_date_e <= t} (1 / factor_e)
+```
+
+`rebuild` inverts the vendor qfq chain back to raw prices, then applies the
+hfq chain with a fixed basis at the archive coverage start. **Key property
+(under test):** hfq and qfq yield identical adjusted *returns* for the same
+factor chain, while hfq additionally guarantees that a price at time `t` is
+untouched by events with ex-date after `t`.
+
+Volume normalization follows the A-share convention: most codes store volume
+in lots (×100 to shares); STAR-market codes (688/689 prefixes) store native
+shares. Both are parameterizable — see `--volume-to-shares` and the
+`native_share_prefixes` argument in `rebuild_bars`.
+
+## Verification model
+
+`pit-adjuster` never trusts its inputs:
+
+- `invert-check` — factor continuity at ex-dates (sanity, false-positive
+  tolerant)
+- `drift-check` — inverted raws vs live raws (authoritative divergence
+  detection; this is the "static forward-adjustment detector" — if a vendor
+  swaps conventions, this fires)
+- `snapshot-equivalence` — before/after equivalence of two rebuilds, the
+  reproducibility gate for pipeline migrations
+
+Every check is read-only. Nothing here trades, prices, or decides.
+
+## Development
+
+```bash
+python -m pip install -e . pytest
+python -m pytest
+```
+
+CI runs the full test suite on Ubuntu, Windows and macOS with Python 3.11 and
+3.12. Issues are handled on weekends; pull requests are welcome.
+
+## Related work
+
+- [Daniel, Sornette & Wohrmann (2008)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=1289222) — look-ahead benchmark bias, quantified
+- [Fonseca (2026)](https://econpapers.repec.org/paper/arxpapers/2607.04958.htm) — look-ahead-freedom as temporal non-interference (the verifiability boundary)
+- [Point-in-Time Backtesting: A Formal Bias Taxonomy](https://www.mdpi.com/2227-7390/14/12/2182) (Mathematics 2026, 14(12):2182)
+- [Kelly et al., Scaling Point-in-Time Language Models](https://www.nber.org/papers/w35247) (NBER w35247)
+- [Look-Ahead-Bench](https://ar5iv.labs.arxiv.org/html/2601.13770) (arXiv:2601.13770) — measuring look-ahead bias in PIT LLMs
+
+## License
+
+MIT

pit_adjuster-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pit-adjuster"
+version = "0.1.0"
+description = "Point-in-time fixed-basis back-adjustment engine: adjustment factor chains, static forward-adjustment detection, snapshot equivalence checks."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["point-in-time", "back-adjustment", "hfq", "qfq", "corporate-actions", "quant", "pandas-free"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.scripts]
+padj = "pit_adjuster.cli:main"
+pit-adjuster = "pit_adjuster.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pit_adjuster-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pit_adjuster-0.1.0/src/pit_adjuster/__init__.py

@@ -0,0 +1,23 @@
+"""pit-adjuster: point-in-time fixed-basis back-adjustment engine.
+
+Rebuild daily price history so that any day reads exactly what that day
+could have known: fixed-basis hfq prices from current-vintage qfq bars plus
+a point-in-time corporate-action archive, with verifiable inversion,
+forward-adjustment drift detection and snapshot equivalence checks.
+
+Zero dependencies. Python 3.11+.
+"""
+
+from .chain import build_multipliers, events_from_actions, rebuild_bars
+from .validation import compare_raw_closes, compare_snapshots, validate_inversion
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "build_multipliers",
+    "compare_raw_closes",
+    "compare_snapshots",
+    "events_from_actions",
+    "rebuild_bars",
+    "validate_inversion",
+]

pit_adjuster-0.1.0/src/pit_adjuster/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pit_adjuster-0.1.0/src/pit_adjuster/chain.py

@@ -0,0 +1,184 @@
+"""Core adjustment chain: PIT-safe fixed-basis back-adjusted (hfq) prices.
+
+Builds a PIT-safe daily history from:
+
+- current-vintage forward-adjusted (qfq) daily bars, and
+- a point-in-time corporate-action archive (one ``adjustment_factor`` per
+  event).
+
+Standard A-share adjustment math (exchange reference-price convention):
+
+    factor_e = (prior_close - cash) / (prior_close * (1 + bonus + transfer))
+    qfq_t    = raw_t * prod_{e: ex_date_e > t} factor_e
+    hfq_t    = raw_t * prod_{e: ex_date_e <= t} (1 / factor_e)
+
+The rebuild inverts the vendor qfq chain back to raw prices, then re-applies
+only events whose ex-date is on or before each bar date (fixed basis at the
+archive coverage start). Raw open/close are kept alongside so
+execution-level backtests can map adjusted prices back to nominal prices.
+"""
+
+from __future__ import annotations
+
+import bisect
+import math
+from typing import Any
+
+DEFAULT_VOLUME_TO_SHARES = 100.0
+DEFAULT_NATIVE_SHARE_PREFIXES = ("688", "689")
+
+
+def events_from_actions(
+    actions: list[dict[str, Any]], *, as_of_date: str
+) -> list[dict[str, Any]]:
+    """Return actions sorted by ex-date, keeping only events <= as_of_date.
+
+    Each returned event carries ``ex_date``, ``factor`` and ``available_at``.
+    Invalid records (missing ex-date or non-positive factor) are dropped.
+    """
+    events: list[dict[str, Any]] = []
+    for action in actions or []:
+        ex_date = str(action.get("ex_date") or "")
+        factor = action.get("adjustment_factor")
+        try:
+            factor = float(factor)
+        except (TypeError, ValueError):
+            continue
+        if len(ex_date) < 10 or not math.isfinite(factor) or factor <= 0:
+            continue
+        if ex_date[:10] > as_of_date:
+            continue
+        events.append(
+            {
+                "ex_date": ex_date[:10],
+                "factor": factor,
+                "available_at": str(action.get("available_at") or ""),
+            }
+        )
+    events.sort(key=lambda item: item["ex_date"])
+    return events
+
+
+def build_multipliers(
+    events: list[dict[str, Any]],
+) -> tuple[list[str], list[float], list[float]]:
+    """Return ``(ex_dates, hfq_prefix, qfq_suffix)`` cumulative multipliers.
+
+    ``hfq_prefix[k]`` = prod_{j<k} (1 / factor_j)
+    ``qfq_suffix[k]`` = prod_{j>=k} factor_j
+    Both arrays have length ``n + 1``; ``k`` is the count of events whose
+    ex-date is on or before a bar date (0 .. n).
+    """
+    ex_dates = [event["ex_date"] for event in events]
+    count = len(events)
+    hfq_prefix = [1.0] * (count + 1)
+    acc = 1.0
+    for index, event in enumerate(events):
+        acc *= 1.0 / float(event["factor"])
+        hfq_prefix[index + 1] = acc
+    qfq_suffix = [1.0] * (count + 1)
+    acc = 1.0
+    for index in range(count - 1, -1, -1):
+        acc *= float(events[index]["factor"])
+        qfq_suffix[index] = acc
+    return ex_dates, hfq_prefix, qfq_suffix
+
+
+def _bar_date(bar: dict[str, Any]) -> str:
+    return str(bar.get("date") or "")[:10]
+
+
+def _raw_close(bar: dict[str, Any]) -> float | None:
+    value = bar.get("raw_close")
+    try:
+        value = float(value)
+    except (TypeError, ValueError):
+        return None
+    return value if math.isfinite(value) and value > 0 else None
+
+
+def rebuild_bars(
+    bars: list[dict[str, Any]],
+    events: list[dict[str, Any]],
+    *,
+    as_of_date: str,
+    code: str | None = None,
+    volume_to_shares: float | None = None,
+    native_share_prefixes: tuple[str, ...] = DEFAULT_NATIVE_SHARE_PREFIXES,
+) -> tuple[list[dict[str, Any]], dict[str, int]]:
+    """Rebuild one code's bars to fixed-basis hfq (PIT).
+
+    Returns ``(new_bars, stats)``.  Every valid bar gets ``open/high/low/
+    close`` as hfq prices, ``raw_open/raw_close`` as nominal prices, and
+    ``adj_factor`` as the cumulative hfq multiplier.  Volume is converted to
+    shares: codes whose prefix is in ``native_share_prefixes`` already store
+    shares (no conversion), all other codes use ``volume_to_shares``
+    (default: 1 lot = 100 shares).  Amount, turnover and any extra fields
+    are preserved.
+
+    The PIT property: a price at time ``t`` is a function only of events
+    whose ex-date is on or before ``t`` (fixed basis at archive coverage
+    start).
+    """
+    effective_multiplier = (
+        volume_to_shares
+        if volume_to_shares is not None
+        else (
+            1.0
+            if str(code or "").startswith(native_share_prefixes)
+            else DEFAULT_VOLUME_TO_SHARES
+        )
+    )
+    events = events_from_actions(events, as_of_date=as_of_date)
+    ex_dates, hfq_prefix, qfq_suffix = build_multipliers(events)
+    new_bars: list[dict[str, Any]] = []
+    stats: dict[str, int] = {"bars": 0, "invalid_bars": 0}
+    for bar in bars or []:
+        date_text = _bar_date(bar)
+        if not date_text:
+            stats["invalid_bars"] += 1
+            continue
+        close = bar.get("close")
+        try:
+            close_f = float(close)
+        except (TypeError, ValueError):
+            close_f = math.nan
+        valid = math.isfinite(close_f) and close_f > 0
+        k = bisect.bisect_right(ex_dates, date_text) if ex_dates else 0
+        qfq_mult = qfq_suffix[k] if ex_dates else 1.0
+        hfq_mult = hfq_prefix[k] if ex_dates else 1.0
+        rebuilt = dict(bar)
+        try:
+            volume_f = float(bar.get("volume") or 0.0)
+        except (TypeError, ValueError):
+            volume_f = math.nan
+        if math.isfinite(volume_f) and volume_f > 0:
+            rebuilt["volume"] = round(volume_f * effective_multiplier, 2)
+        else:
+            rebuilt["volume"] = volume_f if math.isfinite(volume_f) else None
+        if valid:
+            raw_close = close_f / qfq_mult
+            rebuilt["raw_close"] = round(raw_close, 6)
+            rebuilt["adj_factor"] = round(hfq_mult, 12)
+            for key in ("open", "high", "low"):
+                value = bar.get(key)
+                try:
+                    value_f = float(value)
+                except (TypeError, ValueError):
+                    value_f = math.nan
+                if math.isfinite(value_f) and value_f > 0:
+                    raw_value = value_f / qfq_mult
+                    rebuilt[key] = round(raw_value * hfq_mult, 6)
+                    if key == "open":
+                        rebuilt["raw_open"] = round(raw_value, 6)
+                else:
+                    rebuilt[key] = None
+            rebuilt["close"] = round(raw_close * hfq_mult, 6)
+            stats["bars"] += 1
+        else:
+            rebuilt["raw_close"] = None
+            rebuilt["raw_open"] = None
+            rebuilt["adj_factor"] = 1.0
+            stats["invalid_bars"] += 1
+        new_bars.append(rebuilt)
+    return new_bars, stats