falsification-ledger 0.1.0__py3-none-any.whl

falsification_ledger/__init__.py

@@ -0,0 +1,40 @@
+"""falsification-ledger: pre-registration and falsification ledger.
+
+A hash-chained, append-only JSONL ledger for research claims: register the
+hypothesis and the evidence that would kill it *before* running the study,
+submit evidence, adjudicate, and report hit-rate with a Wilson confidence
+interval against a random baseline. Every event is content-addressed and
+chain-verified; nothing here trades, prices, or decides.
+"""
+
+from .contracts import (
+    evidence_status,
+    falsification_object_id,
+    load_falsification_schema,
+    validate_falsification_report,
+)
+from .ledger import (
+    conclude_prediction,
+    ensure_prediction_registered,
+    has_prediction_registered,
+    ledger_path,
+    register_prediction,
+    report_prediction_hitrate,
+    verify_chain,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "conclude_prediction",
+    "ensure_prediction_registered",
+    "evidence_status",
+    "falsification_object_id",
+    "has_prediction_registered",
+    "ledger_path",
+    "load_falsification_schema",
+    "register_prediction",
+    "report_prediction_hitrate",
+    "validate_falsification_report",
+    "verify_chain",
+]

falsification_ledger/__main__.py

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

falsification_ledger/cli.py

