{"id":51431478,"url":"https://github.com/no-way-labs/minimum-state-product","last_synced_at":"2026-07-05T04:02:54.821Z","repository":{"id":353655727,"uuid":"1178892429","full_name":"no-way-labs/minimum-state-product","owner":"no-way-labs","description":"Minimum state products on Dijkstra's self-stabilizing token ring — exact values for n = 3 through 9 and a large-n conjecture supported through n = 10. Paper, sorry-free Lean 4 formalization, Python research probes, and an independent verifier.","archived":false,"fork":false,"pushed_at":"2026-07-03T17:22:56.000Z","size":15456,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T19:19:38.257Z","etag":null,"topics":["automated-reasoning","combinatorics","dijkstra","distributed-computing","formal-verification","lean4","llm-agents","mathematics","self-stabilization","token-ring"],"latest_commit_sha":null,"homepage":"https://doi.org/10.5281/zenodo.19744462","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/no-way-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T13:27:49.000Z","updated_at":"2026-07-03T17:23:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/no-way-labs/minimum-state-product","commit_stats":null,"previous_names":["no-way-labs/minimum-state-product"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/no-way-labs/minimum-state-product","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no-way-labs%2Fminimum-state-product","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no-way-labs%2Fminimum-state-product/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no-way-labs%2Fminimum-state-product/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no-way-labs%2Fminimum-state-product/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/no-way-labs","download_url":"https://codeload.github.com/no-way-labs/minimum-state-product/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no-way-labs%2Fminimum-state-product/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35142824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automated-reasoning","combinatorics","dijkstra","distributed-computing","formal-verification","lean4","llm-agents","mathematics","self-stabilization","token-ring"],"created_at":"2026-07-05T04:02:54.090Z","updated_at":"2026-07-05T04:02:54.734Z","avatar_url":"https://github.com/no-way-labs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minimum state product for self-stabilizing token rings\n\n[![DOI](https://zenodo.org/badge/1178892429.svg)](https://doi.org/10.5281/zenodo.19744462)\n\nCompanion artifact for the paper\n**\"Minimum State Products on Dijkstra's Token Ring: Exact Values for\nn = 3 through 9 and a large-n conjecture supported through n = 10.\"**\n\nZenodo archive DOI: [10.5281/zenodo.19744463](https://doi.org/10.5281/zenodo.19744463)\n\n## What's here\n\n- `paper/` — the paper source (`main.tex`, `references.bib`) and built\n  PDF (`main.pdf`).\n- `lean/` — the Lean 4 / Mathlib formalization. `lake build` in this\n  directory should succeed on the pinned toolchain.\n- `probes/` — the full set of Python research probes (~2,100 files,\n  ~633k LoC). These back every empirical claim in the paper, including\n  the landscape-detail appendix. The top level collects the primary\n  Claude-agent probe lineage (2,050 scripts); `probes/gpt/` collects a\n  parallel GPT-agent lineage (80 probes + 14 pytest regression tests) —\n  the dual-agent methodology used to cross-check results is described\n  in `docs/ra_le_workflow.md`.\n- `docs/` — the independent Python verifier, research memos, and the\n  RA / PA / LE workflow documentation.\n- `docs/lean_docs/` — Lean-program findings memos, post-mortems, plans,\n  roadmaps, and the per-session audit trail.\n- `exploration_logs/` — 30 chronological narrative research logs\n  spanning the Python-probe and Lean-formalization sides of the program.\n- `corpus.json`, `corpus_canonical.json`, `coverage_manifest.json`, and\n  other top-level data artifacts — paper-cited datasets. See the paper's\n  Appendix L for the full manifest.\n- `REVIEWER.md` — theorem ↔ single-reproduction-command map; the\n  contract between the paper and this artifact.\n- `requirements.txt` — pinned Python dependencies (numpy, scipy,\n  z3-solver, more-itertools). Only required for the exploratory probes\n  that use z3 / scipy; the dispositive checks are stdlib-only.\n\nThe volume is deliberate. A reader should see that the paper's\nsurviving results are the ridge of a much larger exploratory program.\n\n## Start here\n\n1. Read `paper/main.pdf`.\n2. Open `REVIEWER.md` — each theorem, observation, and conjecture in\n   the paper is paired with a single reproduction command.\n3. Skim `docs/ra_le_workflow.md` for the research-workflow methodology.\n4. See [Reproducing the results](#reproducing-the-results) below for\n   build, verify, and re-run instructions.\n5. `docs/lean_docs/lb_all_paths_history.md` is the master ledger of\n   attempted lower-bound routes. `exploration_logs/` collects 30\n   chronological narrative logs from both agent lineages — Python probe\n   side (`exploration_log_clb.md`, `exploration_log_cup2.md`,\n   `exploration_log_3cb_*.md`, `exploration_log_allkiller.md`,\n   `exploration_log_glb.md`, `exploration_log_m9_lb.md`, etc.) and Lean\n   formalization side (`exploration_log_lean.md`, `exploration_log_lb.md`,\n   `exploration_log_ax.md`, etc.) — the day-to-day research record.\n\n## Scope\n\nThe Lean formalization is split into two targets so that *proved\nclaims* and *open research obligations* are distinguished in the build\nverdict itself:\n\n- `lake build` (default target `LeanMn`) — verifies every paper-cited\n  theorem. Compiles **sorry-free** with zero `declaration uses sorry`\n  warnings.\n- `lake build LeanMn.Research` — compiles the sink-kernel lower-bound\n  program for general `n`. Builds successfully but surfaces 5\n  `declaration uses sorry` warnings corresponding to the\n  stated-but-not-yet-proved obligations the paper discusses in §7 and\n  Appendix K.\n\nA reader running `lake build` on a fresh clone should see a clean green\nverdict for the proved results.\n\nThe independent Python verifier re-checks every stored witness and every\nrejection certificate. The exhaustive-search coverage manifest\nreproduces bit-for-bit (overall `manifest_hash` = `f684ed53216a0d7f`,\nthe truncated SHA-256 over the manifest payload computed by\n`generate_manifest.py`; the file's own SHA-256 depends on JSON\nwhitespace and is not the stability check).\n\nNot every probe under `probes/` is runnable standalone — some reference\nintermediate data produced by sibling probes, and a small number\noriginally imported from external research projects. Affected files\ncarry an in-file note. The full set is shipped as a research record,\nnot as a product.\n\n## Reproducing the results\n\n### Python version\n\nPython 3.11 or newer (tested on 3.13.2). The dispositive checks\n(`docs/verifier.py`, `docs/verify_witnesses.py`, and\n`probes/exhaustive_search/`) are standard-library only — no `pip\ninstall` required to reproduce the paper-cited verdicts.\n\nThe exploratory probes under `probes/`, the SMT-based certificates\nunder `docs/axisc/` + `docs/m5rel/`, the circulation-LP detector under\n`docs/topo_revival/`, and `exact_check.py` (the rationalising LP post-\ncheck) import `numpy`, `scipy`, `z3-solver`, or `more-itertools`. Pin\nthem all at once with:\n\n```bash\npython3 -m venv .venv \u0026\u0026 . .venv/bin/activate\npip install -r requirements.txt\n```\n\nThe pins in `requirements.txt` are exact; loosening them breaks the\nbit-for-bit reproducibility claim.\n\n\n### Rebuild the paper\n\nRequires a TeX Live (or equivalent) distribution with `pdflatex` and\n`bibtex`. Takes ~1–2 minutes.\n\n```bash\ncd paper\npdflatex main \u0026\u0026 bibtex main \u0026\u0026 pdflatex main \u0026\u0026 pdflatex main\n```\n\n### Build the Lean formalization\n\nRequires [elan](https://github.com/leanprover/elan) (Lean version manager).\nThe toolchain is pinned to `leanprover/lean4:v4.28.0` by\n`lean/lean-toolchain`; `elan` will download it on first use.\n\n```bash\ncd lean\nlake exe cache get    # download prebuilt Mathlib .olean cache (~5 GB)\nlake build            # compile this project on top\n```\n\n**Do not skip `lake exe cache get`** unless you actually want to\nrecompile all of Mathlib from source. With the cache, first-time build\ntakes roughly **25–55 minutes end-to-end** (cache download ~10–20 min,\nproject build ~10–30 min, the latter dominated by 120 `native_decide`\ninvocations that each fork a C compile + run). Without the cache,\nMathlib rebuilds from source and the total is 1.5–4 hours depending\non your CPU.\n\nSubsequent builds reuse `.lake/build/` and take seconds to a few\nminutes unless you touch a heavily-imported file.\n\n**Dependencies** are pinned by `lake-manifest.json`: Mathlib v4.28.0,\nplus batteries, aesop, Qq, proofwidgets, plausible, importGraph, Cli,\nLeanSearchClient. No manual dep management required.\n\nThis command builds `lean_lib LeanMn`, the **proved tree**. It verifies\nevery paper-cited theorem and compiles **sorry-free**. Specifically, the\nproved tree covers:\n\n- The `M_4 = 24` exact-value theorem (`SmallN/Theorem.lean`,\n  `LowerBound/SmallN/LB2222.lean`).\n- Upper-bound constructions for all `n \u003e= 4`, including the CUP-2\n  certificate chain (`UpperBound/`, `SmallN/Cup2Convergence.lean`,\n  `Cycle.lean`, `Tables.lean`).\n- Proved lower-bound infrastructure (`LowerBound/CycleTypes.lean`,\n  `FireCountNe.lean`, `GoodCycleBasics.lean`, the `EntryConflict/`\n  tree, and the sorry-free SK primitives `Forcing`, `SinkKernel`,\n  `PartialDet`, `SlabCounting`).\n\n#### Building the research tree (open obligations)\n\nThe sink-kernel lower-bound program for general `n` is research in\nprogress. These modules are collected under `LeanMn.Research`:\n\n```bash\ncd lean\nlake build LeanMn.Research   # after lake exe cache get + lake build\n```\n\nIncremental on top of the proved-tree build; adds a few minutes.\nCompiles successfully but surfaces **5 `declaration uses sorry`\nwarnings** — the stated-but-not-yet-proved obligations described in\nthe paper's §7 and Appendix K:\n\n- `LowerBound/SK/HammingTube.lean` — 2 obligations\n- `LowerBound/SK/EdgeMajorityB2.lean` — 2 obligations\n- `LowerBound/SK/SlabCountingRing.lean` — 1 obligation\n\nThese files compile, meaning their *statements* are well-typed and\nusable by downstream modules (`CloudsTheorem`, `SmallN/CloudsLB`,\n`LargeN/CloudsLB`). Their *proofs* remain to be filled in.\n\n### Re-run the independent verifier\n\nPure Python, stdlib-only — no external package installs required.\nSpot-checks every stored witness and rejection certificate. Runs in\nunder a minute.\n\n```bash\npython3 docs/verifier.py\npython3 docs/verify_witnesses.py\n```\n\n### Reproduce the exhaustive lower-bound coverage manifest\n\nStdlib-only. Deterministic; the `manifest_hash` field inside\n`coverage_manifest.json` reproduces bit-for-bit to\n`f684ed53216a0d7f` (truncated SHA-256 over the C1 + C2 payload).\nThe C1 + C2 portions populate in seconds from a clean clone.\n\n```bash\npython3 probes/exhaustive_search/driver.py           # C1+C2 summary\npython3 probes/exhaustive_search/generate_manifest.py  # writes coverage_manifest.json\n```\n\nThe per-certificate rejection stream (C3 + C4 + C5) ships in full\nfor `n ∈ {3, 4}` and the all-binary orientation at `n = 5`;\naggregate counts for the remaining `n = 5` orientations are in\n`artifacts/rejections/summary.json`. Regenerating a full\nper-orientation stream for `n ∈ {5, ..., 9}` is done via the\ncompiled C worker (seconds to hours per orientation on a single\ncore):\n\n```bash\ncd probes/exhaustive_search \u0026\u0026 make\n./exhaustive --n N --ms \u003csorted\u003e --orient \u003corient\u003e \u003e out.jsonl\npython3 driver.py --replay out.jsonl\n```\n\nSee `probes/exhaustive_search/REJECTION_STREAM.md` for the full\nship-state rules.\n\n### Re-run a probe\n\nEvery `.py` under `probes/` is a research probe. Most reference\nrepo-relative paths (e.g. `./probes/...`) and expect to be run from the\nrepository root:\n\n```bash\npython3 probes/\u003cprobe-name\u003e.py\n```\n\nSee the per-probe exploration-log memos under `probes/*.md` for\ninterpretation. Probes under `probes/branch_b_bypass/` and\n`probes/sk_*_out/` are session-specific research artifacts — some are\nself-contained, others depend on intermediate data generated by sibling\nprobes. The paper's Appendix §K (landscape-detail) indicates the\nprovenance for each reported result.\n\n#### GPT-agent probe lineage\n\n`probes/gpt/` collects a parallel GPT-agent probe lineage (~90 scripts\nplus 14 pytest regression tests under `probes/gpt/tests/`). These were\nproduced by a second agent running against the same problem statement;\nthe dual-agent methodology is documented in `docs/ra_le_workflow.md`.\n\n```bash\npython3 probes/gpt/\u003cprobe-name\u003e.py\npython3 -m unittest probes.gpt.tests.test_\u003cprobe-name\u003e\n```\n\nThe pytest suite is the only regression-test coverage in this artifact\n— the Claude-agent lineage was validated against paper-cited witnesses\nvia `docs/verifier.py` rather than unit tests. A handful of GPT-lineage\ntests invoke an external `src_comp_ver/` verifier that is not shipped\nin this artifact.\n\n### Note on runtime scope\n\nNot every probe in this repository is runnable standalone. Some\noriginally depended on data or tools outside this artifact (e.g.\n`probes/brainstorm_parity.py` references an external `paper3_dev_010`\ngenerator that is not included). Affected files carry an in-file note.\nThe full set is shipped for research-record transparency, not because\nevery probe is reproducible in isolation.\n\n## Contact\n\nKeston Aquino-Michaels — \u003ckestonamichaels@gmail.com\u003e.\n\nThe single best form of referee feedback is a reproducibility issue\non any row of `REVIEWER.md` — please quote the command you ran, the\nexpected output per that file, and the actual output.\n\n## License\n\n- Code (`probes/`, `docs/`, `lean/`) and repository infrastructure: [MIT](LICENSE)\n- Paper (`paper/`): [CC BY 4.0](paper/LICENSE)\n\n## Citation\n\nSee `CITATION.cff`. (Zenodo DOI is assigned at archive-mint time.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fno-way-labs%2Fminimum-state-product","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fno-way-labs%2Fminimum-state-product","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fno-way-labs%2Fminimum-state-product/lists"}