timefire 0.1.0__tar.gz

timefire-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+# Build and local-venv output for packages/timefire-py. Also the ignore file
+# hatchling ships inside the sdist: it takes the nearest one, so without this
+# file the public tarball would carry the repository root's.
+dist/
+build/
+.venv/
+*.egg-info/

timefire-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cromwell Works LLC
+
+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.

timefire-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: timefire
+Version: 0.1.0
+Summary: Timefire's resolved forecast record as DataFrames, with local signature verification.
+Project-URL: Homepage, https://timefire.ai/developers
+Project-URL: Documentation, https://timefire.ai/developers/python
+Project-URL: Repository, https://github.com/timefire-ai/timefire
+Author: Cromwell Works LLC
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ed25519,forecasts,ledger,pandas,stocks,timefire
+Classifier: Development Status :: 4 - Beta
+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 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=15
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# timefire
+
+Timefire's resolved forecast record as DataFrames. Read-only.
+
+```python
+import timefire as tf
+
+day = tf.book("2026-08-27")              # one graded book
+print(tf.verify("2026-08-27").status)    # verified
+```
+
+## What you get
+
+| Call | Returns | Source |
+| --- | --- | --- |
+| `tf.batches()` | one row per graded book | files |
+| `tf.books()` | every prediction from every graded book | files |
+| `tf.book("2026-08-27")` | one book; `.attrs` has its hash, content address, signature and public verification key | files + API |
+| `tf.nav()` | the paper portfolio, day by day | files |
+| `tf.stats()` | counts and hit rates over graded books, the API's resolved-only fields | files |
+| `tf.manifest()` | the export index with sizes and SHA-256 fingerprints | files |
+| `tf.ticker("AAPL")` | one ticker's graded observations | API |
+| `tf.calibration()` | return deciles, rank buckets, side hit rates | API |
+| `tf.verify("2026-08-27")` | local hash and Ed25519 check against the pinned key | API |
+| `tf.verify_record(record, "2026-08-27")` | the same check on a verify record you fetched yourself; pass the date you asked for | none |
+
+The data calls return graded books only; a book is graded ten trading days after it was sealed. `verify()` also answers for a book that is still sealed, with the `sealed` status below, and never sees its contents. What each column means: https://timefire.ai/developers/columns. How verification works: https://timefire.ai/developers/verification.
+
+`verify()` returns one of `verified`, `sealed`, `failed`, `legacy-unverifiable`. Books before 2026-04-28 predate exact-signed-bytes custody, so a mismatch there is reported as `legacy-unverifiable`, and only when you asked for a pre-cutoff date. Since timefire#995 those books serve their originally signed bytes and verify; treat `legacy-unverifiable` as a failure.
+
+## Changelog
+
+- 0.1.0: first release.

timefire-0.1.0/README.md

@@ -0,0 +1,33 @@
+# timefire
+
+Timefire's resolved forecast record as DataFrames. Read-only.
+
+```python
+import timefire as tf
+
+day = tf.book("2026-08-27")              # one graded book
+print(tf.verify("2026-08-27").status)    # verified
+```
+
+## What you get
+
+| Call | Returns | Source |
+| --- | --- | --- |
+| `tf.batches()` | one row per graded book | files |
+| `tf.books()` | every prediction from every graded book | files |
+| `tf.book("2026-08-27")` | one book; `.attrs` has its hash, content address, signature and public verification key | files + API |
+| `tf.nav()` | the paper portfolio, day by day | files |
+| `tf.stats()` | counts and hit rates over graded books, the API's resolved-only fields | files |
+| `tf.manifest()` | the export index with sizes and SHA-256 fingerprints | files |
+| `tf.ticker("AAPL")` | one ticker's graded observations | API |
+| `tf.calibration()` | return deciles, rank buckets, side hit rates | API |
+| `tf.verify("2026-08-27")` | local hash and Ed25519 check against the pinned key | API |
+| `tf.verify_record(record, "2026-08-27")` | the same check on a verify record you fetched yourself; pass the date you asked for | none |
+
+The data calls return graded books only; a book is graded ten trading days after it was sealed. `verify()` also answers for a book that is still sealed, with the `sealed` status below, and never sees its contents. What each column means: https://timefire.ai/developers/columns. How verification works: https://timefire.ai/developers/verification.
+
+`verify()` returns one of `verified`, `sealed`, `failed`, `legacy-unverifiable`. Books before 2026-04-28 predate exact-signed-bytes custody, so a mismatch there is reported as `legacy-unverifiable`, and only when you asked for a pre-cutoff date. Since timefire#995 those books serve their originally signed bytes and verify; treat `legacy-unverifiable` as a failure.
+
+## Changelog
+
+- 0.1.0: first release.

