certflow 1.0.1__tar.gz

certflow-1.0.1/.gitignore

@@ -0,0 +1,13 @@
+/data/
+cert_env/
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+/results/
+paper/*.pdf
+paper/*.aux
+paper/*.log
+paper/*.out
+venue.md
+.claude/

certflow-1.0.1/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to CERT-FLOW are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.1] - 2026-06-10
+
+First PyPI release (`pip install certflow`).
+
+### Added
+- Top-level package API: `from certflow import CertPlanner, PlannerConfig,
+  Certificate, ConformalScorer, ACITracker, EdgeBelief, World`, plus
+  `certflow.__version__` (previously `certflow/__init__.py` was empty and
+  everything had to be imported from submodules; the old submodule imports
+  still work).
+- `CITATION.cff` (validated, concept DOI 10.5281/zenodo.20631475) and this
+  changelog.
+- Full PyPI packaging metadata: readme, keywords, classifiers, project URLs.
+
+### Changed
+- README: pip-based 30-second quickstart, static DOI badge pointing at the
+  concept DOI, link to the limitations ledger, Python badge corrected to
+  3.10+ (matching `requires-python`).
+- Package version aligned with the release tag (pyproject said 0.1.0 while
+  the repository was at v1.0.0).
+
+### Fixed
+- Lint sweep over `src/`: removed unused imports and dead local assignments
+  (no behavior change; the full 223-test suite passes bit-identically).
+
+## [1.0.0] - 2026-06-10
+
+First public release, accompanying the preprint *CERT: Certified Route
+Planning under Drifting Costs (Extended Version)*.
+
+- Conformal route certificates (LB <= OPT <= UB) under drifting edge costs:
+  age-weighted non-exchangeable quantiles, staleness correction, honest
+  annealing.
+- Certificate-directed sensing (route-critical, churn-aware) and dual
+  incremental search on a flat-array engine (numba kernels with pure-Python
+  fallback).
+- Certificate-gated preprocessing: all-pairs snapshot oracle and certified
+  Contraction Hierarchies (ns-to-microsecond queries that expire under
+  drift).
+- 223 tests; 16 reproduction pipelines covering 17 synthetic regimes,
+  METR-LA / PEMS-BAY traffic replay, MovingAI maps, and DIMACS road
+  networks.
+- Theory T1-T7 documented in `docs/` (coverage, certifiability threshold,
+  sum-aware certificate, impossibility of a tighter lower bound,
+  decision-uniform validity, churn floor).
+
+[1.0.1]: https://github.com/Archerkattri/CERT-FLOW/releases/tag/v1.0.1
+[1.0.0]: https://github.com/Archerkattri/CERT-FLOW/releases/tag/v1.0.0

certflow-1.0.1/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "If you use CERT-FLOW in your research, please cite it as below."
+type: software
+title: "CERT-FLOW: Certified Route Planning under Drifting Costs"
+authors:
+  - family-names: Attri
+    given-names: Krishi
+    email: krishiattriwork@gmail.com
+    affiliation: "Seoul National University"
+doi: 10.5281/zenodo.20631475
+url: "https://github.com/Archerkattri/CERT-FLOW"
+repository-code: "https://github.com/Archerkattri/CERT-FLOW"
+license: MIT
+keywords:
+  - route planning
+  - conformal prediction
+  - path planning
+  - uncertainty quantification
+  - robotics
+  - drifting costs
+abstract: >-
+  Certified route planning under drifting edge costs. Every replanning round
+  emits a high-probability certificate LB <= OPT <= UB on the optimal route
+  cost, built from age-weighted non-exchangeable conformal prediction over
+  drift-adjusted observation residuals, directs paid sensing at the edges
+  that shrink the certified gap fastest, and gates ns-to-microsecond
+  preprocessing (all-pairs snapshot oracle, certified Contraction
+  Hierarchies) behind the certificate so static-speed queries expire the
+  instant drift exceeds tolerance.

certflow-1.0.1/LICENSE

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

certflow-1.0.1/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: certflow
+Version: 1.0.1
+Summary: Certified route planning under drifting costs: conformal LB<=OPT<=UB certificates, certificate-directed sensing, proof-gated preprocessing
+Project-URL: Homepage, https://github.com/Archerkattri/CERT-FLOW
+Project-URL: Repository, https://github.com/Archerkattri/CERT-FLOW
+Project-URL: Documentation, https://github.com/Archerkattri/CERT-FLOW/tree/main/docs
+Project-URL: Issues, https://github.com/Archerkattri/CERT-FLOW/issues
+Author-email: Krishi Attri <krishiattriwork@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: conformal-prediction,contraction-hierarchies,d-star-lite,operations-research,path-planning,robotics,route-planning,uncertainty-quantification
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: fast
+Requires-Dist: numba; extra == 'fast'
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="assets/banner.svg" alt="CERT-FLOW" width="100%"/></p>
+
+<p align="center">
+  <a href="https://pypi.org/project/certflow/"><img alt="PyPI" src="https://img.shields.io/pypi/v/certflow?color=009E73"></a>
+  <a href="#reproducing-every-number"><img alt="tests" src="https://img.shields.io/badge/tests-223%20passing-0072B2"></a>
+  <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-56B4E9">
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-1a7f37">
+  <img alt="coverage claim" src="https://img.shields.io/badge/certificate%20coverage-1.000%20measured-D55E00">
+  <a href="https://doi.org/10.5281/zenodo.20631475"><img alt="DOI" src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20631475-1f6feb"></a>
+</p>
+
+A robot replanning through a world whose costs drift faces a question classical
+planners never answer: **how good is my current route, given that most of the
+map is stale?** CERT-FLOW answers it every round, with a proof: a
+high-probability certificate `LB ≤ OPT ≤ UB` on the optimal route cost, built
+from age-weighted non-exchangeable conformal prediction over drift-adjusted
+observation residuals, and it spends paid sensing exactly where the
+certificate says the gap shrinks fastest.
+
+<p align="center"><img src="assets/overview.png" alt="One CERT round" width="92%"/></p>
+
+## Why it's different
+
+| | classical replanning (D\* Lite, AD\*) | exchangeable conformal (CIA) | **CERT-FLOW** |
+|---|---|---|---|
+| stale map | silently trusts it | coverage collapses (0.95 → **0.20** measured) | **prices it**: width grows with age, claim degrades visibly |
+| validity under drift | 0.02–0.59 measured | gap-dependent | **0.95–1.00, every condition ever run** |
+| sensing | none / heuristic | none | **certificate-directed** (oracle-level regret) |
+| static regime | fast | tight | **proof-gated preprocessing**: ns–µs queries that self-expire |
+
+## Headline results (all reproducible below)
+
+- **Coverage ≥ claimed confidence on every condition ever run**: 17 synthetic
+  regimes, off-model worlds, and two real cities (METR-LA, PEMS-BAY) at up to
+  49% drift-model violation rates.
+- **Route quality**: exactly optimal on known maps (≡ Dijkstra, plus the
+  certificate); travel-regret −0.12 ≈ a clairvoyant oracle in unknown drifting
+  terrain; 2–3× lower regret than freshness/uncertainty/random sensing at
+  equal budget.
+- **Speed**: 3.7 ms p50 / 12 ms p95 per fully-certified round at 60×60 (one
+  CPU core). Certificate-gated preprocessing answers static queries in
+  **269–394 ns** (cost) / 8.7 µs (path), at or below published static-SOTA,
+  and at road scale absorbs cost changes in **0.015–0.34 ms vs ~1 s** for
+  CRP-style recustomization, exact under ±20% perturbation.
+- **Theory T1–T7**: coverage (observable + latent), a certifiability
+  *threshold* (gap ε is sustainable iff sensing rate beats drift, both
+  directions), a √L sum-aware upper certificate with a measured
+  selection-bias hazard and its gate, an **impossibility theorem** (no uniform
+  lower bound can beat Bonferroni by more than log factors, so the certificate's
+  asymmetry is optimal), decision-uniform validity, and a churn-measured floor.
+- **Honest negatives, kept**: the corridor-memory speed hypothesis failed
+  (documented), a predictor's regime claim was downgraded after its test, and
+  the maze negative-control shows exactly where route-critical sensing cannot
+  help. Every known limitation and its disposition:
+  [docs/results/limitations.md](docs/results/limitations.md).
+
+## Quickstart
+
+```bash
+pip install "certflow[fast]"   # "fast" = numba (needed to reproduce the speed numbers)
+python - <<'PY'
+from certflow import CertPlanner, PlannerConfig
+from certflow.drift import grid_world
+
+world = grid_world(6, 6, seed=0, kind="bounded", rho=0.02, noise_scale=0.05)
+planner = CertPlanner(world, (0, 0), (5, 5),
+                      PlannerConfig(epsilon=5.0, alpha_prime=0.2))
+for _ in range(150):
+    cert, sensed = planner.round()
+print(f"[{cert.lb:.2f}, {cert.ub:.2f}] @ confidence {cert.confidence:.2f}, "
+      f"gap {cert.gap:.2f}")
+PY
+```
+
+To develop or reproduce the paper numbers, work from a clone:
+
+```bash
+git clone https://github.com/Archerkattri/CERT-FLOW && cd CERT-FLOW
+python -m venv cert_env && source cert_env/bin/activate
+pip install -e ".[dev,fast]" pandas h5py tables
+pytest   # full suite: 223 with datasets; data-dependent tests skip cleanly without data/
+```
+
+## Reproducing every number
+
+Every quantitative claim traces to a script; the core sweep runs in ~100 s on
+a multicore machine (`CERTFLOW_WORKERS=N` parallelizes seeds bit-identically).
+
+| Result | Script | Documented in |
+|---|---|---|
+| Tier-0 coverage (17 conditions, provable + strict modes) | `scripts/run_tier0.py` | `docs/results/tier0-coverage.md` |
+| CERT vs Gaussian (path level) | `scripts/run_tier0_baselines.py` | `docs/results/tier0-coverage.md` |
+| Edge-level audit (Gaussian break) | `scripts/run_gaussian_break.py` | `docs/results/gaussian-break.md` |
+| Incremental repair latency (T3) | `scripts/run_tier1_latency.py` | `docs/results/tier1-latency.md` |
+| Ablations (κ churn, pre-widening) | `scripts/run_ablations.py` | `docs/results/ablations.md` |
+| Travel regret, unknown terrain | `scripts/run_tier2.py` | `docs/results/tier2-regret.md` |
+| Real traffic (METR-LA / PEMS-BAY) | `scripts/run_metr_la.py [--pems-bay]` | `docs/results/metr-la.md` |
+| MovingAI maps + maze negative control | `scripts/run_movingai.py` | `docs/results/movingai.md` |
+| External algorithms (AD\*, VOI, TASP-degenerate) | `scripts/run_extern_baselines.py` | `docs/results/extern-baselines.md` |
+| CIA exchangeability collapse | `scripts/run_cia_comparison.py` | `docs/results/cia-comparison.md` |
+| E-Graphs + networkx anchors | `scripts/run_repeated_queries.py` | `docs/results/extern-baselines.md` |
+| Lifelong missions (memory vs memoryless) | `scripts/run_lifelong.py` | `docs/results/lifelong.md` |
+| Feature regimes (predictor, decision-uniform) | `scripts/run_feature_regimes.py` | `docs/results/feature-regimes.md` |
+| Scale + engine benchmarks | `scripts/run_scale.py` | `docs/results/scale.md` |
+| Road networks (DIMACS NY/FLA, ALT) | `scripts/run_roadnet.py` | `docs/results/published-speed-comparison.md` |
+| Certified Contraction Hierarchies | `scripts/run_ch.py` | `docs/results/published-speed-comparison.md` |
+
+All scripts accept `--quick`. Real-data runs need `data/` (sources and loaders
+in `data/README.md`; ~230 MB total, links inside).
+
+## How it works
+
+1. **Score** every paid observation with a drift-adjusted residual; weight by
+   age (data-independent geometric weights; exchangeability is *not* assumed).
+2. **Price** each edge as `ĉ ± (λq + ρ·age)`: the conformal quantile pays for
+   noise, the drift term pays for staleness.
+3. **Bound** the optimum from both sides with two incremental searches
+   (optimistic ℓ, conservative u) over a flat-array engine (numba kernels).
+4. **Claim** `LB ≤ OPT ≤ UB` at an honestly-annealed confidence: weak claims
+   during warm-up instead of silence; the claim visibly decays as the map ages.
+5. **Sense** the edge that shrinks the certified gap fastest (route-critical,
+   churn-aware); certification is a *rate*, not a state (T2′).
+6. **When the certificate proves the map tight**, that proof licenses
+   preprocessing: an all-pairs oracle or certified Contraction Hierarchy
+   answering in ns–µs, revoked the instant drift exceeds tolerance.
+
+## Layout
+
+```
+src/certflow/
+  types.py      contracts (World, EdgeBelief, Certificate)
+  conformal.py  weighted non-exchangeable quantiles, Δ_stale, ACI, blocks
+  cert.py       the planner: certify → sense → repair loop, gates, annealing
+  sensing.py    gap-shrink selection + baseline policies
+  fastgraph.py  flat-array CSR engine (numba D* Lite, Dijkstra kernels)
+  snapshot.py   certificate-gated all-pairs oracle (ns queries)
+  ch.py         certified Contraction Hierarchies (231 µs on 264k-node NY)
+  roadnet.py    DIMACS road graphs + exact ALT on landmark lower-bounds
+  drift.py / realworld.py / movingai.py   synthetic, traffic-replay, game maps
+  episodes.py / harness.py / baselines.py runners, seeds, parametric strawman
+docs/results/   one markdown per experiment: numbers, anomalies, verdicts
+docs/specs/     design spec; docs/theory/ working notes
+```
+
+## Citation
+
+Paper: *CERT: Certified Route Planning under Drifting Costs* (preprint
+forthcoming; the citation entry will be updated once the DOI is live).
+
+```bibtex
+@software{attri2026certflow,
+  author = {Attri, Krishi},
+  title  = {{CERT-FLOW}: Certified Route Planning under Drifting Costs},
+  year   = {2026},
+  doi    = {10.5281/zenodo.20631475},
+  url    = {https://github.com/Archerkattri/CERT-FLOW}
+}
+```
+
+The DOI above is the concept DOI (always resolves to the latest archived
+version); [CITATION.cff](CITATION.cff) carries the same metadata in
+machine-readable form.
+
+Paper preprint (extended version): DOI pending engrXiv moderation; this
+section will carry it once posted.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

certflow-1.0.1/README.md

@@ -0,0 +1,169 @@
+<p align="center"><img src="assets/banner.svg" alt="CERT-FLOW" width="100%"/></p>
+
+<p align="center">
+  <a href="https://pypi.org/project/certflow/"><img alt="PyPI" src="https://img.shields.io/pypi/v/certflow?color=009E73"></a>
+  <a href="#reproducing-every-number"><img alt="tests" src="https://img.shields.io/badge/tests-223%20passing-0072B2"></a>
+  <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-56B4E9">
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-1a7f37">
+  <img alt="coverage claim" src="https://img.shields.io/badge/certificate%20coverage-1.000%20measured-D55E00">
+  <a href="https://doi.org/10.5281/zenodo.20631475"><img alt="DOI" src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20631475-1f6feb"></a>
+</p>
+
+A robot replanning through a world whose costs drift faces a question classical
+planners never answer: **how good is my current route, given that most of the
+map is stale?** CERT-FLOW answers it every round, with a proof: a
+high-probability certificate `LB ≤ OPT ≤ UB` on the optimal route cost, built
+from age-weighted non-exchangeable conformal prediction over drift-adjusted
+observation residuals, and it spends paid sensing exactly where the
+certificate says the gap shrinks fastest.
+
+<p align="center"><img src="assets/overview.png" alt="One CERT round" width="92%"/></p>
+
+## Why it's different
+
+| | classical replanning (D\* Lite, AD\*) | exchangeable conformal (CIA) | **CERT-FLOW** |
+|---|---|---|---|
+| stale map | silently trusts it | coverage collapses (0.95 → **0.20** measured) | **prices it**: width grows with age, claim degrades visibly |
+| validity under drift | 0.02–0.59 measured | gap-dependent | **0.95–1.00, every condition ever run** |
+| sensing | none / heuristic | none | **certificate-directed** (oracle-level regret) |
+| static regime | fast | tight | **proof-gated preprocessing**: ns–µs queries that self-expire |
+
+## Headline results (all reproducible below)
+
+- **Coverage ≥ claimed confidence on every condition ever run**: 17 synthetic
+  regimes, off-model worlds, and two real cities (METR-LA, PEMS-BAY) at up to
+  49% drift-model violation rates.
+- **Route quality**: exactly optimal on known maps (≡ Dijkstra, plus the
+  certificate); travel-regret −0.12 ≈ a clairvoyant oracle in unknown drifting
+  terrain; 2–3× lower regret than freshness/uncertainty/random sensing at
+  equal budget.
+- **Speed**: 3.7 ms p50 / 12 ms p95 per fully-certified round at 60×60 (one
+  CPU core). Certificate-gated preprocessing answers static queries in
+  **269–394 ns** (cost) / 8.7 µs (path), at or below published static-SOTA,
+  and at road scale absorbs cost changes in **0.015–0.34 ms vs ~1 s** for
+  CRP-style recustomization, exact under ±20% perturbation.
+- **Theory T1–T7**: coverage (observable + latent), a certifiability
+  *threshold* (gap ε is sustainable iff sensing rate beats drift, both
+  directions), a √L sum-aware upper certificate with a measured
+  selection-bias hazard and its gate, an **impossibility theorem** (no uniform
+  lower bound can beat Bonferroni by more than log factors, so the certificate's
+  asymmetry is optimal), decision-uniform validity, and a churn-measured floor.
+- **Honest negatives, kept**: the corridor-memory speed hypothesis failed
+  (documented), a predictor's regime claim was downgraded after its test, and
+  the maze negative-control shows exactly where route-critical sensing cannot
+  help. Every known limitation and its disposition:
+  [docs/results/limitations.md](docs/results/limitations.md).
+
+## Quickstart
+
+```bash
+pip install "certflow[fast]"   # "fast" = numba (needed to reproduce the speed numbers)
+python - <<'PY'
+from certflow import CertPlanner, PlannerConfig
+from certflow.drift import grid_world
+
+world = grid_world(6, 6, seed=0, kind="bounded", rho=0.02, noise_scale=0.05)
+planner = CertPlanner(world, (0, 0), (5, 5),
+                      PlannerConfig(epsilon=5.0, alpha_prime=0.2))
+for _ in range(150):
+    cert, sensed = planner.round()
+print(f"[{cert.lb:.2f}, {cert.ub:.2f}] @ confidence {cert.confidence:.2f}, "
+      f"gap {cert.gap:.2f}")
+PY
+```
+
+To develop or reproduce the paper numbers, work from a clone:
+
+```bash
+git clone https://github.com/Archerkattri/CERT-FLOW && cd CERT-FLOW
+python -m venv cert_env && source cert_env/bin/activate
+pip install -e ".[dev,fast]" pandas h5py tables
+pytest   # full suite: 223 with datasets; data-dependent tests skip cleanly without data/
+```
+
+## Reproducing every number
+
+Every quantitative claim traces to a script; the core sweep runs in ~100 s on
+a multicore machine (`CERTFLOW_WORKERS=N` parallelizes seeds bit-identically).
+
+| Result | Script | Documented in |
+|---|---|---|
+| Tier-0 coverage (17 conditions, provable + strict modes) | `scripts/run_tier0.py` | `docs/results/tier0-coverage.md` |
+| CERT vs Gaussian (path level) | `scripts/run_tier0_baselines.py` | `docs/results/tier0-coverage.md` |
+| Edge-level audit (Gaussian break) | `scripts/run_gaussian_break.py` | `docs/results/gaussian-break.md` |
+| Incremental repair latency (T3) | `scripts/run_tier1_latency.py` | `docs/results/tier1-latency.md` |
+| Ablations (κ churn, pre-widening) | `scripts/run_ablations.py` | `docs/results/ablations.md` |
+| Travel regret, unknown terrain | `scripts/run_tier2.py` | `docs/results/tier2-regret.md` |
+| Real traffic (METR-LA / PEMS-BAY) | `scripts/run_metr_la.py [--pems-bay]` | `docs/results/metr-la.md` |
+| MovingAI maps + maze negative control | `scripts/run_movingai.py` | `docs/results/movingai.md` |
+| External algorithms (AD\*, VOI, TASP-degenerate) | `scripts/run_extern_baselines.py` | `docs/results/extern-baselines.md` |
+| CIA exchangeability collapse | `scripts/run_cia_comparison.py` | `docs/results/cia-comparison.md` |
+| E-Graphs + networkx anchors | `scripts/run_repeated_queries.py` | `docs/results/extern-baselines.md` |
+| Lifelong missions (memory vs memoryless) | `scripts/run_lifelong.py` | `docs/results/lifelong.md` |
+| Feature regimes (predictor, decision-uniform) | `scripts/run_feature_regimes.py` | `docs/results/feature-regimes.md` |
+| Scale + engine benchmarks | `scripts/run_scale.py` | `docs/results/scale.md` |
+| Road networks (DIMACS NY/FLA, ALT) | `scripts/run_roadnet.py` | `docs/results/published-speed-comparison.md` |
+| Certified Contraction Hierarchies | `scripts/run_ch.py` | `docs/results/published-speed-comparison.md` |
+
+All scripts accept `--quick`. Real-data runs need `data/` (sources and loaders
+in `data/README.md`; ~230 MB total, links inside).
+
+## How it works
+
+1. **Score** every paid observation with a drift-adjusted residual; weight by
+   age (data-independent geometric weights; exchangeability is *not* assumed).
+2. **Price** each edge as `ĉ ± (λq + ρ·age)`: the conformal quantile pays for
+   noise, the drift term pays for staleness.
+3. **Bound** the optimum from both sides with two incremental searches
+   (optimistic ℓ, conservative u) over a flat-array engine (numba kernels).
+4. **Claim** `LB ≤ OPT ≤ UB` at an honestly-annealed confidence: weak claims
+   during warm-up instead of silence; the claim visibly decays as the map ages.
+5. **Sense** the edge that shrinks the certified gap fastest (route-critical,
+   churn-aware); certification is a *rate*, not a state (T2′).
+6. **When the certificate proves the map tight**, that proof licenses
+   preprocessing: an all-pairs oracle or certified Contraction Hierarchy
+   answering in ns–µs, revoked the instant drift exceeds tolerance.
+
+## Layout
+
+```
+src/certflow/
+  types.py      contracts (World, EdgeBelief, Certificate)
+  conformal.py  weighted non-exchangeable quantiles, Δ_stale, ACI, blocks
+  cert.py       the planner: certify → sense → repair loop, gates, annealing
+  sensing.py    gap-shrink selection + baseline policies
+  fastgraph.py  flat-array CSR engine (numba D* Lite, Dijkstra kernels)
+  snapshot.py   certificate-gated all-pairs oracle (ns queries)
+  ch.py         certified Contraction Hierarchies (231 µs on 264k-node NY)
+  roadnet.py    DIMACS road graphs + exact ALT on landmark lower-bounds
+  drift.py / realworld.py / movingai.py   synthetic, traffic-replay, game maps
+  episodes.py / harness.py / baselines.py runners, seeds, parametric strawman
+docs/results/   one markdown per experiment: numbers, anomalies, verdicts
+docs/specs/     design spec; docs/theory/ working notes
+```
+
+## Citation
+
+Paper: *CERT: Certified Route Planning under Drifting Costs* (preprint
+forthcoming; the citation entry will be updated once the DOI is live).
+
+```bibtex
+@software{attri2026certflow,
+  author = {Attri, Krishi},
+  title  = {{CERT-FLOW}: Certified Route Planning under Drifting Costs},
+  year   = {2026},
+  doi    = {10.5281/zenodo.20631475},
+  url    = {https://github.com/Archerkattri/CERT-FLOW}
+}
+```
+
+The DOI above is the concept DOI (always resolves to the latest archived
+version); [CITATION.cff](CITATION.cff) carries the same metadata in
+machine-readable form.
+
+Paper preprint (extended version): DOI pending engrXiv moderation; this
+section will carry it once posted.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

certflow-1.0.1/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "certflow"
+version = "1.0.1"
+authors = [{name = "Krishi Attri", email = "krishiattriwork@gmail.com"}]
+license = {text = "MIT"}
+description = "Certified route planning under drifting costs: conformal LB<=OPT<=UB certificates, certificate-directed sensing, proof-gated preprocessing"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = [
+    "route-planning",
+    "conformal-prediction",
+    "path-planning",
+    "uncertainty-quantification",
+    "robotics",
+    "d-star-lite",
+    "contraction-hierarchies",
+    "operations-research",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/Archerkattri/CERT-FLOW"
+Repository = "https://github.com/Archerkattri/CERT-FLOW"
+Documentation = "https://github.com/Archerkattri/CERT-FLOW/tree/main/docs"
+Issues = "https://github.com/Archerkattri/CERT-FLOW/issues"
+
+[project.optional-dependencies]
+fast = ["numba"]
+dev = ["pytest>=7.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/certflow"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/certflow",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "CITATION.cff",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

certflow-1.0.1/src/certflow/__init__.py

@@ -0,0 +1,40 @@
+"""CERT-FLOW: certified route planning under drifting costs.
+
+Every replanning round emits a high-probability certificate LB <= OPT <= UB
+on the optimal route cost, built from age-weighted non-exchangeable conformal
+prediction over drift-adjusted observation residuals, and directs paid sensing
+at the edges that shrink the certified gap fastest.
+
+Quickstart::
+
+    from certflow import CertPlanner, PlannerConfig
+    from certflow.drift import grid_world
+
+    world = grid_world(6, 6, seed=0, kind="bounded", rho=0.02, noise_scale=0.05)
+    planner = CertPlanner(world, (0, 0), (5, 5),
+                          PlannerConfig(epsilon=5.0, alpha_prime=0.2))
+    for _ in range(150):
+        cert, sensed = planner.round()
+    print(cert.lb, cert.ub, cert.confidence)
+
+Submodules: conformal (quantile machinery), cert (the planner loop), sensing
+(observation selection), fastgraph (flat-array engine), snapshot / ch
+(certificate-gated preprocessing), drift / realworld / movingai / roadnet
+(worlds and graphs), harness / episodes / oracle (experiment infrastructure).
+"""
+from certflow.cert import CertPlanner, PlannerConfig
+from certflow.conformal import ACITracker, ConformalScorer
+from certflow.types import Certificate, EdgeBelief, World
+
+__version__ = "1.0.1"
+
+__all__ = [
+    "ACITracker",
+    "CertPlanner",
+    "Certificate",
+    "ConformalScorer",
+    "EdgeBelief",
+    "PlannerConfig",
+    "World",
+    "__version__",
+]