pit-adjuster 0.1.0__py3-none-any.whl

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/__main__.py

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

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

pit_adjuster/cli.py

@@ -0,0 +1,146 @@
+"""Command-line interface for pit-adjuster.
+
+Subcommands:
+
+- ``rebuild``                rebuild bars to fixed-basis hfq (PIT)
+- ``invert-check``           ex-date continuity sanity check
+- ``drift-check``            static forward-adjustment detection vs live closes
+- ``snapshot-equivalence``   before/after equivalence of two rebuilds
+- ``version``                print version
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from . import __version__
+from .chain import events_from_actions, rebuild_bars
+from .io import load_actions, load_bars, write_json
+from .validation import compare_raw_closes, compare_snapshots, validate_inversion
+
+
+def _print_summary(heading: str, body: dict[str, Any]) -> None:
+    print(f"== {heading} ==")
+    print(json.dumps(body, ensure_ascii=False, indent=2))
+
+
+def _add_common_inputs(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--bars", required=True, help="bars JSON/JSONL path")
+    parser.add_argument("--actions", required=True, help="corporate-action archive JSON/JSONL path")
+    parser.add_argument("--as-of", required=True, help="PIT cutoff date (YYYY-MM-DD)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="padj",
+        description="Point-in-time fixed-basis back-adjustment engine.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    rebuild = sub.add_parser("rebuild", help="rebuild bars to fixed-basis hfq (PIT)")
+    _add_common_inputs(rebuild)
+    rebuild.add_argument("--code", default=None, help="instrument code (prefix rules for volume)")
+    rebuild.add_argument("--volume-to-shares", type=float, default=None, help="override volume multiplier")
+    rebuild.add_argument("--out", default=None, help="output path (JSON); default: stdout summary")
+
+    invert = sub.add_parser("invert-check", help="ex-date continuity sanity check")
+    _add_common_inputs(invert)
+    invert.add_argument("--tolerance", type=float, default=0.03)
+
+    drift = sub.add_parser("drift-check", help="static forward-adjustment detection vs live closes")
+    _add_common_inputs(drift)
+    drift.add_argument("--live", required=True, help="live raw closes JSON (date -> close)")
+    drift.add_argument("--sample-days", type=int, default=5)
+
+    snap = sub.add_parser("snapshot-equivalence", help="before/after equivalence of two rebuilds")
+    snap.add_argument("--before", required=True, help="rebuilt bars JSON (old pipeline)")
+    snap.add_argument("--after", required=True, help="rebuilt bars JSON (new pipeline)")
+    snap.add_argument("--tolerance", type=float, default=1e-6)
+
+    sub.add_parser("version", help="print version")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "version":
+        print(__version__)
+        return 0
+
+    if args.command == "rebuild":
+        bars = load_bars(args.bars)
+        actions = load_actions(args.actions)
+        new_bars, stats = rebuild_bars(
+            bars,
+            actions,
+            as_of_date=args.as_of,
+            code=args.code,
+            volume_to_shares=args.volume_to_shares,
+        )
+        if args.out:
+            write_json(args.out, new_bars)
+            print(f"rebuild: {stats['bars']} bars, {stats['invalid_bars']} invalid -> {args.out}")
+        else:
+            _print_summary(f"rebuild ({stats['bars']} bars, {stats['invalid_bars']} invalid)", new_bars[-5:])
+        return 0
+
+    if args.command == "invert-check":
+        bars = load_bars(args.bars)
+        actions = load_actions(args.actions)
+        violations = validate_inversion(bars, actions, as_of_date=args.as_of, tolerance=args.tolerance)
+        if violations:
+            _print_summary(f"invert-check: {len(violations)} violation(s)", {"violations": violations})
+            return 1
+        print("invert-check: ok (no ex-date continuity violations)")
+        return 0
+
+    if args.command == "drift-check":
+        bars = load_bars(args.bars)
+        actions = load_actions(args.actions)
+        live = _load_live(args.live)
+        report = compare_raw_closes(bars, live, sample_days=args.sample_days)
+        _print_summary("drift-check", report)
+        if report["worst_deviation"] is not None and report["worst_deviation"] > 0.01:
+            return 1
+        return 0
+
+    if args.command == "snapshot-equivalence":
+        before = load_bars(args.before)
+        after = load_bars(args.after)
+        report = compare_snapshots(before, after, tolerance=args.tolerance)
+        _print_summary("snapshot-equivalence", report)
+        return 0 if report["equal"] else 1
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+def _load_live(path: str) -> dict[str, float]:
+    import os
+
+    if path.endswith(".jsonl"):
+        rows: dict[str, float] = {}
+        with open(path, "r", encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if not line:
+                    continue
+                row = json.loads(line)
+                if isinstance(row, dict) and row.get("date"):
+                    rows[str(row["date"])[:10]] = float(row["close"])
+        return rows
+    if os.path.exists(path):
+        with open(path, "r", encoding="utf-8") as handle:
+            loaded = json.load(handle)
+        if isinstance(loaded, dict):
+            return {str(key)[:10]: float(value) for key, value in loaded.items()}
+    raise ValueError(f"live closes must be a JSON object mapping date -> close: {path}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pit_adjuster/io.py

@@ -0,0 +1,62 @@
+"""Tiny JSON/JSONL IO helpers (stdlib only).
+
+Bars and actions are plain JSON; a path or a list are interchangeable
+inputs, so the library works on both files and in-memory data.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+
+def read_json(path: str | os.PathLike[str]) -> Any:
+    """Read one JSON document from a file."""
+    with open(path, "r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def read_jsonl(path: str | os.PathLike[str]) -> list[Any]:
+    """Read a JSON-lines file into a list of records."""
+    rows: list[Any] = []
+    with open(path, "r", encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if line:
+                rows.append(json.loads(line))
+    return rows
+
+
+def write_json(path: str | os.PathLike[str], value: Any) -> None:
+    """Write a JSON document, atomically via a temp file."""
+    tmp = f"{path}.tmp"
+    with open(tmp, "w", encoding="utf-8") as handle:
+        json.dump(value, handle, ensure_ascii=False, indent=2)
+    os.replace(tmp, path)
+
+
+def load_bars(source: str | os.PathLike[str] | list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Accept a path (JSON or JSONL) or an in-memory list of bars."""
+    if isinstance(source, list):
+        return source
+    text = os.fspath(source)
+    if text.endswith(".jsonl"):
+        return [row for row in read_jsonl(text) if isinstance(row, dict)]
+    loaded = read_json(text)
+    if isinstance(loaded, list):
+        return [row for row in loaded if isinstance(row, dict)]
+    raise ValueError(f"bars source must be a JSON list of objects: {text}")
+
+
+def load_actions(source: str | os.PathLike[str] | list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Accept a path (JSON or JSONL) or an in-memory list of actions."""
+    if isinstance(source, list):
+        return source
+    text = os.fspath(source)
+    if text.endswith(".jsonl"):
+        return [row for row in read_jsonl(text) if isinstance(row, dict)]
+    loaded = read_json(text)
+    if isinstance(loaded, list):
+        return [row for row in loaded if isinstance(row, dict)]
+    raise ValueError(f"actions source must be a JSON list of objects: {text}")

pit_adjuster/validation.py

@@ -0,0 +1,178 @@
+"""Verification checks: inversion continuity, drift detection, equivalence.
+
+The checks here are the "look-ahead freedom as a verifiable property" core
+of pit-adjuster.  They operate on the value-independent fragment of the
+adjustment problem (factor chains, ex-date ordering, chain inversion) where
+the checks are exact; the general value-dependent case falls back to
+heuristic guards, stated explicitly per check.
+"""
+
+from __future__ import annotations
+
+import bisect
+import math
+from typing import Any
+
+from .chain import _bar_date, _raw_close, events_from_actions
+
+
+def validate_inversion(
+    bars: list[dict[str, Any]],
+    events: list[dict[str, Any]],
+    *,
+    as_of_date: str,
+    tolerance: float = 0.03,
+) -> list[dict[str, Any]]:
+    """Sanity check of ex-date continuity on rebuilt (raw_close) bars.
+
+    Theoretical raw price on the ex-date is ``raw_{ex-1} * factor_e`` (the
+    exchange ex-right reference price).  This is informational: with real
+    data the ex-date itself carries a normal overnight return, so violations
+    can be false positives.  The authoritative divergence check is
+    ``compare_raw_closes`` against live raw closes.
+    """
+    events = events_from_actions(events, as_of_date=as_of_date)
+    if not events:
+        return []
+    violations: list[dict[str, Any]] = []
+    by_date: dict[str, dict[str, Any]] = {}
+    for bar in bars:
+        date_text = _bar_date(bar)
+        if date_text:
+            by_date[date_text] = bar
+    dates = sorted(by_date)
+    for event in events:
+        ex_date = event["ex_date"]
+        index = bisect.bisect_left(dates, ex_date)
+        if index <= 0 or index >= len(dates):
+            continue
+        prev_date = dates[index - 1]
+        cur_date = dates[index]
+        prev_raw = _raw_close(by_date[prev_date])
+        cur_raw = _raw_close(by_date[cur_date])
+        if prev_raw is None or cur_raw is None or prev_raw <= 0:
+            continue
+        expected = prev_raw * float(event["factor"])
+        deviation = abs(cur_raw - expected) / expected
+        if deviation > tolerance:
+            violations.append(
+                {
+                    "ex_date": ex_date,
+                    "first_bar_on_or_after": cur_date,
+                    "factor": float(event["factor"]),
+                    "prev_date": prev_date,
+                    "prev_raw_close": prev_raw,
+                    "raw_close": cur_raw,
+                    "expected_raw_close": round(expected, 6),
+                    "deviation": round(deviation, 6),
+                    "tolerance": tolerance,
+                }
+            )
+    return violations
+
+
+def compare_raw_closes(
+    bars: list[dict[str, Any]],
+    live_closes: dict[str, float],
+    *,
+    sample_days: int = 5,
+) -> dict[str, Any]:
+    """Compare inverted raw closes against live raw closes.
+
+    Directly detects vendor qfq chains that diverge from the archive
+    adjustment factors (deviation above tolerance is authoritative).  This
+    is the **static forward-adjustment detector**: if a vendor silently
+    swaps adjustment conventions, inverted raws stop matching live raws and
+    this check fires.
+    """
+    dated = [bar for bar in bars if bar.get("date") and bar.get("raw_close")]
+    dated.sort(key=lambda bar: str(bar["date"]))
+    sampled = dated[-max(1, sample_days):]
+    rows: list[dict[str, Any]] = []
+    for bar in sampled:
+        day = str(bar["date"])[:10]
+        live = live_closes.get(day)
+        try:
+            live_f = float(live)
+        except (TypeError, ValueError):
+            continue
+        inverted = float(bar["raw_close"])
+        if not math.isfinite(live_f) or live_f <= 0 or not math.isfinite(inverted):
+            continue
+        deviation = abs(inverted - live_f) / live_f
+        rows.append(
+            {
+                "date": day,
+                "inverted": round(inverted, 6),
+                "live": live_f,
+                "deviation": round(deviation, 6),
+            }
+        )
+    worst = max((row["deviation"] for row in rows), default=None)
+    return {"checked": len(rows), "worst_deviation": worst, "rows": rows}
+
+
+def compare_snapshots(
+    before: list[dict[str, Any]],
+    after: list[dict[str, Any]],
+    *,
+    tolerance: float = 1e-6,
+) -> dict[str, Any]:
+    """Compare two rebuilt outputs date-by-date (equivalence gate).
+
+    Used to prove that a pipeline migration, archive refresh or parameter
+    change did not silently alter history.  Compares ``close`` and
+    ``adj_factor`` per date; rows missing from either side are reported.
+    Returns ``{"equal": bool, "checked": int, "differences": [...], "missing": [...]}``.
+    """
+    def _index(bars: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+        out: dict[str, dict[str, Any]] = {}
+        for bar in bars:
+            date_text = str(bar.get("date") or "")[:10]
+            if date_text:
+                out[date_text] = bar
+        return out
+
+    before_map = _index(before)
+    after_map = _index(after)
+    differences: list[dict[str, Any]] = []
+    missing: list[dict[str, Any]] = []
+    for date_text in sorted(set(before_map) | set(after_map)):
+        before_bar = before_map.get(date_text)
+        after_bar = after_map.get(date_text)
+        if before_bar is None or after_bar is None:
+            missing.append(
+                {
+                    "date": date_text,
+                    "present_in_before": before_bar is not None,
+                    "present_in_after": after_bar is not None,
+                }
+            )
+            continue
+        for key in ("close", "adj_factor"):
+            before_value = before_bar.get(key)
+            after_value = after_bar.get(key)
+            try:
+                before_f = float(before_value)
+                after_f = float(after_value)
+            except (TypeError, ValueError):
+                continue
+            if not (math.isfinite(before_f) and math.isfinite(after_f)):
+                continue
+            deviation = abs(before_f - after_f) / max(abs(after_f), 1e-12)
+            if deviation > tolerance:
+                differences.append(
+                    {
+                        "date": date_text,
+                        "field": key,
+                        "before": before_value,
+                        "after": after_value,
+                        "deviation": round(deviation, 12),
+                    }
+                )
+    return {
+        "equal": not differences and not missing,
+        "checked": len(before_map),
+        "differences": differences,
+        "missing": missing,
+    }

pit_adjuster-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+pit_adjuster/__init__.py,sha256=qSv0RHdecpPLim-wO-5KizNhHHfz0soXwyy4V100n2k,733
+pit_adjuster/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+pit_adjuster/chain.py,sha256=KXoXftqvT8SePerOMczbeav6o-TsZ2i7HAnCH-B8VNM,6729
+pit_adjuster/cli.py,sha256=wxN3hRCG4VXnvSSkV91Yy-l8Asjio2ADI_sRuoF2hfY,5679
+pit_adjuster/io.py,sha256=toWof-L0WMAoe-wagq76hdI5NyY0watl3t_K9e-4nYc,2212
+pit_adjuster/validation.py,sha256=xtAaBoPX9oi4kkRGCcb2DHrPKU9TqbxDR7AMPo7i1WY,6569
+pit_adjuster-0.1.0.dist-info/licenses/LICENSE,sha256=RR_pyaq5AlpbBet0GBNpz4JzymibqG61y8FXaJk7PNw,1082
+pit_adjuster-0.1.0.dist-info/METADATA,sha256=V8Fwe6a4xRy77igwL0fhQUp-6nL2BiRhH9nsnbqwvq0,9757
+pit_adjuster-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pit_adjuster-0.1.0.dist-info/entry_points.txt,sha256=dOwSZaI-GuUbrbz3CMBhc-gkQuIsbGa_3Ldsyb7H2qA,84
+pit_adjuster-0.1.0.dist-info/top_level.txt,sha256=wPasPKK8rKNC5TpJkjftF5zHm_C0vtMrgabifCfbkew,13
+pit_adjuster-0.1.0.dist-info/RECORD,,

pit_adjuster-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pit_adjuster-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+padj = pit_adjuster.cli:main
+pit-adjuster = pit_adjuster.cli:main

pit_adjuster-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+pit_adjuster