timefire-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "timefire"
+dynamic = ["version"]   # single source: src/timefire/__init__.py (__version__)
+description = "Timefire's resolved forecast record as DataFrames, with local signature verification."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Cromwell Works LLC" }]
+keywords = ["timefire", "forecasts", "stocks", "ledger", "ed25519", "pandas"]
+dependencies = ["pandas>=2.0", "pyarrow>=15", "cryptography>=42"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+
+[project.urls]
+Homepage = "https://timefire.ai/developers"
+Documentation = "https://timefire.ai/developers/python"
+# The repository is private today; the changelog ships in this README, which
+# PyPI shows as the project description.
+Repository = "https://github.com/timefire-ai/timefire"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.hatch.version]
+path = "src/timefire/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/timefire"]
+
+[tool.hatch.build.targets.sdist]
+# Only the package, its tests and the metadata files, whatever else sits in
+# this directory. (hatchling also ships the nearest VCS ignore file; the
+# package's own .gitignore exists so that is not the repository root's.)
+only-include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

timefire-0.1.0/src/timefire/__init__.py

@@ -0,0 +1,9 @@
+"""Timefire's resolved forecast record, as DataFrames. Read-only."""
+__version__ = "0.1.0"
+
+FILES_BASE = "https://timefire.ai/data/export/"
+API_BASE = "https://api.timefire.ai/api/v1/"
+
+from ._api import calibration, ticker  # noqa: E402,F401
+from ._files import batches, book, books, manifest, nav, stats  # noqa: E402,F401
+from .verify import VerificationResult, verify, verify_record  # noqa: E402,F401

timefire-0.1.0/src/timefire/_api.py

@@ -0,0 +1,43 @@
+"""Single objects from the public REST API. Resolved books only, by construction."""
+from __future__ import annotations
+
+import json
+import re
+
+import pandas as pd
+
+from . import API_BASE, _http
+from ._frames import frame_from_records
+
+TICKER = re.compile(r"^[A-Z][A-Z0-9.\-]{0,9}$")
+TICKER_COLUMNS = ["trading_date", "rank", "predicted_return", "is_long_pick", "is_short_pick",
+                  "realized_return", "hit", "graded_by_policy"]
+
+
+def get_json(path: str):
+    return json.loads(_http.get_bytes(API_BASE + path))
+
+
+def batch_meta(trading_date: str) -> dict:
+    """The seal fields of one book from GET /batch/{date}; predictions are ignored here."""
+    return get_json(f"batch/{trading_date}")
+
+
+def ticker(symbol: str, limit: int = 500) -> pd.DataFrame:
+    """One ticker's observations from graded books only, newest first."""
+    symbol = symbol.upper()
+    if not TICKER.match(symbol):
+        raise ValueError("ticker must be a stock symbol like AAPL")
+    if not 1 <= limit <= 500:
+        raise ValueError("limit must be between 1 and 500")
+    rows = get_json(f"stock/{symbol}/history?resolved=true&limit={limit}")
+    return frame_from_records(rows, TICKER_COLUMNS)
+
+
+def calibration() -> dict:
+    """Return deciles, rank buckets and side hit rates as DataFrames, plus `meta`."""
+    raw = get_json("calibration")
+    tables = ("return_deciles", "rank_buckets", "side_hit_rates")
+    result = {name: pd.DataFrame(raw[name]) for name in tables}
+    result["meta"] = {key: value for key, value in raw.items() if key not in tables}
+    return result

timefire-0.1.0/src/timefire/_dates.py

@@ -0,0 +1,18 @@
+"""One ISO-date check for every path. ASCII digits only, no trailing newline:
+Python's `$` would accept "2026-04-24\\n", the TS client's regex does not, and
+the legacy carve-out must agree with it."""
+from __future__ import annotations
+
+import re
+
+ISO_DATE = re.compile(r"\A\d{4}-\d{2}-\d{2}\Z", re.ASCII)
+
+
+def is_iso_date(value: str) -> bool:
+    return isinstance(value, str) and ISO_DATE.fullmatch(value) is not None
+
+
+def check_date(trading_date: str) -> str:
+    if not is_iso_date(trading_date):
+        raise ValueError("trading_date must be YYYY-MM-DD")
+    return trading_date

