ashare-data-immunity 0.1.1__tar.gz

ashare_data_immunity-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashare Data Immunity 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.

ashare_data_immunity-0.1.1/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: ashare-data-immunity
+Version: 0.1.1
+Summary: Data immunity for A-share daily bars: cleaning, board-aware price-limit and suspension detection, quality audit and snapshot versioning.
+License-Expression: MIT
+Keywords: a-share,data-quality,price-limit,suspension,cleaning,snapshot,quant
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ashare-data-immunity
+
+**Data immunity for A-share daily bars**: cleaning (NaN / OHLCV
+validation), board-aware price-limit and suspension detection, quality
+audit (listing / coverage / continuity) and snapshot versioning (sha256
+manifests). Python 3.11+, **zero dependencies**, Windows / Linux / macOS.
+
+**Status:** v0.1 鈥?alpha. The audit structure is distilled from a
+production A-share pipeline; board rules follow the current exchange
+conventions and should be re-checked against the exchanges' rule
+documents before you rely on them.
+
+## Why this exists
+
+A-share daily data is not born clean. Vendors ship NaN closes, negative
+opens, volume in lots or shares depending on the board, silent suspensions
+that look like flat prices, and limit-up days that look like "huge moves"
+unless you know the board's 10/20/30% rule. Every one of these corrupts a
+factor pipeline differently, and most corrupt it *quietly*.
+
+`ashare-data-immunity` is the immune system: it does not fetch data and it
+does not trade 鈥?it makes the data you already have **honest**:
+
+- **clean** 鈥?flag or sanitize non-finite values, non-positive prices,
+  OHLC inconsistencies (high below max(open, close), low above
+  min(open, close)), negative volume;
+- **limits** 鈥?board-aware price-limit detection (main 卤10%, STAR and
+  ChiNext 卤20%, BSE 卤30%, ST 卤5% on the main board) against the previous
+  close with tick rounding tolerance, plus a documented suspension
+  heuristic (zero volume, or no prices on a dated row);
+- **audit** 鈥?daily quality audit: are watched codes still listed, does
+  history coverage meet the threshold, are there calendar gaps? All data
+  sources injectable, results append-only;
+- **snapshot** 鈥?sha256 manifests with cutoffs, so "which data did this
+  backtest actually see" is a file you can compare and prove.
+
+## Philosophy
+
+**Data is an asset; immunity is a discipline.**
+
+Most data tooling optimizes for *getting* data. This tool optimizes for
+*trusting* the data you have 鈥?and it refuses to guess: board rules are
+explicit tables, the suspension detector is documented as a heuristic
+(vendor conventions differ), and the audit reports "universe unavailable"
+instead of pretending the listing check ran. Read-only by design; every
+function either returns a report or writes an append-only record. Nothing
+here trades, prices, or decides.
+
+## Quick start
+
+```bash
+# install from PyPI (once published)
+pip install ashare-data-immunity
+
+# or run without installing anything:
+#   PYTHONPATH=src python -m ashare_data_immunity --help
+
+python examples/demo.py   # clean + limits + audit + snapshot on synthetic data
+```
+
+Your own data:
+
+```bash
+# 1. validate / clean a bars file
+imm clean --bars bars.json                     # exit 1 when problems found
+imm clean --bars bars.json --drop-non-positive --out clean.json
+
+# 2. board-aware limits + suspensions
+imm limits --bars bars.json --code 600000
+imm limits --bars bars.json --code 688001 --st
+
+# 3. daily quality audit (watchlist + history dir + append-only audit dir)
+imm audit --watchlist watchlist.json \
+  --history-root data/daily --audit-root data/audits
+
+# 4. snapshot versioning
+imm snapshot --name v2026-08-01 --cutoff 2026-08-01 \
+  --files data/daily/*.json --root data --out manifests/v1.json
+imm snapshot-compare --before manifests/v1.json --after manifests/v2.json
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `clean` | Validate bars (missing/non-finite/non-positive fields, OHLC consistency, negative volume); optionally sanitize (non-finite and non-positive prices 鈫?`None`, volume kept 鈮?0) and optionally drop non-positive rows |
+| `limits` | Board classification, price-limit events (up/down with ratio and limit price) and suspension days for one code |
+| `audit` | Listing (codes not in the injected universe), history coverage, calendar continuity; appends a JSONL record per day |
+| `snapshot` | sha256 manifest of a file list with name + cutoff |
+| `snapshot-compare` | added / removed / changed files between two manifests |
+| `version` | Print version |
+
+## Board rules (v0.1)
+
+| Board | Prefixes | Limit |
+| --- | --- | --- |
+| main | 60xxxx / 00xxxx | 卤10% (ST: 卤5%) |
+| STAR | 688 / 689 | 卤20% |
+| ChiNext | 300 / 301 | 卤20% |
+| Beijing SE | 43x / 83x / 87x / 920 | 卤30% |
+| unknown | 鈥?| 卤10% (assumed main) |
+
+Limit detection compares `close` against `round(prev_close 脳 (1 卤 ratio), 2)`
+with a default tolerance of 0.001 for vendor rounding conventions. The
+first bar has no reference and is never flagged. **Verify the tables
+against the current exchange rule documents before production use** 鈥?the
+tool's job is to make the rules explicit, not to invent them.
+
+Suspension heuristic: a dated row with zero volume, or with no prices at
+all, is a suspension day. Documented, not hidden 鈥?and toggleable
+(`zero_volume_means_suspended`).
+
+## 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
+
+This tool makes no claims to novelty of its own: it is the engineering
+layer under the data-quality principles that the industry is converging on
+鈥?point-in-time discipline ([Kelly et al., NBER w35247](https://www.nber.org/papers/w35247)),
+look-ahead awareness ([Fonseca 2026, arXiv:2607.04958](https://econpapers.repec.org/paper/arxpapers/2607.04958.htm))
+and reproducible snapshots. The pieces that *are* worth citing live in the
+sibling repos of this project family; this one just keeps the data honest.
+
+## Project family
+
+Part of [Foolproof Labs](https://github.com/foolproof-labs) — a toolchain
+against self-deception in quantitative research:
+
+- [pit-adjuster](https://github.com/foolproof-labs/pit-adjuster) — PIT back-adjustment with static forward-adjustment drift detection
+- [falsification-ledger](https://github.com/foolproof-labs/falsification-ledger) — pre-registration and falsification ledger
+- [factor-qc](https://github.com/foolproof-labs/factor-qc) — fail-closed backtest quality gate
+- [lesson-book](https://github.com/foolproof-labs/lesson-book) — tuition memory for traders
+- [lookahead-free](https://github.com/foolproof-labs/lookahead-free) — verifiable look-ahead-freedom checks
+- [ashare-data-immunity](https://github.com/foolproof-labs/ashare-data-immunity) — data immunity for A-share daily bars
+
+## License
+
+MIT

ashare_data_immunity-0.1.1/README.md

@@ -0,0 +1,146 @@
+# ashare-data-immunity
+
+**Data immunity for A-share daily bars**: cleaning (NaN / OHLCV
+validation), board-aware price-limit and suspension detection, quality
+audit (listing / coverage / continuity) and snapshot versioning (sha256
+manifests). Python 3.11+, **zero dependencies**, Windows / Linux / macOS.
+
+**Status:** v0.1 鈥?alpha. The audit structure is distilled from a
+production A-share pipeline; board rules follow the current exchange
+conventions and should be re-checked against the exchanges' rule
+documents before you rely on them.
+
+## Why this exists
+
+A-share daily data is not born clean. Vendors ship NaN closes, negative
+opens, volume in lots or shares depending on the board, silent suspensions
+that look like flat prices, and limit-up days that look like "huge moves"
+unless you know the board's 10/20/30% rule. Every one of these corrupts a
+factor pipeline differently, and most corrupt it *quietly*.
+
+`ashare-data-immunity` is the immune system: it does not fetch data and it
+does not trade 鈥?it makes the data you already have **honest**:
+
+- **clean** 鈥?flag or sanitize non-finite values, non-positive prices,
+  OHLC inconsistencies (high below max(open, close), low above
+  min(open, close)), negative volume;
+- **limits** 鈥?board-aware price-limit detection (main 卤10%, STAR and
+  ChiNext 卤20%, BSE 卤30%, ST 卤5% on the main board) against the previous
+  close with tick rounding tolerance, plus a documented suspension
+  heuristic (zero volume, or no prices on a dated row);
+- **audit** 鈥?daily quality audit: are watched codes still listed, does
+  history coverage meet the threshold, are there calendar gaps? All data
+  sources injectable, results append-only;
+- **snapshot** 鈥?sha256 manifests with cutoffs, so "which data did this
+  backtest actually see" is a file you can compare and prove.
+
+## Philosophy
+
+**Data is an asset; immunity is a discipline.**
+
+Most data tooling optimizes for *getting* data. This tool optimizes for
+*trusting* the data you have 鈥?and it refuses to guess: board rules are
+explicit tables, the suspension detector is documented as a heuristic
+(vendor conventions differ), and the audit reports "universe unavailable"
+instead of pretending the listing check ran. Read-only by design; every
+function either returns a report or writes an append-only record. Nothing
+here trades, prices, or decides.
+
+## Quick start
+
+```bash
+# install from PyPI (once published)
+pip install ashare-data-immunity
+
+# or run without installing anything:
+#   PYTHONPATH=src python -m ashare_data_immunity --help
+
+python examples/demo.py   # clean + limits + audit + snapshot on synthetic data
+```
+
+Your own data:
+
+```bash
+# 1. validate / clean a bars file
+imm clean --bars bars.json                     # exit 1 when problems found
+imm clean --bars bars.json --drop-non-positive --out clean.json
+
+# 2. board-aware limits + suspensions
+imm limits --bars bars.json --code 600000
+imm limits --bars bars.json --code 688001 --st
+
+# 3. daily quality audit (watchlist + history dir + append-only audit dir)
+imm audit --watchlist watchlist.json \
+  --history-root data/daily --audit-root data/audits
+
+# 4. snapshot versioning
+imm snapshot --name v2026-08-01 --cutoff 2026-08-01 \
+  --files data/daily/*.json --root data --out manifests/v1.json
+imm snapshot-compare --before manifests/v1.json --after manifests/v2.json
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `clean` | Validate bars (missing/non-finite/non-positive fields, OHLC consistency, negative volume); optionally sanitize (non-finite and non-positive prices 鈫?`None`, volume kept 鈮?0) and optionally drop non-positive rows |
+| `limits` | Board classification, price-limit events (up/down with ratio and limit price) and suspension days for one code |
+| `audit` | Listing (codes not in the injected universe), history coverage, calendar continuity; appends a JSONL record per day |
+| `snapshot` | sha256 manifest of a file list with name + cutoff |
+| `snapshot-compare` | added / removed / changed files between two manifests |
+| `version` | Print version |
+
+## Board rules (v0.1)
+
+| Board | Prefixes | Limit |
+| --- | --- | --- |
+| main | 60xxxx / 00xxxx | 卤10% (ST: 卤5%) |
+| STAR | 688 / 689 | 卤20% |
+| ChiNext | 300 / 301 | 卤20% |
+| Beijing SE | 43x / 83x / 87x / 920 | 卤30% |
+| unknown | 鈥?| 卤10% (assumed main) |
+
+Limit detection compares `close` against `round(prev_close 脳 (1 卤 ratio), 2)`
+with a default tolerance of 0.001 for vendor rounding conventions. The
+first bar has no reference and is never flagged. **Verify the tables
+against the current exchange rule documents before production use** 鈥?the
+tool's job is to make the rules explicit, not to invent them.
+
+Suspension heuristic: a dated row with zero volume, or with no prices at
+all, is a suspension day. Documented, not hidden 鈥?and toggleable
+(`zero_volume_means_suspended`).
+
+## 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
+
+This tool makes no claims to novelty of its own: it is the engineering
+layer under the data-quality principles that the industry is converging on
+鈥?point-in-time discipline ([Kelly et al., NBER w35247](https://www.nber.org/papers/w35247)),
+look-ahead awareness ([Fonseca 2026, arXiv:2607.04958](https://econpapers.repec.org/paper/arxpapers/2607.04958.htm))
+and reproducible snapshots. The pieces that *are* worth citing live in the
+sibling repos of this project family; this one just keeps the data honest.
+
+## Project family
+
+Part of [Foolproof Labs](https://github.com/foolproof-labs) — a toolchain
+against self-deception in quantitative research:
+
+- [pit-adjuster](https://github.com/foolproof-labs/pit-adjuster) — PIT back-adjustment with static forward-adjustment drift detection
+- [falsification-ledger](https://github.com/foolproof-labs/falsification-ledger) — pre-registration and falsification ledger
+- [factor-qc](https://github.com/foolproof-labs/factor-qc) — fail-closed backtest quality gate
+- [lesson-book](https://github.com/foolproof-labs/lesson-book) — tuition memory for traders
+- [lookahead-free](https://github.com/foolproof-labs/lookahead-free) — verifiable look-ahead-freedom checks
+- [ashare-data-immunity](https://github.com/foolproof-labs/ashare-data-immunity) — data immunity for A-share daily bars
+
+## License
+
+MIT

ashare_data_immunity-0.1.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ashare-data-immunity"
+version = "0.1.1"
+description = "Data immunity for A-share daily bars: cleaning, board-aware price-limit and suspension detection, quality audit and snapshot versioning."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["a-share", "data-quality", "price-limit", "suspension", "cleaning", "snapshot", "quant"]
+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",
+]
+
+[project.scripts]
+imm = "ashare_data_immunity.cli:main"
+ashare-data-immunity = "ashare_data_immunity.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

ashare_data_immunity-0.1.1/setup.cfg

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

ashare_data_immunity-0.1.1/src/ashare_data_immunity/__init__.py

@@ -0,0 +1,36 @@
+"""ashare-data-immunity: data immunity for A-share daily bars.
+
+Cleaning (NaN/OHLCV), board-aware price-limit and suspension detection,
+quality audit (listing / coverage / continuity, with injectable data
+sources) and snapshot versioning (sha256 manifests).  Read-only by design:
+nothing here trades, prices, or decides 鈥?it keeps the data you feed it
+honest.
+"""
+
+from .audit import (
+    continuity_problems,
+    history_coverage,
+    listing_problems,
+    run_quality_audit,
+)
+from .cleaning import clean_bars, validate_bars
+from .limits import board_of, detect_limits, price_limit_ratio, suspension_days
+from .snapshot import build_snapshot, compare_snapshots
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "board_of",
+    "build_snapshot",
+    "clean_bars",
+    "compare_snapshots",
+    "continuity_problems",
+    "detect_limits",
+    "history_coverage",
+    "listing_problems",
+    "price_limit_ratio",
+    "run_quality_audit",
+    "suspension_days",
+    "validate_bars",
+]
+

ashare_data_immunity-0.1.1/src/ashare_data_immunity/__main__.py

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

ashare_data_immunity-0.1.1/src/ashare_data_immunity/audit.py

@@ -0,0 +1,191 @@
+"""Quality audit with injectable data sources.
+
+The audit answers three daily questions about a watchlist:
+
+1. **listing** — are the watched codes still in the current universe?
+   (delisting / suspension check; the universe source is injectable —
+   network fetchers are the caller's business)
+2. **coverage** — what fraction of the watchlist has daily history?
+3. **continuity** — which codes have calendar gaps beyond a threshold?
+
+Everything is read-only; results are appended to a JSONL audit file.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any, Callable
+
+MIN_HISTORY_COVERAGE = 0.8
+MAX_CALENDAR_GAP_DAYS = 15
+
+UniverseFetcher = Callable[[], list[dict[str, Any]]]
+WatchlistLoader = Callable[[Path], dict[str, Any]]
+BarsLoader = Callable[[Path, str], list[dict[str, Any]]]
+
+
+def _watchlist_codes(payload: dict[str, Any]) -> list[str]:
+    eligible = payload.get("eligible_codes")
+    if isinstance(eligible, list):
+        return sorted({str(code).strip() for code in eligible if str(code).strip()})
+    members = payload.get("members") or []
+    return sorted(
+        {
+            str(item.get("code") or "").strip()
+            for item in members
+            if str(item.get("code") or "").strip()
+        }
+    )
+
+
+def default_watchlist_loader(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def default_bars_loader(history_root: Path, code: str) -> list[dict[str, Any]]:
+    """Load ``<history_root>/<code>.json`` with a ``bars`` list."""
+    try:
+        payload = json.loads((history_root / f"{code}.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    bars = payload.get("bars") or []
+    return bars if isinstance(bars, list) else []
+
+
+def listing_problems(
+    codes: list[str],
+    universe_rows: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Codes not present in the current universe (suspected delisted/suspended)."""
+    universe = {
+        str(row.get("code") or "").strip()
+        for row in universe_rows
+        if str(row.get("code") or "").strip()
+    }
+    missing = sorted(code for code in codes if code not in universe)
+    return {
+        "checked": True,
+        "universe_count": len(universe),
+        "not_in_current_universe": missing,
+        "problem": bool(missing),
+    }
+
+
+def history_coverage(
+    codes: list[str],
+    bars_loader: BarsLoader,
+    history_root: Path | str,
+) -> dict[str, Any]:
+    """Fraction of the watchlist with non-empty daily history."""
+    if not codes:
+        return {"checked": True, "covered": 0, "total": 0, "missing_codes": [], "problem": False}
+    covered: list[str] = []
+    missing: list[str] = []
+    for code in codes:
+        bars = bars_loader(Path(history_root), code)
+        (covered if bars else missing).append(code)
+    ratio = len(covered) / len(codes)
+    return {
+        "checked": True,
+        "covered": len(covered),
+        "total": len(codes),
+        "coverage": round(ratio, 4),
+        "missing_codes": missing,
+        "problem": ratio < MIN_HISTORY_COVERAGE,
+    }
+
+
+def continuity_problems(
+    codes: list[str],
+    bars_loader: BarsLoader,
+    history_root: Path | str,
+    *,
+    max_gap_days: int = MAX_CALENDAR_GAP_DAYS,
+) -> list[dict[str, Any]]:
+    """Codes whose daily bars have calendar gaps beyond the threshold."""
+    problems: list[dict[str, Any]] = []
+    for code in codes:
+        bars = bars_loader(Path(history_root), code)
+        dates = sorted(
+            {str(row.get("date") or "")[:10] for row in bars if row.get("date")}
+        )
+        if len(dates) < 2:
+            continue
+        gaps: list[dict[str, Any]] = []
+        for previous, current in zip(dates, dates[1:]):
+            try:
+                gap_days = (date.fromisoformat(current) - date.fromisoformat(previous)).days
+            except ValueError:
+                continue
+            if gap_days > max_gap_days:
+                gaps.append({"from": previous, "to": current, "gap_days": gap_days})
+        if gaps:
+            problems.append({"code": code, "gaps": gaps})
+    return problems
+
+
+def run_quality_audit(
+    *,
+    watchlist_path: Path | str,
+    history_root: Path | str,
+    audit_root: Path | str,
+    universe_fetcher: UniverseFetcher | None = None,
+    watchlist_loader: WatchlistLoader | None = None,
+    bars_loader: BarsLoader | None = None,
+    now: datetime | None = None,
+) -> dict[str, Any]:
+    """Run all checks and append the result record (JSONL, one per day)."""
+    watchlist_path = Path(watchlist_path)
+    watchlist_loader = watchlist_loader or default_watchlist_loader
+    bars_loader = bars_loader or default_bars_loader
+    current = now or datetime.now()
+    codes = _watchlist_codes(watchlist_loader(watchlist_path))
+
+    listing: dict[str, Any] = {"checked": False, "problem": False, "reason": "universe_unavailable"}
+    if universe_fetcher is not None:
+        try:
+            listing = listing_problems(codes, universe_fetcher())
+        except Exception as exc:  # noqa: BLE001 - tolerant of upstream failure
+            listing = {
+                "checked": False,
+                "problem": False,
+                "reason": f"{type(exc).__name__}: {str(exc)[:120]}",
+            }
+
+    coverage = history_coverage(codes, bars_loader, history_root)
+    continuity = continuity_problems(codes, bars_loader, history_root)
+
+    problems: list[str] = []
+    if listing.get("problem"):
+        problems.append(
+            "suspected delisted/suspended (not in current universe): "
+            + ",".join(listing["not_in_current_universe"][:10])
+        )
+    if coverage.get("problem"):
+        problems.append(f"history coverage {coverage['coverage']} < {MIN_HISTORY_COVERAGE}")
+    if continuity:
+        problems.append(f"codes with calendar gaps: {len(continuity)}")
+
+    record = {
+        "schema_version": "ashare_data_immunity.audit.v1",
+        "audit_date": current.date().isoformat(),
+        "checked_at": current.isoformat(timespec="seconds"),
+        "watchlist_code_count": len(codes),
+        "listing": listing,
+        "history_coverage": coverage,
+        "continuity": continuity,
+        "problems": problems,
+        "passed": not problems,
+    }
+    audit_root = Path(audit_root)
+    audit_root.mkdir(parents=True, exist_ok=True)
+    path = audit_root / f"{record['audit_date']}.jsonl"
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+    return record