forward-qpop 0.1.1__tar.gz

forward_qpop-0.1.1/.gitignore

@@ -0,0 +1,53 @@
+# Secrets / credentials — NEVER commit
+.env
+.env.*
+*.key
+*_secret*
+**/secrets/**
+
+# Live / private artifacts — keep this repo methods-only
+**/live/**
+**/brokerage/**
+**/paid_data/**
+*_live_*.jsonl
+*_trades_*.csv
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Allow synthetic / sample data explicitly (it is non-sensitive)
+!data/synthetic/**
+!examples/**/*sample*
+!examples/**/*template*
+
+# LaTeX build artifacts (paper now lives under research/)
+research/paper/*.aux
+research/paper/*.log
+research/paper/*.bbl
+research/paper/*.blg
+research/paper/*.out
+research/paper/*.pdf
+research/paper/*.toc
+
+# session / local agent data (never publish)
+.remember/
+
+# track the built paper PDF for readers / citers
+!research/paper/paper.pdf
+
+# generated anchor artifacts (run `forward-qpop anchor`)
+*.anchor.json
+*.ots

forward_qpop-0.1.1/LICENSE

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

forward_qpop-0.1.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: forward-qpop
+Version: 0.1.1
+Summary: Tamper-evident, append-only forward pre-registration ledger for auditable, leakage-resistant research (the Forward-QPOP protocol).
+Project-URL: Homepage, https://github.com/yixingz3/qpop
+Project-URL: Repository, https://github.com/yixingz3/qpop
+Project-URL: Paper, https://github.com/yixingz3/qpop/tree/main/research/paper
+Author-email: Yixing Zheng <yz11739@stern.nyu.edu>
+License: MIT
+License-File: LICENSE
+Keywords: auditability,forward-validation,hash-chain,look-ahead-bias,pre-registration,reproducibility,research-integrity,trustworthy-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# forward-qpop
+
+**A tamper-evident, append-only forward pre-registration ledger for auditable,
+leakage-resistant research.**
+
+Register a hypothesis — a claim, dated evidence, measurable exit triggers, and a prior —
+*before* the evaluation window opens. Each entry is content-hashed over its frozen fields and
+chained to its predecessor, so the record proves **what was predicted** and that no entry was later
+edited, inserted, deleted, or reordered. Proving it was registered *before* an outcome (wall-clock
+time) needs an external anchor — see [`anchor` / `verify-anchor`](#cli).
+
+This is the domain-agnostic core of the **Forward-QPOP** protocol from the methods paper
+*Forward-Registered, Auditable LLM-Assisted Research* — useful for any pre-registered
+work (ML experiments, forecasts, studies), not only the finance testbed in the paper.
+
+- **Zero dependencies** — pure Python standard library.
+- **`entry_hash = sha256(content_hash ‖ prev_hash)`** — a real hash chain, not just a set
+  of independently-hashed rows.
+- **CI-friendly** — `forward-qpop verify ledger.jsonl` exits non-zero on tampering.
+
+## Install
+
+```bash
+# from source (not yet on PyPI):
+pip install "git+https://github.com/yixingz3/qpop"
+# a PyPI release of `forward-qpop` is planned
+```
+
+## Quickstart
+
+```python
+from forward_qpop import Ledger
+
+led = Ledger("ledger.jsonl")
+
+# 1. Pre-register BEFORE the evaluation window:
+led.register(
+    "H-AI-01",
+    claim="Method X reduces silent production-ML failures vs the ungated baseline.",
+    mechanism="Deterministic gates reject low-evidence candidates before the expensive step.",
+    prior=0.5,
+    evidence=[{"summary": "pilot result", "tier": "primary", "date": "2026-06-24"}],
+    exit_triggers=[{"id": "no_effect", "metric": "failure-rate delta", "op": "~0",
+                    "data_source": {"tier": "primary"}}],
+    fields={"domain": "ai-reliability"},   # any domain-specific payload, also hashed
+)
+
+# 2. Record belief updates as evidence arrives (tertiary-only is blocked by default):
+led.update("H-AI-01", evidence=[{"summary": "replication", "tier": "secondary",
+                                 "date": "2026-09-01"}])
+
+# 3. Close with a pre-committed outcome (supported / weakened / falsified):
+led.close("H-AI-01", "supported", observed={"failure_rate_delta": -0.31})
+
+# 4. Verify integrity at any time:
+res = led.verify()
+print(res.ok, res.n_entries, res.problems)
+```
+
+## CLI
+
+```bash
+forward-qpop verify ledger.jsonl          # exit 0 if intact, 1 (with details) if tampered
+forward-qpop show   ledger.jsonl          # list entries
+forward-qpop anchor ledger.jsonl          # manifest committing to the head (bind to a public commit / OpenTimestamps)
+forward-qpop verify-anchor ledger.jsonl   # detect any drift since anchoring
+```
+
+## Why forward, and why a chain
+
+A backward test of an LLM-scored process is structurally invalid (the outcomes are
+already in the model's training data). Pre-registration replaces "fit the past" with
+"commit, then observe the future"; the hash chain makes that commitment **auditable** — an external
+reviewer can confirm that no past entry was silently changed. Proving the entry existed *before* its
+outcome additionally requires binding the ledger head to an external, publicly-dated record (a pushed
+Git commit, or OpenTimestamps) via `anchor` / `verify-anchor`.
+
+## License
+
+MIT. Part of <https://github.com/yixingz3/qpop>.

forward_qpop-0.1.1/README.md

@@ -0,0 +1,186 @@
+<div align="center">
+
+# qpop
+
+**Your AI agent will admit any plausible idea. `qpop` makes it earn each one — gated, pre-registered, and falsifiable.**
+
+A Claude Code plugin that turns an over-eager LLM into a disciplined researcher. The headline result is
+counterintuitive: a well-run agent **rejects most of what it surfaces** — and that restraint, recorded
+in a tamper-evident ledger, is the point.
+
+![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-d97757)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue)
+![status: v0.1](https://img.shields.io/badge/status-v0.1-lightgrey)
+<!-- ![GitHub stars](https://img.shields.io/github/stars/yixingz3/qpop) -->
+
+</div>
+
+---
+
+> **Two audiences.** **Claude Code users:** [install the plugin](#install-claude-code) — that's the whole setup. **Researchers / citers:** see [the paper](#two-pillars). *One project, three names: the plugin & repo `qpop`, the Python package `forward-qpop`, and the method, **Forward-QPOP**.*
+
+## The problem
+
+LLMs are brilliant at *sourcing* ideas and unreliable as *decision* engines. Left ungated, an LLM
+screener **over-admits by construction** — it is rewarded for *finding* ideas, not *refusing* them —
+and it confabulates, agrees with itself (sycophancy), and, when "backtested," already knows the answer
+(look-ahead leakage). The missing piece isn't better prompts. It's **auditable restraint**.
+
+## What `qpop` does
+
+It wraps your agent's research in a discipline and makes every decision auditable:
+
+- **Rejects most candidates, for defensible reasons** — deterministic gates + a bear case written
+  *before* the recommendation.
+- **Pre-registers the survivors** to a tamper-evident, hash-chained ledger — the claim, dated
+  evidence, and measurable exit triggers, committed *before* the outcome is known.
+- **Validates forward**, not by a leaky backtest.
+
+> **Pilot evidence** (the methods paper, [`research/paper/`](research/paper)): removing any single
+> discipline pushed an LLM screener's admission rate from **0% to 66–100%**; a held-out **LLM-auditor**
+> judged **93%** of the rejections justified (n=14; an LLM-on-LLM diagnostic, not a human audit);
+> "no action" is the modal outcome. *These are pilot metrics —
+> they validate process discipline, not investment performance.*
+
+## Status — what's runnable today
+
+`qpop` is **auditable research infrastructure**, not a turnkey trading engine. What ships in this repo:
+
+| Area | Status |
+|---|---|
+| Claude Code plugin discipline (`auditable-research` + `/qpop:*`) | **Working — v0.1** |
+| Hash-chained Python ledger (`forward_qpop`) + CLI | **Working** (21/21 tests) |
+| External timestamp anchor (`anchor` / `verify-anchor`) | **Working** — manifest + drift-detection + git / OpenTimestamps |
+| JSON Schemas for cards / entries / runs | **Included** ([`schemas/`](schemas)) |
+| Synthetic fixtures + worked examples | **Included** |
+| Methods paper — theory + pilot evidence | **Included** ([PDF](research/paper/paper.pdf)) |
+| Full `SOURCE → GATE → EVALUATE` engine (AI-supply-chain) | **Specified** — interfaces/contracts in [`src/`](src); the reference implementation is private and being generalized |
+| PyPI package (`forward-qpop`) | **Planned** — install from source today |
+| Forward performance results | **Pending — not claimed** |
+
+Nothing here is finance-specific: the discipline and the ledger are domain-agnostic, and finance is a
+deliberately *adversarial* testbed. The same flow fits an agentic literature review, an ML-eval claim,
+or any forecast you want to pre-register — and the metric the ablations measure, the **over-admission
+rate** (how often an agent admits plausible-but-weak ideas), is itself a reusable reliability
+benchmark. *Reviewers:* see [`repro/`](repro) for a one-command-per-claim reproduction path (tests,
+tamper demo, schema validation, the anchor round-trip, and the paper build), each with expected output.
+
+## Install (Claude Code)
+
+```text
+/plugin marketplace add yixingz3/qpop
+/plugin install qpop@qpop
+```
+
+That's it. The `auditable-research` discipline activates when you screen ideas or act on a finding, and
+the `/qpop:*` commands below are ready. *(Other agents: the discipline is portable markdown — see
+[Other tools](#other-tools).)*
+
+## 60-second demo
+
+After installing, ask Claude Code:
+
+> *"Screen these 3 research claims with qpop and pre-register only the survivors."*
+
+A disciplined run looks like this (illustrative):
+
+```text
+3 candidates screened
+2 rejected  — tertiary-only evidence / fails replace-don't-stack
+1 preregistered — H-001
+   entry_hash: sha256:9f3c…  (chained to prev)
+verify: OK — 1 entry, chain intact
+```
+
+"2 of 3 rejected" is the feature, not a bug — **no action** is the correct, modal outcome. Want to
+feel the ledger without Claude Code? `make verify-sample` (or the Python snippet below).
+
+## How it works — the ladder
+
+Apply **in order**; stop at the first failure → **no action** (the correct, modal outcome):
+
+1. **Story or claim?** State it as something falsifiable, with a mechanism — or reject.
+2. **Deterministic gates** (no LLM): eligibility, and *replace-don't-stack* on duplicates.
+3. **Bear case first** — the strongest case *against*, written before the recommendation.
+4. **Source tiers** — primary > secondary > market-implied > tertiary; tertiary alone never moves a conclusion.
+5. **Pre-register, forward** — claim + dated evidence + exit triggers, hash-chained *before* the window.
+6. **Forward, not backtest** — a backward test of an LLM-scored process is *structurally invalid*.
+7. **On balance** — after overlap, cost, and uncertainty, does admitting beat doing nothing?
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| **`auditable-research`** | *(auto)* the full discipline, applied when you screen ideas or evaluate a finding |
+| **`/qpop:preregister`** | register a hypothesis to the tamper-evident ledger *before* evaluating |
+| **`/qpop:review`** | audit current claims / a diff for stories, leakage, over-admission, missing pre-registration |
+| **`/qpop:verify`** | verify a ledger's integrity — detect any post-hoc edit, insertion, or reorder |
+
+The ledger is a real hash chain (`entry_hash = sha256(content_hash ‖ prev_hash)`): edit a past entry,
+insert one, delete one, or reorder them, and `verify` fails (and exits non-zero — drop it in CI).
+
+## What the ledger proves (and what it doesn't)
+
+The hash chain is **tamper-evidence, not a clock.** Be precise about the guarantee:
+
+| Claim | Chain alone? | What closes the gap |
+|---|---|---|
+| A past entry was edited | ✅ detected | hash verification |
+| An entry was inserted / deleted / reordered | ✅ detected | hash-chain verification |
+| An entry existed *before* the outcome | ⚠️ partial | `anchor` + a public commit or OpenTimestamps |
+| The LLM's reasoning was correct | ❌ no | human / source review |
+| The strategy is profitable | ❌ no | a forward window + the validity checklist |
+
+The "before the outcome" guarantee needs an **external anchor** — and `qpop` ships one:
+`python scripts/qpop.py anchor <ledger>` writes a manifest committing to the ledger head, and
+`verify-anchor` detects any drift since. Bind it to time by committing the manifest to a public repo (the commit date
+*is* the anchor) or with `--ots` ([OpenTimestamps](https://opentimestamps.org)); a turnkey Sigstore/Rekor
+backend is on the roadmap.
+
+## Two pillars
+
+- **The tool** — this plugin: the discipline + a runnable, tamper-evident ledger engine.
+- **The paper** — *Forward-Registered, Auditable LLM-Assisted Research* — [**read the PDF**](research/paper/paper.pdf),
+  or the LaTeX source in [`research/`](research). The theory and pilot evidence behind the method; if you
+  build on it, please cite ([`CITATION.cff`](CITATION.cff)).
+
+## Use the ledger without Claude Code (Python)
+
+The pre-registration engine is a dependency-free package, bundled here and importable directly:
+
+```bash
+python scripts/qpop.py verify ledger.jsonl          # from a clone; no install needed
+python scripts/qpop.py anchor ledger.jsonl          # manifest committing to the head…
+python scripts/qpop.py verify-anchor ledger.jsonl   # …then detect any drift since
+# (a PyPI release, `pip install forward-qpop`, is planned)
+```
+
+```python
+# pip install -e .  (or set PYTHONPATH=src) so `forward_qpop` imports from a clone
+from forward_qpop import Ledger
+led = Ledger("ledger.jsonl")
+led.register("H-01", claim="…", prior=0.5,
+             evidence=[{"summary": "…", "tier": "primary", "date": "2026-06-24"}])
+led.verify()   # ok=True — any later edit/insert/reorder flips it to False
+```
+
+## Other tools
+
+Claude Code is supported today. The discipline lives as portable markdown in [`skills/`](skills), so
+Codex / other agents can adopt it by pointing at the skill files; first-class support for more agents
+is planned.
+
+**Roadmap:** first-class adapters for Codex and Cursor; an MCP server exposing `preregister` / `verify`;
+a LangChain / LangGraph wrapper; a turnkey Sigstore/Rekor anchor backend (the git + OpenTimestamps
+anchor ships today); and the `forward-qpop` PyPI release.
+
+## What this is not
+
+Not investment advice, not a stock-picker, not a claim to beat the market. The finance domain is a
+deliberately *adversarial testbed* (markets punish wishful thinking); `qpop` is a research
+**discipline**. See [`DISCLAIMER.md`](DISCLAIMER.md) and [`ETHICS.md`](ETHICS.md).
+
+## License
+
+[MIT](LICENSE). Implements the **Forward-QPOP** protocol — see [`research/`](research) and
+[`CITATION.cff`](CITATION.cff).

forward_qpop-0.1.1/data/synthetic/README.md

@@ -0,0 +1,15 @@
+# data/synthetic
+
+**Non-sensitive, illustrative fixtures only.** Use this directory for synthetic prices, sample
+candidate cards, and sample QPOP ledger entries that exercise the engine for tests and demos.
+
+Never place here (or anywhere in this repo): live broker logs, real trade records, paid-data
+exports, or anything tied to an actual account. The forward paper-trading record, if released later,
+is published as **aggregated** discipline/performance statistics — not as positions or trades.
+
+Suggested contents:
+- `prices_synthetic.csv` — deterministic synthetic price series for a handful of fake tickers.
+- `candidate_cards_sample.jsonl` — example SOURCE output (the card schema).
+- `qpop_ledger_sample.jsonl` — example pre-registration entries with content hashes (admission → belief-update → outcome).
+- `run_manifest_sample.json` — example SOURCE→GATE→EVALUATE run manifest (funnel counts + admission rate).
+- `scoreboard_sample.csv` — example discipline metrics (counts, admission rate) over a fake window.

forward_qpop-0.1.1/examples/ai_supply_chain/README.md

@@ -0,0 +1,94 @@
+# Worked example — AI supply chain
+
+This is the **reference domain** that motivated the framework. It illustrates the *method*; it is
+**not** a portfolio, a set of recommendations, or the live book. The live paper-trading
+implementation (broker integration, the full bottleneck map, the actual QPOP ledger and positions)
+is maintained **privately** — see `DISCLAIMER.md`.
+
+## The chokepoints (illustrative)
+
+The AI accelerator supply chain is a graph of physical bottlenecks. Representative nodes:
+
+| Node | The binding physical constraint |
+|---|---|
+| HBM / high-bandwidth memory | few qualified makers, multi-year capacity lead time |
+| Advanced packaging (CoWoS/SoIC) | interposer + chip-on-wafer capacity gates assembled accelerators |
+| Leading-edge foundry | effectively one volume supplier at the frontier |
+| EDA / litho / WFE | the tools that make the fabs (single-supplier EUV; EDA duopoly) |
+| Power delivery (grid + board-level) | transformers/switchgear upstream; sub-1V point-of-load silicon at the die |
+| Cooling / thermal | liquid cooling + CDUs as rack power density rises |
+| Optical interconnect / connectivity | transceivers, retimers, and the PCIe/CXL signal-integrity fabric |
+| Back-end test | tester machine-hours per AI part are far higher than for mobile SoCs |
+
+Each node carries decomposed scores and measurable exit triggers, exactly as in
+`../template_domain/bottleneck_map.template.yml`.
+
+## What the example demonstrates (the methodological findings)
+
+- **Discovery surfaces far more than it should admit.** Across runs, the funnel sourced and
+  evaluated dozens of candidates and admitted a small single-digit fraction; most cycles are "no
+  action." That restraint is the result.
+- **The gate catches duplication mechanically** — candidates proposed into a node that already holds
+  a position, or highly correlated to the held book, are flagged before any expensive evaluation.
+- **The evaluation catches what the gate cannot** — economic-substitute and competitive-displacement
+  relationships, structural-vs-cyclical traps (a name with the biggest recent move is often the
+  worst chokepoint), and fact-vs-announcement on policy.
+- **Policy enters as evidence, not a multiplier** — a signed, dated, material award becomes durability
+  evidence + a reversal trigger on a real chokepoint; a name whose thesis is *only* policy goes to a
+  separate, capped sleeve.
+
+## A worked candidate flow (real numbers)
+
+One discovery round, end to end (counts are from a real run; tickers are sanitized where a name is
+a live holding, named where it is a *reject* — a reject is not a position):
+
+```
+~40 candidate cards   sourced across 12 lenses (per-node + gaps + social + policy + literature)
+   ~10 NEW symbols    the rest deduped against the persistent "seen" set (already-decided names)
+    ~6 pass the GATE   deterministic: foreign-OTC and sub-liquidity names rejected mechanically
+    ~4 survive TRIAGE  cheap model drops the obvious low-purity (conglomerate / commodity / pre-rev)
+     0 admitted        Sonnet bear-case + Opus adjudication on survivors -> watchlist/reject
+```
+
+Most rounds end at **0 admitted**. Across the build-out the funnel evaluated dozens of finalists and
+admitted a **low single-digit fraction**, all at small satellite weight. "No action" is the modal
+outcome, and it is the result, not a failure.
+
+## One admitted, one rejected, one overlap-penalized
+
+- **Admitted** (an earlier round): a critical-material permanent-magnet chokepoint — a genuinely
+  supplier-concentrated, hard-to-substitute input. Admitted at **half** the unconstrained satellite
+  weight, because a separate critical-inputs concentration cap bound it. *Restraint expressed as
+  sizing, not just selection.* (Vehicle sanitized — it is a live holding.)
+- **Rejected — an integrated energy major pitched for a "helium chokepoint":** the helium scarcity is
+  real and the supply-share claim checks out, but helium is **< 1%** of a ~$330B oil major; the stock trades on crude, not
+  helium economics. The chokepoint is real, the *ticker* captures none of it. Canonical
+  rounding-error-in-a-conglomerate reject.
+- **Overlap-penalized — a pure-play 800G optical-transceiver name:** high purity, real
+  chokepoint, but the optics sleeve was already **full** (at its node cap, holding the incumbent
+  it would duplicate). Routed to a **replace-not-stack** decision — a *future replacement candidate*
+  gated on the incumbent firing an exit trigger, not a standalone add. The gate caught the
+  duplication before any expensive evaluation.
+
+## Ablation — each discipline contributes to restraint
+
+The same **38-candidate batch**, run through baselines that each remove one discipline:
+
+| Arm | Admitted | Rate |
+|---|---|---|
+| **Full pipeline** (gate + seen-set + triage + bear-case-first + overlap) | **0 / 38** | **0%** |
+| − overlap penalty | 25 / 38 | 66% |
+| − bear-case-first | 28 / 38 | 74% |
+| **Ungated LLM screener** (no discipline) | **38 / 38** | **100%** |
+
+An ungated LLM admits *literally everything*; removing any single discipline raises admission far
+past a "beyond noise" threshold; the full stack drives 100% → 0%. Paired with the rejection-quality
+audit (an independent reviewer judged the rejections **0.93 justified**, rising to **1.00** after a
+capital-at-risk adjudication overturned the one flagged false-rejection), this is the evidence that
+the restraint is *discipline*, not blanket conservatism. Full write-up: `../../research/docs/RESULTS_INITIAL.md`.
+
+## Reproducing the method (not the positions)
+
+Use `../template_domain/` to build your own map and run the funnel. The *engine and disciplines* are
+the reusable artifact here; the live AI book's specific holdings and trades are intentionally not
+published (it would read as "copy these trades," which this project explicitly is not).

forward_qpop-0.1.1/examples/template_domain/README.md

@@ -0,0 +1,34 @@
+# template_domain — start a new bottleneck domain here
+
+Copy this directory to `examples/<your_domain>/` and fill in the two configs. The *engine* does not
+change — only the domain map and the benchmark. That is the flywheel: a new domain is a config, not
+a codebase.
+
+```
+examples/<your_domain>/
+  bottleneck_map.yml      # the thesis: nodes (chokepoints), edges, scores, exit triggers
+  benchmark_config.yml    # the theme benchmark + scoreboard settings
+  candidate_process.md    # (optional) domain-specific gate thresholds / notes
+```
+
+## Steps
+
+1. **Name the chokepoints.** What are the *physical*, hard-to-bypass steps in this supply chain
+   (e.g. for rare earth: separation/refining capacity, magnet manufacturing, mining permits,
+   substitution)? Each becomes a node in `bottleneck_map.yml`.
+2. **Score each node** on `bottleneck_dims` (physical_indispensability, substitutability,
+   capacity_lead_time, supplier_concentration, pricing_power) + `demand_score` +
+   `valuation_adjustment` + `crowding_adjustment`.
+3. **Write measurable `exit_triggers`** for each node — each with a checkable `data_source`. A
+   trigger you cannot actually check is rejected.
+4. **List candidate tickers** per node with `exposure_purity` + role. US-tradeable (or your venue)
+   only; foreign-only listings are context, not candidates.
+5. **Set the benchmark** in `benchmark_config.yml` (the theme benchmark you measure alpha against).
+6. **Run the funnel** (source → gate → evaluate), **pre-register** admissions in the QPOP ledger,
+   and **forward-validate**.
+
+## Domains this schema fits
+
+AI supply chain (the worked example) · rare earth / critical minerals · power grid / transformers ·
+LNG / gas infrastructure · uranium / nuclear fuel cycle · copper / electrification · defense
+industrial base · and others. Each is a different `bottleneck_map.yml` over the same engine.

forward_qpop-0.1.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forward-qpop"
+version = "0.1.1"
+description = "Tamper-evident, append-only forward pre-registration ledger for auditable, leakage-resistant research (the Forward-QPOP protocol)."
+readme = "src/forward_qpop/README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Yixing Zheng", email = "yz11739@stern.nyu.edu" }]
+keywords = [
+  "pre-registration", "reproducibility", "trustworthy-ai", "auditability",
+  "hash-chain", "research-integrity", "forward-validation", "look-ahead-bias",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/yixingz3/qpop"
+Repository = "https://github.com/yixingz3/qpop"
+Paper = "https://github.com/yixingz3/qpop/tree/main/research/paper"
+
+[project.scripts]
+forward-qpop = "forward_qpop.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forward_qpop"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/forward_qpop", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

forward_qpop-0.1.1/repro/README.md

@@ -0,0 +1,68 @@
+# Reproducing qpop's claims
+
+Everything below runs from a **clean clone** with **Python 3.9+** (the ledger core has no
+dependencies). Two steps need an extra: schema validation needs `jsonschema`; the paper build
+needs `pdflatex` + `bibtex`. Total time is under a minute, excluding the paper build.
+
+`make` targets are shown first; the raw command beneath each works without `make`.
+
+## 1. Ledger + anchor integrity — the core claim (~1s)
+
+```bash
+make test            # or: python -m pytest -q
+```
+
+Expected: **`21 passed`** — 9 ledger + 7 anchor + 5 schema tests covering field-tamper, insert,
+delete, reorder, terminal re-registration, tertiary-only blocking, anchor drift-detection, and
+schema/fixture validation (with `format: date` enforced).
+
+## 2. Verify the shipped sample ledger (~1s)
+
+```bash
+make verify-sample   # or: python scripts/qpop.py verify data/synthetic/qpop_ledger_sample.jsonl
+```
+
+Expected: **`OK — 3 entries, integrity verified.`**
+
+## 3. Watch tamper-evidence fire (~3s)
+
+```bash
+python repro/tamper_demo.py
+```
+
+Expected: step 1 verifies clean; step 2 (after editing one frozen field) reports a
+`content_hash mismatch`, and the script prints **`PASS`** (exit 0).
+
+## 4. External timestamp anchor (~1s)
+
+```bash
+python scripts/qpop.py anchor        data/synthetic/qpop_ledger_sample.jsonl
+python scripts/qpop.py verify-anchor data/synthetic/qpop_ledger_sample.jsonl
+```
+
+Expected: **`anchor OK`**. Now append or edit an entry and re-run `verify-anchor`: it reports
+the head/digest drift and exits non-zero. The `.anchor.json` is gitignored; add `--ots` to
+also OpenTimestamps-stamp it if the client is installed.
+
+## 5. Fixtures match the published schemas (~1s, needs `pip install jsonschema`)
+
+```bash
+python repro/validate_samples.py
+```
+
+Expected: **`ALL SAMPLES VALID`** — every row in `data/synthetic/` validates against
+[`schemas/`](../schemas).
+
+## 6. Build the paper (~30s, needs pdflatex + bibtex)
+
+```bash
+make paper           # -> research/paper/paper.pdf
+```
+
+Expected: a clean 25-page PDF, no undefined references.
+
+---
+
+**What is *not* reproducible here, by design:** forward performance (the evaluation window is
+open; no return is claimed) and the live book (positions and paid feeds are never released).
+See the paper's *Reproducibility and Release* table.

forward_qpop-0.1.1/schemas/README.md

@@ -0,0 +1,38 @@
+# qpop schemas
+
+Machine-readable [JSON Schema](https://json-schema.org/) (draft 2020-12) for the data structures the
+discipline produces and consumes. They make `qpop` read as **infrastructure**, not a prompt pack: an
+agent (or a CI gate) can validate a card, a ledger entry, or a run before trusting it.
+
+| Schema | Validates | Notes |
+|---|---|---|
+| [`candidate_card.schema.json`](candidate_card.schema.json) | a SOURCE-stage candidate | the unit the gate + bear-case consume |
+| [`qpop_entry.schema.json`](qpop_entry.schema.json) | one line of a ledger `.jsonl` | `oneOf` admission / belief_update / outcome, plus the hash-chain fields |
+| [`evidence.schema.json`](evidence.schema.json) | a dated, tiered fact | the building block of cards + entries |
+| [`exit_trigger.schema.json`](exit_trigger.schema.json) | a pre-committed exit condition | must name a checkable `data_source` |
+| [`run_manifest.schema.json`](run_manifest.schema.json) | one `SOURCE → GATE → EVALUATE` run | provenance + funnel counts + admission rate |
+
+**Self-contained on purpose.** `qpop_entry` and `candidate_card` embed `evidence` / `exit_trigger`
+under `$defs` so they validate with no external `$ref` resolver (the standalone `evidence` and
+`exit_trigger` files are the canonical, reusable copies). The hash fields follow the ledger
+convention: `content_hash` is `sha256:<64-hex>`; `prev_hash` and `entry_hash` are bare `<64-hex>`
+(64 zeros at genesis).
+
+## Validate
+
+```bash
+pip install jsonschema
+python repro/validate_samples.py     # checks data/synthetic/* against these schemas
+```
+
+Or inline:
+
+```python
+import json
+from jsonschema import Draft202012Validator
+schema = json.load(open("schemas/qpop_entry.schema.json", encoding="utf-8"))
+Draft202012Validator(schema).validate(my_entry)
+```
+
+The synthetic fixtures in [`../data/synthetic/`](../data/synthetic) are kept valid against these
+schemas by `repro/validate_samples.py`.