timefire-0.1.0/src/timefire/_files.py

@@ -0,0 +1,80 @@
+"""The flat-file export: bulk data as DataFrames."""
+from __future__ import annotations
+
+import json
+
+import pandas as pd
+
+from . import FILES_BASE, _api, _http
+from ._dates import check_date
+from ._frames import read_csv_bytes, read_parquet_bytes
+
+
+def _csv(name: str) -> pd.DataFrame:
+    return read_csv_bytes(_http.get_bytes(FILES_BASE + name))
+
+
+def manifest() -> dict:
+    """The export index: every file with its path, bytes, rows and sha256."""
+    return json.loads(_http.get_bytes(FILES_BASE + "manifest.json"))
+
+
+def batches() -> pd.DataFrame:
+    """One row per fully graded book."""
+    return _csv("batches.csv")
+
+
+def books() -> pd.DataFrame:
+    """Every prediction from every fully graded book."""
+    return _csv("books.csv")
+
+
+def book(trading_date: str) -> pd.DataFrame:
+    """One graded book, same columns and dtypes as books(). `.attrs` carries
+    the seal: payload_hash, ipfs_cid, signature, signature_pubkey, and the era."""
+    trading_date = check_date(trading_date)
+    frame = read_parquet_bytes(_http.get_bytes(f"{FILES_BASE}books/{trading_date}.parquet"))
+    meta = _api.batch_meta(trading_date)
+    frame.attrs = {
+        "trading_date": trading_date,
+        "payload_hash": meta["payload_hash"],
+        "ipfs_cid": meta["ipfs_cid"],
+        "signature": meta["signature"],
+        "signature_pubkey": meta["signature_pubkey"],
+        "era": str(frame["era"].iloc[0]) if len(frame) else None,
+    }
+    return frame
+
+
+def nav() -> pd.DataFrame:
+    """The paper portfolio, day by day, through the last graded date."""
+    return _csv("simulation-nav.csv")
+
+
+def stats() -> dict:
+    """The API's resolved-only track record fields, computed from the export.
+    Same groups as the backend's _resolved_track_record_stats: realized rows
+    are those with a return, hit rates are over realized rows with a verdict."""
+    b, rows = batches(), books()
+    realized = rows[rows["realized_return"].notna()]
+    hits = realized[realized["hit"].notna()]
+    longs, shorts = hits[hits["side"] == "long"], hits[hits["side"] == "short"]
+
+    def rate(group: pd.DataFrame):
+        return float(group["hit"].astype("float64").mean()) if len(group) else None
+
+    def day(value) -> str | None:
+        return None if pd.isna(value) else value.strftime("%Y-%m-%d")
+
+    return {
+        "scope": "fully_resolved_books",
+        "date_from": day(b["trading_date"].min()),
+        "date_to": day(b["trading_date"].max()),
+        "n_resolved_batches": int(len(b)),
+        "n_predictions": int(len(rows)),
+        "n_realized": int(len(realized)),
+        "mean_realized_return": float(realized["realized_return"].mean()) if len(realized) else None,
+        "hit_rate": rate(hits),
+        "long_hit_rate": rate(longs),
+        "short_hit_rate": rate(shorts),
+    }

timefire-0.1.0/src/timefire/_frames.py