@@ -0,0 +1,146 @@
+"""Command-line interface for falsification-ledger.
+
+Subcommands:
+
+- ``init``                 create the ledger state directory
+- ``preregister``          register a claim (verdict + reason) before evidence;
+                           optionally attach a falsification contract JSON
+- ``submit``               validate a falsification report and print its
+                           content ID and evidence status (read-only)
+- ``adjudicate``           backfill the actual verdict for a case
+- ``report``               hit-rate report (Wilson 95% CI vs random baseline)
+- ``verify``               hash-chain integrity check of the whole ledger
+- ``version``              print version
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .contracts import evidence_status, falsification_object_id, validate_falsification_report
+from .ledger import (
+    conclude_prediction,
+    ledger_path,
+    register_prediction,
+    report_prediction_hitrate,
+    verify_chain,
+)
+
+
+def _print_json(body: dict[str, Any]) -> None:
+    print(json.dumps(body, ensure_ascii=False, indent=2))
+
+
+def _load_json_file(path: str) -> dict[str, Any]:
+    value = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"expected a JSON object: {path}")
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fl",
+        description="Pre-registration and falsification ledger for research.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init", help="create the ledger state directory")
+    init.add_argument("--state-dir", required=True, help="ledger state directory")
+
+    prereg = sub.add_parser("preregister", help="register a claim before evidence")
+    prereg.add_argument("--state-dir", required=True)
+    prereg.add_argument("--case-id", required=True)
+    prereg.add_argument(
+        "--verdict", required=True, choices=["support", "against", "uncertain"]
+    )
+    prereg.add_argument("--reason", required=True)
+    prereg.add_argument("--source-type", default="other",
+                        choices=["paper", "business", "cross_domain", "pipeline", "other"])
+    prereg.add_argument("--contract", default=None,
+                        help="falsification contract JSON: what evidence would kill the claim")
+
+    submit = sub.add_parser("submit", help="validate a falsification report (read-only)")
+    submit.add_argument("--report", required=True, help="falsification report JSON path")
+    submit.add_argument("--schema", default=None, help="override schema JSON path")
+
+    adjudicate = sub.add_parser("adjudicate", help="backfill the actual verdict")
+    adjudicate.add_argument("--state-dir", required=True)
+    adjudicate.add_argument("--case-id", required=True)
+    adjudicate.add_argument(
+        "--verdict", required=True, choices=["support", "against", "uncertain"]
+    )
+
+    report = sub.add_parser("report", help="hit-rate report")
+    report.add_argument("--state-dir", required=True)
+    report.add_argument("--min-cases", type=int, default=20)
+
+    verify = sub.add_parser("verify", help="hash-chain integrity check")
+    verify.add_argument("--state-dir", required=True)
+
+    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 == "init":
+        path = ledger_path(args.state_dir)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        print(f"init: ledger ready at {path}")
+        return 0
+
+    if args.command == "preregister":
+        contract = _load_json_file(args.contract) if args.contract else None
+        result = register_prediction(
+            args.state_dir,
+            args.case_id,
+            args.verdict,
+            args.reason,
+            args.source_type,
+            falsification_contract=contract,
+        )
+        _print_json(result)
+        return 0
+
+    if args.command == "submit":
+        report = _load_json_file(args.report)
+        blockers = validate_falsification_report(report, args.schema)
+        body = {
+            "content_id": falsification_object_id(report),
+            "evidence_status": evidence_status(report, args.schema),
+            "blockers": blockers,
+        }
+        _print_json(body)
+        return 0 if not blockers else 1
+
+    if args.command == "adjudicate":
+        _print_json(conclude_prediction(args.state_dir, args.case_id, args.verdict))
+        return 0
+
+    if args.command == "report":
+        _print_json(report_prediction_hitrate(args.state_dir, min_cases=args.min_cases))
+        return 0
+
+    if args.command == "verify":
+        body = verify_chain(args.state_dir)
+        _print_json(body)
+        return 0 if body.get("ok") else 1
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

falsification_ledger/contracts.py

@@ -0,0 +1,107 @@
+"""Falsification report contract: schema validation, content IDs, evidence status.
+
+A falsification report is the machine-readable evidence that a pre-registered
+claim survived (or did not survive) an independent check.  The contract:
+
+- validates reports against ``schema/falsification-report.schema.json``
+  (fail-closed: blockers are returned, never silently tolerated),
+- computes a content ID (``sha256:<digest>``) over the canonical bytes so
+  reports are addressable and tamper-evident,
+- classifies evidence status for gates: ``valid`` / ``invalid`` /
+  ``missing`` (a falsified or inconsistent report counts as *missing*
+  evidence — absence of proof is not proof of absence, but it is not
+  support either).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+
+SCHEMA_FILE = "falsification-report.schema.json"
+SCHEMA_VERSION = "falsification_ledger.falsification_report.v1"
+DOMAIN_PREFIX = "falsification-ledger/falsification-report.v1"
+CONSISTENCY_TOLERANCE = 0.005
+
+DEFAULT_SCHEMA_PATH = Path(__file__).resolve().parents[2] / "schema" / SCHEMA_FILE
+
+_schema_cache: dict[str, Any] | None = None
+
+
+def load_falsification_schema(schema_path: Path | str | None = None) -> dict[str, Any]:
+    """Load and sanity-check the falsification report schema (cached)."""
+    global _schema_cache
+    if _schema_cache is None or schema_path is not None:
+        path = Path(schema_path) if schema_path is not None else DEFAULT_SCHEMA_PATH
+        schema = json.loads(path.read_text(encoding="utf-8"))
+        jsonschema.Draft202012Validator.check_schema(schema)
+        _schema_cache = schema
+    return _schema_cache
+
+
+def falsification_object_id(value: dict[str, Any]) -> str:
+    """Content ID: sha256(domain_prefix || 0x00 || canonical bytes)."""
+    payload = json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    ).encode("utf-8")
+    digest = hashlib.sha256(
+        DOMAIN_PREFIX.encode("utf-8") + b"\x00" + payload
+    ).hexdigest()
+    return f"sha256:{digest}"
+
+
+def validate_falsification_report(
+    value: dict[str, Any],
+    schema_path: Path | str | None = None,
+) -> list[str]:
+    """Return blockers; an empty list means the report conforms to the contract."""
+    schema = load_falsification_schema(schema_path)
+    validator = jsonschema.Draft202012Validator(schema)
+    blockers: list[str] = []
+    for error in sorted(validator.iter_errors(value), key=lambda e: list(e.path)):
+        path = "/".join(str(p) for p in error.path) or "$"
+        blockers.append(f"{path}: {error.message}")
+    if not blockers and value.get("schema_version") != SCHEMA_VERSION:
+        blockers.append(f"schema_version mismatch: {value.get('schema_version')!r}")
+    if not blockers:
+        consistency = value.get("consistency")
+        if consistency is not None:
+            if consistency.get("tolerance") != CONSISTENCY_TOLERANCE:
+                blockers.append(
+                    f"consistency.tolerance must be {CONSISTENCY_TOLERANCE}, "
+                    f"got {consistency.get('tolerance')!r}"
+                )
+    return blockers
+
+
+def evidence_status(
+    value: dict[str, Any],
+    schema_path: Path | str | None = None,
+) -> str:
+    """Evidence status for gates (fail-closed).
+
+    - ``invalid``  — report does not conform to the contract, or the
+      conclusion is falsified, or consistency is explicitly broken.
+    - ``missing``  — inconclusive: treated as absent evidence.
+    - ``valid``    — conformant, not falsified, consistent.
+    """
+    blockers = validate_falsification_report(value, schema_path)
+    if blockers:
+        return "invalid"
+    conclusion = value.get("conclusion")
+    if conclusion == "falsified":
+        return "invalid"
+    if conclusion == "inconclusive":
+        return "missing"
+    consistency = value.get("consistency")
+    if consistency is not None and consistency.get("consistent") is False:
+        return "invalid"
+    return "valid"

