From 4fc5f0229598a05c08b78769b2d06f3713abf30b Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:09:20 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 18 + ARCHITECTURE.md | 26 - AUTHORS.adoc | 83 ++ AUTHORS.md | 83 -- CHANGELOG.adoc | 383 +++++++ CHANGELOG.md | 320 ------ CODE_OF_CONDUCT.adoc | 170 +++ CODE_OF_CONDUCT.md | 121 --- CONTRIBUTING.adoc | 244 +---- CONTRIBUTING.md | 30 - GOVERNANCE.adoc | 170 +-- GOVERNANCE.md | 24 - README.adoc | 617 +++++++++++ README.md | 665 ------------ SECURITY.adoc | 257 +++++ SECURITY.md | 253 ----- TEST_CI_ECHIDNA.adoc | 10 + TEST_CI_ECHIDNA.md | 10 - audits/audit-ffi-boundary.adoc | 328 ++++++ audits/audit-ffi-boundary.md | 304 ------ audits/audit-pa021-axioms-2026-05-26.adoc | 69 ++ audits/audit-pa021-axioms-2026-05-26.md | 59 -- crates/echidna-core-spark/CREUSOT-SETUP.adoc | 159 +++ crates/echidna-core-spark/CREUSOT-SETUP.md | 137 --- crates/echidna-mcp/README.adoc | 239 +++++ crates/echidna-mcp/README.md | 207 ---- crates/echidna-wire/schemas/VERSIONING.adoc | 79 ++ crates/echidna-wire/schemas/VERSIONING.md | 75 -- .../content/api/{graphql.md => graphql.adoc} | 74 +- docs-site/content/api/{grpc.md => grpc.adoc} | 72 +- docs-site/content/api/rest.adoc | 149 +++ docs-site/content/api/rest.md | 146 --- docs-site/content/index.adoc | 63 ++ docs-site/content/index.md | 62 -- ...NTIC_FEATURES.md => AGENTIC_FEATURES.adoc} | 421 ++++---- docs/{ARCHITECTURE.md => ARCHITECTURE.adoc} | 239 +++-- docs/ASPECT_IMPLEMENTATION_SUMMARY.adoc | 434 ++++++++ docs/ASPECT_IMPLEMENTATION_SUMMARY.md | 446 -------- docs/ASPECT_QUICK_START.adoc | 181 ++++ docs/ASPECT_QUICK_START.md | 164 --- ...{ASPECT_TAGGING.md => ASPECT_TAGGING.adoc} | 300 +++--- docs/COQ_BACKEND_IMPLEMENTATION.adoc | 448 ++++++++ docs/COQ_BACKEND_IMPLEMENTATION.md | 447 -------- docs/CORPUS-ADAPTERS.adoc | 169 +++ docs/CORPUS-ADAPTERS.md | 128 --- docs/CORPUS.adoc | 257 +++++ docs/CORPUS.md | 217 ---- ...REFERENCE.md => CVC5_QUICK_REFERENCE.adoc} | 392 ++++--- docs/DEBT.adoc | 402 +++++++ docs/DEBT.md | 356 ------- docs/ECOSYSTEM-INTEGRATION.adoc | 194 ++++ docs/ECOSYSTEM-INTEGRATION.md | 183 ---- docs/ENV-VARS.adoc | 103 ++ docs/ENV-VARS.md | 65 -- docs/HOSTING.adoc | 137 +++ docs/HOSTING.md | 121 --- docs/HP-BACKEND-ONBOARDING.adoc | 164 +++ docs/HP-BACKEND-ONBOARDING.md | 151 --- docs/Language-Provability-Analysis.adoc | 368 +++++++ docs/Language-Provability-Analysis.md | 432 -------- docs/METAMATH_BACKEND.adoc | 356 +++++++ docs/METAMATH_BACKEND.md | 340 ------ ..._QUICK_START.md => MIZAR_QUICK_START.adoc} | 291 +++--- docs/PROOF-NEEDS.adoc | 298 ++++++ docs/PROOF-NEEDS.md | 176 ---- docs/PROVER_COUNT.adoc | 202 ++++ docs/PROVER_COUNT.md | 134 --- docs/ROADMAP.adoc | 340 ++++++ docs/ROADMAP.md | 262 ----- docs/SUPPORTED_PROVERS.adoc | 117 +++ docs/SUPPORTED_PROVERS.md | 94 -- docs/TEST-NEEDS.adoc | 300 ++++++ docs/TEST-NEEDS.md | 259 ----- docs/academic/ACADEMIC_PAPER.adoc | 476 +++++++++ docs/academic/ACADEMIC_PAPER.md | 435 -------- .../architecture/CHAPEL-SATURATION-HOOKS.adoc | 211 ++++ docs/architecture/CHAPEL-SATURATION-HOOKS.md | 191 ---- .../CORRECTNESS-ARCHITECTURE.adoc | 309 ++++++ docs/architecture/CORRECTNESS-ARCHITECTURE.md | 320 ------ docs/architecture/CROSS-REPO-PROOF-DAG.adoc | 327 ++++++ docs/architecture/CROSS-REPO-PROOF-DAG.md | 306 ------ docs/architecture/JULIA-SATURATION-HOOKS.adoc | 201 ++++ docs/architecture/JULIA-SATURATION-HOOKS.md | 159 --- .../TYPE-DISCIPLINE-EMBEDDING.adoc | 585 +++++++++++ .../architecture/TYPE-DISCIPLINE-EMBEDDING.md | 464 -------- docs/architecture/VERISIM-ER-SCHEMA.adoc | 438 ++++++++ docs/architecture/VERISIM-ER-SCHEMA.md | 331 ------ .../bench/2026-05-30-chapel-mrr-baseline.adoc | 145 +++ docs/bench/2026-05-30-chapel-mrr-baseline.md | 139 --- .../2026-04-28-corpus-and-design-search.adoc | 208 ++++ .../2026-04-28-corpus-and-design-search.md | 204 ---- .../2026-05-19-ci-baseline-triage.adoc | 123 +++ .../2026-05-19-ci-baseline-triage.md | 100 -- .../2026-05-30-chapel-l23-cancel-token.adoc | 154 +++ .../2026-05-30-chapel-l23-cancel-token.md | 155 --- .../2026-05-30-chapel-pic-rebuild.adoc | 162 +++ .../2026-05-30-chapel-pic-rebuild.md | 148 --- .../2026-05-30-chapel-rehabilitation.adoc | 170 +++ .../2026-05-30-chapel-rehabilitation.md | 177 ---- .../2026-05-31-chapel-prover-spawn-hooks.adoc | 174 +++ .../2026-05-31-chapel-prover-spawn-hooks.md | 182 ---- .../2026-06-01-saturation-campaign.adoc | 178 ++++ .../2026-06-01-saturation-campaign.md | 176 ---- docs/deployment/DEPLOYMENT_GUIDE.adoc | 33 + docs/deployment/DEPLOYMENT_GUIDE.md | 26 - docs/design/ADVANCED_TYPING_GAP_ANALYSIS.adoc | 423 ++++++++ docs/design/ADVANCED_TYPING_GAP_ANALYSIS.md | 462 -------- docs/design/OTHER_SYSTEMS_USP_PPA.adoc | 526 ++++++++++ docs/design/OTHER_SYSTEMS_USP_PPA.md | 436 -------- docs/design/SPARK_ADOPTION_PLAN.adoc | 315 ++++++ docs/design/SPARK_ADOPTION_PLAN.md | 284 ----- .../TYPING_CAPABILITIES_COMPARISON.adoc | 292 ++++++ docs/design/TYPING_CAPABILITIES_COMPARISON.md | 212 ---- ...MEWORK.md => JUST_AND_MUST_FRAMEWORK.adoc} | 348 +++--- ...md => TRUST_AND_VALIDATION_FRAMEWORK.adoc} | 451 ++++---- ...IDE.md => TRUST_IMPLEMENTATION_GUIDE.adoc} | 204 ++-- docs/handover/B7-AUDIT-CORRECTION.adoc | 114 ++ docs/handover/B7-AUDIT-CORRECTION.md | 111 -- docs/handover/HANDOVER-INDEX.adoc | 145 +++ docs/handover/HANDOVER-INDEX.md | 92 -- docs/handover/L1-CAPNPROTO-PROMPT.adoc | 149 +++ docs/handover/L1-CAPNPROTO-PROMPT.md | 116 -- docs/handover/L2-CHAPEL-PROMPT.adoc | 132 +++ docs/handover/L2-CHAPEL-PROMPT.md | 101 -- docs/handover/L3-LIVE-PROVER-CI-PROMPT.adoc | 114 ++ docs/handover/L3-LIVE-PROVER-CI-PROMPT.md | 90 -- docs/handover/PHASE-3-PROMPT.adoc | 308 ++++++ docs/handover/PHASE-3-PROMPT.md | 293 ------ docs/handover/PRODUCTION-WIRING-PLAN.adoc | 234 +++++ docs/handover/PRODUCTION-WIRING-PLAN.md | 171 --- .../PROVER-CORPUS-SATURATION-LANE.adoc | 170 +++ .../handover/PROVER-CORPUS-SATURATION-LANE.md | 137 --- docs/handover/README.adoc | 59 ++ docs/handover/README.md | 45 - ...UNBOOK.md => S4-LOOP-CLOSURE-RUNBOOK.adoc} | 144 +-- docs/handover/S5-VERIFICATION-RUNBOOK.adoc | 144 +++ docs/handover/S5-VERIFICATION-RUNBOOK.md | 113 -- docs/handover/SESSION-HANDOFF-2026-06-15.adoc | 151 +++ docs/handover/SESSION-HANDOFF-2026-06-15.md | 72 -- docs/handover/STATE.adoc | 266 +++++ docs/handover/STATE.md | 155 --- docs/handover/SUGGEST-CLI-PROMPT.adoc | 388 +++++++ docs/handover/SUGGEST-CLI-PROMPT.md | 380 ------- docs/handover/THEOREM-METADATA-MIGRATION.adoc | 85 ++ docs/handover/THEOREM-METADATA-MIGRATION.md | 72 -- docs/handover/TODO.adoc | 399 +++++++ docs/handover/TODO.md | 206 ---- docs/handover/llm-warmup-dev.adoc | 240 +++++ docs/handover/llm-warmup-dev.md | 210 ---- docs/handover/llm-warmup-user.adoc | 116 ++ docs/handover/llm-warmup-user.md | 109 -- .../AGDA_IMPLEMENTATION_SUMMARY.adoc | 658 ++++++++++++ .../AGDA_IMPLEMENTATION_SUMMARY.md | 606 ----------- .../CVC5_IMPLEMENTATION_SUMMARY.adoc | 988 ++++++++++++++++++ .../CVC5_IMPLEMENTATION_SUMMARY.md | 947 ----------------- .../HOL_LIGHT_IMPLEMENTATION.adoc | 320 ++++++ .../HOL_LIGHT_IMPLEMENTATION.md | 305 ------ .../MIZAR_IMPLEMENTATION_SUMMARY.adoc | 936 +++++++++++++++++ .../MIZAR_IMPLEMENTATION_SUMMARY.md | 970 ----------------- .../Z3_IMPLEMENTATION_SUMMARY.adoc | 433 ++++++++ .../Z3_IMPLEMENTATION_SUMMARY.md | 441 -------- ...belle-backend.md => isabelle-backend.adoc} | 400 +++---- docs/releases/RELEASE_NOTES_v1.2.adoc | 236 +++++ docs/releases/RELEASE_NOTES_v1.2.md | 266 ----- docs/releases/RELEASE_NOTES_v1.3.adoc | 356 +++++++ docs/releases/RELEASE_NOTES_v1.3.md | 371 ------- ...26-06-06-hypatia-alert-classification.adoc | 174 +++ ...2026-06-06-hypatia-alert-classification.md | 146 --- .../audit/pillar-audit-2026-04-15.adoc | 25 + docs/reports/audit/pillar-audit-2026-04-15.md | 19 - docs/tech-debt-2026-05-26.adoc | 88 ++ docs/tech-debt-2026-05-26.md | 77 -- docs/training-runs/2026-06-02.adoc | 199 ++++ docs/training-runs/2026-06-02.md | 131 --- echidna-playground/CODE_OF_CONDUCT.adoc | 339 ++++++ echidna-playground/CODE_OF_CONDUCT.md | 327 ------ echidna-playground/SECURITY.adoc | 434 ++++++++ echidna-playground/SECURITY.md | 370 ------- .../melange-example/README.adoc | 29 + echidna-playground/melange-example/README.md | 27 - examples/README.adoc | 82 ++ examples/README.md | 74 -- hooks/README.adoc | 27 + hooks/README.md | 24 - metrics/README.adoc | 50 + metrics/README.md | 40 - proofs/acl2/README.adoc | 129 +++ proofs/acl2/README.md | 125 --- proofs/hol4/README.adoc | 220 ++++ proofs/hol4/README.md | 211 ---- proofs/lean/README.adoc | 182 ++++ proofs/lean/README.md | 201 ---- proofs/lean/THEOREMS.adoc | 361 +++++++ proofs/lean/THEOREMS.md | 314 ------ proofs/pvs/README.adoc | 158 +++ proofs/pvs/README.md | 157 --- reports/panic-attack-chunks/SUMMARY.adoc | 83 ++ reports/panic-attack-chunks/SUMMARY.md | 90 -- schemas/VERSIONING.adoc | 141 +++ schemas/VERSIONING.md | 108 -- site/docs/api/core.adoc | 188 ++++ site/docs/api/core.md | 181 ---- site/docs/api/{graphql.md => graphql.adoc} | 106 +- site/docs/api/{grpc.md => grpc.adoc} | 78 +- site/docs/api/rest.adoc | 108 ++ site/docs/api/rest.md | 106 -- site/docs/index.adoc | 83 ++ site/docs/index.md | 81 -- site/index.adoc | 66 ++ site/index.md | 66 -- src/chapel/README.adoc | 169 +++ src/chapel/README.md | 142 --- src/chapel/RESULTS.adoc | 205 ++++ src/chapel/RESULTS.md | 181 ---- src/interfaces/README.adoc | 119 +++ src/interfaces/README.md | 107 -- src/julia/README.adoc | 631 +++++++++++ src/julia/README.md | 599 ----------- tests/README.adoc | 436 ++++++++ tests/README.md | 435 -------- tools/invariant-path/README.adoc | 26 + tools/invariant-path/README.md | 25 - training_data/floor_progress.adoc | 7 + training_data/floor_progress.md | 5 - 224 files changed, 26387 insertions(+), 24143 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 AUTHORS.adoc delete mode 100644 AUTHORS.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 GOVERNANCE.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST_CI_ECHIDNA.adoc delete mode 100644 TEST_CI_ECHIDNA.md create mode 100644 audits/audit-ffi-boundary.adoc delete mode 100644 audits/audit-ffi-boundary.md create mode 100644 audits/audit-pa021-axioms-2026-05-26.adoc delete mode 100644 audits/audit-pa021-axioms-2026-05-26.md create mode 100644 crates/echidna-core-spark/CREUSOT-SETUP.adoc delete mode 100644 crates/echidna-core-spark/CREUSOT-SETUP.md create mode 100644 crates/echidna-mcp/README.adoc delete mode 100644 crates/echidna-mcp/README.md create mode 100644 crates/echidna-wire/schemas/VERSIONING.adoc delete mode 100644 crates/echidna-wire/schemas/VERSIONING.md rename docs-site/content/api/{graphql.md => graphql.adoc} (66%) rename docs-site/content/api/{grpc.md => grpc.adoc} (75%) create mode 100644 docs-site/content/api/rest.adoc delete mode 100644 docs-site/content/api/rest.md create mode 100644 docs-site/content/index.adoc delete mode 100644 docs-site/content/index.md rename docs/{AGENTIC_FEATURES.md => AGENTIC_FEATURES.adoc} (67%) rename docs/{ARCHITECTURE.md => ARCHITECTURE.adoc} (54%) create mode 100644 docs/ASPECT_IMPLEMENTATION_SUMMARY.adoc delete mode 100644 docs/ASPECT_IMPLEMENTATION_SUMMARY.md create mode 100644 docs/ASPECT_QUICK_START.adoc delete mode 100644 docs/ASPECT_QUICK_START.md rename docs/{ASPECT_TAGGING.md => ASPECT_TAGGING.adoc} (54%) create mode 100644 docs/COQ_BACKEND_IMPLEMENTATION.adoc delete mode 100644 docs/COQ_BACKEND_IMPLEMENTATION.md create mode 100644 docs/CORPUS-ADAPTERS.adoc delete mode 100644 docs/CORPUS-ADAPTERS.md create mode 100644 docs/CORPUS.adoc delete mode 100644 docs/CORPUS.md rename docs/{CVC5_QUICK_REFERENCE.md => CVC5_QUICK_REFERENCE.adoc} (51%) create mode 100644 docs/DEBT.adoc delete mode 100644 docs/DEBT.md create mode 100644 docs/ECOSYSTEM-INTEGRATION.adoc delete mode 100644 docs/ECOSYSTEM-INTEGRATION.md create mode 100644 docs/ENV-VARS.adoc delete mode 100644 docs/ENV-VARS.md create mode 100644 docs/HOSTING.adoc delete mode 100644 docs/HOSTING.md create mode 100644 docs/HP-BACKEND-ONBOARDING.adoc delete mode 100644 docs/HP-BACKEND-ONBOARDING.md create mode 100644 docs/Language-Provability-Analysis.adoc delete mode 100644 docs/Language-Provability-Analysis.md create mode 100644 docs/METAMATH_BACKEND.adoc delete mode 100644 docs/METAMATH_BACKEND.md rename docs/{MIZAR_QUICK_START.md => MIZAR_QUICK_START.adoc} (65%) create mode 100644 docs/PROOF-NEEDS.adoc delete mode 100644 docs/PROOF-NEEDS.md create mode 100644 docs/PROVER_COUNT.adoc delete mode 100644 docs/PROVER_COUNT.md create mode 100644 docs/ROADMAP.adoc delete mode 100644 docs/ROADMAP.md create mode 100644 docs/SUPPORTED_PROVERS.adoc delete mode 100644 docs/SUPPORTED_PROVERS.md create mode 100644 docs/TEST-NEEDS.adoc delete mode 100644 docs/TEST-NEEDS.md create mode 100644 docs/academic/ACADEMIC_PAPER.adoc delete mode 100644 docs/academic/ACADEMIC_PAPER.md create mode 100644 docs/architecture/CHAPEL-SATURATION-HOOKS.adoc delete mode 100644 docs/architecture/CHAPEL-SATURATION-HOOKS.md create mode 100644 docs/architecture/CORRECTNESS-ARCHITECTURE.adoc delete mode 100644 docs/architecture/CORRECTNESS-ARCHITECTURE.md create mode 100644 docs/architecture/CROSS-REPO-PROOF-DAG.adoc delete mode 100644 docs/architecture/CROSS-REPO-PROOF-DAG.md create mode 100644 docs/architecture/JULIA-SATURATION-HOOKS.adoc delete mode 100644 docs/architecture/JULIA-SATURATION-HOOKS.md create mode 100644 docs/architecture/TYPE-DISCIPLINE-EMBEDDING.adoc delete mode 100644 docs/architecture/TYPE-DISCIPLINE-EMBEDDING.md create mode 100644 docs/architecture/VERISIM-ER-SCHEMA.adoc delete mode 100644 docs/architecture/VERISIM-ER-SCHEMA.md create mode 100644 docs/bench/2026-05-30-chapel-mrr-baseline.adoc delete mode 100644 docs/bench/2026-05-30-chapel-mrr-baseline.md create mode 100644 docs/decisions/2026-04-28-corpus-and-design-search.adoc delete mode 100644 docs/decisions/2026-04-28-corpus-and-design-search.md create mode 100644 docs/decisions/2026-05-19-ci-baseline-triage.adoc delete mode 100644 docs/decisions/2026-05-19-ci-baseline-triage.md create mode 100644 docs/decisions/2026-05-30-chapel-l23-cancel-token.adoc delete mode 100644 docs/decisions/2026-05-30-chapel-l23-cancel-token.md create mode 100644 docs/decisions/2026-05-30-chapel-pic-rebuild.adoc delete mode 100644 docs/decisions/2026-05-30-chapel-pic-rebuild.md create mode 100644 docs/decisions/2026-05-30-chapel-rehabilitation.adoc delete mode 100644 docs/decisions/2026-05-30-chapel-rehabilitation.md create mode 100644 docs/decisions/2026-05-31-chapel-prover-spawn-hooks.adoc delete mode 100644 docs/decisions/2026-05-31-chapel-prover-spawn-hooks.md create mode 100644 docs/decisions/2026-06-01-saturation-campaign.adoc delete mode 100644 docs/decisions/2026-06-01-saturation-campaign.md create mode 100644 docs/deployment/DEPLOYMENT_GUIDE.adoc delete mode 100644 docs/deployment/DEPLOYMENT_GUIDE.md create mode 100644 docs/design/ADVANCED_TYPING_GAP_ANALYSIS.adoc delete mode 100644 docs/design/ADVANCED_TYPING_GAP_ANALYSIS.md create mode 100644 docs/design/OTHER_SYSTEMS_USP_PPA.adoc delete mode 100644 docs/design/OTHER_SYSTEMS_USP_PPA.md create mode 100644 docs/design/SPARK_ADOPTION_PLAN.adoc delete mode 100644 docs/design/SPARK_ADOPTION_PLAN.md create mode 100644 docs/design/TYPING_CAPABILITIES_COMPARISON.adoc delete mode 100644 docs/design/TYPING_CAPABILITIES_COMPARISON.md rename docs/governance/{JUST_AND_MUST_FRAMEWORK.md => JUST_AND_MUST_FRAMEWORK.adoc} (78%) rename docs/governance/{TRUST_AND_VALIDATION_FRAMEWORK.md => TRUST_AND_VALIDATION_FRAMEWORK.adoc} (74%) rename docs/governance/{TRUST_IMPLEMENTATION_GUIDE.md => TRUST_IMPLEMENTATION_GUIDE.adoc} (68%) create mode 100644 docs/handover/B7-AUDIT-CORRECTION.adoc delete mode 100644 docs/handover/B7-AUDIT-CORRECTION.md create mode 100644 docs/handover/HANDOVER-INDEX.adoc delete mode 100644 docs/handover/HANDOVER-INDEX.md create mode 100644 docs/handover/L1-CAPNPROTO-PROMPT.adoc delete mode 100644 docs/handover/L1-CAPNPROTO-PROMPT.md create mode 100644 docs/handover/L2-CHAPEL-PROMPT.adoc delete mode 100644 docs/handover/L2-CHAPEL-PROMPT.md create mode 100644 docs/handover/L3-LIVE-PROVER-CI-PROMPT.adoc delete mode 100644 docs/handover/L3-LIVE-PROVER-CI-PROMPT.md create mode 100644 docs/handover/PHASE-3-PROMPT.adoc delete mode 100644 docs/handover/PHASE-3-PROMPT.md create mode 100644 docs/handover/PRODUCTION-WIRING-PLAN.adoc delete mode 100644 docs/handover/PRODUCTION-WIRING-PLAN.md create mode 100644 docs/handover/PROVER-CORPUS-SATURATION-LANE.adoc delete mode 100644 docs/handover/PROVER-CORPUS-SATURATION-LANE.md create mode 100644 docs/handover/README.adoc delete mode 100644 docs/handover/README.md rename docs/handover/{S4-LOOP-CLOSURE-RUNBOOK.md => S4-LOOP-CLOSURE-RUNBOOK.adoc} (53%) create mode 100644 docs/handover/S5-VERIFICATION-RUNBOOK.adoc delete mode 100644 docs/handover/S5-VERIFICATION-RUNBOOK.md create mode 100644 docs/handover/SESSION-HANDOFF-2026-06-15.adoc delete mode 100644 docs/handover/SESSION-HANDOFF-2026-06-15.md create mode 100644 docs/handover/STATE.adoc delete mode 100644 docs/handover/STATE.md create mode 100644 docs/handover/SUGGEST-CLI-PROMPT.adoc delete mode 100644 docs/handover/SUGGEST-CLI-PROMPT.md create mode 100644 docs/handover/THEOREM-METADATA-MIGRATION.adoc delete mode 100644 docs/handover/THEOREM-METADATA-MIGRATION.md create mode 100644 docs/handover/TODO.adoc delete mode 100644 docs/handover/TODO.md create mode 100644 docs/handover/llm-warmup-dev.adoc delete mode 100644 docs/handover/llm-warmup-dev.md create mode 100644 docs/handover/llm-warmup-user.adoc delete mode 100644 docs/handover/llm-warmup-user.md create mode 100644 docs/implementation/AGDA_IMPLEMENTATION_SUMMARY.adoc delete mode 100644 docs/implementation/AGDA_IMPLEMENTATION_SUMMARY.md create mode 100644 docs/implementation/CVC5_IMPLEMENTATION_SUMMARY.adoc delete mode 100644 docs/implementation/CVC5_IMPLEMENTATION_SUMMARY.md create mode 100644 docs/implementation/HOL_LIGHT_IMPLEMENTATION.adoc delete mode 100644 docs/implementation/HOL_LIGHT_IMPLEMENTATION.md create mode 100644 docs/implementation/MIZAR_IMPLEMENTATION_SUMMARY.adoc delete mode 100644 docs/implementation/MIZAR_IMPLEMENTATION_SUMMARY.md create mode 100644 docs/implementation/Z3_IMPLEMENTATION_SUMMARY.adoc delete mode 100644 docs/implementation/Z3_IMPLEMENTATION_SUMMARY.md rename docs/{isabelle-backend.md => isabelle-backend.adoc} (55%) create mode 100644 docs/releases/RELEASE_NOTES_v1.2.adoc delete mode 100644 docs/releases/RELEASE_NOTES_v1.2.md create mode 100644 docs/releases/RELEASE_NOTES_v1.3.adoc delete mode 100644 docs/releases/RELEASE_NOTES_v1.3.md create mode 100644 docs/reports/2026-06-06-hypatia-alert-classification.adoc delete mode 100644 docs/reports/2026-06-06-hypatia-alert-classification.md create mode 100644 docs/reports/audit/pillar-audit-2026-04-15.adoc delete mode 100644 docs/reports/audit/pillar-audit-2026-04-15.md create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 docs/training-runs/2026-06-02.adoc delete mode 100644 docs/training-runs/2026-06-02.md create mode 100644 echidna-playground/CODE_OF_CONDUCT.adoc delete mode 100644 echidna-playground/CODE_OF_CONDUCT.md create mode 100644 echidna-playground/SECURITY.adoc delete mode 100644 echidna-playground/SECURITY.md create mode 100644 echidna-playground/melange-example/README.adoc delete mode 100644 echidna-playground/melange-example/README.md create mode 100644 examples/README.adoc delete mode 100644 examples/README.md create mode 100644 hooks/README.adoc delete mode 100644 hooks/README.md create mode 100644 metrics/README.adoc delete mode 100644 metrics/README.md create mode 100644 proofs/acl2/README.adoc delete mode 100644 proofs/acl2/README.md create mode 100644 proofs/hol4/README.adoc delete mode 100644 proofs/hol4/README.md create mode 100644 proofs/lean/README.adoc delete mode 100644 proofs/lean/README.md create mode 100644 proofs/lean/THEOREMS.adoc delete mode 100644 proofs/lean/THEOREMS.md create mode 100644 proofs/pvs/README.adoc delete mode 100644 proofs/pvs/README.md create mode 100644 reports/panic-attack-chunks/SUMMARY.adoc delete mode 100644 reports/panic-attack-chunks/SUMMARY.md create mode 100644 schemas/VERSIONING.adoc delete mode 100644 schemas/VERSIONING.md create mode 100644 site/docs/api/core.adoc delete mode 100644 site/docs/api/core.md rename site/docs/api/{graphql.md => graphql.adoc} (54%) rename site/docs/api/{grpc.md => grpc.adoc} (66%) create mode 100644 site/docs/api/rest.adoc delete mode 100644 site/docs/api/rest.md create mode 100644 site/docs/index.adoc delete mode 100644 site/docs/index.md create mode 100644 site/index.adoc delete mode 100644 site/index.md create mode 100644 src/chapel/README.adoc delete mode 100644 src/chapel/README.md create mode 100644 src/chapel/RESULTS.adoc delete mode 100644 src/chapel/RESULTS.md create mode 100644 src/interfaces/README.adoc delete mode 100644 src/interfaces/README.md create mode 100644 src/julia/README.adoc delete mode 100644 src/julia/README.md create mode 100644 tests/README.adoc delete mode 100644 tests/README.md create mode 100644 tools/invariant-path/README.adoc delete mode 100644 tools/invariant-path/README.md create mode 100644 training_data/floor_progress.adoc delete mode 100644 training_data/floor_progress.md diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 00000000..318e1076 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,18 @@ +== Architecture + +The architecture documentation for ECHIDNA lives in +link:docs/ARCHITECTURE.md[`+docs/ARCHITECTURE.md+`] — the polyglot +layout, the dispatch path, the trust-hardening pipeline, and how the +Rust core, Julia ML sidecar, Idris2 ABI, Zig FFI and optional Chapel +parallel layer fit together. + +Related canonical documents: + +* link:docs/PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`] — backend tier +table and what each published count actually counts +* link:docs/ROADMAP.md[`+docs/ROADMAP.md+`] — stage map and current +direction +* link:docs/DEBT.md[`+docs/DEBT.md+`] — known licence, documentation and +code debt +* link:.machine_readable/descriptiles/META.a2ml[`+.machine_readable/descriptiles/META.a2ml+`] +— the machine-readable architecture record diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 9e3ecd19..00000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,26 +0,0 @@ - - -# Architecture - -The architecture documentation for ECHIDNA lives in -[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — the polyglot layout, the -dispatch path, the trust-hardening pipeline, and how the Rust core, Julia ML -sidecar, Idris2 ABI, Zig FFI and optional Chapel parallel layer fit together. - -Related canonical documents: - -- [`docs/PROVER_COUNT.md`](docs/PROVER_COUNT.md) — backend tier table and what - each published count actually counts -- [`docs/ROADMAP.md`](docs/ROADMAP.md) — stage map and current direction -- [`docs/DEBT.md`](docs/DEBT.md) — known licence, documentation and code debt -- [`.machine_readable/descriptiles/META.a2ml`](.machine_readable/descriptiles/META.a2ml) - — the machine-readable architecture record diff --git a/AUTHORS.adoc b/AUTHORS.adoc new file mode 100644 index 00000000..018dfe18 --- /dev/null +++ b/AUTHORS.adoc @@ -0,0 +1,83 @@ +== Authors and Contributors + +This file lists the authors and contributors to the ECHIDNA project. The +authoritative running list lives in the git history — +`+git shortlog -sne+` will produce a deduplicated, frequency-sorted view +at any commit. + +=== Maintainers + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Name |Role |Contact +|Jonathan D.A. Jewell |Lead Maintainer +|https://github.com/hyperpolymath[@hyperpolymath], +`+j.d.a.jewell@open.ac.uk+` +|=== + +See link:MAINTAINERS.adoc[`+MAINTAINERS.adoc+`] for the maintainer +responsibility model and the path to becoming a maintainer. + +=== Contributors + +Code, documentation, infrastructure, review, issue triage. The +deduplicated running list is in the git history: + +[source,bash] +---- +git shortlog -sne +---- + +We recognise all forms of contribution including but not limited to: + +* Code contributions +* Documentation improvements +* Bug reports and testing +* Feature suggestions +* Community support +* Translations +* Design and artwork +* Infrastructure and tooling + +=== Special Thanks + +* *The theorem-proving community* — for the foundations and the ongoing +maintenance of the backends ECHIDNA integrates with (Coq/Rocq, Lean, +Agda, Isabelle, Idris2, F*, HOL Light, Mizar, PVS, ACL2, HOL4, Z3, CVC5, +Vampire, E Prover, and the long tail in +link:docs/PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`]). +* *The Rhodium Standard Repository (RSR/CCCP)* — for the compliance +template that this repo extends; see +link:RSR_COMPLIANCE.adoc[`+RSR_COMPLIANCE.adoc+`]. + +=== How to be added + +If you’ve contributed to ECHIDNA and would like to be acknowledged +beyond the git history, open an issue or PR on +https://github.com/hyperpolymath/echidna/issues[GitHub] with the +attribution you would like. + +=== License of contributions + +Source files are licensed per the SPDX header at the top of each file; +the project root link:LICENSE[`+LICENSE+`] and the per-tree +link:.reuse/dep5[`+.reuse/dep5+`] catalogue together describe the +authoritative position. By contributing you agree to license your +contribution under the licence noted on the file you touch (or the +project default for new files). + +The documentation surface is intentionally `+MPL-2.0+` — see +https://github.com/hyperpolymath/echidna/issues?q=license[`+feedback_echidna_license_docs_mpl_intentional+`] +for the deliberation. + +=== Contact + +* *GitHub Issues*: https://github.com/hyperpolymath/echidna/issues +* *Security*: see link:SECURITY.md[`+SECURITY.md+`] — use GitHub +Security Advisories for vulnerabilities, not public issues. + +''''' + +_This file is intentionally count-free and date-free in prose. The git +history is the running timeline; the canonical attribution surface is +`+git shortlog -sne+`._ diff --git a/AUTHORS.md b/AUTHORS.md deleted file mode 100644 index 6388b8ab..00000000 --- a/AUTHORS.md +++ /dev/null @@ -1,83 +0,0 @@ - - -# Authors and Contributors - -This file lists the authors and contributors to the ECHIDNA project. -The authoritative running list lives in the git history — `git shortlog --sne` will produce a deduplicated, frequency-sorted view at any commit. - -## Maintainers - -| Name | Role | Contact | -|---|---|---| -| Jonathan D.A. Jewell | Lead Maintainer | [@hyperpolymath](https://github.com/hyperpolymath), `j.d.a.jewell@open.ac.uk` | - -See [`MAINTAINERS.adoc`](MAINTAINERS.adoc) for the maintainer -responsibility model and the path to becoming a maintainer. - -## Contributors - -Code, documentation, infrastructure, review, issue triage. The -deduplicated running list is in the git history: - -```bash -git shortlog -sne -``` - -We recognise all forms of contribution including but not limited to: - -- Code contributions -- Documentation improvements -- Bug reports and testing -- Feature suggestions -- Community support -- Translations -- Design and artwork -- Infrastructure and tooling - -## Special Thanks - -- **The theorem-proving community** — for the foundations and the - ongoing maintenance of the backends ECHIDNA integrates with - (Coq/Rocq, Lean, Agda, Isabelle, Idris2, F*, HOL Light, Mizar, - PVS, ACL2, HOL4, Z3, CVC5, Vampire, E Prover, and the long tail - in [`docs/PROVER_COUNT.md`](docs/PROVER_COUNT.md)). -- **The Rhodium Standard Repository (RSR/CCCP)** — for the - compliance template that this repo extends; see - [`RSR_COMPLIANCE.adoc`](RSR_COMPLIANCE.adoc). - -## How to be added - -If you've contributed to ECHIDNA and would like to be acknowledged -beyond the git history, open an issue or PR on -[GitHub](https://github.com/hyperpolymath/echidna/issues) with the -attribution you would like. - -## License of contributions - -Source files are licensed per the SPDX header at the top of each -file; the project root [`LICENSE`](LICENSE) and the per-tree -[`.reuse/dep5`](.reuse/dep5) catalogue together describe the -authoritative position. By contributing you agree to license your -contribution under the licence noted on the file you touch (or the -project default for new files). - -The documentation surface is intentionally `MPL-2.0` — see -[`feedback_echidna_license_docs_mpl_intentional`](https://github.com/hyperpolymath/echidna/issues?q=license) -for the deliberation. - -## Contact - -- **GitHub Issues**: -- **Security**: see [`SECURITY.md`](SECURITY.md) — use GitHub - Security Advisories for vulnerabilities, not public issues. - ---- - -*This file is intentionally count-free and date-free in prose. The -git history is the running timeline; the canonical attribution -surface is `git shortlog -sne`.* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 00000000..ed2dc906 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,383 @@ +== Changelog + +All notable changes to ECHIDNA will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Fixed + +* ci(chapel): pin runs-on to ubuntu-22.04 for Chapel 2.8.0 +libclang-cpp.so.14 ABI compatibility (#183). Chapel 2.8.0’s debian +package is built against LLVM-14 / Ubuntu 22.04; on Ubuntu 24.04 +(`+ubuntu-latest+`) apt resolves the unmet dependency with +libclang-cpp-18, leaving `+chpl+` unable to load. Also switched install +to `+apt-get install -y /tmp/chapel.deb+` so libclang-cpp14 / libllvm14 +are resolved declaratively in one pass. + +==== Added — Saturation campaign 2026-06-01 + +Branch `+prover-corpus-saturation+` (commits f73ee00..cb8caff). +Owner-directed marginal-benefit push across corpus, vocabulary, +arbitration, exchange, and wire-schema surfaces. See +`+docs/decisions/2026-06-01-saturation-campaign.md+`. + +* *13 new corpus adapters* under `+src/rust/corpus/+` (`+isabelle+`, +`+metamath+`, `+mizar+`, `+hol_light+`, `+hol4+`, `+dafny+`, `+why3+`, +`+fstar+`, `+acl2_books+`, `+tptp+`, `+smtlib+`, `+proofnet+`, +`+minif2f+`). Total corpus adapter coverage: 4 → *17* (4.25×). See +`+docs/CORPUS-ADAPTERS.md+`. +* *9 new per-prover synonym TOMLs* (`+isabelle_afp+`, `+metamath+`, +`+mizar+`, `+hol_light+`, `+hol4+`, `+dafny+`, `+why3+`, `+fstar+`, +`+acl2+`). Total: 5 → *14* per-prover tables. +* *3 cross-prover taxonomic dictionaries* (underscore-prefix): +`+_msc2020.toml+` (87 codes), `+_wordnet_math.toml+` (~80 lemmas), +`+_conceptnet_seed.toml+` (~55 edges, offline-resilient). +* *3 new arbitration mechanisms* under `+src/rust/verification/+`: +`+bayesian_arbiter+` (log-odds posterior), `+dempster_shafer+` +(HighConflict trip at k > 0.95), `+pareto_arbiter+` (4-axis Pareto +frontier). +* *4 new exchange bridges* under `+src/rust/exchange/+`: `+tptp+`, +`+smtlib+`, `+smtcoq+` (stub bridge), `+lambdapi+`. +* *Formal VeriSim E-R schema* at +`+docs/architecture/VERISIM-ER-SCHEMA.md+` (12 entities + 7 +relationships, crosswalk Rust↔Cap’n Proto↔ClickHouse) + Cap’n Proto wire +schema `+crates/echidna-wire/schemas/verisim_er.capnp+` +(@0xe4dc7b1f01a06001). +* *Chapel + Julia integration hooks* at +`+docs/architecture/CHAPEL-SATURATION-HOOKS.md+` + +`+docs/architecture/JULIA-SATURATION-HOOKS.md+` (specifications only — +wave3 chapel + GNN-training-trigger files deliberately untouched). +* *New Julia helper modules* `+src/julia/corpus_loader.jl+` + +`+src/julia/saturation_synonyms.jl+` (bridge Rust corpus JSON + +saturation synonym TOMLs into the GNN training pipeline). +* *Saturation campaign ADR* at +`+docs/decisions/2026-06-01-saturation-campaign.md+`. +* *Handover lane doc* at +`+docs/handover/PROVER-CORPUS-SATURATION-LANE.md+` (collision-avoidance +contract with `+wave3/161-162-bench-telemetry-corpus+`). +* *Corpus adapter index* at `+docs/CORPUS-ADAPTERS.md+`. +* *Justfile recipes*: `+corpus-ingest-saturation+`, +`+corpus-stats-all+`, `+synonym-load-test+`, `+test-saturation+`, +`+arbiter-smoke+`, `+er-schema-drift-check+`. +* *139 new unit tests* across the saturation modules (1 ignored +heuristic-limit). + +==== Changed + +* `+src/rust/suggest/synonyms.rs+`: `+load_all+` extended to 14 provers; +new `+CrossProverDicts+` + `+load_cross_prover_dicts()+` + +`+SynonymTable::merge_external()+`. +* `+src/rust/corpus/mod.rs+`, `+verification/mod.rs+`, +`+exchange/mod.rs+`: register new modules (additive). +* Module-level doc comments on `+corpus/mod.rs+`, +`+verification/mod.rs+`, `+verisim_bridge.rs+` cite the new schemas + +arbiters. + +==== Documentation + +* Wiki updated (Home, Architecture, Getting-Started, Guides, FAQ, +Troubleshooting) to reflect the new surface. +* README.adoc + EXPLAINME.adoc updated with new headline counts + +per-module references. +* Machine-readable metadata under `+.machine_readable/6a2/+` (STATE / +META / ECOSYSTEM / NEUROSYM) updated additively. +* 9 RSR-template substitution gaps closed in CODE_OF_CONDUCT.md / +SECURITY.md / AUTHORS.md. + +==== Verification + +* `+cargo check --lib+` clean (~24s). +* `+cargo test --lib -- corpus:: verification::{bayesian,dempster_shafer,pareto}_arbiter exchange::{tptp,smtlib,smtcoq,lambdapi}+`: +*139 passed, 0 failed, 1 ignored* +(corpus::dafny::tests::detects_datatype_and_extern — heuristic +body-less-extern-method limitation). +* Zero collisions with `+wave3/161-162-bench-telemetry-corpus+`. + +''''' + +=== [2.3.0] - 2026-06-01 + +==== Added + +* *105 ProverKind variants* (exhaustive HP type-checker ecosystem). +* Updated `+ProverKindInjectivity.idr+` to prove injectivity for all 105 +variants. +* Expanded Isabelle synthetic proof corpus (105 entries). +* Resolved security alerts: Binary-Artifacts (#13), rand (#11, #10), +rustls-webpki (#13, #12). +* Atomic repush consolidating corpus expansion and security hardening. + +=== [2.2.0] - 2026-04-05 + +==== Changed + +* *VQL → VCL + verisimdb → verisim rename* (ecosystem-wide, 2026-04-05). +Internal code, docs, module names, and machine-readable manifests adopt +the new ecosystem terminology. `+verisim_bridge.rs+` (was +`+verisimdb_bridge.rs+`), `+vcl_ut.rs+` and `+vcl_ut.zig+` (were +`+vql_ut.*+`), `+verisim.a2ml+` integration manifest (was +`+verisimdb.a2ml+`). GitHub URL `+hyperpolymath/verisimdb+` preserved. + +==== Added + +* *F* corpus* (`+proofs/fstar/+`): 5 arithmetic lemmas (AddComm, +AddAssoc, MulZero, NonNeg, Refl) discharged by F*’s SMT backend. +* *TPTP corpus* (`+proofs/tptp/+`): 8 first-order problems for Vampire + +E Prover, with known SZS statuses. +* *DIMACS corpus* (`+proofs/dimacs/+`): 5 SAT/UNSAT problems for CaDiCaL ++ Kissat. +* *Metamath seeds* (`+proofs/metamath/tiny.mm+`, `+broken.mm+`): +smallest valid + deliberate-fail for the `+run_metamath+` runner. +* *Agda witness* (`+proofs/agda/IdentityLaws.agda+`): known-good +natural-number identity proofs against agda-stdlib v2.3. +* *BasicTotality.idr*: small totality proofs that pass +`+idris2 --check+` with no external dependencies. + +==== Fixed + +* *Three broken Idris2 proofs repaired* (5/5 now type-check): +** `+AxiomCompleteness.idr+`: 23× `+prf = impossible+` (invalid RHS) +rewritten to `+Refl impossible+`. +** `+DispatchOrdering.idr+`: rewritten as a minimal working proof +(6-stage dispatch pipeline with LT witnesses for adjacent stages). +Original had invalid constructor signatures with named args in +return-type position. +** `+ProverKindInjectivity.idr+`: replaced 48× +`+lteSuccRight $ ... $ LTERefl+` chains (unification failed) with +direct `+LTESucc (...)+` constructor nesting. Type signature switched +from `+maxDiscriminant+` alias to literal `+48+` so Idris2 can unfold +`+S ?right+`. Added `+import Data.Nat+`. +* *Agda scoping bugs* in `+Basic.agda+`, `+List.agda+`, `+Nat.agda+`, +`+Propositional.agda+`: files defined datatypes inside `+where+` +clauses, putting them out of scope for outer signatures. All four +rewritten as clean agda-stdlib-backed proofs (5/6 `+.agda+` files now +compile). +* *TPTP precedence* in `+proofs/tptp/transitivity.p+`: added explicit +parens around `+(lt(X,Y) & lt(Y,Z))+` before `+=>+` so E Prover parses +it. Now Theorem-certified by both Vampire and E Prover. +* *`+/api/verify+` false-positive guard*: server-level check in +`+prove_handler+` and `+verify_handler+` now returns `+valid: false+` +when `+parse_string+` produces an empty `+ProofState+` (no goals, +theorems, definitions, axioms, or variables) on non-empty input. Partial +fix for the parse+export round-trip bug documented in `+TEST-NEEDS.md+`. +Verified live: garbage to Coq/Lean now returns `+valid: false+` (was +`+true+`); real proofs unaffected. +* *Isabelle prover backend de-stubbed* +(`+src/rust/provers/isabelle.rs+`). `+parse_string+` previously +discarded its `+content+` argument and always emitted a single +`+Term::Const("True")+` goal, which `+verify_proof+` then +short-circuited to `+Ok(true)+` — Isabelle was never actually invoked. +It now extracts the theory name and top-level +`+theorem|lemma|corollary+` declarations with nested-comment-aware +scanning, stashes the raw `+.thy+` content in +`+ProofState.metadata["raw_thy_content"]+`, and `+verify_proof+` writes +that content to a unique per-invocation temp directory under the correct +filename (Isabelle requires `+.thy+`) before invoking +`+isabelle process -l Main -e 'use_thys [""]'+`. +* *Stale scaffolded temp-file path* in Isabelle’s fallback verification +path: previously wrote `+echidna_verify.thy+` containing +`+theory GeneratedProof+`, causing filename/theory-name mismatch +rejection by `+isabelle build+`. Now writes `+GeneratedProof.thy+` in a +unique temp dir. + +==== Added + +* `+strip_isabelle_comments+` helper for the Isabelle backend (handles +nested `+(* ... *)+` blocks). +* 9 new unit tests for the Isabelle theory-header parsers +(`+test_strip_*+`, `+test_extract_theory_name_*+`, +`+test_extract_lemma_names_*+`) and the `+parse_string+` contract +(metadata populated, goals non-trivial, context theorems enumerated, +empty-theory fallback goal). +* Parser verified against a real 788-line `+Tropical.thy+` (tropical +semiring formalisation): extracts theory name and all 55 +theorems/lemmas. + +==== Notes + +* Deployment of this fix to `+echidna-nesy+` on Fly.io requires +rebuilding the container with the `+isabelle+` binary on `+$PATH+`. +Without it, `+verify_proof+` returns `+Ok(false)+` with a +`+"Failed to run Isabelle process"+` context error. +* Audit of all 50 prover backends confirmed Isabelle was the only truly +stubbed one. `+metamath.rs+` and `+typed_wasm.rs+` are intentionally +pure-Rust in-process verifiers (no subprocess needed by design). The +remaining 47 external-solver backends all spawn real solver subprocesses +via `+Command::new+`. + +''''' + +=== https://github.com/hyperpolymath/echidna/compare/v1.6.0...v1.6.1[1.6.1] - 2026-03-23 + +==== Fixed + +* Fixed `+tamarin.rs+` Definition type (added missing struct fields) +* Fixed non-exhaustive match arms in `+main.rs+` +* Removed unused imports across codebase +* Fixed `+rustfmt.toml+` for stable Rust (removed unstable options) +* Fixed `+resolvers.rs+` syntax error +* Applied `+cargo fmt+` across entire codebase + +==== Changed + +* 389 tests passing (up from 306+) +* Project now compiles cleanly on stable Rust toolchain + +''''' + +=== https://github.com/hyperpolymath/echidna/compare/v1.5.0...v1.6.0[1.6.0] - 2026-03-08 + +==== Major Features + +===== Zig FFI Layer (4 Shared Libraries) + +* `+libechidna_ffi.so+` — Core prover management (init, shutdown, +status, verify) +* `+libechidna_overlay.so+` — Overlay networks (Tor, IPFS, Ethereum) +* `+libechidna_boj.so+` — BoJ cartridge protocol +* `+libechidna_typell.so+` — TypeLL type-level operations +* All functions use dual `+pub export fn+` for both Zig `+@import+` and +C linker access +* Bidirectional callbacks: init/prover-change/error/verify-complete +(core), status/error/progress/circuit/pin (overlay) + +===== Idris2 ABI Formal Proofs (7 Modules, Zero `+believe_me+`) + +* `+EchidnaABI.Types+` — 30 ProverKind, FfiStatus, TrustLevel, Handle +with So non-null proof +* `+EchidnaABI.Layout+` — DivisibleBy proof witnesses for 6 struct +memory layouts (FfiStringSlice, FfiOwnedString, FfiSerializedTerm, +FfiProverConfig, FfiTactic, FfiTacticResult) +* `+EchidnaABI.Foreign+` — Core FFI function declarations +* `+Overlay+`, `+Overlay.Foreign+` — Overlay network types and FFI +* `+Boj.Foreign+`, `+TypeLL.Foreign+` — BoJ and TypeLL FFI declarations +* All 7 modules type-check with idris2 v0.8.0 + +===== Generated C Headers + +* `+echidna_ffi.h+` — 23 functions, 5 enums, 2 structs, 4 callback types +* `+echidna_overlay.h+`, `+echidna_boj.h+`, `+echidna_typell.h+` + +===== zig REST Adapters + +* Core adapter (ports 8100-8102: REST, gRPC, GraphQL) +* Overlay adapter (port 8103) +* BoJ adapter (port 7700) +* TypeLL adapter (port 7800) +* Tentacles adapter (port 8300) + +===== Tentacles FFI/ABI Layer (7-Tentacles Agent System) + +* `+TentaclesForeign.idr+` — Idris2 ABI definitions for 7-Tentacles +agents with dependent type proofs +* `+tentacles.zig+` → `+libechidna_tentacles.so+` — Zig FFI with 7 agent +management, OODA loop dispatch, and event callbacks +* `+echidna_tentacles.h+` — Generated C header for tentacles agent +interface +* `+tentacles.v+` — zig REST adapter on port 8300 exposing agent +management and OODA endpoints + +==== Added + +* 30+ native Zig tests (`+test-core-native+`, `+test-overlay-native+`) +* VerifiedLayout record bundling fields + totalSize + structAlign + +erased proof +* Round-trip enum proofs (OverlayKind, CidVersion, etc.) +* Platform pointer size proofs (ptrSize64, ptrSizeWASM) +* ABI-FFI-README.md with ECHIDNA-specific architecture documentation + +==== Fixed + +* Idris2 Types.idr: Replaced `+DecEq ProverKind+` (30-constructor +catch-all) with `+Eq+` via ordinal comparison +* Idris2 Types.idr: Rewrote Handle to use `+choose (not (ptr == 0))+` +pattern +* Idris2 Layout.idr: Complete rewrite — `+So+`-based proofs replaced +with `+DivisibleBy+` witnesses (Idris2 v0.8 limitation: So proofs don’t +reduce through named definitions) +* Idris2 Overlay.idr: Trailing `+|||+` doc comment changed to `+--+` +comments + +''''' + +=== https://github.com/hyperpolymath/echidna/compare/v1.0.0...v1.5.0[1.5.0] - 2026-02-12 + +==== Major Features + +===== Trust & Safety Pipeline + +Complete implementation of 13-component trust-hardening system: - ✅ +Solver binary integrity (SHAKE3-512 + BLAKE3 checksums) - ✅ SMT +portfolio solving with cross-checking - ✅ Proof certificate validation +(Alethe, DRAT/LRAT, TSTP) - ✅ Axiom usage tracking (4 danger levels: +Safe, Noted, Warning, Reject) - ✅ Solver sandboxing (Podman, +bubblewrap, none) - ✅ 5-level trust hierarchy for confidence scoring - +✅ Mutation testing for specifications - ✅ Unified prover dispatch +pipeline - ✅ Cross-prover proof exchange (OpenTheory, Dedukti) - ✅ +Pareto frontier for multi-objective proof search - ✅ Statistical +confidence tracking with Bayesian timeout estimation + +===== Gitbot-Fleet Integration + +* ✅ Integrated with gitbot-fleet orchestration system +* ✅ Registered as Tier 1 Verifier bot +* ✅ 5 finding rule types (ECHIDNA-VERIFY-001 through 005) +* ✅ Shared context layer for cross-bot coordination +* ✅ Findings flow to Hypatia learning engine +* ✅ Full test coverage (4 integration tests) +* ✅ Documentation: echidnabot/FLEET-INTEGRATION.md + +==== Added + +*Prover Backends* (30 total): - All backends fully implemented with +substantial code - Tier 1: Agda, Coq/Rocq, Lean 4, Isabelle/HOL, Z3, +CVC5 - Tier 2: Metamath, HOL Light, Mizar - Tier 3: PVS, ACL2, HOL4, +Idris2, F*, Dafny, Why3, TLAPS, Twelf, Nuprl, Minlog, Imandra - ATPs: +Vampire, E Prover, SPASS, Alt-Ergo - Constraint Solvers: GLPK, SCIP, +MiniZinc, Chuffed, OR-Tools + +*API Interfaces*: - GraphQL API (async-graphql, port 8081) - gRPC API +(tonic, port 50051) - REST API (axum + OpenAPI, port 8000) + +*Documentation*: - PERFORMANCE.md - Prover creation benchmarks (avg +2.5µs) - SECURITY-SCAN-FINAL.md - Security audit results - +ROADMAP-v2.0.md - v2.0 feature roadmap - ECOSYSTEM-INTEGRATION.md - +Ecosystem service integration - echidnabot/FLEET-INTEGRATION.md - Fleet +integration guide + +*Configuration*: - .echidnabot.toml - Self-verification configuration + +==== Fixed + +*Security* (39% reduction in weak points): - Documented all 24 unsafe +blocks in src/rust/ffi/mod.rs (FFI interop) - Documented all 7 unsafe +blocks in src/rust/proof_search.rs (Chapel FFI) - Converted HTTP URLs to +HTTPS in echidna-owned code (32 fixes) - Verified bash variable quoting +(11 scripts checked) - Cleaned up TODO/FIXME technical debt markers (5 +files) - Final scan: 50 weak points (down from 82) + +==== Performance + +*Prover Creation Benchmarks*: - Fastest: MiniZinc (116ns) - Slowest: +Isabelle (15.5µs) - Average: ~2.5µs + +==== Testing + +* 306+ tests (all passing) +* Fleet integration: 4 tests +* Trust pipeline: Integration tests for all components + +=== https://github.com/hyperpolymath/echidna/releases/tag/v1.0.0[1.0.0] - 2025-12-01 + +==== Initial Release + +* 30 prover backend stubs +* Basic trust pipeline +* GraphQL/gRPC/REST APIs +* Julia ML scaffolding + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index efc80f77..00000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,320 +0,0 @@ - - -# Changelog - -All notable changes to ECHIDNA will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Fixed - -- ci(chapel): pin runs-on to ubuntu-22.04 for Chapel 2.8.0 libclang-cpp.so.14 ABI compatibility (#183). Chapel 2.8.0's debian package is built against LLVM-14 / Ubuntu 22.04; on Ubuntu 24.04 (`ubuntu-latest`) apt resolves the unmet dependency with libclang-cpp-18, leaving `chpl` unable to load. Also switched install to `apt-get install -y /tmp/chapel.deb` so libclang-cpp14 / libllvm14 are resolved declaratively in one pass. - -### Added — Saturation campaign 2026-06-01 - -Branch `prover-corpus-saturation` (commits f73ee00..cb8caff). Owner-directed marginal-benefit push across corpus, vocabulary, arbitration, exchange, and wire-schema surfaces. See `docs/decisions/2026-06-01-saturation-campaign.md`. - -- **13 new corpus adapters** under `src/rust/corpus/` (`isabelle`, `metamath`, `mizar`, `hol_light`, `hol4`, `dafny`, `why3`, `fstar`, `acl2_books`, `tptp`, `smtlib`, `proofnet`, `minif2f`). Total corpus adapter coverage: 4 → **17** (4.25×). See `docs/CORPUS-ADAPTERS.md`. -- **9 new per-prover synonym TOMLs** (`isabelle_afp`, `metamath`, `mizar`, `hol_light`, `hol4`, `dafny`, `why3`, `fstar`, `acl2`). Total: 5 → **14** per-prover tables. -- **3 cross-prover taxonomic dictionaries** (underscore-prefix): `_msc2020.toml` (87 codes), `_wordnet_math.toml` (~80 lemmas), `_conceptnet_seed.toml` (~55 edges, offline-resilient). -- **3 new arbitration mechanisms** under `src/rust/verification/`: `bayesian_arbiter` (log-odds posterior), `dempster_shafer` (HighConflict trip at k > 0.95), `pareto_arbiter` (4-axis Pareto frontier). -- **4 new exchange bridges** under `src/rust/exchange/`: `tptp`, `smtlib`, `smtcoq` (stub bridge), `lambdapi`. -- **Formal VeriSim E-R schema** at `docs/architecture/VERISIM-ER-SCHEMA.md` (12 entities + 7 relationships, crosswalk Rust↔Cap'n Proto↔ClickHouse) + Cap'n Proto wire schema `crates/echidna-wire/schemas/verisim_er.capnp` (@0xe4dc7b1f01a06001). -- **Chapel + Julia integration hooks** at `docs/architecture/CHAPEL-SATURATION-HOOKS.md` + `docs/architecture/JULIA-SATURATION-HOOKS.md` (specifications only — wave3 chapel + GNN-training-trigger files deliberately untouched). -- **New Julia helper modules** `src/julia/corpus_loader.jl` + `src/julia/saturation_synonyms.jl` (bridge Rust corpus JSON + saturation synonym TOMLs into the GNN training pipeline). -- **Saturation campaign ADR** at `docs/decisions/2026-06-01-saturation-campaign.md`. -- **Handover lane doc** at `docs/handover/PROVER-CORPUS-SATURATION-LANE.md` (collision-avoidance contract with `wave3/161-162-bench-telemetry-corpus`). -- **Corpus adapter index** at `docs/CORPUS-ADAPTERS.md`. -- **Justfile recipes**: `corpus-ingest-saturation`, `corpus-stats-all`, `synonym-load-test`, `test-saturation`, `arbiter-smoke`, `er-schema-drift-check`. -- **139 new unit tests** across the saturation modules (1 ignored heuristic-limit). - -### Changed - -- `src/rust/suggest/synonyms.rs`: `load_all` extended to 14 provers; new `CrossProverDicts` + `load_cross_prover_dicts()` + `SynonymTable::merge_external()`. -- `src/rust/corpus/mod.rs`, `verification/mod.rs`, `exchange/mod.rs`: register new modules (additive). -- Module-level doc comments on `corpus/mod.rs`, `verification/mod.rs`, `verisim_bridge.rs` cite the new schemas + arbiters. - -### Documentation - -- Wiki updated (Home, Architecture, Getting-Started, Guides, FAQ, Troubleshooting) to reflect the new surface. -- README.adoc + EXPLAINME.adoc updated with new headline counts + per-module references. -- Machine-readable metadata under `.machine_readable/6a2/` (STATE / META / ECOSYSTEM / NEUROSYM) updated additively. -- 9 RSR-template substitution gaps closed in CODE_OF_CONDUCT.md / SECURITY.md / AUTHORS.md. - -### Verification - -- `cargo check --lib` clean (~24s). -- `cargo test --lib -- corpus:: verification::{bayesian,dempster_shafer,pareto}_arbiter exchange::{tptp,smtlib,smtcoq,lambdapi}`: **139 passed, 0 failed, 1 ignored** (corpus::dafny::tests::detects_datatype_and_extern — heuristic body-less-extern-method limitation). -- Zero collisions with `wave3/161-162-bench-telemetry-corpus`. - ---- - -## [2.3.0] - 2026-06-01 - -### Added -- **105 ProverKind variants** (exhaustive HP type-checker ecosystem). -- Updated `ProverKindInjectivity.idr` to prove injectivity for all 105 variants. -- Expanded Isabelle synthetic proof corpus (105 entries). -- Resolved security alerts: Binary-Artifacts (#13), rand (#11, #10), rustls-webpki (#13, #12). -- Atomic repush consolidating corpus expansion and security hardening. - -## [2.2.0] - 2026-04-05 - -### Changed - -- **VQL → VCL + verisimdb → verisim rename** (ecosystem-wide, 2026-04-05). - Internal code, docs, module names, and machine-readable manifests - adopt the new ecosystem terminology. `verisim_bridge.rs` (was - `verisimdb_bridge.rs`), `vcl_ut.rs` and `vcl_ut.zig` (were `vql_ut.*`), - `verisim.a2ml` integration manifest (was `verisimdb.a2ml`). GitHub URL - `hyperpolymath/verisimdb` preserved. - -### Added - -- **F\* corpus** (`proofs/fstar/`): 5 arithmetic lemmas (AddComm, - AddAssoc, MulZero, NonNeg, Refl) discharged by F\*'s SMT backend. -- **TPTP corpus** (`proofs/tptp/`): 8 first-order problems for - Vampire + E Prover, with known SZS statuses. -- **DIMACS corpus** (`proofs/dimacs/`): 5 SAT/UNSAT problems for - CaDiCaL + Kissat. -- **Metamath seeds** (`proofs/metamath/tiny.mm`, `broken.mm`): - smallest valid + deliberate-fail for the `run_metamath` runner. -- **Agda witness** (`proofs/agda/IdentityLaws.agda`): known-good - natural-number identity proofs against agda-stdlib v2.3. -- **BasicTotality.idr**: small totality proofs that pass - `idris2 --check` with no external dependencies. - -### Fixed - -- **Three broken Idris2 proofs repaired** (5/5 now type-check): - - `AxiomCompleteness.idr`: 23× `prf = impossible` (invalid RHS) - rewritten to `Refl impossible`. - - `DispatchOrdering.idr`: rewritten as a minimal working proof - (6-stage dispatch pipeline with LT witnesses for adjacent stages). - Original had invalid constructor signatures with named args in - return-type position. - - `ProverKindInjectivity.idr`: replaced 48× `lteSuccRight $ ... $ - LTERefl` chains (unification failed) with direct `LTESucc (...)` - constructor nesting. Type signature switched from - `maxDiscriminant` alias to literal `48` so Idris2 can unfold - `S ?right`. Added `import Data.Nat`. -- **Agda scoping bugs** in `Basic.agda`, `List.agda`, `Nat.agda`, - `Propositional.agda`: files defined datatypes inside `where` - clauses, putting them out of scope for outer signatures. All four - rewritten as clean agda-stdlib-backed proofs (5/6 `.agda` files - now compile). -- **TPTP precedence** in `proofs/tptp/transitivity.p`: added explicit - parens around `(lt(X,Y) & lt(Y,Z))` before `=>` so E Prover parses - it. Now Theorem-certified by both Vampire and E Prover. -- **`/api/verify` false-positive guard**: server-level check in - `prove_handler` and `verify_handler` now returns `valid: false` - when `parse_string` produces an empty `ProofState` (no goals, - theorems, definitions, axioms, or variables) on non-empty input. - Partial fix for the parse+export round-trip bug documented in - `TEST-NEEDS.md`. Verified live: garbage to Coq/Lean now returns - `valid: false` (was `true`); real proofs unaffected. -- **Isabelle prover backend de-stubbed** (`src/rust/provers/isabelle.rs`). - `parse_string` previously discarded its `content` argument and always - emitted a single `Term::Const("True")` goal, which `verify_proof` then - short-circuited to `Ok(true)` — Isabelle was never actually invoked. - It now extracts the theory name and top-level `theorem|lemma|corollary` - declarations with nested-comment-aware scanning, stashes the raw `.thy` - content in `ProofState.metadata["raw_thy_content"]`, and `verify_proof` - writes that content to a unique per-invocation temp directory under the - correct filename (Isabelle requires `.thy`) before invoking - `isabelle process -l Main -e 'use_thys [""]'`. -- **Stale scaffolded temp-file path** in Isabelle's fallback verification - path: previously wrote `echidna_verify.thy` containing - `theory GeneratedProof`, causing filename/theory-name mismatch rejection - by `isabelle build`. Now writes `GeneratedProof.thy` in a unique temp dir. - -### Added - -- `strip_isabelle_comments` helper for the Isabelle backend (handles nested - `(* ... *)` blocks). -- 9 new unit tests for the Isabelle theory-header parsers (`test_strip_*`, - `test_extract_theory_name_*`, `test_extract_lemma_names_*`) and the - `parse_string` contract (metadata populated, goals non-trivial, context - theorems enumerated, empty-theory fallback goal). -- Parser verified against a real 788-line `Tropical.thy` (tropical semiring - formalisation): extracts theory name and all 55 theorems/lemmas. - -### Notes - -- Deployment of this fix to `echidna-nesy` on Fly.io requires rebuilding - the container with the `isabelle` binary on `$PATH`. Without it, - `verify_proof` returns `Ok(false)` with a `"Failed to run Isabelle - process"` context error. -- Audit of all 50 prover backends confirmed Isabelle was the only truly - stubbed one. `metamath.rs` and `typed_wasm.rs` are intentionally pure-Rust - in-process verifiers (no subprocess needed by design). The remaining 47 - external-solver backends all spawn real solver subprocesses via - `Command::new`. - ---- - -## [1.6.1] - 2026-03-23 - -### Fixed - -- Fixed `tamarin.rs` Definition type (added missing struct fields) -- Fixed non-exhaustive match arms in `main.rs` -- Removed unused imports across codebase -- Fixed `rustfmt.toml` for stable Rust (removed unstable options) -- Fixed `resolvers.rs` syntax error -- Applied `cargo fmt` across entire codebase - -### Changed - -- 389 tests passing (up from 306+) -- Project now compiles cleanly on stable Rust toolchain - ---- - -## [1.6.0] - 2026-03-08 - -### Major Features - -#### Zig FFI Layer (4 Shared Libraries) -- `libechidna_ffi.so` — Core prover management (init, shutdown, status, verify) -- `libechidna_overlay.so` — Overlay networks (Tor, IPFS, Ethereum) -- `libechidna_boj.so` — BoJ cartridge protocol -- `libechidna_typell.so` — TypeLL type-level operations -- All functions use dual `pub export fn` for both Zig `@import` and C linker access -- Bidirectional callbacks: init/prover-change/error/verify-complete (core), status/error/progress/circuit/pin (overlay) - -#### Idris2 ABI Formal Proofs (7 Modules, Zero `believe_me`) -- `EchidnaABI.Types` — 30 ProverKind, FfiStatus, TrustLevel, Handle with So non-null proof -- `EchidnaABI.Layout` — DivisibleBy proof witnesses for 6 struct memory layouts (FfiStringSlice, FfiOwnedString, FfiSerializedTerm, FfiProverConfig, FfiTactic, FfiTacticResult) -- `EchidnaABI.Foreign` — Core FFI function declarations -- `Overlay`, `Overlay.Foreign` — Overlay network types and FFI -- `Boj.Foreign`, `TypeLL.Foreign` — BoJ and TypeLL FFI declarations -- All 7 modules type-check with idris2 v0.8.0 - -#### Generated C Headers -- `echidna_ffi.h` — 23 functions, 5 enums, 2 structs, 4 callback types -- `echidna_overlay.h`, `echidna_boj.h`, `echidna_typell.h` - -#### zig REST Adapters -- Core adapter (ports 8100-8102: REST, gRPC, GraphQL) -- Overlay adapter (port 8103) -- BoJ adapter (port 7700) -- TypeLL adapter (port 7800) -- Tentacles adapter (port 8300) - -#### Tentacles FFI/ABI Layer (7-Tentacles Agent System) -- `TentaclesForeign.idr` — Idris2 ABI definitions for 7-Tentacles agents with dependent type proofs -- `tentacles.zig` → `libechidna_tentacles.so` — Zig FFI with 7 agent management, OODA loop dispatch, and event callbacks -- `echidna_tentacles.h` — Generated C header for tentacles agent interface -- `tentacles.v` — zig REST adapter on port 8300 exposing agent management and OODA endpoints - -### Added - -- 30+ native Zig tests (`test-core-native`, `test-overlay-native`) -- VerifiedLayout record bundling fields + totalSize + structAlign + erased proof -- Round-trip enum proofs (OverlayKind, CidVersion, etc.) -- Platform pointer size proofs (ptrSize64, ptrSizeWASM) -- ABI-FFI-README.md with ECHIDNA-specific architecture documentation - -### Fixed - -- Idris2 Types.idr: Replaced `DecEq ProverKind` (30-constructor catch-all) with `Eq` via ordinal comparison -- Idris2 Types.idr: Rewrote Handle to use `choose (not (ptr == 0))` pattern -- Idris2 Layout.idr: Complete rewrite — `So`-based proofs replaced with `DivisibleBy` witnesses (Idris2 v0.8 limitation: So proofs don't reduce through named definitions) -- Idris2 Overlay.idr: Trailing `|||` doc comment changed to `--` comments - ---- - -## [1.5.0] - 2026-02-12 - -### Major Features - -#### Trust & Safety Pipeline -Complete implementation of 13-component trust-hardening system: -- ✅ Solver binary integrity (SHAKE3-512 + BLAKE3 checksums) -- ✅ SMT portfolio solving with cross-checking -- ✅ Proof certificate validation (Alethe, DRAT/LRAT, TSTP) -- ✅ Axiom usage tracking (4 danger levels: Safe, Noted, Warning, Reject) -- ✅ Solver sandboxing (Podman, bubblewrap, none) -- ✅ 5-level trust hierarchy for confidence scoring -- ✅ Mutation testing for specifications -- ✅ Unified prover dispatch pipeline -- ✅ Cross-prover proof exchange (OpenTheory, Dedukti) -- ✅ Pareto frontier for multi-objective proof search -- ✅ Statistical confidence tracking with Bayesian timeout estimation - -#### Gitbot-Fleet Integration -- ✅ Integrated with gitbot-fleet orchestration system -- ✅ Registered as Tier 1 Verifier bot -- ✅ 5 finding rule types (ECHIDNA-VERIFY-001 through 005) -- ✅ Shared context layer for cross-bot coordination -- ✅ Findings flow to Hypatia learning engine -- ✅ Full test coverage (4 integration tests) -- ✅ Documentation: echidnabot/FLEET-INTEGRATION.md - -### Added - -**Prover Backends** (30 total): -- All backends fully implemented with substantial code -- Tier 1: Agda, Coq/Rocq, Lean 4, Isabelle/HOL, Z3, CVC5 -- Tier 2: Metamath, HOL Light, Mizar -- Tier 3: PVS, ACL2, HOL4, Idris2, F*, Dafny, Why3, TLAPS, Twelf, Nuprl, Minlog, Imandra -- ATPs: Vampire, E Prover, SPASS, Alt-Ergo -- Constraint Solvers: GLPK, SCIP, MiniZinc, Chuffed, OR-Tools - -**API Interfaces**: -- GraphQL API (async-graphql, port 8081) -- gRPC API (tonic, port 50051) -- REST API (axum + OpenAPI, port 8000) - -**Documentation**: -- PERFORMANCE.md - Prover creation benchmarks (avg 2.5µs) -- SECURITY-SCAN-FINAL.md - Security audit results -- ROADMAP-v2.0.md - v2.0 feature roadmap -- ECOSYSTEM-INTEGRATION.md - Ecosystem service integration -- echidnabot/FLEET-INTEGRATION.md - Fleet integration guide - -**Configuration**: -- .echidnabot.toml - Self-verification configuration - -### Fixed - -**Security** (39% reduction in weak points): -- Documented all 24 unsafe blocks in src/rust/ffi/mod.rs (FFI interop) -- Documented all 7 unsafe blocks in src/rust/proof_search.rs (Chapel FFI) -- Converted HTTP URLs to HTTPS in echidna-owned code (32 fixes) -- Verified bash variable quoting (11 scripts checked) -- Cleaned up TODO/FIXME technical debt markers (5 files) -- Final scan: 50 weak points (down from 82) - -### Performance - -**Prover Creation Benchmarks**: -- Fastest: MiniZinc (116ns) -- Slowest: Isabelle (15.5µs) -- Average: ~2.5µs - -### Testing - -- 306+ tests (all passing) -- Fleet integration: 4 tests -- Trust pipeline: Integration tests for all components - -## [1.0.0] - 2025-12-01 - -### Initial Release - -- 30 prover backend stubs -- Basic trust pipeline -- GraphQL/gRPC/REST APIs -- Julia ML scaffolding - ---- - -[1.6.1]: https://github.com/hyperpolymath/echidna/compare/v1.6.0...v1.6.1 -[1.6.0]: https://github.com/hyperpolymath/echidna/compare/v1.5.0...v1.6.0 -[1.5.0]: https://github.com/hyperpolymath/echidna/compare/v1.0.0...v1.5.0 -[1.0.0]: https://github.com/hyperpolymath/echidna/releases/tag/v1.0.0 diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 00000000..08b4365c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,170 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +the ECHIDNA project a harassment-free experience for everyone, +regardless of age, body size, visible or invisible disability, +ethnicity, sex characteristics, gender identity and expression, level of +experience, education, socio-economic status, nationality, personal +appearance, race, caste, color, religion, or sexual identity and +orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +==== Examples of behavior that contributes to a positive environment: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community +* Using welcoming and inclusive language +* Being patient with newcomers and helping them learn +* Acknowledging and respecting the time and effort of contributors + +==== Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Conduct which could reasonably be considered inappropriate in a +professional setting +* Dismissing or attacking inclusion-oriented requests +* Sustained disruption of community discussions or events +* Pattern of inappropriate social contact, such as requesting/assuming +unprofessional levels of intimacy + +=== Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Project maintainers have the right and responsibility to remove, edit, +or reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned with this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all project spaces, including: + +* GitHub repository (code, issues, pull requests, wiki) and any mirror +(e.g. GitLab CI mirror) +* Project communication channels (mailing lists, chat, forums) +* Official project events (conferences, meetups, workshops) +* Social media when representing the project + +It also applies when an individual is officially representing the +project in public spaces. + +=== Enforcement + +==== Reporting + +Instances of abusive, harassing, or otherwise unacceptable behaviour may +be reported through either of the following channels: + +* *GitHub Security Advisories* (preferred — private, encrypted, +auditable): +https://github.com/hyperpolymath/echidna/security/advisories/new Tag the +report as a conduct matter. +* *Email* (fallback): `+j.d.a.jewell@open.ac.uk+` — maintainer; PGP key +`+4A03639C1EB1F86C7F0C97A91835A14A2867091E+` published on +https://keys.openpgp.org. + +All complaints will be reviewed and investigated promptly and fairly. + +==== Privacy + +All project team members are obligated to respect the privacy and +security of the reporter of any incident. + +==== Enforcement Guidelines + +Project maintainers will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +===== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning from project maintainers, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +===== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +===== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the project community for a specified period of time. +No public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +===== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the project community. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org/[Contributor Covenant], version +2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +=== Questions + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. + +''''' + +*Lineage*: Adapted from the +https://www.contributor-covenant.org/[Contributor Covenant] v2.1. +Revisions tracked via `+git log CODE_OF_CONDUCT.md+`. This file is +intentionally version-free and date-free in prose to avoid R5b drift. + +*Contact*: +https://github.com/hyperpolymath/echidna/security/advisories/new +(preferred) or `+j.d.a.jewell@open.ac.uk+` (fallback). diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index b1194f09..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,121 +0,0 @@ - - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in the ECHIDNA project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -## Our Standards - -### Examples of behavior that contributes to a positive environment: - -- Demonstrating empathy and kindness toward other people -- Being respectful of differing opinions, viewpoints, and experiences -- Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -- Focusing on what is best not just for us as individuals, but for the overall community -- Using welcoming and inclusive language -- Being patient with newcomers and helping them learn -- Acknowledging and respecting the time and effort of contributors - -### Examples of unacceptable behavior: - -- The use of sexualized language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or email address, without their explicit permission -- Conduct which could reasonably be considered inappropriate in a professional setting -- Dismissing or attacking inclusion-oriented requests -- Sustained disruption of community discussions or events -- Pattern of inappropriate social contact, such as requesting/assuming unprofessional levels of intimacy - -## Enforcement Responsibilities - -Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. - -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## Scope - -This Code of Conduct applies within all project spaces, including: - -- GitHub repository (code, issues, pull requests, wiki) and any mirror (e.g. GitLab CI mirror) -- Project communication channels (mailing lists, chat, forums) -- Official project events (conferences, meetups, workshops) -- Social media when representing the project - -It also applies when an individual is officially representing the project in public spaces. - -## Enforcement - -### Reporting - -Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported through either of the following channels: - -- **GitHub Security Advisories** (preferred — private, encrypted, - auditable): - Tag the report as a conduct matter. -- **Email** (fallback): `j.d.a.jewell@open.ac.uk` — maintainer; - PGP key `4A03639C1EB1F86C7F0C97A91835A14A2867091E` published on - https://keys.openpgp.org. - -All complaints will be reviewed and investigated promptly and fairly. - -### Privacy - -All project team members are obligated to respect the privacy and security of the reporter of any incident. - -### Enforcement Guidelines - -Project maintainers will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: - -#### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning from project maintainers, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -#### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -#### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the project community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -#### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the project community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). - -## Questions - -For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. - ---- - -**Lineage**: Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/) -v2.1. Revisions tracked via `git log CODE_OF_CONDUCT.md`. This file -is intentionally version-free and date-free in prose to avoid R5b -drift. - -**Contact**: -(preferred) or `j.d.a.jewell@open.ac.uk` (fallback). diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index bc945a4f..6c883a98 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,222 +1,22 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell -= ECHIDNA — Contributing -:toc: macro -:icons: font - -Thanks for opening this file. ECHIDNA is owner-maintained and slow-merging -by design: each change has to compose with a trust-hardened verification -pipeline, a polyglot backend surface, and the -link:RSR_COMPLIANCE.adoc[RSR / CCCP hard-rule set]. This document tells -you how to keep your contribution composable. - -toc::[] - -== Before you start - -. Skim link:README.adoc[`README.adoc`] for the overview and - link:EXPLAINME.adoc[`EXPLAINME.adoc`] for "show me the receipts". -. Read link:RSR_COMPLIANCE.adoc[`RSR_COMPLIANCE.adoc`]. The - hard-rule list (RSR-H1…H15) is enforced by CI; the soft conventions - are checked at review time. -. Open an issue before doing significant work — design and scope - discussions are cheaper than a re-review. -. If you're using an AI agent (Claude Code, GitHub Copilot, etc.), - read link:CLAUDE.md[`CLAUDE.md`] first; it carries the collaboration - brief and the things to avoid sweeping. - -== Setup - -[source,bash] ----- -git clone https://github.com/hyperpolymath/echidna.git -cd echidna -just doctor # verify toolchain -just heal # auto-install missing tools -just tour # codebase tour ----- - -Language toolchains are described in link:QUICKSTART-DEV.adoc[`QUICKSTART-DEV.adoc`]. - -== What's accepted - -[cols="1,3", options="header"] -|=== -| Type | Notes - -| Corrective (bug fix) -| Welcome. Cite the failing test, log line, or reproduction in the - PR body. If the fix involves a new test, that test must fail at the - parent of the fix commit and pass at the fix commit. - -| Adaptive (env / dep / upstream change) -| Welcome. Pin every action SHA, every tool version, and every - upstream release. The `governance / Security policy checks` job - enforces versioned pins for `just|must|trust|adjust|bust|dust|intend` - family tools (R1 rule); other unpinned installs may be flagged by - reviewers. - -| Perfective (refactor / docs / clarity) -| Welcome _if_ pareto-optimal: every user-facing surface should be - at least as informative after the change. Don't shave numbers or - cite-points out without leaving a canonical pointer in their place - (see link:docs/PROVER_COUNT.md[`docs/PROVER_COUNT.md`] for the - count-deference convention this README uses). - -| Preventive (proactive hardening) -| Welcome with a stated motivation. Drive-by hardening with no - current risk should defer to a tracked issue first. -|=== - -== What's NOT accepted - -* **Python anywhere outside `salt/`** — banned by RSR-H4. The ML - layer is Julia; the rest is Rust / Idris2 / Chapel / Zig / - AffineScript-or-AffineScript. -* **Dockerfiles** — RSR-H15 requires Podman + `Containerfile` (or - `.containerization/Containerfile.wave3` for the per-prover image - tree). -* **Make** — RSR-H14: Justfile is primary. -* **`believe_me`, `assert_total`, `unsafePerformIO`, `prim__crash` - in `src/abi/`** — the Idris2 ABI is gated by - `.github/workflows/idris2-abi-ci.yml`; the scan rejects all four - unconditionally. Existing comments referencing those tokens are - fine; new uses are not. -* **`unsafe {}` in Rust without a `// SAFETY:` comment** — RSR-H6. -* **Removing CI workflows** — RSR-H7: needs explicit owner approval. -* **Generated code outside `generated/`** — RSR-H3. - -== Commits - -Conventional Commits prefixes — `feat`, `fix`, `docs`, `refactor`, -`test`, `chore`, `ci`, `build`, `perf`. The first line stays at or -under 72 characters; the body wraps at 80 and explains *why*. The -project uses GPG-signed commits (`git commit -S`); a maintainer can -help reviewers verify on request. - -For PRs touching more than one concern, prefer multiple atomic -commits over a single squash blob — squash happens at merge time. - -== Pull requests - -. Branch off `main` (`origin/main`). Stacked PRs against feature - branches are accepted but require the base branch in the PR - description. -. Rebase, don't merge, when pulling in main mid-PR. -. Fill in the PR template (the trio of *Summary*, *Why*, *Test plan* - blocks is the floor). If your PR touches the trust pipeline, the - Idris2 ABI, or the Chapel layer, name the invariants you preserved - in the *Why* block. -. Auto-merge (`gh pr merge --auto --squash --delete-branch`) is - fine and encouraged for low-risk PRs once CI is green. Admin merge - is the owner's tool for clearing pre-existing red checks at source. - -== Tests - -* `cargo test --lib` for unit tests; per-module test functions are - expected at change time. -* `cargo test --tests` for integration suites under `tests/`. -* `cargo test --test integration_tests` for the dispatcher - end-to-end suite specifically. -* `cargo bench` for criterion benchmarks. Regressions block merge by - convention — call out an expected regression in the *Why* block - before benchmarking. -* `idris2 --build src/abi/echidnaabi.ipkg` for the ABI. The CI gate - for this is `Type-check Idris2 ABI definitions`. -* `just chapel-build && just chapel-smoke && just chapel-test` for - the optional Chapel layer. - -== Documentation - -The doc surfaces and their authoritative responsibilities are: - -[cols="1,3", options="header"] -|=== -| Surface | Owns - -| link:README.adoc[`README.adoc`] | Overview, prover surface, quick start, architecture pointers. Defers counts to `docs/PROVER_COUNT.md` and history to `CHANGELOG.md`. -| link:README.md[`README.md`] | Thin Markdown pointer to `README.adoc` for `.md`-preferring renderers. -| link:EXPLAINME.adoc[`EXPLAINME.adoc`] | "Receipts for the README claims" — names commands and pointers, not embedded numbers. -| link:CHANGELOG.md[`CHANGELOG.md`] | Per-release notes; the single source of truth for "what shipped in vX.Y". -| link:docs/PROVER_COUNT.md[`docs/PROVER_COUNT.md`] | The canonical prover-count and tier table. If you find a doc that names a specific count, route it through here. -| link:docs/ARCHITECTURE.md[`docs/ARCHITECTURE.md`] | System architecture. -| link:docs/ENV-VARS.md[`docs/ENV-VARS.md`] | Environment variables. -| link:docs/ROADMAP.md[`docs/ROADMAP.md`] | Direction beyond the next release. -| link:RSR_COMPLIANCE.adoc[`RSR_COMPLIANCE.adoc`] | The hard-rule list and ECHIDNA's out-of-template adaptations. -| link:CLAUDE.md[`CLAUDE.md`] | Collaboration brief for Claude Code; not a tutorial. -|=== - -If you add a new doc, slot it into the table above and link to it from -the `Documentation` section of `README.adoc`. - -== License and SPDX - -ECHIDNA is licensed in three parts. Use the licence of the part of the -tree your file sits in — do not copy a header from elsewhere: - -[cols="1,1"] -|=== -| Part | SPDX identifier - -| Application code — `src/`, `crates/`, `ffi/`, `proofs/`, `spark/`, - `verification/`, `scripts/`, build system, CI -| `AGPL-3.0-or-later` - -| Machine-readable specification surface — `.machine_readable/`, - `0-AI-MANIFEST.a2ml`, package/container manifests, OCI image labels -| `MPL-2.0` - -| Documentation — `docs/`, top-level `.md` / `.adoc` -| `CC-BY-SA-4.0` - -| `echidna-playground/` — the Coq-Jr sub-project -| `MPL-2.0` -|=== - -The specification surface is weak-copyleft on purpose. It is metadata and -spec material intended for interoperability, some of it on a path to -standards-body submission, where strong copyleft would obstruct adoption -and re-publication. Improvements to those files stay open; implementing -against them carries no obligation. - -New files carry two lines, with the SPDX identifier *first* (the -workflow linter checks line 1): - -[source] ----- -// SPDX-License-Identifier: AGPL-3.0-or-later -// SPDX-FileCopyrightText: ----- - -`NOTICE` explains why an MPL-2.0 component is compatible inside an -AGPL work (MPL-2.0 §3.3, Secondary Licenses) and carries the full -statement. - -=== The Palimpsest framework is not a licence grant here - -ECHIDNA's contribution model references the *Palimpsest License* as an -ethical / philosophical framework: a discipline about how contributions -are received, attributed, and forwarded. That reference is preserved -and is orthogonal to the SPDX choice. - -It is *not* a legal grant in this repository. The Palimpsest licence -proper is the legal licence only on `palimpsest-license`, -`palimpsest-plasma`, and (prospectively) `consent-aware-http`. Some -files here previously carried `... OR Palimpsest-0.6` / -`... AND Palimpsest-0.6` SPDX identifiers; those were drift, not a -deliberate grant, and were removed in 2026-08. Do not reintroduce a -Palimpsest identifier into an SPDX header in this repository. - -== Security - -Vulnerabilities go through link:SECURITY.md[`SECURITY.md`], not the -public issue tracker. The supply-chain hardening conventions -(SHA-pinned actions, R1 family-tool pins, OpenSSF Scorecard -enforcement) are enforced by CI; the *governance* workflow is the -gate. - -== Where to go next - -* Open an issue: https://github.com/hyperpolymath/echidna/issues -* Read the project Code of Conduct: link:CODE_OF_CONDUCT.md[`CODE_OF_CONDUCT.md`] -* See current maintainers: link:MAINTAINERS.adoc[`MAINTAINERS.adoc`] +== Contributing + +Please read link:CONTRIBUTING.adoc[`+CONTRIBUTING.adoc+`] for the full +contribution guidelines — what is accepted, what is not, the commit and +PR conventions, the test layout, the documentation surface map, and the +licence / SPDX policy. GitHub renders AsciiDoc directly. + +If a quick orientation is enough: + +* *Before you start*: read link:README.md[`+README.md+`], +link:RSR_COMPLIANCE.adoc[`+RSR_COMPLIANCE.adoc+`], and +link:CLAUDE.md[`+CLAUDE.md+`] (if you are using an AI agent). +* *Local setup*: see link:QUICKSTART-DEV.adoc[`+QUICKSTART-DEV.adoc+`]. +* *Tests*: `+cargo test --lib+`, `+cargo test --tests+`, and +`+idris2 --build src/abi/echidnaabi.ipkg+` for the ABI surface. +* *Commits*: Conventional Commits, GPG-signed, atomic. +* *PRs*: branch off `+main+`, rebase don’t merge, fill the template, +auto-merge once green. +* *Banned*: Python outside `+salt/+`, Dockerfiles (use Podman + +`+Containerfile+`), Make (use Justfile), `+believe_me+` / +`+assert_total+` / `+unsafePerformIO+` / `+prim__crash+` in +`+src/abi/+`, bare `+unsafe {}+` without `+// SAFETY:+` in Rust. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 74d0593c..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,30 +0,0 @@ - - -# Contributing - -Please read [`CONTRIBUTING.adoc`](CONTRIBUTING.adoc) for the full -contribution guidelines — what is accepted, what is not, the commit -and PR conventions, the test layout, the documentation surface map, -and the licence / SPDX policy. GitHub renders AsciiDoc directly. - -If a quick orientation is enough: - -- **Before you start**: read [`README.md`](README.md), - [`RSR_COMPLIANCE.adoc`](RSR_COMPLIANCE.adoc), and - [`CLAUDE.md`](CLAUDE.md) (if you are using an AI agent). -- **Local setup**: see [`QUICKSTART-DEV.adoc`](QUICKSTART-DEV.adoc). -- **Tests**: `cargo test --lib`, `cargo test --tests`, and - `idris2 --build src/abi/echidnaabi.ipkg` for the ABI surface. -- **Commits**: Conventional Commits, GPG-signed, atomic. -- **PRs**: branch off `main`, rebase don't merge, fill the - template, auto-merge once green. -- **Banned**: Python outside `salt/`, Dockerfiles (use Podman + - `Containerfile`), Make (use Justfile), `believe_me` / - `assert_total` / `unsafePerformIO` / `prim__crash` in `src/abi/`, - bare `unsafe {}` without `// SAFETY:` in Rust. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index f893c5ca..f662f218 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,14 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +The governance model for ECHIDNA is documented in +link:GOVERNANCE.adoc[`+GOVERNANCE.adoc+`] — decision-making, maintainer +responsibilities, the RSR/CCCP compliance position, and how changes are +ratified. GitHub renders AsciiDoc directly. -== Overview +Related: -This repository follows a **Sole Maintainer Governance Model**: - -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable - -== Core Principles - -[cols="1,2"] -|=== -| Principle | Description - -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input - -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity - -| **Transparency** | All significant decisions are documented publicly - -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary - -| **Open Contribution** | Anyone can contribute via fork and pull request - -|=== - -== Roles and Permissions - -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment - -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users - -|=== - -== Decision Making Framework - -=== Routine Decisions - -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates - -**Process**: Maintainer reviews and merges PRs that meet quality standards. - -=== Significant Changes - -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/descriptiles/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +* link:MAINTAINERS.adoc[`+MAINTAINERS.adoc+`] — who maintains what +* link:CONTRIBUTING.adoc[`+CONTRIBUTING.adoc+`] — contribution process +* link:CODE_OF_CONDUCT.md[`+CODE_OF_CONDUCT.md+`] — expected conduct +* link:RSR_COMPLIANCE.adoc[`+RSR_COMPLIANCE.adoc+`] — compliance +statement diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index 3fd11040..00000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,24 +0,0 @@ - - -# Governance - -The governance model for ECHIDNA is documented in -[`GOVERNANCE.adoc`](GOVERNANCE.adoc) — decision-making, maintainer -responsibilities, the RSR/CCCP compliance position, and how changes are -ratified. GitHub renders AsciiDoc directly. - -Related: - -- [`MAINTAINERS.adoc`](MAINTAINERS.adoc) — who maintains what -- [`CONTRIBUTING.adoc`](CONTRIBUTING.adoc) — contribution process -- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — expected conduct -- [`RSR_COMPLIANCE.adoc`](RSR_COMPLIANCE.adoc) — compliance statement diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..0b275c39 --- /dev/null +++ b/README.adoc @@ -0,0 +1,617 @@ +link:LICENSE[image:https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg[License: +AGPL-3.0-or-later]] +https://www.thegreenwebfoundation.org/green-web-check/?url=nesy-prover.dev[image:https://api.thegreenwebfoundation.org/greencheckimage/nesy-prover.dev[Green +Hosting]] + +____ +*Licensing.* ECHIDNA is licensed in four parts: *application code* under +AGPL-3.0-or-later; the *machine-readable specification surface* +(`+.machine_readable/+`, manifests, OCI labels) under MPL-2.0, +deliberately weak-copyleft so it stays usable for interoperability and +standards work; *documentation* under CC-BY-SA-4.0; and +*`+echidna-playground/+`* under MPL-2.0. The combined work distributes +as AGPL-3.0-or-later — run a modified ECHIDNA as a network service and +you must offer your users the modified source. MPL §3.3 (Secondary +Licenses) is what makes the MPL parts compatible inside the AGPL work. +Full statement: link:NOTICE[`+NOTICE+`]. +____ + +*E*xtensible *C*ognitive *H*ybrid *I*ntelligence for *D*eductive +*N*eural *A*ssistance + +A neurosymbolic theorem-proving platform with a trust-hardened +verification pipeline, multi-objective proof search, and a polyglot +backend surface (Rust core + Julia ML + Idris2 ABI + Zig FFI + optional +Chapel parallel layer). + +== Prover Surface + +Backend tiering, count semantics (variants vs. impl files vs. advertised +vs. core), and "`what’s the canonical number`" answers live in a single +source of truth: link:docs/PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`]. +The REST API (`+GET+` `+/api/provers+`) exposes the Tier-1 _core_ set by +default; all other backends are reachable through `+ProverKind+` and the +dispatch pipeline. See +link:docs/SUPPORTED_PROVERS.md[`+docs/SUPPORTED_PROVERS.md+`] for the +core list, required external binaries, and how to surface additional +backends through the API. + +== Distinguishing Features + +* *Trust-hardened pipeline* — every proof passes through solver +integrity verification, axiom tracking, certificate checking, and +Bayesian confidence scoring before the result is returned. +* *Cross-prover arbitration* — mathematical object identity resolution +across heterogeneous prover backends; four arbitration mechanisms +(portfolio majority-vote, Bayesian posterior, Dempster-Shafer belief +combination, Pareto multi-objective frontier) see the Arbitration +section below. +* *Neurosymbolic architecture* — Julia ML layer suggests tactics; formal +provers always have the final word. +* *Cross-prover proof exchange* — universal interchange across six +formats: OpenTheory, Dedukti, TPTP, SMT-LIB, SMTCoq, Lambdapi +(`+src/rust/exchange/+`). +* *17 corpus adapters* — every major public proof corpus has a +structural ingest path. See Corpus Coverage. +* *Axiom-usage tracking* — four danger levels (Safe, Noted, Warning, +Reject) applied uniformly across every backend. + +== Overview + +ECHIDNA orchestrates theorem provers, SMT solvers, first-order ATPs, and +constraint solvers through a unified Rust core. Every proof result +passes through a trust-hardening pipeline that checks solver integrity, +tracks axiom usage, verifies proof certificates, and assigns a 5-level +confidence score. + +Neural premise selection (via Julia) suggests tactics; formal provers +always have the final word. ECHIDNA never reports a proof as verified +without the underlying backend agreeing. The neurosymbolic and +formal-verification layers are wired so the ML suggestion path can only +ever _accelerate_ a proof attempt — never substitute for one. + +The Idris2 ABI layer (`+src/abi/EchidnaABI/+`) carries the type-level +specifications and totality proofs that pin the on-wire contracts +between the Rust dispatcher, the Julia GNN ranker, and the Chapel +parallel rank-merge — including the fixed-point `+ConfidenceFP+` +encoding with its round-trip and total-order properties (zero +`+believe_me+`, zero postulates, zero admits). + +== Features + +=== Prover Backends + +The Tier-1 _core_ set is what `+GET+` `+/api/provers+` exposes by +default and what is required to pass for green CI; the live membership +list is `+ProverKind::all_core()+` in `+src/rust/provers/mod.rs+`, +mirrored in human-readable form at +link:docs/SUPPORTED_PROVERS.md[`+docs/SUPPORTED_PROVERS.md+`] (with +required external binaries and install hints). The remaining tiers +(extended, niche, Wave-3 secured, Wave-2 modal/real-algebraic, pure-Rust +in-process, HP type-checker ecosystem, TypeChecker disciplines, Coq-Jr +playground) cover interactive provers, first-order ATPs, SAT/SMT +solvers, auto-active verifiers, constraint/optimisation backends, model +checkers, C/hardware verifiers, security-protocol tools, and specialised +systems. The full tier table and membership list — the only place these +counts are maintained — is +link:docs/PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`]. + +All backends in the Tier-1 / Tier-2 / Wave-3 / Wave-2 / pure-Rust groups +implement the `+ProverBackend+` trait (parse, verify, export, tactic +suggestion, theorem search). File-extension detection covers 30+ formats +(`+.v+`, `+.lean+`, `+.smt2+`, `+.tptp+`, `+.dfy+`, `+.mzn+`, …). + +=== Trust & Safety Hardening + +The verification pipeline applies the following checks to every proof: + +* *Solver Binary Integrity* (`+integrity/+`): SHAKE3-512 provenance +hashing and BLAKE3 fast runtime re-verification. Solver binaries are +checked against a TOML manifest at startup; tampered binaries are +rejected. + +* *SMT Portfolio Solving* (`+verification/portfolio.rs+`): Cross-checks +proofs across multiple solvers (e.g. Z3 + CVC5 + Alt-Ergo). Flags +disagreements for human review. Supports SMT, ATP, and ITP solver pools. + +* *Proof Certificate Checking* (`+verification/certificates.rs+`): +Verifies Alethe (CVC5), DRAT/LRAT (SAT solvers), TSTP (first-order +ATPs), Lean4 kernel, and Coq kernel certificate formats. Certificates +are hashed with BLAKE3 and stored for audit trails. + +* *Axiom Usage Tracking* (`+verification/axiom_tracker.rs+`): Scans +proof content for dangerous constructs across provers. Four danger +levels: +** *Safe*: Standard library axioms +** *Noted*: Classical axioms in constructive systems (e.g. `+Axiom+` in +Coq) +** *Warning*: Incomplete proof markers (`+sorry+`, `+Admitted+`, +`+postulate+`) +** *Reject*: Known unsound constructs (`+--type-in-type+`, `+mk_thm+`, +`+believe_me+`) Comments are not flagged. + +* *Solver Sandboxing* (`+executor/sandbox.rs+`): Runs solvers in +isolated environments. Three modes: Podman containers (preferred, +`+--network=none+`, read-only, memory/CPU/disk limits), bubblewrap +namespaces (fallback), or unsandboxed (development only, requires +explicit opt-in). Auto-detection selects the strongest available option. + +* *5-Level Trust Hierarchy* (`+verification/confidence.rs+`): Every +proof result receives a trust level: +** Level 1: Large-TCB system, unchecked, or dangerous axioms used +** Level 2: Single prover, no dangerous axioms +** Level 3: Single prover with verified proof certificate +** Level 4: Small-kernel prover (Lean, Coq, Isabelle, Agda, Metamath, +HOL Light, HOL4, Idris2, F*, Twelf, Nuprl, Minlog) with verified +certificate +** Level 5: Cross-checked by 2+ independent small-kernel systems with +certificates + +* *Mutation Testing* (`+verification/mutation.rs+`): Deliberately +weakens specifications (remove preconditions, weaken postconditions, +negate subterms, replace constants) to verify the pipeline catches them. +Computes a mutation score with a default 95% threshold. + +* *Cross-Prover Proof Exchange* (`+exchange/+`): Export and import +proofs in six universal formats — OpenTheory (HOL family interop), +Dedukti and Lambdapi (lambda-Pi calculus modulo rewriting), TPTP +(`+exchange/tptp.rs+` — first-order ATP universal exchange), SMT-LIB v2 +(`+exchange/smtlib.rs+` — cross-solver normalisation), and SMTCoq +(`+exchange/smtcoq.rs+` — Alethe / LFSC / DRAT skeleton parser for Coq +kernel re-checking). See Wire Schema for the formal data contracts. + +* *Pareto Optimisation* (`+verification/pareto.rs+`): Multi-objective +ranking of proof candidates across four axes: proof time, trust level, +memory usage, and proof size. Computes the Pareto frontier and +optionally applies weighted scoring for single-best selection. + +* *Statistical Confidence Tracking* (`+verification/statistics.rs+`): +Per-prover, per-domain success rates and timing statistics. Bayesian +timeout estimation (mean + 2 sigma). Wilson score intervals for mutation +score confidence. Prover ranking by composite score (success rate, +timeout rate, speed). JSON serialisation for persistence. + +* *Dispatch Pipeline* (`+dispatch.rs+`): Orchestrates the full pipeline: +create prover → parse → verify → axiom scan → confidence scoring. +Supports single-prover and cross-checked (portfolio) modes with +configurable minimum trust levels. + +=== Additional Capabilities + +* *Neurosymbolic ML* (Julia layer): Logistic-regression tactic +prediction; serves rankings via HTTP for the GNN-augmented dispatch +path. Output flows through the type-level `+TacticSuggestion+` / +`+ConfidenceFP+` ABI before any consumer touches it. +* *Aspect Tagging*: Proof categorisation and domain analysis. +* *Anomaly Detection*: ML-based overconfidence detection on dispatcher +outputs. +* *Agentic Proof Search*: Actor-based autonomous proof exploration. +* *Chapel Parallel Layer* (optional): Coforall-based parallel proof +dispatch, including a per-prover cwd/filename-override hook in +`+tryProver+` so each backend can be invoked with its required workspace +shape (Idris2 / Agda case studies in link:src/chapel/[`+src/chapel/+`]). +* *Three API surfaces*: +** GraphQL (async-graphql, port 8081) +** gRPC (tonic + Protocol Buffers, port 50051) +** REST (axum + OpenAPI/Swagger, port 8000) +* *AffineScript / AffineScript UI*: AffineScript components are being +ported to AffineScript-TEA as the stdlib primitives needed for the port +(Http / Promise / Json / Dict) land in +https://github.com/hyperpolymath/affinescript[affinescript]. +* *REPL*: Interactive proof session via rustyline (`+cargo+` +`+run — interactive+`). + +== Quick Start + +=== Prerequisites + +* *Rust* nightly (managed via asdf or rustup) +* *Just* command runner (`+cargo+` `+install+` `+just+`) +* *pkg-config* + *openssl-devel* / *libssl-dev* (system) +* *Podman* (NOT Docker) — recommended for solver sandboxing + +Optional, by component: + +* *Julia* 1.10+ — ML layer (`+src/julia/+`) +* *Idris2* >= 0.7.0 — ABI type-check (`+src/abi/+`) +* *Zig* >= 0.13.0 — FFI bridge (`+ffi/zig/+`, `+src/zig_ffi/+`) +* *Chapel* — optional parallel proof dispatch (`+src/chapel/+`, +`+--features+` `+chapel+`) +* *Deno* >= 2.0 — AffineScript / AffineScript UI (`+src/affinescript/+`, +`+src/ui/+`) + +Run `+just+` `+doctor+` to verify what’s actually installed; `+just+` +`+heal+` will offer to install missing pieces non-destructively. + +=== Build and Test + +[source,bash] +---- +# Clone +git clone https://github.com/hyperpolymath/echidna.git +cd echidna + +# Build +just build +# or: cargo build + +# Run all tests +just test +# or: cargo test + +# Launch the interactive proof REPL +cargo run -- interactive +# or: just run interactive +---- + +=== Prove your first goal + +[source,bash] +---- +# Install at least one solver — Z3 is the smallest dependency +sudo apt install z3 # Debian/Ubuntu (or `brew install z3`) + +# Start the REST API server with CORS enabled +cargo run --bin echidna -- server --cors + +# In another terminal, POST a satisfiable SMT-LIB goal +curl -X POST http://127.0.0.1:8081/api/prove \ + -H 'Content-Type: application/json' \ + -d '{"prover":"Z3", + "content":"(set-logic QF_LIA)\n(declare-const x Int)\n(assert (> x 0))\n(check-sat)\n", + "timeout":30}' +# → {"success":true,"goals":1,"message":"Proof verified successfully"} +---- + +For a minimal browser UI, open `+src/ui/public/prove.html+` directly in +any modern browser and point the "`API base`" field at the running +server. No build step is required. + +See link:docs/SUPPORTED_PROVERS.md[`+docs/SUPPORTED_PROVERS.md+`] for +the Tier-1 core set, required binaries, and how to expose additional +backends through the API. + +=== Using Podman Container + +[source,bash] +---- +podman build -f Containerfile -t echidna:latest . +podman run -it echidna:latest +---- + +== Architecture + +=== Technology Stack + +* *Rust*: Core logic, prover backends, trust pipeline, CLI, REPL, API +servers +* *Julia*: ML inference (tactic prediction, premise selection) +* *AffineScript + Deno*: UI components +* *Chapel*: Optional parallel proof dispatch + +=== Key Modules + +.... +src/rust/ + provers/ # Per-backend ProverBackend impls (see docs/PROVER_COUNT.md for the live tier table) + verification/ # Trust-hardening subsystem + portfolio.rs # SMT portfolio solving / cross-checking + certificates.rs # Proof certificate checking (Alethe, DRAT/LRAT, TSTP) + axiom_tracker.rs# Axiom usage scanning and policy enforcement + confidence.rs # 5-level trust hierarchy + mutation.rs # Mutation testing for specifications + pareto.rs # Pareto frontier candidate ranking + pareto_arbiter.rs # Pareto multi-objective arbiter (post-portfolio) + bayesian_arbiter.rs # Bayesian posterior arbiter + dempster_shafer.rs # Dempster-Shafer mass-function arbiter + statistics.rs # Per-prover statistical tracking + integrity/ # Solver binary integrity (SHAKE3-512, BLAKE3) + executor/ # Sandboxed solver execution (Podman, bubblewrap) + exchange/ # Cross-prover proof exchange (OpenTheory, Dedukti, TPTP, SMT-LIB, SMTCoq, Lambdapi — 6 formats) + dispatch.rs # Full trust-hardening dispatch pipeline + agent/ # Agentic proof search (actor model) + neural.rs # Neural premise selection integration + aspect.rs # Aspect tagging system + anomaly_detection.rs + proof_search.rs # Chapel parallel proof search + core.rs # Core types (Term, ProofState, Tactic, Goal, etc.) + parsers/ # Proof file parsers + ffi/ # Foreign function interface + server.rs # HTTP API server + repl.rs # Interactive REPL + main.rs # CLI entry point + lib.rs # Library root + corpus/ # 17 corpus adapters (see "Corpus Coverage" below) +.... + +=== Corpus Coverage + +Seventeen structural ingest adapters cover every major public proof +corpus reachable to date. Each lives under `+src/rust/corpus/.rs+` +and exposes a `+pub+` `+fn+` `+ingest(root:+` `+&Path)+` `+→+` +`+Result+` returning the canonical `+Corpus+` struct defined at +link:src/rust/corpus/mod.rs[`+src/rust/corpus/mod.rs:156+`]. Two-pass +extraction: pass 1 enumerates module + decl names; pass 2 scans decl +bodies and records references against the pass-1 name set +(link:src/rust/corpus/mod.rs[`+src/rust/corpus/mod.rs:25+`]). Hazards +(axioms, sorry, believe_me, cheat, …) populate `+AxiomUsage+` per entry. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Adapter |Source |Purpose +|`+agda+` |`+*.agda+` |Agda stdlib + cubical (pre-2026-04) + +|`+coq+` |`+*.v+` |Coq / Rocq libraries (pre-2026-04) + +|`+lean+` |`+*.lean+` |Lean 4 + mathlib4 (pre-2026-04) + +|`+idris2+` |`+*.idr+` / `+*.ipkg+` |Idris 2 stdlib + base (pre-2026-04) + +|`+isabelle+` |`+*.thy+` |Isabelle/HOL + AFP entries + +|`+metamath+` |`+*.mm+` |set.mm and friends + +|`+mizar+` |`+*.miz+`, `+*.abs+` |Mizar Mathematical Library + +|`+hol_light+` |`+*.ml+` (HOL Light) |Multivariate / Core + +|`+hol4+` |`+*Script.sml+` |HOL4 theory scripts + +|`+dafny+` |`+*.dfy+` |Dafny verification suite + +|`+why3+` |`+*.mlw+`, `+*.why+` |Why3 TOCCATA gallery + +|`+fstar+` |`+*.fst+`, `+*.fsti+` |F* examples + stdlib + +|`+acl2_books+` |`+*.lisp+`, `+*.acl2+` |ACL2 community books + +|`+tptp+` |`+*.p+`, `+*.tptp+` |TPTP problem library (CNF / FOF) + +|`+smtlib+` |`+*.smt2+`, `+*.smt+` |SMT-LIB v2 benchmarks + +|`+proofnet+` |`+*.jsonl+` |ProofNet NL→formal pairs + +|`+minif2f+` |`+*.lean+` / `+*.thy+` / `+*.ml+` / `+*.mm+` / `+*.v+` +|MiniF2F olympiad multi-target +|=== + +Full per-adapter source URLs, hazard flag inventory, fixture layout and +downstream wiring (`+suggest+` / `+octad-emit+` / GNN training) are in +link:docs/CORPUS-ADAPTERS.md[`+docs/CORPUS-ADAPTERS.md+`]. + +=== Cross-prover Vocabulary + +Per-prover synonym tables (one TOML per backend, ~863 lines of seed +content as of 2026-06-01) sit under +link:data/synonyms/[`+data/synonyms/+`] and drive the `+echidna+` +`+suggest+` variant-tester (`+src/rust/suggest/synonyms.rs+`). The +schema (canonical + aliases + tactic_class + version range) and contract +are documented in +link:data/synonyms/README.adoc[`+data/synonyms/README.adoc+`]. + +Three cross-prover taxonomic dictionaries (underscore-prefixed, merged +via `+SynonymTable::merge_external()+`) layer a common mathematical +vocabulary over the per-prover tables: + +* `+_msc2020.toml+` — *87* MSC2020 codes for cross-domain classification +(e.g. `+03B45+` modal logic, `+68V20+` formalised mathematics). +* `+_wordnet_math.toml+` — *~80* lemmas from the WordNet 3.1 math +sub-hierarchy for natural-language anchor terms. +* `+_conceptnet_seed.toml+` — *~55* pre-fetched ConceptNet 5.7 edges for +offline-resilient `+semantic_class+` resolution. + +=== Arbitration + +When multiple provers attack the same goal, four arbitration mechanisms +turn a multiset of outcomes into a decision: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Mechanism |Module |Behaviour +|Portfolio majority-vote +|link:src/rust/verification/portfolio.rs[`+verification/portfolio.rs+`] +|Simple agreement count across solvers; flags disagreements for human +review. Original cross-checking surface. + +|Bayesian posterior +|link:src/rust/verification/bayesian_arbiter.rs[`+verification/bayesian_arbiter.rs+`] +|Per-prover (precision, 1-FPR) likelihoods + log-odds accumulation; +returns posterior `+(p_proven,+` `+p_refuted,+` `+p_unknown)+` with +Shannon entropy. Numerically stable; Timeout/Unknown/Error contribute LR += 1. + +|Dempster-Shafer +|link:src/rust/verification/dempster_shafer.rs[`+verification/dempster_shafer.rs+`] +|Mass-function combination with explicit ignorance; tracks the conflict +scalar `+K+`. Refuses to combine when total conflict > 0.95 +(`+ArbiterError::ExcessiveConflict+`). + +|Pareto frontier +|link:src/rust/verification/pareto_arbiter.rs[`+verification/pareto_arbiter.rs+`] +(multi-objective arbitration sibling to `+verification/pareto.rs+` — the +candidate-ranking pre-arbiter) |Multi-objective dominance across time / +trust / memory / proof-size; configurable `+Tiebreak+` policy chooses a +single recommended pick from the frontier. +|=== + +=== Wire Schema + +The data contract between ECHIDNA and its long-term memory store +(VeriSimDB) is formalised: + +* link:docs/architecture/VERISIM-ER-SCHEMA.md[`+docs/architecture/VERISIM-ER-SCHEMA.md+`] +— 12 first-class entities + 7 first-class relationships, each with its +Rust struct, VeriSimDB table, Cap’n Proto schema, and PK/FK set. +Replaces the aspirational text in the 2026-04-17 triangulation document. +* link:crates/echidna-wire/schemas/verisim_er.capnp[`+crates/echidna-wire/schemas/verisim_er.capnp+`] +— Cap’n Proto wire schema (struct id `+@0xe4dc7b1f01a06001+`). + +Drift detection is by hash over both files; the per-PR `+er-drift+` CI +gate is tracked alongside the schema. + +=== API Usage + +[source,rust] +---- +use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; + +// Create a prover backend +let backend = ProverFactory::create(ProverKind::Lean, ProverConfig::default())?; +let state = backend.parse_string("theorem foo : 1 + 1 = 2 := by omega").await?; +let verified = backend.verify_proof(&state).await?; +---- + +[source,rust] +---- +use echidna::dispatch::{ProverDispatcher, DispatchConfig}; +use echidna::provers::ProverKind; + +// Use the trust-hardening dispatch pipeline +let dispatcher = ProverDispatcher::with_config(DispatchConfig { + cross_check: true, + track_axioms: true, + ..Default::default() +}); + +// Cross-checked verification +let result = dispatcher.verify_proof_cross_checked( + ProverKind::Z3, + "(set-logic QF_LIA)\n(assert (> x 0))\n(check-sat)", + &[ProverKind::CVC5], +).await?; + +println!("Verified: {}, Trust: {}", result.verified, result.trust_level); +---- + +== Test Suite + +The test surface spans unit tests inside `+src/rust/+` and integration +suites under `+tests/+`, supplemented by property tests, criterion +benchmarks, and Idris2 ABI type-checks. Current counts are not embedded +here — `+cargo+` `+test+` `+--lib+`, `+cargo+` `+test+` `+--tests+`, and +link:CHANGELOG.md[`+CHANGELOG.md+`] carry the live numbers. + +* Smoke E2E integration tests across the Tier-1 prover backends +* Property-based tests (PropTest) +* Criterion benchmarks across all critical paths +* Idris2 ABI type-check (`+idris2+` `+--build+` +`+src/abi/echidnaabi.ipkg+`) enforces zero `+believe_me+` / +`+assert_total+` / `+postulate+` in the ABI modules. + +[source,bash] +---- +cargo test # All Rust tests +cargo test --lib # Unit tests only +cargo test --test integration_tests +idris2 --build src/abi/echidnaabi.ipkg # ABI type-check +---- + +== Development + +=== Quality Checks + +[source,bash] +---- +just check # Roll-up: fmt-check + lint + test +just lint # REUSE, rustfmt, clippy +just audit # cargo-audit + supply-chain check +just pre-commit # fmt-check + lint + test (use in git hooks) +just assail # panic-attacker security scan (requires the panic-attack CLI) +just mvp # MVP smoke checks (reports missing provers, non-fatal) +just doctor # Verify required toolchain is on PATH +just heal # Offer to install missing tools +just tour # Guided walkthrough of the repo +---- + +`+just+` `+--list+` enumerates every recipe; `+just+` `+help-me+` prints +an onboarding subset. + +== Current Status + +The authoritative status surface — release history, what shipped in each +minor, what’s targeted next — is link:CHANGELOG.md[`+CHANGELOG.md+`]. +For roadmap items beyond the next release, see +link:docs/ROADMAP.md[`+docs/ROADMAP.md+`]. + +Headline shape (as of the most recent on-main work): + +* *Trust pipeline*: solver-integrity, certificate-checking, +axiom-tracking, sandboxing, mutation-testing, Pareto ranking, Bayesian +confidence — all wired into `+dispatch.rs+`. +* *Idris2 ABI*: `+EchidnaABI.TacticRecord+` (fixed-point confidence, +total-order proofs, in-range round-trip lemmas), `+Provers+`, +`+AxiomTracker+`, `+Gnn+`, `+CapnSchemas+` — type-checked on every push. +* *Chapel parallel layer*: per-prover cwd / filename hooks +(`+tryProver+`) and L2.3 cancel-token preemption. +* *Wave-3 container infrastructure*: 8-cell weekly cron building each +Tier-3 prover image with stub-sentinel detection. +* *Estate migrations in flight*: AffineScript→AffineScript UI; npm→Deno +for `+echidna-playground+`; CI workflow consolidation under the +governance ruleset. + +== Documentation + +* link:CONTRIBUTING.md[Contributing Guidelines] +* link:CODE_OF_CONDUCT.md[Code of Conduct] +* link:SECURITY.md[Security Policy] +* link:CHANGELOG.md[Changelog] +* link:docs/ROADMAP.md[Roadmap] +* link:RSR_COMPLIANCE.adoc[RSR / CCCP Compliance Statement] +* link:EXPLAINME.adoc[EXPLAINME — receipts for the README claims] +* link:docs/PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`] — canonical +prover-count and tier table +* link:docs/ARCHITECTURE.md[`+docs/ARCHITECTURE.md+`] — system overview +* link:docs/CORPUS-ADAPTERS.md[`+docs/CORPUS-ADAPTERS.md+`] — 17-adapter +corpus ingest index +* link:docs/architecture/VERISIM-ER-SCHEMA.md[`+docs/architecture/VERISIM-ER-SCHEMA.md+`] +— VeriSim ↔ ECHIDNA entity-relationship schema +* link:docs/decisions/2026-06-01-saturation-campaign.md[`+docs/decisions/2026-06-01-saturation-campaign.md+`] +— ADR for the saturation campaign (corpora / vocab / synonyms / exchange +/ arbitration) +* link:docs/handover/PROVER-CORPUS-SATURATION-LANE.md[`+docs/handover/PROVER-CORPUS-SATURATION-LANE.md+`] +— saturation lane handover +* link:docs/ENV-VARS.md[`+docs/ENV-VARS.md+`] — environment variables +* link:CLAUDE.md[`+CLAUDE.md+`] — collaboration brief for Claude Code + +== Critical Constraints + +* *No Python* — Julia for ML, Rust for systems, AffineScript / +AffineScript for UI. (`+salt/+` is the only carve-out.) +* *RSR / CCCP Compliance* — see +link:RSR_COMPLIANCE.adoc[`+RSR_COMPLIANCE.adoc+`] for the full hard-rule +list and ECHIDNA’s out-of-template adaptations. +* *Justfile primary* — Just is the build entry point; no Make. +* *Podman not Docker* — always Podman; `+Containerfile+` +(`+.containerization/+` for the per-prover images) not `+Dockerfile+`. +* *License*: AGPL-3.0-or-later. See LICENSE. + +== License + +This project is licensed under the link:LICENSE[GNU Affero General +Public License v3.0 or later]. Individual files may carry earlier +MPL-2.0 SPDX headers pending the header migration sweep. + +== Citation + +[source,bibtex] +---- +@software{echidna2026, + title = {ECHIDNA: Extensible Cognitive Hybrid Intelligence for Deductive Neural Assistance}, + author = {Jewell, Jonathan D.A.}, + year = {2026}, + url = {https://github.com/hyperpolymath/echidna}, + license = {AGPL-3.0-or-later} +} +---- + +== Contact + +* *GitHub Issues*: https://github.com/hyperpolymath/echidna/issues +* *Pull Requests*: https://github.com/hyperpolymath/echidna/pulls + +''''' + +*Author*: Jonathan D.A. Jewell + +*Version and last-changed date*: tracked in +link:CHANGELOG.md[`+CHANGELOG.md+`] and the git log; not duplicated here +to avoid drift. diff --git a/README.md b/README.md deleted file mode 100644 index 2640ad16..00000000 --- a/README.md +++ /dev/null @@ -1,665 +0,0 @@ - - -[![License: AGPL-3.0-or-later](https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg)](LICENSE) [![Green Hosting](https://api.thegreenwebfoundation.org/greencheckimage/nesy-prover.dev)](https://www.thegreenwebfoundation.org/green-web-check/?url=nesy-prover.dev) - - - -> **Licensing.** ECHIDNA is licensed in four parts: **application code** under -> AGPL-3.0-or-later; the **machine-readable specification surface** -> (`.machine_readable/`, manifests, OCI labels) under MPL-2.0, deliberately -> weak-copyleft so it stays usable for interoperability and standards work; -> **documentation** under CC-BY-SA-4.0; and **`echidna-playground/`** under -> MPL-2.0. The combined work distributes as AGPL-3.0-or-later — run a -> modified ECHIDNA as a network service and you must offer your users the -> modified source. MPL §3.3 (Secondary Licenses) is what makes the MPL parts -> compatible inside the AGPL work. Full statement: [`NOTICE`](NOTICE). - -\*E\*xtensible \*C\*ognitive \*H\*ybrid \*I\*ntelligence for -\*D\*eductive \*N\*eural \*A\*ssistance - -A neurosymbolic theorem-proving platform with a trust-hardened -verification pipeline, multi-objective proof search, and a polyglot -backend surface (Rust core + Julia ML + Idris2 ABI + Zig FFI + optional -Chapel parallel layer). - -# Prover Surface - -Backend tiering, count semantics (variants vs. impl files vs. advertised -vs. core), and "what’s the canonical number" answers live in a single -source of truth: [`docs/PROVER_COUNT.md`](docs/PROVER_COUNT.md). The -REST API (`GET` `/api/provers`) exposes the Tier-1 *core* set by -default; all other backends are reachable through `ProverKind` and the -dispatch pipeline. See -[`docs/SUPPORTED_PROVERS.md`](docs/SUPPORTED_PROVERS.md) for the core -list, required external binaries, and how to surface additional backends -through the API. - -# Distinguishing Features - -- **Trust-hardened pipeline** — every proof passes through solver - integrity verification, axiom tracking, certificate checking, and - Bayesian confidence scoring before the result is returned. - -- **Cross-prover arbitration** — mathematical object identity resolution - across heterogeneous prover backends; four arbitration mechanisms - (portfolio majority-vote, Bayesian posterior, Dempster-Shafer belief - combination, Pareto multi-objective frontier) see the - Arbitration section - below. - -- **Neurosymbolic architecture** — Julia ML layer suggests tactics; - formal provers always have the final word. - -- **Cross-prover proof exchange** — universal interchange across six - formats: OpenTheory, Dedukti, TPTP, SMT-LIB, SMTCoq, Lambdapi - (`src/rust/exchange/`). - -- **17 corpus adapters** — every major public proof corpus has a - structural ingest path. See - Corpus Coverage. - -- **Axiom-usage tracking** — four danger levels (Safe, Noted, Warning, - Reject) applied uniformly across every backend. - -# Overview - -ECHIDNA orchestrates theorem provers, SMT solvers, first-order ATPs, and -constraint solvers through a unified Rust core. Every proof result -passes through a trust-hardening pipeline that checks solver integrity, -tracks axiom usage, verifies proof certificates, and assigns a 5-level -confidence score. - -Neural premise selection (via Julia) suggests tactics; formal provers -always have the final word. ECHIDNA never reports a proof as verified -without the underlying backend agreeing. The neurosymbolic and -formal-verification layers are wired so the ML suggestion path can only -ever *accelerate* a proof attempt — never substitute for one. - -The Idris2 ABI layer (`src/abi/EchidnaABI/`) carries the type-level -specifications and totality proofs that pin the on-wire contracts -between the Rust dispatcher, the Julia GNN ranker, and the Chapel -parallel rank-merge — including the fixed-point `ConfidenceFP` encoding -with its round-trip and total-order properties (zero `believe_me`, zero -postulates, zero admits). - -# Features - -## Prover Backends - -The Tier-1 *core* set is what `GET` `/api/provers` exposes by default -and what is required to pass for green CI; the live membership list is -`ProverKind::all_core()` in `src/rust/provers/mod.rs`, mirrored in -human-readable form at -[`docs/SUPPORTED_PROVERS.md`](docs/SUPPORTED_PROVERS.md) (with required -external binaries and install hints). The remaining tiers (extended, -niche, Wave-3 secured, Wave-2 modal/real-algebraic, pure-Rust -in-process, HP type-checker ecosystem, TypeChecker disciplines, Coq-Jr -playground) cover interactive provers, first-order ATPs, SAT/SMT -solvers, auto-active verifiers, constraint/optimisation backends, model -checkers, C/hardware verifiers, security-protocol tools, and specialised -systems. The full tier table and membership list — the only place these -counts are maintained — is -[`docs/PROVER_COUNT.md`](docs/PROVER_COUNT.md). - -All backends in the Tier-1 / Tier-2 / Wave-3 / Wave-2 / pure-Rust groups -implement the `ProverBackend` trait (parse, verify, export, tactic -suggestion, theorem search). File-extension detection covers 30+ formats -(`.v`, `.lean`, `.smt2`, `.tptp`, `.dfy`, `.mzn`, …). - -## Trust & Safety Hardening - -The verification pipeline applies the following checks to every proof: - -- **Solver Binary Integrity** (`integrity/`): SHAKE3-512 provenance - hashing and BLAKE3 fast runtime re-verification. Solver binaries are - checked against a TOML manifest at startup; tampered binaries are - rejected. - - - -- **SMT Portfolio Solving** (`verification/portfolio.rs`): Cross-checks - proofs across multiple solvers (e.g. Z3 + CVC5 + Alt-Ergo). Flags - disagreements for human review. Supports SMT, ATP, and ITP solver - pools. - - - -- **Proof Certificate Checking** (`verification/certificates.rs`): - Verifies Alethe (CVC5), DRAT/LRAT (SAT solvers), TSTP (first-order - ATPs), Lean4 kernel, and Coq kernel certificate formats. Certificates - are hashed with BLAKE3 and stored for audit trails. - - - -- **Axiom Usage Tracking** (`verification/axiom_tracker.rs`): Scans - proof content for dangerous constructs across provers. Four danger - levels: - - - **Safe**: Standard library axioms - - - **Noted**: Classical axioms in constructive systems (e.g. `Axiom` in - Coq) - - - **Warning**: Incomplete proof markers (`sorry`, `Admitted`, - `postulate`) - - - **Reject**: Known unsound constructs (`--type-in-type`, `mk_thm`, - `believe_me`) Comments are not flagged. - - - -- **Solver Sandboxing** (`executor/sandbox.rs`): Runs solvers in - isolated environments. Three modes: Podman containers (preferred, - `--network=none`, read-only, memory/CPU/disk limits), bubblewrap - namespaces (fallback), or unsandboxed (development only, requires - explicit opt-in). Auto-detection selects the strongest available - option. - - - -- **5-Level Trust Hierarchy** (`verification/confidence.rs`): Every - proof result receives a trust level: - - - Level 1: Large-TCB system, unchecked, or dangerous axioms used - - - Level 2: Single prover, no dangerous axioms - - - Level 3: Single prover with verified proof certificate - - - Level 4: Small-kernel prover (Lean, Coq, Isabelle, Agda, Metamath, - HOL Light, HOL4, Idris2, F\*, Twelf, Nuprl, Minlog) with verified - certificate - - - Level 5: Cross-checked by 2+ independent small-kernel systems with - certificates - - - -- **Mutation Testing** (`verification/mutation.rs`): Deliberately - weakens specifications (remove preconditions, weaken postconditions, - negate subterms, replace constants) to verify the pipeline catches - them. Computes a mutation score with a default 95% threshold. - - - -- **Cross-Prover Proof Exchange** (`exchange/`): Export and import - proofs in six universal formats — OpenTheory (HOL family interop), - Dedukti and Lambdapi (lambda-Pi calculus modulo rewriting), TPTP - (`exchange/tptp.rs` — first-order ATP universal exchange), SMT-LIB v2 - (`exchange/smtlib.rs` — cross-solver normalisation), and SMTCoq - (`exchange/smtcoq.rs` — Alethe / LFSC / DRAT skeleton parser for Coq - kernel re-checking). See - Wire Schema for the - formal data contracts. - - - -- **Pareto Optimisation** (`verification/pareto.rs`): Multi-objective - ranking of proof candidates across four axes: proof time, trust level, - memory usage, and proof size. Computes the Pareto frontier and - optionally applies weighted scoring for single-best selection. - - - -- **Statistical Confidence Tracking** (`verification/statistics.rs`): - Per-prover, per-domain success rates and timing statistics. Bayesian - timeout estimation (mean + 2 sigma). Wilson score intervals for - mutation score confidence. Prover ranking by composite score (success - rate, timeout rate, speed). JSON serialisation for persistence. - - - -- **Dispatch Pipeline** (`dispatch.rs`): Orchestrates the full pipeline: - create prover → parse → verify → axiom scan → confidence scoring. - Supports single-prover and cross-checked (portfolio) modes with - configurable minimum trust levels. - -## Additional Capabilities - -- **Neurosymbolic ML** (Julia layer): Logistic-regression tactic - prediction; serves rankings via HTTP for the GNN-augmented dispatch - path. Output flows through the type-level `TacticSuggestion` / - `ConfidenceFP` ABI before any consumer touches it. - -- **Aspect Tagging**: Proof categorisation and domain analysis. - -- **Anomaly Detection**: ML-based overconfidence detection on dispatcher - outputs. - -- **Agentic Proof Search**: Actor-based autonomous proof exploration. - -- **Chapel Parallel Layer** (optional): Coforall-based parallel proof - dispatch, including a per-prover cwd/filename-override hook in - `tryProver` so each backend can be invoked with its required workspace - shape (Idris2 / Agda case studies in [`src/chapel/`](src/chapel/)). - -- **Three API surfaces**: - - - GraphQL (async-graphql, port 8081) - - - gRPC (tonic + Protocol Buffers, port 50051) - - - REST (axum + OpenAPI/Swagger, port 8000) - -- **AffineScript / AffineScript UI**: AffineScript components are being ported - to AffineScript-TEA as the stdlib primitives needed for the port (Http - / Promise / Json / Dict) land in - [affinescript](https://github.com/hyperpolymath/affinescript). - -- **REPL**: Interactive proof session via rustyline (`cargo` - `run — interactive`). - -# Quick Start - -## Prerequisites - -- **Rust** nightly (managed via asdf or rustup) - -- **Just** command runner (`cargo` `install` `just`) - -- **pkg-config** + **openssl-devel** / **libssl-dev** (system) - -- **Podman** (NOT Docker) — recommended for solver sandboxing - -Optional, by component: - -- **Julia** 1.10+ — ML layer (`src/julia/`) - -- **Idris2** \>= 0.7.0 — ABI type-check (`src/abi/`) - -- **Zig** \>= 0.13.0 — FFI bridge (`ffi/zig/`, `src/zig_ffi/`) - -- **Chapel** — optional parallel proof dispatch (`src/chapel/`, - `--features` `chapel`) - -- **Deno** \>= 2.0 — AffineScript / AffineScript UI (`src/affinescript/`, - `src/ui/`) - -Run `just` `doctor` to verify what’s actually installed; `just` `heal` -will offer to install missing pieces non-destructively. - -## Build and Test - -```bash -# Clone -git clone https://github.com/hyperpolymath/echidna.git -cd echidna - -# Build -just build -# or: cargo build - -# Run all tests -just test -# or: cargo test - -# Launch the interactive proof REPL -cargo run -- interactive -# or: just run interactive -``` - -## Prove your first goal - -```bash -# Install at least one solver — Z3 is the smallest dependency -sudo apt install z3 # Debian/Ubuntu (or `brew install z3`) - -# Start the REST API server with CORS enabled -cargo run --bin echidna -- server --cors - -# In another terminal, POST a satisfiable SMT-LIB goal -curl -X POST http://127.0.0.1:8081/api/prove \ - -H 'Content-Type: application/json' \ - -d '{"prover":"Z3", - "content":"(set-logic QF_LIA)\n(declare-const x Int)\n(assert (> x 0))\n(check-sat)\n", - "timeout":30}' -# → {"success":true,"goals":1,"message":"Proof verified successfully"} -``` - -For a minimal browser UI, open `src/ui/public/prove.html` directly in -any modern browser and point the "API base" field at the running server. -No build step is required. - -See [`docs/SUPPORTED_PROVERS.md`](docs/SUPPORTED_PROVERS.md) for the -Tier-1 core set, required binaries, and how to expose additional -backends through the API. - -## Using Podman Container - -```bash -podman build -f Containerfile -t echidna:latest . -podman run -it echidna:latest -``` - -# Architecture - -## Technology Stack - -- **Rust**: Core logic, prover backends, trust pipeline, CLI, REPL, API - servers - -- **Julia**: ML inference (tactic prediction, premise selection) - -- **AffineScript + Deno**: UI components - -- **Chapel**: Optional parallel proof dispatch - -## Key Modules - - src/rust/ - provers/ # Per-backend ProverBackend impls (see docs/PROVER_COUNT.md for the live tier table) - verification/ # Trust-hardening subsystem - portfolio.rs # SMT portfolio solving / cross-checking - certificates.rs # Proof certificate checking (Alethe, DRAT/LRAT, TSTP) - axiom_tracker.rs# Axiom usage scanning and policy enforcement - confidence.rs # 5-level trust hierarchy - mutation.rs # Mutation testing for specifications - pareto.rs # Pareto frontier candidate ranking - pareto_arbiter.rs # Pareto multi-objective arbiter (post-portfolio) - bayesian_arbiter.rs # Bayesian posterior arbiter - dempster_shafer.rs # Dempster-Shafer mass-function arbiter - statistics.rs # Per-prover statistical tracking - integrity/ # Solver binary integrity (SHAKE3-512, BLAKE3) - executor/ # Sandboxed solver execution (Podman, bubblewrap) - exchange/ # Cross-prover proof exchange (OpenTheory, Dedukti, TPTP, SMT-LIB, SMTCoq, Lambdapi — 6 formats) - dispatch.rs # Full trust-hardening dispatch pipeline - agent/ # Agentic proof search (actor model) - neural.rs # Neural premise selection integration - aspect.rs # Aspect tagging system - anomaly_detection.rs - proof_search.rs # Chapel parallel proof search - core.rs # Core types (Term, ProofState, Tactic, Goal, etc.) - parsers/ # Proof file parsers - ffi/ # Foreign function interface - server.rs # HTTP API server - repl.rs # Interactive REPL - main.rs # CLI entry point - lib.rs # Library root - corpus/ # 17 corpus adapters (see "Corpus Coverage" below) - -## Corpus Coverage - -Seventeen structural ingest adapters cover every major public proof -corpus reachable to date. Each lives under `src/rust/corpus/.rs` -and exposes a `pub` `fn` `ingest(root:` `&Path)` `→` `Result` -returning the canonical `Corpus` struct defined at -[`src/rust/corpus/mod.rs:156`](src/rust/corpus/mod.rs). Two-pass -extraction: pass 1 enumerates module + decl names; pass 2 scans decl -bodies and records references against the pass-1 name set -([`src/rust/corpus/mod.rs:25`](src/rust/corpus/mod.rs)). Hazards -(axioms, sorry, believe_me, cheat, …) populate `AxiomUsage` per entry. - -| Adapter | Source | Purpose | -|----|----|----| -| `agda` | `*.agda` | Agda stdlib + cubical (pre-2026-04) | -| `coq` | `*.v` | Coq / Rocq libraries (pre-2026-04) | -| `lean` | `*.lean` | Lean 4 + mathlib4 (pre-2026-04) | -| `idris2` | `*.idr` / `*.ipkg` | Idris 2 stdlib + base (pre-2026-04) | -| `isabelle` | `*.thy` | Isabelle/HOL + AFP entries | -| `metamath` | `*.mm` | set.mm and friends | -| `mizar` | `*.miz`, `*.abs` | Mizar Mathematical Library | -| `hol_light` | `*.ml` (HOL Light) | Multivariate / Core | -| `hol4` | `*Script.sml` | HOL4 theory scripts | -| `dafny` | `*.dfy` | Dafny verification suite | -| `why3` | `*.mlw`, `*.why` | Why3 TOCCATA gallery | -| `fstar` | `*.fst`, `*.fsti` | F\* examples + stdlib | -| `acl2_books` | `*.lisp`, `*.acl2` | ACL2 community books | -| `tptp` | `*.p`, `*.tptp` | TPTP problem library (CNF / FOF) | -| `smtlib` | `*.smt2`, `*.smt` | SMT-LIB v2 benchmarks | -| `proofnet` | `*.jsonl` | ProofNet NL→formal pairs | -| `minif2f` | `*.lean` / `*.thy` / `*.ml` / `*.mm` / `*.v` | MiniF2F olympiad multi-target | - -Full per-adapter source URLs, hazard flag inventory, fixture layout and -downstream wiring (`suggest` / `octad-emit` / GNN training) are in -[`docs/CORPUS-ADAPTERS.md`](docs/CORPUS-ADAPTERS.md). - -## Cross-prover Vocabulary - -Per-prover synonym tables (one TOML per backend, ~863 lines of seed -content as of 2026-06-01) sit under [`data/synonyms/`](data/synonyms/) -and drive the `echidna` `suggest` variant-tester -(`src/rust/suggest/synonyms.rs`). The schema (canonical + aliases + -tactic_class + version range) and contract are documented in -[`data/synonyms/README.adoc`](data/synonyms/README.adoc). - -Three cross-prover taxonomic dictionaries (underscore-prefixed, merged -via `SynonymTable::merge_external()`) layer a common mathematical -vocabulary over the per-prover tables: - -- `_msc2020.toml` — **87** MSC2020 codes for cross-domain classification - (e.g. `03B45` modal logic, `68V20` formalised mathematics). - -- `_wordnet_math.toml` — **~80** lemmas from the WordNet 3.1 math - sub-hierarchy for natural-language anchor terms. - -- `_conceptnet_seed.toml` — **~55** pre-fetched ConceptNet 5.7 edges for - offline-resilient `semantic_class` resolution. - -## Arbitration - -When multiple provers attack the same goal, four arbitration mechanisms -turn a multiset of outcomes into a decision: - -| Mechanism | Module | Behaviour | -|----|----|----| -| Portfolio majority-vote | [`verification/portfolio.rs`](src/rust/verification/portfolio.rs) | Simple agreement count across solvers; flags disagreements for human review. Original cross-checking surface. | -| Bayesian posterior | [`verification/bayesian_arbiter.rs`](src/rust/verification/bayesian_arbiter.rs) | Per-prover (precision, 1-FPR) likelihoods + log-odds accumulation; returns posterior `(p_proven,` `p_refuted,` `p_unknown)` with Shannon entropy. Numerically stable; Timeout/Unknown/Error contribute LR = 1. | -| Dempster-Shafer | [`verification/dempster_shafer.rs`](src/rust/verification/dempster_shafer.rs) | Mass-function combination with explicit ignorance; tracks the conflict scalar `K`. Refuses to combine when total conflict \> 0.95 (`ArbiterError::ExcessiveConflict`). | -| Pareto frontier | [`verification/pareto_arbiter.rs`](src/rust/verification/pareto_arbiter.rs) (multi-objective arbitration sibling to `verification/pareto.rs` — the candidate-ranking pre-arbiter) | Multi-objective dominance across time / trust / memory / proof-size; configurable `Tiebreak` policy chooses a single recommended pick from the frontier. | - -## Wire Schema - -The data contract between ECHIDNA and its long-term memory store -(VeriSimDB) is formalised: - -- [`docs/architecture/VERISIM-ER-SCHEMA.md`](docs/architecture/VERISIM-ER-SCHEMA.md) - — 12 first-class entities + 7 first-class relationships, each with its - Rust struct, VeriSimDB table, Cap’n Proto schema, and PK/FK set. - Replaces the aspirational text in the 2026-04-17 triangulation - document. - -- [`crates/echidna-wire/schemas/verisim_er.capnp`](crates/echidna-wire/schemas/verisim_er.capnp) - — Cap’n Proto wire schema (struct id `@0xe4dc7b1f01a06001`). - -Drift detection is by hash over both files; the per-PR `er-drift` CI -gate is tracked alongside the schema. - -## API Usage - -```rust -use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; - -// Create a prover backend -let backend = ProverFactory::create(ProverKind::Lean, ProverConfig::default())?; -let state = backend.parse_string("theorem foo : 1 + 1 = 2 := by omega").await?; -let verified = backend.verify_proof(&state).await?; -``` - -```rust -use echidna::dispatch::{ProverDispatcher, DispatchConfig}; -use echidna::provers::ProverKind; - -// Use the trust-hardening dispatch pipeline -let dispatcher = ProverDispatcher::with_config(DispatchConfig { - cross_check: true, - track_axioms: true, - ..Default::default() -}); - -// Cross-checked verification -let result = dispatcher.verify_proof_cross_checked( - ProverKind::Z3, - "(set-logic QF_LIA)\n(assert (> x 0))\n(check-sat)", - &[ProverKind::CVC5], -).await?; - -println!("Verified: {}, Trust: {}", result.verified, result.trust_level); -``` - -# Test Suite - -The test surface spans unit tests inside `src/rust/` and integration -suites under `tests/`, supplemented by property tests, criterion -benchmarks, and Idris2 ABI type-checks. Current counts are not embedded -here — `cargo` `test` `--lib`, `cargo` `test` `--tests`, and -[`CHANGELOG.md`](CHANGELOG.md) carry the live numbers. - -- Smoke E2E integration tests across the Tier-1 prover backends - -- Property-based tests (PropTest) - -- Criterion benchmarks across all critical paths - -- Idris2 ABI type-check (`idris2` `--build` `src/abi/echidnaabi.ipkg`) - enforces zero `believe_me` / `assert_total` / `postulate` in the ABI - modules. - -```bash -cargo test # All Rust tests -cargo test --lib # Unit tests only -cargo test --test integration_tests -idris2 --build src/abi/echidnaabi.ipkg # ABI type-check -``` - -# Development - -## Quality Checks - -```bash -just check # Roll-up: fmt-check + lint + test -just lint # REUSE, rustfmt, clippy -just audit # cargo-audit + supply-chain check -just pre-commit # fmt-check + lint + test (use in git hooks) -just assail # panic-attacker security scan (requires the panic-attack CLI) -just mvp # MVP smoke checks (reports missing provers, non-fatal) -just doctor # Verify required toolchain is on PATH -just heal # Offer to install missing tools -just tour # Guided walkthrough of the repo -``` - -`just` `--list` enumerates every recipe; `just` `help-me` prints an -onboarding subset. - -# Current Status - -The authoritative status surface — release history, what shipped in each -minor, what’s targeted next — is [`CHANGELOG.md`](CHANGELOG.md). For -roadmap items beyond the next release, see -[`docs/ROADMAP.md`](docs/ROADMAP.md). - -Headline shape (as of the most recent on-main work): - -- **Trust pipeline**: solver-integrity, certificate-checking, - axiom-tracking, sandboxing, mutation-testing, Pareto ranking, Bayesian - confidence — all wired into `dispatch.rs`. - -- **Idris2 ABI**: `EchidnaABI.TacticRecord` (fixed-point confidence, - total-order proofs, in-range round-trip lemmas), `Provers`, - `AxiomTracker`, `Gnn`, `CapnSchemas` — type-checked on every push. - -- **Chapel parallel layer**: per-prover cwd / filename hooks - (`tryProver`) and L2.3 cancel-token preemption. - -- **Wave-3 container infrastructure**: 8-cell weekly cron building each - Tier-3 prover image with stub-sentinel detection. - -- **Estate migrations in flight**: AffineScript→AffineScript UI; npm→Deno - for `echidna-playground`; CI workflow consolidation under the - governance ruleset. - -# Documentation - -- [Contributing Guidelines](CONTRIBUTING.md) - -- [Code of Conduct](CODE_OF_CONDUCT.md) - -- [Security Policy](SECURITY.md) - -- [Changelog](CHANGELOG.md) - -- [Roadmap](docs/ROADMAP.md) - -- [RSR / CCCP Compliance Statement](RSR_COMPLIANCE.adoc) - -- [EXPLAINME — receipts for the README claims](EXPLAINME.adoc) - -- [`docs/PROVER_COUNT.md`](docs/PROVER_COUNT.md) — canonical - prover-count and tier table - -- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — system overview - -- [`docs/CORPUS-ADAPTERS.md`](docs/CORPUS-ADAPTERS.md) — 17-adapter - corpus ingest index - -- [`docs/architecture/VERISIM-ER-SCHEMA.md`](docs/architecture/VERISIM-ER-SCHEMA.md) - — VeriSim ↔ ECHIDNA entity-relationship schema - -- [`docs/decisions/2026-06-01-saturation-campaign.md`](docs/decisions/2026-06-01-saturation-campaign.md) - — ADR for the saturation campaign (corpora / vocab / synonyms / - exchange / arbitration) - -- [`docs/handover/PROVER-CORPUS-SATURATION-LANE.md`](docs/handover/PROVER-CORPUS-SATURATION-LANE.md) - — saturation lane handover - -- [`docs/ENV-VARS.md`](docs/ENV-VARS.md) — environment variables - -- [`CLAUDE.md`](CLAUDE.md) — collaboration brief for Claude Code - -# Critical Constraints - -- **No Python** — Julia for ML, Rust for systems, AffineScript / - AffineScript for UI. (`salt/` is the only carve-out.) - -- **RSR / CCCP Compliance** — see - [`RSR_COMPLIANCE.adoc`](RSR_COMPLIANCE.adoc) for the full hard-rule - list and ECHIDNA’s out-of-template adaptations. - -- **Justfile primary** — Just is the build entry point; no Make. - -- **Podman not Docker** — always Podman; `Containerfile` - (`.containerization/` for the per-prover images) not `Dockerfile`. - -- **License**: AGPL-3.0-or-later. See LICENSE. - -# License - -This project is licensed under the [GNU Affero General Public License -v3.0 or later](LICENSE). Individual files may carry earlier MPL-2.0 -SPDX headers pending the header migration sweep. - -# Citation - -```bibtex -@software{echidna2026, - title = {ECHIDNA: Extensible Cognitive Hybrid Intelligence for Deductive Neural Assistance}, - author = {Jewell, Jonathan D.A.}, - year = {2026}, - url = {https://github.com/hyperpolymath/echidna}, - license = {AGPL-3.0-or-later} -} -``` - -# Contact - -- **GitHub Issues**: - -- **Pull Requests**: - ------------------------------------------------------------------------- - -**Author**: Jonathan D.A. Jewell -\<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\>\ -**Version and last-changed date**: tracked in -[`CHANGELOG.md`](CHANGELOG.md) and the git log; not duplicated here to -avoid drift. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 00000000..ad15836a --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,257 @@ +== Security Policy + +=== Supported Versions + +ECHIDNA is in active development. The current major version (`+2.x+`) on +`+main+` receives security updates; pre-`+1.0+` lineages are not +supported. The on-disk version lives in link:Cargo.toml[`+Cargo.toml+`] +and link:CHANGELOG.md[`+CHANGELOG.md+`]; this file deliberately does not +pin a version number to avoid drift. + +[cols=",",options="header",] +|=== +|Lineage |Supported +|2.x (`+main+`) |:white_check_mark: +|1.x |:white_check_mark: (security only) +|< 1.0 |:x: +|=== + +=== Security Principles + +ECHIDNA follows these security principles: + +[arabic] +. *Defense in Depth*: Multiple layers of security controls +. *Least Privilege*: Minimal necessary permissions +. *Secure by Default*: Safe default configurations +. *Fail Securely*: Graceful degradation on errors +. *Complete Mediation*: All access requests are checked +. *Transparency*: Open communication about security issues + +=== Reporting a Vulnerability + +We take the security of ECHIDNA seriously. If you believe you have found +a security vulnerability, please report it to us as described below. + +==== Where to Report + +*DO NOT* report security vulnerabilities through public GitHub issues, +GitLab issues, the issue tracker, or any other public channel. + +Preferred route — *GitHub Security Advisories* (private, encrypted, +auditable): + +* https://github.com/hyperpolymath/echidna/security/advisories/new + +Email fallback (use only if GitHub is unavailable to you): + +* j.d.a.jewell@open.ac.uk (maintainer; PGP key +`+4A03639C1EB1F86C7F0C97A91835A14A2867091E+` published on +https://keys.openpgp.org) + +==== What to Include + +Please include the following information in your report: + +* Type of vulnerability (e.g., buffer overflow, SQL injection, XSS, +etc.) +* Full paths of source file(s) related to the vulnerability +* Location of the affected source code (tag/branch/commit or direct URL) +* Any special configuration required to reproduce the issue +* Step-by-step instructions to reproduce the issue +* Proof-of-concept or exploit code (if possible) +* Impact of the issue, including how an attacker might exploit it + +==== Response Timeline + +* *Initial Response*: Within 48 hours of report +* *Status Update*: Within 7 days with initial assessment +* *Patch Development*: Timeline provided based on severity +* *Public Disclosure*: Coordinated with reporter after patch release + +==== Security Disclosure Process + +[arabic] +. *Report Received*: Security team acknowledges receipt +. *Assessment*: Team assesses severity and impact +. *Development*: Patch is developed and tested +. *Notification*: Security advisory prepared +. *Release*: Patch released with advisory +. *Recognition*: Reporter credited (if desired) + +=== Security Best Practices + +==== For Users + +[arabic] +. *Keep Updated*: Always use the latest stable version +. *Verify Downloads*: Check signatures and checksums +. *Review Configs*: Audit security-related configurations +. *Monitor Logs*: Watch for suspicious activity +. *Report Issues*: Report any security concerns promptly + +==== For Contributors + +[arabic] +. *Input Validation*: Always validate and sanitize inputs +. *Output Encoding*: Properly encode outputs to prevent injection +. *Authentication*: Use strong authentication mechanisms +. *Authorization*: Implement proper access controls +. *Cryptography*: Use well-tested cryptographic libraries +. *Dependencies*: Keep dependencies updated and audited +. *Secrets*: Never commit secrets or credentials +. *Code Review*: All code must be reviewed before merging + +=== Security Features + +==== Current Security Measures + +* *REUSE Compliance*: All code properly licensed and attributed +* *Trivy Scanning*: Automated vulnerability scanning via CI/CD +* *Aqua.jl*: Julia dependency security analysis +* *Cargo Audit*: Rust dependency vulnerability checking +* *Podman*: Container isolation with rootless mode support +* *SPDX Headers*: Clear license and copyright information + +==== Planned Security Enhancements + +* *Code Signing*: Digital signatures for releases +* *SBOM Generation*: Software Bill of Materials for dependencies +* *Fuzzing*: Automated fuzz testing for parsers +* *SAST/DAST*: Static and dynamic security analysis +* *Dependency Pinning*: Locked dependency versions +* *Security Hardening*: Container and binary hardening + +=== Vulnerability Severity + +We use the CVSS (Common Vulnerability Scoring System) v3.1 to assess +severity: + +[cols=",,",options="header",] +|=== +|Score |Severity |Response Time +|9.0-10.0 |Critical |24 hours +|7.0-8.9 |High |7 days +|4.0-6.9 |Medium |30 days +|0.1-3.9 |Low |90 days +|=== + +=== Security Updates + +Security updates are released as: + +* *Critical*: Immediate patch release +* *High*: Next patch release (within 7 days) +* *Medium*: Next minor release (within 30 days) +* *Low*: Next major/minor release (within 90 days) + +=== Security Advisories + +Security advisories are published at: + +* *GitHub Security Advisories*: +https://github.com/hyperpolymath/echidna/security/advisories +* *GitHub Releases* (security patches are tagged accordingly): +https://github.com/hyperpolymath/echidna/releases +* *GitHub Releases atom feed*: +https://github.com/hyperpolymath/echidna/releases.atom + +=== Scope + +==== In Scope + +The following are in scope for security reports: + +* *Core libraries*: Rust core, Julia ML layer, Idris2 ABI, Zig FFI +bridge, AffineScript / AffineScript UI components +* *Prover backends*: every `+ProverKind+` variant wired through the +dispatch pipeline — Tier-1 core through Tier-3 niche. The live +membership list is `+ProverKind::all()+` in `+src/rust/provers/mod.rs+`; +the human-readable mirror is +link:docs/PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`]. +* *Trust-hardening pipeline*: solver integrity, certificate checking, +axiom tracking, sandboxing, mutation testing, Pareto ranking, Bayesian +confidence — wired in `+src/rust/dispatch.rs+`. +* *Build system*: Justfile, CI/CD workflows under `+.github/workflows/+` +* *Containers*: `+Containerfile+`, +`+.containerization/Containerfile.wave3+`, Podman configurations +* *Dependencies*: third-party libraries and tools + +==== Out of Scope + +The following are typically not accepted: + +* Denial of Service (DoS) without proven impact +* Social engineering attacks +* Issues in third-party dependencies (report to upstream) +* Theoretical vulnerabilities without PoC +* Issues requiring physical access +* Issues in unsupported versions + +=== Threat Model + +==== Assets + +* *Source Code*: Intellectual property and implementation +* *User Data*: Proof scripts and theorem libraries +* *Credentials*: API keys and authentication tokens +* *Build Artifacts*: Compiled binaries and containers + +==== Threats + +* *Code Injection*: Malicious code execution via prover input +* *Data Exfiltration*: Unauthorized access to user proofs +* *Supply Chain*: Compromised dependencies +* *Container Escape*: Breaking out of Podman containers +* *Denial of Service*: Resource exhaustion attacks + +==== Mitigations + +* Input validation and sanitization +* Principle of least privilege +* Dependency security scanning +* Container security hardening +* Rate limiting and resource quotas + +=== Security Tooling + +==== Required Tools + +* *Trivy*: Container and filesystem vulnerability scanning +* *cargo-audit*: Rust dependency auditing +* *Aqua.jl*: Julia package security analysis +* *REUSE*: License compliance verification + +==== Recommended Tools + +* *cargo-clippy*: Rust linter with security checks +* *JET.jl*: Julia static analysis +* *Semgrep*: Pattern-based security scanning +* *Bandit*: Security linting (if Python used - should not be!) + +=== Contact + +For security-related questions or concerns: + +* *GitHub Security Advisories*: +https://github.com/hyperpolymath/echidna/security/advisories/new +* *Email*: j.d.a.jewell@open.ac.uk (maintainer) +* *PGP key*: `+4A03639C1EB1F86C7F0C97A91835A14A2867091E+` — fetch via +`+gpg --recv-keys 4A03639C1EB1F86C7F0C97A91835A14A2867091E+` or from +https://keys.openpgp.org/search?q=j.d.a.jewell@open.ac.uk +* *GitHub*: https://github.com/hyperpolymath[@hyperpolymath] + +=== Acknowledgments + +We thank the following researchers and security professionals for +responsibly disclosing vulnerabilities: + +* _No vulnerabilities reported yet_ + +''''' + +*Document lineage*: revisions tracked via `+git log SECURITY.md+`; +versioned alongside the project (see +link:CHANGELOG.md[`+CHANGELOG.md+`]). This file is intentionally +count-free and version-free in prose to avoid R5b drift against +link:Cargo.toml[`+Cargo.toml+`]. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 499ec56c..00000000 --- a/SECURITY.md +++ /dev/null @@ -1,253 +0,0 @@ - - -# Security Policy - -## Supported Versions - -ECHIDNA is in active development. The current major version (`2.x`) -on `main` receives security updates; pre-`1.0` lineages are not -supported. The on-disk version lives in -[`Cargo.toml`](Cargo.toml) and [`CHANGELOG.md`](CHANGELOG.md); this -file deliberately does not pin a version number to avoid drift. - -| Lineage | Supported | -| ------- | ------------------ | -| 2.x (`main`) | :white_check_mark: | -| 1.x | :white_check_mark: (security only) | -| < 1.0 | :x: | - -## Security Principles - -ECHIDNA follows these security principles: - -1. **Defense in Depth**: Multiple layers of security controls -2. **Least Privilege**: Minimal necessary permissions -3. **Secure by Default**: Safe default configurations -4. **Fail Securely**: Graceful degradation on errors -5. **Complete Mediation**: All access requests are checked -6. **Transparency**: Open communication about security issues - -## Reporting a Vulnerability - -We take the security of ECHIDNA seriously. If you believe you have found a security vulnerability, please report it to us as described below. - -### Where to Report - -**DO NOT** report security vulnerabilities through public GitHub -issues, GitLab issues, the issue tracker, or any other public -channel. - -Preferred route — **GitHub Security Advisories** (private, encrypted, -auditable): - -* https://github.com/hyperpolymath/echidna/security/advisories/new - -Email fallback (use only if GitHub is unavailable to you): - -* j.d.a.jewell@open.ac.uk (maintainer; PGP key - `4A03639C1EB1F86C7F0C97A91835A14A2867091E` published on - https://keys.openpgp.org) - -### What to Include - -Please include the following information in your report: - -- Type of vulnerability (e.g., buffer overflow, SQL injection, XSS, etc.) -- Full paths of source file(s) related to the vulnerability -- Location of the affected source code (tag/branch/commit or direct URL) -- Any special configuration required to reproduce the issue -- Step-by-step instructions to reproduce the issue -- Proof-of-concept or exploit code (if possible) -- Impact of the issue, including how an attacker might exploit it - -### Response Timeline - -- **Initial Response**: Within 48 hours of report -- **Status Update**: Within 7 days with initial assessment -- **Patch Development**: Timeline provided based on severity -- **Public Disclosure**: Coordinated with reporter after patch release - -### Security Disclosure Process - -1. **Report Received**: Security team acknowledges receipt -2. **Assessment**: Team assesses severity and impact -3. **Development**: Patch is developed and tested -4. **Notification**: Security advisory prepared -5. **Release**: Patch released with advisory -6. **Recognition**: Reporter credited (if desired) - -## Security Best Practices - -### For Users - -1. **Keep Updated**: Always use the latest stable version -2. **Verify Downloads**: Check signatures and checksums -3. **Review Configs**: Audit security-related configurations -4. **Monitor Logs**: Watch for suspicious activity -5. **Report Issues**: Report any security concerns promptly - -### For Contributors - -1. **Input Validation**: Always validate and sanitize inputs -2. **Output Encoding**: Properly encode outputs to prevent injection -3. **Authentication**: Use strong authentication mechanisms -4. **Authorization**: Implement proper access controls -5. **Cryptography**: Use well-tested cryptographic libraries -6. **Dependencies**: Keep dependencies updated and audited -7. **Secrets**: Never commit secrets or credentials -8. **Code Review**: All code must be reviewed before merging - -## Security Features - -### Current Security Measures - -- **REUSE Compliance**: All code properly licensed and attributed -- **Trivy Scanning**: Automated vulnerability scanning via CI/CD -- **Aqua.jl**: Julia dependency security analysis -- **Cargo Audit**: Rust dependency vulnerability checking -- **Podman**: Container isolation with rootless mode support -- **SPDX Headers**: Clear license and copyright information - -### Planned Security Enhancements - -- **Code Signing**: Digital signatures for releases -- **SBOM Generation**: Software Bill of Materials for dependencies -- **Fuzzing**: Automated fuzz testing for parsers -- **SAST/DAST**: Static and dynamic security analysis -- **Dependency Pinning**: Locked dependency versions -- **Security Hardening**: Container and binary hardening - -## Vulnerability Severity - -We use the CVSS (Common Vulnerability Scoring System) v3.1 to assess severity: - -| Score | Severity | Response Time | -|-------|----------|---------------| -| 9.0-10.0 | Critical | 24 hours | -| 7.0-8.9 | High | 7 days | -| 4.0-6.9 | Medium | 30 days | -| 0.1-3.9 | Low | 90 days | - -## Security Updates - -Security updates are released as: - -- **Critical**: Immediate patch release -- **High**: Next patch release (within 7 days) -- **Medium**: Next minor release (within 30 days) -- **Low**: Next major/minor release (within 90 days) - -## Security Advisories - -Security advisories are published at: - -- **GitHub Security Advisories**: - https://github.com/hyperpolymath/echidna/security/advisories -- **GitHub Releases** (security patches are tagged accordingly): - https://github.com/hyperpolymath/echidna/releases -- **GitHub Releases atom feed**: - - -## Scope - -### In Scope - -The following are in scope for security reports: - -- **Core libraries**: Rust core, Julia ML layer, Idris2 ABI, - Zig FFI bridge, AffineScript / AffineScript UI components -- **Prover backends**: every `ProverKind` variant wired through the - dispatch pipeline — Tier-1 core through Tier-3 niche. The live - membership list is `ProverKind::all()` in - `src/rust/provers/mod.rs`; the human-readable mirror is - [`docs/PROVER_COUNT.md`](docs/PROVER_COUNT.md). -- **Trust-hardening pipeline**: solver integrity, certificate - checking, axiom tracking, sandboxing, mutation testing, Pareto - ranking, Bayesian confidence — wired in - `src/rust/dispatch.rs`. -- **Build system**: Justfile, CI/CD workflows under - `.github/workflows/` -- **Containers**: `Containerfile`, `.containerization/Containerfile.wave3`, - Podman configurations -- **Dependencies**: third-party libraries and tools - -### Out of Scope - -The following are typically not accepted: - -- Denial of Service (DoS) without proven impact -- Social engineering attacks -- Issues in third-party dependencies (report to upstream) -- Theoretical vulnerabilities without PoC -- Issues requiring physical access -- Issues in unsupported versions - -## Threat Model - -### Assets - -- **Source Code**: Intellectual property and implementation -- **User Data**: Proof scripts and theorem libraries -- **Credentials**: API keys and authentication tokens -- **Build Artifacts**: Compiled binaries and containers - -### Threats - -- **Code Injection**: Malicious code execution via prover input -- **Data Exfiltration**: Unauthorized access to user proofs -- **Supply Chain**: Compromised dependencies -- **Container Escape**: Breaking out of Podman containers -- **Denial of Service**: Resource exhaustion attacks - -### Mitigations - -- Input validation and sanitization -- Principle of least privilege -- Dependency security scanning -- Container security hardening -- Rate limiting and resource quotas - -## Security Tooling - -### Required Tools - -- **Trivy**: Container and filesystem vulnerability scanning -- **cargo-audit**: Rust dependency auditing -- **Aqua.jl**: Julia package security analysis -- **REUSE**: License compliance verification - -### Recommended Tools - -- **cargo-clippy**: Rust linter with security checks -- **JET.jl**: Julia static analysis -- **Semgrep**: Pattern-based security scanning -- **Bandit**: Security linting (if Python used - should not be!) - -## Contact - -For security-related questions or concerns: - -- **GitHub Security Advisories**: - https://github.com/hyperpolymath/echidna/security/advisories/new -- **Email**: j.d.a.jewell@open.ac.uk (maintainer) -- **PGP key**: `4A03639C1EB1F86C7F0C97A91835A14A2867091E` - — fetch via `gpg --recv-keys 4A03639C1EB1F86C7F0C97A91835A14A2867091E` - or from -- **GitHub**: [@hyperpolymath](https://github.com/hyperpolymath) - -## Acknowledgments - -We thank the following researchers and security professionals for responsibly disclosing vulnerabilities: - -- *No vulnerabilities reported yet* - ---- - -**Document lineage**: revisions tracked via `git log SECURITY.md`; -versioned alongside the project (see [`CHANGELOG.md`](CHANGELOG.md)). -This file is intentionally count-free and version-free in prose to -avoid R5b drift against [`Cargo.toml`](Cargo.toml). diff --git a/TEST_CI_ECHIDNA.adoc b/TEST_CI_ECHIDNA.adoc new file mode 100644 index 00000000..d22099e9 --- /dev/null +++ b/TEST_CI_ECHIDNA.adoc @@ -0,0 +1,10 @@ +== CI Test for ECHIDNA + +// SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-License-Identifier: +CC-BY-SA-4.0 + +This is a test file to trigger CI workflows for echidna. + +* Testing: codeql, hypatia-scan, governance workflows +* Created: 2026-06-04 +* Purpose: Verify CI fixes are working correctly diff --git a/TEST_CI_ECHIDNA.md b/TEST_CI_ECHIDNA.md deleted file mode 100644 index 19cc96a3..00000000 --- a/TEST_CI_ECHIDNA.md +++ /dev/null @@ -1,10 +0,0 @@ -# CI Test for ECHIDNA - -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-License-Identifier: CC-BY-SA-4.0 - -This is a test file to trigger CI workflows for echidna. - -- Testing: codeql, hypatia-scan, governance workflows -- Created: 2026-06-04 -- Purpose: Verify CI fixes are working correctly diff --git a/audits/audit-ffi-boundary.adoc b/audits/audit-ffi-boundary.adoc new file mode 100644 index 00000000..caa83989 --- /dev/null +++ b/audits/audit-ffi-boundary.adoc @@ -0,0 +1,328 @@ +== FFI Boundary Audit + +*Auditor*: Jonathan D.A. Jewell + +*Date*: 2026-04-26 + +*Scope*: all `+unsafe+` blocks in the echidna Zig/SPARK/Chapel FFI +boundary + +''''' + +=== §1 — `+src/rust/ffi/mod.rs+` (UnsafeCode, ResourceLeak) + +The ffi/mod.rs module exports 24 documented `+unsafe+` blocks for the +Zig FFI layer. Each unsafe block has an inline `+// SAFETY:+` comment. +The patterns: + +* *C-ABI exports* (`+pub unsafe extern "C" fn …+`) — required by Zig and +any C consumer to call Rust across the ABI boundary. +* *Raw pointer → Rust reference* (`+CStr::from_ptr+`, +`+slice::from_raw_parts+`) — caller contract: non-null, +correctly-aligned, valid-lifetime pointer supplied by the Zig shim +(enforced by the Zig wrapper in `+src/zig_ffi/+`). +* *ResourceLeak*: The one finding is a raw pointer returned from +`+Box::into_raw+`; the callee (Zig side) owns the allocation and calls +`+rust_free_*+` to drop it. This is the standard Rust→C +ownership-transfer pattern, not an actual leak. + +*Classification*: legitimate FFI. No remediation required. + +''''' + +=== §2 — `+src/rust/ffi/spark_axiom.rs+` (UnsafeCode) + +Two `+extern "C"+` callouts to SPARK-compiled policy enforcement +routines (`+echidna_spark_enforce_policy+`, +`+echidna_spark_worst_danger+`, `+echidna_spark_max_usages+`). The +module docstring confirms: + +* Never passes null — `+slice.as_ptr()+` on a non-empty slice is always +non-null. +* Length is bounded by `+wire.len()+` which comes from a bounded Vec. +* SPARK-side preconditions checked with Ada contracts. + +*Classification*: legitimate FFI (Rust→SPARK via C ABI). No remediation +required. + +''''' + +=== §3 — `+src/rust/proof_search.rs+` (UnsafeCode, feature-gated Chapel) + +Seven unsafe blocks, ALL behind `+#[cfg(feature = "chapel")]+`. +Patterns: + +* `+CString::new(goal).context(…)+` — only unsafe via the `+extern "C"+` +call site. +* `+CStr::from_ptr+` on Chapel-returned strings — caller contract: +Chapel runtime guarantees null-terminated string lifetime until next +Chapel call. +* `+extern "C"+` callouts to the Chapel parallel search runtime. + +If `+chapel+` feature is not enabled, no unsafe code compiles in. + +*Classification*: legitimate FFI (Rust→Chapel via Zig shim, +feature-gated). No remediation required. + +''''' + +=== §4 — `+src/interfaces/*/ffi_wrapper.rs+` (UnsafeCode × 6) + +The three interface crates (graphql, grpc, rest) each contain an +`+ffi_wrapper.rs+` that calls into the core Rust FFI layer via +`+CStr+`/`+CString+` and raw pointer manipulation. All six findings are +structurally identical to §1 — they are wrappers that adapt the C-ABI +output of `+src/rust/ffi/mod.rs+` to Rust-safe types for the interface +handlers. + +*Classification*: legitimate FFI (interface-layer wrappers over §1 +boundary). No remediation required. + +''''' + +=== §5 — `+src/rust/provers/z3.rs+` (UnsafeCode, PanicPath) + +No actual `+unsafe+` blocks present. panic-attack reports: - +*unwrap_calls*: 18 × `+unwrap_or_else()+` in parser recovery (lines 119, +125, 215) — normal S-expression parser fallback patterns - +*allocations*: 54 units for proof state and SMT-LIB parsing buffers + +The parser `+.expect(token)+` method calls (lines 727+) are parser +combinators that return `+Result+`, not panic sites. Error propagation +via `+?+` operator. + +*Classification*: legitimate SMT solver backend implementation. No +remediation required. + +''''' + +=== §6 — `+src/rust/provers/pvs.rs+` (UnsafeCode) + +Large PVS (Prototype Verification System) backend: 3168 LoC, 105 +variants for PVSExpr, PVSType, and proof state handling. No `+unsafe+` +blocks present. + +panic-attack reports: - *allocations*: 204 units for recursive AST +construction (record expressions, lambda bindings, quantifiers, case +selections — see lines 46-100). - *file_size*: 5 units (normal for a +full prover backend). + +The large allocations are expected: PVS is a rich type system with +dependent types, predicate subtypes, and complex pattern matching. + +*Classification*: legitimate proof assistant backend. No remediation +required. + +''''' + +=== §7 — `+src/rust/provers/hol4.rs+` (UnsafeCode, PanicPath) + +Large HOL4 (Higher-Order Logic) backend: 2621 LoC, with tactic +evaluation, type parser, and bidirectional proof state conversion. No +`+unsafe+` blocks. + +panic-attack reports: - *panic_sites*: 1 from process spawn error (line +1430 `+.spawn()+`), reported but error is caught and propagated via +`+?+` operator. - *allocations*: 174 units for HOL4 tactic vectors +(`+Metis(vec![])+`, `+Simp(vec![])+`) and bidirectional term conversion +(lines 1644-1738). + +All struct-to-vec conversions return `+Result+`, no panic on unwrap. + +*Classification*: legitimate proof assistant backend. No remediation +required. + +''''' + +=== §8 — `+src/rust/provers/mod.rs+` (UnsafeCode) + +Central prover module: 105 prover backends, module declarations (lines +22-94), ProverKind enum (96+ variants), and ProverFactory dispatch +logic. No `+unsafe+` blocks. + +panic-attack reports: - *allocations*: 148 units from enum variants and +module exports. - *file_size*: 3 units (normal for a registry file). + +This is structural overhead from the 105-prover architecture, not FFI or +memory mismanagement. + +*Classification*: legitimate backend registry. No remediation required. + +''''' + +=== §9 — `+src/rust/coprocessor/flint.rs+` (UnsafeCode × 17) — FLINT C bigint bindings + +*Added*: 2026-06-01 (post-#104 panic-attack re-sweep, issue #177) + +FLINT (Fast Library for Number Theory, LGPL-3) is the only CAS backend +in ECHIDNA that links the library in-process rather than shelling out +(earning `+CoprocessorTrustTier::LibraryWrapped+`, Tier 3). +Feature-gated via `+--features flint+`; without it the module compiles +out entirely and +`+CoprocessorFactory::native(CoprocessorKind::FlintMath)+` returns +`+None+`. + +The 17 `+unsafe+` blocks (lines 145, 158, 168, 172, 173, 180, 199, 204, +214, 233, 251, 327, 335, 349, 356, 366, 376) fall into four well-bounded +patterns: + +* *`+fmpz_init+` / `+fmpz_clear+` / `+fmpz_poly_init+` / +`+fmpz_poly_clear+`*: RAII bookkeeping — each `+Fmpz+` / `+FmpzPoly+` +Rust wrapper owns exactly one FLINT object; `+Drop+` runs `+fmpz_clear+` +/ `+fmpz_poly_clear+` exactly once. Pointers passed are always +`+&mut self.inner+`, never null, never aliased (Rust’s borrow checker +prevents the latter). +* *`+fmpz_set_str+` / `+fmpz_get_str+`*: string round-trip through +CString / CStr. Inputs are validated CStrings (no interior nul); outputs +are immediately copied into owned `+String+` and the FLINT-allocated +buffer is released via `+flint_free+` (line 173) — no leak, no +use-after-free. +* *`+fmpz_poly_*+` arithmetic* (`+gcd+`, `+mul+`, `+pseudo_rem+`, +`+content+`, `+set_coeff_fmpz+`, `+get_coeff_fmpz+`, `+length+`): all +called on `+&mut+` pointers to RAII-owned `+FmpzPolyStruct+` instances +created on the same blocking thread, used, and dropped before the thread +returns. +* *`+fmpz_root+` / `+fmpz_bin_uiui+`*: integer k-th root and binomial. +Input bounds (`+n+`, `+k+` as `+u64+`) are validated by callers before +the FFI call; FLINT itself returns 0/1 status to indicate +exact-vs-approximate result (line 366: `+exact = fmpz_root(...)+`). + +*Thread safety*: FLINT is thread-safe from version 2.4 onwards provided +each thread owns its `+fmpz+` / `+fmpz_poly+` instances exclusively. All +FLINT objects in this module are created on the blocking thread, used, +and dropped before the thread returns — no sharing occurs (module +docstring lines 38-43). + +*Type-layout invariants*: `+FmpzPolyStruct+` (`+#[repr(C)]+`, lines +75-80) is a faithful mirror of FLINT’s `+fmpz_poly_struct+` on 64-bit +Linux (3 pointer- sized fields, 24 bytes). We never read or write the +fields directly — all access goes through FLINT functions (lines 73-74 +docstring). + +*Classification*: legitimate FFI (Rust→FLINT C library via in-process +linkage, feature-gated). No remediation required. + +''''' + +=== §10 — Zig FFI bridges (`+src/zig/ffi/axiom_spark_bridge.zig+`, `+src/zig_ffi/chapel_bridge.zig+`) — UnsafeFFI × 2 + +*Added*: 2026-06-01 (post-#104 panic-attack re-sweep, issue #177) + +Two Zig modules that bridge between two non-Rust backends (SPARK/Ada and +Chapel) and the Rust FFI surface. Each contains exactly one `+@cImport+` +directive — the only construct panic-attack flags as `+UnsafeFFI+` for +Zig. + +==== §10.1 — `+src/zig/ffi/axiom_spark_bridge.zig+` + +Zig C-ABI shim over the SPARK axiom-policy layer, sitting between the +Ada/SPARK static library (`+libechidna_spark.a+`) and the Rust FFI +surface defined in `+src/rust/ffi/spark_axiom.rs+` (already audited in +§2). + +.... +SPARK/Ada (axiom_policy.ads/.adb) + → C exports (axiom_c_bridge.ads/.adb: echidna_spark_enforce_policy_inner) + → this Zig shim (input validation + C-ABI re-export) + → Rust extern "C" (src/rust/ffi/spark_axiom.rs) +.... + +The `+@cImport({})+` (line 20) is intentionally empty — the shim’s job +is to re-export the SPARK symbols with predictable C ABI (no name +mangling, predictable layout) and provide a compile-time +`+MAX_USAGES = 1024+` size assertion that Rust’s `+bindgen+` cannot see +across the Ada boundary (module header, lines 4-17). + +Safety invariants: - `+danger_levels: [*]const u8+` + `+count: usize+` +is the standard pointer+length C slice; validated non-empty before +crossing the Rust boundary in `+spark_axiom.rs+` (see §2). - Output +`+policy_out+` / `+status_out+` are `+*i32+` to caller-allocated +storage; the Ada side guarantees they are always written before the call +returns (SPARK contract). + +==== §10.2 — `+src/zig_ffi/chapel_bridge.zig+` + +Type-safe Zig bridge between Chapel’s parallel-search runtime and the +Rust FFI surface, gated by the `+chapel+` Cargo feature (see §3). + +.... +Chapel (C API: chapel_ffi_exports.h) + → Zig (@cImport, this module) + → Rust (safe calls via src/rust/proof_search.rs) +.... + +The `+@cImport({ @cInclude("chapel_ffi_exports.h"); })+` (lines 18-20) +pulls in the Chapel-exported C declarations for 30 prover backends. The +Zig wrappers (`+ProverKind+`, `+ProverCategory+`, `+ProofResult+`) +translate Chapel’s C types into Zig-safe enums and structs, owning all +string copies (`+fromChapel+` at line 143 takes `+std.mem.Allocator+` +and copies before returning). + +Safety invariants: - Enum-from-int boundaries are bounds-checked (line +156: +`+c_result.prover_id >= 0 and c_result.prover_id < @as(c_int, ProverKind.count)+` +before `+@enumFromInt+`). - All string references returned from Chapel +are copied into Zig-owned storage before the Chapel call returns (per +module header line 7). - Chapel runtime guarantees null-terminated +string lifetime until next Chapel call (see §3 for the corresponding +Rust-side contract). + +*Classification (both files)*: legitimate FFI (Zig bridge layer between +Ada/SPARK & Chapel backends and Rust core; both feature-gated). No +remediation required. + +''''' + +=== §11 — `+ffi/zig/src/*+` overlay layer (UnsafeCode × 3) — pointer casts on static error buffers + +*Added*: 2026-06-01 (post-#104 panic-attack re-sweep, issue #177) + +Three Zig modules in the `+ffi/zig/src/+` overlay (the Idris2-ABI → +Zig-FFI → C-ABI surface for BoJ cartridges, the overlay subsystem, and +the TypeLL type-language) each contain exactly one `+@ptrCast+` flagged +by panic-attack as `+UnsafeCode+`. + +[width="100%",cols="40%,8%,52%",options="header",] +|=== +|File |Line |Function +|`+ffi/zig/src/boj.zig+` |456 |`+echidna_boj_last_error+` +|`+ffi/zig/src/overlay.zig+` |684 |`+echidna_overlay_last_error+` +|`+ffi/zig/src/typell.zig+` |333 |`+echidna_typell_last_error+` +|=== + +All three are the *identical pattern*: a `+last_error+` getter that +returns a C-ABI null-terminated string pointer to a module-private +static error buffer: + +[source,zig] +---- +pub export fn echidna__last_error() ?[*:0]const u8 { + if (error_len == 0) return null; + return @ptrCast(&error_buf); +} +---- + +Where `+error_buf: [ERROR_BUF_SIZE]u8+` (typically 512 bytes) is a +module-private static array and `+error_len: usize+` is its current +fill-length. + +Safety invariants: - `+error_buf+` is module-static — its address is +fixed at program load and never freed; the returned pointer is always +valid for the program lifetime. - The cast is from `+*[N]u8+` (array +reference) to `+[*:0]const u8+` (sentinel-terminated many-item pointer); +the buffer is guaranteed to contain a trailing nul because all writers +(`+setError+` helpers in each module) explicitly write a nul terminator +before incrementing `+error_len+`. - Return type is `+?[*:0]const u8+` +(optional); a null-fast-path (`+if (error_len == 0) return null;+`) +guards against returning a pointer to an empty buffer, so consumers can +distinguish "`no error`" from "`empty-string error`". - Read-only on the +Rust/Idris2 side — the pointer is `+const+`; callers must not write +through it. + +*Concurrency note*: the static error buffer is not thread-safe; each +subsystem’s contract is that errors are read on the same thread that +triggered them (consistent with the "`BoJ client`" / "`overlay`" / +"`TypeLL`" single-threaded request-response model). Multi-threaded +callers must serialise error retrieval externally. + +*Classification*: legitimate FFI (idiomatic C-style `+last_error+` +getters for three FFI subsystems sharing a common pattern). No +remediation required. diff --git a/audits/audit-ffi-boundary.md b/audits/audit-ffi-boundary.md deleted file mode 100644 index 0bd637cf..00000000 --- a/audits/audit-ffi-boundary.md +++ /dev/null @@ -1,304 +0,0 @@ - - -# FFI Boundary Audit - -**Auditor**: Jonathan D.A. Jewell -**Date**: 2026-04-26 -**Scope**: all `unsafe` blocks in the echidna Zig/SPARK/Chapel FFI boundary - ---- - -## §1 — `src/rust/ffi/mod.rs` (UnsafeCode, ResourceLeak) - -The ffi/mod.rs module exports 24 documented `unsafe` blocks for the Zig FFI -layer. Each unsafe block has an inline `// SAFETY:` comment. The patterns: - -- **C-ABI exports** (`pub unsafe extern "C" fn …`) — required by Zig and - any C consumer to call Rust across the ABI boundary. -- **Raw pointer → Rust reference** (`CStr::from_ptr`, `slice::from_raw_parts`) - — caller contract: non-null, correctly-aligned, valid-lifetime pointer - supplied by the Zig shim (enforced by the Zig wrapper in `src/zig_ffi/`). -- **ResourceLeak**: The one finding is a raw pointer returned from - `Box::into_raw`; the callee (Zig side) owns the allocation and calls - `rust_free_*` to drop it. This is the standard Rust→C ownership-transfer - pattern, not an actual leak. - -**Classification**: legitimate FFI. No remediation required. - ---- - -## §2 — `src/rust/ffi/spark_axiom.rs` (UnsafeCode) - -Two `extern "C"` callouts to SPARK-compiled policy enforcement routines -(`echidna_spark_enforce_policy`, `echidna_spark_worst_danger`, -`echidna_spark_max_usages`). The module docstring confirms: - -- Never passes null — `slice.as_ptr()` on a non-empty slice is always non-null. -- Length is bounded by `wire.len()` which comes from a bounded Vec. -- SPARK-side preconditions checked with Ada contracts. - -**Classification**: legitimate FFI (Rust→SPARK via C ABI). No remediation required. - ---- - -## §3 — `src/rust/proof_search.rs` (UnsafeCode, feature-gated Chapel) - -Seven unsafe blocks, ALL behind `#[cfg(feature = "chapel")]`. Patterns: - -- `CString::new(goal).context(…)` — only unsafe via the `extern "C"` call site. -- `CStr::from_ptr` on Chapel-returned strings — caller contract: Chapel runtime - guarantees null-terminated string lifetime until next Chapel call. -- `extern "C"` callouts to the Chapel parallel search runtime. - -If `chapel` feature is not enabled, no unsafe code compiles in. - -**Classification**: legitimate FFI (Rust→Chapel via Zig shim, feature-gated). No remediation required. - ---- - -## §4 — `src/interfaces/*/ffi_wrapper.rs` (UnsafeCode × 6) - -The three interface crates (graphql, grpc, rest) each contain an `ffi_wrapper.rs` -that calls into the core Rust FFI layer via `CStr`/`CString` and raw pointer -manipulation. All six findings are structurally identical to §1 — they are -wrappers that adapt the C-ABI output of `src/rust/ffi/mod.rs` to Rust-safe -types for the interface handlers. - -**Classification**: legitimate FFI (interface-layer wrappers over §1 boundary). No remediation required. - ---- - -## §5 — `src/rust/provers/z3.rs` (UnsafeCode, PanicPath) - -No actual `unsafe` blocks present. panic-attack reports: -- **unwrap_calls**: 18 × `unwrap_or_else()` in parser recovery (lines 119, 125, 215) — normal S-expression parser fallback patterns -- **allocations**: 54 units for proof state and SMT-LIB parsing buffers - -The parser `.expect(token)` method calls (lines 727+) are parser combinators -that return `Result`, not panic sites. Error propagation via `?` operator. - -**Classification**: legitimate SMT solver backend implementation. No remediation required. - ---- - -## §6 — `src/rust/provers/pvs.rs` (UnsafeCode) - -Large PVS (Prototype Verification System) backend: 3168 LoC, 105 variants for -PVSExpr, PVSType, and proof state handling. No `unsafe` blocks present. - -panic-attack reports: -- **allocations**: 204 units for recursive AST construction (record expressions, - lambda bindings, quantifiers, case selections — see lines 46-100). -- **file_size**: 5 units (normal for a full prover backend). - -The large allocations are expected: PVS is a rich type system with dependent -types, predicate subtypes, and complex pattern matching. - -**Classification**: legitimate proof assistant backend. No remediation required. - ---- - -## §7 — `src/rust/provers/hol4.rs` (UnsafeCode, PanicPath) - -Large HOL4 (Higher-Order Logic) backend: 2621 LoC, with tactic evaluation, -type parser, and bidirectional proof state conversion. No `unsafe` blocks. - -panic-attack reports: -- **panic_sites**: 1 from process spawn error (line 1430 `.spawn()`), reported but - error is caught and propagated via `?` operator. -- **allocations**: 174 units for HOL4 tactic vectors (`Metis(vec![])`, - `Simp(vec![])`) and bidirectional term conversion (lines 1644-1738). - -All struct-to-vec conversions return `Result`, no panic on unwrap. - -**Classification**: legitimate proof assistant backend. No remediation required. - ---- - -## §8 — `src/rust/provers/mod.rs` (UnsafeCode) - -Central prover module: 105 prover backends, module declarations (lines 22-94), -ProverKind enum (96+ variants), and ProverFactory dispatch logic. No `unsafe` blocks. - -panic-attack reports: -- **allocations**: 148 units from enum variants and module exports. -- **file_size**: 3 units (normal for a registry file). - -This is structural overhead from the 105-prover architecture, not FFI or -memory mismanagement. - -**Classification**: legitimate backend registry. No remediation required. - ---- - -## §9 — `src/rust/coprocessor/flint.rs` (UnsafeCode × 17) — FLINT C bigint bindings - -**Added**: 2026-06-01 (post-#104 panic-attack re-sweep, issue #177) - -FLINT (Fast Library for Number Theory, LGPL-3) is the only CAS backend in -ECHIDNA that links the library in-process rather than shelling out (earning -`CoprocessorTrustTier::LibraryWrapped`, Tier 3). Feature-gated via -`--features flint`; without it the module compiles out entirely and -`CoprocessorFactory::native(CoprocessorKind::FlintMath)` returns `None`. - -The 17 `unsafe` blocks (lines 145, 158, 168, 172, 173, 180, 199, 204, 214, -233, 251, 327, 335, 349, 356, 366, 376) fall into four well-bounded patterns: - -- **`fmpz_init` / `fmpz_clear` / `fmpz_poly_init` / `fmpz_poly_clear`**: - RAII bookkeeping — each `Fmpz` / `FmpzPoly` Rust wrapper owns exactly one - FLINT object; `Drop` runs `fmpz_clear` / `fmpz_poly_clear` exactly once. - Pointers passed are always `&mut self.inner`, never null, never aliased - (Rust's borrow checker prevents the latter). -- **`fmpz_set_str` / `fmpz_get_str`**: string round-trip through CString / - CStr. Inputs are validated CStrings (no interior nul); outputs are - immediately copied into owned `String` and the FLINT-allocated buffer is - released via `flint_free` (line 173) — no leak, no use-after-free. -- **`fmpz_poly_*` arithmetic** (`gcd`, `mul`, `pseudo_rem`, `content`, - `set_coeff_fmpz`, `get_coeff_fmpz`, `length`): all called on `&mut` - pointers to RAII-owned `FmpzPolyStruct` instances created on the same - blocking thread, used, and dropped before the thread returns. -- **`fmpz_root` / `fmpz_bin_uiui`**: integer k-th root and binomial. - Input bounds (`n`, `k` as `u64`) are validated by callers before the - FFI call; FLINT itself returns 0/1 status to indicate exact-vs-approximate - result (line 366: `exact = fmpz_root(...)`). - -**Thread safety**: FLINT is thread-safe from version 2.4 onwards provided -each thread owns its `fmpz` / `fmpz_poly` instances exclusively. All FLINT -objects in this module are created on the blocking thread, used, and dropped -before the thread returns — no sharing occurs (module docstring lines 38-43). - -**Type-layout invariants**: `FmpzPolyStruct` (`#[repr(C)]`, lines 75-80) is -a faithful mirror of FLINT's `fmpz_poly_struct` on 64-bit Linux (3 pointer- -sized fields, 24 bytes). We never read or write the fields directly — all -access goes through FLINT functions (lines 73-74 docstring). - -**Classification**: legitimate FFI (Rust→FLINT C library via in-process -linkage, feature-gated). No remediation required. - ---- - -## §10 — Zig FFI bridges (`src/zig/ffi/axiom_spark_bridge.zig`, `src/zig_ffi/chapel_bridge.zig`) — UnsafeFFI × 2 - -**Added**: 2026-06-01 (post-#104 panic-attack re-sweep, issue #177) - -Two Zig modules that bridge between two non-Rust backends (SPARK/Ada and -Chapel) and the Rust FFI surface. Each contains exactly one `@cImport` -directive — the only construct panic-attack flags as `UnsafeFFI` for Zig. - -### §10.1 — `src/zig/ffi/axiom_spark_bridge.zig` - -Zig C-ABI shim over the SPARK axiom-policy layer, sitting between the -Ada/SPARK static library (`libechidna_spark.a`) and the Rust FFI surface -defined in `src/rust/ffi/spark_axiom.rs` (already audited in §2). - -``` -SPARK/Ada (axiom_policy.ads/.adb) - → C exports (axiom_c_bridge.ads/.adb: echidna_spark_enforce_policy_inner) - → this Zig shim (input validation + C-ABI re-export) - → Rust extern "C" (src/rust/ffi/spark_axiom.rs) -``` - -The `@cImport({})` (line 20) is intentionally empty — the shim's job is to -re-export the SPARK symbols with predictable C ABI (no name mangling, -predictable layout) and provide a compile-time `MAX_USAGES = 1024` size -assertion that Rust's `bindgen` cannot see across the Ada boundary -(module header, lines 4-17). - -Safety invariants: -- `danger_levels: [*]const u8` + `count: usize` is the standard - pointer+length C slice; validated non-empty before crossing the Rust - boundary in `spark_axiom.rs` (see §2). -- Output `policy_out` / `status_out` are `*i32` to caller-allocated - storage; the Ada side guarantees they are always written before the - call returns (SPARK contract). - -### §10.2 — `src/zig_ffi/chapel_bridge.zig` - -Type-safe Zig bridge between Chapel's parallel-search runtime and the -Rust FFI surface, gated by the `chapel` Cargo feature (see §3). - -``` -Chapel (C API: chapel_ffi_exports.h) - → Zig (@cImport, this module) - → Rust (safe calls via src/rust/proof_search.rs) -``` - -The `@cImport({ @cInclude("chapel_ffi_exports.h"); })` (lines 18-20) pulls -in the Chapel-exported C declarations for 30 prover backends. The Zig -wrappers (`ProverKind`, `ProverCategory`, `ProofResult`) translate -Chapel's C types into Zig-safe enums and structs, owning all string copies -(`fromChapel` at line 143 takes `std.mem.Allocator` and copies before -returning). - -Safety invariants: -- Enum-from-int boundaries are bounds-checked (line 156: `c_result.prover_id - >= 0 and c_result.prover_id < @as(c_int, ProverKind.count)` before - `@enumFromInt`). -- All string references returned from Chapel are copied into Zig-owned - storage before the Chapel call returns (per module header line 7). -- Chapel runtime guarantees null-terminated string lifetime until next - Chapel call (see §3 for the corresponding Rust-side contract). - -**Classification (both files)**: legitimate FFI (Zig bridge layer between -Ada/SPARK & Chapel backends and Rust core; both feature-gated). No -remediation required. - ---- - -## §11 — `ffi/zig/src/*` overlay layer (UnsafeCode × 3) — pointer casts on static error buffers - -**Added**: 2026-06-01 (post-#104 panic-attack re-sweep, issue #177) - -Three Zig modules in the `ffi/zig/src/` overlay (the Idris2-ABI → Zig-FFI → -C-ABI surface for BoJ cartridges, the overlay subsystem, and the TypeLL -type-language) each contain exactly one `@ptrCast` flagged by panic-attack -as `UnsafeCode`. - -| File | Line | Function | -|------------------------------|------|---------------------------------------| -| `ffi/zig/src/boj.zig` | 456 | `echidna_boj_last_error` | -| `ffi/zig/src/overlay.zig` | 684 | `echidna_overlay_last_error` | -| `ffi/zig/src/typell.zig` | 333 | `echidna_typell_last_error` | - -All three are the **identical pattern**: a `last_error` getter that returns -a C-ABI null-terminated string pointer to a module-private static error -buffer: - -```zig -pub export fn echidna__last_error() ?[*:0]const u8 { - if (error_len == 0) return null; - return @ptrCast(&error_buf); -} -``` - -Where `error_buf: [ERROR_BUF_SIZE]u8` (typically 512 bytes) is a -module-private static array and `error_len: usize` is its current -fill-length. - -Safety invariants: -- `error_buf` is module-static — its address is fixed at program load and - never freed; the returned pointer is always valid for the program - lifetime. -- The cast is from `*[N]u8` (array reference) to `[*:0]const u8` - (sentinel-terminated many-item pointer); the buffer is guaranteed to - contain a trailing nul because all writers (`setError` helpers in each - module) explicitly write a nul terminator before incrementing - `error_len`. -- Return type is `?[*:0]const u8` (optional); a null-fast-path - (`if (error_len == 0) return null;`) guards against returning a pointer - to an empty buffer, so consumers can distinguish "no error" from - "empty-string error". -- Read-only on the Rust/Idris2 side — the pointer is `const`; callers - must not write through it. - -**Concurrency note**: the static error buffer is not thread-safe; each -subsystem's contract is that errors are read on the same thread that -triggered them (consistent with the "BoJ client" / "overlay" / "TypeLL" -single-threaded request-response model). Multi-threaded callers must -serialise error retrieval externally. - -**Classification**: legitimate FFI (idiomatic C-style `last_error` getters -for three FFI subsystems sharing a common pattern). No remediation required. diff --git a/audits/audit-pa021-axioms-2026-05-26.adoc b/audits/audit-pa021-axioms-2026-05-26.adoc new file mode 100644 index 00000000..c8f6b663 --- /dev/null +++ b/audits/audit-pa021-axioms-2026-05-26.adoc @@ -0,0 +1,69 @@ +== Audit: legitimate mathematical axioms (PA021) + +*Auditor*: Jonathan D.A. Jewell *Date*: 2026-05-26 *Scope*: 2 +panic-attack PA021 ProofDrift findings, both postulates with inline +justification in the source. *Cross-reference*: campaign tracker +https://github.com/hyperpolymath/panic-attack/issues/32[hyperpolymath/panic-attack#32]. +*Registry*: `+audits/assail-classifications.a2ml+`. + +=== §1 — `+proofs/agda/Basic.agda+` — `+funext+` (function extensionality) + +Line 172-179 of `+Basic.agda+`: + +[source,agda] +---- +-- provable in Cubical Agda (--cubical). In plain Agda it must be +-- postulated. It is a standard mathematical axiom accepted by all +-- major proof assistants (Coq's Functional Extensionality, Lean's +-- funext, HoTT axiom). It does NOT compromise soundness. +-- See: HoTT Book, Section 2.9; nLab "function extensionality" +postulate + funext : {A B : Set} {f g : A → B} + → ((x : A) → f x ≡ g x) → f ≡ g +---- + +`+funext+` is one of the foundational axioms of dependent type theory. +Coq has `+FunctionalExtensionality.functional_extensionality+`; Lean’s +mathlib has `+funext+`; HoTT has Axiom 2.9.3. It is provable in Cubical +Agda but must be postulated in plain Agda — a well-known constraint of +the underlying type theory. + +*Classification*: `+legitimate-mathematical-axiom+`. + +=== §2 — `+proofs/agda/SoundnessPreservation.agda+` — `+Conflicts+` (intentional parameter) + +Line 44-53 of `+SoundnessPreservation.agda+`: + +[source,agda] +---- +-- Conflicts is an abstract binary predicate over two axiom lists. +-- We leave it as a postulate-free parameter: the caller supplies a +-- concrete proof of ¬ Conflicts when they know the sets are disjoint. +... +-- an axiom that the other marks Reject. +postulate + Conflicts : List Axiom → List Axiom → Set +---- + +The comment explicitly tags this as "`INTENTIONAL PARAMETER — +'`Conflicts`' is domain knowledge about which axioms conflict`". This is +a parameterised theorem: the theorem statement quantifies over an +arbitrary `+Conflicts+` predicate, and the caller proves `+¬ Conflicts+` +(or supplies a concrete relation) at use-site. This is NOT a proof debt +— it is the _interface_ of the theorem. + +*Classification*: `+intentional-parameter+`. + +=== Anti-gameability + +The registry is `+audits/assail-classifications.a2ml+`. Adding new +postulates to either file does NOT become silently suppressed — only +these two specific postulates are classified. Any new `+postulate+` or +`+sorry+` in these or other proof files remains visible. + +=== Verification + +No proof source touched; `+agda --check+` rebuild is moot (input +unchanged from main). + +Refs hyperpolymath/panic-attack#32. diff --git a/audits/audit-pa021-axioms-2026-05-26.md b/audits/audit-pa021-axioms-2026-05-26.md deleted file mode 100644 index d885e3f1..00000000 --- a/audits/audit-pa021-axioms-2026-05-26.md +++ /dev/null @@ -1,59 +0,0 @@ - - -# Audit: legitimate mathematical axioms (PA021) - -**Auditor**: Jonathan D.A. Jewell -**Date**: 2026-05-26 -**Scope**: 2 panic-attack PA021 ProofDrift findings, both postulates with inline justification in the source. -**Cross-reference**: campaign tracker [hyperpolymath/panic-attack#32](https://github.com/hyperpolymath/panic-attack/issues/32). -**Registry**: `audits/assail-classifications.a2ml`. - -## §1 — `proofs/agda/Basic.agda` — `funext` (function extensionality) - -Line 172-179 of `Basic.agda`: - -```agda --- provable in Cubical Agda (--cubical). In plain Agda it must be --- postulated. It is a standard mathematical axiom accepted by all --- major proof assistants (Coq's Functional Extensionality, Lean's --- funext, HoTT axiom). It does NOT compromise soundness. --- See: HoTT Book, Section 2.9; nLab "function extensionality" -postulate - funext : {A B : Set} {f g : A → B} - → ((x : A) → f x ≡ g x) → f ≡ g -``` - -`funext` is one of the foundational axioms of dependent type theory. Coq has `FunctionalExtensionality.functional_extensionality`; Lean's mathlib has `funext`; HoTT has Axiom 2.9.3. It is provable in Cubical Agda but must be postulated in plain Agda — a well-known constraint of the underlying type theory. - -**Classification**: `legitimate-mathematical-axiom`. - -## §2 — `proofs/agda/SoundnessPreservation.agda` — `Conflicts` (intentional parameter) - -Line 44-53 of `SoundnessPreservation.agda`: - -```agda --- Conflicts is an abstract binary predicate over two axiom lists. --- We leave it as a postulate-free parameter: the caller supplies a --- concrete proof of ¬ Conflicts when they know the sets are disjoint. -... --- an axiom that the other marks Reject. -postulate - Conflicts : List Axiom → List Axiom → Set -``` - -The comment explicitly tags this as "INTENTIONAL PARAMETER — 'Conflicts' is domain knowledge about which axioms conflict". This is a parameterised theorem: the theorem statement quantifies over an arbitrary `Conflicts` predicate, and the caller proves `¬ Conflicts` (or supplies a concrete relation) at use-site. This is NOT a proof debt — it is the *interface* of the theorem. - -**Classification**: `intentional-parameter`. - -## Anti-gameability - -The registry is `audits/assail-classifications.a2ml`. Adding new postulates to either file does NOT become silently suppressed — only these two specific postulates are classified. Any new `postulate` or `sorry` in these or other proof files remains visible. - -## Verification - -No proof source touched; `agda --check` rebuild is moot (input unchanged from main). - -Refs hyperpolymath/panic-attack#32. diff --git a/crates/echidna-core-spark/CREUSOT-SETUP.adoc b/crates/echidna-core-spark/CREUSOT-SETUP.adoc new file mode 100644 index 00000000..a93d1e8b --- /dev/null +++ b/crates/echidna-core-spark/CREUSOT-SETUP.adoc @@ -0,0 +1,159 @@ +== Creusot Setup Guide + +How to run formal verification on `+echidna-core-spark+` using Creusot. + +=== Prerequisites + +Creusot requires a pinned Rust *nightly* toolchain and a Why3 +installation with SMT solvers. Stable Rust builds this crate without +Creusot; the `+--features creusot+` flag is only needed for the verifier +pass. + +=== 1 — Install a Rust nightly toolchain + +Creusot pins to specific nightly versions. Check the Creusot repository +(`+https://github.com/creusot-rs/creusot+`) for the current supported +nightly and add it: + +[source,bash] +---- +rustup toolchain install nightly-2024-05-01 # example — check current pin +rustup override set nightly-2024-05-01 --path crates/echidna-core-spark +---- + +`+rust-toolchain.toml+` is at the crate root (added Stage 8c-M1) and +pins `+nightly-2024-05-01+`. Check the Creusot repository for the +current supported nightly and update both `+rust-toolchain.toml+` and +the `+formal-verification.yml+` workflow when bumping. + +=== 2 — Install Creusot + +[source,bash] +---- +cargo +nightly install creusot +---- + +This installs `+creusot-rustc+` (the annotated Rust compiler) alongside +the standard `+cargo+` toolchain. + +=== 3 — Install Why3 + SMT solvers + +Creusot translates annotated Rust to Why3 ML, which is then discharged +by Z3/CVC5/Alt-Ergo. Echidna already ships these solvers as prover +backends, so they should already be available. + +[source,bash] +---- +# Fedora / RHEL (adjust for your distro) +sudo dnf install why3 z3 cvc5 alt-ergo + +# Or via opam (OCaml package manager) +opam install why3 +---- + +Verify: + +[source,bash] +---- +why3 --version +z3 --version +---- + +=== 4 — Run verification + +From the repository root: + +[source,bash] +---- +cargo +nightly creusot \ + -p echidna-core-spark \ + -- \ + --features creusot \ + --why3 $(which why3) +---- + +Or use the Justfile recipe (added in Stage 8c-M1): + +[source,bash] +---- +just verify-trust-pipeline +---- + +=== 5 — Interpreting output + +Creusot emits Why3 obligations; Why3 reports each obligation as: + +* `+Valid+` — SMT solver discharged the proof obligation. +* `+Unknown+` / `+Timeout+` — solver could not discharge within the time +limit. Increase the limit with `+--timeout +` or simplify the +contract. +* `+Invalid+` — the contract is wrong or there is a real bug. + +All obligations in `+impl_invariants+` are designed to discharge quickly +(< 30 s each on a modern workstation). + +=== 6 — CI integration + +`+.github/workflows/formal-verification.yml+` runs two jobs, both merge +gates: + +* `+stable-tests+`: `+cargo test -p echidna-core-spark+` on stable Rust +(~10 s). +* `+creusot-verify+`: `+cargo +nightly creusot+` with Why3 + Z3 +discharge. Requires `+apt-get install why3 z3 alt-ergo+` in the runner +(Ubuntu 22.04+). + +Both were promoted to hard gates in Stage 8c-M3 (no +`+continue-on-error+`). + +=== Annotation style + +Creusot contracts in this crate are written in two complementary forms: + +[arabic] +. *Doc-comment code blocks* — always compiled and visible in +`+rustdoc+`; describe the contract in human-readable form; not executed +by the compiler. +. *`+#[cfg_attr(feature = "creusot", ...)]+` attributes* — +machine-readable; active when Creusot runs (`+--features creusot+`); +no-ops on stable Rust. + +==== Stage status + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Milestone |Contents |Status +|8c-M1 |`+rust-toolchain.toml+`, `+formal-verification.yml+`, +`+just verify-trust-pipeline+` |*done* + +|8c-M2 |`+dominates+` marked `+#[pure]+`; `+compute+` ensures with +`+^candidates+`; inner-loop `+#[invariant]+` for `+dominated+` |*done* + +|8c-M3 |Outer-loop invariant (`+snapshot!+` + prefix classification); +Why3 CI hard gate |*done* +|=== + +All three milestones are complete. The `+compute+` function now carries +the full two-level invariant structure: + +* *Outer*: `+snapshot!(candidates)+` at entry + `+#[invariant]+` +asserting +[loweralpha] +. objectives unchanged for all k, (b) `+is_pareto_optimal[k]+` correctly +set for k < i. +* *Inner*: `+dominated == (∃ k < j, k ≠ i : dominates(k, i))+`. + +The CI workflow (`+formal-verification.yml+`) is a hard gate: both +`+stable-tests+` and `+creusot-verify+` must pass for a merge. If the +nightly pin drifts, bump `+rust-toolchain.toml+` + the workflow’s +`+toolchain:+` field together. + +This keeps the crate buildable on stable Rust at all times while still +expressing every proof obligation in machine-verifiable syntax. + +=== References + +* Creusot repository: https://github.com/creusot-rs/creusot +* Why3 documentation: https://www.why3.org/ +* SPARK Adoption Plan: `+docs/design/SPARK_ADOPTION_PLAN.md+` +* Echidna ROADMAP Stage 8c: `+docs/ROADMAP.md+` diff --git a/crates/echidna-core-spark/CREUSOT-SETUP.md b/crates/echidna-core-spark/CREUSOT-SETUP.md deleted file mode 100644 index 2caa775c..00000000 --- a/crates/echidna-core-spark/CREUSOT-SETUP.md +++ /dev/null @@ -1,137 +0,0 @@ - - -# Creusot Setup Guide - -How to run formal verification on `echidna-core-spark` using Creusot. - -## Prerequisites - -Creusot requires a pinned Rust **nightly** toolchain and a Why3 installation -with SMT solvers. Stable Rust builds this crate without Creusot; the -`--features creusot` flag is only needed for the verifier pass. - -## 1 — Install a Rust nightly toolchain - -Creusot pins to specific nightly versions. Check the Creusot repository -(`https://github.com/creusot-rs/creusot`) for the current supported nightly -and add it: - -```bash -rustup toolchain install nightly-2024-05-01 # example — check current pin -rustup override set nightly-2024-05-01 --path crates/echidna-core-spark -``` - -`rust-toolchain.toml` is at the crate root (added Stage 8c-M1) and pins -`nightly-2024-05-01`. Check the Creusot repository for the current supported -nightly and update both `rust-toolchain.toml` and the `formal-verification.yml` -workflow when bumping. - -## 2 — Install Creusot - -```bash -cargo +nightly install creusot -``` - -This installs `creusot-rustc` (the annotated Rust compiler) alongside the -standard `cargo` toolchain. - -## 3 — Install Why3 + SMT solvers - -Creusot translates annotated Rust to Why3 ML, which is then discharged by -Z3/CVC5/Alt-Ergo. Echidna already ships these solvers as prover backends, -so they should already be available. - -```bash -# Fedora / RHEL (adjust for your distro) -sudo dnf install why3 z3 cvc5 alt-ergo - -# Or via opam (OCaml package manager) -opam install why3 -``` - -Verify: - -```bash -why3 --version -z3 --version -``` - -## 4 — Run verification - -From the repository root: - -```bash -cargo +nightly creusot \ - -p echidna-core-spark \ - -- \ - --features creusot \ - --why3 $(which why3) -``` - -Or use the Justfile recipe (added in Stage 8c-M1): - -```bash -just verify-trust-pipeline -``` - -## 5 — Interpreting output - -Creusot emits Why3 obligations; Why3 reports each obligation as: - -- `Valid` — SMT solver discharged the proof obligation. -- `Unknown` / `Timeout` — solver could not discharge within the time limit. - Increase the limit with `--timeout ` or simplify the contract. -- `Invalid` — the contract is wrong or there is a real bug. - -All obligations in `impl_invariants` are designed to discharge quickly -(< 30 s each on a modern workstation). - -## 6 — CI integration - -`.github/workflows/formal-verification.yml` runs two jobs, both merge gates: - -- `stable-tests`: `cargo test -p echidna-core-spark` on stable Rust (~10 s). -- `creusot-verify`: `cargo +nightly creusot` with Why3 + Z3 discharge. - Requires `apt-get install why3 z3 alt-ergo` in the runner (Ubuntu 22.04+). - -Both were promoted to hard gates in Stage 8c-M3 (no `continue-on-error`). - -## Annotation style - -Creusot contracts in this crate are written in two complementary forms: - -1. **Doc-comment code blocks** — always compiled and visible in `rustdoc`; - describe the contract in human-readable form; not executed by the compiler. -2. **`#[cfg_attr(feature = "creusot", ...)]` attributes** — machine-readable; - active when Creusot runs (`--features creusot`); no-ops on stable Rust. - -### Stage status - -| Milestone | Contents | Status | -|---|---|---| -| 8c-M1 | `rust-toolchain.toml`, `formal-verification.yml`, `just verify-trust-pipeline` | **done** | -| 8c-M2 | `dominates` marked `#[pure]`; `compute` ensures with `^candidates`; inner-loop `#[invariant]` for `dominated` | **done** | -| 8c-M3 | Outer-loop invariant (`snapshot!` + prefix classification); Why3 CI hard gate | **done** | - -All three milestones are complete. The `compute` function now carries the -full two-level invariant structure: - -- **Outer**: `snapshot!(candidates)` at entry + `#[invariant]` asserting - (a) objectives unchanged for all k, (b) `is_pareto_optimal[k]` correctly - set for k < i. -- **Inner**: `dominated == (∃ k < j, k ≠ i : dominates(k, i))`. - -The CI workflow (`formal-verification.yml`) is a hard gate: both -`stable-tests` and `creusot-verify` must pass for a merge. If the nightly -pin drifts, bump `rust-toolchain.toml` + the workflow's `toolchain:` field -together. - -This keeps the crate buildable on stable Rust at all times while still -expressing every proof obligation in machine-verifiable syntax. - -## References - -- Creusot repository: https://github.com/creusot-rs/creusot -- Why3 documentation: https://www.why3.org/ -- SPARK Adoption Plan: `docs/design/SPARK_ADOPTION_PLAN.md` -- Echidna ROADMAP Stage 8c: `docs/ROADMAP.md` diff --git a/crates/echidna-mcp/README.adoc b/crates/echidna-mcp/README.adoc new file mode 100644 index 00000000..31da2a58 --- /dev/null +++ b/crates/echidna-mcp/README.adoc @@ -0,0 +1,239 @@ +== echidna-mcp + +Model Context Protocol server that exposes +https://github.com/hyperpolymath/echidna[ECHIDNA]’s 105-prover portfolio +to AI coding agents (Claude Code, Claude API, etc.) as first-class +tool-use actions over stdio. + +=== Installation + +[source,sh] +---- +# From source (workspace root) +cargo install --path crates/echidna-mcp + +# Or build without installing +cargo build -p echidna-mcp --release +---- + +The `+echidna+` binary must be on `+PATH+` (or set +`+ECHIDNA_BIN=/abs/path/echidna+`). + +=== Claude Code integration + +Add to your project’s `+.claude/settings.json+`: + +[source,json] +---- +{ + "mcpServers": { + "echidna": { + "command": "echidna-mcp" + } + } +} +---- + +Or with an explicit binary path: + +[source,json] +---- +{ + "mcpServers": { + "echidna": { + "command": "echidna-mcp", + "env": { "ECHIDNA_BIN": "/usr/local/bin/echidna" } + } + } +} +---- + +=== Tools + +==== `+prove+` + +Prove a theorem from a file using one of ECHIDNA’s prover backends (see +link:../../docs/PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`]). + +[width="100%",cols="28%,15%,25%,32%",options="header",] +|=== +|Parameter |Type |Required |Description +|`+file+` |string |yes |Absolute path to the proof file + +|`+prover+` |string |no |Backend name (e.g. `+Z3+`, `+Coq+`, `+Lean+`, +`+Isabelle+`). Auto-detected from extension if omitted. + +|`+timeout_secs+` |integer |no |Prover timeout in seconds. Default: 300. +|=== + +*Returns* a JSON object: + +[source,json] +---- +{ + "verified": true, + "message": "Goal discharged.", + "prover": "Z3", + "raw_output": "...", + "stderr": "" +} +---- + +*Accepted file formats* (by prover): + +[cols=",",options="header",] +|=== +|Extension |Prover +|`+.smt2+` |Z3, CVC5, Alt-Ergo +|`+.lean+` |Lean 4 +|`+.v+` |Coq / Rocq +|`+.agda+` |Agda +|`+.thy+` |Isabelle/HOL +|`+.miz+` |Mizar +|`+.fst+` |F* +|`+.dfg+` |SPASS +|`+.mm+` |Metamath +|=== + +==== `+check_prover+` + +Check whether a named prover backend is installed and reachable on the +current system. + +[width="100%",cols="28%,15%,25%,32%",options="header",] +|=== +|Parameter |Type |Required |Description +|`+prover+` |string |yes |Prover backend name (case-sensitive). +Examples: `+Z3+`, `+Lean+`, `+Coq+`, `+Vampire+`. +|=== + +*Returns* a JSON object: + +[source,json] +---- +{ + "available": true, + "message": "Z3 is available" +} +---- + +==== `+list_provers+` + +List all 105 prover backends supported by ECHIDNA. Takes no parameters. + +*Returns* a JSON object: + +[source,json] +---- +{ + "total": 105, + "provers": { + "Z3": "SMT solver (Microsoft Research)", + "Lean": "Lean 4 interactive proof assistant", + "...": "..." + } +} +---- + +=== Example JSON-RPC exchanges + +==== Prove a trivial SMT goal with Z3 + +Request: + +[source,json] +---- +{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "prove", + "arguments": { + "file": "/tmp/reflexivity.smt2", + "prover": "Z3", + "timeout_secs": 10 + } + } +} +---- + +`+/tmp/reflexivity.smt2+`: + +[source,smt2] +---- +(declare-const x Int) +(assert (not (= x x))) +(check-sat) +---- + +Response: + +[source,json] +---- +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "content": [{ + "type": "text", + "text": "{\n \"verified\": true,\n \"message\": \"unsat\",\n \"prover\": \"Z3\",\n \"raw_output\": \"unsat\\n\",\n \"stderr\": \"\"\n}" + }] + } +} +---- + +==== Check that Z3 is installed + +Request: + +[source,json] +---- +{ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "check_prover", + "arguments": { + "prover": "Z3" + } + } +} +---- + +Response: + +[source,json] +---- +{ + "jsonrpc": "2.0", + "id": 2, + "result": { + "content": [{ + "type": "text", + "text": "{\n \"available\": true,\n \"message\": \"Z3 is available\"\n}" + }] + } +} +---- + +=== Troubleshooting + +*`+Failed to invoke echidna: No such file or directory+`*:: + The `+echidna+` binary is not on PATH. Either install it or set + `+ECHIDNA_BIN=/full/path/echidna+` in the MCP server env config. +*`+verified: false+` with empty `+message+`*:: + The prover binary itself is missing. Confirm the target prover is + installed: `+which z3+`, `+which coqc+`, etc. The `+check_prover+` + tool also reports availability. +*Timeout / `+verified: false+` with partial output*:: + Increase `+timeout_secs+`. Complex goals in interactive provers + (Isabelle, Coq) may need 60–600 s. Default is 300 s. +*Wrong prover selected*:: + Pass `+"prover": "Z3"+` (or whichever backend) explicitly rather than + relying on auto-detection. + +=== License + +MPL-2.0 — see link:../../LICENSE[LICENSE]. diff --git a/crates/echidna-mcp/README.md b/crates/echidna-mcp/README.md deleted file mode 100644 index 24851835..00000000 --- a/crates/echidna-mcp/README.md +++ /dev/null @@ -1,207 +0,0 @@ - - - -# echidna-mcp - -Model Context Protocol server that exposes [ECHIDNA](https://github.com/hyperpolymath/echidna)'s -105-prover portfolio to AI coding agents (Claude Code, Claude API, etc.) as first-class -tool-use actions over stdio. - -## Installation - -```sh -# From source (workspace root) -cargo install --path crates/echidna-mcp - -# Or build without installing -cargo build -p echidna-mcp --release -``` - -The `echidna` binary must be on `PATH` (or set `ECHIDNA_BIN=/abs/path/echidna`). - -## Claude Code integration - -Add to your project's `.claude/settings.json`: - -```json -{ - "mcpServers": { - "echidna": { - "command": "echidna-mcp" - } - } -} -``` - -Or with an explicit binary path: - -```json -{ - "mcpServers": { - "echidna": { - "command": "echidna-mcp", - "env": { "ECHIDNA_BIN": "/usr/local/bin/echidna" } - } - } -} -``` - -## Tools - -### `prove` - -Prove a theorem from a file using one of ECHIDNA's prover backends (see [`docs/PROVER_COUNT.md`](../../docs/PROVER_COUNT.md)). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `file` | string | yes | Absolute path to the proof file | -| `prover` | string | no | Backend name (e.g. `Z3`, `Coq`, `Lean`, `Isabelle`). Auto-detected from extension if omitted. | -| `timeout_secs` | integer | no | Prover timeout in seconds. Default: 300. | - -**Returns** a JSON object: -```json -{ - "verified": true, - "message": "Goal discharged.", - "prover": "Z3", - "raw_output": "...", - "stderr": "" -} -``` - -**Accepted file formats** (by prover): - -| Extension | Prover | -|-----------|--------| -| `.smt2` | Z3, CVC5, Alt-Ergo | -| `.lean` | Lean 4 | -| `.v` | Coq / Rocq | -| `.agda` | Agda | -| `.thy` | Isabelle/HOL | -| `.miz` | Mizar | -| `.fst` | F* | -| `.dfg` | SPASS | -| `.mm` | Metamath | - -### `check_prover` - -Check whether a named prover backend is installed and reachable on the current system. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prover` | string | yes | Prover backend name (case-sensitive). Examples: `Z3`, `Lean`, `Coq`, `Vampire`. | - -**Returns** a JSON object: -```json -{ - "available": true, - "message": "Z3 is available" -} -``` - -### `list_provers` - -List all 105 prover backends supported by ECHIDNA. Takes no parameters. - -**Returns** a JSON object: -```json -{ - "total": 105, - "provers": { - "Z3": "SMT solver (Microsoft Research)", - "Lean": "Lean 4 interactive proof assistant", - "...": "..." - } -} -``` - -## Example JSON-RPC exchanges - -### Prove a trivial SMT goal with Z3 - -Request: -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "tools/call", - "params": { - "name": "prove", - "arguments": { - "file": "/tmp/reflexivity.smt2", - "prover": "Z3", - "timeout_secs": 10 - } - } -} -``` - -`/tmp/reflexivity.smt2`: -```smt2 -(declare-const x Int) -(assert (not (= x x))) -(check-sat) -``` - -Response: -```json -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "content": [{ - "type": "text", - "text": "{\n \"verified\": true,\n \"message\": \"unsat\",\n \"prover\": \"Z3\",\n \"raw_output\": \"unsat\\n\",\n \"stderr\": \"\"\n}" - }] - } -} -``` - -### Check that Z3 is installed - -Request: -```json -{ - "jsonrpc": "2.0", - "id": 2, - "method": "tools/call", - "params": { - "name": "check_prover", - "arguments": { - "prover": "Z3" - } - } -} -``` - -Response: -```json -{ - "jsonrpc": "2.0", - "id": 2, - "result": { - "content": [{ - "type": "text", - "text": "{\n \"available\": true,\n \"message\": \"Z3 is available\"\n}" - }] - } -} -``` - -## Troubleshooting - -**`Failed to invoke echidna: No such file or directory`** -: The `echidna` binary is not on PATH. Either install it or set `ECHIDNA_BIN=/full/path/echidna` in the MCP server env config. - -**`verified: false` with empty `message`** -: The prover binary itself is missing. Confirm the target prover is installed: `which z3`, `which coqc`, etc. The `check_prover` tool also reports availability. - -**Timeout / `verified: false` with partial output** -: Increase `timeout_secs`. Complex goals in interactive provers (Isabelle, Coq) may need 60–600 s. Default is 300 s. - -**Wrong prover selected** -: Pass `"prover": "Z3"` (or whichever backend) explicitly rather than relying on auto-detection. - -## License - -MPL-2.0 — see [LICENSE](../../LICENSE). diff --git a/crates/echidna-wire/schemas/VERSIONING.adoc b/crates/echidna-wire/schemas/VERSIONING.adoc new file mode 100644 index 00000000..cc9068ef --- /dev/null +++ b/crates/echidna-wire/schemas/VERSIONING.adoc @@ -0,0 +1,79 @@ +== ECHIDNA Wire Schema Versioning Policy (`+crates/echidna-wire+`) + +Every root message MUST carry `+schemaVersion :UInt16+`. Current: *1*. +File-level capnp IDs (`+@0x…;+`) are generated once and NEVER changed. + +=== Compatibility model + +Cap’n Proto is structurally forward/backward-compatible within a major +version provided the rules below are respected. Major version bumps are +breaking and require a coordinated rollout across Rust core, Julia, +Chapel, and UI peers. + +=== Adding a field (SAFE — no version bump) + +* Append new fields at the next unused `+@N+`. +* New fields MUST either: +** {blank} +[loweralpha] +. have a default value (e.g. `+@N :Bool = false+`), OR +** {blank} +[loweralpha, start=2] +. be paired with a `+has :Bool+` sibling for optional semantics. +* New union variants may be appended at the end of an existing union. +* New nested structs may be added freely. + +=== Removing / changing a field (UNSAFE — major bump) + +* Reordering `+@N+` IDs of existing fields. +* Changing a field’s wire type (e.g. `+UInt32+` → `+UInt64+`). +* Removing a non-optional field. +* Reordering union discriminants. +* Changing the stable `+ProverKind+` discriminant mapping (mirrored in +`+src/rust/ffi/mod.rs+`). + +=== Deprecation flow + +[arabic] +. Mark the field obsolete in this file and in a comment on the +`+.capnp+` line. Add a new replacement field at the next `+@N+`. +. Wait ONE minor version before removal candidacy (L1.0 → L1.1). +. Field removal = major bump (L1.x → L2.0). Must ship an +`+echidna-wire v2+` alongside v1 for at least one release cycle. + +=== Connection-time negotiation + +Every transport session opens with a `+Hello+` exchange (schema deferred +to L1.1 in `+version.capnp+`): + +.... +client → server : Hello { supportedMajors :List(UInt16); preferredMajor :UInt16; } +server → client : HelloAck { agreedMajor :UInt16; agreedMinor :UInt16; } +.... + +If no overlap: server returns `+HelloAck { agreedMajor = 0 }+` and +closes. + +=== ProverKind discriminant governance + +Appending a new variant to `+ProverKind+` (`+src/rust/provers/mod.rs+`) +is SAFE iff: + +* the next contiguous `+u16+` is used (currently 105), +* `+kind_from_u8+` / `+kind_to_u8+` are updated in lockstep +(`+src/rust/ffi/mod.rs+`), +* this file records the assignment. + +Holes in the discriminant space are FORBIDDEN — the invertibility test +at `+src/rust/ffi/mod.rs+` (see `+kind_to_u8_injective+` / round-trip +tests) must keep passing. + +=== Current assignments + +* Schema major: *1*. Minor: *0*. +* File IDs: +** `+common.capnp+` = `+@0xf2f7187fddaa9139+` +** `+proof.capnp+` = `+@0xfa73f2ec7415f450+` +** `+prover.capnp+` = `+@0xf1841ae6bbc44651+` +** `+gnn.capnp+` = `+@0xfbb66b8481def8a0+` +* Deprecations in flight: none. diff --git a/crates/echidna-wire/schemas/VERSIONING.md b/crates/echidna-wire/schemas/VERSIONING.md deleted file mode 100644 index fc3c1b7f..00000000 --- a/crates/echidna-wire/schemas/VERSIONING.md +++ /dev/null @@ -1,75 +0,0 @@ - - -# ECHIDNA Wire Schema Versioning Policy (`crates/echidna-wire`) - -Every root message MUST carry `schemaVersion :UInt16`. Current: **1**. -File-level capnp IDs (`@0x…;`) are generated once and NEVER changed. - -## Compatibility model - -Cap'n Proto is structurally forward/backward-compatible within a major -version provided the rules below are respected. Major version bumps are -breaking and require a coordinated rollout across Rust core, Julia, -Chapel, and UI peers. - -## Adding a field (SAFE — no version bump) - -- Append new fields at the next unused `@N`. -- New fields MUST either: - - (a) have a default value (e.g. `@N :Bool = false`), OR - - (b) be paired with a `has :Bool` sibling for optional semantics. -- New union variants may be appended at the end of an existing union. -- New nested structs may be added freely. - -## Removing / changing a field (UNSAFE — major bump) - -- Reordering `@N` IDs of existing fields. -- Changing a field's wire type (e.g. `UInt32` → `UInt64`). -- Removing a non-optional field. -- Reordering union discriminants. -- Changing the stable `ProverKind` discriminant mapping - (mirrored in `src/rust/ffi/mod.rs`). - -## Deprecation flow - -1. Mark the field obsolete in this file and in a comment on the `.capnp` - line. Add a new replacement field at the next `@N`. -2. Wait ONE minor version before removal candidacy (L1.0 → L1.1). -3. Field removal = major bump (L1.x → L2.0). Must ship an - `echidna-wire v2` alongside v1 for at least one release cycle. - -## Connection-time negotiation - -Every transport session opens with a `Hello` exchange (schema deferred -to L1.1 in `version.capnp`): - -``` -client → server : Hello { supportedMajors :List(UInt16); preferredMajor :UInt16; } -server → client : HelloAck { agreedMajor :UInt16; agreedMinor :UInt16; } -``` - -If no overlap: server returns `HelloAck { agreedMajor = 0 }` and closes. - -## ProverKind discriminant governance - -Appending a new variant to `ProverKind` (`src/rust/provers/mod.rs`) is -SAFE iff: - -- the next contiguous `u16` is used (currently 105), -- `kind_from_u8` / `kind_to_u8` are updated in lockstep - (`src/rust/ffi/mod.rs`), -- this file records the assignment. - -Holes in the discriminant space are FORBIDDEN — the invertibility test -at `src/rust/ffi/mod.rs` (see `kind_to_u8_injective` / round-trip tests) -must keep passing. - -## Current assignments - -- Schema major: **1**. Minor: **0**. -- File IDs: - - `common.capnp` = `@0xf2f7187fddaa9139` - - `proof.capnp` = `@0xfa73f2ec7415f450` - - `prover.capnp` = `@0xf1841ae6bbc44651` - - `gnn.capnp` = `@0xfbb66b8481def8a0` -- Deprecations in flight: none. diff --git a/docs-site/content/api/graphql.md b/docs-site/content/api/graphql.adoc similarity index 66% rename from docs-site/content/api/graphql.md rename to docs-site/content/api/graphql.adoc index 158dbaf8..6bbac58c 100644 --- a/docs-site/content/api/graphql.md +++ b/docs-site/content/api/graphql.adoc @@ -1,22 +1,17 @@ ---- -title: GraphQL API Reference -date: 2026-02-09 -template: default ---- +== GraphQL API Reference -# GraphQL API Reference +Endpoint: `+https://localhost:8081/graphql+` -Endpoint: `https://localhost:8081/graphql` +Playground: `+https://localhost:8081/playground+` -Playground: `https://localhost:8081/playground` +=== Schema -## Schema +==== Queries -### Queries +===== List Provers -#### List Provers - -```graphql +[source,graphql] +---- query { provers { kind @@ -24,13 +19,14 @@ query { complexity } } -``` +---- Returns all 30 prover backends. -#### Get Proof State +===== Get Proof State -```graphql +[source,graphql] +---- query { proofState(sessionId: "session-uuid") { goals { @@ -41,11 +37,12 @@ query { proofScript } } -``` +---- -#### List Active Proofs +===== List Active Proofs -```graphql +[source,graphql] +---- query { listProofs { sessionId @@ -54,11 +51,12 @@ query { startedAt } } -``` +---- -#### Suggest Tactics +===== Suggest Tactics -```graphql +[source,graphql] +---- query { suggestTactics(sessionId: "session-uuid") { name @@ -66,13 +64,14 @@ query { confidence } } -``` +---- -### Mutations +==== Mutations -#### Submit a Proof +===== Submit a Proof -```graphql +[source,graphql] +---- mutation { submitProof( proverKind: COQ @@ -85,11 +84,12 @@ mutation { } } } -``` +---- -#### Apply a Tactic +===== Apply a Tactic -```graphql +[source,graphql] +---- mutation { applyTactic( sessionId: "session-uuid" @@ -102,19 +102,21 @@ mutation { } } } -``` +---- -#### Cancel a Proof +===== Cancel a Proof -```graphql +[source,graphql] +---- mutation { cancelProof(sessionId: "session-uuid") } -``` +---- -## Prover Kind Enum +=== Prover Kind Enum -```graphql +[source,graphql] +---- enum ProverKind { AGDA COQ @@ -147,4 +149,4 @@ enum ProverKind { CHUFFED OR_TOOLS } -``` +---- diff --git a/docs-site/content/api/grpc.md b/docs-site/content/api/grpc.adoc similarity index 75% rename from docs-site/content/api/grpc.md rename to docs-site/content/api/grpc.adoc index 2b18d56c..973c4cdb 100644 --- a/docs-site/content/api/grpc.md +++ b/docs-site/content/api/grpc.adoc @@ -1,18 +1,13 @@ ---- -title: gRPC API Reference -date: 2026-02-09 -template: default ---- +== gRPC API Reference -# gRPC API Reference +Endpoint: `+localhost:50051+` -Endpoint: `localhost:50051` +Proto file: `+src/interfaces/grpc/proto/echidna.proto+` -Proto file: `src/interfaces/grpc/proto/echidna.proto` +=== Service Definition -## Service Definition - -```protobuf +[source,protobuf] +---- service ProofService { rpc SubmitProof (SubmitProofRequest) returns (SubmitProofResponse); rpc GetProofStatus (GetProofStatusRequest) returns (GetProofStatusResponse); @@ -22,73 +17,82 @@ service ProofService { rpc ListProvers (ListProversRequest) returns (ListProversResponse); rpc SuggestTactics (SuggestTacticsRequest) returns (SuggestTacticsResponse); } -``` +---- -## RPC Methods +=== RPC Methods -### SubmitProof +==== SubmitProof Submit a new proof for verification. -**Request:** -```protobuf +*Request:* + +[source,protobuf] +---- message SubmitProofRequest { string prover_kind = 1; string goal = 2; int64 timeout_ms = 3; } -``` +---- + +*Response:* -**Response:** -```protobuf +[source,protobuf] +---- message SubmitProofResponse { string session_id = 1; ProofStatus status = 2; repeated string goals = 3; } -``` +---- -### StreamProof +==== StreamProof Stream proof progress updates in real time. -**Request:** -```protobuf +*Request:* + +[source,protobuf] +---- message StreamProofRequest { string prover_kind = 1; string goal = 2; } -``` +---- + +*Response (stream):* -**Response (stream):** -```protobuf +[source,protobuf] +---- message ProofUpdate { string step = 1; ProofStatus status = 2; repeated string remaining_goals = 3; float progress = 4; } -``` +---- -### ApplyTactic +==== ApplyTactic Apply a tactic to an active proof session. -### CancelProof +==== CancelProof Cancel an active proof session. -### ListProvers +==== ListProvers List all 30 available prover backends with tier and complexity. -### SuggestTactics +==== SuggestTactics Get ML-suggested tactics for the current proof state. -## Connection +=== Connection -```bash +[source,bash] +---- # Using grpcurl grpcurl -plaintext localhost:50051 echidna.ProofService/ListProvers @@ -97,4 +101,4 @@ grpcurl -plaintext -d '{ "prover_kind": "coq", "goal": "forall n, n + 0 = n" }' localhost:50051 echidna.ProofService/SubmitProof -``` +---- diff --git a/docs-site/content/api/rest.adoc b/docs-site/content/api/rest.adoc new file mode 100644 index 00000000..47b03ef1 --- /dev/null +++ b/docs-site/content/api/rest.adoc @@ -0,0 +1,149 @@ +== REST API Reference + +Base URL: `+https://localhost:8000/api/v1+` + +=== Endpoints + +==== Health Check + +.... +GET /health +.... + +Returns server health status. + +==== Provers + +===== List All Provers + +.... +GET /api/v1/provers +.... + +Returns all 30 supported prover backends with tier and complexity +information. + +===== Get Prover Details + +.... +GET /api/v1/provers/:kind +.... + +Returns details for a specific prover backend. + +*Path Parameters:* - `+kind+` — Prover identifier (e.g., `+coq+`, +`+lean+`, `+z3+`, `+isabelle+`) + +==== Proofs + +===== Submit a Proof + +.... +POST /api/v1/proofs +.... + +*Request Body:* + +[source,json] +---- +{ + "prover": "coq", + "goal": "forall n : nat, n + 0 = n", + "timeout_ms": 30000 +} +---- + +*Response:* + +[source,json] +---- +{ + "id": "proof-uuid", + "status": "verified", + "prover": "coq", + "goals_remaining": 0 +} +---- + +===== List Active Proofs + +.... +GET /api/v1/proofs +.... + +Returns all active proof sessions. + +===== Get Proof Status + +.... +GET /api/v1/proofs/:id +.... + +===== Cancel a Proof + +.... +DELETE /api/v1/proofs/:id +.... + +==== Tactics + +===== Apply a Tactic + +.... +POST /api/v1/proofs/:id/tactics +.... + +*Request Body:* + +[source,json] +---- +{ + "tactic": "induction n" +} +---- + +===== Suggest Tactics + +.... +GET /api/v1/proofs/:id/tactics/suggest +.... + +Returns ML-suggested tactics for the current proof state. Uses Julia ML +service (port 8090) with fallback to prover built-in suggestions. + +=== Prover Kinds + +[cols=",,",options="header",] +|=== +|Kind |Tier |Category +|agda |core |Interactive Proof Assistant +|coq |core |Interactive Proof Assistant +|lean |core |Interactive Proof Assistant +|isabelle |core |Interactive Proof Assistant +|idris2 |core |Interactive Proof Assistant +|fstar |core |Interactive Proof Assistant +|z3 |core |SMT Solver +|cvc5 |core |SMT Solver +|alt_ergo |core |SMT Solver +|dafny |core |Auto-Active Verifier +|why3 |core |Auto-Active Verifier +|metamath |core |Specialised +|hol_light |core |Specialised +|mizar |core |Specialised +|hol4 |core |Specialised +|pvs |core |Specialised +|acl2 |core |Specialised +|tlaps |core |Specialised +|twelf |core |Specialised +|nuprl |core |Specialised +|minlog |core |Specialised +|imandra |core |Specialised +|vampire |core |First-Order ATP +|eprover |core |First-Order ATP +|spass |core |First-Order ATP +|glpk |core |Constraint Solver +|scip |core |Constraint Solver +|minizinc |core |Constraint Solver +|chuffed |core |Constraint Solver +|or_tools |core |Constraint Solver +|=== diff --git a/docs-site/content/api/rest.md b/docs-site/content/api/rest.md deleted file mode 100644 index ce70fc52..00000000 --- a/docs-site/content/api/rest.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: REST API Reference -date: 2026-02-09 -template: default ---- - -# REST API Reference - -Base URL: `https://localhost:8000/api/v1` - -## Endpoints - -### Health Check - -``` -GET /health -``` - -Returns server health status. - -### Provers - -#### List All Provers - -``` -GET /api/v1/provers -``` - -Returns all 30 supported prover backends with tier and complexity information. - -#### Get Prover Details - -``` -GET /api/v1/provers/:kind -``` - -Returns details for a specific prover backend. - -**Path Parameters:** -- `kind` — Prover identifier (e.g., `coq`, `lean`, `z3`, `isabelle`) - -### Proofs - -#### Submit a Proof - -``` -POST /api/v1/proofs -``` - -**Request Body:** -```json -{ - "prover": "coq", - "goal": "forall n : nat, n + 0 = n", - "timeout_ms": 30000 -} -``` - -**Response:** -```json -{ - "id": "proof-uuid", - "status": "verified", - "prover": "coq", - "goals_remaining": 0 -} -``` - -#### List Active Proofs - -``` -GET /api/v1/proofs -``` - -Returns all active proof sessions. - -#### Get Proof Status - -``` -GET /api/v1/proofs/:id -``` - -#### Cancel a Proof - -``` -DELETE /api/v1/proofs/:id -``` - -### Tactics - -#### Apply a Tactic - -``` -POST /api/v1/proofs/:id/tactics -``` - -**Request Body:** -```json -{ - "tactic": "induction n" -} -``` - -#### Suggest Tactics - -``` -GET /api/v1/proofs/:id/tactics/suggest -``` - -Returns ML-suggested tactics for the current proof state. -Uses Julia ML service (port 8090) with fallback to prover built-in suggestions. - -## Prover Kinds - -| Kind | Tier | Category | -|------|------|----------| -| agda | core | Interactive Proof Assistant | -| coq | core | Interactive Proof Assistant | -| lean | core | Interactive Proof Assistant | -| isabelle | core | Interactive Proof Assistant | -| idris2 | core | Interactive Proof Assistant | -| fstar | core | Interactive Proof Assistant | -| z3 | core | SMT Solver | -| cvc5 | core | SMT Solver | -| alt_ergo | core | SMT Solver | -| dafny | core | Auto-Active Verifier | -| why3 | core | Auto-Active Verifier | -| metamath | core | Specialised | -| hol_light | core | Specialised | -| mizar | core | Specialised | -| hol4 | core | Specialised | -| pvs | core | Specialised | -| acl2 | core | Specialised | -| tlaps | core | Specialised | -| twelf | core | Specialised | -| nuprl | core | Specialised | -| minlog | core | Specialised | -| imandra | core | Specialised | -| vampire | core | First-Order ATP | -| eprover | core | First-Order ATP | -| spass | core | First-Order ATP | -| glpk | core | Constraint Solver | -| scip | core | Constraint Solver | -| minizinc | core | Constraint Solver | -| chuffed | core | Constraint Solver | -| or_tools | core | Constraint Solver | diff --git a/docs-site/content/index.adoc b/docs-site/content/index.adoc new file mode 100644 index 00000000..2517cb9c --- /dev/null +++ b/docs-site/content/index.adoc @@ -0,0 +1,63 @@ +== ECHIDNA + +*Extensible Cognitive Hybrid Intelligence for Deductive Neural +Assistance* + +A trust-hardened neurosymbolic theorem proving platform supporting 30 +prover backends with a comprehensive verification pipeline. + +=== Features + +* *30 Prover Backends*: Coq, Lean 4, Isabelle/HOL, Z3, CVC5, Agda, +Idris2, and more +* *Trust Pipeline*: Solver integrity, proof certificates, axiom +tracking, confidence scoring +* *API Interfaces*: REST (OpenAPI), GraphQL, gRPC +* *Neural Premise Selection*: Julia ML layer with tactic prediction +* *Proof Exchange*: Cross-prover via OpenTheory and Dedukti + +=== API Quick Start + +==== REST API (Port 8000) + +List all provers: + +[source,bash] +---- +curl https://localhost:8000/api/v1/provers +---- + +Submit a proof: + +[source,bash] +---- +curl -X POST https://localhost:8000/api/v1/proofs \ + -H "Content-Type: application/json" \ + -d '{"prover": "coq", "goal": "forall n, n + 0 = n"}' +---- + +==== GraphQL (Port 8081) + +Query provers and submit proofs via the GraphQL playground. + +==== gRPC (Port 50051) + +See the proto definition at `+src/interfaces/grpc/proto/echidna.proto+`. + +=== Architecture + +ECHIDNA follows a trust-hardened architecture: + +[arabic] +. *Solver Binary Integrity* — SHAKE3-512 + BLAKE3 verification +. *SMT Portfolio Solving* — cross-checking across solvers +. *Proof Certificate Checking* — Alethe, DRAT/LRAT, TSTP +. *Axiom Usage Tracking* — 4 danger levels (Safe, Noted, Warning, +Reject) +. *Solver Sandboxing* — Podman, bubblewrap, or none +. *Confidence Scoring* — 5-level trust hierarchy +. *Mutation Testing* — specification robustness testing + +=== License + +MPL-2.0 diff --git a/docs-site/content/index.md b/docs-site/content/index.md deleted file mode 100644 index 19c70d6e..00000000 --- a/docs-site/content/index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: ECHIDNA - Neurosymbolic Theorem Proving -date: 2026-02-09 -template: default ---- - -# ECHIDNA - -**Extensible Cognitive Hybrid Intelligence for Deductive Neural Assistance** - -A trust-hardened neurosymbolic theorem proving platform supporting 30 prover backends -with a comprehensive verification pipeline. - -## Features - -- **30 Prover Backends**: Coq, Lean 4, Isabelle/HOL, Z3, CVC5, Agda, Idris2, and more -- **Trust Pipeline**: Solver integrity, proof certificates, axiom tracking, confidence scoring -- **API Interfaces**: REST (OpenAPI), GraphQL, gRPC -- **Neural Premise Selection**: Julia ML layer with tactic prediction -- **Proof Exchange**: Cross-prover via OpenTheory and Dedukti - -## API Quick Start - -### REST API (Port 8000) - -List all provers: - -```bash -curl https://localhost:8000/api/v1/provers -``` - -Submit a proof: - -```bash -curl -X POST https://localhost:8000/api/v1/proofs \ - -H "Content-Type: application/json" \ - -d '{"prover": "coq", "goal": "forall n, n + 0 = n"}' -``` - -### GraphQL (Port 8081) - -Query provers and submit proofs via the GraphQL playground. - -### gRPC (Port 50051) - -See the proto definition at `src/interfaces/grpc/proto/echidna.proto`. - -## Architecture - -ECHIDNA follows a trust-hardened architecture: - -1. **Solver Binary Integrity** — SHAKE3-512 + BLAKE3 verification -2. **SMT Portfolio Solving** — cross-checking across solvers -3. **Proof Certificate Checking** — Alethe, DRAT/LRAT, TSTP -4. **Axiom Usage Tracking** — 4 danger levels (Safe, Noted, Warning, Reject) -5. **Solver Sandboxing** — Podman, bubblewrap, or none -6. **Confidence Scoring** — 5-level trust hierarchy -7. **Mutation Testing** — specification robustness testing - -## License - -MPL-2.0 diff --git a/docs/AGENTIC_FEATURES.md b/docs/AGENTIC_FEATURES.adoc similarity index 67% rename from docs/AGENTIC_FEATURES.md rename to docs/AGENTIC_FEATURES.adoc index e8e5d10c..80921e2d 100644 --- a/docs/AGENTIC_FEATURES.md +++ b/docs/AGENTIC_FEATURES.adoc @@ -1,12 +1,15 @@ -# ECHIDNA Agentic Features +== ECHIDNA Agentic Features -## Overview +=== Overview -ECHIDNA's agentic theorem proving system provides autonomous, self-improving proof search with multi-agent collaboration, neural guidance, and symbolic verification. This document describes the architecture, components, and usage of the agentic features. +ECHIDNA’s agentic theorem proving system provides autonomous, +self-improving proof search with multi-agent collaboration, neural +guidance, and symbolic verification. This document describes the +architecture, components, and usage of the agentic features. -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────────────────────────┐ │ Agent Core │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ @@ -54,23 +57,25 @@ ECHIDNA's agentic theorem proving system provides autonomous, self-improving pro │ │ - Confidence estimation │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ -``` +.... -## Core Components +=== Core Components -### 1. Agent Core (`src/rust/agent/mod.rs`) +==== 1. Agent Core (`+src/rust/agent/mod.rs+`) The central autonomous agent that coordinates theorem proving. -**Key Features:** -- **Priority Queue**: Goals are processed by priority (Critical > High > Medium > Low) -- **Autonomous Loop**: Continuously processes goals without human intervention -- **Reflection**: Learns from successes and failures -- **Decomposition**: Breaks complex goals into simpler sub-goals -- **Memory Integration**: Caches successful proofs for reuse +*Key Features:* - *Priority Queue*: Goals are processed by priority +(Critical > High > Medium > Low) - *Autonomous Loop*: Continuously +processes goals without human intervention - *Reflection*: Learns from +successes and failures - *Decomposition*: Breaks complex goals into +simpler sub-goals - *Memory Integration*: Caches successful proofs for +reuse -**Configuration:** -```rust +*Configuration:* + +[source,rust] +---- AgentConfig { max_concurrent: 4, // Parallel goals max_attempts: 3, // Retry limit @@ -79,10 +84,12 @@ AgentConfig { reflection_enabled: true, // Learn from failures planning_enabled: true, // Decompose goals } -``` +---- + +*Usage:* -**Usage:** -```rust +[source,rust] +---- use echidna::agent::{AgentCore, AgentConfig, AgenticGoal, Priority}; let agent = AgentCore::new( @@ -108,20 +115,21 @@ agent.add_goal(AgenticGoal { tokio::spawn(async move { agent.run().await }); -``` +---- -### 2. Proof Memory (`src/rust/agent/memory.rs`) +==== 2. Proof Memory (`+src/rust/agent/memory.rs+`) SQLite-based storage for successful proofs and failures. -**Key Features:** -- **Success Caching**: Store proofs for instant retrieval -- **Failure Tracking**: Remember what didn't work -- **Similarity Search**: Find similar proofs by aspect overlap -- **Statistics**: Success rates, average times, total proofs +*Key Features:* - *Success Caching*: Store proofs for instant retrieval +- *Failure Tracking*: Remember what didn’t work - *Similarity Search*: +Find similar proofs by aspect overlap - *Statistics*: Success rates, +average times, total proofs + +*Schema:* -**Schema:** -```sql +[source,sql] +---- CREATE TABLE successes ( id INTEGER PRIMARY KEY, goal_id TEXT, @@ -142,10 +150,12 @@ CREATE TABLE failures ( reason TEXT, timestamp TEXT ); -``` +---- -**Usage:** -```rust +*Usage:* + +[source,rust] +---- use echidna::agent::memory::SqliteMemory; let memory = SqliteMemory::new("proofs.db").await?; @@ -161,20 +171,21 @@ if let Some(cached) = memory.find_similar(&goal).await? { // Get stats let stats = memory.stats().await?; println!("Success rate: {:.2}%", stats.success_rate * 100.0); -``` +---- -### 3. Dynamic Prover Router (`src/rust/agent/router.rs`) +==== 3. Dynamic Prover Router (`+src/rust/agent/router.rs+`) Learns which provers work best for different types of goals. -**Key Features:** -- **Aspect-Based Scoring**: Matches goal aspects to prover strengths -- **Success/Failure Tracking**: Per-prover, per-aspect statistics -- **Dynamic Selection**: Adapts based on historical performance -- **Score Formula**: `score = success_rate * (1 / log(avg_time))` +*Key Features:* - *Aspect-Based Scoring*: Matches goal aspects to prover +strengths - *Success/Failure Tracking*: Per-prover, per-aspect +statistics - *Dynamic Selection*: Adapts based on historical performance +- *Score Formula*: `+score = success_rate * (1 / log(avg_time))+` + +*Usage:* -**Usage:** -```rust +[source,rust] +---- use echidna::agent::router::ProverRouter; let router = ProverRouter::new(); @@ -186,26 +197,25 @@ router.record_failure(&goal, ProverKind::Z3).await; // Select best prover let prover = router.select_async(&goal).await; println!("Selected {:?} for goal with aspects {:?}", prover, goal.aspects); -``` +---- -**Aspect Examples:** -- `algebra`, `group_theory`, `ring_theory` -- `logic`, `propositional`, `first_order` -- `type_theory`, `dependent_types` -- `analysis`, `calculus`, `topology` -- `category_theory`, `functors`, `monads` +*Aspect Examples:* - `+algebra+`, `+group_theory+`, `+ring_theory+` - +`+logic+`, `+propositional+`, `+first_order+` - `+type_theory+`, +`+dependent_types+` - `+analysis+`, `+calculus+`, `+topology+` - +`+category_theory+`, `+functors+`, `+monads+` -### 4. Hierarchical Planner (`src/rust/agent/planner.rs`) +==== 4. Hierarchical Planner (`+src/rust/agent/planner.rs+`) Decomposes complex goals into manageable sub-goals. -**Decomposition Rules:** -1. **Implication (A → B)**: Decompose into "Prove B assuming A" -2. **Conjunction (A ∧ B)**: Decompose into "Prove A" + "Prove B" -3. **Universal (∀x. P(x))**: Introduce variable, prove P(x) +*Decomposition Rules:* 1. *Implication (A → B)*: Decompose into "`Prove +B assuming A`" 2. *Conjunction (A ∧ B)*: Decompose into "`Prove A`" + +"`Prove B`" 3. *Universal (∀x. P(x))*: Introduce variable, prove P(x) -**Usage:** -```rust +*Usage:* + +[source,rust] +---- use echidna::agent::planner::RulePlanner; let planner = RulePlanner::new(); @@ -216,20 +226,21 @@ let sub_goals = planner.decompose(&goal).await?; for sub_goal in sub_goals { println!("Sub-goal: {}", sub_goal.goal.id); } -``` +---- -### 5. Multi-Agent System (`src/rust/agent/actors.rs`) +==== 5. Multi-Agent System (`+src/rust/agent/actors.rs+`) Actix-based actor system for parallel proof search. -**Actors:** -- **ProverAgent**: Wraps a prover backend, handles `ProveGoal` messages -- **ContextAgent**: Queries ConceptNet for common-sense knowledge -- **LemmaAgent**: Generates auxiliary lemmas -- **CoordinatorAgent**: Orchestrates parallel proof attempts +*Actors:* - *ProverAgent*: Wraps a prover backend, handles `+ProveGoal+` +messages - *ContextAgent*: Queries ConceptNet for common-sense knowledge +- *LemmaAgent*: Generates auxiliary lemmas - *CoordinatorAgent*: +Orchestrates parallel proof attempts + +*Usage:* -**Usage:** -```rust +[source,rust] +---- use echidna::agent::actors::MultiAgentSystem; let system = MultiAgentSystem::new(vec![ @@ -241,21 +252,22 @@ let system = MultiAgentSystem::new(vec![ // Parallel proof search let (proof, prover) = system.prove(goal, true).await?; println!("Proved with {:?}", prover); -``` +---- -### 6. Explanations (`src/rust/agent/explanations.rs`) +==== 6. Explanations (`+src/rust/agent/explanations.rs+`) Template-based human-readable explanations. -**Explanation Types:** -- **Proof Failure**: Why a proof attempt failed + suggestions -- **Prover Selection**: Why a particular prover was chosen -- **Goal Decomposition**: How a goal was broken down -- **Tactic Selection**: Why a specific tactic was chosen -- **Proof Success**: Summary of successful proof +*Explanation Types:* - *Proof Failure*: Why a proof attempt failed + +suggestions - *Prover Selection*: Why a particular prover was chosen - +*Goal Decomposition*: How a goal was broken down - *Tactic Selection*: +Why a specific tactic was chosen - *Proof Success*: Summary of +successful proof + +*Usage:* -**Usage:** -```rust +[source,rust] +---- use echidna::agent::explanations::ExplanationGenerator; let generator = ExplanationGenerator::new(); @@ -267,10 +279,11 @@ println!("{}", exp.format()); // Explain success let exp = generator.explain_success(&goal, ProverKind::Lean, 150); println!("{}", exp.format()); -``` +---- -**Example Output:** -``` +*Example Output:* + +.... # Proof Attempt Failed The proof attempt for 'goal_123' failed using prover Coq. timeout @@ -288,21 +301,21 @@ The proof attempt for 'goal_123' failed using prover Coq. timeout - Try decomposing the goal into smaller sub-goals - Use a faster prover (Z3 or CVC5) - Simplify the goal using lemmas -``` +.... -## Julia ML Components +=== Julia ML Components -### 7. Reinforcement Learning (`src/julia/rl/training.jl`) +==== 7. Reinforcement Learning (`+src/julia/rl/training.jl+`) Trains neural models from symbolic feedback. -**Environment:** -- **State**: Proof state + aspect vector -- **Action**: Tactic selection -- **Reward**: +1.0 (success), -0.1 (failure), -time_penalty +*Environment:* - *State*: Proof state + aspect vector - *Action*: Tactic +selection - *Reward*: +1.0 (success), -0.1 (failure), -time_penalty + +*Training Loop:* -**Training Loop:** -```julia +[source,julia] +---- using EchidnaML.RLTraining env = RLEnvironment( @@ -316,14 +329,16 @@ train_agent!(env, epochs=100, batch_size=32) # Save model save_model(env, "models/rl_agent_v2.bson") -``` +---- -### 8. Probabilistic Reasoning (`src/julia/probabilistic/gen_reasoning.jl`) +==== 8. Probabilistic Reasoning (`+src/julia/probabilistic/gen_reasoning.jl+`) Gen.jl-based probabilistic models for proof synthesis. -**Generative Model:** -```julia +*Generative Model:* + +[source,julia] +---- @gen function theorem_proving_model(goal::String, context::Vector{String}) num_tactics = @trace(geometric(0.3), :num_tactics) + 1 tactics = String[] @@ -337,10 +352,12 @@ Gen.jl-based probabilistic models for proof synthesis. success = @trace(bernoulli(success_prob), :success) (tactics, success) end -``` +---- + +*Usage:* -**Usage:** -```julia +[source,julia] +---- using EchidnaML.ProbabilisticReasoning # Infer likely proof steps @@ -364,21 +381,26 @@ ranked = rank_candidates_probabilistic( context, num_samples=1000 ) -``` +---- + +=== Integration with ConceptNet -## Integration with ConceptNet +The `+ContextAgent+` queries ConceptNet for common-sense knowledge to +augment theorem proving. -The `ContextAgent` queries ConceptNet for common-sense knowledge to augment theorem proving. +*Example:* -**Example:** -```rust +[source,rust] +---- // Goal: "Prove every group has an identity element" // ConceptNet query: "group", "identity", "element" // Returns: ["inverse", "associativity", "closure", "binary_operation", ...] -``` +---- -**API Usage:** -```rust +*API Usage:* + +[source,rust] +---- use echidna::integrations::ConceptNetClient; let client = ConceptNetClient::new(); @@ -397,13 +419,13 @@ let related = client.augment_theorem( "Prove that every group has an identity element" ).await?; println!("Related concepts: {:?}", related); -``` +---- -## Workflow +=== Workflow -### Typical Agentic Proof Workflow +==== Typical Agentic Proof Workflow -``` +.... 1. User submits goal ↓ 2. Agent Core adds to priority queue @@ -433,29 +455,27 @@ println!("Related concepts: {:?}", related); └─ Update probabilistic models (Gen.jl) ↓ 9. Generate human explanation -``` +.... -## Testing +=== Testing Run integration tests: -```bash + +[source,bash] +---- cargo test --test agentic_integration -``` +---- -Tests cover: -- Proof memory storage/retrieval -- Router aspect-based learning -- Goal decomposition -- Priority queue ordering -- Explanation generation -- Failure tracking -- Multi-prover coordination +Tests cover: - Proof memory storage/retrieval - Router aspect-based +learning - Goal decomposition - Priority queue ordering - Explanation +generation - Failure tracking - Multi-prover coordination -## Configuration +=== Configuration -### Environment Variables +==== Environment Variables -```bash +[source,bash] +---- # Database path export ECHIDNA_PROOF_DB="proofs.db" @@ -470,11 +490,12 @@ export ECHIDNA_GEN_MODEL="models/gen_model.bson" export ECHIDNA_MAX_ATTEMPTS=3 export ECHIDNA_TIMEOUT_SECS=300 export ECHIDNA_MAX_CONCURRENT=4 -``` +---- -### Config File (TOML) +==== Config File (TOML) -```toml +[source,toml] +---- [agent] max_concurrent = 4 max_attempts = 3 @@ -506,78 +527,92 @@ batch_size = 32 model_path = "models/gen_model.bson" num_samples = 100 confidence_threshold = 0.7 -``` - -## Performance Optimization - -### Memory Optimization -- **Limit cache size**: Set `cache_size` to prevent unbounded memory growth -- **Periodic cleanup**: Remove old failures after threshold - -### Speed Optimization -- **Parallel mode**: Enable parallel proof search for independent goals -- **Fast provers first**: Z3 and CVC5 for decidable sub-problems -- **Early termination**: Stop on first success in parallel mode - -### Learning Optimization -- **Batch training**: Train RL model periodically, not per-proof -- **Aspect granularity**: Use specific aspects for better router accuracy -- **Prune statistics**: Remove low-confidence prover-aspect pairs - -## Troubleshooting - -### "No prover succeeded" -- Check aspect tags are descriptive -- Increase `max_attempts` -- Enable `planning_enabled` for decomposition -- Review goal formulation - -### "Timeout on all attempts" -- Decompose goal manually -- Use faster provers (Z3, CVC5) -- Increase `timeout_secs` -- Simplify goal or add lemmas - -### "Memory growing unbounded" -- Set `cache_size` limit -- Run periodic cleanup -- Archive old proofs to separate database - -### "Router always selects same prover" -- Need more training data -- Check aspect distribution -- Reset router statistics if biased - -## Future Enhancements - -### Planned Features -1. **Human-in-the-Loop**: Interactive proof repair -2. **Proof Sketching**: Partial proofs with holes -3. **Multi-Objective RL**: Optimize for speed + correctness + readability -4. **Distributed Agents**: Proof search across multiple machines -5. **Proof Compression**: Minimize proof script length -6. **Explanation Refinement**: NLG for more detailed explanations - -### Research Directions -1. **Neural Theorem Proving**: Full end-to-end neural models -2. **Transfer Learning**: Cross-domain proof transfer -3. **Meta-Learning**: Few-shot adaptation to new domains -4. **Causal Reasoning**: Why proofs succeed or fail -5. **Adversarial Training**: Robustness to malformed goals - -## References - -1. **ConceptNet**: https://conceptnet.io/ -2. **Gen.jl**: https://www.gen.dev/ -3. **ReinforcementLearning.jl**: https://github.com/JuliaReinforcementLearning/ReinforcementLearning.jl -4. **Actix**: https://actix.rs/ -5. **Neurosymbolic AI**: [Combining Logic and Learning (Survey)](https://arxiv.org/abs/2202.01364) - -## License +---- + +=== Performance Optimization + +==== Memory Optimization + +* *Limit cache size*: Set `+cache_size+` to prevent unbounded memory +growth +* *Periodic cleanup*: Remove old failures after threshold + +==== Speed Optimization + +* *Parallel mode*: Enable parallel proof search for independent goals +* *Fast provers first*: Z3 and CVC5 for decidable sub-problems +* *Early termination*: Stop on first success in parallel mode + +==== Learning Optimization + +* *Batch training*: Train RL model periodically, not per-proof +* *Aspect granularity*: Use specific aspects for better router accuracy +* *Prune statistics*: Remove low-confidence prover-aspect pairs + +=== Troubleshooting + +==== "`No prover succeeded`" + +* Check aspect tags are descriptive +* Increase `+max_attempts+` +* Enable `+planning_enabled+` for decomposition +* Review goal formulation + +==== "`Timeout on all attempts`" + +* Decompose goal manually +* Use faster provers (Z3, CVC5) +* Increase `+timeout_secs+` +* Simplify goal or add lemmas + +==== "`Memory growing unbounded`" + +* Set `+cache_size+` limit +* Run periodic cleanup +* Archive old proofs to separate database + +==== "`Router always selects same prover`" + +* Need more training data +* Check aspect distribution +* Reset router statistics if biased + +=== Future Enhancements + +==== Planned Features + +[arabic] +. *Human-in-the-Loop*: Interactive proof repair +. *Proof Sketching*: Partial proofs with holes +. *Multi-Objective RL*: Optimize for speed + correctness + readability +. *Distributed Agents*: Proof search across multiple machines +. *Proof Compression*: Minimize proof script length +. *Explanation Refinement*: NLG for more detailed explanations + +==== Research Directions + +[arabic] +. *Neural Theorem Proving*: Full end-to-end neural models +. *Transfer Learning*: Cross-domain proof transfer +. *Meta-Learning*: Few-shot adaptation to new domains +. *Causal Reasoning*: Why proofs succeed or fail +. *Adversarial Training*: Robustness to malformed goals + +=== References + +[arabic] +. *ConceptNet*: https://conceptnet.io/ +. *Gen.jl*: https://www.gen.dev/ +. *ReinforcementLearning.jl*: +https://github.com/JuliaReinforcementLearning/ReinforcementLearning.jl +. *Actix*: https://actix.rs/ +. *Neurosymbolic AI*: https://arxiv.org/abs/2202.01364[Combining Logic +and Learning (Survey)] + +=== License MIT AND Palimpsest-0.6 ---- +''''' -**ECHIDNA Project Team** -Last Updated: 2025-11-22 +*ECHIDNA Project Team* Last Updated: 2025-11-22 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.adoc similarity index 54% rename from docs/ARCHITECTURE.md rename to docs/ARCHITECTURE.adoc index caef1697..257a50a7 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.adoc @@ -1,27 +1,27 @@ - - - -# ECHIDNA Architecture - -**Status**: canonical human-readable overview. Lives alongside the machine-readable -[`.machine_readable/descriptiles/META.a2ml`](../.machine_readable/descriptiles/META.a2ml) (architecture -decisions) and [`STATE.a2ml`](../.machine_readable/descriptiles/STATE.a2ml) (current state). -Last revised: 2026-05-26. - -ECHIDNA — Extensible Cognitive Hybrid Intelligence for Deductive Neural Assistance — -is the reasoning substrate of the hyperpolymath ecosystem. Two non-negotiable -invariants govern every design choice: - -1. **ML suggests; provers verify.** Neural components rank, route, and propose; - formal provers carry the trust. A wrong suggestion is a wasted CPU cycle, - not a wrong proof. -2. **Trust is checked, not asserted.** Solver binaries are SHAKE3-512 / BLAKE3 - integrity-checked before invocation; certificates are independently - reproduced where formats allow (Alethe, DRAT/LRAT, TSTP). - -## Component map - -``` +== ECHIDNA Architecture + +*Status*: canonical human-readable overview. Lives alongside the +machine-readable +link:../.machine_readable/descriptiles/META.a2ml[`+.machine_readable/descriptiles/META.a2ml+`] +(architecture decisions) and +link:../.machine_readable/descriptiles/STATE.a2ml[`+STATE.a2ml+`] +(current state). Last revised: 2026-05-26. + +ECHIDNA — Extensible Cognitive Hybrid Intelligence for Deductive Neural +Assistance — is the reasoning substrate of the hyperpolymath ecosystem. +Two non-negotiable invariants govern every design choice: + +[arabic] +. *ML suggests; provers verify.* Neural components rank, route, and +propose; formal provers carry the trust. A wrong suggestion is a wasted +CPU cycle, not a wrong proof. +. *Trust is checked, not asserted.* Solver binaries are SHAKE3-512 / +BLAKE3 integrity-checked before invocation; certificates are +independently reproduced where formats allow (Alethe, DRAT/LRAT, TSTP). + +=== Component map + +.... ┌─────────────────────────────────────────────────────────────────────────┐ │ UI Layer │ │ AffineScript-TEA (migrating from src/affinescript/), served by Deno │ @@ -76,85 +76,116 @@ invariants govern every design choice: (cross-repo; verisim REST :8080) historical proof_attempts table, mv_prover_success_by_class -``` - -## Tier overview - -ECHIDNA carries **128 ProverKind variants**. The exposed surface depends on tier: - -- **Tier 1 (12 core)** — the default REST `/api/verify` surface: Coq/Rocq, Lean 4, - Agda, Isabelle/HOL, Idris 2, F*, Z3, CVC5, Alt-Ergo, Dafny, Vampire, E Prover. -- **Tier 2–10** — 116 additional backends: ATPs, SMT, model checkers, constraint - solvers, niche provers, ecosystem type-checkers. Available via explicit - `ProverKind` selection in CLI / REPL / GraphQL but not auto-routed. - -See [`PROVER_COUNT.md`](PROVER_COUNT.md) for the canonical tier table and -per-prover capabilities. - -## Trust pipeline walkthrough - -Each `verify_proof` call passes through (under `--features verisim`, eventually -in default builds; see [`handover/TODO.md`](handover/TODO.md) for current state): - -1. **Integrity** (`integrity/`) — solver binary SHAKE3-512 + BLAKE3 against - `config/solver-manifest.toml`. -2. **Dispatch** (`dispatch.rs`) — `ProverDispatcher::select_prover` picks the - backend; under `with_verisim`, `VeriSimAdvisor` queries - `mv_prover_success_by_class` for historical success-rate hints. -3. **Sandbox** (`executor/`) — Podman or bubblewrap process containment. -4. **Portfolio cross-check** (`verification/portfolio.rs`) — for SMT, run two - independent solvers; ✓ if both agree. -5. **Certificate verification** (`verification/certificates.rs`) — replay - Alethe / DRAT-LRAT / TSTP independently of the originating solver. -6. **Axiom tracking** (`verification/axiom_tracker.rs`) — 4 danger levels - (Safe, Noted, Warning, Reject). -7. **Confidence** (`verification/confidence.rs`) — 5-tier Bayesian trust score. -8. **Mutation testing** (`verification/mutation.rs`) — for specifications. -9. **Pareto** (`verification/pareto.rs`) — multi-objective frontier across - speed / trust / certificate availability. -10. **Statistics** (`verification/statistics.rs`) — per-(prover, domain) success - rates; exported to `/training/update` for online ML weight updates. -11. **Outcome emission** (`dispatch.rs::spawn_record_attempt`, gated on - `with_verisim_writer`) — fire-and-forget write to VeriSimDB - `proof_attempts`, closes the learning loop. - -## Polyglot source layout - -`src/` holds one subdirectory per language. The split is intentional — see -[`RSR_COMPLIANCE.adoc`](../RSR_COMPLIANCE.adoc) §"Out-of-template adaptations". - -| Path | Language | Role | -|---|---|---| -| `src/rust/` | Rust | Core: backends, dispatch, trust pipeline, CLI, REPL, server | -| `crates/` | Rust | Extracted workspace members (`echidna-core`, `-mcp`, `-wire`, `-core-spark`, `typed_wasm`) | -| `src/julia/` | Julia | ML sidecar (GNN, logistic regression, training, eval) | -| `src/abi/` | Idris 2 | Formal ABI proofs (16 modules, zero `believe_me`) | -| `src/idris/` | Idris 2 | UI validator | -| `src/chapel/` | Chapel | Parallel proof search (L2.1 live; L2.2+ gated) | -| `src/zig_ffi/` | Zig | Chapel-bridge FFI shim | -| `ffi/zig/` | Zig | Overlay / tentacles / boj sources | -| `src/ada/` | Ada + SPARK | Formal companion library | -| `src/affinescript/` | AffineScript → AffineScript | UI (migration in progress) | -| `src/ui/` | static assets | Public UI files | -| `src/interfaces/` | Rust | GraphQL, gRPC, REST workspace crates | - -## Internal IPC +.... + +=== Tier overview + +ECHIDNA carries *128 ProverKind variants*. The exposed surface depends +on tier: + +* *Tier 1 (12 core)* — the default REST `+/api/verify+` surface: +Coq/Rocq, Lean 4, Agda, Isabelle/HOL, Idris 2, F*, Z3, CVC5, Alt-Ergo, +Dafny, Vampire, E Prover. +* *Tier 2–10* — 116 additional backends: ATPs, SMT, model checkers, +constraint solvers, niche provers, ecosystem type-checkers. Available +via explicit `+ProverKind+` selection in CLI / REPL / GraphQL but not +auto-routed. + +See link:PROVER_COUNT.md[`+PROVER_COUNT.md+`] for the canonical tier +table and per-prover capabilities. + +=== Trust pipeline walkthrough + +Each `+verify_proof+` call passes through (under `+--features verisim+`, +eventually in default builds; see +link:handover/TODO.md[`+handover/TODO.md+`] for current state): + +[arabic] +. *Integrity* (`+integrity/+`) — solver binary SHAKE3-512 + BLAKE3 +against `+config/solver-manifest.toml+`. +. *Dispatch* (`+dispatch.rs+`) — `+ProverDispatcher::select_prover+` +picks the backend; under `+with_verisim+`, `+VeriSimAdvisor+` queries +`+mv_prover_success_by_class+` for historical success-rate hints. +. *Sandbox* (`+executor/+`) — Podman or bubblewrap process containment. +. *Portfolio cross-check* (`+verification/portfolio.rs+`) — for SMT, run +two independent solvers; ✓ if both agree. +. *Certificate verification* (`+verification/certificates.rs+`) — replay +Alethe / DRAT-LRAT / TSTP independently of the originating solver. +. *Axiom tracking* (`+verification/axiom_tracker.rs+`) — 4 danger levels +(Safe, Noted, Warning, Reject). +. *Confidence* (`+verification/confidence.rs+`) — 5-tier Bayesian trust +score. +. *Mutation testing* (`+verification/mutation.rs+`) — for +specifications. +. *Pareto* (`+verification/pareto.rs+`) — multi-objective frontier +across speed / trust / certificate availability. +. *Statistics* (`+verification/statistics.rs+`) — per-(prover, domain) +success rates; exported to `+/training/update+` for online ML weight +updates. +. *Outcome emission* (`+dispatch.rs::spawn_record_attempt+`, gated on +`+with_verisim_writer+`) — fire-and-forget write to VeriSimDB +`+proof_attempts+`, closes the learning loop. + +=== Polyglot source layout + +`+src/+` holds one subdirectory per language. The split is intentional — +see link:../RSR_COMPLIANCE.adoc[`+RSR_COMPLIANCE.adoc+`] +§"`Out-of-template adaptations`". + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Path |Language |Role +|`+src/rust/+` |Rust |Core: backends, dispatch, trust pipeline, CLI, +REPL, server + +|`+crates/+` |Rust |Extracted workspace members (`+echidna-core+`, +`+-mcp+`, `+-wire+`, `+-core-spark+`, `+typed_wasm+`) + +|`+src/julia/+` |Julia |ML sidecar (GNN, logistic regression, training, +eval) + +|`+src/abi/+` |Idris 2 |Formal ABI proofs (16 modules, zero +`+believe_me+`) + +|`+src/idris/+` |Idris 2 |UI validator + +|`+src/chapel/+` |Chapel |Parallel proof search (L2.1 live; L2.2+ gated) + +|`+src/zig_ffi/+` |Zig |Chapel-bridge FFI shim + +|`+ffi/zig/+` |Zig |Overlay / tentacles / boj sources + +|`+src/ada/+` |Ada + SPARK |Formal companion library + +|`+src/affinescript/+` |AffineScript → AffineScript |UI (migration in +progress) + +|`+src/ui/+` |static assets |Public UI files + +|`+src/interfaces/+` |Rust |GraphQL, gRPC, REST workspace crates +|=== + +=== Internal IPC Today: HTTP + JSON between Rust core and Julia sidecar on port 8090. -Endpoints — `POST /gnn/rank`, `POST /gnn/embed`, `POST /training/update`, -`POST /gnn/health`, plus `POST /reload` (planned port from the orphaned -`api_server.jl`). - -Planned (Stage 5a / L1): Cap'n Proto over Unix domain socket; HTTP+JSON -retained only as debug fallback. See [`docs/handover/L1-CAPNPROTO-PROMPT.md`](handover/L1-CAPNPROTO-PROMPT.md). - -## Where to go next - -- [`docs/ROADMAP.md`](ROADMAP.md) — canonical stage map and sprint targets. -- [`docs/handover/STATE.md`](handover/STATE.md) — running session log. -- [`docs/handover/HANDOVER-INDEX.md`](handover/HANDOVER-INDEX.md) — guide to the - handover/ prompt suite. -- [`docs/ENV-VARS.md`](ENV-VARS.md) — every environment variable the system - reads, with defaults. -- [`docs/PROVER_COUNT.md`](PROVER_COUNT.md) — canonical tier table. -- [`.machine_readable/descriptiles/STATE.a2ml`](../.machine_readable/descriptiles/STATE.a2ml) — machine-readable state, regenerated each sprint. +Endpoints — `+POST /gnn/rank+`, `+POST /gnn/embed+`, +`+POST /training/update+`, `+POST /gnn/health+`, plus `+POST /reload+` +(planned port from the orphaned `+api_server.jl+`). + +Planned (Stage 5a / L1): Cap’n Proto over Unix domain socket; HTTP+JSON +retained only as debug fallback. See +link:handover/L1-CAPNPROTO-PROMPT.md[`+docs/handover/L1-CAPNPROTO-PROMPT.md+`]. + +=== Where to go next + +* link:ROADMAP.md[`+docs/ROADMAP.md+`] — canonical stage map and sprint +targets. +* link:handover/STATE.md[`+docs/handover/STATE.md+`] — running session +log. +* link:handover/HANDOVER-INDEX.md[`+docs/handover/HANDOVER-INDEX.md+`] — +guide to the handover/ prompt suite. +* link:ENV-VARS.md[`+docs/ENV-VARS.md+`] — every environment variable +the system reads, with defaults. +* link:PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`] — canonical tier table. +* link:../.machine_readable/descriptiles/STATE.a2ml[`+.machine_readable/descriptiles/STATE.a2ml+`] +— machine-readable state, regenerated each sprint. diff --git a/docs/ASPECT_IMPLEMENTATION_SUMMARY.adoc b/docs/ASPECT_IMPLEMENTATION_SUMMARY.adoc new file mode 100644 index 00000000..1c9ec884 --- /dev/null +++ b/docs/ASPECT_IMPLEMENTATION_SUMMARY.adoc @@ -0,0 +1,434 @@ +== Aspect Tagging System - Implementation Summary + +=== Overview + +Successfully implemented a production-ready, comprehensive aspect +tagging system for ECHIDNA at `+/home/user/echidna/src/rust/aspect.rs+`. + +=== Implementation Statistics + +* *Total Lines*: 1,156 lines of Rust code +* *Functions*: 46 functions (public and private) +* *Public Types*: 8 public types/enums/structs +* *Unit Tests*: 12 comprehensive tests +* *Aspects*: 60 mathematical/logical aspects +* *Categories*: 10 high-level categories +* *Keyword Rules*: 100+ keyword-to-aspect mappings +* *Symbol Rules*: 20+ mathematical symbol mappings + +=== Components Implemented + +==== 1. Aspect Enum (60 Aspects) + +Comprehensive classification covering: + +===== Logic (7 aspects) + +* PropositionalLogic, PredicateLogic, ModalLogic, TemporalLogic +* HigherOrderLogic, IntuitionisticLogic, ClassicalLogic + +===== Arithmetic (7 aspects) + +* NaturalNumbers, Integers, Rationals, Reals, Complex +* NumberTheory, Arithmetic + +===== Algebra (8 aspects) + +* Groups, Rings, Fields, VectorSpaces, Modules +* Lattices, CategoryTheory, UniversalAlgebra + +===== Analysis (7 aspects) + +* Limits, Continuity, Derivatives, Integrals +* Sequences, MeasureTheory, FunctionalAnalysis + +===== Topology (5 aspects) + +* MetricSpaces, TopologicalSpaces, Compactness +* Connectedness, TopologicalContinuity + +===== Set Theory (5 aspects) + +* SetOperations, Cardinality, Ordinals +* AxiomOfChoice, ZFC + +===== Type Theory (6 aspects) + +* DependentTypes, Universes, InductiveTypes +* CoinductiveTypes, Polymorphism, TypeEquivalence + +===== Computer Science (8 aspects) + +* Algorithms, Complexity, FormalVerification +* ProgramSemantics, Concurrency, Cryptography +* Automata, LambdaCalculus + +===== Proof Techniques (6 aspects) + +* Induction, Coinduction, Recursion +* CaseAnalysis, Contradiction, DirectProof + +===== Other (6 aspects) + +* Combinatorics, GraphTheory, Probability +* GameTheory, Geometry, AbstractNonsense + +*Features*: - Human-readable names via `+name()+` method - Category +grouping via `+category()+` method - Display trait for pretty printing - +Serialization support (Serde) + +==== 2. AspectCategory Enum + +High-level categorization: - Logic, Arithmetic, Algebra, Analysis, +Topology - SetTheory, TypeTheory, ComputerScience, ProofTechniques, +Other + +==== 3. TheoremFeatures Struct + +Extracted features for classification: - `+symbols: HashSet+` - +All symbols in theorem - `+keywords: HashSet+` - Keywords from +name - `+patterns: HashSet+` - Structural patterns - +`+quantifier_count: usize+` - Number of ∀, ∃ - `+lambda_depth: usize+` - +Maximum lambda nesting - `+pi_count: usize+` - Number of dependent types +- `+universe_levels: HashSet+` - Type universe levels - +`+app_depth: usize+` - Function application depth + +==== 4. AspectTagger Trait + +Standard interface for all taggers: + +[source,rust] +---- +pub trait AspectTagger: Send + Sync { + fn tag(&self, theorem_name: &str, statement: &Term) -> Vec; + fn extract_features(&self, statement: &Term) -> TheoremFeatures; + fn tag_with_confidence(&self, theorem_name: &str, statement: &Term) -> HashMap; +} +---- + +*Features*: - Thread-safe (Send + Sync) - Confidence scores (0.0-1.0) - +Optional feature extraction - Multi-label classification + +==== 5. RuleBasedTagger + +Heuristic keyword and pattern matching tagger. + +*Keyword Rules* (100+): - Logic: "`prop`", "`predicate`", "`modal`", +"`temporal`", "`forall`", "`exists`" - Arithmetic: "`nat`", "`int`", +"`real`", "`complex`", "`prime`", "`add`", "`mult`" - Algebra: +"`group`", "`ring`", "`field`", "`vector`", "`lattice`", "`category`" - +Analysis: "`limit`", "`continuous`", "`derivative`", "`integral`", +"`sequence`" - Topology: "`metric`", "`topological`", "`compact`", +"`connected`" - Set Theory: "`set`", "`union`", "`cardinality`", +"`ordinal`", "`choice`" - Type Theory: "`dependent`", "`universe`", +"`inductive`", "`polymorphic`" - Computer Science: "`algorithm`", +"`complexity`", "`verify`", "`concurrent`" - Proof Techniques: +"`induction`", "`recursion`", "`case`", "`contradiction`" + +*Symbol Rules* (20+): - Logical: ∀, ∃, ∧, ∨, ¬, →, ↔, □, ◇ - Arithmetic: +ℕ, ℤ, ℚ, ℝ, ℂ - Set Theory: ∪, ∩, ⊆, ∈ - Analysis: lim, ∫, ∑, ∏ - Type +Theory: λ, Π + +*Structural Analysis*: - Quantifier detection (forall, exists, ∀, ∃) - +Lambda abstraction depth tracking - Pi type (dependent function) +counting - Universe level extraction - Application depth analysis + +*Configuration*: - Configurable confidence threshold (default: 0.3) - +Add custom keyword/symbol rules - Extract detailed features + +*Methods*: - `+new()+` - Create with default rules - +`+with_threshold(f64)+` - Custom threshold - +`+add_keyword_rule(keyword, aspects)+` - Add custom rule - +`+add_symbol_rule(symbol, aspects)+` - Add custom symbol - +`+extract_keywords(name)+` - Extract from theorem name - +`+extract_symbols(term)+` - Extract from statement + +==== 6. NeuralTagger + +ML-based classification with Julia integration. + +*Features*: - Embeddings from theorem statements - Multi-label +classification - Julia ML service integration (HTTP or FFI) - +Configurable threshold (default: 0.5) - Service URL configuration + +*Integration Points*: - `+get_embeddings(statement)+` - Convert term to +vector - `+classify_embeddings(embeddings)+` - Predict aspects - Julia +HTTP service support - Async/await support + +*Methods*: - `+new()+` - Create with defaults - `+with_threshold(f64)+` +- Custom threshold - `+with_service_url(url)+` - Set Julia service + +*Status*: Stub implementation with TODO markers for Julia integration + +==== 7. OpenCycTagger + +Ontology-based semantic tagging using OpenCyc. + +*Features*: - Maps concepts to OpenCyc ontology - Semantic relationship +inference - Cached concept mappings - Async concept queries + +*Methods*: - `+new(service_url)+` - Create with OpenCyc URL - +`+query_concept(concept)+` - Query ontology + +*Status*: Stub implementation with TODO markers for OpenCyc API +integration + +==== 8. CompositeTagger + +Combines multiple tagging strategies. + +*Aggregation Strategies*: 1. *Union* - All aspects from all taggers +(maximum recall) 2. *Intersection* - Only common aspects (maximum +precision) 3. *WeightedVoting* - Weighted confidence scores (threshold: +0.3) 4. *Majority* - Aspects with >50% vote (threshold: 0.5) + +*Features*: - Multiple tagger support - Configurable weights per tagger +- Confidence score aggregation - Flexible strategy selection + +*Methods*: - `+new(strategy)+` - Create with aggregation strategy - +`+add_tagger(tagger, weight)+` - Add weighted tagger + +=== Test Coverage + +==== Unit Tests (12 tests) + +[arabic] +. *test_aspect_categories* - Verify aspect category mappings +. *test_aspect_names* - Verify human-readable names +. *test_rule_based_tagger_keywords* - Test keyword matching +. *test_rule_based_tagger_structure* - Test structural analysis +. *test_rule_based_tagger_quantifiers* - Test quantifier detection +. *test_feature_extraction* - Test feature extraction +. *test_composite_tagger_union* - Test union strategy +. *test_confidence_scores* - Test confidence scoring +. *test_multi_aspect_tagging* - Test multi-label classification +. *test_threshold_filtering* - Test threshold-based filtering +. *test_category_theory_aspects* - Test category theory detection +. *test_induction_detection* - Test induction detection + +*Test Coverage*: - All major components tested - Keyword and symbol +matching verified - Structural analysis validated - Confidence scoring +checked - Aggregation strategies tested - Edge cases covered + +=== Documentation + +==== Created Files + +[arabic] +. *`+/home/user/echidna/src/rust/aspect.rs+`* (1,156 lines) +* Complete implementation +* Comprehensive inline documentation +* 12 unit tests +. *`+/home/user/echidna/docs/ASPECT_TAGGING.md+`* +* Architecture overview +* Usage examples +* Integration guide +* Performance considerations +* Future enhancements +. *`+/home/user/echidna/examples/aspect_tagging_demo.rs+`* +* 9 practical examples +* Demonstrates all major features +* Runnable demo program +. *`+/home/user/echidna/docs/ASPECT_IMPLEMENTATION_SUMMARY.md+`* (this +file) +* Implementation overview +* Component details +* Statistics and metrics + +==== Inline Documentation + +* Module-level documentation (//!) +* Comprehensive function documentation +* Type and struct documentation +* Example code in docs +* TODO markers for future work + +=== Integration Points + +==== With ECHIDNA Core + +* Uses `+crate::core::Term+` for theorem representation +* Integrates with `+Theorem+` struct (has `+aspects: Vec+` +field) +* Compatible with all 12 prover backends +* Works with `+ProofState+` and `+Context+` + +==== With Neural Components (Julia) + +* `+NeuralTagger+` designed for Julia ML integration +* Embeddings interface for neural models +* HTTP service support for remote inference +* Async/await for non-blocking calls + +==== With OpenCyc + +* `+OpenCycTagger+` for ontology-based tagging +* Concept mapping support +* Semantic relationship queries +* Cached mappings for performance + +==== With Premise Selection + +* Aspect-based filtering of relevant theorems +* Multi-aspect matching for similarity +* Confidence-weighted ranking + +=== Code Quality + +==== Best Practices + +* ✅ SPDX license headers (MIT OR Palimpsest-0.6) +* ✅ Comprehensive documentation +* ✅ Thread-safe design (Send + Sync) +* ✅ Error handling preparation +* ✅ Serde serialization support +* ✅ Builder pattern (CompositeTagger) +* ✅ Default implementations +* ✅ Trait-based polymorphism +* ✅ Test-driven development + +==== Performance + +* *RuleBasedTagger*: O(n) keyword matching, very fast +* *Feature extraction*: O(n) tree traversal +* *Symbol extraction*: O(n) recursive traversal +* *Confidence scoring*: O(m) where m = number of aspects +* *Composite aggregation*: O(k*m) where k = number of taggers + +==== Memory + +* Efficient HashSet/HashMap usage +* No unnecessary cloning +* Shared keyword/symbol rules +* Cached concept mappings (OpenCyc) + +=== Usage Examples + +==== Basic Tagging + +[source,rust] +---- +let tagger = RuleBasedTagger::new(); +let aspects = tagger.tag("nat_add_comm", &statement); +// Returns: [Arithmetic, NaturalNumbers] +---- + +==== With Confidence + +[source,rust] +---- +let scores = tagger.tag_with_confidence("group_homomorphism", &statement); +// Returns: {Groups: 0.50, Algebra: 0.25, ...} +---- + +==== Feature Extraction + +[source,rust] +---- +let features = tagger.extract_features(&statement); +// Returns: TheoremFeatures { lambda_depth: 2, quantifier_count: 1, ... } +---- + +==== Composite Strategy + +[source,rust] +---- +let composite = CompositeTagger::new(AggregationStrategy::WeightedVoting) + .add_tagger(Box::new(RuleBasedTagger::new()), 0.7) + .add_tagger(Box::new(NeuralTagger::new()), 0.3); +let aspects = composite.tag(name, &statement); +---- + +=== Future Work + +==== Immediate (TODO markers in code) + +[arabic] +. *Julia Integration* - Implement `+NeuralTagger::get_embeddings()+` and +`+classify_embeddings()+` +. *OpenCyc Integration* - Implement `+OpenCycTagger::query_concept()+` +. *Error Handling* - Add proper Result<> types with custom error types +. *Async Neural Tagger* - Full async implementation for `+NeuralTagger+` + +==== Near-term Enhancements + +[arabic] +. *Active Learning* - Identify low-confidence theorems for manual +tagging +. *Fine-tuning* - Train neural tagger on prover-specific corpora +. *Performance Optimization* - Cache frequently-used results +. *Advanced Features* - Proof complexity, dependency depth + +==== Long-term Vision + +[arabic] +. *Hierarchical Taxonomy* - Multi-level aspect classification +. *Cross-Prover Mapping* - Align aspects across provers +. *Temporal Tracking* - Aspect usage over time +. *User Feedback Loop* - Incorporate corrections +. *Recommendation System* - Suggest relevant theorems + +=== Compliance + +==== RSR/CCCP Standards + +* ✅ SPDX license headers on all files +* ✅ Dual licensing (MIT OR Palimpsest-0.6) +* ✅ 2025 copyright notice +* ✅ Clean module structure +* ✅ Comprehensive documentation + +==== Code Standards + +* ✅ Rust 2021 edition +* ✅ Clippy-clean (no warnings in aspect.rs) +* ✅ Formatted with rustfmt +* ✅ No unsafe code +* ✅ Thread-safe design + +=== Integration Status + +==== Ready to Use + +* ✅ *RuleBasedTagger* - Production ready +* ✅ *CompositeTagger* - Production ready +* ✅ *Aspect enum* - Complete +* ✅ *TheoremFeatures* - Complete +* ✅ *AspectTagger trait* - Complete + +==== Stub/Template + +* ⏳ *NeuralTagger* - Awaits Julia ML integration +* ⏳ *OpenCycTagger* - Awaits OpenCyc API integration + +==== Next Steps + +[arabic] +. *Build & Test* - Resolve unrelated compilation errors in provers +. *Julia Integration* - Implement neural classification service +. *OpenCyc Setup* - Configure ontology service +. *Benchmark* - Performance testing with real theorem corpus +. *Deployment* - Integration into ECHIDNA pipeline + +=== Conclusion + +Successfully implemented a comprehensive, production-ready aspect +tagging system for ECHIDNA with: + +* *60 mathematical/logical aspects* covering major domains +* *4 tagging strategies* (rule-based, neural, ontology, composite) +* *100+ keyword rules* and *20+ symbol rules* +* *Multi-label classification* with confidence scores +* *Feature extraction* for structural analysis +* *12 comprehensive tests* validating all major features +* *Complete documentation* with examples and usage guide + +The system is designed to significantly improve premise selection and +neural learning in the ECHIDNA neurosymbolic theorem proving platform. + +''''' + +*File*: `+/home/user/echidna/src/rust/aspect.rs+` *Lines*: 1,156 +*Tests*: 12 *Documentation*: Complete *Status*: Production Ready +(RuleBasedTagger, CompositeTagger) *License*: MIT OR Palimpsest-0.6 +*Date*: 2025-11-22 diff --git a/docs/ASPECT_IMPLEMENTATION_SUMMARY.md b/docs/ASPECT_IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index db328d44..00000000 --- a/docs/ASPECT_IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,446 +0,0 @@ -# Aspect Tagging System - Implementation Summary - -## Overview - -Successfully implemented a production-ready, comprehensive aspect tagging system for ECHIDNA at `/home/user/echidna/src/rust/aspect.rs`. - -## Implementation Statistics - -- **Total Lines**: 1,156 lines of Rust code -- **Functions**: 46 functions (public and private) -- **Public Types**: 8 public types/enums/structs -- **Unit Tests**: 12 comprehensive tests -- **Aspects**: 60 mathematical/logical aspects -- **Categories**: 10 high-level categories -- **Keyword Rules**: 100+ keyword-to-aspect mappings -- **Symbol Rules**: 20+ mathematical symbol mappings - -## Components Implemented - -### 1. Aspect Enum (60 Aspects) - -Comprehensive classification covering: - -#### Logic (7 aspects) -- PropositionalLogic, PredicateLogic, ModalLogic, TemporalLogic -- HigherOrderLogic, IntuitionisticLogic, ClassicalLogic - -#### Arithmetic (7 aspects) -- NaturalNumbers, Integers, Rationals, Reals, Complex -- NumberTheory, Arithmetic - -#### Algebra (8 aspects) -- Groups, Rings, Fields, VectorSpaces, Modules -- Lattices, CategoryTheory, UniversalAlgebra - -#### Analysis (7 aspects) -- Limits, Continuity, Derivatives, Integrals -- Sequences, MeasureTheory, FunctionalAnalysis - -#### Topology (5 aspects) -- MetricSpaces, TopologicalSpaces, Compactness -- Connectedness, TopologicalContinuity - -#### Set Theory (5 aspects) -- SetOperations, Cardinality, Ordinals -- AxiomOfChoice, ZFC - -#### Type Theory (6 aspects) -- DependentTypes, Universes, InductiveTypes -- CoinductiveTypes, Polymorphism, TypeEquivalence - -#### Computer Science (8 aspects) -- Algorithms, Complexity, FormalVerification -- ProgramSemantics, Concurrency, Cryptography -- Automata, LambdaCalculus - -#### Proof Techniques (6 aspects) -- Induction, Coinduction, Recursion -- CaseAnalysis, Contradiction, DirectProof - -#### Other (6 aspects) -- Combinatorics, GraphTheory, Probability -- GameTheory, Geometry, AbstractNonsense - -**Features**: -- Human-readable names via `name()` method -- Category grouping via `category()` method -- Display trait for pretty printing -- Serialization support (Serde) - -### 2. AspectCategory Enum - -High-level categorization: -- Logic, Arithmetic, Algebra, Analysis, Topology -- SetTheory, TypeTheory, ComputerScience, ProofTechniques, Other - -### 3. TheoremFeatures Struct - -Extracted features for classification: -- `symbols: HashSet` - All symbols in theorem -- `keywords: HashSet` - Keywords from name -- `patterns: HashSet` - Structural patterns -- `quantifier_count: usize` - Number of ∀, ∃ -- `lambda_depth: usize` - Maximum lambda nesting -- `pi_count: usize` - Number of dependent types -- `universe_levels: HashSet` - Type universe levels -- `app_depth: usize` - Function application depth - -### 4. AspectTagger Trait - -Standard interface for all taggers: - -```rust -pub trait AspectTagger: Send + Sync { - fn tag(&self, theorem_name: &str, statement: &Term) -> Vec; - fn extract_features(&self, statement: &Term) -> TheoremFeatures; - fn tag_with_confidence(&self, theorem_name: &str, statement: &Term) -> HashMap; -} -``` - -**Features**: -- Thread-safe (Send + Sync) -- Confidence scores (0.0-1.0) -- Optional feature extraction -- Multi-label classification - -### 5. RuleBasedTagger - -Heuristic keyword and pattern matching tagger. - -**Keyword Rules** (100+): -- Logic: "prop", "predicate", "modal", "temporal", "forall", "exists" -- Arithmetic: "nat", "int", "real", "complex", "prime", "add", "mult" -- Algebra: "group", "ring", "field", "vector", "lattice", "category" -- Analysis: "limit", "continuous", "derivative", "integral", "sequence" -- Topology: "metric", "topological", "compact", "connected" -- Set Theory: "set", "union", "cardinality", "ordinal", "choice" -- Type Theory: "dependent", "universe", "inductive", "polymorphic" -- Computer Science: "algorithm", "complexity", "verify", "concurrent" -- Proof Techniques: "induction", "recursion", "case", "contradiction" - -**Symbol Rules** (20+): -- Logical: ∀, ∃, ∧, ∨, ¬, →, ↔, □, ◇ -- Arithmetic: ℕ, ℤ, ℚ, ℝ, ℂ -- Set Theory: ∪, ∩, ⊆, ∈ -- Analysis: lim, ∫, ∑, ∏ -- Type Theory: λ, Π - -**Structural Analysis**: -- Quantifier detection (forall, exists, ∀, ∃) -- Lambda abstraction depth tracking -- Pi type (dependent function) counting -- Universe level extraction -- Application depth analysis - -**Configuration**: -- Configurable confidence threshold (default: 0.3) -- Add custom keyword/symbol rules -- Extract detailed features - -**Methods**: -- `new()` - Create with default rules -- `with_threshold(f64)` - Custom threshold -- `add_keyword_rule(keyword, aspects)` - Add custom rule -- `add_symbol_rule(symbol, aspects)` - Add custom symbol -- `extract_keywords(name)` - Extract from theorem name -- `extract_symbols(term)` - Extract from statement - -### 6. NeuralTagger - -ML-based classification with Julia integration. - -**Features**: -- Embeddings from theorem statements -- Multi-label classification -- Julia ML service integration (HTTP or FFI) -- Configurable threshold (default: 0.5) -- Service URL configuration - -**Integration Points**: -- `get_embeddings(statement)` - Convert term to vector -- `classify_embeddings(embeddings)` - Predict aspects -- Julia HTTP service support -- Async/await support - -**Methods**: -- `new()` - Create with defaults -- `with_threshold(f64)` - Custom threshold -- `with_service_url(url)` - Set Julia service - -**Status**: Stub implementation with TODO markers for Julia integration - -### 7. OpenCycTagger - -Ontology-based semantic tagging using OpenCyc. - -**Features**: -- Maps concepts to OpenCyc ontology -- Semantic relationship inference -- Cached concept mappings -- Async concept queries - -**Methods**: -- `new(service_url)` - Create with OpenCyc URL -- `query_concept(concept)` - Query ontology - -**Status**: Stub implementation with TODO markers for OpenCyc API integration - -### 8. CompositeTagger - -Combines multiple tagging strategies. - -**Aggregation Strategies**: -1. **Union** - All aspects from all taggers (maximum recall) -2. **Intersection** - Only common aspects (maximum precision) -3. **WeightedVoting** - Weighted confidence scores (threshold: 0.3) -4. **Majority** - Aspects with >50% vote (threshold: 0.5) - -**Features**: -- Multiple tagger support -- Configurable weights per tagger -- Confidence score aggregation -- Flexible strategy selection - -**Methods**: -- `new(strategy)` - Create with aggregation strategy -- `add_tagger(tagger, weight)` - Add weighted tagger - -## Test Coverage - -### Unit Tests (12 tests) - -1. **test_aspect_categories** - Verify aspect category mappings -2. **test_aspect_names** - Verify human-readable names -3. **test_rule_based_tagger_keywords** - Test keyword matching -4. **test_rule_based_tagger_structure** - Test structural analysis -5. **test_rule_based_tagger_quantifiers** - Test quantifier detection -6. **test_feature_extraction** - Test feature extraction -7. **test_composite_tagger_union** - Test union strategy -8. **test_confidence_scores** - Test confidence scoring -9. **test_multi_aspect_tagging** - Test multi-label classification -10. **test_threshold_filtering** - Test threshold-based filtering -11. **test_category_theory_aspects** - Test category theory detection -12. **test_induction_detection** - Test induction detection - -**Test Coverage**: -- All major components tested -- Keyword and symbol matching verified -- Structural analysis validated -- Confidence scoring checked -- Aggregation strategies tested -- Edge cases covered - -## Documentation - -### Created Files - -1. **`/home/user/echidna/src/rust/aspect.rs`** (1,156 lines) - - Complete implementation - - Comprehensive inline documentation - - 12 unit tests - -2. **`/home/user/echidna/docs/ASPECT_TAGGING.md`** - - Architecture overview - - Usage examples - - Integration guide - - Performance considerations - - Future enhancements - -3. **`/home/user/echidna/examples/aspect_tagging_demo.rs`** - - 9 practical examples - - Demonstrates all major features - - Runnable demo program - -4. **`/home/user/echidna/docs/ASPECT_IMPLEMENTATION_SUMMARY.md`** (this file) - - Implementation overview - - Component details - - Statistics and metrics - -### Inline Documentation - -- Module-level documentation (//!) -- Comprehensive function documentation -- Type and struct documentation -- Example code in docs -- TODO markers for future work - -## Integration Points - -### With ECHIDNA Core - -- Uses `crate::core::Term` for theorem representation -- Integrates with `Theorem` struct (has `aspects: Vec` field) -- Compatible with all 12 prover backends -- Works with `ProofState` and `Context` - -### With Neural Components (Julia) - -- `NeuralTagger` designed for Julia ML integration -- Embeddings interface for neural models -- HTTP service support for remote inference -- Async/await for non-blocking calls - -### With OpenCyc - -- `OpenCycTagger` for ontology-based tagging -- Concept mapping support -- Semantic relationship queries -- Cached mappings for performance - -### With Premise Selection - -- Aspect-based filtering of relevant theorems -- Multi-aspect matching for similarity -- Confidence-weighted ranking - -## Code Quality - -### Best Practices - -- ✅ SPDX license headers (MIT OR Palimpsest-0.6) -- ✅ Comprehensive documentation -- ✅ Thread-safe design (Send + Sync) -- ✅ Error handling preparation -- ✅ Serde serialization support -- ✅ Builder pattern (CompositeTagger) -- ✅ Default implementations -- ✅ Trait-based polymorphism -- ✅ Test-driven development - -### Performance - -- **RuleBasedTagger**: O(n) keyword matching, very fast -- **Feature extraction**: O(n) tree traversal -- **Symbol extraction**: O(n) recursive traversal -- **Confidence scoring**: O(m) where m = number of aspects -- **Composite aggregation**: O(k*m) where k = number of taggers - -### Memory - -- Efficient HashSet/HashMap usage -- No unnecessary cloning -- Shared keyword/symbol rules -- Cached concept mappings (OpenCyc) - -## Usage Examples - -### Basic Tagging - -```rust -let tagger = RuleBasedTagger::new(); -let aspects = tagger.tag("nat_add_comm", &statement); -// Returns: [Arithmetic, NaturalNumbers] -``` - -### With Confidence - -```rust -let scores = tagger.tag_with_confidence("group_homomorphism", &statement); -// Returns: {Groups: 0.50, Algebra: 0.25, ...} -``` - -### Feature Extraction - -```rust -let features = tagger.extract_features(&statement); -// Returns: TheoremFeatures { lambda_depth: 2, quantifier_count: 1, ... } -``` - -### Composite Strategy - -```rust -let composite = CompositeTagger::new(AggregationStrategy::WeightedVoting) - .add_tagger(Box::new(RuleBasedTagger::new()), 0.7) - .add_tagger(Box::new(NeuralTagger::new()), 0.3); -let aspects = composite.tag(name, &statement); -``` - -## Future Work - -### Immediate (TODO markers in code) - -1. **Julia Integration** - Implement `NeuralTagger::get_embeddings()` and `classify_embeddings()` -2. **OpenCyc Integration** - Implement `OpenCycTagger::query_concept()` -3. **Error Handling** - Add proper Result<> types with custom error types -4. **Async Neural Tagger** - Full async implementation for `NeuralTagger` - -### Near-term Enhancements - -1. **Active Learning** - Identify low-confidence theorems for manual tagging -2. **Fine-tuning** - Train neural tagger on prover-specific corpora -3. **Performance Optimization** - Cache frequently-used results -4. **Advanced Features** - Proof complexity, dependency depth - -### Long-term Vision - -1. **Hierarchical Taxonomy** - Multi-level aspect classification -2. **Cross-Prover Mapping** - Align aspects across provers -3. **Temporal Tracking** - Aspect usage over time -4. **User Feedback Loop** - Incorporate corrections -5. **Recommendation System** - Suggest relevant theorems - -## Compliance - -### RSR/CCCP Standards - -- ✅ SPDX license headers on all files -- ✅ Dual licensing (MIT OR Palimpsest-0.6) -- ✅ 2025 copyright notice -- ✅ Clean module structure -- ✅ Comprehensive documentation - -### Code Standards - -- ✅ Rust 2021 edition -- ✅ Clippy-clean (no warnings in aspect.rs) -- ✅ Formatted with rustfmt -- ✅ No unsafe code -- ✅ Thread-safe design - -## Integration Status - -### Ready to Use - -- ✅ **RuleBasedTagger** - Production ready -- ✅ **CompositeTagger** - Production ready -- ✅ **Aspect enum** - Complete -- ✅ **TheoremFeatures** - Complete -- ✅ **AspectTagger trait** - Complete - -### Stub/Template - -- ⏳ **NeuralTagger** - Awaits Julia ML integration -- ⏳ **OpenCycTagger** - Awaits OpenCyc API integration - -### Next Steps - -1. **Build & Test** - Resolve unrelated compilation errors in provers -2. **Julia Integration** - Implement neural classification service -3. **OpenCyc Setup** - Configure ontology service -4. **Benchmark** - Performance testing with real theorem corpus -5. **Deployment** - Integration into ECHIDNA pipeline - -## Conclusion - -Successfully implemented a comprehensive, production-ready aspect tagging system for ECHIDNA with: - -- **60 mathematical/logical aspects** covering major domains -- **4 tagging strategies** (rule-based, neural, ontology, composite) -- **100+ keyword rules** and **20+ symbol rules** -- **Multi-label classification** with confidence scores -- **Feature extraction** for structural analysis -- **12 comprehensive tests** validating all major features -- **Complete documentation** with examples and usage guide - -The system is designed to significantly improve premise selection and neural learning in the ECHIDNA neurosymbolic theorem proving platform. - ---- - -**File**: `/home/user/echidna/src/rust/aspect.rs` -**Lines**: 1,156 -**Tests**: 12 -**Documentation**: Complete -**Status**: Production Ready (RuleBasedTagger, CompositeTagger) -**License**: MIT OR Palimpsest-0.6 -**Date**: 2025-11-22 diff --git a/docs/ASPECT_QUICK_START.adoc b/docs/ASPECT_QUICK_START.adoc new file mode 100644 index 00000000..b6046739 --- /dev/null +++ b/docs/ASPECT_QUICK_START.adoc @@ -0,0 +1,181 @@ +== Aspect Tagging - Quick Start Guide + +=== TL;DR + +ECHIDNA’s aspect tagging system classifies theorems into 60 +mathematical/logical domains for better premise selection. + +=== Usage in 30 Seconds + +[source,rust] +---- +use echidna::aspect::{Aspect, AspectTagger, RuleBasedTagger}; +use echidna::core::Term; + +// Create tagger +let tagger = RuleBasedTagger::new(); + +// Tag theorem +let aspects = tagger.tag("nat_add_comm", &statement); + +// Get confidence scores +let scores = tagger.tag_with_confidence("theorem_name", &statement); +---- + +=== Key Files + +[width="99%",cols="30%,42%,28%",options="header",] +|=== +|File |Purpose |Size +|`+/home/user/echidna/src/rust/aspect.rs+` |Core implementation |1,156 +lines + +|`+/home/user/echidna/docs/ASPECT_TAGGING.md+` |Full documentation |11 +KB + +|`+/home/user/echidna/examples/aspect_tagging_demo.rs+` |Examples |6.5 +KB + +|`+/home/user/echidna/docs/ASPECT_IMPLEMENTATION_SUMMARY.md+` +|Implementation details |14 KB +|=== + +=== Key Components + +==== 1. Aspects (60 total) + +[source,rust] +---- +Aspect::PropositionalLogic // Logic +Aspect::NaturalNumbers // Arithmetic +Aspect::Groups // Algebra +Aspect::Limits // Analysis +Aspect::TopologicalSpaces // Topology +Aspect::DependentTypes // Type Theory +Aspect::Algorithms // Computer Science +Aspect::Induction // Proof Techniques +---- + +==== 2. Taggers + +[source,rust] +---- +// Rule-based (keyword/symbol matching) +let rule_tagger = RuleBasedTagger::new(); + +// Neural (Julia ML integration - stub) +let neural_tagger = NeuralTagger::new(); + +// OpenCyc (ontology - stub) +let cyc_tagger = OpenCycTagger::new("http://localhost:3601"); + +// Composite (combine multiple) +let composite = CompositeTagger::new(AggregationStrategy::WeightedVoting) + .add_tagger(Box::new(rule_tagger), 0.7) + .add_tagger(Box::new(neural_tagger), 0.3); +---- + +==== 3. Features + +[source,rust] +---- +let features = tagger.extract_features(&statement); +println!("Lambda depth: {}", features.lambda_depth); +println!("Quantifiers: {}", features.quantifier_count); +println!("Symbols: {:?}", features.symbols); +---- + +=== Common Patterns + +==== Tag All Theorems in Context + +[source,rust] +---- +for theorem in &mut context.theorems { + theorem.aspects = tagger.tag(&theorem.name, &theorem.statement) + .into_iter() + .map(|a| a.to_string()) + .collect(); +} +---- + +==== Filter by Aspect + +[source,rust] +---- +let arithmetic_theorems: Vec<_> = theorems.iter() + .filter(|t| t.aspects.contains(&"Arithmetic".to_string())) + .collect(); +---- + +==== Custom Rules + +[source,rust] +---- +let mut tagger = RuleBasedTagger::new(); +tagger.add_keyword_rule("banach", vec![ + Aspect::FunctionalAnalysis, + Aspect::MetricSpaces, +]); +---- + +=== Run Examples + +[source,bash] +---- +# Build +cargo build + +# Run demo +cargo run --example aspect_tagging_demo + +# Run tests +cargo test --lib aspect +---- + +=== Status + +✅ *Production Ready*: - RuleBasedTagger (100+ rules) - CompositeTagger +(4 strategies) - 60 aspects, 10 categories - 12 comprehensive tests + +⏳ *Stub (needs integration)*: - NeuralTagger (Julia ML) - OpenCycTagger +(OpenCyc API) + +=== Quick Reference: Aspect Categories + +[cols=",,",options="header",] +|=== +|Category |Count |Examples +|Logic |7 |Propositional, Predicate, Modal +|Arithmetic |7 |Natural Numbers, Integers, Reals +|Algebra |8 |Groups, Rings, Fields +|Analysis |7 |Limits, Continuity, Derivatives +|Topology |5 |Metric Spaces, Compactness +|Set Theory |5 |Set Operations, Cardinality +|Type Theory |6 |Dependent Types, Universes +|Computer Science |8 |Algorithms, Complexity +|Proof Techniques |6 |Induction, Recursion +|Other |6 |Combinatorics, Graph Theory +|=== + +=== Integration Checklist + +* [ ] Tag theorems during proof parsing +* [ ] Use aspects for premise selection +* [ ] Integrate with neural models (Julia) +* [ ] Add aspect-based search/filtering +* [ ] Export aspects to prover formats +* [ ] Track aspect statistics +* [ ] Build aspect-based recommendations + +=== Learn More + +* *Full Documentation*: `+/home/user/echidna/docs/ASPECT_TAGGING.md+` +* *Implementation Details*: +`+/home/user/echidna/docs/ASPECT_IMPLEMENTATION_SUMMARY.md+` +* *Examples*: `+/home/user/echidna/examples/aspect_tagging_demo.rs+` +* *Source Code*: `+/home/user/echidna/src/rust/aspect.rs+` + +=== License + +SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/docs/ASPECT_QUICK_START.md b/docs/ASPECT_QUICK_START.md deleted file mode 100644 index 79170fe7..00000000 --- a/docs/ASPECT_QUICK_START.md +++ /dev/null @@ -1,164 +0,0 @@ -# Aspect Tagging - Quick Start Guide - -## TL;DR - -ECHIDNA's aspect tagging system classifies theorems into 60 mathematical/logical domains for better premise selection. - -## Usage in 30 Seconds - -```rust -use echidna::aspect::{Aspect, AspectTagger, RuleBasedTagger}; -use echidna::core::Term; - -// Create tagger -let tagger = RuleBasedTagger::new(); - -// Tag theorem -let aspects = tagger.tag("nat_add_comm", &statement); - -// Get confidence scores -let scores = tagger.tag_with_confidence("theorem_name", &statement); -``` - -## Key Files - -| File | Purpose | Size | -|------|---------|------| -| `/home/user/echidna/src/rust/aspect.rs` | Core implementation | 1,156 lines | -| `/home/user/echidna/docs/ASPECT_TAGGING.md` | Full documentation | 11 KB | -| `/home/user/echidna/examples/aspect_tagging_demo.rs` | Examples | 6.5 KB | -| `/home/user/echidna/docs/ASPECT_IMPLEMENTATION_SUMMARY.md` | Implementation details | 14 KB | - -## Key Components - -### 1. Aspects (60 total) - -```rust -Aspect::PropositionalLogic // Logic -Aspect::NaturalNumbers // Arithmetic -Aspect::Groups // Algebra -Aspect::Limits // Analysis -Aspect::TopologicalSpaces // Topology -Aspect::DependentTypes // Type Theory -Aspect::Algorithms // Computer Science -Aspect::Induction // Proof Techniques -``` - -### 2. Taggers - -```rust -// Rule-based (keyword/symbol matching) -let rule_tagger = RuleBasedTagger::new(); - -// Neural (Julia ML integration - stub) -let neural_tagger = NeuralTagger::new(); - -// OpenCyc (ontology - stub) -let cyc_tagger = OpenCycTagger::new("http://localhost:3601"); - -// Composite (combine multiple) -let composite = CompositeTagger::new(AggregationStrategy::WeightedVoting) - .add_tagger(Box::new(rule_tagger), 0.7) - .add_tagger(Box::new(neural_tagger), 0.3); -``` - -### 3. Features - -```rust -let features = tagger.extract_features(&statement); -println!("Lambda depth: {}", features.lambda_depth); -println!("Quantifiers: {}", features.quantifier_count); -println!("Symbols: {:?}", features.symbols); -``` - -## Common Patterns - -### Tag All Theorems in Context - -```rust -for theorem in &mut context.theorems { - theorem.aspects = tagger.tag(&theorem.name, &theorem.statement) - .into_iter() - .map(|a| a.to_string()) - .collect(); -} -``` - -### Filter by Aspect - -```rust -let arithmetic_theorems: Vec<_> = theorems.iter() - .filter(|t| t.aspects.contains(&"Arithmetic".to_string())) - .collect(); -``` - -### Custom Rules - -```rust -let mut tagger = RuleBasedTagger::new(); -tagger.add_keyword_rule("banach", vec![ - Aspect::FunctionalAnalysis, - Aspect::MetricSpaces, -]); -``` - -## Run Examples - -```bash -# Build -cargo build - -# Run demo -cargo run --example aspect_tagging_demo - -# Run tests -cargo test --lib aspect -``` - -## Status - -✅ **Production Ready**: -- RuleBasedTagger (100+ rules) -- CompositeTagger (4 strategies) -- 60 aspects, 10 categories -- 12 comprehensive tests - -⏳ **Stub (needs integration)**: -- NeuralTagger (Julia ML) -- OpenCycTagger (OpenCyc API) - -## Quick Reference: Aspect Categories - -| Category | Count | Examples | -|----------|-------|----------| -| Logic | 7 | Propositional, Predicate, Modal | -| Arithmetic | 7 | Natural Numbers, Integers, Reals | -| Algebra | 8 | Groups, Rings, Fields | -| Analysis | 7 | Limits, Continuity, Derivatives | -| Topology | 5 | Metric Spaces, Compactness | -| Set Theory | 5 | Set Operations, Cardinality | -| Type Theory | 6 | Dependent Types, Universes | -| Computer Science | 8 | Algorithms, Complexity | -| Proof Techniques | 6 | Induction, Recursion | -| Other | 6 | Combinatorics, Graph Theory | - -## Integration Checklist - -- [ ] Tag theorems during proof parsing -- [ ] Use aspects for premise selection -- [ ] Integrate with neural models (Julia) -- [ ] Add aspect-based search/filtering -- [ ] Export aspects to prover formats -- [ ] Track aspect statistics -- [ ] Build aspect-based recommendations - -## Learn More - -- **Full Documentation**: `/home/user/echidna/docs/ASPECT_TAGGING.md` -- **Implementation Details**: `/home/user/echidna/docs/ASPECT_IMPLEMENTATION_SUMMARY.md` -- **Examples**: `/home/user/echidna/examples/aspect_tagging_demo.rs` -- **Source Code**: `/home/user/echidna/src/rust/aspect.rs` - -## License - -SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/docs/ASPECT_TAGGING.md b/docs/ASPECT_TAGGING.adoc similarity index 54% rename from docs/ASPECT_TAGGING.md rename to docs/ASPECT_TAGGING.adoc index a6a99b95..70c8f4a5 100644 --- a/docs/ASPECT_TAGGING.md +++ b/docs/ASPECT_TAGGING.adoc @@ -1,58 +1,72 @@ -# Aspect Tagging System - -## Overview - -The ECHIDNA aspect tagging system classifies theorems by mathematical domain and logical structure to improve premise selection and neural learning. This system provides comprehensive multi-label classification with confidence scores. - -## Architecture - -### Components - -1. **Aspect Enum** - 60+ mathematical/logical aspects organized into categories: - - Logic (7 aspects): Propositional, Predicate, Modal, Temporal, Higher-Order, Intuitionistic, Classical - - Arithmetic (7 aspects): Natural Numbers, Integers, Rationals, Reals, Complex, Number Theory, Arithmetic - - Algebra (8 aspects): Groups, Rings, Fields, Vector Spaces, Modules, Lattices, Category Theory, Universal Algebra - - Analysis (7 aspects): Limits, Continuity, Derivatives, Integrals, Sequences, Measure Theory, Functional Analysis - - Topology (5 aspects): Metric Spaces, Topological Spaces, Compactness, Connectedness, Topological Continuity - - Set Theory (5 aspects): Set Operations, Cardinality, Ordinals, Axiom of Choice, ZFC - - Type Theory (6 aspects): Dependent Types, Universes, Inductive Types, Coinductive Types, Polymorphism, Type Equivalence - - Computer Science (8 aspects): Algorithms, Complexity, Formal Verification, Program Semantics, Concurrency, Cryptography, Automata, Lambda Calculus - - Proof Techniques (6 aspects): Induction, Coinduction, Recursion, Case Analysis, Contradiction, Direct Proof - - Other (6 aspects): Combinatorics, Graph Theory, Probability, Game Theory, Geometry, Abstract Nonsense - -2. **AspectTagger Trait** - Interface for tagging strategies: - - `tag()` - Tag theorem with aspects - - `extract_features()` - Extract structural features - - `tag_with_confidence()` - Get confidence scores (0.0-1.0) - -3. **RuleBasedTagger** - Heuristic keyword and pattern matching: - - 100+ keyword rules (e.g., "nat" → NaturalNumbers, "group" → Groups) - - 20+ symbol rules (e.g., "∀" → PredicateLogic, "ℕ" → NaturalNumbers) - - Structural analysis (quantifiers, lambda depth, Pi types, universes) - - Configurable confidence threshold - -4. **NeuralTagger** - ML-based classification (Julia integration): - - Embeddings from theorem statements - - Multi-label classification - - Julia ML service integration (HTTP or FFI) - - Trained on tagged theorem corpus - -5. **OpenCycTagger** - Ontology-based semantic tagging: - - Maps concepts to OpenCyc ontology - - Uses semantic relationships - - Cached concept mappings - -6. **CompositeTagger** - Combines multiple strategies: - - Union: All aspects from all taggers - - Intersection: Only common aspects - - WeightedVoting: Weighted confidence scores - - Majority: Aspects with >50% vote - -## Usage - -### Basic Usage - -```rust +== Aspect Tagging System + +=== Overview + +The ECHIDNA aspect tagging system classifies theorems by mathematical +domain and logical structure to improve premise selection and neural +learning. This system provides comprehensive multi-label classification +with confidence scores. + +=== Architecture + +==== Components + +[arabic] +. *Aspect Enum* - 60+ mathematical/logical aspects organized into +categories: +* Logic (7 aspects): Propositional, Predicate, Modal, Temporal, +Higher-Order, Intuitionistic, Classical +* Arithmetic (7 aspects): Natural Numbers, Integers, Rationals, Reals, +Complex, Number Theory, Arithmetic +* Algebra (8 aspects): Groups, Rings, Fields, Vector Spaces, Modules, +Lattices, Category Theory, Universal Algebra +* Analysis (7 aspects): Limits, Continuity, Derivatives, Integrals, +Sequences, Measure Theory, Functional Analysis +* Topology (5 aspects): Metric Spaces, Topological Spaces, Compactness, +Connectedness, Topological Continuity +* Set Theory (5 aspects): Set Operations, Cardinality, Ordinals, Axiom +of Choice, ZFC +* Type Theory (6 aspects): Dependent Types, Universes, Inductive Types, +Coinductive Types, Polymorphism, Type Equivalence +* Computer Science (8 aspects): Algorithms, Complexity, Formal +Verification, Program Semantics, Concurrency, Cryptography, Automata, +Lambda Calculus +* Proof Techniques (6 aspects): Induction, Coinduction, Recursion, Case +Analysis, Contradiction, Direct Proof +* Other (6 aspects): Combinatorics, Graph Theory, Probability, Game +Theory, Geometry, Abstract Nonsense +. *AspectTagger Trait* - Interface for tagging strategies: +* `+tag()+` - Tag theorem with aspects +* `+extract_features()+` - Extract structural features +* `+tag_with_confidence()+` - Get confidence scores (0.0-1.0) +. *RuleBasedTagger* - Heuristic keyword and pattern matching: +* 100+ keyword rules (e.g., "`nat`" → NaturalNumbers, "`group`" → +Groups) +* 20+ symbol rules (e.g., "`∀`" → PredicateLogic, "`ℕ`" → +NaturalNumbers) +* Structural analysis (quantifiers, lambda depth, Pi types, universes) +* Configurable confidence threshold +. *NeuralTagger* - ML-based classification (Julia integration): +* Embeddings from theorem statements +* Multi-label classification +* Julia ML service integration (HTTP or FFI) +* Trained on tagged theorem corpus +. *OpenCycTagger* - Ontology-based semantic tagging: +* Maps concepts to OpenCyc ontology +* Uses semantic relationships +* Cached concept mappings +. *CompositeTagger* - Combines multiple strategies: +* Union: All aspects from all taggers +* Intersection: Only common aspects +* WeightedVoting: Weighted confidence scores +* Majority: Aspects with >50% vote + +=== Usage + +==== Basic Usage + +[source,rust] +---- use echidna::aspect::{Aspect, AspectTagger, RuleBasedTagger}; use echidna::core::Term; @@ -71,11 +85,12 @@ let statement = Term::App { let aspects = tagger.tag(theorem_name, &statement); // aspects = [Aspect::Arithmetic, Aspect::NaturalNumbers] -``` +---- -### Confidence Scores +==== Confidence Scores -```rust +[source,rust] +---- let scores = tagger.tag_with_confidence(theorem_name, &statement); for (aspect, score) in scores { println!("{}: {:.2}", aspect.name(), score); @@ -83,29 +98,32 @@ for (aspect, score) in scores { // Output: // Arithmetic: 0.50 // Natural Numbers: 0.50 -``` +---- -### Feature Extraction +==== Feature Extraction -```rust +[source,rust] +---- let features = tagger.extract_features(&statement); println!("Lambda depth: {}", features.lambda_depth); println!("Quantifiers: {}", features.quantifier_count); println!("Pi types: {}", features.pi_count); println!("Symbols: {:?}", features.symbols); -``` +---- -### Custom Threshold +==== Custom Threshold -```rust +[source,rust] +---- // Only tag with high-confidence aspects (≥0.8) let tagger = RuleBasedTagger::with_threshold(0.8); let aspects = tagger.tag(theorem_name, &statement); -``` +---- -### Composite Tagging +==== Composite Tagging -```rust +[source,rust] +---- use echidna::aspect::{CompositeTagger, AggregationStrategy, NeuralTagger}; let composite = CompositeTagger::new(AggregationStrategy::WeightedVoting) @@ -113,11 +131,12 @@ let composite = CompositeTagger::new(AggregationStrategy::WeightedVoting) .add_tagger(Box::new(NeuralTagger::new()), 0.3); let aspects = composite.tag(theorem_name, &statement); -``` +---- -### Custom Rules +==== Custom Rules -```rust +[source,rust] +---- let mut tagger = RuleBasedTagger::new(); // Add custom keyword rule @@ -128,15 +147,16 @@ tagger.add_keyword_rule("banach", vec![ // Add custom symbol rule tagger.add_symbol_rule("⊗", vec![Aspect::VectorSpaces]); -``` +---- -## Integration with ECHIDNA +=== Integration with ECHIDNA -### Premise Selection +==== Premise Selection Aspects improve premise selection by filtering relevant theorems: -```rust +[source,rust] +---- fn select_premises(goal: &Goal, theorems: &[Theorem], tagger: &dyn AspectTagger) -> Vec { // Tag the goal let goal_aspects = tagger.tag(&goal.id, &goal.target); @@ -150,13 +170,14 @@ fn select_premises(goal: &Goal, theorems: &[Theorem], tagger: &dyn AspectTagger) .cloned() .collect() } -``` +---- -### Neural Learning +==== Neural Learning Aspects provide additional features for neural models: -```rust +[source,rust] +---- struct TheoremEmbedding { syntactic_embedding: Vec, // From term structure aspect_embedding: Vec, // From aspect tags @@ -173,13 +194,14 @@ fn embed_theorem(theorem: &Theorem, tagger: &dyn AspectTagger) -> TheoremEmbeddi aspect_embedding, } } -``` +---- -### Prover Integration +==== Prover Integration Tag theorems during proof state construction: -```rust +[source,rust] +---- impl ProverBackend for MyProver { async fn parse_file(&self, path: &Path) -> Result { let mut state = self.parse_proof(path).await?; @@ -196,15 +218,17 @@ impl ProverBackend for MyProver { Ok(state) } } -``` +---- -## Neural Tagger Integration (Julia) +=== Neural Tagger Integration (Julia) -The `NeuralTagger` integrates with Julia ML components for advanced classification. +The `+NeuralTagger+` integrates with Julia ML components for advanced +classification. -### Julia Service Setup +==== Julia Service Setup -```julia +[source,julia] +---- # julia/aspect_classifier.jl using Flux, BSON @@ -228,11 +252,12 @@ function serve_classifier(classifier, port=8081) HTTP.Response(200, JSON.json(aspects)) end end -``` +---- -### Rust Integration +==== Rust Integration -```rust +[source,rust] +---- impl NeuralTagger { pub async fn tag_async(&self, theorem_name: &str, statement: &Term) -> Vec { // Get embeddings @@ -256,15 +281,15 @@ impl NeuralTagger { } } } -``` +---- -## OpenCyc Integration +=== OpenCyc Integration -The `OpenCycTagger` uses OpenCyc ontology for semantic tagging. +The `+OpenCycTagger+` uses OpenCyc ontology for semantic tagging. -### Concept Mappings +==== Concept Mappings -``` +.... OpenCyc Concept → ECHIDNA Aspects ===================================== #$MathematicalObject → [SetOperations] @@ -274,11 +299,12 @@ OpenCyc Concept → ECHIDNA Aspects #$NaturalNumber → [NaturalNumbers, Arithmetic] #$Predicate → [PredicateLogic] #$PropositionalFormula → [PropositionalLogic] -``` +.... -### Query Example +==== Query Example -```rust +[source,rust] +---- impl OpenCycTagger { async fn query_concept(&self, concept: &str) -> Option> { let query = format!( @@ -293,62 +319,70 @@ impl OpenCycTagger { self.map_types_to_aspects(&response) } } -``` +---- + +=== Performance Considerations + +==== Rule-Based Tagger + +* *Speed*: Very fast (microseconds per theorem) +* *Accuracy*: 70-80% for well-named theorems +* *Best for*: Real-time tagging, initial classification + +==== Neural Tagger -## Performance Considerations +* *Speed*: Slower (milliseconds per theorem, depends on Julia service) +* *Accuracy*: 85-95% with good training data +* *Best for*: High-quality classification, large batches -### Rule-Based Tagger -- **Speed**: Very fast (microseconds per theorem) -- **Accuracy**: 70-80% for well-named theorems -- **Best for**: Real-time tagging, initial classification +==== OpenCyc Tagger -### Neural Tagger -- **Speed**: Slower (milliseconds per theorem, depends on Julia service) -- **Accuracy**: 85-95% with good training data -- **Best for**: High-quality classification, large batches +* *Speed*: Medium (depends on OpenCyc query speed) +* *Accuracy*: 75-85% for concepts in ontology +* *Best for*: Semantic relationships, domain-specific knowledge -### OpenCyc Tagger -- **Speed**: Medium (depends on OpenCyc query speed) -- **Accuracy**: 75-85% for concepts in ontology -- **Best for**: Semantic relationships, domain-specific knowledge +==== Composite Strategy -### Composite Strategy -- **WeightedVoting**: Balanced accuracy and coverage -- **Union**: Maximum recall, may have false positives -- **Intersection**: High precision, may miss relevant aspects -- **Majority**: Good compromise between precision and recall +* *WeightedVoting*: Balanced accuracy and coverage +* *Union*: Maximum recall, may have false positives +* *Intersection*: High precision, may miss relevant aspects +* *Majority*: Good compromise between precision and recall -## Testing +=== Testing Run the test suite: -```bash +[source,bash] +---- cargo test --lib aspect -``` +---- Run the demo: -```bash +[source,bash] +---- cargo run --example aspect_tagging_demo -``` +---- -## Future Enhancements +=== Future Enhancements -1. **Active Learning**: Use confidence scores to identify theorems needing manual tagging -2. **Transfer Learning**: Fine-tune neural tagger on new prover corpora -3. **Hierarchical Classification**: Multi-level aspect taxonomy -4. **Cross-Prover Alignment**: Map aspects across different theorem provers -5. **Temporal Tracking**: Track aspect usage over time for recommendation -6. **User Feedback**: Incorporate user corrections to improve tagging +[arabic] +. *Active Learning*: Use confidence scores to identify theorems needing +manual tagging +. *Transfer Learning*: Fine-tune neural tagger on new prover corpora +. *Hierarchical Classification*: Multi-level aspect taxonomy +. *Cross-Prover Alignment*: Map aspects across different theorem provers +. *Temporal Tracking*: Track aspect usage over time for recommendation +. *User Feedback*: Incorporate user corrections to improve tagging -## References +=== References -- **ECHIDNA Architecture**: See `docs/ARCHITECTURE.md` -- **Core Types**: See `src/rust/core.rs` -- **Prover Integration**: See `docs/PROVER_INTEGRATION.md` -- **Neural Components**: See `src/julia/README.md` +* *ECHIDNA Architecture*: See `+docs/ARCHITECTURE.md+` +* *Core Types*: See `+src/rust/core.rs+` +* *Prover Integration*: See `+docs/PROVER_INTEGRATION.md+` +* *Neural Components*: See `+src/julia/README.md+` -## License +=== License SPDX-FileCopyrightText: 2025 ECHIDNA Project Team SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/docs/COQ_BACKEND_IMPLEMENTATION.adoc b/docs/COQ_BACKEND_IMPLEMENTATION.adoc new file mode 100644 index 00000000..3e0eca49 --- /dev/null +++ b/docs/COQ_BACKEND_IMPLEMENTATION.adoc @@ -0,0 +1,448 @@ +== Coq Backend Implementation for ECHIDNA + +=== Overview + +Complete, production-ready Coq backend implementation for the ECHIDNA +neurosymbolic theorem proving platform. This backend provides full +integration with the Coq proof assistant via SerAPI, supporting parsing, +tactic execution, and proof verification. + +*File*: `+/home/user/echidna/src/rust/provers/coq.rs+` *Lines of Code*: +1,112 *Status*: ✅ *COMPILES SUCCESSFULLY* - No errors or warnings + +=== Architecture + +==== Core Components + +===== 1. *CoqBackend Struct* + +The main backend implementing the `+ProverBackend+` trait: - +*Configuration*: Holds prover-specific configuration (executable path, +library paths, arguments, timeout) - *Session Management*: Manages async +Coq sessions via SerAPI (sertop) - *Thread-Safe*: Uses +`+Mutex>+` for concurrent access + +===== 2. *SerAPI Integration* + +Programmatic interaction with Coq via the serialization API (SerAPI): - +*S-Expression Communication*: Full S-expression parser and serializer - +*Process Management*: Spawns and manages `+sertop+` subprocess - +*Command Execution*: Sends commands and parses responses - *State +Tracking*: Maintains state IDs and command counters + +===== 3. *Coq Parser* + +Complete parser for Coq .v files: + +*Supported Constructs*: - ✅ *Definitions*: +`+Definition name : type := body.+` - ✅ *Fixpoints*: +`+Fixpoint name args : type := body.+` - ✅ *Theorems/Lemmas*: +`+Theorem name : statement.+` - ✅ *Inductive Types*: +`+Inductive name : type := constructors.+` - ✅ *Proof Scripts*: +`+Proof. ... Qed.+` / `+Defined.+` / `+Admitted.+` - ✅ *Tactics*: All +standard Coq tactics - ✅ *Comments*: `+(* comment *)+` - ✅ *String +Literals*: Proper escaping handling + +===== 4. *Gallina Term Parser* + +Converts Coq terms to ECHIDNA’s universal `+Term+` representation: + +*Supported Term Types*: - *Dependent Products (Pi types)*: +`+forall x : A, B+` - *Lambda Abstractions*: `+fun x : A => body+` - +*Function Applications*: `+f arg1 arg2+` - *Binary Operators*: - +Implication: `+A -> B+` - Conjunction: `+A /\ B+` - Disjunction: +`+A \/ B+` - Negation: `+~A+` - *Type Universes*: `+Prop+`, `+Type+`, +`+Set+` - *Variables and Constants*: Proper case distinction + +*Parser Features*: - Top-level operator precedence handling - +Parenthesis depth tracking - Smart whitespace tokenization - Recursive +descent parsing + +===== 5. *Tactic System* + +Bidirectional tactic conversion between universal and Coq-specific +formats: + +*Universal → Coq*: - `+Intro(name)+` → `+intro name.+` - `+Apply(thm)+` +→ `+apply thm.+` - `+Rewrite(thm)+` → `+rewrite thm.+` - `+Reflexivity+` +→ `+reflexivity.+` - `+Simplify+` → `+simpl.+` - `+Assumption+` → +`+assumption.+` - `+Exact(term)+` → `+exact term.+` - `+Cases(term)+` → +`+destruct term.+` - `+Induction(term)+` → `+induction term.+` - +`+Custom{cmd, args}+` → `+cmd args.+` + +*Coq → Universal*: - Parses `+intro+`, `+intros+`, `+apply+`, +`+rewrite+`, `+reflexivity+`, `+simpl+`, `+assumption+`, `+exact+`, +`+destruct+`, `+induction+` - Handles tactic arguments - Supports `+as+` +patterns for destructing + +===== 6. *Proof State Management* + +Complete proof state tracking: - *Goals*: Current proof obligations - +*Context*: Available theorems, definitions, and variables - +*Hypotheses*: Local assumptions per goal - *Proof Scripts*: Sequence of +applied tactics - *Metadata*: Extensible key-value storage + +===== 7. *Proof Verification* + +Autonomous proof checking: - Exports proof to Coq format - Writes to +temporary file - Invokes `+coqc+` compiler - Returns verification result + +===== 8. *Neural Tactic Suggestion* + +Heuristic-based tactic recommendation: - Analyzes goal structure - +Suggests appropriate tactics based on goal type - Supports neural +premise selection integration (placeholder for ML models) + +*Suggestion Heuristics*: - Pi types (forall) → `+intro+` - Conjunctions +→ `+split+` - Disjunctions → `+left+` / `+right+` - Equalities → +`+reflexivity+` - General → `+simpl+`, `+assumption+`, `+auto+` + +=== Implementation Details + +==== S-Expression Processing + +[source,rust] +---- +enum SExp { + Atom(String), + List(Vec), +} +---- + +*Features*: - Tokenization with string literal handling - Escape +sequence support - Recursive parsing - Pretty-printing with proper +quoting + +==== Process Management + +*Async Process Handling*: + +[source,rust] +---- +tokio::process::Command::new("sertop") + .arg("--printer=sertop") + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn()? +---- + +*I/O Operations*: - Async writes to stdin - Buffered async reads from +stdout - Line-based response parsing + +==== File Parsing + +*Statement-Level Parsing*: - Character-by-character scanning - Comment +handling (nested `+(* *)+`) - String literal tracking - Statement +boundary detection (`+.+` followed by whitespace) + +*Error Handling*: - Descriptive error messages - Context preservation - +Graceful degradation for partial parses + +==== Tactic Execution Flow + +[arabic] +. *Convert* universal tactic → Coq command +. *Send* command to sertop via SerAPI +. *Parse* response (success/error/completion) +. *Query* new goals +. *Update* proof state +. *Return* result (Success/Error/QED) + +=== ProverBackend Trait Implementation + +==== Methods Implemented + +[width="100%",cols="29%,27%,44%",options="header",] +|=== +|Method |Status |Description +|`+kind()+` |✅ |Returns `+ProverKind::Coq+` +|`+version()+` |✅ |Executes `+coqc --version+` +|`+parse_file()+` |✅ |Reads and parses .v files +|`+parse_string()+` |✅ |Parses Coq code from string +|`+apply_tactic()+` |✅ |Applies tactic to proof state +|`+verify_proof()+` |✅ |Verifies proof with coqc +|`+export()+` |✅ |Exports proof to Coq format +|`+suggest_tactics()+` |✅ |Neural/heuristic tactic suggestions +|`+search_theorems()+` |✅ |Searches theorems via Coq’s Search command +|`+config()+` |✅ |Returns configuration +|`+set_config()+` |✅ |Updates configuration +|=== + +=== Testing + +==== Test Coverage + +[source,rust] +---- +#[cfg(test)] +mod tests { + #[tokio::test] + async fn test_parse_simple_theorem() { ... } + + #[test] + fn test_parse_term() { ... } + + #[test] + fn test_sexp_parsing() { ... } + + #[test] + fn test_tactic_conversion() { ... } + + #[tokio::test] + async fn test_version() { ... } +} +---- + +*Test Examples*: - ✅ Parsing identity theorem - ✅ Term parsing +(implications, forall) - ✅ S-expression round-tripping - ✅ Tactic +conversion bidirectionality - ✅ Version detection + +==== Example Proofs Tested + +Located in `+/home/user/echidna/proofs/coq/+`: + +[arabic] +. *basic.v* (195 lines) +* Identity, modus ponens, transitivity +* Conjunction/disjunction introduction/elimination +* Curry/uncurry +. *propositional.v* (324 lines) +* De Morgan’s laws (constructive & classical) +* Double negation +* Excluded middle +* Peirce’s law +* Contrapositive +* Distribution laws +. *nat.v* (367 lines) +* Addition/multiplication properties +* Commutativity, associativity +* Induction examples +* Sum formula, powers of 2, factorial +* Even/odd predicates +. *list.v* (488 lines) +* Append, length, reverse +* Map, fold, filter +* Nth element access +* List membership (In) + +=== Dependencies + +[source,toml] +---- +tokio = { version = "1.35", features = ["full"] } +async-trait = "0.1" +anyhow = "1.0" +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" +---- + +=== Usage Example + +[source,rust] +---- +use echidna::provers::{ProverBackend, ProverConfig, ProverFactory, ProverKind}; + +// Create backend +let config = ProverConfig { + executable: PathBuf::from("/usr/bin/sertop"), + library_paths: vec![PathBuf::from("/usr/lib/coq")], + args: vec![], + timeout: 300, + neural_enabled: true, +}; + +let backend = ProverFactory::create(ProverKind::Coq, config)?; + +// Parse Coq file +let state = backend.parse_file(PathBuf::from("proof.v")).await?; + +// Apply tactic +let tactic = Tactic::Intro(Some("H".to_string())); +let result = backend.apply_tactic(&state, &tactic).await?; + +match result { + TacticResult::Success(new_state) => println!("Tactic applied!"), + TacticResult::Error(msg) => println!("Error: {}", msg), + TacticResult::QED => println!("Proof complete!"), +} + +// Verify proof +let is_valid = backend.verify_proof(&state).await?; + +// Export proof +let coq_code = backend.export(&state).await?; +---- + +=== Features + +==== ✅ Implemented + +[arabic] +. *Complete .v file parsing* - All major Coq constructs +. *SerAPI integration* - S-expression communication +. *Bidirectional tactic conversion* - Universal ↔ Coq +. *Gallina term parsing* - Full term representation +. *Proof verification* - Autonomous checking with coqc +. *Theorem search* - Integration with Coq’s Search +. *Neural tactic suggestion* - Heuristic-based recommendations +. *Async/concurrent* - Tokio-based async I/O +. *Error handling* - Comprehensive error messages +. *Export functionality* - Generate valid Coq code + +==== 🚧 Future Enhancements + +[arabic] +. *Advanced SerAPI features* - Goal inspection, proof term extraction +. *Machine learning integration* - Neural premise selection from early +development +. *Tactic composition* - Chained tactics (`+;+`, `+||+`) +. *SSReflect support* - Small-scale reflection tactics +. *Module system* - Import/Export, Module, Section +. *Notation handling* - Custom notations and scopes +. *Type class resolution* - Instance search +. *Ltac programming* - Custom tactic definitions +. *Performance optimization* - Caching, batch operations +. *Rich error reporting* - Location tracking, suggestions + +=== Integration with ECHIDNA + +==== Prover Factory + +[source,rust] +---- +pub struct ProverFactory; + +impl ProverFactory { + pub fn create(kind: ProverKind, config: ProverConfig) + -> Result> + { + match kind { + ProverKind::Coq => Ok(Box::new(CoqBackend::new(config))), + // ... other provers + } + } +} +---- + +==== File Detection + +[source,rust] +---- +impl ProverFactory { + pub fn detect_from_file(path: &PathBuf) -> Option { + path.extension()?.to_str().and_then(|ext| match ext { + "v" => Some(ProverKind::Coq), + // ... other extensions + }) + } +} +---- + +==== Tier Classification + +* *Tier*: 1 (Tier 1: Original + SMT solvers) +* *Complexity*: 3/5 (Moderate) +* *Implementation Time*: 2.5 weeks (estimated) +* *Coverage*: >70% of standard theorems (as part of "`Big Six`") + +=== Performance Characteristics + +==== Parsing + +* *Speed*: ~10,000 lines/second (estimated) +* *Memory*: O(n) where n = file size +* *Async*: Non-blocking I/O + +==== Tactic Execution + +* *Latency*: ~50-200ms per tactic (SerAPI overhead) +* *Throughput*: ~5-20 tactics/second +* *Concurrency*: Safe for parallel proof attempts + +==== Verification + +* *Method*: Full compilation with coqc +* *Accuracy*: 100% (delegated to Coq) +* *Speed*: Dependent on proof complexity + +=== Security Considerations + +[arabic] +. *Command Injection*: All user input properly escaped +. *Path Traversal*: Validates file paths +. *Resource Limits*: Configurable timeouts +. *Process Isolation*: Separate sertop process per session +. *Error Handling*: No sensitive information leakage + +=== Compliance + +* ✅ *RSR/CCCP*: Rhodium Standard Repository compliant +* ✅ *Dual Licensed*: MIT + Palimpsest v0.6 +* ✅ *SPDX Headers*: All files properly tagged +* ✅ *Documentation*: Comprehensive inline docs +* ✅ *Testing*: Unit and integration tests + +=== Comparison with Other Provers + +[width="100%",cols="28%,13%,16%,16%,27%",options="header",] +|=== +|Feature |Coq |Agda |Lean |Isabelle +|*Tactic Language* |Ltac/Ltac2 |Reflection |Lean 4 tactics |Isar +|*Type Theory* |CIC |MLTT |DTT |HOL +|*Automation* |High |Medium |High |Very High +|*SerAPI Support* |✅ Yes |❌ No |⚠️ Partial |⚠️ PIDE +|*Neural Integration* |✅ Ready |🚧 Planned |🚧 Planned |🚧 Planned +|=== + +=== Known Limitations + +[arabic] +. *SerAPI Dependency*: Requires sertop installation +. *Synchronous Execution*: Some operations block on Coq response +. *Simplified Parsing*: Complex notations may not parse correctly +. *Goal Inspection*: Currently returns placeholder goals (needs full +SerAPI response parsing) +. *Error Messages*: Coq errors not fully parsed into structured format + +=== Roadmap + +==== Phase 1 (Current) ✅ + +* [x] Basic ProverBackend implementation +* [x] .v file parsing +* [x] Tactic conversion +* [x] Proof verification + +==== Phase 2 (Next) + +* [ ] Full SerAPI response parsing +* [ ] Real-time goal inspection +* [ ] Proof term extraction +* [ ] Performance optimizations + +==== Phase 3 (Future) + +* [ ] Neural premise selection integration +* [ ] ML-guided tactic synthesis +* [ ] Proof mining and learning +* [ ] Benchmark suite + +=== References + +* *Coq Reference Manual*: https://coq.inria.fr/doc/ +* *SerAPI Documentation*: https://github.com/ejgallego/coq-serapi +* *ECHIDNA Documentation*: /home/user/echidna/docs/ +* *ECHIDNA Repository*: https://github.com/hyperpolymath/echidna + +=== Credits + +* *Implementation*: ECHIDNA Project Team (2025) +* *Coq*: INRIA, France +* *SerAPI*: Emilio J. Gallego Arias +* *Inspiration*: ECHIDNA development + +''''' + +*Status*: ✅ *PRODUCTION READY* *Last Updated*: 2025-11-22 *Version*: +0.1.0 diff --git a/docs/COQ_BACKEND_IMPLEMENTATION.md b/docs/COQ_BACKEND_IMPLEMENTATION.md deleted file mode 100644 index 562f1792..00000000 --- a/docs/COQ_BACKEND_IMPLEMENTATION.md +++ /dev/null @@ -1,447 +0,0 @@ -# Coq Backend Implementation for ECHIDNA - -## Overview - -Complete, production-ready Coq backend implementation for the ECHIDNA neurosymbolic theorem proving platform. This backend provides full integration with the Coq proof assistant via SerAPI, supporting parsing, tactic execution, and proof verification. - -**File**: `/home/user/echidna/src/rust/provers/coq.rs` -**Lines of Code**: 1,112 -**Status**: ✅ **COMPILES SUCCESSFULLY** - No errors or warnings - -## Architecture - -### Core Components - -#### 1. **CoqBackend Struct** -The main backend implementing the `ProverBackend` trait: -- **Configuration**: Holds prover-specific configuration (executable path, library paths, arguments, timeout) -- **Session Management**: Manages async Coq sessions via SerAPI (sertop) -- **Thread-Safe**: Uses `Mutex>` for concurrent access - -#### 2. **SerAPI Integration** -Programmatic interaction with Coq via the serialization API (SerAPI): -- **S-Expression Communication**: Full S-expression parser and serializer -- **Process Management**: Spawns and manages `sertop` subprocess -- **Command Execution**: Sends commands and parses responses -- **State Tracking**: Maintains state IDs and command counters - -#### 3. **Coq Parser** -Complete parser for Coq .v files: - -**Supported Constructs**: -- ✅ **Definitions**: `Definition name : type := body.` -- ✅ **Fixpoints**: `Fixpoint name args : type := body.` -- ✅ **Theorems/Lemmas**: `Theorem name : statement.` -- ✅ **Inductive Types**: `Inductive name : type := constructors.` -- ✅ **Proof Scripts**: `Proof. ... Qed.` / `Defined.` / `Admitted.` -- ✅ **Tactics**: All standard Coq tactics -- ✅ **Comments**: `(* comment *)` -- ✅ **String Literals**: Proper escaping handling - -#### 4. **Gallina Term Parser** -Converts Coq terms to ECHIDNA's universal `Term` representation: - -**Supported Term Types**: -- **Dependent Products (Pi types)**: `forall x : A, B` -- **Lambda Abstractions**: `fun x : A => body` -- **Function Applications**: `f arg1 arg2` -- **Binary Operators**: - - Implication: `A -> B` - - Conjunction: `A /\ B` - - Disjunction: `A \/ B` - - Negation: `~A` -- **Type Universes**: `Prop`, `Type`, `Set` -- **Variables and Constants**: Proper case distinction - -**Parser Features**: -- Top-level operator precedence handling -- Parenthesis depth tracking -- Smart whitespace tokenization -- Recursive descent parsing - -#### 5. **Tactic System** -Bidirectional tactic conversion between universal and Coq-specific formats: - -**Universal → Coq**: -- `Intro(name)` → `intro name.` -- `Apply(thm)` → `apply thm.` -- `Rewrite(thm)` → `rewrite thm.` -- `Reflexivity` → `reflexivity.` -- `Simplify` → `simpl.` -- `Assumption` → `assumption.` -- `Exact(term)` → `exact term.` -- `Cases(term)` → `destruct term.` -- `Induction(term)` → `induction term.` -- `Custom{cmd, args}` → `cmd args.` - -**Coq → Universal**: -- Parses `intro`, `intros`, `apply`, `rewrite`, `reflexivity`, `simpl`, `assumption`, `exact`, `destruct`, `induction` -- Handles tactic arguments -- Supports `as` patterns for destructing - -#### 6. **Proof State Management** -Complete proof state tracking: -- **Goals**: Current proof obligations -- **Context**: Available theorems, definitions, and variables -- **Hypotheses**: Local assumptions per goal -- **Proof Scripts**: Sequence of applied tactics -- **Metadata**: Extensible key-value storage - -#### 7. **Proof Verification** -Autonomous proof checking: -- Exports proof to Coq format -- Writes to temporary file -- Invokes `coqc` compiler -- Returns verification result - -#### 8. **Neural Tactic Suggestion** -Heuristic-based tactic recommendation: -- Analyzes goal structure -- Suggests appropriate tactics based on goal type -- Supports neural premise selection integration (placeholder for ML models) - -**Suggestion Heuristics**: -- Pi types (forall) → `intro` -- Conjunctions → `split` -- Disjunctions → `left` / `right` -- Equalities → `reflexivity` -- General → `simpl`, `assumption`, `auto` - -## Implementation Details - -### S-Expression Processing - -```rust -enum SExp { - Atom(String), - List(Vec), -} -``` - -**Features**: -- Tokenization with string literal handling -- Escape sequence support -- Recursive parsing -- Pretty-printing with proper quoting - -### Process Management - -**Async Process Handling**: -```rust -tokio::process::Command::new("sertop") - .arg("--printer=sertop") - .stdin(Stdio::piped()) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - .spawn()? -``` - -**I/O Operations**: -- Async writes to stdin -- Buffered async reads from stdout -- Line-based response parsing - -### File Parsing - -**Statement-Level Parsing**: -- Character-by-character scanning -- Comment handling (nested `(* *)`) -- String literal tracking -- Statement boundary detection (`.` followed by whitespace) - -**Error Handling**: -- Descriptive error messages -- Context preservation -- Graceful degradation for partial parses - -### Tactic Execution Flow - -1. **Convert** universal tactic → Coq command -2. **Send** command to sertop via SerAPI -3. **Parse** response (success/error/completion) -4. **Query** new goals -5. **Update** proof state -6. **Return** result (Success/Error/QED) - -## ProverBackend Trait Implementation - -### Methods Implemented - -| Method | Status | Description | -|--------|--------|-------------| -| `kind()` | ✅ | Returns `ProverKind::Coq` | -| `version()` | ✅ | Executes `coqc --version` | -| `parse_file()` | ✅ | Reads and parses .v files | -| `parse_string()` | ✅ | Parses Coq code from string | -| `apply_tactic()` | ✅ | Applies tactic to proof state | -| `verify_proof()` | ✅ | Verifies proof with coqc | -| `export()` | ✅ | Exports proof to Coq format | -| `suggest_tactics()` | ✅ | Neural/heuristic tactic suggestions | -| `search_theorems()` | ✅ | Searches theorems via Coq's Search command | -| `config()` | ✅ | Returns configuration | -| `set_config()` | ✅ | Updates configuration | - -## Testing - -### Test Coverage - -```rust -#[cfg(test)] -mod tests { - #[tokio::test] - async fn test_parse_simple_theorem() { ... } - - #[test] - fn test_parse_term() { ... } - - #[test] - fn test_sexp_parsing() { ... } - - #[test] - fn test_tactic_conversion() { ... } - - #[tokio::test] - async fn test_version() { ... } -} -``` - -**Test Examples**: -- ✅ Parsing identity theorem -- ✅ Term parsing (implications, forall) -- ✅ S-expression round-tripping -- ✅ Tactic conversion bidirectionality -- ✅ Version detection - -### Example Proofs Tested - -Located in `/home/user/echidna/proofs/coq/`: - -1. **basic.v** (195 lines) - - Identity, modus ponens, transitivity - - Conjunction/disjunction introduction/elimination - - Curry/uncurry - -2. **propositional.v** (324 lines) - - De Morgan's laws (constructive & classical) - - Double negation - - Excluded middle - - Peirce's law - - Contrapositive - - Distribution laws - -3. **nat.v** (367 lines) - - Addition/multiplication properties - - Commutativity, associativity - - Induction examples - - Sum formula, powers of 2, factorial - - Even/odd predicates - -4. **list.v** (488 lines) - - Append, length, reverse - - Map, fold, filter - - Nth element access - - List membership (In) - -## Dependencies - -```toml -tokio = { version = "1.35", features = ["full"] } -async-trait = "0.1" -anyhow = "1.0" -serde = { version = "1.0", features = ["derive"] } -serde_json = "1.0" -``` - -## Usage Example - -```rust -use echidna::provers::{ProverBackend, ProverConfig, ProverFactory, ProverKind}; - -// Create backend -let config = ProverConfig { - executable: PathBuf::from("/usr/bin/sertop"), - library_paths: vec![PathBuf::from("/usr/lib/coq")], - args: vec![], - timeout: 300, - neural_enabled: true, -}; - -let backend = ProverFactory::create(ProverKind::Coq, config)?; - -// Parse Coq file -let state = backend.parse_file(PathBuf::from("proof.v")).await?; - -// Apply tactic -let tactic = Tactic::Intro(Some("H".to_string())); -let result = backend.apply_tactic(&state, &tactic).await?; - -match result { - TacticResult::Success(new_state) => println!("Tactic applied!"), - TacticResult::Error(msg) => println!("Error: {}", msg), - TacticResult::QED => println!("Proof complete!"), -} - -// Verify proof -let is_valid = backend.verify_proof(&state).await?; - -// Export proof -let coq_code = backend.export(&state).await?; -``` - -## Features - -### ✅ Implemented - -1. **Complete .v file parsing** - All major Coq constructs -2. **SerAPI integration** - S-expression communication -3. **Bidirectional tactic conversion** - Universal ↔ Coq -4. **Gallina term parsing** - Full term representation -5. **Proof verification** - Autonomous checking with coqc -6. **Theorem search** - Integration with Coq's Search -7. **Neural tactic suggestion** - Heuristic-based recommendations -8. **Async/concurrent** - Tokio-based async I/O -9. **Error handling** - Comprehensive error messages -10. **Export functionality** - Generate valid Coq code - -### 🚧 Future Enhancements - -1. **Advanced SerAPI features** - Goal inspection, proof term extraction -2. **Machine learning integration** - Neural premise selection from early development -3. **Tactic composition** - Chained tactics (`;`, `||`) -4. **SSReflect support** - Small-scale reflection tactics -5. **Module system** - Import/Export, Module, Section -6. **Notation handling** - Custom notations and scopes -7. **Type class resolution** - Instance search -8. **Ltac programming** - Custom tactic definitions -9. **Performance optimization** - Caching, batch operations -10. **Rich error reporting** - Location tracking, suggestions - -## Integration with ECHIDNA - -### Prover Factory - -```rust -pub struct ProverFactory; - -impl ProverFactory { - pub fn create(kind: ProverKind, config: ProverConfig) - -> Result> - { - match kind { - ProverKind::Coq => Ok(Box::new(CoqBackend::new(config))), - // ... other provers - } - } -} -``` - -### File Detection - -```rust -impl ProverFactory { - pub fn detect_from_file(path: &PathBuf) -> Option { - path.extension()?.to_str().and_then(|ext| match ext { - "v" => Some(ProverKind::Coq), - // ... other extensions - }) - } -} -``` - -### Tier Classification - -- **Tier**: 1 (Tier 1: Original + SMT solvers) -- **Complexity**: 3/5 (Moderate) -- **Implementation Time**: 2.5 weeks (estimated) -- **Coverage**: >70% of standard theorems (as part of "Big Six") - -## Performance Characteristics - -### Parsing -- **Speed**: ~10,000 lines/second (estimated) -- **Memory**: O(n) where n = file size -- **Async**: Non-blocking I/O - -### Tactic Execution -- **Latency**: ~50-200ms per tactic (SerAPI overhead) -- **Throughput**: ~5-20 tactics/second -- **Concurrency**: Safe for parallel proof attempts - -### Verification -- **Method**: Full compilation with coqc -- **Accuracy**: 100% (delegated to Coq) -- **Speed**: Dependent on proof complexity - -## Security Considerations - -1. **Command Injection**: All user input properly escaped -2. **Path Traversal**: Validates file paths -3. **Resource Limits**: Configurable timeouts -4. **Process Isolation**: Separate sertop process per session -5. **Error Handling**: No sensitive information leakage - -## Compliance - -- ✅ **RSR/CCCP**: Rhodium Standard Repository compliant -- ✅ **Dual Licensed**: MIT + Palimpsest v0.6 -- ✅ **SPDX Headers**: All files properly tagged -- ✅ **Documentation**: Comprehensive inline docs -- ✅ **Testing**: Unit and integration tests - -## Comparison with Other Provers - -| Feature | Coq | Agda | Lean | Isabelle | -|---------|-----|------|------|----------| -| **Tactic Language** | Ltac/Ltac2 | Reflection | Lean 4 tactics | Isar | -| **Type Theory** | CIC | MLTT | DTT | HOL | -| **Automation** | High | Medium | High | Very High | -| **SerAPI Support** | ✅ Yes | ❌ No | ⚠️ Partial | ⚠️ PIDE | -| **Neural Integration** | ✅ Ready | 🚧 Planned | 🚧 Planned | 🚧 Planned | - -## Known Limitations - -1. **SerAPI Dependency**: Requires sertop installation -2. **Synchronous Execution**: Some operations block on Coq response -3. **Simplified Parsing**: Complex notations may not parse correctly -4. **Goal Inspection**: Currently returns placeholder goals (needs full SerAPI response parsing) -5. **Error Messages**: Coq errors not fully parsed into structured format - -## Roadmap - -### Phase 1 (Current) ✅ -- [x] Basic ProverBackend implementation -- [x] .v file parsing -- [x] Tactic conversion -- [x] Proof verification - -### Phase 2 (Next) -- [ ] Full SerAPI response parsing -- [ ] Real-time goal inspection -- [ ] Proof term extraction -- [ ] Performance optimizations - -### Phase 3 (Future) -- [ ] Neural premise selection integration -- [ ] ML-guided tactic synthesis -- [ ] Proof mining and learning -- [ ] Benchmark suite - -## References - -- **Coq Reference Manual**: https://coq.inria.fr/doc/ -- **SerAPI Documentation**: https://github.com/ejgallego/coq-serapi -- **ECHIDNA Documentation**: /home/user/echidna/docs/ -- **ECHIDNA Repository**: https://github.com/hyperpolymath/echidna - -## Credits - -- **Implementation**: ECHIDNA Project Team (2025) -- **Coq**: INRIA, France -- **SerAPI**: Emilio J. Gallego Arias -- **Inspiration**: ECHIDNA development - ---- - -**Status**: ✅ **PRODUCTION READY** -**Last Updated**: 2025-11-22 -**Version**: 0.1.0 diff --git a/docs/CORPUS-ADAPTERS.adoc b/docs/CORPUS-ADAPTERS.adoc new file mode 100644 index 00000000..ad5fd86f --- /dev/null +++ b/docs/CORPUS-ADAPTERS.adoc @@ -0,0 +1,169 @@ +== Corpus Adapters — Index + +*Status*: canonical. Updated 2026-06-01 as part of the saturation +campaign (see `+docs/decisions/2026-06-01-saturation-campaign.md+`). + +Each adapter is a `+pub fn ingest(root: &Path) -> Result+` in +`+src/rust/corpus/.rs+`, structurally indexing a proof tree into +`+Corpus+` (`+src/rust/corpus/mod.rs:138+`). Hazards (axioms, sorry, +believe_me, cheat, …) populate `+AxiomUsage+` per entry. + +=== Adapter table + +[width="100%",cols="20%,20%,20%,20%,20%",options="header",] +|=== +|Adapter |File extensions |Canonical source URL |Hazard flags surfaced +|Status +|*agda* |`+*.agda+` |https://github.com/agda/agda |postulate, +believe_me, assert_total, sorry, trustme |shipped pre-2026-04 + +|*coq* |`+*.v+` |https://github.com/coq/coq |Axiom, Parameter, Admitted +|shipped pre-2026-04 + +|*lean* |`+*.lean+` |https://github.com/leanprover-community/mathlib4 +|sorry, axiom, admit |shipped pre-2026-04 + +|*idris2* |`+*.idr+` / `+*.ipkg+` |https://github.com/idris-lang/Idris2 +|believe_me, assert_total, postulate |shipped pre-2026-04 + +|*isabelle* |`+*.thy+` |https://www.isa-afp.org/ |axiomatization, axiom, +sorry, oops, consts, nitpick, quickcheck |*NEW 2026-06-01* + +|*metamath* |`+*.mm+` |https://github.com/metamath/set.mm |`+$a+` axiom +usage, `+?+` admitted in proof |*NEW 2026-06-01* + +|*mizar* |`+*.miz+`, `+*.abs+` |http://mizar.org/version/8.1.14/mml/ +|`+@proof+` sketch, commented-theorem, consider-without-proof |*NEW +2026-06-01* + +|*hol_light* |`+*.ml+` (HOL Light filter) +|https://github.com/jrh13/hol-light |new_axiom, mk_thm, free ASSUME, +failwith "`not yet`" |*NEW 2026-06-01* + +|*hol4* |`+*Script.sml+` |https://github.com/HOL-Theorem-Prover/HOL +|new_axiom, mk_thm, cheat, CHEAT_TAC |*NEW 2026-06-01* + +|*dafny* |`+*.dfy+` |https://github.com/dafny-lang/dafny |assume, +`+:axiom+`, extern, expect, `+:fuel 0+` |*NEW 2026-06-01* + +|*why3* |`+*.mlw+`, `+*.why+` |https://gitlab.inria.fr/why3/why3 |axiom, +val function (uninterpreted), val lemma, assume, absurd |*NEW +2026-06-01* + +|*fstar* |`+*.fst+`, `+*.fsti+` |https://github.com/FStarLang/FStar +|assume, admit, magic, Obj.magic, unsafe_coerce, admit_smt_queries |*NEW +2026-06-01* + +|*acl2_books* |`+*.lisp+`, `+*.acl2+` |https://github.com/acl2/acl2 +|defaxiom, defstub, skip-proofs (top-level surfaced), ld-skip-proofsp, +local-in-theory-nil |*NEW 2026-06-01* + +|*tptp* |`+*.p+`, `+*.tptp+` |https://tptp.org/ |no_conjecture +(axiom-only file), TFF/THF dialects not fully supported |*NEW +2026-06-01* + +|*smtlib* |`+*.smt2+`, `+*.smt+` |https://smt-lib.org/benchmarks.shtml +|status_unknown, uninterpreted (declared-not-defined), +unnamed_bang_pattern |*NEW 2026-06-01* + +|*proofnet* |`+*.jsonl+` |https://github.com/zhangir-azerbayev/ProofNet +|sorry, admit, axiom, no_formal_proof |*NEW 2026-06-01* + +|*minif2f* |`+*.lean+`, `+*.thy+`, `+*.ml+`, `+*.mm+`, `+*.v+` (multi) +|https://github.com/openai/miniF2F |sorry, admit, Admitted, empty_body, +todo |*NEW 2026-06-01* +|=== + +=== Coverage summary + +*Pre-2026-04*: 4 adapters (agda, coq, lean, idris2). *Post-2026-06-01*: +17 adapters — 4.25× expansion. + +=== Test fixtures + +Every adapter has a minimal smoke fixture under +`+tests/corpus_fixtures//+`. Fixtures cover the happy-path decl +parse plus at least one hazard-detection case. They are intentionally +tiny — the goal is "`compile + smoke correctness`", not "`extensive +coverage`". Larger evaluation corpora live outside the repo (mathlib4 +etc. are fetched at training time via `+just provision-corpora+`). + +=== Cross-prover synonyms + +Every adapter has a corresponding per-prover synonyms TOML at +`+data/synonyms/.toml+` listing tactic / decl / hazard +vocabulary with canonical-and-aliases form. Plus three cross-prover +taxonomic dictionaries (underscore-prefix; merged into `+SynonymTable+` +via `+merge_external()+`): + +* `+_msc2020.toml+` — 87 MSC2020 codes for cross-domain classification +* `+_wordnet_math.toml+` — ~80 lemmas from WordNet 3.1 math +sub-hierarchy +* `+_conceptnet_seed.toml+` — ~55 pre-fetched ConceptNet 5.7 edges for +offline-resilient semantic_class resolution + +=== Wiring into downstream consumers + +[arabic] +. *suggest*: `+src/rust/suggest/synonyms.rs::SynonymTable::load_all()+` +reads per-prover TOMLs. The cross-prover dictionaries are loaded via +`+with_msc2020()+` / `+with_wordnet()+` / `+with_conceptnet()+` (new +methods landing in the same campaign). +. *octad emission*: `+src/rust/corpus/octad.rs::Corpus::emit_octads()+` +walks any `+Corpus+` produced by any adapter and emits 8-modality octads +into VeriSimDB (see `+docs/architecture/VERISIM-ER-SCHEMA.md+`). +. *GNN training*: `+src/julia/training/train.jl+` consumes +`+premises_.jsonl+` files under `+training_data/+`. The new +adapters can produce these files via +`+cargo run --bin corpus-emit -- --adapter --output training_data/premises_.jsonl+` +(TODO — wire CLI). + +=== When to add a new adapter + +* Upstream proof library has > 100 declarations AND +* The library has a stable file format (not a daily-changing CI +artifact) AND +* A real prover backend exists in `+src/rust/provers/+` OR it’s a +recognised ML evaluation set (ProofNet, MiniF2F, NaturalProofs, …). + +Drop the new file under `+src/rust/corpus/.rs+`, add it to +`+mod.rs+`, write at least 2 unit tests, add a fixture under +`+tests/corpus_fixtures//+`, add an entry to this index, and add +the per-prover synonyms TOML at `+data/synonyms/.toml+` (omit if +it’s a format like TPTP/SMT-LIB rather than a prover). + +=== Open backlog (next saturation wave) + +* `+src/rust/corpus/naproche.rs+` (Naproche-SAD) +* `+src/rust/corpus/mathcomp.rs+` (Coq MathComp — distinct from generic +coq.rs) +* `+src/rust/corpus/iris.rs+` (Coq Iris separation logic) +* `+src/rust/corpus/cubical_agda.rs+` (Cubical Agda stdlib) +* `+src/rust/corpus/tlaps.rs+` (TLA+ Proofs) +* `+src/rust/corpus/pvs.rs+` (PVS theories) +* `+src/rust/corpus/naturalproofs.rs+` (Bobrow et al. NL→Coq dataset) +* `+src/rust/corpus/alphaproof.rs+` (DeepMind 2024 olympiad set) + +Drop here as upstream URLs are confirmed and at least one production +consumer needs each. + +=== Type-discipline detection + +See `+docs/architecture/TYPE-DISCIPLINE-EMBEDDING.md+` for the canonical +specification. + +Every adapter calls +`+detect_disciplines(adapter_name, statement, proof, registry)+` +(`+src/rust/disciplines/detector.rs+`) on every `+CorpusEntry+` +post-extraction. The detector returns `+Vec+` against +the 39-discipline taxonomy used by the HP type-checker ecosystem +(`+src/rust/provers/hp_ecosystem.rs:63-126+`, dispatched via TypedWasm +Sigma parameters), and the result is surfaced as +`+CorpusEntry.type_discipline_tags+`. + +The tags flow through `+SemanticPayload+` +(`+src/rust/verisim_bridge.rs+`, new field per `+VERISIM-ER-SCHEMA.md+` +E2 / Cap’n Proto `+@11+`) into VeriSimDB and into the Julia GNN training +pipeline as a 39-dim multi-hot feature vector per example. See sub-table +§4 of `+TYPE-DISCIPLINE-EMBEDDING.md+` for the per-adapter × per-family +expected-hit-frequency matrix. diff --git a/docs/CORPUS-ADAPTERS.md b/docs/CORPUS-ADAPTERS.md deleted file mode 100644 index 594ac534..00000000 --- a/docs/CORPUS-ADAPTERS.md +++ /dev/null @@ -1,128 +0,0 @@ - - -# Corpus Adapters — Index - -**Status**: canonical. Updated 2026-06-01 as part of the saturation campaign -(see `docs/decisions/2026-06-01-saturation-campaign.md`). - -Each adapter is a `pub fn ingest(root: &Path) -> Result` in -`src/rust/corpus/.rs`, structurally indexing a proof tree into -`Corpus` (`src/rust/corpus/mod.rs:138`). Hazards (axioms, sorry, -believe_me, cheat, …) populate `AxiomUsage` per entry. - -## Adapter table - -| Adapter | File extensions | Canonical source URL | Hazard flags surfaced | Status | -|---|---|---|---|---| -| **agda** | `*.agda` | | postulate, believe_me, assert_total, sorry, trustme | shipped pre-2026-04 | -| **coq** | `*.v` | | Axiom, Parameter, Admitted | shipped pre-2026-04 | -| **lean** | `*.lean` | | sorry, axiom, admit | shipped pre-2026-04 | -| **idris2** | `*.idr` / `*.ipkg` | | believe_me, assert_total, postulate | shipped pre-2026-04 | -| **isabelle** | `*.thy` | | axiomatization, axiom, sorry, oops, consts, nitpick, quickcheck | **NEW 2026-06-01** | -| **metamath** | `*.mm` | | `$a` axiom usage, `?` admitted in proof | **NEW 2026-06-01** | -| **mizar** | `*.miz`, `*.abs` | | `@proof` sketch, commented-theorem, consider-without-proof | **NEW 2026-06-01** | -| **hol_light** | `*.ml` (HOL Light filter) | | new_axiom, mk_thm, free ASSUME, failwith "not yet" | **NEW 2026-06-01** | -| **hol4** | `*Script.sml` | | new_axiom, mk_thm, cheat, CHEAT_TAC | **NEW 2026-06-01** | -| **dafny** | `*.dfy` | | assume, `:axiom`, extern, expect, `:fuel 0` | **NEW 2026-06-01** | -| **why3** | `*.mlw`, `*.why` | | axiom, val function (uninterpreted), val lemma, assume, absurd | **NEW 2026-06-01** | -| **fstar** | `*.fst`, `*.fsti` | | assume, admit, magic, Obj.magic, unsafe_coerce, admit_smt_queries | **NEW 2026-06-01** | -| **acl2_books** | `*.lisp`, `*.acl2` | | defaxiom, defstub, skip-proofs (top-level surfaced), ld-skip-proofsp, local-in-theory-nil | **NEW 2026-06-01** | -| **tptp** | `*.p`, `*.tptp` | | no_conjecture (axiom-only file), TFF/THF dialects not fully supported | **NEW 2026-06-01** | -| **smtlib** | `*.smt2`, `*.smt` | | status_unknown, uninterpreted (declared-not-defined), unnamed_bang_pattern | **NEW 2026-06-01** | -| **proofnet** | `*.jsonl` | | sorry, admit, axiom, no_formal_proof | **NEW 2026-06-01** | -| **minif2f** | `*.lean`, `*.thy`, `*.ml`, `*.mm`, `*.v` (multi) | | sorry, admit, Admitted, empty_body, todo | **NEW 2026-06-01** | - -## Coverage summary - -**Pre-2026-04**: 4 adapters (agda, coq, lean, idris2). -**Post-2026-06-01**: 17 adapters — 4.25× expansion. - -## Test fixtures - -Every adapter has a minimal smoke fixture under -`tests/corpus_fixtures//`. Fixtures cover the -happy-path decl parse plus at least one hazard-detection case. -They are intentionally tiny — the goal is "compile + smoke -correctness", not "extensive coverage". Larger evaluation corpora -live outside the repo (mathlib4 etc. are fetched at training time -via `just provision-corpora`). - -## Cross-prover synonyms - -Every adapter has a corresponding per-prover synonyms TOML at -`data/synonyms/.toml` listing tactic / decl / hazard -vocabulary with canonical-and-aliases form. Plus three cross-prover -taxonomic dictionaries (underscore-prefix; merged into -`SynonymTable` via `merge_external()`): - -- `_msc2020.toml` — 87 MSC2020 codes for cross-domain classification -- `_wordnet_math.toml` — ~80 lemmas from WordNet 3.1 math sub-hierarchy -- `_conceptnet_seed.toml` — ~55 pre-fetched ConceptNet 5.7 edges - for offline-resilient semantic_class resolution - -## Wiring into downstream consumers - -1. **suggest**: `src/rust/suggest/synonyms.rs::SynonymTable::load_all()` - reads per-prover TOMLs. The cross-prover dictionaries are loaded - via `with_msc2020()` / `with_wordnet()` / `with_conceptnet()` (new - methods landing in the same campaign). - -2. **octad emission**: `src/rust/corpus/octad.rs::Corpus::emit_octads()` - walks any `Corpus` produced by any adapter and emits 8-modality - octads into VeriSimDB (see `docs/architecture/VERISIM-ER-SCHEMA.md`). - -3. **GNN training**: `src/julia/training/train.jl` consumes - `premises_.jsonl` files under `training_data/`. The new - adapters can produce these files via - `cargo run --bin corpus-emit -- --adapter --output training_data/premises_.jsonl` - (TODO — wire CLI). - -## When to add a new adapter - -- Upstream proof library has > 100 declarations AND -- The library has a stable file format (not a daily-changing CI artifact) AND -- A real prover backend exists in `src/rust/provers/` OR - it's a recognised ML evaluation set (ProofNet, MiniF2F, NaturalProofs, …). - -Drop the new file under `src/rust/corpus/.rs`, add it to -`mod.rs`, write at least 2 unit tests, add a fixture under -`tests/corpus_fixtures//`, add an entry to this index, and -add the per-prover synonyms TOML at `data/synonyms/.toml` -(omit if it's a format like TPTP/SMT-LIB rather than a prover). - -## Open backlog (next saturation wave) - -- `src/rust/corpus/naproche.rs` (Naproche-SAD) -- `src/rust/corpus/mathcomp.rs` (Coq MathComp — distinct from generic coq.rs) -- `src/rust/corpus/iris.rs` (Coq Iris separation logic) -- `src/rust/corpus/cubical_agda.rs` (Cubical Agda stdlib) -- `src/rust/corpus/tlaps.rs` (TLA+ Proofs) -- `src/rust/corpus/pvs.rs` (PVS theories) -- `src/rust/corpus/naturalproofs.rs` (Bobrow et al. NL→Coq dataset) -- `src/rust/corpus/alphaproof.rs` (DeepMind 2024 olympiad set) - -Drop here as upstream URLs are confirmed and at least one production -consumer needs each. - -## Type-discipline detection - -See `docs/architecture/TYPE-DISCIPLINE-EMBEDDING.md` for the canonical -specification. - -Every adapter calls `detect_disciplines(adapter_name, statement, proof, -registry)` (`src/rust/disciplines/detector.rs`) on every `CorpusEntry` -post-extraction. The detector returns `Vec` against the -39-discipline taxonomy used by the HP type-checker ecosystem -(`src/rust/provers/hp_ecosystem.rs:63-126`, dispatched via TypedWasm -Sigma parameters), and the result is surfaced as -`CorpusEntry.type_discipline_tags`. - -The tags flow through `SemanticPayload` -(`src/rust/verisim_bridge.rs`, new field per `VERISIM-ER-SCHEMA.md` -E2 / Cap'n Proto `@11`) into VeriSimDB and into the Julia GNN -training pipeline as a 39-dim multi-hot feature vector per example. -See sub-table §4 of `TYPE-DISCIPLINE-EMBEDDING.md` for the per-adapter -× per-family expected-hit-frequency matrix. diff --git a/docs/CORPUS.adoc b/docs/CORPUS.adoc new file mode 100644 index 00000000..aae7ec5f --- /dev/null +++ b/docs/CORPUS.adoc @@ -0,0 +1,257 @@ +== Echidna Corpus — N-dimensional, octad-shaped, cross-prover + +The corpus subsystem (`+src/rust/corpus/+`) is an N-dimensional index +over named declarations across multiple proof assistants, designed to be +the substrate for design-search, MCTS priors, and the +`+suggest+`/`+learning+` agentic surfaces. It also emits VeriSim-shaped +8-modality octads so the same data round-trips through the +`+/api/v1/octads+` endpoint. + +____ +*For the design history* see +link:decisions/2026-04-28-corpus-and-design-search.md[`+docs/decisions/2026-04-28-corpus-and-design-search.md+`]. +____ + +=== What it is + +Walks a project tree, parses every `+*.agda+` / `+*.v+` / `+*.lean+` / +`+*.idr+` file with adapter-specific heuristics, and produces: + +* A list of *modules* (`+ModuleEntry+`) with options, imports, and +back-references to their declarations. +* A list of *declarations* (`+CorpusEntry+`) with name, qualified name, +kind, statement, optional proof body, source line, forward dependencies, +and an `+AxiomUsage+` hazard flag set. +* Three indices: `+by_name+`, `+by_qualified+`, and *`+dependents+`* +(reverse-dep — the inverse of `+dependencies+`). Reverse-deps answer +"`what proofs would break if I change `+wf-<+`?`". +* A *per-entry metrics tensor* (`+EntryMetrics+`): size, connectivity, +shape (recursive vs structural), hazards, K-elimination risk, head- +symbol class. +* A *per-entry embedding* (`+Vec+`, default 32-dim hashing-trick; +GNN backend pluggable via the `+Embedder+` trait). +* An *8-modality octad* (`+DeclarationOctad+`) form for VeriSim +compatibility — semantic / temporal / provenance / document / graph / +vector / tensor / spatial. + +=== Adapters + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Prover |File extension |Notes +|Agda |`+*.agda+` +|Module/options/imports/data/record/postulate-block/typesig+multi-clause +body. Hazards: postulate, believe_me, assert_total, idris_crash. + +|Coq |`+*.v+` |`+Theorem ... Qed./Defined./Admitted.+`, `+Definition+`, +`+Fixpoint+`, `+Inductive+`, `+Record+`, `+Axiom+`. Hazards: +`+Admitted+`, `+admit+`, `+Axiom+`. + +|Lean 4 |`+*.lean+` +|`+def+`/`+theorem+`/`+lemma+`/`+inductive+`/`+structure+`/`+class+`/`+axiom+`. +Strips `+@[…]+` attributes + +`+private+`/`+protected+`/`+noncomputable+`/etc. modifiers. Hazards: +`+sorry+`, `+admit+`. + +|Idris 2 |`+*.idr+` |Same shape as Agda; `+||| …+` doc comments; +`+%foreign+`/`+%default+`/`+%hint+` pragmas. Hazards: `+believe_me+`, +`+assert_total+`, `+assert_smaller+`, `+idris_crash+`. +|=== + +=== CLI + +[source,bash] +---- +# Build an index +echidna corpus ingest --root --adapter + +# Query by name (qualified, short, or substring) +echidna corpus query [--deps] [--reverse-deps] [--reverse-closure] + +# Cosine-similarity nearest neighbours +echidna corpus near "" [--top N] + +# Cross-prover semantic-class lookup (synonym table) +echidna corpus crossquery + +# Octad emit / round-trip +echidna corpus export-octads --index --out +echidna corpus import-octads --octads --out + +# Stats +echidna corpus stats [--index ] +---- + +=== Programmatic surface — the multi-axis query DSL + +[source,rust] +---- +use echidna::corpus::{Corpus, DeclKind, query::SortKey}; + +let corpus = Corpus::load_json("data/corpus/echo-types.json")?; + +// Recursive functions, axiom-free, sorted by similarity to a goal. +let hits = corpus.query() + .where_kind(DeclKind::Function) + .where_axiom_free() + .where_recursive() + .near_text("WellFounded _<_") + .order_by(SortKey::Similarity) + .limit(10) + .run(); + +for hit in hits { + println!( + "{:.3} {} : {}", + hit.similarity.unwrap_or(0.0), + hit.entry.qualified, + hit.entry.statement + ); +} +---- + +==== Filter axes + +[width="100%",cols="50%,50%",options="header",] +|=== +|Method |What +|`+where_kind(K)+` / `+where_kind_in(&[K, …])+` |Filter by `+DeclKind+` +(Function/Data/Record/Postulate/Module). + +|`+where_axiom_free()+` |Exclude any hazard. + +|`+where_no_hazards()+` |Exclude hazards but keep declared +`+Postulate+`s. + +|`+where_recursive()+` / `+where_non_recursive()+` |Self-reference +detection from the proof body. + +|`+where_structural()+` |Constructor-pattern shape detection. + +|`+where_name_contains(s)+` / `+where_qualified_contains(s)+` |Substring +filter. + +|`+where_head_symbol(s)+` |Exact match on the statement’s first +identifier. + +|`+where_adapter(s)+` |Restrict to one prover. + +|`+where_has_reverse_deps()+` |Non-leaf entries. + +|`+where_custom(fn)+` |Escape hatch — closure over +`+(&Entry, &Metrics)+`. +|=== + +==== Similarity (Vector octad) + +[cols=",",options="header",] +|=== +|Method |What +|`+near_text("…")+` |Embed via `+HashEmbedder+`, cosine-rank. +|`+near_vector(Vec)+` |Pre-computed embedding (e.g. from a GNN). +|=== + +==== Ordering (Tensor octad metrics) + +`+SortKey::{Default, Similarity, StatementSize, ProofDepth, Fanin, Fanout}+`. + +=== File layout + +.... +src/rust/corpus/ +├── mod.rs # Corpus + CorpusEntry + ModuleEntry + DeclKind + AxiomUsage +├── agda.rs # Agda adapter +├── coq.rs # Coq adapter +├── lean.rs # Lean 4 adapter +├── idris2.rs # Idris 2 adapter +├── metrics.rs # EntryMetrics tensor (Step 4) +├── embed.rs # Embedder trait + HashEmbedder (Step 5) +├── octad.rs # DeclarationOctad (8-modality, Step 3) +└── query.rs # Multi-axis query DSL (capstone) + +data/corpus/.json # Local lossless index (gitignored) +data/corpus/.octads.jsonl # 8-modality octad export + +data/synonyms/.toml # Tactic + lemma synonyms; + # `semantic_class` field joins + # entries across provers +.... + +=== Octad shape + +Each declaration becomes one `+DeclarationOctad+` with eight modalities +(see `+corpus/octad.rs+`): + +[width="100%",cols="50%,50%",options="header",] +|=== +|Modality |Carries +|`+semantic+` |adapter, kind, name, qualified, statement, proof +|`+document+` |searchable_text + aspect tags (incl. hazard tags) +|`+graph+` |depends_on + depended_on_by + cross_prover_id +|`+provenance+` |SHA-256 hash chain over (parent, event, ts, file, line) +|`+spatial+` |file path + line + adapter namespace +|`+temporal+` |version chain — content_hash per rung +|`+tensor+` |EntryMetrics serialised as `+HashMap+` +|`+vector+` |embedding (default 32-dim HashEmbedder) +|=== + +`+cross_prover_id+` is SHA-256 of the qualified-name’s _local tail_, so +`+Foo.WellFounded+` (Agda) and `+Bar.WellFounded+` (Coq) share an +identity — cross-prover joins fall out of the graph octad without going +through the synonym layer. + +=== Synonym table cross-prover joins + +Each `+data/synonyms/.toml+` entry can carry a +`+semantic_class+` field. Entries with matching class — across any +prover — are considered equivalent under the same name: + +[source,bash] +---- +$ echidna corpus crossquery well-foundedness +Agda: WellFounded +Coq: well_founded +Lean: WellFounded +Idris2: WellFounded +4 entries across 4 prover(s) for semantic class 'well-foundedness' +---- + +Use cases: + +* *`+suggest+`* can fall back to a peer-prover’s name if the local one +isn’t found. +* *SA energy* can answer "`is `+osuc-mono+` proved in _any_ prover?`" in +one query. +* *Cross-prover proof exchange* (OpenTheory, Dedukti) consumes these +classes when translating goals. + +Currently seeded: `+well-foundedness+`, `+accessibility+`, +`+wf-induction+`, `+wf-subrelation-transport+`. More entries land +alongside the proof work that needs them. + +=== Limitations / known gaps + +* *Adapter parsers are heuristic, not full grammars.* Coq’s notation +system, Lean 4’s macros, Idris 2’s mixfix all have edge cases the +line/keyword approach misses. Verified against real fixtures; iterate as +gaps surface. +* *Dependency edges store short names.* Cross-module name collisions +widen reverse-closures (over-conservative, which is the safer side for +impact analysis). Step 3’s `+cross_prover_id+` and octad provenance can +underwrite a follow-up content-addressed dep resolver. +* *Hashing-trick embeddings collide* at 32 dims on large corpora; swap +in a GNN backend (`+Embedder+` trait) when the Julia ML pipeline is +primed against real corpora. + +=== Verified end-to-end + +[cols=",,,",options="header",] +|=== +|Repo |Adapter |Modules |Entries +|`+echo-types/proofs/agda+` |agda |57 |640 +|`+echidna/proofs/coq+` |coq |5 |108 +|`+jtv/jtv_proofs+` |lean |7 |147 +|`+eclexia/src/abi+` |idris2 |4 |93 +|=== + +1059 lib tests pass; 36 corpus-specific. diff --git a/docs/CORPUS.md b/docs/CORPUS.md deleted file mode 100644 index 66d89a6a..00000000 --- a/docs/CORPUS.md +++ /dev/null @@ -1,217 +0,0 @@ - - -# Echidna Corpus — N-dimensional, octad-shaped, cross-prover - -The corpus subsystem (`src/rust/corpus/`) is an N-dimensional index -over named declarations across multiple proof assistants, designed to -be the substrate for design-search, MCTS priors, and the -`suggest`/`learning` agentic surfaces. It also emits VeriSim-shaped -8-modality octads so the same data round-trips through the -`/api/v1/octads` endpoint. - -> **For the design history** see -> [`docs/decisions/2026-04-28-corpus-and-design-search.md`](decisions/2026-04-28-corpus-and-design-search.md). - -## What it is - -Walks a project tree, parses every `*.agda` / `*.v` / `*.lean` / -`*.idr` file with adapter-specific heuristics, and produces: - -- A list of **modules** (`ModuleEntry`) with options, imports, and - back-references to their declarations. -- A list of **declarations** (`CorpusEntry`) with name, qualified - name, kind, statement, optional proof body, source line, - forward dependencies, and an `AxiomUsage` hazard flag set. -- Three indices: `by_name`, `by_qualified`, and **`dependents`** - (reverse-dep — the inverse of `dependencies`). Reverse-deps answer - "what proofs would break if I change `wf-<`?". -- A **per-entry metrics tensor** (`EntryMetrics`): size, connectivity, - shape (recursive vs structural), hazards, K-elimination risk, head- - symbol class. -- A **per-entry embedding** (`Vec`, default 32-dim hashing-trick; - GNN backend pluggable via the `Embedder` trait). -- An **8-modality octad** (`DeclarationOctad`) form for VeriSim - compatibility — semantic / temporal / provenance / document / graph - / vector / tensor / spatial. - -## Adapters - -| Prover | File extension | Notes | -|---|---|---| -| Agda | `*.agda` | Module/options/imports/data/record/postulate-block/typesig+multi-clause body. Hazards: postulate, believe_me, assert_total, idris_crash. | -| Coq | `*.v` | `Theorem ... Qed./Defined./Admitted.`, `Definition`, `Fixpoint`, `Inductive`, `Record`, `Axiom`. Hazards: `Admitted`, `admit`, `Axiom`. | -| Lean 4 | `*.lean` | `def`/`theorem`/`lemma`/`inductive`/`structure`/`class`/`axiom`. Strips `@[…]` attributes + `private`/`protected`/`noncomputable`/etc. modifiers. Hazards: `sorry`, `admit`. | -| Idris 2 | `*.idr` | Same shape as Agda; `||| …` doc comments; `%foreign`/`%default`/`%hint` pragmas. Hazards: `believe_me`, `assert_total`, `assert_smaller`, `idris_crash`. | - -## CLI - -```bash -# Build an index -echidna corpus ingest --root --adapter - -# Query by name (qualified, short, or substring) -echidna corpus query [--deps] [--reverse-deps] [--reverse-closure] - -# Cosine-similarity nearest neighbours -echidna corpus near "" [--top N] - -# Cross-prover semantic-class lookup (synonym table) -echidna corpus crossquery - -# Octad emit / round-trip -echidna corpus export-octads --index --out -echidna corpus import-octads --octads --out - -# Stats -echidna corpus stats [--index ] -``` - -## Programmatic surface — the multi-axis query DSL - -```rust -use echidna::corpus::{Corpus, DeclKind, query::SortKey}; - -let corpus = Corpus::load_json("data/corpus/echo-types.json")?; - -// Recursive functions, axiom-free, sorted by similarity to a goal. -let hits = corpus.query() - .where_kind(DeclKind::Function) - .where_axiom_free() - .where_recursive() - .near_text("WellFounded _<_") - .order_by(SortKey::Similarity) - .limit(10) - .run(); - -for hit in hits { - println!( - "{:.3} {} : {}", - hit.similarity.unwrap_or(0.0), - hit.entry.qualified, - hit.entry.statement - ); -} -``` - -### Filter axes - -| Method | What | -|---|---| -| `where_kind(K)` / `where_kind_in(&[K, …])` | Filter by `DeclKind` (Function/Data/Record/Postulate/Module). | -| `where_axiom_free()` | Exclude any hazard. | -| `where_no_hazards()` | Exclude hazards but keep declared `Postulate`s. | -| `where_recursive()` / `where_non_recursive()` | Self-reference detection from the proof body. | -| `where_structural()` | Constructor-pattern shape detection. | -| `where_name_contains(s)` / `where_qualified_contains(s)` | Substring filter. | -| `where_head_symbol(s)` | Exact match on the statement's first identifier. | -| `where_adapter(s)` | Restrict to one prover. | -| `where_has_reverse_deps()` | Non-leaf entries. | -| `where_custom(fn)` | Escape hatch — closure over `(&Entry, &Metrics)`. | - -### Similarity (Vector octad) - -| Method | What | -|---|---| -| `near_text("…")` | Embed via `HashEmbedder`, cosine-rank. | -| `near_vector(Vec)` | Pre-computed embedding (e.g. from a GNN). | - -### Ordering (Tensor octad metrics) - -`SortKey::{Default, Similarity, StatementSize, ProofDepth, Fanin, Fanout}`. - -## File layout - -``` -src/rust/corpus/ -├── mod.rs # Corpus + CorpusEntry + ModuleEntry + DeclKind + AxiomUsage -├── agda.rs # Agda adapter -├── coq.rs # Coq adapter -├── lean.rs # Lean 4 adapter -├── idris2.rs # Idris 2 adapter -├── metrics.rs # EntryMetrics tensor (Step 4) -├── embed.rs # Embedder trait + HashEmbedder (Step 5) -├── octad.rs # DeclarationOctad (8-modality, Step 3) -└── query.rs # Multi-axis query DSL (capstone) - -data/corpus/.json # Local lossless index (gitignored) -data/corpus/.octads.jsonl # 8-modality octad export - -data/synonyms/.toml # Tactic + lemma synonyms; - # `semantic_class` field joins - # entries across provers -``` - -## Octad shape - -Each declaration becomes one `DeclarationOctad` with eight modalities -(see `corpus/octad.rs`): - -| Modality | Carries | -|---|---| -| `semantic` | adapter, kind, name, qualified, statement, proof | -| `document` | searchable_text + aspect tags (incl. hazard tags) | -| `graph` | depends_on + depended_on_by + cross_prover_id | -| `provenance`| SHA-256 hash chain over (parent, event, ts, file, line) | -| `spatial` | file path + line + adapter namespace | -| `temporal` | version chain — content_hash per rung | -| `tensor` | EntryMetrics serialised as `HashMap` | -| `vector` | embedding (default 32-dim HashEmbedder) | - -`cross_prover_id` is SHA-256 of the qualified-name's *local tail*, so -`Foo.WellFounded` (Agda) and `Bar.WellFounded` (Coq) share an -identity — cross-prover joins fall out of the graph octad without -going through the synonym layer. - -## Synonym table cross-prover joins - -Each `data/synonyms/.toml` entry can carry a `semantic_class` -field. Entries with matching class — across any prover — are -considered equivalent under the same name: - -```bash -$ echidna corpus crossquery well-foundedness -Agda: WellFounded -Coq: well_founded -Lean: WellFounded -Idris2: WellFounded -4 entries across 4 prover(s) for semantic class 'well-foundedness' -``` - -Use cases: - -- **`suggest`** can fall back to a peer-prover's name if the local - one isn't found. -- **SA energy** can answer "is `osuc-mono` proved in *any* prover?" - in one query. -- **Cross-prover proof exchange** (OpenTheory, Dedukti) consumes - these classes when translating goals. - -Currently seeded: `well-foundedness`, `accessibility`, `wf-induction`, -`wf-subrelation-transport`. More entries land alongside the proof -work that needs them. - -## Limitations / known gaps - -- **Adapter parsers are heuristic, not full grammars.** Coq's - notation system, Lean 4's macros, Idris 2's mixfix all have edge - cases the line/keyword approach misses. Verified against real - fixtures; iterate as gaps surface. -- **Dependency edges store short names.** Cross-module name - collisions widen reverse-closures (over-conservative, which is the - safer side for impact analysis). Step 3's `cross_prover_id` and - octad provenance can underwrite a follow-up content-addressed dep - resolver. -- **Hashing-trick embeddings collide** at 32 dims on large corpora; - swap in a GNN backend (`Embedder` trait) when the Julia ML - pipeline is primed against real corpora. - -## Verified end-to-end - -| Repo | Adapter | Modules | Entries | -|---|---|---|---| -| `echo-types/proofs/agda` | agda | 57 | 640 | -| `echidna/proofs/coq` | coq | 5 | 108 | -| `jtv/jtv_proofs` | lean | 7 | 147 | -| `eclexia/src/abi` | idris2 | 4 | 93 | - -1059 lib tests pass; 36 corpus-specific. diff --git a/docs/CVC5_QUICK_REFERENCE.md b/docs/CVC5_QUICK_REFERENCE.adoc similarity index 51% rename from docs/CVC5_QUICK_REFERENCE.md rename to docs/CVC5_QUICK_REFERENCE.adoc index 68ed0753..dd9735c8 100644 --- a/docs/CVC5_QUICK_REFERENCE.md +++ b/docs/CVC5_QUICK_REFERENCE.adoc @@ -1,10 +1,11 @@ -# CVC5 Backend Quick Reference +== CVC5 Backend Quick Reference -**File**: `/home/user/echidna/src/rust/provers/cvc5.rs` (719 lines) +*File*: `+/home/user/echidna/src/rust/provers/cvc5.rs+` (719 lines) -## Quick Start +=== Quick Start -```rust +[source,rust] +---- use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; use std::path::PathBuf; @@ -21,12 +22,14 @@ let state = backend.parse_file(PathBuf::from("problem.smt2")).await?; // Verify proof let valid = backend.verify_proof(&state).await?; -``` +---- -## Key Types +=== Key Types -### CVC5Config -```rust +==== CVC5Config + +[source,rust] +---- pub struct CVC5Config { pub base: ProverConfig, pub produce_proofs: bool, // default: true @@ -35,32 +38,47 @@ pub struct CVC5Config { pub incremental: bool, // default: true pub cvc5_options: HashMap, } -``` +---- + +==== SmtResult -### SmtResult -```rust +[source,rust] +---- pub enum SmtResult { Sat, // Satisfiable Unsat, // Unsatisfiable (valid theorem) Unknown, // Solver couldn't determine } -``` +---- + +=== Core Methods + +[width="100%",cols="32%,34%,34%",options="header",] +|=== +|Method |Purpose |Example +|`+new(config)+` |Create backend |`+CVC5Backend::new(config)+` + +|`+version()+` |Get CVC5 version |`+backend.version().await?+` + +|`+parse_file(path)+` |Parse SMT-LIB file +|`+backend.parse_file(path).await?+` -## Core Methods +|`+parse_string(s)+` |Parse SMT-LIB string +|`+backend.parse_string(smt).await?+` -| Method | Purpose | Example | -|--------|---------|---------| -| `new(config)` | Create backend | `CVC5Backend::new(config)` | -| `version()` | Get CVC5 version | `backend.version().await?` | -| `parse_file(path)` | Parse SMT-LIB file | `backend.parse_file(path).await?` | -| `parse_string(s)` | Parse SMT-LIB string | `backend.parse_string(smt).await?` | -| `verify_proof(state)` | Check validity | `backend.verify_proof(&state).await?` | -| `export(state)` | Generate SMT-LIB | `backend.export(&state).await?` | -| `apply_tactic(state, t)` | Execute tactic | `backend.apply_tactic(&s, &t).await?` | +|`+verify_proof(state)+` |Check validity +|`+backend.verify_proof(&state).await?+` -## Custom Tactics +|`+export(state)+` |Generate SMT-LIB |`+backend.export(&state).await?+` -```rust +|`+apply_tactic(state, t)+` |Execute tactic +|`+backend.apply_tactic(&s, &t).await?+` +|=== + +=== Custom Tactics + +[source,rust] +---- use echidna::core::Tactic; // Check satisfiability @@ -83,11 +101,12 @@ Tactic::Custom { command: "get-proof".to_string(), args: vec![], } -``` +---- -## String Theory Examples +=== String Theory Examples -```rust +[source,rust] +---- use echidna::provers::cvc5::string_examples; // String concatenation @@ -101,10 +120,12 @@ let ex3 = string_examples::string_contains(); // Regex (email validation) let ex4 = string_examples::regex_match(); -``` +---- + +==== Example SMT-LIB (String Contains) -### Example SMT-LIB (String Contains) -```smt2 +[source,smt2] +---- (set-logic QF_SLIA) (declare-const s String) (assert (str.contains s "abc")) @@ -112,11 +133,12 @@ let ex4 = string_examples::regex_match(); (assert (< (str.len s) 10)) (check-sat) (get-model) -``` +---- -## Sequence Theory Examples +=== Sequence Theory Examples -```rust +[source,rust] +---- use echidna::provers::cvc5::sequence_examples; // Sequence operations @@ -124,10 +146,12 @@ let ex1 = sequence_examples::sequence_ops(); // Subsequence containment let ex2 = sequence_examples::sequence_contains(); -``` +---- -### Example SMT-LIB (Sequences) -```smt2 +==== Example SMT-LIB (Sequences) + +[source,smt2] +---- (set-logic QF_SLIA) (declare-const s (Seq Int)) (assert (= (seq.len s) 5)) @@ -135,11 +159,12 @@ let ex2 = sequence_examples::sequence_contains(); (assert (= (seq.nth s 4) 5)) (check-sat) (get-model) -``` +---- -## Sets and Relations Examples +=== Sets and Relations Examples -```rust +[source,rust] +---- use echidna::provers::cvc5::sets_examples; // Set operations @@ -147,112 +172,138 @@ let ex1 = sets_examples::set_ops(); // Transitive closure let ex2 = sets_examples::relation_ops(); -``` +---- + +==== Example SMT-LIB (Relations) -### Example SMT-LIB (Relations) -```smt2 +[source,smt2] +---- (set-logic QF_ALL) (declare-const R (Relation Int Int)) (assert (set.member (tuple 1 2) R)) (assert (set.member (tuple 2 3) R)) (assert (set.member (tuple 1 3) (rel.tclosure R))) (check-sat) -``` +---- -## Separation Logic Examples +=== Separation Logic Examples -```rust +[source,rust] +---- use echidna::provers::cvc5::separation_logic_examples; // Heap separation let ex = separation_logic_examples::sep_logic_basic(); -``` +---- + +==== Example SMT-LIB (Separation Logic) -### Example SMT-LIB (Separation Logic) -```smt2 +[source,smt2] +---- (set-logic QF_ALL) (declare-const x Int) (declare-const y Int) (assert (sep (pto x 1) (pto y 2))) (assert (distinct x y)) (check-sat) -``` - -## Common SMT-LIB Operations - -### String Operations -| Operation | SMT-LIB | Description | -|-----------|---------|-------------| -| Concatenation | `(str.++ s1 s2)` | Concatenate strings | -| Length | `(str.len s)` | String length | -| Substring | `(str.substr s i n)` | Extract substring | -| Contains | `(str.contains s sub)` | Check substring | -| At | `(str.at s i)` | Character at index | -| Index of | `(str.indexof s sub i)` | Find substring | -| Replace | `(str.replace s old new)` | Replace substring | -| Regex | `(str.in.re s r)` | Regex matching | - -### Sequence Operations -| Operation | SMT-LIB | Description | -|-----------|---------|-------------| -| Concatenation | `(seq.++ s1 s2)` | Concatenate sequences | -| Length | `(seq.len s)` | Sequence length | -| Nth | `(seq.nth s i)` | Element at index | -| Contains | `(seq.contains s sub)` | Check subsequence | -| Extract | `(seq.extract s i n)` | Extract subsequence | -| Unit | `(seq.unit x)` | Single-element sequence | - -### Set Operations -| Operation | SMT-LIB | Description | -|-----------|---------|-------------| -| Member | `(set.member x s)` | Element membership | -| Union | `(set.union s1 s2)` | Set union | -| Intersection | `(set.inter s1 s2)` | Set intersection | -| Difference | `(set.minus s1 s2)` | Set difference | -| Subset | `(set.subset s1 s2)` | Subset test | -| Cardinality | `(set.card s)` | Set size | -| Empty | `(as set.empty (Set Int))` | Empty set | - -### Relation Operations -| Operation | SMT-LIB | Description | -|-----------|---------|-------------| -| Tuple | `(tuple x y)` | Create tuple | -| Transpose | `(rel.transpose R)` | Swap tuple elements | -| Join | `(rel.join R S)` | Relational join | -| Closure | `(rel.tclosure R)` | Transitive closure | - -## Configuration Examples - -### Enable Finite Model Finding -```rust +---- + +=== Common SMT-LIB Operations + +==== String Operations + +[cols=",,",options="header",] +|=== +|Operation |SMT-LIB |Description +|Concatenation |`+(str.++ s1 s2)+` |Concatenate strings +|Length |`+(str.len s)+` |String length +|Substring |`+(str.substr s i n)+` |Extract substring +|Contains |`+(str.contains s sub)+` |Check substring +|At |`+(str.at s i)+` |Character at index +|Index of |`+(str.indexof s sub i)+` |Find substring +|Replace |`+(str.replace s old new)+` |Replace substring +|Regex |`+(str.in.re s r)+` |Regex matching +|=== + +==== Sequence Operations + +[cols=",,",options="header",] +|=== +|Operation |SMT-LIB |Description +|Concatenation |`+(seq.++ s1 s2)+` |Concatenate sequences +|Length |`+(seq.len s)+` |Sequence length +|Nth |`+(seq.nth s i)+` |Element at index +|Contains |`+(seq.contains s sub)+` |Check subsequence +|Extract |`+(seq.extract s i n)+` |Extract subsequence +|Unit |`+(seq.unit x)+` |Single-element sequence +|=== + +==== Set Operations + +[cols=",,",options="header",] +|=== +|Operation |SMT-LIB |Description +|Member |`+(set.member x s)+` |Element membership +|Union |`+(set.union s1 s2)+` |Set union +|Intersection |`+(set.inter s1 s2)+` |Set intersection +|Difference |`+(set.minus s1 s2)+` |Set difference +|Subset |`+(set.subset s1 s2)+` |Subset test +|Cardinality |`+(set.card s)+` |Set size +|Empty |`+(as set.empty (Set Int))+` |Empty set +|=== + +==== Relation Operations + +[cols=",,",options="header",] +|=== +|Operation |SMT-LIB |Description +|Tuple |`+(tuple x y)+` |Create tuple +|Transpose |`+(rel.transpose R)+` |Swap tuple elements +|Join |`+(rel.join R S)+` |Relational join +|Closure |`+(rel.tclosure R)+` |Transitive closure +|=== + +=== Configuration Examples + +==== Enable Finite Model Finding + +[source,rust] +---- let mut config = CVC5Config::default(); config.cvc5_options.insert( "finite-model-find".to_string(), "true".to_string() ); -``` +---- -### Enable Quantifier Instantiation -```rust +==== Enable Quantifier Instantiation + +[source,rust] +---- config.cvc5_options.insert( "full-saturate-quant".to_string(), "true".to_string() ); -``` +---- + +==== Set Time Limit -### Set Time Limit -```rust +[source,rust] +---- config.base.timeout = 30; // seconds -``` +---- + +==== Enable Unsat Cores -### Enable Unsat Cores -```rust +[source,rust] +---- config.produce_unsat_cores = true; -``` +---- -## Error Handling +=== Error Handling -```rust +[source,rust] +---- use anyhow::Result; async fn solve_problem(path: PathBuf) -> Result { @@ -273,11 +324,12 @@ match solve_problem(path).await { Ok(false) => println!("Not valid"), Err(e) => eprintln!("Error: {:?}", e), } -``` +---- -## Testing +=== Testing -```bash +[source,bash] +---- # Run unit tests (no CVC5 binary needed) cargo test --package echidna --lib provers::cvc5 @@ -286,20 +338,23 @@ cargo test --package echidna cvc5 -- --ignored # Run all tests cargo test -``` +---- -## Performance Tips +=== Performance Tips -1. **Reuse Backend** - Create once, use for multiple queries -2. **Incremental Mode** - Use push/pop for related queries -3. **Simplify First** - Simplify formulas before solving -4. **Set Timeouts** - Prevent infinite solving -5. **Choose Logic** - Use specific logic (QF_SLIA) for better performance +[arabic] +. *Reuse Backend* - Create once, use for multiple queries +. *Incremental Mode* - Use push/pop for related queries +. *Simplify First* - Simplify formulas before solving +. *Set Timeouts* - Prevent infinite solving +. *Choose Logic* - Use specific logic (QF_SLIA) for better performance -## Common Patterns +=== Common Patterns -### Batch Verification -```rust +==== Batch Verification + +[source,rust] +---- let backend = CVC5Backend::new(config); for file in problem_files { @@ -307,10 +362,12 @@ for file in problem_files { let valid = backend.verify_proof(&state).await?; results.push((file, valid)); } -``` +---- + +==== Counterexample Extraction -### Counterexample Extraction -```rust +[source,rust] +---- let tactic = Tactic::Custom { prover: "cvc5".to_string(), command: "check-sat".to_string(), @@ -327,67 +384,70 @@ match backend.apply_tactic(&state, &tactic).await? { } _ => {} } -``` +---- + +==== Custom Options -### Custom Options -```rust +[source,rust] +---- let mut config = CVC5Config::default(); config.cvc5_options.insert("strings-exp".to_string(), "true".to_string()); config.cvc5_options.insert("strings-fmf".to_string(), "true".to_string()); let backend = CVC5Backend::with_config(config); -``` +---- -## Debugging +=== Debugging -### Enable Verbose Output -Add to `cvc5_options`: -```rust +==== Enable Verbose Output + +Add to `+cvc5_options+`: + +[source,rust] +---- config.cvc5_options.insert("verbose".to_string(), "true".to_string()); -``` +---- + +==== Dump SMT-LIB -### Dump SMT-LIB -```rust +[source,rust] +---- let smtlib = backend.export(&state).await?; std::fs::write("debug.smt2", smtlib)?; -``` +---- -### Check CVC5 Version -```bash +==== Check CVC5 Version + +[source,bash] +---- cvc5 --version -``` +---- + +==== Test CVC5 Directly -### Test CVC5 Directly -```bash +[source,bash] +---- cvc5 problem.smt2 -``` +---- -## When to Use CVC5 +=== When to Use CVC5 -✅ **Use CVC5 for**: -- String constraint solving -- Sequence reasoning -- Regular expression matching -- Set theory with transitive closure -- Separation logic -- Problems involving strings/sequences +✅ *Use CVC5 for*: - String constraint solving - Sequence reasoning - +Regular expression matching - Set theory with transitive closure - +Separation logic - Problems involving strings/sequences -⚠️ **Consider Z3 instead for**: -- General SMT solving -- Bit-vector reasoning -- Floating-point arithmetic -- More mature ecosystem +⚠️ *Consider Z3 instead for*: - General SMT solving - Bit-vector +reasoning - Floating-point arithmetic - More mature ecosystem -💡 **Use Both**: -- ECHIDNA supports portfolio solving -- Run both solvers in parallel -- Use fastest result +💡 *Use Both*: - ECHIDNA supports portfolio solving - Run both solvers +in parallel - Use fastest result -## Links +=== Links -- [Implementation Summary](implementation/CVC5_IMPLEMENTATION_SUMMARY.md) -- [CVC5 Documentation](https://cvc5.github.io/docs/latest/) -- [SMT-LIB Standard](https://smtlib.cs.uiowa.edu/) +* link:implementation/CVC5_IMPLEMENTATION_SUMMARY.md[Implementation +Summary] +* https://cvc5.github.io/docs/latest/[CVC5 Documentation] +* https://smtlib.cs.uiowa.edu/[SMT-LIB Standard] ---- +''''' -**Quick Reference v1.0** | ECHIDNA Project | 2025-11-22 +*Quick Reference v1.0* | ECHIDNA Project | 2025-11-22 diff --git a/docs/DEBT.adoc b/docs/DEBT.adoc new file mode 100644 index 00000000..e5059476 --- /dev/null +++ b/docs/DEBT.adoc @@ -0,0 +1,402 @@ +== Debt register + +Known, measured debt in this repository: licensing, documentation, and +code. Supersedes +link:tech-debt-2026-05-26.md[`+tech-debt-2026-05-26.md+`], which is +retained as a dated snapshot. + +*Every entry carries the command that produced its figure.* An entry +without evidence is a rumour, and rumours do not belong in a debt +register. Re-run the commands from the repository root before acting on +any item — they are the definition of the finding, not a description of +it. + +Entries are *not* issues. Where a GitHub issue already tracks an item it +is linked; where the fix requires a decision only the owner can make, +the entry says so explicitly and stops there. + +Priorities: *P0* — a downstream consumer can be actively misled or +harmed. *P1* — a reader is misinformed but not exposed. *P2* — friction, +cost, or latent risk. + +''''' + +=== P0 — Licensing: RESOLVED 2026-08-07 + +*Was:* the repository stated four different licences at once — +`+LICENSE+` and `+Cargo.toml+` said AGPL-3.0-or-later while 590 source +files granted MPL-2.0, `+NOTICE+` described the project as MPL-2.0 while +citing the AGPL file as its text, and `+.reuse/dep5+` claimed +`+PMPL-1.0 AND Palimpsest-0.6+`. Because per-file SPDX headers are +themselves a licence grant, a recipient could have taken the tree under +MPL-2.0 — which, unlike AGPL, has no network clause. + +*Now:* reconciled to the owner’s AGPL ruling as a deliberate three-part +split. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Part |Licence |Files +|Code — `+src/+`, `+crates/+`, `+ffi/+`, `+proofs/+`, `+spark/+`, +`+verification/+`, build system, CI, machine-readable metadata +|*AGPL-3.0-or-later* |594 + 6 dual + +|Documentation — `+docs/+`, top-level `+.md+` / `+.adoc+` +|*CC-BY-SA-4.0* |92 + 1 dual + +|`+echidna-playground/+` — Coq-Jr sub-project |*MPL-2.0*, unchanged |35 +|=== + +The playground was *not* relicensed: it carries contributions attributed +to "`Coq-Jr Contributors`", and relicensing another party’s work needs +their consent. It does not need relicensing — MPL-2.0 §3.3 designates +the GNU licences (including AGPL-3.0+) as Secondary Licenses, so MPL +files combine into an AGPL work and the combined work distributes under +AGPL while those files individually remain available under MPL. No file +carries the Exhibit B "`Incompatible With Secondary Licenses`" notice +that would break this. + +`+NOTICE+` and `+.reuse/dep5+` were rewritten to describe the split; +`+LICENSE+` had two prepended SPDX lines removed so it is byte-identical +to `+LICENSES/AGPL-3.0-or-later.txt+` — those lines were stopping +GitHub’s licence detector matching the body, which is why the repository +showed "`Other`". + +*Verification — these should come back clean:* + +[source,bash] +---- +# no MPL outside the playground and licence reference material +git grep -l 'SPDX-License-Identifier:.*MPL-2\.0' \ + | grep -vE '^(echidna-playground/|LICENSES/|docs/legal/)' # expect empty + +# code is AGPL +git grep -I -h -m1 -oP 'SPDX-License-Identifier:\s*\K[A-Za-z0-9.\-+]+( (AND|OR) [A-Za-z0-9.\-+]+)*' \ + -- '*.rs' '*.jl' '*.zig' ':!echidna-playground/' | sort | uniq -c + +# GitHub now detects a licence +gh repo view hyperpolymath/echidna --json licenseInfo +---- + +==== Closed — `+Palimpsest-0.6+` grants removed + +Seven files (later found to be 29) carried `+Palimpsest-0.6+` in their +SPDX identifier. The owner ruled these were never a deliberate legal +grant: `+CONTRIBUTING.adoc+` already recorded that the Palimpsest +licence proper "`is the legal licence only on `+palimpsest-license+`, +`+palimpsest-plasma+`, and (prospectively) `+consent-aware-http+``", and +that in ECHIDNA it is an _ethical framework_ reference, orthogonal to +the SPDX choice. Version 0.6 is also superseded by the +`+hyperpolymath/palimpsest-license+` repository. + +All Palimpsest SPDX identifiers were therefore removed. The framework +reference is preserved in `+CONTRIBUTING.adoc+` and `+NOTICE+`, which +now state explicitly that it is not a grant, so this cannot drift back +in silently. + +Two exclusions, deliberate: `+training_data/proof_states_v2.jsonl+` +contains SPDX strings as _scraped corpus content_ (proof goals harvested +from files, recorded as data — editing them would corrupt the corpus), +and `+docs/legal/+` holds licence reference texts. + +==== Closed — three further licence-drift classes found by the deeper sweep + +The SPDX-header sweep alone would have missed all of these. Recorded +because each is a distinct class worth re-checking after any future +licence change: + +[arabic] +. *Stale `+MIT+` grants.* `+src/affinescript/.gitignore+`, +`+styles/main.css+` and `+tailwind.config.js+` still declared +`+MIT OR Palimpsest-0.6+` — pre-dating even the MPL migration. Removing +only the Palimpsest half would have left them *MIT*. Now +AGPL-3.0-or-later. +. *Machine-readable `+license:+` fields*, which are what packaging and +tooling actually read, and which carry no `+SPDX-License-Identifier:+` +line for a header sweep to match. Eight declared MPL-2.0: +`+docs-site/.well-known/aibdp.json+` (served on the site), +`+stapeln.toml+`, `+container/manifest.toml+`, three Ada `+alire.toml+` +manifests under `+spark/+`, +`+.machine_readable/descriptiles/META.a2ml+`, and +`+0-AI-MANIFEST.a2ml+`. Plus a *nested `+src/affinescript/.reuse/dep5+`* +declaring `+MIT OR Palimpsest-0.6+` for the UI sub-tree. +. *A user-facing licence string.* `+src/affinescript/src/Main.res+` +rendered `+"MIT OR Palimpsest-0.6 License"+` in the UI — a false licence +statement shown to users, invisible to every header-based check. +. *OCI image labels* — 16 +`+LABEL org.opencontainers.image.licenses="MPL-2.0"+` across +`+Containerfile+`, `+container/Containerfile+`, and the +`+.containerization/+` tree (11 in `+Containerfile.wave3+` alone, one +per per-prover stage). These are *baked into every image published to +ghcr.io* and read by registries, SBOM generators and supply-chain +scanners, so the wrong value propagates downstream of the repository +entirely. Also `+canonical-license+` in +`+.machine_readable/anchors/ANCHOR.a2ml+` and two Idris2 `+.ipkg+` +manifests. + +*Detector for next time* — a header sweep is not sufficient: + +[source,bash] +---- +git grep -In '"license"' -- '*.json' +git grep -In '^license' -- '*.toml' '*.a2ml' +git grep -In '^licenses' -- '*.toml' +find . -name dep5 -not -path './.git/*' # nested REUSE configs +git grep -InE '"(MIT|MPL|AGPL|Apache)[^"]*"' -- 'src/' 'site/' # UI strings +git grep -In 'org.opencontainers.image.licenses' # OCI labels + +# or, exhaustively — by value rather than by file type, which is what +# actually caught the last three classes: +git grep -InE '(license|licenses|licence)\s*[:=]\s*"?(MPL-2\.0|MIT|Palimpsest)' \ + | grep -v '^echidna-playground/' +---- + +''''' + +=== P1 — Documentation + +==== D1. Prover counts drift across surfaces _(issue https://github.com/hyperpolymath/echidna/issues/251[#251])_ + +*Largely addressed* in the documentation refresh that added this file; +recorded because the underlying cause is structural and will recur. + +The tree contained five different counts — 48, 105, 128, 138, 141 — +because four different things are all called "`the number of provers`": +enum variants (141), implementation files (105), implementations with +`+suggest_tactics+` (102), and default-exposed core backends (12). All +four are defensible; none is "`the`" count. +link:PROVER_COUNT.md[`+PROVER_COUNT.md+`] is now canonical, carries the +commands that reproduce each figure, and explains the denominators. + +*Residual risk:* the `+R5a+` CI rule +(`+.github/canonical-references/prover-counts.yml+`) that forbids bare +counts covers only the top-level document set named in that file. +`+docs/+`, `+.machine_readable/+`, `+crates/*/README.md+` and +`+.github/*.md+` are *out of scope*, which is precisely where the drift +accumulated. Extending the rule’s scope is unfinished work. + +==== D2. Tier membership is hand-maintained and unverifiable + +`+PROVER_COUNT.md+`’s tier table is the routing contract, but only Tier +1 (`+ProverKind::all_core()+`) and Tier 9 are machine-checkable. Tier +4’s "`19 placeholder backends`" and Tier 8’s "`13 corpus-only provers`" +are asserted, not derived, and were not re-measured in this pass — they +are marked as indicative in the table. Making tier membership an +attribute on each `+ProverKind+` variant would make the table generated +rather than maintained. + +==== D3. Unearned OpenSSF Best Practices badge + +`+README.md+` displays a hardcoded green "`OpenSSF Best Practices`" +badge that links to the project *registration* form, not to a passing +scorecard: + +[source,bash] +---- +grep -oE 'bestpractices.dev[^)]*' README.md +# bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/echidna +---- + +The badge image is a static `+img.shields.io+` green label, so it will +read as "`passed`" regardless of the project’s actual standing — +including now, when the project is not registered. Either register the +project and use the real badge (which reflects the true tier and changes +when it lapses), or remove the badge. A permanently-green badge that +cannot fail is indistinguishable from a false claim. This is a known +estate-wide pattern, not unique to this repository. + +==== D4. Broken links in historical release notes + +Nine dead links remain in `+docs/releases/RELEASE_NOTES_v1.2.md+` and +`+RELEASE_NOTES_v1.3.md+`, pointing at design documents that are not in +the tree (`+CHAPEL_METALAYER_ANALYSIS.md+`, `+ZIG_FFI_ANALYSIS.md+`, +`+FUTURE_DEVELOPMENT_ROADMAP.md+`, `+QUICKSTART.md+`, and others). Live +documents were repaired in the refresh; these were deliberately left, +because release notes are dated records and rewriting them rewrites +history. They should either be de-linked in place or the referenced +documents restored from git history. + +[source,bash] +---- +# re-measure broken relative links across all Markdown/AsciiDoc +git grep -nE '\]\([A-Za-z0-9_./-]+\.(md|adoc)\)' -- '*.md' '*.adoc' | while IFS= read -r l; do + src="${l%%:*}"; ref=$(echo "$l" | grep -oE '\]\([A-Za-z0-9_./-]+\)' | sed -E 's/^\]\(//;s/\)$//') + for r in $ref; do [ -e "$(dirname "$src")/$r" ] || echo "$src -> $r"; done +done +---- + +==== D5. `+echidna-playground/SECURITY.md+` references absent files + +It links to `+README.md+`, `+CHANGELOG.md+`, `+CONTRIBUTING.md+` and +`+SECURITY-ACKNOWLEDGMENTS.md+` inside `+echidna-playground/+`; none +exist (`+ls echidna-playground/+`). The sub-project’s security policy +therefore directs a reporter to nothing. Either add the files or point +the links at the parent repository’s equivalents. + +==== D6. Root scaffold documents displaced the real ones — _fixed, recorded_ + +`+ARCHITECTURE.md+` and `+GOVERNANCE.md+` at the repository root +contained generic template text with *zero* project-specific content, +while the real documents sat at `+docs/ARCHITECTURE.md+` (160 lines) and +`+GOVERNANCE.adoc+` (162 lines): + +[source,bash] +---- +grep -icE 'echidna|prover|neurosym|trust' ARCHITECTURE.md # was 0 +grep -icE 'echidna|prover|RSR|hyperpolymath' GOVERNANCE.md # was 0 +---- + +This was worse than duplication. GitHub surfaces the `+.md+` member in +its community-standards checks and contributor prompts, so the document +most readers landed on described a project that could have been +anything. Both are now explicit pointers to the canonical documents, +following the pattern `+CONTRIBUTING.md+` already used correctly. + +*Watch for recurrence:* these files match the estate’s scaffold-template +shape, so a future template sweep may reinstate them. The check above is +the detector — a root `+.md+` scoring 0 is scaffold, not documentation. + +==== D7. `+.machine_readable/6a2/+` no longer exists + +The six descriptiles moved to `+.machine_readable/descriptiles/+`. +Seventeen documents pointed at the old path and were repaired in the +refresh, but the contractile configurations still name +`+.machine_readable/6a2/DRIFT.a2ml+` and +`+.machine_readable/6a2/ratification-.a2ml+` as *write +destinations*: + +[source,bash] +---- +git grep -n '6a2/' -- '*.ncl' +---- + +Those were left alone deliberately: `+6a2+` is a concept name there, not +a stale path, and changing a contractile’s evidence sink is a semantic +decision. But the directory does not exist, so any drift-log write has +nowhere to land. Confirm whether the sink should be created or +repointed. + +''''' + +=== P2 — Code + +==== C1. AffineScript — removed 2026-08 + +The 37 AffineScript files (24 in `+src/affinescript/+`, 13 orphaned +`+.res+` prover clients in `+src/provers/+`) were deleted, along with +the build and CI wiring that referenced them. AffineScript is a banned +language under the estate policy. + +*The replacement is not ready, and that is now visible rather than +hidden.* The AffineScript-TEA sources sit at `+src/ui/tea/+` but the +compile pipeline is unwired, blocked on missing primitives — +`+Http::fetch+`, `+Async+`, `+Json+` — tracked in +https://github.com/hyperpolymath/echidna/issues/266[#266] and +https://github.com/hyperpolymath/echidna/issues/117[#117]. +`+just build-ui+` now *fails with an explanatory message* instead of +silently doing nothing; `+serve-ui+` serves the static shell at +`+src/ui/public/+`. + +`+echidna-playground/+` keeps its 8 `+.res+` files: that sub-project +carries Coq-Jr contributions, so removing them is a separate decision +from a language-policy cleanup. + +==== C1b. `+.gitlab-ci.yml+` is not valid YAML + +`+python3 -c "import yaml; yaml.safe_load(open('.gitlab-ci.yml'))"+` +fails on a bare `+%+` inside an unquoted shell command. *Pre-existing* — +verified by parsing the file at `+HEAD+` before the AffineScript removal +shifted the line number. Whether it matters depends on whether the +GitLab mirror actually runs CI; if it does not, the file is decorative +and should say so or go. + +==== C2. 185 `+#[allow(dead_code)]+` suppressions + +[source,bash] +---- +git grep -c 'allow(dead_code)' -- '*.rs' | awk -F: '{s+=$2} END{print s}' +---- + +Each one silences the compiler’s own report of unreachable code. At this +volume the suppressions, not the compiler, define what counts as live +code — so genuine dead code is no longer detectable. Worth a pass to +distinguish scaffolding-for-planned-work (annotate with the tracking +issue) from code that should be deleted. + +==== C3. Placeholder backends are indistinguishable from working ones at the API + +Tier 4 backends are `+ProverKind+` variants with mock-only invocation, +but they are reachable through the same `+ProverKind+` selection as real +ones. A caller selecting one receives a response shaped like a proof +result. `+container-ci.yml+` runs stub-sentinel detection for Tier-3 +cells; the corresponding guarantee for Tier-4 placeholders at the API +boundary is not documented. Related: D2 — the placeholder count itself +is unverified. + +==== C4. `+Dogfood Gate+` fails K9 validation on `+main+` + +Observed 2026-08-07 on every PR run: + +.... +Hunt-level K9 file must include a 'signature' or 'signature_required' field +K9 validation failed with 1 error(s) +.... + +A contractile/K9 schema requirement that the repository’s own hunt-level +K9 file does not satisfy — the dogfooding gate cannot pass its own +rules. Not diagnosed further here; reproduce with +`+gh run list -R hyperpolymath/echidna --workflow "Dogfood Gate"+` and +read the failing step. + +==== C5. `+Rust CI+` test failures on `+main+` + +`+cargo test --tests --workspace --locked+` exits 101 under +`+llvm-cov+`. This is a genuine test failure, not infrastructure: it +appears *after* the toolchain installs and the workspace builds. +Distinguish it from the lockfile-pin startup failures that affected the +same workflow until the `+dtolnay/rust-toolchain@stable+` relock — those +failed _before_ running a step and produced no test output. Individual +failing tests have not been enumerated; that is the next action. + +`+Secret Scanner+` also exits 1 on `+main+`; likely the dead +`+VERISIMDB_PAT+` already tracked in +https://github.com/hyperpolymath/echidna/issues/310[#310], but not +confirmed here. + +==== C6. Unfinished-work markers + +Low and healthy for a tree this size — recorded as a baseline to watch: + +[source,bash] +---- +git grep -cE 'TODO|FIXME|XXX' -- '*.rs' | awk -F: '{s+=$2} END{print s}' # 11 across 6 files +git grep -cE 'todo!\(\)|unimplemented!\(\)' -- '*.rs' | awk -F: '{s+=$2} END{print s}' # 1 +---- + +''''' + +=== Already tracked as issues + +Open issues covering debt not duplicated above: +https://github.com/hyperpolymath/echidna/issues/314[#314] (hypatia +baseline gate un-armed — currently the reason `+Governance+` fails on +`+main+`), https://github.com/hyperpolymath/echidna/issues/310[#310] +(dead `+VERISIMDB_PAT+`), +https://github.com/hyperpolymath/echidna/issues/252[#252] +(machine-readable currency audit), +https://github.com/hyperpolymath/echidna/issues/242[#242] (structural +drift in path references), +https://github.com/hyperpolymath/echidna/issues/240[#240] (AffineScript +deprecated-API triage), +https://github.com/hyperpolymath/echidna/issues/239[#239] (safety-alert +classification), +https://github.com/hyperpolymath/echidna/issues/216[#216] +(SPDX-FileCopyrightText hook blocks commits — a licensing-adjacent item +that should be resolved alongside P0). + +=== Maintaining this file + +Add an entry when you find debt you are not fixing in the same change. +Include the command that measures it. Remove an entry only when the +command that detected it comes back clean — not when the work "`feels +done`". diff --git a/docs/DEBT.md b/docs/DEBT.md deleted file mode 100644 index f72b4914..00000000 --- a/docs/DEBT.md +++ /dev/null @@ -1,356 +0,0 @@ - - - -# Debt register - -Known, measured debt in this repository: licensing, documentation, and code. -Supersedes [`tech-debt-2026-05-26.md`](tech-debt-2026-05-26.md), which is -retained as a dated snapshot. - -**Every entry carries the command that produced its figure.** An entry without -evidence is a rumour, and rumours do not belong in a debt register. Re-run the -commands from the repository root before acting on any item — they are the -definition of the finding, not a description of it. - -Entries are **not** issues. Where a GitHub issue already tracks an item it is -linked; where the fix requires a decision only the owner can make, the entry -says so explicitly and stops there. - -Priorities: **P0** — a downstream consumer can be actively misled or harmed. -**P1** — a reader is misinformed but not exposed. **P2** — friction, cost, or -latent risk. - ---- - -## P0 — Licensing: RESOLVED 2026-08-07 - -**Was:** the repository stated four different licences at once — `LICENSE` and -`Cargo.toml` said AGPL-3.0-or-later while 590 source files granted MPL-2.0, -`NOTICE` described the project as MPL-2.0 while citing the AGPL file as its -text, and `.reuse/dep5` claimed `PMPL-1.0 AND Palimpsest-0.6`. Because -per-file SPDX headers are themselves a licence grant, a recipient could have -taken the tree under MPL-2.0 — which, unlike AGPL, has no network clause. - -**Now:** reconciled to the owner's AGPL ruling as a deliberate three-part -split. - -| Part | Licence | Files | -|---|---|---| -| Code — `src/`, `crates/`, `ffi/`, `proofs/`, `spark/`, `verification/`, build system, CI, machine-readable metadata | **AGPL-3.0-or-later** | 594 + 6 dual | -| Documentation — `docs/`, top-level `.md` / `.adoc` | **CC-BY-SA-4.0** | 92 + 1 dual | -| `echidna-playground/` — Coq-Jr sub-project | **MPL-2.0**, unchanged | 35 | - -The playground was **not** relicensed: it carries contributions attributed to -"Coq-Jr Contributors", and relicensing another party's work needs their -consent. It does not need relicensing — MPL-2.0 §3.3 designates the GNU -licences (including AGPL-3.0+) as Secondary Licenses, so MPL files combine -into an AGPL work and the combined work distributes under AGPL while those -files individually remain available under MPL. No file carries the Exhibit B -"Incompatible With Secondary Licenses" notice that would break this. - -`NOTICE` and `.reuse/dep5` were rewritten to describe the split; `LICENSE` -had two prepended SPDX lines removed so it is byte-identical to -`LICENSES/AGPL-3.0-or-later.txt` — those lines were stopping GitHub's licence -detector matching the body, which is why the repository showed "Other". - -**Verification — these should come back clean:** - -```bash -# no MPL outside the playground and licence reference material -git grep -l 'SPDX-License-Identifier:.*MPL-2\.0' \ - | grep -vE '^(echidna-playground/|LICENSES/|docs/legal/)' # expect empty - -# code is AGPL -git grep -I -h -m1 -oP 'SPDX-License-Identifier:\s*\K[A-Za-z0-9.\-+]+( (AND|OR) [A-Za-z0-9.\-+]+)*' \ - -- '*.rs' '*.jl' '*.zig' ':!echidna-playground/' | sort | uniq -c - -# GitHub now detects a licence -gh repo view hyperpolymath/echidna --json licenseInfo -``` - -### Closed — `Palimpsest-0.6` grants removed - -Seven files (later found to be 29) carried `Palimpsest-0.6` in their SPDX -identifier. The owner ruled these were never a deliberate legal grant: -`CONTRIBUTING.adoc` already recorded that the Palimpsest licence proper "is -the legal licence only on `palimpsest-license`, `palimpsest-plasma`, and -(prospectively) `consent-aware-http`", and that in ECHIDNA it is an *ethical -framework* reference, orthogonal to the SPDX choice. Version 0.6 is also -superseded by the `hyperpolymath/palimpsest-license` repository. - -All Palimpsest SPDX identifiers were therefore removed. The framework -reference is preserved in `CONTRIBUTING.adoc` and `NOTICE`, which now state -explicitly that it is not a grant, so this cannot drift back in silently. - -Two exclusions, deliberate: `training_data/proof_states_v2.jsonl` contains -SPDX strings as *scraped corpus content* (proof goals harvested from files, -recorded as data — editing them would corrupt the corpus), and `docs/legal/` -holds licence reference texts. - -### Closed — three further licence-drift classes found by the deeper sweep - -The SPDX-header sweep alone would have missed all of these. Recorded because -each is a distinct class worth re-checking after any future licence change: - -1. **Stale `MIT` grants.** `src/affinescript/.gitignore`, `styles/main.css` and - `tailwind.config.js` still declared `MIT OR Palimpsest-0.6` — pre-dating - even the MPL migration. Removing only the Palimpsest half would have left - them **MIT**. Now AGPL-3.0-or-later. -2. **Machine-readable `license:` fields**, which are what packaging and - tooling actually read, and which carry no `SPDX-License-Identifier:` line - for a header sweep to match. Eight declared MPL-2.0: - `docs-site/.well-known/aibdp.json` (served on the site), `stapeln.toml`, - `container/manifest.toml`, three Ada `alire.toml` manifests under `spark/`, - `.machine_readable/descriptiles/META.a2ml`, and `0-AI-MANIFEST.a2ml`. - Plus a **nested `src/affinescript/.reuse/dep5`** declaring `MIT OR - Palimpsest-0.6` for the UI sub-tree. -3. **A user-facing licence string.** `src/affinescript/src/Main.res` rendered - `"MIT OR Palimpsest-0.6 License"` in the UI — a false licence statement - shown to users, invisible to every header-based check. -4. **OCI image labels** — 16 `LABEL org.opencontainers.image.licenses="MPL-2.0"` - across `Containerfile`, `container/Containerfile`, and the - `.containerization/` tree (11 in `Containerfile.wave3` alone, one per - per-prover stage). These are **baked into every image published to - ghcr.io** and read by registries, SBOM generators and supply-chain - scanners, so the wrong value propagates downstream of the repository - entirely. Also `canonical-license` in - `.machine_readable/anchors/ANCHOR.a2ml` and two Idris2 `.ipkg` manifests. - -**Detector for next time** — a header sweep is not sufficient: - -```bash -git grep -In '"license"' -- '*.json' -git grep -In '^license' -- '*.toml' '*.a2ml' -git grep -In '^licenses' -- '*.toml' -find . -name dep5 -not -path './.git/*' # nested REUSE configs -git grep -InE '"(MIT|MPL|AGPL|Apache)[^"]*"' -- 'src/' 'site/' # UI strings -git grep -In 'org.opencontainers.image.licenses' # OCI labels - -# or, exhaustively — by value rather than by file type, which is what -# actually caught the last three classes: -git grep -InE '(license|licenses|licence)\s*[:=]\s*"?(MPL-2\.0|MIT|Palimpsest)' \ - | grep -v '^echidna-playground/' -``` - ---- - -## P1 — Documentation - -### D1. Prover counts drift across surfaces *(issue [#251](https://github.com/hyperpolymath/echidna/issues/251))* - -**Largely addressed** in the documentation refresh that added this file; recorded -because the underlying cause is structural and will recur. - -The tree contained five different counts — 48, 105, 128, 138, 141 — because -four different things are all called "the number of provers": enum variants -(141), implementation files (105), implementations with `suggest_tactics` -(102), and default-exposed core backends (12). All four are defensible; none is -"the" count. [`PROVER_COUNT.md`](PROVER_COUNT.md) is now canonical, carries the -commands that reproduce each figure, and explains the denominators. - -**Residual risk:** the `R5a` CI rule -(`.github/canonical-references/prover-counts.yml`) that forbids bare counts -covers only the top-level document set named in that file. `docs/`, -`.machine_readable/`, `crates/*/README.md` and `.github/*.md` are **out of -scope**, which is precisely where the drift accumulated. Extending the rule's -scope is unfinished work. - -### D2. Tier membership is hand-maintained and unverifiable - -`PROVER_COUNT.md`'s tier table is the routing contract, but only Tier 1 -(`ProverKind::all_core()`) and Tier 9 are machine-checkable. Tier 4's -"19 placeholder backends" and Tier 8's "13 corpus-only provers" are asserted, -not derived, and were not re-measured in this pass — they are marked as -indicative in the table. Making tier membership an attribute on each -`ProverKind` variant would make the table generated rather than maintained. - -### D3. Unearned OpenSSF Best Practices badge - -`README.md` displays a hardcoded green "OpenSSF Best Practices" badge that -links to the project **registration** form, not to a passing scorecard: - -```bash -grep -oE 'bestpractices.dev[^)]*' README.md -# bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/echidna -``` - -The badge image is a static `img.shields.io` green label, so it will read as -"passed" regardless of the project's actual standing — including now, when the -project is not registered. Either register the project and use the real badge -(which reflects the true tier and changes when it lapses), or remove the badge. -A permanently-green badge that cannot fail is indistinguishable from a false -claim. This is a known estate-wide pattern, not unique to this repository. - -### D4. Broken links in historical release notes - -Nine dead links remain in `docs/releases/RELEASE_NOTES_v1.2.md` and -`RELEASE_NOTES_v1.3.md`, pointing at design documents that are not in the tree -(`CHAPEL_METALAYER_ANALYSIS.md`, `ZIG_FFI_ANALYSIS.md`, -`FUTURE_DEVELOPMENT_ROADMAP.md`, `QUICKSTART.md`, and others). Live documents -were repaired in the refresh; these were deliberately left, because release -notes are dated records and rewriting them rewrites history. They should either -be de-linked in place or the referenced documents restored from git history. - -```bash -# re-measure broken relative links across all Markdown/AsciiDoc -git grep -nE '\]\([A-Za-z0-9_./-]+\.(md|adoc)\)' -- '*.md' '*.adoc' | while IFS= read -r l; do - src="${l%%:*}"; ref=$(echo "$l" | grep -oE '\]\([A-Za-z0-9_./-]+\)' | sed -E 's/^\]\(//;s/\)$//') - for r in $ref; do [ -e "$(dirname "$src")/$r" ] || echo "$src -> $r"; done -done -``` - -### D5. `echidna-playground/SECURITY.md` references absent files - -It links to `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md` and -`SECURITY-ACKNOWLEDGMENTS.md` inside `echidna-playground/`; none exist -(`ls echidna-playground/`). The sub-project's security policy therefore -directs a reporter to nothing. Either add the files or point the links at the -parent repository's equivalents. - -### D6. Root scaffold documents displaced the real ones — *fixed, recorded* - -`ARCHITECTURE.md` and `GOVERNANCE.md` at the repository root contained generic -template text with **zero** project-specific content, while the real documents -sat at `docs/ARCHITECTURE.md` (160 lines) and `GOVERNANCE.adoc` (162 lines): - -```bash -grep -icE 'echidna|prover|neurosym|trust' ARCHITECTURE.md # was 0 -grep -icE 'echidna|prover|RSR|hyperpolymath' GOVERNANCE.md # was 0 -``` - -This was worse than duplication. GitHub surfaces the `.md` member in its -community-standards checks and contributor prompts, so the document most -readers landed on described a project that could have been anything. Both are -now explicit pointers to the canonical documents, following the pattern -`CONTRIBUTING.md` already used correctly. - -**Watch for recurrence:** these files match the estate's scaffold-template -shape, so a future template sweep may reinstate them. The check above is the -detector — a root `.md` scoring 0 is scaffold, not documentation. - -### D7. `.machine_readable/6a2/` no longer exists - -The six descriptiles moved to `.machine_readable/descriptiles/`. Seventeen -documents pointed at the old path and were repaired in the refresh, but the -contractile configurations still name `.machine_readable/6a2/DRIFT.a2ml` and -`.machine_readable/6a2/ratification-.a2ml` as **write -destinations**: - -```bash -git grep -n '6a2/' -- '*.ncl' -``` - -Those were left alone deliberately: `6a2` is a concept name there, not a stale -path, and changing a contractile's evidence sink is a semantic decision. But the -directory does not exist, so any drift-log write has nowhere to land. Confirm -whether the sink should be created or repointed. - ---- - -## P2 — Code - -### C1. AffineScript — removed 2026-08 - -The 37 AffineScript files (24 in `src/affinescript/`, 13 orphaned `.res` prover -clients in `src/provers/`) were deleted, along with the build and CI wiring -that referenced them. AffineScript is a banned language under the estate policy. - -**The replacement is not ready, and that is now visible rather than hidden.** -The AffineScript-TEA sources sit at `src/ui/tea/` but the compile pipeline is -unwired, blocked on missing primitives — `Http::fetch`, `Async`, `Json` — -tracked in [#266](https://github.com/hyperpolymath/echidna/issues/266) and -[#117](https://github.com/hyperpolymath/echidna/issues/117). `just build-ui` -now **fails with an explanatory message** instead of silently doing nothing; -`serve-ui` serves the static shell at `src/ui/public/`. - -`echidna-playground/` keeps its 8 `.res` files: that sub-project carries -Coq-Jr contributions, so removing them is a separate decision from a -language-policy cleanup. - -### C1b. `.gitlab-ci.yml` is not valid YAML - -`python3 -c "import yaml; yaml.safe_load(open('.gitlab-ci.yml'))"` fails on a -bare `%` inside an unquoted shell command. **Pre-existing** — verified by -parsing the file at `HEAD` before the AffineScript removal shifted the line -number. Whether it matters depends on whether the GitLab mirror actually runs -CI; if it does not, the file is decorative and should say so or go. - -### C2. 185 `#[allow(dead_code)]` suppressions - -```bash -git grep -c 'allow(dead_code)' -- '*.rs' | awk -F: '{s+=$2} END{print s}' -``` - -Each one silences the compiler's own report of unreachable code. At this volume -the suppressions, not the compiler, define what counts as live code — so genuine -dead code is no longer detectable. Worth a pass to distinguish -scaffolding-for-planned-work (annotate with the tracking issue) from code that -should be deleted. - -### C3. Placeholder backends are indistinguishable from working ones at the API - -Tier 4 backends are `ProverKind` variants with mock-only invocation, but they -are reachable through the same `ProverKind` selection as real ones. A caller -selecting one receives a response shaped like a proof result. `container-ci.yml` -runs stub-sentinel detection for Tier-3 cells; the corresponding guarantee for -Tier-4 placeholders at the API boundary is not documented. Related: D2 — the -placeholder count itself is unverified. - -### C4. `Dogfood Gate` fails K9 validation on `main` - -Observed 2026-08-07 on every PR run: - -``` -Hunt-level K9 file must include a 'signature' or 'signature_required' field -K9 validation failed with 1 error(s) -``` - -A contractile/K9 schema requirement that the repository's own hunt-level K9 -file does not satisfy — the dogfooding gate cannot pass its own rules. Not -diagnosed further here; reproduce with -`gh run list -R hyperpolymath/echidna --workflow "Dogfood Gate"` and read the -failing step. - -### C5. `Rust CI` test failures on `main` - -`cargo test --tests --workspace --locked` exits 101 under `llvm-cov`. This is a -genuine test failure, not infrastructure: it appears **after** the toolchain -installs and the workspace builds. Distinguish it from the lockfile-pin -startup failures that affected the same workflow until the -`dtolnay/rust-toolchain@stable` relock — those failed *before* running a step -and produced no test output. Individual failing tests have not been -enumerated; that is the next action. - -`Secret Scanner` also exits 1 on `main`; likely the dead `VERISIMDB_PAT` -already tracked in [#310](https://github.com/hyperpolymath/echidna/issues/310), -but not confirmed here. - -### C6. Unfinished-work markers - -Low and healthy for a tree this size — recorded as a baseline to watch: - -```bash -git grep -cE 'TODO|FIXME|XXX' -- '*.rs' | awk -F: '{s+=$2} END{print s}' # 11 across 6 files -git grep -cE 'todo!\(\)|unimplemented!\(\)' -- '*.rs' | awk -F: '{s+=$2} END{print s}' # 1 -``` - ---- - -## Already tracked as issues - -Open issues covering debt not duplicated above: [#314](https://github.com/hyperpolymath/echidna/issues/314) -(hypatia baseline gate un-armed — currently the reason `Governance` fails on -`main`), [#310](https://github.com/hyperpolymath/echidna/issues/310) (dead -`VERISIMDB_PAT`), [#252](https://github.com/hyperpolymath/echidna/issues/252) -(machine-readable currency audit), [#242](https://github.com/hyperpolymath/echidna/issues/242) -(structural drift in path references), [#240](https://github.com/hyperpolymath/echidna/issues/240) -(AffineScript deprecated-API triage), [#239](https://github.com/hyperpolymath/echidna/issues/239) -(safety-alert classification), [#216](https://github.com/hyperpolymath/echidna/issues/216) -(SPDX-FileCopyrightText hook blocks commits — a licensing-adjacent item that -should be resolved alongside P0). - -## Maintaining this file - -Add an entry when you find debt you are not fixing in the same change. Include -the command that measures it. Remove an entry only when the command that -detected it comes back clean — not when the work "feels done". diff --git a/docs/ECOSYSTEM-INTEGRATION.adoc b/docs/ECOSYSTEM-INTEGRATION.adoc new file mode 100644 index 00000000..3a6dcc3c --- /dev/null +++ b/docs/ECOSYSTEM-INTEGRATION.adoc @@ -0,0 +1,194 @@ +== ECHIDNA Ecosystem Integration Status + +=== Overview + +ECHIDNA is integrated with the Hyperpolymath ecosystem for continuous +quality assurance, security scanning, and formal verification. + +=== Integration Status (2026-02-12) + +[width="100%",cols="36%,30%,34%",options="header",] +|=== +|Service |Status |Details +|*gitbot-fleet* |✅ Complete |Fleet integration module implemented, +registered as Tier 1 Verifier + +|*echidnabot* |✅ Self-configured |`+.echidnabot.toml+` added for +self-verification + +|*panic-attacker* |✅ Scanned |Final scan: 50 weak points (down from 82, +39% reduction) + +|*VeriSimDB* |🔄 Manual |Scan results can be ingested via manual +workflow + +|*Hypatia* |🔄 POC |Hypatia learning engine can process findings + +|*git-private-farm* |📝 Documented |Listed in bots group, needs repos +section entry +|=== + +=== Gitbot-Fleet Integration ✅ + +*Status*: COMPLETE + +*What Was Done*: - Created `+echidnabot/src/fleet.rs+` integration +module - Added gitbot-shared-context dependency - Registered as Tier 1 +Verifier bot - 5 finding rule types (ECHIDNA-VERIFY-001 through 005) - +Full test coverage (4 tests passing) - Documentation: +`+echidnabot/FLEET-INTEGRATION.md+` + +*How to Use*: + +[source,rust] +---- +use echidnabot::fleet::FleetIntegration; + +let mut fleet = FleetIntegration::new("my-repo", "/path/to/repo"); +fleet.start()?; + +// Verify proofs and add findings... +for proof_file in proof_files { + let result = echidna_client.verify_proof(prover, &content).await?; + fleet.add_proof_result(&proof_file, &theorem_name, &prover_name, &result); +} + +fleet.complete(findings.len(), errors, files_analyzed)?; +---- + +=== Echidnabot Self-Verification ✅ + +*Status*: COMPLETE + +*Configuration*: `+.echidnabot.toml+` + +*What It Does*: - Verifies ECHIDNA’s own Idris2 ABI definitions +(`+src/abi/+`) - Checks Rust FFI safety properties - Runs SMT solvers on +property specifications - Self-hosting: ECHIDNA verifies its own +correctness + +*Critical Modules*: - `+Foreign.idr+` - FFI safety proofs - +`+Types.idr+` - Core type definitions - `+Layout.idr+` - Memory layout +verification + +=== Panic-Attacker Security Scanning ✅ + +*Status*: COMPLETE + +*Results*: - *Previous*: 82 weak points (3 Critical, 4 High, 70 Medium, +5 Low) - *Current*: 50 weak points (3 Critical, 4 High, 38 Medium, 5 +Low) - *Improvement*: 32 issues fixed (39% reduction) + +*Remaining Issues*: All legitimate or false positives - FFI unsafe +blocks (documented) - Vendor code in HOL/ directory (gitignored) - +Chapel FFI (feature-gated, optional) + +*Report*: `+SECURITY-SCAN-FINAL.md+` + +=== VeriSimDB Integration 🔄 + +*Status*: Manual workflow available + +*How It Works*: 1. Run `+panic-attack assail+` on echidna repo 2. +Generate JSON output with weak points 3. Run +`+verisim-data/scripts/ingest-scan.sh echidna /tmp/scan.json+` 4. Push +to verisim-data repo 5. Hypatia processes findings and learns patterns + +*Command*: + +[source,bash] +---- +cd "$REPOS_DIR/echidna" # Set REPOS_DIR to your local repos root +panic-attack assail . --output /tmp/echidna-scan.json +cd "$REPOS_DIR/verisim-data" +./scripts/ingest-scan.sh echidna /tmp/echidna-scan.json +git push && git push gitlab main +---- + +*Automation*: Would require GITHUB_TOKEN replacement with PAT for +cross-repo dispatch + +=== Hypatia Neurosymbolic Analysis 🔄 + +*Status*: POC available + +*How It Works*: 1. Fleet-coordinator runs Hypatia scanner on repos 2. +Hypatia generates findings in shared context 3. Learning engine observes +patterns (unsafe_panic, eval_usage, etc.) 4. Auto-generates Logtalk +rules after 5+ observations 5. Proposes new detection rules via PRs + +*Command*: + +[source,bash] +---- +cd "$REPOS_DIR/gitbot-fleet" +./fleet-coordinator.sh run-scan "$REPOS_DIR/echidna" +./fleet-coordinator.sh process-findings +./fleet-coordinator.sh generate-rules +---- + +*Current Learning*: 1100+ observations of unsafe_panic pattern + +=== Git-Private-Farm Enrollment 📝 + +*Status*: Documented, needs formal addition + +*Current State*: - Listed in `+repo_groups.bots+` alongside echidnabot - +Needs entry in `+repos+` section of farm-manifest.json + +*Required Entry*: + +[source,json] +---- +"echidna": { + "description": "Neurosymbolic theorem proving platform with 30 prover backends", + "forges": ["github", "gitlab", "sourcehut", "codeberg", "bitbucket"], + "priority": "high", + "auto_propagate": true, + "language": "rust", + "tags": ["formal-verification", "theorem-proving", "neurosymbolic", "ml"] +} +---- + +*Multi-Forge Status*: - ✅ GitHub: Primary (up to date) - ⚠️ GitLab: Out +of sync (branch protection) - ❌ Codeberg: Not created yet - ❌ +Bitbucket: Not created yet - ❌ SourceHut: Not created yet - ❌ Radicle: +Not created yet + +=== Next Steps + +==== Short-Term (Complete for v1.5.0 release) + +* [x] Gitbot-fleet integration +* [x] Security scan and fixes +* [x] Echidnabot self-verification config +* [ ] Add to git-private-farm repos section +* [ ] Mirror to all forges (GitLab, Codeberg, Bitbucket) + +==== Medium-Term (v2.0) + +* [ ] Automated VeriSimDB ingestion workflow +* [ ] Hypatia integration for real-time proof analysis +* [ ] Cross-repo proof pattern learning +* [ ] Automated fix generation for common proof errors + +==== Long-Term + +* [ ] Continuous formal verification in CI/CD +* [ ] Public VeriSimDB API for querying weak points +* [ ] Integration with theorem proving benchmarks (TPTP, etc.) +* [ ] Ecosystem-wide proof quality metrics + +=== References + +* Gitbot-fleet: `+$REPOS_DIR/gitbot-fleet/+` +* Echidnabot: `+$REPOS_DIR/echidna/echidnabot/+` +* Panic-attacker: `+$REPOS_DIR/panic-attacker/+` +* VeriSimDB: `+$REPOS_DIR/verisim-data/+` +* Hypatia: `+$REPOS_DIR/hypatia/+` +* Git-private-farm: `+$REPOS_DIR/.git-private-farm/+` + +''''' + +*Last Updated*: 2026-02-12 *Maintained By*: Jonathan D.A. Jewell +j.d.a.jewell@open.ac.uk diff --git a/docs/ECOSYSTEM-INTEGRATION.md b/docs/ECOSYSTEM-INTEGRATION.md deleted file mode 100644 index 556fab19..00000000 --- a/docs/ECOSYSTEM-INTEGRATION.md +++ /dev/null @@ -1,183 +0,0 @@ -# ECHIDNA Ecosystem Integration Status - -## Overview - -ECHIDNA is integrated with the Hyperpolymath ecosystem for continuous quality assurance, security scanning, and formal verification. - -## Integration Status (2026-02-12) - -| Service | Status | Details | -|---------|--------|---------| -| **gitbot-fleet** | ✅ Complete | Fleet integration module implemented, registered as Tier 1 Verifier | -| **echidnabot** | ✅ Self-configured | `.echidnabot.toml` added for self-verification | -| **panic-attacker** | ✅ Scanned | Final scan: 50 weak points (down from 82, 39% reduction) | -| **VeriSimDB** | 🔄 Manual | Scan results can be ingested via manual workflow | -| **Hypatia** | 🔄 POC | Hypatia learning engine can process findings | -| **git-private-farm** | 📝 Documented | Listed in bots group, needs repos section entry | - -## Gitbot-Fleet Integration ✅ - -**Status**: COMPLETE - -**What Was Done**: -- Created `echidnabot/src/fleet.rs` integration module -- Added gitbot-shared-context dependency -- Registered as Tier 1 Verifier bot -- 5 finding rule types (ECHIDNA-VERIFY-001 through 005) -- Full test coverage (4 tests passing) -- Documentation: `echidnabot/FLEET-INTEGRATION.md` - -**How to Use**: -```rust -use echidnabot::fleet::FleetIntegration; - -let mut fleet = FleetIntegration::new("my-repo", "/path/to/repo"); -fleet.start()?; - -// Verify proofs and add findings... -for proof_file in proof_files { - let result = echidna_client.verify_proof(prover, &content).await?; - fleet.add_proof_result(&proof_file, &theorem_name, &prover_name, &result); -} - -fleet.complete(findings.len(), errors, files_analyzed)?; -``` - -## Echidnabot Self-Verification ✅ - -**Status**: COMPLETE - -**Configuration**: `.echidnabot.toml` - -**What It Does**: -- Verifies ECHIDNA's own Idris2 ABI definitions (`src/abi/`) -- Checks Rust FFI safety properties -- Runs SMT solvers on property specifications -- Self-hosting: ECHIDNA verifies its own correctness - -**Critical Modules**: -- `Foreign.idr` - FFI safety proofs -- `Types.idr` - Core type definitions -- `Layout.idr` - Memory layout verification - -## Panic-Attacker Security Scanning ✅ - -**Status**: COMPLETE - -**Results**: -- **Previous**: 82 weak points (3 Critical, 4 High, 70 Medium, 5 Low) -- **Current**: 50 weak points (3 Critical, 4 High, 38 Medium, 5 Low) -- **Improvement**: 32 issues fixed (39% reduction) - -**Remaining Issues**: All legitimate or false positives -- FFI unsafe blocks (documented) -- Vendor code in HOL/ directory (gitignored) -- Chapel FFI (feature-gated, optional) - -**Report**: `SECURITY-SCAN-FINAL.md` - -## VeriSimDB Integration 🔄 - -**Status**: Manual workflow available - -**How It Works**: -1. Run `panic-attack assail` on echidna repo -2. Generate JSON output with weak points -3. Run `verisim-data/scripts/ingest-scan.sh echidna /tmp/scan.json` -4. Push to verisim-data repo -5. Hypatia processes findings and learns patterns - -**Command**: -```bash -cd "$REPOS_DIR/echidna" # Set REPOS_DIR to your local repos root -panic-attack assail . --output /tmp/echidna-scan.json -cd "$REPOS_DIR/verisim-data" -./scripts/ingest-scan.sh echidna /tmp/echidna-scan.json -git push && git push gitlab main -``` - -**Automation**: Would require GITHUB_TOKEN replacement with PAT for cross-repo dispatch - -## Hypatia Neurosymbolic Analysis 🔄 - -**Status**: POC available - -**How It Works**: -1. Fleet-coordinator runs Hypatia scanner on repos -2. Hypatia generates findings in shared context -3. Learning engine observes patterns (unsafe_panic, eval_usage, etc.) -4. Auto-generates Logtalk rules after 5+ observations -5. Proposes new detection rules via PRs - -**Command**: -```bash -cd "$REPOS_DIR/gitbot-fleet" -./fleet-coordinator.sh run-scan "$REPOS_DIR/echidna" -./fleet-coordinator.sh process-findings -./fleet-coordinator.sh generate-rules -``` - -**Current Learning**: 1100+ observations of unsafe_panic pattern - -## Git-Private-Farm Enrollment 📝 - -**Status**: Documented, needs formal addition - -**Current State**: -- Listed in `repo_groups.bots` alongside echidnabot -- Needs entry in `repos` section of farm-manifest.json - -**Required Entry**: -```json -"echidna": { - "description": "Neurosymbolic theorem proving platform with 30 prover backends", - "forges": ["github", "gitlab", "sourcehut", "codeberg", "bitbucket"], - "priority": "high", - "auto_propagate": true, - "language": "rust", - "tags": ["formal-verification", "theorem-proving", "neurosymbolic", "ml"] -} -``` - -**Multi-Forge Status**: -- ✅ GitHub: Primary (up to date) -- ⚠️ GitLab: Out of sync (branch protection) -- ❌ Codeberg: Not created yet -- ❌ Bitbucket: Not created yet -- ❌ SourceHut: Not created yet -- ❌ Radicle: Not created yet - -## Next Steps - -### Short-Term (Complete for v1.5.0 release) -- [x] Gitbot-fleet integration -- [x] Security scan and fixes -- [x] Echidnabot self-verification config -- [ ] Add to git-private-farm repos section -- [ ] Mirror to all forges (GitLab, Codeberg, Bitbucket) - -### Medium-Term (v2.0) -- [ ] Automated VeriSimDB ingestion workflow -- [ ] Hypatia integration for real-time proof analysis -- [ ] Cross-repo proof pattern learning -- [ ] Automated fix generation for common proof errors - -### Long-Term -- [ ] Continuous formal verification in CI/CD -- [ ] Public VeriSimDB API for querying weak points -- [ ] Integration with theorem proving benchmarks (TPTP, etc.) -- [ ] Ecosystem-wide proof quality metrics - -## References - -- Gitbot-fleet: `$REPOS_DIR/gitbot-fleet/` -- Echidnabot: `$REPOS_DIR/echidna/echidnabot/` -- Panic-attacker: `$REPOS_DIR/panic-attacker/` -- VeriSimDB: `$REPOS_DIR/verisim-data/` -- Hypatia: `$REPOS_DIR/hypatia/` -- Git-private-farm: `$REPOS_DIR/.git-private-farm/` - ---- - -**Last Updated**: 2026-02-12 -**Maintained By**: Jonathan D.A. Jewell diff --git a/docs/ENV-VARS.adoc b/docs/ENV-VARS.adoc new file mode 100644 index 00000000..62013464 --- /dev/null +++ b/docs/ENV-VARS.adoc @@ -0,0 +1,103 @@ +== ECHIDNA Environment Variables + +*Status*: canonical reference. Last revised: 2026-05-26. + +Every environment variable the system reads, with type, default, and the +files that consume it. If you add a new env var, update this table in +the same PR. + +=== Core runtime + +[width="100%",cols="20%,20%,20%,20%,20%",options="header",] +|=== +|Variable |Type |Default |Used by |Purpose +|`+ECHIDNA_ML_API_URL+` |URL |`+http://127.0.0.1:8090+` +|`+src/rust/server.rs:71+` |Julia ML sidecar HTTP endpoint (GNN, +suggest, training/update) + +|`+VERISIM_URL+` |URL |`+http://localhost:8080+` +|`+src/rust/dispatch.rs+`, `+src/rust/learning/daemon.rs+`, +`+src/julia/retrain_from_verisim.jl+` |VeriSimDB REST endpoint for +proof-attempt writes and history reads. *Canonical name* — older +surfaces using `+VERISIMDB_URL+` are stale and being migrated. + +|`+ECHIDNA_GNN_URL+` |URL |falls back to `+ECHIDNA_ML_API_URL+` +|(planned C5 — see Stage 3c fix list) |Specifically the GNN endpoint; +separate from the ML server only when the GNN runs on a different host. +|=== + +=== Training & evaluation (Julia) + +[width="100%",cols="20%,20%,20%,20%,20%",options="header",] +|=== +|Variable |Type |Default |Used by |Purpose +|`+ECHIDNA_MAX_PROOF_STATES+` |int |0 (all) +|`+src/julia/run_training.jl+`, `+run_training_cpu.jl+` |Cap corpus size +for fast smoke runs. `+just train-cpu+` sets this to 2000. + +|`+ECHIDNA_NUM_EPOCHS+` |int |implementation default |same |Number of +training epochs. `+just train-cpu+` sets this to 2. + +|`+ECHIDNA_NUM_NEGATIVES+` |int |20 |same |Negative-sample count per +training step. + +|`+ECHIDNA_MODELS_DIR+` |path |`+models/+` |`+src/julia/api/server.jl+`, +`+src/julia/eval_held_out.jl+` |Where trained Flux model artefacts live. +|=== + +=== CI & supply-chain + +[width="100%",cols="20%,20%,20%,20%,20%",options="header",] +|=== +|Variable |Type |Default |Used by |Purpose +|`+FARM_DISPATCH_TOKEN+` |secret |unset +|`+.github/workflows/instant-sync.yml+` |Push notifications to dependent +forks. + +|`+VERISIMDB_PAT+` |secret |unset +|`+.github/workflows/security-scan.yml+` |Reusable panic-attack workflow +auth. Note: name is `+VERISIMDB_PAT+` not `+VERISIM_PAT+` — secret-name +compatibility with upstream. +|=== + +=== Build flags (not env vars but related) + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Cargo feature |Default? |Enables +|`+verisim+` |no (target: yes after Stage 3c C4 lands) |VeriSimDB writer ++ advisor + entity-type emission + +|`+chapel+` |no |Chapel parallel-search bridge via Zig FFI shim +|=== + +=== Container & secrets + +In `+.containerization/Containerfile.full+`, the following are expected +to be mounted or built into the image rather than passed as env: + +* Solver binaries — paths in `+config/solver-manifest.toml+` (with +SHAKE3-512 hashes) +* Guix manifest — `+manifests/live-provers.scm+` +* TLS material — none in default container; HTTPS terminated by reverse +proxy + +=== Deprecated / soon-removed + +[width="100%",cols="50%,50%",options="header",] +|=== +|Variable |Note +|`+VERISIMDB_URL+` |Old name for `+VERISIM_URL+`. Still read by +`+tests/live_prover_suite.rs:118+` and enforced by `+k9iser.toml:47+`. +Migration tracked in Stage 3c fix C3. +|=== + +=== Reading order for new contributors + +[arabic] +. Set `+ECHIDNA_ML_API_URL+` and `+VERISIM_URL+` for any local dev +session that touches dispatch or ML paths. +. Set the `+ECHIDNA_*+` training caps only when running +`+just train-cpu+` or `+just eval+` on a constrained host. +. CI secrets (`+FARM_DISPATCH_TOKEN+`, `+VERISIMDB_PAT+`) are +repository-level — no local action needed. diff --git a/docs/ENV-VARS.md b/docs/ENV-VARS.md deleted file mode 100644 index 94be7b66..00000000 --- a/docs/ENV-VARS.md +++ /dev/null @@ -1,65 +0,0 @@ - - - -# ECHIDNA Environment Variables - -**Status**: canonical reference. Last revised: 2026-05-26. - -Every environment variable the system reads, with type, default, and the -files that consume it. If you add a new env var, update this table in the -same PR. - -## Core runtime - -| Variable | Type | Default | Used by | Purpose | -|---|---|---|---|---| -| `ECHIDNA_ML_API_URL` | URL | `http://127.0.0.1:8090` | `src/rust/server.rs:71` | Julia ML sidecar HTTP endpoint (GNN, suggest, training/update) | -| `VERISIM_URL` | URL | `http://localhost:8080` | `src/rust/dispatch.rs`, `src/rust/learning/daemon.rs`, `src/julia/retrain_from_verisim.jl` | VeriSimDB REST endpoint for proof-attempt writes and history reads. **Canonical name** — older surfaces using `VERISIMDB_URL` are stale and being migrated. | -| `ECHIDNA_GNN_URL` | URL | falls back to `ECHIDNA_ML_API_URL` | (planned C5 — see Stage 3c fix list) | Specifically the GNN endpoint; separate from the ML server only when the GNN runs on a different host. | - -## Training & evaluation (Julia) - -| Variable | Type | Default | Used by | Purpose | -|---|---|---|---|---| -| `ECHIDNA_MAX_PROOF_STATES` | int | 0 (all) | `src/julia/run_training.jl`, `run_training_cpu.jl` | Cap corpus size for fast smoke runs. `just train-cpu` sets this to 2000. | -| `ECHIDNA_NUM_EPOCHS` | int | implementation default | same | Number of training epochs. `just train-cpu` sets this to 2. | -| `ECHIDNA_NUM_NEGATIVES` | int | 20 | same | Negative-sample count per training step. | -| `ECHIDNA_MODELS_DIR` | path | `models/` | `src/julia/api/server.jl`, `src/julia/eval_held_out.jl` | Where trained Flux model artefacts live. | - -## CI & supply-chain - -| Variable | Type | Default | Used by | Purpose | -|---|---|---|---|---| -| `FARM_DISPATCH_TOKEN` | secret | unset | `.github/workflows/instant-sync.yml` | Push notifications to dependent forks. | -| `VERISIMDB_PAT` | secret | unset | `.github/workflows/security-scan.yml` | Reusable panic-attack workflow auth. Note: name is `VERISIMDB_PAT` not `VERISIM_PAT` — secret-name compatibility with upstream. | - -## Build flags (not env vars but related) - -| Cargo feature | Default? | Enables | -|---|---|---| -| `verisim` | no (target: yes after Stage 3c C4 lands) | VeriSimDB writer + advisor + entity-type emission | -| `chapel` | no | Chapel parallel-search bridge via Zig FFI shim | - -## Container & secrets - -In `.containerization/Containerfile.full`, the following are expected to be -mounted or built into the image rather than passed as env: - -- Solver binaries — paths in `config/solver-manifest.toml` (with SHAKE3-512 hashes) -- Guix manifest — `manifests/live-provers.scm` -- TLS material — none in default container; HTTPS terminated by reverse proxy - -## Deprecated / soon-removed - -| Variable | Note | -|---|---| -| `VERISIMDB_URL` | Old name for `VERISIM_URL`. Still read by `tests/live_prover_suite.rs:118` and enforced by `k9iser.toml:47`. Migration tracked in Stage 3c fix C3. | - -## Reading order for new contributors - -1. Set `ECHIDNA_ML_API_URL` and `VERISIM_URL` for any local dev session that - touches dispatch or ML paths. -2. Set the `ECHIDNA_*` training caps only when running `just train-cpu` or - `just eval` on a constrained host. -3. CI secrets (`FARM_DISPATCH_TOKEN`, `VERISIMDB_PAT`) are repository-level — - no local action needed. diff --git a/docs/HOSTING.adoc b/docs/HOSTING.adoc new file mode 100644 index 00000000..078dbd31 --- /dev/null +++ b/docs/HOSTING.adoc @@ -0,0 +1,137 @@ +== Hosting and deployment topology + +Where each public-facing piece of ECHIDNA runs, how it is published, and +what state each piece is currently in. This is the human-facing +companion to +link:../.machine_readable/deployment.a2ml[`+.machine_readable/deployment.a2ml+`]; +keep the two in step. + +=== The three surfaces + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Surface |Host |Built by |Source +|`+nesy-prover.dev+` — website |*Cloudflare Pages* +|`+.github/workflows/pages.yml+` (Ddraig SSG) |link:../site[`+site/+`] + +link:../echidna-playground[`+echidna-playground/+`] + +|`+api.nesy-prover.dev+` — HTTP API |*Hetzner*, rootless podman behind +Caddy |`+ghcr-publish.yml+` → `+ghcr.io/hyperpolymath/echidna+` +|link:../deploy/hetzner[`+deploy/hetzner/+`] + +|`+sudo@nesy-prover.dev+` — contact |*Cloudflare Email Routing* +(forwarder) |n/a — DNS only |n/a +|=== + +DNS for the zone is on Cloudflare. + +=== Website + +Content lives in link:../site[`+site/+`] as Markdown and is rendered by +*Ddraig SSG* (an Idris2 static site generator) inside `+pages.yml+`. The +playground is copied in as static assets afterwards. + +Two properties of the generator matter when editing: + +* It *hard-fails the build* on any accessibility violation — more than +one `+

+` per page, a skipped heading level, or a missing `+alt+`. A +page that fails prints `+[a11y FAIL]+` and the workflow exits non-zero. +Every page must print `+[a11y ok]+`. +* Its internal `+copyTree+` is *text-only and corrupts binary files*. +Anything binary must be copied with `+cp+` in the workflow, never placed +where the SSG will walk it. This is why the playground has its own copy +step. + +Build it locally exactly as CI does: + +[source,bash] +---- +ddraig build site _site https://nesy-prover.dev +---- + +Links between pages are authored with `+.html+` extensions, because the +SSG renders `+foo.md+` to `+foo.html+` at the same path and does not +rewrite link targets. + +==== Publishing target + +The apex is served by *Cloudflare Pages*. The build must stay in GitHub +Actions because it requires Idris2, which managed build images do not +provide; CI produces `+_site+` and publishes that directory. + +____ +*Current state:* the content is merged and `+pages.yml+` is enabled, but +the site is not yet live — see _Known issues_ below. +____ + +=== API + +The deployed service is the `+echidna+` binary’s `+server+` subcommand. +Its routes, request shapes and response shapes are documented in +link:../site/docs/api/core.md[`+site/docs/api/core.md+`], which was +written from the route table and types in `+src/rust/server.rs+` — *that +page is the accurate one*. The separate REST, GraphQL and gRPC interface +binaries are optional and documented alongside it. + +The full deployment procedure, including preflight gates, is +link:../deploy/hetzner/README.adoc[`+deploy/hetzner/README.adoc+`]. In +outline: + +* `+echidna+` and `+caddy+` run as *rootless podman systemd quadlets* on +a shared network; the API publishes *no host port* and is reachable only +through Caddy +* Caddy terminates TLS and applies a *30 req/min per-IP rate limit* and +a *1 MB request body cap* +* the container is capped at `+--memory=1500m --pids-limit=512+`, with a +tmpfs `+/tmp+` and `+NoNewPrivileges+` +* `+AutoUpdate=registry+` plus `+HealthOnFailure=kill+` means a new +release rolls out unattended and an unhealthy container *fails the +unit*, which is what makes rollback actually fire + +==== Why the caging matters + +The API has *no authentication* and executes prover binaries on +user-supplied input. Rate limiting bounds how _many_ requests arrive; it +does not bound the cost of a single one, and Lean accepts `+#eval+` — +arbitrary code at elaboration time. A per-request server-side prover +timeout is outstanding work (`+src/rust/server.rs+` spawns provers with +no deadline). + +=== Known issues + +[arabic] +. *Repository Actions are failing at startup.* Every workflow in this +repository currently returns `+startup_failure+`, including +`+pages.yml+`. This is repo-level, not a fault in any workflow file — a +minimal probe workflow containing a single SHA-pinned +`+actions/checkout+` fails identically. Until it is resolved, nothing +builds or deploys and *no gate verifies anything*. +. *The apex has no origin yet.* `+nesy-prover.dev+` resolves to +Cloudflare proxy addresses; the TLS handshake completes and the request +then hangs, because Cloudflare is proxying to an origin that does not +exist. The DNS records are likely already correct — what is missing is +the Pages project behind them. + +==== Diagnosing "`the board is green but nothing ran`" + +A workflow that fails at startup registers *no check run at all*, so it +cannot show up as missing or failing. `+gh pr checks+` will report +success while every real gate is dead. Always confirm with: + +[source,bash] +---- +gh run list --branch main --json workflowName,conclusion +---- + +A related tell: when `+gh run list+` shows a workflow by its *path* +(`+.github/workflows/x.yml+`) instead of its *name*, that file has never +been parsed successfully. Confirm with +`+gh api repos/OWNER/REPO/actions/runs//jobs --jq '.jobs|length'+` +returning `+0+`. + +=== Retired + +*fly.io* — the `+echidna-nesy+` app is no longer used, for cost reasons. +Any remaining `+fly.toml+` or `+fly-deploy.yml+` is dead weight and +should be removed; the Fly deploy action was never on the repository’s +permitted-actions list in any case. diff --git a/docs/HOSTING.md b/docs/HOSTING.md deleted file mode 100644 index 9481fe43..00000000 --- a/docs/HOSTING.md +++ /dev/null @@ -1,121 +0,0 @@ - - -# Hosting and deployment topology - -Where each public-facing piece of ECHIDNA runs, how it is published, and what -state each piece is currently in. This is the human-facing companion to -[`.machine_readable/deployment.a2ml`](../.machine_readable/deployment.a2ml); -keep the two in step. - -## The three surfaces - -| Surface | Host | Built by | Source | -|---|---|---|---| -| `nesy-prover.dev` — website | **Cloudflare Pages** | `.github/workflows/pages.yml` (Ddraig SSG) | [`site/`](../site) + [`echidna-playground/`](../echidna-playground) | -| `api.nesy-prover.dev` — HTTP API | **Hetzner**, rootless podman behind Caddy | `ghcr-publish.yml` → `ghcr.io/hyperpolymath/echidna` | [`deploy/hetzner/`](../deploy/hetzner) | -| `sudo@nesy-prover.dev` — contact | **Cloudflare Email Routing** (forwarder) | n/a — DNS only | n/a | - -DNS for the zone is on Cloudflare. - -## Website - -Content lives in [`site/`](../site) as Markdown and is rendered by **Ddraig -SSG** (an Idris2 static site generator) inside `pages.yml`. The playground is -copied in as static assets afterwards. - -Two properties of the generator matter when editing: - -- It **hard-fails the build** on any accessibility violation — more than one - `

` per page, a skipped heading level, or a missing `alt`. A page that - fails prints `[a11y FAIL]` and the workflow exits non-zero. Every page must - print `[a11y ok]`. -- Its internal `copyTree` is **text-only and corrupts binary files**. Anything - binary must be copied with `cp` in the workflow, never placed where the SSG - will walk it. This is why the playground has its own copy step. - -Build it locally exactly as CI does: - -```bash -ddraig build site _site https://nesy-prover.dev -``` - -Links between pages are authored with `.html` extensions, because the SSG -renders `foo.md` to `foo.html` at the same path and does not rewrite link -targets. - -### Publishing target - -The apex is served by **Cloudflare Pages**. The build must stay in GitHub -Actions because it requires Idris2, which managed build images do not provide; -CI produces `_site` and publishes that directory. - -> **Current state:** the content is merged and `pages.yml` is enabled, but the -> site is not yet live — see *Known issues* below. - -## API - -The deployed service is the `echidna` binary's `server` subcommand. Its routes, -request shapes and response shapes are documented in -[`site/docs/api/core.md`](../site/docs/api/core.md), which was written from the -route table and types in `src/rust/server.rs` — **that page is the accurate -one**. The separate REST, GraphQL and gRPC interface binaries are optional and -documented alongside it. - -The full deployment procedure, including preflight gates, is -[`deploy/hetzner/README.adoc`](../deploy/hetzner/README.adoc). In outline: - -- `echidna` and `caddy` run as **rootless podman systemd quadlets** on a shared - network; the API publishes **no host port** and is reachable only through Caddy -- Caddy terminates TLS and applies a **30 req/min per-IP rate limit** and a - **1 MB request body cap** -- the container is capped at `--memory=1500m --pids-limit=512`, with a tmpfs - `/tmp` and `NoNewPrivileges` -- `AutoUpdate=registry` plus `HealthOnFailure=kill` means a new release rolls - out unattended and an unhealthy container **fails the unit**, which is what - makes rollback actually fire - -### Why the caging matters - -The API has **no authentication** and executes prover binaries on -user-supplied input. Rate limiting bounds how *many* requests arrive; it does -not bound the cost of a single one, and Lean accepts `#eval` — arbitrary code -at elaboration time. A per-request server-side prover timeout is outstanding -work (`src/rust/server.rs` spawns provers with no deadline). - -## Known issues - -1. **Repository Actions are failing at startup.** Every workflow in this - repository currently returns `startup_failure`, including `pages.yml`. This - is repo-level, not a fault in any workflow file — a minimal probe workflow - containing a single SHA-pinned `actions/checkout` fails identically. Until - it is resolved, nothing builds or deploys and **no gate verifies anything**. -2. **The apex has no origin yet.** `nesy-prover.dev` resolves to Cloudflare - proxy addresses; the TLS handshake completes and the request then hangs, - because Cloudflare is proxying to an origin that does not exist. The DNS - records are likely already correct — what is missing is the Pages project - behind them. - -### Diagnosing "the board is green but nothing ran" - -A workflow that fails at startup registers **no check run at all**, so it -cannot show up as missing or failing. `gh pr checks` will report success while -every real gate is dead. Always confirm with: - -```bash -gh run list --branch main --json workflowName,conclusion -``` - -A related tell: when `gh run list` shows a workflow by its **path** -(`.github/workflows/x.yml`) instead of its **name**, that file has never been -parsed successfully. Confirm with -`gh api repos/OWNER/REPO/actions/runs//jobs --jq '.jobs|length'` returning `0`. - -## Retired - -**fly.io** — the `echidna-nesy` app is no longer used, for cost reasons. -Any remaining `fly.toml` or `fly-deploy.yml` is dead weight and should be -removed; the Fly deploy action was never on the repository's permitted-actions -list in any case. diff --git a/docs/HP-BACKEND-ONBOARDING.adoc b/docs/HP-BACKEND-ONBOARDING.adoc new file mode 100644 index 00000000..ce85101b --- /dev/null +++ b/docs/HP-BACKEND-ONBOARDING.adoc @@ -0,0 +1,164 @@ +== Onboarding a new HP type-discipline backend + +This is the working checklist for adding a new HP-ecosystem type +discipline to echidna. The 41 existing variants (TypeLL, +KatagoriaVerifier, TropicalTypeChecker, EchoTypeChecker, …) all followed +this same pattern. + +For background on what already exists, see +`+docs/handover/B7-AUDIT-CORRECTION.md+`. + +=== Where the wiring lives + +Adding a new discipline `+Foo+` (i.e. `+ProverKind::FooTypeChecker+`) +touches exactly four files: + +[width="100%",cols="43%,57%",options="header",] +|=== +|File |What to add +|`+src/rust/provers/mod.rs+` |Enum variant + parser arm + +is_hp_ecosystem + default_executable + +|`+src/rust/provers/hp_ecosystem.rs::upstream()+` |One match arm: +`+Foo => ("typell", "foo")+` + +|`+src/rust/provers/typed_wasm.rs::type_info_for+` |`+TypeInfo+` +selector for the discipline (the typed_wasm route) + +|`+tests/fixtures/hp/foo_trivial.tll+` |One smoke fixture exercising the +new wire +|=== + +If the discipline ships its own CLI (i.e. not +`+typell --discipline=foo+` but a standalone binary), it routes through +`+HPEcosystemBackend+` and the `+upstream()+` arm returns +`+("foo-cli", "foo")+`. If it lives under `+typell+`, it routes through +`+TypedWasmBackend+` via the discipline parameter. + +The deciding question: *does the upstream maintainer ship a separate +binary?* Examples: + +* `+KatagoriaVerifier+` → standalone `+katagoria+` binary → +`+HPEcosystemBackend+`. +* `+TropicalTypeChecker+` → standalone `+tropical-type-check+` binary → +either path (currently `+TypedWasmBackend+`). +* `+EchoTypeChecker+` → bundled under `+typell+` → `+TypedWasmBackend+`. + +=== Step-by-step + +==== 1. Add the enum variant + +`+src/rust/provers/mod.rs+`, in the `+ProverKind+` enum (around line +294): + +[source,rust] +---- +pub enum ProverKind { + // ... + FooTypeChecker, + // ... +} +---- + +==== 2. Parser arm + +Same file, around line 567 (the string-to-ProverKind parser): + +[source,rust] +---- +"footypechecker" | "foo" => Ok(ProverKind::FooTypeChecker), +---- + +==== 3. `+is_hp_ecosystem+` arm + +Same file, around line 434: + +[source,rust] +---- +pub fn is_hp_ecosystem(&self) -> bool { + matches!(self, + // ... + | ProverKind::FooTypeChecker + ) +} +---- + +==== 4. `+default_executable+` arm + +Same file, around line 1360. Either: + +[source,rust] +---- +ProverKind::FooTypeChecker => "typell", // bundled +// or +ProverKind::FooTypeChecker => "foo-cli", // standalone +---- + +==== 5. Factory routing arm + +Same file, `+ProverFactory::create+` (around line 1822). Add to the +appropriate match arm: + +* Standalone binary: add to the `+HPEcosystemBackend+` arm at line +1776-1778. +* Bundled discipline: add to the `+TypedWasmBackend+` arm at lines +1784-1822. + +==== 6. (Bundled discipline only) `+upstream()+` arm + +`+src/rust/provers/hp_ecosystem.rs+`, the `+upstream()+` match around +line 63: + +[source,rust] +---- +ProverKind::FooTypeChecker => ("typell", "foo"), +---- + +==== 7. `+TypeInfo+` selector + +`+src/rust/provers/typed_wasm.rs::type_info_for+` — return the +discipline’s parametric `+TypeInfo+` so the unified verifier knows what +to check. + +==== 8. Smoke fixture + +`+tests/fixtures/hp/foo_trivial.tll+`: + +.... +# SPDX-License-Identifier: CC-BY-SA-4.0 +#discipline: foo + +theorem foo_identity : ... . +Proof. + foo_refl. +Qed. +.... + +==== 9. Run the smoke + +`+tests/gnn_augment_integration.rs::test_hp_ecosystem_gnn_wires_top_premise+` +already loops over `+is_hp_ecosystem()+` kinds, so the new variant gets +GNN-wiring coverage for free. A direct backend smoke takes one more line +in `+tests/common/mod.rs+` if you want it. + +=== What you DON’T need to touch + +* *Confidence levels* — the trust bridge reads `+is_hp_ecosystem()+` +once; no per-discipline tuning. +* *Corpus extractors* — the HP corpus is built by `+crates/typed_wasm+` +and indexed by Sigma parameters; new disciplines inherit the existing +pipeline. +* *Result formatter* — `+result_formatter.rs+` reads `+ProverKind+` via +Display; the variant name is the user-facing label. + +=== When the upstream binary doesn’t ship + +For early-development disciplines where the upstream tool isn’t yet +buildable (e.g. an unreleased Wokelang variant), the backend will return +a "`binary not found`" runtime error. That is the right behaviour — +echidna’s trust bridge surfaces it as `+ProverOutcome::Unsupported+` and +the caller sees a clear signal. + +Do *not* stub the backend to return spurious success. Estate consumers +(per the C12 per-repo manifest) configure +`+[provers] disabled = ["foo"]+` to opt out cleanly. diff --git a/docs/HP-BACKEND-ONBOARDING.md b/docs/HP-BACKEND-ONBOARDING.md deleted file mode 100644 index 398df125..00000000 --- a/docs/HP-BACKEND-ONBOARDING.md +++ /dev/null @@ -1,151 +0,0 @@ - - -# Onboarding a new HP type-discipline backend - -This is the working checklist for adding a new HP-ecosystem type -discipline to echidna. The 41 existing variants (TypeLL, -KatagoriaVerifier, TropicalTypeChecker, EchoTypeChecker, ...) all -followed this same pattern. - -For background on what already exists, see -`docs/handover/B7-AUDIT-CORRECTION.md`. - -## Where the wiring lives - -Adding a new discipline `Foo` (i.e. `ProverKind::FooTypeChecker`) -touches exactly four files: - -| File | What to add | -|-------------------------------------------------|-------------------------------------------------------------------| -| `src/rust/provers/mod.rs` | Enum variant + parser arm + is_hp_ecosystem + default_executable | -| `src/rust/provers/hp_ecosystem.rs::upstream()` | One match arm: `Foo => ("typell", "foo")` | -| `src/rust/provers/typed_wasm.rs::type_info_for` | `TypeInfo` selector for the discipline (the typed_wasm route) | -| `tests/fixtures/hp/foo_trivial.tll` | One smoke fixture exercising the new wire | - -If the discipline ships its own CLI (i.e. not `typell --discipline=foo` -but a standalone binary), it routes through `HPEcosystemBackend` and -the `upstream()` arm returns `("foo-cli", "foo")`. If it lives under -`typell`, it routes through `TypedWasmBackend` via the discipline -parameter. - -The deciding question: **does the upstream maintainer ship a separate -binary?** Examples: - -- `KatagoriaVerifier` → standalone `katagoria` binary → `HPEcosystemBackend`. -- `TropicalTypeChecker` → standalone `tropical-type-check` binary → either path (currently `TypedWasmBackend`). -- `EchoTypeChecker` → bundled under `typell` → `TypedWasmBackend`. - -## Step-by-step - -### 1. Add the enum variant - -`src/rust/provers/mod.rs`, in the `ProverKind` enum (around line 294): - -```rust -pub enum ProverKind { - // ... - FooTypeChecker, - // ... -} -``` - -### 2. Parser arm - -Same file, around line 567 (the string-to-ProverKind parser): - -```rust -"footypechecker" | "foo" => Ok(ProverKind::FooTypeChecker), -``` - -### 3. `is_hp_ecosystem` arm - -Same file, around line 434: - -```rust -pub fn is_hp_ecosystem(&self) -> bool { - matches!(self, - // ... - | ProverKind::FooTypeChecker - ) -} -``` - -### 4. `default_executable` arm - -Same file, around line 1360. Either: - -```rust -ProverKind::FooTypeChecker => "typell", // bundled -// or -ProverKind::FooTypeChecker => "foo-cli", // standalone -``` - -### 5. Factory routing arm - -Same file, `ProverFactory::create` (around line 1822). Add to the -appropriate match arm: - -- Standalone binary: add to the `HPEcosystemBackend` arm at line - 1776-1778. -- Bundled discipline: add to the `TypedWasmBackend` arm at lines - 1784-1822. - -### 6. (Bundled discipline only) `upstream()` arm - -`src/rust/provers/hp_ecosystem.rs`, the `upstream()` match around -line 63: - -```rust -ProverKind::FooTypeChecker => ("typell", "foo"), -``` - -### 7. `TypeInfo` selector - -`src/rust/provers/typed_wasm.rs::type_info_for` — return the discipline's -parametric `TypeInfo` so the unified verifier knows what to check. - -### 8. Smoke fixture - -`tests/fixtures/hp/foo_trivial.tll`: - -``` -# SPDX-License-Identifier: CC-BY-SA-4.0 -#discipline: foo - -theorem foo_identity : ... . -Proof. - foo_refl. -Qed. -``` - -### 9. Run the smoke - -`tests/gnn_augment_integration.rs::test_hp_ecosystem_gnn_wires_top_premise` -already loops over `is_hp_ecosystem()` kinds, so the new variant gets -GNN-wiring coverage for free. A direct backend smoke takes one more -line in `tests/common/mod.rs` if you want it. - -## What you DON'T need to touch - -- **Confidence levels** — the trust bridge reads - `is_hp_ecosystem()` once; no per-discipline tuning. -- **Corpus extractors** — the HP corpus is built by - `crates/typed_wasm` and indexed by Sigma parameters; new disciplines - inherit the existing pipeline. -- **Result formatter** — `result_formatter.rs` reads `ProverKind` - via Display; the variant name is the user-facing label. - -## When the upstream binary doesn't ship - -For early-development disciplines where the upstream tool isn't yet -buildable (e.g. an unreleased Wokelang variant), the backend will -return a "binary not found" runtime error. That is the right -behaviour — echidna's trust bridge surfaces it as -`ProverOutcome::Unsupported` and the caller sees a clear signal. - -Do **not** stub the backend to return spurious success. Estate -consumers (per the C12 per-repo manifest) configure `[provers] -disabled = ["foo"]` to opt out cleanly. diff --git a/docs/Language-Provability-Analysis.adoc b/docs/Language-Provability-Analysis.adoc new file mode 100644 index 00000000..e8fe1fc8 --- /dev/null +++ b/docs/Language-Provability-Analysis.adoc @@ -0,0 +1,368 @@ +== Language Provability Analysis - Echidna Framework + +=== Comprehensive Guide to Formal Verification Across Language Ecosystems + +*Prepared for:* Jonathan D.A. Jewell (hyperpolymath) + +*Date:* 2026-04-04 + +*Status:* Master Document for Multi-Language Verification Strategy + +''''' + +=== Table of Contents + +[arabic] +. link:#language-provability-spectrum[Language Provability Spectrum] +. link:#your-specific-questions-answered[Your Specific Questions +Answered] +. link:#recommended-strategy[Recommended Strategy] +. link:#estimated-reuse-potential[Estimated Reuse Potential] +. link:#optimal-architecture[Optimal Architecture] +. link:#conclusion-and-recommendations[Conclusion and Recommendations] + +''''' + +=== Language Provability Spectrum + +==== Tier 1: Fully Provable Languages + +*Languages:* Idris2, Agda, Coq, Lean + +*Characteristics:* - ✅ Full dependent types - ✅ Compile-time proof +checking + +- ✅ Zero-cost abstraction - ✅ Theorem proving capabilities - ✅ +Totality checking + +*Best for:* - Core security algorithms - Cryptographic operations - +Safety-critical logic - Mathematical guarantees - Reusable proof +frameworks + +*Example use cases in your estate:* - `+typed-wasm+` ABI verification - +`+proven+` FFI safety - `+echidna+` multi-prover coordination - +`+boj-server+` security guarantees + +==== Tier 2: Partially Provable Languages + +*Languages:* Zig, V, Rust, Swift + +*Characteristics:* - ✅ Strong type systems - ✅ Compile-time guarantees +- ✅ Memory safety - ✅ Explicit error handling - ❌ Limited/no +dependent types - ❌ No arbitrary theorem proving + +*Best for:* - Systems programming - Performance-critical code - FFI +implementations - Memory-safe runtime code + +*Zig-specific strengths:* - Compile-time execution - No hidden control +flow - Explicit allocators - Manual memory management with safety + +*V-specific strengths:* - Simple syntax - Fast compilation - Built-in +ORM - Memory safety + +*Rust-specific strengths:* - Borrow checker - Zero-cost abstractions - +Fearless concurrency - Mature ecosystem + +==== Tier 3: Runtime Verification Languages + +*Languages:* JavaScript/TypeScript, Python, Ruby, Java, C# + +*Characteristics:* - ✅ Runtime type checking - ✅ Contract programming +- ✅ Dynamic typing - ❌ No compile-time proofs - ❌ Limited static +guarantees + +*Best for:* - Prototyping and iteration - Scripting and automation - +Glue code between systems - Web applications (with runtime checks) + +*Verification strategies:* - Runtime contract checking - Input +validation libraries - Property-based testing - Fuzz testing - Audit +logging + +''''' + +=== Your Specific Questions Answered + +==== "`Is Zig slop?`" + +*No! Zig is excellent, but different from Idris2:* + +*Zig strengths:* - ✅ Memory safety without garbage collection - ✅ No +hidden control flow - ✅ Explicit allocators - ✅ Compile-time execution +- ✅ Cross-compilation - ✅ Small binary size + +*Zig limitations (vs Idris2):* - ❌ No dependent types - ❌ No +compile-time theorem proving - ❌ Limited generic programming - ❌ +Younger ecosystem + +*Verdict:* Zig is *not slop* - it’s a *precision tool* for systems +programming, just in a different category than proof assistants. + +==== "`Is V slop?`" + +*V is promising but younger:* + +*V strengths:* - ✅ Simple, readable syntax - ✅ Memory safety - ✅ Fast +compilation - ✅ Built-in ORM and web framework - ✅ No global state - +✅ No null by default + +*V limitations:* - ❌ Less mature than Zig/Rust - ❌ Smaller ecosystem - +❌ Limited generic programming - ❌ No dependent types + +*Verdict:* V is *not slop* - it’s a *pragmatic language* with good +safety properties, but not at the same maturity level as Zig/Rust. + +==== "`Is an ABI complex?`" + +*ABIs follow predictable patterns:* + +*Simple ABIs (80% of cases):* - Basic function signatures - Primitive +types (int, string, bool) - Simple structs - Error codes + +*Complex ABIs (20% of cases):* - Callbacks and closures - Ownership +semantics - Lifetime management - Async operations - Memory management +contracts + +*Reusability estimate:* - ~90% of ABI proofs can be parameterized and +reused - ~10% require domain-specific proofs - Your estate has ~1,609 +Idris2 ABI files → ~80 unique proof patterns needed + +==== "`Is an FFI complex?`" + +*FFIs have standardized patterns:* + +*Simple FFI (70% of cases):* - Basic function calls - Primitive type +mapping - Simple error handling - Synchronous operations + +*Complex FFI (30% of cases):* - Memory management across language +boundaries - Async callbacks - Exception handling - Resource cleanup - +Thread safety + +*Verification strategy:* - Runtime contract checking - Input/output +validation - Resource tracking - Audit logging + +==== "`Is an API complex?`" + +*APIs vary widely:* + +*Simple APIs (80% of cases):* - REST endpoints - Basic CRUD operations - +Stateless functions - Simple data transformations + +*Complex APIs (20% of cases):* - State machines - Transactional logic - +Distributed protocols - Complex business rules + +*Proof strategy:* - Prove the complex 20% - Runtime checks for the +simple 80% - Property-based testing - Fuzz testing + +''''' + +=== Recommended Strategy + +==== ✅ Do This: + +[arabic] +. *Idris2/Agda for core logic:* +* Prove complex algorithms once +* Create reusable proof frameworks +* Focus on security-critical paths +. *Zig/V/Rust for implementation:* +* Systems programming +* Performance-critical code +* FFI implementations +* Memory-safe runtime code +. *Reusable ABI proofs:* +* Parameterized proof frameworks +* Generic safety certificates +* Domain-specific proof combinators +. *FFI verification layers:* +* Runtime contract checking +* Input validation +* Resource tracking +* Audit logging + +==== ❌ Don’t Do This: + +[arabic] +. *Don’t rewrite everything in Agda:* +* Overkill for most applications +* High maintenance burden +* Limited ecosystem support +. *Don’t prove trivial code:* +* Focus on security-critical paths +* Simple CRUD doesn’t need formal proofs +* Use runtime checks for basic operations +. *Don’t mix proof languages unnecessarily:* +* Stick to Idris2 for proofs (consistency) +* Use each language for its strengths +* Avoid polyglot proof spaghetti + +''''' + +=== Estimated Reuse Potential + +==== Component Reusability Analysis + +[cols=",,,",options="header",] +|=== +|Component |Reusability |Your Estate |Unique Patterns +|*Idris2 ABIs* |95% |1,609 files |~80 unique +|*Zig FFIs* |85% |~5,000 files |~750 unique +|*V APIs* |80% |~3,000 files |~600 unique +|*Rust APIs* |90% |~7,000 files |~700 unique +|*Go APIs* |70% |~1,874 files |~562 unique +|=== + +==== Total Proof Effort Estimate + +*Without reuse:* 17,483 files × 2h = ~34,966 hours *With reuse:* ~2,692 +unique patterns × 2h = ~5,384 hours *Savings:* ~85% reduction in proof +effort + +==== Proof Pattern Library Strategy + +[arabic] +. *Create parameterized proof templates* +. *Domain-specific proof combinators* +. *Generic safety certificates* +. *ABI proof generator* +. *FFI verification framework* + +''''' + +=== Optimal Architecture + +.... +┌─────────────────────────────────────────────────┐ +│ Application Layer │ +│ (TypeScript, Python, etc. - Runtime checks) │ +└─────────────────────────────────────────────────┘ + ↑ +┌─────────────────────────────────────────────────┐ +│ FFI Verification Layer │ +│ (Runtime contract checking, input validation) │ +└─────────────────────────────────────────────────┘ + ↑ +┌─────────────────────────────────────────────────┐ +│ Reusable ABI Proof Framework │ +│ (Idris2 parameterized proofs - Compile-time) │ +└─────────────────────────────────────────────────┘ + ↑ +┌─────────────────────────────────────────────────┐ +│ Core Algorithm Proofs │ +│ (Idris2/Agda - Full formal verification) │ +└─────────────────────────────────────────────────┘ +.... + +==== Layered Verification Strategy + +[arabic] +. *Core Layer (Idris2/Agda):* +* Full formal verification +* Dependent types +* Compile-time proofs +* Zero runtime overhead +. *ABI Layer (Idris2):* +* Parameterized proof frameworks +* Generic safety certificates +* Reusable across all projects +* Compile-time verification +. *FFI Layer (Zig/V/Rust):* +* Runtime contract checking +* Input validation +* Resource tracking +* Audit logging +* Memory safety guarantees +. *Application Layer (Any language):* +* Runtime type checking +* Property-based testing +* Fuzz testing +* Monitoring and observability + +''''' + +=== Conclusion and Recommendations + +==== 🎯 Key Insights + +[arabic] +. *Not everything needs full formal proof* +* Focus on security-critical paths +* Use appropriate verification level for each component +. *Massive reuse potential exists* +* 85-95% of ABI/FFI/API patterns are reusable +* Create parameterized proof frameworks +. *Hybrid approach is optimal* +* Idris2 for core logic and proofs +* Zig/V/Rust for implementation +* Runtime verification for dynamic languages +. *Your estate is proof-ready* +* Well-structured codebase +* Clear separation of concerns +* Defence-in-depth already implemented + +==== ✅ Action Plan + +*Phase 1: Foundation (1 week)* - [ ] Create universal ABI proof +framework - [ ] Develop FFI verification patterns - [ ] Build hybrid +verification architecture - [ ] Document proof patterns library + +*Phase 2: Core Proofs (2 weeks)* - [ ] Prove security-critical +algorithms (Idris2) - [ ] Create reusable ABI proof templates - [ ] +Implement FFI verification layers - [ ] Add runtime contract checking + +*Phase 3: Integration (1 week)* - [ ] CI/CD proof compilation checks - [ +] Automated audit scripts - [ ] Documentation and training - [ ] +Monitoring and observability + +*Phase 4: Scaling (Ongoing)* - [ ] Apply to new projects - [ ] Maintain +proof pattern library - [ ] Quarterly proof audits - [ ] Community +contribution guidelines + +==== 🚀 Expected Outcomes + +[arabic] +. *90% safety coverage with 10% effort* compared to full formal +verification +. *Reusable proof frameworks* across all 150+ repositories +. *Consistent verification standards* across language ecosystems +. *Maintainable architecture* for future growth +. *Industry-leading security* without excessive complexity + +==== 🎓 Training Recommendations + +[arabic] +. *Idris2 for proof authors* (core team) +. *Zig/V/Rust for implementers* (engineering team) +. *Verification patterns* for all contributors +. *CI/CD integration* for DevOps team + +''''' + +=== Appendix: Your Estate Statistics + +==== Language Distribution + +* *Idris2:* 1,609 ABI files +* *Zig:* ~5,000 FFI files + +* *V:* ~3,000 API files +* *Rust:* ~7,000 API files +* *Go:* ~1,874 API files +* *TypeScript/JavaScript:* ~15,000+ files +* *Other:* ~10,000 files + +==== Proof Coverage Targets + +* *Tier 1 (Full proof):* 20 repos (security-critical) +* *Tier 2 (Partial proof):* 30 repos (complex logic) +* *Tier 3 (Runtime checks):* 100 repos (simple/utility) + +==== Timeline Estimate + +* *Phase 1:* 1 week (Foundation) +* *Phase 2:* 2 weeks (Core Proofs) +* *Phase 3:* 1 week (Integration) +* *Phase 4:* Ongoing (Scaling) +* *Total:* 4-6 weeks to full coverage + +''''' + +*Document Status:* MASTER + +*Version:* 1.0 + +*Last Updated:* 2026-04-04 + +*Maintainer:* Mistral Vibe (devstral-2) diff --git a/docs/Language-Provability-Analysis.md b/docs/Language-Provability-Analysis.md deleted file mode 100644 index dadb15b9..00000000 --- a/docs/Language-Provability-Analysis.md +++ /dev/null @@ -1,432 +0,0 @@ -# Language Provability Analysis - Echidna Framework - -## Comprehensive Guide to Formal Verification Across Language Ecosystems - -**Prepared for:** Jonathan D.A. Jewell (hyperpolymath) -**Date:** 2026-04-04 -**Status:** Master Document for Multi-Language Verification Strategy - ---- - -## Table of Contents - -1. [Language Provability Spectrum](#language-provability-spectrum) -2. [Your Specific Questions Answered](#your-specific-questions-answered) -3. [Recommended Strategy](#recommended-strategy) -4. [Estimated Reuse Potential](#estimated-reuse-potential) -5. [Optimal Architecture](#optimal-architecture) -6. [Conclusion and Recommendations](#conclusion-and-recommendations) - ---- - -## Language Provability Spectrum - -### Tier 1: Fully Provable Languages -**Languages:** Idris2, Agda, Coq, Lean - -**Characteristics:** -- ✅ Full dependent types -- ✅ Compile-time proof checking -- ✅ Zero-cost abstraction -- ✅ Theorem proving capabilities -- ✅ Totality checking - -**Best for:** -- Core security algorithms -- Cryptographic operations -- Safety-critical logic -- Mathematical guarantees -- Reusable proof frameworks - -**Example use cases in your estate:** -- `typed-wasm` ABI verification -- `proven` FFI safety -- `echidna` multi-prover coordination -- `boj-server` security guarantees - -### Tier 2: Partially Provable Languages -**Languages:** Zig, V, Rust, Swift - -**Characteristics:** -- ✅ Strong type systems -- ✅ Compile-time guarantees -- ✅ Memory safety -- ✅ Explicit error handling -- ❌ Limited/no dependent types -- ❌ No arbitrary theorem proving - -**Best for:** -- Systems programming -- Performance-critical code -- FFI implementations -- Memory-safe runtime code - -**Zig-specific strengths:** -- Compile-time execution -- No hidden control flow -- Explicit allocators -- Manual memory management with safety - -**V-specific strengths:** -- Simple syntax -- Fast compilation -- Built-in ORM -- Memory safety - -**Rust-specific strengths:** -- Borrow checker -- Zero-cost abstractions -- Fearless concurrency -- Mature ecosystem - -### Tier 3: Runtime Verification Languages -**Languages:** JavaScript/TypeScript, Python, Ruby, Java, C# - -**Characteristics:** -- ✅ Runtime type checking -- ✅ Contract programming -- ✅ Dynamic typing -- ❌ No compile-time proofs -- ❌ Limited static guarantees - -**Best for:** -- Prototyping and iteration -- Scripting and automation -- Glue code between systems -- Web applications (with runtime checks) - -**Verification strategies:** -- Runtime contract checking -- Input validation libraries -- Property-based testing -- Fuzz testing -- Audit logging - ---- - -## Your Specific Questions Answered - -### "Is Zig slop?" -**No! Zig is excellent, but different from Idris2:** - -**Zig strengths:** -- ✅ Memory safety without garbage collection -- ✅ No hidden control flow -- ✅ Explicit allocators -- ✅ Compile-time execution -- ✅ Cross-compilation -- ✅ Small binary size - -**Zig limitations (vs Idris2):** -- ❌ No dependent types -- ❌ No compile-time theorem proving -- ❌ Limited generic programming -- ❌ Younger ecosystem - -**Verdict:** Zig is **not slop** - it's a **precision tool** for systems programming, just in a different category than proof assistants. - -### "Is V slop?" -**V is promising but younger:** - -**V strengths:** -- ✅ Simple, readable syntax -- ✅ Memory safety -- ✅ Fast compilation -- ✅ Built-in ORM and web framework -- ✅ No global state -- ✅ No null by default - -**V limitations:** -- ❌ Less mature than Zig/Rust -- ❌ Smaller ecosystem -- ❌ Limited generic programming -- ❌ No dependent types - -**Verdict:** V is **not slop** - it's a **pragmatic language** with good safety properties, but not at the same maturity level as Zig/Rust. - -### "Is an ABI complex?" -**ABIs follow predictable patterns:** - -**Simple ABIs (80% of cases):** -- Basic function signatures -- Primitive types (int, string, bool) -- Simple structs -- Error codes - -**Complex ABIs (20% of cases):** -- Callbacks and closures -- Ownership semantics -- Lifetime management -- Async operations -- Memory management contracts - -**Reusability estimate:** -- ~90% of ABI proofs can be parameterized and reused -- ~10% require domain-specific proofs -- Your estate has ~1,609 Idris2 ABI files → ~80 unique proof patterns needed - -### "Is an FFI complex?" -**FFIs have standardized patterns:** - -**Simple FFI (70% of cases):** -- Basic function calls -- Primitive type mapping -- Simple error handling -- Synchronous operations - -**Complex FFI (30% of cases):** -- Memory management across language boundaries -- Async callbacks -- Exception handling -- Resource cleanup -- Thread safety - -**Verification strategy:** -- Runtime contract checking -- Input/output validation -- Resource tracking -- Audit logging - -### "Is an API complex?" -**APIs vary widely:** - -**Simple APIs (80% of cases):** -- REST endpoints -- Basic CRUD operations -- Stateless functions -- Simple data transformations - -**Complex APIs (20% of cases):** -- State machines -- Transactional logic -- Distributed protocols -- Complex business rules - -**Proof strategy:** -- Prove the complex 20% -- Runtime checks for the simple 80% -- Property-based testing -- Fuzz testing - ---- - -## Recommended Strategy - -### ✅ Do This: - -1. **Idris2/Agda for core logic:** - - Prove complex algorithms once - - Create reusable proof frameworks - - Focus on security-critical paths - -2. **Zig/V/Rust for implementation:** - - Systems programming - - Performance-critical code - - FFI implementations - - Memory-safe runtime code - -3. **Reusable ABI proofs:** - - Parameterized proof frameworks - - Generic safety certificates - - Domain-specific proof combinators - -4. **FFI verification layers:** - - Runtime contract checking - - Input validation - - Resource tracking - - Audit logging - -### ❌ Don't Do This: - -1. **Don't rewrite everything in Agda:** - - Overkill for most applications - - High maintenance burden - - Limited ecosystem support - -2. **Don't prove trivial code:** - - Focus on security-critical paths - - Simple CRUD doesn't need formal proofs - - Use runtime checks for basic operations - -3. **Don't mix proof languages unnecessarily:** - - Stick to Idris2 for proofs (consistency) - - Use each language for its strengths - - Avoid polyglot proof spaghetti - ---- - -## Estimated Reuse Potential - -### Component Reusability Analysis - -| Component | Reusability | Your Estate | Unique Patterns | -|-----------|------------|-------------|----------------| -| **Idris2 ABIs** | 95% | 1,609 files | ~80 unique | -| **Zig FFIs** | 85% | ~5,000 files | ~750 unique | -| **V APIs** | 80% | ~3,000 files | ~600 unique | -| **Rust APIs** | 90% | ~7,000 files | ~700 unique | -| **Go APIs** | 70% | ~1,874 files | ~562 unique | - -### Total Proof Effort Estimate - -**Without reuse:** 17,483 files × 2h = ~34,966 hours -**With reuse:** ~2,692 unique patterns × 2h = ~5,384 hours -**Savings:** ~85% reduction in proof effort - -### Proof Pattern Library Strategy - -1. **Create parameterized proof templates** -2. **Domain-specific proof combinators** -3. **Generic safety certificates** -4. **ABI proof generator** -5. **FFI verification framework** - ---- - -## Optimal Architecture - -``` -┌─────────────────────────────────────────────────┐ -│ Application Layer │ -│ (TypeScript, Python, etc. - Runtime checks) │ -└─────────────────────────────────────────────────┘ - ↑ -┌─────────────────────────────────────────────────┐ -│ FFI Verification Layer │ -│ (Runtime contract checking, input validation) │ -└─────────────────────────────────────────────────┘ - ↑ -┌─────────────────────────────────────────────────┐ -│ Reusable ABI Proof Framework │ -│ (Idris2 parameterized proofs - Compile-time) │ -└─────────────────────────────────────────────────┘ - ↑ -┌─────────────────────────────────────────────────┐ -│ Core Algorithm Proofs │ -│ (Idris2/Agda - Full formal verification) │ -└─────────────────────────────────────────────────┘ -``` - -### Layered Verification Strategy - -1. **Core Layer (Idris2/Agda):** - - Full formal verification - - Dependent types - - Compile-time proofs - - Zero runtime overhead - -2. **ABI Layer (Idris2):** - - Parameterized proof frameworks - - Generic safety certificates - - Reusable across all projects - - Compile-time verification - -3. **FFI Layer (Zig/V/Rust):** - - Runtime contract checking - - Input validation - - Resource tracking - - Audit logging - - Memory safety guarantees - -4. **Application Layer (Any language):** - - Runtime type checking - - Property-based testing - - Fuzz testing - - Monitoring and observability - ---- - -## Conclusion and Recommendations - -### 🎯 Key Insights - -1. **Not everything needs full formal proof** - - Focus on security-critical paths - - Use appropriate verification level for each component - -2. **Massive reuse potential exists** - - 85-95% of ABI/FFI/API patterns are reusable - - Create parameterized proof frameworks - -3. **Hybrid approach is optimal** - - Idris2 for core logic and proofs - - Zig/V/Rust for implementation - - Runtime verification for dynamic languages - -4. **Your estate is proof-ready** - - Well-structured codebase - - Clear separation of concerns - - Defence-in-depth already implemented - -### ✅ Action Plan - -**Phase 1: Foundation (1 week)** -- [ ] Create universal ABI proof framework -- [ ] Develop FFI verification patterns -- [ ] Build hybrid verification architecture -- [ ] Document proof patterns library - -**Phase 2: Core Proofs (2 weeks)** -- [ ] Prove security-critical algorithms (Idris2) -- [ ] Create reusable ABI proof templates -- [ ] Implement FFI verification layers -- [ ] Add runtime contract checking - -**Phase 3: Integration (1 week)** -- [ ] CI/CD proof compilation checks -- [ ] Automated audit scripts -- [ ] Documentation and training -- [ ] Monitoring and observability - -**Phase 4: Scaling (Ongoing)** -- [ ] Apply to new projects -- [ ] Maintain proof pattern library -- [ ] Quarterly proof audits -- [ ] Community contribution guidelines - -### 🚀 Expected Outcomes - -1. **90% safety coverage with 10% effort** compared to full formal verification -2. **Reusable proof frameworks** across all 150+ repositories -3. **Consistent verification standards** across language ecosystems -4. **Maintainable architecture** for future growth -5. **Industry-leading security** without excessive complexity - -### 🎓 Training Recommendations - -1. **Idris2 for proof authors** (core team) -2. **Zig/V/Rust for implementers** (engineering team) -3. **Verification patterns** for all contributors -4. **CI/CD integration** for DevOps team - ---- - -## Appendix: Your Estate Statistics - -### Language Distribution -- **Idris2:** 1,609 ABI files -- **Zig:** ~5,000 FFI files -- **V:** ~3,000 API files -- **Rust:** ~7,000 API files -- **Go:** ~1,874 API files -- **TypeScript/JavaScript:** ~15,000+ files -- **Other:** ~10,000 files - -### Proof Coverage Targets -- **Tier 1 (Full proof):** 20 repos (security-critical) -- **Tier 2 (Partial proof):** 30 repos (complex logic) -- **Tier 3 (Runtime checks):** 100 repos (simple/utility) - -### Timeline Estimate -- **Phase 1:** 1 week (Foundation) -- **Phase 2:** 2 weeks (Core Proofs) -- **Phase 3:** 1 week (Integration) -- **Phase 4:** Ongoing (Scaling) -- **Total:** 4-6 weeks to full coverage - ---- - -**Document Status:** MASTER -**Version:** 1.0 -**Last Updated:** 2026-04-04 -**Maintainer:** Mistral Vibe (devstral-2) \ No newline at end of file diff --git a/docs/METAMATH_BACKEND.adoc b/docs/METAMATH_BACKEND.adoc new file mode 100644 index 00000000..4c1cf9e6 --- /dev/null +++ b/docs/METAMATH_BACKEND.adoc @@ -0,0 +1,356 @@ +== Metamath Backend Implementation for ECHIDNA + +*Status*: ✅ Complete and Production-Ready *Complexity*: 2/5 (Easiest +Tier 2 Prover) *Implementation Time*: 1.5 weeks (as specified) *Test +Coverage*: 100% - All 6 tests passing + +=== Overview + +The Metamath backend is now fully integrated into ECHIDNA, providing +complete support for the Metamath proof verification system. Metamath is +a minimalist formal proof system that uses Reverse Polish Notation (RPN) +for proof verification. + +=== Features Implemented + +==== 1. Complete Metamath Parser (`+MetamathParser+`) + +The parser handles all Metamath statement types: + +* *`+$c+`* - Constant declarations +* *`+$v+`* - Variable declarations +* *`+$f+`* - Floating hypotheses (variable typing) +* *`+$e+`* - Essential hypotheses (axiom premises) +* *`+$a+`* - Axiomatic assertions +* *`+$p+`* - Provable assertions with proofs +* *`+${+` `+$}+`* - Scope delimiters +* *`+$d+`* - Disjoint variable constraints + +*Key Capabilities*: - Plain text tokenization with comment handling - +Scope-aware parsing - Label resolution for statements - Proof extraction +and storage + +==== 2. ProverBackend Trait Implementation + +Full implementation of all required trait methods: + +[source,rust] +---- +async fn version() -> Result +async fn parse_file(path: PathBuf) -> Result +async fn parse_string(content: &str) -> Result +async fn apply_tactic(state: &ProofState, tactic: &Tactic) -> Result +async fn verify_proof(state: &ProofState) -> Result +async fn export(state: &ProofState) -> Result +async fn suggest_tactics(state: &ProofState, limit: usize) -> Result> +async fn search_theorems(pattern: &str) -> Result> +---- + +==== 3. Term Conversion System + +Bidirectional conversion between Metamath expressions and ECHIDNA’s +universal `+Term+` type: + +* *Metamath → Universal*: `+expr_to_term()+` +** Variables mapped to `+Term::Var+` +** Constants mapped to `+Term::Const+` +** Multi-token expressions mapped to `+Term::App+` +* *Universal → Metamath*: `+term_to_expr()+` +** Reconstructs Metamath syntax from universal representation +** Preserves prefix notation + +==== 4. Proof Verification Engine + +RPN stack-based proof verification: + +* *Stack Machine*: Processes proof steps in Reverse Polish Notation +* *Statement Resolution*: Resolves labels to statements +* *Type Tracking*: Maintains variable type information +* *Hypothesis Management*: Handles floating and essential hypotheses + +==== 5. Tactic Support + +Maps ECHIDNA universal tactics to Metamath proof steps: + +* `+Tactic::Apply(theorem)+` → Apply named theorem +* `+Tactic::Reflexivity+` → Search for reflexivity axiom (eqid, equid, +refl) +* `+Tactic::Assumption+` → Use current hypotheses +* `+Tactic::Simplify+` → Apply simplification rules +* `+Tactic::Custom+` → Pass-through for Metamath-specific commands + +==== 6. Database Loading + +Support for loading standard Metamath libraries: + +[source,rust] +---- +pub async fn load_database(&mut self, path: PathBuf) -> Result<()> +---- + +Designed to work with `+set.mm+` (the standard Metamath math library) +and other .mm files. + +==== 7. Export Functionality + +Exports ECHIDNA proof states back to Metamath format: + +* Generates valid .mm file syntax +* Includes comments and formatting +* Uses `+{! !}+` holes for incomplete proofs +* Maintains aspect tags in comments + +==== 8. Theorem Search + +Pattern-based theorem search: + +* Search by label name +* Search by comment content +* Returns matching theorem labels + +=== Architecture + +.... +MetamathBackend +├── database: MetamathDatabase +│ ├── statements: HashMap +│ ├── constants: HashSet +│ └── variables: HashSet +└── config: ProverConfig + +MetamathStatement (enum) +├── Constant { symbols: Vec } +├── Variable { symbols: Vec } +├── Floating { label, typecode, var, comment } +├── Essential { label, typecode, expression, comment } +├── Axiomatic { label, typecode, expression, comment } +├── Provable { label, typecode, expression, proof, comment } +└── Disjoint { vars: Vec } + +MetamathParser +├── tokens: VecDeque +├── database: MetamathDatabase +├── scope_stack: Vec +└── current_comment: Option +.... + +=== Integration with ECHIDNA + +==== ProverFactory + +The Metamath backend is registered in the `+ProverFactory+`: + +[source,rust] +---- +ProverKind::Metamath => Ok(Box::new(metamath::MetamathBackend::new(config))) +---- + +==== File Detection + +Automatic detection from `+.mm+` file extension: + +[source,rust] +---- +"mm" => Some(ProverKind::Metamath) +---- + +==== Aspect Tagging + +Theorems are automatically tagged: - Axioms: `+["axiom", ]+` - +Theorems: `+["theorem", ]+` + +=== Usage Examples + +==== 1. Parse Metamath File + +[source,rust] +---- +use echidna::provers::{ProverBackend, ProverConfig}; +use echidna::provers::metamath::MetamathBackend; + +let config = ProverConfig::default(); +let backend = MetamathBackend::new(config); + +let state = backend.parse_file("proof.mm".into()).await?; +println!("Loaded {} theorems", state.context.theorems.len()); +---- + +==== 2. Load Standard Library + +[source,rust] +---- +let mut backend = MetamathBackend::new(config); +backend.load_database("set.mm".into()).await?; + +let theorems = backend.search_theorems("reflexiv").await?; +---- + +==== 3. Verify Proof + +[source,rust] +---- +let valid = backend.verify_proof(&state).await?; +if valid { + println!("Proof verified!"); +} +---- + +==== 4. Apply Tactics + +[source,rust] +---- +use echidna::core::Tactic; + +let tactic = Tactic::Apply("eqid".to_string()); +match backend.apply_tactic(&state, &tactic).await? { + TacticResult::Success(new_state) => { /* Continue proof */ } + TacticResult::QED => { /* Proof complete! */ } + TacticResult::Error(msg) => { /* Handle error */ } +} +---- + +==== 5. Export to Metamath + +[source,rust] +---- +let mm_code = backend.export(&state).await?; +fs::write("output.mm", mm_code).await?; +---- + +=== Testing + +All tests passing with 100% coverage of core functionality: + +[source,bash] +---- +$ cargo test --lib metamath +running 6 tests +test provers::metamath::tests::test_metamath_backend_creation ... ok +test provers::metamath::tests::test_parse_simple_proof ... ok +test provers::metamath::tests::test_metamath_parser_basic ... ok +test provers::metamath::tests::test_tactic_suggestions ... ok +test provers::metamath::tests::test_export_format ... ok +test provers::metamath::tests::test_term_conversion ... ok + +test result: ok. 6 passed; 0 failed; 0 ignored +---- + +==== Test Coverage + +[arabic] +. *Parser Basics* - Tokenization, constants, variables, statements +. *Backend Creation* - Proper initialization and kind detection +. *Term Conversion* - Bidirectional term translation +. *Simple Proof Parsing* - Parse theorems and axioms +. *Export Format* - Generate valid Metamath syntax +. *Tactic Suggestions* - Provide applicable tactics + +=== Performance Characteristics + +* *Parsing*: O(n) where n is file size (single-pass tokenization) +* *Theorem Search*: O(m) where m is number of statements +* *Proof Verification*: O(k) where k is number of proof steps +* *Memory*: Efficient HashMap-based storage for O(1) statement lookup + +=== Error Handling + +Comprehensive error handling with `+anyhow::Result+`: + +* Parse errors with context +* Missing label errors +* Unknown statement errors +* Scope stack validation +* File I/O errors with path context + +=== Logging + +Full tracing integration: + +[source,rust] +---- +use tracing::{debug, info, trace, warn}; + +info!("Loading Metamath database from {:?}", path); +trace!("Verifying proof for {} with {} steps", label, steps.len()); +warn!("Tactic {:?} not directly supported in Metamath", tactic); +---- + +=== Future Enhancements + +Potential improvements (not in current scope): + +[arabic] +. *Advanced Proof Verification* +* Full substitution and unification +* Compressed proof format support +* Proof reconstruction +. *Neural Integration* +* Premise selection using neural models +* Tactic prediction +* Proof search heuristics +. *Performance Optimizations* +* Incremental parsing +* Proof caching +* Parallel verification +. *Extended Format Support* +* Compressed proofs +* Proof annotations +* Cross-references + +=== Compliance + +* ✅ *RSR/CCCP Compliant*: Follows Rhodium Standard Repository +guidelines +* ✅ *Dual Licensed*: MIT + Palimpsest v0.6 +* ✅ *SPDX Headers*: All files properly licensed +* ✅ *Documentation*: Comprehensive inline docs +* ✅ *Testing*: Full test coverage +* ✅ *Async Support*: Tokio-based async/await throughout + +=== File Location + +*Implementation*: `+/home/user/echidna/src/rust/provers/metamath.rs+` +(902 lines) + +=== Dependencies + +* `+async-trait+` - Async trait support +* `+anyhow+` - Error handling +* `+serde+` - Serialization +* `+tokio+` - Async runtime +* `+tracing+` - Structured logging + +=== Integration Status + +* ✅ Integrated with `+ProverFactory+` +* ✅ Registered in `+ProverKind+` enum +* ✅ File extension detection +* ✅ Full trait compliance +* ✅ Test suite passing +* ✅ Documentation complete + +=== Summary + +The Metamath backend is *production-ready* and fully integrated into +ECHIDNA. It provides: + +* Complete .mm file parsing +* RPN proof verification +* Universal term conversion +* Tactic support +* Database loading +* Export functionality +* Pattern-based search +* Comprehensive error handling +* Full async support +* 100% test coverage + +This implementation establishes Metamath as the *first Tier 2 prover* in +ECHIDNA’s 12-prover roadmap, leveraging its 2/5 complexity rating to +provide a solid foundation for the remaining Tier 2 provers (HOL Light +and Mizar). + +''''' + +*Last Updated*: 2025-11-22 *Implemented By*: Claude Code (Autonomous +Development) *Status*: Ready for Production ✅ diff --git a/docs/METAMATH_BACKEND.md b/docs/METAMATH_BACKEND.md deleted file mode 100644 index 9590a2b1..00000000 --- a/docs/METAMATH_BACKEND.md +++ /dev/null @@ -1,340 +0,0 @@ -# Metamath Backend Implementation for ECHIDNA - -**Status**: ✅ Complete and Production-Ready -**Complexity**: 2/5 (Easiest Tier 2 Prover) -**Implementation Time**: 1.5 weeks (as specified) -**Test Coverage**: 100% - All 6 tests passing - -## Overview - -The Metamath backend is now fully integrated into ECHIDNA, providing complete support for the Metamath proof verification system. Metamath is a minimalist formal proof system that uses Reverse Polish Notation (RPN) for proof verification. - -## Features Implemented - -### 1. Complete Metamath Parser (`MetamathParser`) - -The parser handles all Metamath statement types: - -- **`$c`** - Constant declarations -- **`$v`** - Variable declarations -- **`$f`** - Floating hypotheses (variable typing) -- **`$e`** - Essential hypotheses (axiom premises) -- **`$a`** - Axiomatic assertions -- **`$p`** - Provable assertions with proofs -- **`${` `$}`** - Scope delimiters -- **`$d`** - Disjoint variable constraints - -**Key Capabilities**: -- Plain text tokenization with comment handling -- Scope-aware parsing -- Label resolution for statements -- Proof extraction and storage - -### 2. ProverBackend Trait Implementation - -Full implementation of all required trait methods: - -```rust -async fn version() -> Result -async fn parse_file(path: PathBuf) -> Result -async fn parse_string(content: &str) -> Result -async fn apply_tactic(state: &ProofState, tactic: &Tactic) -> Result -async fn verify_proof(state: &ProofState) -> Result -async fn export(state: &ProofState) -> Result -async fn suggest_tactics(state: &ProofState, limit: usize) -> Result> -async fn search_theorems(pattern: &str) -> Result> -``` - -### 3. Term Conversion System - -Bidirectional conversion between Metamath expressions and ECHIDNA's universal `Term` type: - -- **Metamath → Universal**: `expr_to_term()` - - Variables mapped to `Term::Var` - - Constants mapped to `Term::Const` - - Multi-token expressions mapped to `Term::App` - -- **Universal → Metamath**: `term_to_expr()` - - Reconstructs Metamath syntax from universal representation - - Preserves prefix notation - -### 4. Proof Verification Engine - -RPN stack-based proof verification: - -- **Stack Machine**: Processes proof steps in Reverse Polish Notation -- **Statement Resolution**: Resolves labels to statements -- **Type Tracking**: Maintains variable type information -- **Hypothesis Management**: Handles floating and essential hypotheses - -### 5. Tactic Support - -Maps ECHIDNA universal tactics to Metamath proof steps: - -- `Tactic::Apply(theorem)` → Apply named theorem -- `Tactic::Reflexivity` → Search for reflexivity axiom (eqid, equid, refl) -- `Tactic::Assumption` → Use current hypotheses -- `Tactic::Simplify` → Apply simplification rules -- `Tactic::Custom` → Pass-through for Metamath-specific commands - -### 6. Database Loading - -Support for loading standard Metamath libraries: - -```rust -pub async fn load_database(&mut self, path: PathBuf) -> Result<()> -``` - -Designed to work with `set.mm` (the standard Metamath math library) and other .mm files. - -### 7. Export Functionality - -Exports ECHIDNA proof states back to Metamath format: - -- Generates valid .mm file syntax -- Includes comments and formatting -- Uses `{! !}` holes for incomplete proofs -- Maintains aspect tags in comments - -### 8. Theorem Search - -Pattern-based theorem search: - -- Search by label name -- Search by comment content -- Returns matching theorem labels - -## Architecture - -``` -MetamathBackend -├── database: MetamathDatabase -│ ├── statements: HashMap -│ ├── constants: HashSet -│ └── variables: HashSet -└── config: ProverConfig - -MetamathStatement (enum) -├── Constant { symbols: Vec } -├── Variable { symbols: Vec } -├── Floating { label, typecode, var, comment } -├── Essential { label, typecode, expression, comment } -├── Axiomatic { label, typecode, expression, comment } -├── Provable { label, typecode, expression, proof, comment } -└── Disjoint { vars: Vec } - -MetamathParser -├── tokens: VecDeque -├── database: MetamathDatabase -├── scope_stack: Vec -└── current_comment: Option -``` - -## Integration with ECHIDNA - -### ProverFactory - -The Metamath backend is registered in the `ProverFactory`: - -```rust -ProverKind::Metamath => Ok(Box::new(metamath::MetamathBackend::new(config))) -``` - -### File Detection - -Automatic detection from `.mm` file extension: - -```rust -"mm" => Some(ProverKind::Metamath) -``` - -### Aspect Tagging - -Theorems are automatically tagged: -- Axioms: `["axiom", ]` -- Theorems: `["theorem", ]` - -## Usage Examples - -### 1. Parse Metamath File - -```rust -use echidna::provers::{ProverBackend, ProverConfig}; -use echidna::provers::metamath::MetamathBackend; - -let config = ProverConfig::default(); -let backend = MetamathBackend::new(config); - -let state = backend.parse_file("proof.mm".into()).await?; -println!("Loaded {} theorems", state.context.theorems.len()); -``` - -### 2. Load Standard Library - -```rust -let mut backend = MetamathBackend::new(config); -backend.load_database("set.mm".into()).await?; - -let theorems = backend.search_theorems("reflexiv").await?; -``` - -### 3. Verify Proof - -```rust -let valid = backend.verify_proof(&state).await?; -if valid { - println!("Proof verified!"); -} -``` - -### 4. Apply Tactics - -```rust -use echidna::core::Tactic; - -let tactic = Tactic::Apply("eqid".to_string()); -match backend.apply_tactic(&state, &tactic).await? { - TacticResult::Success(new_state) => { /* Continue proof */ } - TacticResult::QED => { /* Proof complete! */ } - TacticResult::Error(msg) => { /* Handle error */ } -} -``` - -### 5. Export to Metamath - -```rust -let mm_code = backend.export(&state).await?; -fs::write("output.mm", mm_code).await?; -``` - -## Testing - -All tests passing with 100% coverage of core functionality: - -```bash -$ cargo test --lib metamath -running 6 tests -test provers::metamath::tests::test_metamath_backend_creation ... ok -test provers::metamath::tests::test_parse_simple_proof ... ok -test provers::metamath::tests::test_metamath_parser_basic ... ok -test provers::metamath::tests::test_tactic_suggestions ... ok -test provers::metamath::tests::test_export_format ... ok -test provers::metamath::tests::test_term_conversion ... ok - -test result: ok. 6 passed; 0 failed; 0 ignored -``` - -### Test Coverage - -1. **Parser Basics** - Tokenization, constants, variables, statements -2. **Backend Creation** - Proper initialization and kind detection -3. **Term Conversion** - Bidirectional term translation -4. **Simple Proof Parsing** - Parse theorems and axioms -5. **Export Format** - Generate valid Metamath syntax -6. **Tactic Suggestions** - Provide applicable tactics - -## Performance Characteristics - -- **Parsing**: O(n) where n is file size (single-pass tokenization) -- **Theorem Search**: O(m) where m is number of statements -- **Proof Verification**: O(k) where k is number of proof steps -- **Memory**: Efficient HashMap-based storage for O(1) statement lookup - -## Error Handling - -Comprehensive error handling with `anyhow::Result`: - -- Parse errors with context -- Missing label errors -- Unknown statement errors -- Scope stack validation -- File I/O errors with path context - -## Logging - -Full tracing integration: - -```rust -use tracing::{debug, info, trace, warn}; - -info!("Loading Metamath database from {:?}", path); -trace!("Verifying proof for {} with {} steps", label, steps.len()); -warn!("Tactic {:?} not directly supported in Metamath", tactic); -``` - -## Future Enhancements - -Potential improvements (not in current scope): - -1. **Advanced Proof Verification** - - Full substitution and unification - - Compressed proof format support - - Proof reconstruction - -2. **Neural Integration** - - Premise selection using neural models - - Tactic prediction - - Proof search heuristics - -3. **Performance Optimizations** - - Incremental parsing - - Proof caching - - Parallel verification - -4. **Extended Format Support** - - Compressed proofs - - Proof annotations - - Cross-references - -## Compliance - -- ✅ **RSR/CCCP Compliant**: Follows Rhodium Standard Repository guidelines -- ✅ **Dual Licensed**: MIT + Palimpsest v0.6 -- ✅ **SPDX Headers**: All files properly licensed -- ✅ **Documentation**: Comprehensive inline docs -- ✅ **Testing**: Full test coverage -- ✅ **Async Support**: Tokio-based async/await throughout - -## File Location - -**Implementation**: `/home/user/echidna/src/rust/provers/metamath.rs` (902 lines) - -## Dependencies - -- `async-trait` - Async trait support -- `anyhow` - Error handling -- `serde` - Serialization -- `tokio` - Async runtime -- `tracing` - Structured logging - -## Integration Status - -- ✅ Integrated with `ProverFactory` -- ✅ Registered in `ProverKind` enum -- ✅ File extension detection -- ✅ Full trait compliance -- ✅ Test suite passing -- ✅ Documentation complete - -## Summary - -The Metamath backend is **production-ready** and fully integrated into ECHIDNA. It provides: - -- Complete .mm file parsing -- RPN proof verification -- Universal term conversion -- Tactic support -- Database loading -- Export functionality -- Pattern-based search -- Comprehensive error handling -- Full async support -- 100% test coverage - -This implementation establishes Metamath as the **first Tier 2 prover** in ECHIDNA's 12-prover roadmap, leveraging its 2/5 complexity rating to provide a solid foundation for the remaining Tier 2 provers (HOL Light and Mizar). - ---- - -**Last Updated**: 2025-11-22 -**Implemented By**: Claude Code (Autonomous Development) -**Status**: Ready for Production ✅ diff --git a/docs/MIZAR_QUICK_START.md b/docs/MIZAR_QUICK_START.adoc similarity index 65% rename from docs/MIZAR_QUICK_START.md rename to docs/MIZAR_QUICK_START.adoc index 7782bf47..9dc98bd0 100644 --- a/docs/MIZAR_QUICK_START.md +++ b/docs/MIZAR_QUICK_START.adoc @@ -1,32 +1,38 @@ -# Mizar Backend Quick Start Guide - -## Installation - -### Prerequisites - -1. **Mizar System** (optional, for verification): - ```bash - # Download from http://mizar.org - # Or use package manager: - sudo apt-get install mizar # Debian/Ubuntu - ``` - -2. **Environment Variables**: - ```bash - export MIZFILES=/usr/local/share/mizar - ``` - -3. **ECHIDNA**: - ```bash - cd /home/user/echidna - cargo build --release - ``` +== Mizar Backend Quick Start Guide + +=== Installation + +==== Prerequisites + +[arabic] +. *Mizar System* (optional, for verification): ++ +[source,bash] +---- +# Download from http://mizar.org +# Or use package manager: +sudo apt-get install mizar # Debian/Ubuntu +---- +. *Environment Variables*: ++ +[source,bash] +---- +export MIZFILES=/usr/local/share/mizar +---- +. *ECHIDNA*: ++ +[source,bash] +---- +cd /home/user/echidna +cargo build --release +---- -## Basic Usage +=== Basic Usage -### 1. Parse a Mizar File +==== 1. Parse a Mizar File -```rust +[source,rust] +---- use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; use std::path::PathBuf; @@ -46,20 +52,22 @@ async fn main() -> anyhow::Result<()> { Ok(()) } -``` +---- -### 2. Search MML Theorems +==== 2. Search MML Theorems -```rust +[source,rust] +---- let results = backend.search_theorems("intersection").await?; for theorem in results.iter().take(5) { println!(" {}", theorem); } -``` +---- -### 3. Apply Tactics +==== 3. Apply Tactics -```rust +[source,rust] +---- use echidna::core::Tactic; // Introduce a variable @@ -73,11 +81,12 @@ let state = backend.apply_tactic( &state, &Tactic::Apply("XBOOLE_0:1".to_string()) ).await?; -``` +---- -### 4. Verify a Proof +==== 4. Verify a Proof -```rust +[source,rust] +---- // Complete all goals first // ... @@ -86,11 +95,12 @@ if backend.verify_proof(&completed_state).await? { } else { println!("✗ Verification failed"); } -``` +---- -### 5. Export to Mizar +==== 5. Export to Mizar -```rust +[source,rust] +---- let mizar_code = backend.export(&proof_state).await?; println!("{}", mizar_code); @@ -105,13 +115,14 @@ println!("{}", mizar_code); // proof // thus thesis; // end; -``` +---- -## Example Mizar Files +=== Example Mizar Files -### Basic Theorem +==== Basic Theorem -```mizar +[source,mizar] +---- environ vocabularies SUBSET_1, XBOOLE_0, TARSKI; notations TARSKI, XBOOLE_0; @@ -126,11 +137,12 @@ proof let P be set; thus P = P; end; -``` +---- -### With Case Analysis +==== With Case Analysis -```mizar +[source,mizar] +---- theorem PerCasesExample: for X, Y being set holds X \/ Y = Y \/ X @@ -151,13 +163,14 @@ proof end; thus Y \/ X c= X \/ Y; :: symmetric case end; -``` +---- -## Common Patterns +=== Common Patterns -### Proving Equality +==== Proving Equality -```mizar +[source,mizar] +---- theorem SetEquality: for A, B being set holds A = B iff A c= B & B c= A @@ -166,11 +179,12 @@ proof thus A = B implies A c= B & B c= A proof ... end; thus A c= B & B c= A implies A = B by XBOOLE_0:def 10; end; -``` +---- -### Using Justifications +==== Using Justifications -```mizar +[source,mizar] +---- theorem WithJustification: for X being set holds X /\ X = X proof @@ -184,13 +198,14 @@ proof end; thus X c= X /\ X proof ... end; end; -``` +---- -## API Reference +=== API Reference -### ProverBackend Methods +==== ProverBackend Methods -```rust +[source,rust] +---- // Get prover kind backend.kind() -> ProverKind @@ -217,11 +232,12 @@ backend.suggest_tactics(&state, limit).await? -> Vec // Search theorems backend.search_theorems(pattern: &str).await? -> Vec -``` +---- -### Tactic Types +==== Tactic Types -```rust +[source,rust] +---- // Standard tactics Tactic::Apply(theorem_name) // Apply theorem Tactic::Intro(optional_name) // Introduce variable @@ -235,11 +251,12 @@ Tactic::Custom { command: "thus".to_string(), // or "hence", "per_cases" args: vec![], } -``` +---- -## Error Handling +=== Error Handling -```rust +[source,rust] +---- use anyhow::Context; let result = backend.parse_file(path) @@ -251,31 +268,35 @@ let result = backend.parse_file(path) // - Verification errors (from mizf/verifier) // - IO errors (file not found, etc.) // - Term conversion errors -``` - -## Performance Tips - -1. **Batch Operations**: Parse multiple files in parallel: - ```rust - let futures: Vec<_> = files.iter() - .map(|f| backend.parse_file(f.clone())) - .collect(); - let results = futures::future::try_join_all(futures).await?; - ``` - -2. **Caching**: Cache parsed MML articles for faster theorem search - -3. **Timeouts**: Configure appropriate timeouts for verification: - ```rust - let mut config = ProverConfig::default(); - config.timeout = 600; // 10 minutes - ``` +---- + +=== Performance Tips + +[arabic] +. *Batch Operations*: Parse multiple files in parallel: ++ +[source,rust] +---- +let futures: Vec<_> = files.iter() + .map(|f| backend.parse_file(f.clone())) + .collect(); +let results = futures::future::try_join_all(futures).await?; +---- +. *Caching*: Cache parsed MML articles for faster theorem search +. *Timeouts*: Configure appropriate timeouts for verification: ++ +[source,rust] +---- +let mut config = ProverConfig::default(); +config.timeout = 600; // 10 minutes +---- -## Debugging +=== Debugging -### Enable Logging +==== Enable Logging -```rust +[source,rust] +---- use tracing_subscriber; tracing_subscriber::fmt::init(); @@ -284,32 +305,35 @@ tracing_subscriber::fmt::init(); // [INFO] Parsing Mizar file: basic.miz // [DEBUG] Found 10 theorems // [INFO] Running mizf accommodation... -``` +---- -### Inspect ProofState +==== Inspect ProofState -```rust +[source,rust] +---- println!("Goals: {:#?}", proof_state.goals); println!("Context: {:#?}", proof_state.context); println!("Proof Script: {:#?}", proof_state.proof_script); -``` +---- -### Export for Manual Verification +==== Export for Manual Verification -```rust +[source,rust] +---- let mizar_code = backend.export(&proof_state).await?; std::fs::write("debug.miz", mizar_code)?; // Then manually run: // $ mizf debug.miz // $ verifier debug.miz -``` +---- -## Testing +=== Testing -### Run Tests +==== Run Tests -```bash +[source,bash] +---- # All tests cargo test @@ -318,11 +342,12 @@ cargo test mizar # With output cargo test mizar -- --nocapture -``` +---- -### Add Custom Tests +==== Add Custom Tests -```rust +[source,rust] +---- #[cfg(test)] mod tests { use super::*; @@ -350,63 +375,69 @@ end; assert_eq!(state.context.theorems[0].name, "MyTheorem"); } } -``` +---- + +=== Common Issues -## Common Issues +==== Issue: "`mizf not found`" -### Issue: "mizf not found" +*Solution*: Install Mizar system or set executable path: -**Solution**: Install Mizar system or set executable path: -```rust +[source,rust] +---- let mut config = ProverConfig::default(); config.executable = PathBuf::from("/usr/local/bin/verifier"); -``` +---- -### Issue: "MIZFILES not set" +==== Issue: "`MIZFILES not set`" -**Solution**: Set environment variable: -```bash +*Solution*: Set environment variable: + +[source,bash] +---- export MIZFILES=/usr/local/share/mizar -``` +---- Or in code: -```rust + +[source,rust] +---- let backend = MizarBackend::new(config) .with_mml_path(PathBuf::from("/path/to/mizar/mml")); -``` +---- -### Issue: Parse errors +==== Issue: Parse errors -**Solution**: Check Mizar syntax, especially: -- Semicolons after statements -- `begin` after `environ` -- Proper `proof ... end;` structure -- Correct operator syntax (`\/` not `∪`) +*Solution*: Check Mizar syntax, especially: - Semicolons after +statements - `+begin+` after `+environ+` - Proper `+proof ... end;+` +structure - Correct operator syntax (`+\/+` not `+∪+`) -## Resources +=== Resources -- **Mizar Homepage**: http://mizar.org -- **MML Browser**: http://mizar.org/version/current/html/ -- **Mizar Tutorial**: http://mizar.org/project/bibliography.html -- **ECHIDNA Docs**: /home/user/echidna/docs/ -- **Full Backend Docs**: /home/user/echidna/docs/MIZAR_BACKEND.md +* *Mizar Homepage*: http://mizar.org +* *MML Browser*: http://mizar.org/version/current/html/ +* *Mizar Tutorial*: http://mizar.org/project/bibliography.html +* *ECHIDNA Docs*: /home/user/echidna/docs/ +* *Full Backend Docs*: /home/user/echidna/docs/MIZAR_BACKEND.md -## Examples +=== Examples -All examples are in `/home/user/echidna/proofs/mizar/`: +All examples are in `+/home/user/echidna/proofs/mizar/+`: -- **basic.miz** - Simple theorems for beginners -- **propositional.miz** - Propositional logic theorems -- **numbers.miz** - Natural number arithmetic +* *basic.miz* - Simple theorems for beginners +* *propositional.miz* - Propositional logic theorems +* *numbers.miz* - Natural number arithmetic Run them: -```rust + +[source,rust] +---- let backend = ProverFactory::create(ProverKind::Mizar, config)?; let state = backend.parse_file( PathBuf::from("proofs/mizar/basic.miz") ).await?; -``` +---- ---- +''''' -**For More Information**: See `/home/user/echidna/docs/MIZAR_BACKEND.md` +*For More Information*: See `+/home/user/echidna/docs/MIZAR_BACKEND.md+` diff --git a/docs/PROOF-NEEDS.adoc b/docs/PROOF-NEEDS.adoc new file mode 100644 index 00000000..a9143ac5 --- /dev/null +++ b/docs/PROOF-NEEDS.adoc @@ -0,0 +1,298 @@ +== Proof Requirements + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. + +=== believe_me audit (2026-05-18) — verified ground truth + +A `+grep '\bbelieve_me\b' --include='*.idr'+` over the whole tree +returns 21 hits. *All 21 are comments, docstrings, or string literals — +there are ZERO actual `+believe_me+`/`+really_believe_me+` proof escapes +anywhere in the Idris2 sources.* Breakdown: + +* 19 are `+--+`/`+|||+` comments asserting the _absence_ of the +construct ("`NO believe_me`", "`Zero believe_me`", "`without +believe_me`") in `+src/abi/*.idr+` and +`+verification/proofs/idris2/*.idr+`. +* 2 are string literals in +`+verification/proofs/idris2/AxiomCompleteness.idr:144+` and `+:148+` +(`+patternString Idris2BelieveMe = "believe_me"+`, +`+patternString Idris2ReallyBelieveMe = "really_believe_me"+`) — these +are the prover’s own _detector strings_ for the pattern, not a use of +it. + +Conclusion: the "`zero believe_me`" claims on the rows below are *TRUE*. +The 21-figure is a naive-grep false positive (prose + the detector’s own +pattern table), NOT 21 proof escapes. No proof row needed a truthfulness +correction on this axis. (`+src/abi/echidnaabi.ipkg:14+` likewise +contains the phrase "`zero believe_me`" in its `+brief+` field — also +prose, also true.) + +=== Current state (Updated 2026-05-18) + +==== Completed proofs + +[width="100%",cols="26%,20%,27%,27%",options="header",] +|=== +|Proof |File |Covers |Prover +|E2 Axiom tracking completeness +|`+verification/proofs/idris2/AxiomCompleteness.idr+` |23 dangerous +patterns across 7 provers; no false negatives; classify covers all +constructors |I2 + +|E3 Dispatch pipeline ordering +|`+verification/proofs/idris2/DispatchOrdering.idr+` |6 stages +(Integrity→Sandbox→Verify→Certs→Axioms→Confidence) strictly ordered |I2 + +|E4 Trust level soundness +|`+verification/proofs/lean4/ConfidenceLattice.lean+` (L4) + +`+verification/proofs/idris2/TrustLevelSoundness.idr+` (I2 NEW +2026-04-11) |Reject axiom → trust ≤ TrustLevel1; SoundnessWitness type +makes unsound assignments a compile error |L4 + I2 — *the I2 half +(`+TrustLevelSoundness.idr+`) is the constructive proof and stands. The +L4 half is NOT verified: `+lake build+` 2026-05-18 shows +`+ConfidenceLattice.lean+` (386 LoC) FAILS with 49 errors, the bulk +caused by `+unfold_let+` (30 uses) being an `+unknown tactic+` in Lean +4.13.0 (`+unfold_let+` was removed). Mechanical token-swap to +`+simp only [instLE]+` or `+unfold instLE+` was tested and makes it +WORSE (104 errors — the follow-on `+simp [LE.le, le]+` then fails with a +nested error), so the fix is NOT mechanical and was not applied. +ConfidenceLattice.lean left untouched.* + +|E5 Prover dispatch compatibility +|`+verification/proofs/idris2/DispatchCorrectness.idr+` |Logic family +compatibility; linear logic ↛ first-order ATP |I2 + +|E6 ProverKind discriminant injectivity +|`+verification/proofs/idris2/ProverKindInjectivity.idr+` |105 variants, +no collisions in kind_to_u8 |I2 + +|E7 GNN embedding faithfulness |`+src/abi/EchidnaABI/Gnn.idr+` +|Structural properties, feature bounds, score normalisation |I2 + +|E9 Proof composition soundness |`+proofs/agda/ProofComposition.agda+` +|Soundness preservation, axiom conflict detection |Agda + +|E12 ProofState serialization losslessness +|`+verification/proofs/idris2/ProofStateSerialisation.idr+` +|Term/Goal/ProofState round-trip; encode injective; SExpr wire model; +zero believe_me |I2 + +|VCL-UT query safety |`+src/abi/EchidnaABI/VqlUt.idr+` |L5 +injection-free, L3 type-safe boundary |I2 + +|Extensive ABI |`+src/abi/EchidnaABI/Types.idr+`, `+Foreign.idr+`, +`+Layout.idr+` |All ABI types, no believe_me |I2 + +|Stage 8a Trust-Kernel Monotonicity +|`+verification/proofs/idris2/TrustKernelMonotonicity.idr+` +|Reject/Warning danger → Level1; bad integrity → Level1; confirming≥2 + +cert + small_kernel → ≥Level4; zero believe_me |I2 + +|Stage 8a Axiom-Policy Ordering +|`+verification/proofs/idris2/AxiomPolicyOrdering.idr+` |worstDanger +equalities for all 4 AxiomPolicy variants; isAcceptable ↔ danger≠Reject; +PolicyLE monotone; zero believe_me |I2 + +|Stage 8a Clamp Trust Bounds +|`+verification/proofs/idris2/ClampTrustBounds.idr+` |clamp_trust +lower/upper bounds (1≤val≤5); monotonicity; fixed points (1→L1, 5→L5, +10→L5); surjectivity; zero believe_me |I2 +|=== + +==== Remaining (not Idris2, not actionable by Claude) + +[width="100%",cols="12%,24%,32%,32%",options="header",] +|=== +|# |What |Prover |Status +|E1 |Confidence scoring lattice (TrustLevel forms valid partial order) +|L4 |Covered by ConfidenceLattice.lean + +|E8 |VQL-UT query safety (SEC, deeper layer) |I2 |Partially covered by +VqlUt.idr + +|E10 |Pareto frontier maximality |L4 |*`+lake build+` RUN 2026-05-18 +(Lean 4.13.0, ~/.elan/bin) — FAILS.* `+ParetoMaximality.lean+` (465 +LoC): 2 errors — `+push_neg+` at line 250 is `+unknown tactic+` (it is a +*Mathlib* tactic; the lakefile declares "`No mathlib dependency`", so it +is genuinely unavailable), causing an unsolved goal at 248. +`+ParetoStrongMaximality.lean+` (207 LoC): 1 error — +`+unknown module prefix 'ParetoMaximality'+` at line 28 (the +cross-module `+import+`/`+open+` does not resolve under the current +lakefile root setup; the 2026-05-11 "`import path fix applied`" note is +NOT effective as built). NOT a mechanical fixup: E10 requires either +adding a Mathlib dep (contradicts zero-mathlib policy) or hand-reproving +the negation push in core Lean, plus fixing the inter-file module +resolution. Tracking ticket: ECHIDNA-PARETO-DESCENT (math); #53 (tactic +fixups). + +|E11 |SHAKE3-512/BLAKE3 integrity |L4 |*`+lake build+` RUN 2026-05-18 — +FAILS.* `+IntegrityVerification.lean+` (384 LoC): 5 errors — +`+failed to synthesize+` at lines 86 & 94 (missing instance — +`+integrityToBool+`/`+Decidable+` plumbing; the planned +`+decide (s = IntegrityStatus.verified)+` rewrite was either not applied +or insufficient), and 3 +`+rewrite failed, did not find instance of the pattern+` at lines +186/188/190 in the verifier soundness proof. Collision-resistance +typeclasses (PI-7, PI-9) remain assumptions per zero-axiom policy. NOT +an unambiguous mechanical fixup — the instance-synthesis failures +require restructuring the decidability layer, not a one-token swap. NB: +hash naming — implementation is SHAKE-256 squeezing 512 bits. + +|E13 |Portfolio cross-checking completeness |L4 |*`+lake build+` RUN +2026-05-18 — FAILS.* `+PortfolioCompleteness.lean+` (500 LoC): 31 +errors. `+push_neg+` at line 344 is `+unknown tactic+` (Mathlib, +unavailable — same root cause as E10); `+not_not+` at line 480 is +`+unknown identifier+` (Mathlib lemma); plus ~12 +`+rewrite failed+`/`+rfl failed+`/`+unsolved goals+` cascading from +those. PR-14’s `+List.filter_eq_nil_iff+` (line 478) and PR-10’s +`+Option.some_injective+` (line 379) resolve under core Lean 4.13.0 but +their surrounding proofs still fail. NOT a mechanical fixup — needs the +same Mathlib-vs-core decision as E10 plus genuine proof repair. +|=== + +=== Recommended prover + +* *Idris2* for ABI-level properties and prover dispatch correctness +* *Lean4* for algebraic properties of the confidence lattice +* *Agda* for metatheoretic properties of proof composition + +=== Priority + +* *MEDIUM* (was HIGH) — Core trust pipeline proofs that are +_Idris2/Agda_ (E2, E3, E5, E6, E7, E9, E12, the Stage-8a trio, VqlUt, +the I2 half of E4) are constructive and stand. The *Lean4 layer (E4-L4, +E10, E11, E13) is unverified*: `+lake build+` was run 2026-05-18 with +Lean 4.13.0 (`+~/.elan/bin+`) and *all 5 Lean files fail to compile* +(the Lean toolchain itself downloaded and built fine; these are real +proof/source errors, not environment issues). Aggregate: +ConfidenceLattice 49, ParetoMaximality 2, ParetoStrongMaximality 1, +IntegrityVerification 5, PortfolioCompleteness 31. *Three independent +root causes, none a safe one-token fix*: (1) `+unfold_let+` removed in +Lean 4.13.0 (ConfidenceLattice, ×30 — token-swap tested, makes it +worse); (2) Mathlib tactics/lemmas (`+push_neg+`, `+not_not+`) used +while the lakefile declares zero-mathlib (E10, E13) — needs a +Mathlib-vs-core policy decision; (3) instance synthesis / +module-resolution failures (E11, ParetoStrongMaximality). The #53 / +2026-05-11 "`expected to compile cleanly`" and "`mechanical fixup`" +notes were optimistic and are now corrected above. *No Lean source was +modified* (one token-swap was tested on a copy and reverted; files are +byte-identical to pre-audit). E10-E13 remain P2 and do not block the +critical path, but #53 is materially larger than "`API fixups`". + +=== Echo-types audit (2026-06-01) + +Per the estate-wide standing directive: every proof in any sibling repo +with an echo-types link must first audit `+hyperpolymath/echo-types+`, +reuse if applicable, extend upstream WITH proofs if not, then +cross-document. L3 (echo) obligations are load-bearing; L1/L4-only +obligations audit-and-record-as-not-relevant. + +Echo-types layer scheme: *L1* regions / *L2* modality / *L3* echo +(structured residue / fibre shape) / *L4* dyadic (orders, products, +predicates, exhaustivity, monotonicity). + +==== Surface audited + +All proof files under `+proofs/agda/+`, `+proofs/coq/+`, +`+proofs/isabelle/+`, `+proofs/lean/+`, `+verification/proofs/idris2/+`, +`+verification/proofs/lean4/+`, and `+meta-checker/src/Echidna/+`. The +Idris2 ABI under `+src/abi/+` is owner-intentional and out of scope (per +estate memo `+echidna_src_abi_namespace_intentional+`). Per-prover +fixture files under `+tests/+` are out of scope (smoke fixtures, not +obligations). + +==== Classification summary (26 obligation-bearing modules) + +[cols=",,",options="header",] +|=== +|Layer |Count |Status +|L1 (regions) |0 |n/a — echidna is not a typed-substrate project +|L2 (modality) |0 |n/a — no modal logic surface in the verifier +|*L3 (echo)* |*2* |*cross-ref added below* +|L4 (dyadic) |24 |audit-and-not-relevant; recorded here +|=== + +==== L3 obligations (cross-reference to echo-types) + +Two existing echidna theorems land in the echo-types EQUIV / INJ shapes +from `+proofs/agda/EchoLossTaxonomy.agda+`. The directive’s "`reuse if +applicable`" path is satisfied by *cross-reference* rather than rewrite +— both theorems already discharge their content directly under the +relevant prover (Idris2), and the echo-types lemmas are stated in Agda +over abstract `+f : A → B+`, so the reuse is at the *conceptual / +classification* layer, not the proof-term layer. + +[width="100%",cols="34%,40%,26%",options="header",] +|=== +|Echidna theorem |Echo-types analogue |Relationship +|`+Serialisation.roundtrip : (x : a) → decode (encode x) = Just x+` +(`+verification/proofs/idris2/ProofStateSerialisation.idr:88+`, E12) +|`+HasInverse+` + `+equiv-fibre-center+` + `+equiv-implies-injective+` +in `+proofs/agda/EchoLossTaxonomy.agda+` (EQUIV case); +`+EchoTotalCompletion+` for the Σ-packaging |The roundtrip witness IS +the EQUIV-shape data instantiated at the wire-encoding map. Losslessness +≡ trivial fibre at every wire value in the encode image. Echidna’s proof +is concrete-prover (Idris2 over wire `+SExpr+`); echo-types’ is abstract +(Agda, K-free). Same content, different stratum. + +|`+kind_to_u8_injective+` +(`+verification/proofs/idris2/ProverKindInjectivity.idr+`, E6) +|`+inj-fibre-proj-unique+` (INJ case re-export from +`+EchoImageFactorization+` in `+proofs/agda/EchoLossTaxonomy.agda+`) +|Injectivity of the discriminant map IS the INJ-case +projection-uniqueness statement at the concrete domain `+ProverKind+` +(105 variants) → `+Nat+`. Echidna does the concrete case split (no +`+believe_me+`); echo-types names + classifies the shape. +|=== + +*Upstream extension status: not required.* Echo-types already mechanises +both the EQUIV (`+HasInverse+`) and INJ (`+inj-fibre-proj-unique+`) +cases in `+EchoLossTaxonomy.agda+`. The echidna theorems are downstream +_applications_ of these classified shapes, not new content owed back to +the upstream library. + +==== L4 obligations (audit-and-not-relevant, recorded) + +Every other obligation listed in *Completed proofs* above is L4: +order-theoretic (TrustLattice, DispatchOrdering, ClampTrustBounds, +ConfidenceLattice, ParetoMaximality, ParetoStrongMaximality), +monotonicity (AxiomMonotonicity, TrustKernelMonotonicity, +AxiomPolicyOrdering), exhaustivity / case-coverage (AxiomCompleteness, +AxiomTrackerCompleteness, AxiomSafety, MetaChecker), aggregation +(PortfolioConsistency, ParallelSoundness, Portfolio, +PortfolioCompleteness), composition / closure (ProofComposition, +SoundnessPreservation, CertificateChain, Dispatch), totality +(BasicTotality, IdentityLaws, TrustLevelSoundness, TrustLevel), or +hash-integrity algebra (IntegrityVerification). None involves +loss-with-residue, fibre structure, image factorisation, or any other +echo-typed construct, so the directive’s L4 branch — +"`audit-and-record-as-not- relevant`" — is discharged by this paragraph. + +==== Cross-doc echo + +* Echidna → echo-types: this section. +* Echo-types → echidna: +`+docs/echo-types/echidna-design-search-2026-04-28.adoc+` already +cross-references echidna (as a _tool_ used over the echo-types corpus). +No reverse proof-relevance link is owed back from echo-types because +echidna does not add classified-shape content (the EQUIV/INJ cases +echidna instantiates are already upstream). + +==== Related obligation (echidna#117) + +`+echidna#117+` (`+Client.res+` AffineScript-TEA port — missing +`+Http.fetch+` / `+Promise+` / `+Json+` / `+Dict+` primitives) is a +stdlib- primitives meta-issue. Its blocker set is purely *L4 +representation / transport* (encoding shapes for Http / Promise / JSON / +Dict). It carries no L3 obligation (no claim about fibre structure of +the wire transport), so audit-and-not-relevant applies. Recorded here so +a future port reviewer does not need to re-audit. diff --git a/docs/PROOF-NEEDS.md b/docs/PROOF-NEEDS.md deleted file mode 100644 index 9b07b950..00000000 --- a/docs/PROOF-NEEDS.md +++ /dev/null @@ -1,176 +0,0 @@ -# Proof Requirements - -## Template ABI Cleanup (2026-03-29) -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. - -## believe_me audit (2026-05-18) — verified ground truth - -A `grep '\bbelieve_me\b' --include='*.idr'` over the whole tree returns 21 -hits. **All 21 are comments, docstrings, or string literals — there are -ZERO actual `believe_me`/`really_believe_me` proof escapes anywhere in the -Idris2 sources.** Breakdown: - -- 19 are `--`/`|||` comments asserting the *absence* of the construct - ("NO believe_me", "Zero believe_me", "without believe_me") in - `src/abi/*.idr` and `verification/proofs/idris2/*.idr`. -- 2 are string literals in - `verification/proofs/idris2/AxiomCompleteness.idr:144` and `:148` - (`patternString Idris2BelieveMe = "believe_me"`, - `patternString Idris2ReallyBelieveMe = "really_believe_me"`) — these are - the prover's own *detector strings* for the pattern, not a use of it. - -Conclusion: the "zero believe_me" claims on the rows below are **TRUE**. -The 21-figure is a naive-grep false positive (prose + the detector's own -pattern table), NOT 21 proof escapes. No proof row needed a truthfulness -correction on this axis. (`src/abi/echidnaabi.ipkg:14` likewise contains -the phrase "zero believe_me" in its `brief` field — also prose, also true.) - -## Current state (Updated 2026-05-18) - -### Completed proofs - -| Proof | File | Covers | Prover | -|-------|------|--------|--------| -| E2 Axiom tracking completeness | `verification/proofs/idris2/AxiomCompleteness.idr` | 23 dangerous patterns across 7 provers; no false negatives; classify covers all constructors | I2 | -| E3 Dispatch pipeline ordering | `verification/proofs/idris2/DispatchOrdering.idr` | 6 stages (Integrity→Sandbox→Verify→Certs→Axioms→Confidence) strictly ordered | I2 | -| E4 Trust level soundness | `verification/proofs/lean4/ConfidenceLattice.lean` (L4) + `verification/proofs/idris2/TrustLevelSoundness.idr` (I2 NEW 2026-04-11) | Reject axiom → trust ≤ TrustLevel1; SoundnessWitness type makes unsound assignments a compile error | L4 + I2 — **the I2 half (`TrustLevelSoundness.idr`) is the constructive proof and stands. The L4 half is NOT verified: `lake build` 2026-05-18 shows `ConfidenceLattice.lean` (386 LoC) FAILS with 49 errors, the bulk caused by `unfold_let` (30 uses) being an `unknown tactic` in Lean 4.13.0 (`unfold_let` was removed). Mechanical token-swap to `simp only [instLE]` or `unfold instLE` was tested and makes it WORSE (104 errors — the follow-on `simp [LE.le, le]` then fails with a nested error), so the fix is NOT mechanical and was not applied. ConfidenceLattice.lean left untouched.** | -| E5 Prover dispatch compatibility | `verification/proofs/idris2/DispatchCorrectness.idr` | Logic family compatibility; linear logic ↛ first-order ATP | I2 | -| E6 ProverKind discriminant injectivity | `verification/proofs/idris2/ProverKindInjectivity.idr` | 105 variants, no collisions in kind_to_u8 | I2 | -| E7 GNN embedding faithfulness | `src/abi/EchidnaABI/Gnn.idr` | Structural properties, feature bounds, score normalisation | I2 | -| E9 Proof composition soundness | `proofs/agda/ProofComposition.agda` | Soundness preservation, axiom conflict detection | Agda | -| E12 ProofState serialization losslessness | `verification/proofs/idris2/ProofStateSerialisation.idr` | Term/Goal/ProofState round-trip; encode injective; SExpr wire model; zero believe_me | I2 | -| VCL-UT query safety | `src/abi/EchidnaABI/VqlUt.idr` | L5 injection-free, L3 type-safe boundary | I2 | -| Extensive ABI | `src/abi/EchidnaABI/Types.idr`, `Foreign.idr`, `Layout.idr` | All ABI types, no believe_me | I2 | -| Stage 8a Trust-Kernel Monotonicity | `verification/proofs/idris2/TrustKernelMonotonicity.idr` | Reject/Warning danger → Level1; bad integrity → Level1; confirming≥2 + cert + small_kernel → ≥Level4; zero believe_me | I2 | -| Stage 8a Axiom-Policy Ordering | `verification/proofs/idris2/AxiomPolicyOrdering.idr` | worstDanger equalities for all 4 AxiomPolicy variants; isAcceptable ↔ danger≠Reject; PolicyLE monotone; zero believe_me | I2 | -| Stage 8a Clamp Trust Bounds | `verification/proofs/idris2/ClampTrustBounds.idr` | clamp_trust lower/upper bounds (1≤val≤5); monotonicity; fixed points (1→L1, 5→L5, 10→L5); surjectivity; zero believe_me | I2 | - -### Remaining (not Idris2, not actionable by Claude) - -| # | What | Prover | Status | -|---|------|--------|--------| -| E1 | Confidence scoring lattice (TrustLevel forms valid partial order) | L4 | Covered by ConfidenceLattice.lean | -| E8 | VQL-UT query safety (SEC, deeper layer) | I2 | Partially covered by VqlUt.idr | -| E10 | Pareto frontier maximality | L4 | **`lake build` RUN 2026-05-18 (Lean 4.13.0, ~/.elan/bin) — FAILS.** `ParetoMaximality.lean` (465 LoC): 2 errors — `push_neg` at line 250 is `unknown tactic` (it is a **Mathlib** tactic; the lakefile declares "No mathlib dependency", so it is genuinely unavailable), causing an unsolved goal at 248. `ParetoStrongMaximality.lean` (207 LoC): 1 error — `unknown module prefix 'ParetoMaximality'` at line 28 (the cross-module `import`/`open` does not resolve under the current lakefile root setup; the 2026-05-11 "import path fix applied" note is NOT effective as built). NOT a mechanical fixup: E10 requires either adding a Mathlib dep (contradicts zero-mathlib policy) or hand-reproving the negation push in core Lean, plus fixing the inter-file module resolution. Tracking ticket: ECHIDNA-PARETO-DESCENT (math); #53 (tactic fixups). | -| E11 | SHAKE3-512/BLAKE3 integrity | L4 | **`lake build` RUN 2026-05-18 — FAILS.** `IntegrityVerification.lean` (384 LoC): 5 errors — `failed to synthesize` at lines 86 & 94 (missing instance — `integrityToBool`/`Decidable` plumbing; the planned `decide (s = IntegrityStatus.verified)` rewrite was either not applied or insufficient), and 3 `rewrite failed, did not find instance of the pattern` at lines 186/188/190 in the verifier soundness proof. Collision-resistance typeclasses (PI-7, PI-9) remain assumptions per zero-axiom policy. NOT an unambiguous mechanical fixup — the instance-synthesis failures require restructuring the decidability layer, not a one-token swap. NB: hash naming — implementation is SHAKE-256 squeezing 512 bits. | -| E13 | Portfolio cross-checking completeness | L4 | **`lake build` RUN 2026-05-18 — FAILS.** `PortfolioCompleteness.lean` (500 LoC): 31 errors. `push_neg` at line 344 is `unknown tactic` (Mathlib, unavailable — same root cause as E10); `not_not` at line 480 is `unknown identifier` (Mathlib lemma); plus ~12 `rewrite failed`/`rfl failed`/`unsolved goals` cascading from those. PR-14's `List.filter_eq_nil_iff` (line 478) and PR-10's `Option.some_injective` (line 379) resolve under core Lean 4.13.0 but their surrounding proofs still fail. NOT a mechanical fixup — needs the same Mathlib-vs-core decision as E10 plus genuine proof repair. | - -## Recommended prover -- **Idris2** for ABI-level properties and prover dispatch correctness -- **Lean4** for algebraic properties of the confidence lattice -- **Agda** for metatheoretic properties of proof composition - -## Priority -- **MEDIUM** (was HIGH) — Core trust pipeline proofs that are *Idris2/Agda* - (E2, E3, E5, E6, E7, E9, E12, the Stage-8a trio, VqlUt, the I2 half of E4) - are constructive and stand. The **Lean4 layer (E4-L4, E10, E11, E13) is - unverified**: `lake build` was run 2026-05-18 with Lean 4.13.0 - (`~/.elan/bin`) and **all 5 Lean files fail to compile** (the Lean - toolchain itself downloaded and built fine; these are real proof/source - errors, not environment issues). Aggregate: ConfidenceLattice 49, - ParetoMaximality 2, ParetoStrongMaximality 1, IntegrityVerification 5, - PortfolioCompleteness 31. **Three independent root causes, none a safe - one-token fix**: (1) `unfold_let` removed in Lean 4.13.0 (ConfidenceLattice, - ×30 — token-swap tested, makes it worse); (2) Mathlib tactics/lemmas - (`push_neg`, `not_not`) used while the lakefile declares zero-mathlib - (E10, E13) — needs a Mathlib-vs-core policy decision; (3) instance - synthesis / module-resolution failures (E11, ParetoStrongMaximality). - The #53 / 2026-05-11 "expected to compile cleanly" and "mechanical fixup" - notes were optimistic and are now corrected above. **No Lean source was - modified** (one token-swap was tested on a copy and reverted; files are - byte-identical to pre-audit). E10-E13 remain P2 and do not block the - critical path, but #53 is materially larger than "API fixups". - -## Echo-types audit (2026-06-01) - -Per the estate-wide standing directive: every proof in any sibling repo -with an echo-types link must first audit `hyperpolymath/echo-types`, -reuse if applicable, extend upstream WITH proofs if not, then -cross-document. L3 (echo) obligations are load-bearing; L1/L4-only -obligations audit-and-record-as-not-relevant. - -Echo-types layer scheme: **L1** regions / **L2** modality / **L3** echo -(structured residue / fibre shape) / **L4** dyadic (orders, products, -predicates, exhaustivity, monotonicity). - -### Surface audited - -All proof files under `proofs/agda/`, `proofs/coq/`, `proofs/isabelle/`, -`proofs/lean/`, `verification/proofs/idris2/`, -`verification/proofs/lean4/`, and `meta-checker/src/Echidna/`. The -Idris2 ABI under `src/abi/` is owner-intentional and out of scope (per -estate memo `echidna_src_abi_namespace_intentional`). Per-prover -fixture files under `tests/` are out of scope (smoke fixtures, not -obligations). - -### Classification summary (26 obligation-bearing modules) - -| Layer | Count | Status | -|-------|-------|--------| -| L1 (regions) | 0 | n/a — echidna is not a typed-substrate project | -| L2 (modality) | 0 | n/a — no modal logic surface in the verifier | -| **L3 (echo)** | **2** | **cross-ref added below** | -| L4 (dyadic) | 24 | audit-and-not-relevant; recorded here | - -### L3 obligations (cross-reference to echo-types) - -Two existing echidna theorems land in the echo-types EQUIV / INJ -shapes from `proofs/agda/EchoLossTaxonomy.agda`. The directive's -"reuse if applicable" path is satisfied by **cross-reference** rather -than rewrite — both theorems already discharge their content directly -under the relevant prover (Idris2), and the echo-types lemmas are -stated in Agda over abstract `f : A → B`, so the reuse is at the -**conceptual / classification** layer, not the proof-term layer. - -| Echidna theorem | Echo-types analogue | Relationship | -|-----------------|---------------------|--------------| -| `Serialisation.roundtrip : (x : a) → decode (encode x) = Just x` (`verification/proofs/idris2/ProofStateSerialisation.idr:88`, E12) | `HasInverse` + `equiv-fibre-center` + `equiv-implies-injective` in `proofs/agda/EchoLossTaxonomy.agda` (EQUIV case); `EchoTotalCompletion` for the Σ-packaging | The roundtrip witness IS the EQUIV-shape data instantiated at the wire-encoding map. Losslessness ≡ trivial fibre at every wire value in the encode image. Echidna's proof is concrete-prover (Idris2 over wire `SExpr`); echo-types' is abstract (Agda, K-free). Same content, different stratum. | -| `kind_to_u8_injective` (`verification/proofs/idris2/ProverKindInjectivity.idr`, E6) | `inj-fibre-proj-unique` (INJ case re-export from `EchoImageFactorization` in `proofs/agda/EchoLossTaxonomy.agda`) | Injectivity of the discriminant map IS the INJ-case projection-uniqueness statement at the concrete domain `ProverKind` (105 variants) → `Nat`. Echidna does the concrete case split (no `believe_me`); echo-types names + classifies the shape. | - -**Upstream extension status: not required.** Echo-types already -mechanises both the EQUIV (`HasInverse`) and INJ -(`inj-fibre-proj-unique`) cases in `EchoLossTaxonomy.agda`. The -echidna theorems are downstream *applications* of these classified -shapes, not new content owed back to the upstream library. - -### L4 obligations (audit-and-not-relevant, recorded) - -Every other obligation listed in **Completed proofs** above is L4: -order-theoretic (TrustLattice, DispatchOrdering, ClampTrustBounds, -ConfidenceLattice, ParetoMaximality, ParetoStrongMaximality), -monotonicity (AxiomMonotonicity, TrustKernelMonotonicity, AxiomPolicyOrdering), -exhaustivity / case-coverage (AxiomCompleteness, -AxiomTrackerCompleteness, AxiomSafety, MetaChecker), aggregation -(PortfolioConsistency, ParallelSoundness, Portfolio, -PortfolioCompleteness), composition / closure (ProofComposition, -SoundnessPreservation, CertificateChain, Dispatch), totality (BasicTotality, -IdentityLaws, TrustLevelSoundness, TrustLevel), or hash-integrity -algebra (IntegrityVerification). None involves loss-with-residue, -fibre structure, image factorisation, or any other echo-typed -construct, so the directive's L4 branch — "audit-and-record-as-not- -relevant" — is discharged by this paragraph. - -### Cross-doc echo - -* Echidna → echo-types: this section. -* Echo-types → echidna: `docs/echo-types/echidna-design-search-2026-04-28.adoc` - already cross-references echidna (as a *tool* used over the - echo-types corpus). No reverse proof-relevance link is owed back - from echo-types because echidna does not add classified-shape - content (the EQUIV/INJ cases echidna instantiates are already - upstream). - -### Related obligation (echidna#117) - -`echidna#117` (`Client.res` AffineScript-TEA port — missing -`Http.fetch` / `Promise` / `Json` / `Dict` primitives) is a stdlib- -primitives meta-issue. Its blocker set is purely **L4 representation -/ transport** (encoding shapes for Http / Promise / JSON / Dict). It -carries no L3 obligation (no claim about fibre structure of the wire -transport), so audit-and-not-relevant applies. Recorded here so a -future port reviewer does not need to re-audit. diff --git a/docs/PROVER_COUNT.adoc b/docs/PROVER_COUNT.adoc new file mode 100644 index 00000000..bb8c58e5 --- /dev/null +++ b/docs/PROVER_COUNT.adoc @@ -0,0 +1,202 @@ +== Canonical Prover Count and Tier Table + +*Status*: canonical. Cite this file when documenting backend coverage in +any other doc. Every number below was re-measured against the tree — see +link:#verifying-locally[Verifying locally] for the exact commands, which +are the definition of each figure rather than a description of it. + +____ +*Read this first — the counts differ because they count different +things.* There is no single "`number of provers`". The two figures most +often confused: *141* is the number of `+ProverKind+` _enum variants_; +*105* is the number of _backend implementation files_ in +`+src/rust/provers/+`. Both are correct. A surface quoting one of them +as "`the`" count without saying which is drift — that is why historical +counts (12, 30, 48, 74, 105, 128) are scattered across older documents. +Prefer citing this file to quoting any number. +____ + +=== TL;DR + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Question |Answer |Command +|Total `+ProverKind+` variants in `+src/rust/provers/mod.rs+` |*141* +|`+V+` below + +|Backend implementation files in `+src/rust/provers/+` |*105* |`+F+` +below + +|Implementations providing `+suggest_tactics+` |*102* |`+S+` below + +|Exposed by default REST API (`+Tier 1+` / core) |*12* +(`+GET /api/provers+`) |`+C+` below + +|Variants carrying a type-checker / discipline role |*46* |`+D+` below + +|Routing tactic suggestions through `+gnn_augment_tactics+` |*all +backends with `+suggest_tactics+`* — gracefully no-ops when +`+gnn_api_url+` is None or `+neural_enabled+` is false |— + +|Trust pipeline integrity-hashed |All Tier 1; Tier 2 incrementally |— +|=== + +=== Tier table + +Tiers correspond to CI coverage cadence and default-API visibility. + +____ +*Membership counts in this table are not machine-checked.* Tier 1 +mirrors `+ProverKind::all_core()+` and is verified by command `+C+`. +Tier 9 is verified by command `+D+`. The remaining per-tier figures +(Tier 4’s placeholder count, Tier 8’s corpus-only count) are +hand-maintained and have not been re-measured — treat them as +indicative. Making tier membership derivable from the code (an attribute +on each variant) is tracked as documentation debt in +link:DEBT.md[`+docs/DEBT.md+`]. +____ + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Tier |Cadence |Members |Notes +|*1 — core* |Every PR |Agda, Coq, Lean 4, Isabelle/HOL, Z3, CVC5, +Metamath, HOL Light, Mizar, PVS, ACL2, HOL4 |Returned by +`+ProverKind::all_core()+`; exposed by default at `+GET /api/provers+`; +required to pass for green CI. Install hints in +link:SUPPORTED_PROVERS.md[`+SUPPORTED_PROVERS.md+`]. + +|*2 — extended* |Every PR (allow-fail) |Idris 2, Lean 3, Vampire, E +Prover, SPASS, Alt-Ergo, F*, Dafny, Why3, TLAPS, Twelf, Nuprl, Minlog, +Imandra, Princess, IProver, Twee, MetiTarski, CSI, AProVE, Leo-III, +Satallax, Lash, AgsyHOL, GLPK, SCIP, MiniZinc, Chuffed, OR-Tools, Dreal, +CBMC, KeY, KeYmaera X, EasyCrypt, Abella, Athena, Cameleer |Direct +invocation via `+ProverKind+` (covered by `+ProverKind::all()+` beyond +`+all_core()+`). CI runs but doesn’t block. List is illustrative; the +live set is whatever `+ProverKind::all()+` returns. + +|*3 — niche* |Nightly |Arend, Cedille, Lego, Aprové, Boogie, CVC4, +Petri-net checkers, modal-logic provers, real-algebraic provers +|Specialised use. + +|*4 — placeholder* |Smoke only |19 backends present as `+ProverKind+` +variants but with mock-only invocation. |Promote when upstream +maintainer ships a Containerfile. See +link:handover/TODO.md[`+handover/TODO.md+`] P4. + +|*5 — Wave-3 secured* |Every PR |Tamarin, ProVerif, Metamath +(rust-native), Twelf, OR-Tools |All ✅ real, runtime-smoke verified, +Containerfile.wave3 + +|*6 — pure-Rust* |Every PR |Metamath (own crate) |No external binary; +in-process. + +|*7 — Wave-2 modal/real-algebraic* |Every PR |Modal, real-algebraic +provers (Phase 3 implementations) |See +link:handover/PHASE-3-PROMPT.md[`+handover/PHASE-3-PROMPT.md+`] + +|*8 — HP type-checker ecosystem* |Nightly |13 corpus-only provers +(Ephapax / Wokelang / AffineScript backends) |Adapters pending; tracked +in handover/TODO P4 + +|*9 — TypeChecker disciplines* |Every PR |46 variants carry a +type-checker / discipline role (Hindley-Milner, System F, Rank-N, +ATS-style affine, …) — command `+D+` |Routed via `+crates/typed_wasm+` +Sigma parameters; do not require an external binary. + +|*10 — Coq-Jr ecosystem (playground)* |Sub-project CI +|`+echidna-playground/+` backends |Separate sub-project; tracked there. +|=== + +=== Why so many counts in the wild? + +Two independent causes, and they need different remedies. + +*Cause 1 — genuine growth over time.* Each milestone’s documents quote +the count current to their authoring date: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Release |Declared |What changed +|v1.0 (Dec 2025) |12 |MVP scope: 12 real backends + +|v1.2 (Jan 2026) |30 |12 fully tested + +|v1.3 (Feb 2026) |*48* |~32 with real `+suggest_tactics+` + +|v2.0 (Apr 2026) |74 |Wave-1 + Wave-2 absorption + +|v2.1 (May 2026) |*105* |Wave-3 (Tamarin, ProVerif, Twelf, OR-Tools) + +|v2.2 (May 2026) |*128* |TypeChecker disciplines Sigma-routed through +TypedWasm + +|current `+main+` |*141* |measured, this file +|=== + +Historical snapshots under `+docs/releases/+`, `+docs/handover/+` and +`+docs/decisions/+` are _deliberately_ left at their authoring-time +numbers — they are records, not claims about today. + +*Cause 2 — counting different things and calling both "`provers`".* This +is the harmful one, because both numbers are defensible in isolation. +141 counts enum variants; 105 counts implementation files; 102 counts +implementations exposing `+suggest_tactics+`; 12 counts the +default-exposed core. A document that says "`N prover backends`" without +naming the denominator will be read as a claim about all four. + +*Remedy:* cite this file rather than a number. The `+R5a+` +canonical-reference CI rule +(`+.github/canonical-references/prover-counts.yml+`, enforced by the +`+Canonical-reference drift (R5 generic)+` step in the shared +`+governance-reusable.yml+`) fails the build when a bare count appears +in a load-bearing top-level document. Note its scope is the top-level +document set listed in that file — `+docs/+`, `+.machine_readable/+` and +`+crates/*/README.md+` are *not* covered, which is where the surviving +drift accumulated. + +=== Verifying locally + +Each command is the definition of its figure. Run from the repository +root. + +[source,bash] +---- +# V — total ProverKind variants (141) +awk '/pub enum ProverKind/{f=1;next} f&&/^\}/{exit} f' src/rust/provers/mod.rs \ + | grep -cE '^\s*[A-Z][A-Za-z0-9_]*\s*,' + +# F — backend implementation files (105) +ls src/rust/provers/*.rs | grep -cv 'mod\.rs$' + +# S — implementations providing suggest_tactics (102) +git grep -l 'fn suggest_tactics' -- 'src/rust/provers/*.rs' | wc -l + +# C — Tier-1 core, exposed by default at GET /api/provers (12) +awk '/fn all_core/{f=1} f&&/\]/{print;exit} f' src/rust/provers/mod.rs \ + | grep -oE 'ProverKind::[A-Za-z0-9_]+' | wc -l + +# D — variants carrying a type-checker / discipline role (46) +awk '/pub enum ProverKind/{f=1;next} f&&/^\}/{exit} f' src/rust/provers/mod.rs \ + | grep -icE 'typecheck|discipline' +---- + +`+ProverKind::all()+` in `+src/rust/provers/mod.rs+` is the machine +source of truth; this document is its human-readable mirror. If a count +changes, update this file *and* `+.machine_readable/provers.a2ml+` in +the same PR. + +=== When to cite this file + +Cite `+docs/PROVER_COUNT.md+` (not a number) in: - the `+README.md+` +tagline and the repository description - `+CLAUDE.md+` project overview +- any new design doc - PR descriptions referring to "`all backends`" - +issue templates + +When a number genuinely must appear (a release note, a benchmark table), +name the denominator: "`141 `+ProverKind+` variants`", not "`141 +provers`". + +If a count changes (new wave absorbed, backend retired), update this +file in the same PR. The single source of truth for the count is +`+ProverKind::all()+` in `+src/rust/provers/mod.rs+`; this doc is the +human-readable mirror. diff --git a/docs/PROVER_COUNT.md b/docs/PROVER_COUNT.md deleted file mode 100644 index 7dbf6cd4..00000000 --- a/docs/PROVER_COUNT.md +++ /dev/null @@ -1,134 +0,0 @@ - - - -# Canonical Prover Count and Tier Table - -**Status**: canonical. Cite this file when documenting backend coverage in any -other doc. Every number below was re-measured against the tree — see -[Verifying locally](#verifying-locally) for the exact commands, which are the -definition of each figure rather than a description of it. - -> **Read this first — the counts differ because they count different things.** -> There is no single "number of provers". The two figures most often confused: -> **141** is the number of `ProverKind` *enum variants*; **105** is the number -> of *backend implementation files* in `src/rust/provers/`. Both are correct. -> A surface quoting one of them as "the" count without saying which is drift — -> that is why historical counts (12, 30, 48, 74, 105, 128) are scattered across -> older documents. Prefer citing this file to quoting any number. - -## TL;DR - -| Question | Answer | Command | -|---|---|---| -| Total `ProverKind` variants in `src/rust/provers/mod.rs` | **141** | `V` below | -| Backend implementation files in `src/rust/provers/` | **105** | `F` below | -| Implementations providing `suggest_tactics` | **102** | `S` below | -| Exposed by default REST API (`Tier 1` / core) | **12** (`GET /api/provers`) | `C` below | -| Variants carrying a type-checker / discipline role | **46** | `D` below | -| Routing tactic suggestions through `gnn_augment_tactics` | **all backends with `suggest_tactics`** — gracefully no-ops when `gnn_api_url` is None or `neural_enabled` is false | — | -| Trust pipeline integrity-hashed | All Tier 1; Tier 2 incrementally | — | - -## Tier table - -Tiers correspond to CI coverage cadence and default-API visibility. - -> **Membership counts in this table are not machine-checked.** Tier 1 mirrors -> `ProverKind::all_core()` and is verified by command `C`. Tier 9 is verified by -> command `D`. The remaining per-tier figures (Tier 4's placeholder count, -> Tier 8's corpus-only count) are hand-maintained and have not been -> re-measured — treat them as indicative. Making tier membership derivable -> from the code (an attribute on each variant) is tracked as documentation -> debt in [`docs/DEBT.md`](DEBT.md). - -| Tier | Cadence | Members | Notes | -|---|---|---|---| -| **1 — core** | Every PR | Agda, Coq, Lean 4, Isabelle/HOL, Z3, CVC5, Metamath, HOL Light, Mizar, PVS, ACL2, HOL4 | Returned by `ProverKind::all_core()`; exposed by default at `GET /api/provers`; required to pass for green CI. Install hints in [`SUPPORTED_PROVERS.md`](SUPPORTED_PROVERS.md). | -| **2 — extended** | Every PR (allow-fail) | Idris 2, Lean 3, Vampire, E Prover, SPASS, Alt-Ergo, F*, Dafny, Why3, TLAPS, Twelf, Nuprl, Minlog, Imandra, Princess, IProver, Twee, MetiTarski, CSI, AProVE, Leo-III, Satallax, Lash, AgsyHOL, GLPK, SCIP, MiniZinc, Chuffed, OR-Tools, Dreal, CBMC, KeY, KeYmaera X, EasyCrypt, Abella, Athena, Cameleer | Direct invocation via `ProverKind` (covered by `ProverKind::all()` beyond `all_core()`). CI runs but doesn't block. List is illustrative; the live set is whatever `ProverKind::all()` returns. | -| **3 — niche** | Nightly | Arend, Cedille, Lego, Aprové, Boogie, CVC4, Petri-net checkers, modal-logic provers, real-algebraic provers | Specialised use. | -| **4 — placeholder** | Smoke only | 19 backends present as `ProverKind` variants but with mock-only invocation. | Promote when upstream maintainer ships a Containerfile. See [`handover/TODO.md`](handover/TODO.md) P4. | -| **5 — Wave-3 secured** | Every PR | Tamarin, ProVerif, Metamath (rust-native), Twelf, OR-Tools | All ✅ real, runtime-smoke verified, Containerfile.wave3 | -| **6 — pure-Rust** | Every PR | Metamath (own crate) | No external binary; in-process. | -| **7 — Wave-2 modal/real-algebraic** | Every PR | Modal, real-algebraic provers (Phase 3 implementations) | See [`handover/PHASE-3-PROMPT.md`](handover/PHASE-3-PROMPT.md) | -| **8 — HP type-checker ecosystem** | Nightly | 13 corpus-only provers (Ephapax / Wokelang / AffineScript backends) | Adapters pending; tracked in handover/TODO P4 | -| **9 — TypeChecker disciplines** | Every PR | 46 variants carry a type-checker / discipline role (Hindley-Milner, System F, Rank-N, ATS-style affine, …) — command `D` | Routed via `crates/typed_wasm` Sigma parameters; do not require an external binary. | -| **10 — Coq-Jr ecosystem (playground)** | Sub-project CI | `echidna-playground/` backends | Separate sub-project; tracked there. | - -## Why so many counts in the wild? - -Two independent causes, and they need different remedies. - -**Cause 1 — genuine growth over time.** Each milestone's documents quote the -count current to their authoring date: - -| Release | Declared | What changed | -|---|---|---| -| v1.0 (Dec 2025) | 12 | MVP scope: 12 real backends | -| v1.2 (Jan 2026) | 30 | 12 fully tested | -| v1.3 (Feb 2026) | **48** | ~32 with real `suggest_tactics` | -| v2.0 (Apr 2026) | 74 | Wave-1 + Wave-2 absorption | -| v2.1 (May 2026) | **105** | Wave-3 (Tamarin, ProVerif, Twelf, OR-Tools) | -| v2.2 (May 2026) | **128** | TypeChecker disciplines Sigma-routed through TypedWasm | -| current `main` | **141** | measured, this file | - -Historical snapshots under `docs/releases/`, `docs/handover/` and -`docs/decisions/` are *deliberately* left at their authoring-time numbers — -they are records, not claims about today. - -**Cause 2 — counting different things and calling both "provers".** This is -the harmful one, because both numbers are defensible in isolation. 141 counts -enum variants; 105 counts implementation files; 102 counts implementations -exposing `suggest_tactics`; 12 counts the default-exposed core. A document that -says "N prover backends" without naming the denominator will be read as a claim -about all four. - -**Remedy:** cite this file rather than a number. The `R5a` canonical-reference -CI rule (`.github/canonical-references/prover-counts.yml`, enforced by the -`Canonical-reference drift (R5 generic)` step in the shared -`governance-reusable.yml`) fails the build when a bare count appears in a -load-bearing top-level document. Note its scope is the top-level document set -listed in that file — `docs/`, `.machine_readable/` and `crates/*/README.md` -are **not** covered, which is where the surviving drift accumulated. - -## Verifying locally - -Each command is the definition of its figure. Run from the repository root. - -```bash -# V — total ProverKind variants (141) -awk '/pub enum ProverKind/{f=1;next} f&&/^\}/{exit} f' src/rust/provers/mod.rs \ - | grep -cE '^\s*[A-Z][A-Za-z0-9_]*\s*,' - -# F — backend implementation files (105) -ls src/rust/provers/*.rs | grep -cv 'mod\.rs$' - -# S — implementations providing suggest_tactics (102) -git grep -l 'fn suggest_tactics' -- 'src/rust/provers/*.rs' | wc -l - -# C — Tier-1 core, exposed by default at GET /api/provers (12) -awk '/fn all_core/{f=1} f&&/\]/{print;exit} f' src/rust/provers/mod.rs \ - | grep -oE 'ProverKind::[A-Za-z0-9_]+' | wc -l - -# D — variants carrying a type-checker / discipline role (46) -awk '/pub enum ProverKind/{f=1;next} f&&/^\}/{exit} f' src/rust/provers/mod.rs \ - | grep -icE 'typecheck|discipline' -``` - -`ProverKind::all()` in `src/rust/provers/mod.rs` is the machine source of -truth; this document is its human-readable mirror. If a count changes, update -this file **and** `.machine_readable/provers.a2ml` in the same PR. - -## When to cite this file - -Cite `docs/PROVER_COUNT.md` (not a number) in: -- the `README.md` tagline and the repository description -- `CLAUDE.md` project overview -- any new design doc -- PR descriptions referring to "all backends" -- issue templates - -When a number genuinely must appear (a release note, a benchmark table), name -the denominator: "141 `ProverKind` variants", not "141 provers". - -If a count changes (new wave absorbed, backend retired), update this file -in the same PR. The single source of truth for the count is `ProverKind::all()` -in `src/rust/provers/mod.rs`; this doc is the human-readable mirror. diff --git a/docs/ROADMAP.adoc b/docs/ROADMAP.adoc new file mode 100644 index 00000000..c19972ed --- /dev/null +++ b/docs/ROADMAP.adoc @@ -0,0 +1,340 @@ +== ECHIDNA Roadmap + +*Status*: canonical • supersedes the aspirational parts of +`+FUTURE_DEVELOPMENT_ROADMAP.md+` (removed from the tree; see git +history). *Last revised*: 2026‑06‑01 (doc-coherence pass; previous +revisions 2026‑05‑30 truthfulness audit, 2026‑04‑20) *Scope*: the +shortest honest path from today’s repo to the endpoint vision. + +*Governance status post‑2026‑06‑01*: the R5 doc-canonical-reference +guardrail landed in two halves — R5a (prover-count drift, echidna‑local +at `+.github/canonical-references/+` after PR #174 migration) and R5b +(estate‑wide `+Version: x.y.z+` drift, in the standards reusable, +consumed via PR #172). MVP smoke (#167) and the pareto/bare-build +governance harness are green on `+main+`. The dogfood proof corpus +(`+proofs/{coq,lean,agda}+` + `+src/idris+`) is now CI-gated by +`+dogfood-proofs-ci.yml+` (Coq/Lean/Agda) and `+idris2-abi-ci.yml+` (the +`+src/idris+` validator), each driven by a `+just proofs-*+` recipe — +closing a gap where the corpus had no CI and a green PR proved nothing +about the proofs (PR #234). None of these change the stage map below; +they are infrastructure around the work, not on the critical path. + +This document is the single source of truth for where ECHIDNA is going. +The domain‑specific plans under link:./handover/[`+handover/+`] and +link:./design/SPARK_ADOPTION_PLAN.md[`+design/SPARK_ADOPTION_PLAN.md+`] +are still authoritative for their sub‑areas; they fit _inside_ this +roadmap as implementations of individual stages. + +=== 1. Endpoint + +ECHIDNA, when complete, is the *reasoning substrate of the hyperpolymath +ecosystem* — not just a proof tool. It is: + +* a unified interface to every mature theorem prover, SMT solver, model +checker, and type checker in public use; +* an ML layer (GNN + Transformer over Flux.jl) that actually learns +premise selection, tactic synthesis, and strategy routing well enough to +beat hand‑curated choices on held‑out theorems; +* a persistent E‑R layer (Verisim) that stores every proof, tactic +application, and version as a content‑addressed row and closes a real +learning loop over historical outcomes; +* a parallel dispatch layer (Chapel) that runs portfolio solves across +CPU cores and dispatches specialised work to coprocessors (GPU / tensor +/ vector / FPGA / QPU); +* a high‑speed IPC fabric (Cap’n Proto) between the Rust core and the +Julia ML sidecar and between the backend and the frontend; +* a frontend in AffineScript + Deno (TEA architecture) with i18n via the +LOL locale repo; +* a 16‑endpoint Zig ABI that external consumers (Coursera labs, other +projects) link against, with an SPDX‑pinned, Guix‑built, +Chainguard‑based container managed by Stapeln and hardened by the Vordr +/ Selur / Svalinn / Cerro‑Torre surround; +* itself formally verified — the trust kernel’s critical invariants are +proved in SPARK and in Idris2 / Agda. + +From a user’s seat: *indistinguishable from magic for easy obligations, +honest about ambiguity for hard ones, never silently wrong.* + +=== 2. Stage map + +.... +Stage 1 Train the model at all ML layer can receive signal + 1a extractors emit premises [done 2026‑04‑20, 22 of 50 ✓] + 1b align_premises joins correctly [done 2026‑04‑19 ✓] + 1c residual extractor gaps fixed [done 2026‑04‑26 ✓ — 50/50 named extractors; + see handover/TODO.md S1 batches] + 1d vocab covers the surface [255 K; target ~1 M] + +Stage 2 Signal becomes useful MRR moves off 0.66 baseline + 2a run training at scale hardware task + 2b online vocab growth new feature + 2c re‑baseline and publish metrics run gate + +Stage 3 Learning loop closes model improves from outcomes + 3a Verisim read paths cross‑prover queries by goal_hash + 3b hypatia strategy loop wired `mv_prover_success_by_class` reads + 3c Proof / TacticApplication / ProofVersion emission wired + [defined 2026‑04‑19 ✓, emission pending] + +Stage 4 Interaction layer honest every declared ProverKind works + 4a typed_wasm → crates/typed_wasm [done 2026‑04‑22 ✓] + 4b 39 TypeChecker variant dispatch [done 2026‑04‑22 ✓, all Sigma‑routed] + 4c tactic synthesis template [91/91 real impl ✓; GNN-ranking surface + COMPLETE 2026‑05‑30 — every backend with + suggest_tactics now routes through + gnn_augment_tactics (S5 pilot + Tier-1 + ext + Tier-1 finisher + Tier-2 sweep + + Tier-3/niche sweep). Helper no-ops when + Julia /gnn/rank is unreachable. End-state + target met; remaining S2 dependency is + real trained weights at models/neural/] + 4d search_theorems template [done 2026‑04‑27 ✓ — cross-prover layer + added at dispatcher (CLI/REST/REPL all + call `vcl_ut::cross_prover_search_names`). + The 72 backend `Ok(vec![])` returns are + correct: they report "no native search + command" — cross-prover semantics live + one layer up where Verisim covers all + provers in one query.] + +Stage 5 Distributed & fast scale + specialised hardware + 5a Cap'n Proto IPC Rust ↔ Julia, :8090 + 5b Chapel full integration dispatch.rs picks by config + 5c coprocessor abstraction trait + tensor/vector/QPU/FPGA + 5d Tier‑4 live‑CI provisioning 19 backends, Containerfile path + +Stage 6 Cross‑prover semantics translation actually works + 6a OpenTheory bridge real bidirectional term translation + 6b Dedukti bridge real λΠ modulo as lingua franca + 6c mathematical identity arbitration canonicalise across representations + 6d Coursera delivery Zig ABI exposes capability + +Stage 7 Sovereign tooling surround the rest of the ecosystem + 7a Stapeln container lifecycle + 7b Vordr entry gate + 7c Selur scheduler + 7d Svalinn trust boundary + 7e Cerro‑Torre observability + 7f AffineScript‑TEA frontend src/affinescript/, ≥33 modules + 7g LOL i18n locale/ + t!() macro + 7h Zig ABI 16‑endpoint surface src/zig/echidna_abi.zig + +Stage 8 Self‑verified ECHIDNA proves ECHIDNA + 8a Idris2 meta‑proofs extend from 32 modules to full kernel + 8b Agda meta‑proofs extend from 12 modules + 8c SPARK‑verified trust kernel crates/echidna-core-spark/ + 8d panic‑attack hardened proptest + AFL++ nightly +.... + +=== 3. Endpoint target — row by row + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Claim |Today |End‑state target +|"`Every important solver`" |*128 ProverKind variants* (89 external +prover bindings + 39 TypeChecker disciplines routed through TypedWasm); +*91 / 91 with real `+suggest_tactics+`* (5 still heuristic-only; +GNN-ranked is the end-state target per `+docs/PROVER_COUNT.md+`); *72 +backends with empty native search but a cross-prover Verisim fallback at +the dispatcher layer (CLI/REST/REPL)* |*All variants with real +`+suggest_tactics+` (GNN‑ranked top‑k); per-backend search reflects each +prover’s native capability while cross-prover queries are served from +Verisim by `+goal_hash+`* + +|"`Vocab at 2.5 M`" |255 K |*~1 M canonical tokens* after Mathport + +Iris + VST + Flyspeck + HoTT absorption, with *online growth* adding +tokens during training + +|"`Chapel fully supported`" |*rewritten and CI-green 2026-05-30* — +`+src/chapel/+` compiles under chpl 2.3.0 / 2.8.0 (static lib, apt +Chapel ships `+CHPL_LIB_PIC=none+` only); L2.2 +`+parallelProofSearchSpeculative+` (first-success-wins atomic CAS) +shipped next to best-of `+parallelProofSearch+`; `+chapel-ci.yml+` +chapel-build + zig-ffi strict; aggregation invariants proved in +`+proofs/agda/ParallelSoundness.agda+` with zero +postulate/admit/believe_me. L2.3 cancel-token preemption next +|*`+dispatch.rs+` picks Chapel‑parallel dispatch by config*; runtime +init + cancellation + error propagation wired; ≥1 OoM speedup on +portfolio solves + +|"`Cap’n Proto serialisation`" |0 `+.capnp+` files +|*`+crates/echidna-wire/+`* contains schemas for ProofState / Goal / +Tactic / EmbeddingRequest / RankingResponse; IPC on :8090 is Cap’n +Proto; JSON retained only as debug fallback + +|"`Vordr / Selur / Svalinn / Cerro‑Torre / Stapeln`" |Not present |Each +named as a versioned dependency in Cargo.toml or the container +definition, wired into its role + +|"`AffineScript‑TEA frontend`" |Not present (10 `+.res+` files stub) +|*`+src/affinescript/+`* holds ≥33 AffineScript‑TEA modules, persistent +Model → Msg → Update loop, talks to core over Cap’n Proto WebSocket + +|"`LOL i18n`" |Not present |*`+locale/+`* with LOL‑sourced translations; +`+t!()+` macro for every user‑facing string + +|"`Rust/SPARK base stable`" |Rust only |*`+crates/echidna-core-spark/+`* +holds the Ada/SPARK‑verified kernel (axiom scanning, trust‑level +computation); proved free of runtime errors; called from Rust via C ABI + +|"`16‑endpoint Zig ABI`" |4 shared libs, endpoint count unverified +|*`+src/zig/echidna_abi.zig+`* exports exactly 16 functions +(`+echidna_prove+`, `+echidna_apply_tactic+`, `+echidna_rank_premises+`, +`+echidna_verify_certificate+`, `+echidna_post_octad+`, +`+echidna_query_identity+`, …) with a versioned header + +|"`100 K+ per prover`" |Uneven; long tail <20 K |*Top 15 provers ≥ 100 K +records each*; next 20 ≥ 25 K each; bottom 10 synthetically augmented to +≥ 10 K; `+stats_UNIFIED.json+` reports the distribution publicly + +|"`Panic‑attacked`" |No fuzz infra |*`+benches/panic_attack/+`* with +proptest + AFL++ harnesses covering every parser, FFI boundary, IPC +schema; nightly CI ≥ 1 h; zero known panic paths + +|"`Prover count`" |*128 declared, all 128 factory‑dispatched* (no +orphans, verified 2026‑04‑27) |*`+ProverKind+` ≥ 65 variants, every one +factory‑dispatched*; CLAUDE.md states the canonical count; no orphans — +*target met and exceeded* +|=== + +=== 4. Current sprint — "`the smallest set that flips half the table`" + +Five concrete commitments. Landed together inside ~6 weeks they move +"`Every important solver`", "`Vocab`", "`Prover count`", half of "`100 +K+`", and start the self‑learning loop closure. + +[width="100%",cols="20%,20%,20%,20%,20%",options="header",] +|=== +|# |Stage |Commitment |Agent tier |Status +|S1 |1c |Finish the extractor premise‑emission wave (22 done; 28 +remaining) |*Sonnet* |*done 2026‑04‑26 ✓* — 50/50 named extractors (3 +batches in `+handover/TODO.md+`: 12 + 20 + 6) + +|S2 |2a / 2c |Run training on the fixed corpus; record new MRR; commit +`+metrics_baseline.jsonl+` |*Hardware / you* |gated by S1 (S1 ✓; S2 +hardware step still to run) + +|S3 |4a / 4b |Extract `+typed_wasm+` to `+crates/typed_wasm/+`; route 39 +TypeChecker variants through Sigma parameters |*Opus‑design + +Sonnet‑impl* |*done 2026‑04‑22 ✓* + +|S4 |3a / 3b |Wire Verisim cross‑prover read paths (`+goal_hash+` +queries + `+mv_prover_success_by_class+` + hypatia loop) |*Opus‑design + +Sonnet‑impl* |*wired 2026‑04‑27 ✓* — read paths +(`+query_prover_success_by_class+` via `+VeriSimAdvisor+`, +`+cross_prover_search_names+` via `+vcl_ut+`) + write path +(`+spawn_record_attempt+`) + end-to-end test +(`+tests/s4_loop_closure.rs+`, `+just test-s4-loop+`); CI workflow +filing gated on `+ghcr-publish.yml+` in `+verisimdb+` upstream (runbook +holds the YAML) + +|S5 |4c / 4d (pilot) |Tactic synthesis template for 5 high‑value provers +(coq, lean, agda, isabelle, z3) using the GNN |*Opus‑design + +Sonnet‑impl* |*done 2026‑05‑30 ✓* — `+suggest_tactics+` is 91/91 real; +`+gnn_augment_tactics+` wired into ALL backends with `+suggest_tactics+` +(S5 pilot 5 in c8a4f25, Tier-1 extension 5 in #135, Tier-1 finisher 2 + +Tier-2 sweep 33 in #136, Tier-3/niche sweep 53 in this PR). Wiring is a +no-op when Julia /gnn/rank is unreachable; once S2 trained weights land +at `+models/neural/+`, every backend automatically returns model-derived +premise-apply tactics +|=== + +After S1–S5 land, the roadmap’s next sprint takes up Stage 5 (IPC + +Chapel + Tier‑4 CI) and Stage 8 begins in parallel. + +==== Sprint critical path (as of 2026‑04‑27) + +.... +S1 (extractors, Sonnet) ──┬──► S2 (training, hardware) ──┐ + │ │ + └──► S4 impl (needs S1 data) ────┴──► S5 GNN ranking + ▲ + │ blocked + Verisim schema design ◄── NEEDED FROM OPUS, + (cross‑repo, not in CROSS‑REPO INPUT. + echidna tree) +.... + +What is *not* blocking and can move now: + +* *Phase 1a* (Leo3, Satallax, Lash, AgsyHOL) — done 2026‑04‑26 ✓ +* *Phase 1b* (IProver, Princess, Twee, MetiTarski, CSI, AProVE) — done ✓ +* *S3* (typed_wasm + 39 TypeChecker Sigma routing) — done ✓ +* *`+suggest_tactics+`* — 91/91 real implementations ✓; every backend +now routes through `+gnn_augment_tactics+` (no-op until S2 weights land +at `+models/neural/+`) + +What *is* blocking and needs Opus + cross‑repo input: + +* *Verisim schema contract* (S4 design): the trait surface from +echidna’s side is straightforward +(`+async fn search_by_goal_hash(hash) -> Vec+` and +`+async fn prover_success_by_class(class) -> Vec<(ProverKind, f32)>+`) +but the schema for `+ProofRecord+` and `+class+` lives in the Verisim +repo and must be agreed there before echidna can wire reads. *Status as +of 2026-04-27*: the Verisim schema is in fact fixed (`+ProofAttempt+` +row → ClickHouse `+proof_attempts+` → `+mv_prover_success_by_class+` MV) +and both echidna read paths (`+query_prover_success_by_class+` via +`+VeriSimAdvisor+`, `+cross_prover_search_names+` via `+vcl_ut+`) and +the write path (`+spawn_record_attempt+` from dispatch exits) are now +wired. +** End-to-end loop test: `+tests/s4_loop_closure.rs+`, runnable via +`+just test-s4-loop+`. Skips cleanly when verisim-api is unreachable. +** Operations runbook: +link:handover/S4-LOOP-CLOSURE-RUNBOOK.md[`+docs/handover/S4-LOOP-CLOSURE-RUNBOOK.md+`]. +** CI workflow filing is blocked on a published verisim-api image (no +`+ghcr-publish.yml+` in `+verification-ecosystem/verisimdb+` yet). The +runbook holds the workflow YAML ready to commit on that day. + +=== 5. Agent‑tier guidance + +*Opus* (supervisor): architecture, schema design, cross‑module +contracts, merge review. Touches: IPC protocol design, Verisim schema +additions, Chapel FFI shape, coprocessor trait, SPARK kernel surface. + +*Sonnet* (executor): focused implementation against a clear spec, 3–20 +files, moderate complexity. Touches: per‑prover tactic synthesis, +Verisim read client, typed_wasm crate extraction, adapter code, worker +logic. + +*Haiku* (bulk): template‑driven mechanical edits, CI YAML, deletes, +repetitive stubs. Touches: Tier‑4 provisioning shell commands, extractor +boilerplate, per‑prover factory branches that follow a mould, +localisation key additions. + +=== 6. Inheritance from existing planning docs + +* *`+docs/FUTURE_DEVELOPMENT_ROADMAP.md+`* (removed from the tree; see +git history) — 2026‑01‑29 vision document. Its chapters on RL for tactic +search (§1.1), active learning (§1.2), and distributed dispatch map onto +Stages 3c / 4c and 5b/5c of this roadmap. Retain as background reading; +this document is the source of truth for sequencing. +* *link:handover/PRODUCTION-WIRING-PLAN.md[`+docs/handover/PRODUCTION-WIRING-PLAN.md+`]* +— L1/L2/L3 sprint doc. L1 = Stage 5a. L2 = Stage 5b. L3 Wave‑1/2 are +complete (in Stage 4 surface); Wave‑3 is partially complete in this +branch (tamarin/proverif/metamath/twelf/ortools); Wave‑4 is Stage 5d. +* *link:design/SPARK_ADOPTION_PLAN.md[`+docs/design/SPARK_ADOPTION_PLAN.md+`]* +— design for the SPARK‑verified kernel. Executes Stage 8c. +* *link:handover/L1-CAPNPROTO-PROMPT.md[`+docs/handover/L1-CAPNPROTO-PROMPT.md+`]* +— implementation brief for Stage 5a. Use as the Sonnet prompt when S6 +begins. +* *link:handover/L2-CHAPEL-PROMPT.md[`+docs/handover/L2-CHAPEL-PROMPT.md+`]* +— implementation brief for Stage 5b. +* *link:handover/L3-LIVE-PROVER-CI-PROMPT.md[`+docs/handover/L3-LIVE-PROVER-CI-PROMPT.md+`]* +— implementation brief for Stage 5d. +* *link:handover/STATE.md[`+docs/handover/STATE.md+`]* and +*link:../.machine_readable/descriptiles/STATE.a2ml[`+.machine_readable/descriptiles/STATE.a2ml+`]* +— running log of session‑by‑session progress. Continue to use as running +state; sync highlights to §2 of this document at each sprint boundary. + +=== 7. How to update this roadmap + +* When a stage sub‑item lands, mark its line `+[done YYYY‑MM‑DD ✓]+` in +§2 and update the corresponding row of §3. +* When a new endpoint target emerges, add a row to §3, extend §2’s stage +map if it doesn’t already fit, and add it to the sprint plan in §4 only +once it’s next‑up. +* Don’t remove rows from §3 when they land — keep the history visible, +the "`Today`" column becomes "`Done`" and the "`End‑state`" column stays +as the invariant. +* Record non‑trivial decisions in this doc, not in chat. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index a9f387b9..00000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -1,262 +0,0 @@ - - - -# ECHIDNA Roadmap - -**Status**: canonical • supersedes the aspirational parts of -`FUTURE_DEVELOPMENT_ROADMAP.md` (removed from the tree; see git history). -**Last revised**: 2026‑06‑01 (doc-coherence pass; previous revisions 2026‑05‑30 truthfulness audit, 2026‑04‑20) -**Scope**: the shortest honest path from today's repo to the endpoint vision. - -**Governance status post‑2026‑06‑01**: the R5 doc-canonical-reference -guardrail landed in two halves — R5a (prover-count drift, echidna‑local -at `.github/canonical-references/` after PR #174 migration) and R5b -(estate‑wide `Version: x.y.z` drift, in the standards reusable, consumed -via PR #172). MVP smoke (#167) and the pareto/bare-build governance -harness are green on `main`. The dogfood proof corpus (`proofs/{coq,lean,agda}` + `src/idris`) is now -CI-gated by `dogfood-proofs-ci.yml` (Coq/Lean/Agda) and `idris2-abi-ci.yml` -(the `src/idris` validator), each driven by a `just proofs-*` recipe — closing -a gap where the corpus had no CI and a green PR proved nothing about the -proofs (PR #234). None of these change the stage map below; -they are infrastructure around the work, not on the critical path. - -This document is the single source of truth for where ECHIDNA is going. -The domain‑specific plans under [`handover/`](./handover/) and -[`design/SPARK_ADOPTION_PLAN.md`](./design/SPARK_ADOPTION_PLAN.md) are -still authoritative for their sub‑areas; they fit *inside* this -roadmap as implementations of individual stages. - -## 1. Endpoint - -ECHIDNA, when complete, is the **reasoning substrate of the -hyperpolymath ecosystem** — not just a proof tool. It is: - -* a unified interface to every mature theorem prover, SMT solver, - model checker, and type checker in public use; -* an ML layer (GNN + Transformer over Flux.jl) that actually learns - premise selection, tactic synthesis, and strategy routing well - enough to beat hand‑curated choices on held‑out theorems; -* a persistent E‑R layer (Verisim) that stores every proof, tactic - application, and version as a content‑addressed row and closes a - real learning loop over historical outcomes; -* a parallel dispatch layer (Chapel) that runs portfolio solves - across CPU cores and dispatches specialised work to coprocessors - (GPU / tensor / vector / FPGA / QPU); -* a high‑speed IPC fabric (Cap'n Proto) between the Rust core and - the Julia ML sidecar and between the backend and the frontend; -* a frontend in AffineScript + Deno (TEA architecture) with i18n via - the LOL locale repo; -* a 16‑endpoint Zig ABI that external consumers (Coursera labs, - other projects) link against, with an SPDX‑pinned, Guix‑built, - Chainguard‑based container managed by Stapeln and hardened by the - Vordr / Selur / Svalinn / Cerro‑Torre surround; -* itself formally verified — the trust kernel's critical invariants - are proved in SPARK and in Idris2 / Agda. - -From a user's seat: **indistinguishable from magic for easy -obligations, honest about ambiguity for hard ones, never silently -wrong.** - -## 2. Stage map - -``` -Stage 1 Train the model at all ML layer can receive signal - 1a extractors emit premises [done 2026‑04‑20, 22 of 50 ✓] - 1b align_premises joins correctly [done 2026‑04‑19 ✓] - 1c residual extractor gaps fixed [done 2026‑04‑26 ✓ — 50/50 named extractors; - see handover/TODO.md S1 batches] - 1d vocab covers the surface [255 K; target ~1 M] - -Stage 2 Signal becomes useful MRR moves off 0.66 baseline - 2a run training at scale hardware task - 2b online vocab growth new feature - 2c re‑baseline and publish metrics run gate - -Stage 3 Learning loop closes model improves from outcomes - 3a Verisim read paths cross‑prover queries by goal_hash - 3b hypatia strategy loop wired `mv_prover_success_by_class` reads - 3c Proof / TacticApplication / ProofVersion emission wired - [defined 2026‑04‑19 ✓, emission pending] - -Stage 4 Interaction layer honest every declared ProverKind works - 4a typed_wasm → crates/typed_wasm [done 2026‑04‑22 ✓] - 4b 39 TypeChecker variant dispatch [done 2026‑04‑22 ✓, all Sigma‑routed] - 4c tactic synthesis template [91/91 real impl ✓; GNN-ranking surface - COMPLETE 2026‑05‑30 — every backend with - suggest_tactics now routes through - gnn_augment_tactics (S5 pilot + Tier-1 - ext + Tier-1 finisher + Tier-2 sweep + - Tier-3/niche sweep). Helper no-ops when - Julia /gnn/rank is unreachable. End-state - target met; remaining S2 dependency is - real trained weights at models/neural/] - 4d search_theorems template [done 2026‑04‑27 ✓ — cross-prover layer - added at dispatcher (CLI/REST/REPL all - call `vcl_ut::cross_prover_search_names`). - The 72 backend `Ok(vec![])` returns are - correct: they report "no native search - command" — cross-prover semantics live - one layer up where Verisim covers all - provers in one query.] - -Stage 5 Distributed & fast scale + specialised hardware - 5a Cap'n Proto IPC Rust ↔ Julia, :8090 - 5b Chapel full integration dispatch.rs picks by config - 5c coprocessor abstraction trait + tensor/vector/QPU/FPGA - 5d Tier‑4 live‑CI provisioning 19 backends, Containerfile path - -Stage 6 Cross‑prover semantics translation actually works - 6a OpenTheory bridge real bidirectional term translation - 6b Dedukti bridge real λΠ modulo as lingua franca - 6c mathematical identity arbitration canonicalise across representations - 6d Coursera delivery Zig ABI exposes capability - -Stage 7 Sovereign tooling surround the rest of the ecosystem - 7a Stapeln container lifecycle - 7b Vordr entry gate - 7c Selur scheduler - 7d Svalinn trust boundary - 7e Cerro‑Torre observability - 7f AffineScript‑TEA frontend src/affinescript/, ≥33 modules - 7g LOL i18n locale/ + t!() macro - 7h Zig ABI 16‑endpoint surface src/zig/echidna_abi.zig - -Stage 8 Self‑verified ECHIDNA proves ECHIDNA - 8a Idris2 meta‑proofs extend from 32 modules to full kernel - 8b Agda meta‑proofs extend from 12 modules - 8c SPARK‑verified trust kernel crates/echidna-core-spark/ - 8d panic‑attack hardened proptest + AFL++ nightly -``` - -## 3. Endpoint target — row by row - -| Claim | Today | End‑state target | -|---|---|---| -| "Every important solver" | **128 ProverKind variants** (89 external prover bindings + 39 TypeChecker disciplines routed through TypedWasm); **91 / 91 with real `suggest_tactics`** (5 still heuristic-only; GNN-ranked is the end-state target per `docs/PROVER_COUNT.md`); **72 backends with empty native search but a cross-prover Verisim fallback at the dispatcher layer (CLI/REST/REPL)** | **All variants with real `suggest_tactics` (GNN‑ranked top‑k); per-backend search reflects each prover's native capability while cross-prover queries are served from Verisim by `goal_hash`** | -| "Vocab at 2.5 M" | 255 K | **~1 M canonical tokens** after Mathport + Iris + VST + Flyspeck + HoTT absorption, with **online growth** adding tokens during training | -| "Chapel fully supported" | **rewritten and CI-green 2026-05-30** — `src/chapel/` compiles under chpl 2.3.0 / 2.8.0 (static lib, apt Chapel ships `CHPL_LIB_PIC=none` only); L2.2 `parallelProofSearchSpeculative` (first-success-wins atomic CAS) shipped next to best-of `parallelProofSearch`; `chapel-ci.yml` chapel-build + zig-ffi strict; aggregation invariants proved in `proofs/agda/ParallelSoundness.agda` with zero postulate/admit/believe_me. L2.3 cancel-token preemption next | **`dispatch.rs` picks Chapel‑parallel dispatch by config**; runtime init + cancellation + error propagation wired; ≥1 OoM speedup on portfolio solves | -| "Cap'n Proto serialisation" | 0 `.capnp` files | **`crates/echidna-wire/`** contains schemas for ProofState / Goal / Tactic / EmbeddingRequest / RankingResponse; IPC on :8090 is Cap'n Proto; JSON retained only as debug fallback | -| "Vordr / Selur / Svalinn / Cerro‑Torre / Stapeln" | Not present | Each named as a versioned dependency in Cargo.toml or the container definition, wired into its role | -| "AffineScript‑TEA frontend" | Not present (10 `.res` files stub) | **`src/affinescript/`** holds ≥33 AffineScript‑TEA modules, persistent Model → Msg → Update loop, talks to core over Cap'n Proto WebSocket | -| "LOL i18n" | Not present | **`locale/`** with LOL‑sourced translations; `t!()` macro for every user‑facing string | -| "Rust/SPARK base stable" | Rust only | **`crates/echidna-core-spark/`** holds the Ada/SPARK‑verified kernel (axiom scanning, trust‑level computation); proved free of runtime errors; called from Rust via C ABI | -| "16‑endpoint Zig ABI" | 4 shared libs, endpoint count unverified | **`src/zig/echidna_abi.zig`** exports exactly 16 functions (`echidna_prove`, `echidna_apply_tactic`, `echidna_rank_premises`, `echidna_verify_certificate`, `echidna_post_octad`, `echidna_query_identity`, …) with a versioned header | -| "100 K+ per prover" | Uneven; long tail <20 K | **Top 15 provers ≥ 100 K records each**; next 20 ≥ 25 K each; bottom 10 synthetically augmented to ≥ 10 K; `stats_UNIFIED.json` reports the distribution publicly | -| "Panic‑attacked" | No fuzz infra | **`benches/panic_attack/`** with proptest + AFL++ harnesses covering every parser, FFI boundary, IPC schema; nightly CI ≥ 1 h; zero known panic paths | -| "Prover count" | **128 declared, all 128 factory‑dispatched** (no orphans, verified 2026‑04‑27) | **`ProverKind` ≥ 65 variants, every one factory‑dispatched**; CLAUDE.md states the canonical count; no orphans — **target met and exceeded** | - -## 4. Current sprint — "the smallest set that flips half the table" - -Five concrete commitments. Landed together inside ~6 weeks they move -"Every important solver", "Vocab", "Prover count", half of "100 K+", -and start the self‑learning loop closure. - -| # | Stage | Commitment | Agent tier | Status | -|---|---|---|---|---| -| S1 | 1c | Finish the extractor premise‑emission wave (22 done; 28 remaining) | **Sonnet** | **done 2026‑04‑26 ✓** — 50/50 named extractors (3 batches in `handover/TODO.md`: 12 + 20 + 6) | -| S2 | 2a / 2c | Run training on the fixed corpus; record new MRR; commit `metrics_baseline.jsonl` | **Hardware / you** | gated by S1 (S1 ✓; S2 hardware step still to run) | -| S3 | 4a / 4b | Extract `typed_wasm` to `crates/typed_wasm/`; route 39 TypeChecker variants through Sigma parameters | **Opus‑design + Sonnet‑impl** | **done 2026‑04‑22 ✓** | -| S4 | 3a / 3b | Wire Verisim cross‑prover read paths (`goal_hash` queries + `mv_prover_success_by_class` + hypatia loop) | **Opus‑design + Sonnet‑impl** | **wired 2026‑04‑27 ✓** — read paths (`query_prover_success_by_class` via `VeriSimAdvisor`, `cross_prover_search_names` via `vcl_ut`) + write path (`spawn_record_attempt`) + end-to-end test (`tests/s4_loop_closure.rs`, `just test-s4-loop`); CI workflow filing gated on `ghcr-publish.yml` in `verisimdb` upstream (runbook holds the YAML) | -| S5 | 4c / 4d (pilot) | Tactic synthesis template for 5 high‑value provers (coq, lean, agda, isabelle, z3) using the GNN | **Opus‑design + Sonnet‑impl** | **done 2026‑05‑30 ✓** — `suggest_tactics` is 91/91 real; `gnn_augment_tactics` wired into ALL backends with `suggest_tactics` (S5 pilot 5 in c8a4f25, Tier-1 extension 5 in #135, Tier-1 finisher 2 + Tier-2 sweep 33 in #136, Tier-3/niche sweep 53 in this PR). Wiring is a no-op when Julia /gnn/rank is unreachable; once S2 trained weights land at `models/neural/`, every backend automatically returns model-derived premise-apply tactics | - -After S1–S5 land, the roadmap's next sprint takes up Stage 5 (IPC + -Chapel + Tier‑4 CI) and Stage 8 begins in parallel. - -### Sprint critical path (as of 2026‑04‑27) - -``` -S1 (extractors, Sonnet) ──┬──► S2 (training, hardware) ──┐ - │ │ - └──► S4 impl (needs S1 data) ────┴──► S5 GNN ranking - ▲ - │ blocked - Verisim schema design ◄── NEEDED FROM OPUS, - (cross‑repo, not in CROSS‑REPO INPUT. - echidna tree) -``` - -What is **not** blocking and can move now: - -- **Phase 1a** (Leo3, Satallax, Lash, AgsyHOL) — done 2026‑04‑26 ✓ -- **Phase 1b** (IProver, Princess, Twee, MetiTarski, CSI, AProVE) — done ✓ -- **S3** (typed_wasm + 39 TypeChecker Sigma routing) — done ✓ -- **`suggest_tactics`** — 91/91 real implementations ✓; every backend now - routes through `gnn_augment_tactics` (no-op until S2 weights land at - `models/neural/`) - -What **is** blocking and needs Opus + cross‑repo input: - -- **Verisim schema contract** (S4 design): the trait surface from echidna's - side is straightforward (`async fn search_by_goal_hash(hash) -> - Vec` and `async fn prover_success_by_class(class) -> - Vec<(ProverKind, f32)>`) but the schema for `ProofRecord` and `class` - lives in the Verisim repo and must be agreed there before echidna - can wire reads. **Status as of 2026-04-27**: the Verisim schema is in - fact fixed (`ProofAttempt` row → ClickHouse `proof_attempts` → - `mv_prover_success_by_class` MV) and both echidna read paths - (`query_prover_success_by_class` via `VeriSimAdvisor`, - `cross_prover_search_names` via `vcl_ut`) and the write path - (`spawn_record_attempt` from dispatch exits) are now wired. - - End-to-end loop test: `tests/s4_loop_closure.rs`, runnable via - `just test-s4-loop`. Skips cleanly when verisim-api is unreachable. - - Operations runbook: [`docs/handover/S4-LOOP-CLOSURE-RUNBOOK.md`](handover/S4-LOOP-CLOSURE-RUNBOOK.md). - - CI workflow filing is blocked on a published verisim-api image - (no `ghcr-publish.yml` in `verification-ecosystem/verisimdb` yet). - The runbook holds the workflow YAML ready to commit on that day. - -## 5. Agent‑tier guidance - -**Opus** (supervisor): architecture, schema design, cross‑module -contracts, merge review. Touches: IPC protocol design, Verisim -schema additions, Chapel FFI shape, coprocessor trait, SPARK kernel -surface. - -**Sonnet** (executor): focused implementation against a clear spec, -3–20 files, moderate complexity. Touches: per‑prover tactic -synthesis, Verisim read client, typed_wasm crate extraction, -adapter code, worker logic. - -**Haiku** (bulk): template‑driven mechanical edits, CI YAML, -deletes, repetitive stubs. Touches: Tier‑4 provisioning shell -commands, extractor boilerplate, per‑prover factory branches that -follow a mould, localisation key additions. - -## 6. Inheritance from existing planning docs - -* **`docs/FUTURE_DEVELOPMENT_ROADMAP.md`** (removed from the tree; see git history) - — 2026‑01‑29 vision document. Its chapters on RL for tactic - search (§1.1), active learning (§1.2), and distributed dispatch - map onto Stages 3c / 4c and 5b/5c of this roadmap. Retain as - background reading; this document is the source of truth for - sequencing. -* **[`docs/handover/PRODUCTION-WIRING-PLAN.md`](handover/PRODUCTION-WIRING-PLAN.md)** - — L1/L2/L3 sprint doc. L1 = Stage 5a. L2 = Stage 5b. L3 Wave‑1/2 - are complete (in Stage 4 surface); Wave‑3 is partially complete in - this branch (tamarin/proverif/metamath/twelf/ortools); Wave‑4 is - Stage 5d. -* **[`docs/design/SPARK_ADOPTION_PLAN.md`](design/SPARK_ADOPTION_PLAN.md)** - — design for the SPARK‑verified kernel. Executes Stage 8c. -* **[`docs/handover/L1-CAPNPROTO-PROMPT.md`](handover/L1-CAPNPROTO-PROMPT.md)** - — implementation brief for Stage 5a. Use as the Sonnet prompt - when S6 begins. -* **[`docs/handover/L2-CHAPEL-PROMPT.md`](handover/L2-CHAPEL-PROMPT.md)** - — implementation brief for Stage 5b. -* **[`docs/handover/L3-LIVE-PROVER-CI-PROMPT.md`](handover/L3-LIVE-PROVER-CI-PROMPT.md)** - — implementation brief for Stage 5d. -* **[`docs/handover/STATE.md`](handover/STATE.md)** and - **[`.machine_readable/descriptiles/STATE.a2ml`](../.machine_readable/descriptiles/STATE.a2ml)** - — running log of session‑by‑session progress. Continue to use as - running state; sync highlights to §2 of this document at each - sprint boundary. - -## 7. How to update this roadmap - -* When a stage sub‑item lands, mark its line `[done YYYY‑MM‑DD ✓]` - in §2 and update the corresponding row of §3. -* When a new endpoint target emerges, add a row to §3, extend §2's - stage map if it doesn't already fit, and add it to the sprint - plan in §4 only once it's next‑up. -* Don't remove rows from §3 when they land — keep the history - visible, the "Today" column becomes "Done" and the "End‑state" - column stays as the invariant. -* Record non‑trivial decisions in this doc, not in chat. diff --git a/docs/SUPPORTED_PROVERS.adoc b/docs/SUPPORTED_PROVERS.adoc new file mode 100644 index 00000000..1138448c --- /dev/null +++ b/docs/SUPPORTED_PROVERS.adoc @@ -0,0 +1,117 @@ +== Supported Provers + +ECHIDNA implements 100+ prover backends, but the surface a new user +encounters is deliberately smaller. This document is the source of truth +for what works out of the box. + +=== What the API actually exposes + +`+GET /api/provers+` returns 12 *core* provers +(`+ProverKind::all_core()+` in `+src/rust/provers/mod.rs:689+`). These +are the only ones the bundled UI (`+src/ui/public/prove.html+`) and the +REST clients see by default: + +[width="100%",cols="9%,23%,10%,58%",options="header",] +|=== +|Prover |Kind |Required binary |Install hint +|Agda |Dependent ITP |`+agda+` |`+cabal install Agda+` or distro package + +|Coq |Calculus of Inductive Constructions |`+coqc+` +|`+opam install coq+` (or Coq Platform installer) + +|Lean |Lean 4 |`+lean+`, `+lake+` |`+elan+` toolchain manager: +https://leanprover.github.io/lean4/doc/quickstart.html + +|Isabelle |Higher-order logic |`+isabelle+` +|https://isabelle.in.tum.de/installation.html + +|Z3 |SMT solver |`+z3+` |`+apt install z3+` / `+brew install z3+` / +release tarball + +|CVC5 |SMT solver |`+cvc5+` |https://cvc5.github.io/downloads.html + +|Metamath |Pure-Rust in-process checker |_(none)_ |Works without +external binary — pure-Rust implementation in +`+src/rust/provers/metamath.rs+` + +|HOL Light |Classical higher-order logic |`+hol_light+` |OCaml + HOL +Light: https://github.com/jrh13/hol-light + +|Mizar |Tarski–Grothendieck set theory |`+mizf+`, `+verifier+` +|http://mizar.org/system/index.html + +|PVS |Prototype Verification System |`+pvs+` |https://pvs.csl.sri.com/ + +|ACL2 |Applicative Common Lisp |`+acl2+` +|https://www.cs.utexas.edu/users/moore/acl2/ + +|HOL4 |HOL family theorem prover |`+hol+` +|https://hol-theorem-prover.org/ +|=== + +ECHIDNA does *not* install or bundle these binaries. When a binary is +missing, the corresponding `+POST /api/prove+` call returns a structured +error (e.g. `+"Failed to spawn Z3 process: \"z3\""+`) — it does not +crash the server and the other 11 provers remain available. + +=== Quickstart: prove your first goal + +[source,bash] +---- +# 1. Install Z3 (smallest dependency, ~5 MB) +sudo apt install z3 # Debian/Ubuntu +brew install z3 # macOS + +# 2. Build and run the server +cargo run --bin echidna -- server --cors + +# 3. In another terminal — health check +curl http://127.0.0.1:8081/api/health +# → {"status":"ok","version":"2.1.0"} + +# 4. Prove a satisfiable SMT-LIB goal +curl -X POST http://127.0.0.1:8081/api/prove \ + -H 'Content-Type: application/json' \ + -d '{ + "prover": "Z3", + "content": "(set-logic QF_LIA)\n(declare-const x Int)\n(assert (> x 0))\n(check-sat)\n", + "timeout": 30 + }' +# → {"success":true,"goals":1,"message":"Proof verified successfully"} +---- + +For a browser UI, open `+src/ui/public/prove.html+` directly in any +modern browser and point the "`API base`" field at the running server. +No build step is required. + +=== Beyond the core 12 + +`+ProverKind::all()+` lists 67 additional backends (79 total — 12 core +plus 67 extended) with full `+ProverBackend+` trait implementations +(real subprocess invocation, not stubs), spanning interactive provers +(Idris2, Lean3, F*), first-order ATPs (Vampire, E, SPASS), +constraint/SAT solvers (MiniSat, CaDiCaL, Kissat, MiniZinc), model +checkers (SPIN, NuSMV, TLC, UPPAAL), auto-active verifiers (Dafny, +Why3), security tools (Tamarin, ProVerif, CryptoVerif, EasyCrypt), and +more. + +These are reachable via the Rust API: + +[source,rust] +---- +use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; +let backend = ProverFactory::create(ProverKind::Vampire, ProverConfig::default())?; +---- + +They are deliberately not in `+all_core()+` because each adds an +external binary dependency and most users do not need them. To expose +extra backends through the REST API, edit +`+src/rust/provers/mod.rs:689+` and add the relevant `+ProverKind+` +variants to `+all_core()+`. + +The full `+ProverKind+` enum has 141 variants. The delta between 141 and +79 covers dialect variants (e.g. `+Lean3+` alongside `+Lean+`, `+Rocq+` +alongside `+Coq+`, `+IsabelleZF+` alongside `+Isabelle+`) and +experimental adapters not yet promoted to the canonical roster. They +have implementation files but are not exercised by the default test +suite. diff --git a/docs/SUPPORTED_PROVERS.md b/docs/SUPPORTED_PROVERS.md deleted file mode 100644 index 4a161bf7..00000000 --- a/docs/SUPPORTED_PROVERS.md +++ /dev/null @@ -1,94 +0,0 @@ - - -# Supported Provers - -ECHIDNA implements 100+ prover backends, but the surface a new user -encounters is deliberately smaller. This document is the source of truth -for what works out of the box. - -## What the API actually exposes - -`GET /api/provers` returns 12 **core** provers (`ProverKind::all_core()` -in `src/rust/provers/mod.rs:689`). These are the only ones the bundled -UI (`src/ui/public/prove.html`) and the REST clients see by default: - -| Prover | Kind | Required binary | Install hint | -|------------|---------------------------------------|-----------------|-------------------------------------------------------------------------------------------------| -| Agda | Dependent ITP | `agda` | `cabal install Agda` or distro package | -| Coq | Calculus of Inductive Constructions | `coqc` | `opam install coq` (or Coq Platform installer) | -| Lean | Lean 4 | `lean`, `lake` | `elan` toolchain manager: | -| Isabelle | Higher-order logic | `isabelle` | | -| Z3 | SMT solver | `z3` | `apt install z3` / `brew install z3` / release tarball | -| CVC5 | SMT solver | `cvc5` | | -| Metamath | Pure-Rust in-process checker | *(none)* | Works without external binary — pure-Rust implementation in `src/rust/provers/metamath.rs` | -| HOL Light | Classical higher-order logic | `hol_light` | OCaml + HOL Light: | -| Mizar | Tarski–Grothendieck set theory | `mizf`, `verifier` | | -| PVS | Prototype Verification System | `pvs` | | -| ACL2 | Applicative Common Lisp | `acl2` | | -| HOL4 | HOL family theorem prover | `hol` | | - -ECHIDNA does **not** install or bundle these binaries. When a binary is -missing, the corresponding `POST /api/prove` call returns a structured -error (e.g. `"Failed to spawn Z3 process: \"z3\""`) — it does not crash -the server and the other 11 provers remain available. - -## Quickstart: prove your first goal - -```bash -# 1. Install Z3 (smallest dependency, ~5 MB) -sudo apt install z3 # Debian/Ubuntu -brew install z3 # macOS - -# 2. Build and run the server -cargo run --bin echidna -- server --cors - -# 3. In another terminal — health check -curl http://127.0.0.1:8081/api/health -# → {"status":"ok","version":"2.1.0"} - -# 4. Prove a satisfiable SMT-LIB goal -curl -X POST http://127.0.0.1:8081/api/prove \ - -H 'Content-Type: application/json' \ - -d '{ - "prover": "Z3", - "content": "(set-logic QF_LIA)\n(declare-const x Int)\n(assert (> x 0))\n(check-sat)\n", - "timeout": 30 - }' -# → {"success":true,"goals":1,"message":"Proof verified successfully"} -``` - -For a browser UI, open `src/ui/public/prove.html` directly in any -modern browser and point the "API base" field at the running server. -No build step is required. - -## Beyond the core 12 - -`ProverKind::all()` lists 67 additional backends (79 total — 12 core -plus 67 extended) with full -`ProverBackend` trait implementations (real subprocess invocation, not -stubs), spanning interactive provers (Idris2, Lean3, F\*), first-order -ATPs (Vampire, E, SPASS), constraint/SAT solvers (MiniSat, CaDiCaL, -Kissat, MiniZinc), model checkers (SPIN, NuSMV, TLC, UPPAAL), -auto-active verifiers (Dafny, Why3), security tools (Tamarin, ProVerif, -CryptoVerif, EasyCrypt), and more. - -These are reachable via the Rust API: - -```rust -use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; -let backend = ProverFactory::create(ProverKind::Vampire, ProverConfig::default())?; -``` - -They are deliberately not in `all_core()` because each adds an external -binary dependency and most users do not need them. To expose extra -backends through the REST API, edit `src/rust/provers/mod.rs:689` and -add the relevant `ProverKind` variants to `all_core()`. - -The full `ProverKind` enum has 141 variants. The delta between 141 and -79 covers dialect variants (e.g. `Lean3` alongside `Lean`, `Rocq` -alongside `Coq`, `IsabelleZF` alongside `Isabelle`) and experimental -adapters not yet promoted to the canonical roster. They have -implementation files but are not exercised by the default test suite. diff --git a/docs/TEST-NEEDS.adoc b/docs/TEST-NEEDS.adoc new file mode 100644 index 00000000..037db850 --- /dev/null +++ b/docs/TEST-NEEDS.adoc @@ -0,0 +1,300 @@ +== Test & Benchmark Requirements + +=== CRG Grade: B — ACHIEVED 2026-04-04 + +____ +CRG B achieved 2026-04-04: Verified proofs from 6 diverse external repos +with real output. +____ + +=== CRG B Evidence — External Targets + +[width="99%",cols="29%,20%,35%,16%",options="header",] +|=== +|Target Repo |Language |What Was Tested |Result +|echidna (own proofs) |Coq |`+echidna verify+` on proofs/coq/basic.v +|VALID: 0 goals, 43 tactics, 0 theorems + +|nextgen-languages/wokelang |Coq |`+echidna verify+` on WokeLang.v +|INVALID: proof rejected + +|nextgen-languages/my-lang |Coq |`+echidna verify+` on Syntax.v +|INVALID: proof rejected + +|maa-framework/absolute-zero |Coq |`+echidna verify+` on CNOCategory.v +|VALID: 0 goals, 81 tactics, 0 theorems + +|protocol-squisher |Lean |`+echidna verify+` on +wheelbarrow_necessity.lean |VALID: 0 goals, 0 tactics, 5 theorems + +|nextgen-languages/tangle |Lean |`+echidna verify+` on Tangle.lean +|VALID: 0 goals, 0 tactics, 10 theorems +|=== + +==== Target Details + +*1. echidna own Coq proofs (baseline)* - Command: +`+echidna verify /var/mnt/eclipse/repos/verification-ecosystem/echidna/proofs/coq/basic.v+` +- Key findings: Valid proof. 43 tactics detected. Baseline verification +working correctly. + +*2. nextgen-languages/wokelang (Coq)* - Command: +`+echidna verify /var/mnt/eclipse/repos/nextgen-languages/wokelang/docs/proofs/verification/WokeLang.v+` +- Key findings: Proof invalid. Echidna correctly rejected an +incomplete/malformed proof file. Demonstrates false-positive resilience. + +*3. nextgen-languages/my-lang (Coq)* - Command: +`+echidna verify /var/mnt/eclipse/repos/nextgen-languages/my-lang/proofs/verification/coq/Syntax.v+` +- Key findings: Proof invalid. Another correctly rejected proof. +Confirms echidna does not blindly accept all Coq files. + +*4. maa-framework/absolute-zero (Coq — category theory)* - Command: +`+echidna verify /var/mnt/eclipse/repos/maa-framework/absolute-zero/proofs/coq/category/CNOCategory.v+` +- Key findings: Valid proof with 81 tactics. Complex category theory +proof verified successfully. Demonstrates handling of advanced +mathematical content. + +*5. protocol-squisher (Lean — wheelbarrow necessity)* - Command: +`+echidna verify /var/mnt/eclipse/repos/protocol-squisher/proofs/lean/wheelbarrow_necessity.lean+` +- Key findings: Valid proof. 5 theorems in context, 0 tactics +(declarative style). Cross-prover support (Lean vs Coq) verified. + +*6. nextgen-languages/tangle (Lean — language proofs)* - Command: +`+echidna verify /var/mnt/eclipse/repos/nextgen-languages/tangle/proofs/Tangle.lean+` +- Key findings: Valid proof. 10 theorems in context. Lean parser handles +different proof styles correctly. + +=== Current State (updated 2026-04-04) + +* Unit tests: 756 pass / 0 fail / 16 ignored +** 556 in main crate, 200 across integration/property/aspect/E2E suites +* Integration tests: full (echidnabot + prover backends) +* E2E tests: COMPLETE (tests/e2e_prover_test.rs — 10 tests) +* P2P property tests: COMPLETE (tests/p2p_property_tests.rs — ~1,000 +proptest cases) +* Aspect tests: COMPLETE (tests/aspect_tests.rs — 12 tests) +* Julia smoke tests: COMPLETE (tests/julia/smoke_test.jl — 63 tests) +* Shell validation: COMPLETE (tests/shell/validate_scripts.sh — 68 +checks) +* Benchmarks: BASELINED (benches/proof_benchmarks.rs — 13 Criterion +functions) +* panic-attack scan: NEVER RUN + +=== Benchmark Status (verified 2026-04-04) + +*The 1,035 .v files are Coq proof files from external_corpora/ — NOT +runnable benchmarks.* - `+external_corpora/CoqGym/+` — 6,678 Coq proofs +(training/ML corpus data) - `+proofs/coq/+` — 16 project Coq proof files +- These are NOT zig files and NOT benchmark runners + +*Real Criterion benchmarks exist in `+benches/proof_benchmarks.rs+`:* - +`+bench_proof_state_construction+` (5 goal-count variants) - +`+bench_term_construction+` (4 depth variants) - +`+bench_prover_creation+` (8 provers) - `+bench_prover_detection+` (8 +file extensions) - `+bench_trust_computation+` (3 scenarios: max_trust, +single_prover, dangerous) - `+bench_axiom_scanning+` (4 patterns) - +`+bench_mutation_generation+` - `+bench_pareto_frontier+` (3 point-count +variants) - `+bench_statistics_tracking+` - `+bench_ffi_kind_mapping+` +Run with: `+cargo bench+` + +=== Ignored Test Investigation (9 tests) + +All 9 ignored tests are in `+tests/integration_v1_2.rs+`. They are +*legitimately ignored* — each has a `+// Requires binary+` comment: +- 2 tests: `+#[ignore] // Requires ACL2 binary+` - 2 tests: +`+#[ignore] // Requires PVS binary+` - 2 tests: +`+#[ignore] // Requires HOL4 binary+` - 3 tests: +`+#[ignore] // Requires prover binaries+` + +*No action needed.* These test real prover binary invocation and must +remain skipped until ACL2/PVS/HOL4 are installed in the CI environment. +The ignore reason is clearly documented. + +(Note: TEST-NEEDS.md said "`9 ignored`" but `+cargo test+` shows 16 +ignored total. The additional 7 are in +`+tests/test_neural_integration.rs+` requiring the Julia server running +on port 8081.) + +=== What’s Covered + +==== Point-to-Point (P2P) — tests/p2p_property_tests.rs + +* [x] Dispatch determinism: same input → same trust level (proptest, 500 +cases) +* [x] ProofState serialisation: arbitrary states survive JSON roundtrip +(200 cases) +* [x] Reject danger caps trust at Level2 (proptest, 200 cases) +* [x] Safe danger >= Warning danger (proptest, 200 cases) +* [x] ProverFactory correct kind (proptest, 50 cases) +* [x] AxiomTracker stateless / idempotent (proptest, 200 cases) +* [x] ProverKind JSON roundtrip (proptest, 50 cases) +* [x] TrustLevel ordering consistent with value() (proptest, 200 cases) +* [x] DispatchConfig clone preserves fields (proptest, 100 cases) + +==== End-to-End (E2E) — tests/e2e_prover_test.rs + +* [x] All 48 prover backends instantiate via ProverFactory +* [x] DispatchConfig defaults are safe (invariant check) +* [x] Trust pipeline — all 5 levels produce correct ordering +* [x] Reject axiom prevents Level3+ trust +* [x] Axiom tracker detects sorry/Admitted/believe_me +* [x] Z3 full dispatch workflow (skips if binary absent) +* [x] Malformed input returns error, not panic +* [x] Missing binary returns error (not false success) +* [x] DispatchResult JSON roundtrip (all fields) +* [x] Dispatcher respects timeout config +* [x] select_prover heuristic coverage + +==== Aspect Tests — tests/aspect_tests.rs + +* [x] Security: malicious input no high trust +* [x] Security: no proof cert from arbitrary string +* [x] Security: zero timeout no panic +* [x] Concurrency: parallel dispatches isolated (8 workers) +* [x] Concurrency: axiom tracker stateless (16 workers) +* [x] Error handling: impossible trust requirement +* [x] Error handling: config validation +* [x] Error handling: DispatchResult edge cases +* [x] Trust: DangerLevel total order +* [x] Trust: TrustLevel values monotone +* [x] Trust: compute_trust_level deterministic (100 iterations) +* [x] Coverage: ProverKind::all() count >= 30, no duplicates +* [x] Coverage: ProverKind JSON stable (5 canonical names) + +==== Julia Smoke Tests — tests/julia/smoke_test.jl + +* [x] Syntax validation: 9 top-level scripts (api_server, run_server, +train_models, etc.) +* [x] Syntax validation: inference/ sub-package +* [x] EchidnaML module structure +* [x] api/ sub-package syntax +* [x] scripts/*.jl corpus scripts (32 scripts) +* [x] Directory structure (JULIA_SRC, Project.toml, entrypoints) +* [x] Tokenizer unit smoke (5 properties) +* [x] BOW vectorizer unit smoke (4 properties) + +==== Shell Validation — tests/shell/validate_scripts.sh + +* [x] Syntax check (bash -n) on all scripts/*.sh +* [x] Syntax check on tests/*.sh +* [x] SPDX header check +* [x] Banned pattern check (docker/npm/HTTP) +* [x] –help smoke test for selected scripts + +*Findings from shell validation:* - scripts/install-provers.sh — missing +SPDX header - scripts/mvp-smoke.sh — missing SPDX header - +scripts/expand_training_data.sh — HTTP URL (should use HTTPS) - +scripts/test-integration.sh — HTTP URL - scripts/test_integration.sh — +HTTP URL + +==== Benchmarks — benches/proof_benchmarks.rs + +* [x] Core type construction (ProofState, Term) +* [x] Prover creation (8 representative backends) +* [x] Prover detection from file extension +* [x] Trust computation (3 scenarios) +* [x] Axiom scanning (4 patterns) +* [x] Mutation generation +* [x] Pareto frontier (3 sizes) +* [x] Statistics tracking +* [x] FFI kind mapping roundtrip + +=== Still Missing + +==== zig prover (6,694 files — ZERO tests) + +* This is Coq formal proof code in external_corpora/ (training data) +* The "`V`" extension here means Coq, not zig +* Coq proofs are inherently self-verifying when compiled with coqc +* No dedicated test infrastructure for the Coq corpus +* *Status:* Out of scope for this blitz (requires Coq toolchain + +significant effort) + +==== Zig FFI (34 files — 7 test files) + +* [x] 7 test files exist +* [ ] Coverage verification pending + +==== Idris2 ABI (42 files) + +* Formal proofs are self-verifying (checked at type-check time) +* No runtime integration tests yet +* *Status:* Deferred — requires Idris2 toolchain in CI + +==== AffineScript UI (33 files — ZERO tests) + +* Dashboard components need render tests +* *Status:* Deferred — requires Deno + AffineScript test setup + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] Echidnabot self-scan +* [ ] Prover correctness validation suite + +=== Known Issues + +==== /api/verify false-positive on unparseable input (2026-04-05) + +*Bug:* `+POST /api/verify+` returns `+valid: true+` for content that a +prover’s `+parse_string+` cannot interpret, even when that content is +syntactically invalid for the target prover. + +Reproduction: + +[source,bash] +---- +curl -X POST http://localhost:8090/api/verify \ + -H 'Content-Type: application/json' \ + -d '{"prover":"Coq","content":"absolute garbage @#$ not coq"}' +# → {"valid":true,"goals_remaining":0,"tactics_used":0} +---- + +Also affected: empty content, cross-prover content (Lean syntax to Coq), +anything the per-prover `+parse_string+` cannot extract structure from. + +*Root cause:* the verification pipeline is: + +[arabic] +. `+parse_string(content)+` → `+ProofState+` (partial parse; empty state +on unrecognised input, no failure propagated). +. `+verify_proof(&state)+` calls `+state.export()+` to regenerate prover +source from the `+ProofState+`, writes it to a temp file, then runs the +real backend binary (`+coqc+`, `+lean+`, `+idris2 --check+`). +. Empty `+ProofState+` → empty exported file → prover returns exit 0 → +`+valid: true+`. + +*Impact:* any downstream system treating `+valid: true+` as ground truth +will accumulate false positives. Observed externally: the hyperpolymath +`+proof_attempts+` learning loop was polluted with 29 false-success rows +before the bug was spotted; fix was to bypass `+/api/verify+` and shell +out to prover binaries directly in the batch driver. + +Idris2 has the mirror-image bug (false-negative): `+parse_string+` +parses `+main = putStrLn "ok"+` but `+export()+` regenerates the body as +`+?main_todo+` (a hole), so `+idris2 --check+` always fails. See the +generated file at `+/tmp/echidna_idris2/Verify.idr+` after any Idris2 +API call. + +*Fix direction:* - `+parse_string+` should return `+Err+` on +unrecognised input rather than silently producing an empty state. - +`+verify_proof+` for each prover should either preserve original content +(write `+content+` directly, not `+export(state)+`) or treat an empty +`+ProofState+` as a parse failure. - Add regression tests: `+verify+` on +garbage, empty, cross-prover content must all return `+valid: false+`. + +*Partial fix (2026-04-05):* server-level guard in `+prove_handler+` and +`+verify_handler+` now returns `+valid: false+` when `+parse_string+` +produces an empty `+ProofState+` (no goals, theorems, definitions, +axioms, or variables) on non-empty input. Verified live: - garbage to +Coq/Lean: `+valid: false+` (was `+true+`) - cross-prover (SMT to Coq): +`+valid: false+` - real Coq/Z3 proofs: still work correctly The deeper +fix — making each prover backend preserve original content instead of +round-tripping through ProofState — remains outstanding. + +=== Priority + +* *CRG C COMPLETE* as of 2026-04-04 +* Next priority: Fix 5 shell issues found by validation +* zig prover testing remains the largest correctness gap but is out of +scope until the Coq corpus toolchain is set up in CI diff --git a/docs/TEST-NEEDS.md b/docs/TEST-NEEDS.md deleted file mode 100644 index d6c097cc..00000000 --- a/docs/TEST-NEEDS.md +++ /dev/null @@ -1,259 +0,0 @@ -# Test & Benchmark Requirements - -## CRG Grade: B — ACHIEVED 2026-04-04 - -> CRG B achieved 2026-04-04: Verified proofs from 6 diverse external repos with real output. - -## CRG B Evidence — External Targets - -| Target Repo | Language | What Was Tested | Result | -|-------------|----------|-----------------|--------| -| echidna (own proofs) | Coq | `echidna verify` on proofs/coq/basic.v | VALID: 0 goals, 43 tactics, 0 theorems | -| nextgen-languages/wokelang | Coq | `echidna verify` on WokeLang.v | INVALID: proof rejected | -| nextgen-languages/my-lang | Coq | `echidna verify` on Syntax.v | INVALID: proof rejected | -| maa-framework/absolute-zero | Coq | `echidna verify` on CNOCategory.v | VALID: 0 goals, 81 tactics, 0 theorems | -| protocol-squisher | Lean | `echidna verify` on wheelbarrow_necessity.lean | VALID: 0 goals, 0 tactics, 5 theorems | -| nextgen-languages/tangle | Lean | `echidna verify` on Tangle.lean | VALID: 0 goals, 0 tactics, 10 theorems | - -### Target Details - -**1. echidna own Coq proofs (baseline)** -- Command: `echidna verify /var/mnt/eclipse/repos/verification-ecosystem/echidna/proofs/coq/basic.v` -- Key findings: Valid proof. 43 tactics detected. Baseline verification working correctly. - -**2. nextgen-languages/wokelang (Coq)** -- Command: `echidna verify /var/mnt/eclipse/repos/nextgen-languages/wokelang/docs/proofs/verification/WokeLang.v` -- Key findings: Proof invalid. Echidna correctly rejected an incomplete/malformed proof file. Demonstrates false-positive resilience. - -**3. nextgen-languages/my-lang (Coq)** -- Command: `echidna verify /var/mnt/eclipse/repos/nextgen-languages/my-lang/proofs/verification/coq/Syntax.v` -- Key findings: Proof invalid. Another correctly rejected proof. Confirms echidna does not blindly accept all Coq files. - -**4. maa-framework/absolute-zero (Coq — category theory)** -- Command: `echidna verify /var/mnt/eclipse/repos/maa-framework/absolute-zero/proofs/coq/category/CNOCategory.v` -- Key findings: Valid proof with 81 tactics. Complex category theory proof verified successfully. Demonstrates handling of advanced mathematical content. - -**5. protocol-squisher (Lean — wheelbarrow necessity)** -- Command: `echidna verify /var/mnt/eclipse/repos/protocol-squisher/proofs/lean/wheelbarrow_necessity.lean` -- Key findings: Valid proof. 5 theorems in context, 0 tactics (declarative style). Cross-prover support (Lean vs Coq) verified. - -**6. nextgen-languages/tangle (Lean — language proofs)** -- Command: `echidna verify /var/mnt/eclipse/repos/nextgen-languages/tangle/proofs/Tangle.lean` -- Key findings: Valid proof. 10 theorems in context. Lean parser handles different proof styles correctly. - -## Current State (updated 2026-04-04) - -- Unit tests: 756 pass / 0 fail / 16 ignored - - 556 in main crate, 200 across integration/property/aspect/E2E suites -- Integration tests: full (echidnabot + prover backends) -- E2E tests: COMPLETE (tests/e2e_prover_test.rs — 10 tests) -- P2P property tests: COMPLETE (tests/p2p_property_tests.rs — ~1,000 proptest cases) -- Aspect tests: COMPLETE (tests/aspect_tests.rs — 12 tests) -- Julia smoke tests: COMPLETE (tests/julia/smoke_test.jl — 63 tests) -- Shell validation: COMPLETE (tests/shell/validate_scripts.sh — 68 checks) -- Benchmarks: BASELINED (benches/proof_benchmarks.rs — 13 Criterion functions) -- panic-attack scan: NEVER RUN - -## Benchmark Status (verified 2026-04-04) - -**The 1,035 .v files are Coq proof files from external_corpora/ — NOT runnable benchmarks.** -- `external_corpora/CoqGym/` — 6,678 Coq proofs (training/ML corpus data) -- `proofs/coq/` — 16 project Coq proof files -- These are NOT zig files and NOT benchmark runners - -**Real Criterion benchmarks exist in `benches/proof_benchmarks.rs`:** -- `bench_proof_state_construction` (5 goal-count variants) -- `bench_term_construction` (4 depth variants) -- `bench_prover_creation` (8 provers) -- `bench_prover_detection` (8 file extensions) -- `bench_trust_computation` (3 scenarios: max_trust, single_prover, dangerous) -- `bench_axiom_scanning` (4 patterns) -- `bench_mutation_generation` -- `bench_pareto_frontier` (3 point-count variants) -- `bench_statistics_tracking` -- `bench_ffi_kind_mapping` -Run with: `cargo bench` - -## Ignored Test Investigation (9 tests) - -All 9 ignored tests are in `tests/integration_v1_2.rs`. They are **legitimately ignored** — each has a `// Requires binary` comment: -- 2 tests: `#[ignore] // Requires ACL2 binary` -- 2 tests: `#[ignore] // Requires PVS binary` -- 2 tests: `#[ignore] // Requires HOL4 binary` -- 3 tests: `#[ignore] // Requires prover binaries` - -**No action needed.** These test real prover binary invocation and must remain -skipped until ACL2/PVS/HOL4 are installed in the CI environment. The ignore -reason is clearly documented. - -(Note: TEST-NEEDS.md said "9 ignored" but `cargo test` shows 16 ignored total. -The additional 7 are in `tests/test_neural_integration.rs` requiring the Julia -server running on port 8081.) - -## What's Covered - -### Point-to-Point (P2P) — tests/p2p_property_tests.rs -- [x] Dispatch determinism: same input → same trust level (proptest, 500 cases) -- [x] ProofState serialisation: arbitrary states survive JSON roundtrip (200 cases) -- [x] Reject danger caps trust at Level2 (proptest, 200 cases) -- [x] Safe danger >= Warning danger (proptest, 200 cases) -- [x] ProverFactory correct kind (proptest, 50 cases) -- [x] AxiomTracker stateless / idempotent (proptest, 200 cases) -- [x] ProverKind JSON roundtrip (proptest, 50 cases) -- [x] TrustLevel ordering consistent with value() (proptest, 200 cases) -- [x] DispatchConfig clone preserves fields (proptest, 100 cases) - -### End-to-End (E2E) — tests/e2e_prover_test.rs -- [x] All 48 prover backends instantiate via ProverFactory -- [x] DispatchConfig defaults are safe (invariant check) -- [x] Trust pipeline — all 5 levels produce correct ordering -- [x] Reject axiom prevents Level3+ trust -- [x] Axiom tracker detects sorry/Admitted/believe_me -- [x] Z3 full dispatch workflow (skips if binary absent) -- [x] Malformed input returns error, not panic -- [x] Missing binary returns error (not false success) -- [x] DispatchResult JSON roundtrip (all fields) -- [x] Dispatcher respects timeout config -- [x] select_prover heuristic coverage - -### Aspect Tests — tests/aspect_tests.rs -- [x] Security: malicious input no high trust -- [x] Security: no proof cert from arbitrary string -- [x] Security: zero timeout no panic -- [x] Concurrency: parallel dispatches isolated (8 workers) -- [x] Concurrency: axiom tracker stateless (16 workers) -- [x] Error handling: impossible trust requirement -- [x] Error handling: config validation -- [x] Error handling: DispatchResult edge cases -- [x] Trust: DangerLevel total order -- [x] Trust: TrustLevel values monotone -- [x] Trust: compute_trust_level deterministic (100 iterations) -- [x] Coverage: ProverKind::all() count >= 30, no duplicates -- [x] Coverage: ProverKind JSON stable (5 canonical names) - -### Julia Smoke Tests — tests/julia/smoke_test.jl -- [x] Syntax validation: 9 top-level scripts (api_server, run_server, train_models, etc.) -- [x] Syntax validation: inference/ sub-package -- [x] EchidnaML module structure -- [x] api/ sub-package syntax -- [x] scripts/*.jl corpus scripts (32 scripts) -- [x] Directory structure (JULIA_SRC, Project.toml, entrypoints) -- [x] Tokenizer unit smoke (5 properties) -- [x] BOW vectorizer unit smoke (4 properties) - -### Shell Validation — tests/shell/validate_scripts.sh -- [x] Syntax check (bash -n) on all scripts/*.sh -- [x] Syntax check on tests/*.sh -- [x] SPDX header check -- [x] Banned pattern check (docker/npm/HTTP) -- [x] --help smoke test for selected scripts - -**Findings from shell validation:** -- scripts/install-provers.sh — missing SPDX header -- scripts/mvp-smoke.sh — missing SPDX header -- scripts/expand_training_data.sh — HTTP URL (should use HTTPS) -- scripts/test-integration.sh — HTTP URL -- scripts/test_integration.sh — HTTP URL - -### Benchmarks — benches/proof_benchmarks.rs -- [x] Core type construction (ProofState, Term) -- [x] Prover creation (8 representative backends) -- [x] Prover detection from file extension -- [x] Trust computation (3 scenarios) -- [x] Axiom scanning (4 patterns) -- [x] Mutation generation -- [x] Pareto frontier (3 sizes) -- [x] Statistics tracking -- [x] FFI kind mapping roundtrip - -## Still Missing - -### zig prover (6,694 files — ZERO tests) -- This is Coq formal proof code in external_corpora/ (training data) -- The "V" extension here means Coq, not zig -- Coq proofs are inherently self-verifying when compiled with coqc -- No dedicated test infrastructure for the Coq corpus -- **Status:** Out of scope for this blitz (requires Coq toolchain + significant effort) - -### Zig FFI (34 files — 7 test files) -- [x] 7 test files exist -- [ ] Coverage verification pending - -### Idris2 ABI (42 files) -- Formal proofs are self-verifying (checked at type-check time) -- No runtime integration tests yet -- **Status:** Deferred — requires Idris2 toolchain in CI - -### AffineScript UI (33 files — ZERO tests) -- Dashboard components need render tests -- **Status:** Deferred — requires Deno + AffineScript test setup - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] Echidnabot self-scan -- [ ] Prover correctness validation suite - -## Known Issues - -### /api/verify false-positive on unparseable input (2026-04-05) - -**Bug:** `POST /api/verify` returns `valid: true` for content that a prover's -`parse_string` cannot interpret, even when that content is syntactically -invalid for the target prover. - -Reproduction: -```bash -curl -X POST http://localhost:8090/api/verify \ - -H 'Content-Type: application/json' \ - -d '{"prover":"Coq","content":"absolute garbage @#$ not coq"}' -# → {"valid":true,"goals_remaining":0,"tactics_used":0} -``` - -Also affected: empty content, cross-prover content (Lean syntax to Coq), -anything the per-prover `parse_string` cannot extract structure from. - -**Root cause:** the verification pipeline is: - -1. `parse_string(content)` → `ProofState` (partial parse; empty state on - unrecognised input, no failure propagated). -2. `verify_proof(&state)` calls `state.export()` to regenerate prover source - from the `ProofState`, writes it to a temp file, then runs the real - backend binary (`coqc`, `lean`, `idris2 --check`). -3. Empty `ProofState` → empty exported file → prover returns exit 0 → - `valid: true`. - -**Impact:** any downstream system treating `valid: true` as ground truth -will accumulate false positives. Observed externally: the hyperpolymath -`proof_attempts` learning loop was polluted with 29 false-success rows -before the bug was spotted; fix was to bypass `/api/verify` and shell out -to prover binaries directly in the batch driver. - -Idris2 has the mirror-image bug (false-negative): `parse_string` parses -`main = putStrLn "ok"` but `export()` regenerates the body as `?main_todo` -(a hole), so `idris2 --check` always fails. See the generated file at -`/tmp/echidna_idris2/Verify.idr` after any Idris2 API call. - -**Fix direction:** -- `parse_string` should return `Err` on unrecognised input rather than - silently producing an empty state. -- `verify_proof` for each prover should either preserve original content - (write `content` directly, not `export(state)`) or treat an empty - `ProofState` as a parse failure. -- Add regression tests: `verify` on garbage, empty, cross-prover content - must all return `valid: false`. - -**Partial fix (2026-04-05):** server-level guard in `prove_handler` and -`verify_handler` now returns `valid: false` when `parse_string` produces -an empty `ProofState` (no goals, theorems, definitions, axioms, or variables) -on non-empty input. Verified live: - - garbage to Coq/Lean: `valid: false` (was `true`) - - cross-prover (SMT to Coq): `valid: false` - - real Coq/Z3 proofs: still work correctly -The deeper fix — making each prover backend preserve original content -instead of round-tripping through ProofState — remains outstanding. - -## Priority -- **CRG C COMPLETE** as of 2026-04-04 -- Next priority: Fix 5 shell issues found by validation -- zig prover testing remains the largest correctness gap but is out of scope - until the Coq corpus toolchain is set up in CI diff --git a/docs/academic/ACADEMIC_PAPER.adoc b/docs/academic/ACADEMIC_PAPER.adoc new file mode 100644 index 00000000..2011ff3c --- /dev/null +++ b/docs/academic/ACADEMIC_PAPER.adoc @@ -0,0 +1,476 @@ +== ECHIDNA: A Neurosymbolic Approach to Theorem Proving with Formal Soundness Guarantees + +*Jonathan D.A. Jewell* + +The Open University, UK + +j.d.a.jewell@open.ac.uk + +*Version:* 1.3.0 + +*Date:* January 29, 2026 + +*Status:* Production Implementation + +''''' + +=== Abstract + +We present ECHIDNA, a production-ready neurosymbolic theorem proving +system that combines machine learning-guided proof search with formal +verification across 12 established theorem provers. Unlike pure neural +approaches that can generate unsound proofs, ECHIDNA maintains a strict +separation: neural networks suggest tactics, but all proofs must be +verified by symbolic provers. This architecture guarantees soundness +while benefiting from learned heuristics. + +Our key contributions are: (1) A multi-backend architecture supporting +12 theorem provers with unified HTTP/REST interfaces, (2) A +comprehensive trust framework including benchmarking, property-based +testing, dependent-type validation, and anomaly detection, (3) Automated +training data extraction from 332 proofs yielding 1,603 tactic examples, +(4) Production deployment demonstrating 65% top-1 and 85% top-3 accuracy +in tactic prediction, and (5) Empirical validation of optional parallel +proof search using Chapel coforall parallelism. + +ECHIDNA achieves the benefits of neurosymbolic AI—learning from data +while maintaining formal correctness—in a real-world theorem proving +application. The system is open-source (MIT/PMPL-1.0) and +production-ready. + +*Keywords:* Neurosymbolic AI, Theorem Proving, Machine Learning, Formal +Verification, Interactive Proof Assistants + +''''' + +=== 1. Introduction + +==== 1.1 Motivation + +Automated and interactive theorem proving faces a fundamental tension: +human-guided proofs are reliable but tedious, while automated approaches +can be fast but may produce unsound results. Recent advances in machine +learning for theorem proving [1,2,3] have shown promising results in +tactic prediction and premise selection, but these approaches often lack +formal guarantees. + +The neurosymbolic AI paradigm [4,5] offers a solution: combine neural +learning with symbolic reasoning to get the best of both worlds. +However, most neurosymbolic systems remain research prototypes. We +address this gap with ECHIDNA, a production-ready system that +demonstrates neurosymbolic theorem proving at scale. + +==== 1.2 Problem Statement + +Given a proof goal G and a set of available theorem provers P = \{p₁, …, +pₙ}, we seek to: + +[arabic] +. *Predict* likely successful tactics T = \{t₁, …, tₖ} using learned +models +. *Verify* each predicted tactic tᵢ using symbolic prover pⱼ +. *Guarantee* soundness: no false proofs accepted +. *Optimize* for human time (minimize interaction) not machine time + +Formally: ∀G, ∀t ∈ Predicted(G), Verify(t, G, P) ⇒ Sound(Proof(G,t)) + +==== 1.3 Contributions + +[arabic] +. *Architecture:* Multi-backend neurosymbolic system with 12 theorem +provers (Section 3) +. *Trust Framework:* Four-layer validation ensuring soundness (Section +4) +. *Training Data:* Automated extraction methodology from proof files +(Section 5) +. *Empirical Results:* Production deployment with measured accuracy +(Section 6) +. *Parallel Search:* Chapel-based optional parallelism for multi-prover +consensus (Section 7) + +''''' + +=== 2. Related Work + +==== 2.1 Machine Learning for Theorem Proving + +*Neural Tactic Prediction:* Kaliszyk et al. [1] pioneered deep learning +for theorem proving in HOL Light. Polu & Sutskever [2] demonstrated +GPT-based proof search in Lean. First et al. [3] used deep RL for tactic +synthesis in Coq. + +*Premise Selection:* Alemi et al. [6] used neural networks for premise +selection in Metamath. Wang et al. [7] applied graph neural networks to +proof search. + +*Limitations:* These approaches lack formal soundness guarantees. A +neural model can hallucinate plausible-looking but incorrect proofs. + +==== 2.2 Neurosymbolic AI + +Garcez et al. [4] identified neurosymbolic AI as combining +"`sub-symbolic (neural) learning with symbolic reasoning.`" Lamb et +al. [5] demonstrated graph neural networks for theorem proving with +logical constraints. + +*ECHIDNA’s Position:* We implement the neurosymbolic paradigm strictly: +neural models only suggest, symbolic provers always verify. + +==== 2.3 Multi-Prover Systems + +Blanchette et al. [8] combined SMT solvers (Z3, CVC4) with Isabelle. +Paulson [9] integrated multiple ATP systems in Isabelle/HOL. + +*ECHIDNA’s Innovation:* We support 12 diverse provers (dependent types, +HOL, SMT) with a unified ML-guided interface. + +''''' + +=== 3. System Architecture + +==== 3.1 Overview + +ECHIDNA uses a three-layer architecture: + +.... +Layer 1 (UI): AffineScript/React browser interface +Layer 2 (Core): Rust HTTP server with prover orchestration +Layer 3 (ML): Julia ML API serving trained models +Layer 4 (Provers): 12 theorem prover backends (stdio) +.... + +Communication via HTTP/REST ensures language-agnostic boundaries and +independent scaling. + +==== 3.2 Prover Backends + +We support 12 theorem provers across three tiers: + +*Tier 1 (Interactive):* - Coq 8.18+ (dependent types, Calculus of +Inductive Constructions) - Lean 4 (dependent types, extensive mathlib) - +Isabelle/HOL (higher-order logic, Archive of Formal Proofs) - Agda 2.6+ +(dependently typed programming) + +*Tier 2 (SMT):* - Z3 (Microsoft Research, SMT-LIB 2.6) - CVC5 (SMT +solver with theories) + +*Tier 3 (Specialized):* - ACL2 (industrial verification, Common Lisp) - +PVS (aerospace, hardware verification) - HOL4 (UK defense applications) +- Mizar (natural language proofs) - HOL Light (minimalist HOL) - +Metamath (tiny verifier, high confidence) + +*Integration:* Uniform stdio/stdout protocol with prover-specific +parsers. + +==== 3.3 Neural Model (MVP) + +*Current (v1.3):* Logistic regression with bag-of-words encoding - +Input: Goal text → tokenize → vocabulary lookup → frequency vector - +Model: Multinomial logistic regression (8 tactic classes) - Output: +Softmax probability distribution over tactics + +*Training Data:* 332 proofs, 1,603 tactics, 161 vocabulary words + +*Performance:* 65% top-1 accuracy, 85% top-3 accuracy (sufficient for +guidance) + +*Future (v2.0):* Transformer models, premise selection, proof step +generation + +==== 3.4 REST API + +*Endpoints (13 total):* - `+GET /api/health+` - Service health - +`+GET /api/provers+` - List available provers - +`+POST /api/tactics/suggest+` - Get ML tactic suggestions - +`+POST /api/session/create+` - Create proof session - +`+GET /api/session/:id/state+` - Get proof state - +`+POST /api/session/:id/apply+` - Apply tactic - +`+GET /api/session/:id/tree+` - Get proof tree - +`+GET /api/aspect-tags+` - Get domain/technique tags - +`+GET /api/theorems/search+` - Search theorem library + +*Authentication:* None (localhost development), OAuth planned for +production + +''''' + +=== 4. Trust Framework + +To address concerns about "`LLM hallucination,`" we implement four +validation layers: + +==== 4.1 Performance Benchmarking + +*Tool:* Criterion.rs (statistical benchmarking) + +*Metrics:* - Proof search time - ML inference latency + +- Parser performance - Proof tree construction + +*Purpose:* Detect performance regressions in CI/CD + +==== 4.2 Property-Based Testing + +*Tool:* PropTest (Rust property testing framework) + +*Invariants (8 total):* 1. Confidence bounds: 0.0 ≤ confidence(g, t) ≤ +1.0 2. Roundtrip: encode(decode(x)) = x 3. Deterministic: predict(g) = +predict(g) (same input → same output) 4. Tactic validity: ∀t ∈ +suggestions(g), applicable(t, g) 5. Goal reduction: apply(t, g) ⇒ +subgoals(g’) ⊂ g 6. Premise relevance: premises(t) ⊆ context(g) 7. No +circular reasoning: conclusion ∉ premises 8. Proof tree coherence: +children(node) prove parent(node) + +*Test Cases:* 1000 generated per invariant = 8000 total tests + +==== 4.3 Formal Verification (Idris2) + +*Implementation:* Dependent-typed proof validator in Idris2 + +*Key Components:* - `+ProofTerm.idr+`: AST for dependent type theory +proofs - `+Validator.idr+`: Type checker with totality guarantee - +`+Soundness.idr+`: Formal soundness theorem (signature) + +*Theorem:* ∀p : ProofTerm, validate(p) = Valid ⇒ sound(p) + +*Guarantee:* Total functions (guaranteed termination), detects: - Type +mismatches - Circular reasoning + +- Invalid tactic applications + +==== 4.4 Anomaly Detection + +*System:* Runtime monitoring for ML prediction failures + +*Anomaly Types (7):* 1. Unusually high confidence on complex theorems +(>95% confidence, complexity > threshold) 2. Multi-prover disagreement +(provers disagree on provability) 3. Circular reasoning (goal appears in +premises) 4. Excessive complexity (too many tactics for simple theorem) +5. Type mismatches (premise type ≠ goal type) 6. Invalid tactic +sequences (tactic doesn’t apply to state) 7. Anomalous proof times (too +fast or too slow) + +*Multi-Prover Consensus:* Configurable threshold (e.g., require 3/12 +provers agree) + +''''' + +=== 5. Training Data Collection + +==== 5.1 Extraction Methodology + +*Source:* Proof assistant source files (.v, .lean, .idr, .agda, .smt2, +etc.) + +*Process:* 1. Parse proof file to extract theorems 2. For each proof +script, extract (goal, tactic, premises) triples 3. Normalize tactic +names across provers 4. Build vocabulary from all unique terms 5. Label +with prover and proof metadata + +*Challenges:* - Prover-specific syntax variations - Implicit tactics +(auto, trivial) - Macro expansion + +==== 5.2 Corpus Statistics + +*v1.3 Corpus:* - 332 total proofs (+210% from v1.1) - 1,603 tactic +applications (+174%) - 161 unique vocabulary terms (+160%) + +*Prover Distribution (balanced):* - Lean: 40% - Coq: 22% - Agda: 14% - +HOL4: 9% - Mizar: 9% - PVS: 5% - Isabelle: 1% + +*Goal:* Avoid imbalance (v1.1 had 69% Coq) + +==== 5.3 Quality Control + +* Manual review of parsed examples +* Cross-validation: train on 80%, validate on 20% +* Ablation studies: remove prover X, measure accuracy drop + +''''' + +=== 6. Empirical Evaluation + +==== 6.1 Experimental Setup + +*Hardware:* - CPU: AMD Ryzen 9 5950X (16 cores) - RAM: 64GB DDR4 - +Storage: NVMe SSD + +*Software:* - Rust 1.75, Julia 1.13, Python 3.14 - Provers: Latest +stable versions (Coq 8.18, Lean 4.4, etc.) + +==== 6.2 Tactic Prediction Accuracy + +*Method:* 5-fold cross-validation on 332 proofs + +*Results:* | Metric | Score | |——–|——-| | Top-1 Accuracy | 65.2% | | +Top-3 Accuracy | 84.7% | | Top-5 Accuracy | 91.3% | | Mean Reciprocal +Rank | 0.74 | + +*Interpretation:* Model suggests correct tactic in top-3 for 85% of +goals. + +==== 6.3 Performance Metrics + +[cols=",,",options="header",] +|=== +|Operation |Time (ms) |Notes +|Model load (Julia) |200 |One-time startup +|ML inference |5 |Per prediction +|Rust API call |8 |Including ML roundtrip +|Full UI roundtrip |15-20 |Browser → Rust → Julia → back +|Proof search (simple) |50 |Average for n+0=n +|=== + +*Bottleneck Analysis:* Prover execution dominates (varies by theorem +complexity). + +==== 6.4 Integration Tests + +*Test Suite:* 8 end-to-end scenarios 1. Julia ML API health 2. Rust +backend health 3. List 12 available provers 4. Julia ML tactic +suggestions (direct) 5. Rust → Julia integration 6. Create proof session +7. Get aspect tags 8. UI dev server responsive + +*Status:* 100% passing (v1.3.0) + +''''' + +=== 7. Parallel Proof Search + +==== 7.1 Chapel Implementation + +*Motivation:* Search across all 12 provers simultaneously for: - Faster +proof discovery - Multi-prover consensus validation - Proof quality +selection (choose shortest/fastest) + +*Implementation:* Chapel coforall for task parallelism + +[source,chapel] +---- +coforall i in 1..12 { + results[i] = prover[i].search(goal, timeout); +} +// Wait for first success or all failures +---- + +*Results (Proof-of-Concept):* - 9/12 provers succeeded in parallel - +Shortest proof: PVS (4 tactics) - Robustness: HOL4 succeeded as fallback +(1.41s) + +==== 7.2 Design Choice: Optional + +Chapel made optional via: 1. Rust feature flag: +`+--features chapel-parallel+` 2. Trait abstraction: +`+ProofSearchStrategy+` trait 3. Fallback: Sequential search if Chapel +unavailable + +*Rationale:* Not everyone needs parallelism, Chapel installation +complex. + +''''' + +=== 8. Limitations and Future Work + +==== 8.1 Current Limitations + +[arabic] +. *Simple ML Model:* Bag-of-words loses structure, logistic regression +limited +. *No Premise Selection:* Current model doesn’t suggest premises +(planned v2.0) +. *Limited Proof Explanation:* Suggestions lack natural language +justification +. *Training Data Size:* 332 proofs small compared to Mathlib (100K+ +theorems) + +==== 8.2 Future Directions + +*v2.0 (Planned Q4 2026):* - Transformer models (attention over proof +terms) - Neural premise selection - Proof step generation (beyond tactic +suggestion) - OpenCyc integration for domain knowledge + +*v3.0 (2027):* - Automated theorem discovery (conjecture generation) - +Proof repair for failing attempts - Natural language proof explanations +- Cloud deployment with GPU acceleration + +''''' + +=== 9. Conclusion + +We have presented ECHIDNA, a production-ready neurosymbolic theorem +proving system that combines machine learning with formal verification +across 12 theorem provers. Our key insight is strict separation: neural +models suggest, symbolic provers verify. This architecture guarantees +soundness while benefiting from learned heuristics. + +Our contributions include: (1) Multi-backend architecture with 12 +provers, (2) Comprehensive trust framework with four validation layers, +(3) Automated training data extraction methodology, (4) Production +deployment with measured 65% top-1 accuracy, and (5) Optional parallel +proof search using Chapel. + +ECHIDNA demonstrates that neurosymbolic AI is not merely a research +concept but a viable approach for production theorem proving. The system +is open-source and ready for community adoption. + +''''' + +=== References + +[1] Kaliszyk, C., Chollet, F., & Szegedy, C. (2017). HolStep: A machine +learning dataset for higher-order logic theorem proving. _ICLR 2017_. + +[2] Polu, S., & Sutskever, I. (2020). Generative language modeling for +automated theorem proving. _arXiv:2009.03393_. + +[3] First, E., Brun, Y., & Guha, A. (2020). TacticZero: Learning to +prove theorems from scratch with deep reinforcement learning. _NeurIPS +2020_. + +[4] Garcez, A. d’Avila, et al. (2019). Neurosymbolic AI: The 3rd wave. +_arXiv:2012.05876_. + +[5] Lamb, L. C., et al. (2020). Graph neural networks for theorem +proving. _AAAI 2020_. + +[6] Alemi, A., et al. (2016). DeepMath: Deep sequence models for premise +selection. _NIPS 2016_. + +[7] Wang, M., et al. (2017). Premise selection for theorem proving by +deep graph embedding. _NIPS 2017_. + +[8] Blanchette, J. C., Böhme, S., & Paulson, L. C. (2013). Extending +Sledgehammer with SMT solvers. _JAR 2013_. + +[9] Paulson, L. C. (1999). Generic automatic proof tools. _CADE-16_. + +''''' + +=== Appendix A: Soundness Theorem (Sketch) + +*Theorem (Soundness):* If ECHIDNA accepts a proof P of goal G, then P is +valid under the proof theory of prover backend B. + +*Proof Sketch:* 1. ECHIDNA suggests tactics T = \{t₁, …, tₖ} using ML +model M 2. For each tᵢ ∈ T, ECHIDNA calls prover backend B 3. B either +accepts or rejects tᵢ 4. ECHIDNA only reports success if B accepts 5. +Since B is a trusted theorem prover, B.accept(tᵢ) ⇒ valid(tᵢ) (by B’s +soundness) 6. Therefore, ECHIDNA.accept(P) ⇒ valid(P) + +*Key Insight:* We never trust ML predictions directly. All verification +goes through established provers. + +''''' + +=== Appendix B: Open-Source Availability + +*Repository:* https://github.com/hyperpolymath/echidna + +*License:* MIT OR Palimpsest-1.0-or-later (dual license) + +*Installation:* See QUICKSTART.md in repository + +*Documentation:* - User guide: USER_GUIDE.md - Developer guide: +DEVELOPER_GUIDE.md + +- API reference: Rustdoc comments + +*Community:* GitHub Issues and Discussions + +''''' + +_This paper describes the ECHIDNA v1.3.0 production release (January +2026). For latest updates, see the GitHub repository._ diff --git a/docs/academic/ACADEMIC_PAPER.md b/docs/academic/ACADEMIC_PAPER.md deleted file mode 100644 index a24f4ef4..00000000 --- a/docs/academic/ACADEMIC_PAPER.md +++ /dev/null @@ -1,435 +0,0 @@ -# ECHIDNA: A Neurosymbolic Approach to Theorem Proving with Formal Soundness Guarantees - -**Jonathan D.A. Jewell** -The Open University, UK -j.d.a.jewell@open.ac.uk - -**Version:** 1.3.0 -**Date:** January 29, 2026 -**Status:** Production Implementation - ---- - -## Abstract - -We present ECHIDNA, a production-ready neurosymbolic theorem proving system that combines machine learning-guided proof search with formal verification across 12 established theorem provers. Unlike pure neural approaches that can generate unsound proofs, ECHIDNA maintains a strict separation: neural networks suggest tactics, but all proofs must be verified by symbolic provers. This architecture guarantees soundness while benefiting from learned heuristics. - -Our key contributions are: (1) A multi-backend architecture supporting 12 theorem provers with unified HTTP/REST interfaces, (2) A comprehensive trust framework including benchmarking, property-based testing, dependent-type validation, and anomaly detection, (3) Automated training data extraction from 332 proofs yielding 1,603 tactic examples, (4) Production deployment demonstrating 65% top-1 and 85% top-3 accuracy in tactic prediction, and (5) Empirical validation of optional parallel proof search using Chapel coforall parallelism. - -ECHIDNA achieves the benefits of neurosymbolic AI—learning from data while maintaining formal correctness—in a real-world theorem proving application. The system is open-source (MIT/PMPL-1.0) and production-ready. - -**Keywords:** Neurosymbolic AI, Theorem Proving, Machine Learning, Formal Verification, Interactive Proof Assistants - ---- - -## 1. Introduction - -### 1.1 Motivation - -Automated and interactive theorem proving faces a fundamental tension: human-guided proofs are reliable but tedious, while automated approaches can be fast but may produce unsound results. Recent advances in machine learning for theorem proving [1,2,3] have shown promising results in tactic prediction and premise selection, but these approaches often lack formal guarantees. - -The neurosymbolic AI paradigm [4,5] offers a solution: combine neural learning with symbolic reasoning to get the best of both worlds. However, most neurosymbolic systems remain research prototypes. We address this gap with ECHIDNA, a production-ready system that demonstrates neurosymbolic theorem proving at scale. - -### 1.2 Problem Statement - -Given a proof goal G and a set of available theorem provers P = {p₁, ..., pₙ}, we seek to: - -1. **Predict** likely successful tactics T = {t₁, ..., tₖ} using learned models -2. **Verify** each predicted tactic tᵢ using symbolic prover pⱼ -3. **Guarantee** soundness: no false proofs accepted -4. **Optimize** for human time (minimize interaction) not machine time - -Formally: ∀G, ∀t ∈ Predicted(G), Verify(t, G, P) ⇒ Sound(Proof(G,t)) - -### 1.3 Contributions - -1. **Architecture:** Multi-backend neurosymbolic system with 12 theorem provers (Section 3) -2. **Trust Framework:** Four-layer validation ensuring soundness (Section 4) -3. **Training Data:** Automated extraction methodology from proof files (Section 5) -4. **Empirical Results:** Production deployment with measured accuracy (Section 6) -5. **Parallel Search:** Chapel-based optional parallelism for multi-prover consensus (Section 7) - ---- - -## 2. Related Work - -### 2.1 Machine Learning for Theorem Proving - -**Neural Tactic Prediction:** Kaliszyk et al. [1] pioneered deep learning for theorem proving in HOL Light. Polu & Sutskever [2] demonstrated GPT-based proof search in Lean. First et al. [3] used deep RL for tactic synthesis in Coq. - -**Premise Selection:** Alemi et al. [6] used neural networks for premise selection in Metamath. Wang et al. [7] applied graph neural networks to proof search. - -**Limitations:** These approaches lack formal soundness guarantees. A neural model can hallucinate plausible-looking but incorrect proofs. - -### 2.2 Neurosymbolic AI - -Garcez et al. [4] identified neurosymbolic AI as combining "sub-symbolic (neural) learning with symbolic reasoning." Lamb et al. [5] demonstrated graph neural networks for theorem proving with logical constraints. - -**ECHIDNA's Position:** We implement the neurosymbolic paradigm strictly: neural models only suggest, symbolic provers always verify. - -### 2.3 Multi-Prover Systems - -Blanchette et al. [8] combined SMT solvers (Z3, CVC4) with Isabelle. Paulson [9] integrated multiple ATP systems in Isabelle/HOL. - -**ECHIDNA's Innovation:** We support 12 diverse provers (dependent types, HOL, SMT) with a unified ML-guided interface. - ---- - -## 3. System Architecture - -### 3.1 Overview - -ECHIDNA uses a three-layer architecture: - -``` -Layer 1 (UI): AffineScript/React browser interface -Layer 2 (Core): Rust HTTP server with prover orchestration -Layer 3 (ML): Julia ML API serving trained models -Layer 4 (Provers): 12 theorem prover backends (stdio) -``` - -Communication via HTTP/REST ensures language-agnostic boundaries and independent scaling. - -### 3.2 Prover Backends - -We support 12 theorem provers across three tiers: - -**Tier 1 (Interactive):** -- Coq 8.18+ (dependent types, Calculus of Inductive Constructions) -- Lean 4 (dependent types, extensive mathlib) -- Isabelle/HOL (higher-order logic, Archive of Formal Proofs) -- Agda 2.6+ (dependently typed programming) - -**Tier 2 (SMT):** -- Z3 (Microsoft Research, SMT-LIB 2.6) -- CVC5 (SMT solver with theories) - -**Tier 3 (Specialized):** -- ACL2 (industrial verification, Common Lisp) -- PVS (aerospace, hardware verification) -- HOL4 (UK defense applications) -- Mizar (natural language proofs) -- HOL Light (minimalist HOL) -- Metamath (tiny verifier, high confidence) - -**Integration:** Uniform stdio/stdout protocol with prover-specific parsers. - -### 3.3 Neural Model (MVP) - -**Current (v1.3):** Logistic regression with bag-of-words encoding -- Input: Goal text → tokenize → vocabulary lookup → frequency vector -- Model: Multinomial logistic regression (8 tactic classes) -- Output: Softmax probability distribution over tactics - -**Training Data:** 332 proofs, 1,603 tactics, 161 vocabulary words - -**Performance:** 65% top-1 accuracy, 85% top-3 accuracy (sufficient for guidance) - -**Future (v2.0):** Transformer models, premise selection, proof step generation - -### 3.4 REST API - -**Endpoints (13 total):** -- `GET /api/health` - Service health -- `GET /api/provers` - List available provers -- `POST /api/tactics/suggest` - Get ML tactic suggestions -- `POST /api/session/create` - Create proof session -- `GET /api/session/:id/state` - Get proof state -- `POST /api/session/:id/apply` - Apply tactic -- `GET /api/session/:id/tree` - Get proof tree -- `GET /api/aspect-tags` - Get domain/technique tags -- `GET /api/theorems/search` - Search theorem library - -**Authentication:** None (localhost development), OAuth planned for production - ---- - -## 4. Trust Framework - -To address concerns about "LLM hallucination," we implement four validation layers: - -### 4.1 Performance Benchmarking - -**Tool:** Criterion.rs (statistical benchmarking) - -**Metrics:** -- Proof search time -- ML inference latency -- Parser performance -- Proof tree construction - -**Purpose:** Detect performance regressions in CI/CD - -### 4.2 Property-Based Testing - -**Tool:** PropTest (Rust property testing framework) - -**Invariants (8 total):** -1. Confidence bounds: 0.0 ≤ confidence(g, t) ≤ 1.0 -2. Roundtrip: encode(decode(x)) = x -3. Deterministic: predict(g) = predict(g) (same input → same output) -4. Tactic validity: ∀t ∈ suggestions(g), applicable(t, g) -5. Goal reduction: apply(t, g) ⇒ subgoals(g') ⊂ g -6. Premise relevance: premises(t) ⊆ context(g) -7. No circular reasoning: conclusion ∉ premises -8. Proof tree coherence: children(node) prove parent(node) - -**Test Cases:** 1000 generated per invariant = 8000 total tests - -### 4.3 Formal Verification (Idris2) - -**Implementation:** Dependent-typed proof validator in Idris2 - -**Key Components:** -- `ProofTerm.idr`: AST for dependent type theory proofs -- `Validator.idr`: Type checker with totality guarantee -- `Soundness.idr`: Formal soundness theorem (signature) - -**Theorem:** ∀p : ProofTerm, validate(p) = Valid ⇒ sound(p) - -**Guarantee:** Total functions (guaranteed termination), detects: -- Type mismatches -- Circular reasoning -- Invalid tactic applications - -### 4.4 Anomaly Detection - -**System:** Runtime monitoring for ML prediction failures - -**Anomaly Types (7):** -1. Unusually high confidence on complex theorems (>95% confidence, complexity > threshold) -2. Multi-prover disagreement (provers disagree on provability) -3. Circular reasoning (goal appears in premises) -4. Excessive complexity (too many tactics for simple theorem) -5. Type mismatches (premise type ≠ goal type) -6. Invalid tactic sequences (tactic doesn't apply to state) -7. Anomalous proof times (too fast or too slow) - -**Multi-Prover Consensus:** Configurable threshold (e.g., require 3/12 provers agree) - ---- - -## 5. Training Data Collection - -### 5.1 Extraction Methodology - -**Source:** Proof assistant source files (.v, .lean, .idr, .agda, .smt2, etc.) - -**Process:** -1. Parse proof file to extract theorems -2. For each proof script, extract (goal, tactic, premises) triples -3. Normalize tactic names across provers -4. Build vocabulary from all unique terms -5. Label with prover and proof metadata - -**Challenges:** -- Prover-specific syntax variations -- Implicit tactics (auto, trivial) -- Macro expansion - -### 5.2 Corpus Statistics - -**v1.3 Corpus:** -- 332 total proofs (+210% from v1.1) -- 1,603 tactic applications (+174%) -- 161 unique vocabulary terms (+160%) - -**Prover Distribution (balanced):** -- Lean: 40% -- Coq: 22% -- Agda: 14% -- HOL4: 9% -- Mizar: 9% -- PVS: 5% -- Isabelle: 1% - -**Goal:** Avoid imbalance (v1.1 had 69% Coq) - -### 5.3 Quality Control - -- Manual review of parsed examples -- Cross-validation: train on 80%, validate on 20% -- Ablation studies: remove prover X, measure accuracy drop - ---- - -## 6. Empirical Evaluation - -### 6.1 Experimental Setup - -**Hardware:** -- CPU: AMD Ryzen 9 5950X (16 cores) -- RAM: 64GB DDR4 -- Storage: NVMe SSD - -**Software:** -- Rust 1.75, Julia 1.13, Python 3.14 -- Provers: Latest stable versions (Coq 8.18, Lean 4.4, etc.) - -### 6.2 Tactic Prediction Accuracy - -**Method:** 5-fold cross-validation on 332 proofs - -**Results:** -| Metric | Score | -|--------|-------| -| Top-1 Accuracy | 65.2% | -| Top-3 Accuracy | 84.7% | -| Top-5 Accuracy | 91.3% | -| Mean Reciprocal Rank | 0.74 | - -**Interpretation:** Model suggests correct tactic in top-3 for 85% of goals. - -### 6.3 Performance Metrics - -| Operation | Time (ms) | Notes | -|-----------|-----------|-------| -| Model load (Julia) | 200 | One-time startup | -| ML inference | 5 | Per prediction | -| Rust API call | 8 | Including ML roundtrip | -| Full UI roundtrip | 15-20 | Browser → Rust → Julia → back | -| Proof search (simple) | 50 | Average for n+0=n | - -**Bottleneck Analysis:** Prover execution dominates (varies by theorem complexity). - -### 6.4 Integration Tests - -**Test Suite:** 8 end-to-end scenarios -1. Julia ML API health -2. Rust backend health -3. List 12 available provers -4. Julia ML tactic suggestions (direct) -5. Rust → Julia integration -6. Create proof session -7. Get aspect tags -8. UI dev server responsive - -**Status:** 100% passing (v1.3.0) - ---- - -## 7. Parallel Proof Search - -### 7.1 Chapel Implementation - -**Motivation:** Search across all 12 provers simultaneously for: -- Faster proof discovery -- Multi-prover consensus validation -- Proof quality selection (choose shortest/fastest) - -**Implementation:** Chapel coforall for task parallelism - -```chapel -coforall i in 1..12 { - results[i] = prover[i].search(goal, timeout); -} -// Wait for first success or all failures -``` - -**Results (Proof-of-Concept):** -- 9/12 provers succeeded in parallel -- Shortest proof: PVS (4 tactics) -- Robustness: HOL4 succeeded as fallback (1.41s) - -### 7.2 Design Choice: Optional - -Chapel made optional via: -1. Rust feature flag: `--features chapel-parallel` -2. Trait abstraction: `ProofSearchStrategy` trait -3. Fallback: Sequential search if Chapel unavailable - -**Rationale:** Not everyone needs parallelism, Chapel installation complex. - ---- - -## 8. Limitations and Future Work - -### 8.1 Current Limitations - -1. **Simple ML Model:** Bag-of-words loses structure, logistic regression limited -2. **No Premise Selection:** Current model doesn't suggest premises (planned v2.0) -3. **Limited Proof Explanation:** Suggestions lack natural language justification -4. **Training Data Size:** 332 proofs small compared to Mathlib (100K+ theorems) - -### 8.2 Future Directions - -**v2.0 (Planned Q4 2026):** -- Transformer models (attention over proof terms) -- Neural premise selection -- Proof step generation (beyond tactic suggestion) -- OpenCyc integration for domain knowledge - -**v3.0 (2027):** -- Automated theorem discovery (conjecture generation) -- Proof repair for failing attempts -- Natural language proof explanations -- Cloud deployment with GPU acceleration - ---- - -## 9. Conclusion - -We have presented ECHIDNA, a production-ready neurosymbolic theorem proving system that combines machine learning with formal verification across 12 theorem provers. Our key insight is strict separation: neural models suggest, symbolic provers verify. This architecture guarantees soundness while benefiting from learned heuristics. - -Our contributions include: (1) Multi-backend architecture with 12 provers, (2) Comprehensive trust framework with four validation layers, (3) Automated training data extraction methodology, (4) Production deployment with measured 65% top-1 accuracy, and (5) Optional parallel proof search using Chapel. - -ECHIDNA demonstrates that neurosymbolic AI is not merely a research concept but a viable approach for production theorem proving. The system is open-source and ready for community adoption. - ---- - -## References - -[1] Kaliszyk, C., Chollet, F., & Szegedy, C. (2017). HolStep: A machine learning dataset for higher-order logic theorem proving. *ICLR 2017*. - -[2] Polu, S., & Sutskever, I. (2020). Generative language modeling for automated theorem proving. *arXiv:2009.03393*. - -[3] First, E., Brun, Y., & Guha, A. (2020). TacticZero: Learning to prove theorems from scratch with deep reinforcement learning. *NeurIPS 2020*. - -[4] Garcez, A. d'Avila, et al. (2019). Neurosymbolic AI: The 3rd wave. *arXiv:2012.05876*. - -[5] Lamb, L. C., et al. (2020). Graph neural networks for theorem proving. *AAAI 2020*. - -[6] Alemi, A., et al. (2016). DeepMath: Deep sequence models for premise selection. *NIPS 2016*. - -[7] Wang, M., et al. (2017). Premise selection for theorem proving by deep graph embedding. *NIPS 2017*. - -[8] Blanchette, J. C., Böhme, S., & Paulson, L. C. (2013). Extending Sledgehammer with SMT solvers. *JAR 2013*. - -[9] Paulson, L. C. (1999). Generic automatic proof tools. *CADE-16*. - ---- - -## Appendix A: Soundness Theorem (Sketch) - -**Theorem (Soundness):** If ECHIDNA accepts a proof P of goal G, then P is valid under the proof theory of prover backend B. - -**Proof Sketch:** -1. ECHIDNA suggests tactics T = {t₁, ..., tₖ} using ML model M -2. For each tᵢ ∈ T, ECHIDNA calls prover backend B -3. B either accepts or rejects tᵢ -4. ECHIDNA only reports success if B accepts -5. Since B is a trusted theorem prover, B.accept(tᵢ) ⇒ valid(tᵢ) (by B's soundness) -6. Therefore, ECHIDNA.accept(P) ⇒ valid(P) - -**Key Insight:** We never trust ML predictions directly. All verification goes through established provers. - ---- - -## Appendix B: Open-Source Availability - -**Repository:** https://github.com/hyperpolymath/echidna - -**License:** MIT OR Palimpsest-1.0-or-later (dual license) - -**Installation:** See QUICKSTART.md in repository - -**Documentation:** -- User guide: USER_GUIDE.md -- Developer guide: DEVELOPER_GUIDE.md -- API reference: Rustdoc comments - -**Community:** GitHub Issues and Discussions - ---- - -*This paper describes the ECHIDNA v1.3.0 production release (January 2026). For latest updates, see the GitHub repository.* diff --git a/docs/architecture/CHAPEL-SATURATION-HOOKS.adoc b/docs/architecture/CHAPEL-SATURATION-HOOKS.adoc new file mode 100644 index 00000000..87d4270f --- /dev/null +++ b/docs/architecture/CHAPEL-SATURATION-HOOKS.adoc @@ -0,0 +1,211 @@ +== Chapel ↔ Saturation Campaign Integration Hooks + +*Status*: hook spec, not implementation. *Last revised*: 2026-06-01. +*Why this file exists separately*: the saturation campaign (commits +`+f73ee00..cb8caff+` on `+prover-corpus-saturation+`) lands in a lane +that deliberately excludes `+src/chapel/**+` — that tree is owned by +`+wave3/161-162-bench-telemetry-corpus+`. This file specifies how the +Chapel parallel-proof-search layer SHOULD integrate with the campaign’s +new surface AFTER wave3 lands, without pre-empting wave3’s edits. + +=== What changed that Chapel can benefit from + +Three new surfaces are now first-class in the Rust core: + +[arabic] +. *17 corpus adapters* +(`+src/rust/corpus/{agda,coq,lean,idris2,isabelle,metamath,mizar,hol_light,hol4,dafny,why3,fstar,acl2_books,tptp,smtlib,proofnet,minif2f}.rs+`). +Each emits a `+Corpus+` value with structured `+CorpusEntry+` rows + +dependency edges. +. *4-mechanism arbitration stack* +(`+src/rust/verification/{portfolio,bayesian_arbiter,dempster_shafer,pareto_arbiter}.rs+`). +Replaces the prior single-mechanism majority-vote. +. *Cross-prover semantic index* via `+data/synonyms/_msc2020.toml+`, +`+_wordnet_math.toml+`, `+_conceptnet_seed.toml+` plus the per-prover +tables. Resolved via `+SynonymTable::merge_external()+` +(`+src/rust/suggest/synonyms.rs+`). + +The Chapel parallel-proof-search dispatcher +(`+src/chapel/parallel_proof_search.chpl+`) currently: - Spawns N prover +invocations in parallel across locales. - Aggregates outcomes via +`+parallelProofSearch+` (best-of) or `+parallelProofSearchSpeculative+` +(first-success-wins atomic-CAS). - L2.3 (cancel-token preemption) lands +in the wave3 branch. + +=== Integration topology (proposed) + +.... + ┌─────────────────────────────────────────────────────────┐ + │ Saturation campaign surface (this branch) │ + │ │ + │ Corpus adapters → Corpus JSON │ + │ Synonym tables → SynonymTable + CrossProverDicts │ + │ Arbiters → bayesian / dempster_shafer / pareto │ + └────────────────────┬────────────────────────────────────┘ + │ + ▼ (Zig FFI shim) + ┌─────────────────────────────────────────────────────────┐ + │ Chapel parallel proof search (wave3) │ + │ │ + │ parallelProofSearch(goals[, arbiter_kind]) │ + │ parallelProofSearchSpeculative(goals) │ + │ + new: cross_prover_query(goal, semantic_class) │ + └─────────────────────────────────────────────────────────┘ +.... + +=== Three concrete hook points + +==== Hook A — corpus-driven goal injection + +*What it enables*: instead of Chapel benching against the existing +`+training_data/premises_.jsonl+` files only, Chapel can pull a +fresh batch of goals from any of the 17 adapters via the Rust C FFI. + +*Surface contract* (Rust-side, already present): + +[source,rust] +---- +// src/rust/corpus/.rs +pub fn ingest(root: &Path) -> Result; +// src/rust/corpus/mod.rs +impl Corpus { + pub fn save_json(&self, path: &Path) -> Result<()>; + pub fn load_json(path: &Path) -> Result; +} +---- + +*Chapel-side wiring* (TODO post-wave3): + +[source,chapel] +---- +// src/chapel/corpus_bridge.chpl (NEW FILE — DEFERRED) +extern proc echidna_corpus_load_json(path: c_string): c_voidptr; +extern proc echidna_corpus_entries_count(c: c_voidptr): c_int; +extern proc echidna_corpus_entry_qualified(c: c_voidptr, i: c_int): c_string; +---- + +*Wave3 collision check*: `+src/chapel/corpus_bridge.chpl+` does NOT +exist on wave3; safe to add post-merge. + +==== Hook B — arbitration kind selection + +*What it enables*: Chapel callers pick which arbiter aggregates the N +parallel outcomes. Currently hard-coded to "`best-of`". + +*Surface contract* (Rust-side, already present): + +[source,rust] +---- +// src/rust/verification/bayesian_arbiter.rs +pub fn BayesianArbiter::new(prior_p_true: f64) -> Self; +pub fn BayesianArbiter::combine(&self, evidence: &[ProverEvidence]) -> PosteriorVerdict; + +// src/rust/verification/dempster_shafer.rs +pub fn DempsterShaferArbiter::new() -> Self; +pub fn DempsterShaferArbiter::submit(&mut self, prover: ProverKind, mass: MassFunction); +pub fn DempsterShaferArbiter::combine_all(&self) -> Result; + +// src/rust/verification/pareto_arbiter.rs +pub fn ParetoArbiter::new() -> Self; +pub fn ParetoArbiter::arbitrate(&self, outcomes: &[AttemptOutcome]) -> ParetoDecision; +---- + +*Chapel-side wiring* (TODO post-wave3): + +The signature of `+parallelProofSearch+` becomes: + +[source,chapel] +---- +proc parallelProofSearch(goals: [] Goal, kind: ArbiterKind = .BestOf): Outcome; + +enum ArbiterKind { + BestOf, // current behaviour + Bayesian, // call into bayesian_arbiter + DempsterShafer, // call into dempster_shafer + Pareto // call into pareto_arbiter (multi-objective) +} +---- + +The aggregator on the Rust side picks the right arbiter based on +`+kind+`. *Wave3 collision check*: `+parallelProofSearch+` is currently +modified in wave3 — this hook lands AFTER wave3 merges, in a separate PR +scoped to "`arbiter kind selection`". + +==== Hook C — cross-prover semantic indexing + +*What it enables*: parallel proof search across provers that have +distinct names for the same mathematical object (e.g. Coq +`+Nat.add_comm+` and Lean `+Nat.add_comm+` and Agda `++-comm+`). Chapel +can pick which prover to invoke based on `+cross_prover_identity_key+` +(E6 in the E-R schema). + +*Surface contract* (Rust-side, already present): + +[source,rust] +---- +// src/rust/corpus/mod.rs (cross-prover identity is part of GraphPayload) +pub struct GraphPayload { + pub cross_prover_identity_key: Option, + // ... +} +// src/rust/suggest/synonyms.rs +pub fn SynonymTable::by_semantic_class(&self, class: &str) -> Vec<&SynonymEntry>; +---- + +*Chapel-side wiring* (TODO post-wave3): + +[source,chapel] +---- +// src/chapel/cross_prover_dispatch.chpl (NEW FILE — DEFERRED) +proc dispatchToAllProversForConcept( + semanticClass: string, + goal: Goal +): [] Outcome { + // for each prover with at least one entry tagged `semanticClass`, + // invoke in parallel and arbitrate. +} +---- + +=== Hand-off contract + +When the wave3 branch is merged, the next chapel-side PR can take this +file as the integration spec: + +[arabic] +. Add `+src/chapel/corpus_bridge.chpl+` (Hook A) — ~50 LoC. +. Extend `+src/chapel/parallel_proof_search.chpl+` signature with the +`+ArbiterKind+` parameter (Hook B) — ~30 LoC plus ~50 LoC of per-kind +aggregator stubs that call out via Zig FFI to the Rust arbiters. +. Add `+src/chapel/cross_prover_dispatch.chpl+` (Hook C) — ~80 LoC. +. Update `+src/chapel/parallel_proof_search.chpl+` callers in +`+dispatch.rs::verify_proof_parallel+` to pick the arbiter kind based on +config (`+SaturationConfig+`). +. Add `+chapel-saturation+` feature to `+Cargo.toml+` gating the new +bridge files. + +Estimated total: ~200 LoC chapel, ~50 LoC Rust glue. No wave3 file +modified. + +=== What NOT to do + +* Do NOT pre-write any chapel file under `+src/chapel/+` in this branch. +* Do NOT modify `+dispatch.rs::verify_proof_parallel+` in this branch. +* Do NOT touch the existing Zig FFI shim +(`+src/zig_ffi/chapel_bridge.zig+`). +* Do NOT add the `+ArbiterKind+` enum in this branch — it goes in the +follow-up PR so the spec lives next to the implementation. + +The integration is deferred, not abandoned. This doc IS the spec. + +=== Cross-references + +* E-R schema (consumed by Hook C): +`+docs/architecture/VERISIM-ER-SCHEMA.md+` +* Corpus adapters (consumed by Hook A): `+docs/CORPUS-ADAPTERS.md+` +* Saturation ADR: `+docs/decisions/2026-06-01-saturation-campaign.md+` +* Handover (collision-avoidance contract): +`+docs/handover/PROVER-CORPUS-SATURATION-LANE.md+` +* Existing chapel rehabilitation ADR: +`+docs/decisions/2026-05-30-chapel-rehabilitation.md+` +* Existing chapel cancel-token ADR: +`+docs/decisions/2026-05-30-chapel-l23-cancel-token.md+` diff --git a/docs/architecture/CHAPEL-SATURATION-HOOKS.md b/docs/architecture/CHAPEL-SATURATION-HOOKS.md deleted file mode 100644 index 5fbce037..00000000 --- a/docs/architecture/CHAPEL-SATURATION-HOOKS.md +++ /dev/null @@ -1,191 +0,0 @@ - - -# Chapel ↔ Saturation Campaign Integration Hooks - -**Status**: hook spec, not implementation. -**Last revised**: 2026-06-01. -**Why this file exists separately**: the saturation campaign (commits -`f73ee00..cb8caff` on `prover-corpus-saturation`) lands in a lane that -deliberately excludes `src/chapel/**` — that tree is owned by -`wave3/161-162-bench-telemetry-corpus`. This file specifies how the -Chapel parallel-proof-search layer SHOULD integrate with the campaign's -new surface AFTER wave3 lands, without pre-empting wave3's edits. - -## What changed that Chapel can benefit from - -Three new surfaces are now first-class in the Rust core: - -1. **17 corpus adapters** (`src/rust/corpus/{agda,coq,lean,idris2,isabelle,metamath,mizar,hol_light,hol4,dafny,why3,fstar,acl2_books,tptp,smtlib,proofnet,minif2f}.rs`). Each emits a `Corpus` value with structured `CorpusEntry` rows + dependency edges. -2. **4-mechanism arbitration stack** (`src/rust/verification/{portfolio,bayesian_arbiter,dempster_shafer,pareto_arbiter}.rs`). Replaces the prior single-mechanism majority-vote. -3. **Cross-prover semantic index** via `data/synonyms/_msc2020.toml`, `_wordnet_math.toml`, `_conceptnet_seed.toml` plus the per-prover tables. Resolved via `SynonymTable::merge_external()` (`src/rust/suggest/synonyms.rs`). - -The Chapel parallel-proof-search dispatcher -(`src/chapel/parallel_proof_search.chpl`) currently: -- Spawns N prover invocations in parallel across locales. -- Aggregates outcomes via `parallelProofSearch` (best-of) or - `parallelProofSearchSpeculative` (first-success-wins atomic-CAS). -- L2.3 (cancel-token preemption) lands in the wave3 branch. - -## Integration topology (proposed) - -``` - ┌─────────────────────────────────────────────────────────┐ - │ Saturation campaign surface (this branch) │ - │ │ - │ Corpus adapters → Corpus JSON │ - │ Synonym tables → SynonymTable + CrossProverDicts │ - │ Arbiters → bayesian / dempster_shafer / pareto │ - └────────────────────┬────────────────────────────────────┘ - │ - ▼ (Zig FFI shim) - ┌─────────────────────────────────────────────────────────┐ - │ Chapel parallel proof search (wave3) │ - │ │ - │ parallelProofSearch(goals[, arbiter_kind]) │ - │ parallelProofSearchSpeculative(goals) │ - │ + new: cross_prover_query(goal, semantic_class) │ - └─────────────────────────────────────────────────────────┘ -``` - -## Three concrete hook points - -### Hook A — corpus-driven goal injection - -**What it enables**: instead of Chapel benching against the existing -`training_data/premises_.jsonl` files only, Chapel can pull a -fresh batch of goals from any of the 17 adapters via the Rust C FFI. - -**Surface contract** (Rust-side, already present): -```rust -// src/rust/corpus/.rs -pub fn ingest(root: &Path) -> Result; -// src/rust/corpus/mod.rs -impl Corpus { - pub fn save_json(&self, path: &Path) -> Result<()>; - pub fn load_json(path: &Path) -> Result; -} -``` - -**Chapel-side wiring** (TODO post-wave3): -```chapel -// src/chapel/corpus_bridge.chpl (NEW FILE — DEFERRED) -extern proc echidna_corpus_load_json(path: c_string): c_voidptr; -extern proc echidna_corpus_entries_count(c: c_voidptr): c_int; -extern proc echidna_corpus_entry_qualified(c: c_voidptr, i: c_int): c_string; -``` - -**Wave3 collision check**: `src/chapel/corpus_bridge.chpl` does NOT -exist on wave3; safe to add post-merge. - -### Hook B — arbitration kind selection - -**What it enables**: Chapel callers pick which arbiter aggregates the -N parallel outcomes. Currently hard-coded to "best-of". - -**Surface contract** (Rust-side, already present): -```rust -// src/rust/verification/bayesian_arbiter.rs -pub fn BayesianArbiter::new(prior_p_true: f64) -> Self; -pub fn BayesianArbiter::combine(&self, evidence: &[ProverEvidence]) -> PosteriorVerdict; - -// src/rust/verification/dempster_shafer.rs -pub fn DempsterShaferArbiter::new() -> Self; -pub fn DempsterShaferArbiter::submit(&mut self, prover: ProverKind, mass: MassFunction); -pub fn DempsterShaferArbiter::combine_all(&self) -> Result; - -// src/rust/verification/pareto_arbiter.rs -pub fn ParetoArbiter::new() -> Self; -pub fn ParetoArbiter::arbitrate(&self, outcomes: &[AttemptOutcome]) -> ParetoDecision; -``` - -**Chapel-side wiring** (TODO post-wave3): - -The signature of `parallelProofSearch` becomes: -```chapel -proc parallelProofSearch(goals: [] Goal, kind: ArbiterKind = .BestOf): Outcome; - -enum ArbiterKind { - BestOf, // current behaviour - Bayesian, // call into bayesian_arbiter - DempsterShafer, // call into dempster_shafer - Pareto // call into pareto_arbiter (multi-objective) -} -``` - -The aggregator on the Rust side picks the right arbiter based on -`kind`. **Wave3 collision check**: `parallelProofSearch` is currently -modified in wave3 — this hook lands AFTER wave3 merges, in a separate -PR scoped to "arbiter kind selection". - -### Hook C — cross-prover semantic indexing - -**What it enables**: parallel proof search across provers that have -distinct names for the same mathematical object (e.g. Coq `Nat.add_comm` -and Lean `Nat.add_comm` and Agda `+-comm`). Chapel can pick which -prover to invoke based on `cross_prover_identity_key` (E6 in the E-R -schema). - -**Surface contract** (Rust-side, already present): -```rust -// src/rust/corpus/mod.rs (cross-prover identity is part of GraphPayload) -pub struct GraphPayload { - pub cross_prover_identity_key: Option, - // ... -} -// src/rust/suggest/synonyms.rs -pub fn SynonymTable::by_semantic_class(&self, class: &str) -> Vec<&SynonymEntry>; -``` - -**Chapel-side wiring** (TODO post-wave3): -```chapel -// src/chapel/cross_prover_dispatch.chpl (NEW FILE — DEFERRED) -proc dispatchToAllProversForConcept( - semanticClass: string, - goal: Goal -): [] Outcome { - // for each prover with at least one entry tagged `semanticClass`, - // invoke in parallel and arbitrate. -} -``` - -## Hand-off contract - -When the wave3 branch is merged, the next chapel-side PR can take this -file as the integration spec: - -1. Add `src/chapel/corpus_bridge.chpl` (Hook A) — ~50 LoC. -2. Extend `src/chapel/parallel_proof_search.chpl` signature with the - `ArbiterKind` parameter (Hook B) — ~30 LoC plus ~50 LoC of - per-kind aggregator stubs that call out via Zig FFI to the Rust - arbiters. -3. Add `src/chapel/cross_prover_dispatch.chpl` (Hook C) — ~80 LoC. -4. Update `src/chapel/parallel_proof_search.chpl` callers in - `dispatch.rs::verify_proof_parallel` to pick the arbiter kind based - on config (`SaturationConfig`). -5. Add `chapel-saturation` feature to `Cargo.toml` gating the new - bridge files. - -Estimated total: ~200 LoC chapel, ~50 LoC Rust glue. No wave3 file -modified. - -## What NOT to do - -- Do NOT pre-write any chapel file under `src/chapel/` in this branch. -- Do NOT modify `dispatch.rs::verify_proof_parallel` in this branch. -- Do NOT touch the existing Zig FFI shim (`src/zig_ffi/chapel_bridge.zig`). -- Do NOT add the `ArbiterKind` enum in this branch — it goes in the - follow-up PR so the spec lives next to the implementation. - -The integration is deferred, not abandoned. This doc IS the spec. - -## Cross-references - -- E-R schema (consumed by Hook C): `docs/architecture/VERISIM-ER-SCHEMA.md` -- Corpus adapters (consumed by Hook A): `docs/CORPUS-ADAPTERS.md` -- Saturation ADR: `docs/decisions/2026-06-01-saturation-campaign.md` -- Handover (collision-avoidance contract): `docs/handover/PROVER-CORPUS-SATURATION-LANE.md` -- Existing chapel rehabilitation ADR: `docs/decisions/2026-05-30-chapel-rehabilitation.md` -- Existing chapel cancel-token ADR: `docs/decisions/2026-05-30-chapel-l23-cancel-token.md` diff --git a/docs/architecture/CORRECTNESS-ARCHITECTURE.adoc b/docs/architecture/CORRECTNESS-ARCHITECTURE.adoc new file mode 100644 index 00000000..5007ca3c --- /dev/null +++ b/docs/architecture/CORRECTNESS-ARCHITECTURE.adoc @@ -0,0 +1,309 @@ +== ECHIDNA Correctness Architecture + +*Author*: Claude Opus 4.5 (architecture design) *Date*: 2026-02-05 +*Purpose*: Design for absolute confidence in ECHIDNA’s correctness. This +addresses the core question: how can users trust that ECHIDNA’s outputs +are mathematically sound, not "`AI hallucinations`"? + +''''' + +=== The Core Guarantee + +*ECHIDNA’s soundness invariant*: ML only _suggests_ — provers _verify_. + +No proof can be accepted unless a formal theorem prover has mechanically +checked every step. The ML layer is advisory only. Even if the ML model +is completely wrong, the worst outcome is wasted compute, never a false +proof. + +This is fundamentally different from LLMs generating "`proofs`" — +ECHIDNA uses real theorem provers (Coq, Lean, Isabelle, etc.) as the +final arbiter. + +''''' + +=== Five Layers of Correctness Assurance + +==== Layer 1: Prover Verification (FOUNDATION) + +Every tactic suggestion from ML is submitted to a real theorem prover. +The prover either accepts (proof step valid) or rejects (invalid). This +is a binary gate — no "`maybe`" or "`probably correct`". + +*Implementation*: `+src/rust/provers/*.rs+` — each of 12 backends has +`+apply_tactic()+` which returns `+Ok(new_state)+` or +`+Err(rejection)+`. + +*Guarantee*: No false proofs. Period. The prover’s type checker is the +ultimate authority. + +==== Layer 2: Multi-Prover Cross-Validation (REDUNDANCY) + +For high-assurance proofs, submit the same theorem to multiple provers. +If Coq, Lean, and Isabelle all accept the proof, confidence is extremely +high. + +*Implementation*: `+src/rust/agent/consensus.rs+` (planned for v2.0) + +.... +Proof accepted by: + - 1 prover: Standard confidence + - 2 provers: High confidence + - 3+ provers: Maximum confidence (different foundations agree) +.... + +*Guarantee*: Independent verification across different logical +foundations (constructive type theory, classical HOL, SMT). + +==== Layer 3: Anomaly Detection (EARLY WARNING) + +Detect when ML is behaving abnormally before provers waste time. + +*Implementation*: `+src/rust/anomaly_detection.rs+` — 7 anomaly types: - +Overconfidence (ML claims >95% but prover rejects) - Disagreement +(multiple ML models disagree) - Circular reasoning (tactic chain loops) +- Complexity explosion (proof tree growing without progress) - +Distribution shift (input unlike training data) - Repetition (same +tactic suggested repeatedly) - Timeout (ML inference too slow) + +*Guarantee*: Early detection of ML failures. Does not replace prover +verification — complements it. + +==== Layer 4: Property-Based Testing (INVARIANTS) + +Automatically generated test cases verify core invariants hold. + +*Implementation*: `+tests/property_tests.rs+` using PropTest: - +Confidence scores always in [0, 1] - Tactic serialization roundtrips +correctly - Deterministic: same input → same output - No empty +suggestions for valid goals - Parsing handles all valid syntax - Memory +bounded (no leaks) + +*Guarantee*: Statistical confidence that implementation matches spec. + +==== Layer 5: Formal Proof Validator (META-VERIFICATION) + +An independently-implemented proof checker in Idris2 with dependent +types. + +*Implementation*: `+src/idris/ProofTerm.idr+` + +`+src/idris/Validator.idr+` - AST for dependent type theory proof terms +- Type checker with totality guarantee - Detects: circular reasoning, +type mismatches, invalid tactics - Soundness theorem signature (to be +fully proven) + +*Guarantee*: Even if the Rust/Julia code has bugs, the Idris2 validator +independently checks proof terms. A proof accepted by both the prover +AND the Idris2 validator is extremely unlikely to be false. + +''''' + +=== Correctness Certification Pipeline (v2.0) + +For every proof ECHIDNA produces, generate a *proof certificate*: + +[source,json] +---- +{ + "theorem": "forall n : nat, n + 0 = n", + "proof_steps": [...], + "prover": "coq-8.19", + "prover_output": "", + "cross_validated_by": ["lean4", "isabelle"], + "ml_confidence": 0.87, + "anomaly_flags": [], + "idris2_validation": "PASSED", + "certificate_hash": "sha256:abc123...", + "provenance": { + "echidna_version": "2.0.0", + "model_version": "transformer-v1", + "training_data_hash": "sha256:def456...", + "timestamp": "2026-03-15T10:30:00Z" + } +} +---- + +*Key properties*: 1. *Machine-checkable*: Anyone can replay the proof +steps in the prover 2. *Provenance chain*: Full history of how the proof +was generated 3. *Tamper-evident*: SHA-256 hash of entire certificate 4. +*Reproducible*: Same inputs always produce same proof + +''''' + +=== Compute Layer Integration (Julia/Chapel/Rust) + +==== Current Architecture + +.... +Chapel (ISOLATED) Julia ML (HTTP) Rust Core + | | | + | (no connection) |<-- HTTP POST ---->| + | | port 8090 | + | | + | 12 Prover Backends <--| +.... + +==== Recommended Architecture (v2.0) + +.... +Chapel HPC Layer (parallel orchestration) + | + |-- C FFI --> Rust Core (prover execution) + | | + | |--> Prover 1 (Coq) } executed in + | |--> Prover 2 (Lean) } parallel by + | |--> Prover 3 (Z3) } Chapel coforall + | |--> ... } + | + |-- HTTP --> Julia ML (neural guidance) + | + |--> GNN encoder (proof graph structure) + |--> Transformer (premise selection) + |--> Confidence estimation (Monte Carlo dropout) +.... + +*How it works*: 1. Chapel receives a theorem to prove 2. Chapel calls +Julia for initial neural guidance (which provers + tactics to try) 3. +Chapel launches `+coforall+` over recommended provers 4. Each parallel +task calls Rust via C FFI to execute real prover 5. Chapel collects +results, selects best proof 6. If no proof found, Chapel calls Julia for +refined suggestions (beam search) 7. Repeat until proof found or timeout + +*Why this is better than current*: - Chapel gets REAL provers (not +simulated success/failure) - Julia neural guidance focuses search (not +random exploration) - Rust handles prover lifecycle and safety - All +three layers contribute their strength: - Julia: intelligence (which +tactics to try) - Chapel: parallelism (try many at once) - Rust: safety +(correct prover execution) + +==== Julia/Chapel Interaction Recommendation + +*Option A: HTTP (Simpler, Recommended for v2.0)* - Chapel calls Julia +HTTP API for neural suggestions - Same API that Rust already uses - Pro: +No new FFI code needed - Con: Network overhead per request + +*Option B: Shared Memory via Rust (Advanced, v3.0)* - Julia writes +neural rankings to shared memory - Chapel reads via Rust C FFI bridge - +Pro: Zero-copy, minimum latency - Con: Complex memory management + +*Recommendation*: Start with HTTP (Option A). The latency (~1ms +localhost) is negligible compared to prover execution time (~100ms-10s). +Move to shared memory only if profiling shows HTTP is a bottleneck. + +''''' + +=== Applying ECHIDNA to Absolute Zero (Test Case) + +==== Why Absolute Zero is the Perfect Test Case + +[arabic] +. *Well-defined theorems*: 81 completed Coq proofs to validate against +. *Known gaps*: 19 Admitted proofs that ECHIDNA could attempt +. *Multi-domain*: Category theory, lambda calculus, quantum, +thermodynamics +. *Ground truth*: We know which proofs are correct (Qed) and which are +incomplete +. *Shared author*: Same repository standards, same proof style + +==== Integration Plan + +===== Phase 1: Validation (verify ECHIDNA against known proofs) + +Feed each of the 81 completed Coq proofs to ECHIDNA: - Does ECHIDNA’s ML +suggest the same tactics used in the actual proofs? - Does ECHIDNA find +the proofs faster or slower than the actual proof scripts? - Are there +any false positives (ECHIDNA claims proof but Coq rejects)? + +*Expected outcome*: 0 false positives (soundness invariant), ML accuracy +measurable against ground truth. + +===== Phase 2: Discovery (attempt the 19 Admitted proofs) + +Feed each of the 19 Admitted proofs to ECHIDNA: - Priority order (from +PROOF-INSIGHTS.md): 1. quantum_state_eq_refl/sym/trans (need Cexp +axioms) 2. FilesystemCNO.v 6 proofs 3. MalbolgeCore.v 1 proof 4. +quantum_cno_composition (fix intermediate) 5. global_phase_is_cno 6. +LandauerDerivation.v 3 proofs (hardest) 7. y_not_cno (may be unprovable +constructively) + +*Expected outcome*: ECHIDNA may complete some of the easier proofs +automatically. The harder ones (Landauer, y_not_cno) are likely beyond +current ML capability but provide excellent benchmark data. + +===== Phase 3: Cross-Validation (multi-prover verification) + +For proofs that exist in both Coq and Lean 4: - Verify that both provers +accept equivalent proof terms - Use ECHIDNA’s multi-prover consensus to +increase confidence - Report any discrepancies (which would indicate a +bug in one formalization) + +===== Phase 4: Correctness Certification + +Generate proof certificates for all Absolute Zero theorems: - +Machine-checkable certificates for each of the 81 Coq proofs - +Cross-validation with Lean 4 versions where available - Publish +certificates alongside the proofs in the repository - This demonstrates +ECHIDNA’s certification pipeline on a real project + +==== Concrete First Steps (for Sonnet) + +[arabic] +. Create `+examples/absolute-zero/+` in the echidna repo +. Copy 3 representative Coq proof files (CNO.v, LambdaCNO.v, StatMech.v) +. Add extraction script to parse proof states and tactics +. Feed to Julia training pipeline to expand training data +. Test ECHIDNA’s suggestions against known proofs +. Report accuracy metrics + +''''' + +=== Trust Communication Strategy + +==== For Skeptics ("`This is just LLM bullshit`") + +Show them: 1. ECHIDNA uses REAL theorem provers (Coq, Lean, Isabelle) 2. +Every proof step is mechanically checked — no shortcuts 3. The ML model +cannot override the prover — it can only suggest 4. Property-based tests +catch implementation bugs 5. Idris2 validator independently checks proof +terms 6. Anomaly detection catches ML failures early 7. Multi-prover +consensus validates across different foundations + +==== For Regulators ("`How do we know this is safe?`") + +Provide: 1. Proof certificates with full provenance chain 2. SHA-256 +hashes for tamper-evidence 3. Reproducible proof generation 4. Audit +trail of every ML suggestion + prover decision 5. Independent validation +by Idris2 formal checker 6. Performance benchmarks showing regression +detection + +==== For Users ("`Can I trust this in production?`") + +Demonstrate: 1. 99 unit tests + 38 integration tests passing 2. +Property-based testing of core invariants 3. Four-layer trust framework +documentation 4. Clear error messages when proofs fail 5. Confidence +scores with uncertainty quantification 6. Fallback to manual proving +when ML confidence is low + +''''' + +=== Summary + +ECHIDNA’s correctness comes from *defense in depth*: + +[width="100%",cols="18%,40%,42%",options="header",] +|=== +|Layer |What it catches |Cost of failure +|Prover verification |Invalid proof steps |Zero (binary gate) +|Multi-prover consensus |Prover-specific bugs |Very low (redundancy) +|Anomaly detection |ML misbehavior |Low (early warning) +|Property testing |Implementation bugs |Low (CI catches) +|Formal validator |Systematic errors |Very low (independent check) +|=== + +*The key insight*: No single layer needs to be perfect. The combination +of multiple independent layers makes the probability of a false proof +astronomically low. + +A proof accepted by Coq AND Lean AND Isabelle AND the Idris2 validator +AND passing anomaly detection AND satisfying property-based tests has +essentially zero chance of being incorrect. diff --git a/docs/architecture/CORRECTNESS-ARCHITECTURE.md b/docs/architecture/CORRECTNESS-ARCHITECTURE.md deleted file mode 100644 index a962ea24..00000000 --- a/docs/architecture/CORRECTNESS-ARCHITECTURE.md +++ /dev/null @@ -1,320 +0,0 @@ -# ECHIDNA Correctness Architecture - -**Author**: Claude Opus 4.5 (architecture design) -**Date**: 2026-02-05 -**Purpose**: Design for absolute confidence in ECHIDNA's correctness. -This addresses the core question: how can users trust that ECHIDNA's -outputs are mathematically sound, not "AI hallucinations"? - ---- - -## The Core Guarantee - -**ECHIDNA's soundness invariant**: ML only _suggests_ — provers _verify_. - -No proof can be accepted unless a formal theorem prover has mechanically -checked every step. The ML layer is advisory only. Even if the ML model -is completely wrong, the worst outcome is wasted compute, never a false proof. - -This is fundamentally different from LLMs generating "proofs" — ECHIDNA -uses real theorem provers (Coq, Lean, Isabelle, etc.) as the final arbiter. - ---- - -## Five Layers of Correctness Assurance - -### Layer 1: Prover Verification (FOUNDATION) - -Every tactic suggestion from ML is submitted to a real theorem prover. -The prover either accepts (proof step valid) or rejects (invalid). -This is a binary gate — no "maybe" or "probably correct". - -**Implementation**: `src/rust/provers/*.rs` — each of 12 backends -has `apply_tactic()` which returns `Ok(new_state)` or `Err(rejection)`. - -**Guarantee**: No false proofs. Period. The prover's type checker is -the ultimate authority. - -### Layer 2: Multi-Prover Cross-Validation (REDUNDANCY) - -For high-assurance proofs, submit the same theorem to multiple provers. -If Coq, Lean, and Isabelle all accept the proof, confidence is extremely high. - -**Implementation**: `src/rust/agent/consensus.rs` (planned for v2.0) - -``` -Proof accepted by: - - 1 prover: Standard confidence - - 2 provers: High confidence - - 3+ provers: Maximum confidence (different foundations agree) -``` - -**Guarantee**: Independent verification across different logical foundations -(constructive type theory, classical HOL, SMT). - -### Layer 3: Anomaly Detection (EARLY WARNING) - -Detect when ML is behaving abnormally before provers waste time. - -**Implementation**: `src/rust/anomaly_detection.rs` — 7 anomaly types: -- Overconfidence (ML claims >95% but prover rejects) -- Disagreement (multiple ML models disagree) -- Circular reasoning (tactic chain loops) -- Complexity explosion (proof tree growing without progress) -- Distribution shift (input unlike training data) -- Repetition (same tactic suggested repeatedly) -- Timeout (ML inference too slow) - -**Guarantee**: Early detection of ML failures. Does not replace prover -verification — complements it. - -### Layer 4: Property-Based Testing (INVARIANTS) - -Automatically generated test cases verify core invariants hold. - -**Implementation**: `tests/property_tests.rs` using PropTest: -- Confidence scores always in [0, 1] -- Tactic serialization roundtrips correctly -- Deterministic: same input → same output -- No empty suggestions for valid goals -- Parsing handles all valid syntax -- Memory bounded (no leaks) - -**Guarantee**: Statistical confidence that implementation matches spec. - -### Layer 5: Formal Proof Validator (META-VERIFICATION) - -An independently-implemented proof checker in Idris2 with dependent types. - -**Implementation**: `src/idris/ProofTerm.idr` + `src/idris/Validator.idr` -- AST for dependent type theory proof terms -- Type checker with totality guarantee -- Detects: circular reasoning, type mismatches, invalid tactics -- Soundness theorem signature (to be fully proven) - -**Guarantee**: Even if the Rust/Julia code has bugs, the Idris2 validator -independently checks proof terms. A proof accepted by both the prover -AND the Idris2 validator is extremely unlikely to be false. - ---- - -## Correctness Certification Pipeline (v2.0) - -For every proof ECHIDNA produces, generate a **proof certificate**: - -```json -{ - "theorem": "forall n : nat, n + 0 = n", - "proof_steps": [...], - "prover": "coq-8.19", - "prover_output": "", - "cross_validated_by": ["lean4", "isabelle"], - "ml_confidence": 0.87, - "anomaly_flags": [], - "idris2_validation": "PASSED", - "certificate_hash": "sha256:abc123...", - "provenance": { - "echidna_version": "2.0.0", - "model_version": "transformer-v1", - "training_data_hash": "sha256:def456...", - "timestamp": "2026-03-15T10:30:00Z" - } -} -``` - -**Key properties**: -1. **Machine-checkable**: Anyone can replay the proof steps in the prover -2. **Provenance chain**: Full history of how the proof was generated -3. **Tamper-evident**: SHA-256 hash of entire certificate -4. **Reproducible**: Same inputs always produce same proof - ---- - -## Compute Layer Integration (Julia/Chapel/Rust) - -### Current Architecture - -``` -Chapel (ISOLATED) Julia ML (HTTP) Rust Core - | | | - | (no connection) |<-- HTTP POST ---->| - | | port 8090 | - | | - | 12 Prover Backends <--| -``` - -### Recommended Architecture (v2.0) - -``` -Chapel HPC Layer (parallel orchestration) - | - |-- C FFI --> Rust Core (prover execution) - | | - | |--> Prover 1 (Coq) } executed in - | |--> Prover 2 (Lean) } parallel by - | |--> Prover 3 (Z3) } Chapel coforall - | |--> ... } - | - |-- HTTP --> Julia ML (neural guidance) - | - |--> GNN encoder (proof graph structure) - |--> Transformer (premise selection) - |--> Confidence estimation (Monte Carlo dropout) -``` - -**How it works**: -1. Chapel receives a theorem to prove -2. Chapel calls Julia for initial neural guidance (which provers + tactics to try) -3. Chapel launches `coforall` over recommended provers -4. Each parallel task calls Rust via C FFI to execute real prover -5. Chapel collects results, selects best proof -6. If no proof found, Chapel calls Julia for refined suggestions (beam search) -7. Repeat until proof found or timeout - -**Why this is better than current**: -- Chapel gets REAL provers (not simulated success/failure) -- Julia neural guidance focuses search (not random exploration) -- Rust handles prover lifecycle and safety -- All three layers contribute their strength: - - Julia: intelligence (which tactics to try) - - Chapel: parallelism (try many at once) - - Rust: safety (correct prover execution) - -### Julia/Chapel Interaction Recommendation - -**Option A: HTTP (Simpler, Recommended for v2.0)** -- Chapel calls Julia HTTP API for neural suggestions -- Same API that Rust already uses -- Pro: No new FFI code needed -- Con: Network overhead per request - -**Option B: Shared Memory via Rust (Advanced, v3.0)** -- Julia writes neural rankings to shared memory -- Chapel reads via Rust C FFI bridge -- Pro: Zero-copy, minimum latency -- Con: Complex memory management - -**Recommendation**: Start with HTTP (Option A). The latency (~1ms localhost) -is negligible compared to prover execution time (~100ms-10s). Move to -shared memory only if profiling shows HTTP is a bottleneck. - ---- - -## Applying ECHIDNA to Absolute Zero (Test Case) - -### Why Absolute Zero is the Perfect Test Case - -1. **Well-defined theorems**: 81 completed Coq proofs to validate against -2. **Known gaps**: 19 Admitted proofs that ECHIDNA could attempt -3. **Multi-domain**: Category theory, lambda calculus, quantum, thermodynamics -4. **Ground truth**: We know which proofs are correct (Qed) and which are incomplete -5. **Shared author**: Same repository standards, same proof style - -### Integration Plan - -#### Phase 1: Validation (verify ECHIDNA against known proofs) - -Feed each of the 81 completed Coq proofs to ECHIDNA: -- Does ECHIDNA's ML suggest the same tactics used in the actual proofs? -- Does ECHIDNA find the proofs faster or slower than the actual proof scripts? -- Are there any false positives (ECHIDNA claims proof but Coq rejects)? - -**Expected outcome**: 0 false positives (soundness invariant), ML accuracy -measurable against ground truth. - -#### Phase 2: Discovery (attempt the 19 Admitted proofs) - -Feed each of the 19 Admitted proofs to ECHIDNA: -- Priority order (from PROOF-INSIGHTS.md): - 1. quantum_state_eq_refl/sym/trans (need Cexp axioms) - 2. FilesystemCNO.v 6 proofs - 3. MalbolgeCore.v 1 proof - 4. quantum_cno_composition (fix intermediate) - 5. global_phase_is_cno - 6. LandauerDerivation.v 3 proofs (hardest) - 7. y_not_cno (may be unprovable constructively) - -**Expected outcome**: ECHIDNA may complete some of the easier proofs -automatically. The harder ones (Landauer, y_not_cno) are likely beyond -current ML capability but provide excellent benchmark data. - -#### Phase 3: Cross-Validation (multi-prover verification) - -For proofs that exist in both Coq and Lean 4: -- Verify that both provers accept equivalent proof terms -- Use ECHIDNA's multi-prover consensus to increase confidence -- Report any discrepancies (which would indicate a bug in one formalization) - -#### Phase 4: Correctness Certification - -Generate proof certificates for all Absolute Zero theorems: -- Machine-checkable certificates for each of the 81 Coq proofs -- Cross-validation with Lean 4 versions where available -- Publish certificates alongside the proofs in the repository -- This demonstrates ECHIDNA's certification pipeline on a real project - -### Concrete First Steps (for Sonnet) - -1. Create `examples/absolute-zero/` in the echidna repo -2. Copy 3 representative Coq proof files (CNO.v, LambdaCNO.v, StatMech.v) -3. Add extraction script to parse proof states and tactics -4. Feed to Julia training pipeline to expand training data -5. Test ECHIDNA's suggestions against known proofs -6. Report accuracy metrics - ---- - -## Trust Communication Strategy - -### For Skeptics ("This is just LLM bullshit") - -Show them: -1. ECHIDNA uses REAL theorem provers (Coq, Lean, Isabelle) -2. Every proof step is mechanically checked — no shortcuts -3. The ML model cannot override the prover — it can only suggest -4. Property-based tests catch implementation bugs -5. Idris2 validator independently checks proof terms -6. Anomaly detection catches ML failures early -7. Multi-prover consensus validates across different foundations - -### For Regulators ("How do we know this is safe?") - -Provide: -1. Proof certificates with full provenance chain -2. SHA-256 hashes for tamper-evidence -3. Reproducible proof generation -4. Audit trail of every ML suggestion + prover decision -5. Independent validation by Idris2 formal checker -6. Performance benchmarks showing regression detection - -### For Users ("Can I trust this in production?") - -Demonstrate: -1. 99 unit tests + 38 integration tests passing -2. Property-based testing of core invariants -3. Four-layer trust framework documentation -4. Clear error messages when proofs fail -5. Confidence scores with uncertainty quantification -6. Fallback to manual proving when ML confidence is low - ---- - -## Summary - -ECHIDNA's correctness comes from **defense in depth**: - -| Layer | What it catches | Cost of failure | -|-------|----------------|-----------------| -| Prover verification | Invalid proof steps | Zero (binary gate) | -| Multi-prover consensus | Prover-specific bugs | Very low (redundancy) | -| Anomaly detection | ML misbehavior | Low (early warning) | -| Property testing | Implementation bugs | Low (CI catches) | -| Formal validator | Systematic errors | Very low (independent check) | - -**The key insight**: No single layer needs to be perfect. -The combination of multiple independent layers makes the probability -of a false proof astronomically low. - -A proof accepted by Coq AND Lean AND Isabelle AND the Idris2 validator -AND passing anomaly detection AND satisfying property-based tests -has essentially zero chance of being incorrect. diff --git a/docs/architecture/CROSS-REPO-PROOF-DAG.adoc b/docs/architecture/CROSS-REPO-PROOF-DAG.adoc new file mode 100644 index 00000000..16f3b74b --- /dev/null +++ b/docs/architecture/CROSS-REPO-PROOF-DAG.adoc @@ -0,0 +1,327 @@ +== Cross-Repo Proof Dependency DAG + +*Status*: Design draft — implementation not yet started. *Closes*: +estate blocker *C14* from the 2026-06-03 audit ("`when ephapax +`+formal/+` changes, downstream consumers don’t re-verify`"). + +''''' + +=== Problem + +The estate carries several producer/consumer proof relationships that +the current per-repo CI shape does not honour: + +[width="100%",cols="18%,31%,51%",options="header",] +|=== +|Producer |Path |Known consumers +|`+ephapax+` |`+formal/PRESERVATION-*.v+` |`+valence-shell+`, +`+verisimdb+`, `+proven+` + +|`+echo-types+` |`+formal/echo/*.v+` |`+ephapax+` (L3 obligations), +`+valence-shell+` + +|`+kategoria+` |`+formal/*.v+` |`+verisimdb+`, downstream HP +type-checker repos + +|`+tropical-resource-typing+` |`+formal/*.v+` |`+verisimdb+` (Q1 +foundation) + +|`+vcl-ut+` |`+formal/*.v+` |`+verisimdb+` (P3, V2 foundation pack) +|=== + +Today, when a producer’s proofs change, no automatic signal walks the +DAG to re-verify downstream. Transitive correctness drift goes unnoticed +until a manual reviewer notices, or until a consumer’s own CI happens to +re-run against the new producer SHA. That can be weeks. + +This is *C14* in the 2026-06-03 audit’s punch list. + +''''' + +=== Scope (this doc) vs out-of-scope + +In-scope: - Where the DAG lives. - Edge format (TOML / A2ML). - +Edge-discovery rules (manual + automatic). - Trigger semantics (which +webhook fires which downstream jobs). - Failure semantics (degraded mode +when a consumer can’t be reached). + +Out-of-scope: - Term-level proof translation between Coq ↔ Lean ↔ Agda — +that is cross-prover canonicalisation, blocked on `+verisimdb#3+`. - +Per-theorem dependency tracking (i.e. "`only re-verify proofs whose +imports actually touched the producer hunk`"). v1 is repo-grain only; +per-theorem precision is a follow-up once the v1 plumbing is real. + +''''' + +=== Where the DAG lives + +*Recommendation: edges declared per-consumer; aggregation in echidna.* + +[source,text] +---- + consumer repo echidna (estate dispatcher) + ───────────── ───────────────────────────── + .machine_readable/ ┌─────────────────┐ + proof-deps.a2ml ───── ingest ───────► │ proof_dag.toml │ + │ (synthesised │ + consumer repo │ per-fetch) │ + ───────────── │ │ + .machine_readable/ └─────────┬───────┘ + proof-deps.a2ml ───── ingest ───────► │ + ▼ + ┌─────────────────┐ + │ hypatia │ + │ (push fixes / │ + │ enqueue jobs) │ + └─────────┬───────┘ + │ + ▼ + ┌─────────────────┐ + │ echidnabot │ + │ (per-repo CI) │ + └─────────────────┘ +---- + +Rationale: + +* *Edges live in the consumer*, not the producer. Producers shouldn’t +need to know who depends on them; the reverse direction (consumer +declares what it pulls from) matches how Coq/Lean/Agda imports already +work and means no producer-side coordination is needed when a new +consumer onboards. +* *Aggregation in echidna* because echidna is already the estate’s +prover-aware dispatcher (`+src/rust/provers/+`, prover-class scheduling, +trust-bridge), and the dispatch decision needs prover metadata that +echidnabot doesn’t carry. +* *Trigger orchestration in hypatia* because hypatia is the estate-CI +intelligence layer that already coordinates `+gitbot-fleet+` and the +"`push committed fixes to remotes`" contract (see the C15 PR). + +''''' + +=== Edge format + +A new file `+proof-deps.a2ml+` joins the existing +`+.machine_readable/bot_directives/+` family: + +[source,toml] +---- +# .machine_readable/proof-deps.a2ml +schema_version = "1.0" +directive_type = "proof-deps" + +# Each [[depends_on]] entry is one edge from this consumer to a producer. +[[depends_on]] +producer = "hyperpolymath/ephapax" +ref = "main" # branch | tag | exact-sha +paths = ["formal/PRESERVATION-*.v"] # producer-side globs +local_uses = ["formal/L3-ECHO/**/*.v"] # consumer-side proofs that + # transitively rely on producer +rationale = "L3 echo obligations re-use ephapax's preservation_l3." +# Optional gating override: +fail_open = false # if true: producer red doesn't block consumer CI + # (default false — producer red ⇒ consumer red). + +[[depends_on]] +producer = "hyperpolymath/echo-types" +ref = "main" +paths = ["formal/echo/*.v"] +local_uses = ["formal/L3-ECHO/EchoAxioms.v"] +rationale = "Echo-types canonical axioms; echo-types audit recorded." +---- + +Schema notes: + +* `+producer+` is `+/+` — platform-agnostic; same shape +works for Codeberg / Radicle once those adapters land. +* `+ref+` is normally `+main+`; per-edge SHA pins are allowed for +reproducibility-critical consumers (e.g. release branches). +* `+paths+` are producer-side globs — used both for edge invalidation +("`did this hunk touch a tracked path?`") and for the v2 per-theorem +story. +* `+local_uses+` documents _why_ the edge exists. Mostly for humans, but +hypatia surfaces it in the PR comment so reviewers know what failed. +* Tolerance: unknown fields are ignored. Same forward-compat shape as +the C12 manifest. + +''''' + +=== Discovery + +Two discovery paths feed the DAG: + +[arabic] +. *Manual* — author commits `+proof-deps.a2ml+` declaring producers. +This is the only path that v1 honours. +. *Automatic* (v2, after `+verisimdb#3+`) — extract producer references +from Coq `+Require Import+`, Lean `+import+`, Agda `+open import+`. The +estate’s per-language imports vary too widely to do this safely in v1; a +missing edge surfaces as a stale-proof failure within one +producer-change cycle and the author adds it manually. + +The aggregator (`+echidna ingest-proof-deps+`) walks each repo’s +`+proof-deps.a2ml+` via the same `+PlatformAdapter::get_file_contents+` +path echidnabot already uses for `+bot_directives/echidnabot.a2ml+`. +Edges are cached for 24h with ETag revalidation. No edge → no behaviour +change. + +''''' + +=== Trigger semantics + +[source,text] +---- + producer push to tracked path + │ + ▼ + webhook hits echidna ─────► consult ingested DAG, find consumers + │ (forward edges by `paths` glob match) + ▼ + for each consumer: + enqueue echidnabot job + payload: { repo, ref, reason: "upstream change", + upstream: { producer, sha, paths } } + │ + ▼ + echidnabot runs that repo's proof check (per C12 manifest) + │ + ▼ + result → comment on producer commit + open / update consumer issue + "ephapax@abc1234 broke valence-shell@formal/L3-ECHO/EchoAxioms.v" +---- + +Trigger details: + +* Path-grained: only producers’ commits that touch a tracked `+paths+` +glob fan out. Touching producer README, CI, or non-tracked source does +not enqueue anything. +* Coalesced: multiple pushes within a 60s window collapse to one +downstream job per consumer. +* Backpressure: hypatia’s existing concurrency limits (per-repo +semaphore + global cap) apply. Cascade fan-out is bounded. +* Fail-open: if echidna’s DAG cache is stale or unreachable, fall back +to "`no edges`" — never block producer CI on the dispatcher being down. + +''''' + +=== Failure semantics + +[width="100%",cols="50%,50%",options="header",] +|=== +|Condition |Behaviour +|Consumer’s `+proof-deps.a2ml+` is malformed |Log warning; treat as "`no +edges`". No CI block on the consumer. + +|Producer ref not reachable (deleted branch / private repo) |Edge +skipped; warning surfaced in the consumer’s next PR. + +|Consumer CI red after upstream-triggered run |Issue opened in consumer +repo, label `+blocked-on:#+`; `+fail_open+` overrides +this to advisory-only. + +|Producer red + `+fail_open = false+` |Consumer’s `+merge_block+` (per +C12 manifest) gates merges to consumer-main. + +|DAG cycle (A → B → A) |Detected at ingest; cycle edge dropped + filed +as `+echidna#+` with both repos labelled. v1 logs only; v2 +hard-fails ingestion. +|=== + +''''' + +=== Concrete walk-through + +[source,text] +---- +2026-06-XX 10:00 ephapax main pushes commit abc1234 + touching formal/PRESERVATION-L3.v + + 10:00:02 echidna webhook receives push event + matches DAG glob "formal/PRESERVATION-*.v" + consumers: { valence-shell, verisimdb, proven } + + 10:00:03 hypatia enqueues 3 echidnabot jobs: + valence-shell @ main (proof-set: formal/L3-ECHO/**/*.v) + verisimdb @ main (proof-set: formal/foundation-pack/**) + proven @ main (proof-set: formal/echo-leak/*.v) + + 10:00:08 echidnabot dispatches Coq jobs (per each repo's + C12 manifest provers list) + + 10:01:42 results land: + valence-shell GREEN + verisimdb RED (preservation_l3 fails on L2-modality lemma) + proven GREEN + + 10:01:44 echidna posts comment on ephapax abc1234: + "Downstream impact: verisimdb red — preservation_l3 fails + against L2-modality lemma at line 412." + Opens issue verisimdb#NNN with full diff + the failing + proof excerpt. Adds label "blocked-on:ephapax@abc1234". +---- + +''''' + +=== Open decisions for the owner + +[arabic] +. *Edge ref policy*: do all consumers default to `+ref = "main"+`, or +should release-branch consumers be required to pin a SHA? Tradeoff: +pinned SHAs are reproducible but go stale; `+main+` is current but can +silently flip. +. *Issue spam vs PR comment*: when a producer’s main breaks a consumer, +do we open an issue per consumer (high signal, can pile up) or just +comment on the producer commit (no follow-up nudge)? +. *Echo-types special case*: echo-types is the L3 canonical axioms +producer for ephapax (per estate policy +[[feedback_proofs_must_check_and_cross_doc_echo_types]]). Should +echo-types ↔ ephapax edges be auto-injected by echidna without a +`+proof-deps.a2ml+` declaration, or stay opt-in like everything else? +. *`+fail_open+` default*: producer red ⇒ consumer red is the safer +default but it means an upstream’s bad-day red-CI cascades. Should +`+fail_open = true+` be the default and `+fail_open = false+` be the +opt-in for hard-coupled consumers? + +''''' + +=== What this design unblocks + +Closing C14 makes three other audit blockers more tractable: + +* *C16* (GNN outcome-feedback loop) — per-edge success/failure signals +are exactly the cross-repo training data the GNN currently doesn’t see. +* *F25* (cross-prover RDF alignment, blocked on `+verisimdb#3+`) — the +DAG gives an empirical ground-truth set of co-evolving proof pairs, +which is the input that translation work needs. +* *D22* (no single green "`trust pipeline verified`" badge) — the DAG +defines what "`fully verified estate`" means: every edge green. + +''''' + +=== Acceptance criteria for the implementation PR (out of scope here) + +When this design is implemented: + +* [ ] `+echidna ingest-proof-deps+` walks all repos that echidna already +knows about, parses any `+.machine_readable/proof-deps.a2ml+`, and +builds `+proof_dag.toml+` at the daemon level. +* [ ] Producer webhooks fan out via `+EdgeEnvelope+` events on the +existing `+dispatch.rs+` channel. +* [ ] hypatia’s enqueue path accepts `+EdgeEnvelope+` and routes to +echidnabot exactly as it does for direct-push events. +* [ ] Cycle detection runs at ingest and logs (v1) / hard-fails (v2). +* [ ] Three estate-shaped fixtures: ephapax→valence-shell, +echo-types→ephapax, kategoria→verisimdb. +* [ ] Sad-path: unreachable producer ref, malformed `+proof-deps.a2ml+`, +consumer mid-rebase. All degrade gracefully. + +''''' + +=== See also + +* C12 PR — per-repo manifest schema v2.0 (echidnabot). +* C15 PR — hypatia push-fixes wiring (gitbot-fleet). +* `+docs/architecture/CORRECTNESS-ARCHITECTURE.md+` — the soundness +invariant the DAG must not violate. +* `+docs/architecture/VERISIM-ER-SCHEMA.md+` — where ingested edges +eventually persist for cross-prover analytics. diff --git a/docs/architecture/CROSS-REPO-PROOF-DAG.md b/docs/architecture/CROSS-REPO-PROOF-DAG.md deleted file mode 100644 index 308fa3f8..00000000 --- a/docs/architecture/CROSS-REPO-PROOF-DAG.md +++ /dev/null @@ -1,306 +0,0 @@ - - -# Cross-Repo Proof Dependency DAG - -**Status**: Design draft — implementation not yet started. -**Closes**: estate blocker **C14** from the 2026-06-03 audit -("when ephapax `formal/` changes, downstream consumers don't re-verify"). - ---- - -## Problem - -The estate carries several producer/consumer proof relationships that -the current per-repo CI shape does not honour: - -| Producer | Path | Known consumers | -|-----------------|-------------------------------|---------------------------------------------------| -| `ephapax` | `formal/PRESERVATION-*.v` | `valence-shell`, `verisimdb`, `proven` | -| `echo-types` | `formal/echo/*.v` | `ephapax` (L3 obligations), `valence-shell` | -| `kategoria` | `formal/*.v` | `verisimdb`, downstream HP type-checker repos | -| `tropical-resource-typing` | `formal/*.v` | `verisimdb` (Q1 foundation) | -| `vcl-ut` | `formal/*.v` | `verisimdb` (P3, V2 foundation pack) | - -Today, when a producer's proofs change, no automatic signal walks the -DAG to re-verify downstream. Transitive correctness drift goes -unnoticed until a manual reviewer notices, or until a consumer's own CI -happens to re-run against the new producer SHA. That can be weeks. - -This is **C14** in the 2026-06-03 audit's punch list. - ---- - -## Scope (this doc) vs out-of-scope - -In-scope: -- Where the DAG lives. -- Edge format (TOML / A2ML). -- Edge-discovery rules (manual + automatic). -- Trigger semantics (which webhook fires which downstream jobs). -- Failure semantics (degraded mode when a consumer can't be reached). - -Out-of-scope: -- Term-level proof translation between Coq ↔ Lean ↔ Agda — that is - cross-prover canonicalisation, blocked on `verisimdb#3`. -- Per-theorem dependency tracking (i.e. "only re-verify proofs whose - imports actually touched the producer hunk"). v1 is repo-grain only; - per-theorem precision is a follow-up once the v1 plumbing is real. - ---- - -## Where the DAG lives - -**Recommendation: edges declared per-consumer; aggregation in echidna.** - -```text - consumer repo echidna (estate dispatcher) - ───────────── ───────────────────────────── - .machine_readable/ ┌─────────────────┐ - proof-deps.a2ml ───── ingest ───────► │ proof_dag.toml │ - │ (synthesised │ - consumer repo │ per-fetch) │ - ───────────── │ │ - .machine_readable/ └─────────┬───────┘ - proof-deps.a2ml ───── ingest ───────► │ - ▼ - ┌─────────────────┐ - │ hypatia │ - │ (push fixes / │ - │ enqueue jobs) │ - └─────────┬───────┘ - │ - ▼ - ┌─────────────────┐ - │ echidnabot │ - │ (per-repo CI) │ - └─────────────────┘ -``` - -Rationale: - -- **Edges live in the consumer**, not the producer. Producers shouldn't - need to know who depends on them; the reverse direction (consumer - declares what it pulls from) matches how Coq/Lean/Agda imports already - work and means no producer-side coordination is needed when a new - consumer onboards. -- **Aggregation in echidna** because echidna is already the estate's - prover-aware dispatcher (`src/rust/provers/`, prover-class scheduling, - trust-bridge), and the dispatch decision needs prover metadata that - echidnabot doesn't carry. -- **Trigger orchestration in hypatia** because hypatia is the estate-CI - intelligence layer that already coordinates `gitbot-fleet` and the - "push committed fixes to remotes" contract (see the C15 PR). - ---- - -## Edge format - -A new file `proof-deps.a2ml` joins the existing -`.machine_readable/bot_directives/` family: - -```toml -# .machine_readable/proof-deps.a2ml -schema_version = "1.0" -directive_type = "proof-deps" - -# Each [[depends_on]] entry is one edge from this consumer to a producer. -[[depends_on]] -producer = "hyperpolymath/ephapax" -ref = "main" # branch | tag | exact-sha -paths = ["formal/PRESERVATION-*.v"] # producer-side globs -local_uses = ["formal/L3-ECHO/**/*.v"] # consumer-side proofs that - # transitively rely on producer -rationale = "L3 echo obligations re-use ephapax's preservation_l3." -# Optional gating override: -fail_open = false # if true: producer red doesn't block consumer CI - # (default false — producer red ⇒ consumer red). - -[[depends_on]] -producer = "hyperpolymath/echo-types" -ref = "main" -paths = ["formal/echo/*.v"] -local_uses = ["formal/L3-ECHO/EchoAxioms.v"] -rationale = "Echo-types canonical axioms; echo-types audit recorded." -``` - -Schema notes: - -- `producer` is `/` — platform-agnostic; same shape works - for Codeberg / Radicle once those adapters land. -- `ref` is normally `main`; per-edge SHA pins are allowed for - reproducibility-critical consumers (e.g. release branches). -- `paths` are producer-side globs — used both for edge invalidation - ("did this hunk touch a tracked path?") and for the v2 per-theorem - story. -- `local_uses` documents *why* the edge exists. Mostly for humans, but - hypatia surfaces it in the PR comment so reviewers know what failed. -- Tolerance: unknown fields are ignored. Same forward-compat shape as - the C12 manifest. - ---- - -## Discovery - -Two discovery paths feed the DAG: - -1. **Manual** — author commits `proof-deps.a2ml` declaring producers. - This is the only path that v1 honours. -2. **Automatic** (v2, after `verisimdb#3`) — extract producer references - from Coq `Require Import`, Lean `import`, Agda `open import`. The - estate's per-language imports vary too widely to do this safely in - v1; a missing edge surfaces as a stale-proof failure within one - producer-change cycle and the author adds it manually. - -The aggregator (`echidna ingest-proof-deps`) walks each repo's -`proof-deps.a2ml` via the same `PlatformAdapter::get_file_contents` path -echidnabot already uses for `bot_directives/echidnabot.a2ml`. Edges are -cached for 24h with ETag revalidation. No edge → no behaviour change. - ---- - -## Trigger semantics - -```text - producer push to tracked path - │ - ▼ - webhook hits echidna ─────► consult ingested DAG, find consumers - │ (forward edges by `paths` glob match) - ▼ - for each consumer: - enqueue echidnabot job - payload: { repo, ref, reason: "upstream change", - upstream: { producer, sha, paths } } - │ - ▼ - echidnabot runs that repo's proof check (per C12 manifest) - │ - ▼ - result → comment on producer commit + open / update consumer issue - "ephapax@abc1234 broke valence-shell@formal/L3-ECHO/EchoAxioms.v" -``` - -Trigger details: - -- Path-grained: only producers' commits that touch a tracked `paths` - glob fan out. Touching producer README, CI, or non-tracked source - does not enqueue anything. -- Coalesced: multiple pushes within a 60s window collapse to one - downstream job per consumer. -- Backpressure: hypatia's existing concurrency limits (per-repo - semaphore + global cap) apply. Cascade fan-out is bounded. -- Fail-open: if echidna's DAG cache is stale or unreachable, fall back - to "no edges" — never block producer CI on the dispatcher being down. - ---- - -## Failure semantics - -| Condition | Behaviour | -|--------------------------------------------|--------------------------------------------| -| Consumer's `proof-deps.a2ml` is malformed | Log warning; treat as "no edges". No CI block on the consumer. | -| Producer ref not reachable (deleted branch / private repo) | Edge skipped; warning surfaced in the consumer's next PR. | -| Consumer CI red after upstream-triggered run | Issue opened in consumer repo, label `blocked-on:#`; `fail_open` overrides this to advisory-only. | -| Producer red + `fail_open = false` | Consumer's `merge_block` (per C12 manifest) gates merges to consumer-main. | -| DAG cycle (A → B → A) | Detected at ingest; cycle edge dropped + filed as `echidna#` with both repos labelled. v1 logs only; v2 hard-fails ingestion. | - ---- - -## Concrete walk-through - -```text -2026-06-XX 10:00 ephapax main pushes commit abc1234 - touching formal/PRESERVATION-L3.v - - 10:00:02 echidna webhook receives push event - matches DAG glob "formal/PRESERVATION-*.v" - consumers: { valence-shell, verisimdb, proven } - - 10:00:03 hypatia enqueues 3 echidnabot jobs: - valence-shell @ main (proof-set: formal/L3-ECHO/**/*.v) - verisimdb @ main (proof-set: formal/foundation-pack/**) - proven @ main (proof-set: formal/echo-leak/*.v) - - 10:00:08 echidnabot dispatches Coq jobs (per each repo's - C12 manifest provers list) - - 10:01:42 results land: - valence-shell GREEN - verisimdb RED (preservation_l3 fails on L2-modality lemma) - proven GREEN - - 10:01:44 echidna posts comment on ephapax abc1234: - "Downstream impact: verisimdb red — preservation_l3 fails - against L2-modality lemma at line 412." - Opens issue verisimdb#NNN with full diff + the failing - proof excerpt. Adds label "blocked-on:ephapax@abc1234". -``` - ---- - -## Open decisions for the owner - -1. **Edge ref policy**: do all consumers default to `ref = "main"`, or - should release-branch consumers be required to pin a SHA? Tradeoff: - pinned SHAs are reproducible but go stale; `main` is current but can - silently flip. -2. **Issue spam vs PR comment**: when a producer's main breaks a - consumer, do we open an issue per consumer (high signal, can pile - up) or just comment on the producer commit (no follow-up nudge)? -3. **Echo-types special case**: echo-types is the L3 canonical axioms - producer for ephapax (per estate policy - [[feedback_proofs_must_check_and_cross_doc_echo_types]]). Should - echo-types ↔ ephapax edges be auto-injected by echidna without a - `proof-deps.a2ml` declaration, or stay opt-in like everything else? -4. **`fail_open` default**: producer red ⇒ consumer red is the safer - default but it means an upstream's bad-day red-CI cascades. Should - `fail_open = true` be the default and `fail_open = false` be the - opt-in for hard-coupled consumers? - ---- - -## What this design unblocks - -Closing C14 makes three other audit blockers more tractable: - -- **C16** (GNN outcome-feedback loop) — per-edge success/failure - signals are exactly the cross-repo training data the GNN currently - doesn't see. -- **F25** (cross-prover RDF alignment, blocked on `verisimdb#3`) — the - DAG gives an empirical ground-truth set of co-evolving proof pairs, - which is the input that translation work needs. -- **D22** (no single green "trust pipeline verified" badge) — the DAG - defines what "fully verified estate" means: every edge green. - ---- - -## Acceptance criteria for the implementation PR (out of scope here) - -When this design is implemented: - -- [ ] `echidna ingest-proof-deps` walks all repos that echidna already - knows about, parses any `.machine_readable/proof-deps.a2ml`, - and builds `proof_dag.toml` at the daemon level. -- [ ] Producer webhooks fan out via `EdgeEnvelope` events on the - existing `dispatch.rs` channel. -- [ ] hypatia's enqueue path accepts `EdgeEnvelope` and routes to - echidnabot exactly as it does for direct-push events. -- [ ] Cycle detection runs at ingest and logs (v1) / hard-fails (v2). -- [ ] Three estate-shaped fixtures: ephapax→valence-shell, - echo-types→ephapax, kategoria→verisimdb. -- [ ] Sad-path: unreachable producer ref, malformed `proof-deps.a2ml`, - consumer mid-rebase. All degrade gracefully. - ---- - -## See also - -- C12 PR — per-repo manifest schema v2.0 (echidnabot). -- C15 PR — hypatia push-fixes wiring (gitbot-fleet). -- `docs/architecture/CORRECTNESS-ARCHITECTURE.md` — the soundness - invariant the DAG must not violate. -- `docs/architecture/VERISIM-ER-SCHEMA.md` — where ingested edges - eventually persist for cross-prover analytics. diff --git a/docs/architecture/JULIA-SATURATION-HOOKS.adoc b/docs/architecture/JULIA-SATURATION-HOOKS.adoc new file mode 100644 index 00000000..936308a2 --- /dev/null +++ b/docs/architecture/JULIA-SATURATION-HOOKS.adoc @@ -0,0 +1,201 @@ +== Julia Saturation Hooks — Rust corpus adapters → Julia GNN pipeline + +*Status*: canonical for the hand-off topology produced by the 2026-06-01 +saturation campaign on branch `+prover-corpus-saturation+`. Wire-in PR +(the ~50-LoC additions to `+run_training.jl+`) lands AFTER both this +branch and the parallel `+wave3/161-162-bench-telemetry-corpus+` branch +merge. *Date*: 2026-06-01. *Companion ADR*: +`+docs/decisions/2026-06-01-saturation-campaign.md+`. + +=== 1. Integration topology + +.... +Rust corpus adapter (src/rust/corpus/.rs) + → Corpus JSON (via Corpus::save_json) + → CorpusLoader.load_corpus_json [Julia, NEW this campaign] + → corpus_to_training_examples + → TrainingDataset [Julia, existing — wave3-owned] + → train_solver! [Julia, existing — wave3-owned] + → models/neural/ [Julia, existing — wave3-owned] +.... + +The whole left half (Rust → Corpus JSON → Julia loader) is new in this +campaign. The whole right half (TrainingDataset → train_solver! → +models/neural) is pre-existing AND under sibling-branch ownership. The +join point — the `+Vector{NamedTuple}+` returned by +`+corpus_to_training_examples+` — is the hand-off contract documented in +§4. + +=== 2. Julia files ADDED in this campaign + +All under `+src/julia/+`: + +[width="100%",cols="50%,50%",options="header",] +|=== +|File |Role +|`+corpus_loader.jl+` |New `+CorpusLoader+` module — reads `+Corpus+` +JSON and produces `+TrainingExample+`-shaped NamedTuples. + +|`+saturation_synonyms.jl+` |New `+SaturationSynonyms+` module — reads +per-prover synonym TOMLs and the three cross-prover dictionaries +(`+_msc2020+`, `+_wordnet_math+`, `+_conceptnet_seed+`). + +|`+README.md+` (addendum section only) |Documents the two new modules +and the deliberate hand-off boundary. Existing content untouched. +|=== + +These three are *the entirety of the Julia surface area* added by the +campaign. No edits to any pre-existing Julia file. + +=== 3. Julia files DELIBERATELY NOT TOUCHED + +The following are wave3-owned and/or sit downstream of the GNN training +trigger; they remain untouched on this branch: + +[width="100%",cols="21%,23%,56%",options="header",] +|=== +|File |Owner |Why not touched +|`+src/julia/run_training.jl+` |wave3 chapel bench + telemetry session +|Bench harness modifications in flight. Wiring the new loader in is the +follow-up PR (§5). + +|`+src/julia/training/train.jl+` |wave3 / GNN-trigger |Holds +`+TrainingExample+` / `+TrainingDataset+` / `+train_solver!+`. Schema is +the hand-off target, not the target of edits. + +|`+src/julia/training/dataloader.jl+` |wave3 / GNN-trigger |Holds the +existing JSONL `+proof_states / premises / tactics+` pipeline. New +corpus adapters are additive; they don’t replace it. + +|`+src/julia/models/neural_solver.jl+` |wave3 / GNN-trigger |Encoder + +GNN architecture. Downstream of `+TrainingDataset+`. + +|`+src/julia/models/encoder.jl+` |wave3 / GNN-trigger |Same. + +|`+src/julia/run_training_cpu.jl+` |wave3 chapel bench session |CPU +baseline runner. Touching it would collide with bench numbers. +|=== + +The saturation campaign ADR §"`Coordination with wave3/161-162`" +enumerates the same hard-exclusion set on the Rust + data side; this +table is the Julia mirror. + +=== 4. Hand-off contract: field-name and arity guarantees + +`+CorpusLoader.corpus_to_training_examples(corpus, prover_kind::Symbol)+` +returns `+Vector{NamedTuple}+`. Each element has fields: + +[width="100%",cols="33%,27%,40%",options="header",] +|=== +|Field |Type |Meaning +|`+proof_state_fields+` |`+NamedTuple+` +|`+(goal, context, hypotheses, available_premises, proof_depth, metadata)+` +— ready to be spread into a `+ProofState(prover, …)+` call. + +|`+candidate_premise_field_rows+` |`+Vector{NamedTuple}+` |Each row: +`+(name, statement, frequency_score, relevance_score)+`. Caller wraps in +`+Premise(name, statement, prover, nothing, freq, rel)+`. + +|`+relevant_indices+` |`+Vector{Int}+` |1-based indices into +`+candidate_premise_field_rows+`. Initially `+1:n+` (every recorded +dependency is by definition relevant). + +|`+prover_symbol+` |`+Symbol+` |Passed-through from the caller; maps to +`+ProverType+` via the existing `+safe_parse_prover+` table in +`+dataloader.jl+`. + +|`+adapter+` |`+String+` |Source adapter (`+"lean"+`, `+"coq"+`, +`+"mizar"+`, …). Useful as a metadata tag. + +|`+qualified+` |`+String+` |Fully-qualified entry name +(`+"Foo.Bar.thm1"+`). + +|`+hazards+` |`+Dict{String, Any}+` |The Rust `+AxiomUsage+` flags. +Consumers DROP entries where any of +`+postulate / believe_me / assert_total / admitted / sorry / trustme+` +is `+true+` (matches Rust SA design-search reject filter). + +|`+proof+` |`+Union{String, Nothing}+` |The defining-equation body, if +present. `+Nothing+` for postulates and data declarations. +|=== + +==== Mapping to existing Julia types + +The training-side targets (defined in `+src/julia/EchidnaML.jl+` + +`+src/julia/training/train.jl+`) are unchanged: + +* `+ProofState(prover::ProverType, goal::String, context::Vector{String}, hypotheses::Vector{String}, available_premises::Vector{String}, proof_depth::Int, metadata::Dict{String, Any})+` +* `+Premise(name::String, statement::String, prover::ProverType, embedding::Union{Nothing, Vector{Float32}}, frequency_score::Float32, relevance_score::Float32)+` +* `+TrainingExample(proof_state::ProofState, candidate_premises::Vector{Premise}, relevant_indices::Vector{Int}, prover::ProverType)+` + +The wiring shim is purely a constructor adapter. No type changes are +required on the wave3 side. + +==== Cross-references inside the corpus + +`+corpus.by_qualified+` and `+corpus.by_name+` are passed through +verbatim from the JSON; consumers that want to fill in the empty +`+statement+` column on `+candidate_premise_field_rows+` can join +against `+corpus.by_qualified[dep_qualified]+` → +`+corpus.entries[idx].statement+`. + +=== 5. Follow-up wiring PR (after wave3 lands) + +Single PR, scope ≈ 50 LoC. Sketch: + +[source,julia] +---- +# In src/julia/run_training.jl, near the existing dataloader call: +include("corpus_loader.jl"); using .CorpusLoader + +function load_corpus_examples(corpus_paths::Vector{String}, + prover_kind::Symbol) + corpora = [CorpusLoader.load_corpus_json(p) for p in corpus_paths] + merged = CorpusLoader.merge_corpora(corpora) + rows = CorpusLoader.corpus_to_training_examples(merged, prover_kind) + examples = TrainingExample[] + for row in rows + # Skip axiom-class hazards. + any(values(row.hazards)) && continue + + prover = safe_parse_prover(string(prover_kind)) + prover === nothing && continue + + ps = ProofState(prover, + row.proof_state_fields.goal, + row.proof_state_fields.context, + row.proof_state_fields.hypotheses, + row.proof_state_fields.available_premises, + row.proof_state_fields.proof_depth, + row.proof_state_fields.metadata) + premises = [Premise(p.name, p.statement, prover, nothing, + p.frequency_score, p.relevance_score) + for p in row.candidate_premise_field_rows] + push!(examples, TrainingExample(ps, premises, + row.relevant_indices, prover)) + end + return examples +end +---- + +The PR also adds a `+--corpus-json+` CLI flag to `+run_training.jl+` +that threads the corpus paths through `+load_corpus_examples+` and +unions the result with whatever `+load_jsonl_proof_states+` already +returns. + +Hazard policy: drop entries with ANY axiom flag set. Matches the Rust SA +design-search reject convention documented at +`+src/rust/corpus/mod.rs::AxiomUsage+`. + +=== 6. Cross-references + +* ADR: `+docs/decisions/2026-06-01-saturation-campaign.md+` +* Corpus adapter index: `+docs/CORPUS-ADAPTERS.md+` +* E-R schema for the verisim store these training examples eventually +feed: `+docs/architecture/VERISIM-ER-SCHEMA.md+` +* Handover scoping document: +`+docs/handover/PROVER-CORPUS-SATURATION-LANE.md+` +* Rust corpus root: `+src/rust/corpus/mod.rs+` +* Rust synonyms root: `+src/rust/suggest/synonyms.rs+` +* Julia module addendum: `+src/julia/README.md+` §"`Saturation-campaign +addendum (2026-06-01)`" diff --git a/docs/architecture/JULIA-SATURATION-HOOKS.md b/docs/architecture/JULIA-SATURATION-HOOKS.md deleted file mode 100644 index 5714195f..00000000 --- a/docs/architecture/JULIA-SATURATION-HOOKS.md +++ /dev/null @@ -1,159 +0,0 @@ - - -# Julia Saturation Hooks — Rust corpus adapters → Julia GNN pipeline - -**Status**: canonical for the hand-off topology produced by the -2026-06-01 saturation campaign on branch `prover-corpus-saturation`. -Wire-in PR (the ~50-LoC additions to `run_training.jl`) lands AFTER -both this branch and the parallel -`wave3/161-162-bench-telemetry-corpus` branch merge. -**Date**: 2026-06-01. -**Companion ADR**: -`docs/decisions/2026-06-01-saturation-campaign.md`. - -## 1. Integration topology - -``` -Rust corpus adapter (src/rust/corpus/.rs) - → Corpus JSON (via Corpus::save_json) - → CorpusLoader.load_corpus_json [Julia, NEW this campaign] - → corpus_to_training_examples - → TrainingDataset [Julia, existing — wave3-owned] - → train_solver! [Julia, existing — wave3-owned] - → models/neural/ [Julia, existing — wave3-owned] -``` - -The whole left half (Rust → Corpus JSON → Julia loader) is new in this -campaign. The whole right half (TrainingDataset → train_solver! → -models/neural) is pre-existing AND under sibling-branch ownership. The -join point — the `Vector{NamedTuple}` returned by -`corpus_to_training_examples` — is the hand-off contract documented in -§4. - -## 2. Julia files ADDED in this campaign - -All under `src/julia/`: - -| File | Role | -|------|------| -| `corpus_loader.jl` | New `CorpusLoader` module — reads `Corpus` JSON and produces `TrainingExample`-shaped NamedTuples. | -| `saturation_synonyms.jl` | New `SaturationSynonyms` module — reads per-prover synonym TOMLs and the three cross-prover dictionaries (`_msc2020`, `_wordnet_math`, `_conceptnet_seed`). | -| `README.md` (addendum section only) | Documents the two new modules and the deliberate hand-off boundary. Existing content untouched. | - -These three are **the entirety of the Julia surface area** added by -the campaign. No edits to any pre-existing Julia file. - -## 3. Julia files DELIBERATELY NOT TOUCHED - -The following are wave3-owned and/or sit downstream of the GNN training -trigger; they remain untouched on this branch: - -| File | Owner | Why not touched | -|------|-------|-----------------| -| `src/julia/run_training.jl` | wave3 chapel bench + telemetry session | Bench harness modifications in flight. Wiring the new loader in is the follow-up PR (§5). | -| `src/julia/training/train.jl` | wave3 / GNN-trigger | Holds `TrainingExample` / `TrainingDataset` / `train_solver!`. Schema is the hand-off target, not the target of edits. | -| `src/julia/training/dataloader.jl` | wave3 / GNN-trigger | Holds the existing JSONL `proof_states / premises / tactics` pipeline. New corpus adapters are additive; they don't replace it. | -| `src/julia/models/neural_solver.jl` | wave3 / GNN-trigger | Encoder + GNN architecture. Downstream of `TrainingDataset`. | -| `src/julia/models/encoder.jl` | wave3 / GNN-trigger | Same. | -| `src/julia/run_training_cpu.jl` | wave3 chapel bench session | CPU baseline runner. Touching it would collide with bench numbers. | - -The saturation campaign ADR §"Coordination with wave3/161-162" -enumerates the same hard-exclusion set on the Rust + data side; this -table is the Julia mirror. - -## 4. Hand-off contract: field-name and arity guarantees - -`CorpusLoader.corpus_to_training_examples(corpus, prover_kind::Symbol)` -returns `Vector{NamedTuple}`. Each element has fields: - -| Field | Type | Meaning | -|-------|------|---------| -| `proof_state_fields` | `NamedTuple` | `(goal, context, hypotheses, available_premises, proof_depth, metadata)` — ready to be spread into a `ProofState(prover, …)` call. | -| `candidate_premise_field_rows` | `Vector{NamedTuple}` | Each row: `(name, statement, frequency_score, relevance_score)`. Caller wraps in `Premise(name, statement, prover, nothing, freq, rel)`. | -| `relevant_indices` | `Vector{Int}` | 1-based indices into `candidate_premise_field_rows`. Initially `1:n` (every recorded dependency is by definition relevant). | -| `prover_symbol` | `Symbol` | Passed-through from the caller; maps to `ProverType` via the existing `safe_parse_prover` table in `dataloader.jl`. | -| `adapter` | `String` | Source adapter (`"lean"`, `"coq"`, `"mizar"`, …). Useful as a metadata tag. | -| `qualified` | `String` | Fully-qualified entry name (`"Foo.Bar.thm1"`). | -| `hazards` | `Dict{String, Any}` | The Rust `AxiomUsage` flags. Consumers DROP entries where any of `postulate / believe_me / assert_total / admitted / sorry / trustme` is `true` (matches Rust SA design-search reject filter). | -| `proof` | `Union{String, Nothing}` | The defining-equation body, if present. `Nothing` for postulates and data declarations. | - -### Mapping to existing Julia types - -The training-side targets (defined in `src/julia/EchidnaML.jl` + -`src/julia/training/train.jl`) are unchanged: - -- `ProofState(prover::ProverType, goal::String, context::Vector{String}, hypotheses::Vector{String}, available_premises::Vector{String}, proof_depth::Int, metadata::Dict{String, Any})` -- `Premise(name::String, statement::String, prover::ProverType, embedding::Union{Nothing, Vector{Float32}}, frequency_score::Float32, relevance_score::Float32)` -- `TrainingExample(proof_state::ProofState, candidate_premises::Vector{Premise}, relevant_indices::Vector{Int}, prover::ProverType)` - -The wiring shim is purely a constructor adapter. No type changes are -required on the wave3 side. - -### Cross-references inside the corpus - -`corpus.by_qualified` and `corpus.by_name` are passed through verbatim -from the JSON; consumers that want to fill in the empty `statement` -column on `candidate_premise_field_rows` can join against -`corpus.by_qualified[dep_qualified]` → `corpus.entries[idx].statement`. - -## 5. Follow-up wiring PR (after wave3 lands) - -Single PR, scope ≈ 50 LoC. Sketch: - -```julia -# In src/julia/run_training.jl, near the existing dataloader call: -include("corpus_loader.jl"); using .CorpusLoader - -function load_corpus_examples(corpus_paths::Vector{String}, - prover_kind::Symbol) - corpora = [CorpusLoader.load_corpus_json(p) for p in corpus_paths] - merged = CorpusLoader.merge_corpora(corpora) - rows = CorpusLoader.corpus_to_training_examples(merged, prover_kind) - examples = TrainingExample[] - for row in rows - # Skip axiom-class hazards. - any(values(row.hazards)) && continue - - prover = safe_parse_prover(string(prover_kind)) - prover === nothing && continue - - ps = ProofState(prover, - row.proof_state_fields.goal, - row.proof_state_fields.context, - row.proof_state_fields.hypotheses, - row.proof_state_fields.available_premises, - row.proof_state_fields.proof_depth, - row.proof_state_fields.metadata) - premises = [Premise(p.name, p.statement, prover, nothing, - p.frequency_score, p.relevance_score) - for p in row.candidate_premise_field_rows] - push!(examples, TrainingExample(ps, premises, - row.relevant_indices, prover)) - end - return examples -end -``` - -The PR also adds a `--corpus-json` CLI flag to `run_training.jl` that -threads the corpus paths through `load_corpus_examples` and unions the -result with whatever `load_jsonl_proof_states` already returns. - -Hazard policy: drop entries with ANY axiom flag set. Matches the -Rust SA design-search reject convention documented at -`src/rust/corpus/mod.rs::AxiomUsage`. - -## 6. Cross-references - -- ADR: `docs/decisions/2026-06-01-saturation-campaign.md` -- Corpus adapter index: `docs/CORPUS-ADAPTERS.md` -- E-R schema for the verisim store these training examples eventually - feed: `docs/architecture/VERISIM-ER-SCHEMA.md` -- Handover scoping document: - `docs/handover/PROVER-CORPUS-SATURATION-LANE.md` -- Rust corpus root: `src/rust/corpus/mod.rs` -- Rust synonyms root: `src/rust/suggest/synonyms.rs` -- Julia module addendum: `src/julia/README.md` §"Saturation-campaign - addendum (2026-06-01)" diff --git a/docs/architecture/TYPE-DISCIPLINE-EMBEDDING.adoc b/docs/architecture/TYPE-DISCIPLINE-EMBEDDING.adoc new file mode 100644 index 00000000..23ff8041 --- /dev/null +++ b/docs/architecture/TYPE-DISCIPLINE-EMBEDDING.adoc @@ -0,0 +1,585 @@ +== Type-Discipline Embedding — 39-Discipline Corpus Annotation + +*Status*: canonical. Companion to +`+docs/architecture/VERISIM-ER-SCHEMA.md+` and +`+docs/CORPUS-ADAPTERS.md+`. *Last revised*: 2026-06-01. *Tier*: see +`+docs/PROVER_COUNT.md+` Tier 9 ("`TypeChecker disciplines`"). + +=== 1. Why this doc exists + +The 2026-06-01 saturation campaign added 17 corpus adapters (see +`+docs/CORPUS-ADAPTERS.md+`). Every adapter emits `+CorpusEntry+` values +with a flat `+DeclKind = {Function, Data, Record, Postulate, Module}+` +(defined at `+src/rust/corpus/mod.rs:53+`). That flat tagging is +sufficient for hazard accounting but blind to the _type discipline_ each +declaration belongs to. + +The HP type-checker ecosystem distinguishes *39 type disciplines*, each +routed through TypedWasm Sigma parameters in `+crates/typed_wasm+` and +dispatched by `+src/rust/provers/hp_ecosystem.rs:63-126+`. This document +specifies how every CorpusEntry — regardless of which adapter produced +it — gains a `+type_discipline_tags: Vec+` annotation so +that: + +[arabic] +. cross-prover identity queries (E6 Rel-2 in `+VERISIM-ER-SCHEMA.md+`) +can constrain by discipline, +. the Julia GNN training pipeline (`+src/julia/training/train.jl+`) gets +a 39-dim multi-hot feature vector per example, and +. Panll and Katagoria consumers — neither of which has shipped — can +read the tags as pre-computed type-checker hints rather than re-deriving +them per-query. + +Detection is heuristic, marker-based, and adapter-aware. Confidence is +the cumulative weight of matched markers; see §7. + +=== 2. The 39-discipline taxonomy + +Ten families, 39 disciplines. Sigma parameter names match +`+src/rust/disciplines/disciplines.rs::typell_sigma()+` and the dispatch +table at `+src/rust/provers/hp_ecosystem.rs:63-126+`. + +==== 2.1 Polymorphism (7) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|hindley-milner |`+HM+` |Milner, "`A Theory of Type Polymorphism in +Programming`" (1978) |`+forall a.+`, `+let+`-generalisation, +`+ML+`-style polymorphism + +|system-f |`+SF+` |Reynolds, "`Towards a Theory of Type Structure`" +(1974); Girard PhD (1972) |`+Λ+`, `+Forall+`, explicit type abstraction +`+/\+` + +|rank-n |`+RankN+` |Peyton Jones et al., "`Practical Type Inference for +Arbitrary-Rank Types`" (2007) |`+forall+` under arrow LHS, +`+RankNTypes+` + +|phantom |`+Phantom+` |Leijen & Meijer, "`Domain Specific Embedded +Compilers`" (1999) |unused type parameter on data decl, ghost +`+PhantomData+` + +|existential |`+Exist+` |Mitchell & Plotkin, "`Abstract Types Have +Existential Type`" (1988) |`+exists+`, `+∃+`, `+pack+`/`+unpack+`, +`+Sigma+`-as-existential + +|higher-kinded |`+HKT+` |Jones, "`A System of Constructor Classes`" +(1995) |`+f : Type -> Type+`, kind annotations beyond `+*+` + +|row-poly |`+Row+` |Wand, "`Complete Type Inference for Simple Objects`" +(1987); Rémy (1989) |`+{l : t \| r}+`, row variables, extensible records +|=== + +==== 2.2 Subtyping (4) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|subtyping |`+Sub+` |Cardelli, "`A Semantics of Multiple Inheritance`" +(1984) |`+<:+`, `+≤+`, structural subsumption + +|intersection |`+Int+` |Coppo, Dezani-Ciancaglini & Venneri (1981) +|`+∩+`, `+&+`, conjunctive types + +|union |`+Uni+` |Pierce, "`Programming with Intersection Types, Union +Types, and Polymorphism`" (1991) |`+∪+`, `+\|+`, sum-as-untagged + +|gradual |`+Gra+` |Siek & Taha, "`Gradual Typing for Functional +Languages`" (2006) |`+?+`, `+dyn+`, `+Any+` with consistency +|=== + +==== 2.3 Dependent (5) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|dependent |`+Dep+` |Martin-Löf, "`Intuitionistic Type Theory`" (1984) +|`+(x : A) -> B x+`, `+Π+`, `+Pi+` + +|refinement |`+Ref+` |Freeman & Pfenning, "`Refinement Types for ML`" +(1991); Rondon et al. Liquid (2008) |`+{v : t \| p v}+`, `+predicate+`, +`+requires+`/`+ensures+` + +|hoare |`+Hoa+` |Hoare, "`An Axiomatic Basis for Computer Programming`" +(1969); Nanevski et al. HTT |`+{P} c {Q}+`, `+Hoare ?st ?p ?q+` + +|indexed |`+Ind+` |Zenger, "`Indexed Types`" (1997); Xi & Pfenning DML +(1999) |`+Vec n a+`, type-level Nat indices + +|qtt |`+QTT+` |McBride, "`I Got Plenty o’ Nuttin’`" (2016); Atkey, +"`Syntax and Semantics of Quantitative Type Theory`" (2018) +|`+0 \|- t : T+`, multiplicities `+0 / 1 / ω+` +|=== + +==== 2.4 Substructural (5) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|linear |`+Lin+` |Wadler, "`Linear Types Can Change the World!`" (1990); +Girard "`Linear Logic`" (1987) |`+!+`, `+⊸+`, `+1+` use exactly once + +|affine |`+Aff+` |TBD — fill from author (commonly cited: Walker, +"`Substructural Type Systems`" in ATTAPL ch. 1, 2005) |at-most-once use, +`+Drop+`, `+move+` semantics + +|relevant |`+Rel+` |TBD — fill from author (Walker ATTAPL ch. 1, 2005) +|at-least-once use, mandatory consumption + +|ordered |`+Ord+` |Polakow & Pfenning, "`Natural Deduction for +Intuitionistic Non-commutative Linear Logic`" (1999) |non-exchange +contexts, sequence preservation + +|uniqueness |`+Unq+` |Barendsen & Smetsers, "`Uniqueness Typing for +Functional Languages`" (1996) |Clean `+*+` annotation, unique-reference +invariant +|=== + +==== 2.5 Mutability / capability (3) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|immutable |`+Imm+` |TBD — fill from author |`+const+`, `+final+`, +`+readonly+`, `+val+` + +|capability |`+Cap+` |Crary, Walker & Morrisett, "`Typed Memory +Management in a Calculus of Capabilities`" (1999) |`+cap+`, capability +sets, `+acquire+`/`+release+` + +|bunched |`+Bun+` |O’Hearn & Pym, "`The Logic of Bunched Implications`" +(1999) |`+*+` (separating conjunction), `+-*+`, BI assertion +|=== + +==== 2.6 Modal (4) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|modal |`+Mod+` |Pfenning & Davies, "`A Judgmental Reconstruction of +Modal Logic`" (2001) |`+□+`, `+◇+`, `+box+`, `+dia+` + +|epistemic |`+Epi+` |Hintikka, "`Knowledge and Belief`" (1962); Fagin et +al. (1995) |`+K+`, `+K_i+`, `+knows+`, agent indices + +|temporal |`+Tem+` |Pnueli, "`The Temporal Logic of Programs`" (1977) +|`+□+`, `+◇+`, `+next+`, `+until+`, LTL/CTL operators + +|provability |`+Prv+` |Gödel, Löb; Boolos, "`The Logic of Provability`" +(1993) |`+Bew+`, `+Prov+`, `+□+` as provability operator +|=== + +==== 2.7 Effects / coeffects (4) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|effect-row |`+ERow+` |Leijen, "`Type Directed Compilation of Row-Typed +Algebraic Effects`" (2017) |`++`, `+effect E+`, `+handle+` + +|impure |`+Imp+` |Wadler, "`Comprehending Monads`" (1990); Moggi (1989) +|`+IO+`, `+m a+`, `+do+`-notation + +|coeffect |`+Coef+` |Petricek, Orchard & Mycroft, "`Coeffects: Unified +Static Analysis of Context-Dependence`" (2014) |graded context, +`+[A]r+`, resource grading + +|probabilistic |`+Prob+` |Borgström et al., "`Measure Transformer +Semantics for Bayesian Machine Learning`" (2011) |`+sample+`, +`+observe+`, distribution types +|=== + +==== 2.8 Session / process (4) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|session |`+Ses+` |Honda, "`Types for Dyadic Interaction`" (1993); +Honda, Vasconcelos & Kubo (1998) |`+!T.S+`, `+?T.S+`, `+end+`, channel +session types + +|choreographic |`+Cho+` |Carbone, Honda & Yoshida, "`Multiparty +Asynchronous Session Types`" (2008); Montesi PhD (2013) |global +protocol, role indices `+A -> B : t+` + +|dyadic |`+Dy+` |echo-types (`+hyperpolymath/echo-types+`); see also +Honda’s "`dyadic interaction`" (1993) |`+dyad+`, `+peer A B+`, two-party +protocol + +|echo |`+Echo+` |echo-types (`+hyperpolymath/echo-types+`) — TBD +canonical paper; provisional spec in repo `+docs/+` |`+echo+`, +`+replay+`, `+obs A+`, observational equivalence under echo +|=== + +==== 2.9 Homotopy (3) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|homotopy |`+Hom+` |Univalent Foundations Program, "`Homotopy Type +Theory`" (2013) |univalence axiom, `+Path+`, identity types as paths + +|cubical |`+Cub+` |Cohen, Coquand, Huber & Mörtberg, "`Cubical Type +Theory`" (2018) |`+Path+`, `+PathP+`, `+i0+`/`+i1+`, interval `+I+` + +|nominal |`+Nom+` |Pitts, "`Nominal Logic`" (2001); Gabbay & Pitts +(2002) |`+name+`, `+swap+`, `+freshness ⊥+`, `+α+`-equivalence +|=== + +==== 2.10 Resource (2) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Discipline |TypeLL Sigma |Canonical paper |Markers excerpt +|tropical |`+Trop+` |tropical-resource-typing repo +(`+verification-ecosystem/tropical-resource-typing+`); see also Speyer & +Sturmfels (2009) for the algebra |tropical semiring `+(min, +)+`, +resource cost annotations + +|ceremonial |`+Cer+` |Panll language spec (Panll = panll language) — TBD +canonical paper; ceremonial sub-language doc in `+panll/docs/+` +|`+@[ceremony]+`, `+ritual+`, ceremonial obligation markers +|=== + +=== 3. Detection topology + +.... +Corpus adapter ingests *. + → CorpusEntry { statement, proof, ... } (src/rust/corpus/mod.rs:138) + → detect_disciplines(adapter_name, statement, proof, registry) + (src/rust/disciplines/detector.rs) + → Vec (src/rust/disciplines/disciplines.rs) + → CorpusEntry.type_discipline_tags + → Octad SemanticPayload (src/rust/verisim_bridge.rs) + → VeriSimDB cross-prover identity index (E6 in VERISIM-ER-SCHEMA.md) + → Julia GNN training feature row (src/julia/training/train.jl) +.... + +The detector is pure: same `+(adapter, statement, proof, registry)+` +always returns the same `+Vec+`. The registry +(`+src/rust/disciplines/registry.rs::MarkerRegistry+`) is built once at +process start from `+data/synonyms/_disciplines.toml+` plus the +per-language augmentations in each `+data/synonyms/.toml+`. + +=== 4. Per-adapter coverage matrix + +The 17 saturation-campaign adapters × 10 discipline families. `+✓+` +means the adapter routinely surfaces declarations in that family; +`+partial+` means only via specific idioms; `+—+` means the family is +essentially absent from typical sources for that adapter. + +==== 4.1 Polymorphism, Subtyping (sub-table 1 of 4) + +[width="100%",cols="12%,8%,8%,8%,8%,8%,8%,8%,8%,8%,8%,8%",options="header",] +|=== +|Adapter |HM |SF |RankN |Phantom |Exist |HKT |Row |Sub |Int |Uni |Gra +|agda |✓ |✓ |✓ |partial |✓ |✓ |— |— |— |— |— +|coq |partial |✓ |✓ |partial |✓ |✓ |— |partial |— |— |— +|lean |partial |✓ |✓ |partial |✓ |✓ |— |partial |— |— |— +|idris2 |✓ |✓ |✓ |partial |✓ |✓ |— |— |— |— |— +|isabelle |✓ |partial |— |partial |partial |partial |— |partial |— |— |— +|metamath |— |— |— |— |— |— |— |— |— |— |— +|mizar |— |— |— |— |— |— |— |partial |— |— |— +|hol_light |✓ |partial |— |partial |— |— |— |— |— |— |— +|hol4 |✓ |partial |— |partial |— |— |— |— |— |— |— +|dafny |partial |— |— |partial |— |— |— |✓ |— |— |— +|why3 |✓ |partial |— |partial |— |partial |— |partial |— |— |— +|fstar |✓ |✓ |✓ |partial |✓ |partial |— |partial |— |— |— +|acl2_books |— |— |— |— |— |— |— |— |— |— |— +|tptp |— |partial |— |— |partial |— |— |— |— |— |— +|smtlib |— |— |— |— |— |— |— |partial |— |— |— +|proofnet |partial |partial |— |— |partial |— |— |— |— |— |— +|minif2f |partial |partial |— |— |partial |— |— |— |— |— |— +|=== + +==== 4.2 Dependent, Substructural (sub-table 2 of 4) + +[width="100%",cols="10%,9%,9%,9%,9%,9%,9%,9%,9%,9%,9%",options="header",] +|=== +|Adapter |Dep |Ref |Hoa |Ind |QTT |Lin |Aff |Rel |Ord |Unq +|agda |✓ |partial |— |✓ |— |✓ |✓ |— |— |— +|coq |✓ |partial |partial |✓ |— |partial |partial |— |— |— +|lean |✓ |partial |partial |✓ |— |partial |partial |— |— |— +|idris2 |✓ |partial |— |✓ |✓ |✓ |✓ |— |— |partial +|isabelle |partial |— |✓ |partial |— |— |— |— |— |— +|metamath |— |— |— |— |— |— |— |— |— |— +|mizar |partial |— |— |— |— |— |— |— |— |— +|hol_light |— |— |partial |— |— |— |— |— |— |— +|hol4 |— |— |partial |— |— |— |— |— |— |— +|dafny |partial |✓ |✓ |partial |— |— |— |— |— |— +|why3 |partial |✓ |✓ |partial |— |— |— |— |— |— +|fstar |✓ |✓ |✓ |✓ |— |partial |partial |— |— |— +|acl2_books |— |— |— |— |— |— |— |— |— |— +|tptp |partial |— |— |— |— |— |— |— |— |— +|smtlib |— |— |— |— |— |— |— |— |— |— +|proofnet |partial |partial |partial |partial |— |— |— |— |— |— +|minif2f |partial |partial |partial |partial |— |— |— |— |— |— +|=== + +==== 4.3 Mutability, Modal, Effects (sub-table 3 of 4) + +[width="100%",cols="12%,8%,8%,8%,8%,8%,8%,8%,8%,8%,8%,8%",options="header",] +|=== +|Adapter |Imm |Cap |Bun |Mod |Epi |Tem |Prv |ERow |Imp |Coef |Prob +|agda |— |— |— |partial |— |— |— |— |partial |— |— +|coq |— |— |partial |partial |— |partial |partial |— |partial |— |— +|lean |— |— |— |partial |— |partial |partial |— |partial |— |— +|idris2 |— |— |— |— |— |— |— |partial |partial |— |— +|isabelle |— |— |— |partial |partial |✓ |partial |— |— |— |partial +|metamath |— |— |— |partial |— |— |partial |— |— |— |— +|mizar |— |— |— |— |— |— |— |— |— |— |— +|hol_light |— |— |— |partial |— |partial |partial |— |— |— |— +|hol4 |— |— |— |partial |— |partial |partial |— |— |— |— +|dafny |✓ |✓ |partial |— |— |— |— |— |✓ |— |— +|why3 |partial |— |— |— |— |— |— |— |✓ |— |— +|fstar |partial |partial |partial |— |— |— |— |✓ |✓ |— |partial +|acl2_books |— |— |— |— |— |partial |— |— |— |— |— +|tptp |— |— |— |partial |partial |partial |— |— |— |— |— +|smtlib |— |— |— |— |— |partial |— |— |— |— |— +|proofnet |— |— |— |partial |— |— |— |— |partial |— |— +|minif2f |— |— |— |partial |— |— |— |— |partial |— |— +|=== + +==== 4.4 Session, Homotopy, Resource (sub-table 4 of 4) + +[cols=",,,,,,,,,",options="header",] +|=== +|Adapter |Ses |Cho |Dy |Echo |Hom |Cub |Nom |Trop |Cer +|agda |— |— |— |— |✓ |✓ |— |— |— +|coq |— |— |— |— |partial |— |partial |— |— +|lean |— |— |— |— |partial |— |— |— |— +|idris2 |— |— |— |— |— |— |— |— |— +|isabelle |— |— |— |— |— |— |partial |— |— +|metamath |— |— |— |— |— |— |— |— |— +|mizar |— |— |— |— |— |— |— |— |— +|hol_light |— |— |— |— |— |— |— |— |— +|hol4 |— |— |— |— |— |— |— |— |— +|dafny |— |— |— |— |— |— |— |— |— +|why3 |— |— |— |— |— |— |— |— |— +|fstar |— |— |— |— |— |— |— |— |— +|acl2_books |— |— |— |— |— |— |— |— |— +|tptp |— |— |— |— |— |— |— |— |— +|smtlib |— |— |— |— |— |— |— |— |— +|proofnet |partial |— |— |— |partial |partial |— |— |— +|minif2f |— |— |— |— |partial |partial |— |— |— +|=== + +Cells are best-effort priors based on typical mathlib4 / stdlib / AFP / +mizar-mml content. The detector returns whatever markers fire, so a +`+partial+`-marked cell can still produce real tags when the specific +declaration uses the relevant idiom; the matrix only documents expected +hit frequency for triage. + +=== 5. Crosswalk to TypeLL / Katagoria / VCL-UT / Panll + +==== 5.1 TypeLL + +Each `+TypeDiscipline+` variant has a Sigma parameter name returned by +`+src/rust/disciplines/disciplines.rs::typell_sigma()+`. The Sigma names +are single-token strings (`+"HM"+`, `+"SF"+`, `+"Lin"+`, `+"Aff"+`, +`+"Dep"+`, `+"QTT"+`, `+"Echo"+`, `+"Cub"+`, `+"Trop"+`, `+"Cer"+`, …) +and exactly match the discipline tag passed to +`+typell --discipline=+` by +`+src/rust/provers/hp_ecosystem.rs:63-126+`. The Sigma table is the +single source of truth for the discipline ↔ CLI mapping; this document +does not re-list it. + +==== 5.2 Katagoria + +Katagoria (`+hyperpolymath/katagoria+`, dispatched as +`+ProverKind::KatagoriaVerifier+` at +`+src/rust/provers/hp_ecosystem.rs:66+`) reserves invariant slots keyed +by discipline tag. The intended mapping — which tags populate which +Katagoria invariant slots — is *TBD — needs Katagoria spec audit*. Until +then, the detector emits the tag and Katagoria consumers ignore unknown +tags. + +==== 5.3 VCL-UT + +VCL-UT (`+src/rust/vcl_ut.rs:1-1083+`) already exposes a 10-level +`+TypeLevel+` safety annotation. Discipline tags are orthogonal: a +VCL-UT query can additionally constrain by discipline, e.g. + +[source,text] +---- +select octad +where_discipline(TypeDiscipline::Linear) +where type_level >= TypeLevel::L7 +---- + +The VCL-UT planner pushes the discipline filter down to the +`+octads_semantic+` materialised view (E2 in `+VERISIM-ER-SCHEMA.md+`), +which indexes on the new `+type_discipline_tags+` array column. + +==== 5.4 Panll + +Panll’s type system is the union of all 39 disciplines plus +cross-discipline composition operators (per the +`+panll/docs/type-system/+` design notes). Discipline tags are +*pre-Panll annotation*: they are computed by adapters that pre-date the +Panll compiler, stored in VeriSimDB, and consumed downstream once Panll +lands. The contract is: + +* adapters MUST emit tags they detect, even if Panll cannot yet consume +them; +* Panll’s compiler, when it ships, MUST read `+type_discipline_tags+` as +hints (not authoritative) and may refine or extend the set. + +=== 6. Wire schema impact + +The `+SemanticPayload+` struct in `+src/rust/verisim_bridge.rs+` gains a +new field: + +[source,rust] +---- +pub struct SemanticPayload { + // ...existing fields... + pub type_discipline_tags: Vec, // kebab-case slugs +} +---- + +The slugs are the canonical discipline names from §2 (e.g. +`+"hindley-milner"+`, `+"linear"+`, `+"echo"+`, `+"tropical"+`). + +The Cap’n Proto schema at +`+crates/echidna-wire/schemas/verisim_er.capnp+` adds field 11 on the +`+Semantic+` struct: + +[source,capnp] +---- +struct Semantic { + # ...fields @0..@10 unchanged... + typeDisciplineTags @11 :List(Text); +} +---- + +VeriSimDB stores this as an `+Array(LowCardinality(String))+` column on +the `+octads_semantic+` table, with a secondary skip index for +discipline-filtered queries. The drift-detection SHA in §"`Drift +detection`" of `+VERISIM-ER-SCHEMA.md+` MUST be re-computed when this +field lands. + +=== 7. Detection confidence + +The detector is heuristic; tags are emitted when cumulative marker score +for a discipline exceeds 0.7. Marker entries in `+MarkerRegistry+` have +shape: + +[source,rust] +---- +pub struct Marker { + pub pattern: String, // literal string or regex (compiled lazily) + pub discipline: TypeDiscipline, + pub weight: f64, // 0.0..1.0 + pub adapters: &'static [&'static str], // empty == language-agnostic +} +---- + +* *HIGH-confidence markers* like `+@[ceremony]+` are unambiguous — +weight 0.95. A single occurrence crosses the 0.7 threshold. +* *MEDIUM-confidence markers* like `+forall+` need corroborating +evidence (e.g. a type variable in scope) before they tag System F or +Rank-N. Typical weight 0.45–0.6. +* *LOW-confidence markers* like `+!+` (which could be linear-logic +exponential, boolean negation, factorial, or Haskell strictness) carry +weight 0.2 and require multiple co-occurring markers to fire. + +The `+adapters+` slice scopes a marker: `+adapters: &[]+` (empty) means +the marker is language-agnostic; `+adapters: &["lean"]+` restricts it to +Lean sources only. This matters because `+!+` means "`linear bang`" in +Linear Logic encodings but "`decide`" in Lean tactic scripts. + +=== 8. Per-discipline owner-direction status + +Status of the nine disciplines the owner explicitly called out during +campaign scoping: + +* *linear*: ✓ detector + markers + synonyms shipped +(`+data/synonyms/_disciplines.toml::[linear]+`). +* *affine*: ✓ ditto. Cross-references the Rust borrow-checker vocabulary +(`+move+`, `+Copy+`, `+Drop+`) used in `+idaptik+` corpus. +* *dependent*: ✓ ditto. Routes through `+DependentTypeChecker+` +(`+src/rust/provers/hp_ecosystem.rs:75+`). +* *equality*: ✓ as part of subtyping/dependent; markers `+=+`, `+≡+`, +`+==+`, propositional-equality (`+Path+`, `+Id+`, `+eq+`). Not a +standalone Sigma; surfaces under `+Dep+` or `+Hom+` depending on +context. +* *ceremonial*: ✓ markers shipped (`+@[ceremony]+`, `+ritual+`, +ceremonial-obligation slugs). Detector may need expansion as Panll’s +ceremonial sub-language stabilises. +* *dyadic*: ✓ from echo-types (`+hyperpolymath/echo-types+`); routes +through `+DyadicTypeChecker+` +(`+src/rust/provers/hp_ecosystem.rs:111+`). +* *tropical*: ✓ from tropical-resource-typing repo; routes through +`+TropicalTypeChecker+` (`+src/rust/provers/hp_ecosystem.rs:67+`). +* *choreographic*: ✓ markers shipped (global-protocol syntax, multi-role +declarations); routes through `+ChoreographicTypeChecker+` +(`+src/rust/provers/hp_ecosystem.rs:68+`). +* *epistemic*: ✓ markers shipped (`+K+`, `+K_i+`, `+knows+`); routes +through `+EpistemicTypeChecker+` +(`+src/rust/provers/hp_ecosystem.rs:69+`). + +=== 9. Integration with the GNN training pipeline + +The `+type_discipline_tags+` field flows from CorpusEntry → octad +emission → Julia corpus loader → training example: + +.... +CorpusEntry.type_discipline_tags + → SemanticPayload.type_discipline_tags (verisim_bridge.rs) + → octads_semantic.type_discipline_tags (VeriSimDB column) + → premises_.jsonl (corpus-emit CLI) + → src/julia/training/corpus_loader.jl (reads JSONL) + → TrainingExample.discipline_features (39-dim multi-hot) + → train.jl (consumes both heads) +.... + +Two heads: + +* *Value head*: discipline tags are concatenated as a 39-dim multi-hot +vector and fed to the value-prediction MLP. Disciplines that imply +harder goals (Dep, QTT, Cub) shift the value prior down; the model +learns the offsets. +* *Policy head*: discipline tags constrain candidate tactics. For a +`+Linear+`-tagged goal, the policy head prefers tactics that respect +linearity (no duplication, no discarding). The constraint is a soft +prior implemented as a logit bias in the tactic-ranking softmax — see +the GNN service in `+src/julia/server/gnn_api.jl+`. + +=== 10. Open follow-ups + +* *T1* — wire `+type_discipline_tags+` into `+CorpusEntry+` serde so +every adapter’s emit path populates the field. +* *T2* — each per-language detector gets adapter-aware refinement beyond +plain text-matching (e.g. AST-walking the Coq term for `+Π+`-binders +rather than regexing the source). +* *T3* — Cap’n Proto schema delta on `+Semantic @11+`. +* *T4* — `+src/julia/training/corpus_loader.jl+` pass-through of the +39-dim feature. +* *T5* — cross-reference echo-types repo (`+hyperpolymath/echo-types+`) +for the canonical Echo / Dyadic marker set; audit pending. Per the +standing "`[Proofs MUST check + cross-doc echo-types]`" directive, every +Echo/Dyadic marker addition MUST first audit echo-types and reuse if +applicable, extend upstream WITH proofs if not. +* *T6* — Katagoria invariant-slot mapping (§5.2) needs spec audit. +* *T7* — Panll’s compiler integration once it lands (§5.4). + +=== 11. References + +* `+src/rust/disciplines/disciplines.rs+` — the `+TypeDiscipline+` enum +and `+typell_sigma()+` mapping. +* `+src/rust/disciplines/registry.rs+` — the `+MarkerRegistry+`. +* `+src/rust/disciplines/detector.rs+` — the `+detect_disciplines+` +entry point. +* `+data/synonyms/_disciplines.toml+` — the cross-prover discipline +vocabulary. +* `+docs/architecture/VERISIM-ER-SCHEMA.md+` — E2 Semantic modality +target (this doc adds field `+@11+`). +* `+crates/echidna-wire/schemas/verisim_er.capnp+` — wire schema +(pending field-11 delta per T3). +* `+crates/typed_wasm/src/lib.rs+` — Sigma parameter routing target. +* `+src/rust/provers/hp_ecosystem.rs:63-126+` — 39-discipline dispatch +table. +* `+docs/PROVER_COUNT.md+` Tier 9 — the canonical tier table. +* `+docs/CORPUS-ADAPTERS.md+` — adapter inventory consumed by §4. diff --git a/docs/architecture/TYPE-DISCIPLINE-EMBEDDING.md b/docs/architecture/TYPE-DISCIPLINE-EMBEDDING.md deleted file mode 100644 index 29b884cc..00000000 --- a/docs/architecture/TYPE-DISCIPLINE-EMBEDDING.md +++ /dev/null @@ -1,464 +0,0 @@ - - -# Type-Discipline Embedding — 39-Discipline Corpus Annotation - -**Status**: canonical. Companion to -`docs/architecture/VERISIM-ER-SCHEMA.md` and `docs/CORPUS-ADAPTERS.md`. -**Last revised**: 2026-06-01. -**Tier**: see `docs/PROVER_COUNT.md` Tier 9 ("TypeChecker disciplines"). - -## 1. Why this doc exists - -The 2026-06-01 saturation campaign added 17 corpus adapters (see -`docs/CORPUS-ADAPTERS.md`). Every adapter emits `CorpusEntry` values -with a flat `DeclKind = {Function, Data, Record, Postulate, Module}` -(defined at `src/rust/corpus/mod.rs:53`). That flat tagging is -sufficient for hazard accounting but blind to the *type discipline* -each declaration belongs to. - -The HP type-checker ecosystem distinguishes **39 type disciplines**, -each routed through TypedWasm Sigma parameters in `crates/typed_wasm` -and dispatched by `src/rust/provers/hp_ecosystem.rs:63-126`. This -document specifies how every CorpusEntry — regardless of which adapter -produced it — gains a `type_discipline_tags: Vec` -annotation so that: - -1. cross-prover identity queries (E6 Rel-2 in - `VERISIM-ER-SCHEMA.md`) can constrain by discipline, -2. the Julia GNN training pipeline (`src/julia/training/train.jl`) - gets a 39-dim multi-hot feature vector per example, and -3. Panll and Katagoria consumers — neither of which has shipped — can - read the tags as pre-computed type-checker hints rather than - re-deriving them per-query. - -Detection is heuristic, marker-based, and adapter-aware. Confidence is -the cumulative weight of matched markers; see §7. - -## 2. The 39-discipline taxonomy - -Ten families, 39 disciplines. Sigma parameter names match -`src/rust/disciplines/disciplines.rs::typell_sigma()` and the dispatch table -at `src/rust/provers/hp_ecosystem.rs:63-126`. - -### 2.1 Polymorphism (7) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| hindley-milner | `HM` | Milner, "A Theory of Type Polymorphism in Programming" (1978) | `forall a.`, `let`-generalisation, `ML`-style polymorphism | -| system-f | `SF` | Reynolds, "Towards a Theory of Type Structure" (1974); Girard PhD (1972) | `Λ`, `Forall`, explicit type abstraction `/\` | -| rank-n | `RankN` | Peyton Jones et al., "Practical Type Inference for Arbitrary-Rank Types" (2007) | `forall` under arrow LHS, `RankNTypes` | -| phantom | `Phantom` | Leijen & Meijer, "Domain Specific Embedded Compilers" (1999) | unused type parameter on data decl, ghost `PhantomData` | -| existential | `Exist` | Mitchell & Plotkin, "Abstract Types Have Existential Type" (1988) | `exists`, `∃`, `pack`/`unpack`, `Sigma`-as-existential | -| higher-kinded | `HKT` | Jones, "A System of Constructor Classes" (1995) | `f : Type -> Type`, kind annotations beyond `*` | -| row-poly | `Row` | Wand, "Complete Type Inference for Simple Objects" (1987); Rémy (1989) | `{l : t \| r}`, row variables, extensible records | - -### 2.2 Subtyping (4) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| subtyping | `Sub` | Cardelli, "A Semantics of Multiple Inheritance" (1984) | `<:`, `≤`, structural subsumption | -| intersection | `Int` | Coppo, Dezani-Ciancaglini & Venneri (1981) | `∩`, `&`, conjunctive types | -| union | `Uni` | Pierce, "Programming with Intersection Types, Union Types, and Polymorphism" (1991) | `∪`, `\|`, sum-as-untagged | -| gradual | `Gra` | Siek & Taha, "Gradual Typing for Functional Languages" (2006) | `?`, `dyn`, `Any` with consistency | - -### 2.3 Dependent (5) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| dependent | `Dep` | Martin-Löf, "Intuitionistic Type Theory" (1984) | `(x : A) -> B x`, `Π`, `Pi` | -| refinement | `Ref` | Freeman & Pfenning, "Refinement Types for ML" (1991); Rondon et al. Liquid (2008) | `{v : t \| p v}`, `predicate`, `requires`/`ensures` | -| hoare | `Hoa` | Hoare, "An Axiomatic Basis for Computer Programming" (1969); Nanevski et al. HTT | `{P} c {Q}`, `Hoare ?st ?p ?q` | -| indexed | `Ind` | Zenger, "Indexed Types" (1997); Xi & Pfenning DML (1999) | `Vec n a`, type-level Nat indices | -| qtt | `QTT` | McBride, "I Got Plenty o' Nuttin'" (2016); Atkey, "Syntax and Semantics of Quantitative Type Theory" (2018) | `0 \|- t : T`, multiplicities `0 / 1 / ω` | - -### 2.4 Substructural (5) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| linear | `Lin` | Wadler, "Linear Types Can Change the World!" (1990); Girard "Linear Logic" (1987) | `!`, `⊸`, `1` use exactly once | -| affine | `Aff` | TBD — fill from author (commonly cited: Walker, "Substructural Type Systems" in ATTAPL ch. 1, 2005) | at-most-once use, `Drop`, `move` semantics | -| relevant | `Rel` | TBD — fill from author (Walker ATTAPL ch. 1, 2005) | at-least-once use, mandatory consumption | -| ordered | `Ord` | Polakow & Pfenning, "Natural Deduction for Intuitionistic Non-commutative Linear Logic" (1999) | non-exchange contexts, sequence preservation | -| uniqueness | `Unq` | Barendsen & Smetsers, "Uniqueness Typing for Functional Languages" (1996) | Clean `*` annotation, unique-reference invariant | - -### 2.5 Mutability / capability (3) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| immutable | `Imm` | TBD — fill from author | `const`, `final`, `readonly`, `val` | -| capability | `Cap` | Crary, Walker & Morrisett, "Typed Memory Management in a Calculus of Capabilities" (1999) | `cap`, capability sets, `acquire`/`release` | -| bunched | `Bun` | O'Hearn & Pym, "The Logic of Bunched Implications" (1999) | `*` (separating conjunction), `-*`, BI assertion | - -### 2.6 Modal (4) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| modal | `Mod` | Pfenning & Davies, "A Judgmental Reconstruction of Modal Logic" (2001) | `□`, `◇`, `box`, `dia` | -| epistemic | `Epi` | Hintikka, "Knowledge and Belief" (1962); Fagin et al. (1995) | `K`, `K_i`, `knows`, agent indices | -| temporal | `Tem` | Pnueli, "The Temporal Logic of Programs" (1977) | `□`, `◇`, `next`, `until`, LTL/CTL operators | -| provability | `Prv` | Gödel, Löb; Boolos, "The Logic of Provability" (1993) | `Bew`, `Prov`, `□` as provability operator | - -### 2.7 Effects / coeffects (4) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| effect-row | `ERow` | Leijen, "Type Directed Compilation of Row-Typed Algebraic Effects" (2017) | ``, `effect E`, `handle` | -| impure | `Imp` | Wadler, "Comprehending Monads" (1990); Moggi (1989) | `IO`, `m a`, `do`-notation | -| coeffect | `Coef` | Petricek, Orchard & Mycroft, "Coeffects: Unified Static Analysis of Context-Dependence" (2014) | graded context, `[A]r`, resource grading | -| probabilistic | `Prob` | Borgström et al., "Measure Transformer Semantics for Bayesian Machine Learning" (2011) | `sample`, `observe`, distribution types | - -### 2.8 Session / process (4) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| session | `Ses` | Honda, "Types for Dyadic Interaction" (1993); Honda, Vasconcelos & Kubo (1998) | `!T.S`, `?T.S`, `end`, channel session types | -| choreographic | `Cho` | Carbone, Honda & Yoshida, "Multiparty Asynchronous Session Types" (2008); Montesi PhD (2013) | global protocol, role indices `A -> B : t` | -| dyadic | `Dy` | echo-types (`hyperpolymath/echo-types`); see also Honda's "dyadic interaction" (1993) | `dyad`, `peer A B`, two-party protocol | -| echo | `Echo` | echo-types (`hyperpolymath/echo-types`) — TBD canonical paper; provisional spec in repo `docs/` | `echo`, `replay`, `obs A`, observational equivalence under echo | - -### 2.9 Homotopy (3) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| homotopy | `Hom` | Univalent Foundations Program, "Homotopy Type Theory" (2013) | univalence axiom, `Path`, identity types as paths | -| cubical | `Cub` | Cohen, Coquand, Huber & Mörtberg, "Cubical Type Theory" (2018) | `Path`, `PathP`, `i0`/`i1`, interval `I` | -| nominal | `Nom` | Pitts, "Nominal Logic" (2001); Gabbay & Pitts (2002) | `name`, `swap`, `freshness ⊥`, `α`-equivalence | - -### 2.10 Resource (2) - -| Discipline | TypeLL Sigma | Canonical paper | Markers excerpt | -|---|---|---|---| -| tropical | `Trop` | tropical-resource-typing repo (`verification-ecosystem/tropical-resource-typing`); see also Speyer & Sturmfels (2009) for the algebra | tropical semiring `(min, +)`, resource cost annotations | -| ceremonial | `Cer` | Panll language spec (Panll = panll language) — TBD canonical paper; ceremonial sub-language doc in `panll/docs/` | `@[ceremony]`, `ritual`, ceremonial obligation markers | - -## 3. Detection topology - -``` -Corpus adapter ingests *. - → CorpusEntry { statement, proof, ... } (src/rust/corpus/mod.rs:138) - → detect_disciplines(adapter_name, statement, proof, registry) - (src/rust/disciplines/detector.rs) - → Vec (src/rust/disciplines/disciplines.rs) - → CorpusEntry.type_discipline_tags - → Octad SemanticPayload (src/rust/verisim_bridge.rs) - → VeriSimDB cross-prover identity index (E6 in VERISIM-ER-SCHEMA.md) - → Julia GNN training feature row (src/julia/training/train.jl) -``` - -The detector is pure: same `(adapter, statement, proof, registry)` always -returns the same `Vec`. The registry -(`src/rust/disciplines/registry.rs::MarkerRegistry`) is built once at -process start from `data/synonyms/_disciplines.toml` plus the -per-language augmentations in each `data/synonyms/.toml`. - -## 4. Per-adapter coverage matrix - -The 17 saturation-campaign adapters × 10 discipline families. `✓` means -the adapter routinely surfaces declarations in that family; `partial` -means only via specific idioms; `—` means the family is essentially -absent from typical sources for that adapter. - -### 4.1 Polymorphism, Subtyping (sub-table 1 of 4) - -| Adapter | HM | SF | RankN | Phantom | Exist | HKT | Row | Sub | Int | Uni | Gra | -|---|---|---|---|---|---|---|---|---|---|---|---| -| agda | ✓ | ✓ | ✓ | partial | ✓ | ✓ | — | — | — | — | — | -| coq | partial | ✓ | ✓ | partial | ✓ | ✓ | — | partial | — | — | — | -| lean | partial | ✓ | ✓ | partial | ✓ | ✓ | — | partial | — | — | — | -| idris2 | ✓ | ✓ | ✓ | partial | ✓ | ✓ | — | — | — | — | — | -| isabelle | ✓ | partial | — | partial | partial | partial | — | partial | — | — | — | -| metamath | — | — | — | — | — | — | — | — | — | — | — | -| mizar | — | — | — | — | — | — | — | partial | — | — | — | -| hol_light | ✓ | partial | — | partial | — | — | — | — | — | — | — | -| hol4 | ✓ | partial | — | partial | — | — | — | — | — | — | — | -| dafny | partial | — | — | partial | — | — | — | ✓ | — | — | — | -| why3 | ✓ | partial | — | partial | — | partial | — | partial | — | — | — | -| fstar | ✓ | ✓ | ✓ | partial | ✓ | partial | — | partial | — | — | — | -| acl2_books | — | — | — | — | — | — | — | — | — | — | — | -| tptp | — | partial | — | — | partial | — | — | — | — | — | — | -| smtlib | — | — | — | — | — | — | — | partial | — | — | — | -| proofnet | partial | partial | — | — | partial | — | — | — | — | — | — | -| minif2f | partial | partial | — | — | partial | — | — | — | — | — | — | - -### 4.2 Dependent, Substructural (sub-table 2 of 4) - -| Adapter | Dep | Ref | Hoa | Ind | QTT | Lin | Aff | Rel | Ord | Unq | -|---|---|---|---|---|---|---|---|---|---|---| -| agda | ✓ | partial | — | ✓ | — | ✓ | ✓ | — | — | — | -| coq | ✓ | partial | partial | ✓ | — | partial | partial | — | — | — | -| lean | ✓ | partial | partial | ✓ | — | partial | partial | — | — | — | -| idris2 | ✓ | partial | — | ✓ | ✓ | ✓ | ✓ | — | — | partial | -| isabelle | partial | — | ✓ | partial | — | — | — | — | — | — | -| metamath | — | — | — | — | — | — | — | — | — | — | -| mizar | partial | — | — | — | — | — | — | — | — | — | -| hol_light | — | — | partial | — | — | — | — | — | — | — | -| hol4 | — | — | partial | — | — | — | — | — | — | — | -| dafny | partial | ✓ | ✓ | partial | — | — | — | — | — | — | -| why3 | partial | ✓ | ✓ | partial | — | — | — | — | — | — | -| fstar | ✓ | ✓ | ✓ | ✓ | — | partial | partial | — | — | — | -| acl2_books | — | — | — | — | — | — | — | — | — | — | -| tptp | partial | — | — | — | — | — | — | — | — | — | -| smtlib | — | — | — | — | — | — | — | — | — | — | -| proofnet | partial | partial | partial | partial | — | — | — | — | — | — | -| minif2f | partial | partial | partial | partial | — | — | — | — | — | — | - -### 4.3 Mutability, Modal, Effects (sub-table 3 of 4) - -| Adapter | Imm | Cap | Bun | Mod | Epi | Tem | Prv | ERow | Imp | Coef | Prob | -|---|---|---|---|---|---|---|---|---|---|---|---| -| agda | — | — | — | partial | — | — | — | — | partial | — | — | -| coq | — | — | partial | partial | — | partial | partial | — | partial | — | — | -| lean | — | — | — | partial | — | partial | partial | — | partial | — | — | -| idris2 | — | — | — | — | — | — | — | partial | partial | — | — | -| isabelle | — | — | — | partial | partial | ✓ | partial | — | — | — | partial | -| metamath | — | — | — | partial | — | — | partial | — | — | — | — | -| mizar | — | — | — | — | — | — | — | — | — | — | — | -| hol_light | — | — | — | partial | — | partial | partial | — | — | — | — | -| hol4 | — | — | — | partial | — | partial | partial | — | — | — | — | -| dafny | ✓ | ✓ | partial | — | — | — | — | — | ✓ | — | — | -| why3 | partial | — | — | — | — | — | — | — | ✓ | — | — | -| fstar | partial | partial | partial | — | — | — | — | ✓ | ✓ | — | partial | -| acl2_books | — | — | — | — | — | partial | — | — | — | — | — | -| tptp | — | — | — | partial | partial | partial | — | — | — | — | — | -| smtlib | — | — | — | — | — | partial | — | — | — | — | — | -| proofnet | — | — | — | partial | — | — | — | — | partial | — | — | -| minif2f | — | — | — | partial | — | — | — | — | partial | — | — | - -### 4.4 Session, Homotopy, Resource (sub-table 4 of 4) - -| Adapter | Ses | Cho | Dy | Echo | Hom | Cub | Nom | Trop | Cer | -|---|---|---|---|---|---|---|---|---|---| -| agda | — | — | — | — | ✓ | ✓ | — | — | — | -| coq | — | — | — | — | partial | — | partial | — | — | -| lean | — | — | — | — | partial | — | — | — | — | -| idris2 | — | — | — | — | — | — | — | — | — | -| isabelle | — | — | — | — | — | — | partial | — | — | -| metamath | — | — | — | — | — | — | — | — | — | -| mizar | — | — | — | — | — | — | — | — | — | -| hol_light | — | — | — | — | — | — | — | — | — | -| hol4 | — | — | — | — | — | — | — | — | — | -| dafny | — | — | — | — | — | — | — | — | — | -| why3 | — | — | — | — | — | — | — | — | — | -| fstar | — | — | — | — | — | — | — | — | — | -| acl2_books | — | — | — | — | — | — | — | — | — | -| tptp | — | — | — | — | — | — | — | — | — | -| smtlib | — | — | — | — | — | — | — | — | — | -| proofnet | partial | — | — | — | partial | partial | — | — | — | -| minif2f | — | — | — | — | partial | partial | — | — | — | - -Cells are best-effort priors based on typical mathlib4 / stdlib / -AFP / mizar-mml content. The detector returns whatever markers fire, -so a `partial`-marked cell can still produce real tags when the -specific declaration uses the relevant idiom; the matrix only -documents expected hit frequency for triage. - -## 5. Crosswalk to TypeLL / Katagoria / VCL-UT / Panll - -### 5.1 TypeLL - -Each `TypeDiscipline` variant has a Sigma parameter name returned by -`src/rust/disciplines/disciplines.rs::typell_sigma()`. The Sigma names are -single-token strings (`"HM"`, `"SF"`, `"Lin"`, `"Aff"`, `"Dep"`, -`"QTT"`, `"Echo"`, `"Cub"`, `"Trop"`, `"Cer"`, …) and exactly match -the discipline tag passed to `typell --discipline=` by -`src/rust/provers/hp_ecosystem.rs:63-126`. The Sigma table is the -single source of truth for the discipline ↔ CLI mapping; this -document does not re-list it. - -### 5.2 Katagoria - -Katagoria (`hyperpolymath/katagoria`, dispatched as -`ProverKind::KatagoriaVerifier` at -`src/rust/provers/hp_ecosystem.rs:66`) reserves invariant slots -keyed by discipline tag. The intended mapping — which tags populate -which Katagoria invariant slots — is **TBD — needs Katagoria spec -audit**. Until then, the detector emits the tag and Katagoria -consumers ignore unknown tags. - -### 5.3 VCL-UT - -VCL-UT (`src/rust/vcl_ut.rs:1-1083`) already exposes a 10-level -`TypeLevel` safety annotation. Discipline tags are orthogonal: a -VCL-UT query can additionally constrain by discipline, e.g. - -```text -select octad -where_discipline(TypeDiscipline::Linear) -where type_level >= TypeLevel::L7 -``` - -The VCL-UT planner pushes the discipline filter down to the -`octads_semantic` materialised view (E2 in `VERISIM-ER-SCHEMA.md`), -which indexes on the new `type_discipline_tags` array column. - -### 5.4 Panll - -Panll's type system is the union of all 39 disciplines plus -cross-discipline composition operators (per the -`panll/docs/type-system/` design notes). Discipline tags are -**pre-Panll annotation**: they are computed by adapters that pre-date -the Panll compiler, stored in VeriSimDB, and consumed downstream once -Panll lands. The contract is: - -- adapters MUST emit tags they detect, even if Panll cannot yet - consume them; -- Panll's compiler, when it ships, MUST read `type_discipline_tags` - as hints (not authoritative) and may refine or extend the set. - -## 6. Wire schema impact - -The `SemanticPayload` struct in `src/rust/verisim_bridge.rs` gains a -new field: - -```rust -pub struct SemanticPayload { - // ...existing fields... - pub type_discipline_tags: Vec, // kebab-case slugs -} -``` - -The slugs are the canonical discipline names from §2 (e.g. -`"hindley-milner"`, `"linear"`, `"echo"`, `"tropical"`). - -The Cap'n Proto schema at -`crates/echidna-wire/schemas/verisim_er.capnp` adds field 11 on the -`Semantic` struct: - -```capnp -struct Semantic { - # ...fields @0..@10 unchanged... - typeDisciplineTags @11 :List(Text); -} -``` - -VeriSimDB stores this as an `Array(LowCardinality(String))` column on -the `octads_semantic` table, with a secondary skip index for -discipline-filtered queries. The drift-detection SHA in §"Drift -detection" of `VERISIM-ER-SCHEMA.md` MUST be re-computed when this -field lands. - -## 7. Detection confidence - -The detector is heuristic; tags are emitted when cumulative marker -score for a discipline exceeds 0.7. Marker entries in -`MarkerRegistry` have shape: - -```rust -pub struct Marker { - pub pattern: String, // literal string or regex (compiled lazily) - pub discipline: TypeDiscipline, - pub weight: f64, // 0.0..1.0 - pub adapters: &'static [&'static str], // empty == language-agnostic -} -``` - -- **HIGH-confidence markers** like `@[ceremony]` are unambiguous — - weight 0.95. A single occurrence crosses the 0.7 threshold. -- **MEDIUM-confidence markers** like `forall` need corroborating - evidence (e.g. a type variable in scope) before they tag - System F or Rank-N. Typical weight 0.45–0.6. -- **LOW-confidence markers** like `!` (which could be linear-logic - exponential, boolean negation, factorial, or Haskell strictness) - carry weight 0.2 and require multiple co-occurring markers to fire. - -The `adapters` slice scopes a marker: `adapters: &[]` (empty) means -the marker is language-agnostic; `adapters: &["lean"]` restricts it -to Lean sources only. This matters because `!` means "linear bang" in -Linear Logic encodings but "decide" in Lean tactic scripts. - -## 8. Per-discipline owner-direction status - -Status of the nine disciplines the owner explicitly called out during -campaign scoping: - -- **linear**: ✓ detector + markers + synonyms shipped - (`data/synonyms/_disciplines.toml::[linear]`). -- **affine**: ✓ ditto. Cross-references the Rust borrow-checker - vocabulary (`move`, `Copy`, `Drop`) used in `idaptik` corpus. -- **dependent**: ✓ ditto. Routes through `DependentTypeChecker` - (`src/rust/provers/hp_ecosystem.rs:75`). -- **equality**: ✓ as part of subtyping/dependent; markers `=`, `≡`, - `==`, propositional-equality (`Path`, `Id`, `eq`). Not a standalone - Sigma; surfaces under `Dep` or `Hom` depending on context. -- **ceremonial**: ✓ markers shipped (`@[ceremony]`, `ritual`, - ceremonial-obligation slugs). Detector may need expansion as Panll's - ceremonial sub-language stabilises. -- **dyadic**: ✓ from echo-types (`hyperpolymath/echo-types`); routes - through `DyadicTypeChecker` - (`src/rust/provers/hp_ecosystem.rs:111`). -- **tropical**: ✓ from tropical-resource-typing repo; routes through - `TropicalTypeChecker` (`src/rust/provers/hp_ecosystem.rs:67`). -- **choreographic**: ✓ markers shipped (global-protocol syntax, - multi-role declarations); routes through - `ChoreographicTypeChecker` (`src/rust/provers/hp_ecosystem.rs:68`). -- **epistemic**: ✓ markers shipped (`K`, `K_i`, `knows`); routes - through `EpistemicTypeChecker` - (`src/rust/provers/hp_ecosystem.rs:69`). - -## 9. Integration with the GNN training pipeline - -The `type_discipline_tags` field flows from CorpusEntry → octad -emission → Julia corpus loader → training example: - -``` -CorpusEntry.type_discipline_tags - → SemanticPayload.type_discipline_tags (verisim_bridge.rs) - → octads_semantic.type_discipline_tags (VeriSimDB column) - → premises_.jsonl (corpus-emit CLI) - → src/julia/training/corpus_loader.jl (reads JSONL) - → TrainingExample.discipline_features (39-dim multi-hot) - → train.jl (consumes both heads) -``` - -Two heads: - -- **Value head**: discipline tags are concatenated as a 39-dim - multi-hot vector and fed to the value-prediction MLP. Disciplines - that imply harder goals (Dep, QTT, Cub) shift the value prior down; - the model learns the offsets. -- **Policy head**: discipline tags constrain candidate tactics. For a - `Linear`-tagged goal, the policy head prefers tactics that respect - linearity (no duplication, no discarding). The constraint is a soft - prior implemented as a logit bias in the tactic-ranking softmax — - see the GNN service in `src/julia/server/gnn_api.jl`. - -## 10. Open follow-ups - -- **T1** — wire `type_discipline_tags` into `CorpusEntry` serde so - every adapter's emit path populates the field. -- **T2** — each per-language detector gets adapter-aware refinement - beyond plain text-matching (e.g. AST-walking the Coq term for - `Π`-binders rather than regexing the source). -- **T3** — Cap'n Proto schema delta on `Semantic @11`. -- **T4** — `src/julia/training/corpus_loader.jl` pass-through of the - 39-dim feature. -- **T5** — cross-reference echo-types repo - (`hyperpolymath/echo-types`) for the canonical Echo / Dyadic marker - set; audit pending. Per the standing - "[Proofs MUST check + cross-doc echo-types]" directive, every - Echo/Dyadic marker addition MUST first audit echo-types and reuse - if applicable, extend upstream WITH proofs if not. -- **T6** — Katagoria invariant-slot mapping (§5.2) needs spec audit. -- **T7** — Panll's compiler integration once it lands (§5.4). - -## 11. References - -- `src/rust/disciplines/disciplines.rs` — the `TypeDiscipline` enum and - `typell_sigma()` mapping. -- `src/rust/disciplines/registry.rs` — the `MarkerRegistry`. -- `src/rust/disciplines/detector.rs` — the `detect_disciplines` entry - point. -- `data/synonyms/_disciplines.toml` — the cross-prover discipline - vocabulary. -- `docs/architecture/VERISIM-ER-SCHEMA.md` — E2 Semantic modality - target (this doc adds field `@11`). -- `crates/echidna-wire/schemas/verisim_er.capnp` — wire schema - (pending field-11 delta per T3). -- `crates/typed_wasm/src/lib.rs` — Sigma parameter routing target. -- `src/rust/provers/hp_ecosystem.rs:63-126` — 39-discipline dispatch - table. -- `docs/PROVER_COUNT.md` Tier 9 — the canonical tier table. -- `docs/CORPUS-ADAPTERS.md` — adapter inventory consumed by §4. diff --git a/docs/architecture/VERISIM-ER-SCHEMA.adoc b/docs/architecture/VERISIM-ER-SCHEMA.adoc new file mode 100644 index 00000000..8c8d3700 --- /dev/null +++ b/docs/architecture/VERISIM-ER-SCHEMA.adoc @@ -0,0 +1,438 @@ +== VeriSim ↔ ECHIDNA Entity-Relationship Schema + +*Status*: canonical. Replaces the aspirational text in +`+docs/design/ECHIDNA-VERISIM-TRIANGULATION-2026-04-17.adoc+` as the +formal data-model spec. *Last revised*: 2026-06-01. *Companion*: +`+crates/echidna-wire/schemas/verisim_er.capnp+` (wire format). + +=== Why a formal E-R now + +The 2026-04-17 triangulation document described the _workflow_ for +absorbing 41 provers across 4 phases. It did NOT define the entities +themselves. Implementation drift was easy: the Rust octad payload in +`+src/rust/verisim_bridge.rs+` carries 8 modalities, but the ClickHouse +/ VeriSimDB store at the other end uses 11 tables (per the VeriSimDB +README) — what maps to what was implicit. + +This document closes the gap. Every entity has: + +* a Rust struct it implements, +* a VeriSimDB table it stores in, +* a Cap’n Proto schema it serialises through (where wire-level contracts +apply), and +* a primary key + foreign-key set. + +Diagram drift is detected by a single hash over this file plus the +`+.capnp+` schema; mismatches are blocked by the per-PR `+er-drift+` CI +gate (TODO — track in `+docs/decisions/2026-06-01-er-drift-gate.md+`). + +=== Entity inventory + +There are *12 first-class entities* and *7 first-class relationships*. + +==== E1 — `+Octad+` + +A snapshot of one declaration (theorem / lemma / definition / axiom) at +one moment in time, with all 8 modalities populated. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Source of truth +|`+key+` (PK) |`+UUIDv7+` |Generated client-side at builder time + +|`+created_at+` |`+Timestamp+` |Auto-set on insert + +|`+adapter+` |`+String+` +(`+"agda"+`/`+"coq"+`/…/`+"metamath"+`/`+"mizar"+`/`+"tptp"+`/`+"smtlib"+`/`+"proofnet"+`/`+"minif2f"+`) +|`+Corpus.adapter+` + +|`+module_qualified+` |`+String+` |`+CorpusEntry.qualified+` +|=== + +Rust: `+src/rust/verisim_bridge.rs::OctadPayload+` Cap’n Proto: +`+verisim_er.capnp::Octad+` (struct id `+@0x80…001+`) VeriSimDB table: +`+octads+` Implementation status: *complete*. + +==== E2 — `+SemanticModality+` + +The textual / structural content of the declaration. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+octad_key+` (PK,FK→E1) |`+UUIDv7+` |one-to-one with Octad + +|`+kind+` |enum +`+Function+`/`+Data+`/`+Record+`/`+Postulate+`/`+Module+` |`+DeclKind+` +from `+src/rust/corpus/mod.rs:53+` + +|`+name+` |`+String+` |local name + +|`+statement+` |`+String+` |type signature + +|`+proof+` |`+Option+` |proof body — None for postulates +|=== + +Rust: `+OctadPayload.semantic+` Cap’n Proto: +`+verisim_er.capnp::Semantic+` VeriSimDB table: `+octads_semantic+` + +==== E3 — `+TemporalModality+` + +Version chain across edits, refactorings, rename events. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+octad_key+` (PK,FK→E1) |`+UUIDv7+` | + +|`+versions+` |`+List+` |each entry: timestamp, +change_kind, parent_key + +|`+parent_octad_key+` |`+Option+` |self-FK: previous version of +this declaration +|=== + +Rust: `+OctadPayload.temporal+` VeriSimDB table: `+octads_temporal+` +Foreign-key cycle: `+temporal.parent_octad_key → octads.key+` (self). + +==== E4 — `+ProvenanceModality+` + +Hash chain for replay + audit (who ingested when from where). + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+octad_key+` (PK,FK→E1) |`+UUIDv7+` | + +|`+source_hash+` |`+String+` (SHA-256 hex) |hash of the originating +source file + +|`+ingest_actor+` |`+String+` |who/what ran the ingest (CI job ID, user +agent) + +|`+ingest_ts+` |`+Timestamp+` | + +|`+chain_prev_hash+` |`+Option+` |previous link in chain +|=== + +Rust: `+OctadPayload.provenance+` VeriSimDB table: `+octads_provenance+` + +==== E5 — `+DocumentModality+` + +Full-text searchable representation (for `+near_text+` queries). + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+octad_key+` (PK,FK→E1) |`+UUIDv7+` | + +|`+searchable_text+` |`+String+` |name + statement + proof + aspects, +lowercased + +|`+aspects+` |`+List+` |aspect tags (`+induction+`, +`+well-founded+`, …) +|=== + +Rust: `+OctadPayload.document+` VeriSimDB table: `+octads_document+` +Indexed by: Tantivy full-text index on `+searchable_text+`. + +==== E6 — `+GraphModality+` + +Dependency edges + cross-prover identity edges. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+octad_key+` (PK,FK→E1) |`+UUIDv7+` | + +|`+depends_on+` |`+List+` |forward deps + +|`+depended_on_by+` |`+List+` |reverse deps + +|`+cross_prover_identity_key+` |`+String+` |groups Octads representing +the SAME mathematical object across adapters — see Rel-2 below +|=== + +Rust: `+OctadPayload.graph+` VeriSimDB table: `+octads_graph+` Indexed +by: `+cross_prover_identity_key+` (HNSW for fuzzy match, exact for +direct). + +==== E7 — `+VectorModality+` + +Goal embeddings for `+near_text+` and GNN-guided search. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+octad_key+` (PK,FK→E1) |`+UUIDv7+` | + +|`+goal_embedding+` |`+List+` |currently 32-dim HashEmbedder, +future 256-dim GNN + +|`+embedder+` |`+String+` (`+"hash-v1"+`/`+"gnn-v1"+`) |versioning +|=== + +Rust: `+OctadPayload.vector+` VeriSimDB table: `+octads_vector+` Indexed +by: HNSW on `+goal_embedding+`. + +==== E8 — `+TensorModality+` + +Numeric metrics over the declaration (proof depth, AST size, hazard flag +bitmap, …). + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+octad_key+` (PK,FK→E1) |`+UUIDv7+` | + +|`+proof_depth+` |`+u32+` |tactic nesting depth + +|`+statement_size_tokens+` |`+u32+` | + +|`+hazard_bitmap+` |`+u32+` |postulate / believe_me / admit / sorry / +trustme / other + +|`+axiom_count+` |`+u32+` |declared axioms touched +|=== + +Rust: `+OctadPayload.tensor+` VeriSimDB table: `+octads_tensor+` + +==== E9 — `+SpatialModality+` + +File path + line number in the originating source tree. + +[cols=",,",options="header",] +|=== +|Field |Type |Notes +|`+octad_key+` (PK,FK→E1) |`+UUIDv7+` | +|`+file_path+` |`+String+` |relative to corpus root +|`+line+` |`+u32+` |1-based +|`+column+` |`+Option+` |optional column start +|=== + +Rust: `+OctadPayload.spatial+` VeriSimDB table: `+octads_spatial+` + +==== E10 — `+ProofAttempt+` + +A single invocation of a prover backend against a goal. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+attempt_id+` (PK) |`+UUIDv7+` | + +|`+octad_key+` (FK→E1) |`+UUIDv7+` |the goal + +|`+prover+` |enum `+ProverKind+` |which of the 128 backends + +|`+verdict+` |enum +`+Proven+`/`+Refuted+`/`+Timeout+`/`+Unknown+`/`+Error+` |outcome + +|`+started_at+` |`+Timestamp+` | + +|`+latency_ms+` |`+u64+` |wall-clock + +|`+axiom_cost+` |`+u32+` |declared axioms used (input to E16) + +|`+certificate_blob_key+` |`+Option+` |pointer into E11 + +|`+confidence_self_reported+` |`+Option+` |when the backend +self-rates +|=== + +Rust: `+src/rust/verisim_bridge.rs::ProofAttempt+` VeriSimDB table: +`+proof_attempts+` + +==== E11 — `+CertificateBlob+` + +Raw proof certificate produced by the backend (Alethe, DRAT/LRAT, TSTP, +OpenTheory, Dedukti, Lambdapi). + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+blob_key+` (PK) |`+String+` (SHAKE3-512 hex of contents) +|content-addressed + +|`+format+` |enum +`+Alethe+`/`+Drat+`/`+Lrat+`/`+Tstp+`/`+OpenTheory+`/`+Dedukti+`/`+Lambdapi+`/`+SmtCoq+`/`+Other+` +|exchange format + +|`+bytes+` |`+Bytes+` |raw certificate + +|`+created_at+` |`+Timestamp+` | +|=== + +Rust: TBD — currently inlined in `+ProofAttempt.certificate_path+`. +*Migration entry*: extract to dedicated table 2026-Q3. VeriSimDB table: +`+certificate_blobs+` + +==== E12 — `+ProverBinaryIntegrity+` + +Hash-pinned identity of the binary that produced an attempt. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Field |Type |Notes +|`+prover+` (PK part 1) |enum `+ProverKind+` | + +|`+binary_hash+` (PK part 2) |`+String+` (SHAKE3-512 + BLAKE3) +|dual-hash + +|`+version_label+` |`+String+` |`+"z3-4.13.0-ubuntu22-x64"+` etc. + +|`+first_seen_ts+` |`+Timestamp+` | +|=== + +Rust: `+src/rust/integrity/solver_integrity.rs+` VeriSimDB table: +`+prover_binary_integrity+` + +=== Relationship inventory + +==== Rel-1 — `+Octad has-modalities+` (composition) + +`+Octad (1) — (1) {Semantic, Temporal, Provenance, Document, Graph, Vector, Tensor, Spatial}+` + +Composition. Deleting an Octad cascades all modality rows. Each modality +table holds at most one row per octad_key. + +==== Rel-2 — `+Cross-prover identity+` (many-to-many self-relation on E1) + +`+Octad (M) ←→ (N) Octad+` keyed by +`+GraphModality.cross_prover_identity_key+`. + +Semantics: two Octads `+o1+`, `+o2+` are _cross-prover-identified_ iff +`+o1.graph.cross_prover_identity_key == o2.graph.cross_prover_identity_key+` +AND they have distinct adapters. Example: the Coq `+Nat.add_comm+` and +the Lean `+Nat.add_comm+` both carry identity key +`+"nat-add-commutativity"+`. Used to answer queries like _"`every prover +that has formalised theorem X`"_. + +Materialised view: `+cross_prover_clusters+` in VeriSimDB. + +==== Rel-3 — `+ProofAttempt of Octad+` + +`+ProofAttempt (M) → (1) Octad+` + +A single Octad accumulates many ProofAttempts (one per prover × time). +The attempt FK enables the `+query_prover_success_by_class+` analytic. + +==== Rel-4 — `+ProofAttempt produces CertificateBlob+` + +`+ProofAttempt (1) → (0..1) CertificateBlob+` + +Optional: only some backends emit machine-checkable certificates. +Cardinality is 0..1 because failed attempts produce no blob. + +==== Rel-5 — `+ProofAttempt runs ProverBinaryIntegrity+` + +`+ProofAttempt (M) → (1) ProverBinaryIntegrity+` + +Every attempt links to the exact binary that ran. Enables replay: +"`reproduce attempt X`" = fetch the binary at this hash + re-run. + +==== Rel-6 — `+Octad depends-on Octad+` (DAG) + +`+Octad (M) → (N) Octad+` keyed by `+GraphModality.depends_on+`. + +Forward-dep edges. Transitively walked by `+Corpus::closure+`. The +reverse edges in `+depended_on_by+` are computed by `+Corpus::reindex+` +and stored materialised in `+octads_graph+` for query speed. + +==== Rel-7 — `+Octad evolved-from Octad+` (linear chain) + +`+Octad (1) → (0..1) Octad+` keyed by +`+TemporalModality.parent_octad_key+`. + +The version chain. Used to answer "`what did this theorem look like +before refactor X?`". Stored as a singly-linked list — chain head has +`+parent_octad_key == None+`. + +=== ENTITY ↔ STRUCT ↔ TABLE crosswalk + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Entity |Rust struct |Cap’n Proto |ClickHouse table +|E1 Octad |`+OctadPayload+` |`+Octad@0x80…001+` |`+octads+` + +|E2 Semantic |`+SemanticPayload+` |`+Semantic@0x80…002+` +|`+octads_semantic+` + +|E3 Temporal |`+TemporalPayload+` |`+Temporal@0x80…003+` +|`+octads_temporal+` + +|E4 Provenance |`+ProvenancePayload+` |`+Provenance@0x80…004+` +|`+octads_provenance+` + +|E5 Document |`+DocumentPayload+` |`+Document@0x80…005+` +|`+octads_document+` + +|E6 Graph |`+GraphPayload+` |`+Graph@0x80…006+` |`+octads_graph+` + +|E7 Vector |`+VectorPayload+` |`+Vector@0x80…007+` |`+octads_vector+` + +|E8 Tensor |`+TensorPayload+` |`+Tensor@0x80…008+` |`+octads_tensor+` + +|E9 Spatial |`+SpatialPayload+` |`+Spatial@0x80…009+` +|`+octads_spatial+` + +|E10 ProofAttempt |`+ProofAttempt+` |`+ProofAttempt@0x80…00a+` +|`+proof_attempts+` + +|E11 CertificateBlob |(extract pending) |`+CertificateBlob@0x80…00b+` +|`+certificate_blobs+` + +|E12 ProverBinaryIntegrity |`+ProverBinaryIntegrity+` +|`+ProverBinaryIntegrity@0x80…00c+` |`+prover_binary_integrity+` +|=== + +=== Drift detection + +The single source of truth is this document plus its companion +`+verisim_er.capnp+` schema. Any code change that adds, removes, or +renames an entity / relationship MUST also update both files in the same +PR. A CI gate (TODO: `+er-drift.yml+`) computes: + +.... +sha256( cat docs/architecture/VERISIM-ER-SCHEMA.md + crates/echidna-wire/schemas/verisim_er.capnp ) +.... + +and fails the build if the result differs from the value stored in +`+.machine_readable/er-schema.sha256+`. When the schema changes +intentionally, update the SHA in the same PR. + +=== Open migrations (tracked here, not in CHANGELOG) + +[width="100%",cols="50%,50%",options="header",] +|=== +|Item |Status +|Extract `+CertificateBlob+` to dedicated table (currently inlined) +|tracked, 2026-Q3 + +|Add `+er-drift.yml+` CI gate |tracked, see +`+docs/decisions/2026-06-01-er-drift-gate.md+` + +|Cap’n Proto schema concrete struct IDs (placeholder `+@0x80…001+` etc.) +|tracked, fill before first wire-level consumer + +|Migrate `+query.rs+` to span multiple adapters (currently +single-adapter) |tracked, see capstone in `+src/rust/corpus/query.rs+` + +|VeriSim-side: ensure all 12 entities have writers + readers (currently +10/12 — E11 + E12 deferred) |tracked at verisimdb#XX +|=== + +=== Cross-document references + +* Octad implementation: `+src/rust/verisim_bridge.rs:36-471+` +* VCL-UT query language: `+src/rust/vcl_ut.rs:1-1083+` (consumer of this +schema) +* Learning data flow: `+docs/LEARNING-ARCHITECTURE.adoc+` (consumer of +`+proof_attempts+`) +* Arbitration: +`+src/rust/verification/{portfolio,bayesian_arbiter,dempster_shafer,pareto_arbiter}.rs+` +(consumers of `+proof_attempts+`) +* Corpus adapters: +`+src/rust/corpus/{agda,coq,lean,idris2,isabelle,metamath,mizar,hol_light,hol4,dafny,why3,fstar,acl2_books,tptp,smtlib,proofnet,minif2f}.rs+` +(producers of E1–E9) diff --git a/docs/architecture/VERISIM-ER-SCHEMA.md b/docs/architecture/VERISIM-ER-SCHEMA.md deleted file mode 100644 index af11c159..00000000 --- a/docs/architecture/VERISIM-ER-SCHEMA.md +++ /dev/null @@ -1,331 +0,0 @@ - - -# VeriSim ↔ ECHIDNA Entity-Relationship Schema - -**Status**: canonical. Replaces the aspirational text in -`docs/design/ECHIDNA-VERISIM-TRIANGULATION-2026-04-17.adoc` as the -formal data-model spec. -**Last revised**: 2026-06-01. -**Companion**: `crates/echidna-wire/schemas/verisim_er.capnp` (wire format). - -## Why a formal E-R now - -The 2026-04-17 triangulation document described the *workflow* for -absorbing 41 provers across 4 phases. It did NOT define the entities -themselves. Implementation drift was easy: the Rust octad payload in -`src/rust/verisim_bridge.rs` carries 8 modalities, but the -ClickHouse / VeriSimDB store at the other end uses 11 tables (per the -VeriSimDB README) — what maps to what was implicit. - -This document closes the gap. Every entity has: - -- a Rust struct it implements, -- a VeriSimDB table it stores in, -- a Cap'n Proto schema it serialises through (where wire-level - contracts apply), and -- a primary key + foreign-key set. - -Diagram drift is detected by a single hash over this file plus the -`.capnp` schema; mismatches are blocked by the per-PR `er-drift` CI -gate (TODO — track in `docs/decisions/2026-06-01-er-drift-gate.md`). - -## Entity inventory - -There are **12 first-class entities** and **7 first-class relationships**. - -### E1 — `Octad` - -A snapshot of one declaration (theorem / lemma / definition / axiom) -at one moment in time, with all 8 modalities populated. - -| Field | Type | Source of truth | -|---|---|---| -| `key` (PK) | `UUIDv7` | Generated client-side at builder time | -| `created_at` | `Timestamp` | Auto-set on insert | -| `adapter` | `String` (`"agda"`/`"coq"`/…/`"metamath"`/`"mizar"`/`"tptp"`/`"smtlib"`/`"proofnet"`/`"minif2f"`) | `Corpus.adapter` | -| `module_qualified` | `String` | `CorpusEntry.qualified` | - -Rust: `src/rust/verisim_bridge.rs::OctadPayload` -Cap'n Proto: `verisim_er.capnp::Octad` (struct id `@0x80…001`) -VeriSimDB table: `octads` -Implementation status: **complete**. - -### E2 — `SemanticModality` - -The textual / structural content of the declaration. - -| Field | Type | Notes | -|---|---|---| -| `octad_key` (PK,FK→E1) | `UUIDv7` | one-to-one with Octad | -| `kind` | enum `Function`/`Data`/`Record`/`Postulate`/`Module` | `DeclKind` from `src/rust/corpus/mod.rs:53` | -| `name` | `String` | local name | -| `statement` | `String` | type signature | -| `proof` | `Option` | proof body — None for postulates | - -Rust: `OctadPayload.semantic` -Cap'n Proto: `verisim_er.capnp::Semantic` -VeriSimDB table: `octads_semantic` - -### E3 — `TemporalModality` - -Version chain across edits, refactorings, rename events. - -| Field | Type | Notes | -|---|---|---| -| `octad_key` (PK,FK→E1) | `UUIDv7` | | -| `versions` | `List` | each entry: timestamp, change_kind, parent_key | -| `parent_octad_key` | `Option` | self-FK: previous version of this declaration | - -Rust: `OctadPayload.temporal` -VeriSimDB table: `octads_temporal` -Foreign-key cycle: `temporal.parent_octad_key → octads.key` (self). - -### E4 — `ProvenanceModality` - -Hash chain for replay + audit (who ingested when from where). - -| Field | Type | Notes | -|---|---|---| -| `octad_key` (PK,FK→E1) | `UUIDv7` | | -| `source_hash` | `String` (SHA-256 hex) | hash of the originating source file | -| `ingest_actor` | `String` | who/what ran the ingest (CI job ID, user agent) | -| `ingest_ts` | `Timestamp` | | -| `chain_prev_hash` | `Option` | previous link in chain | - -Rust: `OctadPayload.provenance` -VeriSimDB table: `octads_provenance` - -### E5 — `DocumentModality` - -Full-text searchable representation (for `near_text` queries). - -| Field | Type | Notes | -|---|---|---| -| `octad_key` (PK,FK→E1) | `UUIDv7` | | -| `searchable_text` | `String` | name + statement + proof + aspects, lowercased | -| `aspects` | `List` | aspect tags (`induction`, `well-founded`, …) | - -Rust: `OctadPayload.document` -VeriSimDB table: `octads_document` -Indexed by: Tantivy full-text index on `searchable_text`. - -### E6 — `GraphModality` - -Dependency edges + cross-prover identity edges. - -| Field | Type | Notes | -|---|---|---| -| `octad_key` (PK,FK→E1) | `UUIDv7` | | -| `depends_on` | `List` | forward deps | -| `depended_on_by` | `List` | reverse deps | -| `cross_prover_identity_key` | `String` | groups Octads representing the SAME mathematical object across adapters — see Rel-2 below | - -Rust: `OctadPayload.graph` -VeriSimDB table: `octads_graph` -Indexed by: `cross_prover_identity_key` (HNSW for fuzzy match, exact for direct). - -### E7 — `VectorModality` - -Goal embeddings for `near_text` and GNN-guided search. - -| Field | Type | Notes | -|---|---|---| -| `octad_key` (PK,FK→E1) | `UUIDv7` | | -| `goal_embedding` | `List` | currently 32-dim HashEmbedder, future 256-dim GNN | -| `embedder` | `String` (`"hash-v1"`/`"gnn-v1"`) | versioning | - -Rust: `OctadPayload.vector` -VeriSimDB table: `octads_vector` -Indexed by: HNSW on `goal_embedding`. - -### E8 — `TensorModality` - -Numeric metrics over the declaration (proof depth, AST size, hazard -flag bitmap, …). - -| Field | Type | Notes | -|---|---|---| -| `octad_key` (PK,FK→E1) | `UUIDv7` | | -| `proof_depth` | `u32` | tactic nesting depth | -| `statement_size_tokens` | `u32` | | -| `hazard_bitmap` | `u32` | postulate / believe_me / admit / sorry / trustme / other | -| `axiom_count` | `u32` | declared axioms touched | - -Rust: `OctadPayload.tensor` -VeriSimDB table: `octads_tensor` - -### E9 — `SpatialModality` - -File path + line number in the originating source tree. - -| Field | Type | Notes | -|---|---|---| -| `octad_key` (PK,FK→E1) | `UUIDv7` | | -| `file_path` | `String` | relative to corpus root | -| `line` | `u32` | 1-based | -| `column` | `Option` | optional column start | - -Rust: `OctadPayload.spatial` -VeriSimDB table: `octads_spatial` - -### E10 — `ProofAttempt` - -A single invocation of a prover backend against a goal. - -| Field | Type | Notes | -|---|---|---| -| `attempt_id` (PK) | `UUIDv7` | | -| `octad_key` (FK→E1) | `UUIDv7` | the goal | -| `prover` | enum `ProverKind` | which of the 128 backends | -| `verdict` | enum `Proven`/`Refuted`/`Timeout`/`Unknown`/`Error` | outcome | -| `started_at` | `Timestamp` | | -| `latency_ms` | `u64` | wall-clock | -| `axiom_cost` | `u32` | declared axioms used (input to E16) | -| `certificate_blob_key` | `Option` | pointer into E11 | -| `confidence_self_reported` | `Option` | when the backend self-rates | - -Rust: `src/rust/verisim_bridge.rs::ProofAttempt` -VeriSimDB table: `proof_attempts` - -### E11 — `CertificateBlob` - -Raw proof certificate produced by the backend (Alethe, DRAT/LRAT, -TSTP, OpenTheory, Dedukti, Lambdapi). - -| Field | Type | Notes | -|---|---|---| -| `blob_key` (PK) | `String` (SHAKE3-512 hex of contents) | content-addressed | -| `format` | enum `Alethe`/`Drat`/`Lrat`/`Tstp`/`OpenTheory`/`Dedukti`/`Lambdapi`/`SmtCoq`/`Other` | exchange format | -| `bytes` | `Bytes` | raw certificate | -| `created_at` | `Timestamp` | | - -Rust: TBD — currently inlined in `ProofAttempt.certificate_path`. **Migration entry**: extract to dedicated table 2026-Q3. -VeriSimDB table: `certificate_blobs` - -### E12 — `ProverBinaryIntegrity` - -Hash-pinned identity of the binary that produced an attempt. - -| Field | Type | Notes | -|---|---|---| -| `prover` (PK part 1) | enum `ProverKind` | | -| `binary_hash` (PK part 2) | `String` (SHAKE3-512 + BLAKE3) | dual-hash | -| `version_label` | `String` | `"z3-4.13.0-ubuntu22-x64"` etc. | -| `first_seen_ts` | `Timestamp` | | - -Rust: `src/rust/integrity/solver_integrity.rs` -VeriSimDB table: `prover_binary_integrity` - -## Relationship inventory - -### Rel-1 — `Octad has-modalities` (composition) - -`Octad (1) — (1) {Semantic, Temporal, Provenance, Document, Graph, -Vector, Tensor, Spatial}` - -Composition. Deleting an Octad cascades all modality rows. -Each modality table holds at most one row per octad_key. - -### Rel-2 — `Cross-prover identity` (many-to-many self-relation on E1) - -`Octad (M) ←→ (N) Octad` keyed by `GraphModality.cross_prover_identity_key`. - -Semantics: two Octads `o1`, `o2` are *cross-prover-identified* -iff `o1.graph.cross_prover_identity_key == o2.graph.cross_prover_identity_key` -AND they have distinct adapters. Example: the Coq `Nat.add_comm` and -the Lean `Nat.add_comm` both carry identity key -`"nat-add-commutativity"`. Used to answer queries like *"every prover -that has formalised theorem X"*. - -Materialised view: `cross_prover_clusters` in VeriSimDB. - -### Rel-3 — `ProofAttempt of Octad` - -`ProofAttempt (M) → (1) Octad` - -A single Octad accumulates many ProofAttempts (one per prover × time). -The attempt FK enables the `query_prover_success_by_class` analytic. - -### Rel-4 — `ProofAttempt produces CertificateBlob` - -`ProofAttempt (1) → (0..1) CertificateBlob` - -Optional: only some backends emit machine-checkable certificates. -Cardinality is 0..1 because failed attempts produce no blob. - -### Rel-5 — `ProofAttempt runs ProverBinaryIntegrity` - -`ProofAttempt (M) → (1) ProverBinaryIntegrity` - -Every attempt links to the exact binary that ran. Enables replay: -"reproduce attempt X" = fetch the binary at this hash + re-run. - -### Rel-6 — `Octad depends-on Octad` (DAG) - -`Octad (M) → (N) Octad` keyed by `GraphModality.depends_on`. - -Forward-dep edges. Transitively walked by `Corpus::closure`. The -reverse edges in `depended_on_by` are computed by `Corpus::reindex` -and stored materialised in `octads_graph` for query speed. - -### Rel-7 — `Octad evolved-from Octad` (linear chain) - -`Octad (1) → (0..1) Octad` keyed by `TemporalModality.parent_octad_key`. - -The version chain. Used to answer "what did this theorem look like -before refactor X?". Stored as a singly-linked list — chain head has -`parent_octad_key == None`. - -## ENTITY ↔ STRUCT ↔ TABLE crosswalk - -| Entity | Rust struct | Cap'n Proto | ClickHouse table | -|---|---|---|---| -| E1 Octad | `OctadPayload` | `Octad@0x80…001` | `octads` | -| E2 Semantic | `SemanticPayload` | `Semantic@0x80…002` | `octads_semantic` | -| E3 Temporal | `TemporalPayload` | `Temporal@0x80…003` | `octads_temporal` | -| E4 Provenance | `ProvenancePayload` | `Provenance@0x80…004` | `octads_provenance` | -| E5 Document | `DocumentPayload` | `Document@0x80…005` | `octads_document` | -| E6 Graph | `GraphPayload` | `Graph@0x80…006` | `octads_graph` | -| E7 Vector | `VectorPayload` | `Vector@0x80…007` | `octads_vector` | -| E8 Tensor | `TensorPayload` | `Tensor@0x80…008` | `octads_tensor` | -| E9 Spatial | `SpatialPayload` | `Spatial@0x80…009` | `octads_spatial` | -| E10 ProofAttempt | `ProofAttempt` | `ProofAttempt@0x80…00a` | `proof_attempts` | -| E11 CertificateBlob | (extract pending) | `CertificateBlob@0x80…00b` | `certificate_blobs` | -| E12 ProverBinaryIntegrity | `ProverBinaryIntegrity` | `ProverBinaryIntegrity@0x80…00c` | `prover_binary_integrity` | - -## Drift detection - -The single source of truth is this document plus its companion -`verisim_er.capnp` schema. Any code change that adds, removes, or -renames an entity / relationship MUST also update both files in the -same PR. A CI gate (TODO: `er-drift.yml`) computes: - -``` -sha256( cat docs/architecture/VERISIM-ER-SCHEMA.md - crates/echidna-wire/schemas/verisim_er.capnp ) -``` - -and fails the build if the result differs from the value stored in -`.machine_readable/er-schema.sha256`. When the schema changes -intentionally, update the SHA in the same PR. - -## Open migrations (tracked here, not in CHANGELOG) - -| Item | Status | -|---|---| -| Extract `CertificateBlob` to dedicated table (currently inlined) | tracked, 2026-Q3 | -| Add `er-drift.yml` CI gate | tracked, see `docs/decisions/2026-06-01-er-drift-gate.md` | -| Cap'n Proto schema concrete struct IDs (placeholder `@0x80…001` etc.) | tracked, fill before first wire-level consumer | -| Migrate `query.rs` to span multiple adapters (currently single-adapter) | tracked, see capstone in `src/rust/corpus/query.rs` | -| VeriSim-side: ensure all 12 entities have writers + readers (currently 10/12 — E11 + E12 deferred) | tracked at verisimdb#XX | - -## Cross-document references - -- Octad implementation: `src/rust/verisim_bridge.rs:36-471` -- VCL-UT query language: `src/rust/vcl_ut.rs:1-1083` (consumer of this schema) -- Learning data flow: `docs/LEARNING-ARCHITECTURE.adoc` (consumer of `proof_attempts`) -- Arbitration: `src/rust/verification/{portfolio,bayesian_arbiter,dempster_shafer,pareto_arbiter}.rs` (consumers of `proof_attempts`) -- Corpus adapters: `src/rust/corpus/{agda,coq,lean,idris2,isabelle,metamath,mizar,hol_light,hol4,dafny,why3,fstar,acl2_books,tptp,smtlib,proofnet,minif2f}.rs` (producers of E1–E9) diff --git a/docs/bench/2026-05-30-chapel-mrr-baseline.adoc b/docs/bench/2026-05-30-chapel-mrr-baseline.adoc new file mode 100644 index 00000000..ab89b2a8 --- /dev/null +++ b/docs/bench/2026-05-30-chapel-mrr-baseline.adoc @@ -0,0 +1,145 @@ +== Chapel speedup baseline — 2026-05-30 + +Wave-1 baseline for the three Chapel proof-search strategies introduced +in PR #146: + +* `+sequentialProofSearch+` — serial fallback. +* `+parallelProofSearch+` — best-of: `+coforall+` over all provers, +return the fastest successful result. Wall time bounded by slowest task. +* `+parallelProofSearchSpeculative+` — first-success-wins via atomic +CAS. Wall time bounded by fastest successful prover plus in-flight tail. + +=== Method + +`+src/chapel/bench_mrr.chpl+` reads each fixture from +`+tests/chapel_fixtures/+`, calls each of the three strategies with the +same goal string and the full 30-prover registry (`+timeout = 10 s+`), +and emits CSV. + +Reproduce: + +[source,bash] +---- +just bench-chapel-mrr +---- + +=== Fixtures + +[cols=",,",options="header",] +|=== +|Fixture |Language |Trivially provable in +|`+coq_trivial.v+` |Coq |Coq (`+coqc+`) +|`+lean_trivial.lean+` |Lean 4 |Lean (`+lean+`) +|`+idris2_trivial.idr+` |Idris2 |Idris2 — *see caveats* +|=== + +=== Results (median of 5 runs, seconds) + +[cols=",,,",options="header",] +|=== +|fixture |strategy |wallclock |winning prover +|coq_trivial |sequential |*0.313* |Coq +|coq_trivial |parallel_bestof |0.741 |Coq +|coq_trivial |parallel_speculative |0.640 |Coq +|lean_trivial |sequential |*0.520* |Lean +|lean_trivial |parallel_bestof |0.733 |Lean +|lean_trivial |parallel_speculative |0.636 |Lean +|idris2_trivial |sequential |1.201 |— +|idris2_trivial |parallel_bestof |0.749 |— +|idris2_trivial |parallel_speculative |*0.731* |— +|=== + +=== Interpretation + +Two regimes show clearly: + +*Trivial-goal regime (Coq, Lean fixtures):* sequential is fastest. Both +goals succeed on the first or second prover tried (Coq at registry +position 1; Lean at position 2). The `+coforall+` spawn overhead for 30 +tasks exceeds the parallelism win. Best-of pays the additional cost of +waiting for every spawned task to complete; speculative pays the cost of +the in-flight tail until the next-completing failure registers. + +*Failure regime (Idris2 fixture):* parallel strategies are *~1.6× +faster* than sequential. Sequential walks all 30 registry entries one at +a time, paying the per-spawn cost for each failure (Idris2 itself takes +~0.7 s to error out, the rest are `+which+` misses). `+coforall+` +collapses that 30-deep chain into a single round of parallel spawns. + +Wave-1 confirms: the parallel-dispatch machinery is sound, the +strategy-difference is the predicted shape, and the speculative path is +production-ready as a drop-in for problems where the successful prover +is *not* known in advance. + +=== Caveats + +The baseline is intentionally small (3 fixtures × 4-of-30 provers +locally on PATH). Three known integration gaps surface and are tracked +as follow-ups, *not* blockers for the L2.2 ship: + +[arabic] +. *Idris2 fixture fails for all strategies.* `+idris2 --check+` requires +the file’s path to live inside the configured source directory and loads +`+Prelude+` from `+IDRIS2_DATA_DIR+`. The registry entry in +`+parallel_proof_search.chpl :: buildProverRegistry+` invokes Idris2 +from the parent’s CWD with no env override, so +`+--check /tmp/echidna-chapel/goal_Idris2_.idr+` reports +`+Module Prelude not found+`. Fixing this means a per-prover prelude +hook in `+tryProver+` (cd to tmp dir, export `+IDRIS2_DATA_DIR+`). +Tracked as a Wave-2 follow-up issue. +. *Agda rejects mangled filenames.* Agda’s module-name resolution +requires the source file’s basename to be a valid Agda identifier. +`+tryProver+` writes to `+goal_Agda_.agda+`, which Agda parses as a +compound identifier where `++` is a numeric literal and rejects. +Workaround: use `+agda --safe -i goal_Agda_.agda+` with a +leading letter in the temp basename, or generate Agda content with +`+module _ where+`. Tracked as a Wave-2 follow-up issue. +. *Sub-second wall-clock has ±200 ms jitter.* The medians above are +stable across 5 runs but individual cells vary by 2-3× at cold start +(e.g. one `+parallel_speculative coq_trivial+` reading came in at 2.538 +s on a cold cache). For routine regression checking, run the bench five +times and take the median. CI should use a warm-cache pre-pass. + +A non-trivial corpus benchmark — proofs that take 10-30 s in their +native prover and where multiple provers can succeed — is the follow-up +that will show speculative dramatically beating sequential (target: ≥ 5× +on the success regime). That requires the L3 corpus hand-off and the +Wave-2 Idris2/Agda fixes above. + +=== Raw data + +5-run readings preserved at +`+docs/bench/2026-05-30-chapel-mrr-baseline.csv+`. + +=== Update 2026-05-31 — Caveats 1 & 2 resolved (#158 + #159) + +`+ProverInfo+` gained two optional spawn hooks: `+cwd+` (subprocess +working directory, shell-wrapped to be coforall-safe) and +`+filenameOverride+` (literal basename for provers that enforce +module-name = filename). Registry entries for Idris2 and Agda set both; +the bench fixture set gained `+agda_trivial.agda+`. The +`+bench-chapel-mrr+` Justfile recipe now derives `+IDRIS2_PREFIX+` from +`+which idris2+` so the parent shell doesn’t need to export it. + +Single-run readings (replace with 5-run medians in a follow-up): + +[cols=",,,",options="header",] +|=== +|fixture |strategy |wallclock |winning prover +|idris2_trivial |sequential |1.970 |Idris2 +|idris2_trivial |parallel_bestof |1.037 |Idris2 +|idris2_trivial |parallel_speculative |1.032 |Idris2 +|agda_trivial |sequential |0.101 |Agda +|agda_trivial |parallel_bestof |0.751 |Agda +|agda_trivial |parallel_speculative |0.450 |Agda +|=== + +Note the new Agda regime: `+sequential+` is fastest (0.101 s) because +Agda sits at registry position 0 — the first prover tried — and succeeds +immediately, so the parallel strategies pay coforall spawn overhead with +no benefit. The trivial-goal regime observation from the original bench +applies symmetrically here. + +Wave-3 follow-ups still open: real-corpus speedup bench (#161, 10-30 s +prover invocations) and per-prover preempted/timeout/success telemetry +(#162). diff --git a/docs/bench/2026-05-30-chapel-mrr-baseline.md b/docs/bench/2026-05-30-chapel-mrr-baseline.md deleted file mode 100644 index 34c5352a..00000000 --- a/docs/bench/2026-05-30-chapel-mrr-baseline.md +++ /dev/null @@ -1,139 +0,0 @@ - - - -# Chapel speedup baseline — 2026-05-30 - -Wave-1 baseline for the three Chapel proof-search strategies introduced -in PR #146: - -- `sequentialProofSearch` — serial fallback. -- `parallelProofSearch` — best-of: `coforall` over all provers, return the - fastest successful result. Wall time bounded by slowest task. -- `parallelProofSearchSpeculative` — first-success-wins via atomic CAS. - Wall time bounded by fastest successful prover plus in-flight tail. - -## Method - -`src/chapel/bench_mrr.chpl` reads each fixture from -`tests/chapel_fixtures/`, calls each of the three strategies with the same -goal string and the full 30-prover registry (`timeout = 10 s`), and -emits CSV. - -Reproduce: - -```bash -just bench-chapel-mrr -``` - -## Fixtures - -| Fixture | Language | Trivially provable in | -|---|---|---| -| `coq_trivial.v` | Coq | Coq (`coqc`) | -| `lean_trivial.lean`| Lean 4 | Lean (`lean`) | -| `idris2_trivial.idr`| Idris2 | Idris2 — **see caveats** | - -## Results (median of 5 runs, seconds) - -| fixture | strategy | wallclock | winning prover | -|---|---|---|---| -| coq_trivial | sequential | **0.313** | Coq | -| coq_trivial | parallel_bestof | 0.741 | Coq | -| coq_trivial | parallel_speculative| 0.640 | Coq | -| lean_trivial | sequential | **0.520** | Lean | -| lean_trivial | parallel_bestof | 0.733 | Lean | -| lean_trivial | parallel_speculative| 0.636 | Lean | -| idris2_trivial | sequential | 1.201 | — | -| idris2_trivial | parallel_bestof | 0.749 | — | -| idris2_trivial | parallel_speculative| **0.731** | — | - -## Interpretation - -Two regimes show clearly: - -**Trivial-goal regime (Coq, Lean fixtures):** sequential is fastest. Both -goals succeed on the first or second prover tried (Coq at registry -position 1; Lean at position 2). The `coforall` spawn overhead for 30 -tasks exceeds the parallelism win. Best-of pays the additional cost of -waiting for every spawned task to complete; speculative pays the cost of -the in-flight tail until the next-completing failure registers. - -**Failure regime (Idris2 fixture):** parallel strategies are **~1.6× faster** -than sequential. Sequential walks all 30 registry entries one at a time, -paying the per-spawn cost for each failure (Idris2 itself takes ~0.7 s to -error out, the rest are `which` misses). `coforall` collapses that 30-deep -chain into a single round of parallel spawns. - -Wave-1 confirms: the parallel-dispatch machinery is sound, the -strategy-difference is the predicted shape, and the speculative path is -production-ready as a drop-in for problems where the successful prover -is **not** known in advance. - -## Caveats - -The baseline is intentionally small (3 fixtures × 4-of-30 provers locally -on PATH). Three known integration gaps surface and are tracked as -follow-ups, **not** blockers for the L2.2 ship: - -1. **Idris2 fixture fails for all strategies.** `idris2 --check` requires - the file's path to live inside the configured source directory and - loads `Prelude` from `IDRIS2_DATA_DIR`. The registry entry in - `parallel_proof_search.chpl :: buildProverRegistry` invokes Idris2 - from the parent's CWD with no env override, so `--check - /tmp/echidna-chapel/goal_Idris2_.idr` reports - `Module Prelude not found`. Fixing this means a per-prover prelude - hook in `tryProver` (cd to tmp dir, export `IDRIS2_DATA_DIR`). - Tracked as a Wave-2 follow-up issue. -2. **Agda rejects mangled filenames.** Agda's module-name resolution - requires the source file's basename to be a valid Agda identifier. - `tryProver` writes to `goal_Agda_.agda`, which Agda parses as a - compound identifier where `` is a numeric literal and rejects. - Workaround: use `agda --safe -i goal_Agda_.agda` with a - leading letter in the temp basename, or generate Agda content with - `module _ where`. Tracked as a Wave-2 follow-up issue. -3. **Sub-second wall-clock has ±200 ms jitter.** The medians above are - stable across 5 runs but individual cells vary by 2-3× at cold start - (e.g. one `parallel_speculative coq_trivial` reading came in at 2.538 s - on a cold cache). For routine regression checking, run the bench - five times and take the median. CI should use a warm-cache pre-pass. - -A non-trivial corpus benchmark — proofs that take 10-30 s in their -native prover and where multiple provers can succeed — is the -follow-up that will show speculative dramatically beating sequential -(target: ≥ 5× on the success regime). That requires the L3 corpus -hand-off and the Wave-2 Idris2/Agda fixes above. - -## Raw data - -5-run readings preserved at `docs/bench/2026-05-30-chapel-mrr-baseline.csv`. - -## Update 2026-05-31 — Caveats 1 & 2 resolved (#158 + #159) - -`ProverInfo` gained two optional spawn hooks: `cwd` (subprocess -working directory, shell-wrapped to be coforall-safe) and -`filenameOverride` (literal basename for provers that enforce -module-name = filename). Registry entries for Idris2 and Agda set -both; the bench fixture set gained `agda_trivial.agda`. The -`bench-chapel-mrr` Justfile recipe now derives `IDRIS2_PREFIX` from -`which idris2` so the parent shell doesn't need to export it. - -Single-run readings (replace with 5-run medians in a follow-up): - -| fixture | strategy | wallclock | winning prover | -|---|---|---|---| -| idris2_trivial | sequential | 1.970 | Idris2 | -| idris2_trivial | parallel_bestof | 1.037 | Idris2 | -| idris2_trivial | parallel_speculative| 1.032 | Idris2 | -| agda_trivial | sequential | 0.101 | Agda | -| agda_trivial | parallel_bestof | 0.751 | Agda | -| agda_trivial | parallel_speculative| 0.450 | Agda | - -Note the new Agda regime: `sequential` is fastest (0.101 s) because -Agda sits at registry position 0 — the first prover tried — and -succeeds immediately, so the parallel strategies pay coforall spawn -overhead with no benefit. The trivial-goal regime observation from -the original bench applies symmetrically here. - -Wave-3 follow-ups still open: real-corpus speedup bench (#161, -10-30 s prover invocations) and per-prover preempted/timeout/success -telemetry (#162). diff --git a/docs/decisions/2026-04-28-corpus-and-design-search.adoc b/docs/decisions/2026-04-28-corpus-and-design-search.adoc new file mode 100644 index 00000000..41204df2 --- /dev/null +++ b/docs/decisions/2026-04-28-corpus-and-design-search.adoc @@ -0,0 +1,208 @@ +== 2026-04-28 — Corpus, design-search, swarm, and the N-dim VeriSim plan + +ADR-style record of the decisions made on 2026-04-28 while wiring +Echidna against echo-types’ Buchholz / Brouwer programme. Two threads: a +forward push on the actual proof targets (Phase 1.3 `+_≤_+` redesign, +unbudgeted `+wf-<ᵇʳᶠ_+`) and an underlying capability campaign (corpus, +simulated annealing over design space, swarm, multi-axis query DSL). + +=== Origin + +User asked to attack two open Agda proofs in `+echo-types+`: + +[arabic] +. *Phase 1.3* — monotonicity lemmas for `+Ordinal.Brouwer.Arithmetic+`, +blocked because the current `+data _≤_+` axiomatisation makes +`+osuc-mono-≤ : x ≤ y → osuc x ≤ osuc y+` non-trivial in the `+≤-lim+` +case (premise `+x ≤ f n+` doesn’t lift to `+osuc x ≤ f n+`). +. *Unbudgeted `+wf-<ᵇʳᶠ_+`* — `+RecursiveSurfaceBudget.agda+` carries a +`+BudgetedBT = ℕ × BT+` budget; goal is `+WellFounded _<ᵇʳᶠ_+` directly +without it, under `+--safe --without-K+`. + +Explicit framing from the user: _"`the key thing is us learning about +echidna and making it amazing in the course of doing it — remember, this +is about solving it, but it is about doing so with echidna not doing it +all on your own`"_. Capability-first. + +=== Decisions + +==== D1. The proof targets are first design problems, not tactic problems + +Phase 1.3 isn’t blocked on a tactic — it’s blocked on the _shape of the +axiomatisation_. The fix lives in design space: should `+_≤_+` be a +`+data+` type or a recursive function? Which constructors should it +have? This is combinatorial design search, not proof search. + +Same for unbudgeted `+wf-<ᵇʳᶠ_+`: the design knob is the rank function +`+rank : BT → Ord+`, and the choice between `+psi-rank ν α+` / +`+ω-rank ν ⊕ α+` / `+osuc (ω-rank ν) ⊕ α+` etc. determines how many +downstream lemmas are needed. + +Echidna’s existing `+learning/mcts.rs+` searches over tactic sequences +within a fixed signature. Both targets are outside that surface. + +→ Built `+learning/design_search.rs+` with simulated annealing over the +_signature itself_. Energy is symbolic (no Agda recompile per +candidate), lex-ordered: (mono-blockers, K-elim hazards, ctor count, +style preference). Generic `+DesignProblem+` trait so future redesigns +plug in the same way. + +==== D2. SA, then a swarm of SAs + +Single-chain SA confirms the design direction quickly (Recursive style +for `+_≤_+`; `+psi-rank ν (rank α)+` for the BT rank). Building a swarm +on top is the obvious next step: + +* The 007 swarm choreography: N agents run independent SA chains, +periodically broadcast best-so-far, peers may adopt strictly-better +states. Cross-pollination via in-process `+tokio::sync::mpsc+` channels +— protocol-shape compatible with the BoJ coord bus (`+Heartbeat+`, +`+Adopt+` messages), so dispersed-process swarms reuse the same wire +format. + +→ Built `+agent/swarm.rs+`. Verified on `+brouwer-leq+` with 6 agents × +800 iterations: all converge to the same `+[0, 0, 1, 0]+` energy. + +==== D3. Honest energy beats optimistic energy + +First SA implementation modelled `+data + LimBelow+` as unblocking +`+osuc-mono-≤+`. Hand-traced and discovered this is wrong — in the +`+≤-lim n q+` case where `+q : x ≤ f n+` and goal is +`+osuc x ≤ osuc (olim f)+`: + +* `+≤-suc → ≤-lim k+`: needs `+osuc x ≤ f k+`; recursive call only +yields `+osuc x ≤ osuc (f n)+`, off by one. +* `+LimBelow+`: requires `+∀ k. f k ≤ osuc (olim f)+`; produces +`+olim f ≤ osuc (olim f)+`, not `+osuc x ≤ osuc (olim f)+` — link to +`+x+` is lost. + +Only Recursive style or an explicit `+≤-cong-suc+` constructor truly +unblocks. Refined the energy in `+design_search::brouwer::mono_osuc_ok+` +accordingly. + +→ Lesson: when the SA energy is symbolic, hand-trace the predicates +against actual proof goals before trusting them. + +==== D4. Capability-first, then apply + +Built the recommendation infrastructure (corpus + SA + swarm + rank +search) before attempting the Agda translation. Reasoning: + +* The recursive `+_≤_+` redesign is a non-trivial structural-induction +proof exercise (`+≤-step+` case `+α = osuc α', β = olim f+` requires +careful Σ-witness picking). Hand-writing it without Agda REPL would burn +many compile cycles. +* The right next capability is wiring `+provers/agda.rs+` so Echidna can +compile candidate proofs as part of the design loop. +* A handoff document in +`+echo-types/docs/echidna-design-search-2026-04-28.adoc+` captures the +recommendation graph + risks + repro commands so the actual Agda work +can pick up cleanly in a later session. + +==== D5. The corpus needed N-dimensional indexing across provers + +User pointed out the original 2-coord index (by_name, by_qualified) is +nowhere near what’s needed. Reasoning followed: VeriSim’s 8-modality +octad is the right substrate; cross-prover semantic classes are how the +105 prover backends become a federation rather than 105 silos. + +Plan landed in 6 commits: + +[width="100%",cols="50%,50%",options="header",] +|=== +|Step |Capability +|1 |Reverse-dep index — Graph octad (forward + reverse) + +|2 |Coq + Lean 4 + Idris 2 adapters + `+semantic_class+` field + +|3 |8-modality octad emission as JSONL + +|4 |Tensor metrics (proof_depth, fanin/out, recursive, K-elim risk, +head_symbol) + +|5 |Vector embeddings (hashing-trick offline; GNN-ready) + +|Capstone |Multi-axis query DSL +|=== + +==== D6. Hashing-trick now, GNN later + +The Vector octad needs embeddings, but Julia ML server at port 8090 is +scaffold-only (per echidna’s CLAUDE.md: `+models/neural/+` doesn’t +exist; cosine fallback returns zeros). Building on a non-functional +backend = building on sand. + +→ Used hashing-trick (FNV-1a → 32-dim L2-normalised feature vector) as +default `+Embedder+`. Offline, deterministic, free, dimension- matched +to the GNN’s `+FEATURE_DIM+`. When the GNN server is primed, swap one +trait impl. Vector octad’s `+model+` field reflects which embedder +produced each row — replays distinguish them. + +==== D7. Bennettian / Landauer caveat + +User asked whether the design-search stack is near-Landauer, very +Bennettian, Shannon-violating. Honest answer: no. The corpus IS +provenance-preserving and content-addressed (a Bennettian flavour); the +SA annealer freely erases bits (Metropolis decisions, rejected +candidates, temperature updates). Real reversibility integration is the +next thread — `+januskey/reversible-core+`’s `+ContentStore+` is the +natural backing for the SA trace ledger. + +*Adjacency to* +`+redeem(thermo): honest Landauer/Bennett bounds for finite-domain echoes+` +(echo-types commit, branch `+agda/buchholz-shared-binder-psi-alpha+`): +that proof effort is the _real_ Landauer/Bennett work in this estate; +the corpus stack is a substrate that ought to align with it. +Cross-reference noted; full integration deferred. + +=== Recommended next moves (priority order) + +[arabic] +. *Wire SA energy in `+learning/buchholz_rank.rs::blockers+` to consume +the new query DSL.* Energy becomes data-driven over the corpus, not +hand-coded predicates. ~1-day refactor. +. *Apply Phase 1.3 redesign in Agda.* Multi-session; needs Agda REPL. +Recommendation document in echo-types is the starting point. +. *Reversibility integration.* Move SA trace into `+reversible-core+`’s +ContentStore; uncompute rejected candidates. Closes the Bennettian loop. +. *GNN embeddings.* Prime the Julia ML pipeline against echo-types +* jtv + eclexia corpora. Replaces the hashing-trick fallback. +. *Write the unbudgeted `+wf-<ᵇʳᶠ_+` Agda proof* per +`+learning::buchholz_rank+` recommendation. Three downstream blockers: +rank-mono-<ᵇ (Phase 2.2), ⊕-mono-<-right (Phase 1.3, counted twice). + +=== Commits + +11 in echidna (10 pushed today after rebase from origin): + +.... +8265f9b feat(corpus): multi-axis query DSL — N-dim plan capstone +4558e61 feat(corpus): vector-octad embeddings — Step 5 of N-dim plan +3148d14 feat(corpus): tensor-octad metrics — Step 4 of N-dim plan +8604909 feat(corpus): 8-modality octad emission — Step 3 of N-dim plan +572b9b7 feat(corpus): Coq + Lean 4 + Idris 2 adapters; cross-prover semantic classes +e599868 feat(corpus): reverse-dep index — Step 1 of N-dim VeriSim plan +ca56b96 feat(learning): rank-function search for unbudgeted wf-<ᵇʳᶠ_ +fca18d5 feat(agent): swarm dispatcher + SA energy refinement +ae68579 feat(learning): SA design-search — proof-design space, not tactic space +85c2b55 feat(corpus): project-corpus indexer + Agda adapter + ordinal/WF synonyms +.... + +1 in echo-types: + +.... +12a9fea docs(buchholz): Echidna design-search handoff for Phase 1.3 + unbudgeted wf-<ᵇʳᶠ_ +.... + +=== Test posture + +1059 lib tests pass (16 added). 36 corpus-specific tests; 3 echo-types +fixtures verified (640 / 108 / 147 / 93 entries across Agda / Coq / Lean +/ Idris). Cross-prover query end-to-end: `+well-foundedness+` joins +WellFounded (Agda/Lean/Idris) with well_founded (Coq). + +=== Open at end-of-session + +Tasks #4 and #5 (Apply Echidna to Phase 1.3 / unbudgeted wf-<ᵇʳᶠ in +Agda) remain open by design. The framework is built; the Agda +translation is the next session’s work. diff --git a/docs/decisions/2026-04-28-corpus-and-design-search.md b/docs/decisions/2026-04-28-corpus-and-design-search.md deleted file mode 100644 index a4685cba..00000000 --- a/docs/decisions/2026-04-28-corpus-and-design-search.md +++ /dev/null @@ -1,204 +0,0 @@ - - -# 2026-04-28 — Corpus, design-search, swarm, and the N-dim VeriSim plan - -ADR-style record of the decisions made on 2026-04-28 while wiring -Echidna against echo-types' Buchholz / Brouwer programme. Two -threads: a forward push on the actual proof targets (Phase 1.3 -`_≤_` redesign, unbudgeted `wf-<ᵇʳᶠ_`) and an underlying capability -campaign (corpus, simulated annealing over design space, swarm, -multi-axis query DSL). - -## Origin - -User asked to attack two open Agda proofs in `echo-types`: - -1. **Phase 1.3** — monotonicity lemmas for `Ordinal.Brouwer.Arithmetic`, - blocked because the current `data _≤_` axiomatisation makes - `osuc-mono-≤ : x ≤ y → osuc x ≤ osuc y` non-trivial in the `≤-lim` - case (premise `x ≤ f n` doesn't lift to `osuc x ≤ f n`). -2. **Unbudgeted `wf-<ᵇʳᶠ_`** — `RecursiveSurfaceBudget.agda` carries a - `BudgetedBT = ℕ × BT` budget; goal is `WellFounded _<ᵇʳᶠ_` directly - without it, under `--safe --without-K`. - -Explicit framing from the user: *"the key thing is us learning about -echidna and making it amazing in the course of doing it — remember, -this is about solving it, but it is about doing so with echidna not -doing it all on your own"*. Capability-first. - -## Decisions - -### D1. The proof targets are first design problems, not tactic problems - -Phase 1.3 isn't blocked on a tactic — it's blocked on the *shape of -the axiomatisation*. The fix lives in design space: should `_≤_` be a -`data` type or a recursive function? Which constructors should it -have? This is combinatorial design search, not proof search. - -Same for unbudgeted `wf-<ᵇʳᶠ_`: the design knob is the rank function -`rank : BT → Ord`, and the choice between `psi-rank ν α` / -`ω-rank ν ⊕ α` / `osuc (ω-rank ν) ⊕ α` etc. determines how many -downstream lemmas are needed. - -Echidna's existing `learning/mcts.rs` searches over tactic sequences -within a fixed signature. Both targets are outside that surface. - -→ Built `learning/design_search.rs` with simulated annealing over -the *signature itself*. Energy is symbolic (no Agda recompile per -candidate), lex-ordered: (mono-blockers, K-elim hazards, ctor count, -style preference). Generic `DesignProblem` trait so future redesigns -plug in the same way. - -### D2. SA, then a swarm of SAs - -Single-chain SA confirms the design direction quickly (Recursive -style for `_≤_`; `psi-rank ν (rank α)` for the BT rank). Building a -swarm on top is the obvious next step: - -* The 007 swarm choreography: N agents run independent SA chains, - periodically broadcast best-so-far, peers may adopt strictly-better - states. Cross-pollination via in-process `tokio::sync::mpsc` - channels — protocol-shape compatible with the BoJ coord bus - (`Heartbeat`, `Adopt` messages), so dispersed-process swarms reuse - the same wire format. - -→ Built `agent/swarm.rs`. Verified on `brouwer-leq` with 6 agents × -800 iterations: all converge to the same `[0, 0, 1, 0]` energy. - -### D3. Honest energy beats optimistic energy - -First SA implementation modelled `data + LimBelow` as unblocking -`osuc-mono-≤`. Hand-traced and discovered this is wrong — in the -`≤-lim n q` case where `q : x ≤ f n` and goal is `osuc x ≤ osuc (olim -f)`: - -* `≤-suc → ≤-lim k`: needs `osuc x ≤ f k`; recursive call only - yields `osuc x ≤ osuc (f n)`, off by one. -* `LimBelow`: requires `∀ k. f k ≤ osuc (olim f)`; produces - `olim f ≤ osuc (olim f)`, not `osuc x ≤ osuc (olim f)` — link to - `x` is lost. - -Only Recursive style or an explicit `≤-cong-suc` constructor truly -unblocks. Refined the energy in -`design_search::brouwer::mono_osuc_ok` accordingly. - -→ Lesson: when the SA energy is symbolic, hand-trace the -predicates against actual proof goals before trusting them. - -### D4. Capability-first, then apply - -Built the recommendation infrastructure (corpus + SA + swarm + rank -search) before attempting the Agda translation. Reasoning: - -* The recursive `_≤_` redesign is a non-trivial structural-induction - proof exercise (`≤-step` case `α = osuc α', β = olim f` requires - careful Σ-witness picking). Hand-writing it without Agda REPL - would burn many compile cycles. -* The right next capability is wiring `provers/agda.rs` so Echidna - can compile candidate proofs as part of the design loop. -* A handoff document in `echo-types/docs/echidna-design-search-2026-04-28.adoc` - captures the recommendation graph + risks + repro commands so - the actual Agda work can pick up cleanly in a later session. - -### D5. The corpus needed N-dimensional indexing across provers - -User pointed out the original 2-coord index (by_name, by_qualified) is -nowhere near what's needed. Reasoning followed: VeriSim's 8-modality -octad is the right substrate; cross-prover semantic classes are how -the 105 prover backends become a federation rather than 105 silos. - -Plan landed in 6 commits: - -| Step | Capability | -|---|---| -| 1 | Reverse-dep index — Graph octad (forward + reverse) | -| 2 | Coq + Lean 4 + Idris 2 adapters + `semantic_class` field | -| 3 | 8-modality octad emission as JSONL | -| 4 | Tensor metrics (proof_depth, fanin/out, recursive, K-elim risk, head_symbol) | -| 5 | Vector embeddings (hashing-trick offline; GNN-ready) | -| Capstone | Multi-axis query DSL | - -### D6. Hashing-trick now, GNN later - -The Vector octad needs embeddings, but Julia ML server at port 8090 -is scaffold-only (per echidna's CLAUDE.md: `models/neural/` doesn't -exist; cosine fallback returns zeros). Building on a non-functional -backend = building on sand. - -→ Used hashing-trick (FNV-1a → 32-dim L2-normalised feature vector) -as default `Embedder`. Offline, deterministic, free, dimension- -matched to the GNN's `FEATURE_DIM`. When the GNN server is primed, -swap one trait impl. Vector octad's `model` field reflects which -embedder produced each row — replays distinguish them. - -### D7. Bennettian / Landauer caveat - -User asked whether the design-search stack is near-Landauer, very -Bennettian, Shannon-violating. Honest answer: no. The corpus IS -provenance-preserving and content-addressed (a Bennettian flavour); -the SA annealer freely erases bits (Metropolis decisions, rejected -candidates, temperature updates). Real reversibility integration is -the next thread — `januskey/reversible-core`'s `ContentStore` is the -natural backing for the SA trace ledger. - -**Adjacency to** `redeem(thermo): honest Landauer/Bennett bounds for -finite-domain echoes` (echo-types commit, branch -`agda/buchholz-shared-binder-psi-alpha`): that proof effort is the -*real* Landauer/Bennett work in this estate; the corpus stack is a -substrate that ought to align with it. Cross-reference noted; full -integration deferred. - -## Recommended next moves (priority order) - -1. **Wire SA energy in `learning/buchholz_rank.rs::blockers` to - consume the new query DSL.** Energy becomes data-driven over the - corpus, not hand-coded predicates. ~1-day refactor. -2. **Apply Phase 1.3 redesign in Agda.** Multi-session; needs Agda - REPL. Recommendation document in echo-types is the starting - point. -3. **Reversibility integration.** Move SA trace into `reversible-core`'s - ContentStore; uncompute rejected candidates. Closes the - Bennettian loop. -4. **GNN embeddings.** Prime the Julia ML pipeline against echo-types - + jtv + eclexia corpora. Replaces the hashing-trick fallback. -5. **Write the unbudgeted `wf-<ᵇʳᶠ_` Agda proof** per - `learning::buchholz_rank` recommendation. Three downstream - blockers: rank-mono-<ᵇ (Phase 2.2), ⊕-mono-<-right (Phase 1.3, - counted twice). - -## Commits - -11 in echidna (10 pushed today after rebase from origin): - -``` -8265f9b feat(corpus): multi-axis query DSL — N-dim plan capstone -4558e61 feat(corpus): vector-octad embeddings — Step 5 of N-dim plan -3148d14 feat(corpus): tensor-octad metrics — Step 4 of N-dim plan -8604909 feat(corpus): 8-modality octad emission — Step 3 of N-dim plan -572b9b7 feat(corpus): Coq + Lean 4 + Idris 2 adapters; cross-prover semantic classes -e599868 feat(corpus): reverse-dep index — Step 1 of N-dim VeriSim plan -ca56b96 feat(learning): rank-function search for unbudgeted wf-<ᵇʳᶠ_ -fca18d5 feat(agent): swarm dispatcher + SA energy refinement -ae68579 feat(learning): SA design-search — proof-design space, not tactic space -85c2b55 feat(corpus): project-corpus indexer + Agda adapter + ordinal/WF synonyms -``` - -1 in echo-types: - -``` -12a9fea docs(buchholz): Echidna design-search handoff for Phase 1.3 + unbudgeted wf-<ᵇʳᶠ_ -``` - -## Test posture - -1059 lib tests pass (16 added). -36 corpus-specific tests; 3 echo-types fixtures verified (640 / 108 / -147 / 93 entries across Agda / Coq / Lean / Idris). -Cross-prover query end-to-end: `well-foundedness` joins WellFounded -(Agda/Lean/Idris) with well_founded (Coq). - -## Open at end-of-session - -Tasks #4 and #5 (Apply Echidna to Phase 1.3 / unbudgeted wf-<ᵇʳᶠ in -Agda) remain open by design. The framework is built; the Agda -translation is the next session's work. diff --git a/docs/decisions/2026-05-19-ci-baseline-triage.adoc b/docs/decisions/2026-05-19-ci-baseline-triage.adoc new file mode 100644 index 00000000..b0abb4eb --- /dev/null +++ b/docs/decisions/2026-05-19-ci-baseline-triage.adoc @@ -0,0 +1,123 @@ +== 2026-05-19 — CI baseline triage: real defects vs baseline-rot vs infra jam + +ADR-style record of the CI triage done while landing PR #73 and the two +baseline-blocker follow-ups (#86, #87). Written so future humans *and* +agents do not re-litigate these red checks. Companion machine-readable +record: +`+.machine_readable/descriptiles/STATE.a2ml § [session-2026-05-19-ci-baseline-triage]+`. + +=== TL;DR for anyone debugging echidna PR CI + +A red check on an echidna PR is one of *three* distinct things. Do not +treat them the same: + +[arabic] +. *Real, in-scope PR defect* — caused by the PR’s own diff. Fix it on +the PR. +. *Baseline rot* — fails identically on `+origin/main+`, independent of +any PR diff. *Do not block the PR on it.* Fix in a _dedicated_ PR off +`+main+`; blocked PRs clear on their next `+main+` merge. +. *#77 CI-infra jam* — runner never assigned, or job fast-fails in +~15–30 s with *no step logs*. Not a code defect. Estate-infra, tracked +in #77; an estate-wide remediation owns it. + +*Merge is gated only by these 6 required status checks* (GitHub branch +protection on `+main+`, verified 2026-05-19): + +* `+Analyze (rust)+` +* `+Cargo check + clippy + fmt+` +* `+Dependency audit+` +* `+Dogfood Gate+` +* `+Hypatia Neurosymbolic Analysis+` +* `+OpenSSF Scorecard+` + +Everything else (`+MVP Smoke+`, `+Julia Integration+`, +`+Minimum Supported Rust Version+`, `+PR (address)+`, +`+Validate A2ML/K9 manifests+`, `+governance / *+`, the `+T1–T4+` prover +matrices) is *non-gating*. A red non-required check does not stop +auto-merge. + +=== What was triaged (PR #73 = Wave-3 consolidation, MERGED `+d3db97d+`) + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Check |Class |Resolution +|`+Build & verify container image+` |*Real PR defect* |The minimal +`+.containerization/Containerfile+` + `+Containerfile.full+` copied only +`+src/rust+`+`+src/interfaces+`; the workspace `+Cargo.toml+` has +path-deps `+crates/echidna-core+` + `+crates/typed_wasm+` and +`+crates/*+` members. `+Containerfile.wave3+` fixed it; the other two +were left stale (`+Containerfile.mcp+` was already correct). Carried +`+COPY crates ./crates+` + `+COPY benches ./benches+` to both — merged +in #73. + +|`+Test Suite+`, `+Code Coverage+`, `+MVP Smoke+`, `+Julia Integration+` +|*Baseline rot* |`+rust-ci.yml+` ran with `+--all-features+` → forced on +`+flint+`/`+spark+`/`+chapel+` (system-lib features) → `+cargo test+` +link-failed `+unable to find library -lflint+` on *every* PR. → issue +#85 → *PR #86*. + +|`+governance / *+` (3 jobs, ~15 s, no logs), most pending required jobs +|*#77 infra jam* |Runner-assignment / fast-fail-no-logs. Parked on #77. + +|`+PR (address)+` (clusterfuzzlite) |Pre-existing, non-gating |Action +hardcodes `+.clusterfuzzlite/Dockerfile+`; repo ships `+Containerfile+`. +→ *PR #87* (tracked symlink). + +|`+Minimum Supported Rust Version+` |Baseline / #77-class |Fails +*identically on `+main+`* (24 s, zero step logs). Not introduced by any +PR; not required. +|=== + +=== Decision 1 — `+rust-ci.yml+` feature flags (#85 → #86) + +*Root cause is the workflow, not the code.* `+build.rs+` _correctly_ +gates every `+-l...+` link directive behind `+#[cfg(feature = "...")]+` +for `+flint+`/`+spark+`/`+chapel+`. The defect was `+rust-ci.yml+` +forcing those features on via `+--all-features+` on a runner with no +`+libflint+` / GNAT / Zig FFI lib. + +*Key distinction that shaped the fix:* only `+cargo test+` (and +`+cargo build+`) invoke the *linker*. `+cargo clippy+`, `+cargo doc+`, +`+cargo check+` type-check and lint the `+cfg+`-gated code *without +linking*, so they tolerate `+--all-features+` on a bare runner. + +Therefore: + +* `+clippy+`, `+doc+`, `+check+` → *keep `+--all-features+`* (full +lint/compile coverage of flint/spark/chapel, zero infra cost). +* the two `+cargo test+` steps → *`+--features verisim+`* (the only +pure-Rust optional feature; `+live-provers ⊇ verisim+`). + +A blanket `+--features verisim+` everywhere was *rejected* because it +would stop CI ever compiling/linting ~510 LoC of `+flint+` +(`+src/rust/coprocessor/flint.rs+`) and the root-crate `+spark+`-gated +FFI (`+src/rust/ffi/spark_axiom.rs+`, `+axiom_tracker.rs+`) — a silent +coverage hole. `+flint+`/`+spark+`/`+chapel+` _test execution_ stays +covered by their dedicated workflows (`+chapel-ci.yml+`, the SPARK +Theatre Gate, `+live-provers.yml+`). + +Validated in CI: `+Test Suite+` goes ✗ on `+main+` → *✓ 3m18s* on #86; +local `+cargo test --lib --features verisim+` = 1092 passed, 0 failed. + +=== Decision 2 — clusterfuzzlite filename (#87) + +The `+google/clusterfuzzlite+` `+build_fuzzers+` action hardcodes the +path `+.clusterfuzzlite/Dockerfile+` and exposes *no* filename input. +House style is `+Containerfile+` (Podman-not-Docker estate rule). +Resolution: a *tracked symlink* +`+.clusterfuzzlite/Dockerfile → Containerfile+` (git mode `+120000+`) — +clusterfuzzlite resolves through it, the canonical SPDX-headed file +keeps the house name, zero blast radius (nothing references +`+.clusterfuzzlite/Containerfile+` by name). This check is *non-gating*; +the fix is hygiene so the fuzz job runs. + +=== Standing guidance (do not re-litigate) + +* Before "`fixing`" a red echidna check: `+git show origin/main:+` +and check whether the same check is red on `+main+`. If yes → it is +baseline rot or #77; *do not* patch it on the feature PR. +* Auto-merge (squash) is the norm here. Arm it; do *not* admin-override +CI-gated PRs. +* `+#77+` is estate-infra. Symptoms: queued-forever jobs, ~15–30 s +fast-fail with empty `+--log-failed+`. Not collapsible from a repo PR. diff --git a/docs/decisions/2026-05-19-ci-baseline-triage.md b/docs/decisions/2026-05-19-ci-baseline-triage.md deleted file mode 100644 index 8bc8fa22..00000000 --- a/docs/decisions/2026-05-19-ci-baseline-triage.md +++ /dev/null @@ -1,100 +0,0 @@ - - -# 2026-05-19 — CI baseline triage: real defects vs baseline-rot vs infra jam - -ADR-style record of the CI triage done while landing PR #73 and the -two baseline-blocker follow-ups (#86, #87). Written so future humans -**and** agents do not re-litigate these red checks. Companion -machine-readable record: -`.machine_readable/descriptiles/STATE.a2ml § [session-2026-05-19-ci-baseline-triage]`. - -## TL;DR for anyone debugging echidna PR CI - -A red check on an echidna PR is one of **three** distinct things. Do -not treat them the same: - -1. **Real, in-scope PR defect** — caused by the PR's own diff. Fix it - on the PR. -2. **Baseline rot** — fails identically on `origin/main`, independent - of any PR diff. **Do not block the PR on it.** Fix in a *dedicated* - PR off `main`; blocked PRs clear on their next `main` merge. -3. **#77 CI-infra jam** — runner never assigned, or job fast-fails in - ~15–30 s with **no step logs**. Not a code defect. Estate-infra, - tracked in #77; an estate-wide remediation owns it. - -**Merge is gated only by these 6 required status checks** (GitHub -branch protection on `main`, verified 2026-05-19): - -- `Analyze (rust)` -- `Cargo check + clippy + fmt` -- `Dependency audit` -- `Dogfood Gate` -- `Hypatia Neurosymbolic Analysis` -- `OpenSSF Scorecard` - -Everything else (`MVP Smoke`, `Julia Integration`, `Minimum Supported -Rust Version`, `PR (address)`, `Validate A2ML/K9 manifests`, -`governance / *`, the `T1–T4` prover matrices) is **non-gating**. A -red non-required check does not stop auto-merge. - -## What was triaged (PR #73 = Wave-3 consolidation, MERGED `d3db97d`) - -| Check | Class | Resolution | -|---|---|---| -| `Build & verify container image` | **Real PR defect** | The minimal `.containerization/Containerfile` + `Containerfile.full` copied only `src/rust`+`src/interfaces`; the workspace `Cargo.toml` has path-deps `crates/echidna-core` + `crates/typed_wasm` and `crates/*` members. `Containerfile.wave3` fixed it; the other two were left stale (`Containerfile.mcp` was already correct). Carried `COPY crates ./crates` + `COPY benches ./benches` to both — merged in #73. | -| `Test Suite`, `Code Coverage`, `MVP Smoke`, `Julia Integration` | **Baseline rot** | `rust-ci.yml` ran with `--all-features` → forced on `flint`/`spark`/`chapel` (system-lib features) → `cargo test` link-failed `unable to find library -lflint` on **every** PR. → issue #85 → **PR #86**. | -| `governance / *` (3 jobs, ~15 s, no logs), most pending required jobs | **#77 infra jam** | Runner-assignment / fast-fail-no-logs. Parked on #77. | -| `PR (address)` (clusterfuzzlite) | Pre-existing, non-gating | Action hardcodes `.clusterfuzzlite/Dockerfile`; repo ships `Containerfile`. → **PR #87** (tracked symlink). | -| `Minimum Supported Rust Version` | Baseline / #77-class | Fails **identically on `main`** (24 s, zero step logs). Not introduced by any PR; not required. | - -## Decision 1 — `rust-ci.yml` feature flags (#85 → #86) - -**Root cause is the workflow, not the code.** `build.rs` *correctly* -gates every `-l...` link directive behind `#[cfg(feature = "...")]` -for `flint`/`spark`/`chapel`. The defect was `rust-ci.yml` forcing -those features on via `--all-features` on a runner with no `libflint` -/ GNAT / Zig FFI lib. - -**Key distinction that shaped the fix:** only `cargo test` (and -`cargo build`) invoke the **linker**. `cargo clippy`, `cargo doc`, -`cargo check` type-check and lint the `cfg`-gated code **without -linking**, so they tolerate `--all-features` on a bare runner. - -Therefore: - -- `clippy`, `doc`, `check` → **keep `--all-features`** (full - lint/compile coverage of flint/spark/chapel, zero infra cost). -- the two `cargo test` steps → **`--features verisim`** (the only - pure-Rust optional feature; `live-provers ⊇ verisim`). - -A blanket `--features verisim` everywhere was **rejected** because it -would stop CI ever compiling/linting ~510 LoC of `flint` -(`src/rust/coprocessor/flint.rs`) and the root-crate `spark`-gated FFI -(`src/rust/ffi/spark_axiom.rs`, `axiom_tracker.rs`) — a silent -coverage hole. `flint`/`spark`/`chapel` *test execution* stays covered -by their dedicated workflows (`chapel-ci.yml`, the SPARK Theatre Gate, -`live-provers.yml`). - -Validated in CI: `Test Suite` goes ✗ on `main` → **✓ 3m18s** on #86; -local `cargo test --lib --features verisim` = 1092 passed, 0 failed. - -## Decision 2 — clusterfuzzlite filename (#87) - -The `google/clusterfuzzlite` `build_fuzzers` action hardcodes the path -`.clusterfuzzlite/Dockerfile` and exposes **no** filename input. House -style is `Containerfile` (Podman-not-Docker estate rule). Resolution: -a **tracked symlink** `.clusterfuzzlite/Dockerfile → Containerfile` -(git mode `120000`) — clusterfuzzlite resolves through it, the -canonical SPDX-headed file keeps the house name, zero blast radius -(nothing references `.clusterfuzzlite/Containerfile` by name). This -check is **non-gating**; the fix is hygiene so the fuzz job runs. - -## Standing guidance (do not re-litigate) - -- Before "fixing" a red echidna check: `git show origin/main:` - and check whether the same check is red on `main`. If yes → it is - baseline rot or #77; **do not** patch it on the feature PR. -- Auto-merge (squash) is the norm here. Arm it; do **not** - admin-override CI-gated PRs. -- `#77` is estate-infra. Symptoms: queued-forever jobs, ~15–30 s - fast-fail with empty `--log-failed`. Not collapsible from a repo PR. diff --git a/docs/decisions/2026-05-30-chapel-l23-cancel-token.adoc b/docs/decisions/2026-05-30-chapel-l23-cancel-token.adoc new file mode 100644 index 00000000..8688706b --- /dev/null +++ b/docs/decisions/2026-05-30-chapel-l23-cancel-token.adoc @@ -0,0 +1,154 @@ +== 2026-05-30 — L2.3 cancel-token preemption for speculative search + +ADR-style addendum to +link:./2026-05-30-chapel-rehabilitation.md[2026-05-30-chapel-rehabilitation.md]. +Documents the L2.3 cancel-token plumbing that closes the +"`speculative-search winner doesn’t kill losers`" gap explicitly carried +forward from Wave 1. + +=== Status + +Accepted. Implemented in the PR that introduces this ADR. + +=== Context + +PR #146’s L2.2 `+parallelProofSearchSpeculative+` shipped with a clear +Wave-1 caveat (recorded in the function’s docstring and in the rehab +ADR): + +____ +Wave 1 scope deliberately stops short of the "`kill in-flight losers`" +step. Once a prover has been spawned, `+tryProver+` runs it to its own +per-prover timeout — coforall doesn’t know how to cancel a child task +that’s blocked on subprocess I/O. L2.3 introduces a cancel token +threaded through `+tryProver+` so the children can SIGKILL their own +subprocesses when they observe a winner; that’s a separate PR. +____ + +That separate PR is this one. The visible symptom Wave 1 left behind: +once a successful prover wins the CAS, the bench’s wall-clock for +`+parallel_speculative+` was still bounded by the slowest in-flight +loser (because each one ran to its own `+tryProver+` timeout). The +`+baseline.md+` 5-run medians show this — speculative and best-of were +within noise on the success cases, instead of speculative dominating. + +=== Decision + +Add a shared `+CancelToken+` instance to +`+parallelProofSearchSpeculative+`, thread an optional +`+borrowed CancelToken?+` reference through `+tryProver+`’s signature, +and have the winner pair its CAS with a write to the token. Each loser +polls the token at every 100 ms tick inside the existing bounded-wait +loop; on observing `+cancelled = true+` it SIGKILLs its own subprocess +and returns a preempted result. + +Why a `+class+` (not `+record+`) `+CancelToken+`: + +* The token must be *shared by reference* across all `+coforall+` tasks +so the winner’s write is visible to every loser. Chapel records have +value semantics; classes are passed by reference. +* Atomic-bool fields on a class have well-defined initial state +(`+false+`) after `+init this+` commits field initialisation, so the +init proc body is empty — no race-on-construction concern. +* The class is owned by the search function (`+new owned+`) and borrowed +by each `+tryProver+` call, so its lifetime is exactly the search’s +lifetime and no extra liveness reasoning is needed. + +Why exitCode = -5 for preempted losers: + +* The existing failure codes are `+-1+` (not available / general +failure), `+-2+` (temp file failure), `+-3+` (timeout), `+-4+` +(subprocess error). Preemption is a distinct fourth-kind of failure — +the prover did not get to run to completion, but neither did it time out +nor crash; it was actively SIGKILLed by the portfolio. Reusing `+-3+` +(timeout) would mis-categorise preemption as a slow-prover signal, +polluting any later bench that tracks timeout rates. + +=== Soundness + +The aggregation soundness proof in +`+proofs/agda/ParallelSoundness.agda+` already covers this case. Theorem +`+cancellation-safety+` states: + +[source,agda] +---- +cancellation-safety : {n : ℕ} (bs : Vec Bool n) + → IsTrue (speculative (true ∷ bs)) +cancellation-safety _ = tt +---- + +i.e. *once a head witness is true, the verdict is true regardless of the +tail bs’s contents*. In the L2.3 implementation the "`head`" is the +CAS-winner’s `+success = true+` and the tail `+bs+` is every loser’s +post-preemption result (which is now `+success = false+` with exitCode = +-5 instead of running to a possibly-true result). The theorem says: the +verdict over the whole result vector is unaffected by this difference. +The Agda module’s header docstring is updated in this PR to spell out +the L2.3 cross-reference. + +The CAS itself is the linearisation point: any prover whose poll +observes `+cancelled = true+` ran AFTER the winning CAS. The +happens-before edge from `+winnerIdx.compareAndSwap(-1, i)+` → +`+cancelToken.cancelled.write(true)+` → next-loser’s +`+cancelToken!.cancelled.read()+` is exactly the atomic-bool semantics +Chapel inherits from the C11 memory model. + +=== Expected speedup + +Wave-1 baseline (`+docs/bench/2026-05-30-chapel-mrr-baseline.md+`) +showed speculative ≈ best-of on the success cases because every loser +ran to its own per-prover timeout. After L2.3 the loser wall is bounded +by `+pollInterval + SIGKILL latency ≈ 100-150 ms+`. For the +trivial-success regime this is invisible because the winner itself +returns in 200-700 ms. For the realistic-corpus regime (10-30 s real +prover invocations) this is the difference between waiting +`+max(losers)+` and `+min(winner) + ~150 ms+`. The dramatic speedup the +bench writeup predicted is now structurally present. + +A second baseline run (`+docs/bench/+`) is *not* included in this PR — +the trivial fixtures don’t exercise the new code path enough to show a +meaningful number. A real-corpus bench run is the L2.4+ follow-up. + +=== Reproduce locally + +[source,bash] +---- +just bench-chapel-mrr +# Watch the parallel_speculative wallclock vs parallel_bestof: +# trivial fixtures show no change; a follow-up corpus bench would +# show speculative << bestof. +---- + +=== Risks / counter-arguments considered + +[arabic] +. *Premature cancellation race.* If two provers succeed at nearly the +same instant, the late one might write `+cancelled = true+` between the +early CAS and the early winner’s exit. *Resolved:* the CAS is what +selects the winner; whichever prover’s `+compareAndSwap+` returns true +wins regardless of token-write order. The late prover’s +`+compareAndSwap+` returns false (expected != -1 now), so it does NOT +write to the token. Only ONE prover writes the token, and it’s the same +prover that wins the CAS. +. *Self-cancellation.* Could a winning prover’s poll race with its own +success-detection and trigger preemption on itself? *No:* the +cancellation poll happens INSIDE the `+subproc.running+` loop, which +exits once the subprocess has terminated. A successful prover exits the +loop via the `+!subproc.running+` edge before +`+cancelToken.cancelled.write(true)+` is even called. +. *Loser starvation.* What about provers whose first `+tryProver+` poll +is delayed? *Resolved by 100 ms ceiling:* even the most-delayed prover +observes the cancel within 100 ms of its first poll. Total +preemption-observation latency is bounded by one pollInterval. + +=== Wave-3+ follow-ups + +* A real-corpus bench (10-30 s prover invocations) to demonstrate the +speculative >> bestof speedup quantitatively. +* A `+--bench-chapel-mrr+` `+--strategy=speculative+` flag that reports +the per-prover preemption-vs-timeout-vs-success breakdown, so we can +measure the wallclock improvement attributable to preemption +specifically. +* Extend `+CancelToken+` to carry a reason string (winner-name, +timeout-budget-exhausted, external-cancel, …) for future +cooperative-cancellation flows beyond the speculative-search case. diff --git a/docs/decisions/2026-05-30-chapel-l23-cancel-token.md b/docs/decisions/2026-05-30-chapel-l23-cancel-token.md deleted file mode 100644 index ecfc6e84..00000000 --- a/docs/decisions/2026-05-30-chapel-l23-cancel-token.md +++ /dev/null @@ -1,155 +0,0 @@ - - -# 2026-05-30 — L2.3 cancel-token preemption for speculative search - -ADR-style addendum to [2026-05-30-chapel-rehabilitation.md][rehab]. -Documents the L2.3 cancel-token plumbing that closes the -"speculative-search winner doesn't kill losers" gap explicitly carried -forward from Wave 1. - -[rehab]: ./2026-05-30-chapel-rehabilitation.md - -## Status - -Accepted. Implemented in the PR that introduces this ADR. - -## Context - -PR #146's L2.2 `parallelProofSearchSpeculative` shipped with a clear -Wave-1 caveat (recorded in the function's docstring and in the rehab -ADR): - -> Wave 1 scope deliberately stops short of the "kill in-flight losers" -> step. Once a prover has been spawned, `tryProver` runs it to its own -> per-prover timeout — coforall doesn't know how to cancel a child task -> that's blocked on subprocess I/O. L2.3 introduces a cancel token -> threaded through `tryProver` so the children can SIGKILL their own -> subprocesses when they observe a winner; that's a separate PR. - -That separate PR is this one. The visible symptom Wave 1 left behind: -once a successful prover wins the CAS, the bench's wall-clock for -`parallel_speculative` was still bounded by the slowest in-flight -loser (because each one ran to its own `tryProver` timeout). The -`baseline.md` 5-run medians show this — speculative and best-of were -within noise on the success cases, instead of speculative dominating. - -## Decision - -Add a shared `CancelToken` instance to `parallelProofSearchSpeculative`, -thread an optional `borrowed CancelToken?` reference through -`tryProver`'s signature, and have the winner pair its CAS with a -write to the token. Each loser polls the token at every 100 ms tick -inside the existing bounded-wait loop; on observing `cancelled = true` -it SIGKILLs its own subprocess and returns a preempted result. - -Why a `class` (not `record`) `CancelToken`: - -- The token must be **shared by reference** across all `coforall` - tasks so the winner's write is visible to every loser. Chapel - records have value semantics; classes are passed by reference. -- Atomic-bool fields on a class have well-defined initial state - (`false`) after `init this` commits field initialisation, so the - init proc body is empty — no race-on-construction concern. -- The class is owned by the search function (`new owned`) and - borrowed by each `tryProver` call, so its lifetime is exactly the - search's lifetime and no extra liveness reasoning is needed. - -Why exitCode = -5 for preempted losers: - -- The existing failure codes are `-1` (not available / general failure), - `-2` (temp file failure), `-3` (timeout), `-4` (subprocess error). - Preemption is a distinct fourth-kind of failure — the prover did - not get to run to completion, but neither did it time out nor crash; - it was actively SIGKILLed by the portfolio. Reusing `-3` (timeout) - would mis-categorise preemption as a slow-prover signal, polluting - any later bench that tracks timeout rates. - -## Soundness - -The aggregation soundness proof in `proofs/agda/ParallelSoundness.agda` -already covers this case. Theorem `cancellation-safety` states: - -```agda -cancellation-safety : {n : ℕ} (bs : Vec Bool n) - → IsTrue (speculative (true ∷ bs)) -cancellation-safety _ = tt -``` - -i.e. **once a head witness is true, the verdict is true regardless of -the tail bs's contents**. In the L2.3 implementation the "head" is the -CAS-winner's `success = true` and the tail `bs` is every loser's -post-preemption result (which is now `success = false` with -exitCode = -5 instead of running to a possibly-true result). The -theorem says: the verdict over the whole result vector is unaffected -by this difference. The Agda module's header docstring is updated in -this PR to spell out the L2.3 cross-reference. - -The CAS itself is the linearisation point: any prover whose poll -observes `cancelled = true` ran AFTER the winning CAS. The -happens-before edge from `winnerIdx.compareAndSwap(-1, i)` → -`cancelToken.cancelled.write(true)` → next-loser's -`cancelToken!.cancelled.read()` is exactly the atomic-bool semantics -Chapel inherits from the C11 memory model. - -## Expected speedup - -Wave-1 baseline (`docs/bench/2026-05-30-chapel-mrr-baseline.md`) -showed speculative ≈ best-of on the success cases because every -loser ran to its own per-prover timeout. After L2.3 the loser wall -is bounded by `pollInterval + SIGKILL latency ≈ 100-150 ms`. For the -trivial-success regime this is invisible because the winner itself -returns in 200-700 ms. For the realistic-corpus regime (10-30 s -real prover invocations) this is the difference between waiting -`max(losers)` and `min(winner) + ~150 ms`. The dramatic speedup the -bench writeup predicted is now structurally present. - -A second baseline run (`docs/bench/`) is **not** included in this PR -— the trivial fixtures don't exercise the new code path enough to -show a meaningful number. A real-corpus bench run is the L2.4+ -follow-up. - -## Reproduce locally - -```bash -just bench-chapel-mrr -# Watch the parallel_speculative wallclock vs parallel_bestof: -# trivial fixtures show no change; a follow-up corpus bench would -# show speculative << bestof. -``` - -## Risks / counter-arguments considered - -1. **Premature cancellation race.** If two provers succeed at nearly - the same instant, the late one might write `cancelled = true` - between the early CAS and the early winner's exit. **Resolved:** the - CAS is what selects the winner; whichever prover's `compareAndSwap` - returns true wins regardless of token-write order. The late - prover's `compareAndSwap` returns false (expected != -1 now), so - it does NOT write to the token. Only ONE prover writes the token, - and it's the same prover that wins the CAS. - -2. **Self-cancellation.** Could a winning prover's poll race with its - own success-detection and trigger preemption on itself? **No:** - the cancellation poll happens INSIDE the `subproc.running` loop, - which exits once the subprocess has terminated. A successful - prover exits the loop via the `!subproc.running` edge before - `cancelToken.cancelled.write(true)` is even called. - -3. **Loser starvation.** What about provers whose first `tryProver` - poll is delayed? **Resolved by 100 ms ceiling:** even the - most-delayed prover observes the cancel within 100 ms of its - first poll. Total preemption-observation latency is bounded by - one pollInterval. - -## Wave-3+ follow-ups - -- A real-corpus bench (10-30 s prover invocations) to demonstrate - the speculative >> bestof speedup quantitatively. -- A `--bench-chapel-mrr` `--strategy=speculative` flag that - reports the per-prover preemption-vs-timeout-vs-success breakdown, - so we can measure the wallclock improvement attributable to - preemption specifically. -- Extend `CancelToken` to carry a reason string (winner-name, - timeout-budget-exhausted, external-cancel, …) for future - cooperative-cancellation flows beyond the speculative-search - case. diff --git a/docs/decisions/2026-05-30-chapel-pic-rebuild.adoc b/docs/decisions/2026-05-30-chapel-pic-rebuild.adoc new file mode 100644 index 00000000..944594c8 --- /dev/null +++ b/docs/decisions/2026-05-30-chapel-pic-rebuild.adoc @@ -0,0 +1,162 @@ +== 2026-05-30 — Chapel PIC rebuild from source for `+--library --dynamic+` + +ADR-style addendum to +link:./2026-05-30-chapel-rehabilitation.md[2026-05-30-chapel-rehabilitation.md]. +Documents the procedure and constraints for replacing the apt-shipped +Chapel runtime with a position-independent variant so the metalayer can +be linked as a shared library instead of a static archive. + +=== Status + +Documented. Procedure is `+just chapel-pic-from-source+`; *not* invoked +from any CI workflow because the build is ~30 min wall and ~5 GB disk, +which would dominate the Chapel CI budget for negligible runtime gain +until L2.5 multi-locale work needs the shared-library form. + +=== Context + +The rehabilitation PR (#146) chose `+--library --static+` for +`+chapel-build+` because the apt-distributed Chapel deb only ships one +runtime variant — `+lib_pic-none+`: + +.... +/usr/lib/chapel/2.8/runtime/lib/linux64/gnu/x86_64/loc-flat/ + comm-none/tasks-qthreads/launch-smp/tmr-generic/unwind-system/ + mem-jemalloc/atomics-cstdlib/lib_pic-none/san-none/libchpllaunch.a +.... + +`+chpl --library --dynamic+` requires a `+lib_pic-pic/+` variant in the +same path tree; without it, the link of `+libchpl.a+` into a `+.so+` +fails with: + +.... +relocation R_X86_64_TPOFF32 against symbol `chpl_task_root_uniqueId' +can not be used when making a shared object; recompile with -fPIC +.... + +The same constraint applies to the conda-forge `+chapel+` package, which +also ships only the non-PIC runtime variant as of 2.8.0. + +The only way to obtain a PIC runtime is to build Chapel from the release +source with `+CHPL_LIB_PIC=pic+` set at `+make+` time. The variant ends +up at the parallel `+lib_pic-pic/+` path and is auto-discovered by +`+chpl --library --dynamic+` at link time. + +=== Decision + +Ship a documented, reproducible Justfile recipe that performs the source +rebuild on demand, but do *not* invoke it from CI and do *not* change +the canonical `+chapel-build+` recipe. Local developers and the eventual +L2.5 multi-locale workflow can opt in via +`+just chapel-pic-from-source+`. + +Rationale: + +* The PIC rebuild is a one-shot ~30 min operation per CI runner, which +cannot be amortised across PRs without a registry-pushed container image +— see follow-up below. +* The static-library form (`+--library --static+`) is correct for the +current Rust-link path; Rust binaries already embed the Chapel runtime +by linking against `+libechidna_chapel.a+`. Switching to `+.so+` linkage +gains separability of the Chapel runtime but adds packaging complexity +(now two artifacts to ship and version). +* The PIC form is only *required* for L2.5 (multi-locale Chapel dispatch +under PGAS), where the runtime needs to be loadable from multiple +Chapel-distinct executables. That work is gated on L1 Cap’n Proto, so +the PIC runtime is a precondition we can satisfy asynchronously when +L2.5 starts. + +=== Procedure + +[source,bash] +---- +just chapel-pic-from-source +---- + +Equivalent to: + +[source,bash] +---- +mkdir -p ~/.cache/echidna/chapel-pic && cd ~/.cache/echidna/chapel-pic + +# Source — 2.8.0 matches the local development install. Adjust if +# CI moves to a newer point release. +curl -fL https://github.com/chapel-lang/chapel/releases/download/2.8.0/chapel-2.8.0.tar.gz \ + -o chapel-2.8.0.tar.gz +tar xf chapel-2.8.0.tar.gz +cd chapel-2.8.0 + +# PIC runtime variant — the single env var that drives the additional +# `lib_pic-pic/` subtree under `runtime/lib/.../`. LLVM is the default +# back end on 2.8+; the apt deb also uses LLVM, so we match. +export CHPL_LIB_PIC=pic +export CHPL_LLVM=bundled # match apt deb +export CHPL_HOME=$PWD +source util/setchplenv.bash + +# Build. This step is ~25-35 min wall on a 4-core x86_64 box. +make -j$(nproc) + +# Verify the PIC variant landed. +find lib -name 'lib_pic-pic' -type d | head -1 +---- + +After this completes, `+chpl+` from +`+$CHPL_HOME/bin/linux64-x86_64/chpl+` can produce shared-library +output: + +[source,bash] +---- +$CHPL_HOME/bin/linux64-x86_64/chpl \ + --library --dynamic -I ../zig_ffi \ + -o libechidna_chapel parallel_proof_search.chpl chapel_ffi_exports.chpl +---- + +=== Tradeoffs + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Aspect |`+--library --static+` (current default) +|`+--library --dynamic+` (PIC rebuild) +|Build time, cold |~10 s |~30 min (one-time) + ~10 s + +|Build time, warm |~10 s |~10 s + +|Disk footprint |runtime in libchpl.a (~30 MB) |runtime in libchpl.so +(~30 MB) + source tree (~5 GB) + +|Rust link |static archive into executable |dynamic load at runtime + +|Multi-process sharing |each process embeds runtime |runtime shared +across processes + +|L2.5 multi-locale |does not support |required +|=== + +=== Follow-up + +A registry-pushed Containerfile that pre-builds the PIC runtime would +amortise the 30 min cost across CI runs, but requires: + +* A `+Containerfile.chapel-pic+` under `+.containerization/+`. +* A registry destination +(ghcr.io/hyperpolymath/echidna-chapel-pic:2.8.0). +* A CI job to build + push on chapel version bumps. + +Tracked as a Wave-3 follow-up issue; the current PR does *not* add the +container path because it would duplicate the in-flight L1 Cap’n Proto +schema work and risk image-tag drift if Chapel point-releases between +now and L2.5 starting. + +=== Verification + +The recipe is not executed in CI for the reasons above. Local +verification (one-time, by anyone who wants `+--dynamic+` linkage) is: + +[source,bash] +---- +just chapel-pic-from-source +# Confirm: +find ~/.cache/echidna/chapel-pic/chapel-2.8.0/lib -name 'lib_pic-pic' -type d +# Expected output: at least one path containing `lib_pic-pic/`. +---- diff --git a/docs/decisions/2026-05-30-chapel-pic-rebuild.md b/docs/decisions/2026-05-30-chapel-pic-rebuild.md deleted file mode 100644 index e0923afb..00000000 --- a/docs/decisions/2026-05-30-chapel-pic-rebuild.md +++ /dev/null @@ -1,148 +0,0 @@ - - -# 2026-05-30 — Chapel PIC rebuild from source for `--library --dynamic` - -ADR-style addendum to [2026-05-30-chapel-rehabilitation.md][rehab]. -Documents the procedure and constraints for replacing the apt-shipped -Chapel runtime with a position-independent variant so the metalayer can -be linked as a shared library instead of a static archive. - -[rehab]: ./2026-05-30-chapel-rehabilitation.md - -## Status - -Documented. Procedure is `just chapel-pic-from-source`; **not** invoked -from any CI workflow because the build is ~30 min wall and ~5 GB disk, -which would dominate the Chapel CI budget for negligible runtime gain -until L2.5 multi-locale work needs the shared-library form. - -## Context - -The rehabilitation PR (#146) chose `--library --static` for -`chapel-build` because the apt-distributed Chapel deb only ships one -runtime variant — `lib_pic-none`: - -``` -/usr/lib/chapel/2.8/runtime/lib/linux64/gnu/x86_64/loc-flat/ - comm-none/tasks-qthreads/launch-smp/tmr-generic/unwind-system/ - mem-jemalloc/atomics-cstdlib/lib_pic-none/san-none/libchpllaunch.a -``` - -`chpl --library --dynamic` requires a `lib_pic-pic/` variant in the -same path tree; without it, the link of `libchpl.a` into a `.so` fails -with: - -``` -relocation R_X86_64_TPOFF32 against symbol `chpl_task_root_uniqueId' -can not be used when making a shared object; recompile with -fPIC -``` - -The same constraint applies to the conda-forge `chapel` package, which -also ships only the non-PIC runtime variant as of 2.8.0. - -The only way to obtain a PIC runtime is to build Chapel from the -release source with `CHPL_LIB_PIC=pic` set at `make` time. The variant -ends up at the parallel `lib_pic-pic/` path and is auto-discovered by -`chpl --library --dynamic` at link time. - -## Decision - -Ship a documented, reproducible Justfile recipe that performs the -source rebuild on demand, but do **not** invoke it from CI and do **not** -change the canonical `chapel-build` recipe. Local developers and the -eventual L2.5 multi-locale workflow can opt in via `just chapel-pic-from-source`. - -Rationale: - -- The PIC rebuild is a one-shot ~30 min operation per CI runner, which - cannot be amortised across PRs without a registry-pushed container - image — see follow-up below. -- The static-library form (`--library --static`) is correct for the - current Rust-link path; Rust binaries already embed the Chapel - runtime by linking against `libechidna_chapel.a`. Switching to - `.so` linkage gains separability of the Chapel runtime but adds - packaging complexity (now two artifacts to ship and version). -- The PIC form is only **required** for L2.5 (multi-locale Chapel - dispatch under PGAS), where the runtime needs to be loadable from - multiple Chapel-distinct executables. That work is gated on L1 - Cap'n Proto, so the PIC runtime is a precondition we can satisfy - asynchronously when L2.5 starts. - -## Procedure - -```bash -just chapel-pic-from-source -``` - -Equivalent to: - -```bash -mkdir -p ~/.cache/echidna/chapel-pic && cd ~/.cache/echidna/chapel-pic - -# Source — 2.8.0 matches the local development install. Adjust if -# CI moves to a newer point release. -curl -fL https://github.com/chapel-lang/chapel/releases/download/2.8.0/chapel-2.8.0.tar.gz \ - -o chapel-2.8.0.tar.gz -tar xf chapel-2.8.0.tar.gz -cd chapel-2.8.0 - -# PIC runtime variant — the single env var that drives the additional -# `lib_pic-pic/` subtree under `runtime/lib/.../`. LLVM is the default -# back end on 2.8+; the apt deb also uses LLVM, so we match. -export CHPL_LIB_PIC=pic -export CHPL_LLVM=bundled # match apt deb -export CHPL_HOME=$PWD -source util/setchplenv.bash - -# Build. This step is ~25-35 min wall on a 4-core x86_64 box. -make -j$(nproc) - -# Verify the PIC variant landed. -find lib -name 'lib_pic-pic' -type d | head -1 -``` - -After this completes, `chpl` from `$CHPL_HOME/bin/linux64-x86_64/chpl` -can produce shared-library output: - -```bash -$CHPL_HOME/bin/linux64-x86_64/chpl \ - --library --dynamic -I ../zig_ffi \ - -o libechidna_chapel parallel_proof_search.chpl chapel_ffi_exports.chpl -``` - -## Tradeoffs - -| Aspect | `--library --static` (current default) | `--library --dynamic` (PIC rebuild) | -|---|---|---| -| Build time, cold | ~10 s | ~30 min (one-time) + ~10 s | -| Build time, warm | ~10 s | ~10 s | -| Disk footprint | runtime in libchpl.a (~30 MB) | runtime in libchpl.so (~30 MB) + source tree (~5 GB) | -| Rust link | static archive into executable | dynamic load at runtime | -| Multi-process sharing | each process embeds runtime | runtime shared across processes | -| L2.5 multi-locale | does not support | required | - -## Follow-up - -A registry-pushed Containerfile that pre-builds the PIC runtime would -amortise the 30 min cost across CI runs, but requires: - -- A `Containerfile.chapel-pic` under `.containerization/`. -- A registry destination (ghcr.io/hyperpolymath/echidna-chapel-pic:2.8.0). -- A CI job to build + push on chapel version bumps. - -Tracked as a Wave-3 follow-up issue; the current PR does **not** add -the container path because it would duplicate the in-flight L1 Cap'n -Proto schema work and risk image-tag drift if Chapel point-releases -between now and L2.5 starting. - -## Verification - -The recipe is not executed in CI for the reasons above. Local -verification (one-time, by anyone who wants `--dynamic` linkage) is: - -```bash -just chapel-pic-from-source -# Confirm: -find ~/.cache/echidna/chapel-pic/chapel-2.8.0/lib -name 'lib_pic-pic' -type d -# Expected output: at least one path containing `lib_pic-pic/`. -``` diff --git a/docs/decisions/2026-05-30-chapel-rehabilitation.adoc b/docs/decisions/2026-05-30-chapel-rehabilitation.adoc new file mode 100644 index 00000000..84b878f0 --- /dev/null +++ b/docs/decisions/2026-05-30-chapel-rehabilitation.adoc @@ -0,0 +1,170 @@ +== 2026-05-30 — Chapel metalayer rehabilitation: rewrite, not park + +ADR-style record of the decision and rollout that closed issue #133 +(Chapel CI has never been green) and re-enabled the parallel +proof-search layer as a load-bearing CI signal rather than a muted red +box. + +=== Status + +Accepted. Implemented in the PR that introduces this ADR. + +=== Context + +`+chapel-ci.yml+` (`+Compile Chapel Metalayer+` job) had *never passed* +in repository history at the point of this decision — the `+.chpl+` +sources mixed C++/Rust FFI syntax (`+extern "C" { … }+` blocks, octal +string escapes), used 1.x Chapel APIs that 2.x removed +(`+createStringWithNewBuffer+`, `+send_signal+`, +`+proc.stdout.reader+`), and had a single keyword-collision bug +(`+var proc = spawn(args)+` clashing with Chapel’s `+proc+` keyword) +that cascaded into ~12 reported syntax sites. PR #131 had marked the +affected jobs `+continue-on-error: true+` so the workflow rendered green +without the underlying defect being fixed — a temporary unblock that +became a permanent blind spot for L2. + +At the same time the wider L2 sub-waves (L2.2 speculative search, L2.3 +corpus-parallel, L2.4 mutation parallelism, L2.5 multi-locale, L2.6 +numeric hot paths, L2.7 bench) were documented in CLAUDE.md as "`not +started and hard-gated on L1 Cap’n Proto`" — the surface area was parked +behind a chain of upstream dependencies, so even fixing the syntax +wouldn’t have unlocked downstream work without an explicit choice about +which sub-wave to target. + +Two viable paths were on the table: + +[arabic] +. *Rewrite.* Replace the broken sources with real Chapel 2.x, accept +that the apt-shipped Chapel runtime is `+CHPL_LIB_PIC=none+` only +(forcing static-library distribution until a PIC runtime is available), +and ship one sub-wave (L2.2 first-success-wins speculative search) to +validate the path. +. *Park.* Delete `+src/chapel/+`, drop the `+chapel+` Cargo feature, +strike Chapel from the v2.2+ roadmap, and remove `+chapel-ci.yml+`. +Treat parallel proof search as something a future Rust-native solution +(rayon, async-portfolio) can deliver if the need re-emerges. + +=== Decision + +*Rewrite (option 1).* The Chapel metalayer is the only existing surface +in the estate that (a) makes per-process parallelism explicit at the +language level rather than burying it in async runtimes, and (b) already +terminates at the Rust↔Zig↔Chapel triple-boundary that the L1 Cap’n +Proto plan presupposes. Parking would discard ~650 LOC of staged work +and would not actually save the work in the long run — the +parallel-dispatch row in `+docs/ROADMAP.md+` is a stage requirement, not +an accelerator we can drop without re-planning. + +The specific commitments inside the rewrite decision: + +* *Syntax + API rewrite.* Replace `+extern "C" {…}+` with module-level +`+const c_int+` declarations + a `+require "chapel_ffi_exports.h"+` + +`+extern record CProofResult+` pair that lets Chapel name the C type +without needing LLVM/clang to parse the header. Rename the `+var proc+` +keyword-collision to `+var subproc+`. Move from +`+createStringWithNewBuffer+` to `+string.createCopyingBuffer+`, from +`+send_signal+` to `+sendPosixSignal+`, and from +`+proc.stdout.reader(…)+` to direct reading on `+subproc.stdout+` +(`+pipeStyle.pipe+`). +* *Static, not dynamic.* Ship `+libechidna_chapel.a+` rather than +`+libechidna_chapel.so+` because the apt-shipped 2.3.0 / 2.8.0 Chapel +only ships the `+CHPL_LIB_PIC=none+` runtime variant; the PIC runtime +needed for shared-library output is not in the package and the linker +rejects the non-PIC `+libchpl.a+` with +`+R_X86_64_TPOFF32 … can not be used when making a shared object+`. +Rebuilding Chapel from source with `+CHPL_LIB_PIC=pic+` in CI is a +Wave-2 follow-up. +* *L2.2 lands now, L2.3+ defer.* This PR adds +`+parallelProofSearchSpeculative+` (first-success-wins via atomic CAS, +no mid-flight preemption) alongside the existing best-of +`+parallelProofSearch+`. Preemption is L2.3 because it requires +threading a cancellation token through `+tryProver+` so in-flight +subprocesses can SIGKILL themselves on observing a winner; the cancel +token, in turn, is a natural place to wire the L1 Cap’n Proto message +that the worker tasks subscribe to. +* *CI flipped to strict.* `+chapel-build+` and `+zig-ffi+` drop +`+continue-on-error: true+`; the rewrite means red checks here now +indicate a genuine regression. `+rust-chapel-real+` stays allow-fail +because the Rust-side link of the full Chapel runtime is a different +scope (gated on the PIC-runtime work above and on the static-archive +integration in `+build.zig+`). + +=== Rollout + +Wave 1 (this PR, echidna only): - `+src/chapel/chapel_ffi_exports.chpl+` ++ `+parallel_proof_search.chpl+` rewritten. - `+src/chapel/smoke.chpl+` +added — the toolchain-health signal that stays useful even when the +metalayer is mid-refactor. - `+chapel-ci.yml+` updated as described +above. - `+proofs/agda/ParallelSoundness.agda+` adds three theorems +(soundness, completeness, cancellation-safety) about the +speculative-search aggregation layer, with zero +postulate/admit/believe_me (verified by `+agda --safe+`). - `+Justfile+` +recipes: `+chapel-build+`, `+chapel-smoke+`, `+chapel-test+`. + +Wave 2 (separate PR, after Wave 1 green-on-main for ≥7 days): - Rebuild +Chapel from source with `+CHPL_LIB_PIC=pic+` runtime; revert the +metalayer build to `+--dynamic+`; flip `+rust-chapel-real+` to strict. +Recipe + tradeoffs: +link:./2026-05-30-chapel-pic-rebuild.md[2026-05-30-chapel-pic-rebuild.md]. +CI flip deferred — the ~30 min source build dominates the chapel-ci +budget; a registry-pushed container image is the L2.5 prerequisite. - +Add the cancel-token thread through `+tryProver+` and switch the +Chapel-side default to the speculative search. Implementation + +soundness argument: +link:./2026-05-30-chapel-l23-cancel-token.md[2026-05-30-chapel-l23-cancel-token.md]. +- Wire the `+proven+` and `+docudactyl+` parallel-dispatch tracks off +the same scaffold; breadcrumb issues filed in those repos on the PR +landing. + +Wave 3+ (longer term): - L2.4 mutation parallelism, L2.5 multi-locale +(requires cluster runtime; out of scope until we have one), L2.6 numeric +hot paths, L2.7 bench. - Idris2 ABI proof for the cross-FFI +tactic-record (the GNN-ranked tactics consumed by the Chapel side); +gated on a producer for the serialised record format. + +Wave-3 follow-ups landed: - Per-prover `+cwd+` + `+filenameOverride+` +hooks on `+ProverInfo+` (closes #158 / #159). Resolves caveats 1 + 2 of +the Wave-1 MRR baseline — Idris2 and Agda fixtures now succeed +end-to-end through `+bench-chapel-mrr+`. Mechanism + alternatives: +link:./2026-05-31-chapel-prover-spawn-hooks.md[2026-05-31-chapel-prover-spawn-hooks.md]. + +=== Consequences + +*Positive.* + +* Chapel CI becomes a real signal. A red `+chapel-build+` job now means +a genuine regression, not a baseline-rot that future PRs paper over with +`+continue-on-error+`. +* The L2 sub-waves have a concrete entry point — speculative search is +in-tree and exercisable from Chapel-side benchmarks. +* The Agda layer formally documents the aggregation invariants, +composable with the existing `+SoundnessPreservation+` proof. + +*Negative.* + +* Static-library distribution means the Rust-side link path +(`+rust-chapel-real+`) remains allow-fail until the PIC-runtime CI image +lands. Wave-2 work is non-trivial. +* `+chapel-ci.yml+`’s install step downloads a ~150 MB Chapel deb per +run; this is unchanged from the prior state but matters more now that +the job is strict (any apt mirror flake red-checks the workflow). +Cacheability is on the Wave-2 todo list. + +*Net.* The rewrite path is strictly better than parking: it preserves +option-value on the L2 → L1 → cluster sub-roadmap and shifts the open +work from "`is Chapel even tenable here?`" to concrete, scoped +engineering tasks. + +=== Toolchain version pinning + +* `+chpl 2.3.0+` (CI) and `+chpl 2.8.0+` (local). The same source +compiles under both — the `+require+` + `+extern record+` pair is stable +across the range. +* `+zig 0.14.0+`. The `+b.addLibrary(.{ … })+` form used in +`+src/zig_ffi/build.zig+` is the modern Build API, available since +0.14.0 (the earlier comment in `+chapel-ci.yml+` claiming it was missing +in 0.13.0 was stale relative to the workflow’s own pin). +* `+agda 2.6.3+` against `+agda-stdlib+` (any 2.x compatible release). + +These pins are re-stated in `+chapel-ci.yml+` and `+Justfile+`; see also +`+.machine_readable/descriptiles/META.a2ml+` for the canonical record. diff --git a/docs/decisions/2026-05-30-chapel-rehabilitation.md b/docs/decisions/2026-05-30-chapel-rehabilitation.md deleted file mode 100644 index 356c2e8b..00000000 --- a/docs/decisions/2026-05-30-chapel-rehabilitation.md +++ /dev/null @@ -1,177 +0,0 @@ - - -# 2026-05-30 — Chapel metalayer rehabilitation: rewrite, not park - -ADR-style record of the decision and rollout that closed issue #133 -(Chapel CI has never been green) and re-enabled the parallel -proof-search layer as a load-bearing CI signal rather than a muted -red box. - -## Status - -Accepted. Implemented in the PR that introduces this ADR. - -## Context - -`chapel-ci.yml` (`Compile Chapel Metalayer` job) had **never passed** -in repository history at the point of this decision — the `.chpl` -sources mixed C++/Rust FFI syntax (`extern "C" { … }` blocks, octal -string escapes), used 1.x Chapel APIs that 2.x removed -(`createStringWithNewBuffer`, `send_signal`, `proc.stdout.reader`), -and had a single keyword-collision bug (`var proc = spawn(args)` -clashing with Chapel's `proc` keyword) that cascaded into ~12 reported -syntax sites. PR #131 had marked the affected jobs -`continue-on-error: true` so the workflow rendered green without the -underlying defect being fixed — a temporary unblock that became a -permanent blind spot for L2. - -At the same time the wider L2 sub-waves (L2.2 speculative search, -L2.3 corpus-parallel, L2.4 mutation parallelism, L2.5 multi-locale, -L2.6 numeric hot paths, L2.7 bench) were documented in CLAUDE.md as -"not started and hard-gated on L1 Cap'n Proto" — the surface area was -parked behind a chain of upstream dependencies, so even fixing the -syntax wouldn't have unlocked downstream work without an explicit -choice about which sub-wave to target. - -Two viable paths were on the table: - -1. **Rewrite.** Replace the broken sources with real Chapel 2.x, - accept that the apt-shipped Chapel runtime is `CHPL_LIB_PIC=none` - only (forcing static-library distribution until a PIC runtime is - available), and ship one sub-wave (L2.2 first-success-wins - speculative search) to validate the path. -2. **Park.** Delete `src/chapel/`, drop the `chapel` Cargo feature, - strike Chapel from the v2.2+ roadmap, and remove `chapel-ci.yml`. - Treat parallel proof search as something a future Rust-native - solution (rayon, async-portfolio) can deliver if the need - re-emerges. - -## Decision - -**Rewrite (option 1).** The Chapel metalayer is the only existing -surface in the estate that (a) makes per-process parallelism explicit -at the language level rather than burying it in async runtimes, and -(b) already terminates at the Rust↔Zig↔Chapel triple-boundary that -the L1 Cap'n Proto plan presupposes. Parking would discard ~650 LOC -of staged work and would not actually save the work in the long run — -the parallel-dispatch row in `docs/ROADMAP.md` is a stage requirement, -not an accelerator we can drop without re-planning. - -The specific commitments inside the rewrite decision: - -- **Syntax + API rewrite.** Replace `extern "C" {…}` with module-level - `const c_int` declarations + a `require "chapel_ffi_exports.h"` + - `extern record CProofResult` pair that lets Chapel name the C type - without needing LLVM/clang to parse the header. Rename the - `var proc` keyword-collision to `var subproc`. Move from - `createStringWithNewBuffer` to `string.createCopyingBuffer`, from - `send_signal` to `sendPosixSignal`, and from - `proc.stdout.reader(…)` to direct reading on `subproc.stdout` - (`pipeStyle.pipe`). -- **Static, not dynamic.** Ship `libechidna_chapel.a` rather than - `libechidna_chapel.so` because the apt-shipped 2.3.0 / 2.8.0 - Chapel only ships the `CHPL_LIB_PIC=none` runtime variant; the - PIC runtime needed for shared-library output is not in the - package and the linker rejects the non-PIC `libchpl.a` with - `R_X86_64_TPOFF32 … can not be used when making a shared object`. - Rebuilding Chapel from source with `CHPL_LIB_PIC=pic` in CI is - a Wave-2 follow-up. -- **L2.2 lands now, L2.3+ defer.** This PR adds - `parallelProofSearchSpeculative` (first-success-wins via atomic - CAS, no mid-flight preemption) alongside the existing - best-of `parallelProofSearch`. Preemption is L2.3 because it - requires threading a cancellation token through `tryProver` so - in-flight subprocesses can SIGKILL themselves on observing a - winner; the cancel token, in turn, is a natural place to wire - the L1 Cap'n Proto message that the worker tasks subscribe to. -- **CI flipped to strict.** `chapel-build` and `zig-ffi` - drop `continue-on-error: true`; the rewrite means red checks here - now indicate a genuine regression. `rust-chapel-real` stays - allow-fail because the Rust-side link of the full Chapel runtime - is a different scope (gated on the PIC-runtime work above and on - the static-archive integration in `build.zig`). - -## Rollout - -Wave 1 (this PR, echidna only): -- `src/chapel/chapel_ffi_exports.chpl` + `parallel_proof_search.chpl` - rewritten. -- `src/chapel/smoke.chpl` added — the toolchain-health signal that - stays useful even when the metalayer is mid-refactor. -- `chapel-ci.yml` updated as described above. -- `proofs/agda/ParallelSoundness.agda` adds three theorems - (soundness, completeness, cancellation-safety) about the - speculative-search aggregation layer, with zero - postulate/admit/believe_me (verified by `agda --safe`). -- `Justfile` recipes: `chapel-build`, `chapel-smoke`, `chapel-test`. - -Wave 2 (separate PR, after Wave 1 green-on-main for ≥7 days): -- Rebuild Chapel from source with `CHPL_LIB_PIC=pic` runtime; revert - the metalayer build to `--dynamic`; flip `rust-chapel-real` to - strict. Recipe + tradeoffs: - [2026-05-30-chapel-pic-rebuild.md](./2026-05-30-chapel-pic-rebuild.md). - CI flip deferred — the ~30 min source build dominates the chapel-ci - budget; a registry-pushed container image is the L2.5 prerequisite. -- Add the cancel-token thread through `tryProver` and switch the - Chapel-side default to the speculative search. Implementation + - soundness argument: - [2026-05-30-chapel-l23-cancel-token.md](./2026-05-30-chapel-l23-cancel-token.md). -- Wire the `proven` and `docudactyl` parallel-dispatch tracks - off the same scaffold; breadcrumb issues filed in those repos - on the PR landing. - -Wave 3+ (longer term): -- L2.4 mutation parallelism, L2.5 multi-locale (requires cluster - runtime; out of scope until we have one), L2.6 numeric hot - paths, L2.7 bench. -- Idris2 ABI proof for the cross-FFI tactic-record (the GNN-ranked - tactics consumed by the Chapel side); gated on a producer for - the serialised record format. - -Wave-3 follow-ups landed: -- Per-prover `cwd` + `filenameOverride` hooks on `ProverInfo` - (closes #158 / #159). Resolves caveats 1 + 2 of the Wave-1 MRR - baseline — Idris2 and Agda fixtures now succeed end-to-end - through `bench-chapel-mrr`. Mechanism + alternatives: - [2026-05-31-chapel-prover-spawn-hooks.md](./2026-05-31-chapel-prover-spawn-hooks.md). - -## Consequences - -**Positive.** - -- Chapel CI becomes a real signal. A red `chapel-build` job now - means a genuine regression, not a baseline-rot that future - PRs paper over with `continue-on-error`. -- The L2 sub-waves have a concrete entry point — speculative - search is in-tree and exercisable from Chapel-side benchmarks. -- The Agda layer formally documents the aggregation invariants, - composable with the existing `SoundnessPreservation` proof. - -**Negative.** - -- Static-library distribution means the Rust-side link path - (`rust-chapel-real`) remains allow-fail until the PIC-runtime - CI image lands. Wave-2 work is non-trivial. -- `chapel-ci.yml`'s install step downloads a ~150 MB Chapel deb - per run; this is unchanged from the prior state but matters - more now that the job is strict (any apt mirror flake red-checks - the workflow). Cacheability is on the Wave-2 todo list. - -**Net.** The rewrite path is strictly better than parking: it -preserves option-value on the L2 → L1 → cluster sub-roadmap and -shifts the open work from "is Chapel even tenable here?" to -concrete, scoped engineering tasks. - -## Toolchain version pinning - -- `chpl 2.3.0` (CI) and `chpl 2.8.0` (local). The same source compiles - under both — the `require` + `extern record` pair is stable across - the range. -- `zig 0.14.0`. The `b.addLibrary(.{ … })` form used in - `src/zig_ffi/build.zig` is the modern Build API, available since - 0.14.0 (the earlier comment in `chapel-ci.yml` claiming it was - missing in 0.13.0 was stale relative to the workflow's own pin). -- `agda 2.6.3` against `agda-stdlib` (any 2.x compatible release). - -These pins are re-stated in `chapel-ci.yml` and `Justfile`; see -also `.machine_readable/descriptiles/META.a2ml` for the canonical record. diff --git a/docs/decisions/2026-05-31-chapel-prover-spawn-hooks.adoc b/docs/decisions/2026-05-31-chapel-prover-spawn-hooks.adoc new file mode 100644 index 00000000..6500ffa8 --- /dev/null +++ b/docs/decisions/2026-05-31-chapel-prover-spawn-hooks.adoc @@ -0,0 +1,174 @@ +== 2026-05-31 — Per-prover spawn hooks: cwd + filenameOverride + +ADR-style record of the mechanism added to `+ProverInfo+` and +`+tryProver+` (`+src/chapel/parallel_proof_search.chpl+`) to handle +provers whose CLI invocation requires per-prover state at spawn time. +Closes issues #158 (Idris2 env hook) and #159 (Agda filename hook), both +surfaced by the Wave-1 MRR baseline +(`+docs/bench/2026-05-30-chapel-mrr-baseline.md+`). + +=== Status + +Accepted. Implemented in the PR that introduces this ADR. + +=== Context + +The L2.2 rehabilitation arc (#133 → PR #146) shipped the Chapel +metalayer with a single uniform `+tryProver(info, goal, …)+` contract: +every prover gets a temp file named +`+goal__.+`, spawned from the parent’s CWD +with the parent’s environment. That contract held for ~22 of the 30 +registered backends (Coq, Lean, the SMT row, ATPs, etc.) but two of the +30 — Idris2 and Agda — broke at spawn time: + +* *Idris2* (`+idris2 --check+`) resolves its prelude relative to +`+IDRIS2_PREFIX+` (or the install root) AND requires the source file to +live inside the configured source directory. The Wave-1 invocation +`+idris2 --check /tmp/echidna-chapel/goal_Idris2_0.idr+` failed with +`+Module Prelude not found+` even when the parent shell had +`+IDRIS2_PREFIX+` set, because the source file wasn’t in the cwd Idris2 +used as its source dir (the parent’s cwd, not the temp dir). +* *Agda* (`+agda --safe+`) requires the source-file basename to be a +valid Agda identifier AND the module declaration inside the file to +match the basename. `+goal_Agda_0.agda+` is rejected by the lexer +(`+in the name 0, the part 0 is not valid because it is a literal+`); +even after fixing the lexer issue, Agda then enforces module-name = +file-name and rejects mismatched module declarations. + +The Wave-1 baseline (`+docs/bench/2026-05-30-chapel-mrr-baseline.md+`) +explicitly tracked these as caveats 1 + 2, deferred as Wave-2 follow-up +issues (`+#158+`/`+#159+`). + +=== Decision + +*Two new optional fields on `+ProverInfo+`* with empty-string defaults +that preserve the prior contract for the 28 provers that don’t need +per-prover spawn state: + +[source,chapel] +---- +record ProverInfo { + var id: int; + var name: string; + // … existing fields … + var cwd: string; // "" = inherit parent CWD + var filenameOverride: string; // "" = goal__. +} +---- + +A custom `+proc init(…, cwd = "", filenameOverride = "")+` keeps all 30 +existing registry call-sites compiling unchanged (default arguments fill +the new fields). A zero-arg `+proc init()+` is also defined so +`+var provers: [0..29] ProverInfo+` continues to default-construct each +slot — without it the custom positional init would shadow Chapel’s +auto-generated zero-arg init and the array declaration would fail to +compile. + +`+tryProver+` consumes both fields: + +* *`+filenameOverride+`* swaps the generic +`+goal__.+` for a literal basename (with +extension) when set. The default form remains locale-id-suffixed so +non-overriding provers stay collision-free across locales in +multi-locale runs. +* *`+cwd+`* is implemented as a shell wrapper around the spawn: +`+sh -c "cd && exec "+`. This is the +thread-safe equivalent of `+chdir()+` — process-global `+chdir+` would +race against other parallel spawn calls inside a `+coforall+`, but a +per-subprocess `+sh -c+` keeps the directory change local. The parent’s +full environment (including `+IDRIS2_PREFIX+`, `+IDRIS2_DATA_DIR+`) is +inherited regardless, per POSIX spawn defaults. + +Registry entries updated: + +* `+provers[0]+` (Agda) sets `+cwd = "/tmp/echidna-chapel"+` and +`+filenameOverride = "Trivial.agda"+`. The fixture +`+tests/chapel_fixtures/agda_trivial.agda+` declares +`+module Trivial where+` to match. +* `+provers[4]+` (Idris2) sets `+cwd = "/tmp/echidna-chapel"+` and +`+filenameOverride = "Trivial.idr"+`. The fixture +`+tests/chapel_fixtures/idris2_trivial.idr+` already declared +`+module Trivial+`, so its content is unchanged. + +The Justfile `+bench-chapel-mrr+` recipe gained a derived +`+IDRIS2_PREFIX+` step: if the env var isn’t set and `+which idris2+` +resolves, the recipe sets it to +`+dirname(dirname(realpath(which idris2)))+`. This means a user with +idris2 on PATH no longer needs to remember to export the prefix manually +for `+just bench-chapel-mrr+` to work end-to-end. + +=== Alternatives considered + +[arabic] +. *Per-prover env-extra list (key=value pairs)* — rejected as +over-engineered. Chapel `+spawn+` inherits parent env by default; the +only env hole was Idris2’s `+IDRIS2_PREFIX+`, which the Justfile recipe +now derives and exports parent-side. No prover in the current registry +needs a per-spawn env override that isn’t already in the parent. +. *Auto-extract module name from goal content* (regex +`+^module\s+(\w+)+`) — rejected as fragile. Works for clean fixtures but +breaks on goals containing comments-before-module, pragmas, or +multi-module files. The explicit `+filenameOverride+` field keeps the +registry honest about which provers have basename constraints. +. *Per-prover spawn callback (function pointer in the record)* — +rejected for now: Chapel records with function fields are awkward to +construct in a literal-initialiser-heavy registry, and the two-field +mechanism handles every concrete need surfaced by Wave-1. Revisit if a +third spawn-time wart appears. +. *`+POSIX_spawn+`-style explicit cwd in Chapel `+spawn+`* — Chapel 2.x +`+Subprocess.spawn+` does not expose a `+cwd+` parameter at the time of +writing (verified against the apt-shipped 2.3.0 and the source-built +2.8.0). The shell-wrapper workaround sidesteps the gap with no +Chapel-version dependency. + +=== Consequences + +*Positive.* + +* `+just bench-chapel-mrr+` now shows `+idris2_trivial → true+` and +`+agda_trivial → true+` across all three strategies, satisfying the +explicit acceptance criteria for both #158 and #159. +* The hook pattern is general — future provers with similar module-name +or working-directory requirements (Lean 4 already works out-of-the-box +but a future fixture might trigger its `+Lake+` workspace check; +Isabelle has session-name resolution) can be wired by adding two field +values to their registry entry, no `+tryProver+` changes. +* The Wave-1 baseline document’s caveats 1 + 2 (formerly tracked as +Wave-2 follow-ups) are closed, leaving only caveat 3 (sub-second +wall-clock jitter, which is a measurement-method issue, not a metalayer +defect). + +*Negative.* + +* Shell-wrapping every `+cwd+`-using prover costs one `+fork+exec+` for +the `+sh+` itself per invocation. For 0.1-second prover runs this is ~5% +overhead; for the 10-30 s real-corpus benchmark target (#161), it’s +negligible. If this becomes a hot path, switching to a direct-spawn cwd +implementation (when Chapel exposes it) would remove the overhead. +* `+filenameOverride+` couples the registry entry to fixture content +(the fixture’s `+module X where+` declaration must match the override). +This is acceptable because the fixture corpus is small and +version-controlled together with the registry; a real-corpus runner +would need a different convention (or the auto-extract approach from +"`Alternatives`" above). + +*Net.* Two scoped one-line additions to `+ProverInfo+` close both +acceptance-criterion-driven Wave-3 issues with no churn to the 28 +unaffected provers; the shell-wrapper approach buys portability across +Chapel 2.x runtimes; the Justfile derivation of `+IDRIS2_PREFIX+` +removes the last user-side env-export ceremony. + +=== Toolchain version pinning + +* `+chpl 2.3.0+` (CI) and `+chpl 2.8.0+` (local). The custom +`+proc init+` syntax + `+init this+` invariant used here is stable +across both. +* `+idris2 0.8.0+` (local). `+IDRIS2_PREFIX+`-based prelude resolution +is the documented mechanism; the source-directory check is +`+idris2 --check+`-specific (a `+package+`-driven build doesn’t have the +same constraint). +* `+agda 2.6.3+`. The module-name = filename rule is permanent Agda +design (`+Issue #1062+` upstream). + +These pins are re-stated in `+chapel-ci.yml+`, `+Justfile+`, and +`+docs/decisions/2026-05-30-chapel-rehabilitation.md+`. diff --git a/docs/decisions/2026-05-31-chapel-prover-spawn-hooks.md b/docs/decisions/2026-05-31-chapel-prover-spawn-hooks.md deleted file mode 100644 index 012c5473..00000000 --- a/docs/decisions/2026-05-31-chapel-prover-spawn-hooks.md +++ /dev/null @@ -1,182 +0,0 @@ - - -# 2026-05-31 — Per-prover spawn hooks: cwd + filenameOverride - -ADR-style record of the mechanism added to `ProverInfo` and -`tryProver` (`src/chapel/parallel_proof_search.chpl`) to handle -provers whose CLI invocation requires per-prover state at spawn -time. Closes issues #158 (Idris2 env hook) and #159 (Agda -filename hook), both surfaced by the Wave-1 MRR baseline -(`docs/bench/2026-05-30-chapel-mrr-baseline.md`). - -## Status - -Accepted. Implemented in the PR that introduces this ADR. - -## Context - -The L2.2 rehabilitation arc (#133 → PR #146) shipped the Chapel -metalayer with a single uniform `tryProver(info, goal, …)` -contract: every prover gets a temp file named -`goal__.`, spawned from the parent's -CWD with the parent's environment. That contract held for ~22 of -the 30 registered backends (Coq, Lean, the SMT row, ATPs, etc.) -but two of the 30 — Idris2 and Agda — broke at spawn time: - -- **Idris2** (`idris2 --check`) resolves its prelude relative to - `IDRIS2_PREFIX` (or the install root) AND requires the source - file to live inside the configured source directory. The - Wave-1 invocation `idris2 --check /tmp/echidna-chapel/goal_Idris2_0.idr` - failed with `Module Prelude not found` even when the parent - shell had `IDRIS2_PREFIX` set, because the source file wasn't - in the cwd Idris2 used as its source dir (the parent's cwd, - not the temp dir). -- **Agda** (`agda --safe`) requires the source-file basename - to be a valid Agda identifier AND the module declaration - inside the file to match the basename. `goal_Agda_0.agda` - is rejected by the lexer (`in the name 0, the part 0 is not - valid because it is a literal`); even after fixing the - lexer issue, Agda then enforces module-name = file-name and - rejects mismatched module declarations. - -The Wave-1 baseline (`docs/bench/2026-05-30-chapel-mrr-baseline.md`) -explicitly tracked these as caveats 1 + 2, deferred as Wave-2 -follow-up issues (`#158`/`#159`). - -## Decision - -**Two new optional fields on `ProverInfo`** with empty-string -defaults that preserve the prior contract for the 28 provers -that don't need per-prover spawn state: - -```chapel -record ProverInfo { - var id: int; - var name: string; - // … existing fields … - var cwd: string; // "" = inherit parent CWD - var filenameOverride: string; // "" = goal__. -} -``` - -A custom `proc init(…, cwd = "", filenameOverride = "")` keeps -all 30 existing registry call-sites compiling unchanged -(default arguments fill the new fields). A zero-arg `proc init()` -is also defined so `var provers: [0..29] ProverInfo` continues -to default-construct each slot — without it the custom positional -init would shadow Chapel's auto-generated zero-arg init and the -array declaration would fail to compile. - -`tryProver` consumes both fields: - -- **`filenameOverride`** swaps the generic - `goal__.` for a literal basename (with - extension) when set. The default form remains locale-id-suffixed - so non-overriding provers stay collision-free across locales in - multi-locale runs. -- **`cwd`** is implemented as a shell wrapper around the spawn: - `sh -c "cd && exec "`. This is the - thread-safe equivalent of `chdir()` — process-global `chdir` - would race against other parallel spawn calls inside a - `coforall`, but a per-subprocess `sh -c` keeps the directory - change local. The parent's full environment (including - `IDRIS2_PREFIX`, `IDRIS2_DATA_DIR`) is inherited regardless, - per POSIX spawn defaults. - -Registry entries updated: - -- `provers[0]` (Agda) sets `cwd = "/tmp/echidna-chapel"` and - `filenameOverride = "Trivial.agda"`. The fixture - `tests/chapel_fixtures/agda_trivial.agda` declares - `module Trivial where` to match. -- `provers[4]` (Idris2) sets `cwd = "/tmp/echidna-chapel"` and - `filenameOverride = "Trivial.idr"`. The fixture - `tests/chapel_fixtures/idris2_trivial.idr` already declared - `module Trivial`, so its content is unchanged. - -The Justfile `bench-chapel-mrr` recipe gained a derived -`IDRIS2_PREFIX` step: if the env var isn't set and `which idris2` -resolves, the recipe sets it to `dirname(dirname(realpath(which idris2)))`. -This means a user with idris2 on PATH no longer needs to remember -to export the prefix manually for `just bench-chapel-mrr` to -work end-to-end. - -## Alternatives considered - -1. **Per-prover env-extra list (key=value pairs)** — rejected as - over-engineered. Chapel `spawn` inherits parent env by default; - the only env hole was Idris2's `IDRIS2_PREFIX`, which the - Justfile recipe now derives and exports parent-side. No prover - in the current registry needs a per-spawn env override that - isn't already in the parent. -2. **Auto-extract module name from goal content** (regex - `^module\s+(\w+)`) — rejected as fragile. Works for clean - fixtures but breaks on goals containing comments-before-module, - pragmas, or multi-module files. The explicit - `filenameOverride` field keeps the registry honest about which - provers have basename constraints. -3. **Per-prover spawn callback (function pointer in the record)** — - rejected for now: Chapel records with function fields are - awkward to construct in a literal-initialiser-heavy registry, - and the two-field mechanism handles every concrete need - surfaced by Wave-1. Revisit if a third spawn-time wart appears. -4. **`POSIX_spawn`-style explicit cwd in Chapel `spawn`** — Chapel - 2.x `Subprocess.spawn` does not expose a `cwd` parameter at - the time of writing (verified against the apt-shipped 2.3.0 and - the source-built 2.8.0). The shell-wrapper workaround sidesteps - the gap with no Chapel-version dependency. - -## Consequences - -**Positive.** - -- `just bench-chapel-mrr` now shows `idris2_trivial → true` and - `agda_trivial → true` across all three strategies, satisfying - the explicit acceptance criteria for both #158 and #159. -- The hook pattern is general — future provers with similar - module-name or working-directory requirements (Lean 4 already - works out-of-the-box but a future fixture might trigger its - `Lake` workspace check; Isabelle has session-name resolution) - can be wired by adding two field values to their registry - entry, no `tryProver` changes. -- The Wave-1 baseline document's caveats 1 + 2 (formerly tracked - as Wave-2 follow-ups) are closed, leaving only caveat 3 - (sub-second wall-clock jitter, which is a measurement-method - issue, not a metalayer defect). - -**Negative.** - -- Shell-wrapping every `cwd`-using prover costs one `fork+exec` - for the `sh` itself per invocation. For 0.1-second prover runs - this is ~5% overhead; for the 10-30 s real-corpus benchmark - target (#161), it's negligible. If this becomes a hot path, - switching to a direct-spawn cwd implementation (when Chapel - exposes it) would remove the overhead. -- `filenameOverride` couples the registry entry to fixture - content (the fixture's `module X where` declaration must match - the override). This is acceptable because the fixture corpus - is small and version-controlled together with the registry; - a real-corpus runner would need a different convention (or - the auto-extract approach from "Alternatives" above). - -**Net.** Two scoped one-line additions to `ProverInfo` close -both acceptance-criterion-driven Wave-3 issues with no churn -to the 28 unaffected provers; the shell-wrapper approach buys -portability across Chapel 2.x runtimes; the Justfile derivation -of `IDRIS2_PREFIX` removes the last user-side env-export -ceremony. - -## Toolchain version pinning - -- `chpl 2.3.0` (CI) and `chpl 2.8.0` (local). The custom - `proc init` syntax + `init this` invariant used here is - stable across both. -- `idris2 0.8.0` (local). `IDRIS2_PREFIX`-based prelude - resolution is the documented mechanism; the source-directory - check is `idris2 --check`-specific (a `package`-driven build - doesn't have the same constraint). -- `agda 2.6.3`. The module-name = filename rule is permanent - Agda design (`Issue #1062` upstream). - -These pins are re-stated in `chapel-ci.yml`, `Justfile`, and -`docs/decisions/2026-05-30-chapel-rehabilitation.md`. diff --git a/docs/decisions/2026-06-01-saturation-campaign.adoc b/docs/decisions/2026-06-01-saturation-campaign.adoc new file mode 100644 index 00000000..46202b87 --- /dev/null +++ b/docs/decisions/2026-06-01-saturation-campaign.adoc @@ -0,0 +1,178 @@ +== ADR 2026-06-01 — Prover / Corpus / Vocab / Synonyms / Arbitration Saturation Campaign + +*Status*: Accepted (campaign live on branch +`+prover-corpus-saturation+`, sibling to +`+wave3/161-162-bench-telemetry-corpus+`). *Date*: 2026-06-01. *Author*: +Jonathan D.A. Jewell (executed by Claude Opus 4.7). + +=== Context + +ECHIDNA had reached *128 ProverKind variants with 91/91 real +`+suggest_tactics+`* and *GNN-augment wiring across every backend* (see +`+docs/PROVER_COUNT.md+`). The owner directive was to push the remaining +levers — corpora, vocabulary, synonyms, arbitration, verisim wiring — to +the marginal-benefit limit while a sibling session worked on chapel +bench + telemetry (`+wave3/161-162+`). + +A scoping pass (saved in +`+docs/handover/PROVER-CORPUS-SATURATION-LANE.md+`) identified the +following ordered marginal-benefit hierarchy: + +[arabic] +. *Corpus adapters*: 4 existed (agda, coq, lean, idris2); 14+ major +public corpora (Mizar MML, Isabelle AFP, MetaMath set.mm, HOL Light, +HOL4, Dafny, Why3, F*, ACL2 books, TPTP, SMT-LIB, ProofNet, MiniF2F) had +ZERO adapter coverage. *HIGHEST marginal benefit.* +. *Synonyms*: 5 per-prover tables (lean4/coq/isabelle/idris2/agda, ~863 +lines). 11 supported provers had NO synonym table. No MSC2020 / WordNet +/ ConceptNet integration. *HIGH marginal benefit.* +. *Exchange bridges*: only OpenTheory + Dedukti; TPTP / SMT-LIB / SMTCoq +/ Lambdapi absent. *HIGH marginal benefit.* +. *Arbitration*: portfolio_solver used simple majority vote + flagging; +no Bayesian / Dempster-Shafer / Pareto arbiters. *MEDIUM-HIGH.* +. *SMT portfolio*: Tier-1 only (Z3 / CVC5 / AltErgo / Vampire / +EProver); DReal / SmtRat / OpenSmt / MathSat / Princess / iProver / Twee +not in the cross-check set. *MEDIUM.* +. *Verisim E-R*: existed only as aspirational text in the +`+ECHIDNA-VERISIM-TRIANGULATION-2026-04-17.adoc+` workflow plan; no +formal entity / relationship schema. *MEDIUM.* +. *GNN first training run*: `+models/neural/+` did not exist; Flux.jl +scaffolds never invoked on real data. *HIGHEST in absolute terms but +DEFERRED* — collides with wave3 telemetry baselines and would delete +artefacts the parallel session depended on. + +=== Decision + +Execute (1) through (6) in this branch. *Defer (7)* to a separate +post-wave3 campaign. + +For each lever, the bar is *"`add it AND verify it compiles in +isolation`"* — full integration / training is out of scope. Marginal +benefit is judged by: does the surface area for downstream consumers +(`+suggest+`, `+learning+`, `+portfolio+`, `+octad-emit+`, +`+gnn_augment_tactics+`) get materially wider? + +Termination criteria are spelled out in the handover doc; on this date +the campaign hit all of them except (5) SMT-portfolio expansion (still +in flight) and the Cap’n Proto schema for E-R (declared, not generated). + +=== Consequences + +==== Positive + +* *Corpus adapters: 4 → 17* (4.25× expansion). +** Coverage now spans every Tier-1 + Tier-2 prover that has a public +formalisation library AND the two canonical ML evaluation sets +(ProofNet, MiniF2F). +** Adapters follow a single uniform pattern (two-pass extraction, +`+bounded_read_corpus_file+`, `+AxiomUsage+` hazard surfacing) — every +new one inherits the corpus query DSL + octad emission for free. +* *Synonyms TOML rows: 863 → ~3,400* (4× expansion). +** 9 new per-prover tables (isabelle_afp, metamath, mizar, hol_light, +hol4, dafny, why3, fstar, acl2). +** 3 cross-prover taxonomic dictionaries (`+_msc2020.toml+`, +`+_wordnet_math.toml+`, `+_conceptnet_seed.toml+`) enabling cross-corpus +semantic-class resolution. +* *New arbitration trio* under `+src/rust/verification/+`: +** `+bayesian_arbiter.rs+` — calibrated per-prover likelihoods + +log-odds accumulation + Shannon-entropy reporting. +** `+dempster_shafer.rs+` — belief mass combination with conflict +detection (`+HighConflict+` at k > 0.95). +** `+pareto_arbiter.rs+` — multi-objective Pareto-frontier over +(confidence, latency, axiom_cost, certificate_size). +* *New exchange bridges* under `+src/rust/exchange/+`: +** `+tptp.rs+`, `+smtlib.rs+`, `+smtcoq.rs+`, `+lambdapi.rs+`. +** Round-trip parse/emit + bidirectional translations where the +semantics overlap (TPTP↔SMT-LIB for first-order, Dedukti↔Lambdapi for +proof rewriting). +* *Formal E-R schema* at `+docs/architecture/VERISIM-ER-SCHEMA.md+`: +** 12 entities + 7 relationships fully specified. +** Crosswalk Rust struct ↔ Cap’n Proto schema ↔ ClickHouse table. +** Drift-detection plan (SHA of schema + .capnp) tracked for CI gate. +* *Test fixtures* for every new adapter under +`+tests/corpus_fixtures//+`. + +==== Negative / debt taken on + +* The new corpus adapters are *heuristic structural indexers*, not full +parsers. They will false-positive on some pathological inputs (e.g. +`+assume+` inside a string literal). Matches the existing `+agda.rs+` / +`+coq.rs+` convention but is a known limitation. +* *No real-corpus benchmarking* in this campaign. New adapters were +smoke-tested against fixtures only. Wave3 bench numbers will reveal any +real-corpus performance issues. +* *Cap’n Proto schema for the E-R* is referenced in the doc but *not yet +generated*. Planned in a follow-up commit before the drift-gate CI +lands. +* *CertificateBlob* entity (E11) in the E-R is declared but not yet +extracted to a dedicated table — currently inlined in +`+ProofAttempt.certificate_path+`. Migration tracked in the E-R doc. +* *`+mod.rs+` registration* consumed two trivial edits per affected +module index (one to `+src/rust/corpus/mod.rs+`, one each to +`+src/rust/verification/mod.rs+` and `+src/rust/exchange/mod.rs+`). Each +is additive only; no existing line was reordered or semantically +changed. + +==== Coordination with wave3/161-162 + +The handover document at +`+docs/handover/PROVER-CORPUS-SATURATION-LANE.md+` enumerated the +hard-exclusion list (chapel sources, benches, corpus monitor +diagnostics, training_data premises files, Justfile train recipes, +models/, julia run_training, the 300+ files wave3 had unstaged). +Throughout the campaign, this branch touched *only new files* plus three +surgical mod.rs additions. *Zero overlap* with wave3 was maintained. + +=== Implementation notes + +==== Commit chain on `+prover-corpus-saturation+` + +[arabic] +. `+f73ee00+` — docs(handover): declare saturation lane +. `+46a7408+` — feat(corpus): 13 adapters + 12 synonyms + +MSC2020/WordNet/ConceptNet seeds +. `++` — feat(arbiter): bayesian + dempster-shafer + pareto +trio +. `++` — feat(exchange): tptp + smtlib + smtcoq + lambdapi +bridges +. `++` — docs(er): formal verisim E-R schema + +CORPUS-ADAPTERS index +. `++` — docs(adr): this file + +==== What this campaign did NOT do + +* Did not train the GNN (collision risk + out-of-scope). +* Did not invoke `+just provision-corpora+` to fetch real corpus content +(out-of-scope; the adapters work on whatever the consumer hands them). +* Did not expand SMT portfolio beyond the existing default set (deferred +to a follow-up; intentionally low marginal benefit at this stage). +* Did not touch any of the 19 Tier-4 placeholder backends (genuinely +upstream-blocked on Containerfile work). +* Did not modify any wave3-owned file. + +=== Alternatives considered + +* *Bundle into one mega-PR vs split per-adapter*: chose mega-PR per +agent group (corpus / synonyms / arbiter / exchange / docs) for +reviewability without losing parallel-fan-out throughput. Per-adapter +PRs would have been ~20 round-trips. +* *Fetch real upstream corpora and check them in*: rejected — would blow +the 1MB pre-commit large-file limit many times over and is better +handled by `+just provision-corpora+`. +* *Skip MSC2020 / WordNet / ConceptNet seeds*: rejected — the offline +dictionaries are load-bearing for the S5 verification gate which has no +network access. + +=== Follow-ups + +Tracked in `+docs/CORPUS-ADAPTERS.md+` "`Open backlog`" section and in +the E-R schema "`Open migrations`" section. Highest priority: produce +`+crates/echidna-wire/schemas/verisim_er.capnp+` matching the new doc. + +=== References + +* Handover: `+docs/handover/PROVER-CORPUS-SATURATION-LANE.md+` +* E-R schema: `+docs/architecture/VERISIM-ER-SCHEMA.md+` +* Corpus index: `+docs/CORPUS-ADAPTERS.md+` +* Prover count source of truth: `+docs/PROVER_COUNT.md+` +* Sibling branch: `+wave3/161-162-bench-telemetry-corpus+` diff --git a/docs/decisions/2026-06-01-saturation-campaign.md b/docs/decisions/2026-06-01-saturation-campaign.md deleted file mode 100644 index 8023effe..00000000 --- a/docs/decisions/2026-06-01-saturation-campaign.md +++ /dev/null @@ -1,176 +0,0 @@ - - -# ADR 2026-06-01 — Prover / Corpus / Vocab / Synonyms / Arbitration Saturation Campaign - -**Status**: Accepted (campaign live on branch `prover-corpus-saturation`, -sibling to `wave3/161-162-bench-telemetry-corpus`). -**Date**: 2026-06-01. -**Author**: Jonathan D.A. Jewell (executed by Claude Opus 4.7). - -## Context - -ECHIDNA had reached **128 ProverKind variants with 91/91 real -`suggest_tactics`** and **GNN-augment wiring across every backend** -(see `docs/PROVER_COUNT.md`). The owner directive was to push the -remaining levers — corpora, vocabulary, synonyms, arbitration, -verisim wiring — to the marginal-benefit limit while a sibling -session worked on chapel bench + telemetry (`wave3/161-162`). - -A scoping pass (saved in `docs/handover/PROVER-CORPUS-SATURATION-LANE.md`) -identified the following ordered marginal-benefit hierarchy: - -1. **Corpus adapters**: 4 existed (agda, coq, lean, idris2); 14+ major - public corpora (Mizar MML, Isabelle AFP, MetaMath set.mm, HOL Light, - HOL4, Dafny, Why3, F\*, ACL2 books, TPTP, SMT-LIB, ProofNet, MiniF2F) - had ZERO adapter coverage. **HIGHEST marginal benefit.** -2. **Synonyms**: 5 per-prover tables (lean4/coq/isabelle/idris2/agda, ~863 - lines). 11 supported provers had NO synonym table. No MSC2020 / WordNet - / ConceptNet integration. **HIGH marginal benefit.** -3. **Exchange bridges**: only OpenTheory + Dedukti; TPTP / SMT-LIB / SMTCoq - / Lambdapi absent. **HIGH marginal benefit.** -4. **Arbitration**: portfolio_solver used simple majority vote + flagging; - no Bayesian / Dempster-Shafer / Pareto arbiters. **MEDIUM-HIGH.** -5. **SMT portfolio**: Tier-1 only (Z3 / CVC5 / AltErgo / Vampire / EProver); - DReal / SmtRat / OpenSmt / MathSat / Princess / iProver / Twee not - in the cross-check set. **MEDIUM.** -6. **Verisim E-R**: existed only as aspirational text in the - `ECHIDNA-VERISIM-TRIANGULATION-2026-04-17.adoc` workflow plan; no - formal entity / relationship schema. **MEDIUM.** -7. **GNN first training run**: `models/neural/` did not exist; Flux.jl - scaffolds never invoked on real data. **HIGHEST in absolute terms - but DEFERRED** — collides with wave3 telemetry baselines and would - delete artefacts the parallel session depended on. - -## Decision - -Execute (1) through (6) in this branch. **Defer (7)** to a separate -post-wave3 campaign. - -For each lever, the bar is **"add it AND verify it compiles in -isolation"** — full integration / training is out of scope. Marginal -benefit is judged by: does the surface area for downstream consumers -(`suggest`, `learning`, `portfolio`, `octad-emit`, `gnn_augment_tactics`) -get materially wider? - -Termination criteria are spelled out in the handover doc; on this date -the campaign hit all of them except (5) SMT-portfolio expansion (still -in flight) and the Cap'n Proto schema for E-R (declared, not generated). - -## Consequences - -### Positive - -- **Corpus adapters: 4 → 17** (4.25× expansion). - - Coverage now spans every Tier-1 + Tier-2 prover that has a public - formalisation library AND the two canonical ML evaluation sets - (ProofNet, MiniF2F). - - Adapters follow a single uniform pattern (two-pass extraction, - `bounded_read_corpus_file`, `AxiomUsage` hazard surfacing) — every - new one inherits the corpus query DSL + octad emission for free. -- **Synonyms TOML rows: 863 → ~3,400** (4× expansion). - - 9 new per-prover tables (isabelle_afp, metamath, mizar, hol_light, - hol4, dafny, why3, fstar, acl2). - - 3 cross-prover taxonomic dictionaries - (`_msc2020.toml`, `_wordnet_math.toml`, `_conceptnet_seed.toml`) - enabling cross-corpus semantic-class resolution. -- **New arbitration trio** under `src/rust/verification/`: - - `bayesian_arbiter.rs` — calibrated per-prover likelihoods + log-odds - accumulation + Shannon-entropy reporting. - - `dempster_shafer.rs` — belief mass combination with conflict - detection (`HighConflict` at k > 0.95). - - `pareto_arbiter.rs` — multi-objective Pareto-frontier over - (confidence, latency, axiom_cost, certificate_size). -- **New exchange bridges** under `src/rust/exchange/`: - - `tptp.rs`, `smtlib.rs`, `smtcoq.rs`, `lambdapi.rs`. - - Round-trip parse/emit + bidirectional translations where the - semantics overlap (TPTP↔SMT-LIB for first-order, Dedukti↔Lambdapi - for proof rewriting). -- **Formal E-R schema** at `docs/architecture/VERISIM-ER-SCHEMA.md`: - - 12 entities + 7 relationships fully specified. - - Crosswalk Rust struct ↔ Cap'n Proto schema ↔ ClickHouse table. - - Drift-detection plan (SHA of schema + .capnp) tracked for CI gate. -- **Test fixtures** for every new adapter under - `tests/corpus_fixtures//`. - -### Negative / debt taken on - -- The new corpus adapters are **heuristic structural indexers**, not full - parsers. They will false-positive on some pathological inputs (e.g. - `assume` inside a string literal). Matches the existing - `agda.rs` / `coq.rs` convention but is a known limitation. -- **No real-corpus benchmarking** in this campaign. New adapters were - smoke-tested against fixtures only. Wave3 bench numbers will reveal - any real-corpus performance issues. -- **Cap'n Proto schema for the E-R** is referenced in the doc but - **not yet generated**. Planned in a follow-up commit before the - drift-gate CI lands. -- **CertificateBlob** entity (E11) in the E-R is declared but not yet - extracted to a dedicated table — currently inlined in - `ProofAttempt.certificate_path`. Migration tracked in the E-R doc. -- **`mod.rs` registration** consumed two trivial edits per affected - module index (one to `src/rust/corpus/mod.rs`, one each to - `src/rust/verification/mod.rs` and `src/rust/exchange/mod.rs`). Each - is additive only; no existing line was reordered or semantically - changed. - -### Coordination with wave3/161-162 - -The handover document at `docs/handover/PROVER-CORPUS-SATURATION-LANE.md` -enumerated the hard-exclusion list (chapel sources, benches, corpus -monitor diagnostics, training_data premises files, Justfile train recipes, -models/, julia run_training, the 300+ files wave3 had unstaged). -Throughout the campaign, this branch touched **only new files** plus -three surgical mod.rs additions. **Zero overlap** with wave3 was -maintained. - -## Implementation notes - -### Commit chain on `prover-corpus-saturation` - -1. `f73ee00` — docs(handover): declare saturation lane -2. `46a7408` — feat(corpus): 13 adapters + 12 synonyms + MSC2020/WordNet/ConceptNet seeds -3. `` — feat(arbiter): bayesian + dempster-shafer + pareto trio -4. `` — feat(exchange): tptp + smtlib + smtcoq + lambdapi bridges -5. `` — docs(er): formal verisim E-R schema + CORPUS-ADAPTERS index -6. `` — docs(adr): this file - -### What this campaign did NOT do - -- Did not train the GNN (collision risk + out-of-scope). -- Did not invoke `just provision-corpora` to fetch real corpus content - (out-of-scope; the adapters work on whatever the consumer hands them). -- Did not expand SMT portfolio beyond the existing default set (deferred - to a follow-up; intentionally low marginal benefit at this stage). -- Did not touch any of the 19 Tier-4 placeholder backends (genuinely - upstream-blocked on Containerfile work). -- Did not modify any wave3-owned file. - -## Alternatives considered - -- **Bundle into one mega-PR vs split per-adapter**: chose mega-PR per - agent group (corpus / synonyms / arbiter / exchange / docs) for - reviewability without losing parallel-fan-out throughput. Per-adapter - PRs would have been ~20 round-trips. -- **Fetch real upstream corpora and check them in**: rejected — would - blow the 1MB pre-commit large-file limit many times over and is - better handled by `just provision-corpora`. -- **Skip MSC2020 / WordNet / ConceptNet seeds**: rejected — the offline - dictionaries are load-bearing for the S5 verification gate which has - no network access. - -## Follow-ups - -Tracked in `docs/CORPUS-ADAPTERS.md` "Open backlog" section and in the -E-R schema "Open migrations" section. Highest priority: produce -`crates/echidna-wire/schemas/verisim_er.capnp` matching the new doc. - -## References - -- Handover: `docs/handover/PROVER-CORPUS-SATURATION-LANE.md` -- E-R schema: `docs/architecture/VERISIM-ER-SCHEMA.md` -- Corpus index: `docs/CORPUS-ADAPTERS.md` -- Prover count source of truth: `docs/PROVER_COUNT.md` -- Sibling branch: `wave3/161-162-bench-telemetry-corpus` diff --git a/docs/deployment/DEPLOYMENT_GUIDE.adoc b/docs/deployment/DEPLOYMENT_GUIDE.adoc new file mode 100644 index 00000000..7c6154b6 --- /dev/null +++ b/docs/deployment/DEPLOYMENT_GUIDE.adoc @@ -0,0 +1,33 @@ +== ECHIDNA Deployment Guide — superseded + +*Status: superseded 2026-07-29. Do not follow this document.* + +The previous contents described a v0.1.0 deployment dated 2025-11-22 +whose next step was "`deploy to GitLab`", alongside a +`+zotero-voyant-export+` migration unrelated to how ECHIDNA is deployed. +It also quoted a fixed prover count, which the repository’s +canonical-reference policy forbids in prose. Following it would send an +operator somewhere the project no longer goes. + +Current documentation: + +[width="100%",cols="50%,50%",options="header",] +|=== +|You want to |Read +|Understand where everything runs +|link:../HOSTING.md[`+docs/HOSTING.md+`] + +|Deploy the API to a server +|link:../../deploy/hetzner/README.adoc[`+deploy/hetzner/README.adoc+`] + +|Call the deployed API +|link:../../site/docs/api/core.md[`+site/docs/api/core.md+`] + +|Machine-readable topology +|link:../../.machine_readable/deployment.a2ml[`+.machine_readable/deployment.a2ml+`] + +|Canonical prover counts +|link:../PROVER_COUNT.md[`+docs/PROVER_COUNT.md+`] +|=== + +This stub is kept rather than deleted so existing links do not dead-end. diff --git a/docs/deployment/DEPLOYMENT_GUIDE.md b/docs/deployment/DEPLOYMENT_GUIDE.md deleted file mode 100644 index c8580019..00000000 --- a/docs/deployment/DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,26 +0,0 @@ - - -# ECHIDNA Deployment Guide — superseded - -**Status: superseded 2026-07-29. Do not follow this document.** - -The previous contents described a v0.1.0 deployment dated 2025-11-22 whose -next step was "deploy to GitLab", alongside a `zotero-voyant-export` migration -unrelated to how ECHIDNA is deployed. It also quoted a fixed prover count, -which the repository's canonical-reference policy forbids in prose. Following -it would send an operator somewhere the project no longer goes. - -Current documentation: - -| You want to | Read | -|---|---| -| Understand where everything runs | [`docs/HOSTING.md`](../HOSTING.md) | -| Deploy the API to a server | [`deploy/hetzner/README.adoc`](../../deploy/hetzner/README.adoc) | -| Call the deployed API | [`site/docs/api/core.md`](../../site/docs/api/core.md) | -| Machine-readable topology | [`.machine_readable/deployment.a2ml`](../../.machine_readable/deployment.a2ml) | -| Canonical prover counts | [`docs/PROVER_COUNT.md`](../PROVER_COUNT.md) | - -This stub is kept rather than deleted so existing links do not dead-end. diff --git a/docs/design/ADVANCED_TYPING_GAP_ANALYSIS.adoc b/docs/design/ADVANCED_TYPING_GAP_ANALYSIS.adoc new file mode 100644 index 00000000..d8b7da5b --- /dev/null +++ b/docs/design/ADVANCED_TYPING_GAP_ANALYSIS.adoc @@ -0,0 +1,423 @@ +== Advanced Typing Capabilities: Gap Analysis and Expansion Strategy + +=== Current State of Type Support in ECHIDNA + +==== Supported Type Systems (via Backend Provers) + +ECHIDNA currently supports these type systems *through its backend +provers*: + +[cols=",,",options="header",] +|=== +|Type System Category |Supported via Backend |Native Support +|*Dependent Types* |✅ Agda, Coq, Lean, Idris2 |❌ No +|*Simple Types* |✅ Isabelle/HOL, HOL4, HOL Light |❌ No +|*Inductive Types* |✅ Agda, Coq, Lean, Idris2 |❌ No +|*Coinductive Types* |✅ Agda, Coq |❌ No +|*Linear Types* |✅ Idris2 |❌ No +|*Effect Types* |✅ Idris2, F* |❌ No +|*Refinement Types* |✅ F* |❌ No +|*Universe Polymorphism* |✅ Agda, Coq, Lean |❌ No +|*Type Classes* |✅ Agda, Coq, Idris2, Isabelle |❌ No +|*Substructural Types* |✅ (via backend provers) |❌ No +|*Quantitative Types* |✅ Idris2 |❌ No +|=== + +==== Missing Advanced Type Systems + +Based on our analysis, ECHIDNA is *missing native support* for these +advanced type systems: + +=== 1. Choreographic Types + +*Status*: ❌ Not supported (neither native nor via backend) + +*What’s Missing*: - No prover backend with native choreographic type +support - No choreographic type system detection - No choreographic +protocol verification - No endpoint projection analysis - No multiparty +session type compatibility + +*Potential Backend Candidates*: - TypeLL (choreographic type system +research) - Katagoria (choreographic verification) - Tropical resource +typing extensions + +*Action Plan*: 1. Add TypeLL backend with choreographic type support 2. +Implement choreographic type detection in type system classifier 3. Add +choreographic protocol verification capabilities 4. Develop endpoint +projection analysis 5. Create multiparty session type compatibility +checking + +=== 2. Echo Types + +*Status*: ❌ Not supported + +*What’s Missing*: - No echo type system detection - No echo type +checking infrastructure - No feedback typing analysis - No echo type +safety verification - No echo type preservation proofs + +*Potential Backend Candidates*: - TypeLL (echo type research) - +Katagoria (echo type extensions) + +*Action Plan*: 1. Research echo type theory integration 2. Add echo type +detection to type system classifier 3. Implement echo type safety +monitoring 4. Develop echo type preservation verification 5. Add echo +type compatibility checking + +=== 3. Tropical Types (Resource-Aware) + +*Status*: ❌ Not supported + +*What’s Missing*: - No tropical semiring type system - No resource +budget typing - No latency/throughput type analysis - No tropical Kleene +star operations - No resource consumption verification + +*Potential Backend Candidates*: - Katagoria (tropical resource typing) - +TypeLL (tropical extensions) + +*Action Plan*: 1. Add Katagoria backend with tropical typing 2. +Implement tropical type system detection 3. Develop resource budget +analysis 4. Add latency/throughput type checking 5. Create tropical type +preservation verification + +=== 4. Epistemic Types + +*Status*: ❌ Not supported + +*What’s Missing*: - No epistemic modal type system - No knowledge/belief +type operators - No common knowledge analysis - No epistemic logic +integration - No secrecy/privacy type verification + +*Potential Backend Candidates*: - TypeLL (epistemic type research) - +Security-focused provers (Tamarin, ProVerif extensions) + +*Action Plan*: 1. Research epistemic type theory integration 2. Add +epistemic type detection 3. Implement knowledge/belief type operators 4. +Develop common knowledge analysis 5. Add secrecy/privacy type +verification + +=== 5. Advanced Substructural Types + +*Status*: ✅ Partial (via Idris2 linear types) + +*What’s Missing*: - No comprehensive substructural type system - No +affine type system (single-use types) - No relevant type system +(resource-relevant types) - No bunched type system support - No +fine-grained resource tracking + +*Potential Backend Candidates*: - TypeLL (substructural type research) - +Katagoria (resource typing) + +*Action Plan*: 1. Add TypeLL backend with substructural types 2. +Implement affine type detection 3. Develop relevant type system support +4. Add bunched logic type checking 5. Create fine-grained resource +tracking + +=== 6. Dyadic Types + +*Status*: ❌ Not supported + +*What’s Missing*: - No dyadic type system (two-party protocols) - No +dyadic session type verification - No dual type checking - No protocol +compatibility analysis - No dyadic type preservation + +*Potential Backend Candidates*: - TypeLL (dyadic type research) - +Session type provers + +*Action Plan*: 1. Research dyadic type theory 2. Add dyadic type system +detection 3. Implement dyadic session type verification 4. Develop dual +type checking 5. Create protocol compatibility analysis + +=== 7. Advanced Effect Systems + +*Status*: ✅ Partial (via Idris2, F*) + +*What’s Missing*: - No comprehensive effect system classification - No +algebraic effect type checking - No effect polymorphism analysis - No +effect subtyping verification - No effect handler type safety + +*Potential Backend Candidates*: - Idris2 (enhanced effect system) - F* +(effect refinement) - TypeLL (effect system research) + +*Action Plan*: 1. Enhance effect system detection 2. Implement algebraic +effect analysis 3. Add effect polymorphism support 4. Develop effect +subtyping verification 5. Create effect handler type safety checking + +=== 8. Gradual Typing + +*Status*: ❌ Not supported + +*What’s Missing*: - No gradual type system support - No dynamic/static +type mixing - No gradual type checking - No cast insertion analysis - No +gradual type safety verification + +*Potential Backend Candidates*: - TypeScript (gradual typing research) - +Reticulated Python (gradual typing) + +*Action Plan*: 1. Research gradual typing integration 2. Add gradual +type system detection 3. Implement gradual type checking 4. Develop cast +insertion analysis 5. Create gradual type safety verification + +=== 9. Session Types (Advanced) + +*Status*: ✅ Partial (basic session types) + +*What’s Missing*: - No advanced session type system - No multiparty +session types (beyond dyadic) - No session type polymorphism - No +session type subtyping - No session type refinement + +*Potential Backend Candidates*: - TypeLL (session type research) - +Katagoria (session type extensions) + +*Action Plan*: 1. Add TypeLL backend with advanced session types 2. +Implement multiparty session type detection 3. Develop session type +polymorphism 4. Add session type subtyping 5. Create session type +refinement + +=== 10. Linear Logic Types + +*Status*: ❌ Not supported (beyond Idris2 linear types) + +*What’s Missing*: - No full linear logic type system - No +linear/affine/relevant/unrestricted classification - No linear logic +proof term analysis - No linear resource semantics - No linear type +preservation verification + +*Potential Backend Candidates*: - TypeLL (linear logic research) - +Linear logic provers + +*Action Plan*: 1. Add linear logic prover backend 2. Implement linear +logic type detection 3. Develop linear resource semantics 4. Add linear +type preservation verification 5. Create linear logic proof term +analysis + +=== Comprehensive Gap Analysis + +==== Type System Support Matrix + +[cols=",,,,",options="header",] +|=== +|Type System |Native |Via Backend |Gap Severity |Priority +|Dependent Types |❌ |✅ Agda/Coq/Lean/Idris2 |Low |Medium +|Linear Types |❌ |✅ Idris2 |Medium |High +|Effect Types |❌ |✅ Idris2/F* |Medium |High +|Refinement Types |❌ |✅ F* |Medium |High +|Choreographic Types |❌ |❌ None |Critical |Very High +|Echo Types |❌ |❌ None |Critical |Very High +|Tropical Types |❌ |❌ None |Critical |Very High +|Epistemic Types |❌ |❌ None |Critical |Very High +|Affine Types |❌ |❌ None |High |High +|Relevant Types |❌ |❌ None |High |High +|Dyadic Types |❌ |❌ None |High |High +|Gradual Types |❌ |❌ None |Medium |Medium +|Session Types (Advanced) |❌ |❌ None |Medium |High +|Linear Logic Types |❌ |❌ None |Medium |High +|Substructural Types |❌ |❌ None |Medium |High +|Universe Polymorphism |❌ |✅ Agda/Coq/Lean |Low |Low +|Type Classes |❌ |✅ Multiple |Low |Low +|=== + +=== Strategic Expansion Plan + +==== Phase 1: Critical Gap Closure (6-12 months) + +*Objective*: Add support for the most critical missing type systems + +[arabic] +. *Add TypeLL Backend* (Choreographic, Echo, Tropical, Dyadic, Session, +Linear Logic) +* Implement TypeLL prover backend +* Add choreographic type detection +* Implement echo type system support +* Add tropical resource typing +* Develop dyadic type checking +* Enhance session type capabilities +* Add linear logic type support +. *Add Katagoria Backend* (Tropical, Epistemic, Substructural) +* Implement Katagoria prover backend +* Add tropical resource typing support +* Implement epistemic type system +* Add substructural type checking +* Develop resource-aware type analysis +. *Enhance Type System Classification* +* Extend type system detector +* Add advanced type system categories +* Implement type system capability matrix +* Develop type system compatibility analysis + +==== Phase 2: Advanced Type System Integration (12-24 months) + +*Objective*: Deepen support for advanced type systems + +[arabic] +. *Type System Interoperability Hub* +* Create central type system registry +* Develop type system mapping database +* Implement cross-system type equivalence detection +* Add type system compatibility matrix +. *Meta-Level Type Analysis* +* Implement meta-level type inference +* Develop cross-system type checking +* Add type-aware proof routing enhancement +* Create type safety verification framework +. *Advanced Type Preservation* +* Implement type preservation proofs +* Add type safety monitoring across systems +* Develop type-aware confidence scoring +* Create type system trust metrics + +==== Phase 3: Type System Leadership (24-36 months) + +*Objective*: Establish ECHIDNA as the leader in cross-system type +arbitration + +[arabic] +. *Universal Type Theory Mapping* +* Develop type theory correspondence framework +* Implement automated type equivalence detection +* Create type theory translation algorithms +* Build type system interoperability standards +. *Type-Aware Proof Exchange* +* Enhance OpenTheory with type information +* Extend Dedukti with type preservation +* Develop type-aware proof transformation +* Implement type-safe proof exchange protocols +. *Type System Research Integration* +* Add experimental type system backends +* Implement type system research sandbox +* Develop type theory experimentation framework +* Create type system benchmarking suite + +=== Implementation Roadmap + +==== Immediate Actions (0-3 months) + +[arabic] +. *Add TypeLL Backend* +* Research TypeLL integration requirements +* Implement basic TypeLL prover backend +* Add choreographic type detection +* Test with simple choreographic protocols +. *Enhance Type System Detector* +* Extend current type system classifier +* Add advanced type system categories +* Implement type capability matrix +* Test with existing backends +. *Add Katagoria Backend* +* Research Katagoria integration +* Implement basic Katagoria prover backend +* Add tropical type detection +* Test with resource-aware examples + +==== Short-Term Actions (3-6 months) + +[arabic] +. *Complete TypeLL Integration* +* Add echo type support +* Implement dyadic type checking +* Enhance session type capabilities +* Add linear logic type support +. *Complete Katagoria Integration* +* Add epistemic type support +* Implement substructural type checking +* Enhance resource-aware analysis +* Test with complex examples +. *Type System Documentation* +* Create type system capability matrix +* Document type system support +* Update user guides with type information +* Add type system examples + +==== Medium-Term Actions (6-12 months) + +[arabic] +. *Type System Interoperability* +* Develop type system registry +* Implement type equivalence detection +* Create type compatibility matrix +* Test cross-system type mapping +. *Meta-Level Type Analysis* +* Implement meta-level type inference +* Develop cross-system type checking +* Add type-aware proof routing +* Create type safety verification +. *Type Preservation Framework* +* Implement type preservation proofs +* Add type safety monitoring +* Develop type-aware confidence scoring +* Create type system trust metrics + +=== Resource Requirements + +==== Backend Development + +* *TypeLL Backend*: 2-3 developer months +* *Katagoria Backend*: 2-3 developer months +* *Type System Enhancements*: 1-2 developer months + +==== Type System Research + +* *Type Theory Analysis*: 1-2 researcher months +* *Type System Mapping*: 1-2 researcher months +* *Type Preservation Proofs*: 1-2 researcher months + +==== Testing & Documentation + +* *Type System Testing*: 1 developer month +* *Type System Documentation*: 1 technical writer month +* *User Guide Updates*: 0.5 technical writer month + +=== Success Metrics + +==== Type System Coverage + +* *Phase 1*: 60% of advanced type systems supported +* *Phase 2*: 80% of advanced type systems supported +* *Phase 3*: 95% of advanced type systems supported + +==== Type System Capabilities + +* *Choreographic Types*: Full support by Phase 1 +* *Echo Types*: Full support by Phase 1 +* *Tropical Types*: Full support by Phase 1 +* *Epistemic Types*: Full support by Phase 2 +* *Advanced Substructural*: Full support by Phase 2 +* *Universal Type Mapping*: Full support by Phase 3 + +==== User Impact + +* *Type-Aware Proof Routing*: 30% improvement in routing accuracy +* *Cross-System Type Safety*: 50% reduction in type errors +* *Type System Interoperability*: 40% improvement in cross-system proof +success + +=== Conclusion + +ECHIDNA currently has *significant gaps* in advanced type system +support, particularly in: + +[arabic] +. *Choreographic Types* (multiparty protocols) +. *Echo Types* (feedback typing) +. *Tropical Types* (resource-aware) +. *Epistemic Types* (knowledge/belief) +. *Advanced Substructural Types* (affine, relevant, etc.) +. *Dyadic Types* (two-party protocols) + +Our *strategic expansion plan* focuses on: + +[arabic] +. *Adding TypeLL and Katagoria backends* to gain immediate access to +advanced type systems +. *Enhancing type system classification* to better understand and work +with diverse type systems +. *Developing meta-level type analysis* to provide cross-system type +capabilities +. *Creating type system interoperability* to enable seamless work across +different type theories + +By implementing this plan, ECHIDNA will *transform from a system with +limited native typing* to *the world’s most comprehensive cross-system +type arbitration platform*, capable of working with virtually any +advanced type system while maintaining our unique position as the only +system that can bridge multiple type theories for mathematical object +identity resolution. diff --git a/docs/design/ADVANCED_TYPING_GAP_ANALYSIS.md b/docs/design/ADVANCED_TYPING_GAP_ANALYSIS.md deleted file mode 100644 index 7b784b01..00000000 --- a/docs/design/ADVANCED_TYPING_GAP_ANALYSIS.md +++ /dev/null @@ -1,462 +0,0 @@ -# Advanced Typing Capabilities: Gap Analysis and Expansion Strategy - -## Current State of Type Support in ECHIDNA - -### Supported Type Systems (via Backend Provers) - -ECHIDNA currently supports these type systems **through its backend provers**: - -| Type System Category | Supported via Backend | Native Support | -|---------------------|----------------------|----------------| -| **Dependent Types** | ✅ Agda, Coq, Lean, Idris2 | ❌ No | -| **Simple Types** | ✅ Isabelle/HOL, HOL4, HOL Light | ❌ No | -| **Inductive Types** | ✅ Agda, Coq, Lean, Idris2 | ❌ No | -| **Coinductive Types** | ✅ Agda, Coq | ❌ No | -| **Linear Types** | ✅ Idris2 | ❌ No | -| **Effect Types** | ✅ Idris2, F* | ❌ No | -| **Refinement Types** | ✅ F* | ❌ No | -| **Universe Polymorphism** | ✅ Agda, Coq, Lean | ❌ No | -| **Type Classes** | ✅ Agda, Coq, Idris2, Isabelle | ❌ No | -| **Substructural Types** | ✅ (via backend provers) | ❌ No | -| **Quantitative Types** | ✅ Idris2 | ❌ No | - -### Missing Advanced Type Systems - -Based on our analysis, ECHIDNA is **missing native support** for these advanced type systems: - -## 1. Choreographic Types - -**Status**: ❌ Not supported (neither native nor via backend) - -**What's Missing**: -- No prover backend with native choreographic type support -- No choreographic type system detection -- No choreographic protocol verification -- No endpoint projection analysis -- No multiparty session type compatibility - -**Potential Backend Candidates**: -- TypeLL (choreographic type system research) -- Katagoria (choreographic verification) -- Tropical resource typing extensions - -**Action Plan**: -1. Add TypeLL backend with choreographic type support -2. Implement choreographic type detection in type system classifier -3. Add choreographic protocol verification capabilities -4. Develop endpoint projection analysis -5. Create multiparty session type compatibility checking - -## 2. Echo Types - -**Status**: ❌ Not supported - -**What's Missing**: -- No echo type system detection -- No echo type checking infrastructure -- No feedback typing analysis -- No echo type safety verification -- No echo type preservation proofs - -**Potential Backend Candidates**: -- TypeLL (echo type research) -- Katagoria (echo type extensions) - -**Action Plan**: -1. Research echo type theory integration -2. Add echo type detection to type system classifier -3. Implement echo type safety monitoring -4. Develop echo type preservation verification -5. Add echo type compatibility checking - -## 3. Tropical Types (Resource-Aware) - -**Status**: ❌ Not supported - -**What's Missing**: -- No tropical semiring type system -- No resource budget typing -- No latency/throughput type analysis -- No tropical Kleene star operations -- No resource consumption verification - -**Potential Backend Candidates**: -- Katagoria (tropical resource typing) -- TypeLL (tropical extensions) - -**Action Plan**: -1. Add Katagoria backend with tropical typing -2. Implement tropical type system detection -3. Develop resource budget analysis -4. Add latency/throughput type checking -5. Create tropical type preservation verification - -## 4. Epistemic Types - -**Status**: ❌ Not supported - -**What's Missing**: -- No epistemic modal type system -- No knowledge/belief type operators -- No common knowledge analysis -- No epistemic logic integration -- No secrecy/privacy type verification - -**Potential Backend Candidates**: -- TypeLL (epistemic type research) -- Security-focused provers (Tamarin, ProVerif extensions) - -**Action Plan**: -1. Research epistemic type theory integration -2. Add epistemic type detection -3. Implement knowledge/belief type operators -4. Develop common knowledge analysis -5. Add secrecy/privacy type verification - -## 5. Advanced Substructural Types - -**Status**: ✅ Partial (via Idris2 linear types) - -**What's Missing**: -- No comprehensive substructural type system -- No affine type system (single-use types) -- No relevant type system (resource-relevant types) -- No bunched type system support -- No fine-grained resource tracking - -**Potential Backend Candidates**: -- TypeLL (substructural type research) -- Katagoria (resource typing) - -**Action Plan**: -1. Add TypeLL backend with substructural types -2. Implement affine type detection -3. Develop relevant type system support -4. Add bunched logic type checking -5. Create fine-grained resource tracking - -## 6. Dyadic Types - -**Status**: ❌ Not supported - -**What's Missing**: -- No dyadic type system (two-party protocols) -- No dyadic session type verification -- No dual type checking -- No protocol compatibility analysis -- No dyadic type preservation - -**Potential Backend Candidates**: -- TypeLL (dyadic type research) -- Session type provers - -**Action Plan**: -1. Research dyadic type theory -2. Add dyadic type system detection -3. Implement dyadic session type verification -4. Develop dual type checking -5. Create protocol compatibility analysis - -## 7. Advanced Effect Systems - -**Status**: ✅ Partial (via Idris2, F*) - -**What's Missing**: -- No comprehensive effect system classification -- No algebraic effect type checking -- No effect polymorphism analysis -- No effect subtyping verification -- No effect handler type safety - -**Potential Backend Candidates**: -- Idris2 (enhanced effect system) -- F* (effect refinement) -- TypeLL (effect system research) - -**Action Plan**: -1. Enhance effect system detection -2. Implement algebraic effect analysis -3. Add effect polymorphism support -4. Develop effect subtyping verification -5. Create effect handler type safety checking - -## 8. Gradual Typing - -**Status**: ❌ Not supported - -**What's Missing**: -- No gradual type system support -- No dynamic/static type mixing -- No gradual type checking -- No cast insertion analysis -- No gradual type safety verification - -**Potential Backend Candidates**: -- TypeScript (gradual typing research) -- Reticulated Python (gradual typing) - -**Action Plan**: -1. Research gradual typing integration -2. Add gradual type system detection -3. Implement gradual type checking -4. Develop cast insertion analysis -5. Create gradual type safety verification - -## 9. Session Types (Advanced) - -**Status**: ✅ Partial (basic session types) - -**What's Missing**: -- No advanced session type system -- No multiparty session types (beyond dyadic) -- No session type polymorphism -- No session type subtyping -- No session type refinement - -**Potential Backend Candidates**: -- TypeLL (session type research) -- Katagoria (session type extensions) - -**Action Plan**: -1. Add TypeLL backend with advanced session types -2. Implement multiparty session type detection -3. Develop session type polymorphism -4. Add session type subtyping -5. Create session type refinement - -## 10. Linear Logic Types - -**Status**: ❌ Not supported (beyond Idris2 linear types) - -**What's Missing**: -- No full linear logic type system -- No linear/affine/relevant/unrestricted classification -- No linear logic proof term analysis -- No linear resource semantics -- No linear type preservation verification - -**Potential Backend Candidates**: -- TypeLL (linear logic research) -- Linear logic provers - -**Action Plan**: -1. Add linear logic prover backend -2. Implement linear logic type detection -3. Develop linear resource semantics -4. Add linear type preservation verification -5. Create linear logic proof term analysis - -## Comprehensive Gap Analysis - -### Type System Support Matrix - -| Type System | Native | Via Backend | Gap Severity | Priority | -|-------------|--------|-------------|--------------|----------| -| Dependent Types | ❌ | ✅ Agda/Coq/Lean/Idris2 | Low | Medium | -| Linear Types | ❌ | ✅ Idris2 | Medium | High | -| Effect Types | ❌ | ✅ Idris2/F* | Medium | High | -| Refinement Types | ❌ | ✅ F* | Medium | High | -| Choreographic Types | ❌ | ❌ None | Critical | Very High | -| Echo Types | ❌ | ❌ None | Critical | Very High | -| Tropical Types | ❌ | ❌ None | Critical | Very High | -| Epistemic Types | ❌ | ❌ None | Critical | Very High | -| Affine Types | ❌ | ❌ None | High | High | -| Relevant Types | ❌ | ❌ None | High | High | -| Dyadic Types | ❌ | ❌ None | High | High | -| Gradual Types | ❌ | ❌ None | Medium | Medium | -| Session Types (Advanced) | ❌ | ❌ None | Medium | High | -| Linear Logic Types | ❌ | ❌ None | Medium | High | -| Substructural Types | ❌ | ❌ None | Medium | High | -| Universe Polymorphism | ❌ | ✅ Agda/Coq/Lean | Low | Low | -| Type Classes | ❌ | ✅ Multiple | Low | Low | - -## Strategic Expansion Plan - -### Phase 1: Critical Gap Closure (6-12 months) - -**Objective**: Add support for the most critical missing type systems - -1. **Add TypeLL Backend** (Choreographic, Echo, Tropical, Dyadic, Session, Linear Logic) - - Implement TypeLL prover backend - - Add choreographic type detection - - Implement echo type system support - - Add tropical resource typing - - Develop dyadic type checking - - Enhance session type capabilities - - Add linear logic type support - -2. **Add Katagoria Backend** (Tropical, Epistemic, Substructural) - - Implement Katagoria prover backend - - Add tropical resource typing support - - Implement epistemic type system - - Add substructural type checking - - Develop resource-aware type analysis - -3. **Enhance Type System Classification** - - Extend type system detector - - Add advanced type system categories - - Implement type system capability matrix - - Develop type system compatibility analysis - -### Phase 2: Advanced Type System Integration (12-24 months) - -**Objective**: Deepen support for advanced type systems - -1. **Type System Interoperability Hub** - - Create central type system registry - - Develop type system mapping database - - Implement cross-system type equivalence detection - - Add type system compatibility matrix - -2. **Meta-Level Type Analysis** - - Implement meta-level type inference - - Develop cross-system type checking - - Add type-aware proof routing enhancement - - Create type safety verification framework - -3. **Advanced Type Preservation** - - Implement type preservation proofs - - Add type safety monitoring across systems - - Develop type-aware confidence scoring - - Create type system trust metrics - -### Phase 3: Type System Leadership (24-36 months) - -**Objective**: Establish ECHIDNA as the leader in cross-system type arbitration - -1. **Universal Type Theory Mapping** - - Develop type theory correspondence framework - - Implement automated type equivalence detection - - Create type theory translation algorithms - - Build type system interoperability standards - -2. **Type-Aware Proof Exchange** - - Enhance OpenTheory with type information - - Extend Dedukti with type preservation - - Develop type-aware proof transformation - - Implement type-safe proof exchange protocols - -3. **Type System Research Integration** - - Add experimental type system backends - - Implement type system research sandbox - - Develop type theory experimentation framework - - Create type system benchmarking suite - -## Implementation Roadmap - -### Immediate Actions (0-3 months) - -1. **Add TypeLL Backend** - - Research TypeLL integration requirements - - Implement basic TypeLL prover backend - - Add choreographic type detection - - Test with simple choreographic protocols - -2. **Enhance Type System Detector** - - Extend current type system classifier - - Add advanced type system categories - - Implement type capability matrix - - Test with existing backends - -3. **Add Katagoria Backend** - - Research Katagoria integration - - Implement basic Katagoria prover backend - - Add tropical type detection - - Test with resource-aware examples - -### Short-Term Actions (3-6 months) - -1. **Complete TypeLL Integration** - - Add echo type support - - Implement dyadic type checking - - Enhance session type capabilities - - Add linear logic type support - -2. **Complete Katagoria Integration** - - Add epistemic type support - - Implement substructural type checking - - Enhance resource-aware analysis - - Test with complex examples - -3. **Type System Documentation** - - Create type system capability matrix - - Document type system support - - Update user guides with type information - - Add type system examples - -### Medium-Term Actions (6-12 months) - -1. **Type System Interoperability** - - Develop type system registry - - Implement type equivalence detection - - Create type compatibility matrix - - Test cross-system type mapping - -2. **Meta-Level Type Analysis** - - Implement meta-level type inference - - Develop cross-system type checking - - Add type-aware proof routing - - Create type safety verification - -3. **Type Preservation Framework** - - Implement type preservation proofs - - Add type safety monitoring - - Develop type-aware confidence scoring - - Create type system trust metrics - -## Resource Requirements - -### Backend Development -- **TypeLL Backend**: 2-3 developer months -- **Katagoria Backend**: 2-3 developer months -- **Type System Enhancements**: 1-2 developer months - -### Type System Research -- **Type Theory Analysis**: 1-2 researcher months -- **Type System Mapping**: 1-2 researcher months -- **Type Preservation Proofs**: 1-2 researcher months - -### Testing & Documentation -- **Type System Testing**: 1 developer month -- **Type System Documentation**: 1 technical writer month -- **User Guide Updates**: 0.5 technical writer month - -## Success Metrics - -### Type System Coverage -- **Phase 1**: 60% of advanced type systems supported -- **Phase 2**: 80% of advanced type systems supported -- **Phase 3**: 95% of advanced type systems supported - -### Type System Capabilities -- **Choreographic Types**: Full support by Phase 1 -- **Echo Types**: Full support by Phase 1 -- **Tropical Types**: Full support by Phase 1 -- **Epistemic Types**: Full support by Phase 2 -- **Advanced Substructural**: Full support by Phase 2 -- **Universal Type Mapping**: Full support by Phase 3 - -### User Impact -- **Type-Aware Proof Routing**: 30% improvement in routing accuracy -- **Cross-System Type Safety**: 50% reduction in type errors -- **Type System Interoperability**: 40% improvement in cross-system proof success - -## Conclusion - -ECHIDNA currently has **significant gaps** in advanced type system support, particularly in: - -1. **Choreographic Types** (multiparty protocols) -2. **Echo Types** (feedback typing) -3. **Tropical Types** (resource-aware) -4. **Epistemic Types** (knowledge/belief) -5. **Advanced Substructural Types** (affine, relevant, etc.) -6. **Dyadic Types** (two-party protocols) - -Our **strategic expansion plan** focuses on: - -1. **Adding TypeLL and Katagoria backends** to gain immediate access to advanced type systems -2. **Enhancing type system classification** to better understand and work with diverse type systems -3. **Developing meta-level type analysis** to provide cross-system type capabilities -4. **Creating type system interoperability** to enable seamless work across different type theories - -By implementing this plan, ECHIDNA will **transform from a system with limited native typing** to **the world's most comprehensive cross-system type arbitration platform**, capable of working with virtually any advanced type system while maintaining our unique position as the only system that can bridge multiple type theories for mathematical object identity resolution. \ No newline at end of file diff --git a/docs/design/OTHER_SYSTEMS_USP_PPA.adoc b/docs/design/OTHER_SYSTEMS_USP_PPA.adoc new file mode 100644 index 00000000..d6515417 --- /dev/null +++ b/docs/design/OTHER_SYSTEMS_USP_PPA.adoc @@ -0,0 +1,526 @@ +== Unique Selling Propositions (USP) and Primary Purpose Areas (PPA) of Other Proof Systems + +=== Comparison Framework + +==== ECHIDNA’s USP/PPA (for reference) + +* *USP*: Neurosymbolic cross-prover arbitration with 48+ backends +* *PPA*: Mathematical object identity resolution across heterogeneous +proof systems +* *Key Differentiator*: Only system actively solving cross-system +theorem equivalence + +=== 1. Isabelle/HOL + +==== USP: Mature Interactive Theorem Proving with Sledgehammer + +* *Automation Integration*: Sledgehammer + Metis + SMT solver +integration +* *Isar Language*: Human-readable structured proof language +* *Extensive Libraries*: Archive of Formal Proofs (AFP) with 1,000+ +entries +* *HOL Framework*: Higher-order logic with deep semantic embedding + +==== PPA: Large-Scale Formalization of Mathematics + +* *Mathematical Theories*: Analysis, algebra, topology, number theory +* *Program Verification*: Functional programming, imperative programs +* *Security Protocols*: Cryptographic protocol verification +* *Education*: Widely used in teaching formal methods + +==== Key Strengths: + +* Mature ecosystem with 30+ years of development +* Excellent automation via Sledgehammer +* Strong community and extensive documentation +* Proven track record in large formalizations + +==== Limitations vs ECHIDNA: + +* Single prover backend (no cross-system arbitration) +* No neurosymbolic hybrid architecture +* Limited trust pipeline (basic verification only) +* No cross-prover proof exchange capabilities + +=== 2. Coq + +==== USP: Dependent Type Theory with Extraction + +* *Calculus of Inductive Constructions*: Powerful dependent type system +* *Program Extraction*: Certified program extraction to OCaml/Haskell +* *MathComp Library*: Comprehensive mathematical components library +* *SSReflect*: Advanced proof language for large developments + +==== PPA: Certified Programming and Mathematical Foundations + +* *Program Verification*: Certified algorithms and data structures +* *Mathematical Foundations*: Homology, algebraic topology, category +theory +* *CompCert*: Verified C compiler +* *Four Color Theorem*: Famous formalized proof + +==== Key Strengths: + +* Industry-strength program verification +* Mature dependent type theory implementation +* Strong mathematical library ecosystem +* Active academic and industrial adoption + +==== Limitations vs ECHIDNA: + +* Single prover architecture +* No cross-system theorem equivalence +* Limited automation compared to ECHIDNA’s neurosymbolic approach +* No multi-prover trust pipeline + +=== 3. Lean 4 + +==== USP: Modern Functional Programming + Theorem Proving + +* *Meta Programming*: Elaborated term reflection and quotation +* *Tactic Framework*: Advanced tactic system with meta-programming +* *Mathlib4*: Modern mathematical library +* *Performance*: High-performance kernel and elaboration + +==== PPA: Mathematical Research and Education + +* *Mathematical Formalization*: Algebra, analysis, topology +* *Education*: Lean for the Curious Mathematician +* *Automated Reasoning*: Integration with neural tactics +* *Program Verification*: Functional programming verification + +==== Key Strengths: + +* Modern codebase with excellent performance +* Growing mathematical library (Mathlib4) +* Strong meta-programming capabilities +* Increasing adoption in mathematical research + +==== Limitations vs ECHIDNA: + +* Single prover system +* No cross-prover arbitration capabilities +* Limited trust infrastructure +* No vocabulary management at ECHIDNA’s scale + +=== 4. HOL Light + +==== USP: Minimalist Higher-Order Logic Kernel + +* *Small Trusted Core*: ~400 lines of OCaml +* *Proof Producing*: Generates proof objects for verification +* *Strong Automation*: MESON, METIS, and other decision procedures +* *Flyspeck Project*: Formal proof of Kepler conjecture + +==== PPA: Large-Scale Formal Verification Projects + +* *Mathematical Theories*: Real analysis, measure theory +* *Formalized Mathematics*: Kepler conjecture, odd order theorem +* *Hardware Verification*: Processor verification +* *Theorem Proving Research*: Meta-theoretic results + +==== Key Strengths: + +* Extremely small trusted computing base +* Strong automation capabilities +* Proven track record in large formalizations +* Excellent for research in theorem proving + +==== Limitations vs ECHIDNA: + +* Single prover architecture +* No cross-system integration +* Limited modern features compared to ECHIDNA +* No neurosymbolic capabilities + +=== 5. Mizar + +==== USP: Natural Deduction Style with Readable Syntax + +* *Natural Language-like Syntax*: Close to mathematical notation +* *Mizar Mathematical Library*: Large repository of formalized +mathematics +* *Article-Based*: Modular article system +* *Long History*: One of the oldest working ITPs + +==== PPA: Mathematical Knowledge Formalization + +* *Mathematical Theories*: Algebra, topology, analysis +* *Formalized Mathematics*: Large library of theorems +* *Education*: Used in teaching formal methods +* *Knowledge Management*: Mathematical knowledge base + +==== Key Strengths: + +* Natural deduction style proof language +* Large mathematical library +* Stable and mature system +* Good for mathematical knowledge management + +==== Limitations vs ECHIDNA: + +* Single prover system +* No cross-prover capabilities +* Limited automation +* No modern AI integration + +=== 6. Metamath + +==== USP: Minimalist Foundation with Extreme Simplicity + +* *Minimal Axioms*: Based on minimal logical foundations +* *Proof Verification*: Independent proof verification +* *Set.mm*: Comprehensive mathematical database +* *Extreme Simplicity*: Simple language and proof format + +==== PPA: Foundational Mathematics and Proof Verification + +* *Foundational Mathematics*: Set theory, logic foundations +* *Proof Verification*: Independent verification of proofs +* *Education*: Learning formal systems +* *Research*: Metamathematical investigations + +==== Key Strengths: + +* Extremely simple and verifiable core +* Large database of formalized mathematics +* Independent proof verification capabilities +* Good for foundational research + +==== Limitations vs ECHIDNA: + +* Very low-level abstraction +* No automation +* No cross-system capabilities +* Limited practical applications + +=== 7. Z3 + +==== USP: Industrial-Strength SMT Solving + +* *High Performance*: Optimized for real-world problems +* *Multiple Theories*: UF, LIA, LRA, bitvectors, arrays +* *Incremental Solving*: Support for incremental problems +* *Model Generation*: Counterexample generation + +==== PPA: Program Verification and Constraint Solving + +* *Software Verification*: Program analysis and verification +* *Hardware Verification*: Circuit and hardware verification +* *Security Analysis*: Protocol and cryptographic analysis +* *Constraint Solving*: Industrial constraint problems + +==== Key Strengths: + +* Industry-standard SMT solver +* Excellent performance on real-world problems +* Wide theory support +* Mature and battle-tested + +==== Limitations vs ECHIDNA: + +* Single solver (no ITP capabilities) +* No proof object generation +* Limited mathematical expressiveness +* No cross-system integration + +=== 8. CVC5 + +==== USP: Next-Generation SMT Solving with Advanced Features + +* *Modular Architecture*: Pluggable theory solvers +* *Quantifier Support*: Advanced quantifier handling +* *Strings and Sequences*: Native string theory support +* *Proof Production*: Proof object generation + +==== PPA: Advanced Program Analysis and Verification + +* *Program Verification*: Complex program analysis +* *Security Protocols*: Cryptographic protocol verification +* *Theory Combination*: Multi-theory problem solving +* *Research*: SMT solver research platform + +==== Key Strengths: + +* Advanced quantifier handling +* String theory support +* Proof object generation +* Modular and extensible architecture + +==== Limitations vs ECHIDNA: + +* Still primarily an SMT solver +* No interactive theorem proving +* Limited cross-system capabilities +* No neurosymbolic integration + +=== 9. Vampire + +==== USP: High-Performance First-Order ATP + +* *Superposition Calculus*: State-of-the-art first-order reasoning +* *SAT Solver Integration*: Modern SAT solving techniques +* *Theory Reasoning*: Built-in theory support +* *Proof Generation*: TSTP proof output + +==== PPA: Automated Theorem Proving + +* *Mathematical Theorems*: Automated mathematical reasoning +* *Program Verification*: Verification condition proving +* *Ontology Reasoning*: Description logic reasoning +* *Research*: ATP technique development + +==== Key Strengths: + +* State-of-the-art first-order ATP +* Excellent performance in competitions +* Theory reasoning capabilities +* Proof generation support + +==== Limitations vs ECHIDNA: + +* First-order only (no higher-order) +* No interactive capabilities +* Limited trust infrastructure +* No cross-system integration + +=== 10. E Prover + +==== USP: Equational Reasoning Specialist + +* *Equational Reasoning*: Advanced equational proof techniques +* *Completion Procedures*: Knuth-Bendix completion +* *Theory Support*: Built-in arithmetic theories +* *Proof Output*: Detailed proof generation + +==== PPA: Equational Theorem Proving + +* *Algebraic Reasoning*: Group theory, ring theory +* *Term Rewriting*: Rewriting system analysis +* *Program Verification*: Equational program properties +* *Research*: Equational reasoning research + +==== Key Strengths: + +* Excellent equational reasoning +* Completion procedure support +* Theory-specific optimizations +* Detailed proof output + +==== Limitations vs ECHIDNA: + +* Specialized for equational reasoning +* No higher-order capabilities +* Limited automation scope +* No cross-system features + +=== 11. Dafny + +==== USP: Program Verification with Automatic Proof + +* *Automatic Verification*: SMT-based automatic proving +* *Programming Language*: Full programming language with verification +* *Termination Proofs*: Automatic termination checking +* *Extractable Code*: Verified code extraction + +==== PPA: Program Verification and Correctness + +* *Program Verification*: Functional correctness proofs +* *Algorithm Verification*: Certified algorithms +* *Education*: Teaching program verification +* *Industrial Applications*: Real-world program verification + +==== Key Strengths: + +* Integrated programming and verification +* Automatic SMT-based proving +* Good for teaching verification +* Practical industrial applications + +==== Limitations vs ECHIDNA: + +* Single system architecture +* Limited mathematical expressiveness +* No cross-prover capabilities +* No advanced trust pipeline + +=== 12. Why3 + +==== USP: WhyML Language with Multiple Backend Support + +* *WhyML Language*: Dedicated verification language +* *Multiple Provers*: Supports multiple SMT solvers +* *Program Extraction*: Verified program extraction +* *WP Calculation*: Weakest precondition generation + +==== PPA: Deductive Program Verification + +* *Program Verification*: Functional correctness +* *Algorithm Certification*: Certified algorithms +* *Education*: Teaching deductive verification +* *Research*: Verification technique development + +==== Key Strengths: + +* Dedicated verification language +* Multiple prover backend support +* Weakest precondition approach +* Good educational tool + +==== Limitations vs ECHIDNA: + +* Primarily program verification focused +* No cross-system theorem equivalence +* Limited mathematical library +* No neurosymbolic capabilities + +=== 13. Agda + +==== USP: Dependent Type Theory with Unicode Support + +* *Unicode Syntax*: Mathematical notation support +* *Dependent Types*: Full dependent type system +* *Pattern Matching*: Advanced pattern matching +* *Cubical Extension*: Homotopy type theory support + +==== PPA: Type Theory Research and Formalization + +* *Type Theory*: Advanced type-theoretic developments +* *Homotopy Type Theory*: Cubical Agda extensions +* *Mathematical Formalization*: Type-theoretic mathematics +* *Research*: Type theory and PL research + +==== Key Strengths: + +* Excellent dependent type support +* Unicode mathematical notation +* Cubical extension for HoTT +* Strong type theory research platform + +==== Limitations vs ECHIDNA: + +* Single prover system +* No cross-prover capabilities +* Limited automation +* No trust pipeline infrastructure + +=== 14. Idris 2 + +==== USP: Dependent Types with Linear Types and Effects + +* *Linear Types*: Resource-aware programming +* *Effect System*: Algebraic effects +* *Dependent Types*: Full dependent type system +* *Quantitative Type Theory*: Resource usage tracking + +==== PPA: Resource-Aware Programming and Verification + +* *Resource Verification*: Memory and resource usage +* *Effectful Programming*: Certified effectful programs +* *Quantitative Reasoning*: Resource consumption proofs +* *Research*: Advanced type system research + +==== Key Strengths: + +* Advanced type system features +* Linear and quantitative types +* Effect system integration +* Resource-aware programming + +==== Limitations vs ECHIDNA: + +* Single system architecture +* No cross-prover arbitration +* Limited mathematical library +* No multi-prover trust infrastructure + +=== Comparative Summary + +==== USP Comparison Table + +[width="99%",cols="15%,47%,38%",options="header",] +|=== +|System |Unique Selling Proposition |Primary Purpose Area +|*ECHIDNA* |Neurosymbolic cross-prover arbitration |Mathematical object +identity resolution + +|Isabelle |Sledgehammer automation + Isar |Large-scale mathematical +formalization + +|Coq |Dependent types + program extraction |Certified programming +foundations + +|Lean 4 |Meta-programming + modern FP |Mathematical research & education + +|HOL Light |Minimalist kernel + proof objects |Large-scale formal +verification + +|Mizar |Natural deduction + readable syntax |Mathematical knowledge +formalization + +|Metamath |Minimal foundations + simplicity |Foundational mathematics + +|Z3 |Industrial SMT solving |Program verification & constraints + +|CVC5 |Advanced SMT with proofs |Program analysis & verification + +|Vampire |Superposition calculus ATP |Automated theorem proving + +|E Prover |Equational reasoning |Equational theorem proving + +|Dafny |Automatic program verification |Program correctness proofs + +|Why3 |WhyML + multiple provers |Deductive program verification + +|Agda |Dependent types + Unicode |Type theory research + +|Idris 2 |Linear types + effects |Resource-aware programming +|=== + +==== Key Differentiators of ECHIDNA + +[arabic] +. *Only system with 48+ prover backends* +. *Only system actively solving cross-prover arbitration* +. *Only neurosymbolic hybrid architecture* +. *Only system with 7-stage trust pipeline* +. *Only system integrating OpenTheory + Dedukti* +. *Largest vocabulary management (992K+ terms)* +. *Most comprehensive axiom tracking system* +. *Bayesian confidence scoring across provers* + +==== When to Choose Other Systems + +* *Isabelle*: When you need mature ITP with excellent automation +* *Coq*: For dependent type theory and program extraction +* *Lean 4*: For modern mathematical formalization +* *Z3/CVC5*: For industrial-scale SMT solving +* *Vampire/E Prover*: For automated first-order theorem proving +* *Dafny/Why3*: For program verification tasks +* *Agda/Idris 2*: For advanced type theory research + +==== When ECHIDNA is Uniquely Suited + +* *Cross-prover theorem equivalence* +* *Mathematical object identity resolution* +* *Multi-prover trust arbitration* +* *Neurosymbolic hybrid reasoning* +* *Large-scale vocabulary management* +* *Heterogeneous proof system integration* + +=== Conclusion + +While other proof systems excel in their specific domains (Isabelle for +automation, Coq for dependent types, Z3 for SMT solving, etc.), *ECHIDNA +is uniquely positioned* as the only system that: + +[arabic] +. *Bridges multiple proof systems* (48+ backends) +. *Solves cross-prover arbitration* (mathematical identity resolution) +. *Combines neurosymbolic approaches* (AI + symbolic reasoning) +. *Provides comprehensive trust infrastructure* (7-stage pipeline) +. *Manages large-scale vocabulary* (992K+ terms) + +ECHIDNA’s USP is *cross-system mathematical object arbitration*, making +it the only system capable of determining when theorems from different +proof systems represent the same mathematical truth. diff --git a/docs/design/OTHER_SYSTEMS_USP_PPA.md b/docs/design/OTHER_SYSTEMS_USP_PPA.md deleted file mode 100644 index e757c0e5..00000000 --- a/docs/design/OTHER_SYSTEMS_USP_PPA.md +++ /dev/null @@ -1,436 +0,0 @@ -# Unique Selling Propositions (USP) and Primary Purpose Areas (PPA) of Other Proof Systems - -## Comparison Framework - -### ECHIDNA's USP/PPA (for reference) -- **USP**: Neurosymbolic cross-prover arbitration with 48+ backends -- **PPA**: Mathematical object identity resolution across heterogeneous proof systems -- **Key Differentiator**: Only system actively solving cross-system theorem equivalence - -## 1. Isabelle/HOL - -### USP: Mature Interactive Theorem Proving with Sledgehammer -- **Automation Integration**: Sledgehammer + Metis + SMT solver integration -- **Isar Language**: Human-readable structured proof language -- **Extensive Libraries**: Archive of Formal Proofs (AFP) with 1,000+ entries -- **HOL Framework**: Higher-order logic with deep semantic embedding - -### PPA: Large-Scale Formalization of Mathematics -- **Mathematical Theories**: Analysis, algebra, topology, number theory -- **Program Verification**: Functional programming, imperative programs -- **Security Protocols**: Cryptographic protocol verification -- **Education**: Widely used in teaching formal methods - -### Key Strengths: -- Mature ecosystem with 30+ years of development -- Excellent automation via Sledgehammer -- Strong community and extensive documentation -- Proven track record in large formalizations - -### Limitations vs ECHIDNA: -- Single prover backend (no cross-system arbitration) -- No neurosymbolic hybrid architecture -- Limited trust pipeline (basic verification only) -- No cross-prover proof exchange capabilities - -## 2. Coq - -### USP: Dependent Type Theory with Extraction -- **Calculus of Inductive Constructions**: Powerful dependent type system -- **Program Extraction**: Certified program extraction to OCaml/Haskell -- **MathComp Library**: Comprehensive mathematical components library -- **SSReflect**: Advanced proof language for large developments - -### PPA: Certified Programming and Mathematical Foundations -- **Program Verification**: Certified algorithms and data structures -- **Mathematical Foundations**: Homology, algebraic topology, category theory -- **CompCert**: Verified C compiler -- **Four Color Theorem**: Famous formalized proof - -### Key Strengths: -- Industry-strength program verification -- Mature dependent type theory implementation -- Strong mathematical library ecosystem -- Active academic and industrial adoption - -### Limitations vs ECHIDNA: -- Single prover architecture -- No cross-system theorem equivalence -- Limited automation compared to ECHIDNA's neurosymbolic approach -- No multi-prover trust pipeline - -## 3. Lean 4 - -### USP: Modern Functional Programming + Theorem Proving -- **Meta Programming**: Elaborated term reflection and quotation -- **Tactic Framework**: Advanced tactic system with meta-programming -- **Mathlib4**: Modern mathematical library -- **Performance**: High-performance kernel and elaboration - -### PPA: Mathematical Research and Education -- **Mathematical Formalization**: Algebra, analysis, topology -- **Education**: Lean for the Curious Mathematician -- **Automated Reasoning**: Integration with neural tactics -- **Program Verification**: Functional programming verification - -### Key Strengths: -- Modern codebase with excellent performance -- Growing mathematical library (Mathlib4) -- Strong meta-programming capabilities -- Increasing adoption in mathematical research - -### Limitations vs ECHIDNA: -- Single prover system -- No cross-prover arbitration capabilities -- Limited trust infrastructure -- No vocabulary management at ECHIDNA's scale - -## 4. HOL Light - -### USP: Minimalist Higher-Order Logic Kernel -- **Small Trusted Core**: ~400 lines of OCaml -- **Proof Producing**: Generates proof objects for verification -- **Strong Automation**: MESON, METIS, and other decision procedures -- **Flyspeck Project**: Formal proof of Kepler conjecture - -### PPA: Large-Scale Formal Verification Projects -- **Mathematical Theories**: Real analysis, measure theory -- **Formalized Mathematics**: Kepler conjecture, odd order theorem -- **Hardware Verification**: Processor verification -- **Theorem Proving Research**: Meta-theoretic results - -### Key Strengths: -- Extremely small trusted computing base -- Strong automation capabilities -- Proven track record in large formalizations -- Excellent for research in theorem proving - -### Limitations vs ECHIDNA: -- Single prover architecture -- No cross-system integration -- Limited modern features compared to ECHIDNA -- No neurosymbolic capabilities - -## 5. Mizar - -### USP: Natural Deduction Style with Readable Syntax -- **Natural Language-like Syntax**: Close to mathematical notation -- **Mizar Mathematical Library**: Large repository of formalized mathematics -- **Article-Based**: Modular article system -- **Long History**: One of the oldest working ITPs - -### PPA: Mathematical Knowledge Formalization -- **Mathematical Theories**: Algebra, topology, analysis -- **Formalized Mathematics**: Large library of theorems -- **Education**: Used in teaching formal methods -- **Knowledge Management**: Mathematical knowledge base - -### Key Strengths: -- Natural deduction style proof language -- Large mathematical library -- Stable and mature system -- Good for mathematical knowledge management - -### Limitations vs ECHIDNA: -- Single prover system -- No cross-prover capabilities -- Limited automation -- No modern AI integration - -## 6. Metamath - -### USP: Minimalist Foundation with Extreme Simplicity -- **Minimal Axioms**: Based on minimal logical foundations -- **Proof Verification**: Independent proof verification -- **Set.mm**: Comprehensive mathematical database -- **Extreme Simplicity**: Simple language and proof format - -### PPA: Foundational Mathematics and Proof Verification -- **Foundational Mathematics**: Set theory, logic foundations -- **Proof Verification**: Independent verification of proofs -- **Education**: Learning formal systems -- **Research**: Metamathematical investigations - -### Key Strengths: -- Extremely simple and verifiable core -- Large database of formalized mathematics -- Independent proof verification capabilities -- Good for foundational research - -### Limitations vs ECHIDNA: -- Very low-level abstraction -- No automation -- No cross-system capabilities -- Limited practical applications - -## 7. Z3 - -### USP: Industrial-Strength SMT Solving -- **High Performance**: Optimized for real-world problems -- **Multiple Theories**: UF, LIA, LRA, bitvectors, arrays -- **Incremental Solving**: Support for incremental problems -- **Model Generation**: Counterexample generation - -### PPA: Program Verification and Constraint Solving -- **Software Verification**: Program analysis and verification -- **Hardware Verification**: Circuit and hardware verification -- **Security Analysis**: Protocol and cryptographic analysis -- **Constraint Solving**: Industrial constraint problems - -### Key Strengths: -- Industry-standard SMT solver -- Excellent performance on real-world problems -- Wide theory support -- Mature and battle-tested - -### Limitations vs ECHIDNA: -- Single solver (no ITP capabilities) -- No proof object generation -- Limited mathematical expressiveness -- No cross-system integration - -## 8. CVC5 - -### USP: Next-Generation SMT Solving with Advanced Features -- **Modular Architecture**: Pluggable theory solvers -- **Quantifier Support**: Advanced quantifier handling -- **Strings and Sequences**: Native string theory support -- **Proof Production**: Proof object generation - -### PPA: Advanced Program Analysis and Verification -- **Program Verification**: Complex program analysis -- **Security Protocols**: Cryptographic protocol verification -- **Theory Combination**: Multi-theory problem solving -- **Research**: SMT solver research platform - -### Key Strengths: -- Advanced quantifier handling -- String theory support -- Proof object generation -- Modular and extensible architecture - -### Limitations vs ECHIDNA: -- Still primarily an SMT solver -- No interactive theorem proving -- Limited cross-system capabilities -- No neurosymbolic integration - -## 9. Vampire - -### USP: High-Performance First-Order ATP -- **Superposition Calculus**: State-of-the-art first-order reasoning -- **SAT Solver Integration**: Modern SAT solving techniques -- **Theory Reasoning**: Built-in theory support -- **Proof Generation**: TSTP proof output - -### PPA: Automated Theorem Proving -- **Mathematical Theorems**: Automated mathematical reasoning -- **Program Verification**: Verification condition proving -- **Ontology Reasoning**: Description logic reasoning -- **Research**: ATP technique development - -### Key Strengths: -- State-of-the-art first-order ATP -- Excellent performance in competitions -- Theory reasoning capabilities -- Proof generation support - -### Limitations vs ECHIDNA: -- First-order only (no higher-order) -- No interactive capabilities -- Limited trust infrastructure -- No cross-system integration - -## 10. E Prover - -### USP: Equational Reasoning Specialist -- **Equational Reasoning**: Advanced equational proof techniques -- **Completion Procedures**: Knuth-Bendix completion -- **Theory Support**: Built-in arithmetic theories -- **Proof Output**: Detailed proof generation - -### PPA: Equational Theorem Proving -- **Algebraic Reasoning**: Group theory, ring theory -- **Term Rewriting**: Rewriting system analysis -- **Program Verification**: Equational program properties -- **Research**: Equational reasoning research - -### Key Strengths: -- Excellent equational reasoning -- Completion procedure support -- Theory-specific optimizations -- Detailed proof output - -### Limitations vs ECHIDNA: -- Specialized for equational reasoning -- No higher-order capabilities -- Limited automation scope -- No cross-system features - -## 11. Dafny - -### USP: Program Verification with Automatic Proof -- **Automatic Verification**: SMT-based automatic proving -- **Programming Language**: Full programming language with verification -- **Termination Proofs**: Automatic termination checking -- **Extractable Code**: Verified code extraction - -### PPA: Program Verification and Correctness -- **Program Verification**: Functional correctness proofs -- **Algorithm Verification**: Certified algorithms -- **Education**: Teaching program verification -- **Industrial Applications**: Real-world program verification - -### Key Strengths: -- Integrated programming and verification -- Automatic SMT-based proving -- Good for teaching verification -- Practical industrial applications - -### Limitations vs ECHIDNA: -- Single system architecture -- Limited mathematical expressiveness -- No cross-prover capabilities -- No advanced trust pipeline - -## 12. Why3 - -### USP: WhyML Language with Multiple Backend Support -- **WhyML Language**: Dedicated verification language -- **Multiple Provers**: Supports multiple SMT solvers -- **Program Extraction**: Verified program extraction -- **WP Calculation**: Weakest precondition generation - -### PPA: Deductive Program Verification -- **Program Verification**: Functional correctness -- **Algorithm Certification**: Certified algorithms -- **Education**: Teaching deductive verification -- **Research**: Verification technique development - -### Key Strengths: -- Dedicated verification language -- Multiple prover backend support -- Weakest precondition approach -- Good educational tool - -### Limitations vs ECHIDNA: -- Primarily program verification focused -- No cross-system theorem equivalence -- Limited mathematical library -- No neurosymbolic capabilities - -## 13. Agda - -### USP: Dependent Type Theory with Unicode Support -- **Unicode Syntax**: Mathematical notation support -- **Dependent Types**: Full dependent type system -- **Pattern Matching**: Advanced pattern matching -- **Cubical Extension**: Homotopy type theory support - -### PPA: Type Theory Research and Formalization -- **Type Theory**: Advanced type-theoretic developments -- **Homotopy Type Theory**: Cubical Agda extensions -- **Mathematical Formalization**: Type-theoretic mathematics -- **Research**: Type theory and PL research - -### Key Strengths: -- Excellent dependent type support -- Unicode mathematical notation -- Cubical extension for HoTT -- Strong type theory research platform - -### Limitations vs ECHIDNA: -- Single prover system -- No cross-prover capabilities -- Limited automation -- No trust pipeline infrastructure - -## 14. Idris 2 - -### USP: Dependent Types with Linear Types and Effects -- **Linear Types**: Resource-aware programming -- **Effect System**: Algebraic effects -- **Dependent Types**: Full dependent type system -- **Quantitative Type Theory**: Resource usage tracking - -### PPA: Resource-Aware Programming and Verification -- **Resource Verification**: Memory and resource usage -- **Effectful Programming**: Certified effectful programs -- **Quantitative Reasoning**: Resource consumption proofs -- **Research**: Advanced type system research - -### Key Strengths: -- Advanced type system features -- Linear and quantitative types -- Effect system integration -- Resource-aware programming - -### Limitations vs ECHIDNA: -- Single system architecture -- No cross-prover arbitration -- Limited mathematical library -- No multi-prover trust infrastructure - -## Comparative Summary - -### USP Comparison Table - -| System | Unique Selling Proposition | Primary Purpose Area | -|--------|---------------------------|----------------------| -| **ECHIDNA** | Neurosymbolic cross-prover arbitration | Mathematical object identity resolution | -| Isabelle | Sledgehammer automation + Isar | Large-scale mathematical formalization | -| Coq | Dependent types + program extraction | Certified programming foundations | -| Lean 4 | Meta-programming + modern FP | Mathematical research & education | -| HOL Light | Minimalist kernel + proof objects | Large-scale formal verification | -| Mizar | Natural deduction + readable syntax | Mathematical knowledge formalization | -| Metamath | Minimal foundations + simplicity | Foundational mathematics | -| Z3 | Industrial SMT solving | Program verification & constraints | -| CVC5 | Advanced SMT with proofs | Program analysis & verification | -| Vampire | Superposition calculus ATP | Automated theorem proving | -| E Prover | Equational reasoning | Equational theorem proving | -| Dafny | Automatic program verification | Program correctness proofs | -| Why3 | WhyML + multiple provers | Deductive program verification | -| Agda | Dependent types + Unicode | Type theory research | -| Idris 2 | Linear types + effects | Resource-aware programming | - -### Key Differentiators of ECHIDNA - -1. **Only system with 48+ prover backends** -2. **Only system actively solving cross-prover arbitration** -3. **Only neurosymbolic hybrid architecture** -4. **Only system with 7-stage trust pipeline** -5. **Only system integrating OpenTheory + Dedukti** -6. **Largest vocabulary management (992K+ terms)** -7. **Most comprehensive axiom tracking system** -8. **Bayesian confidence scoring across provers** - -### When to Choose Other Systems - -- **Isabelle**: When you need mature ITP with excellent automation -- **Coq**: For dependent type theory and program extraction -- **Lean 4**: For modern mathematical formalization -- **Z3/CVC5**: For industrial-scale SMT solving -- **Vampire/E Prover**: For automated first-order theorem proving -- **Dafny/Why3**: For program verification tasks -- **Agda/Idris 2**: For advanced type theory research - -### When ECHIDNA is Uniquely Suited - -- **Cross-prover theorem equivalence** -- **Mathematical object identity resolution** -- **Multi-prover trust arbitration** -- **Neurosymbolic hybrid reasoning** -- **Large-scale vocabulary management** -- **Heterogeneous proof system integration** - -## Conclusion - -While other proof systems excel in their specific domains (Isabelle for automation, Coq for dependent types, Z3 for SMT solving, etc.), **ECHIDNA is uniquely positioned** as the only system that: - -1. **Bridges multiple proof systems** (48+ backends) -2. **Solves cross-prover arbitration** (mathematical identity resolution) -3. **Combines neurosymbolic approaches** (AI + symbolic reasoning) -4. **Provides comprehensive trust infrastructure** (7-stage pipeline) -5. **Manages large-scale vocabulary** (992K+ terms) - -ECHIDNA's USP is **cross-system mathematical object arbitration**, making it the only system capable of determining when theorems from different proof systems represent the same mathematical truth. \ No newline at end of file diff --git a/docs/design/SPARK_ADOPTION_PLAN.adoc b/docs/design/SPARK_ADOPTION_PLAN.adoc new file mode 100644 index 00000000..c153dd68 --- /dev/null +++ b/docs/design/SPARK_ADOPTION_PLAN.adoc @@ -0,0 +1,315 @@ +== SPARK Adoption Plan — Echidna Trust Pipeline + +*Status:* Proposal *Target:* `+src/rust/verification/+` (7 modules, +~2600 LoC) *Filed:* 2026-04-05 *Owner:* Jonathan D.A. Jewell + +=== Why + +The hyperpolymath standard is *SPARK integration by default when +touching Rust/Ada code*. Echidna is a theorem prover; its own +verification layer deciding whether a proof is _trustworthy_ is exactly +the code where formal verification pays off. + +The rest of echidna is not a good SPARK target: - Prover backends (52 +files, ~20K LoC) — shell-out glue, domain is external - HTTP server +(server.rs, interfaces/) — network I/O, dynamic - GNN integration, +agent/, neural.rs — ML scoring, heuristic - CLI, REPL, config — +presentation layer + +The trust pipeline is different: it makes *invariant-heavy judgement +calls* ("`is this proof sound?`", "`what is the confidence level?`", +"`does this certificate check out?`") and those judgements determine +whether downstream consumers trust a result. A bug here turns a theorem +prover into a liar. + +=== Target surface + +`+src/rust/verification/+` — 7 modules, ~2600 LoC. + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Module |LoC |Role |Invariant-heavy? +|`+axiom_tracker.rs+` |487 |Detects dangerous patterns (sorry, Admitted, +believe_me, type-in-type) per prover |*Yes* — soundness gate + +|`+certificates.rs+` |413 |Verifies Alethe/DRAT/LRAT/TSTP certificates +|*Yes* — trust root + +|`+confidence.rs+` |259 |5-level trust hierarchy, confidence aggregation +|*Yes* — ordering invariants + +|`+mutation.rs+` |339 |Mutation testing: perturb spec, check prover +still rejects |Partial — methodology + +|`+pareto.rs+` |247 |Pareto frontier over (time, confidence, +axioms-used) |*Yes* — frontier correctness + +|`+portfolio.rs+` |375 |Cross-checks multiple solvers, flags +disagreement |*Yes* — consensus logic + +|`+statistics.rs+` |464 |Bayesian timeout estimation, statistical +tracking |Partial — estimator properties +|=== + +The five "`Yes`" modules are where SPARK delivers the most value. The +two "`Partial`" modules have mathematical content worth proving but can +wait a cycle. + +=== Toolchain candidates + +Four realistic options exist for verifying Rust. None is perfect; each +involves trade-offs that matter for this codebase. + +==== 1. Creusot (SMT-based, annotated Rust) + +* *What:* Deductive verifier — annotate Rust functions with contracts +(`+#[requires]+`, `+#[ensures]+`) in a Rust-embedded logic. Compiles to +Why3, discharged by Z3/CVC5/Alt-Ergo. +* *Strengths:* +** Closest thing to SPARK/Ada for Rust (SMT-based deductive +verification) +** Echidna already ships Z3, CVC5, Alt-Ergo backends — same solvers +** Function-level reasoning matches the pipeline’s modular structure +** Handles `+Vec+`, `+HashMap+`, iterators — the types actually used +here +* *Weaknesses:* +** Pre-1.0, API changes between releases +** Requires a nightly toolchain pinned to specific versions +** Limited async support — verification is opt-in, not whole-crate +* *Fit score:* 8/10 + +==== 2. Prusti (Viper-based, annotated Rust) + +* *What:* Viper-backed verifier from ETH Zürich. Specification via +`+#[requires]+`/`+#[ensures]+` + separation logic primitives. +* *Strengths:* +** Mature research project, well-documented +** Handles ownership/borrow-checker invariants natively +** Good for memory-safety properties +* *Weaknesses:* +** Viper is less familiar than SMT; debugging requires learning a new +backend +** Weak on algebraic/mathematical properties (what we care about here) +** Slower verification cycle +* *Fit score:* 6/10 + +==== 3. Verus (Z3, full-crate verification) + +* *What:* Whole-crate verifier from Microsoft Research. Annotations live +inside `+verus!{ }+` macro blocks. +* *Strengths:* +** Newest and most actively developed +** Designed for systems code, not toy examples +** Strong linear/ghost state support +** Used in real production systems (StorageSystem verification) +* *Weaknesses:* +** Whole-crate model conflicts with "`annotate only the trust pipeline`" +** Requires significant refactoring to adopt incrementally +** Ghost variables + exec separation is an unfamiliar discipline +* *Fit score:* 7/10 + +==== 4. Kani (model checking) + +* *What:* Bounded model checker (backed by CBMC) — proves absence of +panics, overflow, UB within a bound. +* *Strengths:* +** Property-based testing with exhaustive inputs +** No proof writing — just `+#[kani::proof]+` harnesses +** Catches real bugs quickly +* *Weaknesses:* +** Bounded only — can’t prove functional correctness of non-bounded +inputs +** Not equivalent to SPARK/deductive verification +** Better as a complement than a replacement +* *Fit score (as primary):* 4/10 +* *Fit score (as complement):* 9/10 + +==== Recommendation + +*Adopt Creusot as primary, Kani as complement.* + +* *Creusot* handles the deductive reasoning for invariants, ordering, +and certificate correctness. Aligns with SPARK’s philosophy. Uses +solvers echidna already ships (meta-dogfooding). +* *Kani* runs alongside as a sanity layer — harness every public +function in `+verification/+`, prove-no-panic for realistic input +bounds. +* *Verus* and *Prusti* stay on the watchlist. If Creusot stalls, Verus +is the next pick (higher ceiling, higher adoption cost). + +This is a *dual-tool strategy*, not a monoculture. The echidna trust +pipeline already uses 48 provers; using 2 for its own verification is +coherent. + +=== Adoption sequence + +Five milestones. Each one independently valuable; project can stop at +any milestone and ship what’s done. + +==== M1 — Toolchain bring-up (1 session) + +* Install Creusot + Kani +* Pin Rust toolchain in `+rust-toolchain.toml+` (Creusot needs specific +nightly) +* Add `+[workspace.metadata.creusot]+` config +* Add `+cargo creusot+`, `+cargo kani+` recipes to `+Justfile+` +* CI workflow `+.github/workflows/formal-verification.yml+` +(non-blocking, report-only) +* One trivial verified function as smoke test +(`+confidence::level_ordering_reflexive+`) + +*Success criterion:* `+just verify-trust-pipeline+` runs clean on zero +real functions, one trivial lemma discharges. + +==== M2 — axiom_tracker.rs (1-2 sessions) + +Smallest invariant-heavy module. Candidate properties to prove: + +[arabic] +. *Completeness:* Every `+DangerLevel::Reject+` pattern is flagged +whenever it appears in input (modulo the comment/marker exclusions — +those are encoded as pre-conditions). +. *No false reject:* Patterns classified `+DangerLevel::Safe+` or not in +the pattern set never produce a `+Reject+` finding. +. *Scaffold marker soundness:* Lines containing +`+ECHIDNA_SCAFFOLD_SORRY+` are always skipped, regardless of other sorry +presence. (Just proven by test — replace test with Creusot contract.) +. *Monotonicity:* Adding dangerous patterns to a policy never removes +findings from a prior scan. + +*Success criterion:* 4 of 4 properties verified; existing 9 unit tests +pass unchanged. + +==== M3 — confidence.rs + pareto.rs (2 sessions) + +Ordering invariants are textbook Creusot territory. + +*confidence.rs:* - `+TrustLevel+` enum is totally ordered - +`+combine_confidence(a, b)+` is commutative and associative - +Weakest-link semantics: `+combine(low, high) = low+` - Never promotes +below input floor + +*pareto.rs:* - `+ParetoFrontier+` never contains dominated candidates - +`+add_candidate+` preserves the Pareto property - Frontier is +monotone-shrinking under `+dominates_strictly+` + +*Success criterion:* All ordering properties discharge by SMT within 30s +each. + +==== M4 — portfolio.rs (2-3 sessions) + +Consensus logic for cross-checking. Hardest property to state cleanly. + +* *Agreement:* If all solvers return `+Sat+`, portfolio returns `+Sat+` +* *Disagreement flag:* Mixed results trigger +`+PortfolioResult::Divergent+` +* *Timeout handling:* Single-solver timeout doesn’t produce a `+Proved+` +result +* *Majority vote:* If portfolio policy is `+Majority+`, result matches +strict majority or returns `+Divergent+` + +*Risk:* Portfolio spawns async solver tasks; Creusot is weak on async. +May need to extract pure decision logic into separate functions to +verify. + +*Success criterion:* Pure decision-core properties verified; async +dispatch kept outside the verified boundary and explicitly documented. + +==== M5 — certificates.rs (2-3 sessions) + +Hardest target — certificate verification is a trust root. + +* *Format detection:* `+CertificateFormat::detect+` is injective (no +format ambiguity on well-formed input) +* *Round-trip:* `+parse(serialize(c)) = c+` for each format +* *Rejection:* Malformed certificates never pass verification +* *Audit chain:* Every accepted certificate carries a non-empty axiom +list + +*Risk:* DRAT/LRAT parsing is complex. May need external oracles +(pre-verified parsers) or restrict verification to the *acceptance +logic* rather than the parser itself. + +*Success criterion:* Acceptance logic fully verified; parser stays in a +clearly-marked "`trusted parser`" boundary. + +=== Preconditions + +Before M1: + +* [ ] Nightly Rust toolchain decision (pin via `+rust-toolchain.toml+` — +Creusot requires specific versions) +* [ ] Agreement that non-blocking CI is acceptable for M1-M2 (formal +verification failures don’t break merges until M5 lands) +* [ ] Decision: where do verified proofs live? Options: inline as +contracts (Creusot default) OR separate `+verification/proofs/+` +directory + +Before M5: + +* [ ] Trust boundary documented: which parsers are trusted-not-verified? +* [ ] Round-trip property tests exist (QuickCheck/proptest) as ground +truth + +=== Risks + +[arabic] +. *Toolchain churn.* Creusot is pre-1.0. A breaking release mid-adoption +could force rework. *Mitigation:* pin version, upgrade deliberately. +. *Async boundary.* Several modules use `+tokio+`; Creusot doesn’t +verify async. *Mitigation:* refactor to pure decision cores + async +shells; verify cores only. +. *Over-specification.* Writing contracts for code that already has +tests can feel like duplication. *Mitigation:* pick properties tests +_can’t_ express (ordering, monotonicity, completeness over infinite +input sets). +. *Dogfooding loop.* Echidna’s SMT solvers verify echidna’s +SMT-dispatched proofs. Not circular (different proof obligations), but +worth watching. *Mitigation:* at M5, have Kani _and_ a second SMT solver +cross-check. + +=== Non-goals + +* *Not verifying prover backends* (`+provers/*.rs+`). They shell out to +external tools; the trust gap is in the external tool, not our glue. +* *Not verifying HTTP handlers* or GraphQL/gRPC/REST interfaces. Network +code, dynamic by nature. +* *Not replacing the Agda meta-checker.* Agda verifies 30+ +trust-pipeline properties at the specification level. Creusot verifies +the Rust implementation matches that specification. Complementary, not +substitutable. +* *Not touching the Idris2 ABI.* Already formally verified by its own +type system; `+believe_me+` count is confirmed zero (E1). + +=== Open questions + +* *Q1:* Do we pin Creusot to a stable release or track head? _Proposal: +pinned release, reviewed quarterly._ +* *Q2:* Who reviews verification contracts? They’re code; they need +review too. _Proposal: same PR review process as ordinary Rust._ +* *Q3:* How do we handle failures in CI when SMT can’t discharge within +timeout? _Proposal: non-blocking report at M1-M2, blocking from M3._ +* *Q4:* Is there value in also emitting Coq/Lean proof certificates from +the verified pipeline? I.e. "`here is the proof echidna made, verified +by echidna’s own verifier, checkable in Coq.`" _Open — could be a M6._ + +=== First-action checklist (if approved) + +[arabic] +. ☐ Decide Creusot-vs-Verus (owner: Jonathan) +. ☐ Pin Rust nightly in `+rust-toolchain.toml+` +. ☐ Install + test Creusot: `+cargo install creusot+` +. ☐ Add `+just verify-trust-pipeline+` recipe +. ☐ Write first contract on `+confidence::TrustLevel+` ordering +. ☐ Run, debug, document gotchas, commit +. ☐ Open PR with M1 deliverable + updated this plan + +=== References + +* Creusot: https://github.com/creusot-rs/creusot +* Prusti: https://github.com/viperproject/prusti-dev +* Verus: https://github.com/verus-lang/verus +* Kani: https://github.com/model-checking/kani +* SPARK 2014 Reference Manual: https://docs.adacore.com/spark2014-docs/ +* Existing echidna Agda meta-checker: `+proofs/agda/+`, +`+meta-checker/src/Echidna/AxiomSafety.agda+` diff --git a/docs/design/SPARK_ADOPTION_PLAN.md b/docs/design/SPARK_ADOPTION_PLAN.md deleted file mode 100644 index 8636f786..00000000 --- a/docs/design/SPARK_ADOPTION_PLAN.md +++ /dev/null @@ -1,284 +0,0 @@ - -# SPARK Adoption Plan — Echidna Trust Pipeline - -**Status:** Proposal -**Target:** `src/rust/verification/` (7 modules, ~2600 LoC) -**Filed:** 2026-04-05 -**Owner:** Jonathan D.A. Jewell - -## Why - -The hyperpolymath standard is **SPARK integration by default when touching Rust/Ada -code**. Echidna is a theorem prover; its own verification layer deciding whether -a proof is *trustworthy* is exactly the code where formal verification pays off. - -The rest of echidna is not a good SPARK target: -- Prover backends (52 files, ~20K LoC) — shell-out glue, domain is external -- HTTP server (server.rs, interfaces/) — network I/O, dynamic -- GNN integration, agent/, neural.rs — ML scoring, heuristic -- CLI, REPL, config — presentation layer - -The trust pipeline is different: it makes **invariant-heavy judgement calls** -("is this proof sound?", "what is the confidence level?", "does this certificate -check out?") and those judgements determine whether downstream consumers trust -a result. A bug here turns a theorem prover into a liar. - -## Target surface - -`src/rust/verification/` — 7 modules, ~2600 LoC. - -| Module | LoC | Role | Invariant-heavy? | -|---|---|---|---| -| `axiom_tracker.rs` | 487 | Detects dangerous patterns (sorry, Admitted, believe_me, type-in-type) per prover | **Yes** — soundness gate | -| `certificates.rs` | 413 | Verifies Alethe/DRAT/LRAT/TSTP certificates | **Yes** — trust root | -| `confidence.rs` | 259 | 5-level trust hierarchy, confidence aggregation | **Yes** — ordering invariants | -| `mutation.rs` | 339 | Mutation testing: perturb spec, check prover still rejects | Partial — methodology | -| `pareto.rs` | 247 | Pareto frontier over (time, confidence, axioms-used) | **Yes** — frontier correctness | -| `portfolio.rs` | 375 | Cross-checks multiple solvers, flags disagreement | **Yes** — consensus logic | -| `statistics.rs` | 464 | Bayesian timeout estimation, statistical tracking | Partial — estimator properties | - -The five "Yes" modules are where SPARK delivers the most value. The two "Partial" -modules have mathematical content worth proving but can wait a cycle. - -## Toolchain candidates - -Four realistic options exist for verifying Rust. None is perfect; each involves -trade-offs that matter for this codebase. - -### 1. Creusot (SMT-based, annotated Rust) - -- **What:** Deductive verifier — annotate Rust functions with contracts - (`#[requires]`, `#[ensures]`) in a Rust-embedded logic. Compiles to Why3, - discharged by Z3/CVC5/Alt-Ergo. -- **Strengths:** - - Closest thing to SPARK/Ada for Rust (SMT-based deductive verification) - - Echidna already ships Z3, CVC5, Alt-Ergo backends — same solvers - - Function-level reasoning matches the pipeline's modular structure - - Handles `Vec`, `HashMap`, iterators — the types actually used here -- **Weaknesses:** - - Pre-1.0, API changes between releases - - Requires a nightly toolchain pinned to specific versions - - Limited async support — verification is opt-in, not whole-crate -- **Fit score:** 8/10 - -### 2. Prusti (Viper-based, annotated Rust) - -- **What:** Viper-backed verifier from ETH Zürich. Specification via - `#[requires]`/`#[ensures]` + separation logic primitives. -- **Strengths:** - - Mature research project, well-documented - - Handles ownership/borrow-checker invariants natively - - Good for memory-safety properties -- **Weaknesses:** - - Viper is less familiar than SMT; debugging requires learning a new backend - - Weak on algebraic/mathematical properties (what we care about here) - - Slower verification cycle -- **Fit score:** 6/10 - -### 3. Verus (Z3, full-crate verification) - -- **What:** Whole-crate verifier from Microsoft Research. Annotations live - inside `verus!{ }` macro blocks. -- **Strengths:** - - Newest and most actively developed - - Designed for systems code, not toy examples - - Strong linear/ghost state support - - Used in real production systems (StorageSystem verification) -- **Weaknesses:** - - Whole-crate model conflicts with "annotate only the trust pipeline" - - Requires significant refactoring to adopt incrementally - - Ghost variables + exec separation is an unfamiliar discipline -- **Fit score:** 7/10 - -### 4. Kani (model checking) - -- **What:** Bounded model checker (backed by CBMC) — proves absence of panics, - overflow, UB within a bound. -- **Strengths:** - - Property-based testing with exhaustive inputs - - No proof writing — just `#[kani::proof]` harnesses - - Catches real bugs quickly -- **Weaknesses:** - - Bounded only — can't prove functional correctness of non-bounded inputs - - Not equivalent to SPARK/deductive verification - - Better as a complement than a replacement -- **Fit score (as primary):** 4/10 -- **Fit score (as complement):** 9/10 - -### Recommendation - -**Adopt Creusot as primary, Kani as complement.** - -- **Creusot** handles the deductive reasoning for invariants, ordering, and - certificate correctness. Aligns with SPARK's philosophy. Uses solvers - echidna already ships (meta-dogfooding). -- **Kani** runs alongside as a sanity layer — harness every public function - in `verification/`, prove-no-panic for realistic input bounds. -- **Verus** and **Prusti** stay on the watchlist. If Creusot stalls, Verus is - the next pick (higher ceiling, higher adoption cost). - -This is a **dual-tool strategy**, not a monoculture. The echidna trust -pipeline already uses 48 provers; using 2 for its own verification is -coherent. - -## Adoption sequence - -Five milestones. Each one independently valuable; project can stop at any -milestone and ship what's done. - -### M1 — Toolchain bring-up (1 session) - -- Install Creusot + Kani -- Pin Rust toolchain in `rust-toolchain.toml` (Creusot needs specific nightly) -- Add `[workspace.metadata.creusot]` config -- Add `cargo creusot`, `cargo kani` recipes to `Justfile` -- CI workflow `.github/workflows/formal-verification.yml` (non-blocking, report-only) -- One trivial verified function as smoke test (`confidence::level_ordering_reflexive`) - -**Success criterion:** `just verify-trust-pipeline` runs clean on zero real -functions, one trivial lemma discharges. - -### M2 — axiom_tracker.rs (1-2 sessions) - -Smallest invariant-heavy module. Candidate properties to prove: - -1. **Completeness:** Every `DangerLevel::Reject` pattern is flagged whenever it - appears in input (modulo the comment/marker exclusions — those are encoded - as pre-conditions). -2. **No false reject:** Patterns classified `DangerLevel::Safe` or not in the - pattern set never produce a `Reject` finding. -3. **Scaffold marker soundness:** Lines containing `ECHIDNA_SCAFFOLD_SORRY` are - always skipped, regardless of other sorry presence. (Just proven by test — - replace test with Creusot contract.) -4. **Monotonicity:** Adding dangerous patterns to a policy never removes - findings from a prior scan. - -**Success criterion:** 4 of 4 properties verified; existing 9 unit tests pass -unchanged. - -### M3 — confidence.rs + pareto.rs (2 sessions) - -Ordering invariants are textbook Creusot territory. - -**confidence.rs:** -- `TrustLevel` enum is totally ordered -- `combine_confidence(a, b)` is commutative and associative -- Weakest-link semantics: `combine(low, high) = low` -- Never promotes below input floor - -**pareto.rs:** -- `ParetoFrontier` never contains dominated candidates -- `add_candidate` preserves the Pareto property -- Frontier is monotone-shrinking under `dominates_strictly` - -**Success criterion:** All ordering properties discharge by SMT within 30s each. - -### M4 — portfolio.rs (2-3 sessions) - -Consensus logic for cross-checking. Hardest property to state cleanly. - -- **Agreement:** If all solvers return `Sat`, portfolio returns `Sat` -- **Disagreement flag:** Mixed results trigger `PortfolioResult::Divergent` -- **Timeout handling:** Single-solver timeout doesn't produce a `Proved` result -- **Majority vote:** If portfolio policy is `Majority`, result matches strict - majority or returns `Divergent` - -**Risk:** Portfolio spawns async solver tasks; Creusot is weak on async. May -need to extract pure decision logic into separate functions to verify. - -**Success criterion:** Pure decision-core properties verified; async dispatch -kept outside the verified boundary and explicitly documented. - -### M5 — certificates.rs (2-3 sessions) - -Hardest target — certificate verification is a trust root. - -- **Format detection:** `CertificateFormat::detect` is injective (no format - ambiguity on well-formed input) -- **Round-trip:** `parse(serialize(c)) = c` for each format -- **Rejection:** Malformed certificates never pass verification -- **Audit chain:** Every accepted certificate carries a non-empty axiom list - -**Risk:** DRAT/LRAT parsing is complex. May need external oracles (pre-verified -parsers) or restrict verification to the **acceptance logic** rather than the -parser itself. - -**Success criterion:** Acceptance logic fully verified; parser stays in a -clearly-marked "trusted parser" boundary. - -## Preconditions - -Before M1: - -- [ ] Nightly Rust toolchain decision (pin via `rust-toolchain.toml` — Creusot - requires specific versions) -- [ ] Agreement that non-blocking CI is acceptable for M1-M2 (formal - verification failures don't break merges until M5 lands) -- [ ] Decision: where do verified proofs live? Options: inline as contracts - (Creusot default) OR separate `verification/proofs/` directory - -Before M5: - -- [ ] Trust boundary documented: which parsers are trusted-not-verified? -- [ ] Round-trip property tests exist (QuickCheck/proptest) as ground truth - -## Risks - -1. **Toolchain churn.** Creusot is pre-1.0. A breaking release mid-adoption - could force rework. **Mitigation:** pin version, upgrade deliberately. - -2. **Async boundary.** Several modules use `tokio`; Creusot doesn't verify - async. **Mitigation:** refactor to pure decision cores + async shells; - verify cores only. - -3. **Over-specification.** Writing contracts for code that already has tests - can feel like duplication. **Mitigation:** pick properties tests *can't* - express (ordering, monotonicity, completeness over infinite input sets). - -4. **Dogfooding loop.** Echidna's SMT solvers verify echidna's SMT-dispatched - proofs. Not circular (different proof obligations), but worth watching. - **Mitigation:** at M5, have Kani *and* a second SMT solver cross-check. - -## Non-goals - -- **Not verifying prover backends** (`provers/*.rs`). They shell out to - external tools; the trust gap is in the external tool, not our glue. -- **Not verifying HTTP handlers** or GraphQL/gRPC/REST interfaces. Network - code, dynamic by nature. -- **Not replacing the Agda meta-checker.** Agda verifies 30+ trust-pipeline - properties at the specification level. Creusot verifies the Rust - implementation matches that specification. Complementary, not - substitutable. -- **Not touching the Idris2 ABI.** Already formally verified by its own type - system; `believe_me` count is confirmed zero (E1). - -## Open questions - -- **Q1:** Do we pin Creusot to a stable release or track head? *Proposal: - pinned release, reviewed quarterly.* -- **Q2:** Who reviews verification contracts? They're code; they need - review too. *Proposal: same PR review process as ordinary Rust.* -- **Q3:** How do we handle failures in CI when SMT can't discharge within - timeout? *Proposal: non-blocking report at M1-M2, blocking from M3.* -- **Q4:** Is there value in also emitting Coq/Lean proof certificates from - the verified pipeline? I.e. "here is the proof echidna made, verified by - echidna's own verifier, checkable in Coq." *Open — could be a M6.* - -## First-action checklist (if approved) - -1. [ ] Decide Creusot-vs-Verus (owner: Jonathan) -2. [ ] Pin Rust nightly in `rust-toolchain.toml` -3. [ ] Install + test Creusot: `cargo install creusot` -4. [ ] Add `just verify-trust-pipeline` recipe -5. [ ] Write first contract on `confidence::TrustLevel` ordering -6. [ ] Run, debug, document gotchas, commit -7. [ ] Open PR with M1 deliverable + updated this plan - -## References - -- Creusot: https://github.com/creusot-rs/creusot -- Prusti: https://github.com/viperproject/prusti-dev -- Verus: https://github.com/verus-lang/verus -- Kani: https://github.com/model-checking/kani -- SPARK 2014 Reference Manual: https://docs.adacore.com/spark2014-docs/ -- Existing echidna Agda meta-checker: `proofs/agda/`, `meta-checker/src/Echidna/AxiomSafety.agda` diff --git a/docs/design/TYPING_CAPABILITIES_COMPARISON.adoc b/docs/design/TYPING_CAPABILITIES_COMPARISON.adoc new file mode 100644 index 00000000..125a6926 --- /dev/null +++ b/docs/design/TYPING_CAPABILITIES_COMPARISON.adoc @@ -0,0 +1,292 @@ +== ECHIDNA Typing Capabilities vs Advanced Type Systems + +=== Executive Summary + +ECHIDNA is *not directly comparable* to Agda, Idris, and similar +advanced type systems because we operate at a *meta-level* above +individual proof systems. While Agda and Idris focus on *intra-system* +typing within their own type theories, ECHIDNA focuses on *inter-system* +typing and type-aware proof arbitration across heterogeneous systems. + +=== 1. What ECHIDNA Supports + +==== Meta-Level Type Awareness + +ECHIDNA supports *type-aware operations across multiple proof systems*: + +* *Type System Detection*: Identifies the type system of each prover +backend +* *Type Information Extraction*: Extracts type information from proofs +across systems +* *Type-Aware Dispatch*: Routes proofs based on type system requirements +* *Cross-System Type Mapping*: Maps equivalent types across different +systems +* *Type-Safe Proof Exchange*: Ensures type safety in OpenTheory/Dedukti +exchange + +==== Supported Type Systems (via Backend Provers) + +ECHIDNA can *leverage* these type systems through its backends: + +[width="100%",cols="25%,75%",options="header",] +|=== +|Prover |Type System Supported +|Agda |Full dependent types, inductive types, coinductive types + +|Idris 2 |Dependent types, linear types, quantitative types, effect +types + +|Coq |Calculus of Inductive Constructions (CIC), dependent types + +|Lean 4 |Dependent types, universe polymorphism, quotient types + +|Isabelle/HOL |Simple types, type classes, higher-order logic + +|F* |Dependent types, refinement types, effect types + +|Twelf |LF (Logical Framework), dependent types + +|Nuprl |Computational Type Theory (CTT) + +|Minlog |Minimal logic with dependent types +|=== + +==== Type-Aware Features + +* *Type System Classification*: Categorizes provers by type system +capabilities +* *Type Safety Monitoring*: Tracks type safety violations across provers +* *Type-Aware Confidence Scoring*: Adjusts trust levels based on type +system strength +* *Type Information Preservation*: Maintains type info in proof exchange +formats + +=== 2. What ECHIDNA Does NOT Support + +==== Intra-System Advanced Typing + +ECHIDNA does *not implement* its own advanced type system: + +* *No Native Dependent Types*: ECHIDNA doesn’t have its own dependent +type system +* *No Native Linear Types*: No built-in linear type system +* *No Native Effect Types*: No native effect system +* *No Native Refinement Types*: No built-in refinement type checking +* *No Native Universe Polymorphism*: No native universe hierarchy + +==== Advanced Type Features Missing + +* *No Type Inference Engine*: Relies on backend provers for type +inference +* *No Type Checking Algorithm*: Uses backend type checkers +* *No Unification Algorithm*: Relies on backend unification +* *No Elaboration*: No native elaboration from surface to core language +* *No Meta-Programming*: No native meta-programming facilities + +=== 3. Comparison with Agda-Class Systems + +==== Agda Typing Capabilities + +[width="100%",cols="38%,25%,37%",options="header",] +|=== +|Feature |Agda |ECHIDNA +|Dependent types |✅ Native |❌ Native, ✅ via Agda backend + +|Inductive types |✅ Native |❌ Native, ✅ via Agda backend + +|Coinductive types |✅ Native |❌ Native, ✅ via Agda backend + +|Universe polymorphism |✅ Native |❌ Native, ✅ via Agda backend + +|Pattern matching |✅ Native |❌ Native, ✅ via Agda backend + +|Meta-programming |✅ Native |❌ Native, ❌ via backend + +|Unicode syntax |✅ Native |❌ Native, ✅ via Agda backend + +|Type inference |✅ Native |❌ Native, ✅ via Agda backend + +|Elaboration |✅ Native |❌ Native, ✅ via Agda backend + +|Cubical extension |✅ (Cubical Agda) |❌ Native, ✅ via Cubical Agda +backend +|=== + +==== Idris 2 Typing Capabilities + +[cols=",,",options="header",] +|=== +|Feature |Idris 2 |ECHIDNA +|Dependent types |✅ Native |❌ Native, ✅ via Idris 2 backend +|Linear types |✅ Native |❌ Native, ✅ via Idris 2 backend +|Quantitative types |✅ Native |❌ Native, ✅ via Idris 2 backend +|Effect types |✅ Native |❌ Native, ✅ via Idris 2 backend +|Type classes |✅ Native |❌ Native, ✅ via Idris 2 backend +|Interfaces |✅ Native |❌ Native, ✅ via Idris 2 backend +|Elaboration |✅ Native |❌ Native, ✅ via Idris 2 backend +|Meta-programming |✅ Native |❌ Native, ❌ via backend +|Resource tracking |✅ Native |❌ Native, ✅ via Idris 2 backend +|=== + +==== Coq Typing Capabilities + +[width="100%",cols="40%,21%,39%",options="header",] +|=== +|Feature |Coq |ECHIDNA +|CIC (Calculus of Inductive Constructions) |✅ Native |❌ Native, ✅ via +Coq backend + +|Inductive types |✅ Native |❌ Native, ✅ via Coq backend + +|Coinductive types |✅ Native |❌ Native, ✅ via Coq backend + +|Universe polymorphism |✅ Native |❌ Native, ✅ via Coq backend + +|Type classes |✅ Native |❌ Native, ✅ via Coq backend + +|Canonical structures |✅ Native |❌ Native, ✅ via Coq backend + +|Module system |✅ Native |❌ Native, ✅ via Coq backend + +|Extraction |✅ Native |❌ Native, ✅ via Coq backend + +|SSReflect |✅ Native |❌ Native, ✅ via Coq backend +|=== + +=== 4. Why ECHIDNA is Not Directly Comparable + +==== Different Levels of Operation + +.... +Agda/Idris/Coq Level: [Surface Language] → [Elaboration] → [Core Language] → [Type Checking] → [Proof Checking] + ↑ +ECHIDNA Level: [Proof System A] ↔ [Cross-System Arbitration] ↔ [Proof System B] ↔ [Proof System C] + ↑ + [Type System Detection] [Type-Aware Dispatch] [Cross-System Mapping] +.... + +==== ECHIDNA’s Meta-Level Role + +ECHIDNA operates *above* individual type systems: + +[arabic] +. *Type System Orchestration*: Manages multiple type systems +simultaneously +. *Cross-System Type Mapping*: Finds equivalences between different type +theories +. *Type-Aware Proof Routing*: Directs proofs to appropriate type systems +. *Type Safety Monitoring*: Ensures type safety across heterogeneous +systems +. *Type Information Preservation*: Maintains type info in cross-system +exchange + +==== The Comparison Fallacy + +Comparing ECHIDNA directly to Agda/Idris on typing capabilities is like +comparing: + +* *An orchestra conductor* (ECHIDNA) vs *a single violinist* (Agda) +* *A multi-lingual translator* (ECHIDNA) vs *a native speaker* (Idris) +* *A proof system router* (ECHIDNA) vs *a type checker* (Coq) + +=== 5. ECHIDNA’s Unique Typing Value Proposition + +==== What We Provide That Single Systems Cannot + +* *Cross-System Type Arbitration*: Determine when types from different +systems are equivalent +* *Multi-Type-System Proof Routing*: Send proofs to the most appropriate +type system +* *Heterogeneous Type Safety*: Ensure type safety across mixed-system +proofs +* *Type System Interoperability*: Bridge between different type theories +* *Meta-Level Type Awareness*: Understand and work with multiple type +systems simultaneously + +==== Our Typing Advantage + +.... +Single System (Agda/Idris/Coq): + [One Type System] → [Type Checking] → [Proof Checking] → [Theorems] + +ECHIDNA (Meta-System): + [Type System A] ↔ [Type System B] ↔ [Type System C] ↔ ... + ↓ ↓ ↓ + [Cross-System] → [Type Arbitration] → [Proof Equivalence] → [Mathematical Truth] +.... + +=== 6. When to Use ECHIDNA vs Advanced Type Systems + +==== Use Agda/Idris/Coq When You Need: + +* *Intra-system formalization*: Developing mathematics within one type +system +* *Dependent type programming*: Writing certified programs in a single +system +* *Advanced type features*: Using linear types, effect types, refinement +types +* *Meta-programming*: Writing tactics or elaboration functions +* *Extraction*: Extracting certified programs to target languages + +==== Use ECHIDNA When You Need: + +* *Cross-system proof arbitration*: Determining when theorems from +different systems are equivalent +* *Multi-system proof routing*: Finding the best prover for a given +proof obligation +* *Heterogeneous type safety*: Ensuring type safety across mixed-system +proofs +* *Type system interoperability*: Bridging between different +mathematical foundations +* *Meta-level type analysis*: Understanding type information across +multiple systems + +=== 7. Future Typing Capabilities Roadmap + +==== Planned Type-Aware Enhancements + +* *Cross-System Type Equivalence Detection*: AI-powered type equivalence +finding +* *Type System Interoperability Hub*: Central registry of type system +mappings +* *Meta-Level Type Inference*: Infer type relationships across systems +* *Heterogeneous Type Checking*: Validate type safety in mixed-system +proofs +* *Type-Aware Confidence Scoring*: Adjust trust levels based on type +system strength + +==== Research Directions + +* *Universal Type Theory Mapping*: Find correspondences between +different type theories +* *Cross-System Type Preservation*: Ensure type safety in proof exchange +* *Meta-Level Type Safety Proofs*: Formal proofs about cross-system type +safety +* *Type System Classification*: Categorize provers by type system +capabilities +* *Type-Aware Proof Search*: Use type information to guide cross-system +proof search + +=== 8. Conclusion + +ECHIDNA is *not comparable* to Agda, Idris, and similar systems on +advanced typing because: + +[arabic] +. *We operate at a meta-level* above individual type systems +. *We orchestrate multiple type systems* rather than implementing our +own +. *We focus on cross-system type arbitration* rather than intra-system +type checking +. *Our value is in heterogeneity* while theirs is in homogeneity +. *We enable interoperability* while they enable expressivity + +*ECHIDNA’s typing strength* lies in our ability to: - Work with +*multiple advanced type systems simultaneously* - Find *equivalences +between different type theories* - Route proofs to *the most appropriate +type system* - Ensure *type safety across heterogeneous systems* - +Preserve *type information in cross-system exchange* + +While Agda and Idris provide *deep typing within one system*, ECHIDNA +provides *broad typing across many systems* — a fundamentally different +and complementary capability. diff --git a/docs/design/TYPING_CAPABILITIES_COMPARISON.md b/docs/design/TYPING_CAPABILITIES_COMPARISON.md deleted file mode 100644 index 6922d61b..00000000 --- a/docs/design/TYPING_CAPABILITIES_COMPARISON.md +++ /dev/null @@ -1,212 +0,0 @@ -# ECHIDNA Typing Capabilities vs Advanced Type Systems - -## Executive Summary - -ECHIDNA is **not directly comparable** to Agda, Idris, and similar advanced type systems because we operate at a **meta-level** above individual proof systems. While Agda and Idris focus on **intra-system** typing within their own type theories, ECHIDNA focuses on **inter-system** typing and type-aware proof arbitration across heterogeneous systems. - -## 1. What ECHIDNA Supports - -### Meta-Level Type Awareness - -ECHIDNA supports **type-aware operations across multiple proof systems**: - -* **Type System Detection**: Identifies the type system of each prover backend -* **Type Information Extraction**: Extracts type information from proofs across systems -* **Type-Aware Dispatch**: Routes proofs based on type system requirements -* **Cross-System Type Mapping**: Maps equivalent types across different systems -* **Type-Safe Proof Exchange**: Ensures type safety in OpenTheory/Dedukti exchange - -### Supported Type Systems (via Backend Provers) - -ECHIDNA can **leverage** these type systems through its backends: - -| Prover | Type System Supported | -|--------|------------------------| -| Agda | Full dependent types, inductive types, coinductive types | -| Idris 2 | Dependent types, linear types, quantitative types, effect types | -| Coq | Calculus of Inductive Constructions (CIC), dependent types | -| Lean 4 | Dependent types, universe polymorphism, quotient types | -| Isabelle/HOL | Simple types, type classes, higher-order logic | -| F* | Dependent types, refinement types, effect types | -| Twelf | LF (Logical Framework), dependent types | -| Nuprl | Computational Type Theory (CTT) | -| Minlog | Minimal logic with dependent types | - -### Type-Aware Features - -* **Type System Classification**: Categorizes provers by type system capabilities -* **Type Safety Monitoring**: Tracks type safety violations across provers -* **Type-Aware Confidence Scoring**: Adjusts trust levels based on type system strength -* **Type Information Preservation**: Maintains type info in proof exchange formats - -## 2. What ECHIDNA Does NOT Support - -### Intra-System Advanced Typing - -ECHIDNA does **not implement** its own advanced type system: - -* **No Native Dependent Types**: ECHIDNA doesn't have its own dependent type system -* **No Native Linear Types**: No built-in linear type system -* **No Native Effect Types**: No native effect system -* **No Native Refinement Types**: No built-in refinement type checking -* **No Native Universe Polymorphism**: No native universe hierarchy - -### Advanced Type Features Missing - -* **No Type Inference Engine**: Relies on backend provers for type inference -* **No Type Checking Algorithm**: Uses backend type checkers -* **No Unification Algorithm**: Relies on backend unification -* **No Elaboration**: No native elaboration from surface to core language -* **No Meta-Programming**: No native meta-programming facilities - -## 3. Comparison with Agda-Class Systems - -### Agda Typing Capabilities - -| Feature | Agda | ECHIDNA | -|---------|------|---------| -| Dependent types | ✅ Native | ❌ Native, ✅ via Agda backend | -| Inductive types | ✅ Native | ❌ Native, ✅ via Agda backend | -| Coinductive types | ✅ Native | ❌ Native, ✅ via Agda backend | -| Universe polymorphism | ✅ Native | ❌ Native, ✅ via Agda backend | -| Pattern matching | ✅ Native | ❌ Native, ✅ via Agda backend | -| Meta-programming | ✅ Native | ❌ Native, ❌ via backend | -| Unicode syntax | ✅ Native | ❌ Native, ✅ via Agda backend | -| Type inference | ✅ Native | ❌ Native, ✅ via Agda backend | -| Elaboration | ✅ Native | ❌ Native, ✅ via Agda backend | -| Cubical extension | ✅ (Cubical Agda) | ❌ Native, ✅ via Cubical Agda backend | - -### Idris 2 Typing Capabilities - -| Feature | Idris 2 | ECHIDNA | -|---------|---------|---------| -| Dependent types | ✅ Native | ❌ Native, ✅ via Idris 2 backend | -| Linear types | ✅ Native | ❌ Native, ✅ via Idris 2 backend | -| Quantitative types | ✅ Native | ❌ Native, ✅ via Idris 2 backend | -| Effect types | ✅ Native | ❌ Native, ✅ via Idris 2 backend | -| Type classes | ✅ Native | ❌ Native, ✅ via Idris 2 backend | -| Interfaces | ✅ Native | ❌ Native, ✅ via Idris 2 backend | -| Elaboration | ✅ Native | ❌ Native, ✅ via Idris 2 backend | -| Meta-programming | ✅ Native | ❌ Native, ❌ via backend | -| Resource tracking | ✅ Native | ❌ Native, ✅ via Idris 2 backend | - -### Coq Typing Capabilities - -| Feature | Coq | ECHIDNA | -|---------|-----|---------| -| CIC (Calculus of Inductive Constructions) | ✅ Native | ❌ Native, ✅ via Coq backend | -| Inductive types | ✅ Native | ❌ Native, ✅ via Coq backend | -| Coinductive types | ✅ Native | ❌ Native, ✅ via Coq backend | -| Universe polymorphism | ✅ Native | ❌ Native, ✅ via Coq backend | -| Type classes | ✅ Native | ❌ Native, ✅ via Coq backend | -| Canonical structures | ✅ Native | ❌ Native, ✅ via Coq backend | -| Module system | ✅ Native | ❌ Native, ✅ via Coq backend | -| Extraction | ✅ Native | ❌ Native, ✅ via Coq backend | -| SSReflect | ✅ Native | ❌ Native, ✅ via Coq backend | - -## 4. Why ECHIDNA is Not Directly Comparable - -### Different Levels of Operation - -``` -Agda/Idris/Coq Level: [Surface Language] → [Elaboration] → [Core Language] → [Type Checking] → [Proof Checking] - ↑ -ECHIDNA Level: [Proof System A] ↔ [Cross-System Arbitration] ↔ [Proof System B] ↔ [Proof System C] - ↑ - [Type System Detection] [Type-Aware Dispatch] [Cross-System Mapping] -``` - -### ECHIDNA's Meta-Level Role - -ECHIDNA operates **above** individual type systems: - -1. **Type System Orchestration**: Manages multiple type systems simultaneously -2. **Cross-System Type Mapping**: Finds equivalences between different type theories -3. **Type-Aware Proof Routing**: Directs proofs to appropriate type systems -4. **Type Safety Monitoring**: Ensures type safety across heterogeneous systems -5. **Type Information Preservation**: Maintains type info in cross-system exchange - -### The Comparison Fallacy - -Comparing ECHIDNA directly to Agda/Idris on typing capabilities is like comparing: - -- **An orchestra conductor** (ECHIDNA) vs **a single violinist** (Agda) -- **A multi-lingual translator** (ECHIDNA) vs **a native speaker** (Idris) -- **A proof system router** (ECHIDNA) vs **a type checker** (Coq) - -## 5. ECHIDNA's Unique Typing Value Proposition - -### What We Provide That Single Systems Cannot - -* **Cross-System Type Arbitration**: Determine when types from different systems are equivalent -* **Multi-Type-System Proof Routing**: Send proofs to the most appropriate type system -* **Heterogeneous Type Safety**: Ensure type safety across mixed-system proofs -* **Type System Interoperability**: Bridge between different type theories -* **Meta-Level Type Awareness**: Understand and work with multiple type systems simultaneously - -### Our Typing Advantage - -``` -Single System (Agda/Idris/Coq): - [One Type System] → [Type Checking] → [Proof Checking] → [Theorems] - -ECHIDNA (Meta-System): - [Type System A] ↔ [Type System B] ↔ [Type System C] ↔ ... - ↓ ↓ ↓ - [Cross-System] → [Type Arbitration] → [Proof Equivalence] → [Mathematical Truth] -``` - -## 6. When to Use ECHIDNA vs Advanced Type Systems - -### Use Agda/Idris/Coq When You Need: - -* **Intra-system formalization**: Developing mathematics within one type system -* **Dependent type programming**: Writing certified programs in a single system -* **Advanced type features**: Using linear types, effect types, refinement types -* **Meta-programming**: Writing tactics or elaboration functions -* **Extraction**: Extracting certified programs to target languages - -### Use ECHIDNA When You Need: - -* **Cross-system proof arbitration**: Determining when theorems from different systems are equivalent -* **Multi-system proof routing**: Finding the best prover for a given proof obligation -* **Heterogeneous type safety**: Ensuring type safety across mixed-system proofs -* **Type system interoperability**: Bridging between different mathematical foundations -* **Meta-level type analysis**: Understanding type information across multiple systems - -## 7. Future Typing Capabilities Roadmap - -### Planned Type-Aware Enhancements - -* **Cross-System Type Equivalence Detection**: AI-powered type equivalence finding -* **Type System Interoperability Hub**: Central registry of type system mappings -* **Meta-Level Type Inference**: Infer type relationships across systems -* **Heterogeneous Type Checking**: Validate type safety in mixed-system proofs -* **Type-Aware Confidence Scoring**: Adjust trust levels based on type system strength - -### Research Directions - -* **Universal Type Theory Mapping**: Find correspondences between different type theories -* **Cross-System Type Preservation**: Ensure type safety in proof exchange -* **Meta-Level Type Safety Proofs**: Formal proofs about cross-system type safety -* **Type System Classification**: Categorize provers by type system capabilities -* **Type-Aware Proof Search**: Use type information to guide cross-system proof search - -## 8. Conclusion - -ECHIDNA is **not comparable** to Agda, Idris, and similar systems on advanced typing because: - -1. **We operate at a meta-level** above individual type systems -2. **We orchestrate multiple type systems** rather than implementing our own -3. **We focus on cross-system type arbitration** rather than intra-system type checking -4. **Our value is in heterogeneity** while theirs is in homogeneity -5. **We enable interoperability** while they enable expressivity - -**ECHIDNA's typing strength** lies in our ability to: -- Work with **multiple advanced type systems simultaneously** -- Find **equivalences between different type theories** -- Route proofs to **the most appropriate type system** -- Ensure **type safety across heterogeneous systems** -- Preserve **type information in cross-system exchange** - -While Agda and Idris provide **deep typing within one system**, ECHIDNA provides **broad typing across many systems** — a fundamentally different and complementary capability. \ No newline at end of file diff --git a/docs/governance/JUST_AND_MUST_FRAMEWORK.md b/docs/governance/JUST_AND_MUST_FRAMEWORK.adoc similarity index 78% rename from docs/governance/JUST_AND_MUST_FRAMEWORK.md rename to docs/governance/JUST_AND_MUST_FRAMEWORK.adoc index 96e94de2..b7d9c663 100644 --- a/docs/governance/JUST_AND_MUST_FRAMEWORK.md +++ b/docs/governance/JUST_AND_MUST_FRAMEWORK.adoc @@ -1,40 +1,38 @@ -# ECHIDNA: Just and Must Framework +== ECHIDNA: Just and Must Framework -**Status**: Design Standard -**Date**: 2026-01-29 -**Purpose**: Standardize entry paths and stabilize design expectations +*Status*: Design Standard *Date*: 2026-01-29 *Purpose*: Standardize +entry paths and stabilize design expectations ---- +''''' -## Philosophy +=== Philosophy -**Just** = Common entry point for all developers (Justfile) -**Must** = Requirements that MUST be met before acceptance (validation system) +*Just* = Common entry point for all developers (Justfile) *Must* = +Requirements that MUST be met before acceptance (validation system) -Together, these create a **stable, predictable development experience**. +Together, these create a *stable, predictable development experience*. ---- +''''' -## Part 1: Just (Common Entry Point) +=== Part 1: Just (Common Entry Point) -### Justfile as Primary Build System +==== Justfile as Primary Build System -**Why Justfile?** -- ✅ Cross-platform (works on Linux, macOS, Windows) -- ✅ Simple syntax (easier than Make) -- ✅ Self-documenting (`just --list`) -- ✅ Composable recipes -- ✅ No magic variables or implicit rules +*Why Justfile?* - ✅ Cross-platform (works on Linux, macOS, Windows) - +✅ Simple syntax (easier than Make) - ✅ Self-documenting +(`+just --list+`) - ✅ Composable recipes - ✅ No magic variables or +implicit rules -**Rule**: **ALL build commands go through Justfile** +*Rule*: *ALL build commands go through Justfile* ---- +''''' -### Standard Justfile Recipes +==== Standard Justfile Recipes -**Justfile** (complete, comprehensive): +*Justfile* (complete, comprehensive): -```justfile +[source,justfile] +---- # SPDX-License-Identifier: CC-BY-SA-4.0 # ECHIDNA Standard Build System @@ -356,19 +354,20 @@ dev-cycle: @just build-dev @just test @just check-lint -``` +---- ---- +''''' -## Part 2: Must (Requirements Validation) +=== Part 2: Must (Requirements Validation) -### Must Requirements System +==== Must Requirements System -**Concept**: Before any PR is merged, it MUST pass validation +*Concept*: Before any PR is merged, it MUST pass validation -**Implementation**: `scripts/must_validate.sh` +*Implementation*: `+scripts/must_validate.sh+` -```bash +[source,bash] +---- #!/usr/bin/env bash # SPDX-License-Identifier: CC-BY-SA-4.0 # Must Validation System @@ -453,34 +452,47 @@ else echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" exit 1 fi -``` - -### Must Requirements List - -| # | Requirement | Check | Why | -|---|-------------|-------|-----| -| 1 | **Code builds** | `cargo build` | Broken builds block everyone | -| 2 | **All tests pass** | `cargo test` | Regressions must not merge | -| 3 | **No Clippy warnings** | `cargo clippy -D warnings` | Code quality standards | -| 4 | **Code formatted** | `cargo fmt --check` | Consistent style | -| 5 | **SPDX headers** | `reuse lint` | Legal compliance | -| 6 | **No security issues** | `cargo audit` | Vulnerability prevention | -| 7 | **Docs build** | `cargo doc` | Documentation coverage | -| 8 | **Benchmarks compile** | `cargo bench --no-run` | Performance tracking | -| 9 | **Property tests pass** | Property-based testing | Invariant checking | -| 10 | **Integration tests pass** | End-to-end validation | Full stack works | +---- ---- +==== Must Requirements List -## Part 3: Developer Onboarding +[width="100%",cols="12%,46%,25%,17%",options="header",] +|=== +|# |Requirement |Check |Why +|1 |*Code builds* |`+cargo build+` |Broken builds block everyone -### Day 1: New Developer Experience +|2 |*All tests pass* |`+cargo test+` |Regressions must not merge -**Goal**: Developer productive in < 30 minutes +|3 |*No Clippy warnings* |`+cargo clippy -D warnings+` |Code quality +standards -**Onboarding checklist**: +|4 |*Code formatted* |`+cargo fmt --check+` |Consistent style -```bash +|5 |*SPDX headers* |`+reuse lint+` |Legal compliance + +|6 |*No security issues* |`+cargo audit+` |Vulnerability prevention + +|7 |*Docs build* |`+cargo doc+` |Documentation coverage + +|8 |*Benchmarks compile* |`+cargo bench --no-run+` |Performance tracking + +|9 |*Property tests pass* |Property-based testing |Invariant checking + +|10 |*Integration tests pass* |End-to-end validation |Full stack works +|=== + +''''' + +=== Part 3: Developer Onboarding + +==== Day 1: New Developer Experience + +*Goal*: Developer productive in < 30 minutes + +*Onboarding checklist*: + +[source,bash] +---- # 1. Clone repo git clone https://github.com/hyperpolymath/echidna.git cd echidna @@ -498,10 +510,11 @@ just test just dev # Done! Ready to contribute. -``` +---- + +*Expected output*: -**Expected output**: -``` +.... $ just build Building ECHIDNA core... Compiling echidna v1.3.1 @@ -518,17 +531,18 @@ Checking SPDX headers... ✓ Running security audit... ✓ Checking types... ✓ ✓ All quality checks passed! -``` +.... ---- +''''' -## Part 4: CI/CD Integration +=== Part 4: CI/CD Integration -### GitHub Actions Using Just + Must +==== GitHub Actions Using Just + Must -**.github/workflows/ci.yml**: +*.github/workflows/ci.yml*: -```yaml +[source,yaml] +---- name: CI on: [push, pull_request] @@ -556,19 +570,20 @@ jobs: run: just must # If MUST fails, PR cannot merge -``` +---- -**Result**: PRs cannot merge unless `just must` passes +*Result*: PRs cannot merge unless `+just must+` passes ---- +''''' -## Part 5: Pre-Commit Hooks +=== Part 5: Pre-Commit Hooks -### Git Hooks Using Just +==== Git Hooks Using Just -**.git/hooks/pre-commit**: +*.git/hooks/pre-commit*: -```bash +[source,bash] +---- #!/usr/bin/env bash # SPDX-License-Identifier: CC-BY-SA-4.0 # Pre-commit hook: Run quick validation @@ -582,25 +597,28 @@ just check-format just check-lint echo "✓ Pre-commit validation passed" -``` +---- -**Installation**: -```bash +*Installation*: + +[source,bash] +---- # Setup hooks just setup-hooks # Or manually cp scripts/pre-commit.sh .git/hooks/pre-commit chmod +x .git/hooks/pre-commit -``` +---- ---- +''''' -## Part 6: CONTRIBUTING.md Integration +=== Part 6: CONTRIBUTING.md Integration -**CONTRIBUTING.md** (excerpt): +*CONTRIBUTING.md* (excerpt): -```markdown +[source,markdown] +---- # Contributing to ECHIDNA ## Quick Start @@ -620,45 +638,52 @@ just check # Before commit just must -``` +---- -## Requirements (MUST System) +=== Requirements (MUST System) Before your PR can merge, it MUST satisfy: -1. ✓ Code builds -2. ✓ All tests pass -3. ✓ No Clippy warnings -4. ✓ Code formatted -5. ✓ SPDX headers -6. ✓ No security issues -7. ✓ Docs build -8. ✓ Benchmarks compile -9. ✓ Property tests pass -10. ✓ Integration tests pass +[arabic] +. ✓ Code builds +. ✓ All tests pass +. ✓ No Clippy warnings +. ✓ Code formatted +. ✓ SPDX headers +. ✓ No security issues +. ✓ Docs build +. ✓ Benchmarks compile +. ✓ Property tests pass +. ✓ Integration tests pass Check requirements: -```bash + +[source,bash] +---- just must -``` +---- -## I don't know Justfiles +=== I don’t know Justfiles No problem! Just treats it like a better Makefile: -```bash +[source,bash] +---- # Instead of: make build # Use: just build -``` +---- See available commands: -```bash + +[source,bash] +---- just --list -``` -``` +---- + +.... --- @@ -702,102 +727,80 @@ Every module MUST have: /// let result = strategy.search(goal, provers, timeout)?; /// ``` pub struct SequentialSearch; -``` +.... -**Validation**: -```bash +*Validation*: + +[source,bash] +---- # Check docs coverage just check-docs-coverage # Must have 100% public API documented cargo doc --no-deps 2>&1 | grep "warning: missing documentation" -``` +---- ---- +''''' -## Part 8: Stabilization Checklist +=== Part 8: Stabilization Checklist -### Design Stabilization Goals +==== Design Stabilization Goals Before v2.0, we MUST stabilize: -**Architecture** ✓ -- [x] 12 prover backends -- [x] Trait-based abstractions -- [x] Chapel as optional plugin -- [x] ML/neural integration - -**Build System** ✓ -- [x] Justfile as primary interface -- [x] Chapel optional (feature flag) -- [x] Cross-platform support - -**Code Quality** ✓ -- [x] MUST validation system -- [x] Property-based testing -- [x] Benchmarking infrastructure -- [x] Security auditing - -**Documentation** ✓ -- [x] API documentation -- [x] Tutorial/quickstart -- [x] Contribution guidelines -- [x] Chapel separation docs - -**Testing** ✓ -- [x] 137+ unit tests -- [x] 38 integration tests -- [x] Property tests -- [x] Benchmark suite +*Architecture* ✓ - [x] 12 prover backends - [x] Trait-based abstractions +- [x] Chapel as optional plugin - [x] ML/neural integration ---- +*Build System* ✓ - [x] Justfile as primary interface - [x] Chapel +optional (feature flag) - [x] Cross-platform support -## Part 9: Version Stability Promise +*Code Quality* ✓ - [x] MUST validation system - [x] Property-based +testing - [x] Benchmarking infrastructure - [x] Security auditing -### Semantic Versioning + Must +*Documentation* ✓ - [x] API documentation - [x] Tutorial/quickstart - +[x] Contribution guidelines - [x] Chapel separation docs -**1.x.x** = Current (experimental) -- MUST requirements recommended but not enforced -- Breaking changes allowed with notice +*Testing* ✓ - [x] 137+ unit tests - [x] 38 integration tests - [x] +Property tests - [x] Benchmark suite -**2.0.0** = Stable release -- MUST requirements ENFORCED in CI -- No breaking changes without major version bump -- API stability guaranteed +''''' -**2.x.x** = Stable minor releases -- Only backwards-compatible changes -- MUST requirements always enforced +=== Part 9: Version Stability Promise ---- +==== Semantic Versioning + Must -## Conclusion +*1.x.x* = Current (experimental) - MUST requirements recommended but not +enforced - Breaking changes allowed with notice -**Just + Must = Predictable Development** +*2.0.0* = Stable release - MUST requirements ENFORCED in CI - No +breaking changes without major version bump - API stability guaranteed -**Just (Justfile)**: -- ✅ Common entry point for all commands -- ✅ Self-documenting (`just --list`) -- ✅ Cross-platform -- ✅ Composable recipes +*2.x.x* = Stable minor releases - Only backwards-compatible changes - +MUST requirements always enforced -**Must (Validation System)**: -- ✅ Clear requirements before merge -- ✅ Automated checking -- ✅ Prevents regressions -- ✅ Enforced in CI/CD +''''' -**Together**: -- New developers productive in < 30 minutes -- Code quality maintained automatically -- Breaking changes caught before merge -- Stable foundation for growth +=== Conclusion ---- +*Just + Must = Predictable Development* -**Developer Experience**: +*Just (Justfile)*: - ✅ Common entry point for all commands - ✅ +Self-documenting (`+just --list+`) - ✅ Cross-platform - ✅ Composable +recipes -```bash +*Must (Validation System)*: - ✅ Clear requirements before merge - ✅ +Automated checking - ✅ Prevents regressions - ✅ Enforced in CI/CD + +*Together*: - New developers productive in < 30 minutes - Code quality +maintained automatically - Breaking changes caught before merge - Stable +foundation for growth + +''''' + +*Developer Experience*: + +[source,bash] +---- # Day 1 $ git clone echidna && cd echidna $ just build @@ -812,18 +815,19 @@ $ just check $ just must $ git commit && git push # ✓ PR ready! -``` +---- -**Maintainer Experience**: +*Maintainer Experience*: -```bash +[source,bash] +---- # Review PR $ gh pr checkout 123 $ just must # ✓ All requirements met - safe to merge -``` +---- ---- +''''' -*ECHIDNA Just and Must Framework* -*Co-Authored-By: Claude Sonnet 4.5 * +_ECHIDNA Just and Must Framework_ _Co-Authored-By: Claude Sonnet 4.5 +noreply@anthropic.com_ diff --git a/docs/governance/TRUST_AND_VALIDATION_FRAMEWORK.md b/docs/governance/TRUST_AND_VALIDATION_FRAMEWORK.adoc similarity index 74% rename from docs/governance/TRUST_AND_VALIDATION_FRAMEWORK.md rename to docs/governance/TRUST_AND_VALIDATION_FRAMEWORK.adoc index 02b07e23..58b91734 100644 --- a/docs/governance/TRUST_AND_VALIDATION_FRAMEWORK.md +++ b/docs/governance/TRUST_AND_VALIDATION_FRAMEWORK.adoc @@ -1,42 +1,43 @@ -# ECHIDNA Trust and Validation Framework +== ECHIDNA Trust and Validation Framework -**Status**: Design Document -**Date**: 2026-01-29 -**Purpose**: Ensure ECHIDNA produces verifiable, trustworthy proofs—not "LLM bollocks" +*Status*: Design Document *Date*: 2026-01-29 *Purpose*: Ensure ECHIDNA +produces verifiable, trustworthy proofs—not "`LLM bollocks`" ---- +''''' -## Executive Summary +=== Executive Summary -ECHIDNA is a neurosymbolic theorem prover combining neural ML with symbolic reasoning. To build trust, we implement: +ECHIDNA is a neurosymbolic theorem prover combining neural ML with +symbolic reasoning. To build trust, we implement: -1. **Benchmarking Suite** - Performance regression detection -2. **Automated Testing** - Property-based, fuzzing, metamorphic, differential -3. **Idris2 Proof Validator** - Dependent-typed proof checker -4. **Early Warning System** - Detect false positives/negatives -5. **Trust Metrics** - Confidence scoring, multi-prover agreement -6. **Formal Soundness Guarantees** - Prove the validator correct +[arabic] +. *Benchmarking Suite* - Performance regression detection +. *Automated Testing* - Property-based, fuzzing, metamorphic, +differential +. *Idris2 Proof Validator* - Dependent-typed proof checker +. *Early Warning System* - Detect false positives/negatives +. *Trust Metrics* - Confidence scoring, multi-prover agreement +. *Formal Soundness Guarantees* - Prove the validator correct -**Key Principle**: *Trust but verify* - ML suggests tactics, formal provers verify correctness. +*Key Principle*: _Trust but verify_ - ML suggests tactics, formal +provers verify correctness. ---- +''''' -## 1. Benchmarking System +=== 1. Benchmarking System -### 1.1 Performance Benchmarks (Rust + Criterion) +==== 1.1 Performance Benchmarks (Rust + Criterion) -**Goal**: Track performance regressions across versions. +*Goal*: Track performance regressions across versions. -**Metrics**: -- Proof search time (ms per theorem) -- Tactic application latency -- Memory usage during proof search -- ML inference time (Julia API calls) -- Parallel speedup (Chapel vs sequential) +*Metrics*: - Proof search time (ms per theorem) - Tactic application +latency - Memory usage during proof search - ML inference time (Julia +API calls) - Parallel speedup (Chapel vs sequential) -**Implementation**: +*Implementation*: -```rust +[source,rust] +---- // benches/proof_benchmarks.rs use criterion::{black_box, criterion_group, criterion_main, Criterion}; use echidna::provers::*; @@ -68,10 +69,12 @@ fn bench_ml_inference(c: &mut Criterion) { criterion_group!(benches, bench_simple_arithmetic, bench_ml_inference); criterion_main!(benches); -``` +---- -**Setup**: -```toml +*Setup*: + +[source,toml] +---- # Cargo.toml [dev-dependencies] criterion = { version = "0.5", features = ["html_reports"] } @@ -79,10 +82,12 @@ criterion = { version = "0.5", features = ["html_reports"] } [[bench]] name = "proof_benchmarks" harness = false -``` +---- + +*CI Integration*: -**CI Integration**: -```yaml +[source,yaml] +---- # .github/workflows/benchmarks.yml name: Continuous Benchmarking on: [push, pull_request] @@ -100,11 +105,12 @@ jobs: output-file-path: target/criterion/*/new/estimates.json fail-on-alert: true alert-threshold: '150%' # Fail if 50% slower -``` +---- -### 1.2 ML Model Benchmarks (Julia + BenchmarkTools.jl) +==== 1.2 ML Model Benchmarks (Julia + BenchmarkTools.jl) -```julia +[source,julia] +---- # benchmarks/ml_benchmarks.jl using BenchmarkTools @@ -126,11 +132,12 @@ suite["encoding"]["text_to_bow"] = @benchmarkable text_to_bow( # Run and report results = run(suite, verbose = true) BenchmarkTools.save("benchmark_results.json", median(results)) -``` +---- -### 1.3 Chapel Parallel Benchmarks +==== 1.3 Chapel Parallel Benchmarks -```chapel +[source,chapel] +---- // chapel_poc/benchmark_parallel.chpl use Time; @@ -162,17 +169,18 @@ proc benchmarkParallelSearch() { writeln("Parallel: ", avg(parTimes), " ± ", stddev(parTimes)); writeln("Speedup: ", avg(seqTimes) / avg(parTimes), "x"); } -``` +---- ---- +''''' -## 2. Automated Testing Framework +=== 2. Automated Testing Framework -### 2.1 Property-Based Testing (PropTest) +==== 2.1 Property-Based Testing (PropTest) -**Goal**: Test invariants with random inputs. +*Goal*: Test invariants with random inputs. -```rust +[source,rust] +---- // tests/property_tests.rs use proptest::prelude::*; use echidna::core::*; @@ -210,13 +218,14 @@ proptest! { prop_assert!((sum - 1.0).abs() < 0.001); } } -``` +---- -### 2.2 Metamorphic Testing +==== 2.2 Metamorphic Testing -**Goal**: Test proof equivalence under transformations. +*Goal*: Test proof equivalence under transformations. -```rust +[source,rust] +---- #[test] fn test_commutativity_metamorphic() { // Original goal: n + m = m + n @@ -247,13 +256,14 @@ fn test_associativity_metamorphic() { // Alpha-equivalent goals should have structurally similar proofs assert_eq!(proof1.tactics, proof2.tactics); } -``` +---- -### 2.3 Differential Testing +==== 2.3 Differential Testing -**Goal**: Compare outputs across multiple provers. +*Goal*: Compare outputs across multiple provers. -```rust +[source,rust] +---- #[test] fn test_prover_agreement() { let goals = vec![ @@ -275,13 +285,14 @@ fn test_prover_agreement() { } } } -``` +---- -### 2.4 Fuzzing (cargo-fuzz) +==== 2.4 Fuzzing (cargo-fuzz) -**Goal**: Find crashes and panics with random inputs. +*Goal*: Find crashes and panics with random inputs. -```rust +[source,rust] +---- // fuzz/fuzz_targets/fuzz_parse.rs #![no_main] use libfuzzer_sys::fuzz_target; @@ -293,31 +304,33 @@ fuzz_target!(|data: &[u8]| { let _ = Term::parse(s); } }); -``` +---- -```bash +[source,bash] +---- # Run fuzzer cargo fuzz run fuzz_parse -- -max_total_time=300 -``` +---- ---- +''''' -## 3. Idris2 Proof Validator +=== 3. Idris2 Proof Validator -### 3.1 Why Idris2? +==== 3.1 Why Idris2? -**Advantages**: -- **Dependent types**: Encode proof rules as types -- **Totality checking**: Guaranteed termination (no infinite loops) -- **Provably correct**: Can prove properties about the validator itself -- **Fast native code**: Compiles to C/Chez Scheme -- **Interop**: Can call from Rust via FFI +*Advantages*: - *Dependent types*: Encode proof rules as types - +*Totality checking*: Guaranteed termination (no infinite loops) - +*Provably correct*: Can prove properties about the validator itself - +*Fast native code*: Compiles to C/Chez Scheme - *Interop*: Can call from +Rust via FFI -**Goal**: Build a *formally verified* proof checker that validates ECHIDNA's outputs. +*Goal*: Build a _formally verified_ proof checker that validates +ECHIDNA’s outputs. -### 3.2 Idris2 Proof Term Representation +==== 3.2 Idris2 Proof Term Representation -```idris +[source,idris] +---- -- src/idris/ProofTerm.idr module ProofTerm @@ -354,11 +367,12 @@ data HasType : Context -> ProofTerm -> ProofTerm -> Type where (resTy : ProofTerm) -> HasType (Extend ctx name argTy) body resTy -> HasType ctx (Lambda name argTy body) (Implies argTy resTy) -``` +---- -### 3.3 Proof Validator (Type Checker) +==== 3.3 Proof Validator (Type Checker) -```idris +[source,idris] +---- -- src/idris/Validator.idr module Validator @@ -397,11 +411,12 @@ validateProof proof goal = then Valid proof else Invalid "Proof type doesn't match goal" Nothing => Invalid "Failed to infer proof type" -``` +---- -### 3.4 Parser for Prover Outputs +==== 3.4 Parser for Prover Outputs -```idris +[source,idris] +---- -- src/idris/Parser.idr module Parser @@ -433,11 +448,12 @@ parseProof "coq" = parseCoqProof parseProof "lean" = parseLeanProof parseProof "isabelle" = parseIsabelleProof parseProof _ = const Nothing -``` +---- -### 3.5 Soundness Theorem +==== 3.5 Soundness Theorem -```idris +[source,idris] +---- -- Prove the validator is sound soundnessTheorem : (proof : ProofTerm) -> (goal : ProofTerm) -> validateProof proof goal = Valid proof -> @@ -446,11 +462,12 @@ soundnessTheorem proof goal prf = -- Proof by induction on proof structure -- (Full proof omitted for brevity, but this is the signature) ?soundness_hole -``` +---- -### 3.6 FFI Integration with Rust +==== 3.6 FFI Integration with Rust -```idris +[source,idris] +---- -- src/idris/FFI.idr module FFI @@ -473,9 +490,10 @@ validate prover_name proof_text goal_text = case validateProof proof goal of Valid _ => 1 -- Success Invalid _ => 0 -- Validation failed -``` +---- -```rust +[source,rust] +---- // src/rust/idris_validator.rs use std::ffi::{CString, CStr}; use std::os::raw::c_char; @@ -511,11 +529,12 @@ pub fn validate_proof_with_idris( } } } -``` +---- -### 3.7 Build Integration +==== 3.7 Build Integration -```justfile +[source,justfile] +---- # Justfile build-idris-validator: cd src/idris && idris2 --build echidna-validator.ipkg @@ -523,15 +542,16 @@ build-idris-validator: test-idris-validator: cd src/idris && idris2 --test echidna-validator.ipkg -``` +---- ---- +''''' -## 4. Early Warning System +=== 4. Early Warning System -### 4.1 Anomaly Detection +==== 4.1 Anomaly Detection -```rust +[source,rust] +---- // src/rust/anomaly_detection.rs use crate::core::*; @@ -609,11 +629,12 @@ impl AnomalyDetector { goal.len() > 100 } } -``` +---- -### 4.2 Multi-Prover Consensus +==== 4.2 Multi-Prover Consensus -```rust +[source,rust] +---- // src/rust/consensus.rs pub struct ConsensusChecker { provers: Vec>, @@ -645,11 +666,12 @@ impl ConsensusChecker { } } } -``` +---- -### 4.3 Monitoring Dashboard +==== 4.3 Monitoring Dashboard -```rust +[source,rust] +---- // src/rust/monitoring.rs use prometheus::{Counter, Histogram, Registry}; @@ -684,15 +706,16 @@ impl ProofMetrics { } } } -``` +---- ---- +''''' -## 5. Trust Metrics +=== 5. Trust Metrics -### 5.1 Proof Certificates +==== 5.1 Proof Certificates -```rust +[source,rust] +---- // src/rust/certificates.rs use sha2::{Sha256, Digest}; use ed25519_dalek::{Keypair, Signature, Signer}; @@ -743,11 +766,12 @@ impl ProofCertificate { public_key.verify_strict(&self.hash, &self.signature).is_ok() } } -``` +---- -### 5.2 Confidence Calibration +==== 5.2 Confidence Calibration -```julia +[source,julia] +---- # src/julia/calibration.jl using Statistics @@ -792,11 +816,12 @@ function expected_calibration_error(predictions, outcomes) total_error / total_count end -``` +---- -### 5.3 Multi-Prover Agreement Score +==== 5.3 Multi-Prover Agreement Score -```rust +[source,rust] +---- pub fn calculate_trust_score( goal: &str, primary_result: &ProofResult @@ -825,108 +850,115 @@ pub fn calculate_trust_score( } } } -``` +---- + +''''' + +=== 6. Implementation Roadmap + +==== Phase 1: Benchmarking (Week 1-2) + +* [ ] Set up Criterion.rs benchmarks +* [ ] Add BenchmarkTools.jl for Julia +* [ ] Create Chapel performance benchmarks +* [ ] Integrate into CI/CD pipeline +* [ ] Create regression detection alerts + +==== Phase 2: Testing (Week 3-4) ---- +* [ ] Implement property-based tests (PropTest) +* [ ] Add metamorphic test suite +* [ ] Set up differential testing across provers +* [ ] Configure cargo-fuzz for parser fuzzing +* [ ] Achieve 95%+ test coverage -## 6. Implementation Roadmap +==== Phase 3: Idris2 Validator (Week 5-8) -### Phase 1: Benchmarking (Week 1-2) -- [ ] Set up Criterion.rs benchmarks -- [ ] Add BenchmarkTools.jl for Julia -- [ ] Create Chapel performance benchmarks -- [ ] Integrate into CI/CD pipeline -- [ ] Create regression detection alerts +* [ ] Design proof term AST in Idris2 +* [ ] Implement type checker with totality +* [ ] Create parsers for Coq/Lean/Isabelle outputs +* [ ] Prove soundness theorem +* [ ] Build C FFI bindings +* [ ] Integrate with Rust backend -### Phase 2: Testing (Week 3-4) -- [ ] Implement property-based tests (PropTest) -- [ ] Add metamorphic test suite -- [ ] Set up differential testing across provers -- [ ] Configure cargo-fuzz for parser fuzzing -- [ ] Achieve 95%+ test coverage +==== Phase 4: Anomaly Detection (Week 9-10) -### Phase 3: Idris2 Validator (Week 5-8) -- [ ] Design proof term AST in Idris2 -- [ ] Implement type checker with totality -- [ ] Create parsers for Coq/Lean/Isabelle outputs -- [ ] Prove soundness theorem -- [ ] Build C FFI bindings -- [ ] Integrate with Rust backend +* [ ] Implement anomaly detector +* [ ] Add multi-prover consensus checker +* [ ] Create monitoring dashboard (Prometheus + Grafana) +* [ ] Set up alerting for anomalies +* [ ] Test with adversarial inputs -### Phase 4: Anomaly Detection (Week 9-10) -- [ ] Implement anomaly detector -- [ ] Add multi-prover consensus checker -- [ ] Create monitoring dashboard (Prometheus + Grafana) -- [ ] Set up alerting for anomalies -- [ ] Test with adversarial inputs +==== Phase 5: Trust Metrics (Week 11-12) -### Phase 5: Trust Metrics (Week 11-12) -- [ ] Implement proof certificates -- [ ] Calibrate ML confidence scores -- [ ] Create trust scoring system -- [ ] Generate audit logs -- [ ] Build public verification API +* [ ] Implement proof certificates +* [ ] Calibrate ML confidence scores +* [ ] Create trust scoring system +* [ ] Generate audit logs +* [ ] Build public verification API ---- +''''' -## 7. Assurance for Stakeholders +=== 7. Assurance for Stakeholders -### For Users +==== For Users -**"How do I know this proof is correct?"** +*"`How do I know this proof is correct?`"* -✅ **Multi-prover consensus**: 9/12 provers agreed on this proof -✅ **Formal validation**: Idris2 type checker verified proof soundness -✅ **Cryptographic certificate**: Proof signed with timestamp and hash -✅ **Audit trail**: Full proof derivation logged and reproducible -✅ **Trust score**: 0.87/1.0 (high confidence) +✅ *Multi-prover consensus*: 9/12 provers agreed on this proof ✅ +*Formal validation*: Idris2 type checker verified proof soundness ✅ +*Cryptographic certificate*: Proof signed with timestamp and hash ✅ +*Audit trail*: Full proof derivation logged and reproducible ✅ *Trust +score*: 0.87/1.0 (high confidence) -### For Developers +==== For Developers -**"How do I ensure my changes don't break soundness?"** +*"`How do I ensure my changes don’t break soundness?`"* -✅ **137 tests** (99 unit + 38 integration + property-based) -✅ **Continuous benchmarking**: Alerts on performance regressions -✅ **Differential testing**: All changes tested across 12 provers -✅ **Fuzzing**: 1M+ inputs tested for crashes -✅ **Idris2 validator**: Formal soundness guarantee +✅ *137 tests* (99 unit + 38 integration + property-based) ✅ +*Continuous benchmarking*: Alerts on performance regressions ✅ +*Differential testing*: All changes tested across 12 provers ✅ +*Fuzzing*: 1M+ inputs tested for crashes ✅ *Idris2 validator*: Formal +soundness guarantee -### For Researchers +==== For Researchers -**"How do I trust the ML component?"** +*"`How do I trust the ML component?`"* -✅ **Separation of concerns**: ML *suggests*, provers *verify* -✅ **Confidence calibration**: ECE < 0.05 (well-calibrated) -✅ **Anomaly detection**: Flags overconfident predictions -✅ **Ablation studies**: Benchmark with/without ML -✅ **Reproducible**: All training data and models versioned +✅ *Separation of concerns*: ML _suggests_, provers _verify_ ✅ +*Confidence calibration*: ECE < 0.05 (well-calibrated) ✅ *Anomaly +detection*: Flags overconfident predictions ✅ *Ablation studies*: +Benchmark with/without ML ✅ *Reproducible*: All training data and +models versioned -### For Community +==== For Community -**"Is this just LLM bullshit?"** +*"`Is this just LLM bullshit?`"* -❌ **NO.** Here's why: +❌ *NO.* Here’s why: -1. **Proofs are formally verified** by established theorem provers (Coq, Lean, Isabelle) -2. **ML only suggests tactics** - it never generates unsound proofs -3. **Idris2 validator provides mathematical guarantee** of soundness -4. **Multi-prover consensus** - if 9/12 provers agree, it's sound -5. **Public verification** - anyone can re-check proofs independently -6. **Audit logs** - full transparency of proof derivation -7. **Property-based testing** - checked 1M+ invariants -8. **No hallucination** - proofs are syntactic objects, not generated text +[arabic] +. *Proofs are formally verified* by established theorem provers (Coq, +Lean, Isabelle) +. *ML only suggests tactics* - it never generates unsound proofs +. *Idris2 validator provides mathematical guarantee* of soundness +. *Multi-prover consensus* - if 9/12 provers agree, it’s sound +. *Public verification* - anyone can re-check proofs independently +. *Audit logs* - full transparency of proof derivation +. *Property-based testing* - checked 1M+ invariants +. *No hallucination* - proofs are syntactic objects, not generated text -**ECHIDNA is a neurosymbolic system**: -- **Neural** (ML): Fast tactic search (heuristic) -- **Symbolic** (Provers): Guaranteed correctness (formal) +*ECHIDNA is a neurosymbolic system*: - *Neural* (ML): Fast tactic search +(heuristic) - *Symbolic* (Provers): Guaranteed correctness (formal) -**The ML component cannot introduce unsoundness** because all proofs are verified by formal systems. +*The ML component cannot introduce unsoundness* because all proofs are +verified by formal systems. ---- +''''' -## 8. Files to Create +=== 8. Files to Create -``` +.... echidna/ ├── benches/ │ ├── proof_benchmarks.rs # Criterion benchmarks @@ -959,15 +991,15 @@ echidna/ ├── TRUST_FRAMEWORK.md # This document ├── SOUNDNESS_PROOF.md # Idris2 soundness proof └── VERIFICATION_GUIDE.md # How to verify proofs -``` +.... ---- +''''' -## 9. Metrics Dashboard +=== 9. Metrics Dashboard -**Real-time monitoring at `/metrics` endpoint**: +*Real-time monitoring at `+/metrics+` endpoint*: -``` +.... # Proof Statistics echidna_proofs_attempted_total 4,582 echidna_proofs_succeeded_total 4,103 (89.5%) @@ -988,30 +1020,33 @@ echidna_confidence_calibration_error 0.043 echidna_prover_success_rate{prover="lean"} 0.92 echidna_prover_success_rate{prover="coq"} 0.89 echidna_prover_success_rate{prover="agda"} 0.76 -``` +.... ---- +''''' -## 10. Conclusion +=== 10. Conclusion -**ECHIDNA is trustworthy because**: +*ECHIDNA is trustworthy because*: -1. ✅ **Formal verification** - Idris2 validator with soundness proof -2. ✅ **Multi-prover consensus** - 12 independent verifiers -3. ✅ **Comprehensive testing** - 137 tests + fuzzing + property-based -4. ✅ **Anomaly detection** - Flags suspicious proofs -5. ✅ **Transparent audit trail** - Full proof derivation logged -6. ✅ **Cryptographic certificates** - Unforgeable proof signatures -7. ✅ **Calibrated confidence** - ML scores match reality -8. ✅ **Continuous monitoring** - Performance regression detection +[arabic] +. ✅ *Formal verification* - Idris2 validator with soundness proof +. ✅ *Multi-prover consensus* - 12 independent verifiers +. ✅ *Comprehensive testing* - 137 tests + fuzzing + property-based +. ✅ *Anomaly detection* - Flags suspicious proofs +. ✅ *Transparent audit trail* - Full proof derivation logged +. ✅ *Cryptographic certificates* - Unforgeable proof signatures +. ✅ *Calibrated confidence* - ML scores match reality +. ✅ *Continuous monitoring* - Performance regression detection -**This is not "LLM bollocks"** - it's a formally verified, multi-prover consensus system with neural acceleration. +*This is not "`LLM bollocks`"* - it’s a formally verified, multi-prover +consensus system with neural acceleration. ---- +''''' -**Next Steps**: Implement Phase 1 (Benchmarking) to start measuring performance and catching regressions. +*Next Steps*: Implement Phase 1 (Benchmarking) to start measuring +performance and catching regressions. ---- +''''' -*ECHIDNA Trust and Validation Framework* -*Co-Authored-By: Claude Sonnet 4.5 * +_ECHIDNA Trust and Validation Framework_ _Co-Authored-By: Claude Sonnet +4.5 noreply@anthropic.com_ diff --git a/docs/governance/TRUST_IMPLEMENTATION_GUIDE.md b/docs/governance/TRUST_IMPLEMENTATION_GUIDE.adoc similarity index 68% rename from docs/governance/TRUST_IMPLEMENTATION_GUIDE.md rename to docs/governance/TRUST_IMPLEMENTATION_GUIDE.adoc index 7fa8ac4e..e0d85360 100644 --- a/docs/governance/TRUST_IMPLEMENTATION_GUIDE.md +++ b/docs/governance/TRUST_IMPLEMENTATION_GUIDE.adoc @@ -1,14 +1,16 @@ -# Trust Framework Implementation Guide +== Trust Framework Implementation Guide -**Quick Start**: How to implement and use ECHIDNA's trust and validation framework. +*Quick Start*: How to implement and use ECHIDNA’s trust and validation +framework. ---- +''''' -## Phase 1: Benchmarking (Week 1) +=== Phase 1: Benchmarking (Week 1) -### Setup +==== Setup -```bash +[source,bash] +---- # Add dependencies to Cargo.toml [dev-dependencies] criterion = { version = "0.5", features = ["html_reports"] } @@ -17,11 +19,12 @@ proptest = "1.4" [[bench]] name = "proof_benchmarks" harness = false -``` +---- -### Run Benchmarks +==== Run Benchmarks -```bash +[source,bash] +---- # Run all benchmarks cargo bench @@ -30,23 +33,25 @@ open target/criterion/report/index.html # Run specific benchmark cargo bench --bench proof_benchmarks -- simple_arithmetic -``` +---- -### Set Up CI Benchmarking +==== Set Up CI Benchmarking -```bash +[source,bash] +---- # Already created: .github/workflows/benchmarks.yml # Pushes to main will track performance over time # PR benchmarks will compare against main branch -``` +---- ---- +''''' -## Phase 2: Property-Based Testing (Week 1) +=== Phase 2: Property-Based Testing (Week 1) -### Run Property Tests +==== Run Property Tests -```bash +[source,bash] +---- # Run all property tests cargo test property_tests @@ -55,11 +60,12 @@ cargo test property_tests -- --nocapture # Run specific property cargo test reflexivity_is_idempotent -``` +---- -### Add New Property +==== Add New Property -```rust +[source,rust] +---- // In tests/property_tests.rs proptest! { #[test] @@ -68,15 +74,16 @@ proptest! { prop_assert!(some_invariant(input)); } } -``` +---- ---- +''''' -## Phase 3: Idris2 Validator (Week 2-3) +=== Phase 3: Idris2 Validator (Week 2-3) -### Install Idris2 +==== Install Idris2 -```bash +[source,bash] +---- # Option 1: From package manager # Fedora sudo dnf install idris2 @@ -86,11 +93,12 @@ git clone https://github.com/idris-lang/Idris2.git cd Idris2 make bootstrap make install -``` +---- -### Build Validator +==== Build Validator -```bash +[source,bash] +---- # Navigate to Idris source cd src/idris @@ -100,11 +108,12 @@ idris2 --build echidna-validator.ipkg # Run tests idris2 --repl Validator.idr > :exec testValidation -``` +---- -### Integrate with Rust +==== Integrate with Rust -```rust +[source,rust] +---- // In src/rust/main.rs or lib.rs pub mod anomaly_detection; @@ -118,15 +127,16 @@ let anomalies = detector.detect(&result); if !anomalies.is_empty() { println!("⚠️ Anomalies detected: {:?}", anomalies); } -``` +---- ---- +''''' -## Phase 4: Anomaly Detection (Week 3) +=== Phase 4: Anomaly Detection (Week 3) -### Basic Usage +==== Basic Usage -```rust +[source,rust] +---- use echidna::anomaly_detection::{AnomalyDetector, ProofResult}; // Create detector with defaults @@ -154,11 +164,12 @@ let anomalies = detector.detect(&result); for anomaly in anomalies { println!("Anomaly: {:?}", anomaly); } -``` +---- -### Multi-Prover Consensus +==== Multi-Prover Consensus -```rust +[source,rust] +---- use echidna::anomaly_detection::ConsensusChecker; let checker = ConsensusChecker::new(3); // Need 3 agreeing @@ -177,15 +188,16 @@ if consensus.agreed { } else { println!("✗ No consensus - prover disagreement!"); } -``` +---- ---- +''''' -## Phase 5: Integration (Week 4) +=== Phase 5: Integration (Week 4) -### Add to API Endpoint +==== Add to API Endpoint -```rust +[source,rust] +---- // In src/rust/server.rs async fn prove_endpoint( Json(req): Json @@ -216,11 +228,12 @@ async fn prove_endpoint( consensus_confidence: consensus.confidence, })) } -``` +---- -### Trust Score API +==== Trust Score API -```rust +[source,rust] +---- #[derive(Serialize)] pub struct TrustScore { /// Overall trust score (0.0 - 1.0) @@ -262,15 +275,16 @@ fn calculate_trust_score( }, } } -``` +---- ---- +''''' -## Testing the Framework +=== Testing the Framework -### Run All Tests +==== Run All Tests -```bash +[source,bash] +---- # Unit tests cargo test @@ -282,25 +296,27 @@ cargo bench # Idris2 validator cd src/idris && idris2 --test echidna-validator.ipkg -``` +---- -### Test Anomaly Detection +==== Test Anomaly Detection -```bash +[source,bash] +---- # Run anomaly detection tests cargo test anomaly_detection # Test with real proofs cargo run --example test_anomalies -``` +---- ---- +''''' -## Monitoring Dashboard (Future) +=== Monitoring Dashboard (Future) -### Prometheus Metrics +==== Prometheus Metrics -```rust +[source,rust] +---- use prometheus::{Counter, Histogram, Registry}; lazy_static! { @@ -324,11 +340,12 @@ lazy_static! { PROOFS_ATTEMPTED.inc(); ANOMALIES_DETECTED.inc_by(anomalies.len() as f64); PROOF_TIME.observe(duration_secs); -``` +---- -### Grafana Dashboard +==== Grafana Dashboard -```yaml +[source,yaml] +---- # docker-compose.yml services: prometheus: @@ -344,47 +361,54 @@ services: - "3001:3000" environment: - GF_SECURITY_ADMIN_PASSWORD=admin -``` +---- ---- +''''' -## FAQ +=== FAQ -### Q: How do I know if a proof is trustworthy? +==== Q: How do I know if a proof is trustworthy? -Check the trust score: -- **0.9-1.0**: Very trustworthy (multiple provers agree, no anomalies) -- **0.7-0.9**: Trustworthy (some agreement, minor issues) -- **0.5-0.7**: Questionable (low agreement or multiple anomalies) -- **<0.5**: Not trustworthy (prover disagreement or serious anomalies) +Check the trust score: - *0.9-1.0*: Very trustworthy (multiple provers +agree, no anomalies) - *0.7-0.9*: Trustworthy (some agreement, minor +issues) - *0.5-0.7*: Questionable (low agreement or multiple anomalies) +- *<0.5*: Not trustworthy (prover disagreement or serious anomalies) -### Q: What if the ML model is overconfident? +==== Q: What if the ML model is overconfident? -The anomaly detector will flag `UnusuallyHighConfidence` if the model is >95% confident on a complex theorem. This doesn't mean the proof is wrong, just that it needs extra verification. +The anomaly detector will flag `+UnusuallyHighConfidence+` if the model +is >95% confident on a complex theorem. This doesn’t mean the proof is +wrong, just that it needs extra verification. -### Q: How many provers need to agree? +==== Q: How many provers need to agree? -Recommended: **3 out of 12** for basic trust, **6 out of 12** for high trust, **9+ out of 12** for critical applications. +Recommended: *3 out of 12* for basic trust, *6 out of 12* for high +trust, *9+ out of 12* for critical applications. -### Q: Can the ML component introduce unsoundness? +==== Q: Can the ML component introduce unsoundness? -**No.** The ML component only *suggests tactics* - all proofs are verified by formal theorem provers (Coq, Lean, etc.). The ML cannot generate unsound proofs because provers reject invalid tactics. +*No.* The ML component only _suggests tactics_ - all proofs are verified +by formal theorem provers (Coq, Lean, etc.). The ML cannot generate +unsound proofs because provers reject invalid tactics. -### Q: What's the Idris2 validator for? +==== Q: What’s the Idris2 validator for? -Extra assurance. Even if a prover claims a proof is valid, the Idris2 validator provides a **second opinion** with a formally verified type checker. If Idris2 agrees, you have mathematical certainty. +Extra assurance. Even if a prover claims a proof is valid, the Idris2 +validator provides a *second opinion* with a formally verified type +checker. If Idris2 agrees, you have mathematical certainty. ---- +''''' -## Next Steps +=== Next Steps -1. ✅ **Week 1**: Run benchmarks and property tests -2. ⏳ **Week 2**: Install Idris2 and build validator -3. ⏳ **Week 3**: Integrate anomaly detection into API -4. ⏳ **Week 4**: Add multi-prover consensus checking -5. ⏳ **Week 5**: Deploy monitoring dashboard +[arabic] +. ✅ *Week 1*: Run benchmarks and property tests +. ⏳ *Week 2*: Install Idris2 and build validator +. ⏳ *Week 3*: Integrate anomaly detection into API +. ⏳ *Week 4*: Add multi-prover consensus checking +. ⏳ *Week 5*: Deploy monitoring dashboard ---- +''''' -*ECHIDNA Trust Framework - Quick Implementation Guide* -*Co-Authored-By: Claude Sonnet 4.5 * +_ECHIDNA Trust Framework - Quick Implementation Guide_ _Co-Authored-By: +Claude Sonnet 4.5 noreply@anthropic.com_ diff --git a/docs/handover/B7-AUDIT-CORRECTION.adoc b/docs/handover/B7-AUDIT-CORRECTION.adoc new file mode 100644 index 00000000..180be41b --- /dev/null +++ b/docs/handover/B7-AUDIT-CORRECTION.adoc @@ -0,0 +1,114 @@ +== B7 audit correction — HP ecosystem backends are NOT corpus-only + +*Status*: Correction. *Origin*: The 2026-06-03 "`what stops echidna from +running proof work across the estate`" punch list listed *B7* as: + +____ +_HP type-checker ecosystem (13 provers) corpus-only — KatagoriaVerifier, +Modal/Session/Choreographic/Epistemic/Refinement/Echo/Dependent/QTT/ +Effect-Row/Tropical/TypeLL backends missing. Rust adapters not +scaffolded in `+src/rust/provers/+`. Corpus contributes to +vocab/training only._ +____ + +That characterisation is incorrect. This memo replaces B7’s "`scaffold +missing adapters`" framing with what is actually missing. + +=== What is actually in tree (verified 2026-06-03) + +==== Unified `+HPEcosystemBackend+` + +`+src/rust/provers/hp_ecosystem.rs:50-153+` defines +`+HPEcosystemBackend+`, a full `+ProverBackend+` implementation that: + +* Pattern-matches on `+ProverKind+` to select the upstream CLI +(`+typell+`, `+katagoria+`, `+tropical-type-check+`) and discipline tag +(`+echo+`, `+session+`, `+qtt+`, `+effect-row+`, …) — see +`+hp_ecosystem.rs::upstream()+` lines 63-126. +* Implements `+parse_file+`, `+parse_string+`, `+apply_tactic+`, and +`+verify_proof+` against the upstream binary — lines 156-330. +* Injects a `+#discipline:+` header when the source lacks one (lines +196-205), so estate consumers don’t need to know the wire format. + +==== Routing in `+ProverFactory::create+` + +`+src/rust/provers/mod.rs:1774-1824+` routes: + +[width="100%",cols="53%,47%",options="header",] +|=== +|ProverKind |Backend +|`+TypeLL+`, `+KatagoriaVerifier+` |`+hp_ecosystem::HPEcosystemBackend+` + +|39 other `+*TypeChecker+` variants incl. `+EchoTypeChecker+`, +`+TropicalTypeChecker+` |`+typed_wasm::TypedWasmBackend::for_kind+` +|=== + +Both routes exist on `+main+`. None of the 41 enum variants falls +through to "`unsupported`". + +==== Test infrastructure + +`+tests/common/mod.rs:114+`, `+:185+`, `+:245+` already special-case +`+k.is_hp_ecosystem()+` for executable / args / default-binary +resolution in the prover-smoke harness. +`+tests/gnn_augment_integration.rs:545+` covers +`+test_hp_ecosystem_gnn_wires_top_premise+`. + +=== What is genuinely outstanding for these backends + +The audit’s underlying intuition (estate proof work won’t run end-to-end +on these provers) is correct — but the gap is downstream of the +scaffold, not the scaffold itself: + +[arabic] +. *Upstream binaries are not packaged.* `+typell+`, `+katagoria+`, and +`+tropical-type-check+` are referenced from +`+hp_ecosystem.rs::upstream()+` but none of them ship in any of +echidna’s Containerfiles or the Guix manifest. +`+manifests/live-provers.scm+` covers Z3, CVC5, Lean4, Coq, Agda, +Isabelle, Idris2, F*, Dafny, TLAPS — the HP triad is absent. A live CI +run can compile and dispatch but the subprocess exits with "`binary not +found`". +. *No smoke fixture for the three named provers.* +`+tests/chapel_fixtures/+` has `+coq_trivial.v+` and +`+lean_trivial.lean+`; there is no equivalent `+echo_trivial.tll+`, +`+tropical_trivial.tll+`, or `+katagoria_trivial.k+`. This PR adds the +minimum three. +. *No discoverability for "`how do I add a new HP discipline.`"* Adding +a discipline today means editing the 39-arm match in +`+hp_ecosystem.rs::upstream()+`, the 41-arm match in +`+ProverFactory::create+`, and matching arms in `+is_hp_ecosystem()+` +and `+default_executable()+`. There is no documented onboarding flow. + +=== What this PR delivers + +* This correction memo (`+docs/handover/B7-AUDIT-CORRECTION.md+`). +* Three smoke fixtures (`+tests/fixtures/hp/+`): +** `+echo_trivial.tll+` — discipline `+echo+`, single identity goal. +** `+tropical_trivial.tll+` — discipline `+tropical+`, resource-aware +identity. +** `+katagoria_trivial.k+` — discipline `+verify+`, single isomorphism. +* A short onboarding doc (`+docs/HP-BACKEND-ONBOARDING.md+`) listing the +~4 files an author must touch to add a new HP discipline, with line +references. + +What it does *not* deliver: + +* The upstream `+typell+` / `+katagoria+` / `+tropical-type-check+` +binaries (those live in `+developer-ecosystem/katagoria+`, +`+verification-ecosystem/tropical-resource-typing+`, and +`+verification-ecosystem/typell+` and are owner-managed). +* A live CI run gate (that needs the binaries packaged first; see the L3 +path checklist in the D18 PR). +* Per-discipline GNN training data extraction (TypeDiscipline Phase-2 +deferred — audit item F26). + +=== Cross-references + +* `+docs/handover/TODO.md+` P4 — Wave-4 + HP ecosystem expansion (now +partially superseded for the HP rows). +* `+docs/PROVER_COUNT.md+` Tier-8 — canonical 41-variant inventory. +* C12 PR (echidnabot manifest) — per-repo opt-in shape that consumers +using these backends will adopt. +* D18 PR (L3 gate checklist) — packaging the upstream binaries is one of +the L3 → L1 hand-off criteria. diff --git a/docs/handover/B7-AUDIT-CORRECTION.md b/docs/handover/B7-AUDIT-CORRECTION.md deleted file mode 100644 index a103010c..00000000 --- a/docs/handover/B7-AUDIT-CORRECTION.md +++ /dev/null @@ -1,111 +0,0 @@ - - -# B7 audit correction — HP ecosystem backends are NOT corpus-only - -**Status**: Correction. -**Origin**: The 2026-06-03 "what stops echidna from running proof work -across the estate" punch list listed **B7** as: - -> _HP type-checker ecosystem (13 provers) corpus-only — KatagoriaVerifier, -> Modal/Session/Choreographic/Epistemic/Refinement/Echo/Dependent/QTT/ -> Effect-Row/Tropical/TypeLL backends missing. Rust adapters not -> scaffolded in `src/rust/provers/`. Corpus contributes to vocab/training -> only._ - -That characterisation is incorrect. This memo replaces B7's "scaffold -missing adapters" framing with what is actually missing. - -## What is actually in tree (verified 2026-06-03) - -### Unified `HPEcosystemBackend` - -`src/rust/provers/hp_ecosystem.rs:50-153` defines -`HPEcosystemBackend`, a full `ProverBackend` implementation that: - -- Pattern-matches on `ProverKind` to select the upstream CLI - (`typell`, `katagoria`, `tropical-type-check`) and discipline tag - (`echo`, `session`, `qtt`, `effect-row`, ...) — see - `hp_ecosystem.rs::upstream()` lines 63-126. -- Implements `parse_file`, `parse_string`, `apply_tactic`, and - `verify_proof` against the upstream binary — lines 156-330. -- Injects a `#discipline:` header when the source lacks one (lines - 196-205), so estate consumers don't need to know the wire format. - -### Routing in `ProverFactory::create` - -`src/rust/provers/mod.rs:1774-1824` routes: - -| ProverKind | Backend | -|-------------------------------------------------------|--------------------------------------------------| -| `TypeLL`, `KatagoriaVerifier` | `hp_ecosystem::HPEcosystemBackend` | -| 39 other `*TypeChecker` variants incl. `EchoTypeChecker`, `TropicalTypeChecker` | `typed_wasm::TypedWasmBackend::for_kind` | - -Both routes exist on `main`. None of the 41 enum variants falls -through to "unsupported". - -### Test infrastructure - -`tests/common/mod.rs:114`, `:185`, `:245` already special-case -`k.is_hp_ecosystem()` for executable / args / default-binary resolution -in the prover-smoke harness. `tests/gnn_augment_integration.rs:545` -covers `test_hp_ecosystem_gnn_wires_top_premise`. - -## What is genuinely outstanding for these backends - -The audit's underlying intuition (estate proof work won't run end-to-end -on these provers) is correct — but the gap is downstream of the -scaffold, not the scaffold itself: - -1. **Upstream binaries are not packaged.** `typell`, `katagoria`, and - `tropical-type-check` are referenced from `hp_ecosystem.rs::upstream()` - but none of them ship in any of echidna's Containerfiles or the - Guix manifest. `manifests/live-provers.scm` covers Z3, CVC5, Lean4, - Coq, Agda, Isabelle, Idris2, F*, Dafny, TLAPS — the HP triad is - absent. A live CI run can compile and dispatch but the subprocess - exits with "binary not found". - -2. **No smoke fixture for the three named provers.** `tests/chapel_fixtures/` - has `coq_trivial.v` and `lean_trivial.lean`; there is no equivalent - `echo_trivial.tll`, `tropical_trivial.tll`, or `katagoria_trivial.k`. - This PR adds the minimum three. - -3. **No discoverability for "how do I add a new HP discipline."** - Adding a discipline today means editing the 39-arm match in - `hp_ecosystem.rs::upstream()`, the 41-arm match in - `ProverFactory::create`, and matching arms in `is_hp_ecosystem()` - and `default_executable()`. There is no documented onboarding flow. - -## What this PR delivers - -- This correction memo (`docs/handover/B7-AUDIT-CORRECTION.md`). -- Three smoke fixtures (`tests/fixtures/hp/`): - - `echo_trivial.tll` — discipline `echo`, single identity goal. - - `tropical_trivial.tll` — discipline `tropical`, resource-aware identity. - - `katagoria_trivial.k` — discipline `verify`, single isomorphism. -- A short onboarding doc (`docs/HP-BACKEND-ONBOARDING.md`) listing the - ~4 files an author must touch to add a new HP discipline, with line - references. - -What it does **not** deliver: - -- The upstream `typell` / `katagoria` / `tropical-type-check` binaries - (those live in `developer-ecosystem/katagoria`, - `verification-ecosystem/tropical-resource-typing`, and - `verification-ecosystem/typell` and are owner-managed). -- A live CI run gate (that needs the binaries packaged first; see - the L3 path checklist in the D18 PR). -- Per-discipline GNN training data extraction (TypeDiscipline Phase-2 - deferred — audit item F26). - -## Cross-references - -- `docs/handover/TODO.md` P4 — Wave-4 + HP ecosystem expansion (now - partially superseded for the HP rows). -- `docs/PROVER_COUNT.md` Tier-8 — canonical 41-variant inventory. -- C12 PR (echidnabot manifest) — per-repo opt-in shape that consumers - using these backends will adopt. -- D18 PR (L3 gate checklist) — packaging the upstream binaries is one - of the L3 → L1 hand-off criteria. diff --git a/docs/handover/HANDOVER-INDEX.adoc b/docs/handover/HANDOVER-INDEX.adoc new file mode 100644 index 00000000..87a41183 --- /dev/null +++ b/docs/handover/HANDOVER-INDEX.adoc @@ -0,0 +1,145 @@ +== Handover Index + +*Status*: canonical map of the `+docs/handover/+` suite. Last revised: +2026-05-26. + +Each file in this directory is either: - a *prompt* — a self-contained +brief for the next agent to execute a named workstream, OR - a *runbook* +— an operational guide for a now-live workstream, OR - a *plan* — a +multi-sprint coordination document, OR - a *state log* — running notes +from prior sessions. + +Read this index first to know which file is which. + +=== Active prompts (next agent picks one to execute) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|File |Workstream |Pre-condition |Effort +|link:L1-CAPNPROTO-PROMPT.md[`+L1-CAPNPROTO-PROMPT.md+`] |Stage 5a — +Cap’n Proto IPC |L3 hand-off green ≥ 7 days |~2 sprints + +|link:L2-CHAPEL-PROMPT.md[`+L2-CHAPEL-PROMPT.md+`] |Stage 5b — Chapel +L2.2+ (speculative search, corpus-parallel, multi-locale) |L1 landed |~4 +sprints + +|link:L3-LIVE-PROVER-CI-PROMPT.md[`+L3-LIVE-PROVER-CI-PROMPT.md+`] +|Stage 5d — Tier-4 live-CI provisioning |Tier-1 main CI green ≥ 7 days +|~1 sprint + +|link:PHASE-3-PROMPT.md[`+PHASE-3-PROMPT.md+`] |Modal + real-algebraic +backends (Wave-2 follow-on) |Wave-2 done |~1 sprint + +|link:SUGGEST-CLI-PROMPT.md[`+SUGGEST-CLI-PROMPT.md+`] |`+suggest+` verb +implementation |None |~3 days +|=== + +=== Active runbooks (live workstream is in production) + +[width="100%",cols="50%,50%",options="header",] +|=== +|File |What it covers +|link:S4-LOOP-CLOSURE-RUNBOOK.md[`+S4-LOOP-CLOSURE-RUNBOOK.md+`] +|VeriSim learning-loop end-to-end test (`+just test-s4-loop+`) and +operational verification + +|link:S5-VERIFICATION-RUNBOOK.md[`+S5-VERIFICATION-RUNBOOK.md+`] +|Trained-GNN-weights verification flow: `+just train-cpu+` → +`+/gnn/health+` → `+just eval+` +|=== + +=== Plans (multi-sprint coordination) + +[width="100%",cols="50%,50%",options="header",] +|=== +|File |Scope +|link:PRODUCTION-WIRING-PLAN.md[`+PRODUCTION-WIRING-PLAN.md+`] +|Three-tier (L1 Cap’n Proto / L2 Chapel / L3 live CI) production-wiring +plan. L1 prompt is the executable derivative. +|=== + +=== Deferred-work trackers + +[width="100%",cols="50%,50%",options="header",] +|=== +|File |Tracks +|link:THEOREM-METADATA-MIGRATION.md[`+THEOREM-METADATA-MIGRATION.md+`] +|Future migration of 8 parser-site structural meta-tags out of +`+Theorem.aspects+` into a dedicated `+TheoremKind+` field. Boundary +filter contains the damage; this is hygiene. +|=== + +=== State & navigation + +[width="100%",cols="50%,50%",options="header",] +|=== +|File |What it is +|link:TODO.md[`+TODO.md+`] |Living backlog. Single source of truth for +"`what’s next`" between sprints. P0–P4 priority bands. + +|link:STATE.md[`+STATE.md+`] |Running human-readable state log. +Complement to `+.machine_readable/descriptiles/STATE.a2ml+`. + +|link:README.md[`+README.md+`] |Original handover suite intro (older; +kept for orientation). +|=== + +=== Warmup material + +[width="100%",cols="50%,50%",options="header",] +|=== +|File |Audience +|link:llm-warmup-dev.md[`+llm-warmup-dev.md+`] |LLM session warmup for +contributors + +|link:llm-warmup-user.md[`+llm-warmup-user.md+`] |LLM session warmup for +end-users +|=== + +=== Execution order (when starting a fresh sprint) + +[arabic] +. Read `+STATE.md+` (or `+STATE.a2ml+`) for the current sprint state. +. Read `+TODO.md+` for the prioritised backlog. +. Pick the next-up prompt from "`Active prompts`" whose pre-condition is +met. +. Execute the prompt; cite this index in commits if you reorder +priorities. +. When a prompt is "`consumed`" by completion, retire it into the +git-history archive — do not leave consumed prompts alongside active +ones. + +=== Stage cross-reference + +Maps `+docs/ROADMAP.md+` stage IDs to the handover artefact that drives +each: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Stage |Drives |Artefact +|2a/2c |GNN training + eval |`+S5-VERIFICATION-RUNBOOK.md+` + +|3a/3b |Verisim read paths |`+S4-LOOP-CLOSURE-RUNBOOK.md+` (done) + +|3c |Outcome emission wiring |Stage-3c plan in chat history (no +dedicated handover yet — to be written when work begins) + +|4c/4d |`+suggest_tactics+` GNN ranking |`+SUGGEST-CLI-PROMPT.md+` + +|5a |Cap’n Proto IPC |`+L1-CAPNPROTO-PROMPT.md+` + +|5b |Chapel L2.2+ |`+L2-CHAPEL-PROMPT.md+` + +|5d |Tier-4 live CI |`+L3-LIVE-PROVER-CI-PROMPT.md+` +|=== + +=== When this index goes stale + +Update conditions: - A prompt is completed → move it to a `+archive/+` +subdirectory or delete and note in this file. - A new prompt is added → +add a row to the appropriate section. - A stage status changes in +`+docs/ROADMAP.md+` → update the cross-reference table. + +Quick check: `+ls docs/handover/*.md | wc -l+` should match the number +of rows across all tables above. As of 2026-05-26, this file accounts +for 13 entries. diff --git a/docs/handover/HANDOVER-INDEX.md b/docs/handover/HANDOVER-INDEX.md deleted file mode 100644 index 39babaee..00000000 --- a/docs/handover/HANDOVER-INDEX.md +++ /dev/null @@ -1,92 +0,0 @@ - - - -# Handover Index - -**Status**: canonical map of the `docs/handover/` suite. Last revised: 2026-05-26. - -Each file in this directory is either: -- a **prompt** — a self-contained brief for the next agent to execute a named - workstream, OR -- a **runbook** — an operational guide for a now-live workstream, OR -- a **plan** — a multi-sprint coordination document, OR -- a **state log** — running notes from prior sessions. - -Read this index first to know which file is which. - -## Active prompts (next agent picks one to execute) - -| File | Workstream | Pre-condition | Effort | -|---|---|---|---| -| [`L1-CAPNPROTO-PROMPT.md`](L1-CAPNPROTO-PROMPT.md) | Stage 5a — Cap'n Proto IPC | L3 hand-off green ≥ 7 days | ~2 sprints | -| [`L2-CHAPEL-PROMPT.md`](L2-CHAPEL-PROMPT.md) | Stage 5b — Chapel L2.2+ (speculative search, corpus-parallel, multi-locale) | L1 landed | ~4 sprints | -| [`L3-LIVE-PROVER-CI-PROMPT.md`](L3-LIVE-PROVER-CI-PROMPT.md) | Stage 5d — Tier-4 live-CI provisioning | Tier-1 main CI green ≥ 7 days | ~1 sprint | -| [`PHASE-3-PROMPT.md`](PHASE-3-PROMPT.md) | Modal + real-algebraic backends (Wave-2 follow-on) | Wave-2 done | ~1 sprint | -| [`SUGGEST-CLI-PROMPT.md`](SUGGEST-CLI-PROMPT.md) | `suggest` verb implementation | None | ~3 days | - -## Active runbooks (live workstream is in production) - -| File | What it covers | -|---|---| -| [`S4-LOOP-CLOSURE-RUNBOOK.md`](S4-LOOP-CLOSURE-RUNBOOK.md) | VeriSim learning-loop end-to-end test (`just test-s4-loop`) and operational verification | -| [`S5-VERIFICATION-RUNBOOK.md`](S5-VERIFICATION-RUNBOOK.md) | Trained-GNN-weights verification flow: `just train-cpu` → `/gnn/health` → `just eval` | - -## Plans (multi-sprint coordination) - -| File | Scope | -|---|---| -| [`PRODUCTION-WIRING-PLAN.md`](PRODUCTION-WIRING-PLAN.md) | Three-tier (L1 Cap'n Proto / L2 Chapel / L3 live CI) production-wiring plan. L1 prompt is the executable derivative. | - -## Deferred-work trackers - -| File | Tracks | -|---|---| -| [`THEOREM-METADATA-MIGRATION.md`](THEOREM-METADATA-MIGRATION.md) | Future migration of 8 parser-site structural meta-tags out of `Theorem.aspects` into a dedicated `TheoremKind` field. Boundary filter contains the damage; this is hygiene. | - -## State & navigation - -| File | What it is | -|---|---| -| [`TODO.md`](TODO.md) | Living backlog. Single source of truth for "what's next" between sprints. P0–P4 priority bands. | -| [`STATE.md`](STATE.md) | Running human-readable state log. Complement to `.machine_readable/descriptiles/STATE.a2ml`. | -| [`README.md`](README.md) | Original handover suite intro (older; kept for orientation). | - -## Warmup material - -| File | Audience | -|---|---| -| [`llm-warmup-dev.md`](llm-warmup-dev.md) | LLM session warmup for contributors | -| [`llm-warmup-user.md`](llm-warmup-user.md) | LLM session warmup for end-users | - -## Execution order (when starting a fresh sprint) - -1. Read `STATE.md` (or `STATE.a2ml`) for the current sprint state. -2. Read `TODO.md` for the prioritised backlog. -3. Pick the next-up prompt from "Active prompts" whose pre-condition is met. -4. Execute the prompt; cite this index in commits if you reorder priorities. -5. When a prompt is "consumed" by completion, retire it into the git-history - archive — do not leave consumed prompts alongside active ones. - -## Stage cross-reference - -Maps `docs/ROADMAP.md` stage IDs to the handover artefact that drives each: - -| Stage | Drives | Artefact | -|---|---|---| -| 2a/2c | GNN training + eval | `S5-VERIFICATION-RUNBOOK.md` | -| 3a/3b | Verisim read paths | `S4-LOOP-CLOSURE-RUNBOOK.md` (done) | -| 3c | Outcome emission wiring | Stage-3c plan in chat history (no dedicated handover yet — to be written when work begins) | -| 4c/4d | `suggest_tactics` GNN ranking | `SUGGEST-CLI-PROMPT.md` | -| 5a | Cap'n Proto IPC | `L1-CAPNPROTO-PROMPT.md` | -| 5b | Chapel L2.2+ | `L2-CHAPEL-PROMPT.md` | -| 5d | Tier-4 live CI | `L3-LIVE-PROVER-CI-PROMPT.md` | - -## When this index goes stale - -Update conditions: -- A prompt is completed → move it to a `archive/` subdirectory or delete and note in this file. -- A new prompt is added → add a row to the appropriate section. -- A stage status changes in `docs/ROADMAP.md` → update the cross-reference table. - -Quick check: `ls docs/handover/*.md | wc -l` should match the number of rows -across all tables above. As of 2026-05-26, this file accounts for 13 entries. diff --git a/docs/handover/L1-CAPNPROTO-PROMPT.adoc b/docs/handover/L1-CAPNPROTO-PROMPT.adoc new file mode 100644 index 00000000..52a89e57 --- /dev/null +++ b/docs/handover/L1-CAPNPROTO-PROMPT.adoc @@ -0,0 +1,149 @@ +== Echidna L1 — Cap’n Proto Protocol Swap — Continuation Prompt + +*Context*: Echidna currently uses HTTP + JSON for Rust↔Julia (GNN +inference) via `+src/rust/gnn/client.rs+` → `+src/julia/api_server.jl+` +port 8090. This violates the `+feedback_no_json_emit_a2ml+` memory rule +and blocks a clean polyglot IPC story. Swap to *Cap’n Proto* (chosen +over Bebop3 for dependability + maturity + zero-copy reads). + +*Master plan*: `+~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md+` +*Prerequisite*: L3 Tier-1 green for ≥7 days on main. *Follows*: L2 +(Chapel) consumes these schemas. + +=== Deliverables + +==== Schema + +* `+schemas/echidna.capnp+` — canonical wire schemas: +** `+ProofGoal+` — a theorem/claim to prove +** `+ProofResult+` — success/failure + metadata +** `+TacticSuggestion+` — ML-suggested tactic +** `+GnnRankRequest+` / `+GnnRankResponse+` — replaces current HTTP+JSON +** `+ProverInvocation+` — dispatch message to a backend (used later by +Chapel in L2) +** `+TrustedOutcome+` — post-trust-pipeline result +* `+schemas/VERSIONING.md+` — forward/backward compat rules + +==== Rust side (hot-path consumer) + +* `+src/rust/ipc/mod.rs+` — Cap’n Proto transport module +* `+src/rust/ipc/uds.rs+` — Unix-domain socket transport (primary) +* `+src/rust/ipc/tcp.rs+` — TCP transport (fallback for containerised +cases) +* Replace `+src/rust/gnn/client.rs+` HTTP calls with Cap’n Proto over +UDS +* Keep `+serde_json+` out of hot path; retain only for config/log +emission (Nickel for config proper) + +==== Julia side + +* `+src/julia/ipc.jl+` — Cap’n Proto reader/writer +* *RATIFIED 2026-05-18: C-ABI shim through the existing Zig FFI layer* +(NOT `+CapnProto.jl+`). Buffer-oriented ABI — Julia hands the Zig layer +opaque Cap’n Proto frames; Zig owns parse/validate/gate. Rationale: +estate-canonical (FFI=Zig everywhere; single wire codec shared with +Rust; the Zig layer is the estate interface-safety transaction point). +`+CapnProto.jl+` rejected: low maturity + a second independent codec = +wire-drift engine. See open-question #2 resolution below. +* `+src/julia/api_server.jl+` — switch from HTTP to UDS listener + +==== Idris2 ABI proofs + +* `+src/abi/CapnSchemas.idr+` — formal proofs that schema round-trip +preserves meaning +* Zero `+believe_me+` (per estate rule); constructive proofs only +* Coordinate with `+src/abi/Types.idr+` / `+src/abi/Foreign.idr+` + +==== Zig FFI bridge + +* `+ffi/zig/capnp_bridge.zig+` — C-ABI bridge for polyglot consumers +(esp. Chapel in L2) + +==== AffineScript bindings (UI path) + +* `+bindings/affinescript/echidna_capnp.affine+` — typed AffineScript +bindings for the UI layer (compiled to typed-wasm). *AffineScript is +banned estate-wide* — this was formerly listed as +`+bindings/affinescript/echidna_capnp.res+`; the destination is +AffineScript directly, not AffineScript. +* Keep the existing 3 API interfaces (GraphQL/gRPC/REST) as external +surfaces; Cap’n Proto is the *internal* wire format + +==== Tooling + +* `+just capnp-gen+` — regenerates Rust/Julia/Idris2/Zig/AffineScript +bindings from `+.capnp+` schemas +* CI check: `+capnp compile+` runs clean + generated code is committed + +=== Acceptance criteria + +* Zero `+serde_json::to_*+` / `+serde_json::from_*+` calls on the +Rust↔Julia hot path +* `+src/rust/gnn/client.rs+` uses UDS+Cap’n Proto +* Benchmarks: Cap’n Proto round-trip ≤ 50% of JSON latency for GNN rank +request +* Idris2 ABI compiles with zero `+believe_me+` +* Round-trip property tests on all six schemas (Rust, Julia, Idris2) +* `+schemas/VERSIONING.md+` explains migration story + +=== Open design questions to settle early + +[arabic] +. *UDS path convention* — `+/run/echidna/ipc.sock+` vs +`+$XDG_RUNTIME_DIR/echidna/ipc.sock+`? +. *Authentication* — initial handshake signed with existing +BLAKE3/SHAKE3-512 integrity keys? +. *Streaming vs request-response* — Cap’n Proto RPC streams for GNN +batch inference? +. *Multi-locale Chapel* — schemas need to survive locale-to-locale +transit; design for that now so L2 doesn’t re-spec. + +==== Resolved decisions + +* *Julia transport (was: "``+CapnProto.jl+` vs Zig C-ABI shim`", TODO.md +open Q#2)* — *RATIFIED 2026-05-18: Zig C-ABI shim, buffer-oriented.* +Estate-canonical (FFI=Zig; one codec shared with Rust; Zig = the +interface-safety transaction layer). `+CapnProto.jl+` rejected (low +maturity + second wire codec). This is gate-permitted spec/design; L1 +_implementation_ still waits on the L3 hand-off. +* Q1/Q3/Q4 above remain open (recommended defaults, pending +ratification): Q1 → `+$XDG_RUNTIME_DIR/echidna/ipc.sock+` with +`+/run/echidna/ipc.sock+` fallback; Q2 (auth) → yes, sign the handshake +with the existing SHAKE3-512 integrity keys (aligns with estate +interface-safety policy); Q3 → request-response first, streaming +deferred until a measured GNN-batch need; Q4 → frames carry an explicit +`+schemaVersion+`, locale-agnostic by construction (no host pointers on +the wire — Cap’n Proto already guarantees this). + +=== Hand to L2 when + +* Cap’n Proto is the default Rust↔Julia path +* `+ProverInvocation+` + `+TrustedOutcome+` schemas are stable (L2 +Chapel will consume them) +* Zig FFI bridge passes round-trip test + +''''' + +=== Rules active + +* `+no_json_emit_a2ml+` — the whole reason this phase exists +* `+feedback_verisimdb_policy+` — all IPC traffic should be observable +as VeriSimDB records +* `+feedback_code_only_grep_for_banned_patterns+` — when auditing for +`+serde_json+` removal, use code-only grep (`+^[^-|]*serde_json+`) to +avoid comment/doc noise +* `+feedback_wire_everything+` — no stubs; every schema has a live +consumer on all sides + +=== Key files to read first + +[arabic] +. `+~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md+` +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/rust/gnn/client.rs+` +(current JSON path) +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/julia/api_server.jl+` +(Julia server) +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/abi/*.idr+` +(existing Idris2 ABI) +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/zig_ffi/+` +(existing Zig FFI layer) diff --git a/docs/handover/L1-CAPNPROTO-PROMPT.md b/docs/handover/L1-CAPNPROTO-PROMPT.md deleted file mode 100644 index 6f7304ca..00000000 --- a/docs/handover/L1-CAPNPROTO-PROMPT.md +++ /dev/null @@ -1,116 +0,0 @@ -# Echidna L1 — Cap'n Proto Protocol Swap — Continuation Prompt - -**Context**: Echidna currently uses HTTP + JSON for Rust↔Julia (GNN inference) via -`src/rust/gnn/client.rs` → `src/julia/api_server.jl` port 8090. This violates the -`feedback_no_json_emit_a2ml` memory rule and blocks a clean polyglot IPC story. Swap to -**Cap'n Proto** (chosen over Bebop3 for dependability + maturity + zero-copy reads). - -**Master plan**: `~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md` -**Prerequisite**: L3 Tier-1 green for ≥7 days on main. -**Follows**: L2 (Chapel) consumes these schemas. - -## Deliverables - -### Schema -- `schemas/echidna.capnp` — canonical wire schemas: - - `ProofGoal` — a theorem/claim to prove - - `ProofResult` — success/failure + metadata - - `TacticSuggestion` — ML-suggested tactic - - `GnnRankRequest` / `GnnRankResponse` — replaces current HTTP+JSON - - `ProverInvocation` — dispatch message to a backend (used later by Chapel in L2) - - `TrustedOutcome` — post-trust-pipeline result -- `schemas/VERSIONING.md` — forward/backward compat rules - -### Rust side (hot-path consumer) -- `src/rust/ipc/mod.rs` — Cap'n Proto transport module -- `src/rust/ipc/uds.rs` — Unix-domain socket transport (primary) -- `src/rust/ipc/tcp.rs` — TCP transport (fallback for containerised cases) -- Replace `src/rust/gnn/client.rs` HTTP calls with Cap'n Proto over UDS -- Keep `serde_json` out of hot path; retain only for config/log emission (Nickel for config proper) - -### Julia side -- `src/julia/ipc.jl` — Cap'n Proto reader/writer -- **RATIFIED 2026-05-18: C-ABI shim through the existing Zig FFI layer** (NOT - `CapnProto.jl`). Buffer-oriented ABI — Julia hands the Zig layer opaque - Cap'n Proto frames; Zig owns parse/validate/gate. Rationale: estate-canonical - (FFI=Zig everywhere; single wire codec shared with Rust; the Zig layer is the - estate interface-safety transaction point). `CapnProto.jl` rejected: low - maturity + a second independent codec = wire-drift engine. See open-question - #2 resolution below. -- `src/julia/api_server.jl` — switch from HTTP to UDS listener - -### Idris2 ABI proofs -- `src/abi/CapnSchemas.idr` — formal proofs that schema round-trip preserves meaning -- Zero `believe_me` (per estate rule); constructive proofs only -- Coordinate with `src/abi/Types.idr` / `src/abi/Foreign.idr` - -### Zig FFI bridge -- `ffi/zig/capnp_bridge.zig` — C-ABI bridge for polyglot consumers (esp. Chapel in L2) - -### AffineScript bindings (UI path) -- `bindings/affinescript/echidna_capnp.affine` — typed AffineScript bindings for the - UI layer (compiled to typed-wasm). **AffineScript is banned estate-wide** — this was - formerly listed as `bindings/affinescript/echidna_capnp.res`; the destination is - AffineScript directly, not AffineScript. -- Keep the existing 3 API interfaces (GraphQL/gRPC/REST) as external surfaces; Cap'n Proto is the - **internal** wire format - -### Tooling -- `just capnp-gen` — regenerates Rust/Julia/Idris2/Zig/AffineScript bindings from `.capnp` schemas -- CI check: `capnp compile` runs clean + generated code is committed - -## Acceptance criteria - -- Zero `serde_json::to_*` / `serde_json::from_*` calls on the Rust↔Julia hot path -- `src/rust/gnn/client.rs` uses UDS+Cap'n Proto -- Benchmarks: Cap'n Proto round-trip ≤ 50% of JSON latency for GNN rank request -- Idris2 ABI compiles with zero `believe_me` -- Round-trip property tests on all six schemas (Rust, Julia, Idris2) -- `schemas/VERSIONING.md` explains migration story - -## Open design questions to settle early - -1. **UDS path convention** — `/run/echidna/ipc.sock` vs `$XDG_RUNTIME_DIR/echidna/ipc.sock`? -2. **Authentication** — initial handshake signed with existing BLAKE3/SHAKE3-512 integrity keys? -3. **Streaming vs request-response** — Cap'n Proto RPC streams for GNN batch inference? -4. **Multi-locale Chapel** — schemas need to survive locale-to-locale transit; design for that now - so L2 doesn't re-spec. - -### Resolved decisions - -- **Julia transport (was: "`CapnProto.jl` vs Zig C-ABI shim", TODO.md open Q#2)** - — **RATIFIED 2026-05-18: Zig C-ABI shim, buffer-oriented.** Estate-canonical - (FFI=Zig; one codec shared with Rust; Zig = the interface-safety transaction - layer). `CapnProto.jl` rejected (low maturity + second wire codec). This is - gate-permitted spec/design; L1 *implementation* still waits on the L3 hand-off. -- Q1/Q3/Q4 above remain open (recommended defaults, pending ratification): Q1 → - `$XDG_RUNTIME_DIR/echidna/ipc.sock` with `/run/echidna/ipc.sock` fallback; Q2 - (auth) → yes, sign the handshake with the existing SHAKE3-512 integrity keys - (aligns with estate interface-safety policy); Q3 → request-response first, - streaming deferred until a measured GNN-batch need; Q4 → frames carry an - explicit `schemaVersion`, locale-agnostic by construction (no host pointers - on the wire — Cap'n Proto already guarantees this). - -## Hand to L2 when - -- Cap'n Proto is the default Rust↔Julia path -- `ProverInvocation` + `TrustedOutcome` schemas are stable (L2 Chapel will consume them) -- Zig FFI bridge passes round-trip test - ---- - -## Rules active - -- `no_json_emit_a2ml` — the whole reason this phase exists -- `feedback_verisimdb_policy` — all IPC traffic should be observable as VeriSimDB records -- `feedback_code_only_grep_for_banned_patterns` — when auditing for `serde_json` removal, use - code-only grep (`^[^-|]*serde_json`) to avoid comment/doc noise -- `feedback_wire_everything` — no stubs; every schema has a live consumer on all sides - -## Key files to read first - -1. `~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md` -2. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/rust/gnn/client.rs` (current JSON path) -3. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/julia/api_server.jl` (Julia server) -4. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/abi/*.idr` (existing Idris2 ABI) -5. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/zig_ffi/` (existing Zig FFI layer) diff --git a/docs/handover/L2-CHAPEL-PROMPT.adoc b/docs/handover/L2-CHAPEL-PROMPT.adoc new file mode 100644 index 00000000..a613f291 --- /dev/null +++ b/docs/handover/L2-CHAPEL-PROMPT.adoc @@ -0,0 +1,132 @@ +== Echidna L2 — Chapel Maximum Integration — Continuation Prompt + +*Context*: Echidna has a 420-LoC Chapel POC +(`+chapel_poc/parallel_proof_search.chpl+`) that implements 30-prover +parallel portfolio dispatch but is *not wired into +`+src/rust/dispatch.rs+`*. User directive (2026-04-19): "`expand Chapel +to do EVERYTHING it can — no point investing in hard Chapel code and not +using it to maximum value.`" + +*Master plan*: `+~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md+` +*Prerequisites*: L3 Tier-1+Tier-2 green; L1 Cap’n Proto schemas stable. +*Scope*: ~5–6 weeks, broken into 7 sub-waves. + +''''' + +=== What Chapel is actually good at (the full opportunity) + +[arabic] +. *Task parallelism* (`+coforall+`, `+cobegin+`, `+begin+`) — parallel +prover dispatch, speculative tactic branches +. *Data parallelism* (`+forall+`) — corpus-wide premise scoring, tactic +mining +. *Distributed PGAS* (locales, on-clauses) — multi-node proof search +with sharded corpus +. *Domains & distributions* — data-dependent workload partitioning +. *Atomics* — first-wins racing, lock-free coordination +. *Reductions* — parallel statistics, confidence aggregation +. *GPU support* — Chapel-on-NVIDIA for embedding batches +. *NUMA awareness* — locale-aware dispatch on multi-socket machines + +=== Sub-wave breakdown + +==== L2.1 — Portfolio dispatch (promote POC) ~1 week + +* `+src/chapel/portfolio.chpl+` — migrate + adapt from +`+chapel_poc/parallel_proof_search.chpl+` +* Input: Cap’n Proto `+ProverInvocation+` batch (from L1) +* Output: Cap’n Proto `+TrustedOutcome[]+` +* Race semantics: atomic first-wins, SIGKILL losers, cancellation within +`+timeout+` +* Wire into `+src/rust/dispatch.rs+` behind `+--chapel+` feature flag +via Zig FFI +* Default: feature-off; default-on flip after L2.7 benchmarks + +==== L2.2 — Speculative tactic search ~1 week + +* `+src/chapel/tactic_search.chpl+` +* Parallel beam search (k parallel beams) +* Parallel MCTS over tactic trees (UCB1 selection with `+coforall+` +rollouts) +* Speculative branch execution + cancellation on winner commit +* Consumes `+TacticSuggestion+` stream from GNN (L1 schemas) + +==== L2.3 — Corpus-parallel ops ~1 week + +* `+src/chapel/corpus.chpl+` +* `+forall+` over 66,674-proof corpus +* Parallel proof replay (re-verify corpus) +* Parallel premise scoring (vs GNN rankings) +* Parallel tactic mining + inverted index build +* Locality-aware: `+forall ... with (ref corpusShard)+` to avoid +cross-locale traffic + +==== L2.4 — Mutation testing parallelism ~3 days + +* `+src/chapel/mutation.chpl+` +* Fan out 1000s of mutants across all cores/locales +* Integrate with existing Rust `+verification/mutation.rs+` (consume its +mutant stream, run in Chapel) + +==== L2.5 — Multi-locale distributed ~1.5 weeks + +* PGAS-sharded corpus across locales (`+Block+` or `+Cyclic+` +distribution) +* Locale-aware prover dispatch: heavy backends on dedicated locales +* GPU-locale offload: embedding batches on NVIDIA locale if present +* Reproducibility: locale seed propagation +* Single-locale covers 80% of value; multi-locale proven on dev hardware + +==== L2.6 — Numeric hot paths ~4 days + +* `+src/chapel/numeric.chpl+` +* Parallel GNN embedding pre-processing (batch pack + pad) +* Parallel Pareto frontier computation (`+forall+` + atomic minimum +tracking) +* Parallel confidence statistics / Bayesian timeout updates + +==== L2.7 — CI + bench ~3 days + +* `+.github/workflows/chapel-live.yml+` — runs Chapel-in-dispatch tests +* Criterion benchmarks: Chapel portfolio vs Rust+Rayon baseline +* Must show measurable speedup on 8+ core machines to flip default-on + +=== Acceptance criteria + +* Chapel on hot path by default after benchmarks prove it +* `+src/chapel/+` has 6+ modules wired via Zig FFI + Cap’n Proto +* `+chapel_poc/+` archived (or deleted) with redirect note in its README +* Multi-locale path proven on at least one dev-hardware config +* Benchmarks show ≥1.5× speedup for portfolio solving on 8-core machines +(or Chapel stays feature-flagged) +* No Rust code duplicates what Chapel does best (avoid double-paths) + +''''' + +=== Rules active + +* `+feedback_wire_everything+` — no stubs; POC promoted fully, not +re-implemented +* `+feedback_meander_resource_costs+` — Chapel builds slow; cache Chapel +artefacts in CI, clean after +* `+feedback_rust_means_rust_spark+` — Rust side admits SPARK/Ada; +Chapel doesn’t change that +* `+feedback_verisimdb_policy+` — Chapel-dispatched runs still emit +VeriSimDB records (via Cap’n Proto back-channel to Rust) +* `+feedback_full_battery_before_claims+` — before claiming speedup, +full battery: tests + benches + panic-attack + causality + verifiable +I/O + +=== Key files to read first + +[arabic] +. `+~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md+` +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/chapel_poc/parallel_proof_search.chpl+` +(420-LoC POC to promote) +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/zig_ffi/chapel_bridge.zig+` +(existing Zig FFI stub) +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/rust/dispatch.rs+` +(integration target) +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/.github/workflows/chapel-ci.yml+` +(current Chapel CI for compile-only) +. `+schemas/echidna.capnp+` (must exist from L1 — if not, L1 isn’t done) diff --git a/docs/handover/L2-CHAPEL-PROMPT.md b/docs/handover/L2-CHAPEL-PROMPT.md deleted file mode 100644 index 909b74d8..00000000 --- a/docs/handover/L2-CHAPEL-PROMPT.md +++ /dev/null @@ -1,101 +0,0 @@ -# Echidna L2 — Chapel Maximum Integration — Continuation Prompt - -**Context**: Echidna has a 420-LoC Chapel POC (`chapel_poc/parallel_proof_search.chpl`) that implements -30-prover parallel portfolio dispatch but is **not wired into `src/rust/dispatch.rs`**. User directive -(2026-04-19): "expand Chapel to do EVERYTHING it can — no point investing in hard Chapel code and not -using it to maximum value." - -**Master plan**: `~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md` -**Prerequisites**: L3 Tier-1+Tier-2 green; L1 Cap'n Proto schemas stable. -**Scope**: ~5–6 weeks, broken into 7 sub-waves. - ---- - -## What Chapel is actually good at (the full opportunity) - -1. **Task parallelism** (`coforall`, `cobegin`, `begin`) — parallel prover dispatch, speculative tactic branches -2. **Data parallelism** (`forall`) — corpus-wide premise scoring, tactic mining -3. **Distributed PGAS** (locales, on-clauses) — multi-node proof search with sharded corpus -4. **Domains & distributions** — data-dependent workload partitioning -5. **Atomics** — first-wins racing, lock-free coordination -6. **Reductions** — parallel statistics, confidence aggregation -7. **GPU support** — Chapel-on-NVIDIA for embedding batches -8. **NUMA awareness** — locale-aware dispatch on multi-socket machines - -## Sub-wave breakdown - -### L2.1 — Portfolio dispatch (promote POC) ~1 week -- `src/chapel/portfolio.chpl` — migrate + adapt from `chapel_poc/parallel_proof_search.chpl` -- Input: Cap'n Proto `ProverInvocation` batch (from L1) -- Output: Cap'n Proto `TrustedOutcome[]` -- Race semantics: atomic first-wins, SIGKILL losers, cancellation within `timeout` -- Wire into `src/rust/dispatch.rs` behind `--chapel` feature flag via Zig FFI -- Default: feature-off; default-on flip after L2.7 benchmarks - -### L2.2 — Speculative tactic search ~1 week -- `src/chapel/tactic_search.chpl` -- Parallel beam search (k parallel beams) -- Parallel MCTS over tactic trees (UCB1 selection with `coforall` rollouts) -- Speculative branch execution + cancellation on winner commit -- Consumes `TacticSuggestion` stream from GNN (L1 schemas) - -### L2.3 — Corpus-parallel ops ~1 week -- `src/chapel/corpus.chpl` -- `forall` over 66,674-proof corpus -- Parallel proof replay (re-verify corpus) -- Parallel premise scoring (vs GNN rankings) -- Parallel tactic mining + inverted index build -- Locality-aware: `forall ... with (ref corpusShard)` to avoid cross-locale traffic - -### L2.4 — Mutation testing parallelism ~3 days -- `src/chapel/mutation.chpl` -- Fan out 1000s of mutants across all cores/locales -- Integrate with existing Rust `verification/mutation.rs` (consume its mutant stream, run in Chapel) - -### L2.5 — Multi-locale distributed ~1.5 weeks -- PGAS-sharded corpus across locales (`Block` or `Cyclic` distribution) -- Locale-aware prover dispatch: heavy backends on dedicated locales -- GPU-locale offload: embedding batches on NVIDIA locale if present -- Reproducibility: locale seed propagation -- Single-locale covers 80% of value; multi-locale proven on dev hardware - -### L2.6 — Numeric hot paths ~4 days -- `src/chapel/numeric.chpl` -- Parallel GNN embedding pre-processing (batch pack + pad) -- Parallel Pareto frontier computation (`forall` + atomic minimum tracking) -- Parallel confidence statistics / Bayesian timeout updates - -### L2.7 — CI + bench ~3 days -- `.github/workflows/chapel-live.yml` — runs Chapel-in-dispatch tests -- Criterion benchmarks: Chapel portfolio vs Rust+Rayon baseline -- Must show measurable speedup on 8+ core machines to flip default-on - -## Acceptance criteria - -- Chapel on hot path by default after benchmarks prove it -- `src/chapel/` has 6+ modules wired via Zig FFI + Cap'n Proto -- `chapel_poc/` archived (or deleted) with redirect note in its README -- Multi-locale path proven on at least one dev-hardware config -- Benchmarks show ≥1.5× speedup for portfolio solving on 8-core machines (or Chapel stays feature-flagged) -- No Rust code duplicates what Chapel does best (avoid double-paths) - ---- - -## Rules active - -- `feedback_wire_everything` — no stubs; POC promoted fully, not re-implemented -- `feedback_meander_resource_costs` — Chapel builds slow; cache Chapel artefacts in CI, clean after -- `feedback_rust_means_rust_spark` — Rust side admits SPARK/Ada; Chapel doesn't change that -- `feedback_verisimdb_policy` — Chapel-dispatched runs still emit VeriSimDB records (via Cap'n Proto - back-channel to Rust) -- `feedback_full_battery_before_claims` — before claiming speedup, full battery: tests + benches + - panic-attack + causality + verifiable I/O - -## Key files to read first - -1. `~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md` -2. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/chapel_poc/parallel_proof_search.chpl` (420-LoC POC to promote) -3. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/zig_ffi/chapel_bridge.zig` (existing Zig FFI stub) -4. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/rust/dispatch.rs` (integration target) -5. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/.github/workflows/chapel-ci.yml` (current Chapel CI for compile-only) -6. `schemas/echidna.capnp` (must exist from L1 — if not, L1 isn't done) diff --git a/docs/handover/L3-LIVE-PROVER-CI-PROMPT.adoc b/docs/handover/L3-LIVE-PROVER-CI-PROMPT.adoc new file mode 100644 index 00000000..564afe9e --- /dev/null +++ b/docs/handover/L3-LIVE-PROVER-CI-PROMPT.adoc @@ -0,0 +1,114 @@ +== Echidna L3 — Live-Prover CI — Continuation Prompt + +*Context*: Echidna +(`+/var/mnt/eclipse/repos/verification-ecosystem/echidna/+`) has 48 +trait-wired prover backends, but CI only tests them with `+MockProver+`. +Mission: make every provisionable backend run against a canonical +micro-goal on a predictable cadence. Guix sole primary (guix deprecated +estate-wide 2026-06-01). + +*Master plan*: `+~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md+` *Order*: +L3 (this) → L1 (Cap’n Proto) → L2 (Chapel max). + +''''' + +=== Where L3 is when this prompt fires + +Wave-1 (Tier-1, every PR — 9 backends) DONE in kickoff session, commit +`+b022bf4+`: - `+manifests/live-provers.scm+` — Guix manifest with +Tier-1 + Tier-2 provers - ~`+flake.guix+` — expanded with matching +`+liveProverDeps+`~ (removed 2026-06-01 per estate-wide +guix-deprecation) - `+.github/workflows/live-provers.yml+` — tiered +workflow (Tier-1 PR, Tier-2 nightly, etc.) - +`+tests/live_prover_suite.rs+` — Rust test harness with Tier-1 +version-check tests + +Wave-2 (Tier-2, nightly — 10 backends) *DONE 2026-04-19* in commits +`+9a4aeeb+` + `+6717b12+`: - Real provisioning commands for coq, agda, +why3 (apt); idris2 (source bootstrap against Chez Scheme); lean4 (elan); +isabelle (Isabelle2024 tarball); dafny +(`+dotnet tool install --global Dafny+`); fstar (GitHub release tarball, +binary `+fstar.exe+`); tlaps (self-extracting installer for `+tlapm+`). +- `+hol-light+` *deferred* to Wave-3 container path — no prebuilt binary +and opam build is ~20 min + camlp5. - `+tests/live_prover_suite.rs+` +extended with `+live_fstar_version+` + `+live_tlaps_version+`. - Local +verification (not CI yet): 18/18 tests pass, 13 backends return real +versions, 5 auto-skip when binaries are absent. + +`+tests/live_goals/+` was listed in the handover-artefacts but not +actually created. Wave-2 version-check tests do not need it; Wave-2 / +Wave-3 goal-check extensions will. + +=== What to finish in L3 (remaining) + +==== Wave-2 verification in CI (not just local) + +The Wave-2 provisioning installers are not yet exercised by a real CI +run — nightly needs to fire (cron `+0 3 * * *+`) to surface any +CI-specific breakage (apt mirror changes, GitHub release URL format +drift, dotnet sdk availability, etc.). Watch the next nightly after +merge; fix any red matrix cells in-place. + +==== Wave-3: Tier-3 backends (Weekly) + +Container/special-env path: Tamarin, ProVerif, Imandra, SCIP, OR-Tools, +HOL4, ACL2, Twelf, Metamath. These likely need per-backend +Containerfiles (Podman, not Docker — per project CLAUDE.md). + +==== Wave-4: Tier-4 backends (Quarterly, allow-fail) + +Best-effort: Mizar, Nuprl, PVS, Minlog, Dedukti, Arend, KeY, Prism, +UPPAAL, ViPER, NuSMV, Spin, TLC, CBMC, Seahorn, dReal, Boogie, Kissat, +Alloy. Many will stay mock-only (document why). + +==== Harden wiring depth for shallow backends + +Audit flagged *Dafny (165 LoC)* as stub-ish — upgrade to deep during L3 +so the live test isn’t measuring a broken subprocess wrapper. + +==== VeriSimDB integration + +Per `+feedback_verisimdb_policy+`: the live-prover harness should emit a +VeriSimDB record per run (prover, goal, outcome, duration, exit code). +Schema TBD — coordinate with VeriSimDB repo. + +=== Acceptance for L3 complete + +* Tier-1 green on every PR +* Tier-2 green on nightly (or documented flaky backends with +`+continue-on-error: true+`) +* Tier-3 runs weekly with per-backend allow-fail +* Tier-4 runs quarterly, results archived +* Dafny upgraded from 165 LoC stub to deep subprocess wiring +* `+guix shell -m manifests/live-provers.scm -- just test-live+` works +locally +* VeriSimDB records emitted (if schema ready) +* Mock tests retained as fast pre-CI smoke + +=== Hand to L1 when + +* All four waves land or are explicitly deferred with rationale in +STATE.a2ml +* Tier-1 has run green on main for ≥7 days + +''''' + +=== Rules active in this session + +* GitHub-only mirroring (per memory `+feedback_github_only_mirroring+`) +* Commit ASAP, specific paths (`+feedback_commit_asap+`) +* Pre-commit: `+panic-attack assail+` +(`+feedback_panic_attack_precommit+`) +* No `+.unwrap() → .expect("TODO")+` refactor +(`+feedback_unwrap_to_expect_antipattern+`) +* Session close marker: `+SAFE TO CLOSE+` literal at end of final +message + +=== Key files to read first + +[arabic] +. `+~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md+` +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/.machine_readable/descriptiles/STATE.a2ml+` +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/manifests/live-provers.scm+` +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/.github/workflows/live-provers.yml+` +. `+/var/mnt/eclipse/repos/verification-ecosystem/echidna/tests/live_prover_suite.rs+` diff --git a/docs/handover/L3-LIVE-PROVER-CI-PROMPT.md b/docs/handover/L3-LIVE-PROVER-CI-PROMPT.md deleted file mode 100644 index e8d27006..00000000 --- a/docs/handover/L3-LIVE-PROVER-CI-PROMPT.md +++ /dev/null @@ -1,90 +0,0 @@ -# Echidna L3 — Live-Prover CI — Continuation Prompt - -**Context**: Echidna (`/var/mnt/eclipse/repos/verification-ecosystem/echidna/`) has 48 trait-wired -prover backends, but CI only tests them with `MockProver`. Mission: make every provisionable -backend run against a canonical micro-goal on a predictable cadence. Guix sole primary (guix deprecated estate-wide 2026-06-01). - -**Master plan**: `~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md` -**Order**: L3 (this) → L1 (Cap'n Proto) → L2 (Chapel max). - ---- - -## Where L3 is when this prompt fires - -Wave-1 (Tier-1, every PR — 9 backends) DONE in kickoff session, commit `b022bf4`: -- `manifests/live-provers.scm` — Guix manifest with Tier-1 + Tier-2 provers -- ~`flake.guix` — expanded with matching `liveProverDeps`~ (removed 2026-06-01 per estate-wide guix-deprecation) -- `.github/workflows/live-provers.yml` — tiered workflow (Tier-1 PR, Tier-2 nightly, etc.) -- `tests/live_prover_suite.rs` — Rust test harness with Tier-1 version-check tests - -Wave-2 (Tier-2, nightly — 10 backends) **DONE 2026-04-19** in commits `9a4aeeb` + `6717b12`: -- Real provisioning commands for coq, agda, why3 (apt); idris2 (source bootstrap - against Chez Scheme); lean4 (elan); isabelle (Isabelle2024 tarball); dafny - (`dotnet tool install --global Dafny`); fstar (GitHub release tarball, binary - `fstar.exe`); tlaps (self-extracting installer for `tlapm`). -- `hol-light` **deferred** to Wave-3 container path — no prebuilt binary and opam - build is ~20 min + camlp5. -- `tests/live_prover_suite.rs` extended with `live_fstar_version` + `live_tlaps_version`. -- Local verification (not CI yet): 18/18 tests pass, 13 backends return real versions, - 5 auto-skip when binaries are absent. - -`tests/live_goals/` was listed in the handover-artefacts but not actually created. -Wave-2 version-check tests do not need it; Wave-2 / Wave-3 goal-check extensions will. - -## What to finish in L3 (remaining) - -### Wave-2 verification in CI (not just local) -The Wave-2 provisioning installers are not yet exercised by a real CI run — -nightly needs to fire (cron `0 3 * * *`) to surface any CI-specific breakage -(apt mirror changes, GitHub release URL format drift, dotnet sdk availability, -etc.). Watch the next nightly after merge; fix any red matrix cells in-place. - -### Wave-3: Tier-3 backends (Weekly) -Container/special-env path: Tamarin, ProVerif, Imandra, SCIP, OR-Tools, HOL4, ACL2, Twelf, Metamath. -These likely need per-backend Containerfiles (Podman, not Docker — per project CLAUDE.md). - -### Wave-4: Tier-4 backends (Quarterly, allow-fail) -Best-effort: Mizar, Nuprl, PVS, Minlog, Dedukti, Arend, KeY, Prism, UPPAAL, ViPER, NuSMV, Spin, -TLC, CBMC, Seahorn, dReal, Boogie, Kissat, Alloy. Many will stay mock-only (document why). - -### Harden wiring depth for shallow backends -Audit flagged **Dafny (165 LoC)** as stub-ish — upgrade to deep during L3 so the live test isn't -measuring a broken subprocess wrapper. - -### VeriSimDB integration -Per `feedback_verisimdb_policy`: the live-prover harness should emit a VeriSimDB record per run -(prover, goal, outcome, duration, exit code). Schema TBD — coordinate with VeriSimDB repo. - -## Acceptance for L3 complete - -- Tier-1 green on every PR -- Tier-2 green on nightly (or documented flaky backends with `continue-on-error: true`) -- Tier-3 runs weekly with per-backend allow-fail -- Tier-4 runs quarterly, results archived -- Dafny upgraded from 165 LoC stub to deep subprocess wiring -- `guix shell -m manifests/live-provers.scm -- just test-live` works locally -- VeriSimDB records emitted (if schema ready) -- Mock tests retained as fast pre-CI smoke - -## Hand to L1 when - -- All four waves land or are explicitly deferred with rationale in STATE.a2ml -- Tier-1 has run green on main for ≥7 days - ---- - -## Rules active in this session - -- GitHub-only mirroring (per memory `feedback_github_only_mirroring`) -- Commit ASAP, specific paths (`feedback_commit_asap`) -- Pre-commit: `panic-attack assail` (`feedback_panic_attack_precommit`) -- No `.unwrap() → .expect("TODO")` refactor (`feedback_unwrap_to_expect_antipattern`) -- Session close marker: `SAFE TO CLOSE` literal at end of final message - -## Key files to read first - -1. `~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md` -2. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/.machine_readable/descriptiles/STATE.a2ml` -3. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/manifests/live-provers.scm` -4. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/.github/workflows/live-provers.yml` -5. `/var/mnt/eclipse/repos/verification-ecosystem/echidna/tests/live_prover_suite.rs` diff --git a/docs/handover/PHASE-3-PROMPT.adoc b/docs/handover/PHASE-3-PROMPT.adoc new file mode 100644 index 00000000..ca34b4df --- /dev/null +++ b/docs/handover/PHASE-3-PROMPT.adoc @@ -0,0 +1,308 @@ +== Echidna Phase 3 — Real-Algebraic + Modal/Hybrid Backends — Opus Handoff Prompt + +*Context*: Phase 3 of the ECHIDNA expansion is the *architecturally +trickiest* of the three remaining phases. Unlike Phases 2B and 4, where +the backends are mostly subprocess CAS shells or DL/probabilistic +solvers with familiar shapes, Phase 3 brings in _differential dynamic +logic_, _cylindrical algebraic decomposition_, _Reduce-CAS shims_, +_connection-method intuitionistic / modal_, and _tableau generators for +arbitrary modal logics_. Per the *ECHIDNA-EXPANSION-TOMORROW-2026-04-28* +plan: "`Don’t farm these out. Pick a 2-3 hour midweek slot and ask Opus +to do them solo. Each is ~250 LOC but the semantics matter.`" + +This document is *that brief*. It locks the design for all 7 remaining +Phase 3 backends, names the worked example already landed +(`+keymaerax.rs+`), and gives the next Opus session a step-by-step path +to closing the phase. + +*Master plan*: `+~/Desktop/ECHIDNA-EXPANSION-TOMORROW-2026-04-28.md+` +*Reference doc*: `+docs/ROADMAP.md+` row "`Every important solver`" +*Status as of 2026-04-27*: KeYmaera X *landed* in +`+src/rust/provers/keymaerax.rs+` (8/8 tests passing); 6 backends +remain. + +=== Status table + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Backend |Status |LOC |Notes +|*KeYmaera X* (dDL / hybrid systems) |✅ landed 2026-04-27 |313 |Worked +example for this brief + +|*QEPCAD-B* (cylindrical algebraic decomposition) |🟡 open |~250 |CAD +input format + +|*Redlog* (Reduce-CAS frontend, real algebra) |🟡 open |~250 |Reduce +shim + real-quantifier elim + +|*MleanCoP* (connection-method intuitionistic) |🟡 open |~250 +|Prolog-based, esoteric output + +|*ileanCoP* (intuitionistic leanCoP variant) |🟡 open |~250 |Shares +parser with MleanCoP + +|*nanoCoP* (lean-er connection prover) |🟡 open |~250 |Same family as +above + +|*MetTeL2* (tableau generator for modal logics) |🟡 open |~250 |JVM, +configuration-heavy +|=== + +Total expected: ~1500 LOC + tests for the 6 remaining. + +=== Architectural patterns (per-backend semantics) + +==== KeYmaera X (✅ already done — worked example) + +* *Input format*: `+.kyx+` archive entries with hybrid programs. +* *Output*: stdout/stderr scan for `+proved+` / `+closed+` / `+qed+` +(closed) vs `+open subgoals+` / `+failed+` / `+untrusted+` (open or +refuted). +* *Trust tier*: 2 (delegates QE to external CAS — Mathematica/Z3/Polya). +* *FFI u8*: 128. +* *Reference*: `+src/rust/provers/keymaerax.rs+`. Use this as the +template for the remaining six. + +==== QEPCAD-B (CAD) + +* *Input*: prefixed-formula syntax for real-quantifier elimination +problems. Header with variable order, then +`+(quantifier x)[ formula ]+`. +* *CLI invocation*: stdin-driven REPL; backends typically pipe the +QEPCAD input followed by `+finish+` to flush. +* *Output*: prints either +`+Equivalent quantifier-free formula: +` (success) or error / +`+unable to compute+`. Consider formula `+True+` / `+False+` as +`+verify_proof+` outcome. +* *Trust tier*: 2 (CAD result is sound but the implementation is large; +no external proof certificate). +* *Hazard*: very long runtimes for formulae with > 4 variables; honour +the timeout aggressively. + +==== Redlog (REDUCE-CAS frontend) + +* *Input*: REDUCE-CAS surface syntax — `+rlqe formula;+` for QE, +`+rlcad+` for CAD-based decision, etc. Statements terminated with `+;+` +or `+$+` (silent). +* *CLI invocation*: spawn `+redcsl+` (CSL build of Reduce) or +`+redpsl+`, feed the Redlog `+load_package redlog;+` then the goal, read +stdout. +* *Output*: scan for `+true+`, `+false+`, or a residual quantifier-free +formula. `+true+` → `+verify_proof+` returns `+Ok(true)+`; everything +else either `+Ok(false)+` or `+Err+`. +* *Trust tier*: 2 (parallel to QEPCAD). +* *Hazard*: Reduce sometimes prints leading whitespace and +`+END OF FILE+` markers. Strip carefully. + +==== MleanCoP / ileanCoP / nanoCoP (connection-method) + +These three share a parser and CLI shape; implement them as *three +backend files* but factor common helpers into a private +`+connection_method.rs+` module if the duplication exceeds ~30 LOC. + +* *Input*: TPTP CNF/FOF (MleanCoP) or intuitionistic / modal variants +(ileanCoP, nanoCoP). +* *CLI invocation*: Prolog-driven; typical call is +`+swipl -g "leancop:prove('input.p')" -t halt+`. Variants differ in the +`+prove/1+` predicate name. +* *Output*: lines like `+% SZS status Theorem+` / +`+% SZS status CounterSatisfiable+` / `+% SZS status GaveUp+` (when the +upstream uses TPTP-style SZS) OR plain `++ matrix proof found+` (when in +native mode). +* *Trust tier*: 2 for MleanCoP (classical), 3 for ileanCoP +(intuitionistic kernel is small — connection method) and nanoCoP +(similarly small kernel). +* *Hazard*: Prolog stack overflow on goals with deep unification — bound +the heap with `+--stack-limit=256m+`. + +==== MetTeL2 (tableau generator) + +* *Input*: a tableau *specification* (logic axioms in MetTeL’s syntax) +plus a goal formula. Different from a one-shot prover — MetTeL2 +generates a tableau prover _for_ the supplied logic, then uses it. We +only support the "`use the bundled standard logics`" path for v1 (S4, K, +KT, KD45, …). +* *CLI invocation*: +`+java -jar mettel2.jar -s .spec -i .mt+` (typical). +Wrap with `+-version+` probe. +* *Output*: `+Provable.+` / `+Not provable.+` / `+Unknown.+` (tableau +open). +* *Trust tier*: 2 — the generated tableau prover is correct by +construction, but we don’t formally check the spec. +* *Hazard*: JVM cold-start latency. Cache the JVM via `+--keep-alive+` +if benchmark numbers ask for it later. + +=== What "`landed`" looks like (using KeYmaera X as the template) + +For each backend, you produce: + +[arabic] +. *Backend file* at `+src/rust/provers/.rs+`. Mirror +`+keymaerax.rs+`: +* Crate-level `+//!+` doc explaining _why this backend exists_ and the +_input format / output parsing_. +* Module-level `+#![allow(dead_code)]+` (warranted: tests are gated by +`+#[cfg(test)]+`). +* `+pub struct Backend { config: ProverConfig }+`. +* `+impl Backend { new, to_, parse_result }+`. +* `+#[async_trait] impl ProverBackend for Backend+` — `+kind+`, +`+version+`, `+parse_file+`, `+parse_string+`, `+apply_tactic+` (return +`+anyhow::anyhow!(... not supported ...)+` if non-interactive), +`+verify_proof+`, `+export+`, `+suggest_tactics+` (return `+Ok(vec![])+` +for v1), `+search_theorems+` (return `+Ok(vec![])+`), `+config+`, +`+set_config+`. +* `+#[cfg(test)] mod tests+` with at minimum: `+_kind+`, +`+_to__basic+`, `+_parse_result_proved+`, +`+_parse_result_failed+`, `+_parse_result_inconclusive+`. +. *mod.rs wiring* — add the backend at all 10 integration points. Use +`+keymaerax+` as the search anchor for each: +[arabic] +.. `+pub mod ;+` at the top of `+mod.rs+` (~line 70). +.. `++` variant in the `+ProverKind+` enum. +.. Match arm in the name parser +(`+"" | "" => Ok(ProverKind::)+`). +.. `+ProverKind::,+` in the `+all()+` list (~line 700). +.. `+ProverKind:: => ,+` in the complexity table +(~line 800). +.. `+ProverKind:: => ,+` in the trust tier table (~line +960). +.. `+ProverKind:: => ,+` in the ML guidance table (~line +1090). +.. `+ProverKind:: => "",+` in the binary-name table (~line +1224). +.. `+ProverKind:: => Ok(Box::new(::Backend::new(config))),+` +in the factory dispatch (~line 1614). +.. *FFI: u8 mapping at `+src/rust/ffi/mod.rs+`* — add +`+ => Some(ProverKind::),+` to `+kind_from_u8+` and +`+ProverKind:: => ,+` to `+kind_to_u8+`. KeYmaera X took slot +128; the remaining six get 129..134 in the order: QEPCAD-B (129), Redlog +(130), MleanCoP (131), ileanCoP (132), nanoCoP (133), MetTeL2 (134). +MetiTarski is already at its existing slot — do not renumber existing +entries. +. *Tests* — at minimum 8 unit tests per backend (the count +`+keymaerax.rs+` ships). Pattern after the `+keymaerax::tests+` block. +. *Acceptance gate*: `+cargo build --lib+` clean (no new warnings beyond +the pre-existing four), `+cargo test --lib +` passes 100%, +`+cargo test --lib+` overall green. + +=== Sequencing recommendation + +The six remaining backends differ wildly in semantics. Suggested order — +*easiest first* (sets up the dispatch wiring once, then the harder ones +reuse it): + +[arabic] +. *QEPCAD-B* — clean CAD input, well-documented stdout markers. +. *Redlog* — same shape as QEPCAD but uses Reduce CSL; reuse subprocess +pattern. +. *MetTeL2* — JVM call, simple stdout parse. +. *MleanCoP* — Prolog binding, TPTP I/O. +. *ileanCoP* — share helpers with MleanCoP; intuitionistic nuances in +`+parse_result+`. +. *nanoCoP* — share helpers with the leanCoP family; lighter tactic +surface. + +Budget ~30 minutes per backend file + ~15 minutes for the 10 integration +points + ~15 minutes for tests + verification = 1 hour per backend. +Whole phase: 6 hours. Don’t try to compress; semantics matter. + +=== Per-backend FFI u8 reservations + +Already fixed in mod.rs/ffi.rs. Repeat here so a future Opus session +doesn’t have to re-derive them: + +[cols=",",options="header",] +|=== +|Backend |FFI u8 +|KeYmaera X |128 +|QEPCAD-B |129 +|Redlog |130 +|MleanCoP |131 +|ileanCoP |132 +|nanoCoP |133 +|MetTeL2 |134 +|=== + +=== Acceptance criteria for the _phase_ + +[arabic] +. All 6 remaining backend files exist under `+src/rust/provers/+`. +. `+cargo build --lib+` clean (0 errors, no new warnings). +. `+cargo test --lib+` passes (every existing test green plus ≥ 6 × 8 = +48 new backend tests). +. `+provers/mod.rs+` `+all()+` list contains all 7 Phase 3 backends. +. Each backend’s `+verify_proof+` calls the upstream binary with the +correct flag — gated such that *missing binary returns a structured +error*, not a panic. (KeYmaera X already does this via +`+Command::spawn().context(...)+`.) +. `+docs/ROADMAP.md+` row "`Every important solver`" updated with the +new ProverKind count (currently 128 → 134 after Phase 3 closes). +. `+PROOF-NEEDS.md+` and `+.machine_readable/descriptiles/STATE.a2ml+` +reflect the closure of Phase 3. + +=== Non-goals + +* *No upstream binary provisioning.* The CI containers don’t have +KeYmaera X, QEPCAD-B, Redlog, leanCoP family, or MetTeL2 installed; +integration tests gated by `+#[cfg(feature = "-real")]+` are out +of scope here. Document the gap. +* *No Bellerophon / leanCoP tactic-language dispatch.* All Phase 3 +backends route through `+verify_proof+` only; interactive +`+apply_tactic+` returns the "`not supported`" error per the KeYmaera X +pattern. +* *No GNN integration for these backends.* The GNN ranking layer (§4.4 +of ECHIDNA-NOTES) is a separate phase; Phase 3 `+suggest_tactics+` +returns `+Ok(vec![])+`. +* *No formal proofs of `+verify_proof+` correctness for Phase 3.* These +are dispatch-only backends; their outputs feed the +`+compute_trust_level+` pipeline at most. Trust tier 2 is the ceiling +without certificate output. + +=== Test fixtures (where they should live) + +For each backend, add a tiny `+tests/fixtures//+` directory +containing 2-3 `+.kyx+` / `+.qep+` / `+.red+` / `+.p+` / `+.mt+` example +problems lifted from the upstream documentation. These are _not_ loaded +in the unit tests (which use string literals); they exist for +hand-running `+echidna prove+` against a local install during +development. + +=== What you (Opus, future session) should NOT do + +* *Do not implement Bellerophon / leanCoP tactic compilation* inside the +backend file. That is a separate ~1500 LOC project per the ECHIDNA-NOTES +§4.1 design. +* *Do not add upstream-binary auto-detection logic* to mod.rs. Keep the +binary-name table simple; deployment-time configuration handles binary +location. +* *Do not modify the trust pipeline* (`+src/rust/dispatch.rs+`, +`+verification/+`) to "`support`" the new backends. They plug in through +the existing `+ProverBackend+` trait; no pipeline edit should be +necessary. +* *Do not break MetiTarski*. It’s already shipped (Phase 1B, cbd9449); +it stays at trust tier 2 / FFI slot whatever it has. Don’t reshuffle +existing FFI numbers. + +=== How to verify phase completion (5-minute sanity check) + +[source,bash] +---- +cd /var/mnt/eclipse/repos/echidna +cargo build --lib # 0 errors +cargo test --lib qepcad redlog mleancop ileancop nanocop mettel2 keymaerax \ + # all green +grep -c "ProverKind::" src/rust/provers/mod.rs # should rise by 6 +git log --oneline | head -10 # 6 fresh feat() commits +---- + +=== Tracking + +* This brief: `+docs/handover/PHASE-3-PROMPT.md+` +* Master plan: `+~/Desktop/ECHIDNA-EXPANSION-TOMORROW-2026-04-28.md+` +* Worked example: `+src/rust/provers/keymaerax.rs+` (committed +2026-04-27) +* Companion handoff: `+docs/handover/SUGGEST-CLI-PROMPT.md+` (the +§4.1/4.3 mechanical-baseline brief from the same session) + +When Phase 3 closes, update this file’s status table to all-green, move +the doc to `+docs/handover/archived/+`, and link the closing commits. diff --git a/docs/handover/PHASE-3-PROMPT.md b/docs/handover/PHASE-3-PROMPT.md deleted file mode 100644 index 48c39ecc..00000000 --- a/docs/handover/PHASE-3-PROMPT.md +++ /dev/null @@ -1,293 +0,0 @@ - -# Echidna Phase 3 — Real-Algebraic + Modal/Hybrid Backends — Opus Handoff Prompt - -**Context**: Phase 3 of the ECHIDNA expansion is the -**architecturally trickiest** of the three remaining phases. Unlike -Phases 2B and 4, where the backends are mostly subprocess CAS shells -or DL/probabilistic solvers with familiar shapes, Phase 3 brings in -*differential dynamic logic*, *cylindrical algebraic decomposition*, -*Reduce-CAS shims*, *connection-method intuitionistic / modal*, and -*tableau generators for arbitrary modal logics*. Per the -**ECHIDNA-EXPANSION-TOMORROW-2026-04-28** plan: "Don't farm these -out. Pick a 2-3 hour midweek slot and ask Opus to do them solo. Each -is ~250 LOC but the semantics matter." - -This document is **that brief**. It locks the design for all 7 -remaining Phase 3 backends, names the worked example already landed -(`keymaerax.rs`), and gives the next Opus session a step-by-step path -to closing the phase. - -**Master plan**: `~/Desktop/ECHIDNA-EXPANSION-TOMORROW-2026-04-28.md` -**Reference doc**: `docs/ROADMAP.md` row "Every important solver" -**Status as of 2026-04-27**: KeYmaera X **landed** in -`src/rust/provers/keymaerax.rs` (8/8 tests passing); 6 backends -remain. - -## Status table - -| Backend | Status | LOC | Notes | -|---|---|---|---| -| **KeYmaera X** (dDL / hybrid systems) | ✅ landed 2026-04-27 | 313 | Worked example for this brief | -| **QEPCAD-B** (cylindrical algebraic decomposition) | 🟡 open | ~250 | CAD input format | -| **Redlog** (Reduce-CAS frontend, real algebra) | 🟡 open | ~250 | Reduce shim + real-quantifier elim | -| **MleanCoP** (connection-method intuitionistic) | 🟡 open | ~250 | Prolog-based, esoteric output | -| **ileanCoP** (intuitionistic leanCoP variant) | 🟡 open | ~250 | Shares parser with MleanCoP | -| **nanoCoP** (lean-er connection prover) | 🟡 open | ~250 | Same family as above | -| **MetTeL2** (tableau generator for modal logics) | 🟡 open | ~250 | JVM, configuration-heavy | - -Total expected: ~1500 LOC + tests for the 6 remaining. - -## Architectural patterns (per-backend semantics) - -### KeYmaera X (✅ already done — worked example) - -- **Input format**: `.kyx` archive entries with hybrid programs. -- **Output**: stdout/stderr scan for `proved` / `closed` / `qed` (closed) - vs `open subgoals` / `failed` / `untrusted` (open or refuted). -- **Trust tier**: 2 (delegates QE to external CAS — Mathematica/Z3/Polya). -- **FFI u8**: 128. -- **Reference**: `src/rust/provers/keymaerax.rs`. Use this as the - template for the remaining six. - -### QEPCAD-B (CAD) - -- **Input**: prefixed-formula syntax for real-quantifier elimination - problems. Header with variable order, then `(quantifier x)[ formula ]`. -- **CLI invocation**: stdin-driven REPL; backends typically pipe - the QEPCAD input followed by `finish` to flush. -- **Output**: prints either `Equivalent quantifier-free formula: - ` (success) or error / `unable to compute`. Consider - formula `True` / `False` as `verify_proof` outcome. -- **Trust tier**: 2 (CAD result is sound but the implementation is - large; no external proof certificate). -- **Hazard**: very long runtimes for formulae with > 4 variables; - honour the timeout aggressively. - -### Redlog (REDUCE-CAS frontend) - -- **Input**: REDUCE-CAS surface syntax — `rlqe formula;` for QE, - `rlcad` for CAD-based decision, etc. Statements terminated with - `;` or `$` (silent). -- **CLI invocation**: spawn `redcsl` (CSL build of Reduce) or - `redpsl`, feed the Redlog `load_package redlog;` then the goal, - read stdout. -- **Output**: scan for `true`, `false`, or a residual quantifier-free - formula. `true` → `verify_proof` returns `Ok(true)`; everything - else either `Ok(false)` or `Err`. -- **Trust tier**: 2 (parallel to QEPCAD). -- **Hazard**: Reduce sometimes prints leading whitespace and - `END OF FILE` markers. Strip carefully. - -### MleanCoP / ileanCoP / nanoCoP (connection-method) - -These three share a parser and CLI shape; implement them as **three -backend files** but factor common helpers into a private -`connection_method.rs` module if the duplication exceeds ~30 LOC. - -- **Input**: TPTP CNF/FOF (MleanCoP) or intuitionistic / modal - variants (ileanCoP, nanoCoP). -- **CLI invocation**: Prolog-driven; typical call is - `swipl -g "leancop:prove('input.p')" -t halt`. Variants differ in - the `prove/1` predicate name. -- **Output**: lines like `% SZS status Theorem` / - `% SZS status CounterSatisfiable` / `% SZS status GaveUp` - (when the upstream uses TPTP-style SZS) OR plain - `+ matrix proof found` (when in native mode). -- **Trust tier**: 2 for MleanCoP (classical), 3 for ileanCoP - (intuitionistic kernel is small — connection method) and nanoCoP - (similarly small kernel). -- **Hazard**: Prolog stack overflow on goals with deep unification — - bound the heap with `--stack-limit=256m`. - -### MetTeL2 (tableau generator) - -- **Input**: a tableau **specification** (logic axioms in MetTeL's - syntax) plus a goal formula. Different from a one-shot prover — - MetTeL2 generates a tableau prover *for* the supplied logic, then - uses it. We only support the "use the bundled standard logics" - path for v1 (S4, K, KT, KD45, ...). -- **CLI invocation**: `java -jar mettel2.jar -s .spec - -i .mt` (typical). Wrap with `-version` probe. -- **Output**: `Provable.` / `Not provable.` / `Unknown.` (tableau - open). -- **Trust tier**: 2 — the generated tableau prover is correct by - construction, but we don't formally check the spec. -- **Hazard**: JVM cold-start latency. Cache the JVM via - `--keep-alive` if benchmark numbers ask for it later. - -## What "landed" looks like (using KeYmaera X as the template) - -For each backend, you produce: - -1. **Backend file** at `src/rust/provers/.rs`. Mirror - `keymaerax.rs`: - - Crate-level `//!` doc explaining *why this backend exists* and - the *input format / output parsing*. - - Module-level `#![allow(dead_code)]` (warranted: tests are - gated by `#[cfg(test)]`). - - `pub struct Backend { config: ProverConfig }`. - - `impl Backend { new, to_, parse_result }`. - - `#[async_trait] impl ProverBackend for Backend` — - `kind`, `version`, `parse_file`, `parse_string`, `apply_tactic` - (return `anyhow::anyhow!(... not supported ...)` if - non-interactive), `verify_proof`, `export`, - `suggest_tactics` (return `Ok(vec![])` for v1), - `search_theorems` (return `Ok(vec![])`), `config`, `set_config`. - - `#[cfg(test)] mod tests` with at minimum: `_kind`, - `_to__basic`, `_parse_result_proved`, - `_parse_result_failed`, `_parse_result_inconclusive`. - -2. **mod.rs wiring** — add the backend at all 10 integration points. - Use `keymaerax` as the search anchor for each: - - 1. `pub mod ;` at the top of `mod.rs` (~line 70). - 2. `` variant in the `ProverKind` enum. - 3. Match arm in the name parser (`"" | "" => - Ok(ProverKind::)`). - 4. `ProverKind::,` in the `all()` list (~line 700). - 5. `ProverKind:: => ,` in the complexity table - (~line 800). - 6. `ProverKind:: => ,` in the trust tier table - (~line 960). - 7. `ProverKind:: => ,` in the ML guidance table - (~line 1090). - 8. `ProverKind:: => "",` in the binary-name table - (~line 1224). - 9. `ProverKind:: => - Ok(Box::new(::Backend::new(config))),` in the - factory dispatch (~line 1614). - 10. **FFI: u8 mapping at `src/rust/ffi/mod.rs`** — add - ` => Some(ProverKind::),` to `kind_from_u8` and - `ProverKind:: => ,` to `kind_to_u8`. KeYmaera X took - slot 128; the remaining six get 129..134 in the order: - QEPCAD-B (129), Redlog (130), MleanCoP (131), - ileanCoP (132), nanoCoP (133), MetTeL2 (134). MetiTarski is - already at its existing slot — do not renumber existing - entries. - -3. **Tests** — at minimum 8 unit tests per backend (the count - `keymaerax.rs` ships). Pattern after the `keymaerax::tests` - block. - -4. **Acceptance gate**: `cargo build --lib` clean (no new warnings - beyond the pre-existing four), `cargo test --lib ` - passes 100%, `cargo test --lib` overall green. - -## Sequencing recommendation - -The six remaining backends differ wildly in semantics. Suggested -order — **easiest first** (sets up the dispatch wiring once, then -the harder ones reuse it): - -1. **QEPCAD-B** — clean CAD input, well-documented stdout markers. -2. **Redlog** — same shape as QEPCAD but uses Reduce CSL; reuse - subprocess pattern. -3. **MetTeL2** — JVM call, simple stdout parse. -4. **MleanCoP** — Prolog binding, TPTP I/O. -5. **ileanCoP** — share helpers with MleanCoP; intuitionistic - nuances in `parse_result`. -6. **nanoCoP** — share helpers with the leanCoP family; lighter - tactic surface. - -Budget ~30 minutes per backend file + ~15 minutes for the 10 -integration points + ~15 minutes for tests + verification = 1 hour -per backend. Whole phase: 6 hours. Don't try to compress; semantics -matter. - -## Per-backend FFI u8 reservations - -Already fixed in mod.rs/ffi.rs. Repeat here so a future Opus session -doesn't have to re-derive them: - -| Backend | FFI u8 | -|---|---| -| KeYmaera X | 128 | -| QEPCAD-B | 129 | -| Redlog | 130 | -| MleanCoP | 131 | -| ileanCoP | 132 | -| nanoCoP | 133 | -| MetTeL2 | 134 | - -## Acceptance criteria for the *phase* - -1. All 6 remaining backend files exist under `src/rust/provers/`. -2. `cargo build --lib` clean (0 errors, no new warnings). -3. `cargo test --lib` passes (every existing test green plus - ≥ 6 × 8 = 48 new backend tests). -4. `provers/mod.rs` `all()` list contains all 7 Phase 3 backends. -5. Each backend's `verify_proof` calls the upstream binary with the - correct flag — gated such that **missing binary returns a - structured error**, not a panic. (KeYmaera X already does this - via `Command::spawn().context(...)`.) -6. `docs/ROADMAP.md` row "Every important solver" updated with the - new ProverKind count (currently 128 → 134 after Phase 3 closes). -7. `PROOF-NEEDS.md` and `.machine_readable/descriptiles/STATE.a2ml` - reflect the closure of Phase 3. - -## Non-goals - -- **No upstream binary provisioning.** The CI containers don't have - KeYmaera X, QEPCAD-B, Redlog, leanCoP family, or MetTeL2 - installed; integration tests gated by `#[cfg(feature = - "-real")]` are out of scope here. Document the gap. -- **No Bellerophon / leanCoP tactic-language dispatch.** All - Phase 3 backends route through `verify_proof` only; interactive - `apply_tactic` returns the "not supported" error per the - KeYmaera X pattern. -- **No GNN integration for these backends.** The GNN ranking layer - (§4.4 of ECHIDNA-NOTES) is a separate phase; Phase 3 - `suggest_tactics` returns `Ok(vec![])`. -- **No formal proofs of `verify_proof` correctness for Phase 3.** - These are dispatch-only backends; their outputs feed the - `compute_trust_level` pipeline at most. Trust tier 2 is the - ceiling without certificate output. - -## Test fixtures (where they should live) - -For each backend, add a tiny `tests/fixtures//` directory -containing 2-3 `.kyx` / `.qep` / `.red` / `.p` / `.mt` example -problems lifted from the upstream documentation. These are *not* -loaded in the unit tests (which use string literals); they exist -for hand-running `echidna prove` against a local install during -development. - -## What you (Opus, future session) should NOT do - -- **Do not implement Bellerophon / leanCoP tactic compilation** - inside the backend file. That is a separate ~1500 LOC project - per the ECHIDNA-NOTES §4.1 design. -- **Do not add upstream-binary auto-detection logic** to mod.rs. - Keep the binary-name table simple; deployment-time - configuration handles binary location. -- **Do not modify the trust pipeline** (`src/rust/dispatch.rs`, - `verification/`) to "support" the new backends. They plug in - through the existing `ProverBackend` trait; no pipeline edit - should be necessary. -- **Do not break MetiTarski**. It's already shipped (Phase 1B, - cbd9449); it stays at trust tier 2 / FFI slot whatever it has. - Don't reshuffle existing FFI numbers. - -## How to verify phase completion (5-minute sanity check) - -```bash -cd /var/mnt/eclipse/repos/echidna -cargo build --lib # 0 errors -cargo test --lib qepcad redlog mleancop ileancop nanocop mettel2 keymaerax \ - # all green -grep -c "ProverKind::" src/rust/provers/mod.rs # should rise by 6 -git log --oneline | head -10 # 6 fresh feat() commits -``` - -## Tracking - -- This brief: `docs/handover/PHASE-3-PROMPT.md` -- Master plan: `~/Desktop/ECHIDNA-EXPANSION-TOMORROW-2026-04-28.md` -- Worked example: `src/rust/provers/keymaerax.rs` (committed - 2026-04-27) -- Companion handoff: `docs/handover/SUGGEST-CLI-PROMPT.md` - (the §4.1/4.3 mechanical-baseline brief from the same session) - -When Phase 3 closes, update this file's status table to all-green, -move the doc to `docs/handover/archived/`, and link the closing -commits. diff --git a/docs/handover/PRODUCTION-WIRING-PLAN.adoc b/docs/handover/PRODUCTION-WIRING-PLAN.adoc new file mode 100644 index 00000000..336e2994 --- /dev/null +++ b/docs/handover/PRODUCTION-WIRING-PLAN.adoc @@ -0,0 +1,234 @@ +== ECHIDNA — Production Wiring Master Plan + +*Status*: Active — kickoff session 2026-04-19 *Scope*: Take Echidna from +"`48 backends trait-wired with mock-only CI`" to "`production-level live +subprocess CI across ~38/48 backends, Cap’n Proto IPC, Chapel as +first-class execution layer`" *Repo*: +`+/var/mnt/eclipse/repos/verification-ecosystem/echidna/+` *Owner*: +Jonathan D.A. Jewell *Coordinator*: Claude (Opus 4.7, 1M ctx) + +''''' + +=== Decisions Locked + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|# |Decision |Rationale +|D1 |*Serialization = Cap’n Proto* |Chosen over Bebop3 for +dependability+maturity (Cloudflare Workers use at scale), zero-copy +reads, strongest schema-evolution story. Tradeoff: heavier codegen. Shim +Julia/Chapel via C-ABI (fits existing Idris2-ABI + Zig-FFI policy). + +|D2 |*Chapel = first-class, maximal* |Existing POC +(`+chapel_poc/parallel_proof_search.chpl+`, 420 LoC) promoted to +`+src/chapel/+`. Expand into portfolio dispatch, speculative tactic +search, corpus-parallel ops, mutation-testing parallelism, multi-locale +distributed, numeric hot paths. + +|D3 |*Guix sole primary* |Per project `+CLAUDE.md+` package-management +policy. `+guix.scm+` / `+manifests/live-provers.scm+` authoritative. +(Guix fallback removed 2026-06-01 per estate-wide guix-deprecation +directive — originally D3 said "`Guix fallback`"; that path is now +closed.) + +|D4 |*Execution order = L3 → L1 → L2* |Live-prover CI first: +highest-leverage gap, surfaces real bugs mocks hide, no protocol break. +Cap’n Proto next, since Chapel wiring (L2) will consume those schemas. + +|D5 |*Live-prover CI cadence = tiered* |Tier-1 every PR, Tier-2 nightly, +Tier-3 weekly, Tier-4 "`best-effort / allow-fail`" quarterly. + +|D6 |*No JSON emit* |Per memory rule `+feedback_no_json_emit_a2ml+`. +Cap’n Proto replaces the current HTTP-JSON Rust↔Julia channel. Tool +config stays Nickel/A2ML. +|=== + +''''' + +=== The Three Phases + +==== L3 — Live-Prover CI (Guix-first) — *~3 weeks* + +*Goal*: every provisionable backend exercised against a canonical +micro-goal on a predictable cadence. + +*Artefacts*: - `+manifests/live-provers.scm+` — Guix manifest listing +all provisionable prover binaries - +`+.github/workflows/live-provers.yml+` — tiered CI workflow +(PR/nightly/weekly/quarterly) - `+tests/live_prover_suite.rs+` — Rust +test harness with canonical goals per backend - `+tests/live_goals/+` — +micro-goal fixtures (one per backend, per category) + +(Originally also planned `+flake.guix+` as a Guix-fallback mirror of the +Guix set; removed 2026-06-01 per estate-wide guix-deprecation +directive.) + +*Tier assignment* (per +`+/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/rust/provers/+` +audit): + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Tier |Cadence |Backends +|*T1 — apt/trivial* |Every PR |Z3, CVC5, Alt-Ergo, Vampire, E Prover, +SPASS, GLPK, MiniZinc, Chuffed + +|*T2 — build-from-source* |Nightly |Coq/Rocq, Lean 4, Agda, Idris2, F*, +Isabelle/HOL, Why3, Dafny, HOL Light, TLAPS + +|*T3 — container / special* |Weekly |Tamarin, ProVerif, Imandra, SCIP, +OR-Tools, HOL4, ACL2, Twelf, Metamath + +|*T4 — niche / best-effort* |Quarterly, allow-fail |Mizar, Nuprl, PVS, +Minlog, Dedukti, Arend, KeY, Prism, UPPAAL, ViPER, NuSMV, Spin, TLC, +CBMC, Seahorn, dReal, Boogie, Kissat, Alloy +|=== + +*Acceptance criteria*: - Tier-1 matrix runs green on every PR - Each +backend has ≥1 canonical goal fixture that the live binary +accepts/rejects correctly - Mock tests retained as fast pre-CI smoke +(keep `+sanity_suite.rs+`) - +`+guix shell -m manifests/live-provers.scm -- cargo test --test live_prover_suite --features live-provers+` +works locally + +*Out of scope for L3*: Cap’n Proto schemas (L1), Chapel integration +(L2). + +''''' + +==== L1 — Cap’n Proto Protocol Swap — *~2 weeks* + +*Goal*: replace HTTP+JSON Rust↔Julia channel and define canonical wire +format for future Chapel + AffineScript layers. + +*Artefacts*: - `+schemas/echidna.capnp+` — canonical schemas: +`+ProofGoal+`, `+ProofResult+`, `+TacticSuggestion+`, +`+GnnRankRequest+`, `+GnnRankResponse+`, `+ProverInvocation+`, +`+TrustedOutcome+` - `+src/rust/ipc/+` — Cap’n Proto Rust bindings, +transport (Unix-domain socket first, TCP fallback) - +`+src/julia/ipc.jl+` — Julia Cap’n Proto reader/writer (use +`+CapnProto.jl+` or shim via C) - `+src/abi/CapnSchemas.idr+` — Idris2 +ABI mirror proving schema compatibility - `+ffi/zig/capnp_bridge.zig+` — +C-ABI bridge for polyglot consumers - +`+bindings/affinescript/echidna_capnp.res+` — AffineScript client +bindings (for UI layer) + +*Acceptance criteria*: - Existing HTTP-JSON GNN client fully replaced; +zero `+serde_json+` calls on Rust↔Julia hot path - All schemas have +Idris2 ABI proofs (zero `+believe_me+`) - Benchmarks: Cap’n Proto +round-trip ≤ 50% of JSON latency for GNN rank request - Schema +versioning doc (`+schemas/VERSIONING.md+`) explains forward/backward +compat rules + +*Out of scope for L1*: Chapel (L2), gRPC replacement (keep as declared +schema; Cap’n Proto over UDS is the live path). + +''''' + +==== L2 — Chapel Maximum Integration — *~5–6 weeks* + +*Goal*: Chapel is a first-class execution layer handling parallelism +Rust-with-Rayon can’t match. + +*Layered sub-phases*: + +[arabic] +. *L2.1 — Portfolio dispatch (promote POC)* ~1 week +* `+src/chapel/portfolio.chpl+` — migrate from `+chapel_poc/+` +* Consume `+ProverInvocation+` from Cap’n Proto +* 48-prover parallel race via `+coforall+`, atomic first-wins, SIGKILL +losers +* Wired into `+src/rust/dispatch.rs+` behind `+--chapel+` feature flag +via Zig FFI +. *L2.2 — Speculative tactic search* ~1 week +* `+src/chapel/tactic_search.chpl+` +* Parallel beam search, parallel MCTS over tactic trees +* Speculative branch execution with cancellation +. *L2.3 — Corpus-parallel ops* ~1 week +* `+src/chapel/corpus.chpl+` +* Parallel replay of 66k proofs (`+forall+` over corpus) +* Parallel premise scoring, tactic mining, indexing +. *L2.4 — Mutation testing parallelism* ~3 days +* `+src/chapel/mutation.chpl+` +* Fan out 1000s of mutants across all cores/locales +. *L2.5 — Multi-locale distributed* ~1.5 weeks +* PGAS-sharded corpus across locales +* Locale-aware prover dispatch (NUMA / multi-node) +* GPU-locale offload for GNN embeddings (Chapel GPU support) +. *L2.6 — Numeric hot paths* ~4 days +* `+src/chapel/numeric.chpl+` +* Parallel GNN embedding pre-processing +* Parallel Pareto frontier, parallel confidence statistics +. *L2.7 — CI + bench* ~3 days +* `+.github/workflows/chapel-live.yml+` +* Chapel-in-dispatch benchmarks vs Rust-only baseline +* Reproducibility harness + +*Acceptance criteria*: - Chapel invoked on the hot path by default +(feature-flagged off → opt-in → default-on progression across +milestones) - Benchmarks show measurable speedup for portfolio solving +on 8+ core machines - Multi-locale path proven on dev hardware +(single-locale covers 80% of value) + +''''' + +=== Current State Snapshot (audit 2026-04-19) + +*Wiring depth* (sampled 8 backends): - *Deep* (persistent process + +structured protocol parsing): Z3, CVC5, Coq (SerAPI), Lean 4, Idris2 - +*Medium* (subprocess + output parse, no streaming): Agda, Vampire - +*Stub-ish / thin*: Dafny (165 LoC — flag for hardening during L3) + +*IPC today*: - Rust ↔ Julia: *HTTP + JSON* +(`+src/rust/gnn/client.rs:1-195+` → `+src/julia/api_server.jl+`, port +8090) — violates `+no_json_emit+` rule - Rust ↔ Chapel: *Stub* +(`+src/zig_ffi/chapel_bridge.zig+`) — not in dispatch path - Rust ↔ +gRPC: schema-only; `+dispatch.rs+` uses in-process traits + +*CI today*: - `+.github/workflows/rust-ci.yml+` runs mock-only tests on +every PR - `+.github/workflows/chapel-ci.yml+` compiles Chapel but +doesn’t feed into dispatch - *Zero live-prover invocations in CI* + +*Corpus*: - 66,674 proofs across 16 prover systems (from +`+COMPLETE_CORPUS_SUMMARY.md+`) - 179,933 tactics, 10,599 unique tactic +signatures, 300 indexed premises + +''''' + +=== Memory-Rule Cross-Checks + +Applies to this plan: - `+feedback_wire_everything+` — no stubs; L2 +promotes the POC rather than leaves it - `+feedback_no_json_emit_a2ml+` +— L1 kills JSON on hot path - `+feedback_verisimdb_policy+` — L3 test +harness should emit VeriSimDB records per live run - +`+feedback_full_battery_before_claims+` — "`production`" claim means +tests + benches + panic-attack + proofs + axioms + causality + +verifiable I/O - `+feedback_commit_asap+` — one unit = one commit - +`+feedback_meander_resource_costs+` — Chapel builds slow; cache +aggressively in CI - `+feedback_push_merge_default+` — GitHub-only +mirror - `+feedback_resource_awareness+` — max 3 parallel subagents, 2 +parallel Bash - `+feedback_opus_supervise_haiku_first+` — Opus +orchestrates, delegate mechanical subtasks to Haiku - +`+user_priority_order+` — dependability > security > interop > usability +> performance (Cap’n Proto choice respects this) + +''''' + +=== Handover Artefacts + +* `+~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md+` ← this file (master) +* `+~/Desktop/ECHIDNA-L3-LIVE-PROVER-CI-PROMPT.md+` — continuation +prompt for L3 +* `+~/Desktop/ECHIDNA-L1-CAPNPROTO-PROMPT.md+` — continuation prompt for +L1 +* `+~/Desktop/ECHIDNA-L2-CHAPEL-PROMPT.md+` — continuation prompt for L2 +* `+.machine_readable/descriptiles/STATE.a2ml+` — mirrored wave entry +in-repo + +=== Session Log + +* *2026-04-19* — Kickoff. Audited wiring depth (Opus + Explore agent). +User confirmed decisions D1–D5. Created Desktop handover docs + L3 +Wave-1 artefacts (Guix manifest, Guix fallback, `+live-provers.yml+`, +`+tests/live_prover_suite.rs+` skeleton with Tier-1 backends). Committed +as one unit. diff --git a/docs/handover/PRODUCTION-WIRING-PLAN.md b/docs/handover/PRODUCTION-WIRING-PLAN.md deleted file mode 100644 index 1ff487e4..00000000 --- a/docs/handover/PRODUCTION-WIRING-PLAN.md +++ /dev/null @@ -1,171 +0,0 @@ -# ECHIDNA — Production Wiring Master Plan - -**Status**: Active — kickoff session 2026-04-19 -**Scope**: Take Echidna from "48 backends trait-wired with mock-only CI" to "production-level live -subprocess CI across ~38/48 backends, Cap'n Proto IPC, Chapel as first-class execution layer" -**Repo**: `/var/mnt/eclipse/repos/verification-ecosystem/echidna/` -**Owner**: Jonathan D.A. Jewell -**Coordinator**: Claude (Opus 4.7, 1M ctx) - ---- - -## Decisions Locked - -| # | Decision | Rationale | -|---|---|---| -| D1 | **Serialization = Cap'n Proto** | Chosen over Bebop3 for dependability+maturity (Cloudflare Workers use at scale), zero-copy reads, strongest schema-evolution story. Tradeoff: heavier codegen. Shim Julia/Chapel via C-ABI (fits existing Idris2-ABI + Zig-FFI policy). | -| D2 | **Chapel = first-class, maximal** | Existing POC (`chapel_poc/parallel_proof_search.chpl`, 420 LoC) promoted to `src/chapel/`. Expand into portfolio dispatch, speculative tactic search, corpus-parallel ops, mutation-testing parallelism, multi-locale distributed, numeric hot paths. | -| D3 | **Guix sole primary** | Per project `CLAUDE.md` package-management policy. `guix.scm` / `manifests/live-provers.scm` authoritative. (Guix fallback removed 2026-06-01 per estate-wide guix-deprecation directive — originally D3 said "Guix fallback"; that path is now closed.) | -| D4 | **Execution order = L3 → L1 → L2** | Live-prover CI first: highest-leverage gap, surfaces real bugs mocks hide, no protocol break. Cap'n Proto next, since Chapel wiring (L2) will consume those schemas. | -| D5 | **Live-prover CI cadence = tiered** | Tier-1 every PR, Tier-2 nightly, Tier-3 weekly, Tier-4 "best-effort / allow-fail" quarterly. | -| D6 | **No JSON emit** | Per memory rule `feedback_no_json_emit_a2ml`. Cap'n Proto replaces the current HTTP-JSON Rust↔Julia channel. Tool config stays Nickel/A2ML. | - ---- - -## The Three Phases - -### L3 — Live-Prover CI (Guix-first) — **~3 weeks** - -**Goal**: every provisionable backend exercised against a canonical micro-goal on a predictable cadence. - -**Artefacts**: -- `manifests/live-provers.scm` — Guix manifest listing all provisionable prover binaries -- `.github/workflows/live-provers.yml` — tiered CI workflow (PR/nightly/weekly/quarterly) -- `tests/live_prover_suite.rs` — Rust test harness with canonical goals per backend -- `tests/live_goals/` — micro-goal fixtures (one per backend, per category) - -(Originally also planned `flake.guix` as a Guix-fallback mirror of the Guix set; removed 2026-06-01 per estate-wide guix-deprecation directive.) - -**Tier assignment** (per `/var/mnt/eclipse/repos/verification-ecosystem/echidna/src/rust/provers/` audit): - -| Tier | Cadence | Backends | -|---|---|---| -| **T1 — apt/trivial** | Every PR | Z3, CVC5, Alt-Ergo, Vampire, E Prover, SPASS, GLPK, MiniZinc, Chuffed | -| **T2 — build-from-source** | Nightly | Coq/Rocq, Lean 4, Agda, Idris2, F*, Isabelle/HOL, Why3, Dafny, HOL Light, TLAPS | -| **T3 — container / special** | Weekly | Tamarin, ProVerif, Imandra, SCIP, OR-Tools, HOL4, ACL2, Twelf, Metamath | -| **T4 — niche / best-effort** | Quarterly, allow-fail | Mizar, Nuprl, PVS, Minlog, Dedukti, Arend, KeY, Prism, UPPAAL, ViPER, NuSMV, Spin, TLC, CBMC, Seahorn, dReal, Boogie, Kissat, Alloy | - -**Acceptance criteria**: -- Tier-1 matrix runs green on every PR -- Each backend has ≥1 canonical goal fixture that the live binary accepts/rejects correctly -- Mock tests retained as fast pre-CI smoke (keep `sanity_suite.rs`) -- `guix shell -m manifests/live-provers.scm -- cargo test --test live_prover_suite --features live-provers` works locally - -**Out of scope for L3**: Cap'n Proto schemas (L1), Chapel integration (L2). - ---- - -### L1 — Cap'n Proto Protocol Swap — **~2 weeks** - -**Goal**: replace HTTP+JSON Rust↔Julia channel and define canonical wire format for future Chapel + AffineScript layers. - -**Artefacts**: -- `schemas/echidna.capnp` — canonical schemas: `ProofGoal`, `ProofResult`, `TacticSuggestion`, `GnnRankRequest`, `GnnRankResponse`, `ProverInvocation`, `TrustedOutcome` -- `src/rust/ipc/` — Cap'n Proto Rust bindings, transport (Unix-domain socket first, TCP fallback) -- `src/julia/ipc.jl` — Julia Cap'n Proto reader/writer (use `CapnProto.jl` or shim via C) -- `src/abi/CapnSchemas.idr` — Idris2 ABI mirror proving schema compatibility -- `ffi/zig/capnp_bridge.zig` — C-ABI bridge for polyglot consumers -- `bindings/affinescript/echidna_capnp.res` — AffineScript client bindings (for UI layer) - -**Acceptance criteria**: -- Existing HTTP-JSON GNN client fully replaced; zero `serde_json` calls on Rust↔Julia hot path -- All schemas have Idris2 ABI proofs (zero `believe_me`) -- Benchmarks: Cap'n Proto round-trip ≤ 50% of JSON latency for GNN rank request -- Schema versioning doc (`schemas/VERSIONING.md`) explains forward/backward compat rules - -**Out of scope for L1**: Chapel (L2), gRPC replacement (keep as declared schema; Cap'n Proto over UDS is the live path). - ---- - -### L2 — Chapel Maximum Integration — **~5–6 weeks** - -**Goal**: Chapel is a first-class execution layer handling parallelism Rust-with-Rayon can't match. - -**Layered sub-phases**: - -1. **L2.1 — Portfolio dispatch (promote POC)** ~1 week - - `src/chapel/portfolio.chpl` — migrate from `chapel_poc/` - - Consume `ProverInvocation` from Cap'n Proto - - 48-prover parallel race via `coforall`, atomic first-wins, SIGKILL losers - - Wired into `src/rust/dispatch.rs` behind `--chapel` feature flag via Zig FFI -2. **L2.2 — Speculative tactic search** ~1 week - - `src/chapel/tactic_search.chpl` - - Parallel beam search, parallel MCTS over tactic trees - - Speculative branch execution with cancellation -3. **L2.3 — Corpus-parallel ops** ~1 week - - `src/chapel/corpus.chpl` - - Parallel replay of 66k proofs (`forall` over corpus) - - Parallel premise scoring, tactic mining, indexing -4. **L2.4 — Mutation testing parallelism** ~3 days - - `src/chapel/mutation.chpl` - - Fan out 1000s of mutants across all cores/locales -5. **L2.5 — Multi-locale distributed** ~1.5 weeks - - PGAS-sharded corpus across locales - - Locale-aware prover dispatch (NUMA / multi-node) - - GPU-locale offload for GNN embeddings (Chapel GPU support) -6. **L2.6 — Numeric hot paths** ~4 days - - `src/chapel/numeric.chpl` - - Parallel GNN embedding pre-processing - - Parallel Pareto frontier, parallel confidence statistics -7. **L2.7 — CI + bench** ~3 days - - `.github/workflows/chapel-live.yml` - - Chapel-in-dispatch benchmarks vs Rust-only baseline - - Reproducibility harness - -**Acceptance criteria**: -- Chapel invoked on the hot path by default (feature-flagged off → opt-in → default-on progression across milestones) -- Benchmarks show measurable speedup for portfolio solving on 8+ core machines -- Multi-locale path proven on dev hardware (single-locale covers 80% of value) - ---- - -## Current State Snapshot (audit 2026-04-19) - -**Wiring depth** (sampled 8 backends): -- **Deep** (persistent process + structured protocol parsing): Z3, CVC5, Coq (SerAPI), Lean 4, Idris2 -- **Medium** (subprocess + output parse, no streaming): Agda, Vampire -- **Stub-ish / thin**: Dafny (165 LoC — flag for hardening during L3) - -**IPC today**: -- Rust ↔ Julia: **HTTP + JSON** (`src/rust/gnn/client.rs:1-195` → `src/julia/api_server.jl`, port 8090) — violates `no_json_emit` rule -- Rust ↔ Chapel: **Stub** (`src/zig_ffi/chapel_bridge.zig`) — not in dispatch path -- Rust ↔ gRPC: schema-only; `dispatch.rs` uses in-process traits - -**CI today**: -- `.github/workflows/rust-ci.yml` runs mock-only tests on every PR -- `.github/workflows/chapel-ci.yml` compiles Chapel but doesn't feed into dispatch -- **Zero live-prover invocations in CI** - -**Corpus**: -- 66,674 proofs across 16 prover systems (from `COMPLETE_CORPUS_SUMMARY.md`) -- 179,933 tactics, 10,599 unique tactic signatures, 300 indexed premises - ---- - -## Memory-Rule Cross-Checks - -Applies to this plan: -- `feedback_wire_everything` — no stubs; L2 promotes the POC rather than leaves it -- `feedback_no_json_emit_a2ml` — L1 kills JSON on hot path -- `feedback_verisimdb_policy` — L3 test harness should emit VeriSimDB records per live run -- `feedback_full_battery_before_claims` — "production" claim means tests + benches + panic-attack + proofs + axioms + causality + verifiable I/O -- `feedback_commit_asap` — one unit = one commit -- `feedback_meander_resource_costs` — Chapel builds slow; cache aggressively in CI -- `feedback_push_merge_default` — GitHub-only mirror -- `feedback_resource_awareness` — max 3 parallel subagents, 2 parallel Bash -- `feedback_opus_supervise_haiku_first` — Opus orchestrates, delegate mechanical subtasks to Haiku -- `user_priority_order` — dependability > security > interop > usability > performance (Cap'n Proto choice respects this) - ---- - -## Handover Artefacts - -- `~/Desktop/ECHIDNA-PRODUCTION-WIRING-PLAN.md` ← this file (master) -- `~/Desktop/ECHIDNA-L3-LIVE-PROVER-CI-PROMPT.md` — continuation prompt for L3 -- `~/Desktop/ECHIDNA-L1-CAPNPROTO-PROMPT.md` — continuation prompt for L1 -- `~/Desktop/ECHIDNA-L2-CHAPEL-PROMPT.md` — continuation prompt for L2 -- `.machine_readable/descriptiles/STATE.a2ml` — mirrored wave entry in-repo - -## Session Log - -- **2026-04-19** — Kickoff. Audited wiring depth (Opus + Explore agent). User confirmed decisions D1–D5. Created Desktop handover docs + L3 Wave-1 artefacts (Guix manifest, Guix fallback, `live-provers.yml`, `tests/live_prover_suite.rs` skeleton with Tier-1 backends). Committed as one unit. diff --git a/docs/handover/PROVER-CORPUS-SATURATION-LANE.adoc b/docs/handover/PROVER-CORPUS-SATURATION-LANE.adoc new file mode 100644 index 00000000..4f988e3e --- /dev/null +++ b/docs/handover/PROVER-CORPUS-SATURATION-LANE.adoc @@ -0,0 +1,170 @@ +== Saturation Lane — Prover/Corpus/Vocab/Synonyms/Arbitration + +*Branch*: `+prover-corpus-saturation+` (worktree at +`+/tmp/echidna-saturation+`) *Base*: `+origin/main+` @ `+88cd8dc+` +*Started*: 2026-06-01 *Driver*: secondary Claude instance, +owner-directed "`max out / until marginal benefit gone`" *Sibling lane*: +`+wave3/161-162-bench-telemetry-corpus+` (primary Claude — chapel bench ++ telemetry) + +=== Why this exists + +The owner directive: push solvers / corpuses / vocab / synonyms / +verisim E-R / learning / arbitration to their respective +marginal-benefit limits, dispatching agents in parallel. This document +declares the lane so the wave3 branch can avoid collisions. + +=== Lane scope — what this branch DOES touch + +NEW FILES ONLY where possible. Where existing files must be edited, the +file is listed below with the specific functions/symbols I am extending. + +==== Corpus adapters (new files) + +* `+src/rust/corpus/isabelle.rs+` — Isabelle/HOL AFP `+.thy+` +* `+src/rust/corpus/metamath.rs+` — set.mm +* `+src/rust/corpus/mizar.rs+` — MML `+.miz+` / `+.abs+` +* `+src/rust/corpus/hol_light.rs+` — Multivariate / Core +* `+src/rust/corpus/hol4.rs+` — HOL4 Script files +* `+src/rust/corpus/dafny.rs+` — `+.dfy+` +* `+src/rust/corpus/why3.rs+` — TOCCATA gallery `+.mlw+` +* `+src/rust/corpus/fstar.rs+` — F* examples `+.fst+` +* `+src/rust/corpus/tptp.rs+` — TPTP problem library +* `+src/rust/corpus/smtlib.rs+` — SMT-LIB benchmarks +* `+src/rust/corpus/acl2_books.rs+` — ACL2 community books +* `+src/rust/corpus/proofnet.rs+` — ProofNet +* `+src/rust/corpus/minif2f.rs+` — MiniF2F +* `+src/rust/corpus/naproche.rs+` — Naproche libraries +* `+src/rust/corpus/mathcomp.rs+` — Coq MathComp (separate from coq.rs +heuristic) +* `+src/rust/corpus/iris.rs+` — Coq Iris +* `+src/rust/corpus/cubical_agda.rs+` — Cubical Agda stdlib + +==== Corpus mod registration (existing file, additive only) + +* `+src/rust/corpus/mod.rs+` — append `+pub mod isabelle;+` etc. No +reordering of existing `+pub mod+` lines. No edits to existing +functions. + +==== Synonyms data (new files) + +* `+data/synonyms/hol_light.toml+` +* `+data/synonyms/hol4.toml+` +* `+data/synonyms/metamath.toml+` +* `+data/synonyms/mizar.toml+` +* `+data/synonyms/dafny.toml+` +* `+data/synonyms/fstar.toml+` +* `+data/synonyms/why3.toml+` +* `+data/synonyms/acl2.toml+` +* `+data/synonyms/pvs.toml+` +* `+data/synonyms/tlaps.toml+` +* `+data/synonyms/imandra.toml+` +* `+data/synonyms/_msc2020.toml+` — MSC2020 cross-prover dictionary +* `+data/synonyms/_wordnet_math.toml+` — WordNet math entries +* `+data/synonyms/_conceptnet_seed.toml+` — pre-fetched ConceptNet seeds +(offline-resilient) + +==== Exchange bridges (new files) + +* `+src/rust/exchange/tptp.rs+` — universal first-order ATP exchange +* `+src/rust/exchange/smtlib.rs+` — SMT-LIB exchange / round-trip +* `+src/rust/exchange/smtcoq.rs+` — SMT proofs into Coq +* `+src/rust/exchange/lambdapi.rs+` — Dedukti’s successor + +==== Portfolio expansion (existing file) + +* `+src/rust/verification/portfolio.rs+` — extend `+default()+` to +include DReal, OpenSmt, SmtRat, MathSat, SPASS, Princess, iProver, Twee, +Princess in their respective tiers. Pure additive — no semantic changes +to existing solver entries. + +==== New arbitration mechanisms (new files) + +* `+src/rust/verification/bayesian_arbiter.rs+` — posterior over verdict +given evidence stream +* `+src/rust/verification/dempster_shafer.rs+` — belief mass combination +* `+src/rust/verification/pareto_arbiter.rs+` — multi-objective Pareto +frontier voting + +==== Vocab/Synonyms wiring (existing files, surgical edits) + +* `+src/rust/suggest/synonyms.rs+` — add +`+SynonymTable::with_msc2020()+` method; add `+merge_external()+` for +cross-prover dictionaries. Existing `+load()+` / `+alternatives()+` +UNCHANGED. +* `+src/rust/integrations/conceptnet.rs+` — add `+prefetch_to_cache()+` +method using `+_conceptnet_seed.toml+`. Existing `+related_concepts()+` +UNCHANGED. + +==== E-R schema formalization (new files) + +* `+docs/architecture/VERISIM-ER-SCHEMA.md+` — formal entity + +relationship definitions +* `+crates/echidna-wire/schemas/verisim_er.capnp+` — Cap’n Proto schema +(if compatible) + +==== Documentation (new files) + +* `+docs/decisions/2026-06-01-saturation-campaign.md+` — ADR +* `+docs/CORPUS-ADAPTERS.md+` — index of all corpus adapters with their +parsing strategy + canonical source URL +* `+docs/handover/PROVER-CORPUS-SATURATION-LANE.md+` — this file + +=== Lane scope — what this branch DOES NOT touch + +*Hard exclusion list* (collision avoidance with wave3): + +* `+src/chapel/**+` — entirely wave3 +* `+benches/**+` — wave3 telemetry hooks +* `+src/rust/diagnostics/corpus_monitor.rs+` — wave3 per-prover +telemetry +* `+src/rust/diagnostics/gnn_training.rs+` — wave3 training health hooks +* `+training_data/premises_*.jsonl+` — wave3 benches against these +* `+training_data/floor_progress.{md,jsonl}+` — wave3 progress file +* `+training_data/metrics_baseline.jsonl+` — wave3 baseline reference +* `+src/rust/learning/{daemon,curriculum,mcts,self_play}.rs+` — risk of +telemetry collision +* `+models/**+` — first GNN training run risks deleting +`+models/neural/+`; defer +* `+src/julia/run_training.jl+`, `+train.jl+`, `+eval_held_out.jl+` — +deferred (would touch model artefacts) +* `+.github/workflows/*+` — CI changes go through the wave3 lane +* `+Justfile+` — `+just train+` / `+just chapel-*+` are wave3 territory +* Any file the wave3 branch has shown as modified in its working tree +(~300 files; the staged set will land via #161/#162 merges, do not +pre-empt) + +=== Contact protocol + +* Each commit will use prefix `+feat(corpus):+` / `+feat(vocab):+` / +`+feat(exchange):+` / `+feat(arbiter):+` / `+docs(er):+` so wave3 can +grep. +* If a file outside this lane needs touching, I file an issue first and +link it here. +* Final merge order: this branch rebases onto `+main+` AFTER wave3 lands +(or at minimum, after #161/#162 are merged). No competing merge race. + +=== Marginal-benefit termination criteria + +I stop the saturation push when: + +[arabic] +. All 14+ corpus adapters land with at least a smoke-test fixture each, +OR +. Each adapter blocks on an upstream binary/source absent from the +environment, OR +. Synonyms TOML files exceed ~5,000 lines total (current 863) and +ConceptNet/MSC2020/WordNet dictionaries land, OR +. Exchange bridges land for TPTP + SMT-LIB at minimum, OR +. New arbiter trio (Bayesian / Dempster-Shafer / Pareto) compiles with +tests against the existing portfolio results, OR +. The compile-test loop slows below ~5 PRs/hour or fixture-fetch latency +dominates, + +whichever fires first. + +=== Progress log + +* 2026-06-01 — branch created, handover doc landed, scoping agents +reported. +* (subsequent entries added as work lands) diff --git a/docs/handover/PROVER-CORPUS-SATURATION-LANE.md b/docs/handover/PROVER-CORPUS-SATURATION-LANE.md deleted file mode 100644 index 937eca74..00000000 --- a/docs/handover/PROVER-CORPUS-SATURATION-LANE.md +++ /dev/null @@ -1,137 +0,0 @@ - - -# Saturation Lane — Prover/Corpus/Vocab/Synonyms/Arbitration - -**Branch**: `prover-corpus-saturation` (worktree at `/tmp/echidna-saturation`) -**Base**: `origin/main` @ `88cd8dc` -**Started**: 2026-06-01 -**Driver**: secondary Claude instance, owner-directed "max out / until marginal benefit gone" -**Sibling lane**: `wave3/161-162-bench-telemetry-corpus` (primary Claude — chapel bench + telemetry) - -## Why this exists - -The owner directive: push solvers / corpuses / vocab / synonyms / verisim E-R / learning / arbitration to their respective marginal-benefit limits, dispatching agents in parallel. -This document declares the lane so the wave3 branch can avoid collisions. - -## Lane scope — what this branch DOES touch - -NEW FILES ONLY where possible. Where existing files must be edited, the file is listed below with the specific functions/symbols I am extending. - -### Corpus adapters (new files) - -- `src/rust/corpus/isabelle.rs` — Isabelle/HOL AFP `.thy` -- `src/rust/corpus/metamath.rs` — set.mm -- `src/rust/corpus/mizar.rs` — MML `.miz` / `.abs` -- `src/rust/corpus/hol_light.rs` — Multivariate / Core -- `src/rust/corpus/hol4.rs` — HOL4 Script files -- `src/rust/corpus/dafny.rs` — `.dfy` -- `src/rust/corpus/why3.rs` — TOCCATA gallery `.mlw` -- `src/rust/corpus/fstar.rs` — F\* examples `.fst` -- `src/rust/corpus/tptp.rs` — TPTP problem library -- `src/rust/corpus/smtlib.rs` — SMT-LIB benchmarks -- `src/rust/corpus/acl2_books.rs` — ACL2 community books -- `src/rust/corpus/proofnet.rs` — ProofNet -- `src/rust/corpus/minif2f.rs` — MiniF2F -- `src/rust/corpus/naproche.rs` — Naproche libraries -- `src/rust/corpus/mathcomp.rs` — Coq MathComp (separate from coq.rs heuristic) -- `src/rust/corpus/iris.rs` — Coq Iris -- `src/rust/corpus/cubical_agda.rs` — Cubical Agda stdlib - -### Corpus mod registration (existing file, additive only) - -- `src/rust/corpus/mod.rs` — append `pub mod isabelle;` etc. No reordering of existing `pub mod` lines. No edits to existing functions. - -### Synonyms data (new files) - -- `data/synonyms/hol_light.toml` -- `data/synonyms/hol4.toml` -- `data/synonyms/metamath.toml` -- `data/synonyms/mizar.toml` -- `data/synonyms/dafny.toml` -- `data/synonyms/fstar.toml` -- `data/synonyms/why3.toml` -- `data/synonyms/acl2.toml` -- `data/synonyms/pvs.toml` -- `data/synonyms/tlaps.toml` -- `data/synonyms/imandra.toml` -- `data/synonyms/_msc2020.toml` — MSC2020 cross-prover dictionary -- `data/synonyms/_wordnet_math.toml` — WordNet math entries -- `data/synonyms/_conceptnet_seed.toml` — pre-fetched ConceptNet seeds (offline-resilient) - -### Exchange bridges (new files) - -- `src/rust/exchange/tptp.rs` — universal first-order ATP exchange -- `src/rust/exchange/smtlib.rs` — SMT-LIB exchange / round-trip -- `src/rust/exchange/smtcoq.rs` — SMT proofs into Coq -- `src/rust/exchange/lambdapi.rs` — Dedukti's successor - -### Portfolio expansion (existing file) - -- `src/rust/verification/portfolio.rs` — extend `default()` to include DReal, OpenSmt, SmtRat, MathSat, SPASS, Princess, iProver, Twee, Princess in their respective tiers. Pure additive — no semantic changes to existing solver entries. - -### New arbitration mechanisms (new files) - -- `src/rust/verification/bayesian_arbiter.rs` — posterior over verdict given evidence stream -- `src/rust/verification/dempster_shafer.rs` — belief mass combination -- `src/rust/verification/pareto_arbiter.rs` — multi-objective Pareto frontier voting - -### Vocab/Synonyms wiring (existing files, surgical edits) - -- `src/rust/suggest/synonyms.rs` — add `SynonymTable::with_msc2020()` method; add `merge_external()` for cross-prover dictionaries. Existing `load()` / `alternatives()` UNCHANGED. -- `src/rust/integrations/conceptnet.rs` — add `prefetch_to_cache()` method using `_conceptnet_seed.toml`. Existing `related_concepts()` UNCHANGED. - -### E-R schema formalization (new files) - -- `docs/architecture/VERISIM-ER-SCHEMA.md` — formal entity + relationship definitions -- `crates/echidna-wire/schemas/verisim_er.capnp` — Cap'n Proto schema (if compatible) - -### Documentation (new files) - -- `docs/decisions/2026-06-01-saturation-campaign.md` — ADR -- `docs/CORPUS-ADAPTERS.md` — index of all corpus adapters with their parsing strategy + canonical source URL -- `docs/handover/PROVER-CORPUS-SATURATION-LANE.md` — this file - -## Lane scope — what this branch DOES NOT touch - -**Hard exclusion list** (collision avoidance with wave3): - -- `src/chapel/**` — entirely wave3 -- `benches/**` — wave3 telemetry hooks -- `src/rust/diagnostics/corpus_monitor.rs` — wave3 per-prover telemetry -- `src/rust/diagnostics/gnn_training.rs` — wave3 training health hooks -- `training_data/premises_*.jsonl` — wave3 benches against these -- `training_data/floor_progress.{md,jsonl}` — wave3 progress file -- `training_data/metrics_baseline.jsonl` — wave3 baseline reference -- `src/rust/learning/{daemon,curriculum,mcts,self_play}.rs` — risk of telemetry collision -- `models/**` — first GNN training run risks deleting `models/neural/`; defer -- `src/julia/run_training.jl`, `train.jl`, `eval_held_out.jl` — deferred (would touch model artefacts) -- `.github/workflows/*` — CI changes go through the wave3 lane -- `Justfile` — `just train` / `just chapel-*` are wave3 territory -- Any file the wave3 branch has shown as modified in its working tree (~300 files; the staged set will land via #161/#162 merges, do not pre-empt) - -## Contact protocol - -- Each commit will use prefix `feat(corpus):` / `feat(vocab):` / `feat(exchange):` / `feat(arbiter):` / `docs(er):` so wave3 can grep. -- If a file outside this lane needs touching, I file an issue first and link it here. -- Final merge order: this branch rebases onto `main` AFTER wave3 lands (or at minimum, after #161/#162 are merged). No competing merge race. - -## Marginal-benefit termination criteria - -I stop the saturation push when: - -1. All 14+ corpus adapters land with at least a smoke-test fixture each, OR -2. Each adapter blocks on an upstream binary/source absent from the environment, OR -3. Synonyms TOML files exceed ~5,000 lines total (current 863) and ConceptNet/MSC2020/WordNet dictionaries land, OR -4. Exchange bridges land for TPTP + SMT-LIB at minimum, OR -5. New arbiter trio (Bayesian / Dempster-Shafer / Pareto) compiles with tests against the existing portfolio results, OR -6. The compile-test loop slows below ~5 PRs/hour or fixture-fetch latency dominates, - -whichever fires first. - -## Progress log - -- 2026-06-01 — branch created, handover doc landed, scoping agents reported. -- (subsequent entries added as work lands) diff --git a/docs/handover/README.adoc b/docs/handover/README.adoc new file mode 100644 index 00000000..997df960 --- /dev/null +++ b/docs/handover/README.adoc @@ -0,0 +1,59 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 + +== Echidna Handover Prompts + +This directory mirrors the Echidna continuation prompts that live on the +author’s Desktop so that a fresh clone of this repo has the full +handover context tracked in version control. + +[width="100%",cols="47%,53%",options="header",] +|=== +|File |Scope +|*`+TODO.md+`* |*Tight actionable backlog, P0→P4, across L1+L2+L3.* +Start here. + +|*`+STATE.md+`* |*Where we are now vs forward vision — per-phase status ++ decisions D1–D6.* + +|`+PRODUCTION-WIRING-PLAN.md+` |Master plan (L1 Cap’n Proto + L2 Chapel +maximal + L3 live-prover CI) — full rationale + +|`+L1-CAPNPROTO-PROMPT.md+` |L1 — swap HTTP+JSON Rust↔Julia for Cap’n +Proto — full prompt + +|`+L2-CHAPEL-PROMPT.md+` |L2 — promote Chapel POC to first-class +parallel dispatch layer — full prompt + +|`+L3-LIVE-PROVER-CI-PROMPT.md+` |L3 — live subprocess CI tiered across +48 prover backends — full prompt (marked Wave-2 DONE) +|=== + +=== Source of truth + +The Desktop copies at `+~/Desktop/ECHIDNA-*.md+` remain the working +drafts the author edits in-session. These in-repo copies are the +canonical versions for: + +* Anyone cloning the repo without Desktop access +* Submodule consumers reading docs without a shell +* Git archaeology (diff across time) + +When a session updates a handover prompt, update *both* the Desktop copy +and the in-repo copy in the same commit. If they drift, the in-repo copy +wins because it is the committed one. + +=== Current status (as of 2026-04-19) + +* *L3 Wave-1* (Tier-1, every PR, 9 backends): DONE — `+b022bf4+`. +* *L3 Wave-2* (Tier-2, nightly, 10 backends): DONE for 9; `+hol-light+` +deferred to Wave-3. Commits `+9a4aeeb+` + `+6717b12+`. +* *L3 Wave-3* (Tier-3, weekly, 9 backends): scaffold only; needs +per-backend Containerfiles. Handover hints in +`+.machine_readable/descriptiles/STATE.a2ml+` under +`+[wave-3-handover-hints]+`. +* *L3 Wave-4* (Tier-4, quarterly, 19 backends): scaffold only; retained +as mock-only unless a maintainer volunteers. +* *L2 Chapel*: `+--features chapel+` now self-links against bundled Zig +stubs (`+53ab9b8+`); real `+libechidna_chapel.so+` CI path still +outstanding. +* *L1 Cap’n Proto*: not yet started. diff --git a/docs/handover/README.md b/docs/handover/README.md deleted file mode 100644 index 042d9ceb..00000000 --- a/docs/handover/README.md +++ /dev/null @@ -1,45 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 - -# Echidna Handover Prompts - -This directory mirrors the Echidna continuation prompts that live on the -author's Desktop so that a fresh clone of this repo has the full handover -context tracked in version control. - -| File | Scope | -|------|-------| -| **`TODO.md`** | **Tight actionable backlog, P0→P4, across L1+L2+L3.** Start here. | -| **`STATE.md`** | **Where we are now vs forward vision — per-phase status + decisions D1–D6.** | -| `PRODUCTION-WIRING-PLAN.md` | Master plan (L1 Cap'n Proto + L2 Chapel maximal + L3 live-prover CI) — full rationale | -| `L1-CAPNPROTO-PROMPT.md` | L1 — swap HTTP+JSON Rust↔Julia for Cap'n Proto — full prompt | -| `L2-CHAPEL-PROMPT.md` | L2 — promote Chapel POC to first-class parallel dispatch layer — full prompt | -| `L3-LIVE-PROVER-CI-PROMPT.md` | L3 — live subprocess CI tiered across 48 prover backends — full prompt (marked Wave-2 DONE) | - -## Source of truth - -The Desktop copies at `~/Desktop/ECHIDNA-*.md` remain the working drafts -the author edits in-session. These in-repo copies are the canonical -versions for: - -- Anyone cloning the repo without Desktop access -- Submodule consumers reading docs without a shell -- Git archaeology (diff across time) - -When a session updates a handover prompt, update **both** the Desktop -copy and the in-repo copy in the same commit. If they drift, the in-repo -copy wins because it is the committed one. - -## Current status (as of 2026-04-19) - -- **L3 Wave-1** (Tier-1, every PR, 9 backends): DONE — `b022bf4`. -- **L3 Wave-2** (Tier-2, nightly, 10 backends): DONE for 9; `hol-light` - deferred to Wave-3. Commits `9a4aeeb` + `6717b12`. -- **L3 Wave-3** (Tier-3, weekly, 9 backends): scaffold only; needs - per-backend Containerfiles. Handover hints in - `.machine_readable/descriptiles/STATE.a2ml` under `[wave-3-handover-hints]`. -- **L3 Wave-4** (Tier-4, quarterly, 19 backends): scaffold only; - retained as mock-only unless a maintainer volunteers. -- **L2 Chapel**: `--features chapel` now self-links against bundled - Zig stubs (`53ab9b8`); real `libechidna_chapel.so` CI path still - outstanding. -- **L1 Cap'n Proto**: not yet started. diff --git a/docs/handover/S4-LOOP-CLOSURE-RUNBOOK.md b/docs/handover/S4-LOOP-CLOSURE-RUNBOOK.adoc similarity index 53% rename from docs/handover/S4-LOOP-CLOSURE-RUNBOOK.md rename to docs/handover/S4-LOOP-CLOSURE-RUNBOOK.adoc index b10adb76..59a29b55 100644 --- a/docs/handover/S4-LOOP-CLOSURE-RUNBOOK.md +++ b/docs/handover/S4-LOOP-CLOSURE-RUNBOOK.adoc @@ -1,14 +1,11 @@ - - +== S4 Loop-Closure Runbook -# S4 Loop-Closure Runbook +This runbook describes how to verify, locally and in CI, that ECHIDNA’s +cross-prover learning loop (Roadmap stage 3a/3b — "`S4`") is closing. -This runbook describes how to verify, locally and in CI, that ECHIDNA's -cross-prover learning loop (Roadmap stage 3a/3b — "S4") is closing. +=== What is the loop? -## What is the loop? - -``` +.... ProverDispatcher::verify_proof ──fire-and-forget──► VeriSimDBClient::record_proof_attempt └─► POST /api/v1/proof_attempts @@ -17,31 +14,34 @@ ProverDispatcher::verify_proof ──fire-and-forget──► └─► GET /api/v1/mv_prover_success_by_class └─► VeriSimAdvisor::suggest_prover └─► next dispatch routes smarter -``` +.... Three echidna-side wirings carry the loop: -| Wiring | Module | Wired in commit | -|------------------------|---------------------------------|-----------------| -| Write at dispatch exit | `dispatch::spawn_record_attempt`| `60d2e75` | -| Class threading | `dispatch::verify_proof_with_class` | `cf94b49` | -| Cross-prover read | `vcl_ut::cross_prover_search_names` | `cf94b49` | +[width="100%",cols="34%,44%,22%",options="header",] +|=== +|Wiring |Module |Wired in commit +|Write at dispatch exit |`+dispatch::spawn_record_attempt+` |`+60d2e75+` +|Class threading |`+dispatch::verify_proof_with_class+` |`+cf94b49+` +|Cross-prover read |`+vcl_ut::cross_prover_search_names+` |`+cf94b49+` +|=== -## What actually has to be standing up +=== What actually has to be standing up -Just **verisim-api** on a known port. The test never touches Elixir +Just *verisim-api* on a known port. The test never touches Elixir orchestration, Svalinn, federation, drift monitor, or the seven backing databases — it talks directly to the rust-core HTTP endpoints -`/api/v1/proof_attempts` and `/api/v1/mv_prover_success_by_class`. +`+/api/v1/proof_attempts+` and `+/api/v1/mv_prover_success_by_class+`. -## Local verification +=== Local verification -### 1. Start verisim-api +==== 1. Start verisim-api -The canonical way is `selur-compose up rust-core` from the verisimdb +The canonical way is `+selur-compose up rust-core+` from the verisimdb checkout, but for a smoke run any of these work: -```bash +[source,bash] +---- # Option A — selur-compose (preferred) cd ~/Documents/hyperpolymath-repos/verisimdb selur-compose up rust-core --detach @@ -53,64 +53,68 @@ podman-compose -f container/compose.toml up rust-core --detach # Option C — bare cargo run (development only) cd ~/Documents/hyperpolymath-repos/verisimdb/rust-core cargo run --release --bin verisim-api -``` +---- -Wait for `/health` to respond: +Wait for `+/health+` to respond: -```bash +[source,bash] +---- until curl -sf http://localhost:8080/health >/dev/null; do sleep 1; done echo "verisim-api ready" -``` +---- -### 2. Run the loop-closure test +==== 2. Run the loop-closure test -```bash +[source,bash] +---- cd ~/Documents/hyperpolymath-repos/echidna just test-s4-loop -``` +---- Expected output (success): -``` +.... running 2 tests test s4_record_then_read_back_by_goal_hash ... ok test s4_class_aggregation_visible_in_mv ... ok test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured -``` +.... Expected output (verisim-api not running — graceful skip): -``` +.... skip: VeriSimDB at http://localhost:8080 is unreachable — set VERISIM_URL or start verisim-api test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured -``` +.... The skip path is intentional: the test is a no-op rather than a failure -when the dependency is absent, so the same `cargo test` command works on -machines without verisim-api in the loop. +when the dependency is absent, so the same `+cargo test+` command works +on machines without verisim-api in the loop. -### 3. Override the URL +==== 3. Override the URL -```bash +[source,bash] +---- VERISIM_URL=http://verisim.staging.example:9090 just test-s4-loop -``` +---- -## CI wiring +=== CI wiring -A workflow that brings up verisim-api and runs `test-s4-loop` is -**not yet committed**. The blocker is that no published -`ghcr.io/hyperpolymath/verisimdb-api` image exists yet — every CI run +A workflow that brings up verisim-api and runs `+test-s4-loop+` is *not +yet committed*. The blocker is that no published +`+ghcr.io/hyperpolymath/verisimdb-api+` image exists yet — every CI run would have to build verisim-api from a sibling checkout, which is too -heavy for `on: pull_request`. +heavy for `+on: pull_request+`. -When that image is published (verisim's `ghcr-publish.yml` is the +When that image is published (verisim’s `+ghcr-publish.yml+` is the expected channel — currently absent from -`verification-ecosystem/verisimdb/.github/workflows/`), the workflow +`+verification-ecosystem/verisimdb/.github/workflows/+`), the workflow becomes: -```yaml +[source,yaml] +---- name: S4 Loop Closure on: workflow_dispatch: @@ -135,37 +139,43 @@ jobs: - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 - run: just test-s4-loop -``` +---- This workflow is left as an unfiled artefact in this runbook precisely to avoid landing it as a perpetually-skipping no-op. File it the same day verisim publishes its image. -## What "loop closing in production" looks like +=== What "`loop closing in production`" looks like In a production deployment with both echidna and verisim-api running: -1. Run any successful `verify_proof_verisim_guided(..., obligation_class="…")`. -2. Within the verisim writer's HTTP timeout (default 10s) the row appears in - the `proof_attempts` table. -3. ClickHouse refreshes `mv_prover_success_by_class` on the next interval. -4. Subsequent calls to `verify_proof_verisim_guided` with the same class - start receiving a non-default routing decision (look for - `VeriSimAdvisor: obligation_class=… → SomeProver` at INFO level in - echidna's logs). +[arabic] +. Run any successful +`+verify_proof_verisim_guided(..., obligation_class="…")+`. +. Within the verisim writer’s HTTP timeout (default 10s) the row appears +in the `+proof_attempts+` table. +. ClickHouse refreshes `+mv_prover_success_by_class+` on the next +interval. +. Subsequent calls to `+verify_proof_verisim_guided+` with the same +class start receiving a non-default routing decision (look for +`+VeriSimAdvisor: obligation_class=… → SomeProver+` at INFO level in +echidna’s logs). If step 4 never observes a non-default routing for a class that has genuinely accumulated rows, the breakdown is one of: -- **MV not refreshing** → ClickHouse-side problem, check the MV definition. -- **Writer silently dropping** → look for `VeriSim record_proof_attempt failed` - warnings in echidna logs. -- **Class string mismatch** → confirm the dispatch caller passes the same - `obligation_class` the read path queries (the `cf94b49` threading fix - closed the most common version of this). - -## Future work tracked elsewhere - -- Verisim image publish: `verification-ecosystem/verisimdb` repo, not echidna. -- Workflow filing once image is available: `.github/workflows/s4-loop.yml`. -- Tier-3 weekly cadence so it doesn't gate every PR. +* *MV not refreshing* → ClickHouse-side problem, check the MV +definition. +* *Writer silently dropping* → look for +`+VeriSim record_proof_attempt failed+` warnings in echidna logs. +* *Class string mismatch* → confirm the dispatch caller passes the same +`+obligation_class+` the read path queries (the `+cf94b49+` threading +fix closed the most common version of this). + +=== Future work tracked elsewhere + +* Verisim image publish: `+verification-ecosystem/verisimdb+` repo, not +echidna. +* Workflow filing once image is available: +`+.github/workflows/s4-loop.yml+`. +* Tier-3 weekly cadence so it doesn’t gate every PR. diff --git a/docs/handover/S5-VERIFICATION-RUNBOOK.adoc b/docs/handover/S5-VERIFICATION-RUNBOOK.adoc new file mode 100644 index 00000000..10ffbf81 --- /dev/null +++ b/docs/handover/S5-VERIFICATION-RUNBOOK.adoc @@ -0,0 +1,144 @@ +== S5 Verification Runbook: Trained-Weights Verification Flow + +=== Purpose + +This runbook proves end-to-end that once `+just train-cpu+` produces +real weights in `+models/neural/+`, (a) the Julia GNN server picks them +up and stops using cosine similarity, (b) the Rust backends that call +`+gnn_augment_tactics+` receive model-derived scores via the +`+/gnn/rank+` wire format, and (c) MRR on a held-out validation split +can be measured and compared against the 0.66 cosine baseline. Steps 1 +and 2 can run before training has finished; only Step 3 requires +weights. + +''''' + +=== Prerequisite + +`+just train-cpu+` (or `+just train+` on GPU) has completed and +`+models/neural/gnn_ranker/+` (or `+best_model/+` or `+final_model/+`) +exists. + +''''' + +=== Step 1 — Confirm wire format (no training needed) + +[source,bash] +---- +cargo test --test gnn_augment_integration +---- + +Spawns an in-process mock HTTP server and asserts: + +* `+GnnClient::health_status()+` returns the richer payload (model_path, +vocab_size, training_records_received). +* For every backend in `+ProverKind+` whose `+suggest_tactics+` is wired +through `+gnn_augment_tactics+` (S5 pilot 5 + Tier-1 extension 5 + +Tier-1 finisher 2 + Tier-2 sweep 33 + Tier-3/niche sweep 53 — full +coverage as of 2026-05-30): `+suggest_tactics+` returns +`+Tactic::Custom { command: "apply", args: ["lemma_foo"] }+` as the +first tactic, proving the `+/gnn/rank+` wire format is consumed +correctly by every backend. + +Expected output: `+test result: ok. N passed; 0 failed+` where N is +`+1 (health) + |gnn_augment_tactics call-sites|+`. The exact count +tracks the test functions in `+tests/gnn_augment_integration.rs+`; do +not hardcode it in new docs. + +''''' + +=== Step 2 — Confirm model load + +Start the Julia GNN server: + +[source,bash] +---- +julia --project=src/julia src/julia/api_server.jl +---- + +(or however you normally start it — check `+src/julia/run_server.jl+` +for args). Then query health: + +[source,bash] +---- +curl -s http://localhost:8090/gnn/health | jq . +---- + +Expected response when weights are loaded: + +[source,json] +---- +{ + "status": "ok", + "gnn_model_loaded": true, + "model_path": "/absolute/path/to/models/neural/gnn_ranker", + "vocab_size": , + "training_records_received": 0, + "num_gnn_layers": 4, + "service": "echidna-gnn", + "version": "2.1.0" +} +---- + +`+gnn_model_loaded: true+` and `+vocab_size > 0+` confirm the server +picked up real weights and is no longer falling back to cosine +similarity. + +''''' + +=== Step 3 — Measure lift + +[source,bash] +---- +just eval +---- + +Loads the trained model, runs `+compute_metrics+` on the held-out +validation split (20% of `+training_data/+`), and appends one JSONL row +to `+training_data/eval_results.jsonl+`. Read the result: + +[source,bash] +---- +tail -1 training_data/eval_results.jsonl | jq '{mrr, top1, top5, top10, val_size}' +---- + +''''' + +=== Acceptance + +[width="100%",cols="50%,50%",options="header",] +|=== +|Result |Action +|MRR ≥ 0.66 |Baseline met. Log the row. Run `+just train+` on GPU for +full training. + +|MRR < 0.66 |*STOP.* File a bug. Do not paper over it — this signals +architecture mismatch, label leakage, or vocabulary miss. +|=== + +''''' + +=== Troubleshooting + +[width="100%",cols="57%,43%",options="header",] +|=== +|Symptom |Check +|`+gnn_model_loaded: false+` after `+just train-cpu+` |Confirm +`+models/neural/gnn_ranker/+` exists and contains `+model.bson+`, +`+vocabulary.bson+`, `+config.bson+`. Restart the Julia server. + +|Integration test fails on `+connection refused+` |Re-run: +`+cargo test --test gnn_augment_integration+`. The mock binds +`+127.0.0.1:0+`; transient OS port exhaustion is extremely rare but +retry once. + +|`+just eval+` errors with `+No trained model found+` |Run +`+just train-cpu+` first. + +|`+just eval+` errors on a missing solver method |File a bug in the +`+EchidnaML+` Julia module. Do not patch the eval script to bypass. + +|MRR unchanged from 0.66 after training |Check +`+models/model_metadata.txt+` — if it still reads `+0 words, 0 classes+` +the training run did not write weights. Check training logs. +|=== diff --git a/docs/handover/S5-VERIFICATION-RUNBOOK.md b/docs/handover/S5-VERIFICATION-RUNBOOK.md deleted file mode 100644 index 65207ec5..00000000 --- a/docs/handover/S5-VERIFICATION-RUNBOOK.md +++ /dev/null @@ -1,113 +0,0 @@ -# S5 Verification Runbook: Trained-Weights Verification Flow - -## Purpose - -This runbook proves end-to-end that once `just train-cpu` produces real weights -in `models/neural/`, (a) the Julia GNN server picks them up and stops using cosine -similarity, (b) the Rust backends that call `gnn_augment_tactics` receive -model-derived scores via the `/gnn/rank` wire format, and (c) MRR on a held-out -validation split can be measured and compared against the 0.66 cosine baseline. -Steps 1 and 2 can run before training has finished; only Step 3 requires weights. - ---- - -## Prerequisite - -`just train-cpu` (or `just train` on GPU) has completed and -`models/neural/gnn_ranker/` (or `best_model/` or `final_model/`) exists. - ---- - -## Step 1 — Confirm wire format (no training needed) - -```bash -cargo test --test gnn_augment_integration -``` - -Spawns an in-process mock HTTP server and asserts: - -- `GnnClient::health_status()` returns the richer payload (model_path, vocab_size, - training_records_received). -- For every backend in `ProverKind` whose `suggest_tactics` is wired through - `gnn_augment_tactics` (S5 pilot 5 + Tier-1 extension 5 + Tier-1 finisher 2 + - Tier-2 sweep 33 + Tier-3/niche sweep 53 — full coverage as of 2026-05-30): - `suggest_tactics` returns `Tactic::Custom { command: "apply", args: ["lemma_foo"] }` - as the first tactic, proving the `/gnn/rank` wire format is consumed correctly - by every backend. - -Expected output: `test result: ok. N passed; 0 failed` where N is -`1 (health) + |gnn_augment_tactics call-sites|`. The exact count tracks the -test functions in `tests/gnn_augment_integration.rs`; do not hardcode it in -new docs. - ---- - -## Step 2 — Confirm model load - -Start the Julia GNN server: - -```bash -julia --project=src/julia src/julia/api_server.jl -``` - -(or however you normally start it — check `src/julia/run_server.jl` for args). -Then query health: - -```bash -curl -s http://localhost:8090/gnn/health | jq . -``` - -Expected response when weights are loaded: - -```json -{ - "status": "ok", - "gnn_model_loaded": true, - "model_path": "/absolute/path/to/models/neural/gnn_ranker", - "vocab_size": , - "training_records_received": 0, - "num_gnn_layers": 4, - "service": "echidna-gnn", - "version": "2.1.0" -} -``` - -`gnn_model_loaded: true` and `vocab_size > 0` confirm the server picked up real weights -and is no longer falling back to cosine similarity. - ---- - -## Step 3 — Measure lift - -```bash -just eval -``` - -Loads the trained model, runs `compute_metrics` on the held-out validation split -(20% of `training_data/`), and appends one JSONL row to -`training_data/eval_results.jsonl`. Read the result: - -```bash -tail -1 training_data/eval_results.jsonl | jq '{mrr, top1, top5, top10, val_size}' -``` - ---- - -## Acceptance - -| Result | Action | -|--------|--------| -| MRR ≥ 0.66 | Baseline met. Log the row. Run `just train` on GPU for full training. | -| MRR < 0.66 | **STOP.** File a bug. Do not paper over it — this signals architecture mismatch, label leakage, or vocabulary miss. | - ---- - -## Troubleshooting - -| Symptom | Check | -|---------|-------| -| `gnn_model_loaded: false` after `just train-cpu` | Confirm `models/neural/gnn_ranker/` exists and contains `model.bson`, `vocabulary.bson`, `config.bson`. Restart the Julia server. | -| Integration test fails on `connection refused` | Re-run: `cargo test --test gnn_augment_integration`. The mock binds `127.0.0.1:0`; transient OS port exhaustion is extremely rare but retry once. | -| `just eval` errors with `No trained model found` | Run `just train-cpu` first. | -| `just eval` errors on a missing solver method | File a bug in the `EchidnaML` Julia module. Do not patch the eval script to bypass. | -| MRR unchanged from 0.66 after training | Check `models/model_metadata.txt` — if it still reads `0 words, 0 classes` the training run did not write weights. Check training logs. | diff --git a/docs/handover/SESSION-HANDOFF-2026-06-15.adoc b/docs/handover/SESSION-HANDOFF-2026-06-15.adoc new file mode 100644 index 00000000..ea190ebd --- /dev/null +++ b/docs/handover/SESSION-HANDOFF-2026-06-15.adoc @@ -0,0 +1,151 @@ +== Session handoff — 2026-06-15 + +Snapshot of the estate-reconciliation work (echidna + echidnabot) for +the next session. Master tracker *echidna#238 is closed*; remaining work +is split into discrete issues, captured below by normative tier (MUST / +INTEND / WISH). + +Legend: *done* = merged this campaign · *open* = tracked issue · *owner* += needs the repo owner (policy/SPDX/branch-delete) · *blocked* = gated +on another item. + +=== Status — ECHIDNA + +[width="100%",cols="24%,24%,32%,20%",options="header",] +|=== +|Tier |Item |Status |Ref +|MUST |Proof corpus repaired + CI-gated (Coq/Lean/Agda/Idris2) |done +|#234 / #244 + +|MUST |Every workflow job has `+timeout-minutes+` |done |#247 (closed +#241) + +|MUST |`+hooks/+` dir (RSR pre-commit-enforcement requirement) |this PR +|#254·2 + +|MUST |`+src/rust/main.rs+` SPDX hook blocks _all_ commits to it |open · +owner 1-liner |#216 + +|MUST |`+creusot-verify+` CI red (`+alt-ergo+` not apt-installable) +|open |#250 + +|MUST |`+salt/+`/Python rule stale vs standards (no `+salt/+` exists) +|open · owner doc |#254·1 + +|MUST |Prover-count drift (48/105/113/128 vs `+PROVER_COUNT.md+`) |open +· owner (R5a) |#251 + +|INTEND |`+--features verisim+` 22 compile errors |open |#245 + +|INTEND |machine_readable + contractile currency audit |open |#252 + +|INTEND |Reconcile remaining RSR divergences (lang-tier undeclared) +|open |#254·3 + +|INTEND |Delete 6 reconciled stale branches |open · owner (proxy 403) +|#253 + +|INTEND |Wire 13 dispatcher adapters |blocked by #216 +|`+feat/corpus-dispatcher-all-17-adapters+` + +|INTEND |Structural-drift stale paths; AffineScript→AffineScript +migration |open |#242, #240, #266 + +|WISH |Split Rust/FFI/proof safety alerts by risk class |open |#239 + +|WISH |GNN-at-scale; Cap’n Proto / Chapel-full / coprocessors; 8-stage +endpoint |aspirational |`+docs/ROADMAP.md+` +|=== + +=== Status — ECHIDNABOT + +[width="100%",cols="24%,24%,32%,20%",options="header",] +|=== +|Tier |Item |Status |Ref +|MUST |README test-count 129→184 + ProverSlug |done |#86 + +|MUST |`+echidna-fuzz+` rate-limit-check timeout |done |#89 + +|MUST |`+LICENSE+` missing SPDX header (Licence-consistency fails every +PR) |open · owner-only |#87 + +|MUST |`+.gitignore+`/`+.gitattributes+` PMPL→MPL SPDX drift |open · +owner-only |#83 + +|MUST |`+gitbot-shared-context+` path dep (no bare-clone build) +|accepted debt — do not fix |#18 + +|MUST-NOT |`+admitted_stub.v+` / `+sorry_stub.lean+` |intentional +dogfood failures — leave |— + +|INTEND |Post-checkpoint hygiene (STATE dual-truth, SESSION_SUMMARY, +contractiles, `+.scm+`, SONNET-TASKS, `+curl\|sh+`) |open |#88 + +|INTEND |`+proof-debt.md+` TBD→rationale; cflite shared-context +vendoring |open |#68, #67 + +|WISH |Codeberg adapter; pre-built Podman images; K8s distributed; full +bot-modes |aspirational |#62, #61, #59 +|=== + +=== Hard constraints (carry forward — these OVERRIDE defaults) + +* *Languages:* no Python (the `+salt/+` exception was removed upstream), +no TypeScript, no Go. Use Rust / Julia / Idris2 / Agda / Zig / Chapel / +AffineScript / Nickel per `+CLAUDE.md+`. +* *Build:* Justfile primary (RSR-H14). *Containers:* Podman + +`+Containerfile+`, never Docker/`+Dockerfile+` (RSR-H15). *Packaging:* +Guix; *no Guix* (`+flake.guix+`/`+flake.lock+` banned estate-wide). +* *SPDX / LICENSE edits are owner-only, manual, file-by-file* (#216 / +#83 / #87) — never automate; automated sweeps must not touch licence +headers. +* *echidnabot dogfood stubs* (`+admitted_stub.v+`, `+sorry_stub.lean+`) +are intentional failures — never "`fix`". +* *echidnabot* cannot `+cargo build+` from a bare clone (path-dep #18) — +for code work use a `+gitbot-fleet+` monorepo checkout; doc work is fine +standalone. +* *Branch ref-deletes return HTTP 403* via the session git proxy and the +GitHub MCP has no delete-branch tool, so branch cleanup (#253) is +*owner-only*. +* Develop on `+claude/+` branches; open *draft* PRs; be *frugal* +with GitHub comments. + +=== Prompt for the next session + +Copy-paste the block below to the next Claude: + +____ +Continue estate maintenance on `+hyperpolymath/echidna+` + +`+hyperpolymath/echidnabot+`. + +*First read:* echidna issue #238 (closed master checkpoint), +`+docs/handover/SESSION-HANDOFF-2026-06-15.md+`, `+AFFIRMATION.adoc+`, +and both repos’ `+CLAUDE.md+` (their rules OVERRIDE defaults). + +*Where things stand:* the multi-language proof corpus is repaired, +CI-gated, and green on `+main+`; the master checkpoint is closed; all +this campaign’s PRs merged. Remaining work is in discrete issues, +grouped MUST / INTEND / WISH in the handoff doc. + +*Pick up in this order:* 1. _Flag to the owner (don’t auto-do — +SPDX/policy/branch-delete):_ #216 (main.rs SPDX hook — unblocks the +`+feat/corpus-dispatcher-all-17-adapters+` branch), echidnabot #87 + #83 +(LICENSE/SPDX), #251 (prover-count — fix the GitHub repo description +first), #253 (delete the 6 stale branches). 2. _Doable now, as draft +PRs:_ #250 (install `+alt-ergo+` via opam in +`+formal-verification.yml+`), #245 (`+--features verisim+` — 22 compile +errors), #252 (machine_readable + contractile currency audit — run a +Haiku scout before bulk edits), #254 (reconcile the RSR divergences: +drop the stale `+salt/+` wording, declare the polyglot language set as +an out-of-template adaptation), echidnabot #88 (hygiene). + +*Honor the hard constraints* in the handoff doc (SPDX = owner-only; +dogfood stubs intentional; Podman/Justfile/Guix; no Python/TS/Go). +Develop on `+claude/+` branches, open draft PRs, keep GitHub +comments frugal. +____ + +''''' + +_Generated 2026-06-15. Source of truth for status: the linked issues + +`+CHANGELOG.md+` + git log; this snapshot drifts._ diff --git a/docs/handover/SESSION-HANDOFF-2026-06-15.md b/docs/handover/SESSION-HANDOFF-2026-06-15.md deleted file mode 100644 index a5b9ef03..00000000 --- a/docs/handover/SESSION-HANDOFF-2026-06-15.md +++ /dev/null @@ -1,72 +0,0 @@ - - -# Session handoff — 2026-06-15 - -Snapshot of the estate-reconciliation work (echidna + echidnabot) for the next -session. Master tracker **echidna#238 is closed**; remaining work is split into -discrete issues, captured below by normative tier (MUST / INTEND / WISH). - -Legend: **done** = merged this campaign · **open** = tracked issue · **owner** = -needs the repo owner (policy/SPDX/branch-delete) · **blocked** = gated on another item. - -## Status — ECHIDNA - -| Tier | Item | Status | Ref | -|------|------|--------|-----| -| MUST | Proof corpus repaired + CI-gated (Coq/Lean/Agda/Idris2) | done | #234 / #244 | -| MUST | Every workflow job has `timeout-minutes` | done | #247 (closed #241) | -| MUST | `hooks/` dir (RSR pre-commit-enforcement requirement) | this PR | #254·2 | -| MUST | `src/rust/main.rs` SPDX hook blocks *all* commits to it | open · owner 1-liner | #216 | -| MUST | `creusot-verify` CI red (`alt-ergo` not apt-installable) | open | #250 | -| MUST | `salt/`/Python rule stale vs standards (no `salt/` exists) | open · owner doc | #254·1 | -| MUST | Prover-count drift (48/105/113/128 vs `PROVER_COUNT.md`) | open · owner (R5a) | #251 | -| INTEND | `--features verisim` 22 compile errors | open | #245 | -| INTEND | machine_readable + contractile currency audit | open | #252 | -| INTEND | Reconcile remaining RSR divergences (lang-tier undeclared) | open | #254·3 | -| INTEND | Delete 6 reconciled stale branches | open · owner (proxy 403) | #253 | -| INTEND | Wire 13 dispatcher adapters | blocked by #216 | `feat/corpus-dispatcher-all-17-adapters` | -| INTEND | Structural-drift stale paths; AffineScript→AffineScript migration | open | #242, #240, #266 | -| WISH | Split Rust/FFI/proof safety alerts by risk class | open | #239 | -| WISH | GNN-at-scale; Cap'n Proto / Chapel-full / coprocessors; 8-stage endpoint | aspirational | `docs/ROADMAP.md` | - -## Status — ECHIDNABOT - -| Tier | Item | Status | Ref | -|------|------|--------|-----| -| MUST | README test-count 129→184 + ProverSlug | done | #86 | -| MUST | `echidna-fuzz` rate-limit-check timeout | done | #89 | -| MUST | `LICENSE` missing SPDX header (Licence-consistency fails every PR) | open · owner-only | #87 | -| MUST | `.gitignore`/`.gitattributes` PMPL→MPL SPDX drift | open · owner-only | #83 | -| MUST | `gitbot-shared-context` path dep (no bare-clone build) | accepted debt — do not fix | #18 | -| MUST-NOT | `admitted_stub.v` / `sorry_stub.lean` | intentional dogfood failures — leave | — | -| INTEND | Post-checkpoint hygiene (STATE dual-truth, SESSION_SUMMARY, contractiles, `.scm`, SONNET-TASKS, `curl\|sh`) | open | #88 | -| INTEND | `proof-debt.md` TBD→rationale; cflite shared-context vendoring | open | #68, #67 | -| WISH | Codeberg adapter; pre-built Podman images; K8s distributed; full bot-modes | aspirational | #62, #61, #59 | - -## Hard constraints (carry forward — these OVERRIDE defaults) -- **Languages:** no Python (the `salt/` exception was removed upstream), no TypeScript, no Go. Use Rust / Julia / Idris2 / Agda / Zig / Chapel / AffineScript / Nickel per `CLAUDE.md`. -- **Build:** Justfile primary (RSR-H14). **Containers:** Podman + `Containerfile`, never Docker/`Dockerfile` (RSR-H15). **Packaging:** Guix; **no Guix** (`flake.guix`/`flake.lock` banned estate-wide). -- **SPDX / LICENSE edits are owner-only, manual, file-by-file** (#216 / #83 / #87) — never automate; automated sweeps must not touch licence headers. -- **echidnabot dogfood stubs** (`admitted_stub.v`, `sorry_stub.lean`) are intentional failures — never "fix". -- **echidnabot** cannot `cargo build` from a bare clone (path-dep #18) — for code work use a `gitbot-fleet` monorepo checkout; doc work is fine standalone. -- **Branch ref-deletes return HTTP 403** via the session git proxy and the GitHub MCP has no delete-branch tool, so branch cleanup (#253) is **owner-only**. -- Develop on `claude/` branches; open **draft** PRs; be **frugal** with GitHub comments. - -## Prompt for the next session - -Copy-paste the block below to the next Claude: - -> Continue estate maintenance on `hyperpolymath/echidna` + `hyperpolymath/echidnabot`. -> -> **First read:** echidna issue #238 (closed master checkpoint), `docs/handover/SESSION-HANDOFF-2026-06-15.md`, `AFFIRMATION.adoc`, and both repos' `CLAUDE.md` (their rules OVERRIDE defaults). -> -> **Where things stand:** the multi-language proof corpus is repaired, CI-gated, and green on `main`; the master checkpoint is closed; all this campaign's PRs merged. Remaining work is in discrete issues, grouped MUST / INTEND / WISH in the handoff doc. -> -> **Pick up in this order:** -> 1. *Flag to the owner (don't auto-do — SPDX/policy/branch-delete):* #216 (main.rs SPDX hook — unblocks the `feat/corpus-dispatcher-all-17-adapters` branch), echidnabot #87 + #83 (LICENSE/SPDX), #251 (prover-count — fix the GitHub repo description first), #253 (delete the 6 stale branches). -> 2. *Doable now, as draft PRs:* #250 (install `alt-ergo` via opam in `formal-verification.yml`), #245 (`--features verisim` — 22 compile errors), #252 (machine_readable + contractile currency audit — run a Haiku scout before bulk edits), #254 (reconcile the RSR divergences: drop the stale `salt/` wording, declare the polyglot language set as an out-of-template adaptation), echidnabot #88 (hygiene). -> -> **Honor the hard constraints** in the handoff doc (SPDX = owner-only; dogfood stubs intentional; Podman/Justfile/Guix; no Python/TS/Go). Develop on `claude/` branches, open draft PRs, keep GitHub comments frugal. - ---- -_Generated 2026-06-15. Source of truth for status: the linked issues + `CHANGELOG.md` + git log; this snapshot drifts._ diff --git a/docs/handover/STATE.adoc b/docs/handover/STATE.adoc new file mode 100644 index 00000000..9cd646ec --- /dev/null +++ b/docs/handover/STATE.adoc @@ -0,0 +1,266 @@ +== Echidna Production-Wiring — State of Things + +*Where we are now, in relation to the forward vision.* Complements +`+ECHIDNA-TODO.md+` (actionable backlog) and the full continuation +prompts at `+verification-ecosystem/echidna/docs/handover/+`. + +Last updated: 2026-04-26. + +''''' + +=== Vision (one paragraph) + +Take Echidna from "`48 / 105 backends trait-wired with mock-only CI`" to +"`production-level live subprocess CI across ~38 backends, Cap’n Proto +IPC end-to-end, Chapel as first-class parallel execution layer.`" Three +phases, deliberately sequenced *L3 → L1 → L2*: live-prover CI first +because it surfaces real bugs mocks hide, Cap’n Proto next so Chapel can +consume its schemas, Chapel last because its sub-waves are the largest +piece. Guix is the sole authoritative package manager throughout (guix +fallback removed 2026-06-01 per estate-wide guix-deprecation directive). +GitHub is the single source of truth; no other forges pushed directly. + +=== Decisions locked + +[width="100%",cols="14%,41%,45%",options="header",] +|=== +|# |Decision |Rationale +|D1 |*Serialization = Cap’n Proto* |Chosen over Bebop3 for dependability ++ maturity (Cloudflare Workers use at scale), zero-copy reads, strong +schema-evolution. Tradeoff: heavier codegen; shim Julia/Chapel via C-ABI +(fits existing Idris2-ABI + Zig-FFI). + +|D2 |*Chapel = first-class, maximal* |420-LoC POC promoted to +`+src/chapel/+` across 7 sub-waves — portfolio dispatch, speculative +tactic search, corpus-parallel ops, mutation-testing parallelism, +multi-locale distributed, numeric hot paths. + +|D3 |*Guix sole primary* |Per project CLAUDE.md. `+guix.scm+` / +`+manifests/live-provers.scm+` authoritative. (Originally "`Guix +fallback`"; that path closed 2026-06-01 per estate-wide guix-deprecation +directive.) + +|D4 |*Execution order = L3 → L1 → L2* |Live-prover CI first: +highest-leverage gap, surfaces real bugs mocks hide. Cap’n Proto next, +since Chapel consumes those schemas. + +|D5 |*Live-prover CI cadence tiered* |T1 every PR, T2 nightly, T3 +weekly, T4 quarterly allow-fail. + +|D6 |*No JSON emit on hot path* |Per `+feedback_no_json_emit_a2ml+`. +Cap’n Proto replaces HTTP-JSON Rust↔Julia. Tool config stays +Nickel/A2ML. +|=== + +=== Current state per phase + +==== L3 — Live-Prover CI — PARTIALLY SHIPPED + +Four waves. First two done, third and fourth scaffolded only. + +[width="100%",cols="21%,23%,26%,30%",options="header",] +|=== +|Wave |Scope |Status |Commits +|Wave-1 |Tier-1 apt-installable (9 backends) every PR: Z3, CVC5, +Vampire, EProver, SPASS, Alt-Ergo, GLPK, MiniZinc, Chuffed |*DONE* +2026-04-19 |`+b022bf4+` + +|Wave-2 |Tier-2 build-from-source (10 backends) nightly: coq/agda/why3 +(apt), idris2 (source bootstrap), lean4 (elan), isabelle (Isabelle2024 +tarball), dafny (dotnet tool), fstar (release tarball), tlaps +(installer). hol-light deferred to Wave-3. |*DONE 2026-04-19* locally; +CI-unverified |`+9a4aeeb+`, `+6717b12+` + +|Wave-3 |Tier-3 weekly, 9 backends (Tamarin, ProVerif, Imandra, SCIP, +OR-Tools, HOL4, ACL2, Twelf, Metamath). Needs per-backend Containerfiles +(Podman). |*SCAFFOLD ONLY* — handover hints in STATE.a2ml |— + +|Wave-4 |Tier-4 quarterly, 19 backends. Retained as mock-only unless a +maintainer volunteers. |*SCAFFOLD ONLY* |— +|=== + +Local verification of Wave-1 + Wave-2: *18/18 live tests pass* (13 real +versions returned, 5 auto-skipped for missing binaries: +GLPK/SPASS/MiniZinc/TLAPS/Chuffed). + +*Dafny flagged as shallow* (165 LoC subprocess wrapper). Live +version-check passes but the wiring is stub-ish — needs L3-phase +deepening before mocks retire. + +==== L1 — Cap’n Proto Protocol Swap — NOT STARTED + +Blockers: L3 Tier-1 green on main for ≥ 7 days. Current IPC: - *Rust ↔ +Julia*: HTTP + JSON (`+src/rust/gnn/client.rs:1-195+` → +`+src/julia/api_server.jl:8090+`) — violates `+no_json_emit+`. - *Rust ↔ +Chapel*: Stub (Zig bridge self-links but not in dispatch path). - *Rust +↔ gRPC*: schema-only; `+dispatch.rs+` uses in-process traits. + +==== L2 — Chapel Maximum Integration — PARTIALLY PREPARED + +* 420-LoC POC at `+chapel_poc/parallel_proof_search.chpl+` + Chapel +`+export+` functions at `+chapel_poc/chapel_ffi_exports.chpl+`. +* Zig FFI bridge at `+src/zig_ffi/chapel_bridge.zig+` — *now self-links* +against bundled stubs (commit `+53ab9b8+`, 2026-04-19). +`+cargo build --features chapel+` works standalone; 6/6 `+proof_search+` +tests pass. +* Nothing in dispatch path yet. No `+src/chapel/+` directory. All 7 +sub-waves pending. + +=== Wiring depth snapshot (from 2026-04-19 audit) + +* *Deep* (persistent process + structured protocol parsing): Z3, CVC5, +Coq (SerAPI), Lean 4, Idris2. +* *Medium* (subprocess + output parse, no streaming): Agda, Vampire. +* *Stub-ish / thin*: Dafny (165 LoC) — flagged for hardening during L3. + +Also corrected 2026-04-19 (were mis-listed as "`planned`"): - *Tamarin* +— fully wired (`+provers/tamarin.rs+`, 592 LoC, registered in +`+ProverFactory+`, 4 unit tests). - *ProVerif* — fully wired +(`+provers/proverif.rs+`, 799 LoC, registered). - *No TODO/FIXME in +`+src/rust/+`* — 0 matches; standing property. + +=== Corpus + +66,674 proofs across 16 prover systems (`+COMPLETE_CORPUS_SUMMARY.md+`). +179,933 tactics, 10,599 unique tactic signatures, 300 indexed premises. +Untouched this session. + +=== CI today + +* `+.github/workflows/rust-ci.yml+` — mock-only tests on every PR. +Baseline smoke. +* `+.github/workflows/chapel-ci.yml+` — compiles Chapel POC and the Zig +FFI bridge. *Does not feed into dispatch* and *does not link real +Chapel*; tests run against bundled stubs only. +* `+.github/workflows/live-provers.yml+` — tiered workflow (T1 PR, T2 +nightly, T3 weekly, T4 quarterly). T1 + T2 matrices filled with real +provisioning; T3 + T4 placeholder jobs. +* `+.github/workflows/agda-meta-checker.yml+` — formally-verified +trust-pipeline properties. + +=== Architectural invariants (from 0-AI-MANIFEST.a2ml + CLAUDE.md) + +* *Idris2 ABI* for formal proofs; zero `+believe_me+`. +* *Zig FFI* for C-ABI bridges to polyglot consumers. +* *Justfile* primary build system; not Make. +* *Containerfile* + Podman; not Dockerfile / Docker. +* *State files in `+.machine_readable/descriptiles/+` only*; never root. +* *All interfaces under `+src/interfaces/+`*; never extract to separate +repos. +* *When adding provers: update all 3 layers* (Rust backend, Julia ML, +Chapel). +* *Original name: "`Cognitive Hybrid`"* not "`Computational Heuristic`". +* *MPL-2.0* throughout. +* *No Python* — Julia for ML, Rust for systems, AffineScript for apps. + +=== Tech stack + +* *Primary*: Rust (48 / 105 prover backends, trust pipeline, CLI, REPL, +API servers). +* *Secondary*: Julia (ML inference, port 8090), AffineScript + Deno (UI, +33 files, zero TypeScript). +* *Optional*: Chapel (parallel proof dispatch). +* *ABI*: Idris2 (7+ modules, zero `+believe_me+`). +* *FFI*: Zig (4 shared libraries). +* *Interfaces*: GraphQL (8081), gRPC (50051), REST (8000). All three +interface crates build clean as of 2026-04-26. +* *Build*: Justfile primary, Cargo workspace. +* *Container*: Podman + Containerfile. + +=== 11-step trust pipeline (v1.5+) + +[arabic] +. Solver binary integrity (SHAKE3-512 + BLAKE3). +. SMT portfolio solving / cross-checking. +. Proof certificate checking (Alethe, DRAT/LRAT, TSTP). +. Axiom usage tracking (4 danger levels). +. Solver sandboxing (Podman, bubblewrap). +. 5-level trust hierarchy for confidence scoring. +. Mutation testing for specifications. +. Prover dispatch pipeline. +. Cross-prover proof exchange (OpenTheory, Dedukti). +. Pareto frontier (multi-objective proof search). +. Bayesian timeout estimation. + +=== v2.x roadmap (from CLAUDE.md) + +* *v2.1 (landed)*: GNN proof graph construction (7 node kinds, 8 edge +kinds); 32-dim local term embeddings + GNN inference client; GNN-guided +proof search (hybrid GNN + symbolic scoring); Julia `+/gnn/rank+` +endpoint with cosine fallback; Idris2 formal proofs (7 GNN properties, 0 +`+believe_me+`); 28 new tests. +* *v2.2*: Train GNN/Transformer on larger corpus (Flux.jl); Chapel → +Rust C FFI bridge *(the Zig layer is done; dispatch-path integration is +the L2 work above)*; Tamarin/ProVerif bridge *(already landed — stale in +the roadmap)*. + +=== Handover artefacts (in-repo, canonical) + +[width="100%",cols="50%,50%",options="header",] +|=== +|File |Role +|`+verification-ecosystem/echidna/docs/handover/PRODUCTION-WIRING-PLAN.md+` +|Master plan + +|`+verification-ecosystem/echidna/docs/handover/L1-CAPNPROTO-PROMPT.md+` +|L1 Cap’n Proto continuation prompt + +|`+verification-ecosystem/echidna/docs/handover/L2-CHAPEL-PROMPT.md+` +|L2 Chapel continuation prompt + +|`+verification-ecosystem/echidna/docs/handover/L3-LIVE-PROVER-CI-PROMPT.md+` +|L3 live-prover continuation prompt (marked Wave-2 DONE, pointing to +Wave-3) + +|`+verification-ecosystem/echidna/.machine_readable/descriptiles/STATE.a2ml+` +|Session ledger incl. `+[l3-status-after-wave-2]+` + +`+[wave-3-handover-hints]+` + +|`+verification-ecosystem/echidna/docs/handover/README.md+` |Index + +drift-handling policy +|=== + +=== Session log highlights (2026-04-26) + +* *echidna-graphql build fixed* (`+5aec9d5+`) — ProverKind enum expanded +from 30 → 113 variants (exhaustive, no catch-all) across schema.rs + +resolvers.rs + ffi_wrapper.rs; FfiProverBackend trait wired +(config/set_config/search_theorems); FFI pointer casts corrected. +`+cargo build -p echidna-graphql+` now clean. +* *FFI boundary audit* (`+b4d682b+`) — `+audits/audit-ffi-boundary.md+` +(4-section per-module safety review) + +`+audits/assail-classifications.a2ml+` (7 classifications suppressing +legitimate UnsafeCode at all three interface ffi_wrapper.rs files + core +ffi/ + proof_search.rs). panic-attack findings drop from active to +classified. +* *bounded_read_config helper* — `+src/rust/integrity/io.rs+` ships sync +1 MiB-capped read helper; `+solver_integrity.rs+` migrated. Remaining +UnboundedAllocation finding resolved. +* *F5 deferred* — `+boj-server+` `+echidna-llm-mcp+` cartridge real +invocation is the one remaining open item. BoJ currently operates in +skeleton mode for this cartridge; echidna REST layer is fully wired to +its boundary. + +=== Session log highlights (2026-04-19) + +* *Chapel FFI self-link fix* (`+53ab9b8+`) — `+-Dstubs=true+` default in +`+src/zig_ffi/build.zig+`; `+-fno-sanitize=undefined+` flag; +`+use anyhow::Context;+` in `+proof_search.rs+`. +`+cargo build --features chapel+` now links standalone. +* *Stale-gap corrections* — Tamarin + ProVerif marked fully wired; zero +TODO/FIXME standing property; Chapel FFI "`not yet wired`" was actually +a link-time gap, fixed. +* *L3 Wave-2 installers* — idris2 source bootstrap against Chez Scheme; +isabelle Isabelle2024 tarball; dafny `+dotnet tool install+`; fstar +release tarball (binary `+fstar.exe+` even on Linux); tlaps +self-extracting installer (`+tlapm+`). hol-light deferred to Wave-3. +* *Tests extended* — `+live_fstar_version+` + `+live_tlaps_version+` +added; `+kind_label+` gained FStar / TLAPS; `+ProverConfig+` literal +gained missing `+library_paths+` field (pre-existing compile error +fixed). +* *Docs + `+.gitignore+`* — `+QUICKSTART-DEV.adoc+` chapel-feature build +instructions; `+chapel_poc/README.md+` "`Add FFI bindings to call from +Rust`" marked DONE; `+.gitignore+` adds `+models/e*/+`, `+/models_e*/+`, +`+src/zig_ffi/zig-out/+`, `+.zig-cache/+`. +* *Mirrored* — all 4 Desktop handover docs now in-repo at +`+docs/handover/+` (commit `+b6d437c+`). diff --git a/docs/handover/STATE.md b/docs/handover/STATE.md deleted file mode 100644 index 439cb1fc..00000000 --- a/docs/handover/STATE.md +++ /dev/null @@ -1,155 +0,0 @@ -# Echidna Production-Wiring — State of Things - -**Where we are now, in relation to the forward vision.** Complements -`ECHIDNA-TODO.md` (actionable backlog) and the full continuation -prompts at `verification-ecosystem/echidna/docs/handover/`. - -Last updated: 2026-04-26. - ---- - -## Vision (one paragraph) - -Take Echidna from "48 / 105 backends trait-wired with mock-only CI" to -"production-level live subprocess CI across ~38 backends, Cap'n Proto -IPC end-to-end, Chapel as first-class parallel execution layer." Three -phases, deliberately sequenced **L3 → L1 → L2**: live-prover CI first -because it surfaces real bugs mocks hide, Cap'n Proto next so Chapel -can consume its schemas, Chapel last because its sub-waves are the -largest piece. Guix is the sole authoritative package manager -throughout (guix fallback removed 2026-06-01 per estate-wide -guix-deprecation directive). GitHub is the single source of truth; no -other forges pushed directly. - -## Decisions locked - -| # | Decision | Rationale | -|---|----------|-----------| -| D1 | **Serialization = Cap'n Proto** | Chosen over Bebop3 for dependability + maturity (Cloudflare Workers use at scale), zero-copy reads, strong schema-evolution. Tradeoff: heavier codegen; shim Julia/Chapel via C-ABI (fits existing Idris2-ABI + Zig-FFI). | -| D2 | **Chapel = first-class, maximal** | 420-LoC POC promoted to `src/chapel/` across 7 sub-waves — portfolio dispatch, speculative tactic search, corpus-parallel ops, mutation-testing parallelism, multi-locale distributed, numeric hot paths. | -| D3 | **Guix sole primary** | Per project CLAUDE.md. `guix.scm` / `manifests/live-provers.scm` authoritative. (Originally "Guix fallback"; that path closed 2026-06-01 per estate-wide guix-deprecation directive.) | -| D4 | **Execution order = L3 → L1 → L2** | Live-prover CI first: highest-leverage gap, surfaces real bugs mocks hide. Cap'n Proto next, since Chapel consumes those schemas. | -| D5 | **Live-prover CI cadence tiered** | T1 every PR, T2 nightly, T3 weekly, T4 quarterly allow-fail. | -| D6 | **No JSON emit on hot path** | Per `feedback_no_json_emit_a2ml`. Cap'n Proto replaces HTTP-JSON Rust↔Julia. Tool config stays Nickel/A2ML. | - -## Current state per phase - -### L3 — Live-Prover CI — PARTIALLY SHIPPED - -Four waves. First two done, third and fourth scaffolded only. - -| Wave | Scope | Status | Commits | -|------|-------|--------|---------| -| Wave-1 | Tier-1 apt-installable (9 backends) every PR: Z3, CVC5, Vampire, EProver, SPASS, Alt-Ergo, GLPK, MiniZinc, Chuffed | **DONE** 2026-04-19 | `b022bf4` | -| Wave-2 | Tier-2 build-from-source (10 backends) nightly: coq/agda/why3 (apt), idris2 (source bootstrap), lean4 (elan), isabelle (Isabelle2024 tarball), dafny (dotnet tool), fstar (release tarball), tlaps (installer). hol-light deferred to Wave-3. | **DONE 2026-04-19** locally; CI-unverified | `9a4aeeb`, `6717b12` | -| Wave-3 | Tier-3 weekly, 9 backends (Tamarin, ProVerif, Imandra, SCIP, OR-Tools, HOL4, ACL2, Twelf, Metamath). Needs per-backend Containerfiles (Podman). | **SCAFFOLD ONLY** — handover hints in STATE.a2ml | — | -| Wave-4 | Tier-4 quarterly, 19 backends. Retained as mock-only unless a maintainer volunteers. | **SCAFFOLD ONLY** | — | - -Local verification of Wave-1 + Wave-2: **18/18 live tests pass** (13 real versions returned, 5 auto-skipped for missing binaries: GLPK/SPASS/MiniZinc/TLAPS/Chuffed). - -**Dafny flagged as shallow** (165 LoC subprocess wrapper). Live version-check passes but the wiring is stub-ish — needs L3-phase deepening before mocks retire. - -### L1 — Cap'n Proto Protocol Swap — NOT STARTED - -Blockers: L3 Tier-1 green on main for ≥ 7 days. Current IPC: -- **Rust ↔ Julia**: HTTP + JSON (`src/rust/gnn/client.rs:1-195` → `src/julia/api_server.jl:8090`) — violates `no_json_emit`. -- **Rust ↔ Chapel**: Stub (Zig bridge self-links but not in dispatch path). -- **Rust ↔ gRPC**: schema-only; `dispatch.rs` uses in-process traits. - -### L2 — Chapel Maximum Integration — PARTIALLY PREPARED - -- 420-LoC POC at `chapel_poc/parallel_proof_search.chpl` + Chapel `export` functions at `chapel_poc/chapel_ffi_exports.chpl`. -- Zig FFI bridge at `src/zig_ffi/chapel_bridge.zig` — **now self-links** against bundled stubs (commit `53ab9b8`, 2026-04-19). `cargo build --features chapel` works standalone; 6/6 `proof_search` tests pass. -- Nothing in dispatch path yet. No `src/chapel/` directory. All 7 sub-waves pending. - -## Wiring depth snapshot (from 2026-04-19 audit) - -- **Deep** (persistent process + structured protocol parsing): Z3, CVC5, Coq (SerAPI), Lean 4, Idris2. -- **Medium** (subprocess + output parse, no streaming): Agda, Vampire. -- **Stub-ish / thin**: Dafny (165 LoC) — flagged for hardening during L3. - -Also corrected 2026-04-19 (were mis-listed as "planned"): -- **Tamarin** — fully wired (`provers/tamarin.rs`, 592 LoC, registered in `ProverFactory`, 4 unit tests). -- **ProVerif** — fully wired (`provers/proverif.rs`, 799 LoC, registered). -- **No TODO/FIXME in `src/rust/`** — 0 matches; standing property. - -## Corpus - -66,674 proofs across 16 prover systems (`COMPLETE_CORPUS_SUMMARY.md`). 179,933 tactics, 10,599 unique tactic signatures, 300 indexed premises. Untouched this session. - -## CI today - -- `.github/workflows/rust-ci.yml` — mock-only tests on every PR. Baseline smoke. -- `.github/workflows/chapel-ci.yml` — compiles Chapel POC and the Zig FFI bridge. **Does not feed into dispatch** and **does not link real Chapel**; tests run against bundled stubs only. -- `.github/workflows/live-provers.yml` — tiered workflow (T1 PR, T2 nightly, T3 weekly, T4 quarterly). T1 + T2 matrices filled with real provisioning; T3 + T4 placeholder jobs. -- `.github/workflows/agda-meta-checker.yml` — formally-verified trust-pipeline properties. - -## Architectural invariants (from 0-AI-MANIFEST.a2ml + CLAUDE.md) - -- **Idris2 ABI** for formal proofs; zero `believe_me`. -- **Zig FFI** for C-ABI bridges to polyglot consumers. -- **Justfile** primary build system; not Make. -- **Containerfile** + Podman; not Dockerfile / Docker. -- **State files in `.machine_readable/descriptiles/` only**; never root. -- **All interfaces under `src/interfaces/`**; never extract to separate repos. -- **When adding provers: update all 3 layers** (Rust backend, Julia ML, Chapel). -- **Original name: "Cognitive Hybrid"** not "Computational Heuristic". -- **MPL-2.0** throughout. -- **No Python** — Julia for ML, Rust for systems, AffineScript for apps. - -## Tech stack - -- **Primary**: Rust (48 / 105 prover backends, trust pipeline, CLI, REPL, API servers). -- **Secondary**: Julia (ML inference, port 8090), AffineScript + Deno (UI, 33 files, zero TypeScript). -- **Optional**: Chapel (parallel proof dispatch). -- **ABI**: Idris2 (7+ modules, zero `believe_me`). -- **FFI**: Zig (4 shared libraries). -- **Interfaces**: GraphQL (8081), gRPC (50051), REST (8000). All three interface crates build clean as of 2026-04-26. -- **Build**: Justfile primary, Cargo workspace. -- **Container**: Podman + Containerfile. - -## 11-step trust pipeline (v1.5+) - -1. Solver binary integrity (SHAKE3-512 + BLAKE3). -2. SMT portfolio solving / cross-checking. -3. Proof certificate checking (Alethe, DRAT/LRAT, TSTP). -4. Axiom usage tracking (4 danger levels). -5. Solver sandboxing (Podman, bubblewrap). -6. 5-level trust hierarchy for confidence scoring. -7. Mutation testing for specifications. -8. Prover dispatch pipeline. -9. Cross-prover proof exchange (OpenTheory, Dedukti). -10. Pareto frontier (multi-objective proof search). -11. Bayesian timeout estimation. - -## v2.x roadmap (from CLAUDE.md) - -- **v2.1 (landed)**: GNN proof graph construction (7 node kinds, 8 edge kinds); 32-dim local term embeddings + GNN inference client; GNN-guided proof search (hybrid GNN + symbolic scoring); Julia `/gnn/rank` endpoint with cosine fallback; Idris2 formal proofs (7 GNN properties, 0 `believe_me`); 28 new tests. -- **v2.2**: Train GNN/Transformer on larger corpus (Flux.jl); Chapel → Rust C FFI bridge **(the Zig layer is done; dispatch-path integration is the L2 work above)**; Tamarin/ProVerif bridge **(already landed — stale in the roadmap)**. - -## Handover artefacts (in-repo, canonical) - -| File | Role | -|------|------| -| `verification-ecosystem/echidna/docs/handover/PRODUCTION-WIRING-PLAN.md` | Master plan | -| `verification-ecosystem/echidna/docs/handover/L1-CAPNPROTO-PROMPT.md` | L1 Cap'n Proto continuation prompt | -| `verification-ecosystem/echidna/docs/handover/L2-CHAPEL-PROMPT.md` | L2 Chapel continuation prompt | -| `verification-ecosystem/echidna/docs/handover/L3-LIVE-PROVER-CI-PROMPT.md` | L3 live-prover continuation prompt (marked Wave-2 DONE, pointing to Wave-3) | -| `verification-ecosystem/echidna/.machine_readable/descriptiles/STATE.a2ml` | Session ledger incl. `[l3-status-after-wave-2]` + `[wave-3-handover-hints]` | -| `verification-ecosystem/echidna/docs/handover/README.md` | Index + drift-handling policy | - -## Session log highlights (2026-04-26) - -- **echidna-graphql build fixed** (`5aec9d5`) — ProverKind enum expanded from 30 → 113 variants (exhaustive, no catch-all) across schema.rs + resolvers.rs + ffi_wrapper.rs; FfiProverBackend trait wired (config/set_config/search_theorems); FFI pointer casts corrected. `cargo build -p echidna-graphql` now clean. -- **FFI boundary audit** (`b4d682b`) — `audits/audit-ffi-boundary.md` (4-section per-module safety review) + `audits/assail-classifications.a2ml` (7 classifications suppressing legitimate UnsafeCode at all three interface ffi_wrapper.rs files + core ffi/ + proof_search.rs). panic-attack findings drop from active to classified. -- **bounded_read_config helper** — `src/rust/integrity/io.rs` ships sync 1 MiB-capped read helper; `solver_integrity.rs` migrated. Remaining UnboundedAllocation finding resolved. -- **F5 deferred** — `boj-server` `echidna-llm-mcp` cartridge real invocation is the one remaining open item. BoJ currently operates in skeleton mode for this cartridge; echidna REST layer is fully wired to its boundary. - -## Session log highlights (2026-04-19) - -- **Chapel FFI self-link fix** (`53ab9b8`) — `-Dstubs=true` default in `src/zig_ffi/build.zig`; `-fno-sanitize=undefined` flag; `use anyhow::Context;` in `proof_search.rs`. `cargo build --features chapel` now links standalone. -- **Stale-gap corrections** — Tamarin + ProVerif marked fully wired; zero TODO/FIXME standing property; Chapel FFI "not yet wired" was actually a link-time gap, fixed. -- **L3 Wave-2 installers** — idris2 source bootstrap against Chez Scheme; isabelle Isabelle2024 tarball; dafny `dotnet tool install`; fstar release tarball (binary `fstar.exe` even on Linux); tlaps self-extracting installer (`tlapm`). hol-light deferred to Wave-3. -- **Tests extended** — `live_fstar_version` + `live_tlaps_version` added; `kind_label` gained FStar / TLAPS; `ProverConfig` literal gained missing `library_paths` field (pre-existing compile error fixed). -- **Docs + `.gitignore`** — `QUICKSTART-DEV.adoc` chapel-feature build instructions; `chapel_poc/README.md` "Add FFI bindings to call from Rust" marked DONE; `.gitignore` adds `models/e*/`, `/models_e*/`, `src/zig_ffi/zig-out/`, `.zig-cache/`. -- **Mirrored** — all 4 Desktop handover docs now in-repo at `docs/handover/` (commit `b6d437c`). diff --git a/docs/handover/SUGGEST-CLI-PROMPT.adoc b/docs/handover/SUGGEST-CLI-PROMPT.adoc new file mode 100644 index 00000000..90960ce5 --- /dev/null +++ b/docs/handover/SUGGEST-CLI-PROMPT.adoc @@ -0,0 +1,388 @@ +== Echidna `+suggest+` — CLI Verb + Variant Tester — Sonnet Handoff Prompt + +*Context*: Echidna’s `+prove+` CLI is a one-shot dispatcher. When a +proof fails the user is on their own. The 2026-04-26 ECHIDNA-NOTES +failure-mode analysis (§3) classifies "`synonym blindness`" and "`wrong +induction principle`" as two of the ten failure classes a fully-shipped +backend roster doesn’t address — and they happen to be the _easiest_ +class to solve mechanically with no ML and no creativity. This prompt +lays out exactly that: a new `+echidna suggest+` verb that takes a +failing lemma, walks a hand-curated synonym table, and reports which +substitutions close the goal. + +This is the §4.1 / §4.3 pair from +`+~/Desktop/ECHIDNA-NOTES-2026-04-27.md+`. + +*Master plan*: `+docs/ROADMAP.md+` row 4 ("`Every important solver`" → +end-state target: real `+suggest_tactics+` for every backend). + +*Prerequisite*: synonym tables seeded at +`+data/synonyms/{isabelle,coq,lean4}.toml+` (committed 2026-04-27 by +Opus, 27 entries; this prompt expands the table in lockstep with +implementation). + +*Follows*: §4.4 GNN training. The _next_ layer (§4.4) replaces the +hand-curated table with a learned ranker; this layer (§4.1+§4.3) is the +mechanical baseline that the GNN layer must beat to justify itself. + +=== What this verb does (in one paragraph) + +`+echidna suggest : --prover

[--budget 60s]+` extracts +the named lemma from the file into a self-contained probe, runs the +prover on the probe to confirm the failure, then for each tactic name in +the probe that appears in `+data/synonyms/

.toml+` it tries every +alias and the canonical form in turn, re-runs the prover, and prints a +list of successful variants ranked by edit minimality. No ML, no search +beyond the table, no creativity. Mechanical, debuggable, and small +enough to fit in 600 LOC. + +=== Deliverables + +==== CLI surface (`+src/rust/main.rs+`) + +Add a new variant to the `+Commands+` enum: + +[source,rust] +---- +/// Suggest tactic variants that close a failing lemma +Suggest { + /// Target in `:` form + #[arg(value_name = "TARGET")] + target: String, + + /// Prover to use (auto-detect from file extension if absent) + #[arg(short, long)] + prover: Option, + + /// Time budget per variant attempt + #[arg(long, default_value = "60s")] + budget: humantime::Duration, + + /// Maximum number of variants to report + #[arg(long, default_value_t = 10)] + top: usize, + + /// Synonym table directory (defaults to `data/synonyms/`) + #[arg(long)] + synonyms_dir: Option, + + /// Don't actually run the prover; just print the candidate variants + #[arg(long)] + dry_run: bool, +}, +---- + +==== New module `+src/rust/suggest/+` + +.... +src/rust/suggest/ +├── mod.rs -- public API + CLI dispatch +├── extractor.rs -- pull a named lemma out of a file (per-prover) +├── synonyms.rs -- load + index data/synonyms/*.toml +├── variant.rs -- generate candidate substitutions +├── tester.rs -- run prover on each variant; classify outcomes +└── report.rs -- format the result table +.... + +==== `+extractor.rs+` — per-prover lemma extraction + +Five extractors, one per prover the synonym tables cover today: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Prover |File extension |Lemma syntax we extract +|Isabelle |`+.thy+` |`+lemma : ...+` / `+theorem : ...+` +(incl. `+proof ... qed+` block) + +|Coq |`+.v+` |`+Lemma ...+` / `+Theorem ...+` (incl. proof +script up to `+Qed.+` / `+Defined.+`) + +|Lean 4 |`+.lean+` |`+theorem ... := by ...+` / +`+lemma ...+` + +|Idris2 |`+.idr+` |`+ : \n ...+` (the function +clauses) + +|Agda |`+.agda+` |similar, definition + clauses +|=== + +Each extractor returns a self-contained `+Probe+` struct: + +[source,rust] +---- +pub struct Probe { + pub prover: ProverKind, + pub preamble: String, // imports, opens, declarations the lemma depends on + pub lemma_source: String, // the lemma itself, ready to substitute into + pub tactic_sites: Vec, // identified tactic occurrences +} + +pub struct TacticSite { + pub line: usize, // 1-indexed line within `lemma_source` + pub col: usize, + pub name: String, // e.g. "induct", "omega" + pub kind: TacticKind, // TacticName, LemmaRef, RewriteTarget, ... +} +---- + +Preamble extraction is the hard bit — for first cut, copy the file’s +top-of-file `+imports+` / `+Require Import+` / `+import+` block verbatim +plus all definitions that appear before the target lemma in the same +file. Cross-file dependency tracking is *out of scope* for v1. + +==== `+synonyms.rs+` — table loader + +[source,rust] +---- +pub struct SynonymTable { + pub entries: Vec, + /// Index from any name (canonical or alias) to entry indices. + pub by_name: HashMap>, +} + +pub struct SynonymEntry { + pub canonical: String, + pub aliases: Vec, + pub tactic_class: Option, + pub notes: Option, + pub since: Option, + pub until: Option, +} + +impl SynonymTable { + pub fn load(prover: ProverKind, dir: &Path) -> anyhow::Result { ... } + + /// Return every other name in the same entry as `name` (canonical + aliases minus self). + pub fn alternatives(&self, name: &str) -> Vec { ... } +} +---- + +A name appearing in multiple entries (rare but possible — e.g. `+auto+` +in both Isabelle and Coq tables) is *kept separate per prover*: the +loader is keyed on `+prover+`, so cross-prover accidents are impossible. + +==== `+variant.rs+` — substitution generator + +For each `+TacticSite+` in the probe, look up alternatives in the table. +Generate one `+Variant+` per (site, alternative) pair: + +[source,rust] +---- +pub struct Variant { + pub site: TacticSite, + pub original: String, // the name we replaced + pub replacement: String, // the alternative we tried + pub probe_source: String, // full probe with the substitution applied + pub edit_distance: u32, // Levenshtein, for ranking +} +---- + +*Substitution discipline*: replace only at the exact site, not globally. +`+induct+` may legitimately appear in a comment or string literal; only +AST-level positions count. For v1, accept the imprecision of substring +replacement at the recorded line:col and document the limitation in +`+mod.rs+`. + +*Combinatorics*: do NOT try all combinations of substitutions across +sites. For v1, single-site substitutions only. If the table grows large +enough for combinatorial explosion to bite, gate the multi-site mode +behind `+--max-substitutions N+`. + +==== `+tester.rs+` — variant testing harness + +[source,rust] +---- +pub enum VariantOutcome { + Closes, // prover accepted the variant + Fails(String), // prover rejected with this error + Timeout, // exceeded --budget + InvariantSyntax(String), // probe didn't even parse +} + +pub async fn test_variant( + backend: &dyn ProverBackend, + variant: &Variant, + budget: Duration, +) -> VariantOutcome { + // 1. Write probe_source to a temp file + // 2. Invoke backend with the temp file + // 3. Parse the result; classify per VariantOutcome +} +---- + +*Parallelism*: tests are independent; spawn up to `+--max-parallel+` +(default 4) concurrent variant tests via `+tokio::task::JoinSet+`. + +*Sandboxing*: each variant test runs in the same sandbox the regular +`+prove+` pipeline uses (`+src/rust/executor/+`). No new sandbox +infrastructure needed. + +==== `+report.rs+` — output formatter + +Output a markdown table to stdout with columns: + +[cols=",,,",options="header",] +|=== +|Variant |Site |Outcome |Edit +|`+induct+` → `+induction+` |line 7 col 12 |✅ closes |2 +|`+omega+` → `+lia+` |line 7 col 12 |✅ closes |1 +|`+auto+` → `+force+` |line 9 col 5 |❌ fails |2 +|=== + +Sort: first by `+Outcome+` (closes > fails > timeout > syntax), then by +edit distance ascending. + +When `+--dry-run+` is set, print the candidate list without an Outcome +column. + +=== Acceptance criteria + +[arabic] +. *Closes the two ECHIDNA-discovered drifts.* Running +`+echidna suggest tropical-resource-typing/Foo.thy:bar --prover isabelle+` +on a probe that fails because of `+induct rule: finite_induct+` (the +2026-04-26 case) reports `+induct → induction+` as a successful variant +with edit distance 2. +. *Closes the `+add_le_add → add_mono+` drift.* Same setup with the +monotonicity-name failure case from the 2026-04-26 session. +. *Handles all five provers* the synonym tables cover. Each prover has +at least one extractor smoke test in `+tests/+`. +. *Sandboxed* — variant testing uses the existing `+src/rust/executor/+` +sandbox; no new privilege escalation paths. +. *Cancellable* — SIGINT cleans up in-flight variant tests. +. *No ML, no GNN* — the `+suggest+` verb is mechanical. The GNN +integration is out of scope; if it appears in this PR, the PR is wrong. +. *Tests* — at minimum: +* 3 unit tests per extractor (positive, negative, edge case) +* 1 integration test per prover (full probe→variant→test pipeline, with +stub backends) +* 1 end-to-end test using the real Isabelle backend if the CI +environment has it (`+cfg+`-gated) +. *Documentation* — `+EXPLAINME.adoc+` gets a new section under "`How +ECHIDNA helps you when a proof fails`"; `+README.adoc+` gets a one-line +pointer. + +=== Non-goals (Out of scope for v1) + +* *Cross-file dependency analysis.* If the lemma uses a fact defined in +another file, the probe will be missing the dependency and the prover +will fail with `+unknown name+`. Document the limitation, surface it as +a clean error message ("`probe missing definition: … consider running on +a self-contained file`"), and move on. +* *GNN-ranked suggestions.* That’s §4.4 — different layer, different PR, +different ranker. This verb is the mechanical baseline. +* *Multi-site combinatorial substitution.* Single-site only for v1. +* *Synonym discovery from corpus.* Manual table only. Mining +`+training_data/+` for synonym pairs is a separate item (§4.4 adjacent). +* *Prover-version detection.* Trust the `+--prover+` flag. Auto-detect +by file extension, not by parsing version banners. + +=== Testing strategy + +==== Unit (in-tree, fast) + +For each prover, hand-craft three probe files: - +`+closes-on-canonical/+`: lemma works as-written. - +`+fails-needs-alias/+`: lemma fails until aliased to canonical. - +`+unrecoverable/+`: lemma fails for a reason the synonym table can’t +fix. + +The `+tester.rs+` should classify each as Closes / +Closes-after-substitution / Fails-everything respectively. + +==== Integration (CI-gated by prover availability) + +Per-prover integration test that requires the upstream binary: + +[source,rust] +---- +#[tokio::test] +#[cfg(feature = "isabelle-real")] +async fn integration_isabelle_induct_drift() { ... } +---- + +Add a CI workflow `+.github/workflows/suggest-integration.yml+` that +provisions Isabelle 2025 and runs the gated tests. Mirror for Coq / Lean +once their integration tests pass locally. + +==== End-to-end (manual) + +Run `+echidna suggest+` against the actual 2026-04-26 failure cases in +`+tropical-resource-typing/+`. Both should produce a `+Closes+` row in +the report. + +=== Wiring into the existing pipeline + +* `+dispatch.rs+` is *untouched* by this PR — `+suggest+` is a +side-channel verb that doesn’t use the trust pipeline. +* The variant tester reuses the per-backend `+prove()+` entry point but +through a wrapper that classifies prover output as Closes/Fails/etc. +rather than going through `+compute_trust_level+`. +* `+provers/mod.rs+` `+suggest_tactics+` is a _different_ method — it +returns ML-suggested tactics for an open goal. Keep them separate; don’t +rename either. The `+echidna suggest+` verb does *not* call +`+suggest_tactics+`. + +=== Synonym table expansion (parallel work for Haiku) + +While Sonnet implements the verb, Haiku expands the synonym tables from +the seeded 27 entries to ~50–100 per prover. Haiku prompt template: + +.... +Haiku table-expansion, scope = data/synonyms/.toml + +For prover

, add hand-curated synonym entries covering: +- Tactic-name drift across the last 3 major versions of

+- Lemma-name drift in the standard library / mathlib equivalent +- Common typos / abbreviations (only when they're prover-accepted) + +Each entry MUST have: +- canonical (preferred / current name) +- aliases (>= 1) +- notes (rationale or version-specific behaviour) + +DO NOT invent synonyms. If you're not confident two names are +interchangeable, skip the entry. Source from upstream changelogs and +release notes; cite in `notes`. + +Cap: 30 new entries per session per prover, to keep review tractable. +.... + +=== Failure modes the v1 _won’t_ catch (and how to know) + +The §3 failure-mode analysis classified ten classes; this verb addresses +only: + +* *Class 4 (Synonym blindness)* — the headline class. +* *Class 3 (Wrong induction principle)* — partially, when the +alternative principle is in the synonym table. + +Classes 1, 2, 5–10 (wrong abstraction, missing invariant, definition +unfolding choreography, bidirectional gap, cross-domain analogy, +generalization, anti-monotonic information, combinatorial blow-up) are +*not* addressed by this verb and that’s fine — they need different +machinery. The §4.5–4.6 plans cover them. + +When `+echidna suggest+` reports "`no variants close the goal,`" the +user should reach for the next layer: `+echidna prove --diagnose+` +(which has a separate existing diagnostic pipeline) or hand-debug. + +=== Sequencing + +[arabic] +. (parallel) Sonnet builds `+suggest/+` module + CLI verb. +. (parallel) Haiku expands synonym tables to ~100 entries per prover. +. Sonnet’s PR lands first; Haiku’s table additions land as separate PRs +as they accumulate. +. Once both land, file a usability bug if `+suggest+` produces zero +variants on a known-good failure case — the table is too sparse and +needs more entries. + +=== Tracking + +* This prompt: `+docs/handover/SUGGEST-CLI-PROMPT.md+` +* Synonym tables: `+data/synonyms/{isabelle,coq,lean4}.toml+` (committed +2026-04-27, 27 entries) +* Headline notes: `+~/Desktop/ECHIDNA-NOTES-2026-04-27.md+` §4.1, §4.2, +§4.3 +* Item #4 in §6 Active Follow-ups diff --git a/docs/handover/SUGGEST-CLI-PROMPT.md b/docs/handover/SUGGEST-CLI-PROMPT.md deleted file mode 100644 index 47de8d2f..00000000 --- a/docs/handover/SUGGEST-CLI-PROMPT.md +++ /dev/null @@ -1,380 +0,0 @@ - -# Echidna `suggest` — CLI Verb + Variant Tester — Sonnet Handoff Prompt - -**Context**: Echidna's `prove` CLI is a one-shot dispatcher. When a proof -fails the user is on their own. The 2026-04-26 ECHIDNA-NOTES failure-mode -analysis (§3) classifies "synonym blindness" and "wrong induction -principle" as two of the ten failure classes a fully-shipped backend -roster doesn't address — and they happen to be the *easiest* class to -solve mechanically with no ML and no creativity. This prompt lays out -exactly that: a new `echidna suggest` verb that takes a failing lemma, -walks a hand-curated synonym table, and reports which substitutions -close the goal. - -This is the §4.1 / §4.3 pair from `~/Desktop/ECHIDNA-NOTES-2026-04-27.md`. - -**Master plan**: `docs/ROADMAP.md` row 4 ("Every important solver" → -end-state target: real `suggest_tactics` for every backend). - -**Prerequisite**: synonym tables seeded at `data/synonyms/{isabelle,coq,lean4}.toml` -(committed 2026-04-27 by Opus, 27 entries; this prompt expands the table -in lockstep with implementation). - -**Follows**: §4.4 GNN training. The *next* layer (§4.4) replaces the -hand-curated table with a learned ranker; this layer (§4.1+§4.3) is the -mechanical baseline that the GNN layer must beat to justify itself. - -## What this verb does (in one paragraph) - -`echidna suggest : --prover

[--budget 60s]` extracts the -named lemma from the file into a self-contained probe, runs the prover -on the probe to confirm the failure, then for each tactic name in the -probe that appears in `data/synonyms/

.toml` it tries every alias and -the canonical form in turn, re-runs the prover, and prints a list of -successful variants ranked by edit minimality. No ML, no search beyond -the table, no creativity. Mechanical, debuggable, and small enough to -fit in 600 LOC. - -## Deliverables - -### CLI surface (`src/rust/main.rs`) - -Add a new variant to the `Commands` enum: - -```rust -/// Suggest tactic variants that close a failing lemma -Suggest { - /// Target in `:` form - #[arg(value_name = "TARGET")] - target: String, - - /// Prover to use (auto-detect from file extension if absent) - #[arg(short, long)] - prover: Option, - - /// Time budget per variant attempt - #[arg(long, default_value = "60s")] - budget: humantime::Duration, - - /// Maximum number of variants to report - #[arg(long, default_value_t = 10)] - top: usize, - - /// Synonym table directory (defaults to `data/synonyms/`) - #[arg(long)] - synonyms_dir: Option, - - /// Don't actually run the prover; just print the candidate variants - #[arg(long)] - dry_run: bool, -}, -``` - -### New module `src/rust/suggest/` - -``` -src/rust/suggest/ -├── mod.rs -- public API + CLI dispatch -├── extractor.rs -- pull a named lemma out of a file (per-prover) -├── synonyms.rs -- load + index data/synonyms/*.toml -├── variant.rs -- generate candidate substitutions -├── tester.rs -- run prover on each variant; classify outcomes -└── report.rs -- format the result table -``` - -### `extractor.rs` — per-prover lemma extraction - -Five extractors, one per prover the synonym tables cover today: - -| Prover | File extension | Lemma syntax we extract | -|---|---|---| -| Isabelle | `.thy` | `lemma : ...` / `theorem : ...` (incl. `proof ... qed` block) | -| Coq | `.v` | `Lemma ...` / `Theorem ...` (incl. proof script up to `Qed.` / `Defined.`) | -| Lean 4 | `.lean` | `theorem ... := by ...` / `lemma ...` | -| Idris2 | `.idr` | ` : \n ...` (the function clauses) | -| Agda | `.agda` | similar, definition + clauses | - -Each extractor returns a self-contained `Probe` struct: - -```rust -pub struct Probe { - pub prover: ProverKind, - pub preamble: String, // imports, opens, declarations the lemma depends on - pub lemma_source: String, // the lemma itself, ready to substitute into - pub tactic_sites: Vec, // identified tactic occurrences -} - -pub struct TacticSite { - pub line: usize, // 1-indexed line within `lemma_source` - pub col: usize, - pub name: String, // e.g. "induct", "omega" - pub kind: TacticKind, // TacticName, LemmaRef, RewriteTarget, ... -} -``` - -Preamble extraction is the hard bit — for first cut, copy the file's -top-of-file `imports` / `Require Import` / `import` block verbatim plus -all definitions that appear before the target lemma in the same file. -Cross-file dependency tracking is **out of scope** for v1. - -### `synonyms.rs` — table loader - -```rust -pub struct SynonymTable { - pub entries: Vec, - /// Index from any name (canonical or alias) to entry indices. - pub by_name: HashMap>, -} - -pub struct SynonymEntry { - pub canonical: String, - pub aliases: Vec, - pub tactic_class: Option, - pub notes: Option, - pub since: Option, - pub until: Option, -} - -impl SynonymTable { - pub fn load(prover: ProverKind, dir: &Path) -> anyhow::Result { ... } - - /// Return every other name in the same entry as `name` (canonical + aliases minus self). - pub fn alternatives(&self, name: &str) -> Vec { ... } -} -``` - -A name appearing in multiple entries (rare but possible — e.g. `auto` -in both Isabelle and Coq tables) is **kept separate per prover**: the -loader is keyed on `prover`, so cross-prover accidents are impossible. - -### `variant.rs` — substitution generator - -For each `TacticSite` in the probe, look up alternatives in the table. -Generate one `Variant` per (site, alternative) pair: - -```rust -pub struct Variant { - pub site: TacticSite, - pub original: String, // the name we replaced - pub replacement: String, // the alternative we tried - pub probe_source: String, // full probe with the substitution applied - pub edit_distance: u32, // Levenshtein, for ranking -} -``` - -**Substitution discipline**: replace only at the exact site, not -globally. `induct` may legitimately appear in a comment or string -literal; only AST-level positions count. For v1, accept the -imprecision of substring replacement at the recorded line:col and -document the limitation in `mod.rs`. - -**Combinatorics**: do NOT try all combinations of substitutions across -sites. For v1, single-site substitutions only. If the table grows -large enough for combinatorial explosion to bite, gate the multi-site -mode behind `--max-substitutions N`. - -### `tester.rs` — variant testing harness - -```rust -pub enum VariantOutcome { - Closes, // prover accepted the variant - Fails(String), // prover rejected with this error - Timeout, // exceeded --budget - InvariantSyntax(String), // probe didn't even parse -} - -pub async fn test_variant( - backend: &dyn ProverBackend, - variant: &Variant, - budget: Duration, -) -> VariantOutcome { - // 1. Write probe_source to a temp file - // 2. Invoke backend with the temp file - // 3. Parse the result; classify per VariantOutcome -} -``` - -**Parallelism**: tests are independent; spawn up to `--max-parallel` -(default 4) concurrent variant tests via `tokio::task::JoinSet`. - -**Sandboxing**: each variant test runs in the same sandbox the regular -`prove` pipeline uses (`src/rust/executor/`). No new sandbox -infrastructure needed. - -### `report.rs` — output formatter - -Output a markdown table to stdout with columns: - -| Variant | Site | Outcome | Edit | -|---|---|---|---| -| `induct` → `induction` | line 7 col 12 | ✅ closes | 2 | -| `omega` → `lia` | line 7 col 12 | ✅ closes | 1 | -| `auto` → `force` | line 9 col 5 | ❌ fails | 2 | - -Sort: first by `Outcome` (closes > fails > timeout > syntax), then by -edit distance ascending. - -When `--dry-run` is set, print the candidate list without an Outcome -column. - -## Acceptance criteria - -1. **Closes the two ECHIDNA-discovered drifts.** Running - `echidna suggest tropical-resource-typing/Foo.thy:bar --prover isabelle` - on a probe that fails because of `induct rule: finite_induct` (the - 2026-04-26 case) reports `induct → induction` as a successful - variant with edit distance 2. - -2. **Closes the `add_le_add → add_mono` drift.** Same setup with the - monotonicity-name failure case from the 2026-04-26 session. - -3. **Handles all five provers** the synonym tables cover. Each prover - has at least one extractor smoke test in `tests/`. - -4. **Sandboxed** — variant testing uses the existing - `src/rust/executor/` sandbox; no new privilege escalation paths. - -5. **Cancellable** — SIGINT cleans up in-flight variant tests. - -6. **No ML, no GNN** — the `suggest` verb is mechanical. The GNN - integration is out of scope; if it appears in this PR, the PR is - wrong. - -7. **Tests** — at minimum: - - 3 unit tests per extractor (positive, negative, edge case) - - 1 integration test per prover (full probe→variant→test pipeline, - with stub backends) - - 1 end-to-end test using the real Isabelle backend if the CI - environment has it (`cfg`-gated) - -8. **Documentation** — `EXPLAINME.adoc` gets a new section under "How - ECHIDNA helps you when a proof fails"; `README.adoc` gets a one-line - pointer. - -## Non-goals (Out of scope for v1) - -- **Cross-file dependency analysis.** If the lemma uses a fact defined - in another file, the probe will be missing the dependency and the - prover will fail with `unknown name`. Document the limitation, - surface it as a clean error message ("probe missing definition: … - consider running on a self-contained file"), and move on. - -- **GNN-ranked suggestions.** That's §4.4 — different layer, different - PR, different ranker. This verb is the mechanical baseline. - -- **Multi-site combinatorial substitution.** Single-site only for v1. - -- **Synonym discovery from corpus.** Manual table only. Mining - `training_data/` for synonym pairs is a separate item (§4.4 - adjacent). - -- **Prover-version detection.** Trust the `--prover` flag. Auto-detect - by file extension, not by parsing version banners. - -## Testing strategy - -### Unit (in-tree, fast) - -For each prover, hand-craft three probe files: -- `closes-on-canonical/`: lemma works as-written. -- `fails-needs-alias/`: lemma fails until aliased to canonical. -- `unrecoverable/`: lemma fails for a reason the synonym table - can't fix. - -The `tester.rs` should classify each as Closes / Closes-after-substitution / Fails-everything respectively. - -### Integration (CI-gated by prover availability) - -Per-prover integration test that requires the upstream binary: - -```rust -#[tokio::test] -#[cfg(feature = "isabelle-real")] -async fn integration_isabelle_induct_drift() { ... } -``` - -Add a CI workflow `.github/workflows/suggest-integration.yml` that -provisions Isabelle 2025 and runs the gated tests. Mirror for Coq / -Lean once their integration tests pass locally. - -### End-to-end (manual) - -Run `echidna suggest` against the actual 2026-04-26 failure cases in -`tropical-resource-typing/`. Both should produce a `Closes` row in the -report. - -## Wiring into the existing pipeline - -- `dispatch.rs` is **untouched** by this PR — `suggest` is a - side-channel verb that doesn't use the trust pipeline. -- The variant tester reuses the per-backend `prove()` entry point but - through a wrapper that classifies prover output as Closes/Fails/etc. - rather than going through `compute_trust_level`. -- `provers/mod.rs` `suggest_tactics` is a *different* method — - it returns ML-suggested tactics for an open goal. Keep them separate; - don't rename either. The `echidna suggest` verb does **not** call - `suggest_tactics`. - -## Synonym table expansion (parallel work for Haiku) - -While Sonnet implements the verb, Haiku expands the synonym tables -from the seeded 27 entries to ~50–100 per prover. Haiku prompt -template: - -``` -Haiku table-expansion, scope = data/synonyms/.toml - -For prover

, add hand-curated synonym entries covering: -- Tactic-name drift across the last 3 major versions of

-- Lemma-name drift in the standard library / mathlib equivalent -- Common typos / abbreviations (only when they're prover-accepted) - -Each entry MUST have: -- canonical (preferred / current name) -- aliases (>= 1) -- notes (rationale or version-specific behaviour) - -DO NOT invent synonyms. If you're not confident two names are -interchangeable, skip the entry. Source from upstream changelogs and -release notes; cite in `notes`. - -Cap: 30 new entries per session per prover, to keep review tractable. -``` - -## Failure modes the v1 *won't* catch (and how to know) - -The §3 failure-mode analysis classified ten classes; this verb -addresses only: - -- **Class 4 (Synonym blindness)** — the headline class. -- **Class 3 (Wrong induction principle)** — partially, when the - alternative principle is in the synonym table. - -Classes 1, 2, 5–10 (wrong abstraction, missing invariant, definition -unfolding choreography, bidirectional gap, cross-domain analogy, -generalization, anti-monotonic information, combinatorial blow-up) are -**not** addressed by this verb and that's fine — they need different -machinery. The §4.5–4.6 plans cover them. - -When `echidna suggest` reports "no variants close the goal," the user -should reach for the next layer: `echidna prove --diagnose` (which has -a separate existing diagnostic pipeline) or hand-debug. - -## Sequencing - -1. (parallel) Sonnet builds `suggest/` module + CLI verb. -2. (parallel) Haiku expands synonym tables to ~100 entries per prover. -3. Sonnet's PR lands first; Haiku's table additions land as separate - PRs as they accumulate. -4. Once both land, file a usability bug if `suggest` produces zero - variants on a known-good failure case — the table is too sparse and - needs more entries. - -## Tracking - -- This prompt: `docs/handover/SUGGEST-CLI-PROMPT.md` -- Synonym tables: `data/synonyms/{isabelle,coq,lean4}.toml` (committed - 2026-04-27, 27 entries) -- Headline notes: `~/Desktop/ECHIDNA-NOTES-2026-04-27.md` §4.1, §4.2, - §4.3 -- Item #4 in §6 Active Follow-ups diff --git a/docs/handover/THEOREM-METADATA-MIGRATION.adoc b/docs/handover/THEOREM-METADATA-MIGRATION.adoc new file mode 100644 index 00000000..33928940 --- /dev/null +++ b/docs/handover/THEOREM-METADATA-MIGRATION.adoc @@ -0,0 +1,85 @@ +== Theorem Metadata Migration (deferred) + +=== Purpose + +`+Theorem.aspects+` currently serves two unrelated roles: + +[arabic] +. *Math-domain tags* — dotted keys like `+"arithmetic.natural_numbers"+` +produced by `+Aspect::dotted_key()+`. These drive the learning loop, GNN +domain hints, and coprocessor routing. +. *Structural / provenance meta-tags* — plain strings like `+"axiom"+`, +`+"constructor"+`, `+"dedukti-import"+` injected by parsers. These +describe the _kind_ of theorem, not its mathematical content. + +The D1 boundary filter (`+s.contains('.')+`) prevents structural tags +from leaking into the learning-loop key space, so correctness is +preserved. However, mixing the two kinds in a single `+Vec+` +field is a hygiene problem. This document tracks the deferred migration. + +=== Current state — 8 parser sites using structural tags + +[width="100%",cols="22%,32%,46%",options="header",] +|=== +|File |Line(s) |Tag(s) used +|`+src/rust/provers/agda.rs+` |297 |`+"axiom"+` + +|`+src/rust/provers/metamath.rs+` |316, 328 |`+"axiom"+`, `+"theorem"+` + +|`+src/rust/provers/idris2.rs+` |522, 550, 586 |`+"constructor"+`, +`+"projection"+`, `+"interface-method"+` + +|`+src/rust/provers/hol_light.rs+` |457 |`+"hol_light"+` + +|`+src/rust/exchange/dedukti.rs+` |101, 118 |`+"dedukti-import"+`, +`+"has-definition"+` + +|`+src/rust/exchange/opentheory.rs+` |84 |`+"opentheory-import"+` +|=== + +These are *not migrated* in D1. The boundary filter contains the damage. + +=== Proposed target structure + +[source,rust] +---- +pub enum TheoremKind { + Axiom, + Theorem, + Definition, + Constructor, + Projection, + InterfaceMethod, +} + +pub struct Theorem { + // ... existing fields ... + pub kind: TheoremKind, + pub import_source: Option, // e.g. "dedukti", "opentheory" + pub prover_source: Option, + pub has_proof: bool, + // aspects contains ONLY dotted math-domain keys after migration + pub aspects: Vec, +} +---- + +=== Scope of migration work + +* *8 parser sites*: replace `+aspects: vec!["axiom"]+` etc. with +`+kind: TheoremKind::Axiom+`. +* *Callers that read `+Theorem.aspects+` for structural meaning*: find +with `+rg "theorem.*\.aspects" src/+` — expected ~4-6 call sites. +* *Remove boundary filter* once no structural tags can appear in +`+aspects+`. + +Estimated effort: ~3-4 hours of mechanical work. No algorithmic changes +required. + +=== Not blocking + +The boundary filter introduced in D1 +(`+src/rust/provers/mod.rs::gnn_augment_tactics+` and +`+src/rust/agent/meta_controller.rs::primary_domain+`) is sufficient to +prevent correctness issues. This migration is hygiene, not a correctness +fix. Schedule opportunistically alongside the next `+Theorem+` struct +refactor. diff --git a/docs/handover/THEOREM-METADATA-MIGRATION.md b/docs/handover/THEOREM-METADATA-MIGRATION.md deleted file mode 100644 index a0c66f6a..00000000 --- a/docs/handover/THEOREM-METADATA-MIGRATION.md +++ /dev/null @@ -1,72 +0,0 @@ - - - -# Theorem Metadata Migration (deferred) - -## Purpose - -`Theorem.aspects` currently serves two unrelated roles: - -1. **Math-domain tags** — dotted keys like `"arithmetic.natural_numbers"` produced by - `Aspect::dotted_key()`. These drive the learning loop, GNN domain hints, and - coprocessor routing. -2. **Structural / provenance meta-tags** — plain strings like `"axiom"`, `"constructor"`, - `"dedukti-import"` injected by parsers. These describe the *kind* of theorem, not - its mathematical content. - -The D1 boundary filter (`s.contains('.')`) prevents structural tags from leaking into -the learning-loop key space, so correctness is preserved. However, mixing the two kinds -in a single `Vec` field is a hygiene problem. This document tracks the deferred -migration. - -## Current state — 8 parser sites using structural tags - -| File | Line(s) | Tag(s) used | -|------|---------|-------------| -| `src/rust/provers/agda.rs` | 297 | `"axiom"` | -| `src/rust/provers/metamath.rs` | 316, 328 | `"axiom"`, `"theorem"` | -| `src/rust/provers/idris2.rs` | 522, 550, 586 | `"constructor"`, `"projection"`, `"interface-method"` | -| `src/rust/provers/hol_light.rs` | 457 | `"hol_light"` | -| `src/rust/exchange/dedukti.rs` | 101, 118 | `"dedukti-import"`, `"has-definition"` | -| `src/rust/exchange/opentheory.rs` | 84 | `"opentheory-import"` | - -These are **not migrated** in D1. The boundary filter contains the damage. - -## Proposed target structure - -```rust -pub enum TheoremKind { - Axiom, - Theorem, - Definition, - Constructor, - Projection, - InterfaceMethod, -} - -pub struct Theorem { - // ... existing fields ... - pub kind: TheoremKind, - pub import_source: Option, // e.g. "dedukti", "opentheory" - pub prover_source: Option, - pub has_proof: bool, - // aspects contains ONLY dotted math-domain keys after migration - pub aspects: Vec, -} -``` - -## Scope of migration work - -- **8 parser sites**: replace `aspects: vec!["axiom"]` etc. with `kind: TheoremKind::Axiom`. -- **Callers that read `Theorem.aspects` for structural meaning**: find with - `rg "theorem.*\.aspects" src/` — expected ~4-6 call sites. -- **Remove boundary filter** once no structural tags can appear in `aspects`. - -Estimated effort: ~3-4 hours of mechanical work. No algorithmic changes required. - -## Not blocking - -The boundary filter introduced in D1 (`src/rust/provers/mod.rs::gnn_augment_tactics` -and `src/rust/agent/meta_controller.rs::primary_domain`) is sufficient to prevent -correctness issues. This migration is hygiene, not a correctness fix. Schedule -opportunistically alongside the next `Theorem` struct refactor. diff --git a/docs/handover/TODO.adoc b/docs/handover/TODO.adoc new file mode 100644 index 00000000..55b63481 --- /dev/null +++ b/docs/handover/TODO.adoc @@ -0,0 +1,399 @@ +== Echidna Production-Wiring — TODO + +*Source of truth for pending work.* Complements `+ECHIDNA-STATE.md+` +(where we are) and the full continuation prompts at +`+verification-ecosystem/echidna/docs/handover/{L1,L2,L3,PRODUCTION-WIRING-PLAN}.md+`. + +Last updated: 2026-04-26 (session 2). + +Execution order from the master plan: *L3 → L1 → L2.* L3 blocks L1; L1 +blocks L2 (because Chapel consumes Cap’n Proto schemas). + +''''' + +=== Completed items (2026-04-26) + +* ✅ *`+echidna-graphql+` build* — ProverKind 30→113 variants, trait +stubs, FFI casts fixed (`+5aec9d5+`). All three interface crates now +build clean. +* ✅ *FFI boundary audit* — `+audits/audit-ffi-boundary.md+` + +`+audits/assail-classifications.a2ml+` classifying all legitimate +UnsafeCode at FFI boundaries (`+b4d682b+`). +* ✅ *`+bounded_read_config+`* — sync 1 MiB-capped read helper in +`+src/rust/integrity/io.rs+`; `+solver_integrity.rs+` migrated. +* ✅ *F5 (boj-server `+echidna-llm-mcp+`)* — `+consult+` + +`+suggest_tactics+` operations implemented; Elixir router patched for +`+{operation, params}+` alias; 176 boj-server tests pass (`+a6c8456+`). +* ✅ *Real-Chapel CI job* — `+chapel-ci.yml+` Job 4 `+rust-chapel-real+` +added (`+continue-on-error: true+`), downloads real Chapel lib and +builds Rust without Zig stubs (`+3fb6c6b+`). +* ✅ *Stage 8b — Agda meta-proofs 6→12 modules* — TrustLattice, +AxiomMonotonicity, DispatchOrdering, SoundnessPreservation, +PortfolioConsistency, CertificateChain (`+6caff97+`). +* ✅ *Stage 8d — panic-attack proptest harnesses* — 13 property tests +across term/trust/danger/pareto modules (`+99198b0+`). +* ✅ *Stage 8d — AFL++ fuzz targets* — 3 real libfuzzer targets +(proof_state JSON deserialization, trust pipeline, axiom tracker) +replacing stub (`+46453c4+`). +* ✅ *Stage 8a — Idris2 trust-kernel proofs* — TrustKernelMonotonicity, +AxiomPolicyOrdering, ClampTrustBounds; zero believe_me; PROOF-NEEDS.md +updated (`+1444a30+`). +* ✅ *Stage 3a/3b — VeriSimDB read paths + dispatch advisor* — +`+query_by_goal_hash+`, `+query_prover_success_by_class+`, +`+VeriSimAdvisor+`, `+verify_proof_verisim_guided+` (`+804ead6+`). +* ✅ *S5 — GNN-augmented suggest_tactics* — `+gnn_augment_tactics+` +helper; rocq/lean/agda/isabelle/z3 backends prepend GNN-ranked apply +tactics (`+c4bc272+`). +* ✅ *S1 batch — 12 Julia premise extractors* — SMT-LIB, TPTP, Dafny, +Lean3, HOL Light, Metamath, Tamarin, ProVerif, Boogie, Viper, MiniZinc, +Twelf; named extractors 12→24 (`+d7a2493+`). +* ✅ *S1 batch — 20 more extractors* (24→44): Isabelle, Coq/Rocq, Why3, +TLAPS, Idris2, Vampire, EProver, SPASS, AltErgo, FStar, Mizar, CVC5, +HOL4, ACL2, Minlog, PVS, Nuprl, Twelf2, Z3-DTsolver, Agda-core +(`+53ee39a+`). +* ✅ *S1 final 6 extractors* (44→50): SPIN/Promela, CBMC-C, SCIP-opt, +KeY-Java, Alloy-Relational, NuSMV-temporal (`+4ead82a+`). +* ✅ *GPUVerify + Faial backends* — GPU CUDA/OpenCL verification; +`+src/rust/provers/gpuverify.rs+` + `+faial.rs+`; ProverKind variants +113/114; ProverKindInjectivity updated; Julia GPU extractors +(`+a1b0e82+`, `+89b76be+`). +* ✅ *live-provers.yml `+--features live-provers+` compile fix* — +`+gnn_api_url: None+` added to `+live_prover_suite.rs+` and +`+live_prover_verify.rs+` live_config(); GPU backends added to T4-GPU +matrix job (`+dc02547+`). +* ✅ *Wave-4 per-backend rationale* — all 19 backends documented with +mock-only justification in `+STATE.a2ml [wave-4-rationale]+` +(`+1ca9862+`). +* ✅ *chapel-ci.yml checkout v4→v6* — 3 stale v4 SHA pins upgraded to +canonical v6.0.2 (`+1ca9862+`). + +=== P0 — Immediate pickup + +[width="100%",cols="24%,24%,20%,32%",options="header",] +|=== +|Task |Lane |Est |Blocks +|*Watch next `+0 3 * * *+` UTC nightly of `+live-provers.yml+`* — Wave-2 +installers (idris2 / isabelle / dafny / fstar / tlaps) are local-pass +but CI-unverified. Fix red matrix cells in-place. Likely failure modes: +Isabelle2024 500 MB download timeout, tlapm release URL drift, +`+fstar.exe+` symlink resolution, apt mirror changes. |L3 |1 session |L3 +Wave-3 gate + +|[line-through]#*Real-Chapel CI job*# |✅ Done (`+3fb6c6b+`) |— |— +|=== + +=== P1 — L3 completion (~2 weeks) + +==== Wave-3 (Tier-3 weekly, 9 backends) — ✅ DONE & CONSOLIDATED (2026-05-18) + +*Status:* all 9 images authored and landed. Originally nine separate +`+Containerfile.+` files (`+a87fae1+`); each re-compiled the +entire Rust core. *Consolidated 2026-05-18* into a single multi-target +`+.containerization/Containerfile.wave3+` — ONE shared `+rust-builder+` +stage, one `+--target+` per prover +(`+podman build -f … --target +`). Justfile + +`+container-ci.yml+` rewired. Guix-extend was investigated and rejected +as the primary path (only SCIP/OR-Tools/Metamath are in Guix; 5 need +bespoke package defs; Imandra is non-free) — per the 2026-05-18 estate +ruling, the sealed container _is_ the escape hatch for the not-in-Guix / +non-free tail (Guix primary, no Guix mirror; `+flake.guix+` deprecated +and removed estate-wide 2026-06-01). Imandra target remains +licence-gated. Table below kept for the per-backend install strategy of +record. + +Handover hints live in +`+.machine_readable/descriptiles/STATE.a2ml [wave-3-handover-hints]+`. + +Strategy of record below = *as actually shipped & runtime-smoke-verified +in `+.containerization/Containerfile.wave3+`* (2026-05-18, PR #73). +Every non-proprietary backend was confirmed real by running its binary +in the built image, not by trusting the build log — see "`Wave-3 +verification`" note after the table. + +[width="99%",cols="27%,51%,22%",options="header",] +|=== +|Backend |Install strategy (verified) |Status +|Tamarin |Official `+tamarin-prover+` prebuilt + *official SRI-CSL Maude +3.5.1 prebuilt* (bookworm apt `+maude+` is 3.2, which tamarin-prover +1.12.0 rejects) |✅ REAL + +|ProVerif |*Official INRIA source tarball `+proverif2.05+`*, built with +bookworm `+ocaml+`/`+ocaml-findlib+`/`+ocamlbuild+` + +`+liblablgtk2-ocaml-dev+` (`+./build+` hard-fails without it), +`+tar --no-same-owner+`. *No opam* (resolves #74) |✅ REAL + +|Imandra |Proprietary — signed registration required. *Intentional +honest fail-loud stub* + documented `+IMANDRA_TOKEN+`-secret +real-install path; real Rust adapter + Idris2 ABI proofs retained. Kept +by decision 2026-05-18 |⏸ stub (by design) + +|SCIP |Official `+scipopt/scip+` GitHub portable bundle (scipopt.org +download 403s anonymous) |✅ REAL + +|OR-Tools |Official C++ `+.tar.gz+`; asset name carries the build number +— `+ARG ORTOOLS_BUILD+` must track it (v9.12 → 4544) |✅ REAL + +|HOL4 |Poly/ML build (`+trindemossen-2+`; `+kananaskis-15+` was a +phantom tag) |✅ REAL + +|ACL2 |Common Lisp (SBCL); build-in-place (not relocatable) |✅ REAL + +|Twelf |SML/NJ build; build-in-place (heap path baked) |✅ REAL + +|Metamath |Official `+metamath-exe+` v0.198 source, `+gcc m*.c+` — +*requires `+libc6-dev+`* (bookworm-slim `+gcc+` lacks libc headers) |✅ +REAL +|=== + +*Wave-3 verification (2026-05-18, PR #73, `+ea2ce4b+`):* all 8 +non-proprietary backends runtime-smoke-verified REAL by exercising the +binary in the built image — _not_ trusting the build log. A green Wave-3 +build had been masking silent stubs (scip/tamarin dead-download, +metamath missing `+libc6-dev+`, or-tools missing build-number, +twelf/acl2 baked build paths, proverif opam-solve failure); all fixed +at-source. *#74 (proverif opam) resolved.* Imandra remains the only stub +— genuinely proprietary, honestly fail-loud, kept by decision (real +adapter + Idris2 ABI proofs retained). No stub-theatre. + +==== Wave-4 (Tier-4 quarterly, 19 backends, allow-fail placeholder) + +Mizar, Nuprl, PVS, Minlog, Dedukti, Arend, KeY, Prism, UPPAAL, ViPER, +NuSMV, Spin, TLC, CBMC, Seahorn, dReal, Boogie, Kissat, Alloy. Retain as +mock-only unless a maintainer volunteers a Containerfile. Document why +each stays mock in a per-backend one-liner. + +==== Wave-5 (new backend targets, no adapter yet) + +Backends not yet scaffolded in `+src/rust/provers/+`; ProverKind enum, +factory dispatch, `+kind_to_u8+` discriminant, Idris2 injectivity proof, +FFI table all need entries before any CI work. Tracked here so they are +not forgotten: + +[width="100%",cols="24%,38%,38%",options="header",] +|=== +|Backend |Scaffold plan |Accessibility +|Andromeda |New `+provers/andromeda.rs+` adapter shelling out to +`+andromeda+` CLI; OCaml source build required |Open-source (MIT), build +from source + +|Theorema |Deferred — requires Mathematica licence (commercial) +|Access-blocked in OSS CI; revisit if a maintainer has a licence + +|Globular |Not a CLI prover (web UI for higher category theory) — +skipped unless scoped to graphical proof capture |N/A +|=== + +==== L3 hygiene + +* [line-through]#*Dafny deep-wiring upgrade*# — ✅ Done (`+e54275d+`): +temp-file subprocess, term_to_dafny_expr, real suggest_tactics. +* [line-through]#*VeriSimDB record emission*# — ✅ Done (`+13cf817+`): +`+emit_live_result()+` wired in `+assert_version_reachable+`. +* *`+guix shell -m manifests/live-provers.scm -- just test-live+`* — +local-reproducibility acceptance criterion; confirm works end-to-end. +* *L3 hand-to-L1 gate*: Tier-1 green on main for ≥ 7 days + all four +waves landed or explicitly deferred with rationale in STATE.a2ml. + +=== P2 — L1: Cap’n Proto protocol swap (~2 weeks, gated on L3 hand-off) + +Rationale: HTTP+JSON on Rust↔Julia hot path +(`+src/rust/gnn/client.rs:1-195+` → `+src/julia/api_server.jl:8090+`) +violates `+feedback_no_json_emit_a2ml+`. + +==== Deliverables + +* `+schemas/echidna.capnp+` — canonical wire schemas: `+ProofGoal+`, +`+ProofResult+`, `+TacticSuggestion+`, `+GnnRankRequest+`, +`+GnnRankResponse+`, `+ProverInvocation+`, `+TrustedOutcome+`. +* `+schemas/VERSIONING.md+` — forward/backward compat rules. +* `+src/rust/ipc/+` — Cap’n Proto transport module; UDS primary, TCP +fallback. +* Replace HTTP calls in `+src/rust/gnn/client.rs+` with UDS + Cap’n +Proto. +* `+src/julia/ipc.jl+` — use `+CapnProto.jl+` if mature; otherwise shim +via C-ABI through Zig. +* `+src/abi/CapnSchemas.idr+` — Idris2 ABI mirror proving schema +compatibility, zero `+believe_me+`. +* `+ffi/zig/capnp_bridge.zig+` — C-ABI bridge for polyglot consumers. +* `+bindings/affinescript/echidna_capnp.res+` — AffineScript UI +bindings. +* `+just capnp-gen+` recipe regenerating all bindings; CI check that +generated code is committed. + +==== Acceptance + +* Zero `+serde_json::to_*+`/`+from_*+` on Rust↔Julia hot path (verify +with code-only grep per +`+feedback_code_only_grep_for_banned_patterns+`). +* Idris2 ABI compiles zero `+believe_me+`. +* Cap’n Proto round-trip ≤ 50% of JSON latency for GNN rank request. +* Round-trip property tests on all six schemas (Rust, Julia, Idris2). +* Existing GraphQL/gRPC/REST interfaces unchanged — Cap’n Proto is the +*internal* wire format. + +==== Design questions to settle early + +[arabic] +. UDS path convention: `+/run/echidna/ipc.sock+` vs +`+$XDG_RUNTIME_DIR/echidna/ipc.sock+`. +. Initial handshake signed with existing BLAKE3/SHAKE3-512 integrity +keys? +. Streaming vs request-response: Cap’n Proto RPC streams for GNN batch +inference? +. Multi-locale Chapel: schemas need to survive locale-to-locale transit; +design now so L2 doesn’t re-spec. + +=== P3 — L2: Chapel maximum integration (~5–6 weeks, gated on L1) + +Existing POC: `+chapel_poc/parallel_proof_search.chpl+` (420 LoC) + the +self-linking FFI bridge (`+53ab9b8+`). *L2.1 is wired into the dispatch +path* (`+dispatch.rs::verify_proof_parallel+` → +`+ChapelParallelSearch+`, live on `+/api/verify_parallel+`). Sub-waves: + +[width="100%",cols="47%,31%,22%",options="header",] +|=== +|Sub-wave |Scope |Est +|L2.1 |✅ *Done.* Portfolio dispatch POC promoted; +`+ChapelParallelSearch+` wired into `+src/rust/dispatch.rs+` behind +`+--features chapel+` with sequential fallback; reachable via +`+/api/verify_parallel+`. Build reproducibility fixed 2026-05-18 +(`+build.rs+` artifact `+rerun-if-changed+`; `+build.zig+` +`+bundle_compiler_rt+`) — `+cargo build/test --features chapel+` green +standalone, 7/7 incl. `+test_verify_proof_parallel_chapel_path+`. |— + +|L2.2 |Speculative tactic search — parallel beam + MCTS; consumes +`+TacticSuggestion+` stream from GNN |1 week + +|L2.3 |Corpus-parallel ops — `+forall+` over 66,674-proof corpus; +replay, premise scoring, tactic mining, inverted index |1 week + +|L2.4 |Mutation-testing parallelism — fan out 1000s of mutants; +integrate with `+verification/mutation.rs+` |3 days + +|L2.5 |Multi-locale distributed — PGAS-sharded corpus; locale-aware +dispatch; GPU-locale offload for GNN embeddings |1.5 weeks + +|L2.6 |Numeric hot paths — parallel embedding pre-proc, Pareto frontier, +confidence statistics |4 days + +|L2.7 |CI + bench — `+chapel-live.yml+`; Chapel portfolio vs Rust+Rayon; +reproducibility harness |3 days +|=== + +==== L2 acceptance + +* Chapel invoked on the hot path by *default* after L2.7 benchmarks +prove ≥ 1.5× speedup on 8+ core machines (until then: feature-flagged, +opt-in). +* `+src/chapel/+` has 6+ modules wired via Zig FFI + Cap’n Proto. +* `+chapel_poc/+` archived with redirect note in its README. +* Multi-locale path proven on at least one dev-hardware config. +* No Rust code duplicates what Chapel does best (avoid double-paths). + +=== P4 — Adjacent / deferred + +* *Tamarin + ProVerif backend stale-listing* — corrected 2026-04-19 in +STATE.a2ml. They are fully wired (592 / 799 LoC Rust) and registered in +`+ProverFactory+`. Handover docs + AI-WORK-todo already updated. +* *No TODO/FIXME in src/rust/ Rust core* — corrected 2026-04-19; +standing property. +* *VeriSim RDF cross-prover alignment* — blocked on `+verisimdb#3+`; not +`+echidna#3+`. +* *TypeDiscipline deep native wiring* (phase-2 deferred) — +per-discipline proof encoding, Idris2 validator tagging, family-aware +GNN features, per-discipline integration tests under +`+tests/disciplines/+`, Katagoria fixture round-trip, per-discipline +dispatch scoring. +* *HP type-checker ecosystem backends* — 13 corpus-only provers +(KatagoriaVerifier, +Modal/Session/Choreographic/Epistemic/Refinement/Echo/Dependent/QTT/Effect-Row/Tropical/TypeLL +etc.) need Rust backends shelling out to the HP stack (Ephapax, +Wokelang, AffineScript) — corpus contributes to vocab/training only +until backends wire up dispatch. +* *CR-1..CR-10 cross-repo tests* from standards +`+TESTING-TAXONOMY.adoc+` — notably CR-2 foreign-enum exhaustive-match +lint, CR-3 FFI roundtrip over all variants, CR-6 upstream-HEAD sentinel. +* *Remaining CI infra failures* — Mirror to Git Forges Radicle SSH key +unset; Instant Sync `+.git-private-farm+` bad credentials. Tokens +human-owned — see `+YOUR-ACTIONS-todo.md §0c+`. + +=== Non-goals (explicit) + +* HTTP capability gateway + SDP for local (non-goal — v2 federation +only). +* L1 replacing the declared GraphQL/gRPC/REST external surfaces — Cap’n +Proto is *internal* wire format only. +* `+boj_cartridge_invoke+` wiring ahead of primary HTTP path — not +blocking. + +=== Open questions + +[arabic] +. *Imandra licence* — signed registration needed before Wave-3 +Containerfile can download. Do you already hold a licence, or defer +Imandra to Wave-4? (Current default: Wave-3 scaffold mentions it but +install is gated on this decision.) +. [line-through]#*Cap’n Proto Julia library*# — *RESOLVED 2026-05-18: +Zig C-ABI shim (buffer-oriented), NOT `+CapnProto.jl+`.* +Estate-canonical (FFI=Zig; single codec shared with Rust; Zig = +interface-safety transaction layer). `+CapnProto.jl+` rejected (low +maturity + second wire codec = drift). See +`+docs/handover/L1-CAPNPROTO-PROMPT.md+` §Resolved decisions. +. *Chapel default-on threshold* — the plan says ≥ 1.5× speedup to flip +default-on. Is that the right threshold, or do we want absolute +wall-clock improvement too (e.g. ≥ 5 s saved on portfolio dispatch of +the full 48-backend set)? + +=== Rules active (applies to all phases) + +* `+feedback_wire_everything+` — no stubs; promote not re-implement. +* `+feedback_no_json_emit_a2ml+` — L1’s raison d’être. +* `+feedback_verisimdb_policy+` — L3 harness + all IPC traffic emit +VeriSimDB records. +* `+feedback_full_battery_before_claims+` — "`production`" = tests + +benches + panic-attack + proofs + axioms + causality + verifiable I/O. +* `+feedback_commit_asap+` — one unit = one commit. +* `+feedback_push_merge_default+` — push `+origin+` only (GitHub); no +other forges directly. +* `+feedback_meander_resource_costs+` — Chapel builds slow; cache +aggressively. +* `+feedback_resource_awareness+` — max 3 parallel subagents, 2 parallel +Bash. +* `+feedback_opus_supervise_haiku_first+` — Opus orchestrates, Haiku for +mechanical subtasks. + +=== Task status snapshot + +*Complete (L3 Wave-1 + Wave-2 + Chapel self-link + Dafny deep-wiring + +VeriSimDB emit):* 19 Tier-1/2 backends CI-installable; 18/18 live tests +pass locally; `+cargo build --features chapel+` links standalone against +bundled Zig stubs; Tamarin/ProVerif confirmed fully wired (were +stale-listed as "`planned`"); Dafny deep-wiring done (`+e54275d+`); +VeriSimDB record emission done (`+13cf817+`); Real-Chapel CI job done +(`+3fb6c6b+`). + +*P0 immediate:* Watch the `+0 3 * * *+` UTC nightly of +`+live-provers.yml+` — Wave-2 CI verification (Tier-2 backends: +idris2/isabelle/dafny/fstar/tlaps). Fix any red matrix cells in-place. +`+guix shell -m manifests/live-provers.scm -- just test-live+` local +acceptance run. + +*P1 L3 finishers:* Wave-3 ✅ DONE & consolidated to one +`+Containerfile.wave3+` (2026-05-18; see Wave-3 section above), Wave-4 +✅ (19 placeholder + rationale docs in STATE.a2ml). L3 P1 finisher work +is complete; the L3→L1 hand-off remains gated only on the calendar/infra +gate (Tier-1 green ≥7 days on main — blocked by main CI stuck +`+queued/+`, infra-owned, not collapsible here). + +*P2 L1:* Implementation NOT started — still gated on the L3 hand-off. +Ahead-of-gate spec/design is landed: `+schemas/echidna.capnp+` + +`+schemas/VERSIONING.md+` present; Julia-transport open question +RESOLVED (Zig C-ABI shim, see §Open questions #2). L1 implementation +(src/rust/ipc, gnn/client.rs swap, julia ipc.jl, CapnSchemas.idr, zig +bridge) waits on the gate. + +*P3 L2:* L2.1 done — POC promoted, wired into dispatch +(`+/api/verify_parallel+`), `+--features chapel+` builds/tests green +standalone (build reproducibility fixed 2026-05-18). L2.2–L2.7 not +started, hard-gated on L1 Cap’n Proto (itself gated on L3 7-day-green +hand-off). diff --git a/docs/handover/TODO.md b/docs/handover/TODO.md deleted file mode 100644 index 9fc4bfce..00000000 --- a/docs/handover/TODO.md +++ /dev/null @@ -1,206 +0,0 @@ -# Echidna Production-Wiring — TODO - -**Source of truth for pending work.** Complements `ECHIDNA-STATE.md` (where -we are) and the full continuation prompts at -`verification-ecosystem/echidna/docs/handover/{L1,L2,L3,PRODUCTION-WIRING-PLAN}.md`. - -Last updated: 2026-04-26 (session 2). - -Execution order from the master plan: **L3 → L1 → L2.** L3 blocks L1; -L1 blocks L2 (because Chapel consumes Cap'n Proto schemas). - ---- - -## Completed items (2026-04-26) - -- ✅ **`echidna-graphql` build** — ProverKind 30→113 variants, trait stubs, FFI casts fixed (`5aec9d5`). All three interface crates now build clean. -- ✅ **FFI boundary audit** — `audits/audit-ffi-boundary.md` + `audits/assail-classifications.a2ml` classifying all legitimate UnsafeCode at FFI boundaries (`b4d682b`). -- ✅ **`bounded_read_config`** — sync 1 MiB-capped read helper in `src/rust/integrity/io.rs`; `solver_integrity.rs` migrated. -- ✅ **F5 (boj-server `echidna-llm-mcp`)** — `consult` + `suggest_tactics` operations implemented; Elixir router patched for `{operation, params}` alias; 176 boj-server tests pass (`a6c8456`). -- ✅ **Real-Chapel CI job** — `chapel-ci.yml` Job 4 `rust-chapel-real` added (`continue-on-error: true`), downloads real Chapel lib and builds Rust without Zig stubs (`3fb6c6b`). -- ✅ **Stage 8b — Agda meta-proofs 6→12 modules** — TrustLattice, AxiomMonotonicity, DispatchOrdering, SoundnessPreservation, PortfolioConsistency, CertificateChain (`6caff97`). -- ✅ **Stage 8d — panic-attack proptest harnesses** — 13 property tests across term/trust/danger/pareto modules (`99198b0`). -- ✅ **Stage 8d — AFL++ fuzz targets** — 3 real libfuzzer targets (proof_state JSON deserialization, trust pipeline, axiom tracker) replacing stub (`46453c4`). -- ✅ **Stage 8a — Idris2 trust-kernel proofs** — TrustKernelMonotonicity, AxiomPolicyOrdering, ClampTrustBounds; zero believe_me; PROOF-NEEDS.md updated (`1444a30`). -- ✅ **Stage 3a/3b — VeriSimDB read paths + dispatch advisor** — `query_by_goal_hash`, `query_prover_success_by_class`, `VeriSimAdvisor`, `verify_proof_verisim_guided` (`804ead6`). -- ✅ **S5 — GNN-augmented suggest_tactics** — `gnn_augment_tactics` helper; rocq/lean/agda/isabelle/z3 backends prepend GNN-ranked apply tactics (`c4bc272`). -- ✅ **S1 batch — 12 Julia premise extractors** — SMT-LIB, TPTP, Dafny, Lean3, HOL Light, Metamath, Tamarin, ProVerif, Boogie, Viper, MiniZinc, Twelf; named extractors 12→24 (`d7a2493`). -- ✅ **S1 batch — 20 more extractors** (24→44): Isabelle, Coq/Rocq, Why3, TLAPS, Idris2, Vampire, EProver, SPASS, AltErgo, FStar, Mizar, CVC5, HOL4, ACL2, Minlog, PVS, Nuprl, Twelf2, Z3-DTsolver, Agda-core (`53ee39a`). -- ✅ **S1 final 6 extractors** (44→50): SPIN/Promela, CBMC-C, SCIP-opt, KeY-Java, Alloy-Relational, NuSMV-temporal (`4ead82a`). -- ✅ **GPUVerify + Faial backends** — GPU CUDA/OpenCL verification; `src/rust/provers/gpuverify.rs` + `faial.rs`; ProverKind variants 113/114; ProverKindInjectivity updated; Julia GPU extractors (`a1b0e82`, `89b76be`). -- ✅ **live-provers.yml `--features live-provers` compile fix** — `gnn_api_url: None` added to `live_prover_suite.rs` and `live_prover_verify.rs` live_config(); GPU backends added to T4-GPU matrix job (`dc02547`). -- ✅ **Wave-4 per-backend rationale** — all 19 backends documented with mock-only justification in `STATE.a2ml [wave-4-rationale]` (`1ca9862`). -- ✅ **chapel-ci.yml checkout v4→v6** — 3 stale v4 SHA pins upgraded to canonical v6.0.2 (`1ca9862`). - -## P0 — Immediate pickup - -| Task | Lane | Est | Blocks | -|------|------|-----|--------| -| **Watch next `0 3 * * *` UTC nightly of `live-provers.yml`** — Wave-2 installers (idris2 / isabelle / dafny / fstar / tlaps) are local-pass but CI-unverified. Fix red matrix cells in-place. Likely failure modes: Isabelle2024 500 MB download timeout, tlapm release URL drift, `fstar.exe` symlink resolution, apt mirror changes. | L3 | 1 session | L3 Wave-3 gate | -| ~~**Real-Chapel CI job**~~ | ✅ Done (`3fb6c6b`) | — | — | - -## P1 — L3 completion (~2 weeks) - -### Wave-3 (Tier-3 weekly, 9 backends) — ✅ DONE & CONSOLIDATED (2026-05-18) - -**Status:** all 9 images authored and landed. Originally nine separate -`Containerfile.` files (`a87fae1`); each re-compiled the entire Rust -core. **Consolidated 2026-05-18** into a single multi-target -`.containerization/Containerfile.wave3` — ONE shared `rust-builder` stage, one -`--target` per prover (`podman build -f … --target `). Justfile + -`container-ci.yml` rewired. Guix-extend was investigated and rejected as the -primary path (only SCIP/OR-Tools/Metamath are in Guix; 5 need bespoke package -defs; Imandra is non-free) — per the 2026-05-18 estate ruling, the sealed -container *is* the escape hatch for the not-in-Guix / non-free tail (Guix -primary, no Guix mirror; `flake.guix` deprecated and removed estate-wide 2026-06-01). Imandra target remains -licence-gated. Table below kept for the per-backend install strategy of record. - -Handover hints live in `.machine_readable/descriptiles/STATE.a2ml [wave-3-handover-hints]`. - -Strategy of record below = **as actually shipped & runtime-smoke-verified -in `.containerization/Containerfile.wave3`** (2026-05-18, PR #73). Every -non-proprietary backend was confirmed real by running its binary in the -built image, not by trusting the build log — see "Wave-3 verification" -note after the table. - -| Backend | Install strategy (verified) | Status | -|---------|------------------|--------| -| Tamarin | Official `tamarin-prover` prebuilt + **official SRI-CSL Maude 3.5.1 prebuilt** (bookworm apt `maude` is 3.2, which tamarin-prover 1.12.0 rejects) | ✅ REAL | -| ProVerif | **Official INRIA source tarball `proverif2.05`**, built with bookworm `ocaml`/`ocaml-findlib`/`ocamlbuild` + `liblablgtk2-ocaml-dev` (`./build` hard-fails without it), `tar --no-same-owner`. **No opam** (resolves #74) | ✅ REAL | -| Imandra | Proprietary — signed registration required. **Intentional honest fail-loud stub** + documented `IMANDRA_TOKEN`-secret real-install path; real Rust adapter + Idris2 ABI proofs retained. Kept by decision 2026-05-18 | ⏸ stub (by design) | -| SCIP | Official `scipopt/scip` GitHub portable bundle (scipopt.org download 403s anonymous) | ✅ REAL | -| OR-Tools | Official C++ `.tar.gz`; asset name carries the build number — `ARG ORTOOLS_BUILD` must track it (v9.12 → 4544) | ✅ REAL | -| HOL4 | Poly/ML build (`trindemossen-2`; `kananaskis-15` was a phantom tag) | ✅ REAL | -| ACL2 | Common Lisp (SBCL); build-in-place (not relocatable) | ✅ REAL | -| Twelf | SML/NJ build; build-in-place (heap path baked) | ✅ REAL | -| Metamath | Official `metamath-exe` v0.198 source, `gcc m*.c` — **requires `libc6-dev`** (bookworm-slim `gcc` lacks libc headers) | ✅ REAL | - -**Wave-3 verification (2026-05-18, PR #73, `ea2ce4b`):** all 8 -non-proprietary backends runtime-smoke-verified REAL by exercising the -binary in the built image — *not* trusting the build log. A green Wave-3 -build had been masking silent stubs (scip/tamarin dead-download, -metamath missing `libc6-dev`, or-tools missing build-number, -twelf/acl2 baked build paths, proverif opam-solve failure); all fixed -at-source. **#74 (proverif opam) resolved.** Imandra remains the only -stub — genuinely proprietary, honestly fail-loud, kept by decision -(real adapter + Idris2 ABI proofs retained). No stub-theatre. - -### Wave-4 (Tier-4 quarterly, 19 backends, allow-fail placeholder) - -Mizar, Nuprl, PVS, Minlog, Dedukti, Arend, KeY, Prism, UPPAAL, ViPER, NuSMV, Spin, TLC, CBMC, Seahorn, dReal, Boogie, Kissat, Alloy. Retain as mock-only unless a maintainer volunteers a Containerfile. Document why each stays mock in a per-backend one-liner. - -### Wave-5 (new backend targets, no adapter yet) - -Backends not yet scaffolded in `src/rust/provers/`; ProverKind enum, factory dispatch, `kind_to_u8` discriminant, Idris2 injectivity proof, FFI table all need entries before any CI work. Tracked here so they are not forgotten: - -| Backend | Scaffold plan | Accessibility | -|---------|---------------|---------------| -| Andromeda | New `provers/andromeda.rs` adapter shelling out to `andromeda` CLI; OCaml source build required | Open-source (MIT), build from source | -| Theorema | Deferred — requires Mathematica licence (commercial) | Access-blocked in OSS CI; revisit if a maintainer has a licence | -| Globular | Not a CLI prover (web UI for higher category theory) — skipped unless scoped to graphical proof capture | N/A | - -### L3 hygiene - -- ~~**Dafny deep-wiring upgrade**~~ — ✅ Done (`e54275d`): temp-file subprocess, term_to_dafny_expr, real suggest_tactics. -- ~~**VeriSimDB record emission**~~ — ✅ Done (`13cf817`): `emit_live_result()` wired in `assert_version_reachable`. -- **`guix shell -m manifests/live-provers.scm -- just test-live`** — local-reproducibility acceptance criterion; confirm works end-to-end. -- **L3 hand-to-L1 gate**: Tier-1 green on main for ≥ 7 days + all four waves landed or explicitly deferred with rationale in STATE.a2ml. - -## P2 — L1: Cap'n Proto protocol swap (~2 weeks, gated on L3 hand-off) - -Rationale: HTTP+JSON on Rust↔Julia hot path (`src/rust/gnn/client.rs:1-195` → `src/julia/api_server.jl:8090`) violates `feedback_no_json_emit_a2ml`. - -### Deliverables - -- `schemas/echidna.capnp` — canonical wire schemas: `ProofGoal`, `ProofResult`, `TacticSuggestion`, `GnnRankRequest`, `GnnRankResponse`, `ProverInvocation`, `TrustedOutcome`. -- `schemas/VERSIONING.md` — forward/backward compat rules. -- `src/rust/ipc/` — Cap'n Proto transport module; UDS primary, TCP fallback. -- Replace HTTP calls in `src/rust/gnn/client.rs` with UDS + Cap'n Proto. -- `src/julia/ipc.jl` — use `CapnProto.jl` if mature; otherwise shim via C-ABI through Zig. -- `src/abi/CapnSchemas.idr` — Idris2 ABI mirror proving schema compatibility, zero `believe_me`. -- `ffi/zig/capnp_bridge.zig` — C-ABI bridge for polyglot consumers. -- `bindings/affinescript/echidna_capnp.res` — AffineScript UI bindings. -- `just capnp-gen` recipe regenerating all bindings; CI check that generated code is committed. - -### Acceptance - -- Zero `serde_json::to_*`/`from_*` on Rust↔Julia hot path (verify with code-only grep per `feedback_code_only_grep_for_banned_patterns`). -- Idris2 ABI compiles zero `believe_me`. -- Cap'n Proto round-trip ≤ 50% of JSON latency for GNN rank request. -- Round-trip property tests on all six schemas (Rust, Julia, Idris2). -- Existing GraphQL/gRPC/REST interfaces unchanged — Cap'n Proto is the **internal** wire format. - -### Design questions to settle early - -1. UDS path convention: `/run/echidna/ipc.sock` vs `$XDG_RUNTIME_DIR/echidna/ipc.sock`. -2. Initial handshake signed with existing BLAKE3/SHAKE3-512 integrity keys? -3. Streaming vs request-response: Cap'n Proto RPC streams for GNN batch inference? -4. Multi-locale Chapel: schemas need to survive locale-to-locale transit; design now so L2 doesn't re-spec. - -## P3 — L2: Chapel maximum integration (~5–6 weeks, gated on L1) - -Existing POC: `chapel_poc/parallel_proof_search.chpl` (420 LoC) + the self-linking FFI bridge (`53ab9b8`). **L2.1 is wired into the dispatch path** (`dispatch.rs::verify_proof_parallel` → `ChapelParallelSearch`, live on `/api/verify_parallel`). Sub-waves: - -| Sub-wave | Scope | Est | -|----------|-------|-----| -| L2.1 | ✅ **Done.** Portfolio dispatch POC promoted; `ChapelParallelSearch` wired into `src/rust/dispatch.rs` behind `--features chapel` with sequential fallback; reachable via `/api/verify_parallel`. Build reproducibility fixed 2026-05-18 (`build.rs` artifact `rerun-if-changed`; `build.zig` `bundle_compiler_rt`) — `cargo build/test --features chapel` green standalone, 7/7 incl. `test_verify_proof_parallel_chapel_path`. | — | -| L2.2 | Speculative tactic search — parallel beam + MCTS; consumes `TacticSuggestion` stream from GNN | 1 week | -| L2.3 | Corpus-parallel ops — `forall` over 66,674-proof corpus; replay, premise scoring, tactic mining, inverted index | 1 week | -| L2.4 | Mutation-testing parallelism — fan out 1000s of mutants; integrate with `verification/mutation.rs` | 3 days | -| L2.5 | Multi-locale distributed — PGAS-sharded corpus; locale-aware dispatch; GPU-locale offload for GNN embeddings | 1.5 weeks | -| L2.6 | Numeric hot paths — parallel embedding pre-proc, Pareto frontier, confidence statistics | 4 days | -| L2.7 | CI + bench — `chapel-live.yml`; Chapel portfolio vs Rust+Rayon; reproducibility harness | 3 days | - -### L2 acceptance - -- Chapel invoked on the hot path by **default** after L2.7 benchmarks prove ≥ 1.5× speedup on 8+ core machines (until then: feature-flagged, opt-in). -- `src/chapel/` has 6+ modules wired via Zig FFI + Cap'n Proto. -- `chapel_poc/` archived with redirect note in its README. -- Multi-locale path proven on at least one dev-hardware config. -- No Rust code duplicates what Chapel does best (avoid double-paths). - -## P4 — Adjacent / deferred - -- **Tamarin + ProVerif backend stale-listing** — corrected 2026-04-19 in STATE.a2ml. They are fully wired (592 / 799 LoC Rust) and registered in `ProverFactory`. Handover docs + AI-WORK-todo already updated. -- **No TODO/FIXME in src/rust/ Rust core** — corrected 2026-04-19; standing property. -- **VeriSim RDF cross-prover alignment** — blocked on `verisimdb#3`; not `echidna#3`. -- **TypeDiscipline deep native wiring** (phase-2 deferred) — per-discipline proof encoding, Idris2 validator tagging, family-aware GNN features, per-discipline integration tests under `tests/disciplines/`, Katagoria fixture round-trip, per-discipline dispatch scoring. -- **HP type-checker ecosystem backends** — 13 corpus-only provers (KatagoriaVerifier, Modal/Session/Choreographic/Epistemic/Refinement/Echo/Dependent/QTT/Effect-Row/Tropical/TypeLL etc.) need Rust backends shelling out to the HP stack (Ephapax, Wokelang, AffineScript) — corpus contributes to vocab/training only until backends wire up dispatch. -- **CR-1..CR-10 cross-repo tests** from standards `TESTING-TAXONOMY.adoc` — notably CR-2 foreign-enum exhaustive-match lint, CR-3 FFI roundtrip over all variants, CR-6 upstream-HEAD sentinel. -- **Remaining CI infra failures** — Mirror to Git Forges Radicle SSH key unset; Instant Sync `.git-private-farm` bad credentials. Tokens human-owned — see `YOUR-ACTIONS-todo.md §0c`. - -## Non-goals (explicit) - -- HTTP capability gateway + SDP for local (non-goal — v2 federation only). -- L1 replacing the declared GraphQL/gRPC/REST external surfaces — Cap'n Proto is **internal** wire format only. -- `boj_cartridge_invoke` wiring ahead of primary HTTP path — not blocking. - -## Open questions - -1. **Imandra licence** — signed registration needed before Wave-3 Containerfile can download. Do you already hold a licence, or defer Imandra to Wave-4? (Current default: Wave-3 scaffold mentions it but install is gated on this decision.) -2. ~~**Cap'n Proto Julia library**~~ — **RESOLVED 2026-05-18: Zig C-ABI shim (buffer-oriented), NOT `CapnProto.jl`.** Estate-canonical (FFI=Zig; single codec shared with Rust; Zig = interface-safety transaction layer). `CapnProto.jl` rejected (low maturity + second wire codec = drift). See `docs/handover/L1-CAPNPROTO-PROMPT.md` §Resolved decisions. -3. **Chapel default-on threshold** — the plan says ≥ 1.5× speedup to flip default-on. Is that the right threshold, or do we want absolute wall-clock improvement too (e.g. ≥ 5 s saved on portfolio dispatch of the full 48-backend set)? - -## Rules active (applies to all phases) - -- `feedback_wire_everything` — no stubs; promote not re-implement. -- `feedback_no_json_emit_a2ml` — L1's raison d'être. -- `feedback_verisimdb_policy` — L3 harness + all IPC traffic emit VeriSimDB records. -- `feedback_full_battery_before_claims` — "production" = tests + benches + panic-attack + proofs + axioms + causality + verifiable I/O. -- `feedback_commit_asap` — one unit = one commit. -- `feedback_push_merge_default` — push `origin` only (GitHub); no other forges directly. -- `feedback_meander_resource_costs` — Chapel builds slow; cache aggressively. -- `feedback_resource_awareness` — max 3 parallel subagents, 2 parallel Bash. -- `feedback_opus_supervise_haiku_first` — Opus orchestrates, Haiku for mechanical subtasks. - -## Task status snapshot - -**Complete (L3 Wave-1 + Wave-2 + Chapel self-link + Dafny deep-wiring + VeriSimDB emit):** 19 Tier-1/2 backends CI-installable; 18/18 live tests pass locally; `cargo build --features chapel` links standalone against bundled Zig stubs; Tamarin/ProVerif confirmed fully wired (were stale-listed as "planned"); Dafny deep-wiring done (`e54275d`); VeriSimDB record emission done (`13cf817`); Real-Chapel CI job done (`3fb6c6b`). - -**P0 immediate:** Watch the `0 3 * * *` UTC nightly of `live-provers.yml` — Wave-2 CI verification (Tier-2 backends: idris2/isabelle/dafny/fstar/tlaps). Fix any red matrix cells in-place. `guix shell -m manifests/live-provers.scm -- just test-live` local acceptance run. - -**P1 L3 finishers:** Wave-3 ✅ DONE & consolidated to one `Containerfile.wave3` (2026-05-18; see Wave-3 section above), Wave-4 ✅ (19 placeholder + rationale docs in STATE.a2ml). L3 P1 finisher work is complete; the L3→L1 hand-off remains gated only on the calendar/infra gate (Tier-1 green ≥7 days on main — blocked by main CI stuck `queued/`, infra-owned, not collapsible here). - -**P2 L1:** Implementation NOT started — still gated on the L3 hand-off. Ahead-of-gate spec/design is landed: `schemas/echidna.capnp` + `schemas/VERSIONING.md` present; Julia-transport open question RESOLVED (Zig C-ABI shim, see §Open questions #2). L1 implementation (src/rust/ipc, gnn/client.rs swap, julia ipc.jl, CapnSchemas.idr, zig bridge) waits on the gate. - -**P3 L2:** L2.1 done — POC promoted, wired into dispatch (`/api/verify_parallel`), `--features chapel` builds/tests green standalone (build reproducibility fixed 2026-05-18). L2.2–L2.7 not started, hard-gated on L1 Cap'n Proto (itself gated on L3 7-day-green hand-off). diff --git a/docs/handover/llm-warmup-dev.adoc b/docs/handover/llm-warmup-dev.adoc new file mode 100644 index 00000000..d934237f --- /dev/null +++ b/docs/handover/llm-warmup-dev.adoc @@ -0,0 +1,240 @@ +== ECHIDNA — Developer Context + +=== Architecture + +ECHIDNA is a Rust workspace with Julia ML, Idris2 ABI, Zig FFI, and +AffineScript UI. + +==== Rust Core (src/rust/) + +The main binary and library. Key modules: + +[width="100%",cols="53%,47%",options="header",] +|=== +|File/Dir |Purpose +|`+main.rs+` |CLI entry (clap) + +|`+lib.rs+` |Library root — re-exports all modules + +|`+core.rs+` |Core types: `+Term+`, `+ProofState+`, `+Tactic+`, +`+Goal+`, `+Context+`, `+Theorem+` + +|`+repl.rs+` |Interactive REPL + +|`+server.rs+` |HTTP API server + +|`+dispatch.rs+` |Full trust-hardening dispatch pipeline + +|`+neural.rs+` |Neural premise selection + +|`+aspect.rs+` |Aspect tagging + +|`+provers/+` |30 prover backend implementations + +|`+provers/mod.rs+` |`+ProverBackend+` trait, `+ProverKind+` enum (48 +variants), `+ProverFactory+` + +|`+verification/+` |Trust pipeline modules + +|`+integrity/+` |Solver binary integrity (SHAKE3-512, BLAKE3) + +|`+executor/+` |Sandboxed execution (Podman, bubblewrap) + +|`+exchange/+` |Cross-prover proof exchange (OpenTheory, Dedukti) + +|`+agent/+` |Agentic proof search (actor model) + +|`+parsers/+` |Proof file parsers + +|`+ffi/+` |Foreign function interface +|=== + +==== Verification Pipeline (src/rust/verification/) + +[width="100%",cols="48%,52%",options="header",] +|=== +|Module |Purpose +|`+portfolio.rs+` |SMT portfolio solving / cross-checking + +|`+certificates.rs+` |Proof certificate checking (Alethe, DRAT/LRAT, +TSTP) + +|`+axiom_tracker.rs+` |Axiom usage tracking (Safe, Noted, Warning, +Reject) + +|`+confidence.rs+` |5-level trust hierarchy, Bayesian scoring + +|`+mutation.rs+` |Mutation testing for specifications + +|`+pareto.rs+` |Pareto frontier for multi-objective proof search + +|`+statistics.rs+` |Statistical confidence + Bayesian timeout estimation +|=== + +==== API Interfaces (src/interfaces/) + +Three workspace members under `+src/interfaces/+`: + +[cols=",,,",options="header",] +|=== +|Dir |Tech |Port |Notes +|`+graphql/+` |async-graphql |8081 |Query/Mutation/Subscription +|`+grpc/+` |tonic |50051 |4 services +|`+rest/+` |axum + utoipa |8000 |OpenAPI spec +|=== + +*Invariant*: Interfaces stay under `+src/interfaces/+` — never extract +to separate repos. + +==== Julia ML Layer (src/julia/) + +Logistic regression for tactic prediction. Runs on port 8090. Future: +Flux.jl Transformer models. + +==== Idris2 ABI (src/abi/) + +7 modules with dependent type proofs. Zero `+believe_me+`. + +[cols=",",options="header",] +|=== +|File |Purpose +|`+Types.idr+` |Core types with proofs +|`+GraphQL.idr+` |Query/Mutation/Subscription operations +|`+GRPC.idr+` |gRPC service definitions +|`+REST.idr+` |REST endpoint definitions (18 endpoints, 6 groups) +|`+FFI.idr+` |GADT constructors for C ABI functions +|`+echidnaabi.ipkg+` |Package definition +|=== + +==== Zig FFI (ffi/zig/) + +4 shared libraries. Bridges Idris2 ABI to C ABI. + +==== AffineScript UI (src/affinescript/) + +33 .res files. Deno runtime. Zero TypeScript. + +==== Chapel PoC (chapel_poc/) + +Optional parallel proof dispatch. Requires Chapel compiler. + +=== ProverBackend Trait + +The core abstraction in `+src/rust/provers/mod.rs+`: + +[source,rust] +---- +pub trait ProverBackend: Send + Sync { + fn name(&self) -> &str; + fn kind(&self) -> ProverKind; + fn prove(&self, goal: &Goal, timeout: Duration) -> ProofResult; + fn check_certificate(&self, cert: &Certificate) -> CertificateResult; + fn supports_exchange(&self) -> bool; +} +---- + +48 variants in `+ProverKind+` enum. `+ProverFactory+` creates instances. + +=== Dispatch Pipeline (dispatch.rs) + +Full trust-hardening flow: 1. Select candidate provers (aspect tags + +neural ranking) 2. Verify solver binary integrity (SHAKE3-512 + BLAKE3) +3. Execute in sandbox (Podman/bubblewrap/none) 4. Portfolio cross-check +(multiple solvers on same goal) 5. Verify proof certificates 6. Track +axiom usage 7. Score confidence (Bayesian, 5-level hierarchy) 8. +Optional: mutation testing, Pareto frontier + +=== Build Commands + +[source,bash] +---- +just build # Debug build +just build-release # Release build +just test # Unit tests (232) +just test-all # All tests (389) +just test-integration # Integration tests (38) +just test-neural # Julia ML tests +just lint # Clippy +just fmt # Rustfmt +just pre-commit # fmt-check + lint + test +just container-build # Minimal container +just container-build-full # Full container +just build-chapel-ffi # Zig FFI for Chapel +just build-chapel-poc # Chapel PoC binary +just chapel-all # Full Chapel stack +just doctor # Check prerequisites +just heal # Install instructions +---- + +=== Adding a New Prover Backend + +[arabic] +. Add variant to `+ProverKind+` enum in `+src/rust/provers/mod.rs+` +. Implement `+ProverBackend+` trait in `+src/rust/provers/.rs+` +. Register in `+ProverFactory+` +. Add tests (unit + integration) +. Update Julia layer (`+src/julia/+`) with prover metadata +. Update Chapel layer (`+chapel_poc/+`) if parallel dispatch applies +. Run `+just test-all+` + +=== Workspace Members + +[source,toml] +---- +[workspace] +members = [".", "src/interfaces/graphql", "src/interfaces/grpc", "src/interfaces/rest"] +---- + +=== Key Dependencies + +* `+tokio+` — Async runtime +* `+clap+` — CLI parsing +* `+serde+`/`+serde_json+`/`+toml+` — Serialization +* `+anyhow+`/`+thiserror+` — Error handling +* `+async-graphql+` — GraphQL +* `+tonic+`/`+prost+` — gRPC +* `+axum+`/`+utoipa+` — REST + OpenAPI +* `+sha3+`/`+blake3+` — Integrity hashing + +=== Machine-Readable Metadata + +All in `+.machine_readable/+`: - `+descriptiles/STATE.a2ml+` — Current +state - `+descriptiles/META.a2ml+` — Architecture decisions - +`+descriptiles/ECOSYSTEM.a2ml+` — Ecosystem position - +`+descriptiles/AGENTIC.a2ml+`, `+NEUROSYM.a2ml+`, `+PLAYBOOK.a2ml+` + +*NEVER* create these in the root directory. + +=== Packaging + +* `+guix.scm+` — Guix package definition (uses cargo-build-system) +* `+Containerfile+` — Podman container + +(Guix flake removed 2026-06-01 per estate-wide guix-deprecation +directive; Guix is the sole packaging primary.) + +=== Test Structure + +* 232 unit tests (`+cargo test --lib+`) +* 38 integration tests (`+cargo test --test integration_tests+`) +* 119 additional tests (doc tests, property tests) +* Total: 389 + +=== Banned Patterns + +* No Python anywhere (use Julia for ML) +* No Docker (use Podman) +* No TypeScript (use AffineScript) +* No `+believe_me+`/`+assert_total+` in Idris2 +* MPL-2.0 license throughout + +=== CI/CD + +17 workflows in `+.github/workflows/+`: - `+hypatia-scan.yml+`, +`+codeql.yml+`, `+scorecard.yml+`, `+quality.yml+` - `+mirror.yml+`, +`+instant-sync.yml+` - All actions SHA-pinned + +=== License + +MPL-2.0. Author: Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk Git +author: 6759885+hyperpolymath@users.noreply.github.com diff --git a/docs/handover/llm-warmup-dev.md b/docs/handover/llm-warmup-dev.md deleted file mode 100644 index c6c23f81..00000000 --- a/docs/handover/llm-warmup-dev.md +++ /dev/null @@ -1,210 +0,0 @@ - - - - -# ECHIDNA — Developer Context - -## Architecture - -ECHIDNA is a Rust workspace with Julia ML, Idris2 ABI, Zig FFI, and AffineScript UI. - -### Rust Core (src/rust/) - -The main binary and library. Key modules: - -| File/Dir | Purpose | -|----------|---------| -| `main.rs` | CLI entry (clap) | -| `lib.rs` | Library root — re-exports all modules | -| `core.rs` | Core types: `Term`, `ProofState`, `Tactic`, `Goal`, `Context`, `Theorem` | -| `repl.rs` | Interactive REPL | -| `server.rs` | HTTP API server | -| `dispatch.rs` | Full trust-hardening dispatch pipeline | -| `neural.rs` | Neural premise selection | -| `aspect.rs` | Aspect tagging | -| `provers/` | 30 prover backend implementations | -| `provers/mod.rs` | `ProverBackend` trait, `ProverKind` enum (48 variants), `ProverFactory` | -| `verification/` | Trust pipeline modules | -| `integrity/` | Solver binary integrity (SHAKE3-512, BLAKE3) | -| `executor/` | Sandboxed execution (Podman, bubblewrap) | -| `exchange/` | Cross-prover proof exchange (OpenTheory, Dedukti) | -| `agent/` | Agentic proof search (actor model) | -| `parsers/` | Proof file parsers | -| `ffi/` | Foreign function interface | - -### Verification Pipeline (src/rust/verification/) - -| Module | Purpose | -|--------|---------| -| `portfolio.rs` | SMT portfolio solving / cross-checking | -| `certificates.rs` | Proof certificate checking (Alethe, DRAT/LRAT, TSTP) | -| `axiom_tracker.rs` | Axiom usage tracking (Safe, Noted, Warning, Reject) | -| `confidence.rs` | 5-level trust hierarchy, Bayesian scoring | -| `mutation.rs` | Mutation testing for specifications | -| `pareto.rs` | Pareto frontier for multi-objective proof search | -| `statistics.rs` | Statistical confidence + Bayesian timeout estimation | - -### API Interfaces (src/interfaces/) - -Three workspace members under `src/interfaces/`: - -| Dir | Tech | Port | Notes | -|-----|------|------|-------| -| `graphql/` | async-graphql | 8081 | Query/Mutation/Subscription | -| `grpc/` | tonic | 50051 | 4 services | -| `rest/` | axum + utoipa | 8000 | OpenAPI spec | - -**Invariant**: Interfaces stay under `src/interfaces/` — never extract to separate repos. - -### Julia ML Layer (src/julia/) - -Logistic regression for tactic prediction. Runs on port 8090. -Future: Flux.jl Transformer models. - -### Idris2 ABI (src/abi/) - -7 modules with dependent type proofs. Zero `believe_me`. - -| File | Purpose | -|------|---------| -| `Types.idr` | Core types with proofs | -| `GraphQL.idr` | Query/Mutation/Subscription operations | -| `GRPC.idr` | gRPC service definitions | -| `REST.idr` | REST endpoint definitions (18 endpoints, 6 groups) | -| `FFI.idr` | GADT constructors for C ABI functions | -| `echidnaabi.ipkg` | Package definition | - -### Zig FFI (ffi/zig/) - -4 shared libraries. Bridges Idris2 ABI to C ABI. - -### AffineScript UI (src/affinescript/) - -33 .res files. Deno runtime. Zero TypeScript. - -### Chapel PoC (chapel_poc/) - -Optional parallel proof dispatch. Requires Chapel compiler. - -## ProverBackend Trait - -The core abstraction in `src/rust/provers/mod.rs`: - -```rust -pub trait ProverBackend: Send + Sync { - fn name(&self) -> &str; - fn kind(&self) -> ProverKind; - fn prove(&self, goal: &Goal, timeout: Duration) -> ProofResult; - fn check_certificate(&self, cert: &Certificate) -> CertificateResult; - fn supports_exchange(&self) -> bool; -} -``` - -48 variants in `ProverKind` enum. `ProverFactory` creates instances. - -## Dispatch Pipeline (dispatch.rs) - -Full trust-hardening flow: -1. Select candidate provers (aspect tags + neural ranking) -2. Verify solver binary integrity (SHAKE3-512 + BLAKE3) -3. Execute in sandbox (Podman/bubblewrap/none) -4. Portfolio cross-check (multiple solvers on same goal) -5. Verify proof certificates -6. Track axiom usage -7. Score confidence (Bayesian, 5-level hierarchy) -8. Optional: mutation testing, Pareto frontier - -## Build Commands - -```bash -just build # Debug build -just build-release # Release build -just test # Unit tests (232) -just test-all # All tests (389) -just test-integration # Integration tests (38) -just test-neural # Julia ML tests -just lint # Clippy -just fmt # Rustfmt -just pre-commit # fmt-check + lint + test -just container-build # Minimal container -just container-build-full # Full container -just build-chapel-ffi # Zig FFI for Chapel -just build-chapel-poc # Chapel PoC binary -just chapel-all # Full Chapel stack -just doctor # Check prerequisites -just heal # Install instructions -``` - -## Adding a New Prover Backend - -1. Add variant to `ProverKind` enum in `src/rust/provers/mod.rs` -2. Implement `ProverBackend` trait in `src/rust/provers/.rs` -3. Register in `ProverFactory` -4. Add tests (unit + integration) -5. Update Julia layer (`src/julia/`) with prover metadata -6. Update Chapel layer (`chapel_poc/`) if parallel dispatch applies -7. Run `just test-all` - -## Workspace Members - -```toml -[workspace] -members = [".", "src/interfaces/graphql", "src/interfaces/grpc", "src/interfaces/rest"] -``` - -## Key Dependencies - -- `tokio` — Async runtime -- `clap` — CLI parsing -- `serde`/`serde_json`/`toml` — Serialization -- `anyhow`/`thiserror` — Error handling -- `async-graphql` — GraphQL -- `tonic`/`prost` — gRPC -- `axum`/`utoipa` — REST + OpenAPI -- `sha3`/`blake3` — Integrity hashing - -## Machine-Readable Metadata - -All in `.machine_readable/`: -- `descriptiles/STATE.a2ml` — Current state -- `descriptiles/META.a2ml` — Architecture decisions -- `descriptiles/ECOSYSTEM.a2ml` — Ecosystem position -- `descriptiles/AGENTIC.a2ml`, `NEUROSYM.a2ml`, `PLAYBOOK.a2ml` - -**NEVER** create these in the root directory. - -## Packaging - -- `guix.scm` — Guix package definition (uses cargo-build-system) -- `Containerfile` — Podman container - -(Guix flake removed 2026-06-01 per estate-wide guix-deprecation directive; -Guix is the sole packaging primary.) - -## Test Structure - -- 232 unit tests (`cargo test --lib`) -- 38 integration tests (`cargo test --test integration_tests`) -- 119 additional tests (doc tests, property tests) -- Total: 389 - -## Banned Patterns - -- No Python anywhere (use Julia for ML) -- No Docker (use Podman) -- No TypeScript (use AffineScript) -- No `believe_me`/`assert_total` in Idris2 -- MPL-2.0 license throughout - -## CI/CD - -17 workflows in `.github/workflows/`: -- `hypatia-scan.yml`, `codeql.yml`, `scorecard.yml`, `quality.yml` -- `mirror.yml`, `instant-sync.yml` -- All actions SHA-pinned - -## License - -MPL-2.0. -Author: Jonathan D.A. Jewell -Git author: 6759885+hyperpolymath@users.noreply.github.com diff --git a/docs/handover/llm-warmup-user.adoc b/docs/handover/llm-warmup-user.adoc new file mode 100644 index 00000000..d1b9e088 --- /dev/null +++ b/docs/handover/llm-warmup-user.adoc @@ -0,0 +1,116 @@ +== ECHIDNA — User Context + +=== What it is + +ECHIDNA (Extensible Cognitive Hybrid Intelligence for Deductive Neural +Assistance) is a trust-hardened neurosymbolic theorem proving platform +with 48 prover backends. + +It accepts proof obligations, dispatches them to the best-fit prover, +verifies the result through a trust pipeline, and returns +confidence-scored theorems. + +=== Architecture overview + +.... +CLI / REPL / REST / GraphQL / gRPC + | + Rust core (dispatch + trust pipeline) + | + 48 prover backends (SMT, ITP, ATP, constraint) + | + Trust verification: integrity → portfolio → certificates → axioms → confidence + | + Julia ML (tactic prediction, premise selection) +.... + +=== Prover categories (48 total) + +[width="100%",cols="53%,47%",options="header",] +|=== +|Category |Examples +|Interactive proof assistants |Coq, Lean 4, Isabelle, Agda, Idris2, F* +|SMT solvers |Z3, CVC5, Alt-Ergo +|First-order ATPs |Vampire, E Prover, SPASS +|Auto-active verifiers |Dafny, Why3 +|Specialised |Metamath, HOL Light, Mizar, PVS, ACL2, TLAPS +|Constraint solvers |GLPK, SCIP, MiniZinc, OR-Tools +|=== + +=== Key files + +[cols=",",options="header",] +|=== +|Path |Purpose +|`+src/rust/main.rs+` |CLI entry point +|`+src/rust/repl.rs+` |Interactive REPL +|`+src/rust/server.rs+` |HTTP API server +|`+src/rust/provers/+` |30 prover backend implementations +|`+src/rust/verification/+` |Trust pipeline +|`+src/rust/dispatch.rs+` |Full dispatch pipeline +|`+src/interfaces/+` |GraphQL + gRPC + REST APIs +|`+src/julia/+` |ML tactic prediction +|`+Cargo.toml+` |Rust workspace root +|=== + +=== Quick commands + +[source,bash] +---- +just build # Build debug binary +just test # Run 232 unit tests +just test-all # Run all 389 tests +just run repl # Interactive theorem prover +just run serve # Start REST API (port 8000) +just doctor # Check prerequisites +---- + +Prerequisites: Rust (nightly), just, pkg-config, openssl-devel. + +=== Trust pipeline + +Every proof goes through: + +[arabic] +. *Integrity* — Solver binary hash verification (SHAKE3-512 + BLAKE3) +. *Portfolio* — Cross-check with multiple solvers +. *Certificates* — Verify proof certificates (Alethe, DRAT/LRAT, TSTP) +. *Axioms* — Track axiom usage (4 danger levels) +. *Confidence* — Bayesian confidence scoring (5-level hierarchy) +. *Mutation* — Mutation testing for specifications +. *Exchange* — Cross-prover proof exchange (OpenTheory, Dedukti) + +=== Sandboxed execution + +Provers run in sandboxes: - *Podman* — Full container isolation - +*bubblewrap* — Lightweight namespace isolation - *none* — Direct +execution (trusted provers only) + +=== API endpoints + +[cols=",,",options="header",] +|=== +|Interface |Port |Tech +|REST |8000 |axum + OpenAPI +|GraphQL |8081 |async-graphql +|gRPC |50051 |tonic +|=== + +=== Container images + +[source,bash] +---- +just container-build # Minimal (Z3, CVC5, Lean, Idris2) +just container-build-full # All provers + Julia ML +---- + +=== License + +MPL-2.0. Author: Jonathan D.A. Jewell. + +=== Ecosystem position + +* *Depends on*: proven (verified safety), Z3/CVC5/Lean/etc. (solver +binaries) +* *Used by*: hypatia (CI/CD intelligence), ecosystem-wide proof checking +* *Siblings*: panic-attacker (scanning), verisim (data layer) diff --git a/docs/handover/llm-warmup-user.md b/docs/handover/llm-warmup-user.md deleted file mode 100644 index efd0e92f..00000000 --- a/docs/handover/llm-warmup-user.md +++ /dev/null @@ -1,109 +0,0 @@ - - - - -# ECHIDNA — User Context - -## What it is - -ECHIDNA (Extensible Cognitive Hybrid Intelligence for Deductive Neural Assistance) -is a trust-hardened neurosymbolic theorem proving platform with 48 prover backends. - -It accepts proof obligations, dispatches them to the best-fit prover, verifies -the result through a trust pipeline, and returns confidence-scored theorems. - -## Architecture overview - -``` -CLI / REPL / REST / GraphQL / gRPC - | - Rust core (dispatch + trust pipeline) - | - 48 prover backends (SMT, ITP, ATP, constraint) - | - Trust verification: integrity → portfolio → certificates → axioms → confidence - | - Julia ML (tactic prediction, premise selection) -``` - -## Prover categories (48 total) - -| Category | Examples | -|----------|---------| -| Interactive proof assistants | Coq, Lean 4, Isabelle, Agda, Idris2, F* | -| SMT solvers | Z3, CVC5, Alt-Ergo | -| First-order ATPs | Vampire, E Prover, SPASS | -| Auto-active verifiers | Dafny, Why3 | -| Specialised | Metamath, HOL Light, Mizar, PVS, ACL2, TLAPS | -| Constraint solvers | GLPK, SCIP, MiniZinc, OR-Tools | - -## Key files - -| Path | Purpose | -|------|---------| -| `src/rust/main.rs` | CLI entry point | -| `src/rust/repl.rs` | Interactive REPL | -| `src/rust/server.rs` | HTTP API server | -| `src/rust/provers/` | 30 prover backend implementations | -| `src/rust/verification/` | Trust pipeline | -| `src/rust/dispatch.rs` | Full dispatch pipeline | -| `src/interfaces/` | GraphQL + gRPC + REST APIs | -| `src/julia/` | ML tactic prediction | -| `Cargo.toml` | Rust workspace root | - -## Quick commands - -```bash -just build # Build debug binary -just test # Run 232 unit tests -just test-all # Run all 389 tests -just run repl # Interactive theorem prover -just run serve # Start REST API (port 8000) -just doctor # Check prerequisites -``` - -Prerequisites: Rust (nightly), just, pkg-config, openssl-devel. - -## Trust pipeline - -Every proof goes through: - -1. **Integrity** — Solver binary hash verification (SHAKE3-512 + BLAKE3) -2. **Portfolio** — Cross-check with multiple solvers -3. **Certificates** — Verify proof certificates (Alethe, DRAT/LRAT, TSTP) -4. **Axioms** — Track axiom usage (4 danger levels) -5. **Confidence** — Bayesian confidence scoring (5-level hierarchy) -6. **Mutation** — Mutation testing for specifications -7. **Exchange** — Cross-prover proof exchange (OpenTheory, Dedukti) - -## Sandboxed execution - -Provers run in sandboxes: -- **Podman** — Full container isolation -- **bubblewrap** — Lightweight namespace isolation -- **none** — Direct execution (trusted provers only) - -## API endpoints - -| Interface | Port | Tech | -|-----------|------|------| -| REST | 8000 | axum + OpenAPI | -| GraphQL | 8081 | async-graphql | -| gRPC | 50051 | tonic | - -## Container images - -```bash -just container-build # Minimal (Z3, CVC5, Lean, Idris2) -just container-build-full # All provers + Julia ML -``` - -## License - -MPL-2.0. Author: Jonathan D.A. Jewell. - -## Ecosystem position - -- **Depends on**: proven (verified safety), Z3/CVC5/Lean/etc. (solver binaries) -- **Used by**: hypatia (CI/CD intelligence), ecosystem-wide proof checking -- **Siblings**: panic-attacker (scanning), verisim (data layer) diff --git a/docs/implementation/AGDA_IMPLEMENTATION_SUMMARY.adoc b/docs/implementation/AGDA_IMPLEMENTATION_SUMMARY.adoc new file mode 100644 index 00000000..081c24c9 --- /dev/null +++ b/docs/implementation/AGDA_IMPLEMENTATION_SUMMARY.adoc @@ -0,0 +1,658 @@ +== Agda Backend Implementation Summary + +=== COMPLETION STATUS: ✅ PRODUCTION-READY + +The complete Agda backend for ECHIDNA has been successfully implemented +and tested. + +=== Implementation Details + +==== Files Created + +[arabic] +. *Main Implementation* +* `+/home/user/echidna/src/rust/provers/agda.rs+` (17KB, 495 lines) +* Complete production-ready implementation +* Fully documented with extensive inline comments +. *Supporting Infrastructure* +* `+/home/user/echidna/src/rust/provers/coq.rs+` - Coq backend stub +* `+/home/user/echidna/src/rust/provers/lean.rs+` - Lean backend stub +* `+/home/user/echidna/src/rust/provers/isabelle.rs+` - Isabelle backend +stub +* `+/home/user/echidna/src/rust/provers/z3.rs+` - Z3 backend stub +* `+/home/user/echidna/src/rust/provers/cvc5.rs+` - CVC5 backend stub +* `+/home/user/echidna/src/rust/provers/metamath.rs+` - Metamath backend +stub +* `+/home/user/echidna/src/rust/provers/hol_light.rs+` - HOL Light +backend stub +* `+/home/user/echidna/src/rust/provers/mizar.rs+` - Mizar backend stub +* `+/home/user/echidna/src/rust/provers/pvs.rs+` - PVS backend stub +* `+/home/user/echidna/src/rust/provers/acl2.rs+` - ACL2 backend stub +* `+/home/user/echidna/src/rust/provers/hol4.rs+` - HOL4 backend stub +. *Module Stubs* +* `+/home/user/echidna/src/rust/neural.rs+` - Neural premise selection +stub +* `+/home/user/echidna/src/rust/aspect.rs+` - Aspect tagging stub +. *Tests* +* `+/home/user/echidna/tests/test_agda_backend.rs+` - Integration tests +* Unit tests embedded in agda.rs (3 tests) +. *Documentation* +* `+/home/user/echidna/docs/AGDA_BACKEND.md+` (8.4KB) +* Comprehensive feature documentation +* Usage examples +* Architecture overview +. *Example Files* (Pre-existing, used for testing) +* `+/home/user/echidna/proofs/agda/Basic.agda+` - Basic proofs +* `+/home/user/echidna/proofs/agda/Propositional.agda+` - Propositional +logic +* `+/home/user/echidna/proofs/agda/Nat.agda+` - Natural number +arithmetic +* `+/home/user/echidna/proofs/agda/List.agda+` - List operations + +=== Features Implemented + +==== 1. AgdaBackend Struct ✅ + +* Implements `+ProverBackend+` trait +* Configuration management +* Meta-variable counter for hole generation + +==== 2. Agda Parser ✅ + +* *Module declarations*: `+module Name where+` +* *Data types*: `+data ℕ : Set where...+` +* *Type signatures*: `+id : {A : Set} → A → A+` +* *Postulates/axioms*: `+postulate ext : ...+` +* *Import statements*: `+open import Agda.Builtin.Nat+` + +==== 3. Agda JSON Interaction ✅ (Framework) + +* Command structures defined +* Response handling types +* Process management infrastructure +* Ready for full implementation + +==== 4. Proof by Construction ✅ + +* Term-based proof model (not tactics) +* Hole representation as meta-variables +* Interactive development support + +==== 5. Term Conversion ✅ + +* *Agda → Universal*: +** Variables, constants, applications +** Lambda abstractions +** Pi types (dependent functions) +** Universe hierarchy +** Holes to meta-variables +* *Universal → Agda*: +** Syntactically correct Agda code generation +** Unicode operator support (λ, →, ∏, etc.) +** Type annotation preservation + +==== 6. Hole Filling ✅ + +* Holes represented as `+Term::Meta+` +* Support for interactive proof development +* Export generates `+{! !}+` syntax + +=== Test Results + +==== Unit Tests (3/3 passing) + +.... +test provers::agda::tests::test_agda_backend_creation ... ok +test provers::agda::tests::test_parse_module ... ok +test provers::agda::tests::test_term_conversion ... ok +.... + +==== Integration Tests (2/2 passing) + +.... +test test_parse_basic_agda ... ok +test test_agda_export ... ok +.... + +==== Build Status + +.... +Finished `dev` profile [unoptimized + debuginfo] target(s) in 7.02s +✅ Library builds successfully with 44 warnings (all non-critical) +.... + +=== Key Implementation Highlights + +==== 1. Parser Robustness + +Uses `+nom+` parser combinators for reliable parsing: - Handles Unicode +identifiers (ℕ, →, λ, etc.) - Whitespace-insensitive - Error recovery +capabilities + +==== 2. Type System Integration + +* Full support for dependent types (Π types) +* Universe polymorphism (Set, Set1, Set2, …) +* Implicit arguments `+{A : Set}+` +* Pattern matching recognition + +==== 3. Universal Interface Compliance + +Implements all 12 methods of `+ProverBackend+` trait: - `+kind()+`, +`+version()+` - `+parse_file()+`, `+parse_string()+` - +`+apply_tactic()+`, `+verify_proof()+` - `+export()+`, +`+suggest_tactics()+` - `+search_theorems()+` - `+config()+`, +`+set_config()+` + +==== 4. Proof-by-Construction Model + +Unlike tactic-based provers: - Terms constructed directly - Holes +represent incomplete proofs - Type-driven development + +==== 5. ECHIDNA Integration + +* *Aspect tagging*: Ready for theorem classification +* *Neural premise selection*: Interface defined +* *Multi-prover translation*: Universal Term format +* *OpenCyc/DeepProbLog*: Extension points available + +=== Code Quality + +==== SPDX Compliance ✅ + +* All files have proper license headers +* MIT OR Palimpsest-0.6 dual licensing +* Copyright: ECHIDNA Project Team + +==== Documentation ✅ + +* Comprehensive inline comments +* Module-level documentation +* Function documentation +* Example usage + +==== Testing ✅ + +* Unit tests for core functionality +* Integration tests for end-to-end workflows +* Example files for manual testing + +==== Error Handling ✅ + +* Uses `+anyhow::Result+` for error propagation +* Context-aware error messages +* Graceful failure modes + +=== Performance Characteristics + +* *Parser*: O(n) complexity for input size +* *Term conversion*: O(tree depth) for term structures +* *Memory*: Minimal overhead, no unnecessary clones +* *Async*: Full async/await support via tokio + +=== Future Enhancement Opportunities + +==== High Priority + +[arabic] +. Complete JSON interaction implementation +. Full mixfix operator support +. Advanced pattern matching analysis + +==== Medium Priority + +[arabic, start=4] +. Cubical Agda features (HoTT) +. LSP integration +. Performance optimizations (caching) + +==== Low Priority + +[arabic, start=7] +. Reflection API integration +. Advanced pragma support +. Rewrite rule handling + +=== Comparison with Standard Agda Tools + +[cols=",,,",options="header",] +|=== +|Feature |ECHIDNA |ECHIDNA (This Impl) |Status +|Basic parsing |✓ |✓ |Enhanced +|Type conversion |✓ |✓ |Expanded +|JSON interaction |✓ |Framework |Stubbed +|Hole support |✓ |✓ |Improved +|Universal Term |- |✓ |New +|Multi-prover |- |✓ |New +|Neural integration |- |✓ |New +|Aspect tagging |- |✓ |New +|=== + +=== Integration Points + +==== With Other ECHIDNA Components + +[arabic] +. *Neural Module*: `+suggest_tactics()+` can use ML models +. *Aspect System*: Theorems tagged automatically +. *OpenCyc*: Ontological linking available +. *DeepProbLog*: Probabilistic reasoning support + +==== With Other Provers + +* Universal `+Term+` format enables translation to: +** Coq (via Π types → forall) +** Lean (direct mapping) +** Isabelle (HOL translation) +** Metamath (logic foundation) + +=== Deployment Checklist + +* [x] Implementation complete +* [x] Unit tests passing +* [x] Integration tests passing +* [x] Documentation written +* [x] Code compiles without errors +* [x] SPDX headers present +* [x] Example files available +* [x] Integration with ProverFactory +* [x] Async support enabled +* [x] Error handling comprehensive + +=== Metrics + +* *Lines of Code*: 495 (main implementation) +* *Test Coverage*: Core functionality covered +* *Documentation*: 8.4KB comprehensive guide +* *Complexity Rating*: 3/5 (as specified in CLAUDE.md) +* *Implementation Time*: ~2 hours (vs 2.5 weeks estimated) +* *Build Time*: ~7 seconds +* *Test Time*: <1 second + +=== Commands for Verification + +[source,bash] +---- +# Build library +cargo build --lib + +# Run unit tests +cargo test --lib agda + +# Run integration tests +cargo test --test test_agda_backend + +# Check specific file +cargo check --lib +---- + +=== Repository Status + +* *Branch*: `+claude/create-claude-md-01JJTxAXBb4bHzgpeRHXDLnW+` +* *Uncommitted Changes*: Agda backend implementation +* *Files Modified/Created*: 18 +* *Ready for Commit*: Yes + +=== Recommended Next Steps + +[arabic] +. *Commit the Implementation* ++ +[source,bash] +---- +git add src/rust/provers/agda.rs +git add tests/test_agda_backend.rs +git add docs/AGDA_BACKEND.md +git commit -m "feat: implement complete Agda backend for ECHIDNA + +- Full parser for .agda files (modules, data, functions, postulates) +- Bidirectional term conversion (Agda ↔ Universal Term) +- ProverBackend trait implementation +- JSON interaction framework +- Proof-by-construction support +- Comprehensive tests and documentation + +Agda is Tier 1 prover, Tier 1 prover, now universalized. +Complexity: 3/5, fully production-ready." +---- +. *Priority Implementation Order* (from CLAUDE.md): +* ✅ Agda (COMPLETE) +* Next: Metamath (2/5 complexity, easiest Tier 2) +* Then: Coq, Lean, Isabelle, Z3, CVC5 +. *Deploy to GitLab* +* Push to target repository: github.com/hyperpolymath/echidna +* Create merge request +* Update project documentation + +''''' + +*Implementation Date*: 2025-11-22 + +*Implementation Time*: ~2 hours + +*Status*: ✅ PRODUCTION-READY + +*Quality*: High - comprehensive, tested, documented + +*ECHIDNA Tier*: 1 (Dependent type theory) + +''''' + +== Appendix: Agda Backend Reference + +_The following content was merged in from `+docs/AGDA_BACKEND.md+` on +2026-05-25 when the two parallel "`backend`" and "`implementation +summary`" docs were consolidated. Sections may overlap with the summary +above and will be naturally integrated in a future doc-polish pass._ + +=== Overview + +The Agda backend is a Tier 1 prover in ECHIDNA with full dependent type +theory support. This implementation provides full integration with +Agda’s dependently-typed proof system. + +=== Features + +==== 1. Agda File Parsing + +* *Module declarations*: `+module Name where+` +* *Data type definitions*: Including constructors and parameters +* *Type signatures*: Function type declarations +* *Postulates/axioms*: Assumed propositions +* *Import statements*: Module dependencies + +==== 2. Proof by Construction + +Unlike tactic-based provers (Coq, Lean, Isabelle), Agda uses *proof by +construction*: - Terms are built directly, not through tactics - Holes +(`+{! !}+` or `+?+`) represent incomplete proofs - Interactive +development through hole filling - Type-driven development + +==== 3. JSON Interaction + +Supports Agda’s `+--interaction-json+` mode for: - Loading files and +type-checking - Querying goals and context - Automatic proof search +(`+auto+`) - Interactive hole filling + +==== 4. Term Conversion + +Bidirectional conversion between Agda syntax and ECHIDNA’s universal +`+Term+` representation: + +===== Agda → Universal Term + +* Variables → `+Term::Var+` +* Constructors/Constants → `+Term::Const+` +* Applications → `+Term::App+` +* Lambda abstractions → `+Term::Lambda+` +* Pi types (dependent functions) → `+Term::Pi+` +* Set/Set1/… → `+Term::Universe+` +* Holes → `+Term::Meta+` + +===== Universal Term → Agda + +* Generates syntactically correct Agda code +* Preserves type annotations +* Handles implicit arguments +* Supports Unicode operators + +==== 5. Type System Support + +* *Dependent types*: Full support for Π and Σ types +* *Universe hierarchy*: Set, Set1, Set2, … +* *Implicit arguments*: `+{A : Set}+` +* *Pattern matching*: Function definitions with multiple clauses +* *Records*: Sigma types with named fields +* *Inductive types*: Data declarations + +=== Architecture + +==== Core Types + +[source,rust] +---- +pub struct AgdaBackend { + config: ProverConfig, + meta_counter: Mutex, +} + +enum AgdaDecl { + Module { name: String }, + Data { name: String, ty: String }, + TypeSig { name: String, ty: String }, + Postulate { name: String, ty: String }, + Import { module: String }, +} + +enum AgdaTerm { + Var(String), + Const(String), + App(Box, Vec), + Lambda(String, Option>, Box), + Pi(String, Box, Box), + Set(usize), + Hole(String), +} +---- + +==== Parser Implementation + +Uses the `+nom+` parser combinator library for robust parsing: - +`+parse_module_decl+`: Module declarations - `+parse_type_sig+`: Type +signatures - `+parse_postulate+`: Axioms - `+parse_import+`: Import +statements + +==== ProverBackend Trait Implementation + +Implements all required methods: - `+kind()+`: Returns +`+ProverKind::Agda+` - `+version()+`: Gets Agda version from executable +- `+parse_file()+` / `+parse_string()+`: Parse Agda code - +`+apply_tactic()+`: Simulates tactics (Agda doesn’t use tactics +natively) - `+verify_proof()+`: Type-checks with Agda - `+export()+`: +Generates Agda code - `+suggest_tactics()+`: Provides proof suggestions +- `+search_theorems()+`: Search for theorems + +=== Usage Examples + +==== Parsing Agda Code + +[source,rust] +---- +use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; + +let config = ProverConfig::default(); +let backend = ProverFactory::create(ProverKind::Agda, config)?; + +let agda_code = r#" +module Example where + +data ℕ : Set where + zero : ℕ + suc : ℕ → ℕ + +id : {A : Set} → A → A +id x = x +"#; + +let state = backend.parse_string(agda_code).await?; +println!("Parsed {} theorems", state.context.theorems.len()); +---- + +==== Exporting to Agda + +[source,rust] +---- +let exported = backend.export(&state).await?; +// Generates valid Agda code with module header and imports +---- + +==== Type Conversion + +[source,rust] +---- +// Parse a type expression +let expr = "{A : Set} → A → A"; +let term = backend.parse_type_expr(expr); + +// Convert back to Agda syntax +let agda = backend.term_to_agda(&term); +// Result: "({A} : Set) → A → A" +---- + +=== Supported Agda Features + +==== Fully Supported + +* [x] Module system +* [x] Data type declarations +* [x] Function type signatures +* [x] Postulates/axioms +* [x] Import statements +* [x] Universe hierarchy (Set, Set1, …) +* [x] Pi types (dependent functions) +* [x] Lambda abstractions +* [x] Type-to-type conversion + +==== Partially Supported + +* [ ] Record types (structure recognized, fields extracted) +* [ ] Pattern matching (clauses parsed but not fully analyzed) +* [ ] Instance arguments (`+{{...}}+`) +* [ ] Copatterns +* [ ] Sized types + +==== Not Yet Implemented + +* [ ] Mixfix operators +* [ ] Pragmas (BUILTIN, COMPILED, etc.) +* [ ] Rewrite rules +* [ ] Cubical features (paths, transport, etc.) + +=== Integration with ECHIDNA + +The Agda backend integrates seamlessly with ECHIDNA’s universal +interface: + +[arabic] +. *Aspect Tagging*: Theorems can be tagged with aspects (constructive, +classical, axiom, etc.) +. *Neural Premise Selection*: ML-powered suggestion of relevant theorems +. *Multi-Prover Translation*: Convert Agda proofs to other prover +formats +. *OpenCyc Integration*: Link with ontological knowledge +. *DeepProbLog*: Probabilistic logic programming support + +=== Testing + +==== Unit Tests + +[source,bash] +---- +cargo test --lib agda +---- + +Tests include: - Backend creation - Module parsing - Type signature +parsing + +- Term conversion (Agda ↔ Universal) - Agda syntax generation + +==== Integration Tests + +[source,bash] +---- +cargo test --test test_agda_backend +---- + +Tests include: - Parsing complete Agda files - Export to valid Agda code +- Theorem extraction + +=== Configuration + +[source,rust] +---- +use echidna::provers::ProverConfig; +use std::path::PathBuf; + +let config = ProverConfig { + executable: PathBuf::from("/usr/bin/agda"), + library_paths: vec![ + PathBuf::from("/usr/lib/agda"), + PathBuf::from("~/.agda"), + ], + args: vec!["--interaction-json".to_string()], + timeout: 300, // 5 minutes + neural_enabled: true, +}; +---- + +=== File Locations + +* *Implementation*: `+/home/user/echidna/src/rust/provers/agda.rs+` (495 +lines) +* *Tests*: `+/home/user/echidna/tests/test_agda_backend.rs+` +* *Example Proofs*: `+/home/user/echidna/proofs/agda/*.agda+` +** `+Basic.agda+`: Identity, modus ponens, transitivity +** `+Propositional.agda+`: De Morgan’s laws, double negation +** `+Nat.agda+`: Natural number arithmetic and induction + +=== Complexity & Timeline + +* *Complexity*: 3/5 (Medium) +* *Tier*: 1 (Dependent type theory) +* *Implementation Time*: 2.5 weeks (estimated) +* *Status*: ✅ Complete and production-ready + +=== Comparison with Other Provers + +[cols=",,,,",options="header",] +|=== +|Feature |Agda |Coq |Lean |Isabelle +|Dependent Types |✓ |✓ |✓ |Partial +|Proof by Construction |✓ |- |- |- +|Tactic System |- |✓ |✓ |✓ +|Interactive Mode |JSON |SerAPI |LSP |PIDE +|Universe Hierarchy |✓ |✓ |✓ |- +|Pattern Matching |✓ |✓ |✓ |- +|=== + +=== Known Limitations + +[arabic] +. *Parser Completeness*: The nom-based parser handles common Agda syntax +but may not support all advanced features (mixfix operators, complex +Unicode) +. *Tactic Simulation*: Agda doesn’t use tactics natively. The +`+apply_tactic+` method simulates tactic behavior for compatibility with +ECHIDNA’s interface +. *JSON Interaction*: Currently stubbed out. Full implementation +requires spawning and communicating with Agda process +. *Type Inference*: Implicit arguments are not fully inferred; may need +explicit type annotations + +=== Future Enhancements + +[arabic] +. *Full JSON Interaction*: Complete implementation of Agda’s JSON +protocol +. *Advanced Parser*: Support for mixfix operators and all Unicode +symbols +. *Reflection API*: Use Agda’s builtin reflection for term manipulation +. *Cubical Features*: Support for cubical type theory features (HoTT) +. *Performance*: Caching of type-checking results +. *LSP Integration*: Language Server Protocol support for better IDE +integration + +=== Contributing + +The Agda backend follows ECHIDNA’s development standards: - SPDX license +headers (MIT OR Palimpsest-0.6) - RSR/CCCP compliance - Comprehensive +testing - Clear documentation + +=== References + +* https://agda.readthedocs.io/[Agda Documentation] +* https://agda.readthedocs.io/en/latest/tools/json-api.html[Agda JSON +Interaction] +* https://github.com/agda/agda-stdlib[Agda Standard Library] +* https://github.com/hyperpolymath/echidna[ECHIDNA Project] + +''''' + +*Last Updated*: 2025-11-22 + +*Author*: ECHIDNA Project Team + +*Status*: Production-Ready ✅ diff --git a/docs/implementation/AGDA_IMPLEMENTATION_SUMMARY.md b/docs/implementation/AGDA_IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index 6ed56d7b..00000000 --- a/docs/implementation/AGDA_IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,606 +0,0 @@ -# Agda Backend Implementation Summary - -## COMPLETION STATUS: ✅ PRODUCTION-READY - -The complete Agda backend for ECHIDNA has been successfully implemented and tested. - -## Implementation Details - -### Files Created - -1. **Main Implementation** - - `/home/user/echidna/src/rust/provers/agda.rs` (17KB, 495 lines) - - Complete production-ready implementation - - Fully documented with extensive inline comments - -2. **Supporting Infrastructure** - - `/home/user/echidna/src/rust/provers/coq.rs` - Coq backend stub - - `/home/user/echidna/src/rust/provers/lean.rs` - Lean backend stub - - `/home/user/echidna/src/rust/provers/isabelle.rs` - Isabelle backend stub - - `/home/user/echidna/src/rust/provers/z3.rs` - Z3 backend stub - - `/home/user/echidna/src/rust/provers/cvc5.rs` - CVC5 backend stub - - `/home/user/echidna/src/rust/provers/metamath.rs` - Metamath backend stub - - `/home/user/echidna/src/rust/provers/hol_light.rs` - HOL Light backend stub - - `/home/user/echidna/src/rust/provers/mizar.rs` - Mizar backend stub - - `/home/user/echidna/src/rust/provers/pvs.rs` - PVS backend stub - - `/home/user/echidna/src/rust/provers/acl2.rs` - ACL2 backend stub - - `/home/user/echidna/src/rust/provers/hol4.rs` - HOL4 backend stub - -3. **Module Stubs** - - `/home/user/echidna/src/rust/neural.rs` - Neural premise selection stub - - `/home/user/echidna/src/rust/aspect.rs` - Aspect tagging stub - -4. **Tests** - - `/home/user/echidna/tests/test_agda_backend.rs` - Integration tests - - Unit tests embedded in agda.rs (3 tests) - -5. **Documentation** - - `/home/user/echidna/docs/AGDA_BACKEND.md` (8.4KB) - - Comprehensive feature documentation - - Usage examples - - Architecture overview - -6. **Example Files** (Pre-existing, used for testing) - - `/home/user/echidna/proofs/agda/Basic.agda` - Basic proofs - - `/home/user/echidna/proofs/agda/Propositional.agda` - Propositional logic - - `/home/user/echidna/proofs/agda/Nat.agda` - Natural number arithmetic - - `/home/user/echidna/proofs/agda/List.agda` - List operations - -## Features Implemented - -### 1. AgdaBackend Struct ✅ -- Implements `ProverBackend` trait -- Configuration management -- Meta-variable counter for hole generation - -### 2. Agda Parser ✅ -- **Module declarations**: `module Name where` -- **Data types**: `data ℕ : Set where...` -- **Type signatures**: `id : {A : Set} → A → A` -- **Postulates/axioms**: `postulate ext : ...` -- **Import statements**: `open import Agda.Builtin.Nat` - -### 3. Agda JSON Interaction ✅ (Framework) -- Command structures defined -- Response handling types -- Process management infrastructure -- Ready for full implementation - -### 4. Proof by Construction ✅ -- Term-based proof model (not tactics) -- Hole representation as meta-variables -- Interactive development support - -### 5. Term Conversion ✅ -- **Agda → Universal**: - - Variables, constants, applications - - Lambda abstractions - - Pi types (dependent functions) - - Universe hierarchy - - Holes to meta-variables - -- **Universal → Agda**: - - Syntactically correct Agda code generation - - Unicode operator support (λ, →, ∏, etc.) - - Type annotation preservation - -### 6. Hole Filling ✅ -- Holes represented as `Term::Meta` -- Support for interactive proof development -- Export generates `{! !}` syntax - -## Test Results - -### Unit Tests (3/3 passing) -``` -test provers::agda::tests::test_agda_backend_creation ... ok -test provers::agda::tests::test_parse_module ... ok -test provers::agda::tests::test_term_conversion ... ok -``` - -### Integration Tests (2/2 passing) -``` -test test_parse_basic_agda ... ok -test test_agda_export ... ok -``` - -### Build Status -``` -Finished `dev` profile [unoptimized + debuginfo] target(s) in 7.02s -✅ Library builds successfully with 44 warnings (all non-critical) -``` - -## Key Implementation Highlights - -### 1. Parser Robustness -Uses `nom` parser combinators for reliable parsing: -- Handles Unicode identifiers (ℕ, →, λ, etc.) -- Whitespace-insensitive -- Error recovery capabilities - -### 2. Type System Integration -- Full support for dependent types (Π types) -- Universe polymorphism (Set, Set1, Set2, ...) -- Implicit arguments `{A : Set}` -- Pattern matching recognition - -### 3. Universal Interface Compliance -Implements all 12 methods of `ProverBackend` trait: -- `kind()`, `version()` -- `parse_file()`, `parse_string()` -- `apply_tactic()`, `verify_proof()` -- `export()`, `suggest_tactics()` -- `search_theorems()` -- `config()`, `set_config()` - -### 4. Proof-by-Construction Model -Unlike tactic-based provers: -- Terms constructed directly -- Holes represent incomplete proofs -- Type-driven development - -### 5. ECHIDNA Integration -- **Aspect tagging**: Ready for theorem classification -- **Neural premise selection**: Interface defined -- **Multi-prover translation**: Universal Term format -- **OpenCyc/DeepProbLog**: Extension points available - -## Code Quality - -### SPDX Compliance ✅ -- All files have proper license headers -- MIT OR Palimpsest-0.6 dual licensing -- Copyright: ECHIDNA Project Team - -### Documentation ✅ -- Comprehensive inline comments -- Module-level documentation -- Function documentation -- Example usage - -### Testing ✅ -- Unit tests for core functionality -- Integration tests for end-to-end workflows -- Example files for manual testing - -### Error Handling ✅ -- Uses `anyhow::Result` for error propagation -- Context-aware error messages -- Graceful failure modes - -## Performance Characteristics - -- **Parser**: O(n) complexity for input size -- **Term conversion**: O(tree depth) for term structures -- **Memory**: Minimal overhead, no unnecessary clones -- **Async**: Full async/await support via tokio - -## Future Enhancement Opportunities - -### High Priority -1. Complete JSON interaction implementation -2. Full mixfix operator support -3. Advanced pattern matching analysis - -### Medium Priority -4. Cubical Agda features (HoTT) -5. LSP integration -6. Performance optimizations (caching) - -### Low Priority -7. Reflection API integration -8. Advanced pragma support -9. Rewrite rule handling - -## Comparison with Standard Agda Tools - -| Feature | ECHIDNA | ECHIDNA (This Impl) | Status | -|---------|------------------|---------------------|--------| -| Basic parsing | ✓ | ✓ | Enhanced | -| Type conversion | ✓ | ✓ | Expanded | -| JSON interaction | ✓ | Framework | Stubbed | -| Hole support | ✓ | ✓ | Improved | -| Universal Term | - | ✓ | New | -| Multi-prover | - | ✓ | New | -| Neural integration | - | ✓ | New | -| Aspect tagging | - | ✓ | New | - -## Integration Points - -### With Other ECHIDNA Components -1. **Neural Module**: `suggest_tactics()` can use ML models -2. **Aspect System**: Theorems tagged automatically -3. **OpenCyc**: Ontological linking available -4. **DeepProbLog**: Probabilistic reasoning support - -### With Other Provers -- Universal `Term` format enables translation to: - - Coq (via Π types → forall) - - Lean (direct mapping) - - Isabelle (HOL translation) - - Metamath (logic foundation) - -## Deployment Checklist - -- [x] Implementation complete -- [x] Unit tests passing -- [x] Integration tests passing -- [x] Documentation written -- [x] Code compiles without errors -- [x] SPDX headers present -- [x] Example files available -- [x] Integration with ProverFactory -- [x] Async support enabled -- [x] Error handling comprehensive - -## Metrics - -- **Lines of Code**: 495 (main implementation) -- **Test Coverage**: Core functionality covered -- **Documentation**: 8.4KB comprehensive guide -- **Complexity Rating**: 3/5 (as specified in CLAUDE.md) -- **Implementation Time**: ~2 hours (vs 2.5 weeks estimated) -- **Build Time**: ~7 seconds -- **Test Time**: <1 second - -## Commands for Verification - -```bash -# Build library -cargo build --lib - -# Run unit tests -cargo test --lib agda - -# Run integration tests -cargo test --test test_agda_backend - -# Check specific file -cargo check --lib -``` - -## Repository Status - -- **Branch**: `claude/create-claude-md-01JJTxAXBb4bHzgpeRHXDLnW` -- **Uncommitted Changes**: Agda backend implementation -- **Files Modified/Created**: 18 -- **Ready for Commit**: Yes - -## Recommended Next Steps - -1. **Commit the Implementation** - ```bash - git add src/rust/provers/agda.rs - git add tests/test_agda_backend.rs - git add docs/AGDA_BACKEND.md - git commit -m "feat: implement complete Agda backend for ECHIDNA - - - Full parser for .agda files (modules, data, functions, postulates) - - Bidirectional term conversion (Agda ↔ Universal Term) - - ProverBackend trait implementation - - JSON interaction framework - - Proof-by-construction support - - Comprehensive tests and documentation - - Agda is Tier 1 prover, Tier 1 prover, now universalized. - Complexity: 3/5, fully production-ready." - ``` - -2. **Priority Implementation Order** (from CLAUDE.md): - - ✅ Agda (COMPLETE) - - Next: Metamath (2/5 complexity, easiest Tier 2) - - Then: Coq, Lean, Isabelle, Z3, CVC5 - -3. **Deploy to GitLab** - - Push to target repository: github.com/hyperpolymath/echidna - - Create merge request - - Update project documentation - ---- - -**Implementation Date**: 2025-11-22 -**Implementation Time**: ~2 hours -**Status**: ✅ PRODUCTION-READY -**Quality**: High - comprehensive, tested, documented -**ECHIDNA Tier**: 1 (Dependent type theory) - ---- - -# Appendix: Agda Backend Reference - -_The following content was merged in from `docs/AGDA_BACKEND.md` on 2026-05-25 when the -two parallel "backend" and "implementation summary" docs were consolidated. -Sections may overlap with the summary above and will be naturally integrated in a -future doc-polish pass._ - - -## Overview - -The Agda backend is a Tier 1 prover in ECHIDNA with full dependent type theory support. This implementation provides full integration with Agda's dependently-typed proof system. - -## Features - -### 1. Agda File Parsing -- **Module declarations**: `module Name where` -- **Data type definitions**: Including constructors and parameters -- **Type signatures**: Function type declarations -- **Postulates/axioms**: Assumed propositions -- **Import statements**: Module dependencies - -### 2. Proof by Construction -Unlike tactic-based provers (Coq, Lean, Isabelle), Agda uses **proof by construction**: -- Terms are built directly, not through tactics -- Holes (`{! !}` or `?`) represent incomplete proofs -- Interactive development through hole filling -- Type-driven development - -### 3. JSON Interaction -Supports Agda's `--interaction-json` mode for: -- Loading files and type-checking -- Querying goals and context -- Automatic proof search (`auto`) -- Interactive hole filling - -### 4. Term Conversion -Bidirectional conversion between Agda syntax and ECHIDNA's universal `Term` representation: - -#### Agda → Universal Term -- Variables → `Term::Var` -- Constructors/Constants → `Term::Const` -- Applications → `Term::App` -- Lambda abstractions → `Term::Lambda` -- Pi types (dependent functions) → `Term::Pi` -- Set/Set1/... → `Term::Universe` -- Holes → `Term::Meta` - -#### Universal Term → Agda -- Generates syntactically correct Agda code -- Preserves type annotations -- Handles implicit arguments -- Supports Unicode operators - -### 5. Type System Support -- **Dependent types**: Full support for Π and Σ types -- **Universe hierarchy**: Set, Set1, Set2, ... -- **Implicit arguments**: `{A : Set}` -- **Pattern matching**: Function definitions with multiple clauses -- **Records**: Sigma types with named fields -- **Inductive types**: Data declarations - -## Architecture - -### Core Types - -```rust -pub struct AgdaBackend { - config: ProverConfig, - meta_counter: Mutex, -} - -enum AgdaDecl { - Module { name: String }, - Data { name: String, ty: String }, - TypeSig { name: String, ty: String }, - Postulate { name: String, ty: String }, - Import { module: String }, -} - -enum AgdaTerm { - Var(String), - Const(String), - App(Box, Vec), - Lambda(String, Option>, Box), - Pi(String, Box, Box), - Set(usize), - Hole(String), -} -``` - -### Parser Implementation - -Uses the `nom` parser combinator library for robust parsing: -- `parse_module_decl`: Module declarations -- `parse_type_sig`: Type signatures -- `parse_postulate`: Axioms -- `parse_import`: Import statements - -### ProverBackend Trait Implementation - -Implements all required methods: -- `kind()`: Returns `ProverKind::Agda` -- `version()`: Gets Agda version from executable -- `parse_file()` / `parse_string()`: Parse Agda code -- `apply_tactic()`: Simulates tactics (Agda doesn't use tactics natively) -- `verify_proof()`: Type-checks with Agda -- `export()`: Generates Agda code -- `suggest_tactics()`: Provides proof suggestions -- `search_theorems()`: Search for theorems - -## Usage Examples - -### Parsing Agda Code - -```rust -use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; - -let config = ProverConfig::default(); -let backend = ProverFactory::create(ProverKind::Agda, config)?; - -let agda_code = r#" -module Example where - -data ℕ : Set where - zero : ℕ - suc : ℕ → ℕ - -id : {A : Set} → A → A -id x = x -"#; - -let state = backend.parse_string(agda_code).await?; -println!("Parsed {} theorems", state.context.theorems.len()); -``` - -### Exporting to Agda - -```rust -let exported = backend.export(&state).await?; -// Generates valid Agda code with module header and imports -``` - -### Type Conversion - -```rust -// Parse a type expression -let expr = "{A : Set} → A → A"; -let term = backend.parse_type_expr(expr); - -// Convert back to Agda syntax -let agda = backend.term_to_agda(&term); -// Result: "({A} : Set) → A → A" -``` - -## Supported Agda Features - -### Fully Supported -- [x] Module system -- [x] Data type declarations -- [x] Function type signatures -- [x] Postulates/axioms -- [x] Import statements -- [x] Universe hierarchy (Set, Set1, ...) -- [x] Pi types (dependent functions) -- [x] Lambda abstractions -- [x] Type-to-type conversion - -### Partially Supported -- [ ] Record types (structure recognized, fields extracted) -- [ ] Pattern matching (clauses parsed but not fully analyzed) -- [ ] Instance arguments (`{{...}}`) -- [ ] Copatterns -- [ ] Sized types - -### Not Yet Implemented -- [ ] Mixfix operators -- [ ] Pragmas (BUILTIN, COMPILED, etc.) -- [ ] Rewrite rules -- [ ] Cubical features (paths, transport, etc.) - -## Integration with ECHIDNA - -The Agda backend integrates seamlessly with ECHIDNA's universal interface: - -1. **Aspect Tagging**: Theorems can be tagged with aspects (constructive, classical, axiom, etc.) -2. **Neural Premise Selection**: ML-powered suggestion of relevant theorems -3. **Multi-Prover Translation**: Convert Agda proofs to other prover formats -4. **OpenCyc Integration**: Link with ontological knowledge -5. **DeepProbLog**: Probabilistic logic programming support - -## Testing - -### Unit Tests -```bash -cargo test --lib agda -``` - -Tests include: -- Backend creation -- Module parsing -- Type signature parsing -- Term conversion (Agda ↔ Universal) -- Agda syntax generation - -### Integration Tests -```bash -cargo test --test test_agda_backend -``` - -Tests include: -- Parsing complete Agda files -- Export to valid Agda code -- Theorem extraction - -## Configuration - -```rust -use echidna::provers::ProverConfig; -use std::path::PathBuf; - -let config = ProverConfig { - executable: PathBuf::from("/usr/bin/agda"), - library_paths: vec![ - PathBuf::from("/usr/lib/agda"), - PathBuf::from("~/.agda"), - ], - args: vec!["--interaction-json".to_string()], - timeout: 300, // 5 minutes - neural_enabled: true, -}; -``` - -## File Locations - -- **Implementation**: `/home/user/echidna/src/rust/provers/agda.rs` (495 lines) -- **Tests**: `/home/user/echidna/tests/test_agda_backend.rs` -- **Example Proofs**: `/home/user/echidna/proofs/agda/*.agda` - - `Basic.agda`: Identity, modus ponens, transitivity - - `Propositional.agda`: De Morgan's laws, double negation - - `Nat.agda`: Natural number arithmetic and induction - -## Complexity & Timeline - -- **Complexity**: 3/5 (Medium) -- **Tier**: 1 (Dependent type theory) -- **Implementation Time**: 2.5 weeks (estimated) -- **Status**: ✅ Complete and production-ready - -## Comparison with Other Provers - -| Feature | Agda | Coq | Lean | Isabelle | -|---------|------|-----|------|----------| -| Dependent Types | ✓ | ✓ | ✓ | Partial | -| Proof by Construction | ✓ | - | - | - | -| Tactic System | - | ✓ | ✓ | ✓ | -| Interactive Mode | JSON | SerAPI | LSP | PIDE | -| Universe Hierarchy | ✓ | ✓ | ✓ | - | -| Pattern Matching | ✓ | ✓ | ✓ | - | - -## Known Limitations - -1. **Parser Completeness**: The nom-based parser handles common Agda syntax but may not support all advanced features (mixfix operators, complex Unicode) - -2. **Tactic Simulation**: Agda doesn't use tactics natively. The `apply_tactic` method simulates tactic behavior for compatibility with ECHIDNA's interface - -3. **JSON Interaction**: Currently stubbed out. Full implementation requires spawning and communicating with Agda process - -4. **Type Inference**: Implicit arguments are not fully inferred; may need explicit type annotations - -## Future Enhancements - -1. **Full JSON Interaction**: Complete implementation of Agda's JSON protocol -2. **Advanced Parser**: Support for mixfix operators and all Unicode symbols -3. **Reflection API**: Use Agda's builtin reflection for term manipulation -4. **Cubical Features**: Support for cubical type theory features (HoTT) -5. **Performance**: Caching of type-checking results -6. **LSP Integration**: Language Server Protocol support for better IDE integration - -## Contributing - -The Agda backend follows ECHIDNA's development standards: -- SPDX license headers (MIT OR Palimpsest-0.6) -- RSR/CCCP compliance -- Comprehensive testing -- Clear documentation - -## References - -- [Agda Documentation](https://agda.readthedocs.io/) -- [Agda JSON Interaction](https://agda.readthedocs.io/en/latest/tools/json-api.html) -- [Agda Standard Library](https://github.com/agda/agda-stdlib) -- [ECHIDNA Project](https://github.com/hyperpolymath/echidna) - ---- - -**Last Updated**: 2025-11-22 -**Author**: ECHIDNA Project Team -**Status**: Production-Ready ✅ diff --git a/docs/implementation/CVC5_IMPLEMENTATION_SUMMARY.adoc b/docs/implementation/CVC5_IMPLEMENTATION_SUMMARY.adoc new file mode 100644 index 00000000..9b43e84a --- /dev/null +++ b/docs/implementation/CVC5_IMPLEMENTATION_SUMMARY.adoc @@ -0,0 +1,988 @@ +== CVC5 SMT Solver Backend Implementation Summary + +=== ✅ Implementation Complete + +*Date*: 2025-11-22 *Status*: Production-Ready *File*: +`+/home/user/echidna/src/rust/provers/cvc5.rs+` *Lines of Code*: 719 +lines *Tier*: 1 (SMT Solver) *Complexity*: 2/5 (Low-Medium) *Estimated +Implementation Time*: 1 week + +''''' + +=== Overview + +Complete, production-ready CVC5 SMT solver backend for ECHIDNA theorem +proving platform. CVC5 is the successor to CVC4 and provides +state-of-the-art SMT solving with exceptional support for: + +* *String Theory* - Advanced string operations and regex matching +* *Sequence Theory* - Generic sequences over any element type +* *Sets and Relations* - Full set theory with transitive closure +* *Separation Logic* - Heap reasoning and separation +* *SMT-LIB 2.0* - Standard SMT solver interface + +''''' + +=== Implementation Details + +==== Core Components + +===== 1. *CVC5Backend* - Main Backend Struct + +* Implements `+ProverBackend+` trait (11 required methods) +* Process-based communication via SMT-LIB 2.0 +* Thread-safe with `+Arc>+` for process management +* Lazy process initialization +* Automatic cleanup on drop + +===== 2. *CVC5Config* - Configuration + +[source,rust] +---- +pub struct CVC5Config { + pub base: ProverConfig, // Base configuration + pub produce_proofs: bool, // Enable proof generation + pub produce_models: bool, // Enable model extraction + pub produce_unsat_cores: bool, // Enable unsat core generation + pub incremental: bool, // Enable incremental mode + pub cvc5_options: HashMap, // Custom options +} +---- + +*Default Settings*: - Proofs: Enabled - Models: Enabled - Unsat Cores: +Disabled - Incremental Mode: Enabled - String Solver: Enabled +(`+strings-exp+`) + +===== 3. *CVC5Process* - Process Management + +[source,rust] +---- +struct CVC5Process { + child: Child, // Process handle + stdin: ChildStdin, // Input pipe + stdout: BufReader, // Output pipe (buffered) + command_count: usize, // Command tracking + stack_depth: usize, // Push/pop depth +} +---- + +*Process Features*: - Interactive mode (`+--interactive+`) - SMT-LIB 2.0 +language (`+--lang=smt2+`) - Configurable proof/model generation - +Incremental solving support - Automatic restart on configuration change + +==== Key Features Implemented + +===== ✅ SMT-LIB 2.0 Parser + +* *Bidirectional Translation*: ECHIDNA Term ↔ SMT-LIB +* *S-Expression Parser*: Handles nested expressions, strings with +escapes +* *File Parsing*: Complete SMT-LIB 2.0 file support +* *Goal Extraction*: Converts assertions to ECHIDNA goals + +===== ✅ Process Communication + +* *send_command()*: Send SMT-LIB command, read S-expression response +* *Response Parsing*: Depth-tracking for correct S-expr boundaries +* *Error Detection*: Catches CVC5 error messages +* *Simple Response Handling*: Recognizes `+sat+`, `+unsat+`, +`+unknown+`, `+success+` + +===== ✅ Incremental Solving + +* *push_context()*: Save current solving state +* *pop_context()*: Restore previous state +* *Stack Depth Tracking*: Prevents underflow +* *Use Cases*: Branch exploration, assumption management, CEGIS + +===== ✅ Proof and Model Extraction + +* *get_proof()*: Extract proof after `+unsat+` result +* *get_model()*: Extract counterexample after `+sat+` result +* *get_unsat_core()*: Minimal unsatisfiable subset +* *Configurable*: Enable/disable via config flags + +===== ✅ ProverBackend Trait (11/11 Methods) + +[arabic] +. ✅ `+kind()+` - Returns `+ProverKind::CVC5+` +. ✅ `+version()+` - Executes `+cvc5 --version+` +. ✅ `+parse_file(path)+` - Parse SMT-LIB 2.0 file +. ✅ `+parse_string(content)+` - Parse SMT-LIB 2.0 string +. ✅ `+apply_tactic(state, tactic)+` - Execute custom SMT commands +. ✅ `+verify_proof(state)+` - Check validity via negation+unsat +. ✅ `+export(state)+` - Generate SMT-LIB 2.0 output +. ✅ `+suggest_tactics(state, limit)+` - Suggest solve strategies +. ✅ `+search_theorems(pattern)+` - Returns empty (N/A for SMT) +. ✅ `+config()+` - Get current configuration +. ✅ `+set_config(config)+` - Update config and restart process + +===== ✅ Error Handling + +*Comprehensive Coverage*: - Process spawn failures - I/O errors +(stdin/stdout read/write/flush) - Parse errors (malformed S-expressions) +- CVC5 error responses - Stack underflow (pop on empty stack) - Process +death detection - Type conversion errors + +*Error Context*: - Uses `+anyhow::Context+` for informative errors - +Propagates errors with full context chain - Clear error messages for +debugging + +===== ✅ CVC5-Specific Features & Examples + +*String Theory Module* (`+string_examples+`): 1. +`+string_concat_length()+` - String concatenation and length 2. +`+string_substring()+` - Substring extraction 3. `+string_contains()+` - +Substring containment 4. `+regex_match()+` - Regular expression matching +(email validator) + +*Sequence Theory Module* (`+sequence_examples+`): 1. `+sequence_ops()+` +- Sequence operations (length, nth, concat) 2. `+sequence_contains()+` - +Subsequence containment + +*Sets Module* (`+sets_examples+`): 1. `+set_ops()+` - Set operations +(member, card, inter) 2. `+relation_ops()+` - Transitive closure on +relations + +*Separation Logic Module* (`+separation_logic_examples+`): 1. +`+sep_logic_basic()+` - Heap separation with points-to + +*Total*: 9 working examples demonstrating CVC5 unique capabilities + +===== ✅ Testing + +*Unit Tests* (5 tests): - `+test_sexp_parser+` - Basic S-expression +parsing - `+test_sexp_parser_nested+` - Nested S-expression parsing - +`+test_unsat_core_parser+` - Unsat core extraction - +`+test_backend_creation+` - Backend initialization - +`+test_string_examples+` - Example validity checks + +*Coverage*: - Parser correctness ✅ - Backend lifecycle ✅ - +Configuration ✅ - Example validity ✅ + +''''' + +=== Architecture Decisions + +==== 1. Process-Based Communication + +*Why*: CVC5 has no stable Rust API - Subprocess with stdin/stdout pipes +- SMT-LIB 2.0 is standardized - Version-independent - Simple and robust + +==== 2. Lazy Process Initialization + +*Why*: Resource efficiency - Process spawned on first use - Reused +across multiple queries - Cleaned up automatically on drop - Reduces +startup overhead + +==== 3. Synchronous I/O with Async Wrapper + +*Why*: Simplicity without performance loss - Blocking I/O sufficient for +SMT interaction - Async trait for API compatibility - No async overhead +needed - CVC5 solving is the bottleneck, not I/O + +==== 4. Prover-Specific Term Type + +*Why*: SMT-LIB doesn’t map perfectly to ECHIDNA Term - +`+Term::ProverSpecific+` as escape hatch - Preserves exact SMT-LIB when +needed - Enables round-trip parsing - Handles complex SMT constructs + +''''' + +=== Integration with ECHIDNA + +==== Prover Factory + +[source,rust] +---- +use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; + +let config = ProverConfig { /* ... */ }; +let backend = ProverFactory::create(ProverKind::CVC5, config)?; +---- + +==== File Detection + +* `+.smt2+` files automatically detected as SMT solver format +* Can be used with both CVC5 and Z3 + +==== Neural Integration + +* `+suggest_tactics()+` provides stub for neural premise selection +* Returns SMT-specific tactics (check-sat, get-model, get-proof) +* Future: ML-based tactic selection + +==== Aspect Tagging + +* Metadata preserved in `+ProofState+` +* Prover and format tags automatically added +* Custom metadata supported + +''''' + +=== Usage Examples + +==== Basic Verification + +[source,rust] +---- +use echidna::provers::cvc5::CVC5Backend; +use echidna::provers::ProverConfig; +use std::path::PathBuf; + +let config = ProverConfig { + executable: PathBuf::from("cvc5"), + timeout: 60, + ..Default::default() +}; + +let backend = CVC5Backend::new(config); + +// Get version +let version = backend.version().await?; +println!("CVC5 version: {}", version); + +// Parse and verify SMT-LIB file +let state = backend.parse_file(PathBuf::from("problem.smt2")).await?; +let valid = backend.verify_proof(&state).await?; +println!("Valid: {}", valid); +---- + +==== Custom Commands + +[source,rust] +---- +use echidna::core::Tactic; + +// Check satisfiability +let tactic = Tactic::Custom { + prover: "cvc5".to_string(), + command: "check-sat".to_string(), + args: vec![], +}; +let result = backend.apply_tactic(&state, &tactic).await?; + +// Get model if sat +let tactic = Tactic::Custom { + prover: "cvc5".to_string(), + command: "get-model".to_string(), + args: vec![], +}; +let result = backend.apply_tactic(&state, &tactic).await?; +---- + +==== String Theory Example + +[source,rust] +---- +use echidna::provers::cvc5::string_examples; + +let smtlib = string_examples::regex_match(); +let state = backend.parse_string(&smtlib).await?; +let valid = backend.verify_proof(&state).await?; +// Checks if string matches email regex pattern +---- + +==== Incremental Solving (Internal Use) + +[source,rust] +---- +// Internal API - used by verify_proof() +backend.push_context()?; +backend.send_command("(assert (> x 5))")?; +let result1 = backend.check_sat()?; + +backend.push_context()?; +backend.send_command("(assert (< x 3))")?; +let result2 = backend.check_sat()?; // Should be unsat + +backend.pop_context()?; +let result3 = backend.check_sat()?; // Back to first context +backend.pop_context()?; +---- + +''''' + +=== Performance Characteristics + +[cols=",,",options="header",] +|=== +|Metric |Value |Notes +|Memory |~10MB + CVC5 process |Low overhead +|Startup |50-100ms |Process spawn time +|Query Time |Variable |Depends on problem complexity +|Incremental |Fast |No restart needed +|I/O Overhead |Minimal |Buffered reading, batch writes +|=== + +''''' + +=== Dependencies + +==== Required Rust Crates + +* `+async-trait+` - Async trait support +* `+anyhow+` - Error handling +* `+serde+` + `+serde_json+` - Serialization +* `+tokio+` - Async runtime +* Standard library: `+std::process+`, `+std::io+`, `+std::sync+` + +==== External Dependencies + +* `+cvc5+` executable (system dependency) +* Version: CVC5 1.0.0+ recommended + +''''' + +=== Comparison: CVC5 vs Z3 + +[cols=",,",options="header",] +|=== +|Feature |CVC5 |Z3 +|*String Theory* |✅ Excellent |✅ Good +|*Sequence Theory* |✅ Native |⚠️ Limited +|*Sets/Relations* |✅ Full |✅ Full +|*Separation Logic* |✅ Native |❌ No +|*Regular Expressions* |✅ Full |⚠️ Basic +|*Proof Production* |✅ Yes |✅ Yes +|*Model Generation* |✅ Yes |✅ Yes +|*Performance* |⚡ Fast |⚡ Fast +|*Maturity* |🆕 Newer |🏆 Established +|*Use Case* |String/sequence problems |General SMT +|=== + +*Recommendation*: - Use *CVC5* for string/sequence-heavy problems - Use +*Z3* for general SMT solving - ECHIDNA supports both! ✅ + +''''' + +=== Testing Strategy + +==== Unit Tests (Included) + +✅ Parser correctness ✅ Configuration handling ✅ Backend +initialization ✅ Example validity + +==== Integration Tests (Requires CVC5 Binary) + +⏳ Actual solving ⏳ Process communication ⏳ Incremental mode ⏳ +Proof/model extraction ⏳ Error handling + +*Note*: Full integration tests run in CI/CD with CVC5 installed + +==== Manual Testing Commands + +[source,bash] +---- +# Test with CVC5 installed +cargo test --package echidna --lib provers::cvc5::tests + +# Test with actual CVC5 binary +cargo test --package echidna -- --ignored + +# Benchmark (if implemented) +cargo bench --package echidna cvc5 +---- + +''''' + +=== Future Enhancements + +==== Short-Term (Next Release) + +[arabic] +. *Proof Certification* - Parse and validate CVC5 proof objects +. *Incremental Tactics* - Expose push/pop as user-facing tactics +. *Option Presets* - Predefined configs (strings, arrays, etc.) + +==== Medium-Term (Q1 2026) + +[arabic, start=4] +. *Performance Monitoring* - Track query times, statistics +. *Parallel Queries* - Multiple CVC5 instances for portfolio solving +. *Better Error Messages* - Parse and explain CVC5 errors + +==== Long-Term (Q2+ 2026) + +[arabic, start=7] +. *Neural Integration* - ML-based tactic selection for SMT +. *Benchmarking Suite* - Automated performance testing +. *Native API Bindings* - CVC5 C++ API via FFI (when stable) + +''''' + +=== Known Limitations + +[arabic] +. *No Library Search* - CVC5 has no theorem database (returns empty +list) +. *Limited Term Conversion* - Complex SMT-LIB constructs use +`+ProverSpecific+` +. *Process Overhead* - Subprocess slower than native API (when +available) +. *Error Messages* - CVC5 errors can be cryptic, minimal parsing +. *Version Sensitivity* - CVC5 flags may change across versions + +''''' + +=== File Locations + +.... +/home/user/echidna/ +├── src/rust/provers/ +│ └── cvc5.rs # Main implementation (719 lines) +├── docs/ +│ └── CVC5_IMPLEMENTATION.md # Detailed documentation +└── CVC5_IMPLEMENTATION_SUMMARY.md # This file +.... + +''''' + +=== Success Criteria Met ✅ + +[arabic] +. ✅ *Complete Implementation* - All 11 ProverBackend methods +implemented +. ✅ *SMT-LIB 2.0 Support* - Full parser and generator +. ✅ *CVC5-Specific Features* - String, sequence, sets, separation logic +. ✅ *Process Management* - Robust subprocess handling +. ✅ *Incremental Mode* - Push/pop context management +. ✅ *Proof Production* - Proof/model/unsat-core extraction +. ✅ *Error Handling* - Comprehensive error coverage +. ✅ *Examples* - 9 working examples across 4 theory modules +. ✅ *Testing* - 5 unit tests +. ✅ *Documentation* - Extensive inline docs + separate guides +. ✅ *Production-Ready* - Clean code, proper resource management, Drop +impl + +''''' + +=== License + +Dual-licensed under: - *MIT License* - *Palimpsest License v0.6* + +SPDX: `+MIT OR Palimpsest-0.6+` + +''''' + +=== References + +* https://cvc5.github.io/[CVC5 Official Site] +* https://cvc5.github.io/docs/latest/[CVC5 Documentation] +* https://smtlib.cs.uiowa.edu/[SMT-LIB 2.0 Standard] +* https://github.com/cvc5/cvc5[CVC5 GitHub] +* https://cvc5.github.io/docs/latest/theories/strings.html[String Theory +in CVC5] +* https://cvc5.github.io/docs/latest/theories/separation-logic.html[Separation +Logic in CVC5] + +''''' + +=== Implementation Statistics + +[width="100%",cols="54%,46%",options="header",] +|=== +|Metric |Value +|*Total Lines* |719 + +|*Structs* |3 (CVC5Config, CVC5Backend, CVC5Process) + +|*Enums* |1 (SmtResult) + +|*Public Functions* |22 + +|*Private Functions* |15 + +|*Example Modules* |4 + +|*Examples* |9 + +|*Tests* |5 + +|*Trait Implementations* |4 (Default, ProverBackend, Drop, partial +Clone) + +|*Documentation Lines* |~150 + +|*Code-to-Doc Ratio* |~21% +|=== + +''''' + +*Implementation Complete* ✅ *Status*: Production-Ready *Author*: +ECHIDNA Project Team (via Claude Code) *Date*: 2025-11-22 + +''''' + +== Appendix: CVC5 Backend Reference + +_The following content was merged in from +`+docs/CVC5_IMPLEMENTATION.md+` on 2026-05-25 when the two parallel +"`backend`" and "`implementation summary`" docs were consolidated. +Sections may overlap with the summary above and will be naturally +integrated in a future doc-polish pass._ + +*File*: `+/home/user/echidna/src/rust/provers/cvc5.rs+` *Lines of Code*: +943 *Status*: ✅ Complete Production-Ready Implementation *Tier*: 1 +(Complexity: 2/5, Est. Time: 1 week) + +=== Overview + +Complete CVC5 SMT solver backend for ECHIDNA theorem proving platform. +CVC5 is the successor to CVC4 and provides state-of-the-art SMT solving +with excellent support for string theory, sequences, sets, relations, +and separation logic. + +=== Implementation Features + +==== 1. Core Backend Structure + +===== `+CVC5Backend+` struct + +* Implements `+ProverBackend+` trait for universal prover interface +* Process-based communication via SMT-LIB 2.0 +* Thread-safe with `+Arc>+` for process management +* Configurable via `+CVC5Config+` + +===== `+CVC5Config+` struct + +[source,rust] +---- +pub struct CVC5Config { + pub base: ProverConfig, // Standard config + pub produce_proofs: bool, // Enable proof generation + pub produce_models: bool, // Enable model extraction + pub produce_unsat_cores: bool, // Enable unsat core generation + pub incremental: bool, // Enable incremental mode + pub cvc5_options: HashMap, // CVC5-specific options +} +---- + +==== 2. SMT-LIB 2.0 Parser + +*Bidirectional Translation*: - `+term_to_smtlib()+`: Convert ECHIDNA +Term → SMT-LIB format - `+smtlib_to_term()+`: Convert SMT-LIB → ECHIDNA +Term - `+parse_sexp_parts()+`: Robust S-expression parser with: - Nested +parentheses handling - String literal support with escape sequences - +Whitespace normalization + +*File Parsing*: - `+parse_smtlib_content()+`: Full SMT-LIB 2.0 file +parser - Extracts declarations, assertions, and goals - Preserves +metadata and aspects + +==== 3. Process Management + +*Interactive Mode*: + +[source,rust] +---- +struct CVC5Process { + child: Child, // Process handle + stdin: ChildStdin, // Input pipe + stdout: BufReader, // Output pipe (buffered) + command_count: usize, // Track commands + stack_depth: usize, // Track push/pop depth +} +---- + +*Key Operations*: - `+start_process()+`: Launch CVC5 with proper flags - +`+send_command()+`: Send SMT-LIB command and read response - +`+get_process()+`: Lazy initialization of CVC5 process - `+reset()+`: +Clean shutdown and restart + +==== 4. Incremental Solving + +*Push/Pop Stack*: - `+push_context()+`: Save current solving context - +`+pop_context()+`: Restore previous context - Stack depth tracking for +safety - Prevents pop on empty stack + +*Use Cases*: - Try multiple strategies without restart - Branch +exploration in proof search - Assumption management - +Counterexample-guided refinement + +==== 5. Proof Production + +*Commands*: - `+get_proof()+`: Extract proof certificate after `+unsat+` +- `+get_model()+`: Extract model/counterexample after `+sat+` - +`+get_unsat_core()+`: Get minimal unsatisfiable subset + +*Configuration*: + +[source,bash] +---- +--dump-proofs # Enable proof output +--proof-mode=full # Full proof details +--produce-models # Enable model generation +--produce-unsat-cores # Enable core extraction +---- + +==== 6. CVC5-Specific Features + +===== String Theory (`+QF_SLIA+` logic) + +*Operations*: - `+str.+++`: String concatenation - `+str.len+`: String +length - `+str.substr+`: Substring extraction - `+str.contains+`: +Substring check - `+str.in.re+`: Regular expression matching - +`+str.to.re+`: String to regex conversion + +*Example*: Email validation with regex + +[source,smt2] +---- +(declare-const email String) +(assert (str.in.re email + (re.++ + (re.+ (re.range "a" "z")) + (str.to.re "@") + (re.+ (re.range "a" "z")) + (str.to.re ".") + (re.+ (re.range "a" "z")) + ) +)) +---- + +===== Sequence Theory + +*Operations*: - `+seq.+++`: Sequence concatenation - `+seq.len+`: +Sequence length - `+seq.nth+`: Element access - `+seq.contains+`: +Subsequence check - Generic over element types: `+(Seq Int)+`, +`+(Seq String)+`, etc. + +*Example*: Integer sequence operations + +[source,smt2] +---- +(declare-const s (Seq Int)) +(assert (= (seq.len s) 5)) +(assert (= (seq.nth s 0) 1)) +(assert (= (seq.nth s 4) 5)) +---- + +===== Sets and Relations + +*Set Operations*: - `+set.member+`: Element membership - `+set.union+`: +Set union - `+set.inter+`: Set intersection - `+set.minus+`: Set +difference - `+set.card+`: Cardinality + +*Relation Operations*: - `+tuple+`: Create tuples - `+rel.tclosure+`: +Transitive closure - `+rel.join+`: Relational join - `+Relation+` type: +`+(Relation Int Int)+` for binary relations + +*Example*: Transitive closure + +[source,smt2] +---- +(declare-const R (Relation Int Int)) +(assert (set.member (tuple 1 2) R)) +(assert (set.member (tuple 2 3) R)) +(assert (set.member (tuple 1 3) (rel.tclosure R))) +---- + +===== Separation Logic + +*Predicates*: - `+sep+`: Separating conjunction (heap separation) - +`+pto+`: Points-to predicate - `+emp+`: Empty heap + +*Example*: Heap separation + +[source,smt2] +---- +(declare-const x Int) +(declare-const y Int) +(assert (sep (pto x 1) (pto y 2))) +(assert (distinct x y)) +---- + +==== 7. ProverBackend Trait Implementation + +All 11 required methods implemented: + +[arabic] +. *`+kind()+`* → Returns `+ProverKind::CVC5+` +. *`+version()+`* → Executes `+cvc5 --version+` +. *`+parse_file(path)+`* → Parse SMT-LIB 2.0 file +. *`+parse_string(content)+`* → Parse SMT-LIB 2.0 string +. *`+apply_tactic(state, tactic)+`* → Execute tactic +. *`+verify_proof(state)+`* → Check validity (unsat check) +. *`+export(state)+`* → Generate SMT-LIB 2.0 output +. *`+suggest_tactics(state, limit)+`* → Suggest solve strategies +. *`+search_theorems(pattern)+`* → Theorem search (N/A for SMT) +. *`+config()+`* → Get configuration +. *`+set_config(config)+`* → Update configuration + +==== 8. Error Handling + +*Comprehensive Coverage*: - Process spawn failures - I/O errors +(stdin/stdout) - Parse errors (malformed S-expressions) - CVC5 error +responses - Stack underflow (pop on empty stack) - Process death +detection - Timeout handling (via config) + +*Error Context*: + +[source,rust] +---- +use anyhow::{anyhow, Context as AnyhowContext, Result}; + +self.send_command(cmd) + .context("Failed to send command to CVC5")?; +---- + +==== 9. Testing + +*Unit Tests* (8 tests): - `+test_sexp_parser+`: Basic S-expression +parsing - `+test_sexp_parser_nested+`: Nested expression parsing - +`+test_unsat_core_parser+`: Unsat core extraction - +`+test_backend_creation+`: Backend initialization - +`+test_string_examples+`: String theory examples + +*Test Coverage*: - Parser correctness - Backend lifecycle - Example +validity - Configuration handling + +==== 10. Example Library + +*Four Example Modules* with real-world use cases: + +===== `+string_examples+` (4 examples) + +* String concatenation and length +* Substring operations +* String contains +* Regular expression matching + +===== `+sequence_examples+` (2 examples) + +* Sequence operations +* Sequence contains + +===== `+sets_examples+` (2 examples) + +* Set operations +* Relation transitive closure + +===== `+separation_logic_examples+` (1 example) + +* Basic separation logic heap + +*Total*: 9 working examples demonstrating CVC5’s unique capabilities + +=== Architecture Decisions + +==== 1. Process-Based Communication + +*Why*: CVC5 has no stable Rust API - Use subprocess with stdin/stdout +pipes - SMT-LIB 2.0 is standardized and stable - Allows version +independence + +==== 2. Lazy Process Initialization + +*Why*: Reduce resource usage - Process spawned on first use - Reused for +multiple queries - Cleaned up on drop + +==== 3. Synchronous with Async Wrapper + +*Why*: Simplify I/O handling - Blocking I/O is sufficient for CVC5 +interaction - Async trait for API compatibility - No performance penalty +(CVC5 is the bottleneck) + +==== 4. Prover-Specific Term Escape Hatch + +*Why*: Some SMT-LIB constructs don’t map to ECHIDNA Term - Use +`+Term::ProverSpecific+` for complex SMT-LIB - Preserves exact SMT-LIB +when needed - Allows round-trip parsing + +=== Performance Characteristics + +*Memory*: Low (~10MB + CVC5 process) *Startup*: ~50-100ms (process +spawn) *Query*: Variable (depends on problem complexity) *Incremental*: +Fast (no restart needed) + +=== Integration with ECHIDNA + +==== Prover Factory + +[source,rust] +---- +ProverFactory::create(ProverKind::CVC5, config)? +---- + +==== File Detection + +`+.smt2+` files auto-detected as CVC5/Z3 + +==== Neural Integration + +Stub for neural premise selection via `+suggest_tactics()+` + +==== Aspect Tagging + +Metadata preserved in `+ProofState+` + +=== Usage Examples + +==== Basic Usage + +[source,rust] +---- +use echidna::provers::{ProverBackend, ProverConfig, ProverKind}; +use echidna::provers::cvc5::CVC5Backend; + +let config = ProverConfig { + executable: PathBuf::from("cvc5"), + timeout: 60, + ..Default::default() +}; + +let backend = CVC5Backend::new(config); +let version = backend.version().await?; +println!("CVC5 version: {}", version); + +// Parse SMT-LIB file +let state = backend.parse_file(PathBuf::from("problem.smt2")).await?; + +// Verify +let valid = backend.verify_proof(&state).await?; +println!("Valid: {}", valid); +---- + +==== Custom Commands + +[source,rust] +---- +use echidna::core::Tactic; + +let tactic = Tactic::Custom { + prover: "cvc5".to_string(), + command: "check-sat".to_string(), + args: vec![], +}; + +let result = backend.apply_tactic(&state, &tactic).await?; +---- + +==== String Theory Example + +[source,rust] +---- +let smtlib = r#" +(set-logic QF_SLIA) +(declare-const x String) +(declare-const y String) +(assert (= (str.++ x y) "helloworld")) +(assert (= (str.len x) 5)) +(check-sat) +(get-model) +"#; + +let state = backend.parse_string(smtlib).await?; +let valid = backend.verify_proof(&state).await?; +---- + +=== Dependencies + +*Required*: - `+serde+` + `+serde_json+`: Serialization - `+tokio+` + +`+async-trait+`: Async runtime - `+anyhow+`: Error handling - Standard +library: `+std::process+`, `+std::io+` + +*External*: - `+cvc5+` executable (system dependency) + +=== Configuration + +==== Default Configuration + +[source,rust] +---- +CVC5Config { + base: ProverConfig { + executable: PathBuf::from("cvc5"), + timeout: 300, // 5 minutes + neural_enabled: true, + .. + }, + produce_proofs: true, + produce_models: true, + produce_unsat_cores: false, + incremental: true, + cvc5_options: [("strings-exp", "true")].into(), +} +---- + +==== Custom Options + +[source,rust] +---- +let mut config = CVC5Config::default(); +config.cvc5_options.insert("finite-model-find".to_string(), "true".to_string()); +config.cvc5_options.insert("fmf-bound".to_string(), "true".to_string()); +---- + +=== Comparison with Z3 Backend + +[cols=",,",options="header",] +|=== +|Feature |CVC5 |Z3 +|String Theory |✅ Excellent |✅ Good +|Sequence Theory |✅ Native |⚠️ Limited +|Sets/Relations |✅ Full |✅ Full +|Separation Logic |✅ Native |❌ No +|Regular Expressions |✅ Full |⚠️ Basic +|Proof Production |✅ Yes |✅ Yes +|Model Generation |✅ Yes |✅ Yes +|Performance |⚡ Fast |⚡ Fast +|Maturity |🆕 Newer |🏆 Established +|=== + +*Recommendation*: Use CVC5 for string/sequence-heavy problems, Z3 for +general SMT. + +=== Future Enhancements + +[arabic] +. *Proof Certification*: Parse and validate CVC5 proofs +. *Incremental Tactics*: Expose push/pop as tactics +. *Option Presets*: Common configurations (strings, arrays, etc.) +. *Performance Monitoring*: Track query times and statistics +. *Parallel Queries*: Multiple CVC5 instances for portfolio solving +. *Neural Integration*: ML-based tactic selection for SMT +. *Benchmarking*: Automated performance testing suite +. *API Bindings*: Native CVC5 C++ API via FFI (when stable) + +=== Known Limitations + +[arabic] +. *No Library Search*: CVC5 has no theorem database +. *Limited Term Conversion*: Complex SMT-LIB → Term mapping incomplete +. *Process Overhead*: Subprocess communication slower than API +. *Error Messages*: CVC5 errors may be cryptic +. *Version Sensitivity*: Flags may change across CVC5 versions + +=== Testing Coverage + +*What’s Tested*: - ✅ S-expression parser - ✅ Unsat core parser - ✅ +Backend creation - ✅ Configuration - ✅ Example validity + +*What’s Not Tested* (requires CVC5 binary): - ❌ Actual solving - ❌ +Process communication - ❌ Incremental mode - ❌ Proof/model extraction +- ❌ Error handling + +*Note*: Full integration tests require CVC5 installation and are +typically run in CI/CD. + +=== License + +Dual-licensed under: - *MIT License* - *Palimpsest License v0.6* + +=== References + +* https://cvc5.github.io/[CVC5 Official Site] +* https://cvc5.github.io/docs/latest/[CVC5 Documentation] +* https://smtlib.cs.uiowa.edu/[SMT-LIB 2.0 Standard] +* https://github.com/cvc5/cvc5[CVC5 GitHub] +* https://cvc5.github.io/docs/latest/theories/strings.html[String Theory +in SMT] +* https://cvc5.github.io/docs/latest/theories/separation-logic.html[Separation +Logic] + +''''' + +*Implementation Date*: 2025-11-22 *Author*: ECHIDNA Project Team (via +Claude Code) *Status*: Production-Ready ✅ diff --git a/docs/implementation/CVC5_IMPLEMENTATION_SUMMARY.md b/docs/implementation/CVC5_IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index 054344b7..00000000 --- a/docs/implementation/CVC5_IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,947 +0,0 @@ -# CVC5 SMT Solver Backend Implementation Summary - -## ✅ Implementation Complete - -**Date**: 2025-11-22 -**Status**: Production-Ready -**File**: `/home/user/echidna/src/rust/provers/cvc5.rs` -**Lines of Code**: 719 lines -**Tier**: 1 (SMT Solver) -**Complexity**: 2/5 (Low-Medium) -**Estimated Implementation Time**: 1 week - ---- - -## Overview - -Complete, production-ready CVC5 SMT solver backend for ECHIDNA theorem proving platform. CVC5 is the successor to CVC4 and provides state-of-the-art SMT solving with exceptional support for: - -- **String Theory** - Advanced string operations and regex matching -- **Sequence Theory** - Generic sequences over any element type -- **Sets and Relations** - Full set theory with transitive closure -- **Separation Logic** - Heap reasoning and separation -- **SMT-LIB 2.0** - Standard SMT solver interface - ---- - -## Implementation Details - -### Core Components - -#### 1. **CVC5Backend** - Main Backend Struct -- Implements `ProverBackend` trait (11 required methods) -- Process-based communication via SMT-LIB 2.0 -- Thread-safe with `Arc>` for process management -- Lazy process initialization -- Automatic cleanup on drop - -#### 2. **CVC5Config** - Configuration -```rust -pub struct CVC5Config { - pub base: ProverConfig, // Base configuration - pub produce_proofs: bool, // Enable proof generation - pub produce_models: bool, // Enable model extraction - pub produce_unsat_cores: bool, // Enable unsat core generation - pub incremental: bool, // Enable incremental mode - pub cvc5_options: HashMap, // Custom options -} -``` - -**Default Settings**: -- Proofs: Enabled -- Models: Enabled -- Unsat Cores: Disabled -- Incremental Mode: Enabled -- String Solver: Enabled (`strings-exp`) - -#### 3. **CVC5Process** - Process Management -```rust -struct CVC5Process { - child: Child, // Process handle - stdin: ChildStdin, // Input pipe - stdout: BufReader, // Output pipe (buffered) - command_count: usize, // Command tracking - stack_depth: usize, // Push/pop depth -} -``` - -**Process Features**: -- Interactive mode (`--interactive`) -- SMT-LIB 2.0 language (`--lang=smt2`) -- Configurable proof/model generation -- Incremental solving support -- Automatic restart on configuration change - -### Key Features Implemented - -#### ✅ SMT-LIB 2.0 Parser -- **Bidirectional Translation**: ECHIDNA Term ↔ SMT-LIB -- **S-Expression Parser**: Handles nested expressions, strings with escapes -- **File Parsing**: Complete SMT-LIB 2.0 file support -- **Goal Extraction**: Converts assertions to ECHIDNA goals - -#### ✅ Process Communication -- **send_command()**: Send SMT-LIB command, read S-expression response -- **Response Parsing**: Depth-tracking for correct S-expr boundaries -- **Error Detection**: Catches CVC5 error messages -- **Simple Response Handling**: Recognizes `sat`, `unsat`, `unknown`, `success` - -#### ✅ Incremental Solving -- **push_context()**: Save current solving state -- **pop_context()**: Restore previous state -- **Stack Depth Tracking**: Prevents underflow -- **Use Cases**: Branch exploration, assumption management, CEGIS - -#### ✅ Proof and Model Extraction -- **get_proof()**: Extract proof after `unsat` result -- **get_model()**: Extract counterexample after `sat` result -- **get_unsat_core()**: Minimal unsatisfiable subset -- **Configurable**: Enable/disable via config flags - -#### ✅ ProverBackend Trait (11/11 Methods) -1. ✅ `kind()` - Returns `ProverKind::CVC5` -2. ✅ `version()` - Executes `cvc5 --version` -3. ✅ `parse_file(path)` - Parse SMT-LIB 2.0 file -4. ✅ `parse_string(content)` - Parse SMT-LIB 2.0 string -5. ✅ `apply_tactic(state, tactic)` - Execute custom SMT commands -6. ✅ `verify_proof(state)` - Check validity via negation+unsat -7. ✅ `export(state)` - Generate SMT-LIB 2.0 output -8. ✅ `suggest_tactics(state, limit)` - Suggest solve strategies -9. ✅ `search_theorems(pattern)` - Returns empty (N/A for SMT) -10. ✅ `config()` - Get current configuration -11. ✅ `set_config(config)` - Update config and restart process - -#### ✅ Error Handling -**Comprehensive Coverage**: -- Process spawn failures -- I/O errors (stdin/stdout read/write/flush) -- Parse errors (malformed S-expressions) -- CVC5 error responses -- Stack underflow (pop on empty stack) -- Process death detection -- Type conversion errors - -**Error Context**: -- Uses `anyhow::Context` for informative errors -- Propagates errors with full context chain -- Clear error messages for debugging - -#### ✅ CVC5-Specific Features & Examples - -**String Theory Module** (`string_examples`): -1. `string_concat_length()` - String concatenation and length -2. `string_substring()` - Substring extraction -3. `string_contains()` - Substring containment -4. `regex_match()` - Regular expression matching (email validator) - -**Sequence Theory Module** (`sequence_examples`): -1. `sequence_ops()` - Sequence operations (length, nth, concat) -2. `sequence_contains()` - Subsequence containment - -**Sets Module** (`sets_examples`): -1. `set_ops()` - Set operations (member, card, inter) -2. `relation_ops()` - Transitive closure on relations - -**Separation Logic Module** (`separation_logic_examples`): -1. `sep_logic_basic()` - Heap separation with points-to - -**Total**: 9 working examples demonstrating CVC5 unique capabilities - -#### ✅ Testing -**Unit Tests** (5 tests): -- `test_sexp_parser` - Basic S-expression parsing -- `test_sexp_parser_nested` - Nested S-expression parsing -- `test_unsat_core_parser` - Unsat core extraction -- `test_backend_creation` - Backend initialization -- `test_string_examples` - Example validity checks - -**Coverage**: -- Parser correctness ✅ -- Backend lifecycle ✅ -- Configuration ✅ -- Example validity ✅ - ---- - -## Architecture Decisions - -### 1. Process-Based Communication -**Why**: CVC5 has no stable Rust API -- Subprocess with stdin/stdout pipes -- SMT-LIB 2.0 is standardized -- Version-independent -- Simple and robust - -### 2. Lazy Process Initialization -**Why**: Resource efficiency -- Process spawned on first use -- Reused across multiple queries -- Cleaned up automatically on drop -- Reduces startup overhead - -### 3. Synchronous I/O with Async Wrapper -**Why**: Simplicity without performance loss -- Blocking I/O sufficient for SMT interaction -- Async trait for API compatibility -- No async overhead needed -- CVC5 solving is the bottleneck, not I/O - -### 4. Prover-Specific Term Type -**Why**: SMT-LIB doesn't map perfectly to ECHIDNA Term -- `Term::ProverSpecific` as escape hatch -- Preserves exact SMT-LIB when needed -- Enables round-trip parsing -- Handles complex SMT constructs - ---- - -## Integration with ECHIDNA - -### Prover Factory -```rust -use echidna::provers::{ProverFactory, ProverKind, ProverConfig}; - -let config = ProverConfig { /* ... */ }; -let backend = ProverFactory::create(ProverKind::CVC5, config)?; -``` - -### File Detection -- `.smt2` files automatically detected as SMT solver format -- Can be used with both CVC5 and Z3 - -### Neural Integration -- `suggest_tactics()` provides stub for neural premise selection -- Returns SMT-specific tactics (check-sat, get-model, get-proof) -- Future: ML-based tactic selection - -### Aspect Tagging -- Metadata preserved in `ProofState` -- Prover and format tags automatically added -- Custom metadata supported - ---- - -## Usage Examples - -### Basic Verification -```rust -use echidna::provers::cvc5::CVC5Backend; -use echidna::provers::ProverConfig; -use std::path::PathBuf; - -let config = ProverConfig { - executable: PathBuf::from("cvc5"), - timeout: 60, - ..Default::default() -}; - -let backend = CVC5Backend::new(config); - -// Get version -let version = backend.version().await?; -println!("CVC5 version: {}", version); - -// Parse and verify SMT-LIB file -let state = backend.parse_file(PathBuf::from("problem.smt2")).await?; -let valid = backend.verify_proof(&state).await?; -println!("Valid: {}", valid); -``` - -### Custom Commands -```rust -use echidna::core::Tactic; - -// Check satisfiability -let tactic = Tactic::Custom { - prover: "cvc5".to_string(), - command: "check-sat".to_string(), - args: vec![], -}; -let result = backend.apply_tactic(&state, &tactic).await?; - -// Get model if sat -let tactic = Tactic::Custom { - prover: "cvc5".to_string(), - command: "get-model".to_string(), - args: vec![], -}; -let result = backend.apply_tactic(&state, &tactic).await?; -``` - -### String Theory Example -```rust -use echidna::provers::cvc5::string_examples; - -let smtlib = string_examples::regex_match(); -let state = backend.parse_string(&smtlib).await?; -let valid = backend.verify_proof(&state).await?; -// Checks if string matches email regex pattern -``` - -### Incremental Solving (Internal Use) -```rust -// Internal API - used by verify_proof() -backend.push_context()?; -backend.send_command("(assert (> x 5))")?; -let result1 = backend.check_sat()?; - -backend.push_context()?; -backend.send_command("(assert (< x 3))")?; -let result2 = backend.check_sat()?; // Should be unsat - -backend.pop_context()?; -let result3 = backend.check_sat()?; // Back to first context -backend.pop_context()?; -``` - ---- - -## Performance Characteristics - -| Metric | Value | Notes | -|--------|-------|-------| -| Memory | ~10MB + CVC5 process | Low overhead | -| Startup | 50-100ms | Process spawn time | -| Query Time | Variable | Depends on problem complexity | -| Incremental | Fast | No restart needed | -| I/O Overhead | Minimal | Buffered reading, batch writes | - ---- - -## Dependencies - -### Required Rust Crates -- `async-trait` - Async trait support -- `anyhow` - Error handling -- `serde` + `serde_json` - Serialization -- `tokio` - Async runtime -- Standard library: `std::process`, `std::io`, `std::sync` - -### External Dependencies -- `cvc5` executable (system dependency) -- Version: CVC5 1.0.0+ recommended - ---- - -## Comparison: CVC5 vs Z3 - -| Feature | CVC5 | Z3 | -|---------|------|-----| -| **String Theory** | ✅ Excellent | ✅ Good | -| **Sequence Theory** | ✅ Native | ⚠️ Limited | -| **Sets/Relations** | ✅ Full | ✅ Full | -| **Separation Logic** | ✅ Native | ❌ No | -| **Regular Expressions** | ✅ Full | ⚠️ Basic | -| **Proof Production** | ✅ Yes | ✅ Yes | -| **Model Generation** | ✅ Yes | ✅ Yes | -| **Performance** | ⚡ Fast | ⚡ Fast | -| **Maturity** | 🆕 Newer | 🏆 Established | -| **Use Case** | String/sequence problems | General SMT | - -**Recommendation**: -- Use **CVC5** for string/sequence-heavy problems -- Use **Z3** for general SMT solving -- ECHIDNA supports both! ✅ - ---- - -## Testing Strategy - -### Unit Tests (Included) -✅ Parser correctness -✅ Configuration handling -✅ Backend initialization -✅ Example validity - -### Integration Tests (Requires CVC5 Binary) -⏳ Actual solving -⏳ Process communication -⏳ Incremental mode -⏳ Proof/model extraction -⏳ Error handling - -**Note**: Full integration tests run in CI/CD with CVC5 installed - -### Manual Testing Commands -```bash -# Test with CVC5 installed -cargo test --package echidna --lib provers::cvc5::tests - -# Test with actual CVC5 binary -cargo test --package echidna -- --ignored - -# Benchmark (if implemented) -cargo bench --package echidna cvc5 -``` - ---- - -## Future Enhancements - -### Short-Term (Next Release) -1. **Proof Certification** - Parse and validate CVC5 proof objects -2. **Incremental Tactics** - Expose push/pop as user-facing tactics -3. **Option Presets** - Predefined configs (strings, arrays, etc.) - -### Medium-Term (Q1 2026) -4. **Performance Monitoring** - Track query times, statistics -5. **Parallel Queries** - Multiple CVC5 instances for portfolio solving -6. **Better Error Messages** - Parse and explain CVC5 errors - -### Long-Term (Q2+ 2026) -7. **Neural Integration** - ML-based tactic selection for SMT -8. **Benchmarking Suite** - Automated performance testing -9. **Native API Bindings** - CVC5 C++ API via FFI (when stable) - ---- - -## Known Limitations - -1. **No Library Search** - CVC5 has no theorem database (returns empty list) -2. **Limited Term Conversion** - Complex SMT-LIB constructs use `ProverSpecific` -3. **Process Overhead** - Subprocess slower than native API (when available) -4. **Error Messages** - CVC5 errors can be cryptic, minimal parsing -5. **Version Sensitivity** - CVC5 flags may change across versions - ---- - -## File Locations - -``` -/home/user/echidna/ -├── src/rust/provers/ -│ └── cvc5.rs # Main implementation (719 lines) -├── docs/ -│ └── CVC5_IMPLEMENTATION.md # Detailed documentation -└── CVC5_IMPLEMENTATION_SUMMARY.md # This file -``` - ---- - -## Success Criteria Met ✅ - -1. ✅ **Complete Implementation** - All 11 ProverBackend methods implemented -2. ✅ **SMT-LIB 2.0 Support** - Full parser and generator -3. ✅ **CVC5-Specific Features** - String, sequence, sets, separation logic -4. ✅ **Process Management** - Robust subprocess handling -5. ✅ **Incremental Mode** - Push/pop context management -6. ✅ **Proof Production** - Proof/model/unsat-core extraction -7. ✅ **Error Handling** - Comprehensive error coverage -8. ✅ **Examples** - 9 working examples across 4 theory modules -9. ✅ **Testing** - 5 unit tests -10. ✅ **Documentation** - Extensive inline docs + separate guides -11. ✅ **Production-Ready** - Clean code, proper resource management, Drop impl - ---- - -## License - -Dual-licensed under: -- **MIT License** -- **Palimpsest License v0.6** - -SPDX: `MIT OR Palimpsest-0.6` - ---- - -## References - -- [CVC5 Official Site](https://cvc5.github.io/) -- [CVC5 Documentation](https://cvc5.github.io/docs/latest/) -- [SMT-LIB 2.0 Standard](https://smtlib.cs.uiowa.edu/) -- [CVC5 GitHub](https://github.com/cvc5/cvc5) -- [String Theory in CVC5](https://cvc5.github.io/docs/latest/theories/strings.html) -- [Separation Logic in CVC5](https://cvc5.github.io/docs/latest/theories/separation-logic.html) - ---- - -## Implementation Statistics - -| Metric | Value | -|--------|-------| -| **Total Lines** | 719 | -| **Structs** | 3 (CVC5Config, CVC5Backend, CVC5Process) | -| **Enums** | 1 (SmtResult) | -| **Public Functions** | 22 | -| **Private Functions** | 15 | -| **Example Modules** | 4 | -| **Examples** | 9 | -| **Tests** | 5 | -| **Trait Implementations** | 4 (Default, ProverBackend, Drop, partial Clone) | -| **Documentation Lines** | ~150 | -| **Code-to-Doc Ratio** | ~21% | - ---- - -**Implementation Complete** ✅ -**Status**: Production-Ready -**Author**: ECHIDNA Project Team (via Claude Code) -**Date**: 2025-11-22 - ---- - -# Appendix: CVC5 Backend Reference - -_The following content was merged in from `docs/CVC5_IMPLEMENTATION.md` on 2026-05-25 when the -two parallel "backend" and "implementation summary" docs were consolidated. -Sections may overlap with the summary above and will be naturally integrated in a -future doc-polish pass._ - - -**File**: `/home/user/echidna/src/rust/provers/cvc5.rs` -**Lines of Code**: 943 -**Status**: ✅ Complete Production-Ready Implementation -**Tier**: 1 (Complexity: 2/5, Est. Time: 1 week) - -## Overview - -Complete CVC5 SMT solver backend for ECHIDNA theorem proving platform. CVC5 is the successor to CVC4 and provides state-of-the-art SMT solving with excellent support for string theory, sequences, sets, relations, and separation logic. - -## Implementation Features - -### 1. Core Backend Structure - -#### `CVC5Backend` struct -- Implements `ProverBackend` trait for universal prover interface -- Process-based communication via SMT-LIB 2.0 -- Thread-safe with `Arc>` for process management -- Configurable via `CVC5Config` - -#### `CVC5Config` struct -```rust -pub struct CVC5Config { - pub base: ProverConfig, // Standard config - pub produce_proofs: bool, // Enable proof generation - pub produce_models: bool, // Enable model extraction - pub produce_unsat_cores: bool, // Enable unsat core generation - pub incremental: bool, // Enable incremental mode - pub cvc5_options: HashMap, // CVC5-specific options -} -``` - -### 2. SMT-LIB 2.0 Parser - -**Bidirectional Translation**: -- `term_to_smtlib()`: Convert ECHIDNA Term → SMT-LIB format -- `smtlib_to_term()`: Convert SMT-LIB → ECHIDNA Term -- `parse_sexp_parts()`: Robust S-expression parser with: - - Nested parentheses handling - - String literal support with escape sequences - - Whitespace normalization - -**File Parsing**: -- `parse_smtlib_content()`: Full SMT-LIB 2.0 file parser -- Extracts declarations, assertions, and goals -- Preserves metadata and aspects - -### 3. Process Management - -**Interactive Mode**: -```rust -struct CVC5Process { - child: Child, // Process handle - stdin: ChildStdin, // Input pipe - stdout: BufReader, // Output pipe (buffered) - command_count: usize, // Track commands - stack_depth: usize, // Track push/pop depth -} -``` - -**Key Operations**: -- `start_process()`: Launch CVC5 with proper flags -- `send_command()`: Send SMT-LIB command and read response -- `get_process()`: Lazy initialization of CVC5 process -- `reset()`: Clean shutdown and restart - -### 4. Incremental Solving - -**Push/Pop Stack**: -- `push_context()`: Save current solving context -- `pop_context()`: Restore previous context -- Stack depth tracking for safety -- Prevents pop on empty stack - -**Use Cases**: -- Try multiple strategies without restart -- Branch exploration in proof search -- Assumption management -- Counterexample-guided refinement - -### 5. Proof Production - -**Commands**: -- `get_proof()`: Extract proof certificate after `unsat` -- `get_model()`: Extract model/counterexample after `sat` -- `get_unsat_core()`: Get minimal unsatisfiable subset - -**Configuration**: -```bash ---dump-proofs # Enable proof output ---proof-mode=full # Full proof details ---produce-models # Enable model generation ---produce-unsat-cores # Enable core extraction -``` - -### 6. CVC5-Specific Features - -#### String Theory (`QF_SLIA` logic) -**Operations**: -- `str.++`: String concatenation -- `str.len`: String length -- `str.substr`: Substring extraction -- `str.contains`: Substring check -- `str.in.re`: Regular expression matching -- `str.to.re`: String to regex conversion - -**Example**: Email validation with regex -```smt2 -(declare-const email String) -(assert (str.in.re email - (re.++ - (re.+ (re.range "a" "z")) - (str.to.re "@") - (re.+ (re.range "a" "z")) - (str.to.re ".") - (re.+ (re.range "a" "z")) - ) -)) -``` - -#### Sequence Theory -**Operations**: -- `seq.++`: Sequence concatenation -- `seq.len`: Sequence length -- `seq.nth`: Element access -- `seq.contains`: Subsequence check -- Generic over element types: `(Seq Int)`, `(Seq String)`, etc. - -**Example**: Integer sequence operations -```smt2 -(declare-const s (Seq Int)) -(assert (= (seq.len s) 5)) -(assert (= (seq.nth s 0) 1)) -(assert (= (seq.nth s 4) 5)) -``` - -#### Sets and Relations -**Set Operations**: -- `set.member`: Element membership -- `set.union`: Set union -- `set.inter`: Set intersection -- `set.minus`: Set difference -- `set.card`: Cardinality - -**Relation Operations**: -- `tuple`: Create tuples -- `rel.tclosure`: Transitive closure -- `rel.join`: Relational join -- `Relation` type: `(Relation Int Int)` for binary relations - -**Example**: Transitive closure -```smt2 -(declare-const R (Relation Int Int)) -(assert (set.member (tuple 1 2) R)) -(assert (set.member (tuple 2 3) R)) -(assert (set.member (tuple 1 3) (rel.tclosure R))) -``` - -#### Separation Logic -**Predicates**: -- `sep`: Separating conjunction (heap separation) -- `pto`: Points-to predicate -- `emp`: Empty heap - -**Example**: Heap separation -```smt2 -(declare-const x Int) -(declare-const y Int) -(assert (sep (pto x 1) (pto y 2))) -(assert (distinct x y)) -``` - -### 7. ProverBackend Trait Implementation - -All 11 required methods implemented: - -1. **`kind()`** → Returns `ProverKind::CVC5` -2. **`version()`** → Executes `cvc5 --version` -3. **`parse_file(path)`** → Parse SMT-LIB 2.0 file -4. **`parse_string(content)`** → Parse SMT-LIB 2.0 string -5. **`apply_tactic(state, tactic)`** → Execute tactic -6. **`verify_proof(state)`** → Check validity (unsat check) -7. **`export(state)`** → Generate SMT-LIB 2.0 output -8. **`suggest_tactics(state, limit)`** → Suggest solve strategies -9. **`search_theorems(pattern)`** → Theorem search (N/A for SMT) -10. **`config()`** → Get configuration -11. **`set_config(config)`** → Update configuration - -### 8. Error Handling - -**Comprehensive Coverage**: -- Process spawn failures -- I/O errors (stdin/stdout) -- Parse errors (malformed S-expressions) -- CVC5 error responses -- Stack underflow (pop on empty stack) -- Process death detection -- Timeout handling (via config) - -**Error Context**: -```rust -use anyhow::{anyhow, Context as AnyhowContext, Result}; - -self.send_command(cmd) - .context("Failed to send command to CVC5")?; -``` - -### 9. Testing - -**Unit Tests** (8 tests): -- `test_sexp_parser`: Basic S-expression parsing -- `test_sexp_parser_nested`: Nested expression parsing -- `test_unsat_core_parser`: Unsat core extraction -- `test_backend_creation`: Backend initialization -- `test_string_examples`: String theory examples - -**Test Coverage**: -- Parser correctness -- Backend lifecycle -- Example validity -- Configuration handling - -### 10. Example Library - -**Four Example Modules** with real-world use cases: - -#### `string_examples` (4 examples) -- String concatenation and length -- Substring operations -- String contains -- Regular expression matching - -#### `sequence_examples` (2 examples) -- Sequence operations -- Sequence contains - -#### `sets_examples` (2 examples) -- Set operations -- Relation transitive closure - -#### `separation_logic_examples` (1 example) -- Basic separation logic heap - -**Total**: 9 working examples demonstrating CVC5's unique capabilities - -## Architecture Decisions - -### 1. Process-Based Communication -**Why**: CVC5 has no stable Rust API -- Use subprocess with stdin/stdout pipes -- SMT-LIB 2.0 is standardized and stable -- Allows version independence - -### 2. Lazy Process Initialization -**Why**: Reduce resource usage -- Process spawned on first use -- Reused for multiple queries -- Cleaned up on drop - -### 3. Synchronous with Async Wrapper -**Why**: Simplify I/O handling -- Blocking I/O is sufficient for CVC5 interaction -- Async trait for API compatibility -- No performance penalty (CVC5 is the bottleneck) - -### 4. Prover-Specific Term Escape Hatch -**Why**: Some SMT-LIB constructs don't map to ECHIDNA Term -- Use `Term::ProverSpecific` for complex SMT-LIB -- Preserves exact SMT-LIB when needed -- Allows round-trip parsing - -## Performance Characteristics - -**Memory**: Low (~10MB + CVC5 process) -**Startup**: ~50-100ms (process spawn) -**Query**: Variable (depends on problem complexity) -**Incremental**: Fast (no restart needed) - -## Integration with ECHIDNA - -### Prover Factory -```rust -ProverFactory::create(ProverKind::CVC5, config)? -``` - -### File Detection -`.smt2` files auto-detected as CVC5/Z3 - -### Neural Integration -Stub for neural premise selection via `suggest_tactics()` - -### Aspect Tagging -Metadata preserved in `ProofState` - -## Usage Examples - -### Basic Usage -```rust -use echidna::provers::{ProverBackend, ProverConfig, ProverKind}; -use echidna::provers::cvc5::CVC5Backend; - -let config = ProverConfig { - executable: PathBuf::from("cvc5"), - timeout: 60, - ..Default::default() -}; - -let backend = CVC5Backend::new(config); -let version = backend.version().await?; -println!("CVC5 version: {}", version); - -// Parse SMT-LIB file -let state = backend.parse_file(PathBuf::from("problem.smt2")).await?; - -// Verify -let valid = backend.verify_proof(&state).await?; -println!("Valid: {}", valid); -``` - -### Custom Commands -```rust -use echidna::core::Tactic; - -let tactic = Tactic::Custom { - prover: "cvc5".to_string(), - command: "check-sat".to_string(), - args: vec![], -}; - -let result = backend.apply_tactic(&state, &tactic).await?; -``` - -### String Theory Example -```rust -let smtlib = r#" -(set-logic QF_SLIA) -(declare-const x String) -(declare-const y String) -(assert (= (str.++ x y) "helloworld")) -(assert (= (str.len x) 5)) -(check-sat) -(get-model) -"#; - -let state = backend.parse_string(smtlib).await?; -let valid = backend.verify_proof(&state).await?; -``` - -## Dependencies - -**Required**: -- `serde` + `serde_json`: Serialization -- `tokio` + `async-trait`: Async runtime -- `anyhow`: Error handling -- Standard library: `std::process`, `std::io` - -**External**: -- `cvc5` executable (system dependency) - -## Configuration - -### Default Configuration -```rust -CVC5Config { - base: ProverConfig { - executable: PathBuf::from("cvc5"), - timeout: 300, // 5 minutes - neural_enabled: true, - .. - }, - produce_proofs: true, - produce_models: true, - produce_unsat_cores: false, - incremental: true, - cvc5_options: [("strings-exp", "true")].into(), -} -``` - -### Custom Options -```rust -let mut config = CVC5Config::default(); -config.cvc5_options.insert("finite-model-find".to_string(), "true".to_string()); -config.cvc5_options.insert("fmf-bound".to_string(), "true".to_string()); -``` - -## Comparison with Z3 Backend - -| Feature | CVC5 | Z3 | -|---------|------|-----| -| String Theory | ✅ Excellent | ✅ Good | -| Sequence Theory | ✅ Native | ⚠️ Limited | -| Sets/Relations | ✅ Full | ✅ Full | -| Separation Logic | ✅ Native | ❌ No | -| Regular Expressions | ✅ Full | ⚠️ Basic | -| Proof Production | ✅ Yes | ✅ Yes | -| Model Generation | ✅ Yes | ✅ Yes | -| Performance | ⚡ Fast | ⚡ Fast | -| Maturity | 🆕 Newer | 🏆 Established | - -**Recommendation**: Use CVC5 for string/sequence-heavy problems, Z3 for general SMT. - -## Future Enhancements - -1. **Proof Certification**: Parse and validate CVC5 proofs -2. **Incremental Tactics**: Expose push/pop as tactics -3. **Option Presets**: Common configurations (strings, arrays, etc.) -4. **Performance Monitoring**: Track query times and statistics -5. **Parallel Queries**: Multiple CVC5 instances for portfolio solving -6. **Neural Integration**: ML-based tactic selection for SMT -7. **Benchmarking**: Automated performance testing suite -8. **API Bindings**: Native CVC5 C++ API via FFI (when stable) - -## Known Limitations - -1. **No Library Search**: CVC5 has no theorem database -2. **Limited Term Conversion**: Complex SMT-LIB → Term mapping incomplete -3. **Process Overhead**: Subprocess communication slower than API -4. **Error Messages**: CVC5 errors may be cryptic -5. **Version Sensitivity**: Flags may change across CVC5 versions - -## Testing Coverage - -**What's Tested**: -- ✅ S-expression parser -- ✅ Unsat core parser -- ✅ Backend creation -- ✅ Configuration -- ✅ Example validity - -**What's Not Tested** (requires CVC5 binary): -- ❌ Actual solving -- ❌ Process communication -- ❌ Incremental mode -- ❌ Proof/model extraction -- ❌ Error handling - -**Note**: Full integration tests require CVC5 installation and are typically run in CI/CD. - -## License - -Dual-licensed under: -- **MIT License** -- **Palimpsest License v0.6** - -## References - -- [CVC5 Official Site](https://cvc5.github.io/) -- [CVC5 Documentation](https://cvc5.github.io/docs/latest/) -- [SMT-LIB 2.0 Standard](https://smtlib.cs.uiowa.edu/) -- [CVC5 GitHub](https://github.com/cvc5/cvc5) -- [String Theory in SMT](https://cvc5.github.io/docs/latest/theories/strings.html) -- [Separation Logic](https://cvc5.github.io/docs/latest/theories/separation-logic.html) - ---- - -**Implementation Date**: 2025-11-22 -**Author**: ECHIDNA Project Team (via Claude Code) -**Status**: Production-Ready ✅ diff --git a/docs/implementation/HOL_LIGHT_IMPLEMENTATION.adoc b/docs/implementation/HOL_LIGHT_IMPLEMENTATION.adoc new file mode 100644 index 00000000..60e2fa59 --- /dev/null +++ b/docs/implementation/HOL_LIGHT_IMPLEMENTATION.adoc @@ -0,0 +1,320 @@ +== HOL Light Backend Implementation for ECHIDNA + +=== Overview + +Complete production-ready implementation of HOL Light backend for +ECHIDNA theorem proving platform. + +*Status*: ✅ COMPLETE - Tier 2 "`Big Six`" Finalized *Complexity*: 3/5 +*Implementation Time*: ~2 weeks (as specified) *Lines of Code*: 1,167 +lines + +=== File Location + +`+/home/user/echidna/src/rust/provers/hol_light.rs+` + +=== Features Implemented + +==== 1. Core Backend Structure + +* *HolLightBackend* struct implementing `+ProverBackend+` trait +* Full async support with `+async-trait+` +* Session management with `+Mutex+` for thread safety +* Library loading system with lazy initialization + +==== 2. OCaml Process Interaction + +===== Session Management + +* `+HolLightSession+` struct for OCaml process lifecycle +* Automatic process spawning with `+ocaml+` executable +* Stdin/stdout communication via async I/O +* Graceful process termination on drop +* Command counter for debugging + +===== Features + +* Start OCaml session with HOL Light loaded +* Execute commands interactively +* Parse responses with smart termination detection +* Handle OCaml prompts and completion markers +* Support for long-running computations + +==== 3. HOL Light Syntax Parser + +===== Parser Structure + +* `+HolLightParser+` for parsing .ml files +* Tokenization with ML comment support (nested `+(* ... *)+`) +* Whitespace handling + +===== Supported Constructs + +* *Theorems*: `+let THEOREM = prove (statement, tactics);;+` +* *Definitions*: `+let NAME = new_definition term;;+` +* *Goals*: `+g term;;+` +* *Let bindings*: Generic ML bindings + +===== Term Representation + +* `+HolTerm+` enum with 4 variants: +** `+Var { name, ty }+` - Variables with optional types +** `+Const { name, ty }+` - Constants +** `+Comb { func, arg }+` - Function application +** `+Abs { var, var_type, body }+` - Lambda abstractions + +==== 4. Tactic System + +===== ECHIDNA to HOL Light Tactic Mapping + +[cols=",,",options="header",] +|=== +|ECHIDNA Tactic |HOL Light Tactic |Description +|`+Apply(thm)+` |`+MATCH_MP_TAC thm+` |Apply theorem +|`+Intro+` |`+GEN_TAC+` |Introduce variable +|`+Cases(term)+` |`+STRUCT_CASES_TAC+` |Case analysis +|`+Induction(term)+` |`+INDUCT_TAC+` |Induction +|`+Rewrite(thm)+` |`+REWRITE_TAC[thm]+` |Rewrite with theorem +|`+Simplify+` |`+SIMP_TAC[]+` |Simplification +|`+Reflexivity+` |`+REFL_TAC+` |Reflexivity of equality +|`+Assumption+` |`+ASM_REWRITE_TAC[]+` |Use assumptions +|`+Exact(term)+` |`+ACCEPT_TAC term+` |Exact proof term +|=== + +===== Supported HOL Light Tactics + +* `+REWRITE_TAC+` - Rewriting +* `+ASM_REWRITE_TAC+` - Assumption-based rewriting +* `+INDUCT_TAC+` - Induction +* `+STRUCT_CASES_TAC+` - Structural case analysis +* `+MESON_TAC+` - First-order automated reasoning +* `+SIMP_TAC+` - Simplification +* `+GEN_TAC+` - Universal generalization +* `+DISCH_TAC+` - Discharge assumption +* `+CONJ_TAC+` - Conjunction splitting +* `+MATCH_MP_TAC+` - Modus ponens matching +* `+ACCEPT_TAC+` - Accept exact term +* Custom tactics via `+Custom+` variant + +==== 5. Term Conversion + +===== HOL Light → Universal Term + +* Converts HOL Light’s 4-constructor representation to ECHIDNA’s +universal `+Term+` +* Handles variables, constants, combinations, and abstractions +* Smart application flattening (combines nested `+Comb+` into single +`+App+`) +* Type information preservation + +===== Universal Term → HOL Light Syntax + +* Backtick quoting for variables +* Lambda notation: `+\var. body+` +* Forall notation: `+!var : type. body+` +* Function application with proper parenthesization + +==== 6. Library Integration + +===== Standard Library Loading + +Automatically loads essential HOL Light libraries: - `+bool.ml+` - +Boolean logic - `+equal.ml+` - Equality - `+ind_defs.ml+` - Inductive +definitions - `+pair.ml+` - Pairs - `+nums.ml+` - Natural numbers - +`+arith.ml+` - Arithmetic - `+lists.ml+` - Lists + +===== Features + +* Lazy loading (loaded once on first use) +* Configurable library paths +* Graceful fallback if libraries not found +* Per-library error handling + +==== 7. ProverBackend Trait Implementation + +===== Required Methods + +[arabic] +. *`+version()+`* - Returns HOL Light session info +. *`+parse_file()+`* - Parse .ml files into `+ProofState+` +. *`+parse_string()+`* - Parse ML code from string +. *`+apply_tactic()+`* - Execute tactic in HOL Light session +. *`+verify_proof()+`* - Verify complete proof via OCaml +. *`+export()+`* - Export proof to HOL Light ML format +. *`+suggest_tactics()+`* - AI-powered tactic suggestions +. *`+search_theorems()+`* - Search using HOL Light’s search function + +===== Smart Features + +* *Tactic suggestions* based on goal structure: +** Suggest `+Intro+` for Pi types (universal quantification) +** Suggest `+Reflexivity+` and `+Simplify+` for equalities +** Suggest powerful tactics like `+MESON_TAC+` and `+ASM_MESON_TAC+` +** Suggest applicable theorems from context +* *Intelligent parsing* of OCaml output to detect proof completion +* *Temporary file handling* for verification with automatic cleanup + +==== 8. Export Format + +Generates production-ready HOL Light ML scripts: + +[source,ocaml] +---- +(* Generated by ECHIDNA *) +(* HOL Light proof script *) + +#use "hol.ml";; + +(* Definitions *) +let DEF_NAME = new_definition `DEF_NAME = body`;; + +(* Theorems *) +let THEOREM_NAME = prove + (statement, + TACTIC1;; + TACTIC2;; + ...);; + +(* Goals *) +g `goal_statement`;; +(* Apply tactics here *) +---- + +==== 9. Error Handling + +* Comprehensive error messages with context +* Graceful degradation when HOL Light not available +* Proper resource cleanup (files, processes) +* Result-based error propagation with `+anyhow+` + +==== 10. Testing + +Comprehensive test suite covering: - Backend creation and configuration +- Parser functionality (theorems, definitions, goals) - Term conversion +(bidirectional) - Tactic mapping - Export format validation - Tactic +suggestions - All major code paths + +=== Architecture Highlights + +==== Session Management Pattern + +[source,rust] +---- +pub struct HolLightBackend { + config: ProverConfig, + session: Mutex>, // Lazy initialization + library_loaded: Mutex, // One-time library loading +} +---- + +==== Async Command Execution + +[source,rust] +---- +async fn execute_command(&self, command: &str) -> Result { + self.get_session().await?; // Ensure session exists + let mut session = self.session.lock().await; + session.send_command(command).await +} +---- + +==== Smart Response Parsing + +Detects OCaml prompt completion via: - `+#+` prompt - `+val+` +declarations - `+Exception+` messages - `+Theorem+` markers - +`+No subgoals+` indicators + +=== Integration + +==== Module Structure + +* Registered in `+/home/user/echidna/src/rust/provers/mod.rs+` +* Factory method: +`+ProverFactory::create(ProverKind::HolLight, config)+` +* File extension detection: `+.ml+` → `+ProverKind::HolLight+` + +==== Dependencies + +All required dependencies already present in `+Cargo.toml+`: - `+tokio+` +- Async runtime - `+async-trait+` - Async trait support - `+anyhow+` - +Error handling - `+serde_json+` - JSON serialization - `+uuid+` - Unique +ID generation - `+tracing+` - Logging + +=== Compilation Status + +✅ *Compiles successfully* with `+cargo check --lib+` - Zero compilation +errors - Only minor warnings about unused imports in other files - Ready +for production use + +=== Comparison with Other Tier 2 Provers + +[cols=",,,",options="header",] +|=== +|Feature |Metamath |Mizar |*HOL Light* +|Complexity |2/5 |3/5 |*3/5* +|Implementation |1,015 lines |1,319 lines |*1,167 lines* +|Process Type |File-based |Multi-phase exec |*Interactive REPL* +|Tactic System |RPN stack |Natural language |*ML tactics* +|Parsing |Plain text |Complex grammar |*Backtick terms* +|Unique Feature |Minimalist |MML library |*LCF kernel* +|=== + +=== HOL Light Specifics + +==== What Makes HOL Light Unique + +[arabic] +. *LCF Architecture*: Small trusted kernel, all proofs go through it +. *OCaml Integration*: Theorem prover embedded in programming language +. *Interactive Development*: REPL-based proof construction +. *Meta-programming*: Proof automation via ML code +. *Conservative Extension*: New definitions must be conservative + +==== Implementation Challenges Solved + +[arabic] +. ✅ OCaml process lifecycle management +. ✅ Interactive session with async I/O +. ✅ ML syntax parsing (comments, backticks, structures) +. ✅ Response termination detection +. ✅ Library dependency handling +. ✅ Tactic execution and feedback parsing + +=== Next Steps + +==== For Production Deployment + +[arabic] +. Add more sophisticated ML parser (full OCaml grammar) +. Implement tactic proof tree parsing +. Add support for HOL Light’s goal stack +. Integration with John Harrison’s proof recording +. Support for Interactive mode with `+e()+`, `+p()+`, `+b()+` commands + +==== For Testing + +[arabic] +. Integration tests with actual HOL Light installation +. Benchmark against Metamath and Mizar +. Performance testing for large proofs +. Memory leak testing for long-running sessions + +=== Conclusion + +*HOL Light backend is COMPLETE and PRODUCTION-READY*, finalizing +ECHIDNA’s Tier 2 "`Big Six`" theorem prover support. + +This implementation provides: - Full OCaml process interaction - +Complete ML file parsing - Comprehensive tactic system (10+ tactics) - +Bidirectional term conversion - Library integration - Smart tactic +suggestions - Production-ready export format - Full error handling - +Comprehensive test coverage + +The HOL Light backend, along with Metamath and Mizar, completes the Tier +2 prover implementation phase of ECHIDNA, providing >70% standard +theorem coverage as specified in the project roadmap. + +''''' + +*Implementation Date*: 2025-11-22 *Status*: ✅ Complete - Ready for +Integration *Next Tier*: Tier 3 (PVS, ACL2) - Months 8-10 diff --git a/docs/implementation/HOL_LIGHT_IMPLEMENTATION.md b/docs/implementation/HOL_LIGHT_IMPLEMENTATION.md deleted file mode 100644 index 402f4d78..00000000 --- a/docs/implementation/HOL_LIGHT_IMPLEMENTATION.md +++ /dev/null @@ -1,305 +0,0 @@ -# HOL Light Backend Implementation for ECHIDNA - -## Overview - -Complete production-ready implementation of HOL Light backend for ECHIDNA theorem proving platform. - -**Status**: ✅ COMPLETE - Tier 2 "Big Six" Finalized -**Complexity**: 3/5 -**Implementation Time**: ~2 weeks (as specified) -**Lines of Code**: 1,167 lines - -## File Location - -`/home/user/echidna/src/rust/provers/hol_light.rs` - -## Features Implemented - -### 1. Core Backend Structure - -- **HolLightBackend** struct implementing `ProverBackend` trait -- Full async support with `async-trait` -- Session management with `Mutex` for thread safety -- Library loading system with lazy initialization - -### 2. OCaml Process Interaction - -#### Session Management -- `HolLightSession` struct for OCaml process lifecycle -- Automatic process spawning with `ocaml` executable -- Stdin/stdout communication via async I/O -- Graceful process termination on drop -- Command counter for debugging - -#### Features -- Start OCaml session with HOL Light loaded -- Execute commands interactively -- Parse responses with smart termination detection -- Handle OCaml prompts and completion markers -- Support for long-running computations - -### 3. HOL Light Syntax Parser - -#### Parser Structure -- `HolLightParser` for parsing .ml files -- Tokenization with ML comment support (nested `(* ... *)`) -- Whitespace handling - -#### Supported Constructs -- **Theorems**: `let THEOREM = prove (statement, tactics);;` -- **Definitions**: `let NAME = new_definition term;;` -- **Goals**: `g term;;` -- **Let bindings**: Generic ML bindings - -#### Term Representation -- `HolTerm` enum with 4 variants: - - `Var { name, ty }` - Variables with optional types - - `Const { name, ty }` - Constants - - `Comb { func, arg }` - Function application - - `Abs { var, var_type, body }` - Lambda abstractions - -### 4. Tactic System - -#### ECHIDNA to HOL Light Tactic Mapping - -| ECHIDNA Tactic | HOL Light Tactic | Description | -|----------------|------------------|-------------| -| `Apply(thm)` | `MATCH_MP_TAC thm` | Apply theorem | -| `Intro` | `GEN_TAC` | Introduce variable | -| `Cases(term)` | `STRUCT_CASES_TAC` | Case analysis | -| `Induction(term)` | `INDUCT_TAC` | Induction | -| `Rewrite(thm)` | `REWRITE_TAC[thm]` | Rewrite with theorem | -| `Simplify` | `SIMP_TAC[]` | Simplification | -| `Reflexivity` | `REFL_TAC` | Reflexivity of equality | -| `Assumption` | `ASM_REWRITE_TAC[]` | Use assumptions | -| `Exact(term)` | `ACCEPT_TAC term` | Exact proof term | - -#### Supported HOL Light Tactics -- `REWRITE_TAC` - Rewriting -- `ASM_REWRITE_TAC` - Assumption-based rewriting -- `INDUCT_TAC` - Induction -- `STRUCT_CASES_TAC` - Structural case analysis -- `MESON_TAC` - First-order automated reasoning -- `SIMP_TAC` - Simplification -- `GEN_TAC` - Universal generalization -- `DISCH_TAC` - Discharge assumption -- `CONJ_TAC` - Conjunction splitting -- `MATCH_MP_TAC` - Modus ponens matching -- `ACCEPT_TAC` - Accept exact term -- Custom tactics via `Custom` variant - -### 5. Term Conversion - -#### HOL Light → Universal Term -- Converts HOL Light's 4-constructor representation to ECHIDNA's universal `Term` -- Handles variables, constants, combinations, and abstractions -- Smart application flattening (combines nested `Comb` into single `App`) -- Type information preservation - -#### Universal Term → HOL Light Syntax -- Backtick quoting for variables -- Lambda notation: `\var. body` -- Forall notation: `!var : type. body` -- Function application with proper parenthesization - -### 6. Library Integration - -#### Standard Library Loading -Automatically loads essential HOL Light libraries: -- `bool.ml` - Boolean logic -- `equal.ml` - Equality -- `ind_defs.ml` - Inductive definitions -- `pair.ml` - Pairs -- `nums.ml` - Natural numbers -- `arith.ml` - Arithmetic -- `lists.ml` - Lists - -#### Features -- Lazy loading (loaded once on first use) -- Configurable library paths -- Graceful fallback if libraries not found -- Per-library error handling - -### 7. ProverBackend Trait Implementation - -#### Required Methods - -1. **`version()`** - Returns HOL Light session info -2. **`parse_file()`** - Parse .ml files into `ProofState` -3. **`parse_string()`** - Parse ML code from string -4. **`apply_tactic()`** - Execute tactic in HOL Light session -5. **`verify_proof()`** - Verify complete proof via OCaml -6. **`export()`** - Export proof to HOL Light ML format -7. **`suggest_tactics()`** - AI-powered tactic suggestions -8. **`search_theorems()`** - Search using HOL Light's search function - -#### Smart Features -- **Tactic suggestions** based on goal structure: - - Suggest `Intro` for Pi types (universal quantification) - - Suggest `Reflexivity` and `Simplify` for equalities - - Suggest powerful tactics like `MESON_TAC` and `ASM_MESON_TAC` - - Suggest applicable theorems from context -- **Intelligent parsing** of OCaml output to detect proof completion -- **Temporary file handling** for verification with automatic cleanup - -### 8. Export Format - -Generates production-ready HOL Light ML scripts: - -```ocaml -(* Generated by ECHIDNA *) -(* HOL Light proof script *) - -#use "hol.ml";; - -(* Definitions *) -let DEF_NAME = new_definition `DEF_NAME = body`;; - -(* Theorems *) -let THEOREM_NAME = prove - (statement, - TACTIC1;; - TACTIC2;; - ...);; - -(* Goals *) -g `goal_statement`;; -(* Apply tactics here *) -``` - -### 9. Error Handling - -- Comprehensive error messages with context -- Graceful degradation when HOL Light not available -- Proper resource cleanup (files, processes) -- Result-based error propagation with `anyhow` - -### 10. Testing - -Comprehensive test suite covering: -- Backend creation and configuration -- Parser functionality (theorems, definitions, goals) -- Term conversion (bidirectional) -- Tactic mapping -- Export format validation -- Tactic suggestions -- All major code paths - -## Architecture Highlights - -### Session Management Pattern -```rust -pub struct HolLightBackend { - config: ProverConfig, - session: Mutex>, // Lazy initialization - library_loaded: Mutex, // One-time library loading -} -``` - -### Async Command Execution -```rust -async fn execute_command(&self, command: &str) -> Result { - self.get_session().await?; // Ensure session exists - let mut session = self.session.lock().await; - session.send_command(command).await -} -``` - -### Smart Response Parsing -Detects OCaml prompt completion via: -- `#` prompt -- `val` declarations -- `Exception` messages -- `Theorem` markers -- `No subgoals` indicators - -## Integration - -### Module Structure -- Registered in `/home/user/echidna/src/rust/provers/mod.rs` -- Factory method: `ProverFactory::create(ProverKind::HolLight, config)` -- File extension detection: `.ml` → `ProverKind::HolLight` - -### Dependencies -All required dependencies already present in `Cargo.toml`: -- `tokio` - Async runtime -- `async-trait` - Async trait support -- `anyhow` - Error handling -- `serde_json` - JSON serialization -- `uuid` - Unique ID generation -- `tracing` - Logging - -## Compilation Status - -✅ **Compiles successfully** with `cargo check --lib` -- Zero compilation errors -- Only minor warnings about unused imports in other files -- Ready for production use - -## Comparison with Other Tier 2 Provers - -| Feature | Metamath | Mizar | **HOL Light** | -|---------|----------|-------|---------------| -| Complexity | 2/5 | 3/5 | **3/5** | -| Implementation | 1,015 lines | 1,319 lines | **1,167 lines** | -| Process Type | File-based | Multi-phase exec | **Interactive REPL** | -| Tactic System | RPN stack | Natural language | **ML tactics** | -| Parsing | Plain text | Complex grammar | **Backtick terms** | -| Unique Feature | Minimalist | MML library | **LCF kernel** | - -## HOL Light Specifics - -### What Makes HOL Light Unique - -1. **LCF Architecture**: Small trusted kernel, all proofs go through it -2. **OCaml Integration**: Theorem prover embedded in programming language -3. **Interactive Development**: REPL-based proof construction -4. **Meta-programming**: Proof automation via ML code -5. **Conservative Extension**: New definitions must be conservative - -### Implementation Challenges Solved - -1. ✅ OCaml process lifecycle management -2. ✅ Interactive session with async I/O -3. ✅ ML syntax parsing (comments, backticks, structures) -4. ✅ Response termination detection -5. ✅ Library dependency handling -6. ✅ Tactic execution and feedback parsing - -## Next Steps - -### For Production Deployment -1. Add more sophisticated ML parser (full OCaml grammar) -2. Implement tactic proof tree parsing -3. Add support for HOL Light's goal stack -4. Integration with John Harrison's proof recording -5. Support for Interactive mode with `e()`, `p()`, `b()` commands - -### For Testing -1. Integration tests with actual HOL Light installation -2. Benchmark against Metamath and Mizar -3. Performance testing for large proofs -4. Memory leak testing for long-running sessions - -## Conclusion - -**HOL Light backend is COMPLETE and PRODUCTION-READY**, finalizing ECHIDNA's Tier 2 "Big Six" theorem prover support. - -This implementation provides: -- Full OCaml process interaction -- Complete ML file parsing -- Comprehensive tactic system (10+ tactics) -- Bidirectional term conversion -- Library integration -- Smart tactic suggestions -- Production-ready export format -- Full error handling -- Comprehensive test coverage - -The HOL Light backend, along with Metamath and Mizar, completes the Tier 2 prover implementation phase of ECHIDNA, providing >70% standard theorem coverage as specified in the project roadmap. - ---- - -**Implementation Date**: 2025-11-22 -**Status**: ✅ Complete - Ready for Integration -**Next Tier**: Tier 3 (PVS, ACL2) - Months 8-10 diff --git a/docs/implementation/MIZAR_IMPLEMENTATION_SUMMARY.adoc b/docs/implementation/MIZAR_IMPLEMENTATION_SUMMARY.adoc new file mode 100644 index 00000000..2f330e26 --- /dev/null +++ b/docs/implementation/MIZAR_IMPLEMENTATION_SUMMARY.adoc @@ -0,0 +1,936 @@ +== Mizar Backend Implementation Summary + +=== ✅ COMPLETE - Production-Ready Implementation + +*Date*: November 22, 2025 *Status*: Fully Implemented & Tested +*Location*: `+/home/user/echidna/src/rust/provers/mizar.rs+` + +''''' + +=== Implementation Statistics + +[cols=",",options="header",] +|=== +|Metric |Value +|*Total Lines* |1,318 +|*Implementation Time* |Complete +|*Test Coverage* |2/2 tests passing +|*Compilation Status* |✅ Success (warnings only) +|*Complexity Rating* |3/5 (Tier 2) +|*Target Timeframe* |Months 5-7 (as per 12-month roadmap) +|=== + +''''' + +=== What Was Implemented + +==== 1. Core Backend (`+MizarBackend+`) + +✅ *Complete ProverBackend trait implementation*: - `+kind()+` - Returns +ProverKind::Mizar - `+version()+` - Gets Mizar verifier version - +`+parse_file()+` - Parses .miz files - `+parse_string()+` - Parses Mizar +content from strings - `+apply_tactic()+` - Applies proof tactics - +`+verify_proof()+` - Full two-phase verification - `+export()+` - +Exports to valid Mizar format - `+suggest_tactics()+` - Tactical +suggestions - `+search_theorems()+` - MML library search - `+config()+` +/ `+set_config()+` - Configuration management + +==== 2. Mizar Article Parser + +✅ *Environ Section Parsing*: - `+vocabularies+` - Mathematical +vocabulary declarations - `+notations+` - Notation system imports - +`+constructors+` - Type constructor declarations - `+registrations+` - +Type registrations - `+theorems+` - External theorem references - +`+requirements+` - System requirements (REAL, NUMERALS, SUBSET, BOOLE, +ARITHM) + +✅ *Content Parsing*: - Theorem statements with natural language syntax +- Full proof structure parsing - Definition handling (stubs for complex +definitions) - Scheme declarations (basic support) + +✅ *Proof Step Parsing*: - `+let+` - Variable introduction with type +annotations - `+assume+` - Hypothesis assumption (with optional labels) +- `+thus+` / `+hence+` - Proof steps with justifications - `+per cases+` +- Case analysis structures - `+take+` - Witness provision - `+consider+` +- Existential elimination (stub) + +==== 3. Verification System + +✅ *Two-Phase Mizar Verification*: + +*Phase 1: Accommodation (`+mizf+`)*: - Environment variable setup +(`+MIZFILES+`) - Environ directive processing - MML article loading - +Dependency resolution + +*Phase 2: Verification (`+verifier+`)*: - Type checking - Proof step +validation - Justification verification - Error collection with +line/column precision + +==== 4. Term Conversion System + +✅ *Mizar → Universal Term*: - Variables and constants - Function +applications - Quantifiers (`+for+` → Pi, `+ex+` → Exists via Lambda) - +Binary operators (=, c=, /, /, &, or, implies, +, -, *, /, <, >, <=, >=) +- Unary operators - Type annotations + +✅ *Universal Term → Mizar*: - Pretty-printing with natural language +style - Operator translation - Quantifier formatting +(`+for X being Type holds ...+`) - Parenthesization + +==== 5. Error Handling + +✅ *Sophisticated Error Parsing*: - Two error message formats supported: +- `+* line col error_code message+` (Mizar native) - +`+filename:line:col: message+` (standard) - Structured error +representation: - Line number - Column number - Error code - Descriptive +message - Warning collection and reporting + +==== 6. MML Integration + +✅ *Mizar Mathematical Library Support*: - MML path configuration +(environment variable or default) - Theorem search in `+mml.lar+` - +Case-insensitive pattern matching - Result limiting (up to 100 matches) +- Article reference resolution + +==== 7. Tactic System + +✅ *Standard Tactics*: - `+Apply(theorem)+` - Apply MML or local theorem +- `+Intro(name)+` - Introduce universal quantifier (implements `+let+`) +- `+Cases(term)+` - Case analysis (implements `+per cases+`) - +`+Assumption+` - Solve goal with hypothesis - `+Exact(term)+` - Provide +exact proof term + +✅ *Mizar-Specific Tactics*: - Custom tactic support: - `+thus+` - +Assert proof step - `+hence+` - Assert with implicit assumption use - +`+per_cases+` - Explicit case analysis + +==== 8. Export Functionality + +✅ *Mizar Article Generation*: - Standard environ section generation - +Theorem formatting with proper syntax - Goal representation - Proof stub +generation (`+thus thesis;+`) - Valid Mizar article structure + +''''' + +=== Test Coverage + +==== Unit Tests (2/2 passing) + +✅ *test_mizar_parser_basic*: - Tests basic environ parsing - Tests +theorem parsing - Tests proof structure parsing - Validates article +structure + +✅ *test_mizar_backend_creation*: - Tests backend instantiation - Tests +ProverKind identification - Validates configuration + +==== Integration Test Files + +✅ *basic.miz* (10 theorems): - Simple equality properties (reflexivity, +symmetry, transitivity) - Set operations (union/intersection with self) +- Empty set properties - Subset relations - *Complexity*: Beginner + +✅ *propositional.miz* (10 theorems): - De Morgan’s laws (2 theorems) - +Distributive laws (2 theorems) - Commutative laws (2 theorems) - +Associative laws (2 theorems) - Complex case analysis proofs - +*Complexity*: Intermediate + +✅ *numbers.miz* (27 theorems): - Natural number properties - +Commutativity (addition, multiplication) - Associativity (addition, +multiplication) - Distributivity (left, right) - Order properties +(transitivity, antisymmetry, monotonicity) - Cancellation laws +(addition, multiplication) - Advanced theorems (square expansion, +difference of squares) - Min/max properties - *Complexity*: Advanced + +''''' + +=== Technical Highlights + +==== Parser Architecture + +*Recursive Descent Parser*: - Hand-written for maximum control and error +recovery - O(n) time complexity - Minimal memory allocations - Robust +whitespace and comment handling + +*Key Features*: - Natural language syntax support - Operator precedence +handling - Label parsing (`+A1:+`, `+A2:+`, etc.) - Justification +parsing (`+by XBOOLE_0:def 3+`) - Error recovery at statement boundaries + +==== Verification Pipeline + +.... +.miz file → Parser → ProofState + ↓ + mizf (accommodation) + ↓ + verifier (checking) + ↓ + Error Parsing + ↓ + VerificationResult +.... + +==== Memory Efficiency + +* Streaming file operations +* Temporary files auto-cleaned +* Efficient tree structures +* Minimal cloning + +==== Error Recovery + +* Graceful handling of malformed input +* Detailed error locations +* Continuation past errors when possible +* User-friendly error messages + +''''' + +=== File Structure + +.... +echidna/ +├── src/rust/provers/ +│ └── mizar.rs (1,318 lines) +│ ├── MizarBackend struct +│ ├── ProverBackend trait impl +│ ├── MizarParser struct +│ ├── MizarArticle/Theorem/Proof structures +│ ├── Term conversion (mizar_to_term, term_to_mizar) +│ ├── Verification (run_mizf, run_verifier) +│ ├── Error parsing +│ └── Unit tests +├── proofs/mizar/ +│ ├── basic.miz (147 lines, 10 theorems) +│ ├── propositional.miz (291 lines, 10 theorems) +│ └── numbers.miz (280 lines, 27 theorems) +└── docs/ + └── MIZAR_BACKEND.md (comprehensive documentation) +.... + +''''' + +=== Dependencies Added + +==== Cargo.toml Updates + +[source,toml] +---- +[dependencies] +uuid = { version = "1.6", features = ["v4"] } # For temp file generation +---- + +All other dependencies were already present: - `+async-trait+` - Async +trait support - `+anyhow+` - Error handling - `+tokio+` - Async runtime +- `+serde+` - Serialization + +''''' + +=== Compilation Status + +✅ *Successfully compiles*: + +[source,bash] +---- +$ cargo check --lib + Finished `dev` profile [unoptimized + debuginfo] target(s) in 10.63s +---- + +✅ *Tests pass*: + +[source,bash] +---- +$ cargo test --lib mizar +running 2 tests +test provers::mizar::tests::test_mizar_backend_creation ... ok +test provers::mizar::tests::test_mizar_parser_basic ... ok + +test result: ok. 2 passed; 0 failed; 0 ignored +---- + +*Warnings*: 44 warnings (mostly unused variables in stub +implementations, not in Mizar backend) + +''''' + +=== Integration with ECHIDNA + +==== ProverFactory Integration + +The Mizar backend is fully integrated via `+ProverFactory+`: + +[source,rust] +---- +// In provers/mod.rs +impl ProverFactory { + pub fn create(kind: ProverKind, config: ProverConfig) + -> anyhow::Result> + { + match kind { + // ... other provers ... + ProverKind::Mizar => Ok(Box::new(mizar::MizarBackend::new(config))), + // ... other provers ... + } + } + + pub fn detect_from_file(path: &PathBuf) -> Option { + path.extension()?.to_str().and_then(|ext| match ext { + // ... other extensions ... + "miz" => Some(ProverKind::Mizar), + // ... other extensions ... + }) + } +} +---- + +==== Universal Term System + +Full bidirectional conversion ensures: - ✅ Mizar proofs can be imported +into ECHIDNA - ✅ ECHIDNA proofs can be exported to Mizar - ✅ +Cross-prover theorem sharing - ✅ Uniform proof representation + +==== Aspect Tagging + +Theorems support aspect classification: - Mathematical domain (logic, +algebra, topology, etc.) - Proof techniques (induction, case analysis, +etc.) - Difficulty level (beginner, intermediate, advanced) - +Dependencies (MML articles required) + +''''' + +=== Future Enhancements + +While the implementation is complete and production-ready, these +enhancements could be added: + +==== Parser Completeness + +* [ ] Full definition syntax (mode, predicate, functor, attribute) +* [ ] Complete scheme support with parameters +* [ ] Cluster and registration parsing +* [ ] Consider statement with full syntax + +==== Performance + +* [ ] MML indexing for faster theorem search +* [ ] Parallel verification of multiple theorems +* [ ] Caching of parsed MML articles + +==== Neural Integration + +* [ ] ML-based premise selection from MML +* [ ] Proof step suggestion using neural networks +* [ ] Automatic proof completion + +==== Interactive Features + +* [ ] Real-time verification as-you-type +* [ ] IDE integration (LSP server) +* [ ] Proof visualization +* [ ] Step-by-step debugging + +''''' + +=== Comparison with Other Provers + +[cols=",,,,",options="header",] +|=== +|Feature |Mizar |Agda |Coq |Lean +|Lines of Code |1,318 |495 |1,112 |26 (stub) +|Parser |Complete |Complete |Complete |Stub +|Verification |External |External |External |- +|Term Conversion |✅ |✅ |✅ |❌ +|Export |✅ |✅ |✅ |❌ +|Library Search |✅ (MML) |❌ |❌ |❌ +|Natural Language |✅ |❌ |❌ |❌ +|Complexity |3/5 |3/5 |3/5 |3/5 +|Tier |2 |1 |1 |1 +|=== + +''''' + +=== Key Achievements + +==== ✅ Complete Implementation + +* All required components implemented +* No TODO comments in critical paths +* Production-ready code quality + +==== ✅ Robust Parsing + +* Handles complex Mizar syntax +* Supports 47+ test theorems across 3 files +* Error recovery and reporting + +==== ✅ Full Verification + +* Two-phase Mizar pipeline +* External tool integration +* Detailed error messages + +==== ✅ Universal Integration + +* Seamless ProverBackend trait implementation +* Term conversion both directions +* Factory pattern integration + +==== ✅ Well Tested + +* Unit tests passing +* Integration test files +* Real-world Mizar examples + +==== ✅ Documented + +* Comprehensive inline documentation +* Full backend documentation (MIZAR_BACKEND.md) +* Usage examples +* Architecture diagrams + +''''' + +=== Conclusion + +The Mizar backend for ECHIDNA is *complete, tested, and +production-ready*. It provides: + +[arabic] +. ✅ *Full Mizar language support* for common theorem proving tasks +. ✅ *Robust parsing* with excellent error recovery +. ✅ *External verifier integration* (mizf + verifier) +. ✅ *MML library search* capabilities +. ✅ *Bidirectional term conversion* for cross-prover interoperability +. ✅ *Comprehensive test coverage* with real-world examples +. ✅ *Production-ready code quality* with proper error handling + +The implementation demonstrates ECHIDNA’s capability to integrate +diverse theorem provers with natural language-like syntax, paving the +way for the remaining Tier 2 provers (Metamath, HOL Light) and beyond. + +''''' + +*Next Steps*: 1. Deploy to actual ECHIDNA repository (Priority 1 from +CLAUDE.md) 2. Continue with Metamath implementation (easiest Tier 2, 2/5 +complexity) 3. Integrate neural premise selection for MML theorem +suggestions 4. Add interactive proof development features + +''''' + +*Implementation Team*: ECHIDNA Project *License*: MIT OR Palimpsest-0.6 +*Repository*: https://github.com/hyperpolymath/echidna *Documentation*: +/home/user/echidna/docs/MIZAR_BACKEND.md + +''''' + +== Appendix: Mizar Backend Reference + +_The following content was merged in from `+docs/MIZAR_BACKEND.md+` on +2026-05-25 when the two parallel "`backend`" and "`implementation +summary`" docs were consolidated. Sections may overlap with the summary +above and will be naturally integrated in a future doc-polish pass._ + +*File*: `+/home/user/echidna/src/rust/provers/mizar.rs+` *Status*: ✅ +Complete Production-Ready Implementation *Lines of Code*: 1,318 +*Complexity*: 3/5 (Tier 2) *Estimated Implementation Time*: 2 weeks + +=== Overview + +The Mizar backend is a complete, production-ready implementation for +integrating the Mizar theorem prover into ECHIDNA. Mizar is unique among +theorem provers for its natural-language-like syntax and the Mizar +Mathematical Library (MML), one of the largest formalized mathematics +collections in the world. + +=== Architecture + +==== Core Components + +===== 1. *MizarBackend Struct* + +[source,rust] +---- +pub struct MizarBackend { + config: ProverConfig, + mml_path: PathBuf, +} +---- + +The main backend struct implementing the `+ProverBackend+` trait. It +manages: - Prover configuration (executable path, timeout, etc.) - MML +(Mizar Mathematical Library) path - Two-phase verification process +(accommodation + analysis) + +===== 2. *Mizar Article Parser* + +The parser handles complete Mizar article syntax: + +*Environ Section*: - `+vocabularies+` - Mathematical vocabulary - +`+notations+` - Notation definitions - `+constructors+` - Type +constructors - `+registrations+` - Type registrations - `+theorems+` - +Referenced theorems - `+requirements+` - System requirements + +*Content*: - Theorem statements with proofs - Definitions (types, +functions, predicates) - Schemes (proof schemas) + +*Proof Structures*: - `+let+` - Variable introduction - `+assume+` - +Hypothesis assumption - `+thus+` / `+hence+` - Proof steps with +justifications - `+per cases+` - Case analysis - `+take+` - Witness +provision - `+consider+` - Existential elimination + +===== 3. *Mizar Verification System* + +Implements Mizar’s two-phase verification: + +*Phase 1: Accommodation (`+mizf+`)* - Processes environ directives - +Loads required articles from MML - Prepares verification environment + +*Phase 2: Verification (`+verifier+`)* - Type checks all terms - +Verifies proof correctness - Generates error messages with line/column +information + +===== 4. *Term Conversion* + +Bidirectional conversion between: - Mizar’s natural language terms - +ECHIDNA’s universal `+Term+` representation + +Handles: - Quantifiers (`+for+`/`+ex+`) - Binary operators (`+=+`, +`+c=+`, `+\/+`, `+/\+`, `+&+`, `+or+`, `+implies+`) - Function +application - Type annotations + +===== 5. *Error Parsing* + +Sophisticated error message parsing supporting two formats: - +`+* line col error_code message+` (Mizar format) - +`+filename:line:col: message+` (standard format) + +Extracts: - Line and column numbers - Error codes - Descriptive messages + +=== Implementation Details + +==== Mizar Term Representation + +[source,rust] +---- +enum MizarTerm { + Variable(String), + Constant(String), + Application { func: Box, args: Vec }, + Quantifier { kind: QuantifierKind, var: String, var_type: Box, body: Box }, + BinaryOp { op: String, left: Box, right: Box }, + UnaryOp { op: String, operand: Box }, +} +---- + +==== Parser Implementation + +The `+MizarParser+` uses a hand-written recursive descent parser: + +*Key Methods*: - `+parse_environ()+` - Parse environment directives - +`+parse_theorem()+` - Parse theorem statements - `+parse_proof()+` - +Parse proof structures - `+parse_formula()+` - Parse logical formulas - +`+parse_term()+` - Parse mathematical terms - +`+skip_whitespace_and_comments()+` - Handle `+::+` comments + +*Features*: - Robust error recovery - Support for Mizar’s operator +precedence - Handling of labeled statements (`+A1:+`, `+A2:+`, etc.) - +Justification parsing (`+by XBOOLE_0:def 3+`) + +==== Verification Integration + +[source,rust] +---- +async fn verify_file(&self, path: &Path) -> Result +---- + +Executes the full Mizar verification pipeline: + +[arabic] +. *Run `+mizf+`* (accommodation) +* Set `+MIZFILES+` environment variable to MML path +* Process environ directives +* Load required articles +. *Run `+verifier+`* (type checking and proof verification) +* Verify all proof steps +* Check type correctness +* Validate justifications +. *Parse Results* +* Extract errors and warnings +* Return success/failure status + +==== MML Integration + +The backend integrates with the Mizar Mathematical Library (MML): + +[source,rust] +---- +async fn search_theorems(&self, pattern: &str) -> Result> +---- + +* Searches `+$MIZFILES/mml.lar+` for theorem references +* Case-insensitive pattern matching +* Returns up to 100 matching theorems + +==== Tactic Application + +Implements standard and Mizar-specific tactics: + +*Standard Tactics*: - `+Apply(theorem)+` - Apply a theorem - +`+Intro(name)+` - Introduce variables (implements `+let+`) - +`+Cases(term)+` - Case analysis (implements `+per cases+`) - +`+Assumption+` - Solve with hypothesis - `+Exact(term)+` - Provide exact +proof term + +*Mizar-Specific Tactics*: + +[source,rust] +---- +Tactic::Custom { + prover: "mizar", + command: "thus" | "hence" | "per_cases", + args: .. +} +---- + +==== Export Functionality + +[source,rust] +---- +async fn export(&self, state: &ProofState) -> Result +---- + +Generates valid Mizar articles from proof states: + +[source,mizar] +---- +:: Generated by ECHIDNA +:: Mizar article + +environ + vocabularies SUBSET_1, XBOOLE_0, TARSKI; + notations TARSKI, XBOOLE_0; + constructors TARSKI, XBOOLE_0; + registrations XBOOLE_0; + +begin + +theorem TheoremName: + for P being set holds P = P +proof + thus thesis; +end; +---- + +=== Test Cases + +The implementation includes test cases in +`+/home/user/echidna/proofs/mizar/+`: + +==== 1. `+basic.miz+` - Basic Logical Proofs + +* Simple equality theorems (reflexivity, symmetry, transitivity) +* Set operations (union, intersection with self) +* Empty set properties +* Subset relations + +*Example*: + +[source,mizar] +---- +theorem Th1: + for P, Q being set holds P = Q implies Q = P +proof + let P, Q be set; + assume P = Q; + thus Q = P; +end; +---- + +==== 2. `+propositional.miz+` - Propositional Logic + +* De Morgan’s laws for sets +* Distributive laws +* Commutative and associative laws +* Complex proofs with `+per cases+` + +*Example*: + +[source,mizar] +---- +theorem DeMorgan1: + for X, Y, Z being set holds + Z \ (X \/ Y) = (Z \ X) /\ (Z \ Y) +proof + let X, Y, Z be set; + thus Z \ (X \/ Y) c= (Z \ X) /\ (Z \ Y) proof ... end; + thus (Z \ X) /\ (Z \ Y) c= Z \ (X \/ Y) proof ... end; +end; +---- + +==== 3. `+numbers.miz+` - Arithmetic Properties + +* Natural number properties +* Commutativity and associativity of addition/multiplication +* Distributivity +* Order properties (transitivity, antisymmetry) +* Cancellation laws +* Advanced theorems (square formulas, min/max) + +*Example*: + +[source,mizar] +---- +theorem AddSquare: + for m, n being Nat holds + (m + n) * (m + n) = m * m + 2 * m * n + n * n +proof + let m, n be Nat; + thus (m + n) * (m + n) + = (m + n) * m + (m + n) * n + .= m * m + n * m + (m + n) * n + ... +end; +---- + +=== Usage Examples + +==== Creating a Backend + +[source,rust] +---- +use echidna::provers::{ProverConfig, ProverKind, ProverFactory}; +use std::path::PathBuf; + +let mut config = ProverConfig::default(); +config.executable = PathBuf::from("/usr/local/bin/verifier"); +config.timeout = 300; // 5 minutes + +let backend = ProverFactory::create(ProverKind::Mizar, config)?; +---- + +==== Parsing a Mizar File + +[source,rust] +---- +let proof_state = backend.parse_file( + PathBuf::from("/home/user/echidna/proofs/mizar/basic.miz") +).await?; + +println!("Goals: {}", proof_state.goals.len()); +println!("Theorems: {}", proof_state.context.theorems.len()); +---- + +==== Applying Tactics + +[source,rust] +---- +// Introduce a variable +let new_state = backend.apply_tactic( + &proof_state, + &Tactic::Intro(Some("x".to_string())) +).await?; + +// Apply a theorem +let new_state = backend.apply_tactic( + &new_state, + &Tactic::Apply("XBOOLE_0:def_3".to_string()) +).await?; + +// Mizar-specific tactic +let new_state = backend.apply_tactic( + &new_state, + &Tactic::Custom { + prover: "mizar".to_string(), + command: "thus".to_string(), + args: vec![], + } +).await?; +---- + +==== Verifying a Proof + +[source,rust] +---- +// Complete the proof +let final_state = /* ... complete all goals ... */; + +// Verify +let is_valid = backend.verify_proof(&final_state).await?; +if is_valid { + println!("✓ Proof verified successfully!"); +} else { + println!("✗ Proof verification failed"); +} +---- + +==== Searching MML + +[source,rust] +---- +// Search for theorems about sets +let results = backend.search_theorems("intersection").await?; + +for theorem in results { + println!("Found: {}", theorem); +} +---- + +=== Technical Considerations + +==== Environment Setup + +Required environment variables: - `+MIZFILES+` - Path to MML directory +(default: `+/usr/local/share/mizar+`) + +Required executables: - `+mizf+` - Accommodation processor - +`+verifier+` - Proof verifier + +==== Error Handling + +The implementation provides detailed error information: + +[source,rust] +---- +#[derive(Debug, Clone)] +struct MizarError { + line: usize, + column: usize, + code: String, + message: String, +} +---- + +Errors are reported at the exact location in the source file, making +debugging straightforward. + +==== Performance + +* *Parsing*: ~O(n) where n is file size +* *Verification*: Depends on Mizar verifier (typically seconds for +simple proofs) +* *MML Search*: O(m) where m is MML size, with early termination at 100 +results + +==== Memory Usage + +* Efficient recursive descent parser with minimal allocations +* Streaming file operations for large MML searches +* Temporary files cleaned up automatically + +=== Integration Points + +==== With Neural Selector + +[source,rust] +---- +let suggestions = backend.suggest_tactics(&proof_state, 10).await?; +// Returns tactically sound suggestions based on goal structure +---- + +==== With Aspect Tagger + +Theorems can be tagged with mathematical aspects: - Set theory - Logic - +Arithmetic - Topology - etc. + +==== With Universal Term System + +Full bidirectional conversion ensures: - Mizar proofs can be translated +to other provers - Proofs from other systems can be exported to Mizar - +Cross-prover theorem databases + +=== Limitations and Future Work + +==== Current Limitations + +[arabic] +. *Simplified Definition Parsing*: Full definition syntax not yet +implemented +. *Scheme Parsing*: Basic scheme support only +. *Proof Checking*: Relies on external Mizar verifier +. *Neural Suggestions*: Basic heuristics (can be enhanced with ML +models) + +==== Planned Enhancements + +[arabic] +. *Complete Parser*: Full Mizar language support including: +* Definitions (mode, predicate, functor, attribute) +* Schemes with full parameter handling +* Clusters and registrations +. *Proof Reconstruction*: Native proof checking without external +verifier +. *MML Indexing*: Fast indexed search of MML theorems +. *Interactive Mode*: Real-time proof assistant integration +. *Neural Premise Selection*: ML-based theorem suggestion from MML + +=== Testing + +==== Unit Tests + +[source,rust] +---- +#[test] +fn test_mizar_parser_basic() { + let content = r#" +environ + vocabularies SUBSET_1, XBOOLE_0; +begin + +theorem Th1: + for P being set holds P = P +proof + let P be set; + thus P = P; +end; +"#; + + let mut parser = MizarParser::new(content); + let article = parser.parse().unwrap(); + assert_eq!(article.theorems.len(), 1); +} +---- + +==== Integration Tests + +Test against actual Mizar files: - `+basic.miz+` - 10 theorems - +`+propositional.miz+` - 10 theorems (complex proofs) - `+numbers.miz+` - +27 theorems (arithmetic) + +=== Dependencies + +*Rust Crates*: - `+async-trait+` - Async trait support - `+anyhow+` - +Error handling - `+tokio+` - Async runtime - `+serde+` - Serialization - +`+uuid+` - Temporary file generation + +*External*: - Mizar system (mizf, verifier) - MML (Mizar Mathematical +Library) + +=== Performance Benchmarks + +[cols=",,",options="header",] +|=== +|Operation |Time |Notes +|Parse basic.miz |~5ms |147 lines +|Parse propositional.miz |~12ms |291 lines +|Parse numbers.miz |~15ms |280 lines +|Verify simple theorem |~100ms |External verifier +|Search MML |~50ms |Pattern matching +|=== + +=== Conclusion + +The Mizar backend provides a complete, production-ready integration for +ECHIDNA. It handles: + +✅ Full article parsing with robust error recovery ✅ Two-phase +verification integration ✅ MML library search ✅ Bidirectional term +conversion ✅ Detailed error reporting ✅ Tactic application and proof +state management ✅ Export to valid Mizar format + +The implementation is well-tested, documented, and ready for use in the +full ECHIDNA system. + +''''' + +*Implementation Date*: November 2025 *Author*: ECHIDNA Project Team +*License*: MIT OR Palimpsest-0.6 *Tier*: 2 (Big Six completion) +*Priority*: Months 5-7 of 12-month roadmap diff --git a/docs/implementation/MIZAR_IMPLEMENTATION_SUMMARY.md b/docs/implementation/MIZAR_IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index f9921ffb..00000000 --- a/docs/implementation/MIZAR_IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,970 +0,0 @@ -# Mizar Backend Implementation Summary - -## ✅ COMPLETE - Production-Ready Implementation - -**Date**: November 22, 2025 -**Status**: Fully Implemented & Tested -**Location**: `/home/user/echidna/src/rust/provers/mizar.rs` - ---- - -## Implementation Statistics - -| Metric | Value | -|--------|-------| -| **Total Lines** | 1,318 | -| **Implementation Time** | Complete | -| **Test Coverage** | 2/2 tests passing | -| **Compilation Status** | ✅ Success (warnings only) | -| **Complexity Rating** | 3/5 (Tier 2) | -| **Target Timeframe** | Months 5-7 (as per 12-month roadmap) | - ---- - -## What Was Implemented - -### 1. Core Backend (`MizarBackend`) - -✅ **Complete ProverBackend trait implementation**: -- `kind()` - Returns ProverKind::Mizar -- `version()` - Gets Mizar verifier version -- `parse_file()` - Parses .miz files -- `parse_string()` - Parses Mizar content from strings -- `apply_tactic()` - Applies proof tactics -- `verify_proof()` - Full two-phase verification -- `export()` - Exports to valid Mizar format -- `suggest_tactics()` - Tactical suggestions -- `search_theorems()` - MML library search -- `config()` / `set_config()` - Configuration management - -### 2. Mizar Article Parser - -✅ **Environ Section Parsing**: -- `vocabularies` - Mathematical vocabulary declarations -- `notations` - Notation system imports -- `constructors` - Type constructor declarations -- `registrations` - Type registrations -- `theorems` - External theorem references -- `requirements` - System requirements (REAL, NUMERALS, SUBSET, BOOLE, ARITHM) - -✅ **Content Parsing**: -- Theorem statements with natural language syntax -- Full proof structure parsing -- Definition handling (stubs for complex definitions) -- Scheme declarations (basic support) - -✅ **Proof Step Parsing**: -- `let` - Variable introduction with type annotations -- `assume` - Hypothesis assumption (with optional labels) -- `thus` / `hence` - Proof steps with justifications -- `per cases` - Case analysis structures -- `take` - Witness provision -- `consider` - Existential elimination (stub) - -### 3. Verification System - -✅ **Two-Phase Mizar Verification**: - -**Phase 1: Accommodation (`mizf`)**: -- Environment variable setup (`MIZFILES`) -- Environ directive processing -- MML article loading -- Dependency resolution - -**Phase 2: Verification (`verifier`)**: -- Type checking -- Proof step validation -- Justification verification -- Error collection with line/column precision - -### 4. Term Conversion System - -✅ **Mizar → Universal Term**: -- Variables and constants -- Function applications -- Quantifiers (`for` → Pi, `ex` → Exists via Lambda) -- Binary operators (=, c=, \/, /\, &, or, implies, +, -, *, /, <, >, <=, >=) -- Unary operators -- Type annotations - -✅ **Universal Term → Mizar**: -- Pretty-printing with natural language style -- Operator translation -- Quantifier formatting (`for X being Type holds ...`) -- Parenthesization - -### 5. Error Handling - -✅ **Sophisticated Error Parsing**: -- Two error message formats supported: - - `* line col error_code message` (Mizar native) - - `filename:line:col: message` (standard) -- Structured error representation: - - Line number - - Column number - - Error code - - Descriptive message -- Warning collection and reporting - -### 6. MML Integration - -✅ **Mizar Mathematical Library Support**: -- MML path configuration (environment variable or default) -- Theorem search in `mml.lar` -- Case-insensitive pattern matching -- Result limiting (up to 100 matches) -- Article reference resolution - -### 7. Tactic System - -✅ **Standard Tactics**: -- `Apply(theorem)` - Apply MML or local theorem -- `Intro(name)` - Introduce universal quantifier (implements `let`) -- `Cases(term)` - Case analysis (implements `per cases`) -- `Assumption` - Solve goal with hypothesis -- `Exact(term)` - Provide exact proof term - -✅ **Mizar-Specific Tactics**: -- Custom tactic support: - - `thus` - Assert proof step - - `hence` - Assert with implicit assumption use - - `per_cases` - Explicit case analysis - -### 8. Export Functionality - -✅ **Mizar Article Generation**: -- Standard environ section generation -- Theorem formatting with proper syntax -- Goal representation -- Proof stub generation (`thus thesis;`) -- Valid Mizar article structure - ---- - -## Test Coverage - -### Unit Tests (2/2 passing) - -✅ **test_mizar_parser_basic**: -- Tests basic environ parsing -- Tests theorem parsing -- Tests proof structure parsing -- Validates article structure - -✅ **test_mizar_backend_creation**: -- Tests backend instantiation -- Tests ProverKind identification -- Validates configuration - -### Integration Test Files - -✅ **basic.miz** (10 theorems): -- Simple equality properties (reflexivity, symmetry, transitivity) -- Set operations (union/intersection with self) -- Empty set properties -- Subset relations -- **Complexity**: Beginner - -✅ **propositional.miz** (10 theorems): -- De Morgan's laws (2 theorems) -- Distributive laws (2 theorems) -- Commutative laws (2 theorems) -- Associative laws (2 theorems) -- Complex case analysis proofs -- **Complexity**: Intermediate - -✅ **numbers.miz** (27 theorems): -- Natural number properties -- Commutativity (addition, multiplication) -- Associativity (addition, multiplication) -- Distributivity (left, right) -- Order properties (transitivity, antisymmetry, monotonicity) -- Cancellation laws (addition, multiplication) -- Advanced theorems (square expansion, difference of squares) -- Min/max properties -- **Complexity**: Advanced - ---- - -## Technical Highlights - -### Parser Architecture - -**Recursive Descent Parser**: -- Hand-written for maximum control and error recovery -- O(n) time complexity -- Minimal memory allocations -- Robust whitespace and comment handling - -**Key Features**: -- Natural language syntax support -- Operator precedence handling -- Label parsing (`A1:`, `A2:`, etc.) -- Justification parsing (`by XBOOLE_0:def 3`) -- Error recovery at statement boundaries - -### Verification Pipeline - -``` -.miz file → Parser → ProofState - ↓ - mizf (accommodation) - ↓ - verifier (checking) - ↓ - Error Parsing - ↓ - VerificationResult -``` - -### Memory Efficiency - -- Streaming file operations -- Temporary files auto-cleaned -- Efficient tree structures -- Minimal cloning - -### Error Recovery - -- Graceful handling of malformed input -- Detailed error locations -- Continuation past errors when possible -- User-friendly error messages - ---- - -## File Structure - -``` -echidna/ -├── src/rust/provers/ -│ └── mizar.rs (1,318 lines) -│ ├── MizarBackend struct -│ ├── ProverBackend trait impl -│ ├── MizarParser struct -│ ├── MizarArticle/Theorem/Proof structures -│ ├── Term conversion (mizar_to_term, term_to_mizar) -│ ├── Verification (run_mizf, run_verifier) -│ ├── Error parsing -│ └── Unit tests -├── proofs/mizar/ -│ ├── basic.miz (147 lines, 10 theorems) -│ ├── propositional.miz (291 lines, 10 theorems) -│ └── numbers.miz (280 lines, 27 theorems) -└── docs/ - └── MIZAR_BACKEND.md (comprehensive documentation) -``` - ---- - -## Dependencies Added - -### Cargo.toml Updates - -```toml -[dependencies] -uuid = { version = "1.6", features = ["v4"] } # For temp file generation -``` - -All other dependencies were already present: -- `async-trait` - Async trait support -- `anyhow` - Error handling -- `tokio` - Async runtime -- `serde` - Serialization - ---- - -## Compilation Status - -✅ **Successfully compiles**: -```bash -$ cargo check --lib - Finished `dev` profile [unoptimized + debuginfo] target(s) in 10.63s -``` - -✅ **Tests pass**: -```bash -$ cargo test --lib mizar -running 2 tests -test provers::mizar::tests::test_mizar_backend_creation ... ok -test provers::mizar::tests::test_mizar_parser_basic ... ok - -test result: ok. 2 passed; 0 failed; 0 ignored -``` - -**Warnings**: 44 warnings (mostly unused variables in stub implementations, not in Mizar backend) - ---- - -## Integration with ECHIDNA - -### ProverFactory Integration - -The Mizar backend is fully integrated via `ProverFactory`: - -```rust -// In provers/mod.rs -impl ProverFactory { - pub fn create(kind: ProverKind, config: ProverConfig) - -> anyhow::Result> - { - match kind { - // ... other provers ... - ProverKind::Mizar => Ok(Box::new(mizar::MizarBackend::new(config))), - // ... other provers ... - } - } - - pub fn detect_from_file(path: &PathBuf) -> Option { - path.extension()?.to_str().and_then(|ext| match ext { - // ... other extensions ... - "miz" => Some(ProverKind::Mizar), - // ... other extensions ... - }) - } -} -``` - -### Universal Term System - -Full bidirectional conversion ensures: -- ✅ Mizar proofs can be imported into ECHIDNA -- ✅ ECHIDNA proofs can be exported to Mizar -- ✅ Cross-prover theorem sharing -- ✅ Uniform proof representation - -### Aspect Tagging - -Theorems support aspect classification: -- Mathematical domain (logic, algebra, topology, etc.) -- Proof techniques (induction, case analysis, etc.) -- Difficulty level (beginner, intermediate, advanced) -- Dependencies (MML articles required) - ---- - -## Future Enhancements - -While the implementation is complete and production-ready, these enhancements could be added: - -### Parser Completeness -- [ ] Full definition syntax (mode, predicate, functor, attribute) -- [ ] Complete scheme support with parameters -- [ ] Cluster and registration parsing -- [ ] Consider statement with full syntax - -### Performance -- [ ] MML indexing for faster theorem search -- [ ] Parallel verification of multiple theorems -- [ ] Caching of parsed MML articles - -### Neural Integration -- [ ] ML-based premise selection from MML -- [ ] Proof step suggestion using neural networks -- [ ] Automatic proof completion - -### Interactive Features -- [ ] Real-time verification as-you-type -- [ ] IDE integration (LSP server) -- [ ] Proof visualization -- [ ] Step-by-step debugging - ---- - -## Comparison with Other Provers - -| Feature | Mizar | Agda | Coq | Lean | -|---------|-------|------|-----|------| -| Lines of Code | 1,318 | 495 | 1,112 | 26 (stub) | -| Parser | Complete | Complete | Complete | Stub | -| Verification | External | External | External | - | -| Term Conversion | ✅ | ✅ | ✅ | ❌ | -| Export | ✅ | ✅ | ✅ | ❌ | -| Library Search | ✅ (MML) | ❌ | ❌ | ❌ | -| Natural Language | ✅ | ❌ | ❌ | ❌ | -| Complexity | 3/5 | 3/5 | 3/5 | 3/5 | -| Tier | 2 | 1 | 1 | 1 | - ---- - -## Key Achievements - -### ✅ Complete Implementation -- All required components implemented -- No TODO comments in critical paths -- Production-ready code quality - -### ✅ Robust Parsing -- Handles complex Mizar syntax -- Supports 47+ test theorems across 3 files -- Error recovery and reporting - -### ✅ Full Verification -- Two-phase Mizar pipeline -- External tool integration -- Detailed error messages - -### ✅ Universal Integration -- Seamless ProverBackend trait implementation -- Term conversion both directions -- Factory pattern integration - -### ✅ Well Tested -- Unit tests passing -- Integration test files -- Real-world Mizar examples - -### ✅ Documented -- Comprehensive inline documentation -- Full backend documentation (MIZAR_BACKEND.md) -- Usage examples -- Architecture diagrams - ---- - -## Conclusion - -The Mizar backend for ECHIDNA is **complete, tested, and production-ready**. It provides: - -1. ✅ **Full Mizar language support** for common theorem proving tasks -2. ✅ **Robust parsing** with excellent error recovery -3. ✅ **External verifier integration** (mizf + verifier) -4. ✅ **MML library search** capabilities -5. ✅ **Bidirectional term conversion** for cross-prover interoperability -6. ✅ **Comprehensive test coverage** with real-world examples -7. ✅ **Production-ready code quality** with proper error handling - -The implementation demonstrates ECHIDNA's capability to integrate diverse theorem provers with natural language-like syntax, paving the way for the remaining Tier 2 provers (Metamath, HOL Light) and beyond. - ---- - -**Next Steps**: -1. Deploy to actual ECHIDNA repository (Priority 1 from CLAUDE.md) -2. Continue with Metamath implementation (easiest Tier 2, 2/5 complexity) -3. Integrate neural premise selection for MML theorem suggestions -4. Add interactive proof development features - ---- - -**Implementation Team**: ECHIDNA Project -**License**: MIT OR Palimpsest-0.6 -**Repository**: https://github.com/hyperpolymath/echidna -**Documentation**: /home/user/echidna/docs/MIZAR_BACKEND.md - ---- - -# Appendix: Mizar Backend Reference - -_The following content was merged in from `docs/MIZAR_BACKEND.md` on 2026-05-25 when the -two parallel "backend" and "implementation summary" docs were consolidated. -Sections may overlap with the summary above and will be naturally integrated in a -future doc-polish pass._ - - -**File**: `/home/user/echidna/src/rust/provers/mizar.rs` -**Status**: ✅ Complete Production-Ready Implementation -**Lines of Code**: 1,318 -**Complexity**: 3/5 (Tier 2) -**Estimated Implementation Time**: 2 weeks - -## Overview - -The Mizar backend is a complete, production-ready implementation for integrating the Mizar theorem prover into ECHIDNA. Mizar is unique among theorem provers for its natural-language-like syntax and the Mizar Mathematical Library (MML), one of the largest formalized mathematics collections in the world. - -## Architecture - -### Core Components - -#### 1. **MizarBackend Struct** -```rust -pub struct MizarBackend { - config: ProverConfig, - mml_path: PathBuf, -} -``` - -The main backend struct implementing the `ProverBackend` trait. It manages: -- Prover configuration (executable path, timeout, etc.) -- MML (Mizar Mathematical Library) path -- Two-phase verification process (accommodation + analysis) - -#### 2. **Mizar Article Parser** - -The parser handles complete Mizar article syntax: - -**Environ Section**: -- `vocabularies` - Mathematical vocabulary -- `notations` - Notation definitions -- `constructors` - Type constructors -- `registrations` - Type registrations -- `theorems` - Referenced theorems -- `requirements` - System requirements - -**Content**: -- Theorem statements with proofs -- Definitions (types, functions, predicates) -- Schemes (proof schemas) - -**Proof Structures**: -- `let` - Variable introduction -- `assume` - Hypothesis assumption -- `thus` / `hence` - Proof steps with justifications -- `per cases` - Case analysis -- `take` - Witness provision -- `consider` - Existential elimination - -#### 3. **Mizar Verification System** - -Implements Mizar's two-phase verification: - -**Phase 1: Accommodation (`mizf`)** -- Processes environ directives -- Loads required articles from MML -- Prepares verification environment - -**Phase 2: Verification (`verifier`)** -- Type checks all terms -- Verifies proof correctness -- Generates error messages with line/column information - -#### 4. **Term Conversion** - -Bidirectional conversion between: -- Mizar's natural language terms -- ECHIDNA's universal `Term` representation - -Handles: -- Quantifiers (`for`/`ex`) -- Binary operators (`=`, `c=`, `\/`, `/\`, `&`, `or`, `implies`) -- Function application -- Type annotations - -#### 5. **Error Parsing** - -Sophisticated error message parsing supporting two formats: -- `* line col error_code message` (Mizar format) -- `filename:line:col: message` (standard format) - -Extracts: -- Line and column numbers -- Error codes -- Descriptive messages - -## Implementation Details - -### Mizar Term Representation - -```rust -enum MizarTerm { - Variable(String), - Constant(String), - Application { func: Box, args: Vec }, - Quantifier { kind: QuantifierKind, var: String, var_type: Box, body: Box }, - BinaryOp { op: String, left: Box, right: Box }, - UnaryOp { op: String, operand: Box }, -} -``` - -### Parser Implementation - -The `MizarParser` uses a hand-written recursive descent parser: - -**Key Methods**: -- `parse_environ()` - Parse environment directives -- `parse_theorem()` - Parse theorem statements -- `parse_proof()` - Parse proof structures -- `parse_formula()` - Parse logical formulas -- `parse_term()` - Parse mathematical terms -- `skip_whitespace_and_comments()` - Handle `::` comments - -**Features**: -- Robust error recovery -- Support for Mizar's operator precedence -- Handling of labeled statements (`A1:`, `A2:`, etc.) -- Justification parsing (`by XBOOLE_0:def 3`) - -### Verification Integration - -```rust -async fn verify_file(&self, path: &Path) -> Result -``` - -Executes the full Mizar verification pipeline: - -1. **Run `mizf`** (accommodation) - - Set `MIZFILES` environment variable to MML path - - Process environ directives - - Load required articles - -2. **Run `verifier`** (type checking and proof verification) - - Verify all proof steps - - Check type correctness - - Validate justifications - -3. **Parse Results** - - Extract errors and warnings - - Return success/failure status - -### MML Integration - -The backend integrates with the Mizar Mathematical Library (MML): - -```rust -async fn search_theorems(&self, pattern: &str) -> Result> -``` - -- Searches `$MIZFILES/mml.lar` for theorem references -- Case-insensitive pattern matching -- Returns up to 100 matching theorems - -### Tactic Application - -Implements standard and Mizar-specific tactics: - -**Standard Tactics**: -- `Apply(theorem)` - Apply a theorem -- `Intro(name)` - Introduce variables (implements `let`) -- `Cases(term)` - Case analysis (implements `per cases`) -- `Assumption` - Solve with hypothesis -- `Exact(term)` - Provide exact proof term - -**Mizar-Specific Tactics**: -```rust -Tactic::Custom { - prover: "mizar", - command: "thus" | "hence" | "per_cases", - args: .. -} -``` - -### Export Functionality - -```rust -async fn export(&self, state: &ProofState) -> Result -``` - -Generates valid Mizar articles from proof states: - -```mizar -:: Generated by ECHIDNA -:: Mizar article - -environ - vocabularies SUBSET_1, XBOOLE_0, TARSKI; - notations TARSKI, XBOOLE_0; - constructors TARSKI, XBOOLE_0; - registrations XBOOLE_0; - -begin - -theorem TheoremName: - for P being set holds P = P -proof - thus thesis; -end; -``` - -## Test Cases - -The implementation includes test cases in `/home/user/echidna/proofs/mizar/`: - -### 1. `basic.miz` - Basic Logical Proofs -- Simple equality theorems (reflexivity, symmetry, transitivity) -- Set operations (union, intersection with self) -- Empty set properties -- Subset relations - -**Example**: -```mizar -theorem Th1: - for P, Q being set holds P = Q implies Q = P -proof - let P, Q be set; - assume P = Q; - thus Q = P; -end; -``` - -### 2. `propositional.miz` - Propositional Logic -- De Morgan's laws for sets -- Distributive laws -- Commutative and associative laws -- Complex proofs with `per cases` - -**Example**: -```mizar -theorem DeMorgan1: - for X, Y, Z being set holds - Z \ (X \/ Y) = (Z \ X) /\ (Z \ Y) -proof - let X, Y, Z be set; - thus Z \ (X \/ Y) c= (Z \ X) /\ (Z \ Y) proof ... end; - thus (Z \ X) /\ (Z \ Y) c= Z \ (X \/ Y) proof ... end; -end; -``` - -### 3. `numbers.miz` - Arithmetic Properties -- Natural number properties -- Commutativity and associativity of addition/multiplication -- Distributivity -- Order properties (transitivity, antisymmetry) -- Cancellation laws -- Advanced theorems (square formulas, min/max) - -**Example**: -```mizar -theorem AddSquare: - for m, n being Nat holds - (m + n) * (m + n) = m * m + 2 * m * n + n * n -proof - let m, n be Nat; - thus (m + n) * (m + n) - = (m + n) * m + (m + n) * n - .= m * m + n * m + (m + n) * n - ... -end; -``` - -## Usage Examples - -### Creating a Backend - -```rust -use echidna::provers::{ProverConfig, ProverKind, ProverFactory}; -use std::path::PathBuf; - -let mut config = ProverConfig::default(); -config.executable = PathBuf::from("/usr/local/bin/verifier"); -config.timeout = 300; // 5 minutes - -let backend = ProverFactory::create(ProverKind::Mizar, config)?; -``` - -### Parsing a Mizar File - -```rust -let proof_state = backend.parse_file( - PathBuf::from("/home/user/echidna/proofs/mizar/basic.miz") -).await?; - -println!("Goals: {}", proof_state.goals.len()); -println!("Theorems: {}", proof_state.context.theorems.len()); -``` - -### Applying Tactics - -```rust -// Introduce a variable -let new_state = backend.apply_tactic( - &proof_state, - &Tactic::Intro(Some("x".to_string())) -).await?; - -// Apply a theorem -let new_state = backend.apply_tactic( - &new_state, - &Tactic::Apply("XBOOLE_0:def_3".to_string()) -).await?; - -// Mizar-specific tactic -let new_state = backend.apply_tactic( - &new_state, - &Tactic::Custom { - prover: "mizar".to_string(), - command: "thus".to_string(), - args: vec![], - } -).await?; -``` - -### Verifying a Proof - -```rust -// Complete the proof -let final_state = /* ... complete all goals ... */; - -// Verify -let is_valid = backend.verify_proof(&final_state).await?; -if is_valid { - println!("✓ Proof verified successfully!"); -} else { - println!("✗ Proof verification failed"); -} -``` - -### Searching MML - -```rust -// Search for theorems about sets -let results = backend.search_theorems("intersection").await?; - -for theorem in results { - println!("Found: {}", theorem); -} -``` - -## Technical Considerations - -### Environment Setup - -Required environment variables: -- `MIZFILES` - Path to MML directory (default: `/usr/local/share/mizar`) - -Required executables: -- `mizf` - Accommodation processor -- `verifier` - Proof verifier - -### Error Handling - -The implementation provides detailed error information: - -```rust -#[derive(Debug, Clone)] -struct MizarError { - line: usize, - column: usize, - code: String, - message: String, -} -``` - -Errors are reported at the exact location in the source file, making debugging straightforward. - -### Performance - -- **Parsing**: ~O(n) where n is file size -- **Verification**: Depends on Mizar verifier (typically seconds for simple proofs) -- **MML Search**: O(m) where m is MML size, with early termination at 100 results - -### Memory Usage - -- Efficient recursive descent parser with minimal allocations -- Streaming file operations for large MML searches -- Temporary files cleaned up automatically - -## Integration Points - -### With Neural Selector - -```rust -let suggestions = backend.suggest_tactics(&proof_state, 10).await?; -// Returns tactically sound suggestions based on goal structure -``` - -### With Aspect Tagger - -Theorems can be tagged with mathematical aspects: -- Set theory -- Logic -- Arithmetic -- Topology -- etc. - -### With Universal Term System - -Full bidirectional conversion ensures: -- Mizar proofs can be translated to other provers -- Proofs from other systems can be exported to Mizar -- Cross-prover theorem databases - -## Limitations and Future Work - -### Current Limitations - -1. **Simplified Definition Parsing**: Full definition syntax not yet implemented -2. **Scheme Parsing**: Basic scheme support only -3. **Proof Checking**: Relies on external Mizar verifier -4. **Neural Suggestions**: Basic heuristics (can be enhanced with ML models) - -### Planned Enhancements - -1. **Complete Parser**: Full Mizar language support including: - - Definitions (mode, predicate, functor, attribute) - - Schemes with full parameter handling - - Clusters and registrations - -2. **Proof Reconstruction**: Native proof checking without external verifier - -3. **MML Indexing**: Fast indexed search of MML theorems - -4. **Interactive Mode**: Real-time proof assistant integration - -5. **Neural Premise Selection**: ML-based theorem suggestion from MML - -## Testing - -### Unit Tests - -```rust -#[test] -fn test_mizar_parser_basic() { - let content = r#" -environ - vocabularies SUBSET_1, XBOOLE_0; -begin - -theorem Th1: - for P being set holds P = P -proof - let P be set; - thus P = P; -end; -"#; - - let mut parser = MizarParser::new(content); - let article = parser.parse().unwrap(); - assert_eq!(article.theorems.len(), 1); -} -``` - -### Integration Tests - -Test against actual Mizar files: -- `basic.miz` - 10 theorems -- `propositional.miz` - 10 theorems (complex proofs) -- `numbers.miz` - 27 theorems (arithmetic) - -## Dependencies - -**Rust Crates**: -- `async-trait` - Async trait support -- `anyhow` - Error handling -- `tokio` - Async runtime -- `serde` - Serialization -- `uuid` - Temporary file generation - -**External**: -- Mizar system (mizf, verifier) -- MML (Mizar Mathematical Library) - -## Performance Benchmarks - -| Operation | Time | Notes | -|-----------|------|-------| -| Parse basic.miz | ~5ms | 147 lines | -| Parse propositional.miz | ~12ms | 291 lines | -| Parse numbers.miz | ~15ms | 280 lines | -| Verify simple theorem | ~100ms | External verifier | -| Search MML | ~50ms | Pattern matching | - -## Conclusion - -The Mizar backend provides a complete, production-ready integration for ECHIDNA. It handles: - -✅ Full article parsing with robust error recovery -✅ Two-phase verification integration -✅ MML library search -✅ Bidirectional term conversion -✅ Detailed error reporting -✅ Tactic application and proof state management -✅ Export to valid Mizar format - -The implementation is well-tested, documented, and ready for use in the full ECHIDNA system. - ---- - -**Implementation Date**: November 2025 -**Author**: ECHIDNA Project Team -**License**: MIT OR Palimpsest-0.6 -**Tier**: 2 (Big Six completion) -**Priority**: Months 5-7 of 12-month roadmap diff --git a/docs/implementation/Z3_IMPLEMENTATION_SUMMARY.adoc b/docs/implementation/Z3_IMPLEMENTATION_SUMMARY.adoc new file mode 100644 index 00000000..3b7d89aa --- /dev/null +++ b/docs/implementation/Z3_IMPLEMENTATION_SUMMARY.adoc @@ -0,0 +1,433 @@ +== Z3 SMT Solver Backend - Implementation Summary + +=== ✅ Complete Implementation + +A production-ready Z3 SMT solver backend for ECHIDNA with full SMT-LIB +2.0 support. + +=== 📊 Statistics + +* *File*: `+/home/user/echidna/src/rust/provers/z3.rs+` +* *Lines of Code*: 772 (including documentation and tests) +* *Functions/Methods*: 31 +* *Tier*: 1 (Priority) +* *Complexity*: 2/5 (Easy) +* *Estimated Time*: 1 week +* *Status*: ✅ *COMPLETE* + +=== 🎯 Implementation Features + +==== 1. Core Backend (`+Z3Backend+`) + +Implements all `+ProverBackend+` trait methods: + +* ✅ `+kind()+` - Returns ProverKind::Z3 +* ✅ `+version()+` - Gets Z3 version from executable +* ✅ `+parse_file()+` - Parses .smt2 files into ProofState +* ✅ `+parse_string()+` - Parses SMT-LIB from string +* ✅ `+apply_tactic()+` - Applies tactics (simplify, custom Z3 tactics) +* ✅ `+verify_proof()+` - Validates proofs via unsatisfiability checking +* ✅ `+export()+` - Exports ProofState to SMT-LIB 2.0 format +* ✅ `+suggest_tactics()+` - Suggests Z3-specific tactics +* ✅ `+search_theorems()+` - Theorem search (stub for SMT solvers) +* ✅ `+config()+` / `+set_config()+` - Configuration management + +==== 2. SMT-LIB 2.0 Parser (`+SmtParser+`) + +Complete parser with 10+ methods: + +* ✅ `+tokenize()+` - Lexical analysis with comment/string handling +* ✅ `+parse()+` - Full SMT-LIB file parsing +* ✅ `+parse_term()+` - Recursive term parsing +* ✅ `+peek()+` / `+next()+` / `+expect()+` - Token stream management +* ✅ `+smt_to_term()+` - Conversion to universal Term type + +Supported constructs: - ✅ `+declare-const+`, `+declare-fun+` - ✅ +`+assert+`, `+check-sat+`, `+get-model+` - ✅ `+set-logic+`, +`+set-option+`, `+set-info+` - ✅ `+forall+`, `+exists+` (quantifiers) - +✅ `+let+` bindings - ✅ Semicolon comments - ✅ String literals - ✅ +Nested S-expressions + +==== 3. Term Representations + +Three term types: + +[arabic] +. *SmtTerm* - SMT-LIB native representation +* Symbol, Numeral, Bool +* App (function application) +* Quantified (forall/exists) +* Let (local bindings) +. *Term* - Universal ECHIDNA representation +* Bidirectional conversion from SmtTerm +. *SmtResult* - Z3 execution results +* Sat, Unsat, Unknown, Error, Output + +==== 4. Process Management + +Asynchronous Z3 process handling: + +* ✅ `+spawn_z3()+` - Launch Z3 with stdin/stdout/stderr pipes +* ✅ `+execute_command()+` - Send SMT commands with timeout +* ✅ `+parse_smt_result()+` - Parse Z3 output +* ✅ Configurable timeouts (default: 300 seconds) +* ✅ Clean process termination +* ✅ Error handling with context + +==== 5. Term Conversion + +Bidirectional SMT ↔ Universal conversion: + +* ✅ `+smt_to_term()+` - SmtTerm → Term +* ✅ `+term_to_smt()+` - Term → SMT-LIB string +* ✅ Handles quantifiers, applications, let bindings +* ✅ Preserves type information + +==== 6. Tactic System + +Z3-specific tactics: + +* ✅ `+Simplify+` - Basic simplification +* ✅ Custom tactics: +** `+(then simplify solve-eqs)+` +** `+(then ctx-simplify propagate-values)+` +** `+(then simplify normalize-bounds lia2pb pb2bv bit-blast)+` +* ✅ Context-aware tactic suggestions +* ✅ Arithmetic detection for specialized tactics + +==== 7. Proof Verification + +Logical validity checking: + +* ✅ Negation-based verification (goal ¬φ → unsat means φ valid) +* ✅ Multi-goal support +* ✅ Sat/Unsat/Unknown result handling +* ✅ Error propagation with context + +==== 8. Testing + +Comprehensive test suite: + +* ✅ `+test_tokenize()+` - Lexer testing +* ✅ `+test_parse_simple_term()+` - Basic term parsing +* ✅ `+test_parse_app()+` - Function application parsing +* ✅ `+test_z3_backend_version()+` - Integration test + +=== 📝 SMT Theories Supported + +* ✅ *QF_UF* - Uninterpreted functions +* ✅ *QF_LIA* - Linear integer arithmetic +* ✅ *QF_NIA* - Nonlinear integer arithmetic +* ✅ *QF_BV* - Bitvectors +* ✅ *ALL* - All theories (for quantifiers) +* ✅ Arrays, Datatypes, etc. (via Z3) + +=== 📁 Project Structure + +.... +echidna/ +├── src/rust/provers/ +│ ├── z3.rs (772 lines) ✅ COMPLETE +│ ├── mod.rs (updated to include z3) +│ └── ... (other provers) +├── examples/ +│ ├── z3_simple.smt2 ✅ +│ └── z3_quantifiers.smt2 ✅ +└── docs/ + └── Z3_BACKEND.md ✅ +.... + +=== 🔧 Dependencies + +All required dependencies present in `+Cargo.toml+`: + +* ✅ `+tokio+` - Async runtime (process management) +* ✅ `+async-trait+` - Async trait support +* ✅ `+anyhow+` - Error handling +* ✅ `+serde+`, `+serde_json+` - Serialization + +=== ✨ Key Highlights + +==== Production Ready Features + +[arabic] +. *Comprehensive Error Handling* +* Parse errors with line/column info +* Process spawn/timeout errors +* Clear error messages with context +. *Robust Parser* +* Handles comments, strings, nested expressions +* Recursive descent with proper error recovery +* Full SMT-LIB 2.0 compliance +. *Async/Await Support* +* Non-blocking Z3 execution +* Configurable timeouts +* Proper resource cleanup +. *Type Safety* +* Strong typing throughout +* Enum-based result types +* No unsafe code +. *Extensibility* +* Custom tactic support +* Pluggable configuration +* Universal term abstraction + +==== Example Usage + +[source,rust] +---- +use echidna::provers::{ProverBackend, ProverConfig, ProverKind, z3::Z3Backend}; +use std::path::PathBuf; + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + // Configure Z3 + let config = ProverConfig { + executable: PathBuf::from("z3"), + timeout: 60, + neural_enabled: true, + ..Default::default() + }; + + // Create backend + let backend = Z3Backend::new(config); + + // Parse SMT file + let state = backend.parse_file( + PathBuf::from("examples/z3_simple.smt2") + ).await?; + + println!("Parsed {} goals", state.goals.len()); + println!("Parsed {} variables", state.context.variables.len()); + + // Verify proof + if backend.verify_proof(&state).await? { + println!("✓ Proof is valid!"); + } else { + println!("✗ Proof is invalid"); + } + + // Get tactic suggestions + let tactics = backend.suggest_tactics(&state, 5).await?; + for tactic in tactics { + println!("Suggested: {:?}", tactic); + } + + Ok(()) +} +---- + +==== Example SMT-LIB File + +[source,smt2] +---- +; examples/z3_simple.smt2 +(set-logic QF_LIA) + +(declare-const x Int) +(declare-const y Int) + +(assert (> x 0)) +(assert (> y 0)) +(assert (= (+ x y) 10)) +(assert (< x y)) + +(check-sat) +; Expected: sat (e.g., x=3, y=7) +---- + +=== 🎓 Technical Achievements + +[arabic] +. *Complete SMT-LIB 2.0 Parser* (400+ lines) +* Tokenization with comment/string handling +* Recursive descent parsing +* Full quantifier support +. *Async Process Management* +* Tokio-based async I/O +* Timeout handling +* Clean resource management +. *Universal Term Conversion* +* SMT ↔ ECHIDNA term translation +* Type preservation +* Quantifier encoding +. *Z3 Integration* +* Command execution +* Result parsing +* Model extraction (basic) + +=== 📊 Compilation Status + +✅ *SUCCESS* - Compiles without errors + +[source,bash] +---- +$ cargo check --lib + Compiling echidna v0.1.0 (/home/user/echidna) + Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.56s +---- + +Only warnings (unused variables, etc.) - no errors! + +=== 🚀 Next Steps (Future Enhancements) + +While the implementation is complete, potential enhancements: + +* [ ] Persistent Z3 session (reuse process for multiple queries) +* [ ] Full model extraction (arrays, functions, datatypes) +* [ ] Unsat core extraction +* [ ] Proof term/certificate extraction +* [ ] Incremental solving (push/pop stack) +* [ ] Optimization support (maximize/minimize) + +=== 📚 Documentation + +* ✅ Inline documentation (doc comments) +* ✅ README: `+/home/user/echidna/docs/Z3_BACKEND.md+` +* ✅ Examples: `+/home/user/echidna/examples/*.smt2+` +* ✅ Tests: Included in z3.rs + +=== 🏆 Deliverables + +[arabic] +. ✅ *Complete Z3 backend implementation* (772 lines) +. ✅ *SMT-LIB 2.0 parser* (400+ lines) +. ✅ *ProverBackend trait implementation* (all 11 methods) +. ✅ *Process management* (async, timeout, error handling) +. ✅ *Term conversion* (bidirectional SMT ↔ Universal) +. ✅ *Tactic support* (6+ Z3 tactics) +. ✅ *Model extraction* (basic support) +. ✅ *Test suite* (4 tests) +. ✅ *Documentation* (comprehensive) +. ✅ *Examples* (2 .smt2 files) +. ✅ *Compilation* (no errors) +. ✅ *Stub modules* (for missing provers to enable compilation) + +=== ✅ Acceptance Criteria + +All requirements met: + +* [x] Z3Backend struct implementing ProverBackend trait +* [x] SMT-LIB 2.0 parser with full syntax support +* [x] Z3 process management with subprocess and timeout +* [x] Term conversion (SMT ↔ Universal Term) +* [x] Tactic support (simplify, custom tactics) +* [x] Model extraction capability +* [x] Comprehensive error handling +* [x] Production-ready code quality +* [x] Full documentation +* [x] Working examples + +=== 📄 License + +MIT OR Palimpsest-0.6 + +''''' + +*Implementation Date*: 2025-11-22 + +*ECHIDNA Version*: 0.1.0 + +*Status*: ✅ *PRODUCTION READY* + +''''' + +== Appendix: Z3 Backend Reference + +_The following content was merged in from `+docs/Z3_BACKEND.md+` on +2026-05-25 when the two parallel "`backend`" and "`implementation +summary`" docs were consolidated. Sections may overlap with the summary +above and will be naturally integrated in a future doc-polish pass._ + +Complete implementation of Z3 SMT solver integration for ECHIDNA. + +=== Overview + +Z3 is a Tier 1 SMT (Satisfiability Modulo Theories) solver supporting +multiple theories and SMT-LIB 2.0 format. This backend provides full +integration including parsing, tactic application, and proof +verification. + +=== Features + +==== 1. SMT-LIB 2.0 Parser + +Complete parser supporting: - *Declarations*: `+declare-const+`, +`+declare-fun+` - *Assertions*: `+assert+` statements - *Commands*: +`+check-sat+`, `+get-model+`, `+set-logic+`, `+set-option+` - +*Quantifiers*: `+forall+`, `+exists+` with typed bindings - *Let +bindings*: Local variable definitions - *Comments*: Semicolon-based +comments + +==== 2. Supported SMT Theories + +* *QF_UF*: Uninterpreted functions with equality +* *QF_LIA*: Linear integer arithmetic +* *QF_NIA*: Nonlinear integer arithmetic + +* *QF_BV*: Fixed-size bitvectors +* *ALL*: All supported theories (for quantified formulas) +* Arrays, datatypes, and more + +==== 3. Process Management + +* Asynchronous Z3 process spawning +* Configurable timeouts (default: 300 seconds) +* Proper stdin/stdout/stderr handling +* Clean process termination + +==== 4. Term Conversion + +Bidirectional conversion between: - SMT-LIB 2.0 terms (SmtTerm) - +ECHIDNA universal terms (Term) + +Supports: - Symbols and constants - Function applications - Quantified +formulas - Let expressions + +==== 5. Tactic Support + +Built-in Z3 tactics: - `+simplify+` - Term simplification - +`+solve-eqs+` - Equation solving - `+ctx-simplify+` - Context-aware +simplification - `+propagate-values+` - Value propagation - +`+normalize-bounds+` - Bound normalization - `+lia2pb+`, `+pb2bv+`, +`+bit-blast+` - Arithmetic encoding + +==== 6. Proof Verification + +Validates proofs by checking if goal negation is unsatisfiable. + +=== Usage Example + +[source,rust] +---- +use echidna::{ProverBackend, ProverConfig}; +use std::path::PathBuf; + +let config = ProverConfig { + executable: PathBuf::from("z3"), + timeout: 60, + ..Default::default() +}; + +let backend = z3::Z3Backend::new(config); +let state = backend.parse_file( + PathBuf::from("examples/z3_simple.smt2") +).await?; + +let is_valid = backend.verify_proof(&state).await?; +---- + +=== Implementation Details + +*File*: `+/home/user/echidna/src/rust/provers/z3.rs+` + +*Lines*: ~850 (including parser and tests) + +*Complexity*: 2/5 + +*Tier*: 1 + +=== Testing + +[source,bash] +---- +cargo test --lib z3 +---- + +=== License + +MIT OR Palimpsest-0.6 diff --git a/docs/implementation/Z3_IMPLEMENTATION_SUMMARY.md b/docs/implementation/Z3_IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index 64778207..00000000 --- a/docs/implementation/Z3_IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,441 +0,0 @@ -# Z3 SMT Solver Backend - Implementation Summary - -## ✅ Complete Implementation - -A production-ready Z3 SMT solver backend for ECHIDNA with full SMT-LIB 2.0 support. - -## 📊 Statistics - -- **File**: `/home/user/echidna/src/rust/provers/z3.rs` -- **Lines of Code**: 772 (including documentation and tests) -- **Functions/Methods**: 31 -- **Tier**: 1 (Priority) -- **Complexity**: 2/5 (Easy) -- **Estimated Time**: 1 week -- **Status**: ✅ **COMPLETE** - -## 🎯 Implementation Features - -### 1. Core Backend (`Z3Backend`) - -Implements all `ProverBackend` trait methods: - -- ✅ `kind()` - Returns ProverKind::Z3 -- ✅ `version()` - Gets Z3 version from executable -- ✅ `parse_file()` - Parses .smt2 files into ProofState -- ✅ `parse_string()` - Parses SMT-LIB from string -- ✅ `apply_tactic()` - Applies tactics (simplify, custom Z3 tactics) -- ✅ `verify_proof()` - Validates proofs via unsatisfiability checking -- ✅ `export()` - Exports ProofState to SMT-LIB 2.0 format -- ✅ `suggest_tactics()` - Suggests Z3-specific tactics -- ✅ `search_theorems()` - Theorem search (stub for SMT solvers) -- ✅ `config()` / `set_config()` - Configuration management - -### 2. SMT-LIB 2.0 Parser (`SmtParser`) - -Complete parser with 10+ methods: - -- ✅ `tokenize()` - Lexical analysis with comment/string handling -- ✅ `parse()` - Full SMT-LIB file parsing -- ✅ `parse_term()` - Recursive term parsing -- ✅ `peek()` / `next()` / `expect()` - Token stream management -- ✅ `smt_to_term()` - Conversion to universal Term type - -Supported constructs: -- ✅ `declare-const`, `declare-fun` -- ✅ `assert`, `check-sat`, `get-model` -- ✅ `set-logic`, `set-option`, `set-info` -- ✅ `forall`, `exists` (quantifiers) -- ✅ `let` bindings -- ✅ Semicolon comments -- ✅ String literals -- ✅ Nested S-expressions - -### 3. Term Representations - -Three term types: - -1. **SmtTerm** - SMT-LIB native representation - - Symbol, Numeral, Bool - - App (function application) - - Quantified (forall/exists) - - Let (local bindings) - -2. **Term** - Universal ECHIDNA representation - - Bidirectional conversion from SmtTerm - -3. **SmtResult** - Z3 execution results - - Sat, Unsat, Unknown, Error, Output - -### 4. Process Management - -Asynchronous Z3 process handling: - -- ✅ `spawn_z3()` - Launch Z3 with stdin/stdout/stderr pipes -- ✅ `execute_command()` - Send SMT commands with timeout -- ✅ `parse_smt_result()` - Parse Z3 output -- ✅ Configurable timeouts (default: 300 seconds) -- ✅ Clean process termination -- ✅ Error handling with context - -### 5. Term Conversion - -Bidirectional SMT ↔ Universal conversion: - -- ✅ `smt_to_term()` - SmtTerm → Term -- ✅ `term_to_smt()` - Term → SMT-LIB string -- ✅ Handles quantifiers, applications, let bindings -- ✅ Preserves type information - -### 6. Tactic System - -Z3-specific tactics: - -- ✅ `Simplify` - Basic simplification -- ✅ Custom tactics: - - `(then simplify solve-eqs)` - - `(then ctx-simplify propagate-values)` - - `(then simplify normalize-bounds lia2pb pb2bv bit-blast)` -- ✅ Context-aware tactic suggestions -- ✅ Arithmetic detection for specialized tactics - -### 7. Proof Verification - -Logical validity checking: - -- ✅ Negation-based verification (goal ¬φ → unsat means φ valid) -- ✅ Multi-goal support -- ✅ Sat/Unsat/Unknown result handling -- ✅ Error propagation with context - -### 8. Testing - -Comprehensive test suite: - -- ✅ `test_tokenize()` - Lexer testing -- ✅ `test_parse_simple_term()` - Basic term parsing -- ✅ `test_parse_app()` - Function application parsing -- ✅ `test_z3_backend_version()` - Integration test - -## 📝 SMT Theories Supported - -- ✅ **QF_UF** - Uninterpreted functions -- ✅ **QF_LIA** - Linear integer arithmetic -- ✅ **QF_NIA** - Nonlinear integer arithmetic -- ✅ **QF_BV** - Bitvectors -- ✅ **ALL** - All theories (for quantifiers) -- ✅ Arrays, Datatypes, etc. (via Z3) - -## 📁 Project Structure - -``` -echidna/ -├── src/rust/provers/ -│ ├── z3.rs (772 lines) ✅ COMPLETE -│ ├── mod.rs (updated to include z3) -│ └── ... (other provers) -├── examples/ -│ ├── z3_simple.smt2 ✅ -│ └── z3_quantifiers.smt2 ✅ -└── docs/ - └── Z3_BACKEND.md ✅ -``` - -## 🔧 Dependencies - -All required dependencies present in `Cargo.toml`: - -- ✅ `tokio` - Async runtime (process management) -- ✅ `async-trait` - Async trait support -- ✅ `anyhow` - Error handling -- ✅ `serde`, `serde_json` - Serialization - -## ✨ Key Highlights - -### Production Ready Features - -1. **Comprehensive Error Handling** - - Parse errors with line/column info - - Process spawn/timeout errors - - Clear error messages with context - -2. **Robust Parser** - - Handles comments, strings, nested expressions - - Recursive descent with proper error recovery - - Full SMT-LIB 2.0 compliance - -3. **Async/Await Support** - - Non-blocking Z3 execution - - Configurable timeouts - - Proper resource cleanup - -4. **Type Safety** - - Strong typing throughout - - Enum-based result types - - No unsafe code - -5. **Extensibility** - - Custom tactic support - - Pluggable configuration - - Universal term abstraction - -### Example Usage - -```rust -use echidna::provers::{ProverBackend, ProverConfig, ProverKind, z3::Z3Backend}; -use std::path::PathBuf; - -#[tokio::main] -async fn main() -> anyhow::Result<()> { - // Configure Z3 - let config = ProverConfig { - executable: PathBuf::from("z3"), - timeout: 60, - neural_enabled: true, - ..Default::default() - }; - - // Create backend - let backend = Z3Backend::new(config); - - // Parse SMT file - let state = backend.parse_file( - PathBuf::from("examples/z3_simple.smt2") - ).await?; - - println!("Parsed {} goals", state.goals.len()); - println!("Parsed {} variables", state.context.variables.len()); - - // Verify proof - if backend.verify_proof(&state).await? { - println!("✓ Proof is valid!"); - } else { - println!("✗ Proof is invalid"); - } - - // Get tactic suggestions - let tactics = backend.suggest_tactics(&state, 5).await?; - for tactic in tactics { - println!("Suggested: {:?}", tactic); - } - - Ok(()) -} -``` - -### Example SMT-LIB File - -```smt2 -; examples/z3_simple.smt2 -(set-logic QF_LIA) - -(declare-const x Int) -(declare-const y Int) - -(assert (> x 0)) -(assert (> y 0)) -(assert (= (+ x y) 10)) -(assert (< x y)) - -(check-sat) -; Expected: sat (e.g., x=3, y=7) -``` - -## 🎓 Technical Achievements - -1. **Complete SMT-LIB 2.0 Parser** (400+ lines) - - Tokenization with comment/string handling - - Recursive descent parsing - - Full quantifier support - -2. **Async Process Management** - - Tokio-based async I/O - - Timeout handling - - Clean resource management - -3. **Universal Term Conversion** - - SMT ↔ ECHIDNA term translation - - Type preservation - - Quantifier encoding - -4. **Z3 Integration** - - Command execution - - Result parsing - - Model extraction (basic) - -## 📊 Compilation Status - -✅ **SUCCESS** - Compiles without errors - -```bash -$ cargo check --lib - Compiling echidna v0.1.0 (/home/user/echidna) - Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.56s -``` - -Only warnings (unused variables, etc.) - no errors! - -## 🚀 Next Steps (Future Enhancements) - -While the implementation is complete, potential enhancements: - -- [ ] Persistent Z3 session (reuse process for multiple queries) -- [ ] Full model extraction (arrays, functions, datatypes) -- [ ] Unsat core extraction -- [ ] Proof term/certificate extraction -- [ ] Incremental solving (push/pop stack) -- [ ] Optimization support (maximize/minimize) - -## 📚 Documentation - -- ✅ Inline documentation (doc comments) -- ✅ README: `/home/user/echidna/docs/Z3_BACKEND.md` -- ✅ Examples: `/home/user/echidna/examples/*.smt2` -- ✅ Tests: Included in z3.rs - -## 🏆 Deliverables - -1. ✅ **Complete Z3 backend implementation** (772 lines) -2. ✅ **SMT-LIB 2.0 parser** (400+ lines) -3. ✅ **ProverBackend trait implementation** (all 11 methods) -4. ✅ **Process management** (async, timeout, error handling) -5. ✅ **Term conversion** (bidirectional SMT ↔ Universal) -6. ✅ **Tactic support** (6+ Z3 tactics) -7. ✅ **Model extraction** (basic support) -8. ✅ **Test suite** (4 tests) -9. ✅ **Documentation** (comprehensive) -10. ✅ **Examples** (2 .smt2 files) -11. ✅ **Compilation** (no errors) -12. ✅ **Stub modules** (for missing provers to enable compilation) - -## ✅ Acceptance Criteria - -All requirements met: - -- [x] Z3Backend struct implementing ProverBackend trait -- [x] SMT-LIB 2.0 parser with full syntax support -- [x] Z3 process management with subprocess and timeout -- [x] Term conversion (SMT ↔ Universal Term) -- [x] Tactic support (simplify, custom tactics) -- [x] Model extraction capability -- [x] Comprehensive error handling -- [x] Production-ready code quality -- [x] Full documentation -- [x] Working examples - -## 📄 License - -MIT OR Palimpsest-0.6 - ---- - -**Implementation Date**: 2025-11-22 -**ECHIDNA Version**: 0.1.0 -**Status**: ✅ **PRODUCTION READY** - ---- - -# Appendix: Z3 Backend Reference - -_The following content was merged in from `docs/Z3_BACKEND.md` on 2026-05-25 when the -two parallel "backend" and "implementation summary" docs were consolidated. -Sections may overlap with the summary above and will be naturally integrated in a -future doc-polish pass._ - - -Complete implementation of Z3 SMT solver integration for ECHIDNA. - -## Overview - -Z3 is a Tier 1 SMT (Satisfiability Modulo Theories) solver supporting multiple theories and SMT-LIB 2.0 format. This backend provides full integration including parsing, tactic application, and proof verification. - -## Features - -### 1. SMT-LIB 2.0 Parser - -Complete parser supporting: -- **Declarations**: `declare-const`, `declare-fun` -- **Assertions**: `assert` statements -- **Commands**: `check-sat`, `get-model`, `set-logic`, `set-option` -- **Quantifiers**: `forall`, `exists` with typed bindings -- **Let bindings**: Local variable definitions -- **Comments**: Semicolon-based comments - -### 2. Supported SMT Theories - -- **QF_UF**: Uninterpreted functions with equality -- **QF_LIA**: Linear integer arithmetic -- **QF_NIA**: Nonlinear integer arithmetic -- **QF_BV**: Fixed-size bitvectors -- **ALL**: All supported theories (for quantified formulas) -- Arrays, datatypes, and more - -### 3. Process Management - -- Asynchronous Z3 process spawning -- Configurable timeouts (default: 300 seconds) -- Proper stdin/stdout/stderr handling -- Clean process termination - -### 4. Term Conversion - -Bidirectional conversion between: -- SMT-LIB 2.0 terms (SmtTerm) -- ECHIDNA universal terms (Term) - -Supports: -- Symbols and constants -- Function applications -- Quantified formulas -- Let expressions - -### 5. Tactic Support - -Built-in Z3 tactics: -- `simplify` - Term simplification -- `solve-eqs` - Equation solving -- `ctx-simplify` - Context-aware simplification -- `propagate-values` - Value propagation -- `normalize-bounds` - Bound normalization -- `lia2pb`, `pb2bv`, `bit-blast` - Arithmetic encoding - -### 6. Proof Verification - -Validates proofs by checking if goal negation is unsatisfiable. - -## Usage Example - -```rust -use echidna::{ProverBackend, ProverConfig}; -use std::path::PathBuf; - -let config = ProverConfig { - executable: PathBuf::from("z3"), - timeout: 60, - ..Default::default() -}; - -let backend = z3::Z3Backend::new(config); -let state = backend.parse_file( - PathBuf::from("examples/z3_simple.smt2") -).await?; - -let is_valid = backend.verify_proof(&state).await?; -``` - -## Implementation Details - -**File**: `/home/user/echidna/src/rust/provers/z3.rs` -**Lines**: ~850 (including parser and tests) -**Complexity**: 2/5 -**Tier**: 1 - -## Testing - -```bash -cargo test --lib z3 -``` - -## License - -MIT OR Palimpsest-0.6 diff --git a/docs/isabelle-backend.md b/docs/isabelle-backend.adoc similarity index 55% rename from docs/isabelle-backend.md rename to docs/isabelle-backend.adoc index 28c6d5fb..0daa8066 100644 --- a/docs/isabelle-backend.md +++ b/docs/isabelle-backend.adoc @@ -1,48 +1,50 @@ -# Isabelle/HOL Backend Implementation +== Isabelle/HOL Backend Implementation -## Overview +=== Overview -Complete production-ready Isabelle/HOL backend implementation for ECHIDNA at `/home/user/echidna/src/rust/provers/isabelle.rs`. +Complete production-ready Isabelle/HOL backend implementation for +ECHIDNA at `+/home/user/echidna/src/rust/provers/isabelle.rs+`. -**Status**: ✅ Implemented and Tested -**Tier**: 1 (Priority Prover) -**Complexity**: 4/5 -**Lines of Code**: 313 +*Status*: ✅ Implemented and Tested *Tier*: 1 (Priority Prover) +*Complexity*: 4/5 *Lines of Code*: 313 -## Features Implemented +=== Features Implemented -### 1. IsabelleBackend Struct with PIDE Server Management +==== 1. IsabelleBackend Struct with PIDE Server Management -```rust +[source,rust] +---- pub struct IsabelleBackend { config: ProverConfig, server: Arc>, context: Context, } -``` +---- -- **PIDE Server**: Protocol IDE for interactive proof development -- **Async server management**: Start/stop Isabelle server process -- **Port discovery**: Automatic detection of server port from output -- **Thread-safe access**: Arc for concurrent access +* *PIDE Server*: Protocol IDE for interactive proof development +* *Async server management*: Start/stop Isabelle server process +* *Port discovery*: Automatic detection of server port from output +* *Thread-safe access*: Arc for concurrent access -### 2. Theory File Parser +==== 2. Theory File Parser -Parses Isabelle/HOL `.thy` files with support for: +Parses Isabelle/HOL `+.thy+` files with support for: -- **Theory headers**: `theory Name imports Main begin` -- **Lemma declarations**: Extract theorem statements -- **Proof structures**: Both apply-style and Isar proofs -- **Documentation blocks**: Text and section markers +* *Theory headers*: `+theory Name imports Main begin+` +* *Lemma declarations*: Extract theorem statements +* *Proof structures*: Both apply-style and Isar proofs +* *Documentation blocks*: Text and section markers -```rust +[source,rust] +---- async fn parse_file(&self, path: PathBuf) -> Result async fn parse_string(&self, content: &str) -> Result -``` +---- -### 3. PIDE Protocol Communication +==== 3. PIDE Protocol Communication -```rust +[source,rust] +---- pub struct PideServer { process: Option, port: u16, @@ -52,30 +54,33 @@ impl PideServer { pub async fn start(&mut self, executable: &PathBuf) -> Result<()> pub async fn stop(&mut self) -> Result<()> } -``` +---- -- Launches Isabelle server process -- Captures stdout/stderr for debugging -- Parses server port from output -- Clean shutdown on drop +* Launches Isabelle server process +* Captures stdout/stderr for debugging +* Parses server port from output +* Clean shutdown on drop -### 4. Tactic Execution +==== 4. Tactic Execution Supports multiple Isabelle tactics: -- **Simplification**: `simp`, `auto`, `blast`, `fastforce` -- **Assumption**: Solve goals using hypotheses -- **Induction**: Creates base case and inductive case subgoals -- **Cases**: Case analysis with True/False branches -- **Sledgehammer**: Automated theorem proving integration -- **Custom tactics**: Extensible framework for prover-specific commands +* *Simplification*: `+simp+`, `+auto+`, `+blast+`, `+fastforce+` +* *Assumption*: Solve goals using hypotheses +* *Induction*: Creates base case and inductive case subgoals +* *Cases*: Case analysis with True/False branches +* *Sledgehammer*: Automated theorem proving integration +* *Custom tactics*: Extensible framework for prover-specific commands -```rust +[source,rust] +---- async fn apply_tactic(&self, state: &ProofState, tactic: &Tactic) -> Result -``` +---- Example tactic execution: -```rust + +[source,rust] +---- match tactic { Tactic::Simplify => self.execute_tactic(state).await, Tactic::Induction(_) => { @@ -88,13 +93,15 @@ match tactic { Ok(TacticResult::Success(new_state)) } } -``` +---- -### 5. Term Conversion +==== 5. Term Conversion -Bidirectional conversion between Isabelle/HOL and universal term representation: +Bidirectional conversion between Isabelle/HOL and universal term +representation: -```rust +[source,rust] +---- pub enum IsabelleTerm { Var(String), Const(String), @@ -104,63 +111,61 @@ pub enum IsabelleTerm { List(Vec), Num(i64), } -``` +---- -**Conversion features**: -- Variables and constants -- Function application (curried) -- Lambda abstractions with optional types -- Infix operators (`=`, `+`, `*`, `<`, `>`, `∧`, `∨`, `→`, `↔`) -- Lists (encoded as Cons cells) -- Numeric literals +*Conversion features*: - Variables and constants - Function application +(curried) - Lambda abstractions with optional types - Infix operators +(`+=+`, `+++`, `+*+`, `+<+`, `+>+`, `+∧+`, `+∨+`, `+→+`, `+↔+`) - Lists +(encoded as Cons cells) - Numeric literals -```rust +[source,rust] +---- fn isabelle_to_universal(&self, term: &IsabelleTerm) -> Term -``` +---- Example: -```isabelle + +[source,isabelle] +---- A → B (* Isabelle infix *) -``` +---- + converts to: -```rust + +[source,rust] +---- Term::App { func: Box::new(Term::Const("→")), args: vec![Term::Var("A"), Term::Var("B")] } -``` +---- -### 6. Sledgehammer Integration +==== 6. Sledgehammer Integration -Isabelle's powerful automated theorem prover integration: +Isabelle’s powerful automated theorem prover integration: -```rust +[source,rust] +---- Tactic::Custom { prover: "isabelle", command: "sledgehammer", args: vec![], } -``` - -Sledgehammer invokes external ATP/SMT solvers: -- **E prover** -- **SPASS** -- **Z3** -- **CVC4/CVC5** -- **Vampire** -- **And more...** - -In production, this would: -1. Send current proof state to Isabelle -2. Invoke sledgehammer with timeout -3. Parse suggested lemmas and tactics +---- + +Sledgehammer invokes external ATP/SMT solvers: - *E prover* - *SPASS* - +*Z3* - *CVC4/CVC5* - *Vampire* - *And more…* + +In production, this would: 1. Send current proof state to Isabelle 2. +Invoke sledgehammer with timeout 3. Parse suggested lemmas and tactics 4. Return reconstructed proof -### 7. Complete ProverBackend Trait Implementation +==== 7. Complete ProverBackend Trait Implementation All 11 trait methods fully implemented: -```rust +[source,rust] +---- #[async_trait] impl ProverBackend for IsabelleBackend { fn kind(&self) -> ProverKind @@ -175,18 +180,21 @@ impl ProverBackend for IsabelleBackend { fn config(&self) -> &ProverConfig fn set_config(&mut self, config: ProverConfig) } -``` +---- -### 8. Theory Export +==== 8. Theory Export Converts proof states back to Isabelle/HOL theory format: -```rust +[source,rust] +---- async fn export(&self, state: &ProofState) -> Result -``` +---- Example output: -```isabelle + +[source,isabelle] +---- theory GeneratedProof imports Main begin @@ -200,13 +208,14 @@ lemma modus_ponens: sorry end -``` +---- -### 9. Proof Verification +==== 9. Proof Verification Verifies proofs by running Isabelle build: -```rust +[source,rust] +---- async fn verify_proof(&self, state: &ProofState) -> Result { let theory_content = self.export_theory(state)?; let temp_path = std::env::temp_dir().join("echidna_verify.thy"); @@ -221,13 +230,14 @@ async fn verify_proof(&self, state: &ProofState) -> Result { Ok(output.status.success()) } -``` +---- -### 10. Tactic Suggestions +==== 10. Tactic Suggestions Neural-assisted and heuristic-based tactic suggestions: -```rust +[source,rust] +---- async fn suggest_tactics(&self, state: &ProofState, limit: usize) -> Result> { let mut suggestions = vec![ Tactic::Simplify, @@ -238,48 +248,53 @@ async fn suggest_tactics(&self, state: &ProofState, limit: usize) -> Result anyhow::Result<()> { Ok(()) } -``` +---- -## Architecture +=== Architecture -``` +.... IsabelleBackend ├── PIDE Server Management │ ├── Process spawning (tokio) @@ -383,64 +399,74 @@ IsabelleBackend ├── Theory file generation ├── isabelle build invocation └── Status checking -``` +.... -## Dependencies +=== Dependencies -```toml +[source,toml] +---- [dependencies] tokio = { version = "1.35", features = ["full"] } async-trait = "0.1" anyhow = "1.0" serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" -``` - -## Performance Characteristics - -- **Parse time**: O(n) where n is theory file size -- **Term conversion**: O(t) where t is term tree depth -- **Tactic execution**: Depends on Isabelle server response (typically 100ms-5s) -- **Sledgehammer**: 30 seconds default timeout (configurable) -- **Memory**: Minimal overhead, most data lives in Isabelle process - -## Future Enhancements - -1. **Full parser implementation**: Currently simplified, could use nom combinators for complete .thy parsing -2. **Advanced PIDE protocol**: Implement full JSON-RPC communication -3. **Proof caching**: Cache sledgehammer results for faster replay -4. **Parallel tactic search**: Try multiple tactics concurrently -5. **Neural premise selection**: Integrate ML model for smarter tactic suggestions -6. **Incremental checking**: Only re-check changed parts of theories -7. **Jedit integration**: Connect to Isabelle/jEdit for IDE features - -## Integration with ECHIDNA - -The Isabelle backend integrates seamlessly with ECHIDNA's 12-prover architecture: - -- **Tier 1 status**: Isabelle is a priority prover covering ~15% of standard theorems -- **HOL foundation**: Shares type theory with HOL Light, HOL4, and Mizar -- **ATP bridge**: Sledgehammer provides access to multiple external solvers -- **Aspect tagging**: Theorems can be tagged with semantic aspects -- **Neural integration**: Ready for neural premise selection (neural integration ready) - -## Compliance - -- ✅ **RSR/CCCP**: Follows Rhodium Standard Repository guidelines -- ✅ **Dual licensing**: MIT OR Palimpsest-0.6 -- ✅ **REUSE compliant**: SPDX headers on all files -- ✅ **Documentation**: Comprehensive inline docs and examples -- ✅ **Testing**: Unit tests with >80% coverage - -## References - -- [Isabelle/HOL Documentation](https://isabelle.in.tum.de/documentation.html) -- [PIDE Protocol](https://isabelle.in.tum.de/dist/Isabelle2024/doc/implementation.pdf) -- [Sledgehammer Paper](https://doi.org/10.1007/978-3-642-22863-6_11) -- [ECHIDNA Architecture](../CLAUDE.md) - ---- - -**Implemented by**: ECHIDNA Project Team -**Date**: 2025-11-22 -**File**: `/home/user/echidna/src/rust/provers/isabelle.rs` +---- + +=== Performance Characteristics + +* *Parse time*: O(n) where n is theory file size +* *Term conversion*: O(t) where t is term tree depth +* *Tactic execution*: Depends on Isabelle server response (typically +100ms-5s) +* *Sledgehammer*: 30 seconds default timeout (configurable) +* *Memory*: Minimal overhead, most data lives in Isabelle process + +=== Future Enhancements + +[arabic] +. *Full parser implementation*: Currently simplified, could use nom +combinators for complete .thy parsing +. *Advanced PIDE protocol*: Implement full JSON-RPC communication +. *Proof caching*: Cache sledgehammer results for faster replay +. *Parallel tactic search*: Try multiple tactics concurrently +. *Neural premise selection*: Integrate ML model for smarter tactic +suggestions +. *Incremental checking*: Only re-check changed parts of theories +. *Jedit integration*: Connect to Isabelle/jEdit for IDE features + +=== Integration with ECHIDNA + +The Isabelle backend integrates seamlessly with ECHIDNA’s 12-prover +architecture: + +* *Tier 1 status*: Isabelle is a priority prover covering ~15% of +standard theorems +* *HOL foundation*: Shares type theory with HOL Light, HOL4, and Mizar +* *ATP bridge*: Sledgehammer provides access to multiple external +solvers +* *Aspect tagging*: Theorems can be tagged with semantic aspects +* *Neural integration*: Ready for neural premise selection (neural +integration ready) + +=== Compliance + +* ✅ *RSR/CCCP*: Follows Rhodium Standard Repository guidelines +* ✅ *Dual licensing*: MIT OR Palimpsest-0.6 +* ✅ *REUSE compliant*: SPDX headers on all files +* ✅ *Documentation*: Comprehensive inline docs and examples +* ✅ *Testing*: Unit tests with >80% coverage + +=== References + +* https://isabelle.in.tum.de/documentation.html[Isabelle/HOL +Documentation] +* https://isabelle.in.tum.de/dist/Isabelle2024/doc/implementation.pdf[PIDE +Protocol] +* https://doi.org/10.1007/978-3-642-22863-6_11[Sledgehammer Paper] +* link:../CLAUDE.md[ECHIDNA Architecture] + +''''' + +*Implemented by*: ECHIDNA Project Team *Date*: 2025-11-22 *File*: +`+/home/user/echidna/src/rust/provers/isabelle.rs+` diff --git a/docs/releases/RELEASE_NOTES_v1.2.adoc b/docs/releases/RELEASE_NOTES_v1.2.adoc new file mode 100644 index 00000000..e855a7f5 --- /dev/null +++ b/docs/releases/RELEASE_NOTES_v1.2.adoc @@ -0,0 +1,236 @@ +== ECHIDNA v1.2 Release Notes + +*Release Date:* 2026-01-29 *Tag:* v1.2.0 *Status:* Production Ready + +=== Overview + +ECHIDNA v1.2 completes the core neurosymbolic theorem proving +infrastructure with *all 12 prover backends operational*, expanded +training data, and comprehensive trust & validation frameworks. + +=== What’s New + +==== 🎯 All 12 Prover Backends Complete + +Successfully integrated all planned interactive theorem provers: + +*Tier 1 (Production):* - ✅ Coq 8.18+ - Fully operational - ✅ Lean 4 - +Fully operational - ✅ Isabelle/HOL - Fully operational - ✅ Agda 2.6+ - +Fully operational + +*Tier 2 (SMT Solvers):* - ✅ Z3 - Fully operational - ✅ CVC5 - Fully +operational + +*Tier 3 (Specialized):* - ✅ ACL2 - Complete (1,737 lines, 5 examples) - +✅ PVS - Complete (2,785 lines, 5 examples) - ✅ HOL4 - Complete (2,257 +lines, 5 examples) - ✅ Mizar - Operational - ✅ HOL Light - Operational +- ✅ Metamath - Operational + +*Total Coverage:* 12/12 provers (100%) + +==== 📚 Training Data Expansion (3x) + +Massively expanded proof corpus for ML training: + +* *Proofs:* 107 → *332* (+210%) +* *Tactics:* 585 → *1,603* (+174%) +* *Vocabulary:* 62 → *161 words* (+160%) +* *Prover Balance:* +** Before: 69% Coq, 20% Lean, 11% others (imbalanced) +** After: 40% Lean, 22% Coq, 38% others (balanced) + +*New Sources:* - `+examples/acl2/+` - 11 ACL2 proofs - `+examples/pvs/+` +- 7 PVS proofs - `+examples/hol4/+` - 5 HOL4 proofs - +`+examples/mizar/+` - 7 Mizar proofs - Additional Lean, Agda, Isabelle +examples + +==== 🧪 Trust & Validation Framework + +Comprehensive multi-layer validation system to ensure soundness: + +*1. Performance Benchmarking* - Criterion.rs integration +(`+benches/proof_benchmarks.rs+`) - Tracks: proof search, ML inference, +parsing, tree construction - Regression detection via CI + +*2. Property-Based Testing* - PropTest integration +(`+tests/property_tests.rs+`) - 8 core invariants validated: - +Confidence bounds (0.0 ≤ c ≤ 1.0) - Roundtrip serialization - +Deterministic predictions - Tactic application validity - Goal reduction +monotonicity - Premise relevance - Circular reasoning detection - Proof +tree coherence + +*3. Formal Verification* - Idris2 proof validator (`+src/idris/+`) - +Dependent-typed AST (`+ProofTerm.idr+`) - Total type checker with +termination guarantees - Detects: type mismatches, circular reasoning, +invalid tactics - Formal soundness theorem signature + +*4. Anomaly Detection* - 7 anomaly types +(`+src/rust/anomaly_detection.rs+`): - Overconfidence on complex +theorems - Multi-prover disagreement - Circular reasoning - Excessive +complexity - Type mismatches - Invalid tactic sequences - Anomalous +proof times - Multi-prover consensus checker (configurable threshold) + +*Documentation:* - +link:./TRUST_AND_VALIDATION_FRAMEWORK.md[TRUST_AND_VALIDATION_FRAMEWORK.md] +(30,000 words) - +link:./TRUST_IMPLEMENTATION_GUIDE.md[TRUST_IMPLEMENTATION_GUIDE.md] +(5-phase rollout) + +==== 🚀 Chapel Parallelism Analysis + +Explored high-performance parallel proof search: + +*Chapel Proof-of-Concept:* - Parallel search across 12 provers +(`+chapel_poc/parallel_proof_search.chpl+`) - Results: *9/12 provers +succeeded* in parallel - Demonstrates `+coforall+` task parallelism - +Beam search with parallel proof space exploration + +*Findings:* - ✅ Chapel metalayer is *viable* for ECHIDNA - Enables +proof quality selection (e.g., shortest proof) - Validates robustness +(HOL4 succeeded as fallback at 1.41s) - Implementation estimate: 2-4 +developer-months + +*Documentation:* - +link:./CHAPEL_METALAYER_ANALYSIS.md[CHAPEL_METALAYER_ANALYSIS.md] (5,200 +lines) - +link:./CHAPEL_PLUGGABILITY_DESIGN.md[CHAPEL_PLUGGABILITY_DESIGN.md] +(trait-based abstraction) - +link:./chapel_poc/RESULTS.md[chapel_poc/RESULTS.md] + +*Zig Alternative:* - link:./ZIG_FFI_ANALYSIS.md[ZIG_FFI_ANALYSIS.md] - +Zig recommended over C for FFI: compile-time safety, better error +handling - Implementation estimate: 1-2 developer-months + +==== 🏗️ Build & Validation System + +Standardized development workflow: + +*Justfile Recipes:* - `+just build+` - Compile all components - +`+just test+` - Run all tests - `+just bench+` - Performance benchmarks +- `+just check+` - Quality checks - `+just must+` - Pre-merge validation +(10 requirements) + +*Must Validation Requirements:* 1. Code builds cleanly 2. All tests pass +3. Benchmarks complete 4. No security warnings 5. Code formatted 6. No +linter errors 7. Docs build 8. Examples work 9. Git clean (no +uncommitted changes) 10. Passes trust validation + +link:./JUST_AND_MUST_FRAMEWORK.md[JUST_AND_MUST_FRAMEWORK.md] + +==== 📊 Development Roadmap + +Prioritized 40+ features across 8 categories: + +* *Core Proving* (15 features) +* *Neural Learning* (8 features) +* *Performance* (6 features) +* *Integration* (4 features) +* *UI/UX* (3 features) +* *Documentation* (2 features) +* *Infrastructure* (2 features) +* *Trust & Validation* (2 features) + +link:./FUTURE_DEVELOPMENT_ROADMAP.md[FUTURE_DEVELOPMENT_ROADMAP.md] + +=== Technical Details + +==== Architecture + +.... +AffineScript UI (Browser) + ↓ Fetch API +Rust Backend (Axum HTTP) + ↓ reqwest +Julia ML API (HTTP.jl) + ↓ Models +12 Prover Backends (stdio) +.... + +==== Performance + +* *Proof Search:* ~50ms average (simple theorems) +* *ML Inference:* ~5ms per prediction (Julia) +* *Parser:* ~2ms per proof +* *Proof Tree:* ~10ms construction + +==== Test Coverage + +* *Unit Tests:* 120 passing +* *Property Tests:* 8 properties × 1000 cases each +* *Integration Tests:* 8 scenarios +* *Benchmarks:* 4 benchmark groups + +==== Example Libraries + +* *69 theorems* across 15 files +* *332 proofs* in training set +* Covers: arithmetic, algebra, lists, logic, induction + +=== Breaking Changes + +None - v1.2 is fully backward compatible with v1.1. + +=== Bug Fixes + +* Fixed anomaly detection thresholds (≥2 foralls, ≥1 exists) +* Fixed test_complex_theorem_detection (threshold sensitivity) +* Fixed test_anomaly_detection (test case clarity) +* Corrected Chapel 2.2 string formatting (writef vs .format()) + +=== Known Issues + +* UI needs syntax highlighting for all 12 provers +* Documentation could use more examples +* Performance benchmarking baseline needed +* AffineScript affinescript.json uses deprecated '`es6`' → should be +'`esmodule`' + +=== Upgrade Notes + +==== From v1.1 + +No breaking changes. Simply rebuild: + +[source,bash] +---- +cargo build --release +cd src/affinescript && npm run build +---- + +==== New Dependencies + +* Julia packages: HTTP, JSON3, LinearAlgebra +* Rust crates: reqwest (for ML API client) + +=== Contributors + +* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk +* Claude Sonnet 4.5 (AI pair programmer) + +=== Next Steps (v1.3) + +* ✅ Connect Rust backend to Julia ML API (DONE) +* ✅ Connect AffineScript UI to Rust HTTP server (DONE) +* ✅ End-to-end proof flow testing (DONE) +* □ Train neural models on 600+ proof corpus +* □ Polish UI with proof tree visualization +* □ Deploy demo instance + +=== License + +MIT OR Palimpsest-0.6 + +=== Links + +* Repository: https://github.com/hyperpolymath/echidna +* Documentation: https://echidna.hyperpolymath.org +* Issues: https://github.com/hyperpolymath/echidna/issues + +''''' + +*Total Accomplishments:* - 12/12 prover backends operational ✓ - 332 +proofs, 1,603 tactics, 161 vocabulary words ✓ - Comprehensive trust +framework ✓ - Chapel parallelism validated ✓ - Build system standardized +✓ - Test coverage: 120 unit + 8000 property + 8 integration ✓ + +*Release Status:* ✅ Production Ready diff --git a/docs/releases/RELEASE_NOTES_v1.2.md b/docs/releases/RELEASE_NOTES_v1.2.md deleted file mode 100644 index 79f46519..00000000 --- a/docs/releases/RELEASE_NOTES_v1.2.md +++ /dev/null @@ -1,266 +0,0 @@ -# ECHIDNA v1.2 Release Notes - -**Release Date:** 2026-01-29 -**Tag:** v1.2.0 -**Status:** Production Ready - -## Overview - -ECHIDNA v1.2 completes the core neurosymbolic theorem proving infrastructure with **all 12 prover backends operational**, expanded training data, and comprehensive trust & validation frameworks. - -## What's New - -### 🎯 All 12 Prover Backends Complete - -Successfully integrated all planned interactive theorem provers: - -**Tier 1 (Production):** -- ✅ Coq 8.18+ - Fully operational -- ✅ Lean 4 - Fully operational -- ✅ Isabelle/HOL - Fully operational -- ✅ Agda 2.6+ - Fully operational - -**Tier 2 (SMT Solvers):** -- ✅ Z3 - Fully operational -- ✅ CVC5 - Fully operational - -**Tier 3 (Specialized):** -- ✅ ACL2 - Complete (1,737 lines, 5 examples) -- ✅ PVS - Complete (2,785 lines, 5 examples) -- ✅ HOL4 - Complete (2,257 lines, 5 examples) -- ✅ Mizar - Operational -- ✅ HOL Light - Operational -- ✅ Metamath - Operational - -**Total Coverage:** 12/12 provers (100%) - -### 📚 Training Data Expansion (3x) - -Massively expanded proof corpus for ML training: - -- **Proofs:** 107 → **332** (+210%) -- **Tactics:** 585 → **1,603** (+174%) -- **Vocabulary:** 62 → **161 words** (+160%) -- **Prover Balance:** - - Before: 69% Coq, 20% Lean, 11% others (imbalanced) - - After: 40% Lean, 22% Coq, 38% others (balanced) - -**New Sources:** -- `examples/acl2/` - 11 ACL2 proofs -- `examples/pvs/` - 7 PVS proofs -- `examples/hol4/` - 5 HOL4 proofs -- `examples/mizar/` - 7 Mizar proofs -- Additional Lean, Agda, Isabelle examples - -### 🧪 Trust & Validation Framework - -Comprehensive multi-layer validation system to ensure soundness: - -**1. Performance Benchmarking** -- Criterion.rs integration (`benches/proof_benchmarks.rs`) -- Tracks: proof search, ML inference, parsing, tree construction -- Regression detection via CI - -**2. Property-Based Testing** -- PropTest integration (`tests/property_tests.rs`) -- 8 core invariants validated: - - Confidence bounds (0.0 ≤ c ≤ 1.0) - - Roundtrip serialization - - Deterministic predictions - - Tactic application validity - - Goal reduction monotonicity - - Premise relevance - - Circular reasoning detection - - Proof tree coherence - -**3. Formal Verification** -- Idris2 proof validator (`src/idris/`) -- Dependent-typed AST (`ProofTerm.idr`) -- Total type checker with termination guarantees -- Detects: type mismatches, circular reasoning, invalid tactics -- Formal soundness theorem signature - -**4. Anomaly Detection** -- 7 anomaly types (`src/rust/anomaly_detection.rs`): - - Overconfidence on complex theorems - - Multi-prover disagreement - - Circular reasoning - - Excessive complexity - - Type mismatches - - Invalid tactic sequences - - Anomalous proof times -- Multi-prover consensus checker (configurable threshold) - -**Documentation:** -- [TRUST_AND_VALIDATION_FRAMEWORK.md](./TRUST_AND_VALIDATION_FRAMEWORK.md) (30,000 words) -- [TRUST_IMPLEMENTATION_GUIDE.md](./TRUST_IMPLEMENTATION_GUIDE.md) (5-phase rollout) - -### 🚀 Chapel Parallelism Analysis - -Explored high-performance parallel proof search: - -**Chapel Proof-of-Concept:** -- Parallel search across 12 provers (`chapel_poc/parallel_proof_search.chpl`) -- Results: **9/12 provers succeeded** in parallel -- Demonstrates `coforall` task parallelism -- Beam search with parallel proof space exploration - -**Findings:** -- ✅ Chapel metalayer is **viable** for ECHIDNA -- Enables proof quality selection (e.g., shortest proof) -- Validates robustness (HOL4 succeeded as fallback at 1.41s) -- Implementation estimate: 2-4 developer-months - -**Documentation:** -- [CHAPEL_METALAYER_ANALYSIS.md](./CHAPEL_METALAYER_ANALYSIS.md) (5,200 lines) -- [CHAPEL_PLUGGABILITY_DESIGN.md](./CHAPEL_PLUGGABILITY_DESIGN.md) (trait-based abstraction) -- [chapel_poc/RESULTS.md](./chapel_poc/RESULTS.md) - -**Zig Alternative:** -- [ZIG_FFI_ANALYSIS.md](./ZIG_FFI_ANALYSIS.md) -- Zig recommended over C for FFI: compile-time safety, better error handling -- Implementation estimate: 1-2 developer-months - -### 🏗️ Build & Validation System - -Standardized development workflow: - -**Justfile Recipes:** -- `just build` - Compile all components -- `just test` - Run all tests -- `just bench` - Performance benchmarks -- `just check` - Quality checks -- `just must` - Pre-merge validation (10 requirements) - -**Must Validation Requirements:** -1. Code builds cleanly -2. All tests pass -3. Benchmarks complete -4. No security warnings -5. Code formatted -6. No linter errors -7. Docs build -8. Examples work -9. Git clean (no uncommitted changes) -10. Passes trust validation - -[JUST_AND_MUST_FRAMEWORK.md](./JUST_AND_MUST_FRAMEWORK.md) - -### 📊 Development Roadmap - -Prioritized 40+ features across 8 categories: - -- **Core Proving** (15 features) -- **Neural Learning** (8 features) -- **Performance** (6 features) -- **Integration** (4 features) -- **UI/UX** (3 features) -- **Documentation** (2 features) -- **Infrastructure** (2 features) -- **Trust & Validation** (2 features) - -[FUTURE_DEVELOPMENT_ROADMAP.md](./FUTURE_DEVELOPMENT_ROADMAP.md) - -## Technical Details - -### Architecture - -``` -AffineScript UI (Browser) - ↓ Fetch API -Rust Backend (Axum HTTP) - ↓ reqwest -Julia ML API (HTTP.jl) - ↓ Models -12 Prover Backends (stdio) -``` - -### Performance - -- **Proof Search:** ~50ms average (simple theorems) -- **ML Inference:** ~5ms per prediction (Julia) -- **Parser:** ~2ms per proof -- **Proof Tree:** ~10ms construction - -### Test Coverage - -- **Unit Tests:** 120 passing -- **Property Tests:** 8 properties × 1000 cases each -- **Integration Tests:** 8 scenarios -- **Benchmarks:** 4 benchmark groups - -### Example Libraries - -- **69 theorems** across 15 files -- **332 proofs** in training set -- Covers: arithmetic, algebra, lists, logic, induction - -## Breaking Changes - -None - v1.2 is fully backward compatible with v1.1. - -## Bug Fixes - -- Fixed anomaly detection thresholds (≥2 foralls, ≥1 exists) -- Fixed test_complex_theorem_detection (threshold sensitivity) -- Fixed test_anomaly_detection (test case clarity) -- Corrected Chapel 2.2 string formatting (writef vs .format()) - -## Known Issues - -- UI needs syntax highlighting for all 12 provers -- Documentation could use more examples -- Performance benchmarking baseline needed -- AffineScript affinescript.json uses deprecated 'es6' → should be 'esmodule' - -## Upgrade Notes - -### From v1.1 - -No breaking changes. Simply rebuild: - -```bash -cargo build --release -cd src/affinescript && npm run build -``` - -### New Dependencies - -- Julia packages: HTTP, JSON3, LinearAlgebra -- Rust crates: reqwest (for ML API client) - -## Contributors - -- Jonathan D.A. Jewell -- Claude Sonnet 4.5 (AI pair programmer) - -## Next Steps (v1.3) - -- ✅ Connect Rust backend to Julia ML API (DONE) -- ✅ Connect AffineScript UI to Rust HTTP server (DONE) -- ✅ End-to-end proof flow testing (DONE) -- □ Train neural models on 600+ proof corpus -- □ Polish UI with proof tree visualization -- □ Deploy demo instance - -## License - -MIT OR Palimpsest-0.6 - -## Links - -- Repository: https://github.com/hyperpolymath/echidna -- Documentation: https://echidna.hyperpolymath.org -- Issues: https://github.com/hyperpolymath/echidna/issues - ---- - -**Total Accomplishments:** -- 12/12 prover backends operational ✓ -- 332 proofs, 1,603 tactics, 161 vocabulary words ✓ -- Comprehensive trust framework ✓ -- Chapel parallelism validated ✓ -- Build system standardized ✓ -- Test coverage: 120 unit + 8000 property + 8 integration ✓ - -**Release Status:** ✅ Production Ready diff --git a/docs/releases/RELEASE_NOTES_v1.3.adoc b/docs/releases/RELEASE_NOTES_v1.3.adoc new file mode 100644 index 00000000..2cdcffd5 --- /dev/null +++ b/docs/releases/RELEASE_NOTES_v1.3.adoc @@ -0,0 +1,356 @@ +== ECHIDNA v1.3 Release Notes + +*Release Date:* 2026-01-29 *Tag:* v1.3.0 *Status:* Production Ready - +Full Stack Operational + +=== Overview + +ECHIDNA v1.3 completes the *end-to-end neurosymbolic proving stack*. All +three layers—Julia ML API, Rust backend, and AffineScript UI—are now +integrated and operational. Real AI-powered tactic suggestions flow from +trained models through the entire system. + +=== What’s New + +==== 🔗 Full Stack Integration + +*Three-Layer Architecture Connected:* + +.... +┌─────────────────┐ +│ AffineScript UI │ Port 3000 +│ (Browser) │ → Fetch API +└────────┬────────┘ + │ + ✓ Connected + │ +┌─────────────────┐ +│ Rust Backend │ Port 8081 +│ (HTTP Server) │ → reqwest +└────────┬────────┘ + │ + ✓ Connected + │ +┌─────────────────┐ +│ Julia ML API │ Port 9000 +│ (Trained │ → HTTP.jl +│ Models) │ +└─────────────────┘ +.... + +*Integration Details:* - Julia ML API server +(`+src/julia/api_server.jl+`) serves trained models via HTTP - Rust +backend calls Julia `+/suggest+` endpoint for AI predictions - Falls +back to prover-specific suggestions if ML unavailable - AffineScript UI +calls Rust `+/api/tactics/suggest+` endpoint - Real confidence scores: +reflexivity (0.321), simpl (0.288), intros (0.233) + +==== 🧠 Julia ML API Server + +*Endpoints:* - `+GET /health+` - Health check & model status - +`+POST /suggest+` - Tactic suggestions with confidence scores - +`+GET /info+` - Model metadata + +*Features:* - Bag-of-words text encoding (vocabulary: 161 words) - +Softmax probability distribution - Logistic regression classifier (8 +tactic classes) - CORS enabled for browser access - Graceful degradation +if models unavailable + +*Performance:* - Model load time: ~200ms - Inference time: ~5ms per +prediction - Memory usage: ~50MB (models loaded) + +==== 🦀 Rust Backend Enhancements + +*Updated Endpoints:* - `+POST /api/tactics/suggest+` - Now calls Julia +ML API - `+POST /api/session/create+` - Create interactive proof +sessions - `+GET /api/session/:id/state+` - Get current proof state - +`+POST /api/session/:id/apply+` - Apply tactic to session - +`+GET /api/session/:id/tree+` - Get proof tree structure - +`+GET /api/aspect-tags+` - Get domain & technique tags - +`+GET /api/theorems/search+` - Search theorem library + +*Total Endpoints:* 13 REST + 1 WebSocket + +*New Features:* - HTTP client for Julia ML API (reqwest) - Fallback to +prover suggestions if ML unavailable - Real-time AI confidence scores in +responses - Aspect tag inference (algebraic, geometric, logical, +inductive, deductive, automated) - Session management with proof state +tracking + +==== 📊 AffineScript UI + +*Status:* Compiled & Operational + +*Components:* - `+Main.res+` - App shell with state management - +`+Client.res+` - API client (calls Rust backend on port 8081) - +`+components/+` - 6 UI components: - ProofViewer - TacticSuggester - +TheoremSearch - ProofTree - AspectTags - SessionManager + +*Features:* - Connects to Rust backend via Fetch API - Displays ML +tactic suggestions with confidence - Aspect tag filtering - Proof tree +visualization (structure ready) - Session state management + +*Build System:* - AffineScript → ES6 modules - Output: `+.bs.js+` files +- Served via Python http.server (dev) + +==== 🧪 Comprehensive Testing + +*Integration Test Suite* (`+tests/integration_test.sh+`): + +*8 Tests:* 1. Julia ML API Health ✓ 2. Rust Backend Health ✓ 3. List +Available Provers (12) ✓ 4. Julia ML Tactic Suggestions ✓ 5. Rust → +Julia Integration ✓ 6. Create Proof Session ✓ 7. Get Aspect Tags (6) ✓ +8. UI Dev Server ✓ + +*All Tests Passing:* ✅ + +*Example Output:* + +[source,bash] +---- +$ ./tests/integration_test.sh +╔═══════════════════════════════════════════════════════════╗ +║ ECHIDNA v1.3 - Full Stack Integration Tests ║ +╚═══════════════════════════════════════════════════════════╝ + +Test 1: Julia ML API Health + ✓ Julia ML API responding + {premise_selector: true, tactic_predictor: true} + +Test 5: Rust Backend → Julia ML Integration + ✓ Got 5 suggestions via Rust backend + - reflexivity (confidence: 0.321) + - simpl (confidence: 0.288) + - intros (confidence: 0.233) + +╔═══════════════════════════════════════════════════════════╗ +║ All Integration Tests Passed ✓ ║ +╚═══════════════════════════════════════════════════════════╝ +---- + +==== 📖 Quick Start Guide + +*New Documentation:* - link:./QUICKSTART.md[QUICKSTART.md] - 5-minute +setup guide - Architecture overview with service diagram - Example REST +API usage - Troubleshooting guide - Development workflow + +*Start All Services (3 commands):* + +[source,bash] +---- +julia src/julia/api_server.jl & +./target/release/echidna server --port 8081 --enable-cors & +cd src/affinescript && python3 -m http.server 3000 & +---- + +*Access:* http://127.0.0.1:3000 + +=== Technical Details + +==== Data Flow + +[arabic] +. *User Input* → AffineScript UI captures goal +. *API Request* → Fetch POST to Rust `+/api/tactics/suggest+` +. *ML Inference* → Rust forwards to Julia `+/suggest+` +. *Model Prediction* → Julia runs logistic regression (332 proofs) +. *Response* → Julia returns tactics + confidences +. *Format* → Rust adds aspect tags, formats JSON +. *Display* → UI renders suggestions with confidence bars + +==== Model Details + +*Tactic Predictor:* - Algorithm: Logistic regression - Features: 161 +vocabulary words (bag-of-words) - Classes: 8 tactics (reflexivity, +simpl, intros, apply, rewrite, auto, induction, unfold) - Training data: +332 proofs, 1,603 tactics - Accuracy: ~65% top-1, ~85% top-3 + +*Premise Selector:* - Vocabulary: 870 terms - Currently vocabulary-based +(ML model in progress) + +==== Performance Benchmarks + +[cols=",,",options="header",] +|=== +|Operation |Time (avg) |Notes +|Julia model load |200ms |One-time startup +|ML inference |5ms |Per prediction +|Rust API request |8ms |Including ML call +|Full round-trip |15-20ms |UI → Rust → Julia → UI +|Prover fallback |50ms |If ML unavailable +|=== + +==== REST API Usage + +*Get Tactic Suggestions:* + +[source,bash] +---- +curl -X POST http://127.0.0.1:8081/api/tactics/suggest \ + -H "Content-Type: application/json" \ + -d '{ + "goal": "forall n : nat, n + 0 = n", + "prover": "Coq", + "top_k": 5 + }' +---- + +*Response:* + +[source,json] +---- +{ + "suggestions": [ + { + "tactic": "reflexivity", + "confidence": 0.321, + "premise": null, + "aspect_tags": ["algebraic", "deductive"] + }, + { + "tactic": "simpl", + "confidence": 0.288, + "premise": null, + "aspect_tags": ["algebraic", "deductive"] + } + ] +} +---- + +=== Breaking Changes + +None - v1.3 is fully backward compatible with v1.2. + +=== Improvements Over v1.2 + +[arabic] +. *Julia ML API* - Now serving predictions via HTTP (was: local training +only) +. *Rust Backend* - Now calls ML API (was: mock/prover suggestions only) +. *AffineScript UI* - Now connected to backend (was: standalone) +. *Integration Tests* - New 8-test suite (was: unit tests only) +. *Documentation* - Added QUICKSTART.md (was: scattered docs) + +=== Bug Fixes + +* Fixed server.rs imports (added reqwest, Duration) +* Fixed AppState to include ml_client and ml_api_url +* Fixed suggest_handler signature to receive State parameter +* Fixed AffineScript compilation warnings (unused variable) + +=== Known Issues + +* AffineScript deno bundle fails (not critical - ES6 modules work) +* UI needs syntax highlighting for all 12 provers +* Proof tree visualization structure ready but rendering incomplete +* aspect-tags endpoint returns null descriptions + +=== Deployment + +==== Requirements + +* Julia 1.10+ with HTTP, JSON3, LinearAlgebra +* Rust 1.75+ +* Python 3.8+ (dev server) +* 512MB RAM minimum (1GB recommended) +* Ports 3000, 8081, 9000 available + +==== Production Checklist + +* [ ] Build Rust in release mode: `+cargo build --release+` +* [ ] Compile AffineScript UI: `+cd src/affinescript && npm run build+` +* [ ] Train models if needed: `+julia src/julia/train_models.jl+` +* [ ] Start Julia ML API: `+julia src/julia/api_server.jl+` +* [ ] Start Rust backend: +`+./target/release/echidna server --port 8081+` +* [ ] Serve UI (production: nginx, dev: python http.server) +* [ ] Run integration tests: `+./tests/integration_test.sh+` + +==== Docker Compose (Recommended) + +[source,yaml] +---- +version: '3.8' +services: + julia-ml: + build: ./docker/julia + ports: ["9000:9000"] + volumes: ["./models:/app/models:ro"] + + rust-backend: + build: ./docker/rust + ports: ["8081:8081"] + depends_on: ["julia-ml"] + environment: + JULIA_ML_URL: "http://julia-ml:9000" + + ui: + build: ./docker/ui + ports: ["3000:80"] + depends_on: ["rust-backend"] +---- + +=== Upgrade Notes + +==== From v1.2 + +[arabic] +. Pull latest: `+git pull origin main+` +. Install Julia packages: +`+julia -e 'using Pkg; Pkg.add(["HTTP", "JSON3"])'+` +. Rebuild Rust: `+cargo build --release+` +. Rebuild AffineScript: `+cd src/affinescript && npm run build+` +. Start services (see Quick Start) +. Run tests: `+./tests/integration_test.sh+` + +==== Configuration + +*Julia ML API:* - Port: 9000 (default, change in +`+src/julia/api_server.jl:20+`) - Models dir: `+models/+` (relative to +repo root) + +*Rust Backend:* - Port: 8081 (default, CLI: `+--port+`) - Julia URL: +`+http://127.0.0.1:9000+` (hardcoded in server.rs:48) + +*AffineScript UI:* - API base: `+http://localhost:8081/api+` +(src/affinescript/src/api/Client.res:12) + +=== Contributors + +* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk +* Claude Sonnet 4.5 (AI pair programmer) + +=== Next Steps (v1.4) + +* [ ] Expand training data to 600+ proofs +* [ ] Implement proof tree visualization rendering +* [ ] Add syntax highlighting for all 12 provers +* [ ] Deploy demo instance (echidna-demo.hyperpolymath.org) +* [ ] Implement premise selector ML model +* [ ] Add WebSocket support for live proof sessions + +=== Acknowledgments + +Thanks to the theorem proving community: - Coq, Lean, Isabelle, Agda +development teams - SMT solver projects (Z3, CVC5) - ACL2, PVS, HOL4, +Mizar communities + +=== License + +MIT OR Palimpsest-0.6 + +=== Links + +* Repository: https://github.com/hyperpolymath/echidna +* Documentation: https://echidna.hyperpolymath.org +* Demo: http://127.0.0.1:3000 (local) +* Issues: https://github.com/hyperpolymath/echidna/issues + +''''' + +*v1.3 Highlights:* - ✅ Full stack integration (Julia ← Rust ← +AffineScript) - ✅ Real AI predictions with confidence scores - ✅ 13 +REST API endpoints operational - ✅ 8 integration tests passing - ✅ +5-minute quick start guide - ✅ Production ready deployment + +*Release Status:* 🚀 Production Ready - All Systems Operational diff --git a/docs/releases/RELEASE_NOTES_v1.3.md b/docs/releases/RELEASE_NOTES_v1.3.md deleted file mode 100644 index f239d63f..00000000 --- a/docs/releases/RELEASE_NOTES_v1.3.md +++ /dev/null @@ -1,371 +0,0 @@ -# ECHIDNA v1.3 Release Notes - -**Release Date:** 2026-01-29 -**Tag:** v1.3.0 -**Status:** Production Ready - Full Stack Operational - -## Overview - -ECHIDNA v1.3 completes the **end-to-end neurosymbolic proving stack**. All three layers—Julia ML API, Rust backend, and AffineScript UI—are now integrated and operational. Real AI-powered tactic suggestions flow from trained models through the entire system. - -## What's New - -### 🔗 Full Stack Integration - -**Three-Layer Architecture Connected:** - -``` -┌─────────────────┐ -│ AffineScript UI │ Port 3000 -│ (Browser) │ → Fetch API -└────────┬────────┘ - │ - ✓ Connected - │ -┌─────────────────┐ -│ Rust Backend │ Port 8081 -│ (HTTP Server) │ → reqwest -└────────┬────────┘ - │ - ✓ Connected - │ -┌─────────────────┐ -│ Julia ML API │ Port 9000 -│ (Trained │ → HTTP.jl -│ Models) │ -└─────────────────┘ -``` - -**Integration Details:** -- Julia ML API server (`src/julia/api_server.jl`) serves trained models via HTTP -- Rust backend calls Julia `/suggest` endpoint for AI predictions -- Falls back to prover-specific suggestions if ML unavailable -- AffineScript UI calls Rust `/api/tactics/suggest` endpoint -- Real confidence scores: reflexivity (0.321), simpl (0.288), intros (0.233) - -### 🧠 Julia ML API Server - -**Endpoints:** -- `GET /health` - Health check & model status -- `POST /suggest` - Tactic suggestions with confidence scores -- `GET /info` - Model metadata - -**Features:** -- Bag-of-words text encoding (vocabulary: 161 words) -- Softmax probability distribution -- Logistic regression classifier (8 tactic classes) -- CORS enabled for browser access -- Graceful degradation if models unavailable - -**Performance:** -- Model load time: ~200ms -- Inference time: ~5ms per prediction -- Memory usage: ~50MB (models loaded) - -### 🦀 Rust Backend Enhancements - -**Updated Endpoints:** -- `POST /api/tactics/suggest` - Now calls Julia ML API -- `POST /api/session/create` - Create interactive proof sessions -- `GET /api/session/:id/state` - Get current proof state -- `POST /api/session/:id/apply` - Apply tactic to session -- `GET /api/session/:id/tree` - Get proof tree structure -- `GET /api/aspect-tags` - Get domain & technique tags -- `GET /api/theorems/search` - Search theorem library - -**Total Endpoints:** 13 REST + 1 WebSocket - -**New Features:** -- HTTP client for Julia ML API (reqwest) -- Fallback to prover suggestions if ML unavailable -- Real-time AI confidence scores in responses -- Aspect tag inference (algebraic, geometric, logical, inductive, deductive, automated) -- Session management with proof state tracking - -### 📊 AffineScript UI - -**Status:** Compiled & Operational - -**Components:** -- `Main.res` - App shell with state management -- `Client.res` - API client (calls Rust backend on port 8081) -- `components/` - 6 UI components: - - ProofViewer - - TacticSuggester - - TheoremSearch - - ProofTree - - AspectTags - - SessionManager - -**Features:** -- Connects to Rust backend via Fetch API -- Displays ML tactic suggestions with confidence -- Aspect tag filtering -- Proof tree visualization (structure ready) -- Session state management - -**Build System:** -- AffineScript → ES6 modules -- Output: `.bs.js` files -- Served via Python http.server (dev) - -### 🧪 Comprehensive Testing - -**Integration Test Suite** (`tests/integration_test.sh`): - -**8 Tests:** -1. Julia ML API Health ✓ -2. Rust Backend Health ✓ -3. List Available Provers (12) ✓ -4. Julia ML Tactic Suggestions ✓ -5. Rust → Julia Integration ✓ -6. Create Proof Session ✓ -7. Get Aspect Tags (6) ✓ -8. UI Dev Server ✓ - -**All Tests Passing:** ✅ - -**Example Output:** -```bash -$ ./tests/integration_test.sh -╔═══════════════════════════════════════════════════════════╗ -║ ECHIDNA v1.3 - Full Stack Integration Tests ║ -╚═══════════════════════════════════════════════════════════╝ - -Test 1: Julia ML API Health - ✓ Julia ML API responding - {premise_selector: true, tactic_predictor: true} - -Test 5: Rust Backend → Julia ML Integration - ✓ Got 5 suggestions via Rust backend - - reflexivity (confidence: 0.321) - - simpl (confidence: 0.288) - - intros (confidence: 0.233) - -╔═══════════════════════════════════════════════════════════╗ -║ All Integration Tests Passed ✓ ║ -╚═══════════════════════════════════════════════════════════╝ -``` - -### 📖 Quick Start Guide - -**New Documentation:** -- [QUICKSTART.md](./QUICKSTART.md) - 5-minute setup guide -- Architecture overview with service diagram -- Example REST API usage -- Troubleshooting guide -- Development workflow - -**Start All Services (3 commands):** -```bash -julia src/julia/api_server.jl & -./target/release/echidna server --port 8081 --enable-cors & -cd src/affinescript && python3 -m http.server 3000 & -``` - -**Access:** http://127.0.0.1:3000 - -## Technical Details - -### Data Flow - -1. **User Input** → AffineScript UI captures goal -2. **API Request** → Fetch POST to Rust `/api/tactics/suggest` -3. **ML Inference** → Rust forwards to Julia `/suggest` -4. **Model Prediction** → Julia runs logistic regression (332 proofs) -5. **Response** → Julia returns tactics + confidences -6. **Format** → Rust adds aspect tags, formats JSON -7. **Display** → UI renders suggestions with confidence bars - -### Model Details - -**Tactic Predictor:** -- Algorithm: Logistic regression -- Features: 161 vocabulary words (bag-of-words) -- Classes: 8 tactics (reflexivity, simpl, intros, apply, rewrite, auto, induction, unfold) -- Training data: 332 proofs, 1,603 tactics -- Accuracy: ~65% top-1, ~85% top-3 - -**Premise Selector:** -- Vocabulary: 870 terms -- Currently vocabulary-based (ML model in progress) - -### Performance Benchmarks - -| Operation | Time (avg) | Notes | -|-----------|------------|-------| -| Julia model load | 200ms | One-time startup | -| ML inference | 5ms | Per prediction | -| Rust API request | 8ms | Including ML call | -| Full round-trip | 15-20ms | UI → Rust → Julia → UI | -| Prover fallback | 50ms | If ML unavailable | - -### REST API Usage - -**Get Tactic Suggestions:** -```bash -curl -X POST http://127.0.0.1:8081/api/tactics/suggest \ - -H "Content-Type: application/json" \ - -d '{ - "goal": "forall n : nat, n + 0 = n", - "prover": "Coq", - "top_k": 5 - }' -``` - -**Response:** -```json -{ - "suggestions": [ - { - "tactic": "reflexivity", - "confidence": 0.321, - "premise": null, - "aspect_tags": ["algebraic", "deductive"] - }, - { - "tactic": "simpl", - "confidence": 0.288, - "premise": null, - "aspect_tags": ["algebraic", "deductive"] - } - ] -} -``` - -## Breaking Changes - -None - v1.3 is fully backward compatible with v1.2. - -## Improvements Over v1.2 - -1. **Julia ML API** - Now serving predictions via HTTP (was: local training only) -2. **Rust Backend** - Now calls ML API (was: mock/prover suggestions only) -3. **AffineScript UI** - Now connected to backend (was: standalone) -4. **Integration Tests** - New 8-test suite (was: unit tests only) -5. **Documentation** - Added QUICKSTART.md (was: scattered docs) - -## Bug Fixes - -- Fixed server.rs imports (added reqwest, Duration) -- Fixed AppState to include ml_client and ml_api_url -- Fixed suggest_handler signature to receive State parameter -- Fixed AffineScript compilation warnings (unused variable) - -## Known Issues - -- AffineScript deno bundle fails (not critical - ES6 modules work) -- UI needs syntax highlighting for all 12 provers -- Proof tree visualization structure ready but rendering incomplete -- aspect-tags endpoint returns null descriptions - -## Deployment - -### Requirements - -- Julia 1.10+ with HTTP, JSON3, LinearAlgebra -- Rust 1.75+ -- Python 3.8+ (dev server) -- 512MB RAM minimum (1GB recommended) -- Ports 3000, 8081, 9000 available - -### Production Checklist - -- [ ] Build Rust in release mode: `cargo build --release` -- [ ] Compile AffineScript UI: `cd src/affinescript && npm run build` -- [ ] Train models if needed: `julia src/julia/train_models.jl` -- [ ] Start Julia ML API: `julia src/julia/api_server.jl` -- [ ] Start Rust backend: `./target/release/echidna server --port 8081` -- [ ] Serve UI (production: nginx, dev: python http.server) -- [ ] Run integration tests: `./tests/integration_test.sh` - -### Docker Compose (Recommended) - -```yaml -version: '3.8' -services: - julia-ml: - build: ./docker/julia - ports: ["9000:9000"] - volumes: ["./models:/app/models:ro"] - - rust-backend: - build: ./docker/rust - ports: ["8081:8081"] - depends_on: ["julia-ml"] - environment: - JULIA_ML_URL: "http://julia-ml:9000" - - ui: - build: ./docker/ui - ports: ["3000:80"] - depends_on: ["rust-backend"] -``` - -## Upgrade Notes - -### From v1.2 - -1. Pull latest: `git pull origin main` -2. Install Julia packages: `julia -e 'using Pkg; Pkg.add(["HTTP", "JSON3"])'` -3. Rebuild Rust: `cargo build --release` -4. Rebuild AffineScript: `cd src/affinescript && npm run build` -5. Start services (see Quick Start) -6. Run tests: `./tests/integration_test.sh` - -### Configuration - -**Julia ML API:** -- Port: 9000 (default, change in `src/julia/api_server.jl:20`) -- Models dir: `models/` (relative to repo root) - -**Rust Backend:** -- Port: 8081 (default, CLI: `--port`) -- Julia URL: `http://127.0.0.1:9000` (hardcoded in server.rs:48) - -**AffineScript UI:** -- API base: `http://localhost:8081/api` (src/affinescript/src/api/Client.res:12) - -## Contributors - -- Jonathan D.A. Jewell -- Claude Sonnet 4.5 (AI pair programmer) - -## Next Steps (v1.4) - -- [ ] Expand training data to 600+ proofs -- [ ] Implement proof tree visualization rendering -- [ ] Add syntax highlighting for all 12 provers -- [ ] Deploy demo instance (echidna-demo.hyperpolymath.org) -- [ ] Implement premise selector ML model -- [ ] Add WebSocket support for live proof sessions - -## Acknowledgments - -Thanks to the theorem proving community: -- Coq, Lean, Isabelle, Agda development teams -- SMT solver projects (Z3, CVC5) -- ACL2, PVS, HOL4, Mizar communities - -## License - -MIT OR Palimpsest-0.6 - -## Links - -- Repository: https://github.com/hyperpolymath/echidna -- Documentation: https://echidna.hyperpolymath.org -- Demo: http://127.0.0.1:3000 (local) -- Issues: https://github.com/hyperpolymath/echidna/issues - ---- - -**v1.3 Highlights:** -- ✅ Full stack integration (Julia ← Rust ← AffineScript) -- ✅ Real AI predictions with confidence scores -- ✅ 13 REST API endpoints operational -- ✅ 8 integration tests passing -- ✅ 5-minute quick start guide -- ✅ Production ready deployment - -**Release Status:** 🚀 Production Ready - All Systems Operational diff --git a/docs/reports/2026-06-06-hypatia-alert-classification.adoc b/docs/reports/2026-06-06-hypatia-alert-classification.adoc new file mode 100644 index 00000000..8f81305c --- /dev/null +++ b/docs/reports/2026-06-06-hypatia-alert-classification.adoc @@ -0,0 +1,174 @@ +== Hypatia Alert Classification Report + +Repository: `+hyperpolymath/echidna+` + +Date: 2026-06-06 + +This deposited report classifies the non-Dependabot code-scanning state +seen in `+echidna+`. It separates scanner/reporting debris from real +repository work, and it records which work should be handled by existing +systems, extended systems, or human/specialist review. + +=== Open Alert Count + +GitHub code scanning showed 249 open alerts. + +[width="99%",cols="24%,>30%,23%,23%",options="header",] +|=== +|Bucket |Count |Classification |Route +|Hypatia `+code_scanning_alerts/CSA001+` self-echo |27 |Reporting debris +|Standards/Hypatia SARIF fix, then clear stale alerts + +|Structural stale refs: `+SD022+`, `+SD007+` |28 |Lifecycle hygiene +|PR-only documentation/state cleanup + +|Workflow and Scorecard control-plane hygiene |51 |CI/security control +|Existing PR machinery, conservative batching + +|AffineScript migration findings |73 |Language migration |Batch by +subsystem, PR-only + +|Runtime crash/availability code safety |45 |Source risk |Context-aware +PRs, no blind rewrites + +|FFI/proof/memory-safety findings |22 |High-risk source/proof boundary +|Specialist review, proof route, report-only by default + +|Environment/report-only findings |3 |Control-plane topology |Observe, +model, and route manually +|=== + +=== Findings Expected To Dissolve + +The 27 `+code_scanning_alerts/CSA001+` alerts are not source work in +`+echidna+`. They should dissolve after: + +[arabic] +. the standards reusable SARIF converter stops uploading +`+code_scanning_alerts+` meta-findings; +. the next authoritative Hypatia run uploads an empty or reduced Hypatia +SARIF result set for that rule family; +. stale GitHub code-scanning alerts clear or are dismissed with +rationale. + +Related issue: https://github.com/hyperpolymath/standards/issues/378 + +=== Real Work Buckets + +==== Workflow and Scorecard Hygiene + +These are mostly easy or existing-system work. They include missing +`+timeout-minutes+`, Scorecard token-permission issues, and specific +workflow audit findings such as CodeQL language coverage and +secret-action gates. + +Recommended handling: + +* set proportional timeouts, not a universal 10-minute value; +* let Scorecard/CodeQL work already in flight finish before duplicating +work; +* use PR-only mode; +* verify workflows with focused CI. + +Related issue: https://github.com/hyperpolymath/echidna/issues/241 + +==== AffineScript Migration + +The 73 migration findings should be treated as one language-migration +campaign, not 73 isolated defects. + +Recommended handling: + +* group by API and subtree; +* preserve deliberate externals and FFI bindings with local rationale; +* batch migration work by subsystem; +* avoid whole-tree automatic rewrites without build verification. + +Related issue: https://github.com/hyperpolymath/echidna/issues/240 + +==== Structural Drift + +The 28 structural findings are stale references in docs and +machine-readable state. They are low-risk when the canonical replacement +path is known. + +Recommended handling: + +* map each old path to a current path or tombstone; +* keep machine-readable state parseable; +* update references in PR-only mode. + +Related issue: https://github.com/hyperpolymath/echidna/issues/242 + +==== Runtime Code Safety + +The unwrap, expect, panic, and lock-unwrap findings are plausible +source-risk signals. Some may be test-only or invariant-protected; +others need proper error propagation. + +Recommended handling: + +* separate tests and fixtures from production paths; +* replace production panics with typed errors only where behavior is +preserved; +* avoid replacing `+unwrap()+` with default values that could corrupt +prover state. + +Related issue: https://github.com/hyperpolymath/echidna/issues/239 + +==== FFI, Memory, And Proof Boundary + +The unsafe block, raw pointer, `+mem_forget+`, Zig pointer cast, and +Agda postulate findings are high-risk. They should not be auto-fixed +from pattern matching alone. + +Recommended handling: + +* route to echidnabot or proof review; +* require focused tests or proof obligations; +* use report-only unless a proven recipe exists. + +Related issue: https://github.com/hyperpolymath/echidna/issues/239 + +=== Summary By Action Class + +[width="100%",cols="30%,>40%,30%",options="header",] +|=== +|Action class |Count |Notes +|Dissolve as stale/reporting debris |27 |Self-echo SARIF artifacts + +|Trivial/easy existing-system PR work |79 |Workflow/Scorecard plus +structural docs/state + +|Readily accommodated by extended system |118 |AffineScript migration +plus runtime code-safety with context + +|High risk, specialist review only |22 |FFI/proof/memory boundary + +|Report-only environment topology |3 |Needs environment self-modeling +|=== + +=== Ordering + +The safe order is: + +[arabic] +. Fix the self-echo reporting path and clear stale alert debris. +. Let relevant in-flight GitHub Actions, CodeQL, Scorecard, and +Dependabot work finish when it covers the same class. +. Apply workflow and structural hygiene PRs. +. Run the AffineScript migration campaign by subsystem. +. Triage runtime code-safety paths. +. Hold FFI/proof/memory-safety items for specialist review. + +Doing this out of order can create more work than it removes. For +example, rewriting source before clearing stale SARIF debris makes alert +counts look worse, and blind workflow timeout edits can break formal or +live-prover jobs. + +=== Portfolio Note + +For `+Git in the Time of NeSy Agency+`, this report is an example of +repository portfolio triage: the useful unit is not a raw alert, but a +classified work order with route, cost, risk, and expected +class-collapse. diff --git a/docs/reports/2026-06-06-hypatia-alert-classification.md b/docs/reports/2026-06-06-hypatia-alert-classification.md deleted file mode 100644 index 893f1fd9..00000000 --- a/docs/reports/2026-06-06-hypatia-alert-classification.md +++ /dev/null @@ -1,146 +0,0 @@ - - - - -# Hypatia Alert Classification Report - -Repository: `hyperpolymath/echidna` - -Date: 2026-06-06 - -This deposited report classifies the non-Dependabot code-scanning state seen in -`echidna`. It separates scanner/reporting debris from real repository work, and -it records which work should be handled by existing systems, extended systems, -or human/specialist review. - -## Open Alert Count - -GitHub code scanning showed 249 open alerts. - -| Bucket | Count | Classification | Route | -| --- | ---: | --- | --- | -| Hypatia `code_scanning_alerts/CSA001` self-echo | 27 | Reporting debris | Standards/Hypatia SARIF fix, then clear stale alerts | -| Structural stale refs: `SD022`, `SD007` | 28 | Lifecycle hygiene | PR-only documentation/state cleanup | -| Workflow and Scorecard control-plane hygiene | 51 | CI/security control | Existing PR machinery, conservative batching | -| AffineScript migration findings | 73 | Language migration | Batch by subsystem, PR-only | -| Runtime crash/availability code safety | 45 | Source risk | Context-aware PRs, no blind rewrites | -| FFI/proof/memory-safety findings | 22 | High-risk source/proof boundary | Specialist review, proof route, report-only by default | -| Environment/report-only findings | 3 | Control-plane topology | Observe, model, and route manually | - -## Findings Expected To Dissolve - -The 27 `code_scanning_alerts/CSA001` alerts are not source work in `echidna`. -They should dissolve after: - -1. the standards reusable SARIF converter stops uploading `code_scanning_alerts` - meta-findings; -2. the next authoritative Hypatia run uploads an empty or reduced Hypatia SARIF - result set for that rule family; -3. stale GitHub code-scanning alerts clear or are dismissed with rationale. - -Related issue: - -## Real Work Buckets - -### Workflow and Scorecard Hygiene - -These are mostly easy or existing-system work. They include missing -`timeout-minutes`, Scorecard token-permission issues, and specific workflow -audit findings such as CodeQL language coverage and secret-action gates. - -Recommended handling: - -- set proportional timeouts, not a universal 10-minute value; -- let Scorecard/CodeQL work already in flight finish before duplicating work; -- use PR-only mode; -- verify workflows with focused CI. - -Related issue: - -### AffineScript Migration - -The 73 migration findings should be treated as one language-migration campaign, -not 73 isolated defects. - -Recommended handling: - -- group by API and subtree; -- preserve deliberate externals and FFI bindings with local rationale; -- batch migration work by subsystem; -- avoid whole-tree automatic rewrites without build verification. - -Related issue: - -### Structural Drift - -The 28 structural findings are stale references in docs and machine-readable -state. They are low-risk when the canonical replacement path is known. - -Recommended handling: - -- map each old path to a current path or tombstone; -- keep machine-readable state parseable; -- update references in PR-only mode. - -Related issue: - -### Runtime Code Safety - -The unwrap, expect, panic, and lock-unwrap findings are plausible source-risk -signals. Some may be test-only or invariant-protected; others need proper error -propagation. - -Recommended handling: - -- separate tests and fixtures from production paths; -- replace production panics with typed errors only where behavior is preserved; -- avoid replacing `unwrap()` with default values that could corrupt prover - state. - -Related issue: - -### FFI, Memory, And Proof Boundary - -The unsafe block, raw pointer, `mem_forget`, Zig pointer cast, and Agda -postulate findings are high-risk. They should not be auto-fixed from pattern -matching alone. - -Recommended handling: - -- route to echidnabot or proof review; -- require focused tests or proof obligations; -- use report-only unless a proven recipe exists. - -Related issue: - -## Summary By Action Class - -| Action class | Count | Notes | -| --- | ---: | --- | -| Dissolve as stale/reporting debris | 27 | Self-echo SARIF artifacts | -| Trivial/easy existing-system PR work | 79 | Workflow/Scorecard plus structural docs/state | -| Readily accommodated by extended system | 118 | AffineScript migration plus runtime code-safety with context | -| High risk, specialist review only | 22 | FFI/proof/memory boundary | -| Report-only environment topology | 3 | Needs environment self-modeling | - -## Ordering - -The safe order is: - -1. Fix the self-echo reporting path and clear stale alert debris. -2. Let relevant in-flight GitHub Actions, CodeQL, Scorecard, and Dependabot - work finish when it covers the same class. -3. Apply workflow and structural hygiene PRs. -4. Run the AffineScript migration campaign by subsystem. -5. Triage runtime code-safety paths. -6. Hold FFI/proof/memory-safety items for specialist review. - -Doing this out of order can create more work than it removes. For example, -rewriting source before clearing stale SARIF debris makes alert counts look -worse, and blind workflow timeout edits can break formal or live-prover jobs. - -## Portfolio Note - -For `Git in the Time of NeSy Agency`, this report is an example of repository -portfolio triage: the useful unit is not a raw alert, but a classified work -order with route, cost, risk, and expected class-collapse. diff --git a/docs/reports/audit/pillar-audit-2026-04-15.adoc b/docs/reports/audit/pillar-audit-2026-04-15.adoc new file mode 100644 index 00000000..f4cc856d --- /dev/null +++ b/docs/reports/audit/pillar-audit-2026-04-15.adoc @@ -0,0 +1,25 @@ +== Gemini Audit Report (M2: Pillar Repo Audits) + +Date: 2026-04-15 Repository: /var/mnt/eclipse/repos/echidna + +=== Audit Criteria + +* *Dangerous Patterns*: +** `+believe_me+`, `+assert_total+`, `+Admitted+`, `+sorry+`, +`+unsafeCoerce+`, `+Obj.magic+`: *CLEAN* in engine (grep matches in +training corpora only). +* *Standards Check*: +** `+.machine_readable/*.a2ml+`: `+CLADE.a2ml+`, `+AGENTIC.a2ml+` +(manifest) present. +** `+Justfile+`: *PRESENT*. +** `+K9.k9+` / `+coordination.k9+`: `+setup-prover-env.k9.ncl+` present +in `+.machine_readable+`. +* *CI/CD Status*: `+.github/workflows+` and `+.gitlab-ci.yml+` +*PRESENT*. +* *Documentation Parity*: Neurosymbolic theorem proving claims. +* *Template Residue*: *CLEAN*. + +=== Verdict + +* *CRG Grade*: A +* *Publishable?*: YES diff --git a/docs/reports/audit/pillar-audit-2026-04-15.md b/docs/reports/audit/pillar-audit-2026-04-15.md deleted file mode 100644 index f6eb452e..00000000 --- a/docs/reports/audit/pillar-audit-2026-04-15.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gemini Audit Report (M2: Pillar Repo Audits) -Date: 2026-04-15 -Repository: /var/mnt/eclipse/repos/echidna - -## Audit Criteria - -- **Dangerous Patterns**: - - `believe_me`, `assert_total`, `Admitted`, `sorry`, `unsafeCoerce`, `Obj.magic`: **CLEAN** in engine (grep matches in training corpora only). -- **Standards Check**: - - `.machine_readable/*.a2ml`: `CLADE.a2ml`, `AGENTIC.a2ml` (manifest) present. - - `Justfile`: **PRESENT**. - - `K9.k9` / `coordination.k9`: `setup-prover-env.k9.ncl` present in `.machine_readable`. -- **CI/CD Status**: `.github/workflows` and `.gitlab-ci.yml` **PRESENT**. -- **Documentation Parity**: Neurosymbolic theorem proving claims. -- **Template Residue**: **CLEAN**. - -## Verdict -- **CRG Grade**: A -- **Publishable?**: YES diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 00000000..37be3575 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,88 @@ +== Tech-Debt Audit — echidna — 2026-05-26 + +____ +*Superseded — kept as a dated snapshot.* The live debt register is +link:DEBT.md[`+DEBT.md+`]. This file records what an automated scan +found on 2026-05-26 and is not maintained; its findings were not +re-verified when `+DEBT.md+` was written, so treat any item here as +unconfirmed until you re-run its measurement. +____ + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 103 | Coq-Axm/Adm= 0 | Lean-srry/ax= 6 | Agda-pst= 2 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 12 +.... + +*Total markers:* 20. *Severity:* `+>020+`. + +*Marker types* (any non-zero counts above): - Coq `+Axiom+`/`+Admitted+` +— unconditional proof escapes. - Lean `+sorry+`/`+axiom+` — Lean’s +equivalent. - Agda `+postulate+` — accepted axiomatically. - Idris2 +`+believe_me+`/`+assert_total+` — runtime-safe coercion / totality +assumption. - Idris2 top-level `+partial+` — totality-check waived. - F* +`+assume val+`/`+admit_p+` — F* admit. - `+TODO PROOF+` / `+OWED:+` — +self-documented debt markers. - `+unsafePerformIO+`/`+unsafeCoerce+` — +soundness-relevant escape hatches in Haskell/Rust source. + +*Recommended next move:* triage each finding into one of: (a) discharge +by proof, (b) cover with property-tests + a documented refutation +budget, or (c) annotate as a known/necessary axiom (e.g. `+funExt+`) in +`+docs/proof-debt.md+`. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MPL-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |428 +|`+docs/+` files |75 +|`+docs/+` LoC |23198 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+OK+` +|=== + +*Recommended next move:* none for docs. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index a24a69e1..00000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,77 +0,0 @@ - - -# Tech-Debt Audit — echidna — 2026-05-26 - -> **Superseded — kept as a dated snapshot.** The live debt register is -> [`DEBT.md`](DEBT.md). This file records what an automated scan found on -> 2026-05-26 and is not maintained; its findings were not re-verified when -> `DEBT.md` was written, so treat any item here as unconfirmed until you re-run -> its measurement. - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 103 | Coq-Axm/Adm= 0 | Lean-srry/ax= 6 | Agda-pst= 2 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 12 -``` - -**Total markers:** 20. **Severity:** `>020`. - -**Marker types** (any non-zero counts above): -- Coq `Axiom`/`Admitted` — unconditional proof escapes. -- Lean `sorry`/`axiom` — Lean's equivalent. -- Agda `postulate` — accepted axiomatically. -- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -- Idris2 top-level `partial` — totality-check waived. -- F\* `assume val`/`admit_p` — F\* admit. -- `TODO PROOF` / `OWED:` — self-documented debt markers. -- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. - -**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MPL-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 428 | -| `docs/` files | 75 | -| `docs/` LoC | 23198 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `OK` | - -**Recommended next move:** none for docs. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/docs/training-runs/2026-06-02.adoc b/docs/training-runs/2026-06-02.adoc new file mode 100644 index 00000000..26cc25ea --- /dev/null +++ b/docs/training-runs/2026-06-02.adoc @@ -0,0 +1,199 @@ +== GNN training run — 2026-06-02 + +First owner-authorised GNN training run after the post-wave3 wiring PR +landed (#207, merged 2026-06-02T04:14:04Z). + +=== Provenance + +[width="100%",cols="50%,50%",options="header",] +|=== +|Field |Value +|Branch |`+gnn-training-run-2026-06-02+` (local-only, no main pollution +per Option 4) + +|Worktree +|`+/home/hyperpolymath/developer/repos/echidna-training-2026-06-02+` + +|Launcher |`+/tmp/echidna-training-launcher.sh+` + +|Log |`+/tmp/echidna-training-2026-06-02.log+` + +|Status file |`+/tmp/echidna-training-2026-06-02.status+` + +|Pre-requisite PRs merged |#198 saturation+typing, #206 wave3 closeout, +#207 GNN wiring, #210 JSON dep fix + +|Hardware |4 CPU / 5GB RAM / WSL2 with CUDA passthrough +(libcuda.so.535.309.01) + +|Julia |1.12.6 via juliaup +|=== + +=== Pipeline + +[arabic] +. *Stage 0* — `+Pkg.instantiate()+` to verify Julia env +. *Stage 1* — `+just provision-corpora+` (shallow clones of all upstream +sources to `+external_corpora/+`) +. *Stage 2* — loop over 17 saturation adapters via +`+just corpus-ingest-saturation training_data//+` +. *Stage 3* — `+just train-from-corpus lean+` +. *Stage 4* — `+just train-from-corpus coq+` +. *Stage 5* — list `+models/neural/+` artefacts + +=== Run outcomes (filled in as stages complete) + +==== Stage 0 — Julia env + +* _2026-06-02T10:46:36Z_ — `+Pkg.status()+` green; 14 direct deps + JSON +(added in #210) + +==== Stage 1 — provision-corpora + +* _2026-06-02T10:46:55Z_ — *43 upstream corpora present* (idempotent +cache hits after v2 run) +* Known per-source failures: several GitLab sources return +`+Gitlab::GitAccess::NotFoundError+`; matita returns 404 +(rocq-prover/matita repo unavailable). Non-fatal — script tolerates +per-source failures. + +==== Stage 2 — ingest 17 adapters + +* _2026-06-02T10:48:05Z_ — *4 of 17 adapters ingested*: `+agda+`, +`+coq+` confirmed; lean + idris2 expected. +* Known cause for the 13 failures: `+corpus-ingest-saturation+` recipe +(Justfile:988) only knows the 4 dependent-typed provers. The other 13 +(`+isabelle+`, `+metamath+`, `+mizar+`, `+hol_light+`, `+hol4+`, +`+dafny+`, `+why3+`, `+fstar+`, `+acl2_books+`, `+tptp+`, `+smtlib+`, +`+proofnet+`, `+minif2f+`) need per-adapter ingest scripts written. +Sketch §7 promised 17; reality is 4. Tracked as roadmap follow-up. + +==== Stage 3 — train-from-corpus lean + +* _2026-06-02T10:48:06Z → 13:11:14Z_ (~2hr 23min wall-clock) +* 16 epochs, early stopping triggered +* Loss trajectory from log: +** train_loss: 1.76 → 1.04 (epoch 5) → 0.85 (epoch 15) +** val_loss: 1.62 → 1.34 (epoch 5) → 1.33 (epoch 16, plateau) +* Checkpoints saved at epochs 5, 10, 15 +(`+models/neural/checkpoint_epoch_{5,10,15}/+`) +* `+best_model/+` saved at 11:55 (lean-side best) +* Per-epoch MRR not recorded for lean run (training_metrics.csv was +overwritten by coq) + +==== Stage 4 — train-from-corpus coq + +* _2026-06-02T13:11:14Z → 13:45:39Z_ (~34min wall-clock) +* 17 epochs, early stopping triggered +* Real per-epoch metrics from `+models/neural/training_metrics.csv+`: + +[cols=",,,,,",options="header",] +|=== +|Epoch |train_loss |val_loss |MRR |recall@10 |precision@10 +|1 |1.887 |1.610 |0.794 |0.821 |0.177 +|5 |1.118 |1.100 |0.862 |0.833 |0.185 +|9 |*0.969* |1.007 |*0.923* |0.859 |0.192 +|12 |0.861 |*0.983* |0.785 |0.808 |0.177 +|17 |0.876 |1.146 |0.862 |0.827 |0.185 +|=== + +* *Best MRR: 0.92 @ epoch 9* (val_loss 1.01) +* *Best val_loss: 0.98 @ epoch 12* (MRR 0.79) +* `+final_model/+` saved at 14:11 +* `+gnn_ranker/+` (production-deployable) at 14:45 + +==== Stage 5 — artefacts + +`+models/neural/+` contents (952MB total): + +[cols=",,",options="header",] +|=== +|Artefact |Created |model.bson size +|`+best_model/+` |11:55 (lean) |~155MB +|`+checkpoint_epoch_5/+` |12:23 |155MB +|`+checkpoint_epoch_10/+` |12:38 |155MB +|`+checkpoint_epoch_15/+` |14:09 |155MB +|`+final_model/+` |14:11 (coq) |~155MB +|*`+gnn_ranker/+`* |14:45 |*162MB* ← production-deployable +|`+training_metrics.csv+` |14:45 |3.3KB +|=== + +=== Outcomes summary + +* *Models produced*: ✅ 6 model directories + 1 metrics CSV (952MB +total) +* *Best MRR*: 0.92 (epoch 9, coq) — solidly above the cosine baseline of +0.66 the eval script’s MRR gate requires +* *Best val_loss*: 0.98 (epoch 12, coq) +* *Comparable to wave3 baseline*: pending — wave3’s first GNN run hasn’t +landed yet; this run’s artefacts are on dedicated branch +`+gnn-training-run-2026-06-02+` (no main pollution) +* *Production ranker*: `+gnn_ranker/model.bson+` (162MB) — picked up by +`+src/rust/gnn/client.rs::cosine_fallback+` once placed in the canonical +`+models/neural/+` location + +=== Known issues discovered this run + +[arabic] +. *JSON dep mismatch* — fixed via #210. `+corpus_loader.jl+` uses +`+JSON.parse+` but `+Project.toml+` had only `+JSON3+`. +. *`+CUDA.version()+` MethodError* — fixed via #211. CUDA.jl 5.x removed +the method; replaced with `+runtime_version()+` / `+driver_version()+` +defensively wrapped. +. *`+corpus-ingest-saturation+` 4-vs-17 gap* — Stage 2 ingested 4/17 +adapters (agda/coq/lean/idris2). 13 missing adapters have Rust extractor +modules at `+src/rust/corpus/.rs+` but were not wired into the CLI +dispatcher at `+src/rust/main.rs:1177+`. Dispatcher fix prepared on +branch `+feat/corpus-dispatcher-all-17-adapters+` but blocked by an +SPDX-FileCopyrightText pre-commit hook on `+main.rs+` (Owner = "`ECHIDNA +Project Team`" instead of canonical "`Jonathan D.A. Jewell +j.d.a.jewell@open.ac.uk`"). Owner-action: manually fix the Owner header +to unblock. +. *`+BSON not defined in Main+` LoadError* at final-save path — +non-fatal: checkpoint scaffold saved 155MB `+model.bson+` per checkpoint +regardless. Final-save call needs a `+using BSON+` somewhere in the +JSONL-fallback training path (separate from the checkpoint-save path +which already had `+using BSON+`). +. *`+training_data//+` was empty when launcher ran ingest* — +the launcher pointed at fresh-created empty dirs instead of +`+external_corpora//+`. The pipeline still produced real +training because train.jl has a JSONL-fallback path that found the +pre-existing `+training_data/proof_states_UNIFIED.jsonl+` + +`+premises_*.jsonl+` from wave3 work. Real Corpus JSON adapter input was +bypassed entirely. +. *`+per-epoch metrics overwrite+`* — lean run’s training_metrics.csv +was overwritten by coq run. Per-prover output dirs needed. + +=== Follow-up tickets / PRs + +* *echidna dispatcher fix* — branch +`+feat/corpus-dispatcher-all-17-adapters+` ready to PR once Owner header +unblocked. +* *BSON `+using+` fix* — small one-line fix at the failing final-save +path. +* *Launcher path correction* — per-adapter upstream-source mapping (agda +← agda-stdlib/agda-unimath/agda-cubical; coq ← mathcomp + coq-contribs; +lean ← mathlib4; idris2 ← idris2). +* *Per-prover metrics dirs* — separate `+training_metrics_lean.csv+` / +`+training_metrics_coq.csv+` to avoid overwrite. +* Compare `+models/neural/+` outputs vs wave3 baseline once wave3’s +first GNN run lands. + +=== Re-running + +Owner-side re-run (after dispatcher fix lands): + +[source,bash] +---- +just provision-corpora # idempotent; ~18s if cached +just extract-corpora # SEPARATE call — not a positional arg +for adapter in agda coq lean idris2; do + just corpus-ingest-saturation "$adapter" "external_corpora//" +done +just train-from-corpus lean +just train-from-corpus coq +---- + +Note `+extract-corpora+` is a separate recipe call — not a positional +arg to `+provision-corpora+` (that was the early-run mistake; cost 1 +launcher iteration). diff --git a/docs/training-runs/2026-06-02.md b/docs/training-runs/2026-06-02.md deleted file mode 100644 index a14aabf5..00000000 --- a/docs/training-runs/2026-06-02.md +++ /dev/null @@ -1,131 +0,0 @@ - - -# GNN training run — 2026-06-02 - -First owner-authorised GNN training run after the post-wave3 wiring -PR landed (#207, merged 2026-06-02T04:14:04Z). - -## Provenance - -| Field | Value | -|---|---| -| Branch | `gnn-training-run-2026-06-02` (local-only, no main pollution per Option 4) | -| Worktree | `/home/hyperpolymath/developer/repos/echidna-training-2026-06-02` | -| Launcher | `/tmp/echidna-training-launcher.sh` | -| Log | `/tmp/echidna-training-2026-06-02.log` | -| Status file | `/tmp/echidna-training-2026-06-02.status` | -| Pre-requisite PRs merged | #198 saturation+typing, #206 wave3 closeout, #207 GNN wiring, #210 JSON dep fix | -| Hardware | 4 CPU / 5GB RAM / WSL2 with CUDA passthrough (libcuda.so.535.309.01) | -| Julia | 1.12.6 via juliaup | - -## Pipeline - -1. **Stage 0** — `Pkg.instantiate()` to verify Julia env -2. **Stage 1** — `just provision-corpora` (shallow clones of all upstream sources to `external_corpora/`) -3. **Stage 2** — loop over 17 saturation adapters via `just corpus-ingest-saturation training_data//` -4. **Stage 3** — `just train-from-corpus lean` -5. **Stage 4** — `just train-from-corpus coq` -6. **Stage 5** — list `models/neural/` artefacts - -## Run outcomes (filled in as stages complete) - -### Stage 0 — Julia env - -- _2026-06-02T10:46:36Z_ — `Pkg.status()` green; 14 direct deps + JSON (added in #210) - -### Stage 1 — provision-corpora - -- _2026-06-02T10:46:55Z_ — **43 upstream corpora present** (idempotent cache hits after v2 run) -- Known per-source failures: several GitLab sources return `Gitlab::GitAccess::NotFoundError`; matita returns 404 (rocq-prover/matita repo unavailable). Non-fatal — script tolerates per-source failures. - -### Stage 2 — ingest 17 adapters - -- _2026-06-02T10:48:05Z_ — **4 of 17 adapters ingested**: `agda`, `coq` confirmed; lean + idris2 expected. -- Known cause for the 13 failures: `corpus-ingest-saturation` recipe (Justfile:988) only knows the 4 dependent-typed provers. The other 13 (`isabelle`, `metamath`, `mizar`, `hol_light`, `hol4`, `dafny`, `why3`, `fstar`, `acl2_books`, `tptp`, `smtlib`, `proofnet`, `minif2f`) need per-adapter ingest scripts written. Sketch §7 promised 17; reality is 4. Tracked as roadmap follow-up. - -### Stage 3 — train-from-corpus lean - -- _2026-06-02T10:48:06Z → 13:11:14Z_ (~2hr 23min wall-clock) -- 16 epochs, early stopping triggered -- Loss trajectory from log: - - train_loss: 1.76 → 1.04 (epoch 5) → 0.85 (epoch 15) - - val_loss: 1.62 → 1.34 (epoch 5) → 1.33 (epoch 16, plateau) -- Checkpoints saved at epochs 5, 10, 15 (`models/neural/checkpoint_epoch_{5,10,15}/`) -- `best_model/` saved at 11:55 (lean-side best) -- Per-epoch MRR not recorded for lean run (training_metrics.csv was overwritten by coq) - -### Stage 4 — train-from-corpus coq - -- _2026-06-02T13:11:14Z → 13:45:39Z_ (~34min wall-clock) -- 17 epochs, early stopping triggered -- Real per-epoch metrics from `models/neural/training_metrics.csv`: - -| Epoch | train_loss | val_loss | MRR | recall@10 | precision@10 | -|---|---|---|---|---|---| -| 1 | 1.887 | 1.610 | 0.794 | 0.821 | 0.177 | -| 5 | 1.118 | 1.100 | 0.862 | 0.833 | 0.185 | -| 9 | **0.969** | 1.007 | **0.923** | 0.859 | 0.192 | -| 12 | 0.861 | **0.983** | 0.785 | 0.808 | 0.177 | -| 17 | 0.876 | 1.146 | 0.862 | 0.827 | 0.185 | - -- **Best MRR: 0.92 @ epoch 9** (val_loss 1.01) -- **Best val_loss: 0.98 @ epoch 12** (MRR 0.79) -- `final_model/` saved at 14:11 -- `gnn_ranker/` (production-deployable) at 14:45 - -### Stage 5 — artefacts - -`models/neural/` contents (952MB total): - -| Artefact | Created | model.bson size | -|---|---|---| -| `best_model/` | 11:55 (lean) | ~155MB | -| `checkpoint_epoch_5/` | 12:23 | 155MB | -| `checkpoint_epoch_10/` | 12:38 | 155MB | -| `checkpoint_epoch_15/` | 14:09 | 155MB | -| `final_model/` | 14:11 (coq) | ~155MB | -| **`gnn_ranker/`** | 14:45 | **162MB** ← production-deployable | -| `training_metrics.csv` | 14:45 | 3.3KB | - -## Outcomes summary - -- **Models produced**: ✅ 6 model directories + 1 metrics CSV (952MB total) -- **Best MRR**: 0.92 (epoch 9, coq) — solidly above the cosine baseline of 0.66 the eval script's MRR gate requires -- **Best val_loss**: 0.98 (epoch 12, coq) -- **Comparable to wave3 baseline**: pending — wave3's first GNN run hasn't landed yet; this run's artefacts are on dedicated branch `gnn-training-run-2026-06-02` (no main pollution) -- **Production ranker**: `gnn_ranker/model.bson` (162MB) — picked up by `src/rust/gnn/client.rs::cosine_fallback` once placed in the canonical `models/neural/` location - -## Known issues discovered this run - -1. **JSON dep mismatch** — fixed via #210. `corpus_loader.jl` uses `JSON.parse` but `Project.toml` had only `JSON3`. -2. **`CUDA.version()` MethodError** — fixed via #211. CUDA.jl 5.x removed the method; replaced with `runtime_version()` / `driver_version()` defensively wrapped. -3. **`corpus-ingest-saturation` 4-vs-17 gap** — Stage 2 ingested 4/17 adapters (agda/coq/lean/idris2). 13 missing adapters have Rust extractor modules at `src/rust/corpus/.rs` but were not wired into the CLI dispatcher at `src/rust/main.rs:1177`. Dispatcher fix prepared on branch `feat/corpus-dispatcher-all-17-adapters` but blocked by an SPDX-FileCopyrightText pre-commit hook on `main.rs` (Owner = "ECHIDNA Project Team" instead of canonical "Jonathan D.A. Jewell "). Owner-action: manually fix the Owner header to unblock. -4. **`BSON not defined in Main` LoadError** at final-save path — non-fatal: checkpoint scaffold saved 155MB `model.bson` per checkpoint regardless. Final-save call needs a `using BSON` somewhere in the JSONL-fallback training path (separate from the checkpoint-save path which already had `using BSON`). -5. **`training_data//` was empty when launcher ran ingest** — the launcher pointed at fresh-created empty dirs instead of `external_corpora//`. The pipeline still produced real training because train.jl has a JSONL-fallback path that found the pre-existing `training_data/proof_states_UNIFIED.jsonl` + `premises_*.jsonl` from wave3 work. Real Corpus JSON adapter input was bypassed entirely. -6. **`per-epoch metrics overwrite`** — lean run's training_metrics.csv was overwritten by coq run. Per-prover output dirs needed. - -## Follow-up tickets / PRs - -- **echidna dispatcher fix** — branch `feat/corpus-dispatcher-all-17-adapters` ready to PR once Owner header unblocked. -- **BSON `using` fix** — small one-line fix at the failing final-save path. -- **Launcher path correction** — per-adapter upstream-source mapping (agda ← agda-stdlib/agda-unimath/agda-cubical; coq ← mathcomp + coq-contribs; lean ← mathlib4; idris2 ← idris2). -- **Per-prover metrics dirs** — separate `training_metrics_lean.csv` / `training_metrics_coq.csv` to avoid overwrite. -- Compare `models/neural/` outputs vs wave3 baseline once wave3's first GNN run lands. - -## Re-running - -Owner-side re-run (after dispatcher fix lands): -```bash -just provision-corpora # idempotent; ~18s if cached -just extract-corpora # SEPARATE call — not a positional arg -for adapter in agda coq lean idris2; do - just corpus-ingest-saturation "$adapter" "external_corpora//" -done -just train-from-corpus lean -just train-from-corpus coq -``` - -Note `extract-corpora` is a separate recipe call — not a positional arg to `provision-corpora` (that was the early-run mistake; cost 1 launcher iteration). diff --git a/echidna-playground/CODE_OF_CONDUCT.adoc b/echidna-playground/CODE_OF_CONDUCT.adoc new file mode 100644 index 00000000..edd02154 --- /dev/null +++ b/echidna-playground/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Echidna a harassment-free experience for everyone, regardless of age, +body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/echidna/discussions[Discussion] (for +general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/echidna-playground/CODE_OF_CONDUCT.md b/echidna-playground/CODE_OF_CONDUCT.md deleted file mode 100644 index dabf87d1..00000000 --- a/echidna-playground/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Echidna a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/echidna/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/echidna-playground/SECURITY.adoc b/echidna-playground/SECURITY.adoc new file mode 100644 index 00000000..d1b2069f --- /dev/null +++ b/echidna-playground/SECURITY.adoc @@ -0,0 +1,434 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/template-repo/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: GitHub Issues (Non-Sensitive) + +For non-sensitive security concerns that don’t require confidential +disclosure, you may open a regular GitHub issue with the `+security+` +label. + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/template-repo+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/template-repo/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using template-repo, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://github.com/hyperpolymath/template-repo/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/template-repo/security/advisories/new[Report +via GitHub] + +|*General questions* +|https://github.com/hyperpolymath/template-repo/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep template-repo and its users safe._ 🛡️ + +''''' + +Last updated: 2025 · Policy version: 1.0.0 diff --git a/echidna-playground/SECURITY.md b/echidna-playground/SECURITY.md deleted file mode 100644 index 860dbb94..00000000 --- a/echidna-playground/SECURITY.md +++ /dev/null @@ -1,370 +0,0 @@ -# Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/template-repo/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: GitHub Issues (Non-Sensitive) - -For non-sensitive security concerns that don't require confidential disclosure, you may open a regular GitHub issue with the `security` label. - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/template-repo`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/template-repo/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using template-repo, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Security Advisories](https://github.com/hyperpolymath/template-repo/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/template-repo/security/advisories/new) | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/template-repo/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep template-repo and its users safe.* 🛡️ - ---- - -Last updated: 2025 · Policy version: 1.0.0 diff --git a/echidna-playground/melange-example/README.adoc b/echidna-playground/melange-example/README.adoc new file mode 100644 index 00000000..6942c24e --- /dev/null +++ b/echidna-playground/melange-example/README.adoc @@ -0,0 +1,29 @@ +== Melange Route + +This shows how to use Melange (AffineScript → OCaml → JS or native). + +=== Setup + +[source,bash] +---- +# Install opam (OCaml package manager) +opam init +opam switch create . 5.1.0 + +# Install Melange +opam install melange dune + +# Build +dune build +---- + +=== Key Difference from AffineScript + +* *AffineScript*: npm-based, JS output only +* *Melange*: opam-based, can also compile to native + +=== Native Binary Option + +Change dune file to use `+(executable ...)+` instead of +`+(melange.emit ...)+` to get a standalone binary that generates HTML +without any runtime. diff --git a/echidna-playground/melange-example/README.md b/echidna-playground/melange-example/README.md deleted file mode 100644 index 52d539d7..00000000 --- a/echidna-playground/melange-example/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# Melange Route - -This shows how to use Melange (AffineScript → OCaml → JS or native). - -## Setup - -```bash -# Install opam (OCaml package manager) -opam init -opam switch create . 5.1.0 - -# Install Melange -opam install melange dune - -# Build -dune build -``` - -## Key Difference from AffineScript - -- **AffineScript**: npm-based, JS output only -- **Melange**: opam-based, can also compile to native - -## Native Binary Option - -Change dune file to use `(executable ...)` instead of `(melange.emit ...)` -to get a standalone binary that generates HTML without any runtime. diff --git a/examples/README.adoc b/examples/README.adoc new file mode 100644 index 00000000..af3168d4 --- /dev/null +++ b/examples/README.adoc @@ -0,0 +1,82 @@ +== ECHIDNA Example Proofs + +This directory contains example proofs demonstrating ECHIDNA’s +capabilities across all 12 supported provers. + +=== Quick Try + +==== Coq Example (simple_proof.v) + +[source,bash] +---- +# Start ECHIDNA +./start.sh + +# In the UI: +# 1. Select "Coq" prover +# 2. Load examples/simple_proof.v +# 3. Use tactic suggester to get AI recommendations +---- + +==== Via API + +[source,bash] +---- +# Verify the proof via API +curl -X POST http://127.0.0.1:8081/api/verify \ + -H "Content-Type: application/json" \ + -d @- << JSON +{ + "prover": "Coq", + "content": "$(cat simple_proof.v)" +} +JSON +---- + +=== Available Examples + +[cols=",,",options="header",] +|=== +|File |Prover |Description +|`+simple_proof.v+` |Coq |Basic arithmetic proofs +|`+(more coming)+` |Various |Additional examples +|=== + +=== Learning Path + +[arabic] +. *Start Simple*: Try `+simple_proof.v+` to understand basic workflow +. *Explore Tactics*: Use the AI suggester to discover new tactics +. *Filter by Aspect*: Try different aspect tags to see specialized +suggestions +. *Visualize*: Watch the proof tree grow as you build your proof +. *Compare Provers*: Try the same theorem in different provers + +=== Tips + +* Use aspect tags to filter suggestions: +** `+algebraic+` - For algebraic properties +** `+geometric+` - For geometric reasoning +** `+logical+` - For logical inferences +** `+inductive+` - For induction-based proofs +** `+deductive+` - For direct reasoning +** `+automated+` - For automatic tactics +* Check confidence scores - higher confidence (>0.8) suggestions are +more likely to succeed +* Explore the proof tree to understand proof structure + +=== Adding Your Own Examples + +To add new examples: + +[arabic] +. Create a file with appropriate extension (`+.v+`, `+.lean+`, `+.thy+`, +etc.) +. Add SPDX header for licensing +. Include comments explaining the proof +. Test it works with ECHIDNA +. Submit a PR! + +''''' + +*Happy Proving! 🦔* diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 88973e85..00000000 --- a/examples/README.md +++ /dev/null @@ -1,74 +0,0 @@ -# ECHIDNA Example Proofs - -This directory contains example proofs demonstrating ECHIDNA's capabilities across all 12 supported provers. - -## Quick Try - -### Coq Example (simple_proof.v) - -```bash -# Start ECHIDNA -./start.sh - -# In the UI: -# 1. Select "Coq" prover -# 2. Load examples/simple_proof.v -# 3. Use tactic suggester to get AI recommendations -``` - -### Via API - -```bash -# Verify the proof via API -curl -X POST http://127.0.0.1:8081/api/verify \ - -H "Content-Type: application/json" \ - -d @- << JSON -{ - "prover": "Coq", - "content": "$(cat simple_proof.v)" -} -JSON -``` - -## Available Examples - -| File | Prover | Description | -|------|--------|-------------| -| `simple_proof.v` | Coq | Basic arithmetic proofs | -| `(more coming)` | Various | Additional examples | - -## Learning Path - -1. **Start Simple**: Try `simple_proof.v` to understand basic workflow -2. **Explore Tactics**: Use the AI suggester to discover new tactics -3. **Filter by Aspect**: Try different aspect tags to see specialized suggestions -4. **Visualize**: Watch the proof tree grow as you build your proof -5. **Compare Provers**: Try the same theorem in different provers - -## Tips - -- Use aspect tags to filter suggestions: - - `algebraic` - For algebraic properties - - `geometric` - For geometric reasoning - - `logical` - For logical inferences - - `inductive` - For induction-based proofs - - `deductive` - For direct reasoning - - `automated` - For automatic tactics - -- Check confidence scores - higher confidence (>0.8) suggestions are more likely to succeed - -- Explore the proof tree to understand proof structure - -## Adding Your Own Examples - -To add new examples: - -1. Create a file with appropriate extension (`.v`, `.lean`, `.thy`, etc.) -2. Add SPDX header for licensing -3. Include comments explaining the proof -4. Test it works with ECHIDNA -5. Submit a PR! - ---- - -**Happy Proving! 🦔** diff --git a/hooks/README.adoc b/hooks/README.adoc new file mode 100644 index 00000000..e92d2099 --- /dev/null +++ b/hooks/README.adoc @@ -0,0 +1,27 @@ +== Git hooks + +Governance hooks for ECHIDNA — the RSR `+hooks/+` requirement +(pre-commit enforcement). Each wraps the same `+just+` gate CI runs, so +commits and pushes fail fast on the same checks. + +[width="100%",cols="30%,30%,40%",options="header",] +|=== +|Hook |Runs |Covers +|`+pre-commit+` |`+just pre-commit+` |fmt-check + lint (REUSE/SPDX + +rustfmt + clippy) + test + +|`+pre-push+` |`+just validate-rsr+` |RSR compliance gate (RSR-H12) +|=== + +=== Enable + +Hooks are opt-in. Point git at this directory once per clone: + +[source,bash] +---- +git config core.hooksPath hooks +---- + +Disable with `+git config --unset core.hooksPath+`. Each hook no-ops +with a warning if `+just+` is not on PATH, so a missing toolchain never +hard-blocks a commit. diff --git a/hooks/README.md b/hooks/README.md deleted file mode 100644 index 46069db5..00000000 --- a/hooks/README.md +++ /dev/null @@ -1,24 +0,0 @@ - - -# Git hooks - -Governance hooks for ECHIDNA — the RSR `hooks/` requirement (pre-commit -enforcement). Each wraps the same `just` gate CI runs, so commits and pushes -fail fast on the same checks. - -| Hook | Runs | Covers | -|------|------|--------| -| `pre-commit` | `just pre-commit` | fmt-check + lint (REUSE/SPDX + rustfmt + clippy) + test | -| `pre-push` | `just validate-rsr` | RSR compliance gate (RSR-H12) | - -## Enable - -Hooks are opt-in. Point git at this directory once per clone: - -```bash -git config core.hooksPath hooks -``` - -Disable with `git config --unset core.hooksPath`. Each hook no-ops with a -warning if `just` is not on PATH, so a missing toolchain never hard-blocks a -commit. diff --git a/metrics/README.adoc b/metrics/README.adoc new file mode 100644 index 00000000..db4309cf --- /dev/null +++ b/metrics/README.adoc @@ -0,0 +1,50 @@ +== ECHIDNA metrics suite + +Measures the cross-prover corpus along eight axes that together bound +the vocabulary horizon and triangulation capacity. Every metric writes +its result to VeriSimDB via `+POST /api/v1/metrics+`; the local JSONL +file is a cache, not the source of truth. + +=== Axes + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Module |Metric |Target +|`+triangulation_rate.jl+` |% of theorems proved in ≥3 provers |≥ 15 % + +|`+alignment_rate.jl+` |RDF-triples linking named theorems across +provers |≥ 30 % + +|`+oov_rate.jl+` |tokens in corpus not in CANON |≤ 3 % + +|`+heaps_beta.jl+` |β from V ≈ k · N^β |0.55 – 0.70 + +|`+tactic_cluster_purity.jl+` |per-prover n-gram distinctiveness |≥ 0.65 + +|`+msc_taxonomy_coverage.jl+` |MSC categories with ≥ 10 proofs |≥ 40 % + +|`+prover_floor.jl+` |proofs in least-represented prover |≥ 5 000 + +|`+zipf_s.jl+` |Zipf slope on theorem-name frequencies |0.9 – 1.1 +|=== + +=== Running + +[source,bash] +---- +julia --project=src/julia metrics/run_all.jl +---- + +Environment: `+VERISIM_URL+` (default `+http://localhost:8080+`), +`+METRIC_RUN_ID+` (default `+metrics-+`). + +=== Design + +* Single loader in `+corpus_loader.jl+` — reads all +`+proof_states_*.jsonl+` once per run and hands per-prover slices to +each metric. +* Sink in `+verisim_sink.jl+` POSTs metric rows to VeriSimDB. If the API +is unreachable, the row still lands in +`+training_data/metrics_.jsonl+` so no measurement is lost. +* Targets in the table above come from +`+Desktop/ECHIDNA-VERISIM-STRATEGY-2026-04-17.md+`. diff --git a/metrics/README.md b/metrics/README.md deleted file mode 100644 index cbcccdb1..00000000 --- a/metrics/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# ECHIDNA metrics suite - - - -Measures the cross-prover corpus along eight axes that together bound -the vocabulary horizon and triangulation capacity. Every metric -writes its result to VeriSimDB via `POST /api/v1/metrics`; the local -JSONL file is a cache, not the source of truth. - -## Axes - -| Module | Metric | Target | -|---|---|---| -| `triangulation_rate.jl` | % of theorems proved in ≥3 provers | ≥ 15 % | -| `alignment_rate.jl` | RDF-triples linking named theorems across provers | ≥ 30 % | -| `oov_rate.jl` | tokens in corpus not in CANON | ≤ 3 % | -| `heaps_beta.jl` | β from V ≈ k · N^β | 0.55 – 0.70 | -| `tactic_cluster_purity.jl` | per-prover n-gram distinctiveness | ≥ 0.65 | -| `msc_taxonomy_coverage.jl` | MSC categories with ≥ 10 proofs | ≥ 40 % | -| `prover_floor.jl` | proofs in least-represented prover | ≥ 5 000 | -| `zipf_s.jl` | Zipf slope on theorem-name frequencies | 0.9 – 1.1 | - -## Running - -```bash -julia --project=src/julia metrics/run_all.jl -``` - -Environment: `VERISIM_URL` (default `http://localhost:8080`), -`METRIC_RUN_ID` (default `metrics-`). - -## Design - -- Single loader in `corpus_loader.jl` — reads all `proof_states_*.jsonl` - once per run and hands per-prover slices to each metric. -- Sink in `verisim_sink.jl` POSTs metric rows to VeriSimDB. If the API - is unreachable, the row still lands in - `training_data/metrics_.jsonl` so no measurement is lost. -- Targets in the table above come from - `Desktop/ECHIDNA-VERISIM-STRATEGY-2026-04-17.md`. diff --git a/proofs/acl2/README.adoc b/proofs/acl2/README.adoc new file mode 100644 index 00000000..2f2e208f --- /dev/null +++ b/proofs/acl2/README.adoc @@ -0,0 +1,129 @@ +== ACL2 Example Proofs for ECHIDNA + +This directory contains example ACL2 proofs demonstrating the ECHIDNA +ACL2 backend capabilities. + +=== Files + +==== 1. `+associativity.lisp+` + +Demonstrates associativity of a custom addition function with induction +hints. + +*Key Concepts:* - Recursive function definition with `+defun+` - +Induction hints (`+:hints (("Goal" :induct ...))+`) - Natural number +reasoning with `+natp+` + +==== 2. `+list_append.lisp+` + +Properties of list append operation. + +*Theorems Proved:* - `+append-nil+`: Appending nil is identity - +`+append-associative+`: Append is associative - `+length-append+`: +Length distributes over append + +*Key Concepts:* - List recursion with `+endp+`, `+car+`, `+cdr+` - +Multiple related theorems - Structural induction + +==== 3. `+factorial.lisp+` + +Factorial function with guards and tail-recursive variant. + +*Theorems Proved:* - `+fact-positive+`: Factorial is always positive - +`+fact-tail-correct+`: Tail-recursive version equivalence + +*Key Concepts:* - Guard verification with `+declare xargs :guard+` - +Type prescription rules (`+:rule-classes :type-prescription+`) - +Accumulator-based tail recursion + +==== 4. `+binary_trees.lisp+` + +Binary tree operations and properties. + +*Theorems Proved:* - `+mirror-involutive+`: Mirror is its own inverse - +`+mirror-preserves-size+`: Mirror preserves tree size + +*Key Concepts:* - Data structure predicates (`+tree-p+`) - Structural +recursion on trees - Property preservation proofs + +==== 5. `+sorting.lisp+` + +Insertion sort correctness. + +*Theorems Proved:* - `+insert-ordered+`: Insert maintains sortedness - +`+insertion-sort-ordered+`: Insertion sort produces sorted output - +`+member-insert+`: Insert preserves membership + +*Key Concepts:* - Algorithm verification - Conditional logic with +`+cond+` - Property-based specification (`+ordered+`) - Using previous +lemmas in proofs (`+:use+` hint) + +=== Running These Proofs + +==== With ACL2 Installed + +[source,bash] +---- +# Interactive mode +acl2 +ACL2 !> (ld "associativity.lisp") + +# Batch mode +acl2 < associativity.lisp +---- + +==== With ECHIDNA + +[source,bash] +---- +# Parse and verify +echidna verify --prover acl2 associativity.lisp + +# Interactive proof exploration +echidna repl --prover acl2 +---- + +=== ACL2 Syntax Cheat Sheet + +==== Function Definition + +[source,lisp] +---- +(defun name (params) + (if condition + then-branch + else-branch)) +---- + +==== Theorem Statement + +[source,lisp] +---- +(defthm theorem-name + (implies hypothesis + conclusion) + :hints (("Goal" :induct (function-name args)))) +---- + +==== Common Hints + +* `+:induct (f x)+` - Induction on function application +* `+:use lemma-name+` - Use previously proved lemma +* `+:expand (f x)+` - Expand function definition +* `+:in-theory (enable ...)+` - Enable specific rules +* `+:do-not-induct t+` - Disable automatic induction + +==== Type Predicates + +* `+natp+` - Natural number (≥ 0) +* `+posp+` - Positive integer (> 0) +* `+integerp+` - Integer +* `+rationalp+` - Rational number +* `+true-listp+` - Proper list + +=== Resources + +* http://www.cs.utexas.edu/users/moore/acl2/[ACL2 Documentation] +* http://www.cs.utexas.edu/users/moore/acl2/tutorial.html[ACL2 Tutorial] +* http://www.cs.utexas.edu/users/moore/acl2/current/manual/index.html?topic=ACL2____HINTS[Proof +Hints Guide] diff --git a/proofs/acl2/README.md b/proofs/acl2/README.md deleted file mode 100644 index ace4c7d7..00000000 --- a/proofs/acl2/README.md +++ /dev/null @@ -1,125 +0,0 @@ -# ACL2 Example Proofs for ECHIDNA - -This directory contains example ACL2 proofs demonstrating the ECHIDNA ACL2 backend capabilities. - -## Files - -### 1. `associativity.lisp` -Demonstrates associativity of a custom addition function with induction hints. - -**Key Concepts:** -- Recursive function definition with `defun` -- Induction hints (`:hints (("Goal" :induct ...))`) -- Natural number reasoning with `natp` - -### 2. `list_append.lisp` -Properties of list append operation. - -**Theorems Proved:** -- `append-nil`: Appending nil is identity -- `append-associative`: Append is associative -- `length-append`: Length distributes over append - -**Key Concepts:** -- List recursion with `endp`, `car`, `cdr` -- Multiple related theorems -- Structural induction - -### 3. `factorial.lisp` -Factorial function with guards and tail-recursive variant. - -**Theorems Proved:** -- `fact-positive`: Factorial is always positive -- `fact-tail-correct`: Tail-recursive version equivalence - -**Key Concepts:** -- Guard verification with `declare xargs :guard` -- Type prescription rules (`:rule-classes :type-prescription`) -- Accumulator-based tail recursion - -### 4. `binary_trees.lisp` -Binary tree operations and properties. - -**Theorems Proved:** -- `mirror-involutive`: Mirror is its own inverse -- `mirror-preserves-size`: Mirror preserves tree size - -**Key Concepts:** -- Data structure predicates (`tree-p`) -- Structural recursion on trees -- Property preservation proofs - -### 5. `sorting.lisp` -Insertion sort correctness. - -**Theorems Proved:** -- `insert-ordered`: Insert maintains sortedness -- `insertion-sort-ordered`: Insertion sort produces sorted output -- `member-insert`: Insert preserves membership - -**Key Concepts:** -- Algorithm verification -- Conditional logic with `cond` -- Property-based specification (`ordered`) -- Using previous lemmas in proofs (`:use` hint) - -## Running These Proofs - -### With ACL2 Installed - -```bash -# Interactive mode -acl2 -ACL2 !> (ld "associativity.lisp") - -# Batch mode -acl2 < associativity.lisp -``` - -### With ECHIDNA - -```bash -# Parse and verify -echidna verify --prover acl2 associativity.lisp - -# Interactive proof exploration -echidna repl --prover acl2 -``` - -## ACL2 Syntax Cheat Sheet - -### Function Definition -```lisp -(defun name (params) - (if condition - then-branch - else-branch)) -``` - -### Theorem Statement -```lisp -(defthm theorem-name - (implies hypothesis - conclusion) - :hints (("Goal" :induct (function-name args)))) -``` - -### Common Hints -- `:induct (f x)` - Induction on function application -- `:use lemma-name` - Use previously proved lemma -- `:expand (f x)` - Expand function definition -- `:in-theory (enable ...)` - Enable specific rules -- `:do-not-induct t` - Disable automatic induction - -### Type Predicates -- `natp` - Natural number (≥ 0) -- `posp` - Positive integer (> 0) -- `integerp` - Integer -- `rationalp` - Rational number -- `true-listp` - Proper list - -## Resources - -- [ACL2 Documentation](http://www.cs.utexas.edu/users/moore/acl2/) -- [ACL2 Tutorial](http://www.cs.utexas.edu/users/moore/acl2/tutorial.html) -- [Proof Hints Guide](http://www.cs.utexas.edu/users/moore/acl2/current/manual/index.html?topic=ACL2____HINTS) diff --git a/proofs/hol4/README.adoc b/proofs/hol4/README.adoc new file mode 100644 index 00000000..d2cc7e6e --- /dev/null +++ b/proofs/hol4/README.adoc @@ -0,0 +1,220 @@ +== HOL4 Example Proofs for ECHIDNA + +This directory contains example HOL4 theories demonstrating the ECHIDNA +HOL4 backend capabilities. + +=== Files + +==== 1. `+list_append.sml+` + +List append properties with reverse. + +*Theorems Proved:* - `+LENGTH_APPEND_THM+`: Length distributes over +append - `+APPEND_ASSOC_THM+`: Append is associative - +`+APPEND_NIL_RIGHT+`: Nil is right identity - `+REVERSE_APPEND+`: +Reverse distributes over append - `+REVERSE_REVERSE+`: Reverse is +involutive + +*Key Concepts:* - List induction (`+Induct+`) - Simplification +(`+rw[]+`) - Automated reasoning (`+metis_tac+`) - Definition/Theorem +forms + +==== 2. `+arithmetic.sml+` + +Factorial, exponentiation, and sum formulas. + +*Theorems Proved:* - `+FACT_POSITIVE+`: Factorial is always positive - +`+FACT_MONO+`: Factorial is monotonic - `+EXP_ADD+`: Exponent addition +law - `+EXP_MULT+`: Exponent multiplication law - `+SUM_TO_FORMULA+`: +Sum of first n naturals + +*Key Concepts:* - Recursive definitions - Decision procedures +(`+DECIDE_TAC+`) - Arithmetic reasoning - Induction over naturals + +==== 3. `+binary_tree.sml+` + +Binary tree operations and properties. + +*Theorems Proved:* - `+MIRROR_MIRROR+`: Mirror is involutive - +`+MIRROR_SIZE+`: Mirror preserves size - `+MIRROR_HEIGHT+`: Mirror +preserves height - `+SIZE_INORDER+`: Size equals inorder length - +`+PERFECT_SIZE+`: Perfect tree size formula + +*Key Concepts:* - Datatype definitions - Structural induction - Complex +recursive functions - Property preservation + +==== 4. `+sorting.sml+` + +Insertion sort and quicksort correctness. + +*Theorems Proved:* - `+INSERT_SORTED+`: Insert maintains sortedness - +`+ISORT_SORTED+`: Insertion sort produces sorted output - +`+ISORT_COUNT+`: Insertion sort preserves element counts - +`+QSORT_SORTED+`: Quicksort produces sorted output + +*Key Concepts:* - Algorithm verification - Termination measures - +Filter-based definitions - Permutation reasoning + +==== 5. `+set_theory.sml+` + +Set operations using HOL4’s pred_setTheory. + +*Theorems Proved:* - De Morgan’s laws (2 theorems) - Distributivity laws +(2 theorems) - Subset properties (3 theorems) - Powerset theorems (3 +theorems) - Cardinality theorems (2 theorems) + +*Key Concepts:* - Higher-order predicates - Extension principle - Finite +set theory - Built-in set libraries + +=== Running These Proofs + +==== With HOL4 Installed + +[source,bash] +---- +# Interactive mode +Holmake +hol + +# In HOL4 REPL: +- use "list_append.sml"; + +# Or batch compile: +Holmake +---- + +==== With ECHIDNA + +[source,bash] +---- +# Parse and verify +echidna verify --prover hol4 list_append.sml + +# Interactive proof mode +echidna repl --prover hol4 +---- + +=== HOL4 Syntax Cheat Sheet + +==== Theory Structure + +[source,sml] +---- +open HolKernel boolLib bossLib; + +val _ = new_theory "theory_name"; + +(* Definitions and theorems *) + +val _ = export_theory(); +---- + +==== Definition Forms + +[source,sml] +---- +Definition NAME_DEF: + (f base_case = result) /\ + (f (recursive_case x) = body) +End +---- + +==== Theorem Form (New Style) + +[source,sml] +---- +Theorem NAME: + !x y. premise ==> conclusion +Proof + tactic1 >> + tactic2 >> + ... +QED +---- + +==== Theorem Form (Old Style) + +[source,sml] +---- +val NAME = store_thm("NAME", + ``!x y. premise ==> conclusion``, + tactic1 >> tactic2 >> ...); +---- + +==== Common Tactics + +[cols=",",options="header",] +|=== +|Tactic |Purpose +|`+rw[]+` |Rewrite with theorems +|`+simp[]+` |Simplification +|`+fs[]+` |Full simplification +|`+gs[]+` |Goal simplification +|`+Induct+` |List induction +|`+Induct_on 'var'+` |Induction on variable +|`+Cases_on 'expr'+` |Case split +|`+DECIDE_TAC+` |Arithmetic decision +|`+ARITH_TAC+` |Arithmetic automation +|`+metis_tac[]+` |Automated reasoning +|`+irule thm+` |Apply theorem backwards +|`+EVAL_TAC+` |Computation +|=== + +==== Tactic Combinators + +[cols=",",options="header",] +|=== +|Combinator |Meaning +|`+t1 >> t2+` |Sequence (then) +|`+t1 ORELSE t2+` |Try t1, else t2 +|`+REPEAT t+` |Repeat until fails +|`+TRY t+` |Try t, don’t fail +|`+ALL_TAC+` |Do nothing +|=== + +==== Datatype Definition + +[source,sml] +---- +Datatype: + tree = Leaf + | Node tree 'a tree +End +---- + +=== Proof Style Guidelines + +==== Goal-Oriented Style + +[source,sml] +---- +Proof + Induct >> rw[] >> + Cases_on 'l' >> fs[] >> + metis_tac[LEMMA_NAME] +QED +---- + +==== Named Intermediate Steps + +[source,sml] +---- +Proof + rw[] >> + 'intermediate_fact' by (simp[] >> DECIDE_TAC) >> + 'another_fact' by metis_tac[LEMMA] >> + DECIDE_TAC +QED +---- + +=== Resources + +* https://hol-theorem-prover.org/[HOL4 Website] +* https://sourceforge.net/projects/hol/files/hol/kananaskis-14/[HOL4 +Tutorial] +* https://hol-theorem-prover.org/kananaskis-14-helpdocs/help/Docfiles/HTML/Description.html[HOL4 +Description Manual] +* https://hol-theorem-prover.org/kananaskis-14-helpdocs/help/Docfiles/HTML/tactic_index.html[HOL4 +Tactic Reference] +* https://hol-theorem-prover.org/kananaskis-14-helpdocs/help/Docfiles/HTML/bossLib.html[bossLib +Automation] diff --git a/proofs/hol4/README.md b/proofs/hol4/README.md deleted file mode 100644 index 1240dcff..00000000 --- a/proofs/hol4/README.md +++ /dev/null @@ -1,211 +0,0 @@ -# HOL4 Example Proofs for ECHIDNA - -This directory contains example HOL4 theories demonstrating the ECHIDNA HOL4 backend capabilities. - -## Files - -### 1. `list_append.sml` -List append properties with reverse. - -**Theorems Proved:** -- `LENGTH_APPEND_THM`: Length distributes over append -- `APPEND_ASSOC_THM`: Append is associative -- `APPEND_NIL_RIGHT`: Nil is right identity -- `REVERSE_APPEND`: Reverse distributes over append -- `REVERSE_REVERSE`: Reverse is involutive - -**Key Concepts:** -- List induction (`Induct`) -- Simplification (`rw[]`) -- Automated reasoning (`metis_tac`) -- Definition/Theorem forms - -### 2. `arithmetic.sml` -Factorial, exponentiation, and sum formulas. - -**Theorems Proved:** -- `FACT_POSITIVE`: Factorial is always positive -- `FACT_MONO`: Factorial is monotonic -- `EXP_ADD`: Exponent addition law -- `EXP_MULT`: Exponent multiplication law -- `SUM_TO_FORMULA`: Sum of first n naturals - -**Key Concepts:** -- Recursive definitions -- Decision procedures (`DECIDE_TAC`) -- Arithmetic reasoning -- Induction over naturals - -### 3. `binary_tree.sml` -Binary tree operations and properties. - -**Theorems Proved:** -- `MIRROR_MIRROR`: Mirror is involutive -- `MIRROR_SIZE`: Mirror preserves size -- `MIRROR_HEIGHT`: Mirror preserves height -- `SIZE_INORDER`: Size equals inorder length -- `PERFECT_SIZE`: Perfect tree size formula - -**Key Concepts:** -- Datatype definitions -- Structural induction -- Complex recursive functions -- Property preservation - -### 4. `sorting.sml` -Insertion sort and quicksort correctness. - -**Theorems Proved:** -- `INSERT_SORTED`: Insert maintains sortedness -- `ISORT_SORTED`: Insertion sort produces sorted output -- `ISORT_COUNT`: Insertion sort preserves element counts -- `QSORT_SORTED`: Quicksort produces sorted output - -**Key Concepts:** -- Algorithm verification -- Termination measures -- Filter-based definitions -- Permutation reasoning - -### 5. `set_theory.sml` -Set operations using HOL4's pred_setTheory. - -**Theorems Proved:** -- De Morgan's laws (2 theorems) -- Distributivity laws (2 theorems) -- Subset properties (3 theorems) -- Powerset theorems (3 theorems) -- Cardinality theorems (2 theorems) - -**Key Concepts:** -- Higher-order predicates -- Extension principle -- Finite set theory -- Built-in set libraries - -## Running These Proofs - -### With HOL4 Installed - -```bash -# Interactive mode -Holmake -hol - -# In HOL4 REPL: -- use "list_append.sml"; - -# Or batch compile: -Holmake -``` - -### With ECHIDNA - -```bash -# Parse and verify -echidna verify --prover hol4 list_append.sml - -# Interactive proof mode -echidna repl --prover hol4 -``` - -## HOL4 Syntax Cheat Sheet - -### Theory Structure -```sml -open HolKernel boolLib bossLib; - -val _ = new_theory "theory_name"; - -(* Definitions and theorems *) - -val _ = export_theory(); -``` - -### Definition Forms -```sml -Definition NAME_DEF: - (f base_case = result) /\ - (f (recursive_case x) = body) -End -``` - -### Theorem Form (New Style) -```sml -Theorem NAME: - !x y. premise ==> conclusion -Proof - tactic1 >> - tactic2 >> - ... -QED -``` - -### Theorem Form (Old Style) -```sml -val NAME = store_thm("NAME", - ``!x y. premise ==> conclusion``, - tactic1 >> tactic2 >> ...); -``` - -### Common Tactics -| Tactic | Purpose | -|--------|---------| -| `rw[]` | Rewrite with theorems | -| `simp[]` | Simplification | -| `fs[]` | Full simplification | -| `gs[]` | Goal simplification | -| `Induct` | List induction | -| `Induct_on 'var'` | Induction on variable | -| `Cases_on 'expr'` | Case split | -| `DECIDE_TAC` | Arithmetic decision | -| `ARITH_TAC` | Arithmetic automation | -| `metis_tac[]` | Automated reasoning | -| `irule thm` | Apply theorem backwards | -| `EVAL_TAC` | Computation | - -### Tactic Combinators -| Combinator | Meaning | -|------------|---------| -| `t1 >> t2` | Sequence (then) | -| `t1 ORELSE t2` | Try t1, else t2 | -| `REPEAT t` | Repeat until fails | -| `TRY t` | Try t, don't fail | -| `ALL_TAC` | Do nothing | - -### Datatype Definition -```sml -Datatype: - tree = Leaf - | Node tree 'a tree -End -``` - -## Proof Style Guidelines - -### Goal-Oriented Style -```sml -Proof - Induct >> rw[] >> - Cases_on 'l' >> fs[] >> - metis_tac[LEMMA_NAME] -QED -``` - -### Named Intermediate Steps -```sml -Proof - rw[] >> - 'intermediate_fact' by (simp[] >> DECIDE_TAC) >> - 'another_fact' by metis_tac[LEMMA] >> - DECIDE_TAC -QED -``` - -## Resources - -- [HOL4 Website](https://hol-theorem-prover.org/) -- [HOL4 Tutorial](https://sourceforge.net/projects/hol/files/hol/kananaskis-14/) -- [HOL4 Description Manual](https://hol-theorem-prover.org/kananaskis-14-helpdocs/help/Docfiles/HTML/Description.html) -- [HOL4 Tactic Reference](https://hol-theorem-prover.org/kananaskis-14-helpdocs/help/Docfiles/HTML/tactic_index.html) -- [bossLib Automation](https://hol-theorem-prover.org/kananaskis-14-helpdocs/help/Docfiles/HTML/bossLib.html) diff --git a/proofs/lean/README.adoc b/proofs/lean/README.adoc new file mode 100644 index 00000000..d8b45fc2 --- /dev/null +++ b/proofs/lean/README.adoc @@ -0,0 +1,182 @@ +== ECHIDNA Lean 4 Proof Examples + +This directory contains comprehensive Lean 4 proof examples +demonstrating progressive complexity for the ECHIDNA neurosymbolic +theorem proving platform. + +=== Files + +==== 1. Basic.lean + +Foundation-level proofs covering: - Identity proofs (A → A) - Modus +ponens ((A → B) → A → B) - Transitivity ((A → B) → (B → C) → (A → C)) - +Conjunction (AND) properties - Disjunction (OR) properties - Implication +chains - Distribution laws - Curry-Howard correspondence examples + +*Complexity*: Beginner *Lines*: ~350 *Key Tactics*: `+intro+`, +`+exact+`, `+apply+`, `+constructor+`, `+cases+`, `+left+`, `+right+` + +==== 2. Propositional.lean + +Propositional logic theorems: - De Morgan’s laws (both directions) - +Double negation introduction/elimination - Classical logic principles +(excluded middle, Peirce’s law) - Contrapositive reasoning - Proof by +contradiction - Material implication - Currying/uncurrying - Ex falso +quodlibet - Distributivity laws - Logical equivalence properties + +*Complexity*: Intermediate *Lines*: ~450 *Key Tactics*: `+by_cases+`, +`+exfalso+`, `+intro+`, `+cases+`, `+constructor+` + +==== 3. Nat.lean + +Natural number proofs: - Basic arithmetic (addition, multiplication +identities) - Commutativity and associativity - Distributivity - +Induction examples - Comparison and ordering - Cancellation laws - +Subtraction properties - Number theory (even/odd definitions) - Division +and modulo properties - GCD properties + +*Complexity*: Intermediate-Advanced *Lines*: ~500 *Key Tactics*: +`+induction+`, `+rw+`, `+rfl+`, `+omega+`, `+ring+`, `+simp+` + +==== 4. List.lean + +List data structure proofs: - Append properties (identity, +associativity) - Length theorems - Reverse properties (involutive, +length preservation) - Map properties (length preservation, composition, +identity) - Filter properties - Fold (left/right) properties - Sum and +product - Membership properties - Take/drop operations - Zip properties +- All/any predicates - Replicate properties + +*Complexity*: Advanced *Lines*: ~550 *Key Tactics*: `+induction+`, +`+simp+`, `+rw+`, `+cases+`, `+omega+`, `+generalizing+` + +=== Usage + +==== Type-Checking + +To verify these proofs with Lean 4: + +[source,bash] +---- +# Install Lean 4 (if not already installed) +curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh + +# Navigate to this directory +cd /home/user/echidna/proofs/lean + +# Initialize Lake project (if needed) +lake init + +# Build and type-check all proofs +lake build +---- + +==== Running Individual Files + +[source,bash] +---- +# Check a specific file +lean Basic.lean +lean Propositional.lean +lean Nat.lean +lean List.lean +---- + +==== Interactive Mode + +Open any `+.lean+` file in VS Code with the Lean 4 extension installed +for interactive theorem proving with inline feedback. + +=== Integration with ECHIDNA + +These proof files serve multiple purposes in the ECHIDNA system: + +[arabic] +. *Test Cases*: Verify that the Lean backend integration correctly +handles various proof patterns +. *Benchmarks*: Measure performance across different complexity levels +. *Examples*: Demonstrate proof techniques to users +. *Regression Tests*: Ensure system updates don’t break existing +functionality + +==== Aspect Tagging + +Each file corresponds to different proof aspects: - *Basic.lean*: +`+logic.foundation+`, `+proof.intro+`, `+curry-howard+` - +*Propositional.lean*: `+logic.classical+`, `+proof.contradiction+`, +`+logic.equivalence+` - *Nat.lean*: `+arithmetic.basic+`, +`+induction.nat+`, `+number-theory.elementary+` - *List.lean*: +`+data-structures.list+`, `+functional.map-fold+`, +`+induction.structural+` + +=== Lean 4 Features Used + +==== Syntax + +* Pattern matching with `+cases+` +* Structured tactic proofs with `+by+` +* Anonymous constructor (`+⟨⟩+` notation) +* Function composition (`+∘+`) +* Unicode symbols (`+→+`, `+∧+`, `+∨+`, `+¬+`, `+∀+`, `+∃+`) + +==== Tactics + +* *intro*: Introduce hypotheses +* *exact*: Provide exact proof term +* *apply*: Apply function/theorem +* *rw/rewrite*: Rewrite using equality +* *rfl*: Reflexivity of equality +* *cases*: Case analysis +* *induction*: Structural induction +* *simp*: Simplification +* *omega*: Linear arithmetic solver +* *ring*: Ring normalization +* *by_cases*: Classical case split +* *constructor*: Build inductive types +* *left/right*: Disjunction introduction +* *exfalso*: Proof from False + +==== Standard Library + +* `+Nat+`: Natural numbers +* `+List+`: Polymorphic lists +* `+Prop+`: Propositions +* `+Bool+`: Boolean values + +=== Verification Status + +* [x] Basic.lean - Type-checks with Lean 4.13.0 +* [x] Propositional.lean - Type-checks with Lean 4.13.0 +* [x] Nat.lean - Type-checks with Lean 4.13.0 (all theorems fully +proven, zero sorry) +* [x] List.lean - Type-checks with Lean 4.13.0 + +=== Dependencies + +* *Lean 4*: v4.13.0 or later +* *Lake*: Lean 4 build system +* *Mathlib* (optional): For advanced theorems + +=== License + +Dual-licensed under: - MIT License - Palimpsest License v0.6 + +=== Contributing + +When adding new proofs: 1. Follow existing naming conventions 2. Include +clear doc comments (`+/-- ... -/+`) 3. Use standard tactics where +possible 4. Ensure proofs type-check before committing 5. Update this +README with new content + +=== References + +* https://lean-lang.org/documentation/[Lean 4 Documentation] +* https://leanprover.github.io/theorem_proving_in_lean4/[Theorem Proving +in Lean 4] +* https://github.com/leanprover-community/mathlib4[Lean 4 Mathlib] +* https://github.com/hyperpolymath/echidna[ECHIDNA Project] + +''''' + +*Last Updated*: 2025-11-22 *Lean Version*: 4.13.0 *Status*: Production +Ready diff --git a/proofs/lean/README.md b/proofs/lean/README.md deleted file mode 100644 index aba26392..00000000 --- a/proofs/lean/README.md +++ /dev/null @@ -1,201 +0,0 @@ - - -# ECHIDNA Lean 4 Proof Examples - -This directory contains comprehensive Lean 4 proof examples demonstrating progressive complexity for the ECHIDNA neurosymbolic theorem proving platform. - -## Files - -### 1. Basic.lean -Foundation-level proofs covering: -- Identity proofs (A → A) -- Modus ponens ((A → B) → A → B) -- Transitivity ((A → B) → (B → C) → (A → C)) -- Conjunction (AND) properties -- Disjunction (OR) properties -- Implication chains -- Distribution laws -- Curry-Howard correspondence examples - -**Complexity**: Beginner -**Lines**: ~350 -**Key Tactics**: `intro`, `exact`, `apply`, `constructor`, `cases`, `left`, `right` - -### 2. Propositional.lean -Propositional logic theorems: -- De Morgan's laws (both directions) -- Double negation introduction/elimination -- Classical logic principles (excluded middle, Peirce's law) -- Contrapositive reasoning -- Proof by contradiction -- Material implication -- Currying/uncurrying -- Ex falso quodlibet -- Distributivity laws -- Logical equivalence properties - -**Complexity**: Intermediate -**Lines**: ~450 -**Key Tactics**: `by_cases`, `exfalso`, `intro`, `cases`, `constructor` - -### 3. Nat.lean -Natural number proofs: -- Basic arithmetic (addition, multiplication identities) -- Commutativity and associativity -- Distributivity -- Induction examples -- Comparison and ordering -- Cancellation laws -- Subtraction properties -- Number theory (even/odd definitions) -- Division and modulo properties -- GCD properties - -**Complexity**: Intermediate-Advanced -**Lines**: ~500 -**Key Tactics**: `induction`, `rw`, `rfl`, `omega`, `ring`, `simp` - -### 4. List.lean -List data structure proofs: -- Append properties (identity, associativity) -- Length theorems -- Reverse properties (involutive, length preservation) -- Map properties (length preservation, composition, identity) -- Filter properties -- Fold (left/right) properties -- Sum and product -- Membership properties -- Take/drop operations -- Zip properties -- All/any predicates -- Replicate properties - -**Complexity**: Advanced -**Lines**: ~550 -**Key Tactics**: `induction`, `simp`, `rw`, `cases`, `omega`, `generalizing` - -## Usage - -### Type-Checking - -To verify these proofs with Lean 4: - -```bash -# Install Lean 4 (if not already installed) -curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh - -# Navigate to this directory -cd /home/user/echidna/proofs/lean - -# Initialize Lake project (if needed) -lake init - -# Build and type-check all proofs -lake build -``` - -### Running Individual Files - -```bash -# Check a specific file -lean Basic.lean -lean Propositional.lean -lean Nat.lean -lean List.lean -``` - -### Interactive Mode - -Open any `.lean` file in VS Code with the Lean 4 extension installed for interactive theorem proving with inline feedback. - -## Integration with ECHIDNA - -These proof files serve multiple purposes in the ECHIDNA system: - -1. **Test Cases**: Verify that the Lean backend integration correctly handles various proof patterns -2. **Benchmarks**: Measure performance across different complexity levels -3. **Examples**: Demonstrate proof techniques to users -4. **Regression Tests**: Ensure system updates don't break existing functionality - -### Aspect Tagging - -Each file corresponds to different proof aspects: -- **Basic.lean**: `logic.foundation`, `proof.intro`, `curry-howard` -- **Propositional.lean**: `logic.classical`, `proof.contradiction`, `logic.equivalence` -- **Nat.lean**: `arithmetic.basic`, `induction.nat`, `number-theory.elementary` -- **List.lean**: `data-structures.list`, `functional.map-fold`, `induction.structural` - -## Lean 4 Features Used - -### Syntax -- Pattern matching with `cases` -- Structured tactic proofs with `by` -- Anonymous constructor (`⟨⟩` notation) -- Function composition (`∘`) -- Unicode symbols (`→`, `∧`, `∨`, `¬`, `∀`, `∃`) - -### Tactics -- **intro**: Introduce hypotheses -- **exact**: Provide exact proof term -- **apply**: Apply function/theorem -- **rw/rewrite**: Rewrite using equality -- **rfl**: Reflexivity of equality -- **cases**: Case analysis -- **induction**: Structural induction -- **simp**: Simplification -- **omega**: Linear arithmetic solver -- **ring**: Ring normalization -- **by_cases**: Classical case split -- **constructor**: Build inductive types -- **left/right**: Disjunction introduction -- **exfalso**: Proof from False - -### Standard Library -- `Nat`: Natural numbers -- `List`: Polymorphic lists -- `Prop`: Propositions -- `Bool`: Boolean values - -## Verification Status - -- [x] Basic.lean - Type-checks with Lean 4.13.0 -- [x] Propositional.lean - Type-checks with Lean 4.13.0 -- [x] Nat.lean - Type-checks with Lean 4.13.0 (all theorems fully proven, zero sorry) -- [x] List.lean - Type-checks with Lean 4.13.0 - -## Dependencies - -- **Lean 4**: v4.13.0 or later -- **Lake**: Lean 4 build system -- **Mathlib** (optional): For advanced theorems - -## License - -Dual-licensed under: -- MIT License -- Palimpsest License v0.6 - -## Contributing - -When adding new proofs: -1. Follow existing naming conventions -2. Include clear doc comments (`/-- ... -/`) -3. Use standard tactics where possible -4. Ensure proofs type-check before committing -5. Update this README with new content - -## References - -- [Lean 4 Documentation](https://lean-lang.org/documentation/) -- [Theorem Proving in Lean 4](https://leanprover.github.io/theorem_proving_in_lean4/) -- [Lean 4 Mathlib](https://github.com/leanprover-community/mathlib4) -- [ECHIDNA Project](https://github.com/hyperpolymath/echidna) - ---- - -**Last Updated**: 2025-11-22 -**Lean Version**: 4.13.0 -**Status**: Production Ready diff --git a/proofs/lean/THEOREMS.adoc b/proofs/lean/THEOREMS.adoc new file mode 100644 index 00000000..6e182de1 --- /dev/null +++ b/proofs/lean/THEOREMS.adoc @@ -0,0 +1,361 @@ +== ECHIDNA Lean 4 Theorems Reference + +Quick reference guide for all theorems and definitions in the Lean proof +files. + +=== Basic.lean (28 theorems/defs) + +==== Identity Proofs + +* `+identity+` - A → A (tactic proof) +* `+identity'+` - A → A (term proof) +* `+identity_type+` - x = x (type identity) + +==== Modus Ponens + +* `+modus_ponens+` - (A → B) → A → B +* `+modus_ponens'+` - (A → B) → A → B (concise) + +==== Transitivity + +* `+transitivity+` - (A → B) → (B → C) → (A → C) +* `+transitivity'+` - (A → B) → (B → C) → (A → C) (concise) + +==== Conjunction (AND) + +* `+and_intro+` - A → B → (A ∧ B) +* `+and_elim_left+` - (A ∧ B) → A +* `+and_elim_right+` - (A ∧ B) → B +* `+and_comm+` - (A ∧ B) → (B ∧ A) + +==== Disjunction (OR) + +* `+or_intro_left+` - A → (A ∨ B) +* `+or_intro_right+` - B → (A ∨ B) +* `+or_comm+` - (A ∨ B) → (B ∨ A) + +==== Implication Chains + +* `+hypothetical_syllogism+` - (A → B) → (B → C) → (A → C) +* `+triple_transitivity+` - (A → B) → (B → C) → (C → D) → (A → D) + +==== Distribution Laws + +* `+and_or_distrib_left+` - A ∧ (B ∨ C) → (A ∧ B) ∨ (A ∧ C) +* `+and_or_distrib_right+` - (A ∨ B) ∧ C → (A ∧ C) ∨ (B ∧ C) + +==== Curry-Howard + +* `+id_function+` - Identity function +* `+compose+` - Function composition +* `+compose_assoc+` - Composition associativity + +*Total: 21 theorems + 3 definitions = 24 items* + +''''' + +=== Propositional.lean (36 theorems) + +==== De Morgan’s Laws + +* `+de_morgan_1+` - ¬(A ∧ B) → (¬A ∨ ¬B) +* `+de_morgan_1_rev+` - (¬A ∨ ¬B) → ¬(A ∧ B) +* `+de_morgan_2+` - ¬(A ∨ B) → (¬A ∧ ¬B) +* `+de_morgan_2_rev+` - (¬A ∧ ¬B) → ¬(A ∨ B) + +==== Double Negation + +* `+double_neg_intro+` - A → ¬¬A (constructive) +* `+double_neg_elim+` - ¬¬A → A (classical) +* `+triple_neg+` - ¬¬¬A → ¬A (constructive) + +==== Classical Logic + +* `+excluded_middle+` - A ∨ ¬A +* `+peirce+` - ((A → B) → A) → A +* `+double_neg_excluded_middle+` - ¬¬(A ∨ ¬A) + +==== Contrapositive + +* `+contrapositive+` - (A → B) → (¬B → ¬A) +* `+contrapositive_rev+` - (¬B → ¬A) → (A → B) +* `+proof_by_contradiction+` - (¬A → False) → A + +==== Material Implication + +* `+material_impl_fwd+` - (A → B) → (¬A ∨ B) +* `+material_impl_rev+` - (¬A ∨ B) → (A → B) + +==== Implication Properties + +* `+impl_trans+` - (A → B) → (B → C) → (A → C) +* `+curry+` - (A ∧ B → C) → (A → B → C) +* `+uncurry+` - (A → B → C) → (A ∧ B → C) + +==== Absurdity + +* `+ex_falso+` - False → A +* `+not_true+` - ¬True → False +* `+not_not_false+` - ¬¬False → False + +==== Distributivity + +* `+and_distrib_or+` - A ∧ (B ∨ C) ↔ (A ∧ B) ∨ (A ∧ C) +* `+or_distrib_and+` - A ∨ (B ∧ C) → (A ∨ B) ∧ (A ∨ C) + +==== Equivalence + +* `+iff_refl+` - A ↔ A +* `+iff_symm+` - (A ↔ B) → (B ↔ A) +* `+iff_trans+` - (A ↔ B) → (B ↔ C) → (A ↔ C) + +*Total: 27 theorems* + +''''' + +=== Nat.lean (48 theorems/defs) + +==== Basic Arithmetic + +* `+add_zero+` - n + 0 = n +* `+zero_add+` - 0 + n = n +* `+mul_one+` - n * 1 = n +* `+one_mul+` - 1 * n = n +* `+mul_zero+` - n * 0 = 0 +* `+zero_mul+` - 0 * n = 0 + +==== Commutativity + +* `+add_comm+` - m + n = n + m +* `+mul_comm+` - m * n = n * m + +==== Associativity + +* `+add_assoc+` - (m + n) + k = m + (n + k) +* `+mul_assoc+` - (m * n) * k = m * (n * k) + +==== Distributivity + +* `+left_distrib+` - m * (n + k) = m * n + m * k +* `+right_distrib+` - (m + n) * k = m * k + n * k + +==== Induction Examples + +* `+sumTo_formula+` - Sum formula (fully proven via omega) +* `+double_add+` - n + n = 2 * n +* `+pow2_ge+` - 2^n ≥ n for n ≥ 1 + +==== Ordering + +* `+le_refl+` - n ≤ n +* `+le_antisymm+` - m ≤ n → n ≤ m → m = n +* `+le_trans+` - m ≤ n → n ≤ k → m ≤ k +* `+lt_succ_self+` - n < n + 1 +* `+zero_le+` - 0 ≤ n + +==== Addition Properties + +* `+add_left_cancel+` - k + m = k + n → m = n +* `+add_right_cancel+` - m + k = n + k → m = n +* `+add_le_add_left+` - m ≤ n → k + m ≤ k + n +* `+add_le_add_right+` - m ≤ n → m + k ≤ n + k + +==== Multiplication Properties + +* `+mul_succ+` - m * (n + 1) = m * n + m +* `+succ_mul+` - (m + 1) * n = m * n + n +* `+mul_left_cancel+` - k > 0 → k * m = k * n → m = n + +==== Subtraction + +* `+sub_zero+` - n - 0 = n +* `+sub_self+` - n - n = 0 +* `+sub_add_cancel+` - n ≤ m → (m - n) + n = m + +==== Number Theory + +* `+is_even+` (def) - ∃ k, n = 2 * k +* `+is_odd+` (def) - ∃ k, n = 2 * k + 1 +* `+zero_is_even+` - is_even 0 +* `+one_is_odd+` - is_odd 1 +* `+two_is_even+` - is_even 2 +* `+even_add_even+` - Even + even = even +* `+mul_even+` - m * even = even + +==== Division + +* `+div_one+` - n / 1 = n +* `+div_self+` - n > 0 → n / n = 1 + +==== Modulo + +* `+mod_one+` - n % 1 = 0 +* `+mod_self+` - n > 0 → n % n = 0 +* `+mod_lt+` - n > 0 → m % n < n + +==== GCD + +* `+gcd_comm+` - gcd m n = gcd n m +* `+gcd_zero_right+` - gcd n 0 = n +* `+gcd_self+` - gcd n n = n + +*Total: 46 theorems + 2 definitions = 48 items* + +''''' + +=== List.lean (52 theorems) + +==== Basic Properties + +* `+length_nil+` - length [] = 0 +* `+length_singleton+` - length [x] = 1 +* `+length_cons+` - length (x :: xs) = length xs + 1 + +==== Append + +* `+append_nil+` - xs ++ [] = xs +* `+nil_append+` - [] ++ xs = xs +* `+append_assoc+` - (xs ++ ys) ++ zs = xs ++ (ys ++ zs) +* `+length_append+` - length (xs ++ ys) = length xs + length ys + +==== Reverse + +* `+reverse_nil+` - reverse [] = [] +* `+reverse_singleton+` - reverse [x] = [x] +* `+reverse_reverse+` - reverse (reverse xs) = xs +* `+length_reverse+` - length (reverse xs) = length xs +* `+reverse_append+` - reverse (xs ++ ys) = reverse ys ++ reverse xs + +==== Map + +* `+map_nil+` - map f [] = [] +* `+map_cons+` - map f (x :: xs) = f x :: map f xs +* `+length_map+` - length (map f xs) = length xs +* `+map_append+` - map f (xs ++ ys) = map f xs ++ map f ys +* `+map_id+` - map id xs = xs +* `+map_map+` - map g (map f xs) = map (g ∘ f) xs + +==== Filter + +* `+filter_nil+` - filter p [] = [] +* `+length_filter_le+` - length (filter p xs) ≤ length xs +* `+filter_append+` - filter p (xs ++ ys) = filter p xs ++ filter p ys + +==== Fold + +* `+foldr_nil+` - foldr f init [] = init +* `+foldr_cons+` - foldr f init (x :: xs) = f x (foldr f init xs) +* `+foldr_append+` - foldr f init (xs ++ ys) = foldr f (foldr f init ys) +xs +* `+foldl_nil+` - foldl f init [] = init +* `+foldl_cons+` - foldl f init (x :: xs) = foldl f (f init x) xs + +==== Sum and Product + +* `+sum_nil+` - sum [] = 0 +* `+sum_cons+` - sum (x :: xs) = x + sum xs +* `+sum_append+` - sum (xs ++ ys) = sum xs + sum ys + +==== Membership + +* `+mem_nil+` - x ∉ [] +* `+mem_cons_self+` - x ∈ (x :: xs) +* `+mem_cons_of_mem+` - x ∈ xs → x ∈ (y :: xs) +* `+mem_append_left+` - x ∈ xs → x ∈ (xs ++ ys) +* `+mem_append_right+` - x ∈ ys → x ∈ (xs ++ ys) + +==== Take and Drop + +* `+take_zero+` - take 0 xs = [] +* `+take_nil+` - take n [] = [] +* `+drop_zero+` - drop 0 xs = xs +* `+drop_nil+` - drop n [] = [] +* `+take_append_drop+` - take n xs ++ drop n xs = xs + +==== Zip + +* `+zip_nil_left+` - zip [] ys = [] +* `+zip_nil_right+` - zip xs [] = [] +* `+length_zip+` - length (zip xs ys) = min (length xs) (length ys) + +==== All and Any + +* `+all_nil+` - all [] p = true +* `+any_nil+` - any [] p = false +* `+all_append+` - all (xs ++ ys) p = (all xs p && all ys p) + +==== Replicate + +* `+replicate_zero+` - replicate 0 x = [] +* `+length_replicate+` - length (replicate n x) = n + +*Total: 48 theorems* + +''''' + +=== Summary Statistics + +[cols=",,,,",options="header",] +|=== +|File |Theorems |Definitions |Total |Lines +|Basic.lean |21 |3 |24 |225 +|Propositional.lean |27 |0 |27 |319 +|Nat.lean |46 |2 |48 |377 +|List.lean |48 |0 |48 |437 +|*TOTAL* |*142* |*5* |*147* |*1358* +|=== + +=== Coverage Analysis + +==== Proof Techniques + +* *Direct proof*: 65% +* *Induction*: 20% +* *Case analysis*: 10% +* *Classical reasoning*: 5% + +==== Tactics Used + +* `+intro+`, `+exact+`, `+apply+`: Universal +* `+induction+`, `+cases+`: Structural proofs +* `+rw+`, `+rfl+`, `+simp+`: Rewriting +* `+omega+`, `+ring+`: Automation +* `+by_cases+`, `+exfalso+`: Classical + +==== Mathematical Areas + +* *Logic*: Propositional, predicate, classical +* *Arithmetic*: Natural numbers, basic operations +* *Algebra*: Associativity, commutativity, distributivity +* *Data structures*: Lists, functional programming +* *Number theory*: Even/odd, GCD, divisibility + +=== Integration with ECHIDNA + +==== Test Coverage + +* *Tier 1*: Basic logic and arithmetic (100%) +* *Tier 2*: Induction and data structures (100%) +* *Tier 3*: Advanced proofs (100% - all sorry instances resolved) + +==== Performance Benchmarks + +* Small proofs (<10 lines): ~0.1s +* Medium proofs (10-30 lines): ~0.5s +* Large proofs (>30 lines): ~2s + +==== Aspect Tags + +[source,rust] +---- +// Example aspect tagging for ECHIDNA +Basic.lean: ["logic.foundation", "proof.intro", "curry-howard"] +Propositional.lean: ["logic.classical", "proof.contradiction", "de-morgan"] +Nat.lean: ["arithmetic.nat", "induction.nat", "number-theory"] +List.lean: ["data.list", "functional.map-fold", "induction.structural"] +---- + +''''' + +*Generated*: 2025-11-22 *Verified*: Lean 4.13.0 *Status*: Production +Ready diff --git a/proofs/lean/THEOREMS.md b/proofs/lean/THEOREMS.md deleted file mode 100644 index 1bbd52e2..00000000 --- a/proofs/lean/THEOREMS.md +++ /dev/null @@ -1,314 +0,0 @@ - - -# ECHIDNA Lean 4 Theorems Reference - -Quick reference guide for all theorems and definitions in the Lean proof files. - -## Basic.lean (28 theorems/defs) - -### Identity Proofs -- `identity` - A → A (tactic proof) -- `identity'` - A → A (term proof) -- `identity_type` - x = x (type identity) - -### Modus Ponens -- `modus_ponens` - (A → B) → A → B -- `modus_ponens'` - (A → B) → A → B (concise) - -### Transitivity -- `transitivity` - (A → B) → (B → C) → (A → C) -- `transitivity'` - (A → B) → (B → C) → (A → C) (concise) - -### Conjunction (AND) -- `and_intro` - A → B → (A ∧ B) -- `and_elim_left` - (A ∧ B) → A -- `and_elim_right` - (A ∧ B) → B -- `and_comm` - (A ∧ B) → (B ∧ A) - -### Disjunction (OR) -- `or_intro_left` - A → (A ∨ B) -- `or_intro_right` - B → (A ∨ B) -- `or_comm` - (A ∨ B) → (B ∨ A) - -### Implication Chains -- `hypothetical_syllogism` - (A → B) → (B → C) → (A → C) -- `triple_transitivity` - (A → B) → (B → C) → (C → D) → (A → D) - -### Distribution Laws -- `and_or_distrib_left` - A ∧ (B ∨ C) → (A ∧ B) ∨ (A ∧ C) -- `and_or_distrib_right` - (A ∨ B) ∧ C → (A ∧ C) ∨ (B ∧ C) - -### Curry-Howard -- `id_function` - Identity function -- `compose` - Function composition -- `compose_assoc` - Composition associativity - -**Total: 21 theorems + 3 definitions = 24 items** - ---- - -## Propositional.lean (36 theorems) - -### De Morgan's Laws -- `de_morgan_1` - ¬(A ∧ B) → (¬A ∨ ¬B) -- `de_morgan_1_rev` - (¬A ∨ ¬B) → ¬(A ∧ B) -- `de_morgan_2` - ¬(A ∨ B) → (¬A ∧ ¬B) -- `de_morgan_2_rev` - (¬A ∧ ¬B) → ¬(A ∨ B) - -### Double Negation -- `double_neg_intro` - A → ¬¬A (constructive) -- `double_neg_elim` - ¬¬A → A (classical) -- `triple_neg` - ¬¬¬A → ¬A (constructive) - -### Classical Logic -- `excluded_middle` - A ∨ ¬A -- `peirce` - ((A → B) → A) → A -- `double_neg_excluded_middle` - ¬¬(A ∨ ¬A) - -### Contrapositive -- `contrapositive` - (A → B) → (¬B → ¬A) -- `contrapositive_rev` - (¬B → ¬A) → (A → B) -- `proof_by_contradiction` - (¬A → False) → A - -### Material Implication -- `material_impl_fwd` - (A → B) → (¬A ∨ B) -- `material_impl_rev` - (¬A ∨ B) → (A → B) - -### Implication Properties -- `impl_trans` - (A → B) → (B → C) → (A → C) -- `curry` - (A ∧ B → C) → (A → B → C) -- `uncurry` - (A → B → C) → (A ∧ B → C) - -### Absurdity -- `ex_falso` - False → A -- `not_true` - ¬True → False -- `not_not_false` - ¬¬False → False - -### Distributivity -- `and_distrib_or` - A ∧ (B ∨ C) ↔ (A ∧ B) ∨ (A ∧ C) -- `or_distrib_and` - A ∨ (B ∧ C) → (A ∨ B) ∧ (A ∨ C) - -### Equivalence -- `iff_refl` - A ↔ A -- `iff_symm` - (A ↔ B) → (B ↔ A) -- `iff_trans` - (A ↔ B) → (B ↔ C) → (A ↔ C) - -**Total: 27 theorems** - ---- - -## Nat.lean (48 theorems/defs) - -### Basic Arithmetic -- `add_zero` - n + 0 = n -- `zero_add` - 0 + n = n -- `mul_one` - n * 1 = n -- `one_mul` - 1 * n = n -- `mul_zero` - n * 0 = 0 -- `zero_mul` - 0 * n = 0 - -### Commutativity -- `add_comm` - m + n = n + m -- `mul_comm` - m * n = n * m - -### Associativity -- `add_assoc` - (m + n) + k = m + (n + k) -- `mul_assoc` - (m * n) * k = m * (n * k) - -### Distributivity -- `left_distrib` - m * (n + k) = m * n + m * k -- `right_distrib` - (m + n) * k = m * k + n * k - -### Induction Examples -- `sumTo_formula` - Sum formula (fully proven via omega) -- `double_add` - n + n = 2 * n -- `pow2_ge` - 2^n ≥ n for n ≥ 1 - -### Ordering -- `le_refl` - n ≤ n -- `le_antisymm` - m ≤ n → n ≤ m → m = n -- `le_trans` - m ≤ n → n ≤ k → m ≤ k -- `lt_succ_self` - n < n + 1 -- `zero_le` - 0 ≤ n - -### Addition Properties -- `add_left_cancel` - k + m = k + n → m = n -- `add_right_cancel` - m + k = n + k → m = n -- `add_le_add_left` - m ≤ n → k + m ≤ k + n -- `add_le_add_right` - m ≤ n → m + k ≤ n + k - -### Multiplication Properties -- `mul_succ` - m * (n + 1) = m * n + m -- `succ_mul` - (m + 1) * n = m * n + n -- `mul_left_cancel` - k > 0 → k * m = k * n → m = n - -### Subtraction -- `sub_zero` - n - 0 = n -- `sub_self` - n - n = 0 -- `sub_add_cancel` - n ≤ m → (m - n) + n = m - -### Number Theory -- `is_even` (def) - ∃ k, n = 2 * k -- `is_odd` (def) - ∃ k, n = 2 * k + 1 -- `zero_is_even` - is_even 0 -- `one_is_odd` - is_odd 1 -- `two_is_even` - is_even 2 -- `even_add_even` - Even + even = even -- `mul_even` - m * even = even - -### Division -- `div_one` - n / 1 = n -- `div_self` - n > 0 → n / n = 1 - -### Modulo -- `mod_one` - n % 1 = 0 -- `mod_self` - n > 0 → n % n = 0 -- `mod_lt` - n > 0 → m % n < n - -### GCD -- `gcd_comm` - gcd m n = gcd n m -- `gcd_zero_right` - gcd n 0 = n -- `gcd_self` - gcd n n = n - -**Total: 46 theorems + 2 definitions = 48 items** - ---- - -## List.lean (52 theorems) - -### Basic Properties -- `length_nil` - length [] = 0 -- `length_singleton` - length [x] = 1 -- `length_cons` - length (x :: xs) = length xs + 1 - -### Append -- `append_nil` - xs ++ [] = xs -- `nil_append` - [] ++ xs = xs -- `append_assoc` - (xs ++ ys) ++ zs = xs ++ (ys ++ zs) -- `length_append` - length (xs ++ ys) = length xs + length ys - -### Reverse -- `reverse_nil` - reverse [] = [] -- `reverse_singleton` - reverse [x] = [x] -- `reverse_reverse` - reverse (reverse xs) = xs -- `length_reverse` - length (reverse xs) = length xs -- `reverse_append` - reverse (xs ++ ys) = reverse ys ++ reverse xs - -### Map -- `map_nil` - map f [] = [] -- `map_cons` - map f (x :: xs) = f x :: map f xs -- `length_map` - length (map f xs) = length xs -- `map_append` - map f (xs ++ ys) = map f xs ++ map f ys -- `map_id` - map id xs = xs -- `map_map` - map g (map f xs) = map (g ∘ f) xs - -### Filter -- `filter_nil` - filter p [] = [] -- `length_filter_le` - length (filter p xs) ≤ length xs -- `filter_append` - filter p (xs ++ ys) = filter p xs ++ filter p ys - -### Fold -- `foldr_nil` - foldr f init [] = init -- `foldr_cons` - foldr f init (x :: xs) = f x (foldr f init xs) -- `foldr_append` - foldr f init (xs ++ ys) = foldr f (foldr f init ys) xs -- `foldl_nil` - foldl f init [] = init -- `foldl_cons` - foldl f init (x :: xs) = foldl f (f init x) xs - -### Sum and Product -- `sum_nil` - sum [] = 0 -- `sum_cons` - sum (x :: xs) = x + sum xs -- `sum_append` - sum (xs ++ ys) = sum xs + sum ys - -### Membership -- `mem_nil` - x ∉ [] -- `mem_cons_self` - x ∈ (x :: xs) -- `mem_cons_of_mem` - x ∈ xs → x ∈ (y :: xs) -- `mem_append_left` - x ∈ xs → x ∈ (xs ++ ys) -- `mem_append_right` - x ∈ ys → x ∈ (xs ++ ys) - -### Take and Drop -- `take_zero` - take 0 xs = [] -- `take_nil` - take n [] = [] -- `drop_zero` - drop 0 xs = xs -- `drop_nil` - drop n [] = [] -- `take_append_drop` - take n xs ++ drop n xs = xs - -### Zip -- `zip_nil_left` - zip [] ys = [] -- `zip_nil_right` - zip xs [] = [] -- `length_zip` - length (zip xs ys) = min (length xs) (length ys) - -### All and Any -- `all_nil` - all [] p = true -- `any_nil` - any [] p = false -- `all_append` - all (xs ++ ys) p = (all xs p && all ys p) - -### Replicate -- `replicate_zero` - replicate 0 x = [] -- `length_replicate` - length (replicate n x) = n - -**Total: 48 theorems** - ---- - -## Summary Statistics - -| File | Theorems | Definitions | Total | Lines | -|------|----------|-------------|-------|-------| -| Basic.lean | 21 | 3 | 24 | 225 | -| Propositional.lean | 27 | 0 | 27 | 319 | -| Nat.lean | 46 | 2 | 48 | 377 | -| List.lean | 48 | 0 | 48 | 437 | -| **TOTAL** | **142** | **5** | **147** | **1358** | - -## Coverage Analysis - -### Proof Techniques -- **Direct proof**: 65% -- **Induction**: 20% -- **Case analysis**: 10% -- **Classical reasoning**: 5% - -### Tactics Used -- `intro`, `exact`, `apply`: Universal -- `induction`, `cases`: Structural proofs -- `rw`, `rfl`, `simp`: Rewriting -- `omega`, `ring`: Automation -- `by_cases`, `exfalso`: Classical - -### Mathematical Areas -- **Logic**: Propositional, predicate, classical -- **Arithmetic**: Natural numbers, basic operations -- **Algebra**: Associativity, commutativity, distributivity -- **Data structures**: Lists, functional programming -- **Number theory**: Even/odd, GCD, divisibility - -## Integration with ECHIDNA - -### Test Coverage -- **Tier 1**: Basic logic and arithmetic (100%) -- **Tier 2**: Induction and data structures (100%) -- **Tier 3**: Advanced proofs (100% - all sorry instances resolved) - -### Performance Benchmarks -- Small proofs (<10 lines): ~0.1s -- Medium proofs (10-30 lines): ~0.5s -- Large proofs (>30 lines): ~2s - -### Aspect Tags -```rust -// Example aspect tagging for ECHIDNA -Basic.lean: ["logic.foundation", "proof.intro", "curry-howard"] -Propositional.lean: ["logic.classical", "proof.contradiction", "de-morgan"] -Nat.lean: ["arithmetic.nat", "induction.nat", "number-theory"] -List.lean: ["data.list", "functional.map-fold", "induction.structural"] -``` - ---- - -**Generated**: 2025-11-22 -**Verified**: Lean 4.13.0 -**Status**: Production Ready diff --git a/proofs/pvs/README.adoc b/proofs/pvs/README.adoc new file mode 100644 index 00000000..1b539a62 --- /dev/null +++ b/proofs/pvs/README.adoc @@ -0,0 +1,158 @@ +== PVS Example Proofs for ECHIDNA + +This directory contains example PVS specifications demonstrating the +ECHIDNA PVS backend capabilities. + +=== Files + +==== 1. `+list_theory.pvs+` + +Parametric list theory with append and length. + +*Theorems Proved:* - `+append_nil_right+`: Appending empty list is +identity - `+append_associative+`: Append is associative - +`+length_append+`: Length distributes over append + +*Key Concepts:* - Parametric theories (`+[T: TYPE]+`) - Datatype +definitions - Recursive functions with MEASURE clauses - CASES +expressions + +==== 2. `+arithmetic.pvs+` + +Arithmetic properties and recursive functions. + +*Theorems Proved:* - Basic arithmetic properties (commutativity, +associativity, distributivity) - `+factorial_positive+`: Factorial is +always positive - `+factorial_increasing+`: Factorial is monotonic - +`+fib_positive+`: Fibonacci numbers are positive + +*Key Concepts:* - Natural number arithmetic - RECURSIVE functions with +MEASURE - IF-THEN-ELSE vs CASES - Dependent types with TCCs + +==== 3. `+binary_search.pvs+` + +Binary search algorithm specification and correctness. + +*Theorems Proved:* - `+binary_search_correct+`: Algorithm finds element +if present + +*Key Concepts:* - Array theory (IMPORTING arrays@array_ops) - +Preconditions with sorted? - LET bindings - Postconditions with +implications - Algorithm verification + +==== 4. `+set_theory.pvs+` + +Set operations using higher-order predicates. + +*Theorems Proved:* - De Morgan’s laws (2 theorems) - Set algebra +(commutativity, associativity) - Subset properties (reflexive, +transitive) + +*Key Concepts:* - Higher-order types (`+set: TYPE = [T -> bool]+`) - +Lambda expressions - First-class predicates - Extensionality + +==== 5. `+sorting.pvs+` + +Insertion sort with correctness and permutation preservation. + +*Theorems Proved:* - `+insert_sorted+`: Insert maintains sortedness - +`+insertion_sort_sorted+`: Sort produces sorted output - +`+insert_preserves_occurrences+`: Permutation preservation + +*Key Concepts:* - Parametric theory with ordering relation - +total_order? predicate - Algorithm correctness - Counting occurrences - +Property preservation + +=== Running These Proofs + +==== With PVS Installed + +[source,bash] +---- +# Start PVS Emacs interface +pvs + +# Or use command-line +pvs -batch -l list_theory.pvs + +# Type check theory +M-x typecheck-file + +# Prove theorem +M-x prove +---- + +==== With ECHIDNA + +[source,bash] +---- +# Parse and verify +echidna verify --prover pvs list_theory.pvs + +# Check type correctness conditions (TCCs) +echidna check-tccs --prover pvs arithmetic.pvs +---- + +=== PVS Syntax Cheat Sheet + +==== Theory Structure + +[source,pvs] +---- +theory_name: THEORY +BEGIN + % Definitions and theorems +END theory_name +---- + +==== Parametric Theory + +[source,pvs] +---- +theory_name[T: TYPE, R: (relation?[T])]: THEORY +BEGIN + ... +END theory_name +---- + +==== Function Definition + +[source,pvs] +---- +function_name(x: type1, y: type2): RECURSIVE return_type = + body +MEASURE measure_expression +---- + +==== Theorem Statement + +[source,pvs] +---- +theorem_name: THEOREM + FORALL (x: type): precondition IMPLIES conclusion +---- + +==== Common Proof Commands + +* `+(grind)+` - Powerful automated proof +* `+(split)+` - Case split +* `+(induct "var")+` - Induction +* `+(expand "function")+` - Expand definition +* `+(lemma "name")+` - Apply lemma +* `+(skolem!)+` - Skolemize quantifiers + +==== Type Checking + +* TCCs (Type Correctness Conditions) auto-generated for: +** Array bounds +** Division by zero +** Recursive function termination +** Subtype constraints + +=== Resources + +* http://pvs.csl.sri.com/[PVS Specification and Verification System] +* http://pvs.csl.sri.com/doc/pvs-language-reference.pdf[PVS Language +Reference] +* http://pvs.csl.sri.com/doc/pvs-prover-guide.pdf[PVS Prover Guide] +* http://shemesh.larc.nasa.gov/fm/pvs/tutorial/[PVS Tutorial] diff --git a/proofs/pvs/README.md b/proofs/pvs/README.md deleted file mode 100644 index c49299de..00000000 --- a/proofs/pvs/README.md +++ /dev/null @@ -1,157 +0,0 @@ -# PVS Example Proofs for ECHIDNA - -This directory contains example PVS specifications demonstrating the ECHIDNA PVS backend capabilities. - -## Files - -### 1. `list_theory.pvs` -Parametric list theory with append and length. - -**Theorems Proved:** -- `append_nil_right`: Appending empty list is identity -- `append_associative`: Append is associative -- `length_append`: Length distributes over append - -**Key Concepts:** -- Parametric theories (`[T: TYPE]`) -- Datatype definitions -- Recursive functions with MEASURE clauses -- CASES expressions - -### 2. `arithmetic.pvs` -Arithmetic properties and recursive functions. - -**Theorems Proved:** -- Basic arithmetic properties (commutativity, associativity, distributivity) -- `factorial_positive`: Factorial is always positive -- `factorial_increasing`: Factorial is monotonic -- `fib_positive`: Fibonacci numbers are positive - -**Key Concepts:** -- Natural number arithmetic -- RECURSIVE functions with MEASURE -- IF-THEN-ELSE vs CASES -- Dependent types with TCCs - -### 3. `binary_search.pvs` -Binary search algorithm specification and correctness. - -**Theorems Proved:** -- `binary_search_correct`: Algorithm finds element if present - -**Key Concepts:** -- Array theory (IMPORTING arrays@array_ops) -- Preconditions with sorted? -- LET bindings -- Postconditions with implications -- Algorithm verification - -### 4. `set_theory.pvs` -Set operations using higher-order predicates. - -**Theorems Proved:** -- De Morgan's laws (2 theorems) -- Set algebra (commutativity, associativity) -- Subset properties (reflexive, transitive) - -**Key Concepts:** -- Higher-order types (`set: TYPE = [T -> bool]`) -- Lambda expressions -- First-class predicates -- Extensionality - -### 5. `sorting.pvs` -Insertion sort with correctness and permutation preservation. - -**Theorems Proved:** -- `insert_sorted`: Insert maintains sortedness -- `insertion_sort_sorted`: Sort produces sorted output -- `insert_preserves_occurrences`: Permutation preservation - -**Key Concepts:** -- Parametric theory with ordering relation -- total_order? predicate -- Algorithm correctness -- Counting occurrences -- Property preservation - -## Running These Proofs - -### With PVS Installed - -```bash -# Start PVS Emacs interface -pvs - -# Or use command-line -pvs -batch -l list_theory.pvs - -# Type check theory -M-x typecheck-file - -# Prove theorem -M-x prove -``` - -### With ECHIDNA - -```bash -# Parse and verify -echidna verify --prover pvs list_theory.pvs - -# Check type correctness conditions (TCCs) -echidna check-tccs --prover pvs arithmetic.pvs -``` - -## PVS Syntax Cheat Sheet - -### Theory Structure -```pvs -theory_name: THEORY -BEGIN - % Definitions and theorems -END theory_name -``` - -### Parametric Theory -```pvs -theory_name[T: TYPE, R: (relation?[T])]: THEORY -BEGIN - ... -END theory_name -``` - -### Function Definition -```pvs -function_name(x: type1, y: type2): RECURSIVE return_type = - body -MEASURE measure_expression -``` - -### Theorem Statement -```pvs -theorem_name: THEOREM - FORALL (x: type): precondition IMPLIES conclusion -``` - -### Common Proof Commands -- `(grind)` - Powerful automated proof -- `(split)` - Case split -- `(induct "var")` - Induction -- `(expand "function")` - Expand definition -- `(lemma "name")` - Apply lemma -- `(skolem!)` - Skolemize quantifiers - -### Type Checking -- TCCs (Type Correctness Conditions) auto-generated for: - - Array bounds - - Division by zero - - Recursive function termination - - Subtype constraints - -## Resources - -- [PVS Specification and Verification System](http://pvs.csl.sri.com/) -- [PVS Language Reference](http://pvs.csl.sri.com/doc/pvs-language-reference.pdf) -- [PVS Prover Guide](http://pvs.csl.sri.com/doc/pvs-prover-guide.pdf) -- [PVS Tutorial](http://shemesh.larc.nasa.gov/fm/pvs/tutorial/) diff --git a/reports/panic-attack-chunks/SUMMARY.adoc b/reports/panic-attack-chunks/SUMMARY.adoc new file mode 100644 index 00000000..4d248413 --- /dev/null +++ b/reports/panic-attack-chunks/SUMMARY.adoc @@ -0,0 +1,83 @@ +== Echidna Chunked panic-attack Sweep — 2026-04-25 + +Single full-repo `+panic-attack assail .+` had timed out at 180s. This +sweep splits the tree into 14 per-subdir chunks, each completing in < +30s for a combined wall time well under the prior single-run cap. + +=== Per-chunk totals (severity counts) + +[width="99%",cols="58%,>15%,>7%,>11%,>9%",options="header",] +|=== +|Chunk |Critical |High |Medium |Total +|`+src/rust+` |26 |6 |2 |34 +|`+src/interfaces+` |0 |6 |0 |6 +|`+src/zig+` |0 |1 |0 |1 +|`+src/zig_ffi+` |0 |1 |0 |1 +|`+src/abi+` |1 |0 |0 |1 +|`+crates/echidna-mcp+` |0 |1 |0 |1 +|`+crates/echidna-core+` |0 |0 |0 |0 +|`+crates/echidna-wire+` |0 |0 |0 |0 +|`+crates/typed_wasm+` |0 |0 |0 |0 +|`+src/julia+` |0 |0 |0 |0 +|`+src/idris+` |0 |0 |0 |0 +|`+src/ada+` |0 |0 |0 |0 +|`+src/affinescript+` |0 |0 |0 |0 +|`+src/ui+` |0 |0 |0 |0 +|`+src/chapel+` |– |– |– |– +|*Total* |*27* |*15* |*2* |*44* +|=== + +Note: `+src/chapel+` returned "`Could not detect language`" — +panic-attack has no Chapel detector. Track separately. + +=== Classification (per `+feedback_panic_attack_*+` memory rules) + +==== Structural / expected (do not chase counts) + +* *26× Critical UnboundedAllocation in `+src/rust/provers/*.rs+`* — one +per prover backend, file-level aggregation of `+Vec::new()+` / +`+String+` allocations across 600+ LoC parsers. This is the +PanicPath-is-file-level pattern: one finding per file, not one per site. +The 26 backends with the highest Vec/parse density flag here. +Investigation required per backend before any structural rewrite — most +allocations are in error-message construction or proof-script parsing, +both bounded in practice by `+ProverConfig::timeout+`. +* *6× High UnsafeCode in `+src/interfaces/*/ffi_wrapper.rs+`* — two per +FFI wrapper × three interfaces (rest, grpc, graphql). All calls into the +Zig FFI shim’s `+extern "C"+` surface plus `+CStr::from_ptr+`. These +cannot be eliminated without dropping the FFI boundary; per +`+feedback_panic_attack_unsafe_blocks_meaning.md+` this is the +legitimate-FFI-try/catch class, not the banned partial-cast class. +* *2× High UnsafeFFI in zig bridges* (`+chapel_bridge.zig+`, +`+ffi/axiom_spark_bridge.zig+`) — required for cross-language FFI. +* *1× Critical ProofDrift in `+src/abi/echidnaabi.ipkg+`* — flagged per +`+feedback_panic_attack_proofdrift_parameter_pattern.md+`. The `+.ipkg+` +is an Idris2 package manifest; the rule’s "`free Parameter unless inside +designated Section Carriers`" pattern doesn’t quite fit a config file. +Worth re-reading the rule’s scope; likely a detector false-positive on +`+.ipkg+` files. +* *2× High UnsafeCode in `+src/rust/proof_search.rs+`* — Chapel FFI +boundary; behind `+--features chapel+` cargo feature. Same class as the +interface FFI wrappers. +* *3× High UnsafeCode + 1× High ResourceLeak in `+src/rust/ffi/+`* — +same FFI-boundary class. + +==== Actionable today (low cost, structural fixes) + +* *1× High SupplyChain `+crates/echidna-mcp/Cargo.toml+`* — needs +inspection. May be an unpinned dep version or a permissive feature set. +* *1× Medium PanicPath `+src/rust/provers/z3.rs+`* — single panic site +in a hot prover. Easy to convert to anyhow::Result. +* *1× Medium InsecureProtocol `+src/rust/provers/uppaal.rs+`* — probably +an `+http://+` URL in a comment or test fixture; quick audit. + +=== Conclusion + +Chunked sweep replaces the 180s timeout with 14 fast per-subdir runs. Of +44 findings: ~41 are structural / FFI / file-level aggregation classes +that the memory rules say not to chase by count, and 3 are genuinely +actionable in a follow-up (1 SupplyChain, 1 PanicPath, 1 +InsecureProtocol). No new criticals discovered — all in the expected +places (FFI surfaces and prover wrappers). + +Reports retained at `+reports/panic-attack-chunks/*.json+`. diff --git a/reports/panic-attack-chunks/SUMMARY.md b/reports/panic-attack-chunks/SUMMARY.md deleted file mode 100644 index 76d14021..00000000 --- a/reports/panic-attack-chunks/SUMMARY.md +++ /dev/null @@ -1,90 +0,0 @@ -# Echidna Chunked panic-attack Sweep — 2026-04-25 - -Single full-repo `panic-attack assail .` had timed out at 180s. -This sweep splits the tree into 14 per-subdir chunks, each completing -in < 30s for a combined wall time well under the prior single-run cap. - -## Per-chunk totals (severity counts) - -| Chunk | Critical | High | Medium | Total | -| ------------------------------ | -------: | ---: | -----: | ----: | -| `src/rust` | 26 | 6 | 2 | 34 | -| `src/interfaces` | 0 | 6 | 0 | 6 | -| `src/zig` | 0 | 1 | 0 | 1 | -| `src/zig_ffi` | 0 | 1 | 0 | 1 | -| `src/abi` | 1 | 0 | 0 | 1 | -| `crates/echidna-mcp` | 0 | 1 | 0 | 1 | -| `crates/echidna-core` | 0 | 0 | 0 | 0 | -| `crates/echidna-wire` | 0 | 0 | 0 | 0 | -| `crates/typed_wasm` | 0 | 0 | 0 | 0 | -| `src/julia` | 0 | 0 | 0 | 0 | -| `src/idris` | 0 | 0 | 0 | 0 | -| `src/ada` | 0 | 0 | 0 | 0 | -| `src/affinescript` | 0 | 0 | 0 | 0 | -| `src/ui` | 0 | 0 | 0 | 0 | -| `src/chapel` | – | – | – | – | -| **Total** | **27** | **15** | **2** | **44** | - -Note: `src/chapel` returned "Could not detect language" — panic-attack -has no Chapel detector. Track separately. - -## Classification (per `feedback_panic_attack_*` memory rules) - -### Structural / expected (do not chase counts) - -- **26× Critical UnboundedAllocation in `src/rust/provers/*.rs`** — - one per prover backend, file-level aggregation of `Vec::new()` / - `String` allocations across 600+ LoC parsers. This is the - PanicPath-is-file-level pattern: one finding per file, not one per - site. The 26 backends with the highest Vec/parse density flag here. - Investigation required per backend before any structural rewrite — - most allocations are in error-message construction or proof-script - parsing, both bounded in practice by `ProverConfig::timeout`. - -- **6× High UnsafeCode in `src/interfaces/*/ffi_wrapper.rs`** — two - per FFI wrapper × three interfaces (rest, grpc, graphql). All - calls into the Zig FFI shim's `extern "C"` surface plus `CStr::from_ptr`. - These cannot be eliminated without dropping the FFI boundary; per - `feedback_panic_attack_unsafe_blocks_meaning.md` this is the - legitimate-FFI-try/catch class, not the banned partial-cast class. - -- **2× High UnsafeFFI in zig bridges** (`chapel_bridge.zig`, - `ffi/axiom_spark_bridge.zig`) — required for cross-language FFI. - -- **1× Critical ProofDrift in `src/abi/echidnaabi.ipkg`** — flagged - per `feedback_panic_attack_proofdrift_parameter_pattern.md`. The - `.ipkg` is an Idris2 package manifest; the rule's "free Parameter - unless inside designated Section Carriers" pattern doesn't quite - fit a config file. Worth re-reading the rule's scope; likely a - detector false-positive on `.ipkg` files. - -- **2× High UnsafeCode in `src/rust/proof_search.rs`** — Chapel FFI - boundary; behind `--features chapel` cargo feature. Same class as - the interface FFI wrappers. - -- **3× High UnsafeCode + 1× High ResourceLeak in `src/rust/ffi/`** — - same FFI-boundary class. - -### Actionable today (low cost, structural fixes) - -- **1× High SupplyChain `crates/echidna-mcp/Cargo.toml`** — needs - inspection. May be an unpinned dep version or a permissive feature - set. - -- **1× Medium PanicPath `src/rust/provers/z3.rs`** — single panic site - in a hot prover. Easy to convert to anyhow::Result. - -- **1× Medium InsecureProtocol `src/rust/provers/uppaal.rs`** — - probably an `http://` URL in a comment or test fixture; quick - audit. - -## Conclusion - -Chunked sweep replaces the 180s timeout with 14 fast per-subdir runs. -Of 44 findings: ~41 are structural / FFI / file-level aggregation -classes that the memory rules say not to chase by count, and 3 are -genuinely actionable in a follow-up (1 SupplyChain, 1 PanicPath, -1 InsecureProtocol). No new criticals discovered — all in the -expected places (FFI surfaces and prover wrappers). - -Reports retained at `reports/panic-attack-chunks/*.json`. diff --git a/schemas/VERSIONING.adoc b/schemas/VERSIONING.adoc new file mode 100644 index 00000000..abf5e6ba --- /dev/null +++ b/schemas/VERSIONING.adoc @@ -0,0 +1,141 @@ +== Cap’n Proto Schema Versioning Policy + +Schema file: `+schemas/echidna.capnp+` Schema ID: +`+@0xd3b45f8ae1c79012+` (immutable — generated once, never changed) + +=== Wire Compatibility Guarantee + +Cap’n Proto’s wire format is *forward- and backward-compatible by +default*, but only if the following rule is obeyed without exception: + +____ +*Add fields at the end of a struct only. Never reorder, rename, or +remove existing fields. Never change an existing field’s type or ordinal +number.* +____ + +Each field carries an explicit ordinal (`+@N+`). The ordinal is its wire +identity. Renaming a field in the `+.capnp+` source is safe (it only +changes the generated symbol name). Changing `+@N+` or the field type is +a *breaking change*. + +=== Non-Breaking Changes (safe to make freely) + +[width="100%",cols="34%,66%",options="header",] +|=== +|Change |Why it is safe +|Add a new field at the end of a struct (`+@N+` where N > current max) +|Older readers ignore unknown fields; older writers produce zero for +missing fields + +|Add a new struct or enum anywhere in the file |Unused by older code + +|Add a new enum variant at the end |Older code sees it as an unknown +discriminant + +|Rename a field or type (source only) |Ordinals and wire layout +unchanged + +|Change a default value in the schema |Wire encoding unaffected; +generated code picks up the new default + +|Add a new `+annotation+` |Not encoded on the wire +|=== + +=== Breaking Changes (require a new struct name or a bumped `+schemaVersion+` field) + +[cols=",",options="header",] +|=== +|Change |Why it breaks +|Remove or reorder a field |Changes the ordinal-to-meaning mapping +|Change a field’s type |Existing wire bytes are misinterpreted +|Change a field’s ordinal number |Direct wire breakage +|Remove an enum variant |Existing discriminant values become invalid +|Reorder enum variants |Discriminant values shift +|=== + +If a breaking change is truly necessary, *create a new top-level struct* +(e.g. `+GnnRankRequestV2+`) and increment the `+schemaVersion+` content +field. Do not alter `+@0xd3b45f8ae1c79012+`. + +=== Content Versioning (`+schemaVersion+` field) + +The schema ID identifies the file-level wire format and is fixed. For +application-level content versioning, add a `+schemaVersion @N :UInt32+` +field to any message that needs it (default `+1+`). Consumers check this +field and reject or transform messages from unexpected versions. Current +L1 messages omit it — add when the first breaking content change is +needed. + +=== Adding a New Message Type + +[arabic] +. Append the new struct or enum at the *end* of `+echidna.capnp+`. +. Add a section-header comment (see existing style). +. Run `+just capnp-gen+` to regenerate all language bindings. +. Update `+src/abi/EchidnaABI/CapnSchemas.idr+` (see §Idris2 below). +. If the new type is part of a breaking redesign, bump `+schemaVersion+` +in the affected request/response structs rather than changing the schema +ID. + +=== Regenerating Bindings (`+just capnp-gen+`) + +After every schema change — including non-breaking additions — run: + +[source,sh] +---- +just capnp-gen +---- + +This regenerates `+src/rust/ipc/echidna_capnp.rs+` (and future Zig/Julia +targets as they are wired into the recipe). *Commit generated bindings.* +They are checked in so that consumers without a local `+capnp+` +installation can build. A CI check (`+just capnp-gen-check+`) verifies +committed bindings match the schema; failing it is a merge blocker. + +=== Multi-Language Consumers + +[width="100%",cols="28%,50%,22%",options="header",] +|=== +|Language |Binding mechanism |Status +|*Rust* |`+capnpc-rust+` (generated `+echidna_capnp.rs+`) |L1 wave 1 +target + +|*Idris2* |`+src/abi/EchidnaABI/CapnSchemas.idr+` — type mirror + proofs +|Present; update alongside schema + +|*Julia* |Zig C-ABI shim, buffer-oriented (RATIFIED 2026-05-18; +`+CapnProto.jl+` rejected) |`+src/julia/ipc.jl+` stub present; impl +gated on L3 hand-off + +|*AffineScript* |`+bindings/affinescript/echidna_capnp.affine+` → +typed-wasm (UI path; AffineScript banned estate-wide) |Planned L1 wave 1 + +|*Zig* |C-ABI bridge in `+ffi/zig/src/capnp_bridge.zig+` — also the +codec the Julia shim calls |Stub present; real impl in L1 wave 1 +|=== + +=== Idris2 ABI Proofs (`+src/abi/EchidnaABI/CapnSchemas.idr+`) + +`+CapnSchemas.idr+` mirrors enum cardinalities and struct field counts +as Idris2 types and proves bounded-representation invariants. When +adding a field or enum variant: + +[arabic] +. Add the corresponding constructor to the Idris2 mirror type. +. Update the `+allXxx+` Vect witness and its +`+xxxCountCorrect : length … = n+` proof. +. Re-run `+%search+` on the `+xxxBounded : LTE n 256+` proof (it will +still hold). +. Zero `+believe_me+` is a hard invariant — all proofs must be +constructive. + +=== Quick Reference + +.... +Safe: add field at end, add struct, add enum variant at end, rename +Unsafe: remove, reorder, change type, change ordinal +If breaking: new struct name + increment schemaVersion field +After any change: just capnp-gen && commit generated bindings +Update CapnSchemas.idr to match +.... diff --git a/schemas/VERSIONING.md b/schemas/VERSIONING.md deleted file mode 100644 index 4984f82c..00000000 --- a/schemas/VERSIONING.md +++ /dev/null @@ -1,108 +0,0 @@ - - -# Cap'n Proto Schema Versioning Policy - -Schema file: `schemas/echidna.capnp` -Schema ID: `@0xd3b45f8ae1c79012` (immutable — generated once, never changed) - -## Wire Compatibility Guarantee - -Cap'n Proto's wire format is **forward- and backward-compatible by default**, -but only if the following rule is obeyed without exception: - -> **Add fields at the end of a struct only. Never reorder, rename, or remove -> existing fields. Never change an existing field's type or ordinal number.** - -Each field carries an explicit ordinal (`@N`). The ordinal is its wire identity. -Renaming a field in the `.capnp` source is safe (it only changes the generated -symbol name). Changing `@N` or the field type is a **breaking change**. - -## Non-Breaking Changes (safe to make freely) - -| Change | Why it is safe | -|--------|----------------| -| Add a new field at the end of a struct (`@N` where N > current max) | Older readers ignore unknown fields; older writers produce zero for missing fields | -| Add a new struct or enum anywhere in the file | Unused by older code | -| Add a new enum variant at the end | Older code sees it as an unknown discriminant | -| Rename a field or type (source only) | Ordinals and wire layout unchanged | -| Change a default value in the schema | Wire encoding unaffected; generated code picks up the new default | -| Add a new `annotation` | Not encoded on the wire | - -## Breaking Changes (require a new struct name or a bumped `schemaVersion` field) - -| Change | Why it breaks | -|--------|---------------| -| Remove or reorder a field | Changes the ordinal-to-meaning mapping | -| Change a field's type | Existing wire bytes are misinterpreted | -| Change a field's ordinal number | Direct wire breakage | -| Remove an enum variant | Existing discriminant values become invalid | -| Reorder enum variants | Discriminant values shift | - -If a breaking change is truly necessary, **create a new top-level struct** -(e.g. `GnnRankRequestV2`) and increment the `schemaVersion` content field. -Do not alter `@0xd3b45f8ae1c79012`. - -## Content Versioning (`schemaVersion` field) - -The schema ID identifies the file-level wire format and is fixed. For -application-level content versioning, add a `schemaVersion @N :UInt32` -field to any message that needs it (default `1`). Consumers check this field -and reject or transform messages from unexpected versions. Current L1 messages -omit it — add when the first breaking content change is needed. - -## Adding a New Message Type - -1. Append the new struct or enum at the **end** of `echidna.capnp`. -2. Add a section-header comment (see existing style). -3. Run `just capnp-gen` to regenerate all language bindings. -4. Update `src/abi/EchidnaABI/CapnSchemas.idr` (see §Idris2 below). -5. If the new type is part of a breaking redesign, bump `schemaVersion` in - the affected request/response structs rather than changing the schema ID. - -## Regenerating Bindings (`just capnp-gen`) - -After every schema change — including non-breaking additions — run: - -```sh -just capnp-gen -``` - -This regenerates `src/rust/ipc/echidna_capnp.rs` (and future Zig/Julia targets -as they are wired into the recipe). **Commit generated bindings.** They are -checked in so that consumers without a local `capnp` installation can build. -A CI check (`just capnp-gen-check`) verifies committed bindings match the -schema; failing it is a merge blocker. - -## Multi-Language Consumers - -| Language | Binding mechanism | Status | -|----------|------------------|--------| -| **Rust** | `capnpc-rust` (generated `echidna_capnp.rs`) | L1 wave 1 target | -| **Idris2** | `src/abi/EchidnaABI/CapnSchemas.idr` — type mirror + proofs | Present; update alongside schema | -| **Julia** | Zig C-ABI shim, buffer-oriented (RATIFIED 2026-05-18; `CapnProto.jl` rejected) | `src/julia/ipc.jl` stub present; impl gated on L3 hand-off | -| **AffineScript** | `bindings/affinescript/echidna_capnp.affine` → typed-wasm (UI path; AffineScript banned estate-wide) | Planned L1 wave 1 | -| **Zig** | C-ABI bridge in `ffi/zig/src/capnp_bridge.zig` — also the codec the Julia shim calls | Stub present; real impl in L1 wave 1 | - -## Idris2 ABI Proofs (`src/abi/EchidnaABI/CapnSchemas.idr`) - -`CapnSchemas.idr` mirrors enum cardinalities and struct field counts as Idris2 -types and proves bounded-representation invariants. When adding a field or -enum variant: - -1. Add the corresponding constructor to the Idris2 mirror type. -2. Update the `allXxx` Vect witness and its `xxxCountCorrect : length … = n` proof. -3. Re-run `%search` on the `xxxBounded : LTE n 256` proof (it will still hold). -4. Zero `believe_me` is a hard invariant — all proofs must be constructive. - -## Quick Reference - -``` -Safe: add field at end, add struct, add enum variant at end, rename -Unsafe: remove, reorder, change type, change ordinal -If breaking: new struct name + increment schemaVersion field -After any change: just capnp-gen && commit generated bindings -Update CapnSchemas.idr to match -``` diff --git a/site/docs/api/core.adoc b/site/docs/api/core.adoc new file mode 100644 index 00000000..00076571 --- /dev/null +++ b/site/docs/api/core.adoc @@ -0,0 +1,188 @@ +== Core Server API Reference + +This is the API of the `+echidna server+` binary — the service hosted at +`+https://api.nesy-prover.dev+` and the one you get from the published +container image. Self-hosted instances serve the same routes over plain +HTTP on the port given to `+--port+` (default 8081); the public instance +is the same service behind a TLS-terminating proxy. + +Every route below is documented from `+src/rust/server.rs+`. There is no +authentication; the public instance is rate-limited and caps request +bodies, so treat it as an evaluation endpoint rather than a backend for +production workloads. + +Prover names are the `+ProverKind+` variant names — `+Z3+`, `+CVC5+`, +`+Coq+`, `+Lean+`, `+Isabelle+`, `+Agda+`, `+Metamath+`, `+HOLLight+`, +and so on. Use `+/api/provers+` for the list your instance actually +exposes. + +=== Service + +==== Health + +.... +GET /api/health +.... + +[source,json] +---- +{ "status": "ok", "version": "2.3.0" } +---- + +`+GET /api/diagnostics/health+` returns a richer report covering solver +availability and pipeline state. `+GET /.well-known/groove+` returns the +service’s Groove capability manifest. + +==== List provers + +.... +GET /api/provers +.... + +[source,json] +---- +{ "provers": [ { "name": "Z3", "tier": 1, "complexity": 2 } ] } +---- + +=== Proving and verification + +==== Verify a proof or SMT script + +.... +POST /api/verify +.... + +Request: + +[source,json] +---- +{ "prover": "Z3", "content": "(assert (forall ((x Int)) (= (+ x 0) x)))(check-sat)" } +---- + +Response — `+outcome+` is the primary field (one of `+PROVED+`, +`+NO_PROOF_FOUND+`, `+INVALID_INPUT+`, `+UNSUPPORTED_FEATURE+`, +`+TIMEOUT+`, `+INCONSISTENT_PREMISES+`, `+PROVER_ERROR+`, +`+SYSTEM_ERROR+`); `+valid+` is a backward-compatible boolean that is +true exactly when the outcome is `+PROVED+`: + +[source,json] +---- +{ + "valid": true, + "outcome": "PROVED", + "goals_remaining": 0, + "tactics_used": 0 +} +---- + +`+POST /api/verify_parallel+` takes the same request shape and +dispatches across the portfolio. + +==== Verify with raw prover output + +.... +POST /api/verify_raw +.... + +Same request shape as `+/api/verify+`. The response exposes the backend +process result directly, which is what you want when debugging a script: + +[source,json] +---- +{ "valid": true, "exit_code": 0, "stdout": "unsat\n", "stderr": "", "message": "" } +---- + +==== Prove a goal + +.... +POST /api/prove +.... + +[source,json] +---- +{ "prover": "Coq", "content": "Lemma t : forall n, n + 0 = n.", "timeout": 30, "neural": false } +---- + +[source,json] +---- +{ "success": true, "goals": 0, "message": "" } +---- + +`+timeout+` is in seconds and optional; `+neural+` optionally enables +neural premise selection. + +==== Suggest tactics + +.... +POST /api/suggest +.... + +[source,json] +---- +{ "prover": "Coq", "content": "forall n : nat, n + 0 = n", "limit": 5 } +---- + +[source,json] +---- +{ "suggestions": ["induction n", "simpl", "reflexivity"] } +---- + +Suggestions come from the Julia ML service when it is reachable and fall +back to the prover’s built-in heuristics otherwise, so this route works +on instances with no ML sidecar. + +==== Search + +.... +GET /api/search?q= +.... + +The `+q+` parameter is required; a request without it returns 400. + +[source,json] +---- +{ "results": ["Nat.add_0_r"], "count": 1 } +---- + +=== Interactive sessions + +Sessions hold proof state in server memory across tactic applications. + +==== Create a session + +.... +POST /api/session/create +.... + +[source,json] +---- +{ "prover": "Coq" } +---- + +[source,json] +---- +{ "session_id": "b3f1c2de-..." } +---- + +==== Inspect and drive a session + +.... +GET /api/session/{id}/state +POST /api/session/{id}/apply +GET /api/session/{id}/tree +.... + +`+state+` returns +`+{ "goals": 1, "complete": false, "tactics_applied": 0 }+`. `+apply+` +takes `+{ "tactic": "induction n" }+` and reports +`+{ "success": true, "complete": false, "goals_remaining": 2, ... }+`. +`+tree+` returns the proof tree built so far. + +=== Other routes + +`+POST /api/agent/plan+` performs Pareto-ranked prover selection from +goal aspect tags. `+GET /api/aspect-tags+` lists the tag vocabulary. +`+POST /api/tactics/suggest+` and `+GET /api/theorems/search+` back the +bundled UI. + +link:/docs/index.html[Documentation index] diff --git a/site/docs/api/core.md b/site/docs/api/core.md deleted file mode 100644 index 58e86e52..00000000 --- a/site/docs/api/core.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Core Server API Reference -description: HTTP API of the echidna server binary, as hosted at api.nesy-prover.dev -date: 2026-07-28 -template: default ---- - -# Core Server API Reference - -This is the API of the `echidna server` binary — the service hosted at -`https://api.nesy-prover.dev` and the one you get from the published -container image. Self-hosted instances serve the same routes over plain -HTTP on the port given to `--port` (default 8081); the public instance -is the same service behind a TLS-terminating proxy. - -Every route below is documented from `src/rust/server.rs`. There is no -authentication; the public instance is rate-limited and caps request -bodies, so treat it as an evaluation endpoint rather than a backend for -production workloads. - -Prover names are the `ProverKind` variant names — `Z3`, `CVC5`, `Coq`, -`Lean`, `Isabelle`, `Agda`, `Metamath`, `HOLLight`, and so on. Use -`/api/provers` for the list your instance actually exposes. - -## Service - -### Health - -``` -GET /api/health -``` - -```json -{ "status": "ok", "version": "2.3.0" } -``` - -`GET /api/diagnostics/health` returns a richer report covering solver -availability and pipeline state. `GET /.well-known/groove` returns the -service's Groove capability manifest. - -### List provers - -``` -GET /api/provers -``` - -```json -{ "provers": [ { "name": "Z3", "tier": 1, "complexity": 2 } ] } -``` - -## Proving and verification - -### Verify a proof or SMT script - -``` -POST /api/verify -``` - -Request: - -```json -{ "prover": "Z3", "content": "(assert (forall ((x Int)) (= (+ x 0) x)))(check-sat)" } -``` - -Response — `outcome` is the primary field (one of `PROVED`, -`NO_PROOF_FOUND`, `INVALID_INPUT`, `UNSUPPORTED_FEATURE`, `TIMEOUT`, -`INCONSISTENT_PREMISES`, `PROVER_ERROR`, `SYSTEM_ERROR`); `valid` is a -backward-compatible boolean that is true exactly when the outcome is -`PROVED`: - -```json -{ - "valid": true, - "outcome": "PROVED", - "goals_remaining": 0, - "tactics_used": 0 -} -``` - -`POST /api/verify_parallel` takes the same request shape and dispatches -across the portfolio. - -### Verify with raw prover output - -``` -POST /api/verify_raw -``` - -Same request shape as `/api/verify`. The response exposes the backend -process result directly, which is what you want when debugging a script: - -```json -{ "valid": true, "exit_code": 0, "stdout": "unsat\n", "stderr": "", "message": "" } -``` - -### Prove a goal - -``` -POST /api/prove -``` - -```json -{ "prover": "Coq", "content": "Lemma t : forall n, n + 0 = n.", "timeout": 30, "neural": false } -``` - -```json -{ "success": true, "goals": 0, "message": "" } -``` - -`timeout` is in seconds and optional; `neural` optionally enables -neural premise selection. - -### Suggest tactics - -``` -POST /api/suggest -``` - -```json -{ "prover": "Coq", "content": "forall n : nat, n + 0 = n", "limit": 5 } -``` - -```json -{ "suggestions": ["induction n", "simpl", "reflexivity"] } -``` - -Suggestions come from the Julia ML service when it is reachable and -fall back to the prover's built-in heuristics otherwise, so this route -works on instances with no ML sidecar. - -### Search - -``` -GET /api/search?q= -``` - -The `q` parameter is required; a request without it returns 400. - -```json -{ "results": ["Nat.add_0_r"], "count": 1 } -``` - -## Interactive sessions - -Sessions hold proof state in server memory across tactic applications. - -### Create a session - -``` -POST /api/session/create -``` - -```json -{ "prover": "Coq" } -``` - -```json -{ "session_id": "b3f1c2de-..." } -``` - -### Inspect and drive a session - -``` -GET /api/session/{id}/state -POST /api/session/{id}/apply -GET /api/session/{id}/tree -``` - -`state` returns `{ "goals": 1, "complete": false, "tactics_applied": 0 }`. -`apply` takes `{ "tactic": "induction n" }` and reports -`{ "success": true, "complete": false, "goals_remaining": 2, ... }`. -`tree` returns the proof tree built so far. - -## Other routes - -`POST /api/agent/plan` performs Pareto-ranked prover selection from -goal aspect tags. `GET /api/aspect-tags` lists the tag vocabulary. -`POST /api/tactics/suggest` and `GET /api/theorems/search` back the -bundled UI. - -[Documentation index](/docs/index.html) diff --git a/site/docs/api/graphql.md b/site/docs/api/graphql.adoc similarity index 54% rename from site/docs/api/graphql.md rename to site/docs/api/graphql.adoc index 5a11aa7d..03735e91 100644 --- a/site/docs/api/graphql.md +++ b/site/docs/api/graphql.adoc @@ -1,24 +1,19 @@ ---- -title: GraphQL Interface Reference -date: 2026-07-28 -template: default ---- +== GraphQL Interface Reference -# GraphQL Interface Reference +The `+echidna-graphql+` binary is an optional self-hosted service. It +binds `+127.0.0.1:8081+` over plain HTTP and serves both the GraphQL +endpoint and the interactive playground at the server root — a `+POST+` +to `+/+` executes operations, a `+GET+` renders the playground. There is +a separate `+GET /health+`. -The `echidna-graphql` binary is an optional self-hosted service. It -binds `127.0.0.1:8081` over plain HTTP and serves both the GraphQL -endpoint and the interactive playground at the server root — a `POST` -to `/` executes operations, a `GET` renders the playground. There is a -separate `GET /health`. +Documented from `+src/interfaces/graphql/{main,schema}.rs+`. -Documented from `src/interfaces/graphql/{main,schema}.rs`. +=== Queries -## Queries +==== provers -### provers - -```graphql +[source,graphql] +---- query { provers { kind @@ -28,13 +23,14 @@ query { available } } -``` +---- -### proofState +==== proofState -Takes `id`, not a session identifier: +Takes `+id+`, not a session identifier: -```graphql +[source,graphql] +---- query { proofState(id: "proof-uuid") { id @@ -47,11 +43,12 @@ query { errorMessage } } -``` +---- -### listProofs +==== listProofs -```graphql +[source,graphql] +---- query { listProofs(limit: 20) { id @@ -60,13 +57,14 @@ query { goalsRemaining } } -``` +---- -### suggestTacticsByProofId +==== suggestTacticsByProofId The query form of tactic suggestion, keyed by an existing proof: -```graphql +[source,graphql] +---- query { suggestTacticsByProofId(proofId: "proof-uuid", limit: 5) { name @@ -75,23 +73,25 @@ query { confidence } } -``` +---- -### proverStatus +==== proverStatus -```graphql +[source,graphql] +---- query { proverStatus(prover: "Coq") { available } } -``` +---- -## Mutations +=== Mutations -### submitProof +==== submitProof -```graphql +[source,graphql] +---- mutation { submitProof(goal: "forall n : nat, n + 0 = n", prover: COQ) { id @@ -99,14 +99,15 @@ mutation { goalsRemaining } } -``` +---- -### applyTactic +==== applyTactic -`proofId`, `tactic`, and `args` are all required; pass an empty list -when the tactic takes no arguments: +`+proofId+`, `+tactic+`, and `+args+` are all required; pass an empty +list when the tactic takes no arguments: -```graphql +[source,graphql] +---- mutation { applyTactic(proofId: "proof-uuid", tactic: "induction", args: ["n"]) { id @@ -115,13 +116,14 @@ mutation { goalsRemaining } } -``` +---- -### verifyProof +==== verifyProof Verifies prover source directly, without a proof session: -```graphql +[source,graphql] +---- mutation { verifyProof(prover: "Z3", content: "(check-sat)") { status @@ -131,14 +133,15 @@ mutation { artifacts } } -``` +---- -### suggestTactics +==== suggestTactics -Tactic suggestion is a **mutation**, not a query, and takes a goal -state rather than a proof identifier: +Tactic suggestion is a *mutation*, not a query, and takes a goal state +rather than a proof identifier: -```graphql +[source,graphql] +---- mutation { suggestTactics(prover: "Coq", context: "", goalState: "forall n : nat, n + 0 = n") { tactic @@ -146,14 +149,15 @@ mutation { explanation } } -``` +---- -### cancelProof +==== cancelProof -```graphql +[source,graphql] +---- mutation { cancelProof(proofId: "proof-uuid") } -``` +---- -[Documentation index](/docs/index.html) +link:/docs/index.html[Documentation index] diff --git a/site/docs/api/grpc.md b/site/docs/api/grpc.adoc similarity index 66% rename from site/docs/api/grpc.md rename to site/docs/api/grpc.adoc index d90cbee8..e583ec3f 100644 --- a/site/docs/api/grpc.md +++ b/site/docs/api/grpc.adoc @@ -1,19 +1,14 @@ ---- -title: gRPC Interface Reference -date: 2026-07-28 -template: default ---- +== gRPC Interface Reference -# gRPC Interface Reference - -The `echidna-grpc` binary is an optional self-hosted service listening -on `localhost:50051`. The authoritative schema is -`src/interfaces/grpc/proto/echidna.proto`; everything below is taken +The `+echidna-grpc+` binary is an optional self-hosted service listening +on `+localhost:50051+`. The authoritative schema is +`+src/interfaces/grpc/proto/echidna.proto+`; everything below is taken from it. -## Service definition +=== Service definition -```protobuf +[source,protobuf] +---- service ProofService { rpc SubmitProof (SubmitProofRequest) returns (ProofResponse); rpc GetProofStatus (GetProofStatusRequest) returns (ProofResponse); @@ -23,16 +18,17 @@ service ProofService { rpc ListProvers (ListProversRequest) returns (ListProversResponse); rpc SuggestTactics (SuggestTacticsRequest) returns (SuggestTacticsResponse); } -``` +---- -## Methods +=== Methods -### SubmitProof +==== SubmitProof -Submit a goal for verification. `prover` is the `ProverKind` enum and -the timeout is expressed in seconds. +Submit a goal for verification. `+prover+` is the `+ProverKind+` enum +and the timeout is expressed in seconds. -```protobuf +[source,protobuf] +---- message SubmitProofRequest { string goal = 1; ProverKind prover = 2; @@ -48,17 +44,18 @@ message ProofResponse { optional double time_elapsed = 6; optional string error_message = 7; } -``` +---- -`GetProofStatus` takes `{ proof_id }` and returns the same -`ProofResponse`. +`+GetProofStatus+` takes `+{ proof_id }+` and returns the same +`+ProofResponse+`. -### StreamProof +==== StreamProof Streams progress for a proof that has already been submitted, so the request is just its identifier: -```protobuf +[source,protobuf] +---- message StreamProofRequest { string proof_id = 1; } @@ -69,13 +66,14 @@ message ProofUpdate { string message = 3; optional double progress = 4; } -``` +---- -### ApplyTactic +==== ApplyTactic -Note the field names: `tactic_name` and a repeated `tactic_args`. +Note the field names: `+tactic_name+` and a repeated `+tactic_args+`. -```protobuf +[source,protobuf] +---- message ApplyTacticRequest { string proof_id = 1; string tactic_name = 2; @@ -86,22 +84,23 @@ message TacticResponse { bool success = 1; ProofResponse proof_state = 2; } -``` +---- -### CancelProof +==== CancelProof -Takes `{ proof_id }`, returns `{ success }`. +Takes `+{ proof_id }+`, returns `+{ success }+`. -### ListProvers +==== ListProvers -Takes an empty request and returns `ProverInfo` entries carrying kind, +Takes an empty request and returns `+ProverInfo+` entries carrying kind, version, tier, complexity, and availability. -### SuggestTactics +==== SuggestTactics Keyed by proof, not by goal text: -```protobuf +[source,protobuf] +---- message SuggestTacticsRequest { string proof_id = 1; optional uint32 limit = 2; @@ -113,17 +112,18 @@ message Tactic { optional string description = 3; optional float confidence = 4; } -``` +---- -## Connecting +=== Connecting -```bash +[source,bash] +---- grpcurl -plaintext localhost:50051 echidna.ProofService/ListProvers grpcurl -plaintext -d '{ "goal": "forall n, n + 0 = n", "prover": "COQ" }' localhost:50051 echidna.ProofService/SubmitProof -``` +---- -[Documentation index](/docs/index.html) +link:/docs/index.html[Documentation index] diff --git a/site/docs/api/rest.adoc b/site/docs/api/rest.adoc new file mode 100644 index 00000000..9bde09ea --- /dev/null +++ b/site/docs/api/rest.adoc @@ -0,0 +1,108 @@ +== REST Interface Reference + +The `+echidna-rest+` binary is an optional self-hosted service that +exposes an OpenAPI-documented `+/api/v1+` surface, separate from the +link:/docs/api/core.html[core server API]. It binds `+127.0.0.1:8000+` +over plain HTTP — put it behind a TLS-terminating proxy before exposing +it. + +Documented from `+src/interfaces/rest/{main,handlers,models}.rs+`. + +=== Endpoints + +==== Health check + +.... +GET /health +.... + +Note that health sits at the server root, not under `+/api/v1+`. + +==== Provers + +.... +GET /api/v1/provers +GET /api/v1/provers/{kind} +.... + +Each entry carries the prover kind, version string, tier, complexity, +and whether the backend binary is available on this host: + +[source,json] +---- +{ "kind": "Coq", "version": "8.19", "tier": 1, "complexity": 3, "available": true } +---- + +`+{kind}+` is a `+ProverKind+` variant name, for example `+Coq+`, +`+Lean+`, `+Z3+`. + +==== Proofs + +.... +POST /api/v1/proofs +GET /api/v1/proofs +GET /api/v1/proofs/{id} +DELETE /api/v1/proofs/{id} +.... + +Submit request — the timeout field is `+timeout_seconds+` and is +optional: + +[source,json] +---- +{ + "goal": "forall n : nat, n + 0 = n", + "prover": "Coq", + "timeout_seconds": 30 +} +---- + +Response: + +[source,json] +---- +{ + "id": "proof-uuid", + "prover": "Coq", + "goal": "forall n : nat, n + 0 = n", + "status": "Verified", + "proof_script": ["induction n", "reflexivity"], + "time_elapsed": 0.42 +} +---- + +`+error_message+` is present only on failure. + +==== Tactics + +.... +POST /api/v1/proofs/{id}/tactics +.... + +The request is a tactic name plus its arguments; `+args+` is required +and may be an empty array: + +[source,json] +---- +{ "name": "induction", "args": ["n"] } +---- + +The response wraps the updated proof state: + +[source,json] +---- +{ "success": true, "proof_state": { "id": "proof-uuid", "status": "InProgress" } } +---- + +==== Exchange and consultation + +.... +GET /api/v1/proofs/{id}/export +POST /api/v1/exchange/import +POST /api/v1/consult +.... + +`+export+` and `+import+` move proofs across provers via the exchange +layer; `+consult+` runs a portfolio consultation. + +link:/docs/index.html[Documentation index] diff --git a/site/docs/api/rest.md b/site/docs/api/rest.md deleted file mode 100644 index a28085fc..00000000 --- a/site/docs/api/rest.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: REST Interface Reference -date: 2026-07-28 -template: default ---- - -# REST Interface Reference - -The `echidna-rest` binary is an optional self-hosted service that -exposes an OpenAPI-documented `/api/v1` surface, separate from the -[core server API](/docs/api/core.html). It binds `127.0.0.1:8000` over -plain HTTP — put it behind a TLS-terminating proxy before exposing it. - -Documented from `src/interfaces/rest/{main,handlers,models}.rs`. - -## Endpoints - -### Health check - -``` -GET /health -``` - -Note that health sits at the server root, not under `/api/v1`. - -### Provers - -``` -GET /api/v1/provers -GET /api/v1/provers/{kind} -``` - -Each entry carries the prover kind, version string, tier, complexity, -and whether the backend binary is available on this host: - -```json -{ "kind": "Coq", "version": "8.19", "tier": 1, "complexity": 3, "available": true } -``` - -`{kind}` is a `ProverKind` variant name, for example `Coq`, `Lean`, `Z3`. - -### Proofs - -``` -POST /api/v1/proofs -GET /api/v1/proofs -GET /api/v1/proofs/{id} -DELETE /api/v1/proofs/{id} -``` - -Submit request — the timeout field is `timeout_seconds` and is optional: - -```json -{ - "goal": "forall n : nat, n + 0 = n", - "prover": "Coq", - "timeout_seconds": 30 -} -``` - -Response: - -```json -{ - "id": "proof-uuid", - "prover": "Coq", - "goal": "forall n : nat, n + 0 = n", - "status": "Verified", - "proof_script": ["induction n", "reflexivity"], - "time_elapsed": 0.42 -} -``` - -`error_message` is present only on failure. - -### Tactics - -``` -POST /api/v1/proofs/{id}/tactics -``` - -The request is a tactic name plus its arguments; `args` is required and -may be an empty array: - -```json -{ "name": "induction", "args": ["n"] } -``` - -The response wraps the updated proof state: - -```json -{ "success": true, "proof_state": { "id": "proof-uuid", "status": "InProgress" } } -``` - -### Exchange and consultation - -``` -GET /api/v1/proofs/{id}/export -POST /api/v1/exchange/import -POST /api/v1/consult -``` - -`export` and `import` move proofs across provers via the exchange -layer; `consult` runs a portfolio consultation. - -[Documentation index](/docs/index.html) diff --git a/site/docs/index.adoc b/site/docs/index.adoc new file mode 100644 index 00000000..05569975 --- /dev/null +++ b/site/docs/index.adoc @@ -0,0 +1,83 @@ +== Platform Documentation + +*Extensible Cognitive Hybrid Intelligence for Deductive Neural +Assistance* + +A trust-hardened neurosymbolic theorem proving platform supporting a +broad portfolio of prover backends with a comprehensive verification +pipeline. + +=== Features + +* *Prover portfolio*: Coq, Lean 4, Isabelle/HOL, Z3, CVC5, Agda, Idris2, +and many more — see the canonical tier table in the repository’s +`+docs/PROVER_COUNT.md+` +* *Trust pipeline*: solver integrity, proof certificates, axiom +tracking, confidence scoring +* *API interfaces*: REST (OpenAPI), GraphQL, gRPC +* *Neural premise selection*: Julia ML layer with tactic prediction +* *Proof exchange*: cross-prover via OpenTheory and Dedukti + +=== API Quick Start + +The hosted core server at `+https://api.nesy-prover.dev+` exposes the +primary HTTP API: + +[source,bash] +---- +curl https://api.nesy-prover.dev/api/health +curl https://api.nesy-prover.dev/api/provers +---- + +Verifying an SMT script takes a prover name and its source: + +[source,bash] +---- +curl -X POST https://api.nesy-prover.dev/api/verify \ + -H "Content-Type: application/json" \ + -d '{"prover": "Z3", "content": "(assert (forall ((x Int)) (= (+ x 0) x)))(check-sat)"}' +---- + +See the link:/docs/api/core.html[core server API reference] for every +route. A self-hosted instance serves the same routes over plain HTTP on +the port passed to `+--port+` (default 8081) — front it with a TLS proxy +before exposing it. + +Three further interface services ship as separate optional binaries, +each binding loopback over plain HTTP: + +==== REST interface (port 8000) + +An OpenAPI-documented `+/api/v1+` surface — see the +link:/docs/api/rest.html[REST interface reference]. + +==== GraphQL interface (port 8081) + +Endpoint and interactive playground both at the server root — see the +link:/docs/api/graphql.html[GraphQL interface reference]. + +==== gRPC interface (port 50051) + +See the link:/docs/api/grpc.html[gRPC interface reference] and the proto +definition at `+src/interfaces/grpc/proto/echidna.proto+`. + +=== Architecture + +ECHIDNA follows a trust-hardened architecture: + +[arabic] +. *Solver Binary Integrity* — SHAKE3-512 + BLAKE3 verification +. *SMT Portfolio Solving* — cross-checking across solvers +. *Proof Certificate Checking* — Alethe, DRAT/LRAT, TSTP +. *Axiom Usage Tracking* — 4 danger levels (Safe, Noted, Warning, +Reject) +. *Solver Sandboxing* — Podman, bubblewrap, or none +. *Confidence Scoring* — 5-level trust hierarchy +. *Mutation Testing* — specification robustness testing + +=== License + +AGPL-3.0-or-later. Source at +https://github.com/hyperpolymath/echidna[github.com/hyperpolymath/echidna]. + +link:/index.html[Back to home] diff --git a/site/docs/index.md b/site/docs/index.md deleted file mode 100644 index 429e2a07..00000000 --- a/site/docs/index.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: ECHIDNA Platform Documentation -description: Architecture, features, and API quick start -date: 2026-07-28 -template: default ---- - -# Platform Documentation - -**Extensible Cognitive Hybrid Intelligence for Deductive Neural Assistance** - -A trust-hardened neurosymbolic theorem proving platform supporting a broad -portfolio of prover backends with a comprehensive verification pipeline. - -## Features - -- **Prover portfolio**: Coq, Lean 4, Isabelle/HOL, Z3, CVC5, Agda, Idris2, and many more — see the canonical tier table in the repository's `docs/PROVER_COUNT.md` -- **Trust pipeline**: solver integrity, proof certificates, axiom tracking, confidence scoring -- **API interfaces**: REST (OpenAPI), GraphQL, gRPC -- **Neural premise selection**: Julia ML layer with tactic prediction -- **Proof exchange**: cross-prover via OpenTheory and Dedukti - -## API Quick Start - -The hosted core server at `https://api.nesy-prover.dev` exposes the -primary HTTP API: - -```bash -curl https://api.nesy-prover.dev/api/health -curl https://api.nesy-prover.dev/api/provers -``` - -Verifying an SMT script takes a prover name and its source: - -```bash -curl -X POST https://api.nesy-prover.dev/api/verify \ - -H "Content-Type: application/json" \ - -d '{"prover": "Z3", "content": "(assert (forall ((x Int)) (= (+ x 0) x)))(check-sat)"}' -``` - -See the [core server API reference](/docs/api/core.html) for every -route. A self-hosted instance serves the same routes over plain HTTP on -the port passed to `--port` (default 8081) — front it with a TLS proxy -before exposing it. - -Three further interface services ship as separate optional binaries, -each binding loopback over plain HTTP: - -### REST interface (port 8000) - -An OpenAPI-documented `/api/v1` surface — see the -[REST interface reference](/docs/api/rest.html). - -### GraphQL interface (port 8081) - -Endpoint and interactive playground both at the server root — see the -[GraphQL interface reference](/docs/api/graphql.html). - -### gRPC interface (port 50051) - -See the [gRPC interface reference](/docs/api/grpc.html) and the proto -definition at `src/interfaces/grpc/proto/echidna.proto`. - -## Architecture - -ECHIDNA follows a trust-hardened architecture: - -1. **Solver Binary Integrity** — SHAKE3-512 + BLAKE3 verification -2. **SMT Portfolio Solving** — cross-checking across solvers -3. **Proof Certificate Checking** — Alethe, DRAT/LRAT, TSTP -4. **Axiom Usage Tracking** — 4 danger levels (Safe, Noted, Warning, Reject) -5. **Solver Sandboxing** — Podman, bubblewrap, or none -6. **Confidence Scoring** — 5-level trust hierarchy -7. **Mutation Testing** — specification robustness testing - -## License - -AGPL-3.0-or-later. Source at -[github.com/hyperpolymath/echidna](https://github.com/hyperpolymath/echidna). - -[Back to home](/index.html) diff --git a/site/index.adoc b/site/index.adoc new file mode 100644 index 00000000..73903619 --- /dev/null +++ b/site/index.adoc @@ -0,0 +1,66 @@ +== ECHIDNA + +*Extensible Cognitive Hybrid Intelligence for Deductive Neural +Assistance* + +ECHIDNA is a trust-hardened neurosymbolic theorem-proving platform. A +Rust core orchestrates a broad portfolio of interactive proof +assistants, SMT solvers, first-order ATPs, and constraint solvers behind +a single dispatch pipeline, with neural premise selection and tactic +prediction provided by a Julia ML layer. + +Every proof result passes through a trust-hardening pipeline before it +is reported: solver-binary integrity verification, portfolio +cross-checking, proof-certificate checking, axiom-usage tracking, +sandboxed execution, and statistical confidence scoring. + +=== Explore + +* link:/docs/index.html[Platform documentation] — architecture, +features, and API quick start +* link:/docs/api/core.html[Core server API] — the API served at +api.nesy-prover.dev +* link:/docs/api/rest.html[REST interface] +* link:/docs/api/graphql.html[GraphQL interface] +* link:/docs/api/grpc.html[gRPC interface] +* link:/playground/[Coq playground] — prove theorems in your browser +with jsCoq + +=== Live API + +A public instance of the ECHIDNA core server is available at +`+https://api.nesy-prover.dev+`. + +Check service health: + +[source,bash] +---- +curl https://api.nesy-prover.dev/api/health +---- + +List the core prover backends: + +[source,bash] +---- +curl https://api.nesy-prover.dev/api/provers +---- + +Verify a small SMT goal with Z3: + +[source,bash] +---- +curl -X POST https://api.nesy-prover.dev/api/verify \ + -H 'Content-Type: application/json' \ + -d '{"prover": "Z3", "content": "(assert (forall ((x Int)) (= (+ x 0) x)))(check-sat)"}' +---- + +The public instance is rate-limited and intended for evaluation. For +sustained or private use, run your own instance — the container image is +published at `+ghcr.io/hyperpolymath/echidna+`. + +=== Source and license + +ECHIDNA is free software, licensed under AGPL-3.0-or-later. Development +happens at +https://github.com/hyperpolymath/echidna[github.com/hyperpolymath/echidna], +where issues and contributions are welcome. diff --git a/site/index.md b/site/index.md deleted file mode 100644 index a8acb9e1..00000000 --- a/site/index.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: ECHIDNA — Neurosymbolic Theorem Proving -description: Trust-hardened neurosymbolic theorem proving platform -date: 2026-07-28 -template: default ---- - -# ECHIDNA - -**Extensible Cognitive Hybrid Intelligence for Deductive Neural Assistance** - -ECHIDNA is a trust-hardened neurosymbolic theorem-proving platform. A Rust -core orchestrates a broad portfolio of interactive proof assistants, SMT -solvers, first-order ATPs, and constraint solvers behind a single dispatch -pipeline, with neural premise selection and tactic prediction provided by a -Julia ML layer. - -Every proof result passes through a trust-hardening pipeline before it is -reported: solver-binary integrity verification, portfolio cross-checking, -proof-certificate checking, axiom-usage tracking, sandboxed execution, and -statistical confidence scoring. - -## Explore - -- [Platform documentation](/docs/index.html) — architecture, features, and API quick start -- [Core server API](/docs/api/core.html) — the API served at api.nesy-prover.dev -- [REST interface](/docs/api/rest.html) -- [GraphQL interface](/docs/api/graphql.html) -- [gRPC interface](/docs/api/grpc.html) -- [Coq playground](/playground/) — prove theorems in your browser with jsCoq - -## Live API - -A public instance of the ECHIDNA core server is available at -`https://api.nesy-prover.dev`. - -Check service health: - -```bash -curl https://api.nesy-prover.dev/api/health -``` - -List the core prover backends: - -```bash -curl https://api.nesy-prover.dev/api/provers -``` - -Verify a small SMT goal with Z3: - -```bash -curl -X POST https://api.nesy-prover.dev/api/verify \ - -H 'Content-Type: application/json' \ - -d '{"prover": "Z3", "content": "(assert (forall ((x Int)) (= (+ x 0) x)))(check-sat)"}' -``` - -The public instance is rate-limited and intended for evaluation. For -sustained or private use, run your own instance — the container image is -published at `ghcr.io/hyperpolymath/echidna`. - -## Source and license - -ECHIDNA is free software, licensed under AGPL-3.0-or-later. Development -happens at -[github.com/hyperpolymath/echidna](https://github.com/hyperpolymath/echidna), -where issues and contributions are welcome. diff --git a/src/chapel/README.adoc b/src/chapel/README.adoc new file mode 100644 index 00000000..21875476 --- /dev/null +++ b/src/chapel/README.adoc @@ -0,0 +1,169 @@ +== Chapel Production Integration for ECHIDNA + +Parallel proof search using Chapel’s task parallelism, integrated into +the main ECHIDNA codebase. + +=== Overview + +This directory contains the Chapel-based parallel proof search +framework, now integrated into the main ECHIDNA codebase. The Chapel +code is used to accelerate proof search by dispatching theorem proving +goals to multiple prover backends concurrently. + +=== Integration Status + +* *Status*: Production-ready +* *Location*: `+src/chapel/+` +* *Build System*: Integrated with `+Justfile+` and `+Cargo.toml+` +* *FFI Bridge*: Zig bridge at `+src/zig_ffi/chapel_bridge.zig+` + +=== Build Instructions + +==== 1. Install Chapel + +[source,bash] +---- +# Download Chapel 2.0 +wget https://github.com/chapel-lang/chapel/releases/download/2.0.0/chapel-2.0.0.tar.gz +tar xzf chapel-2.0.0.tar.gz +cd chapel-2.0.0 + +# Set environment +source util/setchplenv.bash + +# Build (takes ~10 minutes) +make +---- + +==== 2. Build Chapel Code + +[source,bash] +---- +cd src/chapel +chpl parallel_proof_search.chpl -o proof_search +---- + +==== 3. Build Zig FFI Bridge + +[source,bash] +---- +cd src/zig_ffi +zig build -Dstubs=false +---- + +==== 4. Build Rust with Chapel Feature + +[source,bash] +---- +cargo build --features chapel +---- + +=== Expected Output + +.... +╔═══════════════════════════════════════════════════════╗ +║ ECHIDNA Chapel Metalayer - Proof of Concept ║ +╚═══════════════════════════════════════════════════════╝ + +Goal: forall n m : nat, n + m = m + n +Provers: 12 + +═══════════════════════════════════════════════════════ +BENCHMARK: Sequential vs Parallel Proof Search +═══════════════════════════════════════════════════════ + +Sequential search: trying provers one by one... + Trying Coq... ✗ failed + Trying Lean... ✓ SUCCESS + Trying Isabelle... (skipped) + +─────────────────────────────────────────────────────── + +Parallel search: trying all 12 provers concurrently... + ✓ Lean succeeded in 2.34 seconds (3 tactics) + ✓ Agda succeeded in 3.12 seconds (5 tactics) + ✓ PVS succeeded in 4.01 seconds (7 tactics) + +Parallel search completed in 4.50 seconds + Successful proofs: 3/12 + +═══════════════════════════════════════════════════════ +RESULTS +═══════════════════════════════════════════════════════ + +Sequential Search: + Time: 6.78 seconds + Result: ✓ SUCCESS (Lean, 3 tactics) + +Parallel Search: + Time: 4.50 seconds + Result: ✓ SUCCESS (Lean, 3 tactics) + +Speedup: 1.51x +✓ Parallel search is significantly faster! +.... + +=== What This Demonstrates + +==== 1. Parallel Proof Search + +* Tries all 30 provers simultaneously +* Returns first/best successful proof +* Automatic load balancing + +==== 2. Performance Benefits + +* Typical speedup: 1.5x - 12x (depending on prover success rate) +* Best case: 12x (all provers take similar time) +* Worst case: 1x (first prover succeeds immediately) + +==== 3. Beam Search + +* Parallel exploration of proof space +* Multiple tactic strategies simultaneously +* Finds optimal proofs faster + +=== Integration Details + +==== Depth of Integration + +* *FFI Layer*: Chapel functions are exposed via +`+chapel_ffi_exports.chpl+` and wrapped by the Zig bridge at +`+src/zig_ffi/chapel_bridge.zig+`. +* *Rust Consumption*: The Rust code in `+src/rust/proof_search.rs+` +consumes these functions under the `+chapel+` feature flag. +* *Build System*: The build process is integrated into `+Justfile+` and +`+Cargo.toml+`. + +==== Breadth of Integration + +* *Prover Dispatch*: The Chapel code is used for parallel prover +dispatch, replacing the sequential dispatch in Rust. +* *Result Aggregation*: Results from all provers are aggregated and the +best proof is selected. +* *Fallback Mechanism*: If Chapel is not available, the system falls +back to sequential dispatch. + +==== Relation to Other Parts of the System + +* *Rust Core*: The Rust core remains the primary logic layer, with +Chapel accelerating specific tasks. +* *Julia ML Layer*: The Julia ML layer is unaffected by the Chapel +integration. +* *FFI Bridge*: The Zig FFI bridge is a critical component that enables +communication between Rust and Chapel. + +=== Next Steps + +[arabic] +. *Update Rust Dispatch*: Modify `+src/rust/dispatch.rs+` to use Chapel +for parallel proof search when the `+chapel+` feature is enabled. +. *Add CI/CD Support*: Ensure Chapel code is built and tested in CI. +. *Performance Optimization*: Run benchmarks and tune the Chapel code. +. *Documentation*: Update documentation to reflect the production +integration. + +=== References + +* Full analysis: `+../CHAPEL_METALAYER_ANALYSIS.md+` +* Chapel docs: https://chapel-lang.org/docs/ diff --git a/src/chapel/README.md b/src/chapel/README.md deleted file mode 100644 index ec6a5085..00000000 --- a/src/chapel/README.md +++ /dev/null @@ -1,142 +0,0 @@ -# Chapel Production Integration for ECHIDNA - -Parallel proof search using Chapel's task parallelism, integrated into the main ECHIDNA codebase. - -## Overview - -This directory contains the Chapel-based parallel proof search framework, now integrated into the main ECHIDNA codebase. The Chapel code is used to accelerate proof search by dispatching theorem proving goals to multiple prover backends concurrently. - -## Integration Status - -- **Status**: Production-ready -- **Location**: `src/chapel/` -- **Build System**: Integrated with `Justfile` and `Cargo.toml` -- **FFI Bridge**: Zig bridge at `src/zig_ffi/chapel_bridge.zig` - -## Build Instructions - -### 1. Install Chapel - -```bash -# Download Chapel 2.0 -wget https://github.com/chapel-lang/chapel/releases/download/2.0.0/chapel-2.0.0.tar.gz -tar xzf chapel-2.0.0.tar.gz -cd chapel-2.0.0 - -# Set environment -source util/setchplenv.bash - -# Build (takes ~10 minutes) -make -``` - -### 2. Build Chapel Code - -```bash -cd src/chapel -chpl parallel_proof_search.chpl -o proof_search -``` - -### 3. Build Zig FFI Bridge - -```bash -cd src/zig_ffi -zig build -Dstubs=false -``` - -### 4. Build Rust with Chapel Feature - -```bash -cargo build --features chapel -``` - -## Expected Output - -``` -╔═══════════════════════════════════════════════════════╗ -║ ECHIDNA Chapel Metalayer - Proof of Concept ║ -╚═══════════════════════════════════════════════════════╝ - -Goal: forall n m : nat, n + m = m + n -Provers: 12 - -═══════════════════════════════════════════════════════ -BENCHMARK: Sequential vs Parallel Proof Search -═══════════════════════════════════════════════════════ - -Sequential search: trying provers one by one... - Trying Coq... ✗ failed - Trying Lean... ✓ SUCCESS - Trying Isabelle... (skipped) - -─────────────────────────────────────────────────────── - -Parallel search: trying all 12 provers concurrently... - ✓ Lean succeeded in 2.34 seconds (3 tactics) - ✓ Agda succeeded in 3.12 seconds (5 tactics) - ✓ PVS succeeded in 4.01 seconds (7 tactics) - -Parallel search completed in 4.50 seconds - Successful proofs: 3/12 - -═══════════════════════════════════════════════════════ -RESULTS -═══════════════════════════════════════════════════════ - -Sequential Search: - Time: 6.78 seconds - Result: ✓ SUCCESS (Lean, 3 tactics) - -Parallel Search: - Time: 4.50 seconds - Result: ✓ SUCCESS (Lean, 3 tactics) - -Speedup: 1.51x -✓ Parallel search is significantly faster! -``` - -## What This Demonstrates - -### 1. Parallel Proof Search -- Tries all 30 provers simultaneously -- Returns first/best successful proof -- Automatic load balancing - -### 2. Performance Benefits -- Typical speedup: 1.5x - 12x (depending on prover success rate) -- Best case: 12x (all provers take similar time) -- Worst case: 1x (first prover succeeds immediately) - -### 3. Beam Search -- Parallel exploration of proof space -- Multiple tactic strategies simultaneously -- Finds optimal proofs faster - -## Integration Details - -### Depth of Integration -- **FFI Layer**: Chapel functions are exposed via `chapel_ffi_exports.chpl` and wrapped by the Zig bridge at `src/zig_ffi/chapel_bridge.zig`. -- **Rust Consumption**: The Rust code in `src/rust/proof_search.rs` consumes these functions under the `chapel` feature flag. -- **Build System**: The build process is integrated into `Justfile` and `Cargo.toml`. - -### Breadth of Integration -- **Prover Dispatch**: The Chapel code is used for parallel prover dispatch, replacing the sequential dispatch in Rust. -- **Result Aggregation**: Results from all provers are aggregated and the best proof is selected. -- **Fallback Mechanism**: If Chapel is not available, the system falls back to sequential dispatch. - -### Relation to Other Parts of the System -- **Rust Core**: The Rust core remains the primary logic layer, with Chapel accelerating specific tasks. -- **Julia ML Layer**: The Julia ML layer is unaffected by the Chapel integration. -- **FFI Bridge**: The Zig FFI bridge is a critical component that enables communication between Rust and Chapel. - -## Next Steps - -1. **Update Rust Dispatch**: Modify `src/rust/dispatch.rs` to use Chapel for parallel proof search when the `chapel` feature is enabled. -2. **Add CI/CD Support**: Ensure Chapel code is built and tested in CI. -3. **Performance Optimization**: Run benchmarks and tune the Chapel code. -4. **Documentation**: Update documentation to reflect the production integration. - -## References - -- Full analysis: `../CHAPEL_METALAYER_ANALYSIS.md` -- Chapel docs: https://chapel-lang.org/docs/ diff --git a/src/chapel/RESULTS.adoc b/src/chapel/RESULTS.adoc new file mode 100644 index 00000000..32d30ed9 --- /dev/null +++ b/src/chapel/RESULTS.adoc @@ -0,0 +1,205 @@ +== Chapel Metalayer Proof-of-Concept Results + +*Date*: 2026-01-29 *Status*: ✅ Successful + +''''' + +=== Execution Summary + +Successfully compiled and ran parallel proof search demonstration using +Chapel 2.2.0 in Podman container. + +==== Test Configuration + +* *Goal*: `+forall n m : nat, n + m = m + n+` (commutativity of +addition) +* *Provers*: 12 concurrent (Coq, Lean, Isabelle, Agda, Z3, CVC5, ACL2, +PVS, HOL4, Metamath, HOL Light, Mizar) +* *Environment*: Podman container (docker.io/chapel/chapel:2.2.0) + +''''' + +=== Results + +==== Sequential Search + +* *Time*: 1.62 seconds +* *Result*: ✓ SUCCESS (Coq, 4 tactics) +* *Provers tried*: 1/12 (stopped after first success) + +==== Parallel Search + +* *Time*: 4.25 seconds +* *Result*: ✓ SUCCESS (best from 9 successful proofs) +* *Successful proofs*: 9/12 provers found valid proofs +* *Proofs found*: +[arabic] +. HOL4 - 1.41s (5 tactics) +. Metamath - 1.44s (9 tactics) +. Agda - 1.81s (5 tactics) +. Lean - 2.34s (5 tactics) +. Isabelle - 2.64s (9 tactics) +. ACL2 - 2.74s (5 tactics) +. PVS - 3.03s (4 tactics) ← *Best proof (fewest tactics)* +. CVC5 - 3.05s (5 tactics) +. Coq - 4.25s (4 tactics) + +''''' + +=== Analysis + +==== This Run: Sequential Faster (0.38x) + +In this particular run, sequential search was faster because: - Coq +(first prover tried) succeeded immediately - This represents the *best +case for sequential*, *worst case for parallel* + +==== Parallel Search Value Proposition + +Even though sequential won this round, parallel search provides: + +[arabic] +. *Multiple Proofs*: Found 9 different valid proofs vs just 1 +. *Proof Quality Selection*: Can choose shortest proof (PVS: 4 tactics) +. *Robustness*: If Coq had failed, parallel would have succeeded with +HOL4 at 1.41s +. *Average Case Performance*: Real-world proofs don’t always succeed on +first try + +==== Expected Performance Distribution + +[cols=",,,",options="header",] +|=== +|Scenario |Sequential Time |Parallel Time |Speedup +|*Best (1st succeeds)* |1-2s |4-5s |0.3x (slower) +|*Average (3rd succeeds)* |6-8s |4-5s |1.5x +|*Worst (8th succeeds)* |20-30s |4-5s |5-6x +|=== + +==== Beam Search Demonstration + +Successfully demonstrated parallel proof space exploration: - Width: 5 +concurrent search paths - Depth: 3 steps - Total states explored: 15 (in +parallel) + +''''' + +=== Technical Achievements + +==== ✅ Compilation + +* Fixed Chapel string formatting (`+.format()+` → `+writef()+`) +* Successfully compiled 258-line Chapel program +* Zero compilation errors after fixes + +==== ✅ Execution + +* Ran in containerized environment (Podman + Chapel image) +* All 12 provers simulated concurrently +* Beam search demonstration successful + +==== ✅ Proof of Concept Validated + +* `+coforall+` parallel loop works as expected +* Task-based parallelism scales to 12+ provers +* Results correctly aggregated from parallel tasks + +''''' + +=== Key Insights + +==== 1. Parallel Search Trade-offs + +* *Pro*: Finds multiple proofs, better average-case performance +* *Con*: Overhead when first prover succeeds quickly +* *Recommendation*: Use parallel for hard/unknown problems + +==== 2. Proof Quality Matters + +In this run, parallel search found: - *Shortest proof*: PVS (4 tactics) +- *Fastest proof*: HOL4 (1.41s) - *Most tactics*: Isabelle, Metamath (9 +tactics) + +This diversity allows *selecting optimal proof* rather than just first +proof. + +==== 3. Chapel Performance + +* Minimal overhead for task spawning +* Clean syntax for parallel patterns +* Easy integration potential with Rust/Julia + +''''' + +=== Next Steps + +==== Phase 1: Integration (Recommended) + +[arabic] +. Add Chapel FFI to Rust (`+chapel_proof_api.h+`) +. Replace mock `+tryProver()+` with real prover backends +. Expose parallel search via `+/api/proof/parallel+` endpoint + +==== Phase 2: Optimization + +[arabic] +. Add timeout handling (cancel slow provers) +. Implement proof caching (avoid redundant searches) +. Add priority queues (try likely provers first in parallel) + +==== Phase 3: Distributed (Optional) + +[arabic] +. Run on multi-node cluster (Chapel’s `+on+` locale) +. Scale to 100+ provers across machines +. Integrate with ML model for prover selection + +''''' + +=== Conclusion + +Chapel metalayer is *✅ VIABLE* for ECHIDNA: + +* ✅ Compiles and runs successfully +* ✅ Parallel proof search works as designed +* ✅ Demonstrates clear value proposition (multiple proofs, quality +selection) +* ✅ Integration path clear (C FFI → Rust → Julia) + +*Recommendation*: Proceed with Phase 1 integration as outlined in +`+CHAPEL_METALAYER_ANALYSIS.md+`. + +''''' + +=== Files Generated + +* `+parallel_proof_search.chpl+` - 258 lines (fixed formatting) +* `+proof_search+` - Compiled Chapel binary +* `+RESULTS.md+` - This document + +''''' + +=== Installation Method + +Used Podman container to avoid native compilation issues: + +[source,bash] +---- +# Pull Chapel image +podman pull docker.io/chapel/chapel:2.2.0 + +# Compile +podman run --rm -v ./chapel_poc:/workspace:z \ + docker.io/chapel/chapel:2.2.0 \ + chpl /workspace/parallel_proof_search.chpl -o /workspace/proof_search + +# Run +podman run --rm -v ./chapel_poc:/workspace:z \ + docker.io/chapel/chapel:2.2.0 \ + /workspace/proof_search +---- + +''''' + +_ECHIDNA Chapel Metalayer - Proof-of-Concept Results_ _Co-Authored-By: +Claude Sonnet 4.5 noreply@anthropic.com_ diff --git a/src/chapel/RESULTS.md b/src/chapel/RESULTS.md deleted file mode 100644 index 4044c9d0..00000000 --- a/src/chapel/RESULTS.md +++ /dev/null @@ -1,181 +0,0 @@ -# Chapel Metalayer Proof-of-Concept Results - -**Date**: 2026-01-29 -**Status**: ✅ Successful - ---- - -## Execution Summary - -Successfully compiled and ran parallel proof search demonstration using Chapel 2.2.0 in Podman container. - -### Test Configuration - -- **Goal**: `forall n m : nat, n + m = m + n` (commutativity of addition) -- **Provers**: 12 concurrent (Coq, Lean, Isabelle, Agda, Z3, CVC5, ACL2, PVS, HOL4, Metamath, HOL Light, Mizar) -- **Environment**: Podman container (docker.io/chapel/chapel:2.2.0) - ---- - -## Results - -### Sequential Search -- **Time**: 1.62 seconds -- **Result**: ✓ SUCCESS (Coq, 4 tactics) -- **Provers tried**: 1/12 (stopped after first success) - -### Parallel Search -- **Time**: 4.25 seconds -- **Result**: ✓ SUCCESS (best from 9 successful proofs) -- **Successful proofs**: 9/12 provers found valid proofs -- **Proofs found**: - 1. HOL4 - 1.41s (5 tactics) - 2. Metamath - 1.44s (9 tactics) - 3. Agda - 1.81s (5 tactics) - 4. Lean - 2.34s (5 tactics) - 5. Isabelle - 2.64s (9 tactics) - 6. ACL2 - 2.74s (5 tactics) - 7. PVS - 3.03s (4 tactics) ← **Best proof (fewest tactics)** - 8. CVC5 - 3.05s (5 tactics) - 9. Coq - 4.25s (4 tactics) - ---- - -## Analysis - -### This Run: Sequential Faster (0.38x) - -In this particular run, sequential search was faster because: -- Coq (first prover tried) succeeded immediately -- This represents the **best case for sequential**, **worst case for parallel** - -### Parallel Search Value Proposition - -Even though sequential won this round, parallel search provides: - -1. **Multiple Proofs**: Found 9 different valid proofs vs just 1 -2. **Proof Quality Selection**: Can choose shortest proof (PVS: 4 tactics) -3. **Robustness**: If Coq had failed, parallel would have succeeded with HOL4 at 1.41s -4. **Average Case Performance**: Real-world proofs don't always succeed on first try - -### Expected Performance Distribution - -| Scenario | Sequential Time | Parallel Time | Speedup | -|----------|----------------|---------------|---------| -| **Best (1st succeeds)** | 1-2s | 4-5s | 0.3x (slower) | -| **Average (3rd succeeds)** | 6-8s | 4-5s | 1.5x | -| **Worst (8th succeeds)** | 20-30s | 4-5s | 5-6x | - -### Beam Search Demonstration - -Successfully demonstrated parallel proof space exploration: -- Width: 5 concurrent search paths -- Depth: 3 steps -- Total states explored: 15 (in parallel) - ---- - -## Technical Achievements - -### ✅ Compilation -- Fixed Chapel string formatting (`.format()` → `writef()`) -- Successfully compiled 258-line Chapel program -- Zero compilation errors after fixes - -### ✅ Execution -- Ran in containerized environment (Podman + Chapel image) -- All 12 provers simulated concurrently -- Beam search demonstration successful - -### ✅ Proof of Concept Validated -- `coforall` parallel loop works as expected -- Task-based parallelism scales to 12+ provers -- Results correctly aggregated from parallel tasks - ---- - -## Key Insights - -### 1. Parallel Search Trade-offs -- **Pro**: Finds multiple proofs, better average-case performance -- **Con**: Overhead when first prover succeeds quickly -- **Recommendation**: Use parallel for hard/unknown problems - -### 2. Proof Quality Matters -In this run, parallel search found: -- **Shortest proof**: PVS (4 tactics) -- **Fastest proof**: HOL4 (1.41s) -- **Most tactics**: Isabelle, Metamath (9 tactics) - -This diversity allows **selecting optimal proof** rather than just first proof. - -### 3. Chapel Performance -- Minimal overhead for task spawning -- Clean syntax for parallel patterns -- Easy integration potential with Rust/Julia - ---- - -## Next Steps - -### Phase 1: Integration (Recommended) -1. Add Chapel FFI to Rust (`chapel_proof_api.h`) -2. Replace mock `tryProver()` with real prover backends -3. Expose parallel search via `/api/proof/parallel` endpoint - -### Phase 2: Optimization -1. Add timeout handling (cancel slow provers) -2. Implement proof caching (avoid redundant searches) -3. Add priority queues (try likely provers first in parallel) - -### Phase 3: Distributed (Optional) -1. Run on multi-node cluster (Chapel's `on` locale) -2. Scale to 100+ provers across machines -3. Integrate with ML model for prover selection - ---- - -## Conclusion - -Chapel metalayer is **✅ VIABLE** for ECHIDNA: - -- ✅ Compiles and runs successfully -- ✅ Parallel proof search works as designed -- ✅ Demonstrates clear value proposition (multiple proofs, quality selection) -- ✅ Integration path clear (C FFI → Rust → Julia) - -**Recommendation**: Proceed with Phase 1 integration as outlined in `CHAPEL_METALAYER_ANALYSIS.md`. - ---- - -## Files Generated - -- `parallel_proof_search.chpl` - 258 lines (fixed formatting) -- `proof_search` - Compiled Chapel binary -- `RESULTS.md` - This document - ---- - -## Installation Method - -Used Podman container to avoid native compilation issues: - -```bash -# Pull Chapel image -podman pull docker.io/chapel/chapel:2.2.0 - -# Compile -podman run --rm -v ./chapel_poc:/workspace:z \ - docker.io/chapel/chapel:2.2.0 \ - chpl /workspace/parallel_proof_search.chpl -o /workspace/proof_search - -# Run -podman run --rm -v ./chapel_poc:/workspace:z \ - docker.io/chapel/chapel:2.2.0 \ - /workspace/proof_search -``` - ---- - -*ECHIDNA Chapel Metalayer - Proof-of-Concept Results* -*Co-Authored-By: Claude Sonnet 4.5 * diff --git a/src/interfaces/README.adoc b/src/interfaces/README.adoc new file mode 100644 index 00000000..a8fce6d4 --- /dev/null +++ b/src/interfaces/README.adoc @@ -0,0 +1,119 @@ +== ECHIDNA Interfaces + +This directory contains all interface implementations for ECHIDNA +theorem proving platform. + +=== Available Interfaces + +==== GraphQL (`+graphql/+`) + +* *Framework:* Rust + async-graphql + axum +* *Port:* 8081 +* *Playground:* http://localhost:8081/ +* *Features:* +** Type-safe schema with all 17 provers +** Queries: `+provers+`, `+proofState+`, `+listProofs+`, +`+suggestTacticsByProofId+` (renamed from `+suggestTactics+` 2026-06-01, +issue #180), `+proverStatus+`, `+health+` +** Mutations: `+submitProof+`, `+applyTactic+`, `+cancelProof+`, +`+verifyProof+` (synchronous one-shot, returns typed `+VerifyOutcome+` + +optional `+mode+` / `+smtStatus+`), +`+suggestTactics(prover, context, goalState)+` (ad-hoc, ML-backed) +** Subscriptions: `+proofUpdates+` (planned) + +==== gRPC (`+grpc/+`) + +* *Framework:* Rust + tonic + Protocol Buffers +* *Port:* 50051 +* *Proto:* `+grpc/proto/echidna.proto+` +* *Features:* +** High-performance binary protocol +** Bidirectional streaming for long-running proofs +** RPCs: SubmitProof, GetProofStatus, StreamProof, ApplyTactic, +CancelProof +** Neural premise selection via SuggestTactics + +==== REST (`+rest/+`) + +* *Framework:* Rust + axum + utoipa (OpenAPI) +* *Port:* 8000 +* *Swagger UI:* http://localhost:8000/swagger-ui +* *Features:* +** RESTful JSON API +** OpenAPI 3.0 specification with Swagger UI +** Standard HTTP verbs (GET, POST, DELETE) +** Endpoints: `+/api/v1/provers+`, `+/api/v1/proofs+`, +`+/api/v1/proofs/:id/tactics+` + +=== Running Interfaces + +Each interface can be run independently: + +[source,bash] +---- +# GraphQL +cd src/interfaces/graphql && cargo run + +# gRPC +cd src/interfaces/grpc && cargo run + +# REST +cd src/interfaces/rest && cargo run +---- + +=== Integration with ECHIDNA Core + +All interfaces communicate with the ECHIDNA core via: - *Option 1:* FFI +(Foreign Function Interface) - direct Rust calls - *Option 2:* IPC +(Inter-Process Communication) - message passing - *Option 3:* Shared +library - dynamic linking + +*TODO:* Implement core integration layer + +=== Architecture + +.... +ECHIDNA Core (Rust) +├── Prover Backends (17 provers) +├── ML Layer (Julia) +└── Parallel Layer (Chapel) + ↓ +Interface Layer +├── GraphQL Server → Port 8081 +├── gRPC Server → Port 50051 +└── REST Server → Port 8000 + ↓ +Clients +├── echidnabot +├── Web UI +├── CLI tools +└── External integrations +.... + +=== Development + +Each interface is a separate Cargo package within the workspace: + +[source,toml] +---- +[workspace] +members = [ + "src/interfaces/graphql", + "src/interfaces/grpc", + "src/interfaces/rest", +] +---- + +Build all interfaces: + +[source,bash] +---- +cargo build --workspace +---- + +Test all interfaces: + +[source,bash] +---- +cargo test --workspace +---- diff --git a/src/interfaces/README.md b/src/interfaces/README.md deleted file mode 100644 index 8af0a0c1..00000000 --- a/src/interfaces/README.md +++ /dev/null @@ -1,107 +0,0 @@ -# ECHIDNA Interfaces - -This directory contains all interface implementations for ECHIDNA theorem proving platform. - -## Available Interfaces - -### GraphQL (`graphql/`) -- **Framework:** Rust + async-graphql + axum -- **Port:** 8081 -- **Playground:** http://localhost:8081/ -- **Features:** - - Type-safe schema with all 17 provers - - Queries: `provers`, `proofState`, `listProofs`, - `suggestTacticsByProofId` (renamed from `suggestTactics` 2026-06-01, - issue #180), `proverStatus`, `health` - - Mutations: `submitProof`, `applyTactic`, `cancelProof`, - `verifyProof` (synchronous one-shot, returns typed `VerifyOutcome` + - optional `mode` / `smtStatus`), `suggestTactics(prover, context, - goalState)` (ad-hoc, ML-backed) - - Subscriptions: `proofUpdates` (planned) - -### gRPC (`grpc/`) -- **Framework:** Rust + tonic + Protocol Buffers -- **Port:** 50051 -- **Proto:** `grpc/proto/echidna.proto` -- **Features:** - - High-performance binary protocol - - Bidirectional streaming for long-running proofs - - RPCs: SubmitProof, GetProofStatus, StreamProof, ApplyTactic, CancelProof - - Neural premise selection via SuggestTactics - -### REST (`rest/`) -- **Framework:** Rust + axum + utoipa (OpenAPI) -- **Port:** 8000 -- **Swagger UI:** http://localhost:8000/swagger-ui -- **Features:** - - RESTful JSON API - - OpenAPI 3.0 specification with Swagger UI - - Standard HTTP verbs (GET, POST, DELETE) - - Endpoints: `/api/v1/provers`, `/api/v1/proofs`, `/api/v1/proofs/:id/tactics` - -## Running Interfaces - -Each interface can be run independently: - -```bash -# GraphQL -cd src/interfaces/graphql && cargo run - -# gRPC -cd src/interfaces/grpc && cargo run - -# REST -cd src/interfaces/rest && cargo run -``` - -## Integration with ECHIDNA Core - -All interfaces communicate with the ECHIDNA core via: -- **Option 1:** FFI (Foreign Function Interface) - direct Rust calls -- **Option 2:** IPC (Inter-Process Communication) - message passing -- **Option 3:** Shared library - dynamic linking - -**TODO:** Implement core integration layer - -## Architecture - -``` -ECHIDNA Core (Rust) -├── Prover Backends (17 provers) -├── ML Layer (Julia) -└── Parallel Layer (Chapel) - ↓ -Interface Layer -├── GraphQL Server → Port 8081 -├── gRPC Server → Port 50051 -└── REST Server → Port 8000 - ↓ -Clients -├── echidnabot -├── Web UI -├── CLI tools -└── External integrations -``` - -## Development - -Each interface is a separate Cargo package within the workspace: - -```toml -[workspace] -members = [ - "src/interfaces/graphql", - "src/interfaces/grpc", - "src/interfaces/rest", -] -``` - -Build all interfaces: -```bash -cargo build --workspace -``` - -Test all interfaces: -```bash -cargo test --workspace -``` diff --git a/src/julia/README.adoc b/src/julia/README.adoc new file mode 100644 index 00000000..264dbabb --- /dev/null +++ b/src/julia/README.adoc @@ -0,0 +1,631 @@ +== SPDX-FileCopyrightText: 2025 ECHIDNA Project Team + +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== ECHIDNA Julia ML Components + +*Neural Premise Selection for Universal Theorem Proving* + +This directory contains the complete Julia-based machine learning system +for ECHIDNA (Extensible Cognitive Hybrid Intelligence for Deductive +Neural Assistance). It generalizes ECHIDNA’s universal neural +architecture to support all 12 theorem provers. + +=== Overview + +*NO PYTHON* - Pure Julia implementation using Flux.jl for deep learning. + +==== Supported Provers (12 Total) + +* *Tier 1 (7)*: Agda, Coq/Rocq, Lean, Isabelle, Z3, CVC5 +* *Tier 2 (3)*: Metamath (easiest!), HOL Light, Mizar +* *Tier 3 (2)*: PVS, ACL2 +* *Tier 4 (1)*: HOL4 + +==== Architecture + +[arabic] +. *Text Encoding*: Transformer-based encoding of proof states and +premises +. *Graph Neural Networks*: Model theorem dependencies and relationships +. *Premise Ranking*: Cross-attention between goals and candidate +premises +. *Multi-Prover*: Unified architecture handling prover-specific syntax + +=== Directory Structure + +.... +julia/ +├── Project.toml # Julia package dependencies +├── EchidnaML.jl # Main module entry point +├── models/ +│ ├── encoder.jl # Multi-prover proof state encoding +│ └── neural_solver.jl # GNN + Transformer architecture +├── training/ +│ └── train.jl # Training pipeline and loss functions +├── inference/ +│ └── predict.jl # Inference engine and caching +└── api/ + └── server.jl # HTTP API server (Oxygen.jl) +.... + +=== Installation + +==== Prerequisites + +* Julia 1.9 or higher +* CUDA-compatible GPU (optional, but recommended) +* Podman (for containerized deployment) + +==== Setup + +[source,bash] +---- +cd /home/user/echidna/src/julia + +# Install dependencies +julia --project=. -e 'using Pkg; Pkg.instantiate()' + +# Optional: Precompile for faster startup +julia --project=. -e 'using Pkg; Pkg.precompile()' +---- + +==== GPU Support + +If you have CUDA available: + +[source,julia] +---- +using CUDA +CUDA.functional() # Should return true +---- + +The system will automatically use GPU acceleration if available. + +=== Quick Start + +==== 1. Basic Usage + +[source,julia] +---- +using EchidnaML + +# Create vocabulary from training corpus +corpus = ["theorem example : ∀ x, P x → Q x", "lemma test : A ∧ B → C", ...] +vocab = create_vocabulary(corpus, min_freq=2, max_vocab=50000) + +# Create neural solver +solver = create_solver(vocab) + +# Define proof state +goal = ProofState( + LEAN, # Prover type + "∀ x, P x → Q x", # Goal + ["P : Type", "Q : Type"], # Context + ["h1 : ∀ x, P x"], # Hypotheses + String[], + 0, + Dict{String, Any}() +) + +# Available premises +premises = [ + Premise("modus_ponens", "∀ P Q, (P → Q) → P → Q", LEAN, nothing, 0.8f0, 0.0f0), + Premise("forall_intro", "∀ P, (∀ x, P x) → P a", LEAN, nothing, 0.6f0, 0.0f0), + # ... more premises +] + +# Predict relevant premises +ranking = predict_premises(solver, goal, premises, top_k=10) + +# Display results +for (premise, score) in zip(ranking.premises, ranking.scores) + println("$(premise.name): $(score)") +end +---- + +==== 2. Training + +[source,julia] +---- +using EchidnaML + +# Load training data +train_data, val_data = load_training_data("path/to/data", train_split=0.8) + +# Create solver +vocab = create_vocabulary(training_corpus) +solver = create_solver(vocab) + +# Configure training +config = TrainingConfig( + num_epochs=100, + learning_rate=1f-4, + lr_schedule=:cosine, + early_stopping_patience=10, + checkpoint_every=5, + save_dir="checkpoints" +) + +# Train +metrics = train_solver!(solver, train_data, val_data, config=config) + +# Save model +save_solver(solver, "trained_models/echidna_v1") +---- + +==== 3. Inference + +[source,julia] +---- +using EchidnaML + +# Load trained model +solver = load_solver("trained_models/echidna_v1") + +# Create inference cache +cache = InferenceCache(1000) + +# Interactive suggestion with diversity +ranking = suggest_next_step( + solver, + current_proof_state, + available_premises, + top_k=5, + use_diversity=true, + estimate_uncertainty=true +) + +# Beam search for proof exploration +beam = beam_search_premises( + solver, + initial_state, + available_premises, + beam_width=5, + max_depth=10 +) + +# Extract proof path from best beam node +proof_path = extract_proof_path(beam[1]) +---- + +==== 4. HTTP API Server + +[source,julia] +---- +using EchidnaML + +# Start server +start_api_server( + "trained_models/echidna_v1", + port=8081, + host="0.0.0.0", + cache_size=1000, + async=true +) + +# Server runs at http://localhost:8081 +---- + +===== API Endpoints + +*Health Check* + +[source,bash] +---- +curl http://localhost:8081/health +---- + +*Predict Premises* + +[source,bash] +---- +curl -X POST http://localhost:8081/predict \ + -H "Content-Type: application/json" \ + -d '{ + "goal": "∀ x, P x → Q x", + "context": ["P : Type", "Q : Type"], + "hypotheses": ["h1 : ∀ x, P x"], + "available_premises": [ + {"name": "mp", "statement": "P → Q → (P → Q)"}, + {"name": "ax1", "statement": "P → (Q → P)"} + ], + "prover": "lean", + "top_k": 10, + "min_confidence": 0.1, + "use_cache": true + }' +---- + +*Interactive Suggestion* + +[source,bash] +---- +curl -X POST http://localhost:8081/suggest \ + -H "Content-Type: application/json" \ + -d '{ + "goal": "theorem_statement", + "context": ["context"], + "hypotheses": ["hyps"], + "available_premises": [...], + "prover": "coq", + "top_k": 5, + "use_diversity": true, + "estimate_uncertainty": true + }' +---- + +*List Provers* + +[source,bash] +---- +curl http://localhost:8081/provers +---- + +*Metrics* + +[source,bash] +---- +curl http://localhost:8081/metrics +---- + +=== Architecture Details + +==== Text Encoder + +* *Embeddings*: Learned token embeddings with positional encoding +* *Transformer*: Multi-head self-attention (8 heads, 6 layers) +* *Dimensions*: 512-dim embeddings, 1024-dim hidden states +* *Prover-Specific*: Custom tokenizers for each prover’s syntax + +==== Graph Neural Network + +* *Node Types*: Premises, theorems, goals +* *Edge Types*: Dependencies, implications, similarities +* *Layers*: 4 Graph Attention (GAT) layers with residual connections +* *Aggregation*: Neighborhood aggregation with learned attention weights + +==== Premise Ranking + +* *Cross-Attention*: Goal queries premise candidates +* *Scoring*: MLP combines goal and premise features +* *Loss*: Combined ranking loss + contrastive learning (InfoNCE) +* *Output*: Scores in [0, 1] indicating premise relevance + +==== Diversity & Confidence + +* *Diversity*: Maximum Marginal Relevance (MMR) for varied suggestions +* *Confidence*: Monte Carlo dropout for uncertainty estimation +* *Caching*: LRU cache for repeated queries + +=== Performance Optimization + +==== GPU Acceleration + +Automatically uses CUDA if available: + +[source,julia] +---- +# Check GPU status +using CUDA +CUDA.functional() # true if GPU available + +# Move model to GPU (automatic in create_solver if GPU detected) +solver = gpu(solver) +---- + +==== Batch Processing + +Process multiple requests efficiently: + +[source,julia] +---- +requests = BatchInferenceRequest(goals, premises, top_k) +results = predict_premises_batch(solver, requests) +---- + +==== Inference Caching + +[source,julia] +---- +cache = InferenceCache(1000) # Cache 1000 most recent queries + +ranking = predict_premises( + solver, goal, premises, + use_cache=true, + cache=cache +) + +# Check cache stats +stats = cache_stats(cache) +println("Hit rate: $(stats.hit_rate)") +---- + +=== Quality Assurance + +==== Running Tests + +[source,julia] +---- +# From Julia REPL +using Pkg +Pkg.test("EchidnaML") +---- + +==== Static Analysis + +[source,julia] +---- +using JET +@report_opt create_solver(vocab) +---- + +==== Dependency Security + +[source,julia] +---- +using Aqua +Aqua.test_all(EchidnaML) +---- + +==== Coverage + +[source,julia] +---- +using Coverage +coverage = process_folder() +---- + +=== Prover-Specific Features + +==== Metamath (Tier 2 - Easiest!) + +[source,julia] +---- +# Metamath uses plain text RPN notation +goal = ProofState(METAMATH, "|- ( ph -> ph )", ...) +premises = [Premise("ax-1", "|- ( ph -> ( ps -> ph ) )", METAMATH, ...)] +---- + +==== Lean 4 + +[source,julia] +---- +# Modern dependent type theory +goal = ProofState(LEAN, "∀ x, P x → Q x", ...) +---- + +==== Isabelle/HOL + +[source,julia] +---- +# Higher-order logic +goal = ProofState(ISABELLE, "⟦ P; Q ⟧ ⟹ P ∧ Q", ...) +---- + +==== SMT Solvers (Z3, CVC5) + +[source,julia] +---- +# SMT-LIB format +goal = ProofState(Z3, "(assert (forall ((x Int)) (> x 0)))", ...) +---- + +=== Integration with ECHIDNA + +==== Rust FFI + +The Julia components integrate with ECHIDNA’s Rust core via FFI: + +[source,rust] +---- +// In Rust (echidna_provers.rs) +use echidna_julia_ffi::predict_premises; + +let ranking = predict_premises(goal, premises, top_k)?; +---- + +==== AffineScript UI + +The HTTP API serves the AffineScript+Deno frontend: + +[source,affinescript] +---- +// In AffineScript +let response = await fetch("/predict", { + method: "POST", + body: JSON.stringify(request) +}) +---- + +=== Deployment + +==== Podman Container + +[source,bash] +---- +# Build container +podman build -t echidna-ml -f Containerfile.julia . + +# Run server +podman run -p 8081:8081 \ + -v ./trained_models:/models:ro \ + echidna-ml \ + julia --project=/app -e 'using EchidnaML; start_api_server("/models/echidna_v1")' +---- + +==== Justfile Integration + +[source,bash] +---- +# From project root +just julia-train # Train model +just julia-serve # Start API server +just julia-test # Run tests +just julia-check # Quality checks +---- + +=== Roadmap + +==== Current Status (v0.1.0) + +✅ Complete architecture implementation ✅ All 12 prover encoders ✅ +Training pipeline ✅ Inference engine ✅ HTTP API server + +==== Next Steps + +* [ ] Implement actual data loaders for each prover +* [ ] Train initial models on theorem datasets +* [ ] Add prover-specific optimizations +* [ ] Implement proof state updates after premise application +* [ ] Add streaming inference for long proofs +* [ ] Multi-GPU distributed training +* [ ] Model compression for edge deployment + +=== Contributing + +See `+/home/user/echidna/CLAUDE.md+` for contribution guidelines. + +==== Code Style + +* Use descriptive variable names +* Add docstrings to all public functions +* Include type annotations +* Write tests for new features +* Run quality checks before committing + +==== Testing New Provers + +To add support for a new prover: + +[arabic] +. Add enum variant to `+ProverType+` in `+EchidnaML.jl+` +. Implement `+ProverEncoder+` subtype in `+encoder.jl+` +. Add tokenization rules +. Add test cases +. Update documentation + +=== License + +Dual licensed under: - MIT License - Palimpsest v0.6 + +See LICENSE files for details. + +=== Support + +* Issues: GitLab issue tracker at +https://github.com/hyperpolymath/echidna +* Documentation: See `+/home/user/echidna/docs/+` +* ECHIDNA Project: https://github.com/hyperpolymath/echidna + +=== References + +* ECHIDNA project: https://github.com/hyperpolymath/echidna +* Flux.jl: https://fluxml.ai/ +* GraphNeuralNetworks.jl: +https://github.com/CarloLucibello/GraphNeuralNetworks.jl +* Oxygen.jl: https://github.com/ndortega/Oxygen.jl + +''''' + +*Built with Julia. No Python. Pure power.* + +=== Saturation-campaign addendum (2026-06-01) + +The saturation campaign on branch `+prover-corpus-saturation+` added 13 +new Rust corpus adapters (lifting coverage from 4 → 17) plus 9 new +per-prover synonym TOMLs and 3 cross-prover dictionaries (`+_msc2020+`, +`+_wordnet_math+`, `+_conceptnet_seed+`). See +`+docs/decisions/2026-06-01-saturation-campaign.md+` for the full ADR. + +The campaign added *two new Julia helper modules* to bridge that new +Rust surface area into the existing GNN training pipeline, without +touching any file the parallel `+wave3/161-162-bench-telemetry-corpus+` +session owns. + +==== `+CorpusLoader+` — `+src/julia/corpus_loader.jl+` + +Reads `+Corpus+` JSON files produced by `+Corpus::save_json+` in +`+src/rust/corpus/mod.rs+`. Public API: + +* `+load_corpus_json(path)+` — reads one adapter’s JSON output, returns +a NamedTuple matching the Rust `+Corpus+` schema field-for-field. +* `+corpus_to_training_examples(corpus, prover_kind)+` — translates +`+CorpusEntry+` rows into `+TrainingExample+`-shaped NamedTuples. The +function does NOT depend on `+training/dataloader.jl+`; it returns the +field bundles that a downstream wiring shim can spread into +`+ProofState(...)+` / `+Premise(...)+` / `+TrainingExample(...)+` +constructors. Schema is documented in the function’s docstring. +* `+corpus_stats(corpus)+` — module count, entry count, hazard count, +per-`+DeclKind+` breakdown. +* `+merge_corpora([…])+` — concatenates multiple loaded corpora into +one, preserving `+(adapter, qualified)+` uniqueness, rebuilding the +by-name / by-qualified / dependents indices over the merged result. + +A self-contained `+corpus_loader_test()+` smoke test sits at the bottom +of the file. + +==== `+SaturationSynonyms+` — `+src/julia/saturation_synonyms.jl+` + +Reads the per-prover synonym TOMLs and the three cross-prover +dictionaries shipped by the campaign. Schema source of truth: +`+src/rust/suggest/synonyms.rs+`. Public API: + +* `+load_prover_synonyms(prover::Symbol, dir)+` — loads +`+dir/.toml+`, returns a `+Dict{String, NamedTuple}+` keyed by +canonical name. +* `+load_msc2020(dir)+`, `+load_wordnet_math(dir)+`, +`+load_conceptnet_seed(dir)+` — three cross-prover taxonomic +dictionaries. +* `+by_semantic_class(table, class)+` — cross-table semantic-class +lookup, mirrors `+SynonymTable::by_semantic_class+`. +* `+expand_aliases(name, table)+` — given any canonical-or-alias name, +returns the rest of the synonym group; mirrors +`+SynonymTable::alternatives+`. + +==== Why this lives in Julia + +The new Rust adapters emit structured `+Corpus+` JSON that downstream +training code needs to ingest as `+TrainingExample+` rows for the Flux / +GNN learner. Doing the translation in Julia (rather than burning it into +the Rust side) keeps the training-pipeline schema mutable under +sibling-branch ownership without churning Rust. + +==== Worked example (described, NOT invoked) + +[source,julia] +---- +using JSON +include("src/julia/corpus_loader.jl"); using .CorpusLoader + +# Load one adapter's output. +corpus = load_corpus_json("data/corpus/lean.json") +@info corpus_stats(corpus) + +# Translate to TrainingExample-shaped rows. +rows = corpus_to_training_examples(corpus, :lean) + +# Downstream consumer (NOT invoked here — see hand-off doc): +# for row in rows +# ps = ProofState(LEAN, row.proof_state_fields.goal, +# row.proof_state_fields.context, …) +# prems = [Premise(p.name, p.statement, LEAN, nothing, +# p.frequency_score, p.relevance_score) +# for p in row.candidate_premise_field_rows] +# push!(examples, TrainingExample(ps, prems, row.relevant_indices, LEAN)) +# end +# dataset = TrainingDataset(examples; batch_size = 32) +---- + +==== Caveat: deliberate hand-off boundary + +`+src/julia/training/train.jl+`, `+src/julia/run_training.jl+`, and +`+src/julia/training/dataloader.jl+` are *NOT modified by this +campaign*. They are owned by the parallel +`+wave3/161-162-bench-telemetry-corpus+` session (chapel bench + +telemetry work). The integration commit that wires `+CorpusLoader+` +output INTO the training pipeline (a ~50-line addition to +`+run_training.jl+`) is a deliberate hand-off, landing AFTER both +branches merge. See `+docs/architecture/JULIA-SATURATION-HOOKS.md+` for +the topology, the field-shape contract, and the follow-up wiring PR +sketch. diff --git a/src/julia/README.md b/src/julia/README.md deleted file mode 100644 index 4e38b5fb..00000000 --- a/src/julia/README.md +++ /dev/null @@ -1,599 +0,0 @@ -# SPDX-FileCopyrightText: 2025 ECHIDNA Project Team -# SPDX-License-Identifier: CC-BY-SA-4.0 - -# ECHIDNA Julia ML Components - -**Neural Premise Selection for Universal Theorem Proving** - -This directory contains the complete Julia-based machine learning system for ECHIDNA (Extensible Cognitive Hybrid Intelligence for Deductive Neural Assistance). It generalizes ECHIDNA's universal neural architecture to support all 12 theorem provers. - -## Overview - -**NO PYTHON** - Pure Julia implementation using Flux.jl for deep learning. - -### Supported Provers (12 Total) - -- **Tier 1 (7)**: Agda, Coq/Rocq, Lean, Isabelle, Z3, CVC5 -- **Tier 2 (3)**: Metamath (easiest!), HOL Light, Mizar -- **Tier 3 (2)**: PVS, ACL2 -- **Tier 4 (1)**: HOL4 - -### Architecture - -1. **Text Encoding**: Transformer-based encoding of proof states and premises -2. **Graph Neural Networks**: Model theorem dependencies and relationships -3. **Premise Ranking**: Cross-attention between goals and candidate premises -4. **Multi-Prover**: Unified architecture handling prover-specific syntax - -## Directory Structure - -``` -julia/ -├── Project.toml # Julia package dependencies -├── EchidnaML.jl # Main module entry point -├── models/ -│ ├── encoder.jl # Multi-prover proof state encoding -│ └── neural_solver.jl # GNN + Transformer architecture -├── training/ -│ └── train.jl # Training pipeline and loss functions -├── inference/ -│ └── predict.jl # Inference engine and caching -└── api/ - └── server.jl # HTTP API server (Oxygen.jl) -``` - -## Installation - -### Prerequisites - -- Julia 1.9 or higher -- CUDA-compatible GPU (optional, but recommended) -- Podman (for containerized deployment) - -### Setup - -```bash -cd /home/user/echidna/src/julia - -# Install dependencies -julia --project=. -e 'using Pkg; Pkg.instantiate()' - -# Optional: Precompile for faster startup -julia --project=. -e 'using Pkg; Pkg.precompile()' -``` - -### GPU Support - -If you have CUDA available: - -```julia -using CUDA -CUDA.functional() # Should return true -``` - -The system will automatically use GPU acceleration if available. - -## Quick Start - -### 1. Basic Usage - -```julia -using EchidnaML - -# Create vocabulary from training corpus -corpus = ["theorem example : ∀ x, P x → Q x", "lemma test : A ∧ B → C", ...] -vocab = create_vocabulary(corpus, min_freq=2, max_vocab=50000) - -# Create neural solver -solver = create_solver(vocab) - -# Define proof state -goal = ProofState( - LEAN, # Prover type - "∀ x, P x → Q x", # Goal - ["P : Type", "Q : Type"], # Context - ["h1 : ∀ x, P x"], # Hypotheses - String[], - 0, - Dict{String, Any}() -) - -# Available premises -premises = [ - Premise("modus_ponens", "∀ P Q, (P → Q) → P → Q", LEAN, nothing, 0.8f0, 0.0f0), - Premise("forall_intro", "∀ P, (∀ x, P x) → P a", LEAN, nothing, 0.6f0, 0.0f0), - # ... more premises -] - -# Predict relevant premises -ranking = predict_premises(solver, goal, premises, top_k=10) - -# Display results -for (premise, score) in zip(ranking.premises, ranking.scores) - println("$(premise.name): $(score)") -end -``` - -### 2. Training - -```julia -using EchidnaML - -# Load training data -train_data, val_data = load_training_data("path/to/data", train_split=0.8) - -# Create solver -vocab = create_vocabulary(training_corpus) -solver = create_solver(vocab) - -# Configure training -config = TrainingConfig( - num_epochs=100, - learning_rate=1f-4, - lr_schedule=:cosine, - early_stopping_patience=10, - checkpoint_every=5, - save_dir="checkpoints" -) - -# Train -metrics = train_solver!(solver, train_data, val_data, config=config) - -# Save model -save_solver(solver, "trained_models/echidna_v1") -``` - -### 3. Inference - -```julia -using EchidnaML - -# Load trained model -solver = load_solver("trained_models/echidna_v1") - -# Create inference cache -cache = InferenceCache(1000) - -# Interactive suggestion with diversity -ranking = suggest_next_step( - solver, - current_proof_state, - available_premises, - top_k=5, - use_diversity=true, - estimate_uncertainty=true -) - -# Beam search for proof exploration -beam = beam_search_premises( - solver, - initial_state, - available_premises, - beam_width=5, - max_depth=10 -) - -# Extract proof path from best beam node -proof_path = extract_proof_path(beam[1]) -``` - -### 4. HTTP API Server - -```julia -using EchidnaML - -# Start server -start_api_server( - "trained_models/echidna_v1", - port=8081, - host="0.0.0.0", - cache_size=1000, - async=true -) - -# Server runs at http://localhost:8081 -``` - -#### API Endpoints - -**Health Check** -```bash -curl http://localhost:8081/health -``` - -**Predict Premises** -```bash -curl -X POST http://localhost:8081/predict \ - -H "Content-Type: application/json" \ - -d '{ - "goal": "∀ x, P x → Q x", - "context": ["P : Type", "Q : Type"], - "hypotheses": ["h1 : ∀ x, P x"], - "available_premises": [ - {"name": "mp", "statement": "P → Q → (P → Q)"}, - {"name": "ax1", "statement": "P → (Q → P)"} - ], - "prover": "lean", - "top_k": 10, - "min_confidence": 0.1, - "use_cache": true - }' -``` - -**Interactive Suggestion** -```bash -curl -X POST http://localhost:8081/suggest \ - -H "Content-Type: application/json" \ - -d '{ - "goal": "theorem_statement", - "context": ["context"], - "hypotheses": ["hyps"], - "available_premises": [...], - "prover": "coq", - "top_k": 5, - "use_diversity": true, - "estimate_uncertainty": true - }' -``` - -**List Provers** -```bash -curl http://localhost:8081/provers -``` - -**Metrics** -```bash -curl http://localhost:8081/metrics -``` - -## Architecture Details - -### Text Encoder - -- **Embeddings**: Learned token embeddings with positional encoding -- **Transformer**: Multi-head self-attention (8 heads, 6 layers) -- **Dimensions**: 512-dim embeddings, 1024-dim hidden states -- **Prover-Specific**: Custom tokenizers for each prover's syntax - -### Graph Neural Network - -- **Node Types**: Premises, theorems, goals -- **Edge Types**: Dependencies, implications, similarities -- **Layers**: 4 Graph Attention (GAT) layers with residual connections -- **Aggregation**: Neighborhood aggregation with learned attention weights - -### Premise Ranking - -- **Cross-Attention**: Goal queries premise candidates -- **Scoring**: MLP combines goal and premise features -- **Loss**: Combined ranking loss + contrastive learning (InfoNCE) -- **Output**: Scores in [0, 1] indicating premise relevance - -### Diversity & Confidence - -- **Diversity**: Maximum Marginal Relevance (MMR) for varied suggestions -- **Confidence**: Monte Carlo dropout for uncertainty estimation -- **Caching**: LRU cache for repeated queries - -## Performance Optimization - -### GPU Acceleration - -Automatically uses CUDA if available: - -```julia -# Check GPU status -using CUDA -CUDA.functional() # true if GPU available - -# Move model to GPU (automatic in create_solver if GPU detected) -solver = gpu(solver) -``` - -### Batch Processing - -Process multiple requests efficiently: - -```julia -requests = BatchInferenceRequest(goals, premises, top_k) -results = predict_premises_batch(solver, requests) -``` - -### Inference Caching - -```julia -cache = InferenceCache(1000) # Cache 1000 most recent queries - -ranking = predict_premises( - solver, goal, premises, - use_cache=true, - cache=cache -) - -# Check cache stats -stats = cache_stats(cache) -println("Hit rate: $(stats.hit_rate)") -``` - -## Quality Assurance - -### Running Tests - -```julia -# From Julia REPL -using Pkg -Pkg.test("EchidnaML") -``` - -### Static Analysis - -```julia -using JET -@report_opt create_solver(vocab) -``` - -### Dependency Security - -```julia -using Aqua -Aqua.test_all(EchidnaML) -``` - -### Coverage - -```julia -using Coverage -coverage = process_folder() -``` - -## Prover-Specific Features - -### Metamath (Tier 2 - Easiest!) - -```julia -# Metamath uses plain text RPN notation -goal = ProofState(METAMATH, "|- ( ph -> ph )", ...) -premises = [Premise("ax-1", "|- ( ph -> ( ps -> ph ) )", METAMATH, ...)] -``` - -### Lean 4 - -```julia -# Modern dependent type theory -goal = ProofState(LEAN, "∀ x, P x → Q x", ...) -``` - -### Isabelle/HOL - -```julia -# Higher-order logic -goal = ProofState(ISABELLE, "⟦ P; Q ⟧ ⟹ P ∧ Q", ...) -``` - -### SMT Solvers (Z3, CVC5) - -```julia -# SMT-LIB format -goal = ProofState(Z3, "(assert (forall ((x Int)) (> x 0)))", ...) -``` - -## Integration with ECHIDNA - -### Rust FFI - -The Julia components integrate with ECHIDNA's Rust core via FFI: - -```rust -// In Rust (echidna_provers.rs) -use echidna_julia_ffi::predict_premises; - -let ranking = predict_premises(goal, premises, top_k)?; -``` - -### AffineScript UI - -The HTTP API serves the AffineScript+Deno frontend: - -```affinescript -// In AffineScript -let response = await fetch("/predict", { - method: "POST", - body: JSON.stringify(request) -}) -``` - -## Deployment - -### Podman Container - -```bash -# Build container -podman build -t echidna-ml -f Containerfile.julia . - -# Run server -podman run -p 8081:8081 \ - -v ./trained_models:/models:ro \ - echidna-ml \ - julia --project=/app -e 'using EchidnaML; start_api_server("/models/echidna_v1")' -``` - -### Justfile Integration - -```bash -# From project root -just julia-train # Train model -just julia-serve # Start API server -just julia-test # Run tests -just julia-check # Quality checks -``` - -## Roadmap - -### Current Status (v0.1.0) - -✅ Complete architecture implementation -✅ All 12 prover encoders -✅ Training pipeline -✅ Inference engine -✅ HTTP API server - -### Next Steps - -- [ ] Implement actual data loaders for each prover -- [ ] Train initial models on theorem datasets -- [ ] Add prover-specific optimizations -- [ ] Implement proof state updates after premise application -- [ ] Add streaming inference for long proofs -- [ ] Multi-GPU distributed training -- [ ] Model compression for edge deployment - -## Contributing - -See `/home/user/echidna/CLAUDE.md` for contribution guidelines. - -### Code Style - -- Use descriptive variable names -- Add docstrings to all public functions -- Include type annotations -- Write tests for new features -- Run quality checks before committing - -### Testing New Provers - -To add support for a new prover: - -1. Add enum variant to `ProverType` in `EchidnaML.jl` -2. Implement `ProverEncoder` subtype in `encoder.jl` -3. Add tokenization rules -4. Add test cases -5. Update documentation - -## License - -Dual licensed under: -- MIT License -- Palimpsest v0.6 - -See LICENSE files for details. - -## Support - -- Issues: GitLab issue tracker at https://github.com/hyperpolymath/echidna -- Documentation: See `/home/user/echidna/docs/` -- ECHIDNA Project: https://github.com/hyperpolymath/echidna - -## References - -- ECHIDNA project: https://github.com/hyperpolymath/echidna -- Flux.jl: https://fluxml.ai/ -- GraphNeuralNetworks.jl: https://github.com/CarloLucibello/GraphNeuralNetworks.jl -- Oxygen.jl: https://github.com/ndortega/Oxygen.jl - ---- - -**Built with Julia. No Python. Pure power.** - - - -## Saturation-campaign addendum (2026-06-01) - -The saturation campaign on branch `prover-corpus-saturation` added 13 -new Rust corpus adapters (lifting coverage from 4 → 17) plus 9 new -per-prover synonym TOMLs and 3 cross-prover dictionaries -(`_msc2020`, `_wordnet_math`, `_conceptnet_seed`). See -`docs/decisions/2026-06-01-saturation-campaign.md` for the full ADR. - -The campaign added **two new Julia helper modules** to bridge that new -Rust surface area into the existing GNN training pipeline, without -touching any file the parallel `wave3/161-162-bench-telemetry-corpus` -session owns. - -### `CorpusLoader` — `src/julia/corpus_loader.jl` - -Reads `Corpus` JSON files produced by `Corpus::save_json` in -`src/rust/corpus/mod.rs`. Public API: - -- `load_corpus_json(path)` — reads one adapter's JSON output, returns - a NamedTuple matching the Rust `Corpus` schema field-for-field. -- `corpus_to_training_examples(corpus, prover_kind)` — translates - `CorpusEntry` rows into `TrainingExample`-shaped NamedTuples. The - function does NOT depend on `training/dataloader.jl`; it returns the - field bundles that a downstream wiring shim can spread into - `ProofState(...)` / `Premise(...)` / `TrainingExample(...)` - constructors. Schema is documented in the function's docstring. -- `corpus_stats(corpus)` — module count, entry count, hazard count, - per-`DeclKind` breakdown. -- `merge_corpora([…])` — concatenates multiple loaded corpora into - one, preserving `(adapter, qualified)` uniqueness, rebuilding the - by-name / by-qualified / dependents indices over the merged result. - -A self-contained `corpus_loader_test()` smoke test sits at the bottom -of the file. - -### `SaturationSynonyms` — `src/julia/saturation_synonyms.jl` - -Reads the per-prover synonym TOMLs and the three cross-prover -dictionaries shipped by the campaign. Schema source of truth: -`src/rust/suggest/synonyms.rs`. Public API: - -- `load_prover_synonyms(prover::Symbol, dir)` — loads `dir/.toml`, - returns a `Dict{String, NamedTuple}` keyed by canonical name. -- `load_msc2020(dir)`, `load_wordnet_math(dir)`, - `load_conceptnet_seed(dir)` — three cross-prover taxonomic - dictionaries. -- `by_semantic_class(table, class)` — cross-table semantic-class - lookup, mirrors `SynonymTable::by_semantic_class`. -- `expand_aliases(name, table)` — given any canonical-or-alias name, - returns the rest of the synonym group; mirrors - `SynonymTable::alternatives`. - -### Why this lives in Julia - -The new Rust adapters emit structured `Corpus` JSON that downstream -training code needs to ingest as `TrainingExample` rows for the Flux / -GNN learner. Doing the translation in Julia (rather than burning it -into the Rust side) keeps the training-pipeline schema mutable -under sibling-branch ownership without churning Rust. - -### Worked example (described, NOT invoked) - -```julia -using JSON -include("src/julia/corpus_loader.jl"); using .CorpusLoader - -# Load one adapter's output. -corpus = load_corpus_json("data/corpus/lean.json") -@info corpus_stats(corpus) - -# Translate to TrainingExample-shaped rows. -rows = corpus_to_training_examples(corpus, :lean) - -# Downstream consumer (NOT invoked here — see hand-off doc): -# for row in rows -# ps = ProofState(LEAN, row.proof_state_fields.goal, -# row.proof_state_fields.context, …) -# prems = [Premise(p.name, p.statement, LEAN, nothing, -# p.frequency_score, p.relevance_score) -# for p in row.candidate_premise_field_rows] -# push!(examples, TrainingExample(ps, prems, row.relevant_indices, LEAN)) -# end -# dataset = TrainingDataset(examples; batch_size = 32) -``` - -### Caveat: deliberate hand-off boundary - -`src/julia/training/train.jl`, `src/julia/run_training.jl`, and -`src/julia/training/dataloader.jl` are **NOT modified by this -campaign**. They are owned by the parallel -`wave3/161-162-bench-telemetry-corpus` session (chapel bench + -telemetry work). The integration commit that wires `CorpusLoader` -output INTO the training pipeline (a ~50-line addition to -`run_training.jl`) is a deliberate hand-off, landing AFTER both -branches merge. See `docs/architecture/JULIA-SATURATION-HOOKS.md` for -the topology, the field-shape contract, and the follow-up wiring PR -sketch. diff --git a/tests/README.adoc b/tests/README.adoc new file mode 100644 index 00000000..cf391797 --- /dev/null +++ b/tests/README.adoc @@ -0,0 +1,436 @@ +== ECHIDNA Test Infrastructure + +Comprehensive testing framework for the ECHIDNA neurosymbolic theorem +proving platform. + +=== Overview + +This test suite provides: - *Integration tests* - Full prover pipeline +testing for all 12 supported provers - *Property-based tests* - +Automated invariant checking with proptest - *Benchmarks* - Performance +regression testing with criterion - *Proof validation* - Automated +verification of proof examples - *Test utilities* - Mock backends, +generators, and assertion helpers + +=== Directory Structure + +.... +tests/ +├── README.md # This file +├── common/ # Test utilities +│ ├── mod.rs # Main utilities module +│ ├── mock_prover.rs # Mock prover backend for testing +│ ├── generators.rs # Property-based test generators +│ └── assertions.rs # Custom assertion helpers +├── integration_tests.rs # Integration tests for all provers +├── property_tests.rs # Property-based tests with proptest +└── test_agda_backend.rs # Agda-specific tests + +benches/ +├── parser_bench.rs # Parser performance benchmarks +└── verification_bench.rs # Verification performance benchmarks + +scripts/ +└── test-proofs.sh # Proof validation script +.... + +=== Running Tests + +==== Unit Tests + +Run all tests (including integration tests): + +[source,bash] +---- +cargo test +---- + +Run tests for a specific module: + +[source,bash] +---- +cargo test integration_tests +cargo test property_tests +---- + +Run tests with output: + +[source,bash] +---- +cargo test -- --nocapture +---- + +==== Integration Tests + +Integration tests cover all 12 theorem provers: + +*Tier 1 (6 provers):* - Agda - Coq/Rocq - Lean - Isabelle - Z3 - CVC5 + +*Tier 2 (3 provers):* - Metamath - HOL Light - Mizar + +*Tier 3 (2 provers):* - PVS - ACL2 + +*Tier 4 (1 prover):* - HOL4 + +Run integration tests: + +[source,bash] +---- +cargo test --test integration_tests +---- + +*Note:* Tests automatically skip provers that are not installed on your +system. + +==== Property-Based Tests + +Property-based tests use proptest to verify invariants: - Term +serialization roundtrips - Parser invariants - Tactic composition - Type +system properties + +Run property tests: + +[source,bash] +---- +cargo test --test property_tests +---- + +==== Benchmarks + +Performance benchmarks using criterion: + +Run all benchmarks: + +[source,bash] +---- +cargo bench +---- + +Run specific benchmark suite: + +[source,bash] +---- +cargo bench parser_bench +cargo bench verification_bench +---- + +View benchmark reports: + +[source,bash] +---- +open target/criterion/report/index.html +---- + +==== Proof Validation + +Validate all proof examples using the automated script: + +[source,bash] +---- +# Test all provers +./scripts/test-proofs.sh + +# Test specific prover +./scripts/test-proofs.sh agda +./scripts/test-proofs.sh coq +./scripts/test-proofs.sh z3 +---- + +Available provers: `+agda+`, `+coq+`, `+lean+`, `+isabelle+`, `+z3+`, +`+cvc5+`, `+metamath+`, `+mizar+` + +=== Test Utilities + +==== Mock Prover Backend + +The `+MockProver+` allows testing without real prover installations: + +[source,rust] +---- +use echidna::provers::ProverKind; +use crate::common::mock_prover::MockProver; + +let mock = MockProver::new(ProverKind::Agda); +mock.add_verify_result(Ok(true)); + +let state = simple_proof_state(); +let result = mock.verify_proof(&state).await; +assert!(result.unwrap()); +---- + +==== Test Generators + +Property-based test generators for core types: + +[source,rust] +---- +use crate::common::generators; +use proptest::prelude::*; + +proptest! { + #[test] + fn test_term_roundtrip(term in generators::arb_term()) { + let json = serde_json::to_string(&term).unwrap(); + let deserialized: Term = serde_json::from_str(&json).unwrap(); + assert_eq!(term, deserialized); + } +} +---- + +Available generators: - `+arb_term()+` - Generate arbitrary terms - +`+arb_goal()+` - Generate proof goals - `+arb_proof_state()+` - Generate +proof states - `+arb_tactic()+` - Generate tactics - `+arb_context()+` - +Generate contexts + +==== Custom Assertions + +Specialized assertion helpers: + +[source,rust] +---- +use crate::common::assertions::*; + +// Alpha-equivalence +assert_alpha_equivalent(&lambda1, &lambda2); + +// Proof state validity +assert_valid_proof_state(&state); + +// Proof progress +assert_progress(&before_state, &after_state); + +// Well-formed terms +assert_well_formed_term(&term); + +// Serialization roundtrip +assert_serialization_roundtrip(&value); +---- + +==== Helper Functions + +Common test utilities: + +[source,rust] +---- +use crate::common::*; + +// Create test configurations +let config = test_prover_config(ProverKind::Agda); + +// Find proof files +let files = find_proof_files(ProverKind::Coq); + +// Check prover availability +if is_prover_available(ProverKind::Z3) { + // Run test +} + +// Create test terms +let simple = simple_term(); +let lambda = lambda_term(); +let pi = pi_term(); +let complex = complex_term(); + +// Create test proof states +let state = simple_proof_state(); +let multi = multi_goal_proof_state(); +---- + +=== Test Categories + +==== 1. Parser Tests + +Test proof parsing for each prover: - Valid syntax parsing - Error +handling for invalid syntax - File I/O operations - Performance +benchmarks + +==== 2. Verification Tests + +Test proof verification: - Valid proof verification - Invalid proof +rejection - Timeout handling - Cross-prover verification + +==== 3. Tactic Tests + +Test interactive proof tactics: - Basic tactics (intro, reflexivity, +assumption) - Advanced tactics (apply, rewrite, induction) - Tactic +composition - Error handling + +==== 4. Translation Tests + +Test cross-prover term translation: - Agda ↔ Coq - Z3 ↔ CVC5 - Lean ↔ +Isabelle - Term equivalence preservation + +==== 5. Export Tests + +Test proof export to different formats: - Export to native prover syntax +- Roundtrip conversions - Format validation + +==== 6. Error Handling Tests + +Test error conditions: - Invalid syntax - Type errors - Timeout errors - +Missing dependencies + +=== Writing New Tests + +==== Integration Test Template + +[source,rust] +---- +#[tokio::test] +async fn test_new_feature() { + if !common::is_prover_available(ProverKind::Agda) { + eprintln!("Skipping: Agda not available"); + return; + } + + let config = common::test_prover_config(ProverKind::Agda); + let backend = ProverFactory::create(ProverKind::Agda, config).unwrap(); + + let content = r#" + module Test where + -- Your test content + "#; + + let result = backend.parse_string(content).await; + assert!(result.is_ok()); +} +---- + +==== Property Test Template + +[source,rust] +---- +proptest! { + #[test] + fn test_invariant(term in generators::arb_term()) { + // Test your invariant + prop_assert!(some_property(&term)); + } +} +---- + +==== Benchmark Template + +[source,rust] +---- +fn bench_operation(c: &mut Criterion) { + c.bench_function("operation_name", |b| { + b.iter(|| { + // Operation to benchmark + black_box(expensive_operation()); + }); + }); +} +---- + +=== Continuous Integration + +Tests are designed to work in CI environments: - Automatic prover +detection - Graceful skipping of unavailable provers - Parallel test +execution - HTML benchmark reports + +Example CI configuration: + +[source,yaml] +---- +test: + script: + - cargo test --all + - cargo bench --no-run + - ./scripts/test-proofs.sh +---- + +=== Dependencies + +Test dependencies (from Cargo.toml): - `+tokio-test+` - Async test +utilities - `+proptest+` - Property-based testing - `+criterion+` - +Benchmarking framework - `+mockall+` - Mock object generation - +`+tempfile+` - Temporary file creation - `+pretty_assertions+` - Better +assertion output - `+quickcheck+` - Alternative property testing - +`+which+` - Executable detection + +=== Coverage + +Generate test coverage reports: + +[source,bash] +---- +# Install tarpaulin +cargo install cargo-tarpaulin + +# Generate coverage +cargo tarpaulin --out Html +---- + +=== Performance + +Benchmark results are saved to: - `+target/criterion/+` - Detailed +benchmark data - `+target/criterion/report/+` - HTML reports + +Track performance regressions by comparing benchmark results across +commits. + +=== Best Practices + +[arabic] +. *Test Isolation* - Each test should be independent +. *Prover Detection* - Always check if prover is available +. *Timeout Handling* - Use reasonable timeouts (10-30s for tests) +. *Error Messages* - Provide clear failure messages +. *Property Tests* - Test invariants, not specific values +. *Benchmarks* - Use `+black_box+` to prevent optimization +. *Mock Backends* - Use for unit tests, real backends for integration + +=== Troubleshooting + +==== Tests Failing + +[arabic] +. Check prover installation: ++ +[source,bash] +---- +which agda coqc lean isabelle z3 cvc5 +---- +. Check prover versions: ++ +[source,bash] +---- +agda --version +coqc --version +---- +. Run with verbose output: ++ +[source,bash] +---- +cargo test -- --nocapture --test-threads=1 +---- + +==== Benchmarks Not Running + +[arabic] +. Build in release mode: ++ +[source,bash] +---- +cargo bench +---- +. Check benchmark configuration in Cargo.toml + +==== Proof Validation Failing + +[arabic] +. Check proof file syntax +. Verify prover can compile file directly +. Check environment variables (e.g., `+MIZAR_HOME+`) + +=== Contributing + +When adding new tests: 1. Add to appropriate test file (integration, +property, or unit) 2. Use common test utilities where possible 3. Add +documentation for new test patterns 4. Update this README if adding new +test categories 5. Ensure tests work with and without provers installed + +''''' + +*Last Updated:* 2025-11-22 *Maintained By:* ECHIDNA Project Team diff --git a/tests/README.md b/tests/README.md deleted file mode 100644 index d9c778fc..00000000 --- a/tests/README.md +++ /dev/null @@ -1,435 +0,0 @@ -# ECHIDNA Test Infrastructure - -Comprehensive testing framework for the ECHIDNA neurosymbolic theorem proving platform. - -## Overview - -This test suite provides: -- **Integration tests** - Full prover pipeline testing for all 12 supported provers -- **Property-based tests** - Automated invariant checking with proptest -- **Benchmarks** - Performance regression testing with criterion -- **Proof validation** - Automated verification of proof examples -- **Test utilities** - Mock backends, generators, and assertion helpers - -## Directory Structure - -``` -tests/ -├── README.md # This file -├── common/ # Test utilities -│ ├── mod.rs # Main utilities module -│ ├── mock_prover.rs # Mock prover backend for testing -│ ├── generators.rs # Property-based test generators -│ └── assertions.rs # Custom assertion helpers -├── integration_tests.rs # Integration tests for all provers -├── property_tests.rs # Property-based tests with proptest -└── test_agda_backend.rs # Agda-specific tests - -benches/ -├── parser_bench.rs # Parser performance benchmarks -└── verification_bench.rs # Verification performance benchmarks - -scripts/ -└── test-proofs.sh # Proof validation script -``` - -## Running Tests - -### Unit Tests - -Run all tests (including integration tests): -```bash -cargo test -``` - -Run tests for a specific module: -```bash -cargo test integration_tests -cargo test property_tests -``` - -Run tests with output: -```bash -cargo test -- --nocapture -``` - -### Integration Tests - -Integration tests cover all 12 theorem provers: - -**Tier 1 (6 provers):** -- Agda -- Coq/Rocq -- Lean -- Isabelle -- Z3 -- CVC5 - -**Tier 2 (3 provers):** -- Metamath -- HOL Light -- Mizar - -**Tier 3 (2 provers):** -- PVS -- ACL2 - -**Tier 4 (1 prover):** -- HOL4 - -Run integration tests: -```bash -cargo test --test integration_tests -``` - -**Note:** Tests automatically skip provers that are not installed on your system. - -### Property-Based Tests - -Property-based tests use proptest to verify invariants: -- Term serialization roundtrips -- Parser invariants -- Tactic composition -- Type system properties - -Run property tests: -```bash -cargo test --test property_tests -``` - -### Benchmarks - -Performance benchmarks using criterion: - -Run all benchmarks: -```bash -cargo bench -``` - -Run specific benchmark suite: -```bash -cargo bench parser_bench -cargo bench verification_bench -``` - -View benchmark reports: -```bash -open target/criterion/report/index.html -``` - -### Proof Validation - -Validate all proof examples using the automated script: - -```bash -# Test all provers -./scripts/test-proofs.sh - -# Test specific prover -./scripts/test-proofs.sh agda -./scripts/test-proofs.sh coq -./scripts/test-proofs.sh z3 -``` - -Available provers: `agda`, `coq`, `lean`, `isabelle`, `z3`, `cvc5`, `metamath`, `mizar` - -## Test Utilities - -### Mock Prover Backend - -The `MockProver` allows testing without real prover installations: - -```rust -use echidna::provers::ProverKind; -use crate::common::mock_prover::MockProver; - -let mock = MockProver::new(ProverKind::Agda); -mock.add_verify_result(Ok(true)); - -let state = simple_proof_state(); -let result = mock.verify_proof(&state).await; -assert!(result.unwrap()); -``` - -### Test Generators - -Property-based test generators for core types: - -```rust -use crate::common::generators; -use proptest::prelude::*; - -proptest! { - #[test] - fn test_term_roundtrip(term in generators::arb_term()) { - let json = serde_json::to_string(&term).unwrap(); - let deserialized: Term = serde_json::from_str(&json).unwrap(); - assert_eq!(term, deserialized); - } -} -``` - -Available generators: -- `arb_term()` - Generate arbitrary terms -- `arb_goal()` - Generate proof goals -- `arb_proof_state()` - Generate proof states -- `arb_tactic()` - Generate tactics -- `arb_context()` - Generate contexts - -### Custom Assertions - -Specialized assertion helpers: - -```rust -use crate::common::assertions::*; - -// Alpha-equivalence -assert_alpha_equivalent(&lambda1, &lambda2); - -// Proof state validity -assert_valid_proof_state(&state); - -// Proof progress -assert_progress(&before_state, &after_state); - -// Well-formed terms -assert_well_formed_term(&term); - -// Serialization roundtrip -assert_serialization_roundtrip(&value); -``` - -### Helper Functions - -Common test utilities: - -```rust -use crate::common::*; - -// Create test configurations -let config = test_prover_config(ProverKind::Agda); - -// Find proof files -let files = find_proof_files(ProverKind::Coq); - -// Check prover availability -if is_prover_available(ProverKind::Z3) { - // Run test -} - -// Create test terms -let simple = simple_term(); -let lambda = lambda_term(); -let pi = pi_term(); -let complex = complex_term(); - -// Create test proof states -let state = simple_proof_state(); -let multi = multi_goal_proof_state(); -``` - -## Test Categories - -### 1. Parser Tests - -Test proof parsing for each prover: -- Valid syntax parsing -- Error handling for invalid syntax -- File I/O operations -- Performance benchmarks - -### 2. Verification Tests - -Test proof verification: -- Valid proof verification -- Invalid proof rejection -- Timeout handling -- Cross-prover verification - -### 3. Tactic Tests - -Test interactive proof tactics: -- Basic tactics (intro, reflexivity, assumption) -- Advanced tactics (apply, rewrite, induction) -- Tactic composition -- Error handling - -### 4. Translation Tests - -Test cross-prover term translation: -- Agda ↔ Coq -- Z3 ↔ CVC5 -- Lean ↔ Isabelle -- Term equivalence preservation - -### 5. Export Tests - -Test proof export to different formats: -- Export to native prover syntax -- Roundtrip conversions -- Format validation - -### 6. Error Handling Tests - -Test error conditions: -- Invalid syntax -- Type errors -- Timeout errors -- Missing dependencies - -## Writing New Tests - -### Integration Test Template - -```rust -#[tokio::test] -async fn test_new_feature() { - if !common::is_prover_available(ProverKind::Agda) { - eprintln!("Skipping: Agda not available"); - return; - } - - let config = common::test_prover_config(ProverKind::Agda); - let backend = ProverFactory::create(ProverKind::Agda, config).unwrap(); - - let content = r#" - module Test where - -- Your test content - "#; - - let result = backend.parse_string(content).await; - assert!(result.is_ok()); -} -``` - -### Property Test Template - -```rust -proptest! { - #[test] - fn test_invariant(term in generators::arb_term()) { - // Test your invariant - prop_assert!(some_property(&term)); - } -} -``` - -### Benchmark Template - -```rust -fn bench_operation(c: &mut Criterion) { - c.bench_function("operation_name", |b| { - b.iter(|| { - // Operation to benchmark - black_box(expensive_operation()); - }); - }); -} -``` - -## Continuous Integration - -Tests are designed to work in CI environments: -- Automatic prover detection -- Graceful skipping of unavailable provers -- Parallel test execution -- HTML benchmark reports - -Example CI configuration: -```yaml -test: - script: - - cargo test --all - - cargo bench --no-run - - ./scripts/test-proofs.sh -``` - -## Dependencies - -Test dependencies (from Cargo.toml): -- `tokio-test` - Async test utilities -- `proptest` - Property-based testing -- `criterion` - Benchmarking framework -- `mockall` - Mock object generation -- `tempfile` - Temporary file creation -- `pretty_assertions` - Better assertion output -- `quickcheck` - Alternative property testing -- `which` - Executable detection - -## Coverage - -Generate test coverage reports: -```bash -# Install tarpaulin -cargo install cargo-tarpaulin - -# Generate coverage -cargo tarpaulin --out Html -``` - -## Performance - -Benchmark results are saved to: -- `target/criterion/` - Detailed benchmark data -- `target/criterion/report/` - HTML reports - -Track performance regressions by comparing benchmark results across commits. - -## Best Practices - -1. **Test Isolation** - Each test should be independent -2. **Prover Detection** - Always check if prover is available -3. **Timeout Handling** - Use reasonable timeouts (10-30s for tests) -4. **Error Messages** - Provide clear failure messages -5. **Property Tests** - Test invariants, not specific values -6. **Benchmarks** - Use `black_box` to prevent optimization -7. **Mock Backends** - Use for unit tests, real backends for integration - -## Troubleshooting - -### Tests Failing - -1. Check prover installation: - ```bash - which agda coqc lean isabelle z3 cvc5 - ``` - -2. Check prover versions: - ```bash - agda --version - coqc --version - ``` - -3. Run with verbose output: - ```bash - cargo test -- --nocapture --test-threads=1 - ``` - -### Benchmarks Not Running - -1. Build in release mode: - ```bash - cargo bench - ``` - -2. Check benchmark configuration in Cargo.toml - -### Proof Validation Failing - -1. Check proof file syntax -2. Verify prover can compile file directly -3. Check environment variables (e.g., `MIZAR_HOME`) - -## Contributing - -When adding new tests: -1. Add to appropriate test file (integration, property, or unit) -2. Use common test utilities where possible -3. Add documentation for new test patterns -4. Update this README if adding new test categories -5. Ensure tests work with and without provers installed - ---- - -**Last Updated:** 2025-11-22 -**Maintained By:** ECHIDNA Project Team diff --git a/tools/invariant-path/README.adoc b/tools/invariant-path/README.adoc new file mode 100644 index 00000000..351dee9d --- /dev/null +++ b/tools/invariant-path/README.adoc @@ -0,0 +1,26 @@ +== Invariant Path Integration (Echidna) + +Echidna wrapper script: + +[source,bash] +---- +./scripts/invariant-path.sh scan --file ./README.adoc --artifact-uri repo://README.adoc --write +---- + +Via `+just+` from repo root: + +[source,bash] +---- +just invariant-path scan --file ./README.adoc --artifact-uri repo://README.adoc --write +---- + +Default profile: `+echidna+` + +Focus: - theorem -> guarantee - assumption-bound -> general truth - +local result -> universal claim + +Store path defaults to `+.invariant-path/+` in the current working +directory. + +Desktop/start-menu launcher for shared tooling: - +`+/var/mnt/eclipse/repos/.desktop-tools/invariant-path-launcher.sh+` diff --git a/tools/invariant-path/README.md b/tools/invariant-path/README.md deleted file mode 100644 index 2716bf65..00000000 --- a/tools/invariant-path/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Invariant Path Integration (Echidna) - -Echidna wrapper script: - -```bash -./scripts/invariant-path.sh scan --file ./README.adoc --artifact-uri repo://README.adoc --write -``` - -Via `just` from repo root: - -```bash -just invariant-path scan --file ./README.adoc --artifact-uri repo://README.adoc --write -``` - -Default profile: `echidna` - -Focus: -- theorem -> guarantee -- assumption-bound -> general truth -- local result -> universal claim - -Store path defaults to `.invariant-path/` in the current working directory. - -Desktop/start-menu launcher for shared tooling: -- `/var/mnt/eclipse/repos/.desktop-tools/invariant-path-launcher.sh` diff --git a/training_data/floor_progress.adoc b/training_data/floor_progress.adoc new file mode 100644 index 00000000..7c85fba8 --- /dev/null +++ b/training_data/floor_progress.adoc @@ -0,0 +1,7 @@ +== Phase-1 floor progress (target: 10 000 proofs per prover) + +[width="100%",cols="15%,13%,>18%,>18%,>18%,>18%",options="header",] +|=== +|ts |run_id |provers_at_10k / total |floor |total_records |newly_crossed +|2026-04-17T20:11:40.451 |baseline |4 / 41 |5 |302847 |4 +|=== diff --git a/training_data/floor_progress.md b/training_data/floor_progress.md deleted file mode 100644 index 59ffc3f3..00000000 --- a/training_data/floor_progress.md +++ /dev/null @@ -1,5 +0,0 @@ -# Phase-1 floor progress (target: 10 000 proofs per prover) - -| ts | run_id | provers_at_10k / total | floor | total_records | newly_crossed | -|---|---|---:|---:|---:|---:| -| 2026-04-17T20:11:40.451 | baseline | 4 / 41 | 5 | 302847 | 4 |