@@ -0,0 +1,64 @@
+"""One dtype vocabulary for every path in, whichever of CSV, Parquet or JSON
+the rows came from: dates are datetimes, counts are nullable Int64, money
+and returns are float64, `hit` is a nullable boolean, everything else is
+text with an empty cell as missing. CSV is read as text first, so a ticker
+spelled NA stays a ticker instead of becoming a missing value."""
+from __future__ import annotations
+
+import io
+
+import pandas as pd
+
+DATE_COLUMNS = frozenset(("trading_date", "open_date", "close_date", "cohort_open_date", "cohort_close_date"))
+INT_COLUMNS = frozenset(("rank", "n_predictions", "n_realized", "n_open_positions", "n_opened_today",
+                         "n_closed_today"))   # trade `id` is a UUID: text
+FLOAT_COLUMNS = frozenset(("predicted_return", "weight", "realized_return", "open_price", "close_price",
+                           "portfolio_return_10d", "spy_return_10d", "alpha_10d", "cash", "positions_value",
+                           "nav", "daily_return", "cumulative_return", "realized_pnl_today", "spy_nav",
+                           "spy_cumulative_return", "weight_in_cohort", "allocated_value", "open_value",
+                           "close_value", "unspent_cash", "pnl", "shares"))   # shares are fractional
+BOOL_COLUMNS = frozenset(("hit", "is_long_pick", "is_short_pick"))
+_BOOL_WORDS = {"true": True, "false": False, True: True, False: False}
+
+
+def _blank_to_na(series: pd.Series) -> pd.Series:
+    if series.dtype == object or str(series.dtype) == "str":
+        return series.mask(series == "", pd.NA)
+    return series
+
+
+def _to_boolean(series: pd.Series) -> pd.Series:
+    if series.dtype == object or str(series.dtype) == "str":
+        series = series.map(lambda v: _BOOL_WORDS.get(v.lower() if isinstance(v, str) else v, pd.NA))
+    return series.astype("boolean")
+
+
+def normalise(frame: pd.DataFrame) -> pd.DataFrame:
+    for column in frame.columns:
+        series = frame[column]
+        if column in DATE_COLUMNS:
+            # one resolution whatever the source: CSV text parses to [us] on
+            # pandas 3 and [ns] on 2, Parquet's date32 arrives as [s]
+            frame[column] = pd.to_datetime(_blank_to_na(series)).astype("datetime64[ns]")
+        elif column in INT_COLUMNS:
+            frame[column] = pd.to_numeric(_blank_to_na(series)).astype("Int64")
+        elif column in FLOAT_COLUMNS:
+            frame[column] = pd.to_numeric(_blank_to_na(series)).astype("float64")
+        elif column in BOOL_COLUMNS:
+            frame[column] = _to_boolean(series)
+        else:
+            frame[column] = _blank_to_na(series).astype("string")
+    return frame
+
+
+def read_csv_bytes(data: bytes) -> pd.DataFrame:
+    """Every cell as text, nothing treated as missing until normalise() decides."""
+    return normalise(pd.read_csv(io.BytesIO(data), dtype=str, keep_default_na=False, na_filter=False))
+
+
+def read_parquet_bytes(data: bytes) -> pd.DataFrame:
+    return normalise(pd.read_parquet(io.BytesIO(data)))
+
+
+def frame_from_records(rows: list, columns: list[str]) -> pd.DataFrame:
+    return normalise(pd.DataFrame(rows, columns=columns))

timefire-0.1.0/src/timefire/_http.py

@@ -0,0 +1,70 @@
+"""Every byte the client fetches comes through get_bytes(); tests replace it."""
+from __future__ import annotations
+
+import datetime
+import email.utils
+import random
+import time
+import urllib.error
+import urllib.request
+
+from . import __version__
+
+USER_AGENT = f"timefire-python/{__version__} (+https://timefire.ai/developers/python)"
+TIMEOUT_SECONDS = 60
+
+# 429 handling (#817). The API shares one per-address budget across every
+# route, so a burst of calls can hit it. Every call here is an idempotent GET,
+# so a 429 is retried after the server's Retry-After, a bounded number of
+# times and within a bounded total wait. Nothing else is retried.
+MAX_RETRIES = 3
+MAX_TOTAL_WAIT_SECONDS = 120.0
+BACKOFF_BASE_SECONDS = 1.0
+
+
+def _retry_after_seconds(value: str | None) -> float | None:
+    """Retry-After as seconds: delta-seconds or an HTTP date; None if unusable."""
+    if not value:
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return float(value)
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when is None:
+        return None
+    if when.tzinfo is None:   # asctime form has no zone; every HTTP-date is UTC (RFC 9110 §5.6.7)
+        when = when.replace(tzinfo=datetime.timezone.utc)
+    return max(0.0, when.timestamp() - time.time())
+
+
+def _delay(retry_after: str | None, attempt: int) -> float:
+    """The server's wait plus up to a second of jitter, or jittered
+    exponential backoff when the header is missing or unreadable."""
+    server = _retry_after_seconds(retry_after)
+    if server is not None:
+        return server + random.uniform(0.0, 1.0)
+    backoff = BACKOFF_BASE_SECONDS * (2 ** attempt)
+    return backoff / 2 + random.uniform(0.0, backoff / 2)
+
+
+def get_bytes(url: str) -> bytes:
+    waited = 0.0
+    attempt = 0
+    while True:
+        request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+        try:
+            with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+                return response.read()
+        except urllib.error.HTTPError as err:
+            if err.code != 429 or attempt >= MAX_RETRIES:
+                raise
+            delay = _delay(err.headers.get("Retry-After") if err.headers else None, attempt)
+            if waited + delay > MAX_TOTAL_WAIT_SECONDS:
+                raise
+            err.close()
+        time.sleep(delay)
+        waited += delay
+        attempt += 1