falsification_ledger/ledger.py

@@ -0,0 +1,363 @@
+"""Append-only, hash-chained prediction ledger core.
+
+The ledger answers one question honestly: *did your pre-registered beliefs
+hit?*  Events are appended to a JSONL file; every event carries the hash of
+the previous event, so the file is a hash chain and any edit is detectable
+by ``verify_chain``.
+
+Event kinds:
+
+- ``register``   — a claim about a case: expected verdict + reason, recorded
+  before evidence is seen (one per case, duplicate rejected).
+- ``conclude``   — the actual verdict, backfilled at study end (requires a
+  prior register; once per case).
+
+Reports aggregate resolved cases into a hit rate with a Wilson 95% CI and
+compare it against the random baseline (most common actual verdict): if the
+baseline is inside the CI, there is no systematic signal.
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import json
+import math
+import uuid
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION = "falsification_ledger.prediction_event.v1"
+REPORT_SCHEMA_VERSION = "falsification_ledger.prediction_report.v1"
+VERDICTS = ("support", "against", "uncertain")
+SOURCE_TYPES = ("paper", "business", "cross_domain", "pipeline", "other")
+DEFAULT_MIN_CASES = 20
+SAFETY = {
+    "production_effect": False,
+    "changes_probability": False,
+    "allow_real_trade": False,
+}
+
+
+def _now_text() -> str:
+    return datetime.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def _canonical_bytes(value: dict[str, Any]) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False
+    ).encode("utf-8")
+
+
+def _event_hash(prev_hash: str | None, payload: dict[str, Any]) -> str:
+    """sha256(prev_hash || 0x00 || canonical payload)."""
+    body = (prev_hash or "").encode("utf-8") + b"\x00" + _canonical_bytes(payload)
+    return hashlib.sha256(body).hexdigest()
+
+
+def ledger_path(state_dir: Path | str) -> Path:
+    return Path(state_dir) / "ledger.jsonl"
+
+
+def _load_events(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    events: list[dict[str, Any]] = []
+    for line_no, line in enumerate(
+        path.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"ledger_corrupt:{path}:{line_no}") from exc
+    return events
+
+
+def _append_event(path: Path, event: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(event, ensure_ascii=False) + "\n")
+
+
+def _last_hash(events: list[dict[str, Any]]) -> str | None:
+    return events[-1].get("event_hash") if events else None
+
+
+def register_prediction(
+    state_dir: Path | str,
+    case_id: str,
+    expected_verdict: str,
+    expected_reason: str,
+    source_type: str = "other",
+    *,
+    falsification_contract: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Register a claim about a case (once per case; duplicates rejected).
+
+    ``falsification_contract`` is optional free-form JSON describing what
+    evidence would kill the claim — written down *before* the study runs.
+    """
+    if expected_verdict not in VERDICTS:
+        raise ValueError(f"invalid_verdict:{expected_verdict}")
+    if source_type not in SOURCE_TYPES:
+        raise ValueError(f"invalid_source_type:{source_type}")
+    if not expected_reason.strip():
+        raise ValueError("expected_reason_required")
+    path = ledger_path(state_dir)
+    events = _load_events(path)
+    if any(
+        e.get("case_id") == case_id and e.get("event") == "register"
+        for e in events
+    ):
+        raise ValueError(f"duplicate_register:{case_id}")
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "event": "register",
+        "record_id": str(uuid.uuid4()),
+        "case_id": case_id,
+        "expected_verdict": expected_verdict,
+        "expected_reason": expected_reason.strip(),
+        "source_type": source_type,
+        "falsification_contract": falsification_contract,
+        "actual_verdict": None,
+        "recorded_at": _now_text(),
+        "concluded_at": None,
+    }
+    event = {**payload, "prev_hash": _last_hash(events)}
+    event["event_hash"] = _event_hash(event["prev_hash"], payload)
+    _append_event(path, event)
+    return {"event": "register", "case_id": case_id, "recorded_at": event["recorded_at"]}
+
+
+def has_prediction_registered(state_dir: Path | str, case_id: str) -> bool:
+    """Whether the case already has a registration (required before conclude)."""
+    path = ledger_path(state_dir)
+    return any(
+        e.get("case_id") == case_id and e.get("event") == "register"
+        for e in _load_events(path)
+    )
+
+
+def ensure_prediction_registered(
+    state_dir: Path | str,
+    case_id: str,
+    expected_verdict: str,
+    expected_reason: str,
+    source_type: str = "other",
+) -> dict[str, Any]:
+    """Idempotent register: skip when already registered (for automation)."""
+    if has_prediction_registered(state_dir, case_id):
+        return {"event": "register", "case_id": case_id, "already_registered": True}
+    return {
+        **register_prediction(
+            state_dir, case_id, expected_verdict, expected_reason, source_type
+        ),
+        "already_registered": False,
+    }
+
+
+def conclude_prediction(
+    state_dir: Path | str,
+    case_id: str,
+    actual_verdict: str,
+) -> dict[str, Any]:
+    """Backfill the actual verdict (register required; once per case)."""
+    if actual_verdict not in VERDICTS:
+        raise ValueError(f"invalid_verdict:{actual_verdict}")
+    path = ledger_path(state_dir)
+    events = _load_events(path)
+    if not any(
+        e.get("case_id") == case_id and e.get("event") == "register"
+        for e in events
+    ):
+        raise ValueError(f"register_required:{case_id}")
+    if any(
+        e.get("case_id") == case_id and e.get("event") == "conclude"
+        for e in events
+    ):
+        raise ValueError(f"already_concluded:{case_id}")
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "event": "conclude",
+        "record_id": str(uuid.uuid4()),
+        "case_id": case_id,
+        "actual_verdict": actual_verdict,
+        "recorded_at": _now_text(),
+        "concluded_at": _now_text(),
+    }
+    event = {**payload, "prev_hash": _last_hash(events)}
+    event["event_hash"] = _event_hash(event["prev_hash"], payload)
+    _append_event(path, event)
+    return {"event": "conclude", "case_id": case_id, "concluded_at": event["concluded_at"]}
+
+
+def verify_chain(state_dir: Path | str) -> dict[str, Any]:
+    """Recompute and check the hash chain of the whole ledger.
+
+    Detects any edit, insertion, or reordering after the fact.  Read-only.
+    """
+    path = ledger_path(state_dir)
+    if not path.exists():
+        return {"exists": False, "ok": True, "events": 0, "first_bad_line": None}
+    problems: list[dict[str, Any]] = []
+    prev_hash: str | None = None
+    events = 0
+    for line_no, line in enumerate(
+        path.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as exc:
+            problems.append({"line": line_no, "reason": f"invalid_json:{exc.msg}"})
+            continue
+        if not isinstance(event, dict):
+            problems.append({"line": line_no, "reason": "not_object"})
+            continue
+        events += 1
+        stored_prev = event.get("prev_hash") or None
+        if stored_prev != prev_hash:
+            problems.append(
+                {
+                    "line": line_no,
+                    "reason": "prev_hash_mismatch",
+                    "expected": prev_hash,
+                    "found": stored_prev,
+                }
+            )
+        payload = {
+            key: value
+            for key, value in event.items()
+            if key not in ("event_hash", "prev_hash")
+        }
+        expected = _event_hash(stored_prev, payload)
+        if event.get("event_hash") != expected:
+            problems.append(
+                {"line": line_no, "reason": "event_hash_mismatch", "expected": expected}
+            )
+        prev_hash = event.get("event_hash")
+    return {
+        "exists": True,
+        "ok": not problems,
+        "events": events,
+        "first_bad_line": problems[0]["line"] if problems else None,
+        "problems": problems[:20],
+    }
+
+
+def _wilson_ci(hits: int, n: int, z: float = 1.96) -> tuple[float, float]:
+    if n == 0:
+        return (0.0, 0.0)
+    p = hits / n
+    denom = 1 + z * z / n
+    center = (p + z * z / (2 * n)) / denom
+    half = z * math.sqrt((p * (1 - p) + z * z / (4 * n)) / n) / denom
+    return (max(0.0, center - half), min(1.0, center + half))
+
+
+def report_prediction_hitrate(
+    state_dir: Path | str,
+    min_cases: int = DEFAULT_MIN_CASES,
+) -> dict[str, Any]:
+    """Read-only hit-rate report (Wilson 95% CI, compared against random baseline).
+
+    Rule: a hit is ``expected_verdict == actual_verdict`` over *certain*
+    expectations; ``uncertain`` expectations count into participation only.
+    The report is verdict-ready when ``resolved >= min_cases``,
+    ``completeness >= 0.9`` and ``participation >= 0.7``.  If the Wilson CI
+    contains the random baseline, there is no systematic signal.
+    """
+    events = _load_events(ledger_path(state_dir))
+    registers = {
+        e["case_id"]: e for e in events if e.get("event") == "register"
+    }
+    concludes = {
+        e["case_id"]: e for e in events if e.get("event") == "conclude"
+    }
+    resolved = sorted(set(registers) & set(concludes))
+    unresolved = sorted(set(registers) - set(concludes))
+    registered_total = len(registers)
+    completeness = (
+        len(resolved) / registered_total if registered_total else 0.0
+    )
+    hits = 0
+    certain_cases = 0
+    uncertain_cases = 0
+    for case in resolved:
+        expected = registers[case]["expected_verdict"]
+        if expected == "uncertain":
+            uncertain_cases += 1
+            continue
+        certain_cases += 1
+        if expected == concludes[case]["actual_verdict"]:
+            hits += 1
+    n = len(resolved)
+    hit_rate = hits / certain_cases if certain_cases else None
+    low, high = _wilson_ci(hits, certain_cases) if certain_cases else (None, None)
+    participation = certain_cases / n if n else 0.0
+    actual_distribution: dict[str, int] = {}
+    for case in resolved:
+        if registers[case]["expected_verdict"] == "uncertain":
+            continue
+        verdict = concludes[case]["actual_verdict"]
+        actual_distribution[verdict] = actual_distribution.get(verdict, 0) + 1
+    baseline = (
+        max(actual_distribution.values()) / certain_cases if certain_cases else None
+    )
+    baseline_in_ci = (
+        low <= baseline <= high if (low is not None and baseline is not None) else None
+    )
+    by_source_type: dict[str, dict[str, Any]] = {}
+    for case in resolved:
+        source = registers[case].get("source_type", "other")
+        bucket = by_source_type.setdefault(
+            source, {"resolved": 0, "certain": 0, "hits": 0, "hit_rate": None}
+        )
+        bucket["resolved"] += 1
+        expected = registers[case]["expected_verdict"]
+        if expected == "uncertain":
+            continue
+        bucket["certain"] += 1
+        if expected == concludes[case]["actual_verdict"]:
+            bucket["hits"] += 1
+    for source, bucket in by_source_type.items():
+        bucket["hit_rate"] = (
+            bucket["hits"] / bucket["certain"] if bucket["certain"] else None
+        )
+    verdict_ready = (
+        n >= min_cases and completeness >= 0.9 and participation >= 0.7
+    )
+    return {
+        "schema_version": REPORT_SCHEMA_VERSION,
+        "generated_at": _now_text(),
+        "min_cases": min_cases,
+        "resolved_cases": n,
+        "unresolved_cases": len(unresolved),
+        "registered_total": registered_total,
+        "completeness": round(completeness, 4),
+        "certain_cases": certain_cases,
+        "uncertain_cases": uncertain_cases,
+        "participation": round(participation, 4),
+        "hit_rate": round(hit_rate, 4) if hit_rate is not None else None,
+        "wilson_ci_95": [round(low, 4), round(high, 4)]
+        if low is not None
+        else None,
+        "random_baseline": round(baseline, 4) if baseline is not None else None,
+        "baseline_in_ci": baseline_in_ci,
+        "actual_verdict_distribution": actual_distribution,
+        "by_source_type": by_source_type,
+        "verdict_ready": verdict_ready,
+        "verdict_rule": (
+            "hit = expected_verdict == actual_verdict, only over certain "
+            "expectations; uncertain expectations count into participation; "
+            "ready when resolved>=min_cases and completeness>=0.9 and "
+            "participation>=0.7; "
+            "if wilson_ci_95 contains random_baseline -> no systematic signal"
+        ),
+        "safety": SAFETY,
+    }

falsification_ledger-0.1.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: falsification-ledger
+Version: 0.1.0
+Summary: Pre-registration and falsification ledger for research: hash-chained, append-only, with Wilson-CI hit-rate reporting and fail-closed evidence contracts.
+License-Expression: MIT
+Keywords: preregistration,falsification,reproducibility,ledger,research,quant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.18
+Dynamic: license-file
+
+# falsification-ledger
+
+A hash-chained, append-only ledger for research claims: **pre-register the
+hypothesis and the evidence that would kill it *before* the study runs**,
+then adjudicate honestly and measure your hit rate against a random
+baseline. Python 3.11+, one dependency (`jsonschema`), Windows / Linux /
+macOS.
+
+**Status:** v0.1 — alpha. The ledger semantics are distilled from a
+production research pipeline, but this standalone package is new: expect the
+CLI and schemas to shift before v1.0.
+
+## Why this exists
+
+Quantitative research has a self-deception problem: you test 500 factor
+ideas, remember the 3 that worked, and forget the 497 that died. By the time
+you "validate" the lucky survivors, the evidence is already contaminated by
+what you saw. Every backtest-hygiene tool on the market attacks the
+*statistics* of this problem (deflated Sharpe, PBO, multiple-testing
+corrections). `falsification-ledger` attacks the *process*: it makes you
+write down, before seeing evidence:
+
+- what you expect (`support` / `against` / `uncertain`), and
+- what evidence would **kill** your claim (the falsification contract).
+
+Then it keeps the receipts. Every event lands in an append-only JSONL
+**hash chain** — any edit after the fact is detected by `fl verify` — and
+the report answers the only question that matters: *do your pre-registered
+beliefs actually hit, or is your hit rate indistinguishable from a random
+baseline?* (Wilson 95% CI vs the most common actual verdict.)
+
+## Philosophy
+
+**Research is a promise; the ledger keeps it.**
+
+- **Falsifiability is the default, not the exception.** Popper's criterion
+  — a claim is scientific only if something could count against it — is
+  usually invoked as a lecture. Here it is a required JSON field
+  (`falsification_contract` on `preregister`).
+- **Pre-analysis plans have known costs and benefits.** [Olken (2015),
+  "Promises and Perils of Pre-Analysis Plans"](https://www.aeaweb.org/articles?id=10.1257/jep.29.3.61)
+  (JEP 29(3)) documents both; this tool implements the benefits (frozen
+  expectations, audit trail) while keeping the costs explicit (`uncertain`
+  verdicts and exploratory source types are first-class, so you can register
+  what you genuinely do not know).
+- **Moderation beats total freezing.** [Banerjee & Duflo, "In Praise of
+  Moderation"](https://www.semanticscholar.org/paper/05ecf99a05419f0a268fe885be11a2cf4a8dbd46)
+  argue for layered pre-registration; `source_type` (paper / business /
+  cross_domain / pipeline / other) exists so confirmatory and exploratory
+  claims are never mixed in the same bucket.
+- **Finance can become scientific.** [López de Prado (2023), *Causal Factor
+  Investing*](https://www.cambridge.org/core/elements/causal-factor-investing/9AFE270D7099B787B8FD4F4CBADE0C6E)
+  asks whether factor investing can become a science; this ledger is one
+  concrete answer — evidence with a chain of custody, adjudicated against a
+  pre-registered expectation.
+- **Automated research needs machine-checkable evidence.** [EviBound
+  (arXiv:2511.05524)](https://ar5iv.labs.arxiv.org/html/2511.05524) and
+  [ECLIPSE v2.0](https://ideas.repec.org/p/osf/metaar/z3fke_v1.html) argue
+  that agentic research pipelines must eliminate false claims through
+  verifiable evidence; `fl submit` validates falsification reports against a
+  JSON Schema and computes content IDs, so gates can trust the evidence
+  without trusting the messenger.
+
+## Quick start
+
+```bash
+# install from PyPI (once published)
+pip install falsification-ledger
+
+# or run without installing anything:
+#   PYTHONPATH=src python -m falsification_ledger --help
+
+# try the full loop on a scratch ledger (creates files under a temp dir)
+python examples/demo.py
+```
+
+The manual loop:
+
+```bash
+fl init --state-dir ~/.research-ledger
+
+# 1. BEFORE running the study: register what you expect,
+#    and what evidence would kill the claim.
+fl preregister --state-dir ~/.research-ledger \
+  --case-id MOMENTUM-OOS-2026Q3 \
+  --verdict support \
+  --reason "momentum rank IC stays positive OOS" \
+  --source-type paper \
+  --contract kill-criteria.json
+
+# 2. When an independent check produces evidence, submit it:
+fl submit --report falsification-report.json
+# -> {"content_id": "sha256:...", "evidence_status": "valid", ...}
+
+# 3. AFTER the study: adjudicate honestly.
+fl adjudicate --state-dir ~/.research-ledger \
+  --case-id MOMENTUM-OOS-2026Q3 --verdict support
+
+# 4. Measure whether you are better than a coin flip.
+fl report --state-dir ~/.research-ledger --min-cases 20
+
+# 5. Any time: prove nobody rewrote history.
+fl verify --state-dir ~/.research-ledger
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init` | Create the ledger state directory |
+| `preregister` | Register a claim: `--case-id`, `--verdict` (support/against/uncertain), `--reason`, optional `--source-type`, optional `--contract` (falsification contract JSON). Duplicate registration for the same case is rejected |
+| `submit` | Validate a falsification report against the contract schema; print its content ID (`sha256:...`) and evidence status (`valid` / `invalid` / `missing`). Read-only; exits non-zero on blockers |
+| `adjudicate` | Backfill the actual verdict for a registered case (register required; once per case) |
+| `report` | Hit-rate report: resolved cases, completeness, participation, hit rate with **Wilson 95% CI**, random baseline, per-source-type breakdown, `verdict_ready` gate |
+| `verify` | Recompute the hash chain of the whole ledger; detects any edit, insertion, or reordering |
+| `version` | Print version |
+
+Global flag: `--state-dir` on every stateful command (default: none — the
+ledger path is always explicit, so a `git add .` can never sweep it into
+version control).
+
+## Ledger format
+
+The ledger is a JSONL file at `<state-dir>/ledger.jsonl`. Every line is one
+event:
+
+```json
+{"schema_version": "falsification_ledger.prediction_event.v1",
+ "event": "register", "record_id": "...", "case_id": "CASE-1",
+ "expected_verdict": "support", "expected_reason": "...",
+ "source_type": "paper", "falsification_contract": {...},
+ "actual_verdict": null, "recorded_at": "...", "concluded_at": null,
+ "prev_hash": null,
+ "event_hash": "sha256(prev_hash || 0x00 || canonical payload)"}
+```
+
+`verify` recomputes every `event_hash` and checks each `prev_hash` link.
+**Any tampering — editing a reason, deleting a line, reordering events —
+breaks the chain at a specific line number.**
+
+## Falsification reports
+
+A falsification report is the machine-readable evidence produced by an
+independent check (null-model randomization, OOS rank IC, FDR correction,
+protocol deviation, effect CI, cost sensitivity, ...). The contract:
+
+- schema: [`schema/falsification-report.schema.json`](schema/falsification-report.schema.json)
+  (draft 2020-12, `additionalProperties: false`, fail-closed);
+- content ID: `sha256:` over `domain-prefix || 0x00 || canonical JSON` —
+  the same report always yields the same ID, a one-field change yields a
+  different ID;
+- evidence status (fail-closed for gates):
+  - `valid` — conformant, conclusion `not_falsified`, consistency intact;
+  - `invalid` — non-conformant, or conclusion `falsified`, or explicitly
+    inconsistent;
+  - `missing` — conclusion `inconclusive`: treated as *absent* evidence.
+
+## Verification model
+
+`fl verify` is the tamper-evidence layer: it re-derives the entire chain
+from the file bytes and reports the first bad line. Combined with
+`preregister` (frozen expectations) and `submit` (content-addressed
+evidence), a research pipeline can prove to itself — and to reviewers —
+that the expectation existed before the evidence did. 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
+
+- [Olken (2015), Promises and Perils of Pre-Analysis Plans](https://www.aeaweb.org/articles?id=10.1257/jep.29.3.61) — the economics of freezing expectations
+- [Banerjee & Duflo, In Praise of Moderation](https://www.semanticscholar.org/paper/05ecf99a05419f0a268fe885be11a2cf4a8dbd46) — layered pre-registration
+- [López de Prado (2023), Causal Factor Investing](https://www.cambridge.org/core/elements/causal-factor-investing/9AFE270D7099B787B8FD4F4CBADE0C6E) — can factor investing become scientific?
+- [EviBound: Evidence-Bound Autonomous Research (arXiv:2511.05524)](https://ar5iv.labs.arxiv.org/html/2511.05524) — governance for agentic research
+- [ECLIPSE v2.0: A Systematic Falsification Framework](https://ideas.repec.org/p/osf/metaar/z3fke_v1.html) — enforce falsifiability integrity
+
+## License
+
+MIT

falsification_ledger-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+falsification_ledger/__init__.py,sha256=Kp8_0uUlig5EEv9tYW4Kv5JswY4_rM4rG2nP7Nsj0rs,1133
+falsification_ledger/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+falsification_ledger/cli.py,sha256=LLgAvyiuJXQec_4fGEC803E0aUUUx8A3uotMMHG_i0s,5152
+falsification_ledger/contracts.py,sha256=WFS-_x3xSvAGbs-dfeyUebdHMR2dDTr_rsZtLILtahY,4075
+falsification_ledger/ledger.py,sha256=oWm-Kpgek5UQSJB8paTMYXjqqh6cqq1n4e4etsUyJdo,13145
+falsification_ledger-0.1.0.dist-info/licenses/LICENSE,sha256=fuOqBeL8dZoJ9gqMC8N389Mw-Y-J_WlfkVMAJ6a5gfY,1090
+falsification_ledger-0.1.0.dist-info/METADATA,sha256=nnk8FiR2fSCku4JXXOPpCHOCrjxtTQjePqXUojVt-DM,9878
+falsification_ledger-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+falsification_ledger-0.1.0.dist-info/entry_points.txt,sha256=m6ONL2FaDJ65GHZa-IZl_-KSJhWgOzmT7nP7rmvySRU,106
+falsification_ledger-0.1.0.dist-info/top_level.txt,sha256=zAoTdWSre6QyNE_kRcCPKARqg4Jl-ghMlSrOcw6bh-k,21
+falsification_ledger-0.1.0.dist-info/RECORD,,

falsification_ledger-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
+

falsification_ledger-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+falsification-ledger = falsification_ledger.cli:main
+fl = falsification_ledger.cli:main

falsification_ledger-0.1.0.dist-info/licenses/LICENSE

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

falsification_ledger-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+falsification_ledger