Model Context Protocol (MCP) server and C++20 verification/search/prover toolkit implementing the Foundation-0 Repository Standard and Proven-Commons Verified Bar across arbitrary discrete state systems (formal_* suite) as well as Jonah Ostroff's PuzzleScript trilogy. The canonical catalog contains all 66 original rooms (I-1 through III-22), with dated source, tutorial and baseline provenance. See Agent quickstart and trilogy corpus parity evidence. (Part I, Part II: Monsters, Part III: The Bard and The Druid) on the Sokoban Eval Frontier benchmark (write-up).
Zero third-party Python packages are required (python >= 3.10 standard library only). On first Sokoban tool call, soko_mcp automatically compiles the C++20 engine (cpp/soko_engine.cpp) via g++ or clang++ (-O3 -pthread -std=c++20), while maintaining fail-closed dual-Python verification (PuzzleScriptOracle + zero-shared-code FlatBitmaskOracle) and honest capability reporting (soko_capabilities) even when no C++20 compiler is present.
-
Foundation-0/gfq-codesExact Rational LP Dual & Cost-Partitioned Quotient Certificates (formal_certify_lower_bound):- Adds
proof_mode='cost_partitioned_quotients'(exactfractions.Fractionadditive action-cost partitioning$\sum_m w_m(s,a,s') \le \text{cost}(s,a,s')$ across$M \ge 2$ Quotient Graph Homomorphisms, strictly dominating pointwise$\max_m h_m$ ) andproof_mode='rational_lp_dual'(exactfractions.Fractionstate-equation / operator-counting Farkas dual multiplier verification$y \ge 0$ ,$y^\top(F(s')-F(s)) \le \text{cost}(s,a,s')$ with zero floating-point LP solver in the TCB).
- Adds
-
Foundation-0/finite-state-proofsExact 4-Cell Row Strip Automaton (FastRowStripPDB) &F-11/F-12Soundness Audit (cpp/frontier_iii14_iii20_prover.cpp):- Stress-testing
v0.3.0's hand-written analyticalh_iii14_fastacross 15.5M concrete transitions uncovered two subtle inadmissibility hazards:F-11(assuming 9 switch-weighing atoms instead of 7/8-atom hero tandem entry whenopen_pdoors != 0) andF-12(independentxs/ysorder-statistic window slicing dropping10 -> 8on a single Druid transmutation). - Replaces hand-written analytical formulas completely with a 100% pure 5-Quotient-PDB Homomorphism Suite (
FastRowStripPDBtracking{empty, crate, wall}^4on(4..7, y)acrossy = 2, 3, 4viay <-> 6 - yvertical symmetry +PairAtomHomPDB+HarvestColPDB+BardDruidQuotientPDB), giving a sound lower bound>= 34on the 14x7III-14fixture. The completedf-layer covers79,587,434exactPacked14states, catches22,551live 64-bit hash collisions, and passes123,784,748runtimeh(s) <= 1 + h(s')edge checks with0violations. The trailingFINAL_CERTcounters run into the next layer until the 82 s cutoff and change with the machine. - Unlocks
M.n <= 256Multi-Core Exact-State Bucketed A* incpp/soko_engine.cpp(coveringIII-2015x9=135andII-2213x13=169), raising the generic MCP lower bound onIII-20from25(v0.3.0) to>= 48at a 30 s budget (8,475,805nodes expanded,77,437live 64-bit hash collisions caught,25,096,136runtime edge checks with0violations; wall time 10.8 to 14.5 s across three runs on the porting box and 19.2 s on the reviewer box). The search does not reach an exact optimum and returns no witness, sosoko_prove_floorreports it asLOWER_BOUND_UNWITNESSED, notVERIFIED.
- Stress-testing
-
Foundation-0/formal-claims-auditStatic AST Soundness & Anti-Tautology Tool (formal_audit_checkers, the 20th MCP tool on this branch):- Synchronized with
Foundation-0/formal-claims-audit#16(alongsideFoundation-0/math0#9andFoundation-0/f0#36): audits single or dual Python checkers forF-01optimisticTrueflags, IEEE-754 float drift, vacuous stubs, and alpha-renamed copy-paste tautologies.
- Synchronized with
-
Foundation-0/incentre-latticesLocked-Checkertracks/Harness (tracks/iii-14/,tracks/iii-20/):- Adds standalone dual-oracle
verify.pyscripts and append-onlyresults.tsvledgers logging both breakthroughs and negative high-width LNS runs.
- Adds standalone dual-oracle
An optional global record-query system now builds unrestricted bounded SAT problems for III-14 and III-20, verifies complete SAT assignments, checks optional UNSAT certificates, and replays candidates in the pinned original game. It requires separate research dependencies and has not yet demonstrated a new record or end-to-end formal equivalence.
PairAtomQuotientPDB+ Multi-Core Exact-State Bucketed A (soko_prove_floor):*- Adds a 39.7M-state 2-Atom Quotient Homomorphism Pattern Database (
PairAtomQuotientPDB) modeling unordered pairs of created weighing atoms ({crate@cell, interior_wall@cell, UNBORN, SPARE}), explicitly accounting for both rigid Bard 5x5 aura co-translation and wall-blocked/moving charmed crate pairs (including step 25 ofIII-14's 48-key route), Druid# <-> *transmutations, border re-petrification, and 10th-crateSPAREcreation. - Replaces per-iteration IDA* re-expansion on grids
<= 128cells with Multi-Core Exact-State Bucketed A* (CompactNodefull-state equality, zero hash-collision pruning, live collision counter, and runtimeh(s) <= 1 + h(s')edge checks), raising the built-in MCP certified floor onIII-14from29(inv0.2.0) to>= 33in ~6.6s with 100% exact-state deduplication. The larger v0.3.0 figure forIII-14is withdrawn because ofF-11/F-12. - Adds
WizardRayGoalBoundfor rooms with Wizard warpballs (III-15,III-20,II-22), eliminating the priorfloor = 1fallback on Wizard rooms.
- Adds a 39.7M-state 2-Atom Quotient Homomorphism Pattern Database (
- Automatic Inductive Invariant & Deadlock-Trap Synthesis (
formal_synthesize_invariant):- Adds a 7th universal
formal_*primitive supporting both Houdini greatest-fixpoint inductive safety invariant synthesis (synthesis_mode='houdini_safety') and irreversible forward-closed deadlock-trap synthesis (synthesis_mode='deadlock_trap') over reachable concrete subgraphs or explicit universal state domains (universe_code). - Certificates report
proof_scope:complete_reachable_statesonly applies to states reachable from the initial state, whileenumerated_closed_domainapplies to the supplied, checked closed domain. Neither covers states outside its domain.explored_reachable_subgraphis incomplete;open_transitionscounts outgoing transitions to states omitted by the limit, and no global induction or trap is established.
- Adds a 7th universal
- Executable Capability Contract & Review Hardening (
soko_capabilities+ Blocking Fixes):- Adds
soko_capabilitiesto report compiler/backend readiness and distinguishBACKEND_UNAVAILABLEfromUNSOLVED_WITHIN_BUDGET. - Enforces strict
REPO_ROOTpath confinement (unconfined_paths) and mandatorychecker_pinschecks insoko_verify_tcb_lock, fail-closed C++ epistemic/witness validation insoko_prove_floor, and exact 9-step (RRRRRRRRR)I-1benchmark metadata.
- Adds
claude mcp add soko-verified -- python3 -m soko_mcp{
"mcpServers": {
"soko-verified": {
"command": "python3",
"args": ["-m", "soko_mcp"],
"cwd": "/path/to/soko"
}
}
}| Suite | Primitive | Name | Purpose |
|---|---|---|---|
| Formal | Tool | formal_define_system |
AST-sandboxed dual-checker registration (spec_code != impl_code skeleton), negative controls, mutation kills & BFS fuzzing |
| Formal | Tool | formal_verify_trace |
Dual-checker step-by-step trace replay with rolling SHA-256 transcript digest and premise assertions |
| Formal | Tool | formal_solve_system |
Exact Dijkstra/BFS (goal synthesis or find_invariant_violation bug hunting), Diversified Beam, & Sliding-Window LNS |
| Formal | Tool | formal_certify_lower_bound |
Zero-trust PROVEN lower bounds via Quotient Homomorphisms, Inductive Potentials, Rational Cost-Partitioned Quotients, or Rational LP Duals |
| Formal | Tool | formal_synthesize_invariant |
Automatic Houdini inductive safety invariant synthesis (houdini_safety) & irreversible deadlock-trap synthesis (deadlock_trap) |
| Formal | Tool | formal_triage_portfolio |
Expected-verified-gain priority ranking across open instances |
| Formal | Tool | formal_export_ledger |
Export SHA-256-pinned PROVEN / VERIFIED / KNOWN / CONJECTURE claim ledger |
| Formal | Tool | formal_audit_checkers |
Static AST soundness & alpha-normalized anti-tautology auditor for single or dual Python checkers |
| Sokoban | Tool | soko_capabilities |
Inspect executable backend readiness, oracle count, lower-bound abstractions, and TCB manifest status |
| Sokoban | Tool | soko_list_rooms |
List built-in Frontier rooms (I-1, II-22, III-14, III-14-15x7, III-15, III-20, III-22) |
| Sokoban | Tool | soko_get_room |
Full source-pinned original room metadata, grid, tutorials and reference baseline provenance |
| Sokoban | Tool | soko_replay_original |
Replay UDLRA keys in the pinned original PuzzleScript browser engine |
| Sokoban | Tool | soko_play |
Stateless original-engine play with portable JSON checkpoints, undo and reset |
| Sokoban | Tool | soko_inspect_room |
Detect X/Y/180-degree symmetries, hero-switch chirality, switch deficits, and Bard constraints |
| Sokoban | Tool | soko_verify_route |
Triple-oracle (PuzzleScriptOracle + FlatBitmaskOracle + C++20) per-frame trajectory digest verifier |
| Sokoban | Tool | soko_optimize_route |
Shorten seed routes via Sliding-Window Exact BFS + Chiral-Mirror Tube Beam + Iterative Refinement |
| Sokoban | Tool | soko_solve_room |
Solve (part, grid) rooms from scratch via bucket-diversified C++20 beam search |
| Sokoban | Tool | soko_prove_floor |
Multi-Core Exact-State Bucketed A* (<= 256 cells) + PairAtomQuotientPDB + BardDruidQuotientPDB + WizardRayGoalBound. Returns VERIFIED only for an exact optimum with a dual-oracle-checked witness on a board with a reference route; otherwise WITNESS_MATCHES_CLAIM_UNREFERENCED (no reference route) or LOWER_BOUND_UNWITNESSED (inexact search) |
| Sokoban | Tool | soko_run_planted_bug_audit |
Cross-oracle baseline parity + 10-mutation Proven-Commons Planted-Bug Suite (10/10 caught) |
| Sokoban | Tool | soko_verify_tcb_lock |
Path-confined runtime SHA256SUMS manifest verification and SHA-256 checker pin inspection |
| Room | Keys | Status | SHA-256 (12) | Notes & Submission String |
|---|---|---|---|---|
III-20 (Primary) |
84 |
VERIFIED |
eecbea96b091 |
Live Frontier record (floor 74): ADDDRRADAAADRULARADAAADDLLALAAAARRRRUULAAUALLRADRRRRADRULRURRRRRARRUURURAURRRDDRAUUR |
III-20 (Alt) |
84 |
VERIFIED |
4edff1ad8c90 |
Alternate 84-key ending (URU): ADDDRRADAAADRULARADAAADDLLALAAAARRRRUULAAUALLRADRRRRADRULRURRRRRARRUURURAURRRDDRAURU |
III-14 (14x7 & 15x7) |
48 |
VERIFIED |
cd934d25a629 |
Matches 48 shortest known. Lower bound >= 34 holds on the 14x7 fixture only (standalone prover, completed layer of 79,587,434 exact states); it is not established for the 15x7 catalog board: LLULULULRURURURURUAUDRRDDAUARRDLRAULDLDRARURDUUR |
II-22 |
94 |
VERIFIED |
d5e82e8e3c65 |
Verified baseline (92 closed optimal on Frontier): ADDUUULDDRDDLDULDDRLLLLULURDLDRURUAAUUULLLLLLLAAAULURUARRRARRRDRUUDRRRDLLLDDDLDRLALUADDDRDRRUR |
III-15 |
69 |
VERIFIED |
76e195c497c1 |
Proven optimal: AULADDALAULDRALAULDALALURALADLUALALDRALAULDALALURALADLUALALDLRAUAULLU |
I-1 / III-22 |
9 |
VERIFIED |
179f01ec4093 |
Proven optimal opening & finale: RRRRRRRRR |
# Verify SHA256SUMS lock and run all unit & regression test suites
sha256sum -c SHA256SUMS
python3 -m unittest discover -s tests -v
# Run CLI commands directly
python3 -m soko_mcp capabilities
python3 -m soko_mcp tcb-lock
python3 -m soko_mcp audit
python3 -m soko_mcp prove-floor --room III-14 --max-bound 33 --budget-sec 10
python3 -m soko_mcp verify --room III-20 --route ADDDRRADAAADRULARADAAADDLLALAAAARRRRUULAAUALLRADRRRRADRULRURRRRRARRUURURAURRRDDRAUUR
# Run locked track verifiers (Foundation-0 / incentre-lattices pattern)
python3 tracks/iii-14/verify.py
python3 tracks/iii-20/verify.py