timefire-0.1.0/src/timefire/keys/README.md

@@ -0,0 +1,16 @@
+# Timefire ledger signing key
+
+`timefire-ledger-ed25519-v1.txt` is the canonical public statement for the
+Ed25519 key pinned by this verifier package. Its `.ots` companion is an
+OpenTimestamps receipt over the exact statement bytes.
+
+Verify the receipt without contacting Timefire:
+
+```sh
+ots verify timefire-ledger-ed25519-v1.txt.ots
+```
+
+The receipt carries Bitcoin block attestations (blocks 964634, 964639 and
+964667; upgraded from the calendars on 2026-09-12), so it proves the statement
+existed before those blocks. It does not replace the verifier's pinned-key
+check or authorize a future key rotation.

timefire-0.1.0/src/timefire/keys/timefire-ledger-ed25519-v1.txt

@@ -0,0 +1,4 @@
+timefire-ledger-signing-key-v1
+algorithm: Ed25519
+public-key-base64: 7ZqgyDLHcrwkUlfZGNdDYRzY7NXWLEMxsFcOVl0IE2I=
+purpose: prediction-ledger

timefire-0.1.0/src/timefire/verify.py

@@ -0,0 +1,118 @@
+"""Local Ed25519 verification of a published book. Verdict-for-verdict port
+of packages/timefire-client/src/verify.ts; keep the two in step.
+
+Scheme (mirrors the backend):
+    payload_hash = sha256_hex(utf8(canonical_payload))
+    signature    = ed25519_sign(utf8(payload_hash))   # over the ASCII hex
+
+Trust direction: nothing the server sends decides the verdict category. The
+signature is checked against the hash WE compute from the served bytes, the
+public key is pinned here, and the legacy carve-out is keyed off the date the
+CALLER asked for, never the record's own date. A sealed record (no bytes) is
+the one place the server-asserted hash is trusted, and it earns its own
+provisional verdict, never a plain success."""
+from __future__ import annotations
+
+import base64
+import binascii
+from dataclasses import dataclass
+import hashlib
+import re
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from . import _api
+from ._dates import check_date, is_iso_date
+
+TIMEFIRE_LEDGER_PUBKEYS_B64: tuple[str, ...] = ("7ZqgyDLHcrwkUlfZGNdDYRzY7NXWLEMxsFcOVl0IE2I=",)
+LEGACY_BYTES_CUTOFF = "2026-04-28"
+_B64_ALPHABET = re.compile(r"^[A-Za-z0-9+/]*$")
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    status: str                      # "verified" | "sealed" | "failed" | "legacy-unverifiable"
+    payload_hash_local: str | None   # None when sealed: nothing to hash, not a mismatch
+    payload_hash_server: str
+    hash_matches: bool | None        # None when sealed
+    signature_valid: bool
+    pubkey_pinned: bool
+    date_matches: bool
+    sealed: bool
+    revealed_at: str | None = None
+
+
+def _atob(text: str) -> bytes:
+    """The browser's atob(): WHATWG forgiving-base64. ASCII whitespace is
+    dropped, missing padding is tolerated, up to two trailing `=` are
+    allowed only when the length is a multiple of four, a length of 1 mod 4
+    or a character outside the alphabet raises. Same accept/reject set as
+    the TS client, so the two give the same verdict on the same bytes."""
+    data = re.sub(r"[\t\n\f\r ]", "", text)
+    if len(data) % 4 == 0 and data.endswith("=="):
+        data = data[:-2]
+    elif len(data) % 4 == 0 and data.endswith("="):
+        data = data[:-1]
+    if len(data) % 4 == 1 or not _B64_ALPHABET.match(data):
+        raise ValueError("not base64")
+    return base64.b64decode(data + "=" * (-len(data) % 4), validate=True)
+
+
+def _signature_ok(signature_b64: str, message: str, pubkey_b64: str) -> bool:
+    try:
+        Ed25519PublicKey.from_public_bytes(_atob(pubkey_b64)).verify(_atob(signature_b64), message.encode("utf-8"))
+        return True
+    except (InvalidSignature, ValueError, binascii.Error):
+        return False
+
+
+def verify_batch(
+    *,
+    expected_trading_date: str,
+    served_trading_date: str,
+    canonical_payload: str | None,
+    server_payload_hash: str,
+    signature_b64: str,
+    pubkey_b64: str,
+    revealed_at: str | None = None,
+    pinned_pubkeys_b64: tuple[str, ...] = TIMEFIRE_LEDGER_PUBKEYS_B64,
+) -> VerificationResult:
+    pubkey_pinned = pubkey_b64 in pinned_pubkeys_b64
+    date_matches = served_trading_date == expected_trading_date
+    sealed = canonical_payload is None
+    payload_hash_local = None if sealed else hashlib.sha256(canonical_payload.encode("utf-8")).hexdigest()
+    hash_matches = None if sealed else payload_hash_local == server_payload_hash.lower()
+    signed_hash = server_payload_hash.lower() if sealed else payload_hash_local
+    signature_valid = bool(pubkey_pinned and signed_hash and _signature_ok(signature_b64, signed_hash, pubkey_b64))
+
+    if sealed:
+        status = "sealed" if (signature_valid and pubkey_pinned and date_matches) else "failed"
+        return VerificationResult(status, None, server_payload_hash, None, signature_valid,
+                                  pubkey_pinned, date_matches, True, revealed_at)
+
+    ok = hash_matches is True and signature_valid and pubkey_pinned and date_matches
+    legacy_eligible = (date_matches and is_iso_date(expected_trading_date)
+                       and expected_trading_date < LEGACY_BYTES_CUTOFF)
+    status = "verified" if ok else "legacy-unverifiable" if legacy_eligible else "failed"
+    return VerificationResult(status, payload_hash_local, server_payload_hash, hash_matches,
+                              signature_valid, pubkey_pinned, date_matches, False, revealed_at)
+
+
+def verify_record(record: dict, expected_trading_date: str, **options) -> VerificationResult:
+    """Adapter from the /verify/{date} response. Pass the date YOU asked for."""
+    return verify_batch(
+        expected_trading_date=expected_trading_date,
+        served_trading_date=record["trading_date"],
+        canonical_payload=record.get("canonical_payload"),   # absent or null = sealed
+        server_payload_hash=record["payload_hash"],
+        signature_b64=record["signature"],
+        pubkey_b64=record["signature_pubkey"],
+        revealed_at=record.get("revealed_at"),
+        **options,
+    )
+
+
+def verify(trading_date: str) -> VerificationResult:
+    """Fetch the verify record for a date and check it locally."""
+    return verify_record(_api.get_json(f"verify/{check_date(trading_date)}"), trading_date)

timefire-0.1.0/tests/conftest.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import timefire
+from timefire import _http
+
+FIXTURES = Path(__file__).parent / "fixtures"
+ORIGINAL_GET_BYTES = _http.get_bytes   # the real fetcher, kept for the User-Agent regression test
+ROUTES = {
+    timefire.FILES_BASE + "manifest.json": "manifest.json",
+    timefire.FILES_BASE + "batches.csv": "batches.csv",
+    timefire.FILES_BASE + "books.csv": "books.csv",
+    timefire.FILES_BASE + "books/2026-08-27.parquet": "books-2026-08-27.parquet",
+    timefire.FILES_BASE + "simulation-nav.csv": "simulation-nav.csv",
+    timefire.API_BASE + "batch/2026-08-27": "batch-2026-08-27.json",
+    timefire.API_BASE + "verify/2026-08-27": "verify-2026-08-27.json",
+    timefire.API_BASE + "verify/2026-04-24": "verify-2026-04-24.json",
+    timefire.API_BASE + "stock/AAPL/history?resolved=true&limit=500": "stock-AAPL.json",
+    timefire.API_BASE + "calibration": "calibration.json",
+}
+
+
+@pytest.fixture(autouse=True)
+def offline(monkeypatch):
+    """Serve recorded bytes; any URL outside ROUTES is a test failure."""
+    calls: list[str] = []
+
+    def fake_get_bytes(url: str) -> bytes:
+        calls.append(url)
+        if url not in ROUTES:
+            raise AssertionError(f"unexpected network call: {url}")
+        return (FIXTURES / ROUTES[url]).read_bytes()
+
+    monkeypatch.setattr(_http, "get_bytes", fake_get_bytes)
+    return calls