Jevon: a 20M-parameter decision model for Maze and Snake

Answers typed questions about a grid -- "which way should I move?", "is north
clear?", "how far is the goal?" -- with calibrated probabilities and no token
decoding. A from-scratch reimplementation of the idea behind NanoJev, rebuilt
around the thing that made the original fail at Maze: planning depth. The
backbone is a min-plus recurrence whose fixed point is a shortest-path
distance by construction; the three Jev primitives (Choice, Score, Boolean)
are kept as the interface.

Trained for 9,000 steps on one Apple M4 Max. On the held-out test split it
picks the BFS-optimal maze move 141 times out of 141 and the oracle snake move
89 out of 92, and the planner's distance field matches BFS to within 0.01
cells after a single global rescale.

This repository is the release: the weights (balanced.pt and best.pt, through
Git LFS), the model code, the training and evaluation scripts, the frozen
splits every number is measured on, and a model card whose tables are
generated from the JSON beside them rather than typed. `pytest -q` is 143
checks, most of them joins between a file that writes a number and a file that
quotes it.

AGPL-3.0-or-later, so anything built on it is open source too -- including
a network service, which is what section 13 is for. A commercial licence
without those terms is available: see COMMERCIAL-LICENSE.md.

Watch it play: https://github.com/lewislulu/jevon-arcade

.gitattributes

@@ -33,3 +33,24 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+
+# ---------------------------------------------------------------------------
+# Everything above is the list HuggingFace writes into a new repository, kept
+# verbatim: a format added here later is then already routed correctly, and a
+# diff against a fresh Hub repo shows only what this project chose.
+#
+# Checkpoints are why it matters. An 80MB blob in the git object store is a
+# clone people retry rather than finish, and the Hub rejects non-LFS files
+# above 10MB outright -- `*.pt` is covered above, and a clone made without LFS
+# gets a pointer file that `resolve_weights` names and explains rather than
+# dying inside `torch.load`.
+
+# The frozen splits stay ordinary git objects. They are 14MB of JSONL, under
+# the Hub's LFS threshold, and keeping them out of LFS means a clone made
+# without LFS still has everything `pytest -q` reads.
+*.jsonl -text
+
+# Generated tables live inside README.md and RESULTS.md; a merge driver that
+# tries to be clever about them produces a file that no longer matches the
+# JSON it is generated from, which the suite then fails on.
+*.md    -merge

.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.DS_Store
+
+# Checkpoints are ignored by default, then the shipped run is exempted file by
+# file below. `*.pt` comes first because gitignore is last-match-wins.
+*.pt
+
+# Runs are ignored except the one this model card is about, and that one is
+# tracked *completely* -- its JSON metadata and the two checkpoints every
+# number here is scored from. The exception is not housekeeping:
+#
+#   - README.md and RESULTS.md are generated from these JSON files, and the
+#     tests that check the prose against them skip when they are absent. An
+#     earlier `.gitignore` read `runs/`, which shipped a repo whose guards all
+#     passed by not running.
+#   - The weights are the model. A repo that carries the recipe and not the
+#     artefact is not a model release, and `from_pretrained` would have
+#     nothing to download.
+#
+# `last.pt` stays out: it is wherever training stopped, which is not a claim
+# this repo makes about anything.
+runs/*
+!runs/jevon-final/
+runs/jevon-final/*
+!runs/jevon-final/*.json
+!runs/jevon-final/balanced.pt
+!runs/jevon-final/best.pt
+!runs/jevon-final/play/
+!runs/jevon-final/play/*.json
+
+# Training logs and scratch runs.
+runs/*.log

COMMERCIAL-LICENSE.md

@@ -0,0 +1,38 @@
+# Commercial licence
+
+Jevon is published under the GNU Affero General Public License, version 3 or
+later — the full text is in [LICENSE](LICENSE).
+
+The AGPL is a strong copyleft licence. You may use, modify and run this model
+and its code for any purpose, including commercially, on one condition: the
+complete source of whatever you build on it has to be offered under the AGPL
+as well. Section 13 extends that to people who never receive a copy — if your
+users reach Jevon over a network, they are entitled to the source of the
+service they are reaching. Serving it behind an API counts.
+
+If your product cannot carry that obligation, a separate commercial licence is
+available. It covers the same artefacts under terms with no copyleft clause,
+so your own source stays yours.
+
+**Contact:** Lewis <sudolewis@gmail.com>
+
+Useful to include: who you are, what you intend to build, and whether you will
+be distributing the weights or serving them. The second case is the one the
+AGPL treats differently, so it changes the answer.
+
+## What both licences cover
+
+The model code in `jevon/`, the environments in `envs/`, the training and
+evaluation scripts, and the checkpoints in `runs/jevon-final/`.
+
+Copyright © 2026 Lewis. Sole authorship is what makes a second licence
+possible at all: there is no CLA to collect and no third-party contribution
+that would have to be re-licensed first. That stays true only while it stays
+true, so a pull request large enough to be copyrightable will be asked for a
+licence grant before it is merged.
+
+## What this is not
+
+Not legal advice, and not a warranty. The AGPL's sections 15 and 16 disclaim
+both, and a commercial licence is a negotiated document rather than a file in
+a repository — this page is an offer to start that conversation.

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

README.md

@@ -1,3 +1,813 @@
 ---
 license: agpl-3.0
+pipeline_tag: reinforcement-learning
+tags:
+- maze
+- snake
+- planning
+- grid-world
+- value-iteration-network
+- decision-model
+- pytorch
+metrics:
+- accuracy
 ---
+
+# Jevon
+
+A 20M-parameter decision model that answers **typed questions about a grid** —
+"which way should I move?", "is north clear?", "how far is the goal?" — with
+calibrated probabilities and no token decoding. It is a from-scratch
+reimplementation of the idea behind [NanoJev][nanojev] (itself a small
+open replication of TypeSafe AI's [Jev][jev]), rebuilt around the thing that
+made the original fail at Maze: **planning depth**.
+
+Jevon keeps NanoJev's interface — the three Jev primitives, `Choice`, `Score`
+and `Boolean` — and replaces the backbone.
+
+[nanojev]: https://github.com/TianyuCodings/NanoJev
+[jev]: https://typesafe.ai
+
+```python
+from jevon import from_pretrained
+
+jevon = from_pretrained("lewislululu/jevon")   # config + tokenizer + balanced.pt
+```
+
+| | |
+| --- | --- |
+| Parameters | 20,105,047 |
+| Checkpoint | `runs/jevon-final/balanced.pt` — 80MB of fp32 weights, via Git LFS |
+| Games | Maze (4 topologies, sizes 11–51) and Snake (8–24) |
+| Question types | `choice`, `boolean`, `score` — the three Jev primitives |
+| Training | 9,000 steps on one Apple M4 Max, from scratch |
+| Watch it play | [jevon-arcade](https://github.com/lewislulu/jevon-arcade) |
+| Licence | [AGPL-3.0-or-later](LICENSE), or a [commercial licence](COMMERCIAL-LICENSE.md) |
+
+Weights, code, frozen evaluation splits and every number below are in this one
+repository, and the tables are generated from the JSON beside them rather than
+typed — `pytest -q` fails if this page and that JSON disagree.
+
+## Results at a glance
+
+<!-- BEGIN:headline (generated by scripts/readme_table.py) -->
+
+**Decision accuracy** (held-out `test` split, next to the uniform control). `boards` is the number of distinct boards behind those questions; it tracks `n` because the generator draws a fresh board per state, which is what makes `n` an honest denominator rather than an assumed one:
+
+| question | n | boards | accuracy | uniform control |
+| --- | ---: | ---: | ---: | ---: |
+| `maze/choice` | 141 | 140 | **1.0000** | 0.4882 |
+| `snake/choice` | 92 | 92 | **0.9674** | 0.4783 |
+
+**Maze**, 36 episodes across topologies and sizes:
+
+| controller | solve rate | efficiency | cells visited |
+| --- | ---: | ---: | ---: |
+| `model` (network alone) | **1.00** | 1.000 | 94.2 |
+| `model-field` (architectural) | **1.00** | 1.000 | 94.2 |
+| `random` (floor) | 0.14 | 0.068 | 92.2 |
+| `reference` (BFS) | 1.00 | 1.000 | 94.2 |
+
+**Snake**, 6 episodes:
+
+| controller | mean food | max food | survival |
+| --- | ---: | ---: | ---: |
+| `model` | **4.50** | 16 | 1.00 |
+| `random` (floor) | 0.67 | 2 | 0.00 |
+| `reference` (oracle) | 23.50 | 31 | 1.00 |
+
+<!-- END:headline -->
+
+Regenerated from the evaluation JSON by `scripts/readme_table.py`, and
+`--check` fails the test suite if this block drifts from it. Full tables,
+including calibration and the planner probe, are in [RESULTS.md](RESULTS.md).
+
+---
+
+## Using it
+
+```bash
+pip install torch huggingface_hub
+git clone https://github.com/lewislulu/jevon-arcade   # or this repo, for the code
+```
+
+`from_pretrained` fetches the config, the tokenizer and one checkpoint — about
+80MB, not the whole repository — and caches them under `~/.cache/huggingface`.
+It takes a local run directory just as happily, so the same line works before
+and after publishing:
+
+```python
+from jevon import from_pretrained
+from jevon.inference import maze_state_sample
+from envs import maze as mz
+
+jevon = from_pretrained("lewislululu/jevon")        # or "runs/jevon-final"
+
+state = mz.generate_maze(21, "tree", seed=7)
+state.step("south")            # the start cell has one exit, so it poses no choice
+
+answers = {a["question"]: a for a in jevon.answer([maze_state_sample(state)])}
+answers["action"]["probabilities"]
+# {'north': 0.002, 'south': 0.998}                     BFS-optimal: south
+answers["clear_west"]["probabilities"]
+# {'false': 0.999, 'true': 0.001}                      a wall
+answers["solvable"]["probabilities"]
+# {'false': 0.001, 'true': 0.999}
+```
+
+One pass answers **every** question the state offers — `action`, the four
+`clear_*` booleans, `distance` and `solvable` — because the state and the
+board are encoded once and the questions cross-attend to them. "Offers" is
+literal: a cell with one exit poses no choice, so no `action` question is
+asked there and none is answered. Nothing is
+decoded as text: each answer is a distribution over that question's own
+candidates, which is what makes the numbers above comparable across states.
+
+The planner's distance field is readable directly, and costs nothing extra
+during an episode because it does not depend on the agent:
+
+```python
+field = jevon.distance_field(maze_state_sample(state))   # (21, 21), lower is closer
+```
+
+On a maze that field is a shortest-path distance up to one global scale — on
+the board above, rescaled by a single constant it matches BFS to within
+**0.0096 cells** — which is why greedy descent on it arrives from anywhere.
+[Building the property in](#building-the-property-in) is the part to read
+before treating that as a result about training; it is a property of the
+recurrence, and the honest apples-to-apples number is the `model` row.
+
+Device: `cuda`, then `mps`, then CPU, unless you pass `device=`.
+
+To watch it play rather than query it, [jevon-arcade][arcade] runs the maze and
+snake boards in a browser while this model decides, one forward pass per step,
+through the generators in `scripts/play.py` that produced every number above.
+
+[arcade]: https://github.com/lewislulu/jevon-arcade
+
+## Intended use, and what this is not
+
+Jevon is a **research artefact**: a demonstration that a 20M-parameter model
+with the right structural prior solves grid planning that a language-model
+backbone of similar size does not. It is useful for studying amortised value
+iteration, typed decision heads, and for reproducing or disputing the
+comparison with NanoJev below.
+
+It is not a general agent and not a language model. It answers a fixed set of
+typed questions about Maze and Snake boards; it has no text output, no
+instruction following, and nothing it learned transfers off a grid.
+
+Three limits worth knowing before quoting a number:
+
+1. **The maze field is exact by construction, not by training.** A checkpoint
+   trained for 60 steps already solves every maze optimally. Any
+   `model-field` maze figure describes the architecture. See [Building the
+   property in](#building-the-property-in).
+2. **Snake is the weak game.** 4.50 mean food against its own oracle's 23.50.
+   There is no planner for Snake the way there is for Maze, because distance
+   to food is the wrong field to descend — survival dominates.
+3. **The splits are small.** 141 maze and 92 snake choice questions in `test`.
+   Every accuracy here is printed next to its constant-prediction control for
+   that reason, and [RESULTS.md](RESULTS.md) gives `n` and the distinct board
+   count for each.
+
+Trained entirely on synthetic boards from the generators in `envs/`, whose
+oracles are exact. There is no human data anywhere in it.
+
+---
+
+## Why rebuild it
+
+NanoJev's own development log reports that its maze model learned nothing:
+its test-maze atomic accuracy (`0.5625`) is *identical* to its always-true
+control (`0.5625`), and every trained arm solved **0 of 3** mazes within the
+step cap. The impressive "244 attempts" demo comes from the surrounding
+controller — collision memory, untried-edge exploration, repositioning — not
+from the network.
+
+Three things caused that, and Jevon fixes each one.
+
+### 1. The board was a string
+
+NanoJev feeds the maze to a language model as ASCII art. In a flattened token
+sequence, two vertically adjacent cells of a 50×50 maze are ~51 tokens apart,
+so the model has to learn 2-D adjacency through attention, from scratch, for
+every board size. Jevon reads the board as an **8-channel grid**
+(`free, blocked, focus, target, body, tail, decay, game`) shared by both games,
+so one set of spatial weights serves Maze and Snake alike.
+
+### 2. There was no iterative computation
+
+Shortest-path distance is not a local function. A 21×21 corridor maze has a
+shortest path of 154 cells; a 31×31 has 312. A fixed-depth transformer cannot
+propagate a distance signal that far in one pass, no matter how wide it is.
+
+Jevon adds a **`SpatialPlanner`**: a weight-shared gated message-passing block
+applied recurrently over the 4-neighbourhood, masked by passability. `T`
+iterations propagate information `T` cells — amortised value iteration, or
+Bellman–Ford with learned operators. The budget is sized to the board:
+
+```python
+default_iterations(size) = min(4096, max(32, 2 * size + size * size // 2))
+# 11 -> 82    21 -> 262    31 -> 542    51 -> 1402
+```
+
+Memory stays flat in `T` because only the last `grad_steps` iterations carry
+gradient; earlier ones run under `no_grad` (implicit/phantom gradient).
+
+### 3. One question per state cannot teach a 500-step recurrence
+
+This was the subtle one. Even with a correct planner and a correct iteration
+budget, a linear probe from the planner's features to true BFS distance scored
+**R² = 0.21** — the field was barely related to distance. The recurrence was
+getting gradient from a *single* `distance` question per state.
+
+So the planner gets its own dense objective: a 1×1 convolution reads every cell
+and predicts the BFS distance to the target (log-squashed) plus a reachability
+logit. That is ~`size²` supervised targets per board instead of one, and it is
+defined purely on the board the planner receives, so the target is exactly the
+quantity the planner has the information to compute.
+
+```
+tests/test_model.py::test_planner_can_learn_a_distance_field
+    R² -31.9 -> 0.79   (4 boards, 400 steps, 9x9)
+```
+
+### 4. A graded scale is not seven unrelated categories
+
+`distance` and `room` are Jev **Score** questions: their criteria are an
+ordered scale ("within ten moves", "within twenty-five moves"). Encoded as a
+flat softmax with a one-hot target, naming the neighbouring level costs exactly
+as much as naming the opposite end of the scale, and with seven near-synonymous
+levels the marginal mode becomes the easiest minimum.
+
+It did, for a long time. `acc_score` sat on **0.3333** at every evaluation
+through the first 1000 steps of a run — exactly the always-level-4 constant —
+while a ridge probe on the very same planner features, binned through the very
+same thresholds, scored:
+
+```
+probe -> level   0.4335        best constant   0.3436
+within one level 0.9076
+```
+
+The information was there and the head was not using it, and 91% of the probe's
+errors were *one level off* — precisely the structure a one-hot target
+discards.
+
+A matched control run says how much of this is the target and how much is just
+impatience: left alone, the one-hot head does eventually escape, reaching
+0.3722 at step 1200. So the constant is an early-training attractor rather than
+a permanent trap, and the question the ablation answers is whether these two
+changes escape it sooner and end higher, not whether escape is possible at all.
+Both are off by default and measured in `runs/arm-*`:
+
+* **Ordinal targets** (`--score-smoothing`): score mass decays with distance
+  along the scale. The peak stays on the true level, so every reported accuracy
+  stays comparable with runs trained without it.
+* **Exposed field** (`--expose-field`): the text side gathers the field head's
+  own distance/reach read-out alongside the raw planner features. The field
+  head is already trained on every free cell, so its output is the most
+  distilled form of exactly what the question asks; without this the
+  transformer re-derives the same map from a far sparser signal.
+
+### 5. Two ways of being wrong about the same number
+
+`field_r2` appeared to fall while the decision metrics rose, which looks like
+the decision loss dragging the planner off its objective. That produced one
+falsified hypothesis and one real bug, and the order matters: measuring first
+is what separated them.
+
+**The hypothesis.** If the decision loss were overwhelming the field loss, the
+planner's gradient would show it. It does not:
+
+```
+decision loss 0.5050   grad->planner 0.03195
+field loss    0.0653   grad->planner 0.04808      ratio 0.66 : 1
+```
+
+The field objective already dominates, so `--field-weight 1.0` is calibrated
+and the tempting fix — raising it — would have been a change made for a reason
+measurement does not support.
+
+**The bug.** `field_r2` was computed per evaluation batch and then averaged.
+R² is a ratio of sums and is not averageable: a batch of boards with little
+distance variance drives its own R² arbitrarily negative and drags the mean
+with it. Pooling the sums and dividing once gives a stable number, and the
+"collapse" disappears. The probe, which pools over every cell, had been
+reporting R² ≈ 0.50 on the same checkpoints the whole time.
+
+### 6. R² is not the metric the controller uses
+
+Greedy descent never reads an absolute distance. It compares a cell's four
+neighbours and steps to the lowest, so what matters is whether the *ordering*
+of neighbours is right — and a path only succeeds if every comparison along it
+succeeds. `scripts/probe.py` reports that directly:
+
+```
+size  probe R²  field head R²  descent
+  11    0.5013         0.3425   0.6325
+  21    0.2697         0.1801   0.6561
+```
+
+Descent accuracy 0.65 means a 21×21 maze needs ~130 consecutive correct
+choices; the measured closed-loop solve rate for `--controller model-field` was
+0, exactly as that predicts.
+
+The cause is arithmetic. With a log-squashed target, neighbouring cells differ
+by ~`1/d`, so contrast collapses as distance grows — measured on a trained
+checkpoint:
+
+```
+true dist   descent acc   mean target gap
+      0-9        0.7273           0.08279
+    10-19        0.6458           0.02730
+    20-29        0.6531           0.01680
+    30-39        0.7429           0.01191
+    40-49        0.5000           0.00980      <- 8.5x less contrast
+```
+
+and the same checkpoint's field MAE was **0.107** — larger than the gap it had
+to resolve *anywhere* on the board. Rescaling would not help, since it scales
+the error by the same factor; the shape has to change. `--field-target linear`
+makes every neighbouring pair differ by exactly `1/size²` wherever it sits, so
+precision is spent uniformly instead of being concentrated near the goal.
+
+That argument is arithmetic and stands on its own. The *empirical* claim it
+invites — that the linear target measurably improves closed-loop descent — does
+not survive the seed-variance check in section 7, and is not made here.
+
+### 7. A field the controller can follow is not the same as an accurate field
+
+Section 6 explained a solve rate of 0 with descent accuracy 0.65: a 21×21 maze
+needs ~130 consecutive correct choices, and `0.65¹³⁰` is nothing. That
+reasoning is wrong, and the way it is wrong mattered more than the original
+problem.
+
+A wrong step is not a lost episode. It moves the agent to another cell, where
+it descends again. What ends an episode is not error *rate* but error
+*structure*: a spurious local minimum, which descent enters and never leaves.
+So the thing to measure is not how often a step is right but how often a walk
+arrives. From every free cell, follow the field downhill and record where it
+ends up:
+
+```
+ size      T   reach   cycle  descent
+   11     41   0.272   0.728    0.729
+   11     82   0.293   0.707    0.743
+   11    164   0.299   0.701    0.736
+   21    131   0.070   0.930    0.623
+   21    262   0.072   0.928    0.630
+   21    524   0.072   0.928    0.641
+```
+
+Two things fall out. 70–93% of cells sit in a basin, so the failure is
+structural rather than statistical — descent accuracy of 0.63 and reach of 0.07
+are not two views of one number. And quadrupling the iteration budget moves
+reach by under three points, so the recurrence has converged: propagation
+depth, the thing this architecture was built to supply, was never what was
+missing.
+
+#### The direct fix does not work, and measuring the noise is why we know
+
+The obvious response is to supervise the property: for every cell, hinge the
+best true-downhill neighbour below every other neighbour by one true step
+(`descent_loss`). It is exactly 0 on the true field under both target shapes,
+so it cannot fight the regression term, and raising its weight does move reach
+in the right direction — 0.104, 0.122, 0.132, 0.154 at weights 0, 1, 5, 20.
+
+That looks like a small win. It is not a win at all. Re-running the *unchanged*
+baseline under three seeds gives:
+
+```
+seed    reach   descent acc
+   0   0.1040        0.6700
+   1   0.0446        0.6283
+   2   0.1478        0.6575
+```
+
+A 3.3× spread, with the whole ablation sitting comfortably inside it. The
+honest reading is that the hinge's effect is not resolvable at this sample
+size, and any conclusion drawn from that first table would have been an
+artefact. The term is kept — it is principled and costs nothing at weight 0 —
+but it is not what fixed the problem, and this repository does not claim it
+did.
+
+One correction to that table, found later. Each row ran in a fresh process,
+and at the time `generate_maze` seeded itself with `hash(topology)`, which
+Python salts per process — so the rows differ in their held-out boards as
+well as their training seed, and the spread bounds the two together rather
+than the seed alone. That is now fixed (`TOPOLOGIES.index`, pinned by a test
+that runs the generator under three hash salts). It does not rescue the
+ablation: a band measured over *more* sources of variation than intended is
+still a band the ablation sits inside, and the four ablation rows were drawn
+from separate processes too, so they were never a controlled comparison in
+the first place. It does mean the number quoted above is an upper bound on
+seed variance specifically, and the honest summary is narrower than it looks:
+this experiment does not resolve the hinge's effect, and it never could
+have.
+
+The same caveat retires a claim section 6 would otherwise support: matched
+conv-head baselines differing only in target shape came out at 0.104 and 0.200,
+which is also within the noise band above.
+
+#### Building the property in
+
+Global monotonicity is all the local constraints holding at once, so a penalty
+that gets ~70% of them right buys far less than 70% of the benefit. Stop asking
+for the property and construct it. `MinPlusField` predicts a per-cell **cost**
+and reads distance off a Bellman–Ford recurrence:
+
+```
+v(c) ← cost(c) + min over passable neighbours n of v(n),    v(goal) = 0
+```
+
+With strictly positive costs the fixed point *is* a shortest-path distance, so
+every non-goal cell has a strictly lower neighbour and greedy descent
+terminates at the goal from anywhere. Reach is 1.0 by construction rather than
+by training — the test suite asserts it with the cost weights randomised, where
+the field bears no resemblance to the true distance and is still traversable.
+Costs are emitted in units of `1/area`, exactly the step size of the `linear`
+target, so the two agree by design rather than by tuning.
+
+```
+            descent acc   reach   field MAE   time
+conv             0.7115  0.2001     0.05636    65s
+min-plus         1.0000  1.0000     0.00000    67s
+```
+
+The `conv` row carries the noise band established above; the `min-plus` row
+does not, because 1.0000 there is a proof obligation the tests discharge
+rather than a measurement that could have come out otherwise. That asymmetry
+is the whole argument for building the property in instead of training for it.
+
+**The zero MAE is the caveat, and it belongs next to the headline.** For a
+maze, uniform cost is exactly right; the head initialises at
+`softplus(0.5413) ≈ 1`; so it computes exact BFS before a single gradient step
+(measured error against true BFS: under `1e-2` cells). The maze field is
+therefore a property of the architecture, not something the run learned, and
+any maze number produced by `--controller model-field` has to be read that way.
+
+What stays genuinely learned is the cost map — which is where Snake lives,
+since distance to food is not the whole objective there — and whether handing
+the transformer an exact field improves the action head. That second question
+is the apples-to-apples comparison with NanoJev, and it is the one the
+headline `model` controller reports.
+
+Closed-loop, the guarantee survives the whole inference path. A checkpoint
+trained for **60 steps** — long enough to confirm the plumbing works and not
+much else — played with `--controller model-field`:
+
+```
+size   solve rate   mean steps   mean shortest   collisions
+  11        1.000         33.0            33.0            0
+  21        1.000         82.0            82.0            0
+  31        1.000        172.5           172.5            0
+```
+
+Every maze solved, by an exactly optimal path. Read that as a statement about
+the architecture: a 60-step checkpoint has learned nothing, and the number
+comes from the recurrence being breadth-first search. It is reported because
+the comparison it replaces — Jev and NanoJev both solving 0 of 128 — is a
+comparison between controllers, and this is what a controller with the right
+structural prior does on the same boards.
+
+This is the Value-Iteration-Network idea (Tamar et al., 2016) with the
+max-plus reward recurrence swapped for the min-plus distance one the field head
+was already supervised on.
+
+---
+
+## Architecture
+
+```
+header + question text ──► shared prefix encoder (6 layers)  ─┐
+                                                              ├─► cross-attention ──► score ──► softmax
+candidate k text ────────► candidate encoder (2 layers) ──────┘        │
+                                                                       │
+8-channel board ──► SpatialPlanner (recurrent, T steps) ──► field ─────┤
+                                    │                                  │
+                                    └──► 1x1 conv ──► distance + reach (training only)
+```
+
+Three structural differences from NanoJev, beyond the planner:
+
+**Shared prefix.** NanoJev runs one full forward pass *per candidate*,
+re-encoding the whole state prefix each time. A 50×50 ASCII maze is ~2,600
+tokens, so a 4-candidate decision costs ~10.4K tokens. Jevon encodes the state
+and question **once** and lets candidates cross-attend to it: cost is
+`|prefix| + K·|candidate|` rather than `K·(|prefix| + |candidate|)`. This is
+the "tree sharing" NanoJev lists as unimplemented.
+
+**Anchored candidates.** A candidate that names a cell ("Move north to (7,11)")
+carries that coordinate, and the scoring head gathers the planner's feature at
+exactly that cell. The model does not have to re-derive from text which cell a
+candidate refers to.
+
+**Field caching.** The planner never sees the agent — the focus channel is
+zeroed before the recurrence — so for a fixed maze the field is constant for an
+entire episode and is computed **once**. Measured: 10 maze decisions in 0.71 s
+with `planner_calls=1`, `cache_hits=9` (71 ms/decision).
+
+---
+
+## Environments
+
+Both games ship with exact oracles, because the oracle *is* the training signal.
+
+**Maze** reproduces NanoJev's four topologies (`corridor`, `tree`, `loops`,
+`random_obstacle`) and its ASCII rendering so numbers are comparable. Targets
+are the full BFS-optimal action distribution — every shortest-path move shares
+the mass, so the model is never punished for picking a different optimal move.
+
+**Snake** deliberately departs from NanoJev. NanoJev's target is a local greedy
+rule: step toward the food. That self-traps. Jevon's oracle prefers, in order:
+survive → keep the tail reachable → keep room for the body → then close on the
+food. Measured over 20 games on 12×12:
+
+| Snake target policy | mean food | max food | mean steps |
+| --- | --- | --- | --- |
+| NanoJev-style greedy | 22.70 | 41 | 229.0 |
+| Jevon survival oracle | **43.00** | **105** | **2000.0** (full horizon, every game) |
+
+Half of all sampled Snake states are **constructed directly** as self-avoiding
+walks rather than reached by play. A good policy almost never produces a
+cramped board, so rolling out to one is both slow and rare — yet cramped boards
+are exactly where the survival questions carry signal.
+
+---
+
+## Question types
+
+| Type | Example | Candidates |
+| --- | --- | --- |
+| `choice` | which move to make | 2–4 dynamic |
+| `boolean` | "north is clear", "the goal is reachable" | false / true |
+| `score` | how far the goal is, how much room remains | 5–7 ordered levels |
+
+Every accuracy in this repo is reported next to the **constant-prediction
+control** for the same questions. That is not decoration: the original
+`room` question was scored against board area rather than snake length, which
+made *every* sampled state the top level, and the model scored exactly the
+constant baseline (`0.405556`) to six decimal places while appearing to learn.
+
+---
+
+## Training and reproduction
+
+```bash
+uv venv && uv pip install -r requirements.txt
+
+python scripts/build_dataset.py            # freeze val / test / OOD splits
+
+# The shipped checkpoint, exactly. Every flag matters: --min-plus-field is
+# what makes descent reach the goal by construction, --expose-field is what
+# lets the text side read the planner, and --planner-lr-mult compensates for
+# the planner block being applied several hundred times per step but carrying
+# gradient through only the last eight.
+python scripts/train.py --out runs/jevon-final --steps 9000 --eval-every 500 \
+  --planner-lr-mult 10 --field-weight 1.0 --seed 11 --min-plus-field --expose-field
+
+bash scripts/benchmark.sh runs/jevon-final    # eval + probe + play + RESULTS.md
+pytest -q
+```
+
+Each run directory records both halves of its own provenance: `config.json`
+is the architecture and `args.json` is the recipe (`argv` verbatim, plus the
+parsed values the defaults filled in). `benchmark.sh` defaults to
+`balanced.pt` — see [Which checkpoint ships](#which-checkpoint-ships).
+
+`runs/jevon-final/` ships whole: the JSON this page is generated from, and
+`balanced.pt` and `best.pt`, the two checkpoints [Which checkpoint
+ships](#which-checkpoint-ships) compares. Each is 80MB of fp32 weights and
+goes through **Git LFS**, so a clone needs it:
+
+```bash
+git lfs install
+git clone https://huggingface.co/lewislululu/jevon
+```
+
+Cloned without LFS, those two paths hold 130-byte pointer files. Loading one
+says exactly that and names the command, rather than failing inside
+`torch.load`.
+
+The JSON matters separately from the weights, and for a reason worth stating:
+every test that reads those files degrades to a **skip** when they are
+missing. An earlier `.gitignore` excluded the whole `runs/` directory, which
+shipped a repo whose entire documentation-drift apparatus passed by not
+running. `pytest -q` on a fresh clone now really does check this page against
+the run it describes. `last.pt` stays out — it is wherever training stopped,
+which is not a claim this repo makes.
+
+`scripts/play.py` exposes each controller loop twice: as `maze_steps` /
+`snake_steps`, generators that take one decision per `next()`, and as
+`play_maze` / `play_snake`, which drain them. The split exists so that
+[jevon-arcade](https://github.com/lewislulu/jevon-arcade)'s live viewer can take a single forward pass
+per HTTP request without owning a second copy of the decision logic. A
+divergent copy would be a viewer demonstrating a model nobody benchmarked,
+which is the failure these two repos have hit more often than any other. The
+step budget lives there too, in `default_max_steps`, so a live episode and a
+recorded one agree about what running out means.
+
+It exposes deliberately separable controllers so that model skill is never
+confused with controller scaffolding:
+
+- `model` — the network alone. No search, no memory, no visited set.
+- `model+memory` — plus one bit per cell: prefer a move onto ground not yet
+  stood on. This is the same kind of scaffolding this README faults NanoJev's
+  demo for, so it is reported separately and never as the model's score.
+- `random+memory` — **the control for the row above.** Identical bookkeeping,
+  no network. It exists because `model+memory` cannot be read without it, and
+  reading the two together is less flattering than reading one:
+
+<!-- BEGIN:memory (generated by scripts/readme_table.py) -->
+
+| controller | size | solve | efficiency |
+| --- | ---: | ---: | ---: |
+| `model+memory` | 11 | **1.00** | **1.000** |
+| `random+memory` | 11 | 0.92 | 0.588 |
+| `model+memory` | 21 | **1.00** | **1.000** |
+| `random+memory` | 21 | 0.83 | 0.310 |
+| `model+memory` | 31 | **1.00** | **1.000** |
+| `random+memory` | 31 | 0.75 | 0.147 |
+
+12 episodes per size per topology, from the shipped checkpoint.
+
+<!-- END:memory -->
+
+  Read the two rows together, per size. The memory alone is a capable maze
+  solver on a small board — near-exhaustive exploration finds the goal — so
+  wherever `random+memory` matches `model+memory` on solve rate, arrival is
+  the scaffolding's doing and not the network's. The table bolds whichever of
+  the pair wins each column rather than always bolding the model, so a bold
+  control is a column the model does not own.
+
+  Efficiency is the column that does belong to the network. When the model
+  arrives it arrives on very nearly the shortest path; the control reaches the
+  same place several times slower. That gap is what the planner contributes,
+  and it is worth being exact about what it is not. The model knows the
+  direction and has no state with which to notice it has been somewhere
+  before, so cycling is what ends its unsolved episodes — and the memory masks
+  that rather than fixing it: when every neighbour has been visited the
+  controller falls back to the full legal set and the greedy policy walks back
+  into the cycle it just left.
+- `reference` — BFS-optimal (maze) / survival oracle (snake).
+- `random`.
+
+**Why the memory is in the controller and not in the board.** The grid has a
+`visited` channel (channel 6, used by snake for tail age) and maze leaves it
+empty on purpose. Filling it would not teach the model to stop cycling: the
+targets are BFS-optimal actions, and the optimal action from a cell is a
+function of `(walls, goal, cell)` alone — where the agent has already been is
+conditionally independent of it. Under this supervision the channel is noise
+by construction, and a better-fitted model would learn to ignore it faster.
+Cycling is approximation error in the action head, not absent memory, so the
+lever that moves it is action accuracy; the architectural answer is
+`model-field`, whose fixed point is a shortest-path distance and which
+therefore cannot cycle at all.
+
+The candidate set is `state.legal_actions()`, which is what the model was
+trained to score. Offering it all four compass directions instead let a wall
+win the argmax, and since a blocked move does not change the state, the next
+decision was identical — an agent that stood still for the entire budget.
+Every maze number for `model` predating commit `6afaae8` measured that.
+
+Held-out splits are by seed (`seed % 10`: `<8` train, `8` val, `9` test), and
+the OOD split uses board sizes never sampled during training (maze 41, 51;
+snake 20, 24).
+
+## Which checkpoint ships
+
+Training writes three: `last.pt`, `best.pt` (lowest eval loss) and
+`balanced.pt`. `balanced.pt` is what loads when you do not name one —
+`benchmark.sh`, `record.sh` and every script's `--weights` agree on that, and
+a test pins them to each other so they cannot drift. The reason is a selection
+bug that `best.pt` walks straight into.
+
+The frozen validation split is 1325 questions over 180 states: **974 boolean,
+180 score, and 171 choice**. Eval loss averages over all of them, so 73.5% of
+it is booleans and 12.9% is choice — while every headline number in this
+README comes from those 171 choice questions, because those are the gameplay
+decision. The two can move in opposite directions, and they do.
+
+One run hit its lowest loss at a step scoring maze `0.9794` and snake
+`0.2973`. The uniform controls on this split are `0.4905` for maze and
+`0.4955` for snake — not `1/k`, because many states have several
+tied-optimal moves — so that checkpoint was a full 20 points *below chance*
+on snake while holding the best loss in the run. It had stopped playing one
+of the two games, and eval loss could not see it.
+
+So `balanced.pt` selects on `min(maze_action, snake_action)` instead —
+
+```python
+def balanced_score(metrics: dict) -> float:
+    return min(metrics.get("maze_action", 0.0), metrics.get("snake_action", 0.0))
+```
+
+`min` rather than a mean, because the failure being guarded against is
+exactly the trade of one game for the other, and a mean averages it away. A
+missing metric scores zero rather than being skipped, so a run that never
+reports `snake_action` cannot earn a balanced checkpoint by default.
+
+This is not hypothetical, and it is not rare — the shipped run did it too.
+Caught mid-training at step 1500, the two checkpoints on disk at that instant
+made the point better than any argument (both were later superseded; the
+final ones are in `runs/jevon-final/`):
+
+| | `best.pt` (step 1500) | `balanced.pt` (step 1000) |
+| --- | ---: | ---: |
+| eval loss | **0.6161** | 0.6269 |
+| `acc_boolean` | 0.94688 | 0.94688 |
+| `acc_score` | 0.42222 | 0.42222 |
+| `acc_choice` | 0.6665 | **0.8469** |
+| `snake_action` | 0.5135 | **0.9459** |
+
+`best.pt` won on loss. Boolean and score accuracy are *identical to five
+decimal places* between the two, so neither moved; the only accuracy that
+moved is choice, and it moved **18 points the wrong way**. The loss improved
+because the model sharpened its confidence on booleans it was already getting
+right (`ce` 0.4377 → 0.4286) while its snake play fell to `0.5135`, a hair
+above the `0.4955` control. Selecting on loss would have shipped that.
+
+Training later reached maze `1.0000` and snake `0.9595` together, and
+`balanced.pt` followed it up as readily as it had refused to follow it down.
+
+The shipped run's own two checkpoints are that same argument, and unlike the
+snapshot above both are on disk for a reader to check:
+
+<!-- BEGIN:shipped (generated by scripts/readme_table.py) -->
+
+| | `best.pt` (step 8500) | `balanced.pt` (step 3000) |
+| --- | ---: | ---: |
+| eval loss | **0.3999** | 0.4821 |
+| `acc_boolean` | **0.96732** | 0.94688 |
+| `acc_score` | 0.34444 | **0.35000** |
+| `acc_choice` | 0.9889 | **0.9944** |
+| `maze_action` | 1.0000 | 1.0000 |
+| `snake_action` | 0.9730 | **0.9865** |
+
+<!-- END:shipped -->
+
+Bold marks the better cell in each row — loss being the one row where smaller
+is better. `best.pt` takes loss and the two question types that dominate it;
+`balanced.pt` takes the choice questions, which are the ones every headline
+number in this README is scored on. `benchmark.sh` defaults to `balanced.pt`,
+which is why.
+
+### Selection reads `val`; every headline number comes from `test`
+
+That separation matters more here than it usually does, because the quantity
+being selected on keeps moving. The eval is deterministic — running it twice
+on a fixed checkpoint returns identical figures to six decimals — so what the
+table below measures is real weight movement between checkpoints, not
+measurement noise.
+
+<!-- BEGIN:volatility (generated by scripts/readme_table.py) -->
+
+| half of the run | evals | largest eval-to-eval move in `snake_action` | in questions |
+| --- | ---: | ---: | ---: |
+| first (500-5000) | 10 | `0.446` | 33 of 74 |
+| second (5000-9000) | 9 | `0.122` | 9 of 74 |
+
+<!-- END:volatility -->
+
+The movement shrinks by the factor shown there, and it does not reach zero.
+An earlier draft of this section claimed it stopped, on the evidence of four
+consecutive evals returning a byte-identical `0.9865`; two evals later one
+gave back six questions and the sentence was false. Any claim phrased over
+the last N evals goes stale as soon as training continues past them, which is
+why this one is phrased over halves of the run and generated rather than
+typed.
+
+Selecting the maximum of ~18 such evals is a maximum of a noisy estimate, so
+a `val` figure is biased upward by construction — and it is the second-half
+column that sizes that bias, not the first. `test` is scored
+once, by a checkpoint that never competed on it, which is why the headline
+quotes it and names the split it is quoting. `val` is reported too, in
+[RESULTS.md](RESULTS.md), where it can be read against the split that
+selection never touched.
+
+## Results
+
+See [RESULTS.md](RESULTS.md), which is generated from the evaluation JSON
+rather than typed by hand.
+
+## Licence
+
+Copyright © 2026 Lewis.
+
+[AGPL-3.0-or-later](LICENSE). Use it, modify it, run it for any purpose
+including a commercial one — provided the complete source of whatever you
+build on it is offered under the same licence. Section 13 is why this is the
+AGPL and not the GPL: it extends that to users who only ever reach the model
+over a network, so serving Jevon behind an API is covered where plain GPL
+would not have been.
+
+If your product cannot carry that obligation, a
+[commercial licence](COMMERCIAL-LICENSE.md) without the copyleft terms is
+available — sudolewis@gmail.com.
+
+The viewer, [jevon-arcade][arcade], is MIT instead. It holds no model code, it
+imports this repository at runtime, and a demo is worth more the more people
+run it — but a distribution that combines the two carries this licence, not
+that one.

RESULTS.md

@@ -0,0 +1,157 @@
+# Results
+
+Generated by `scripts/make_results.py` from the JSON written by `train.py`, `evaluate.py`, `probe.py` and `play.py`. Do not edit by hand.
+
+## Baseline: what NanoJev reports for itself
+
+From `docs/DEVELOPMENT_RESULTS.md` in the NanoJev repository.
+
+| NanoJev task | reported acc | always-true control | above control |
+| --- | ---: | ---: | :---: |
+| `scaled_maze` (test) | 0.5625 | 0.5625 | no |
+| `scaled_maze` (ood) | 0.5625 | 0.5625 | no |
+| `snake_one_step_safety_v4` | 0.9220 | 0.9220 | no |
+
+Closed-loop play, same source, 128-step limit:
+
+| maze | Jev | NanoJev | reference |
+| --- | ---: | ---: | ---: |
+| all three mazes | 0/128 | 0/128 | solved 1/16, 1/24, 1/96 |
+
+> "The learned direct-action models and Jev do not solve any of these
+> three mazes within the shared 128-step limit."
+
+Every accuracy in this file is therefore printed next to its
+constant-prediction control, and gameplay is reported as solve rate
+rather than per-question accuracy.
+
+## Does the planner actually compute distances?
+
+Ridge probe from the planner's per-cell features to true BFS distance, on held-out mazes. `diameter` is the longest true shortest-path in those boards; `T` is the iteration budget.
+
+`descent` is the fraction of cells whose lowest-predicted neighbour lies on a true shortest path. `reach` is the fraction from which greedy descent actually arrives at the goal, and it is the one that predicts solve rate: a field can be right 70% of the time per step and still trap most walks in a spurious basin, so `descent` is an upper bound on nothing in particular. R² scores absolute values; only `reach` scores the behaviour.
+
+`read-out R²` scores `predict_field()`, the field this controller actually descends -- the min-plus recurrence when the run enabled it, the conv head otherwise. The training curve's `conv field R²` scores a different head; see the note there.
+
+| size | cells | probe R² | probe MAE (cells) | read-out R² | descent | reach | diameter | T |
+| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 11 | 215 | **0.0937** | 7.97 | 1.0000 | 1.0000 | **1.0000** | 48 | 82 |
+| 21 | 901 | **0.0420** | 29.71 | 1.0000 | 1.0000 | **1.0000** | 152 | 262 |
+| 31 | 2011 | **0.0316** | 63.06 | 1.0000 | 1.0000 | **1.0000** | 310 | 542 |
+| 51 | 5679 | **0.0068** | 145.23 | 1.0000 | 1.0000 | **1.0000** | 672 | 1402 |
+
+## Question-level accuracy
+
+`uniform` is the accuracy of guessing uniformly over the same candidates. A model that matches its control has learned nothing, which is the failure NanoJev's own log records for its maze model.
+
+`boards` is how many distinct boards the row's questions came from, and it is there so that `n` can be trusted. Questions that share a board are not independent tests of whether the model can read a board -- they share walls, goal and distance field, so they succeed or fail together -- and a row reporting `n` alone cannot tell you whether that is happening. Here it is not: the generator draws a fresh board per state, so `boards` tracks `n` on every split and `n` is the honest denominator. A row where the two diverge is one whose precision should be read off `boards`.
+
+### val — 1325 questions, ECE 0.0865
+
+| group | n | boards | accuracy | uniform control | TVD | Brier |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `maze/action` | 97 | 97 | **1.0000** | 0.4905 | 0.0188 | 0.0023 |
+| `maze/boolean` | 530 | 106 | **1.0000** | 0.5000 | 0.0007 | 0.0000 |
+| `maze/choice` | 97 | 97 | **1.0000** | 0.4905 | 0.0188 | 0.0023 |
+| `maze/clear` | 424 | 106 | **1.0000** | 0.5000 | 0.0004 | 0.0000 |
+| `maze/distance` | 106 | 106 | **0.3962** | 0.1429 | 0.7764 | 0.7640 |
+| `maze/score` | 106 | 106 | **0.3962** | 0.1429 | 0.7764 | 0.7640 |
+| `maze/solvable` | 106 | 106 | **1.0000** | 0.5000 | 0.0018 | 0.0000 |
+| `snake/action` | 74 | 74 | **0.9865** | 0.4955 | 0.3500 | 0.3148 |
+| `snake/boolean` | 444 | 74 | **0.8829** | 0.5000 | 0.2338 | 0.2022 |
+| `snake/choice` | 74 | 74 | **0.9865** | 0.4955 | 0.3500 | 0.3148 |
+| `snake/escape` | 222 | 74 | **0.8108** | 0.5000 | 0.2773 | 0.2891 |
+| `snake/room` | 74 | 74 | **0.2838** | 0.2000 | 0.7990 | 0.7981 |
+| `snake/safe` | 222 | 74 | **0.9550** | 0.5000 | 0.1903 | 0.1152 |
+| `snake/score` | 74 | 74 | **0.2838** | 0.2000 | 0.7990 | 0.7981 |
+
+### test — 1765 questions, ECE 0.0590
+
+| group | n | boards | accuracy | uniform control | TVD | Brier |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `maze/action` | 141 | 140 | **1.0000** | 0.4882 | 0.0396 | 0.0079 |
+| `maze/boolean` | 740 | 147 | **1.0000** | 0.5000 | 0.0007 | 0.0000 |
+| `maze/choice` | 141 | 140 | **1.0000** | 0.4882 | 0.0396 | 0.0079 |
+| `maze/clear` | 592 | 147 | **1.0000** | 0.5000 | 0.0004 | 0.0000 |
+| `maze/distance` | 148 | 147 | **0.2973** | 0.1429 | 0.7847 | 0.7796 |
+| `maze/score` | 148 | 147 | **0.2973** | 0.1429 | 0.7847 | 0.7796 |
+| `maze/solvable` | 148 | 147 | **1.0000** | 0.5000 | 0.0019 | 0.0000 |
+| `snake/action` | 92 | 92 | **0.9674** | 0.4783 | 0.3107 | 0.2770 |
+| `snake/boolean` | 552 | 92 | **0.8895** | 0.5000 | 0.2223 | 0.1938 |
+| `snake/choice` | 92 | 92 | **0.9674** | 0.4783 | 0.3107 | 0.2770 |
+| `snake/escape` | 276 | 92 | **0.8188** | 0.5000 | 0.2628 | 0.2747 |
+| `snake/room` | 92 | 92 | **0.2500** | 0.2000 | 0.7993 | 0.7986 |
+| `snake/safe` | 276 | 92 | **0.9601** | 0.5000 | 0.1818 | 0.1128 |
+| `snake/score` | 92 | 92 | **0.2500** | 0.2000 | 0.7993 | 0.7986 |
+
+### ood — 1167 questions, ECE 0.0540
+
+| group | n | boards | accuracy | uniform control | TVD | Brier |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `maze/action` | 107 | 107 | **1.0000** | 0.5132 | 0.2699 | 0.1504 |
+| `maze/boolean` | 550 | 110 | **1.0000** | 0.5000 | 0.0007 | 0.0000 |
+| `maze/choice` | 107 | 107 | **1.0000** | 0.5132 | 0.2699 | 0.1504 |
+| `maze/clear` | 440 | 110 | **1.0000** | 0.5000 | 0.0004 | 0.0000 |
+| `maze/distance` | 110 | 110 | **0.0545** | 0.1429 | 0.8542 | 0.9160 |
+| `maze/score` | 110 | 110 | **0.0545** | 0.1429 | 0.8542 | 0.9160 |
+| `maze/solvable` | 110 | 110 | **1.0000** | 0.5000 | 0.0020 | 0.0000 |
+| `snake/action` | 50 | 50 | **0.9800** | 0.4867 | 0.3574 | 0.3199 |
+| `snake/boolean` | 300 | 50 | **0.8333** | 0.5000 | 0.2636 | 0.2621 |
+| `snake/choice` | 50 | 50 | **0.9800** | 0.4867 | 0.3574 | 0.3199 |
+| `snake/escape` | 150 | 50 | **0.6800** | 0.5000 | 0.3561 | 0.4471 |
+| `snake/room` | 50 | 50 | **0.2000** | 0.2000 | 0.7989 | 0.7978 |
+| `snake/safe` | 150 | 50 | **0.9867** | 0.5000 | 0.1710 | 0.0771 |
+| `snake/score` | 50 | 50 | **0.2000** | 0.2000 | 0.7989 | 0.7978 |
+
+## Closed-loop play
+
+Read `model` and `model-field` as answering different questions. `model` is the network's action head alone -- no search, no memory, no visited set -- and is the apples-to-apples comparison with NanoJev. `model-field` descends a min-plus recurrence whose fixed point is a shortest-path distance by construction, so it arrives from anywhere; for a maze it does so at initialisation, before any training, because uniform cost is already the right answer. Its solve rate is a property of the architecture, not a measurement of what this run learned.
+
+### Maze
+
+`deadlock` is the fraction of episodes in which the controller spent a tenth of its step budget walking into the same wall, and `cells` is how many distinct squares it stood on. They separate two failures a solve rate of 0.00 reports identically: standing still and touring the board. Deadlock should now read 0.00 for every controller, because only legal moves are offered as candidates -- it is kept as a regression guard, not a finding. The failure that remains is cycling: the planner never sees the agent, so a greedy policy that steps A->B->A has no state with which to notice, and `cells` is what exposes it.
+
+| controller | solve rate | mean steps | efficiency | collisions | deadlock | cells |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `maze_model` | 1.00 | 93.2 | 1.000 | 0.0 | 0.00 | 94.2 |
+| `maze_model_sampled` | 1.00 | 106.1 | 0.926 | 0.0 | 0.00 | 95.4 |
+| `maze_model_field` | 1.00 | 93.2 | 1.000 | 0.0 | 0.00 | 94.2 |
+| `maze_model_memory` | 1.00 | 93.2 | 1.000 | 0.0 | 0.00 | 94.2 |
+| `maze_random_memory` | 0.83 | 689.7 | 0.363 | 0.0 | 0.00 | 188.5 |
+| `maze_reference` | 1.00 | 93.2 | 1.000 | 0.0 | 0.00 | 94.2 |
+| `maze_random` | 0.14 | 560.4 | 0.068 | 0.0 | 0.00 | 92.2 |
+
+### Snake
+
+| controller | mean food | max food | mean steps | survival |
+| --- | ---: | ---: | ---: | ---: |
+| `snake_model` | 4.50 | 16 | 288.0 | 1.00 |
+| `snake_reference` | 23.50 | 31 | 288.0 | 1.00 |
+| `snake_random` | 0.67 | 2 | 33.8 | 0.00 |
+
+## Training curve
+
+Frozen validation split, never sampled during training.
+
+`conv field R²` scores `supervised_field()` -- the conv head the field loss trains. It is **not** the field the controller descends. Under `--min-plus-field` those are different objects: the read-out is the min-plus recurrence, scored as `read-out R²` in the probe table above, and nothing at inference reads the conv head at all. It stays in the loss as an auxiliary task on the shared trunk, so a negative value here means that auxiliary head has stopped tracking the trunk the action head and the recurrence are shaping -- it does not mean the planner is wrong, and `reach` is where that would show up.
+
+| step | loss | acc | choice | boolean | score | conv field R² | maze action | snake action |
+| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 500 | 0.6430 | 0.8310 | 0.6806 | 0.9469 | 0.3500 | 0.5048 | 0.5773 | 0.8108 |
+| 1000 | 0.6269 | 0.8626 | 0.8469 | 0.9469 | 0.4222 | -2.7876 | 0.7732 | 0.9459 |
+| 1500 | 0.6161 | 0.8393 | 0.6665 | 0.9469 | 0.4222 | 0.0461 | 0.7835 | 0.5135 |
+| 2000 | 0.5041 | 0.8703 | 0.9833 | 0.9469 | 0.3500 | -0.1305 | 1.0000 | 0.9595 |
+| 2500 | 0.4842 | 0.8531 | 0.8499 | 0.9469 | 0.3500 | 0.1714 | 1.0000 | 0.6486 |
+| 3000 | 0.4821 | 0.8718 | 0.9944 | 0.9469 | 0.3500 | -0.2088 | 1.0000 | 0.9865 |
+| 3500 | 0.4725 | 0.8718 | 0.9944 | 0.9469 | 0.3500 | 0.0103 | 1.0000 | 0.9865 |
+| 4000 | 0.4797 | 0.8702 | 0.9828 | 0.9469 | 0.3500 | 0.2466 | 0.9794 | 0.9865 |
+| 4500 | 0.4765 | 0.8710 | 0.9889 | 0.9469 | 0.3500 | 0.2097 | 0.9897 | 0.9865 |
+| 5000 | 0.4733 | 0.8718 | 0.9944 | 0.9469 | 0.3500 | 0.1148 | 1.0000 | 0.9865 |
+| 5500 | 0.4667 | 0.8725 | 0.9944 | 0.9469 | 0.3556 | -0.2881 | 1.0000 | 0.9865 |
+| 6000 | 0.4579 | 0.8673 | 0.9595 | 0.9469 | 0.3500 | -0.1574 | 1.0000 | 0.9054 |
+| 6500 | 0.4543 | 0.8695 | 0.9767 | 0.9469 | 0.3500 | 0.2626 | 1.0000 | 0.9459 |
+| 7000 | 0.4258 | 0.8860 | 0.9889 | 0.9673 | 0.3500 | 0.0325 | 1.0000 | 0.9730 |
+| 7500 | 0.4088 | 0.8831 | 0.9368 | 0.9673 | 0.3778 | -0.4171 | 1.0000 | 0.8514 |
+| 8000 | 0.4030 | 0.8860 | 0.9889 | 0.9673 | 0.3500 | 0.0676 | 1.0000 | 0.9730 |
+| 8500 | 0.3999 | 0.8853 | 0.9889 | 0.9673 | 0.3444 | 0.2261 | 1.0000 | 0.9730 |
+| 9000 | 0.4021 | 0.8958 | 0.9889 | 0.9673 | 0.4222 | 0.1083 | 1.0000 | 0.9730 |

data/frozen/manifest.json

@@ -0,0 +1,31 @@
+{
+  "val": 180,
+  "test": 240,
+  "ood": 160,
+  "config": {
+    "train_maze_sizes": [
+      7,
+      9,
+      11,
+      15,
+      21,
+      25,
+      31
+    ],
+    "train_snake_sizes": [
+      8,
+      10,
+      12,
+      14,
+      16
+    ],
+    "ood_maze_sizes": [
+      41,
+      51
+    ],
+    "ood_snake_sizes": [
+      20,
+      24
+    ]
+  }
+}

envs/__init__.py

@@ -0,0 +1 @@
+"""Maze and Snake environments with exact oracles."""

envs/maze.py

@@ -0,0 +1,363 @@
+"""Maze environment: generators, BFS oracle, renderers, and question profiles.
+
+Topologies and the ASCII rendering follow NanoJev's `scaled_maze.py` so that
+numbers from the two projects can be placed side by side. Everything else --
+the oracle targets and the structured grid view -- is new.
+
+Coordinate convention is zero-based ``(row, col)`` with row 0 at the top.
+"""
+from __future__ import annotations
+
+import random
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Iterable, Sequence
+
+DIRECTIONS: dict[str, tuple[int, int]] = {
+    "north": (-1, 0),
+    "east": (0, 1),
+    "south": (1, 0),
+    "west": (0, -1),
+}
+ACTIONS: tuple[str, ...] = ("north", "east", "south", "west")
+TOPOLOGIES: tuple[str, ...] = ("corridor", "tree", "loops", "random_obstacle")
+
+
+@dataclass
+class MazeState:
+    size: int
+    walls: frozenset[tuple[int, int]]
+    position: tuple[int, int]
+    goal: tuple[int, int]
+    topology: str = "tree"
+    seed: int = 0
+    # Set by the simulator, not by the model's view of the world.
+    steps: int = 0
+    collisions: int = 0
+    visited: set[tuple[int, int]] = field(default_factory=set)
+
+    def free(self, cell: tuple[int, int]) -> bool:
+        row, col = cell
+        return 0 <= row < self.size and 0 <= col < self.size and cell not in self.walls
+
+    def legal_actions(self) -> list[str]:
+        out = []
+        for action in ACTIONS:
+            dr, dc = DIRECTIONS[action]
+            if self.free((self.position[0] + dr, self.position[1] + dc)):
+                out.append(action)
+        return out
+
+    def step(self, action: str) -> bool:
+        """Apply ``action``. Returns True when the agent actually moved."""
+        dr, dc = DIRECTIONS[action]
+        target = (self.position[0] + dr, self.position[1] + dc)
+        self.steps += 1
+        if self.free(target):
+            self.position = target
+            self.visited.add(target)
+            return True
+        self.collisions += 1
+        return False
+
+    def solved(self) -> bool:
+        return self.position == self.goal
+
+    def clone(self) -> "MazeState":
+        return MazeState(self.size, self.walls, self.position, self.goal, self.topology,
+                         self.seed, self.steps, self.collisions, set(self.visited))
+
+
+# --------------------------------------------------------------------------
+# Generation
+# --------------------------------------------------------------------------
+
+def _carve_dfs(size: int, rng: random.Random, straight_bias: float) -> set[tuple[int, int]]:
+    """Randomised DFS on the odd sublattice; returns the set of carved cells."""
+    start = (1, 1)
+    opened = {start}
+    stack = [(start, None)]
+    while stack:
+        cell, incoming = stack[-1]
+        options = []
+        for action in ACTIONS:
+            dr, dc = DIRECTIONS[action]
+            nxt = (cell[0] + 2 * dr, cell[1] + 2 * dc)
+            if 1 <= nxt[0] < size - 1 and 1 <= nxt[1] < size - 1 and nxt not in opened:
+                options.append((action, nxt))
+        if not options:
+            stack.pop()
+            continue
+        # Straight bias keeps corridors long, which makes the planning horizon deep.
+        weights = [straight_bias if action == incoming else 1.0 for action, _ in options]
+        action, nxt = rng.choices(options, weights=weights, k=1)[0]
+        dr, dc = DIRECTIONS[action]
+        opened.add((cell[0] + dr, cell[1] + dc))
+        opened.add(nxt)
+        stack.append((nxt, action))
+    return opened
+
+
+def _largest_component(size: int, free: set[tuple[int, int]]) -> set[tuple[int, int]]:
+    seen: set[tuple[int, int]] = set()
+    best: set[tuple[int, int]] = set()
+    for cell in free:
+        if cell in seen:
+            continue
+        queue, comp = deque([cell]), set()
+        seen.add(cell)
+        while queue:
+            cur = queue.popleft()
+            comp.add(cur)
+            for dr, dc in DIRECTIONS.values():
+                nxt = (cur[0] + dr, cur[1] + dc)
+                if nxt in free and nxt not in seen:
+                    seen.add(nxt)
+                    queue.append(nxt)
+        if len(comp) > len(best):
+            best = comp
+    return best
+
+
+def generate_maze(size: int, topology: str, seed: int) -> MazeState:
+    """Build a solvable maze of the given size and topology."""
+    if topology not in TOPOLOGIES:
+        raise ValueError(f"unknown topology {topology!r}")
+    if size < 5:
+        raise ValueError("size must be at least 5")
+    # TOPOLOGIES.index, not hash(topology): str.__hash__ is salted per process
+    # unless PYTHONHASHSEED is pinned, so hashing the name here handed every
+    # process a different maze for the same (size, topology, seed). Training
+    # merely resampled, but probe.py and play.py both regenerate their boards,
+    # which made their numbers incomparable between runs and unreproducible for
+    # anyone cloning the repository.
+    base = (seed * 1_000_003) ^ (size * 7919) ^ (TOPOLOGIES.index(topology) * 65_537)
+
+    # Retry rather than raise. random_obstacle draws its density before it
+    # knows whether the result percolates, so a small fraction of seeds leave
+    # a largest component too small to use. That used to raise, and since
+    # nothing up the stack caught it, one unlucky draw killed a training run
+    # hours in -- which is how this was found. Thinning the density on each
+    # attempt makes the retry converge instead of resampling the same tail
+    # forever, and attempt 0 is byte-identical to the previous behaviour, so
+    # only the seeds that already failed move.
+    free: set[tuple[int, int]] = set()
+    for attempt in range(8):
+        rng = random.Random(base ^ (attempt * 2_654_435_761))
+        if topology == "random_obstacle":
+            density = rng.uniform(0.22, 0.32) * (0.7 ** attempt)
+            free = {
+                (r, c)
+                for r in range(1, size - 1)
+                for c in range(1, size - 1)
+                if rng.random() > density
+            }
+            free = _largest_component(size, free)
+        else:
+            straight = {"corridor": 6.0, "tree": 1.0, "loops": 1.5}[topology]
+            free = _carve_dfs(size, rng, straight)
+            if topology == "loops":
+                # Knock out extra walls to introduce cycles (multiple shortest paths).
+                candidates = [
+                    (r, c)
+                    for r in range(1, size - 1)
+                    for c in range(1, size - 1)
+                    if (r, c) not in free
+                    and sum((r + dr, c + dc) in free for dr, dc in DIRECTIONS.values()) >= 2
+                ]
+                rng.shuffle(candidates)
+                for cell in candidates[: max(1, len(candidates) // 6)]:
+                    free.add(cell)
+            free = _largest_component(size, free)
+        if len(free) >= 4:
+            break
+    else:
+        # Unreachable for size >= 5: by attempt 7 the density is under 2%.
+        raise RuntimeError(f"degenerate maze: {topology} size={size} seed={seed}")
+    walls = frozenset(
+        (r, c) for r in range(size) for c in range(size) if (r, c) not in free
+    )
+
+    # Pick a start/goal pair that is far apart so the task needs real planning.
+    cells = sorted(free)
+    anchor = rng.choice(cells)
+    far = bfs_distances(size, walls, anchor)
+    start = max((c for c in cells if far[c] < 10**8), key=lambda c: far[c])
+    dist = bfs_distances(size, walls, start)
+    reachable = [c for c in cells if dist[c] < 10**8 and c != start]
+    goal = max(reachable, key=lambda c: dist[c])
+    return MazeState(size, walls, start, goal, topology, seed, visited={start})
+
+
+# --------------------------------------------------------------------------
+# Oracle
+# --------------------------------------------------------------------------
+
+UNREACHABLE = 10**9
+
+
+def bfs_distances(size: int, walls: Iterable[tuple[int, int]],
+                  source: tuple[int, int]) -> dict[tuple[int, int], int]:
+    """Shortest-path distance in cells from ``source`` to every free cell."""
+    wallset = walls if isinstance(walls, (set, frozenset)) else set(walls)
+    dist = {source: 0}
+    queue = deque([source])
+    while queue:
+        cur = queue.popleft()
+        for dr, dc in DIRECTIONS.values():
+            nxt = (cur[0] + dr, cur[1] + dc)
+            if not (0 <= nxt[0] < size and 0 <= nxt[1] < size):
+                continue
+            if nxt in wallset or nxt in dist:
+                continue
+            dist[nxt] = dist[cur] + 1
+            queue.append(nxt)
+    out: dict[tuple[int, int], int] = {}
+    for r in range(size):
+        for c in range(size):
+            out[(r, c)] = dist.get((r, c), UNREACHABLE)
+    return out
+
+
+def optimal_action_distribution(state: MazeState) -> dict[str, float]:
+    """Uniform mass over every legal move that lies on *a* shortest path.
+
+    When the goal is unreachable all legal moves tie, matching NanoJev's stated
+    contract, so the two label sets describe the same target concept.
+    """
+    actions = state.legal_actions()
+    if not actions:
+        return {}
+    dist = bfs_distances(state.size, state.walls, state.goal)
+    scored = []
+    for action in actions:
+        dr, dc = DIRECTIONS[action]
+        nxt = (state.position[0] + dr, state.position[1] + dc)
+        scored.append((action, dist[nxt]))
+    best = min(value for _, value in scored)
+    if best >= UNREACHABLE:
+        return {action: 1.0 / len(actions) for action in actions}
+    winners = [action for action, value in scored if value == best]
+    return {action: (1.0 / len(winners) if action in winners else 0.0) for action in actions}
+
+
+DISTANCE_LEVELS: tuple[str, ...] = (
+    "The goal is on this cell already.",
+    "The goal is within two moves.",
+    "The goal is within five moves.",
+    "The goal is within ten moves.",
+    "The goal is within twenty-five moves.",
+    "The goal is within sixty moves.",
+    "The goal is more than sixty moves away or cannot be reached.",
+)
+_LEVEL_BOUNDS = (0, 2, 5, 10, 25, 60)
+
+
+def distance_level(steps: int) -> int:
+    for index, bound in enumerate(_LEVEL_BOUNDS):
+        if steps <= bound:
+            return index
+    return len(DISTANCE_LEVELS) - 1
+
+
+# --------------------------------------------------------------------------
+# Views
+# --------------------------------------------------------------------------
+
+def render_ascii(state: MazeState) -> str:
+    """NanoJev-compatible full-board ASCII rendering (no cropping)."""
+    rows = []
+    for row in range(state.size):
+        line = []
+        for col in range(state.size):
+            cell = (row, col)
+            char = "#" if cell in state.walls else "."
+            if cell == state.goal:
+                char = "G"
+            if cell == state.position:
+                char = "@" if state.position == state.goal else "A"
+            line.append(char)
+        rows.append("".join(line))
+    return (
+        f"Maze {state.size}x{state.size}. Coordinates are zero-based (row,column). "
+        f"Agent=({state.position[0]},{state.position[1]}), "
+        f"goal=({state.goal[0]},{state.goal[1]}).\n"
+        "#=wall, .=free, A=agent, G=goal, @=agent at goal. "
+        "Move one cell north/east/south/west; no diagonals or wraparound. "
+        "Stop on the goal.\n" + "\n".join(rows)
+    )
+
+
+def render_header(state: MazeState) -> str:
+    """The text a grid-aware model sees: framing only, no flattened board."""
+    return (
+        f"Maze {state.size}x{state.size}. Coordinates are zero-based (row,column). "
+        f"Agent=({state.position[0]},{state.position[1]}), "
+        f"goal=({state.goal[0]},{state.goal[1]}). Topology={state.topology}. "
+        "Move one cell north/east/south/west; no diagonals or wraparound. "
+        "Stop on the goal."
+    )
+
+
+# --------------------------------------------------------------------------
+# Question profiles (the Jev decision contract)
+# --------------------------------------------------------------------------
+
+def question_profile(state: MazeState, *, include_planning: bool = True) -> dict:
+    """Build the question map plus oracle targets for one maze state."""
+    actions = state.legal_actions()
+    dist_from_goal = bfs_distances(state.size, state.walls, state.goal)
+    questions: dict[str, dict] = {}
+    targets: dict[str, dict] = {}
+
+    if len(actions) >= 2:
+        criteria, anchors = {}, {}
+        for action in actions:
+            dr, dc = DIRECTIONS[action]
+            cell = (state.position[0] + dr, state.position[1] + dc)
+            criteria[action] = f"Move {action} to ({cell[0]},{cell[1]})."
+            anchors[action] = cell
+        questions["action"] = {
+            "type": "choice",
+            "instructions": (
+                "Choose a legal next move on a shortest path to the goal. "
+                "All equally short next moves tie; if the goal is unreachable, "
+                "all legal moves tie."
+            ),
+            "criteria": criteria,
+            "anchors": anchors,
+        }
+        targets["action"] = {"probs": optimal_action_distribution(state)}
+
+    for action in ACTIONS:
+        dr, dc = DIRECTIONS[action]
+        cell = (state.position[0] + dr, state.position[1] + dc)
+        questions[f"clear_{action}"] = {
+            "type": "boolean",
+            "instructions": (
+                f"Moving {action} from ({state.position[0]},{state.position[1]}) "
+                f"reaches ({cell[0]},{cell[1]}), which is inside the maze and not a wall."
+            ),
+            "anchors": {"true": cell},
+        }
+        targets[f"clear_{action}"] = {"probs": {"true": float(state.free(cell)),
+                                                "false": float(not state.free(cell))}}
+
+    if include_planning:
+        steps = dist_from_goal[state.position]
+        questions["distance"] = {
+            "type": "score",
+            "instructions": "How far is the goal from the agent's current cell?",
+            "criteria": list(DISTANCE_LEVELS),
+        }
+        level = distance_level(steps if steps < UNREACHABLE else UNREACHABLE)
+        targets["distance"] = {"level": level, "steps": min(steps, 9999)}
+
+        questions["solvable"] = {
+            "type": "boolean",
+            "instructions": "A path of open cells connects the agent to the goal.",
+        }
+        reachable = dist_from_goal[state.position] < UNREACHABLE
+        targets["solvable"] = {"probs": {"true": float(reachable),
+                                         "false": float(not reachable)}}
+    return {"questions": questions, "targets": targets}

envs/snake.py

@@ -0,0 +1,386 @@
+"""Snake environment with a survival-aware oracle.
+
+NanoJev labels Snake with a purely local rule: avoid an immediate collision,
+then minimise Manhattan distance to the current food.  That rule walks the
+snake into pockets it cannot leave, which is why its recorded episodes stall in
+the twenties.  The oracle here keeps the same one-step action interface but
+scores each move by whether the snake can still reach its own tail afterwards
+and how much free space the move leaves behind -- the standard strong heuristic
+for Snake -- so the imitation target is worth imitating.
+"""
+from __future__ import annotations
+
+import random
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Optional
+
+DIRECTIONS: dict[str, tuple[int, int]] = {
+    "north": (-1, 0),
+    "east": (0, 1),
+    "south": (1, 0),
+    "west": (0, -1),
+}
+ACTIONS: tuple[str, ...] = ("north", "east", "south", "west")
+OPPOSITE = {"north": "south", "south": "north", "east": "west", "west": "east"}
+
+
+@dataclass
+class SnakeState:
+    size: int
+    body: list[tuple[int, int]]          # head first, tail last
+    direction: str
+    food: tuple[int, int]
+    rng_state: int
+    steps: int = 0
+    eaten: int = 0
+    alive: bool = True
+    death: Optional[str] = None
+    history: list[str] = field(default_factory=list)
+
+    @property
+    def head(self) -> tuple[int, int]:
+        return self.body[0]
+
+    def clone(self) -> "SnakeState":
+        return SnakeState(self.size, list(self.body), self.direction, self.food,
+                          self.rng_state, self.steps, self.eaten, self.alive,
+                          self.death, list(self.history))
+
+    def in_bounds(self, cell: tuple[int, int]) -> bool:
+        return 0 <= cell[0] < self.size and 0 <= cell[1] < self.size
+
+    def candidate_actions(self) -> list[str]:
+        """Every non-reversing action. Fatal moves stay on the list on purpose."""
+        if len(self.body) == 1:
+            return list(ACTIONS)
+        return [a for a in ACTIONS if a != OPPOSITE[self.direction]]
+
+    def step(self, action: str) -> None:
+        if not self.alive:
+            return
+        if len(self.body) > 1 and action == OPPOSITE[self.direction]:
+            action = self.direction  # A reversal is not offered; treat it as "keep going".
+        dr, dc = DIRECTIONS[action]
+        head = (self.head[0] + dr, self.head[1] + dc)
+        self.steps += 1
+        self.direction = action
+        self.history.append(action)
+        if not self.in_bounds(head):
+            self.alive, self.death = False, "wall"
+            return
+        eats = head == self.food
+        # The tail vacates unless the snake eats, so entering it is legal.
+        occupied = set(self.body if eats else self.body[:-1])
+        if head in occupied:
+            self.alive, self.death = False, "body"
+            return
+        self.body.insert(0, head)
+        if eats:
+            self.eaten += 1
+            self._respawn_food()
+        else:
+            self.body.pop()
+
+    def _next_random(self) -> int:
+        # SplitMix64: reproducible, and the stream never enters the model's view.
+        self.rng_state = (self.rng_state + 0x9E3779B97F4A7C15) & 0xFFFFFFFFFFFFFFFF
+        z = self.rng_state
+        z = ((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9) & 0xFFFFFFFFFFFFFFFF
+        z = ((z ^ (z >> 27)) * 0x94D049BB133111EB) & 0xFFFFFFFFFFFFFFFF
+        return z ^ (z >> 31)
+
+    def _respawn_food(self) -> None:
+        occupied = set(self.body)
+        empty = [(r, c) for r in range(self.size) for c in range(self.size)
+                 if (r, c) not in occupied]
+        if not empty:
+            self.food = self.head          # Board is full; the episode is a win.
+            return
+        self.food = empty[self._next_random() % len(empty)]
+
+
+def new_game(size: int = 12, seed: int = 0, length: int = 3) -> SnakeState:
+    rng = random.Random(seed)
+    mid = size // 2
+    body = [(mid, mid - i) for i in range(length)]
+    state = SnakeState(size=size, body=body, direction="east", food=(0, 0),
+                       rng_state=(seed * 0x2545F4914F6CDD1D) & 0xFFFFFFFFFFFFFFFF)
+    occupied = set(body)
+    empty = [(r, c) for r in range(size) for c in range(size) if (r, c) not in occupied]
+    state.food = empty[rng.randrange(len(empty))]
+    return state
+
+
+def random_state(size: int, length: int, rng: random.Random,
+                 attempts: int = 8) -> SnakeState | None:
+    """Build a valid snake of roughly ``length`` as a self-avoiding walk.
+
+    Reaching cramped positions by playing the oracle takes thousands of steps
+    per sample and still almost never produces them -- a good policy avoids
+    them by construction. Sampling body shapes directly is cheap and covers the
+    tight configurations where the survival questions actually carry signal.
+    The walk prefers neighbours with fewer free neighbours (Warnsdorff's rule),
+    which produces bodies that hug themselves rather than sprawl.
+    """
+    length = max(2, min(length, size * size - 2))
+    for _ in range(attempts):
+        start = (rng.randrange(size), rng.randrange(size))
+        body = [start]
+        occupied = {start}
+        while len(body) < length:
+            head = body[-1]
+            options = []
+            for dr, dc in DIRECTIONS.values():
+                cell = (head[0] + dr, head[1] + dc)
+                if not (0 <= cell[0] < size and 0 <= cell[1] < size):
+                    continue
+                if cell in occupied:
+                    continue
+                free = sum(
+                    1 for dr2, dc2 in DIRECTIONS.values()
+                    if 0 <= cell[0] + dr2 < size and 0 <= cell[1] + dc2 < size
+                    and (cell[0] + dr2, cell[1] + dc2) not in occupied)
+                options.append((free, cell))
+            if not options:
+                break
+            fewest = min(o[0] for o in options)
+            cell = rng.choice([c for f, c in options if f == fewest])
+            body.append(cell)
+            occupied.add(cell)
+        if len(body) < max(2, length // 2):
+            continue
+        # The walk was grown tail-first, so reverse it to put the head at index 0.
+        body.reverse()
+        empty = [(r, c) for r in range(size) for c in range(size)
+                 if (r, c) not in occupied]
+        if not empty:
+            continue
+        head, neck = body[0], body[1]
+        direction = next((name for name, (dr, dc) in DIRECTIONS.items()
+                          if (neck[0] + dr, neck[1] + dc) == head), "east")
+        return SnakeState(size=size, body=body, direction=direction,
+                          food=rng.choice(empty),
+                          rng_state=rng.randrange(1, 2 ** 63))
+    return None
+
+
+# --------------------------------------------------------------------------
+# Oracle
+# --------------------------------------------------------------------------
+
+def _flood_fill(size: int, blocked: set[tuple[int, int]],
+                source: tuple[int, int]) -> set[tuple[int, int]]:
+    if source in blocked or not (0 <= source[0] < size and 0 <= source[1] < size):
+        return set()
+    seen = {source}
+    queue = deque([source])
+    while queue:
+        cur = queue.popleft()
+        for dr, dc in DIRECTIONS.values():
+            nxt = (cur[0] + dr, cur[1] + dc)
+            if (0 <= nxt[0] < size and 0 <= nxt[1] < size
+                    and nxt not in blocked and nxt not in seen):
+                seen.add(nxt)
+                queue.append(nxt)
+    return seen
+
+
+def _bfs_len(size: int, blocked: set[tuple[int, int]], source: tuple[int, int],
+             target: tuple[int, int]) -> int:
+    if source == target:
+        return 0
+    dist = {source: 0}
+    queue = deque([source])
+    while queue:
+        cur = queue.popleft()
+        for dr, dc in DIRECTIONS.values():
+            nxt = (cur[0] + dr, cur[1] + dc)
+            if not (0 <= nxt[0] < size and 0 <= nxt[1] < size) or nxt in dist:
+                continue
+            if nxt in blocked and nxt != target:
+                continue
+            dist[nxt] = dist[cur] + 1
+            if nxt == target:
+                return dist[nxt]
+            queue.append(nxt)
+    return 10**9
+
+
+def evaluate_action(state: SnakeState, action: str) -> dict:
+    """Score one action without mutating ``state``.
+
+    Returns immediate safety, the free area the new head can still reach, whether
+    the tail stays reachable (the snake can always follow it out of a pocket),
+    and the post-move path length to the food.
+    """
+    dr, dc = DIRECTIONS[action]
+    head = (state.head[0] + dr, state.head[1] + dc)
+    size = state.size
+    if not state.in_bounds(head):
+        return {"safe": False, "reason": "wall", "space": 0,
+                "tail_reachable": False, "food_distance": 10**9, "eats": False}
+    eats = head == state.food
+    occupied = set(state.body if eats else state.body[:-1])
+    if head in occupied:
+        return {"safe": False, "reason": "body", "space": 0,
+                "tail_reachable": False, "food_distance": 10**9, "eats": False}
+
+    body_after = [head] + (state.body if eats else state.body[:-1])
+    blocked = set(body_after)
+    reachable = _flood_fill(size, blocked - {head}, head)
+    tail = body_after[-1]
+    # The tail vacates next tick, so treat it as passable when testing escape.
+    tail_reachable = _bfs_len(size, blocked - {head, tail}, head, tail) < 10**9
+    food_distance = (0 if eats else
+                     _bfs_len(size, blocked - {head}, head, state.food))
+    return {"safe": True, "reason": None, "space": len(reachable),
+            "tail_reachable": tail_reachable, "food_distance": food_distance,
+            "eats": eats, "length_after": len(body_after)}
+
+
+def oracle_action_distribution(state: SnakeState) -> tuple[dict[str, float], dict]:
+    """Uniform mass over the moves a strong player would consider.
+
+    Preference order: survive this tick, keep the tail reachable, keep enough
+    room for the whole body, then close on the food. Ties share mass evenly.
+    """
+    actions = state.candidate_actions()
+    if not actions:
+        return {}, {}
+    scored = {a: evaluate_action(state, a) for a in actions}
+    survivors = [a for a in actions if scored[a]["safe"]]
+    if not survivors:
+        return {a: 1.0 / len(actions) for a in actions}, scored
+
+    pool = [a for a in survivors if scored[a]["tail_reachable"]] or survivors
+    need = len(state.body) + 1
+    roomy = [a for a in pool if scored[a]["space"] >= need]
+    pool = roomy or pool
+
+    reachable_food = [a for a in pool if scored[a]["food_distance"] < 10**9]
+    if reachable_food:
+        best = min(scored[a]["food_distance"] for a in reachable_food)
+        winners = [a for a in reachable_food if scored[a]["food_distance"] == best]
+    else:
+        best = max(scored[a]["space"] for a in pool)
+        winners = [a for a in pool if scored[a]["space"] == best]
+
+    probs = {a: (1.0 / len(winners) if a in winners else 0.0) for a in actions}
+    return probs, scored
+
+
+# --------------------------------------------------------------------------
+# Views
+# --------------------------------------------------------------------------
+
+def render_ascii(state: SnakeState) -> str:
+    grid = [["." for _ in range(state.size)] for _ in range(state.size)]
+    for idx, (r, c) in enumerate(state.body):
+        grid[r][c] = "H" if idx == 0 else "o"
+    fr, fc = state.food
+    if grid[fr][fc] == ".":
+        grid[fr][fc] = "*"
+    rows = ["".join(row) for row in grid]
+    return (
+        f"Snake {state.size}x{state.size}. Coordinates are zero-based (row,column). "
+        f"Head=({state.head[0]},{state.head[1]}), facing {state.direction}, "
+        f"length={len(state.body)}, food=({fr},{fc}).\n"
+        "H=head, o=body, *=food, .=empty. Move one cell north/east/south/west; "
+        "reversing onto your own neck is not offered. Hitting a wall or your body ends the game.\n"
+        + "\n".join(rows)
+    )
+
+
+def render_header(state: SnakeState) -> str:
+    return (
+        f"Snake {state.size}x{state.size}. Coordinates are zero-based (row,column). "
+        f"Head=({state.head[0]},{state.head[1]}), facing {state.direction}, "
+        f"length={len(state.body)}, food=({state.food[0]},{state.food[1]}). "
+        "Move one cell north/east/south/west; reversing onto your own neck is not "
+        "offered. Hitting a wall or your body ends the game."
+    )
+
+
+def question_profile(state: SnakeState) -> dict:
+    actions = state.candidate_actions()
+    probs, scored = oracle_action_distribution(state)
+    questions: dict[str, dict] = {}
+    targets: dict[str, dict] = {}
+
+    if len(actions) >= 2:
+        criteria, anchors = {}, {}
+        for action in actions:
+            dr, dc = DIRECTIONS[action]
+            cell = (state.head[0] + dr, state.head[1] + dc)
+            criteria[action] = f"Move {action} to ({cell[0]},{cell[1]})."
+            anchors[action] = cell
+        questions["action"] = {
+            "type": "choice",
+            "instructions": (
+                "Choose the next move that keeps the snake alive and makes the most "
+                "progress towards eating the food. Prefer moves that leave an escape "
+                "route; equally good moves tie."
+            ),
+            "criteria": criteria,
+            "anchors": anchors,
+        }
+        targets["action"] = {"probs": probs}
+
+    for action in actions:
+        dr, dc = DIRECTIONS[action]
+        cell = (state.head[0] + dr, state.head[1] + dc)
+        info = scored[action]
+        questions[f"safe_{action}"] = {
+            "type": "boolean",
+            "instructions": (
+                f"Moving {action} to ({cell[0]},{cell[1]}) does not immediately end the game."
+            ),
+            "anchors": {"true": cell},
+        }
+        targets[f"safe_{action}"] = {"probs": {"true": float(info["safe"]),
+                                               "false": float(not info["safe"])}}
+        questions[f"escape_{action}"] = {
+            "type": "boolean",
+            "instructions": (
+                f"After moving {action} to ({cell[0]},{cell[1]}) the snake can still "
+                "reach its own tail, so it is not sealed into a dead pocket."
+            ),
+            "anchors": {"true": cell},
+        }
+        ok = info["safe"] and info["tail_reachable"]
+        targets[f"escape_{action}"] = {"probs": {"true": float(ok), "false": float(not ok)}}
+
+    best_space = max((scored[a]["space"] for a in actions), default=0)
+    questions["room"] = {
+        "type": "score",
+        "instructions": "How much open room does the snake still have to manoeuvre in?",
+        "criteria": list(ROOM_LEVELS),
+    }
+    targets["room"] = {"level": room_level(best_space, len(state.body))}
+    return {"questions": questions, "targets": targets}
+
+
+ROOM_LEVELS: tuple[str, ...] = (
+    "Trapped: less open room than the snake is long.",
+    "Barely enough room to fit the snake; a dead end is likely.",
+    "Limited room, under three times the snake's length.",
+    "Comfortable room, several times the snake's length.",
+    "Wide open, more than eight times the snake's length.",
+)
+
+
+def room_level(space: int, length: int) -> int:
+    """Rate open room *relative to the snake's own length*.
+
+    An absolute fraction of the board is the wrong scale: a short snake on a
+    large board always scores the top level regardless of how it is placed,
+    which collapses the label to a constant and teaches nothing. What actually
+    decides whether the snake survives is how much room it has compared with
+    the space its own body needs.
+    """
+    ratio = space / max(1, length)
+    for index, bound in enumerate((1.0, 2.0, 3.0, 8.0)):
+        if ratio <= bound:
+            return index
+    return len(ROOM_LEVELS) - 1

jevon/__init__.py

@@ -0,0 +1,33 @@
+"""Jevon: a small typed-decision model with a recurrent spatial planner.
+
+Copyright (C) 2026 Lewis
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+It is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+details, in LICENSE or at <https://www.gnu.org/licenses/>.
+
+A commercial licence without the copyleft terms is available; see
+COMMERCIAL-LICENSE.md.
+"""
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name):                          # PEP 562
+    """Expose `from_pretrained` without making `import jevon` import torch.
+
+    The Hub helper is the first thing a reader of the model card reaches for,
+    so it should be `from jevon import from_pretrained`. Importing `.hub`
+    eagerly here would pull torch into every `import jevon`, including the
+    ones that only want `__version__`.
+    """
+    if name in ("from_pretrained", "REPO_ID", "CHECKPOINT", "DEFAULT_WEIGHTS"):
+        from . import hub
+        return getattr(hub, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

jevon/data.py

@@ -0,0 +1,380 @@
+"""Sampling, paraphrasing, and collation of decision records.
+
+Both games are procedural, so training draws from an endless seeded stream
+rather than a fixed file.  Splits are decided by the map seed: a maze or Snake
+episode belongs to exactly one split for the whole run, and evaluation seeds are
+never sampled during training.  Board sizes held out for OOD are never sampled
+during training either, which is what makes the size-generalisation claim mean
+something.
+"""
+from __future__ import annotations
+
+import json
+import random
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator, Optional, Sequence
+
+import torch
+
+from . import grid as gridmod
+from .modeling import TYPE_INDEX
+
+SPLITS = ("train", "val", "test")
+
+
+def split_for_seed(seed: int) -> str:
+    """Deterministic, collision-free assignment of a map seed to a split."""
+    bucket = seed % 10
+    if bucket < 8:
+        return "train"
+    return "val" if bucket == 8 else "test"
+
+
+@dataclass
+class QuestionSample:
+    name: str
+    qtype: str
+    instructions: str
+    candidate_ids: list[str]
+    candidate_texts: list[str]
+    anchors: list[Optional[tuple[int, int]]]
+    probs: list[float]
+
+
+@dataclass
+class StateSample:
+    uid: str
+    game: str
+    split: str
+    size: int
+    topology: str
+    board: torch.Tensor
+    focus: tuple[int, int]
+    target: tuple[int, int]
+    header: str
+    ascii_board: str
+    questions: list[QuestionSample] = field(default_factory=list)
+    # Dense supervision for the planner: BFS distance from ``target`` to every
+    # cell, -1 where blocked or unreachable. One question per state is far too
+    # little signal to teach a several-hundred-step recurrence; this is ~size^2.
+    dist_field: Optional[torch.Tensor] = None
+
+
+# --------------------------------------------------------------------------
+# Instruction paraphrasing
+# --------------------------------------------------------------------------
+# Jevon-S learns its vocabulary from this corpus, so it would happily overfit a
+# single phrasing of every question. Paraphrasing at sample time forces the
+# decision to depend on the board rather than on a memorised string.
+
+_PREFIXES = ("", "Task: ", "Decide: ", "Question: ", "Please decide. ", "Read the board. ")
+_SUFFIXES = ("", " Answer with a probability for each option.",
+             " Weigh the options carefully.", " Ties should share probability evenly.",
+             " Report your confidence.")
+
+
+def paraphrase(text: str, rng: random.Random) -> str:
+    return f"{rng.choice(_PREFIXES)}{text}{rng.choice(_SUFFIXES)}"
+
+
+# --------------------------------------------------------------------------
+# Samplers
+# --------------------------------------------------------------------------
+
+def _questions_from_profile(profile: dict, rng: random.Random,
+                            augment: bool) -> list[QuestionSample]:
+    out: list[QuestionSample] = []
+    for name, question in profile["questions"].items():
+        target = profile["targets"].get(name)
+        if target is None:
+            continue
+        qtype = question["type"]
+        anchors_map = question.get("anchors") or {}
+        if qtype == "choice":
+            ids = list(question["criteria"])
+            texts = [question["criteria"][key] for key in ids]
+            probs = [float(target["probs"].get(key, 0.0)) for key in ids]
+            anchors = [anchors_map.get(key) for key in ids]
+        elif qtype == "boolean":
+            # One semantic path, scored against an implicit zero logit.
+            ids, texts = ["true"], ["The proposition is true."]
+            probs = [float(target["probs"]["false"]), float(target["probs"]["true"])]
+            anchors = [anchors_map.get("true")]
+        else:
+            levels = question["criteria"]
+            ids = [str(i) for i in range(len(levels))]
+            texts = list(levels)
+            probs = [0.0] * len(levels)
+            probs[int(target["level"])] = 1.0
+            anchors = [None] * len(levels)
+        total = sum(probs)
+        if total <= 0:
+            continue
+        probs = [p / total for p in probs]
+        instructions = question["instructions"]
+        if augment:
+            instructions = paraphrase(instructions, rng)
+        out.append(QuestionSample(name, qtype, instructions, ids, texts, anchors, probs))
+    return out
+
+
+def sample_maze_state(seed: int, size: int, topology: str, rng: random.Random,
+                      augment: bool = True) -> Optional[StateSample]:
+    from envs import maze as mz
+
+    state = mz.generate_maze(size, topology, seed)
+    # Walk the agent to a random reachable cell so training sees mid-episode
+    # states, not only the start. Positions come from BFS, never from rollouts.
+    distances = mz.bfs_distances(size, state.walls, state.position)
+    reachable = [cell for cell, d in distances.items() if d < mz.UNREACHABLE]
+    if len(reachable) > 1:
+        state.position = rng.choice(reachable)
+        state.visited = {state.position}
+    if state.position == state.goal:
+        return None
+    profile = mz.question_profile(state)
+    questions = _questions_from_profile(profile, rng, augment)
+    if not questions:
+        return None
+    board, focus, target = gridmod.encode_maze(state)
+    return StateSample(
+        dist_field=gridmod.bfs_field(board, target),
+        uid=f"maze:{topology}:{size}:{seed}:{state.position[0]}_{state.position[1]}",
+        game="maze", split=split_for_seed(seed), size=size, topology=topology,
+        board=board, focus=focus, target=target,
+        header=mz.render_header(state), ascii_board=mz.render_ascii(state),
+        questions=questions)
+
+
+def sample_snake_state(seed: int, size: int, rng: random.Random,
+                       augment: bool = True, max_advance: int = 220
+                       ) -> Optional[StateSample]:
+    from envs import snake as sk
+
+    # Half the states come from play, half from directly constructed bodies.
+    # Oracle play gives realistic positions but, being a good policy, it almost
+    # never produces a cramped board -- which is exactly where the survival and
+    # room questions carry their signal. Constructed walks cover that half of
+    # the state space at a fraction of the cost of rolling out to it.
+    if rng.random() < 0.5:
+        target = max(3, int(size * size * rng.uniform(0.04, 0.45)))
+        state = sk.random_state(size, target, rng)
+        if state is None:
+            return None
+    else:
+        state = sk.new_game(size, seed)
+        steps = rng.randrange(0, max_advance)
+        for _ in range(steps):
+            if not state.alive:
+                break
+            probs, _ = sk.oracle_action_distribution(state)
+            if not probs:
+                break
+            actions = list(probs)
+            if rng.random() < 0.15:
+                action = rng.choice(state.candidate_actions())
+            else:
+                action = max(actions, key=lambda a: probs[a])
+            state.step(action)
+    if not state.alive or len(state.candidate_actions()) < 1:
+        return None
+    profile = sk.question_profile(state)
+    questions = _questions_from_profile(profile, rng, augment)
+    if not questions:
+        return None
+    board, focus, target = gridmod.encode_snake(state)
+    return StateSample(
+        dist_field=gridmod.bfs_field(board, target),
+        uid=f"snake:{size}:{seed}:{state.steps}", game="snake",
+        split=split_for_seed(seed), size=size, topology="snake",
+        board=board, focus=focus, target=target,
+        header=sk.render_header(state), ascii_board=sk.render_ascii(state),
+        questions=questions)
+
+
+@dataclass
+class SamplerConfig:
+    maze_sizes: Sequence[int] = (7, 9, 11, 15, 21, 25, 31)
+    maze_topologies: Sequence[str] = ("corridor", "tree", "loops", "random_obstacle")
+    snake_sizes: Sequence[int] = (8, 10, 12, 14, 16)
+    snake_fraction: float = 0.45
+    augment: bool = True
+    seed_space: int = 1_000_000
+
+
+class TaskSampler:
+    """Endless stream of :class:`StateSample` restricted to one split."""
+
+    def __init__(self, cfg: SamplerConfig, split: str, seed: int = 0):
+        self.cfg = cfg
+        self.split = split
+        self.rng = random.Random(seed)
+
+    def _draw_seed(self) -> int:
+        while True:
+            seed = self.rng.randrange(self.cfg.seed_space)
+            if split_for_seed(seed) == self.split:
+                return seed
+
+    def __iter__(self) -> Iterator[StateSample]:
+        while True:
+            sample = self.sample()
+            if sample is not None:
+                yield sample
+
+    def sample(self) -> Optional[StateSample]:
+        seed = self._draw_seed()
+        if self.rng.random() < self.cfg.snake_fraction:
+            size = self.rng.choice(list(self.cfg.snake_sizes))
+            return sample_snake_state(seed, size, self.rng, self.cfg.augment)
+        size = self.rng.choice(list(self.cfg.maze_sizes))
+        topology = self.rng.choice(list(self.cfg.maze_topologies))
+        return sample_maze_state(seed, size, topology, self.rng, self.cfg.augment)
+
+    def batch(self, states: int) -> list[StateSample]:
+        out: list[StateSample] = []
+        while len(out) < states:
+            sample = self.sample()
+            if sample is not None:
+                out.append(sample)
+        return out
+
+
+# --------------------------------------------------------------------------
+# Collation
+# --------------------------------------------------------------------------
+
+def collate(states: Sequence[StateSample], tokenizer, *, max_prefix: int = 320,
+            max_candidate: int = 48, text_only: bool = False,
+            device: str | torch.device = "cpu") -> dict:
+    """Turn states into the tensor batch :meth:`JevonModel.forward` expects."""
+    prefixes: list[list[int]] = []
+    candidates: list[list[list[int]]] = []
+    anchors: list[list[tuple[int, int]]] = []
+    targets: list[list[float]] = []
+    types: list[int] = []
+    state_index: list[int] = []
+    focus: list[tuple[int, int]] = []
+    target_cell: list[tuple[int, int]] = []
+    meta: list[dict] = []
+
+    for s_idx, state in enumerate(states):
+        context = state.ascii_board if text_only else state.header
+        for question in state.questions:
+            prefix = tokenizer.encode(
+                f"{context}\n{question.qtype}\n{question.instructions}",
+                add_bos=True, add_eos=True)[:max_prefix]
+            prefixes.append(prefix)
+            candidates.append([
+                tokenizer.encode(text, add_bos=True, add_eos=True)[:max_candidate]
+                for text in question.candidate_texts])
+            anchors.append([a if a is not None else (-1, -1) for a in question.anchors])
+            targets.append(list(question.probs))
+            types.append(TYPE_INDEX[question.qtype])
+            state_index.append(s_idx)
+            focus.append(state.focus)
+            target_cell.append(state.target)
+            meta.append({"uid": state.uid, "game": state.game, "size": state.size,
+                         "topology": state.topology, "question": question.name,
+                         "type": question.qtype, "candidate_ids": question.candidate_ids,
+                         "probs": list(question.probs)})
+
+    q = len(prefixes)
+    lp = max(len(p) for p in prefixes)
+    kmax = max(max(len(c) for c in candidates), max(len(t) for t in targets))
+    lc = max(max(len(ids) for ids in group) for group in candidates)
+
+    prefix_ids = torch.zeros(q, lp, dtype=torch.long)
+    cand_ids = torch.zeros(q, kmax, lc, dtype=torch.long)
+    cand_valid = torch.zeros(q, kmax, dtype=torch.bool)
+    target_probs = torch.zeros(q, kmax)
+    anchor_t = torch.full((q, kmax, 2), -1, dtype=torch.long)
+
+    for i in range(q):
+        prefix_ids[i, : len(prefixes[i])] = torch.tensor(prefixes[i])
+        for k, ids in enumerate(candidates[i]):
+            cand_ids[i, k, : len(ids)] = torch.tensor(ids)
+            anchor_t[i, k] = torch.tensor(anchors[i][k])
+        # A Boolean has one candidate path but a two-way distribution.
+        cand_valid[i, : len(targets[i])] = True
+        target_probs[i, : len(targets[i])] = torch.tensor(targets[i])
+
+    batch = {
+        "prefix_ids": prefix_ids,
+        "candidate_ids": cand_ids,
+        "candidate_valid": cand_valid,
+        "target_probs": target_probs,
+        "anchors": anchor_t,
+        "question_type": torch.tensor(types, dtype=torch.long),
+        "question_state": torch.tensor(state_index, dtype=torch.long),
+        "focus": torch.tensor(focus, dtype=torch.long),
+        "target": torch.tensor(target_cell, dtype=torch.long),
+    }
+    if not text_only:
+        boards, passable, sizes = gridmod.pad_boards([s.board for s in states])
+        batch.update(boards=boards, passable=passable, board_size=sizes)
+        if all(s.dist_field is not None for s in states):
+            batch["dist_field"] = gridmod.pad_fields([s.dist_field for s in states])
+    batch = {k: v.to(device) for k, v in batch.items()}
+    batch["meta"] = meta
+    return batch
+
+
+def build_corpus(sampler: TaskSampler, states: int = 400) -> list[str]:
+    """Text used to fit the tokenizer vocabulary."""
+    corpus: list[str] = []
+    for state in sampler.batch(states):
+        corpus.append(state.header)
+        for question in state.questions:
+            corpus.append(question.instructions)
+            corpus.extend(question.candidate_texts)
+    corpus.extend(_PREFIXES)
+    corpus.extend(_SUFFIXES)
+    return corpus
+
+
+def freeze_split(path: str | Path, cfg: SamplerConfig, split: str, states: int,
+                 seed: int) -> int:
+    """Write a fixed evaluation set so numbers stay comparable across runs."""
+    sampler = TaskSampler(cfg, split, seed)
+    rows = []
+    for state in sampler.batch(states):
+        rows.append({
+            "uid": state.uid, "game": state.game, "split": state.split,
+            "size": state.size, "topology": state.topology,
+            "header": state.header, "focus": list(state.focus),
+            "target": list(state.target),
+            "board": state.board.to(torch.int16).flatten().tolist()
+            if state.game == "maze" else state.board.flatten().tolist(),
+            "shape": list(state.board.shape),
+            "dist_field": state.dist_field.flatten().tolist(),
+            "questions": [{
+                "name": q.name, "type": q.qtype, "instructions": q.instructions,
+                "candidate_ids": q.candidate_ids, "candidate_texts": q.candidate_texts,
+                "anchors": [list(a) if a else None for a in q.anchors],
+                "probs": q.probs} for q in state.questions],
+        })
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    Path(path).write_text("".join(json.dumps(r) + "\n" for r in rows))
+    return len(rows)
+
+
+def load_frozen(path: str | Path) -> list[StateSample]:
+    out = []
+    for line in Path(path).read_text().splitlines():
+        row = json.loads(line)
+        board = torch.tensor(row["board"], dtype=torch.float32).view(*row["shape"])
+        questions = [QuestionSample(
+            q["name"], q["type"], q["instructions"], q["candidate_ids"],
+            q["candidate_texts"],
+            [tuple(a) if a else None for a in q["anchors"]], q["probs"])
+            for q in row["questions"]]
+        shape = row["shape"][1:]
+        field_t = (torch.tensor(row["dist_field"], dtype=torch.float32).view(*shape)
+                   if "dist_field" in row else gridmod.bfs_field(board, tuple(row["target"])))
+        out.append(StateSample(
+            row["uid"], row["game"], row["split"], row["size"], row["topology"],
+            board, tuple(row["focus"]), tuple(row["target"]), row["header"], "",
+            questions, dist_field=field_t))
+    return out

jevon/grid.py

@@ -0,0 +1,141 @@
+"""One board representation shared by every game.
+
+Maze and Snake look different on screen but pose the planner the same question:
+propagate reachability out from a target cell, around obstacles, and report what
+each neighbouring cell is worth.  Giving both games the same channel layout lets
+a single set of planner weights serve both, so the propagation circuit learned
+on mazes transfers to Snake's flood-fill and back.
+
+Channel meanings are fixed:
+
+===  ==========================================================
+ 0   ``free``    cell is enterable on the next tick
+ 1   ``blocked`` static obstacle (maze wall)
+ 2   ``focus``   the agent / snake head
+ 3   ``target``  the goal / the food
+ 4   ``body``    a dynamic obstacle that will move (snake body)
+ 5   ``tail``    the body cell that vacates first
+ 6   ``decay``   how soon a dynamic obstacle clears; maze: visited cells
+ 7   ``game``    constant plane, 0 for maze and 1 for snake
+===  ==========================================================
+"""
+from __future__ import annotations
+
+from collections import deque
+from typing import Sequence
+
+import torch
+
+FREE_CHANNEL = 0
+
+UNIFIED_CHANNELS: tuple[str, ...] = (
+    "free", "blocked", "focus", "target", "body", "tail", "decay", "game",
+)
+NUM_CHANNELS = len(UNIFIED_CHANNELS)
+
+
+def _empty(size: int) -> torch.Tensor:
+    return torch.zeros(NUM_CHANNELS, size, size, dtype=torch.float32)
+
+
+def encode_maze(state) -> tuple[torch.Tensor, tuple[int, int], tuple[int, int]]:
+    """Returns ``(board, focus_cell, target_cell)`` for a :class:`MazeState`."""
+    size = state.size
+    board = _empty(size)
+    wall_rows = torch.zeros(size, size, dtype=torch.bool)
+    for r, c in state.walls:
+        wall_rows[r, c] = True
+    board[0] = (~wall_rows).float()
+    board[1] = wall_rows.float()
+    board[2, state.position[0], state.position[1]] = 1.0
+    board[3, state.goal[0], state.goal[1]] = 1.0
+    # `visited` is deliberately left empty, and filling it would not help. The
+    # targets are BFS-optimal actions, and the optimal action from a cell is a
+    # function of (walls, goal, cell) alone -- where the agent has already been
+    # is conditionally independent of it. So under this supervision the channel
+    # is noise by construction, and a perfectly fitted model would learn to
+    # ignore it. Cycling is approximation error in the action head, not missing
+    # memory, which is why the fix lives in the controller and the measured
+    # lever is action accuracy. Leaving it empty also keeps the board constant
+    # for the whole episode, which is what lets the planner field be cached.
+    return board, state.position, state.goal
+
+
+def encode_snake(state) -> tuple[torch.Tensor, tuple[int, int], tuple[int, int]]:
+    """Returns ``(board, head_cell, food_cell)`` for a :class:`SnakeState`."""
+    size = state.size
+    board = _empty(size)
+    board[0] = 1.0
+    length = len(state.body)
+    for index, (r, c) in enumerate(state.body):
+        board[0, r, c] = 0.0
+        board[4, r, c] = 1.0
+        # Cells near the tail free up soonest; the planner needs that ordering
+        # to tell a real dead end from one that unblocks in a few ticks.
+        board[6, r, c] = 1.0 - index / max(length - 1, 1)
+    head_r, head_c = state.head
+    board[2, head_r, head_c] = 1.0
+    tail_r, tail_c = state.body[-1]
+    board[5, tail_r, tail_c] = 1.0
+    board[0, tail_r, tail_c] = 1.0          # the tail vacates, so it is enterable
+    food_r, food_c = state.food
+    board[3, food_r, food_c] = 1.0
+    board[7] = 1.0
+    return board, state.head, state.food
+
+
+def pad_boards(boards: Sequence[torch.Tensor]) -> tuple[torch.Tensor, torch.Tensor,
+                                                        torch.Tensor]:
+    """Pad a ragged list of boards to a common size.
+
+    Returns ``(boards, passable, sizes)``.  Padding is marked unpassable so a
+    small board in a mixed batch cannot leak signal into the padded margin.
+    """
+    height = max(int(b.shape[1]) for b in boards)
+    width = max(int(b.shape[2]) for b in boards)
+    stacked = torch.zeros(len(boards), NUM_CHANNELS, height, width)
+    passable = torch.zeros(len(boards), 1, height, width)
+    sizes = torch.zeros(len(boards), dtype=torch.long)
+    for i, board in enumerate(boards):
+        h, w = board.shape[1], board.shape[2]
+        stacked[i, :, :h, :w] = board
+        passable[i, 0, :h, :w] = board[0]
+        sizes[i] = max(h, w)
+    return stacked, passable, sizes
+
+
+def bfs_field(board: torch.Tensor, target: tuple[int, int]) -> torch.Tensor:
+    """Shortest-path distance from ``target`` to every cell, in cells.
+
+    Defined purely on the unified board the planner receives -- channel 0 is
+    passability for both games -- so the supervision target is exactly the
+    quantity the planner has the information to compute.  Unreachable and
+    blocked cells are ``-1``.
+    """
+    free = board[FREE_CHANNEL] > 0.5
+    height, width = free.shape
+    dist = torch.full((height, width), -1.0)
+    if not (0 <= target[0] < height and 0 <= target[1] < width):
+        return dist
+    queue = deque([target])
+    dist[target[0], target[1]] = 0.0
+    while queue:
+        row, col = queue.popleft()
+        step = dist[row, col] + 1
+        for dr, dc in ((-1, 0), (1, 0), (0, -1), (0, 1)):
+            nr, nc = row + dr, col + dc
+            if 0 <= nr < height and 0 <= nc < width and free[nr, nc] \
+                    and dist[nr, nc] < 0:
+                dist[nr, nc] = step
+                queue.append((nr, nc))
+    return dist
+
+
+def pad_fields(fields: Sequence[torch.Tensor]) -> torch.Tensor:
+    """Pad distance fields to a common shape with ``-1`` (= no supervision)."""
+    height = max(f.shape[0] for f in fields)
+    width = max(f.shape[1] for f in fields)
+    out = torch.full((len(fields), height, width), -1.0)
+    for index, field in enumerate(fields):
+        out[index, : field.shape[0], : field.shape[1]] = field
+    return out

jevon/hub.py

@@ -0,0 +1,88 @@
+"""Loading the published checkpoint from the HuggingFace Hub.
+
+``JevonRunner`` takes a directory. On the Hub that directory arrives as a
+snapshot download, so this module is the few lines in between -- kept in code
+rather than in the README so the repo id has exactly one spelling, which a
+test then pins the model card to.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import torch
+
+from .inference import REPO_ID as _REPO_ID, JevonRunner
+
+#: The published repository. One spelling, imported by anything that needs it.
+REPO_ID = _REPO_ID
+
+#: Where the checkpoint sits inside that repository.
+#:
+#: The Hub convention is weights at the root. This repo keeps the run
+#: directory intact instead, because ``config.json``, ``tokenizer.json`` and
+#: the ``.pt`` files are one artefact: a root-level copy of the config would
+#: be a second spelling of the architecture, free to drift from the weights
+#: sitting beside it, and this project has lost more time to writer/reader
+#: pairs like that than to anything else.
+CHECKPOINT = "runs/jevon-final"
+
+#: What ``from_pretrained`` fetches when no checkpoint is named. Selected on
+#: ``min(maze_action, snake_action)`` rather than on aggregate eval loss --
+#: see "Which checkpoint ships" in the model card. Every published number
+#: comes from this file.
+DEFAULT_WEIGHTS = "balanced.pt"
+
+
+def default_device() -> str:
+    """The best device actually present, rather than the one this was built on.
+
+    ``JevonRunner`` keeps ``mps`` as its default because every script in this
+    repo runs on the machine the model was trained on. A download from the Hub
+    is the opposite case -- most of them are CUDA or CPU -- and silently
+    falling back from an unavailable ``mps`` would leave a CUDA user on CPU
+    wondering why a 20M-parameter model is slow.
+    """
+    if torch.cuda.is_available():
+        return "cuda"
+    if torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+def from_pretrained(repo_id: str | Path = REPO_ID, *, device: str | None = None,
+                    weights: str | None = None,
+                    revision: str | None = None) -> JevonRunner:
+    """A loaded ``JevonRunner``, from the Hub or from a local run directory.
+
+    ``repo_id`` may be either. A path that already contains ``config.json`` is
+    loaded straight from disk, so the same call works before and after
+    publishing and in the tests, which have no network.
+
+    Only the files needed to answer questions are fetched -- the config, the
+    tokenizer and one checkpoint -- so this costs ~80MB rather than the whole
+    repository. Name ``weights`` to pull a different one.
+    """
+    local = Path(repo_id)
+    if (local / "config.json").is_file():
+        return JevonRunner(local, device or default_device(), weights)
+
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError as err:                   # optional: local runs need no Hub
+        raise ImportError(
+            "from_pretrained() needs huggingface_hub "
+            "(`pip install huggingface_hub`). To load a run you already have, "
+            "pass its directory instead: from_pretrained('runs/jevon-final')."
+        ) from err
+
+    # Named explicitly rather than left to resolve_weights' preference order:
+    # the fallback scans a directory, and this one will only ever contain the
+    # single file that was just downloaded.
+    wanted = weights or DEFAULT_WEIGHTS
+    snapshot = snapshot_download(
+        str(repo_id), revision=revision,
+        allow_patterns=[f"{CHECKPOINT}/config.json",
+                        f"{CHECKPOINT}/tokenizer.json",
+                        f"{CHECKPOINT}/{wanted}"])
+    return JevonRunner(Path(snapshot) / CHECKPOINT,
+                       device or default_device(), wanted)

jevon/inference.py

@@ -0,0 +1,252 @@
+"""Loading a checkpoint and answering decision requests."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Optional, Sequence
+
+import torch
+
+from . import grid as gridmod
+from .data import QuestionSample, StateSample, collate
+from .modeling import JevonConfig, JevonModel
+from .planner import default_iterations
+from .tokenizer import JevonTokenizer
+
+
+# The order `benchmark.sh` and `record.sh` also use. `balanced.pt` is selected
+# on min(maze_action, snake_action) and `best.pt` on aggregate eval loss, which
+# the boolean questions outnumber the action questions in badly enough that a
+# checkpoint which had stopped playing snake once held the lowest loss in the
+# run -- so every number this repo ships comes from `balanced.pt`, and the
+# README argues the case at length. The scripts nonetheless defaulted
+# `--weights` to `best.pt`, handing anyone who read `--help` the checkpoint the
+# documentation exists to argue against, and quietly disagreeing with RESULTS.md.
+PREFERRED_WEIGHTS = ("balanced.pt", "best.pt")
+
+# Defined here rather than in `hub.py` because the error below names it and
+# `hub` imports this module; one spelling, no cycle.
+REPO_ID = "lewislululu/jevon"
+
+# The first line of a Git LFS pointer file.
+LFS_POINTER = b"version https://git-lfs.github.com/spec/v1"
+
+
+def _is_lfs_pointer(path: Path) -> bool:
+    """True for a checkpoint that was cloned without Git LFS.
+
+    This is the one failure a published repo produces that a local one never
+    does, and it does not look like a missing file: the path exists, and holds
+    ~130 bytes of text naming the object that should have been fetched.
+    `torch.load` on that dies inside the zip reader with a message about a
+    central directory, which says nothing about the cause -- and the cause is
+    one command.
+    """
+    if path.stat().st_size > 1024:               # a real checkpoint is ~80MB
+        return False
+    with path.open("rb") as handle:
+        return handle.read(len(LFS_POINTER)) == LFS_POINTER
+
+
+def resolve_weights(checkpoint_dir: str | Path,
+                    name: str | None = None) -> Path:
+    """The checkpoint file to load, preferring the one the docs describe.
+
+    `name` names one explicitly; without it the first of PREFERRED_WEIGHTS
+    that exists wins, so a run trained before `balanced.pt` existed still
+    loads.
+    """
+    path = Path(checkpoint_dir)
+    wanted = (name,) if name else PREFERRED_WEIGHTS
+    for candidate in wanted:
+        target = path / candidate
+        if target.is_file():
+            if _is_lfs_pointer(target):
+                raise FileNotFoundError(
+                    f"{target} is a Git LFS pointer, not a checkpoint -- this "
+                    f"clone was made without LFS. Run `git lfs install && git "
+                    f"lfs pull`, or fetch the file from "
+                    f"https://huggingface.co/{REPO_ID}.")
+            return target
+
+    # A bare FileNotFoundError names the path but not the reason, and the
+    # reason is the non-obvious half. Which reason it is depends on where the
+    # reader got this directory: the published run carries both checkpoints,
+    # so reaching this line means either LFS was never pulled or this is a run
+    # they trained themselves.
+    have = sorted(q.name for q in path.glob("*.pt"))
+    tried = " or ".join(str(path / c) for c in wanted)
+    raise FileNotFoundError(
+        f"no weights at {tried}. The published run ships `balanced.pt` and "
+        f"`best.pt` through Git LFS: on a clone, `git lfs pull` fetches them. "
+        f"Otherwise train one with `scripts/train.py --out runs/my-run`, or "
+        f"point --checkpoint at a run that has them."
+        + (f" This directory has: {', '.join(have)}." if have else ""))
+
+
+class JevonRunner:
+    """A loaded model plus the glue that turns states into distributions."""
+
+    def __init__(self, checkpoint_dir: str | Path, device: str = "mps",
+                 weights: str | None = None):
+        path = Path(checkpoint_dir)
+        chosen = resolve_weights(path, weights)
+        cfg_dict = json.loads((path / "config.json").read_text())
+        self.cfg = JevonConfig(**cfg_dict)
+        self.tokenizer = JevonTokenizer.load(path / "tokenizer.json")
+        usable = device != "mps" or torch.backends.mps.is_available()
+        self.device = torch.device(device if usable else "cpu")
+        self.model = JevonModel(self.cfg).to(self.device)
+        self.weights = chosen.name
+        state = torch.load(chosen, map_location=self.device)
+        self.model.load_state_dict(state)
+        self.model.eval()
+        self._field_cache: dict[bytes, torch.Tensor] = {}
+        self.planner_calls = 0
+        self.planner_cache_hits = 0
+
+    def reset_cache(self) -> None:
+        self._field_cache.clear()
+
+    def _fields(self, batch: dict, steps: int) -> Optional[torch.Tensor]:
+        """Planner fields for the batch, reusing any already computed.
+
+        The planner never sees the agent, so a maze board hashes to the same key
+        for every step of an episode and the field is computed once.  Snake
+        boards change each tick and simply miss.
+        """
+        if self.model.planner is None or batch.get("boards") is None:
+            return None
+        boards, passable = batch["boards"], batch["passable"]
+        probe = boards.clone()
+        probe[:, self.model.FOCUS_CHANNEL] = 0.0
+        out, missing = [None] * boards.shape[0], []
+        keys = []
+        for i in range(boards.shape[0]):
+            key = hashlib.blake2b(
+                probe[i].to(torch.float16).cpu().numpy().tobytes()
+                + steps.to_bytes(4, "big"), digest_size=16).digest()
+            keys.append(key)
+            cached = self._field_cache.get(key)
+            if cached is None:
+                missing.append(i)
+            else:
+                out[i] = cached
+                self.planner_cache_hits += 1
+        if missing:
+            self.planner_calls += len(missing)
+            index = torch.tensor(missing, device=boards.device)
+            computed = self.model.encode_boards(
+                boards[index], passable[index], steps, 0)
+            for slot, i in enumerate(missing):
+                field = computed[slot]
+                out[i] = field
+                if len(self._field_cache) < 64:
+                    self._field_cache[keys[i]] = field
+        return torch.stack(out, dim=0)
+
+    @torch.no_grad()
+    def distance_field(self, state: StateSample, *,
+                       iterations: Optional[int] = None) -> torch.Tensor:
+        """The model's own predicted distance-to-target for every cell.
+
+        This is the planner's training read-out, reused at play time. It costs
+        nothing extra during an episode: the field does not depend on the agent,
+        so the cache that serves ``answer`` serves this too.
+        """
+        batch = collate([state], self.tokenizer, device=self.device)
+        steps = iterations or default_iterations(int(batch["board_size"].max()))
+        cells = self._fields(batch, steps)
+        if cells is None:
+            raise RuntimeError("checkpoint has no planner")
+        with torch.no_grad():
+            return self.model.predict_field(
+                cells, batch["boards"], batch["passable"],
+                iterations=steps)[0, 0].float().cpu()
+
+    def answer(self, states: Sequence[StateSample], *,
+               iterations: Optional[int] = None) -> list[dict]:
+        """Score every question on every state in a single batched pass."""
+        batch = collate(states, self.tokenizer, device=self.device)
+        steps = iterations or default_iterations(int(batch["board_size"].max()))
+        cells = self._fields(batch, steps)
+        logits = self.model(batch, iterations=steps, grad_steps=0, cells=cells)
+        probs = logits.float().softmax(-1).cpu()
+        out = []
+        for row, meta in enumerate(batch["meta"]):
+            ids = meta["candidate_ids"]
+            if meta["type"] == "boolean":
+                names = ["false", "true"]
+                values = probs[row, :2].tolist()
+            else:
+                names = list(ids)
+                values = probs[row, : len(ids)].tolist()
+            total = sum(values) or 1.0
+            distribution = {n: v / total for n, v in zip(names, values)}
+            record = {
+                "uid": meta["uid"], "question": meta["question"],
+                "type": meta["type"], "probabilities": distribution,
+                "choice": max(distribution, key=distribution.get),
+                "target": meta["probs"],
+            }
+            if meta["type"] == "score":
+                k = len(names)
+                record["expected_score"] = sum(
+                    i / max(k - 1, 1) * distribution[n] for i, n in enumerate(names))
+            out.append(record)
+        return out
+
+
+def maze_state_sample(state, *, uid: str = "live") -> StateSample:
+    from envs import maze as mz
+
+    profile = mz.question_profile(state)
+    board, focus, target = gridmod.encode_maze(state)
+    return _assemble(profile, board, focus, target, mz.render_header(state),
+                     mz.render_ascii(state), uid, "maze", state.size, state.topology)
+
+
+def snake_state_sample(state, *, uid: str = "live") -> StateSample:
+    from envs import snake as sk
+
+    profile = sk.question_profile(state)
+    board, focus, target = gridmod.encode_snake(state)
+    return _assemble(profile, board, focus, target, sk.render_header(state),
+                     sk.render_ascii(state), uid, "snake", state.size, "snake")
+
+
+def _assemble(profile, board, focus, target, header, ascii_board, uid, game, size,
+              topology) -> StateSample:
+    questions = []
+    for name, question in profile["questions"].items():
+        qtype = question["type"]
+        anchors_map = question.get("anchors") or {}
+        if qtype == "choice":
+            ids = list(question["criteria"])
+            texts = [question["criteria"][k] for k in ids]
+            anchors = [anchors_map.get(k) for k in ids]
+            probs = [0.0] * len(ids)
+        elif qtype == "boolean":
+            ids, texts = ["true"], ["The proposition is true."]
+            anchors = [anchors_map.get("true")]
+            probs = [0.0, 0.0]
+        else:
+            levels = question["criteria"]
+            ids = [str(i) for i in range(len(levels))]
+            texts, anchors = list(levels), [None] * len(levels)
+            probs = [0.0] * len(levels)
+        target_row = profile["targets"].get(name)
+        if target_row is not None:
+            if qtype == "choice":
+                probs = [float(target_row["probs"].get(k, 0.0)) for k in ids]
+            elif qtype == "boolean":
+                probs = [float(target_row["probs"]["false"]),
+                         float(target_row["probs"]["true"])]
+            else:
+                probs = [0.0] * len(ids)
+                probs[int(target_row["level"])] = 1.0
+        questions.append(QuestionSample(name, qtype, question["instructions"], ids,
+                                        texts, anchors, probs))
+    return StateSample(uid, game, "live", size, topology, board, focus, target,
+                       header, ascii_board, questions)

jevon/losses.py

@@ -0,0 +1,290 @@
+"""Training objectives for calibrated decisions.
+
+Cross-entropy against the oracle's full distribution is the main term: the
+targets are genuine distributions (all shortest-path moves tie, all equally good
+Snake moves tie), so matching them is matching the right answer *and* the right
+uncertainty.  A Brier term is added because cross-entropy alone rewards
+confident near-misses more than it should, and Brier is the proper score that
+penalises overconfidence directly.
+
+Question types arrive in very different quantities -- a maze state emits four
+Boolean questions but only one choice -- so each type is reweighted to keep the
+gameplay-relevant choice questions from being drowned out.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+import torch.nn.functional as F
+
+from .modeling import TYPE_INDEX
+
+
+@dataclass
+class LossWeights:
+    choice: float = 2.0
+    boolean: float = 0.6
+    score: float = 0.6
+    brier: float = 0.5
+    # Score levels are a graded scale, not unrelated categories: "within ten
+    # moves" and "within twenty-five moves" are neighbours on one axis.  A
+    # one-hot target says otherwise, so a near-miss earns exactly as much loss
+    # as naming the opposite end of the scale, and with seven near-synonymous
+    # levels the marginal mode becomes the easiest minimum -- measured, the
+    # score head sat on the always-level-4 constant for a whole run while a
+    # linear probe on the same features binned to 0.43 against its 0.34.  That
+    # probe lands within one level 91% of the time, which is the shape the
+    # target should have: mass decaying with distance along the scale.
+    score_smoothing: float = 0.0
+    entropy: float = 0.0          # optional confidence penalty
+
+
+def _grade_score_targets(target, valid, types, tau):
+    """Spread score-question mass over neighbouring levels.
+
+    Candidate ``j`` of a score question *is* level ``j`` (the criteria arrive in
+    order), so distance along the candidate axis is distance along the scale.
+    The peak stays on the true level, which keeps every reported accuracy
+    comparable with runs trained without this.
+    """
+    is_score = types.eq(TYPE_INDEX["score"])
+    if not bool(is_score.any()):
+        return target
+    levels = torch.arange(target.shape[1], device=target.device).float()
+    true = target.argmax(-1, keepdim=True).float()
+    graded = torch.exp(-(levels.unsqueeze(0) - true).abs() / tau)
+    graded = graded * valid.float()
+    graded = graded / graded.sum(-1, keepdim=True).clamp(min=1e-9)
+    return torch.where(is_score.unsqueeze(-1), graded, target)
+
+
+def decision_loss(logits: torch.Tensor, batch: dict,
+                  weights: LossWeights = LossWeights()) -> tuple[torch.Tensor, dict]:
+    target = batch["target_probs"]
+    valid = batch["candidate_valid"]
+    types = batch["question_type"]
+    if weights.score_smoothing > 0:
+        target = _grade_score_targets(target, valid, types, weights.score_smoothing)
+
+    log_probs = logits.float().log_softmax(-1)
+    probs = log_probs.exp()
+    ce = -(target * log_probs).sum(-1)
+    brier = ((probs - target) ** 2 * valid).sum(-1)
+
+    per_type = torch.tensor(
+        [weights.choice, weights.boolean, weights.score], device=logits.device)
+    w = per_type[types]
+    # Normalise within the batch so a lopsided type mix cannot change the step size.
+    w = w / w.mean().clamp(min=1e-6)
+
+    loss = (w * (ce + weights.brier * brier)).mean()
+    if weights.entropy:
+        entropy = -(probs.clamp_min(1e-9).log() * probs * valid).sum(-1)
+        loss = loss - weights.entropy * (w * entropy).mean()
+
+    with torch.no_grad():
+        picked = logits.argmax(-1)
+        best = target.argmax(-1)
+        # A tie counts as correct whenever the pick carries maximal target mass.
+        hit = target.gather(1, picked.unsqueeze(1)).squeeze(1)
+        top = target.max(-1).values
+        correct = (hit >= top - 1e-6).float()
+        stats = {
+            "loss": loss.detach(),
+            "ce": ce.mean().detach(),
+            "brier": brier.mean().detach(),
+            "acc": correct.mean().detach(),
+            "acc_choice": _masked_mean(correct, types == TYPE_INDEX["choice"]),
+            "acc_boolean": _masked_mean(correct, types == TYPE_INDEX["boolean"]),
+            "acc_score": _masked_mean(correct, types == TYPE_INDEX["score"]),
+            "tvd": _masked_mean(0.5 * (probs - target).abs().sum(-1),
+                                torch.ones_like(types, dtype=torch.bool)),
+        }
+        del best
+    return loss, stats
+
+
+def _masked_mean(values: torch.Tensor, mask: torch.Tensor) -> torch.Tensor:
+    if mask.sum() == 0:
+        return torch.tensor(float("nan"), device=values.device)
+    return values[mask].mean().detach()
+
+
+@torch.no_grad()
+def calibration_bins(probs: torch.Tensor, correct: torch.Tensor,
+                     bins: int = 10) -> dict:
+    """Expected calibration error over equal-width confidence bins."""
+    edges = torch.linspace(0, 1, bins + 1, device=probs.device)
+    total, ece = probs.numel(), torch.zeros((), device=probs.device)
+    rows = []
+    for i in range(bins):
+        lo, hi = edges[i], edges[i + 1]
+        mask = (probs > lo) & (probs <= hi) if i else (probs >= lo) & (probs <= hi)
+        count = int(mask.sum())
+        if not count:
+            rows.append({"bin": [float(lo), float(hi)], "count": 0})
+            continue
+        conf, acc = probs[mask].mean(), correct[mask].float().mean()
+        ece = ece + (count / total) * (conf - acc).abs()
+        rows.append({"bin": [float(lo), float(hi)], "count": count,
+                     "confidence": float(conf), "accuracy": float(acc)})
+    return {"ece": float(ece), "bins": rows}
+
+
+def squash_distance(dist: torch.Tensor, size: torch.Tensor,
+                    mode: str = "log") -> torch.Tensor:
+    """Map raw cell counts onto [0, 1].
+
+    ``log`` gives near-uniform resolution per doubling, which is the right
+    choice if you care about reading a distance off the field.  It is the wrong
+    choice if you care about *descending* it: neighbouring cells then differ by
+    ~1/d in target units, so contrast falls from 0.083 near the goal to 0.0098
+    forty cells out -- an 8.5x collapse, measured on a trained checkpoint whose
+    field MAE was 0.107, i.e. larger than the gap it had to resolve anywhere.
+
+    ``linear`` spends resolution uniformly: every neighbouring pair differs by
+    exactly 1/size^2 wherever it sits on the board.  Greedy descent has to win
+    *every* comparison along a path, so the weakest link sets the solve rate,
+    and a uniform target is the one that lifts the weakest link.
+
+    Rescaling alone would change nothing -- it scales the head's error by the
+    same factor -- so this is a change of shape, not of units.
+    """
+    area = size.to(dist.dtype).clamp(min=2.0) ** 2
+    if mode == "linear":
+        return dist.clamp(min=0.0) / area.view(-1, 1, 1)
+    return torch.log1p(dist.clamp(min=0.0)) / torch.log1p(area).view(-1, 1, 1)
+
+
+def _neighbours(x: torch.Tensor, fill: float) -> torch.Tensor:
+    """The four 4-neighbourhood shifts of an ``(S, H, W)`` map, stacked on dim 0.
+
+    Off-board cells are filled with ``fill`` so a neighbour past the border is
+    rejected by the same comparison that rejects a wall, with no edge case.
+    """
+    pads = ((0, 0, 1, 0), (0, 0, 0, 1), (1, 0, 0, 0), (0, 1, 0, 0))
+    crops = (lambda t: t[:, :-1, :], lambda t: t[:, 1:, :],
+             lambda t: t[:, :, :-1], lambda t: t[:, :, 1:])
+    return torch.stack([crop(F.pad(x, pad, value=fill))
+                        for pad, crop in zip(pads, crops)], dim=0)
+
+
+def descent_loss(dist_pred: torch.Tensor, dist_field: torch.Tensor,
+                 passable: torch.Tensor, size: torch.Tensor,
+                 margin_mult: float = 1.0) -> tuple:
+    """Supervise the ordering a greedy controller reads, not just the values.
+
+    Regressing each cell's distance is supervision on absolute values, but
+    descent never uses an absolute value: it compares a cell's four neighbours
+    and steps to the smallest.  Those two objectives come apart badly here.
+    Measured on a trained checkpoint, the field's MAE was 0.107 while the gap
+    between neighbouring target values was 0.0098 forty cells out -- the error
+    was an order of magnitude larger than the quantity being compared, so the
+    ordering was noise even where the values looked good.  The consequence is
+    not a slightly worse route: 70-93% of cells descended into a spurious basin
+    and cycled forever, which is what a solve rate of zero looks like up close.
+
+    So state the requirement directly.  For every cell with a true downhill
+    neighbour, the best predicted downhill neighbour must sit below every other
+    passable neighbour by a margin, and anything less is a hinge penalty.  The
+    margin is one true step (``margin_mult / area``), which asks the field to
+    separate real neighbours by at least as much as the truth separates them.
+
+    Returns ``(loss, ordered_fraction)`` where the second value is the share of
+    cells whose argmin already points along a shortest path -- the training-time
+    reading of the metric the controller's solve rate actually depends on.
+    """
+    inside = passable.squeeze(1) > 0.5                        # (S, H, W)
+    # The goal itself has no step to get right, and unreachable cells have no
+    # truth to compare against.
+    here_ok = inside & (dist_field > 0)
+
+    nb_true = _neighbours(dist_field, -1.0)
+    nb_inside = _neighbours(inside.to(dist_pred.dtype), 0.0) > 0.5
+    nb_pred = _neighbours(dist_pred, 0.0)
+
+    valid = nb_inside & (nb_true >= 0)
+    down = valid & nb_true.eq(dist_field.unsqueeze(0) - 1)
+    other = valid & ~down
+
+    big = torch.finfo(dist_pred.dtype).max
+    down_min = torch.where(down, nb_pred, nb_pred.new_full((), big)).amin(dim=0)
+
+    area = size.to(dist_pred.dtype).clamp(min=2.0) ** 2
+    margin = (margin_mult / area).view(-1, 1, 1)
+
+    rows = (here_ok & down.any(dim=0)).unsqueeze(0)
+    penal = torch.relu(down_min.unsqueeze(0) + margin - nb_pred) * (other & rows)
+    count = (other & rows).sum().clamp(min=1)
+
+    with torch.no_grad():
+        other_min = torch.where(other, nb_pred, nb_pred.new_full((), big)).amin(dim=0)
+        # A cell is ordered when its best downhill neighbour beats every other
+        # one.  Cells whose neighbours are all downhill are ordered by
+        # construction -- any move is correct -- and the ``big`` fill makes that
+        # fall out of the same comparison.
+        ordered = ((down_min < other_min) & rows.squeeze(0)).sum()
+        total = rows.sum().clamp(min=1)
+
+    return penal.sum() / count, float(ordered / total)
+
+
+def field_loss(pred: torch.Tensor, dist_field: torch.Tensor,
+               passable: torch.Tensor, size: torch.Tensor,
+               mode: str = "log", descent_weight: float = 0.0,
+               descent_margin: float = 1.0) -> tuple:
+    """Dense planner supervision.
+
+    ``pred`` is (S, 2, H, W): channel 0 regresses the squashed distance to the
+    target over reachable cells, channel 1 classifies reachability over every
+    cell inside the board. Padding outside a board is excluded from both.
+    """
+    inside = passable.squeeze(1) > 0.5                      # (S, H, W)
+    reachable = dist_field >= 0.0
+    target = squash_distance(dist_field, size, mode)
+
+    dist_pred = pred[:, 0]
+    mask = reachable & inside
+    count = mask.sum().clamp(min=1)
+    dist_term = (torch.nn.functional.smooth_l1_loss(
+        dist_pred, target, beta=0.05, reduction="none") * mask).sum() / count
+
+    reach_term = (torch.nn.functional.binary_cross_entropy_with_logits(
+        pred[:, 1], reachable.to(pred.dtype), reduction="none")
+        * inside).sum() / inside.sum().clamp(min=1)
+
+    with torch.no_grad():
+        abs_err = ((dist_pred - target).abs() * mask).sum()
+        sse = (((dist_pred - target) ** 2) * mask).sum()
+        tsum = (target * mask).sum()
+        tsq = ((target ** 2) * mask).sum()
+        centred = (tsq - tsum ** 2 / count).clamp(min=1e-9)
+        r2 = 1.0 - sse / centred
+    total = dist_term + 0.3 * reach_term
+    extra = {}
+    if descent_weight > 0:
+        order_term, ordered = descent_loss(dist_pred, dist_field, passable,
+                                           size, descent_margin)
+        total = total + descent_weight * order_term
+        # Only reported when the term is on, so a caller that averages the
+        # stats never has to average a placeholder.
+        extra = {"field_order": float(order_term.detach()),
+                 "field_ordered": ordered}
+
+    return total, {
+        **extra,
+        "field": float(dist_term.detach()),
+        # A penalty, so lower is better and 0 is perfect. Not to be read as
+        # probe.py's `reach_rate`, which is a fraction of cells and where
+        # higher is better -- these sit next to each other in a run directory
+        # and mean opposite things by the same word.
+        "field_reach": float(reach_term.detach()),
+        "field_mae": float(abs_err / count), "field_r2": float(r2),
+        # Raw sums so a caller spanning several batches can pool the statistic.
+        # R^2 is a ratio of sums and is NOT averageable: one batch of boards
+        # with little distance variance sends its own R^2 arbitrarily negative
+        # and drags a mean with it, which is what made field_r2 look like it
+        # was collapsing during training when the pooled value was fine.
+        "_f_sse": float(sse), "_f_abs": float(abs_err), "_f_sum": float(tsum),
+        "_f_sumsq": float(tsq), "_f_n": float(count)}

jevon/modeling.py

@@ -0,0 +1,390 @@
+"""Jevon: a System-One decision model with a spatial planner.
+
+Contract (identical to Jev/NanoJev): a request carries states, each with a map
+of typed questions -- ``choice`` over 2..255 dynamic candidates, ``boolean``
+over a proposition, ``score`` over 2..10 ordered levels.  Every question returns
+a complete probability distribution and nothing is decoded token by token.
+
+Three things differ from NanoJev's implementation:
+
+1. **Shared prefix.**  NanoJev re-encodes the whole state once per candidate.
+   Here the state and question are encoded once and candidates cross-attend to
+   that encoding, so cost is ``|prefix| + K*|candidate|`` rather than
+   ``K*(|prefix| + |candidate|)``.
+2. **Structured board input.**  A 50x50 maze flattened into ASCII puts
+   vertically adjacent cells 51 tokens apart.  Jevon reads the board as a
+   ``(C, H, W)`` tensor through :class:`~jevon.planner.SpatialPlanner`, which
+   has the 2D adjacency built in.
+3. **Anchored candidates.**  A candidate that names a cell carries that cell's
+   coordinate, so the scoring head reads the planner's feature for exactly the
+   cell the candidate would move to.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import torch
+from torch import nn
+import torch.nn.functional as F
+
+from .planner import MinPlusField, SpatialPlanner, default_iterations
+
+QUESTION_TYPES: tuple[str, ...] = ("choice", "boolean", "score")
+TYPE_INDEX = {name: i for i, name in enumerate(QUESTION_TYPES)}
+
+
+@dataclass
+class JevonConfig:
+    vocab_size: int = 4096
+    d_model: int = 384
+    n_heads: int = 6
+    prefix_layers: int = 6
+    candidate_layers: int = 2
+    set_layers: int = 2
+    ffn_mult: int = 4
+    dropout: float = 0.1
+    max_prefix_len: int = 320
+    max_candidate_len: int = 48
+    # Spatial planner
+    grid_channels: int = 8
+    planner_dim: int = 96
+    planner_blocks: int = 2
+    planner_grad_steps: int = 8
+    local_patch: int = 5
+    use_planner: bool = True
+    # Let the text side read the planner's own distance/reach read-out at
+    # the cells it gathers, instead of re-deriving it from raw features.
+    expose_field: bool = False
+    # Read the distance off a min-plus recurrence instead of a 1x1 conv, which
+    # makes the field a genuine shortest-path distance and so traversable by
+    # construction. Pairs with --field-target linear; see MinPlusField.
+    min_plus_field: bool = False
+
+    def to_dict(self) -> dict:
+        return dict(self.__dict__)
+
+
+def _mha(d_model: int, n_heads: int, dropout: float) -> nn.MultiheadAttention:
+    return nn.MultiheadAttention(d_model, n_heads, dropout=dropout, batch_first=True)
+
+
+class EncoderLayer(nn.Module):
+    """Pre-norm self-attention block, optionally with cross-attention."""
+
+    def __init__(self, cfg: JevonConfig, cross: bool = False):
+        super().__init__()
+        d = cfg.d_model
+        self.norm_self = nn.LayerNorm(d)
+        self.self_attn = _mha(d, cfg.n_heads, cfg.dropout)
+        self.cross = cross
+        if cross:
+            self.norm_q = nn.LayerNorm(d)
+            self.norm_kv = nn.LayerNorm(d)
+            self.cross_attn = _mha(d, cfg.n_heads, cfg.dropout)
+        self.norm_ffn = nn.LayerNorm(d)
+        self.ffn = nn.Sequential(
+            nn.Linear(d, d * cfg.ffn_mult), nn.GELU(),
+            nn.Dropout(cfg.dropout), nn.Linear(d * cfg.ffn_mult, d),
+        )
+        self.drop = nn.Dropout(cfg.dropout)
+
+    def forward(self, x, pad_mask=None, memory=None, memory_pad_mask=None):
+        h = self.norm_self(x)
+        attn, _ = self.self_attn(h, h, h, key_padding_mask=pad_mask, need_weights=False)
+        x = x + self.drop(attn)
+        if self.cross and memory is not None:
+            q = self.norm_q(x)
+            kv = self.norm_kv(memory)
+            attn, _ = self.cross_attn(q, kv, kv, key_padding_mask=memory_pad_mask,
+                                      need_weights=False)
+            x = x + self.drop(attn)
+        return x + self.drop(self.ffn(self.norm_ffn(x)))
+
+
+class JevonModel(nn.Module):
+    def __init__(self, cfg: JevonConfig):
+        super().__init__()
+        self.cfg = cfg
+        d = cfg.d_model
+        self.token_embed = nn.Embedding(cfg.vocab_size, d, padding_idx=0)
+        self.prefix_pos = nn.Embedding(cfg.max_prefix_len, d)
+        self.candidate_pos = nn.Embedding(cfg.max_candidate_len, d)
+        self.type_embed = nn.Embedding(len(QUESTION_TYPES), d)
+        self.drop = nn.Dropout(cfg.dropout)
+
+        self.prefix_layers = nn.ModuleList(
+            EncoderLayer(cfg) for _ in range(cfg.prefix_layers))
+        self.prefix_norm = nn.LayerNorm(d)
+        self.candidate_layers = nn.ModuleList(
+            EncoderLayer(cfg, cross=True) for _ in range(cfg.candidate_layers))
+        self.candidate_norm = nn.LayerNorm(d)
+        self.candidate_pool = nn.Linear(d, 1)
+
+        if cfg.use_planner:
+            self.planner = SpatialPlanner(cfg.grid_channels, cfg.planner_dim,
+                                          cfg.planner_blocks)
+            gathered = cfg.planner_dim + (2 if cfg.expose_field else 0)
+            self.gathered_dim = gathered
+            self.grid_to_text = nn.Linear(gathered, d)
+            self.grid_token_type = nn.Embedding(4, d)   # pooled / focus / target / patch
+            self.anchor_proj = nn.Sequential(
+                nn.Linear(gathered * 3, d), nn.GELU(), nn.Linear(d, d))
+            # Dense read-out used only as a training signal: channel 0 is the
+            # squashed distance to the target, channel 1 a reachability logit.
+            # Every free cell supervises the recurrence, so the planner learns
+            # a real value function instead of whatever the sparse decision
+            # questions happen to reward.
+            self.field_head = nn.Conv2d(cfg.planner_dim, 2, 1)
+            # The min-plus head is a read-out, not a replacement. Its output
+            # matches BFS at initialisation, so a field loss on it is ~0 from
+            # step one and its zero-initialised cost conv passes no gradient
+            # back -- which would quietly retire the dense planner supervision
+            # section 3 exists to provide. Keeping the conv head supervised
+            # preserves that signal; the min-plus head is what gets read.
+            self.min_plus = (MinPlusField(cfg.planner_dim)
+                             if cfg.min_plus_field else None)
+        else:
+            self.planner = None
+            self.field_head = None
+            self.min_plus = None
+
+        feature_dim = d * 2
+        self.score_head = nn.Sequential(
+            nn.LayerNorm(feature_dim), nn.Linear(feature_dim, d), nn.GELU(),
+            nn.Linear(d, 1))
+        self.set_layers = nn.ModuleList(
+            EncoderLayer(cfg) for _ in range(cfg.set_layers))
+        self.set_norm = nn.LayerNorm(d)
+        self.set_out = nn.Linear(d, 1)
+        nn.init.zeros_(self.set_out.weight)
+        nn.init.zeros_(self.set_out.bias)
+        self.count_embed = nn.Linear(1, d)
+
+        self.apply(self._init)
+
+    @staticmethod
+    def _init(module: nn.Module) -> None:
+        if isinstance(module, nn.Linear):
+            nn.init.normal_(module.weight, std=0.02)
+            if module.bias is not None:
+                nn.init.zeros_(module.bias)
+        elif isinstance(module, nn.Embedding):
+            nn.init.normal_(module.weight, std=0.02)
+
+    # ------------------------------------------------------------------
+    # Channel 2 is the agent/head cell. It is withheld from the planner so the
+    # field it computes describes the *board* -- distance to the goal, reachable
+    # space around the food -- and not the agent. Two things follow: a maze field
+    # stays valid for a whole episode and can be computed once, and the readout
+    # below is forced to locate the agent by gathering cells rather than by
+    # memorising a position-specific shortcut.
+    FOCUS_CHANNEL = 2
+
+    def encode_boards(self, boards, passable, iterations, grad_steps=None):
+        if self.planner is None or boards is None:
+            return None
+        boards = boards.clone()
+        boards[:, self.FOCUS_CHANNEL] = 0.0
+        return self.planner(
+            boards, passable, iterations=iterations,
+            grad_steps=self.cfg.planner_grad_steps if grad_steps is None else grad_steps)
+
+    def predict_field(self, cells: torch.Tensor, board: Optional[torch.Tensor] = None,
+                      passable: Optional[torch.Tensor] = None, *,
+                      iterations: Optional[int] = None,
+                      grad_steps: Optional[int] = None) -> torch.Tensor:
+        """(S, P, H, W) planner features -> (S, 2, H, W) distance / reach.
+
+        This is the *read-out*: what the controller descends and what
+        ``expose_field`` shows the text side. :meth:`supervised_field` is the
+        one the field loss trains. They are the same conv head unless
+        ``min_plus_field`` is set.
+
+        ``board`` and ``passable`` are required only by the min-plus head, which
+        needs the walls and the goal to run its recurrence over. The conv head
+        ignores them, so existing callers keep working unchanged.
+        """
+        if self.min_plus is None:
+            return self.field_head(cells)
+        if board is None or passable is None:
+            raise ValueError(
+                "min_plus_field needs the board and passable mask; pass them to "
+                "predict_field(cells, board, passable)")
+        steps = iterations or default_iterations(min(board.shape[-2:]))
+        return self.min_plus(
+            cells, board, passable, iterations=steps,
+            grad_steps=(self.cfg.planner_grad_steps if grad_steps is None
+                        else grad_steps))
+
+    def supervised_field(self, cells: torch.Tensor) -> torch.Tensor:
+        """The field head the loss trains, which is always the conv one.
+
+        Its job is to keep dense gradient flowing into the recurrence, so it
+        stays on even when the min-plus read-out makes its output redundant for
+        the controller.
+        """
+        return self.field_head(cells)
+
+    def _readable(self, cells: torch.Tensor, board: Optional[torch.Tensor] = None,
+                  passable: Optional[torch.Tensor] = None) -> torch.Tensor:
+        """Planner features as the text side sees them.
+
+        The field head is trained on every free cell, so its output is the most
+        distilled form of exactly what the distance question asks.  Without this
+        the transformer has to re-learn that same linear map from the raw
+        planner features, through a far sparser signal.
+
+        Computed once per forward pass and threaded to both gather sites.  The
+        min-plus head runs a T-step recurrence, and T is in the hundreds, so
+        recomputing it per site was pure duplicated work.
+        """
+        if not self.cfg.expose_field:
+            return cells
+        return torch.cat([cells, self.predict_field(cells, board, passable)], dim=1)
+
+    def _grid_tokens(self, cells, question_state, focus, target):
+        """Board summary tokens prepended to each question's prefix.
+
+        ``cells``  (S, P, H, W) planner features
+        ``focus``  (Q, 2) the agent/head cell; ``target`` (Q, 2) goal/food cell.
+        """
+        q_cells = cells[question_state]                      # (Q, P, H, W)
+        flat = q_cells.flatten(2)                             # (Q, P, HW)
+        pooled = torch.stack([flat.mean(-1), flat.amax(-1)], dim=1)   # (Q, 2, P)
+        focus_vec = self._gather_cells(q_cells, focus).unsqueeze(1)
+        target_vec = self._gather_cells(q_cells, target).unsqueeze(1)
+        patch = self._gather_patch(q_cells, focus, self.cfg.local_patch)
+
+        tokens = torch.cat([pooled, focus_vec, target_vec, patch], dim=1)
+        tokens = self.grid_to_text(tokens)
+        kinds = torch.tensor(
+            [0, 0, 1, 2] + [3] * patch.shape[1], device=tokens.device)
+        return tokens + self.grid_token_type(kinds).unsqueeze(0)
+
+    @staticmethod
+    def _gather_cells(cells, coords):
+        """``cells`` (Q, P, H, W), ``coords`` (Q, 2) -> (Q, P). Negative rows give zeros."""
+        q, p, h, w = cells.shape
+        rows = coords[:, 0].clamp(0, h - 1)
+        cols = coords[:, 1].clamp(0, w - 1)
+        index = (rows * w + cols).view(q, 1, 1).expand(q, p, 1)
+        out = cells.flatten(2).gather(2, index).squeeze(2)
+        return out * (coords[:, :1] >= 0).to(out.dtype)
+
+    @staticmethod
+    def _gather_patch(cells, centre, patch):
+        q, p, h, w = cells.shape
+        radius = patch // 2
+        offsets = torch.arange(-radius, radius + 1, device=cells.device)
+        dr = offsets.view(-1, 1).expand(patch, patch).reshape(-1)
+        dc = offsets.view(1, -1).expand(patch, patch).reshape(-1)
+        rows = (centre[:, :1] + dr.view(1, -1))
+        cols = (centre[:, 1:2] + dc.view(1, -1))
+        inside = ((rows >= 0) & (rows < h) & (cols >= 0) & (cols < w)).unsqueeze(-1)
+        index = (rows.clamp(0, h - 1) * w + cols.clamp(0, w - 1))
+        index = index.unsqueeze(1).expand(q, p, patch * patch)
+        out = cells.flatten(2).gather(2, index).transpose(1, 2)      # (Q, patch^2, P)
+        return out * inside.to(out.dtype)
+
+    # ------------------------------------------------------------------
+    def forward(self, batch: dict, *, iterations: Optional[int] = None,
+                grad_steps: Optional[int] = None,
+                cells: Optional[torch.Tensor] = None) -> torch.Tensor:
+        """Returns candidate logits of shape ``(Q, Kmax)``, padded with -1e9.
+
+        ``cells`` lets a caller supply a planner field computed earlier.  A maze
+        field depends only on walls and goal, so an episode computes it once and
+        reuses it for every step.
+        """
+        cfg = self.cfg
+        prefix_ids = batch["prefix_ids"]                 # (Q, Lp)
+        cand_ids = batch["candidate_ids"]                # (Q, K, Lc)
+        cand_valid = batch["candidate_valid"]            # (Q, K) bool
+        q, kmax, lc = cand_ids.shape
+        device = prefix_ids.device
+
+        if cells is None and cfg.use_planner and batch.get("boards") is not None:
+            steps = iterations or default_iterations(int(batch["board_size"].max()))
+            cells = self.encode_boards(batch["boards"], batch["passable"], steps, grad_steps)
+
+        # --- prefix ---------------------------------------------------
+        positions = torch.arange(prefix_ids.shape[1], device=device)
+        x = self.token_embed(prefix_ids) + self.prefix_pos(positions).unsqueeze(0)
+        x = x + self.type_embed(batch["question_type"]).unsqueeze(1)
+        prefix_pad = prefix_ids.eq(0)
+        readable = (self._readable(cells, batch.get("boards"), batch.get("passable"))
+                    if cells is not None else None)
+        if cells is not None:
+            grid_tokens = self._grid_tokens(
+                readable, batch["question_state"], batch["focus"], batch["target"])
+            x = torch.cat([grid_tokens, x], dim=1)
+            prefix_pad = torch.cat(
+                [torch.zeros(q, grid_tokens.shape[1], dtype=torch.bool, device=device),
+                 prefix_pad], dim=1)
+        x = self.drop(x)
+        for layer in self.prefix_layers:
+            x = layer(x, pad_mask=prefix_pad)
+        memory = self.prefix_norm(x)
+
+        # --- candidates cross-attend to the shared prefix --------------
+        positions = torch.arange(lc, device=device)
+        c = self.token_embed(cand_ids) + self.candidate_pos(positions).view(1, 1, lc, -1)
+        c = self.drop(c).reshape(q * kmax, lc, cfg.d_model)
+        cand_pad = cand_ids.eq(0).reshape(q * kmax, lc)
+        # A fully padded row would make softmax produce NaNs; let it see slot 0.
+        empty = cand_pad.all(dim=1)
+        cand_pad = cand_pad.clone()
+        cand_pad[empty, 0] = False
+        mem = memory.unsqueeze(1).expand(q, kmax, memory.shape[1], cfg.d_model)
+        mem = mem.reshape(q * kmax, memory.shape[1], cfg.d_model)
+        mem_pad = prefix_pad.unsqueeze(1).expand(q, kmax, prefix_pad.shape[1])
+        mem_pad = mem_pad.reshape(q * kmax, prefix_pad.shape[1])
+        for layer in self.candidate_layers:
+            c = layer(c, pad_mask=cand_pad, memory=mem, memory_pad_mask=mem_pad)
+        c = self.candidate_norm(c)
+
+        weights = self.candidate_pool(c).masked_fill(cand_pad.unsqueeze(-1), -1e9)
+        pooled = (c * weights.softmax(dim=1)).sum(dim=1).reshape(q, kmax, cfg.d_model)
+
+        # --- anchor the candidate on the cell it would move to ---------
+        if cells is not None:
+            anchors = batch["anchors"]                              # (Q, K, 2)
+            q_cells = readable[batch["question_state"]]
+            flat_anchor = anchors.reshape(q * kmax, 2)
+            rep = q_cells.repeat_interleave(kmax, dim=0)
+            anchor_vec = self._gather_cells(rep, flat_anchor).reshape(q, kmax, -1)
+            focus_vec = self._gather_cells(q_cells, batch["focus"]).unsqueeze(1)
+            target_vec = self._gather_cells(q_cells, batch["target"]).unsqueeze(1)
+            pooled = pooled + self.anchor_proj(torch.cat([
+                anchor_vec,
+                anchor_vec - focus_vec.expand_as(anchor_vec),
+                target_vec.expand_as(anchor_vec),
+            ], dim=-1))
+
+        # --- set reasoning over the live candidate set -----------------
+        count = cand_valid.sum(-1, keepdim=True).clamp(min=1).float().log()
+        h = pooled + self.count_embed(count).unsqueeze(1)
+        set_pad = ~cand_valid
+        set_pad = set_pad.clone()
+        set_pad[set_pad.all(dim=1), 0] = False
+        for layer in self.set_layers:
+            h = layer(h, pad_mask=set_pad)
+        h = self.set_norm(h)
+        delta = self.set_out(h).squeeze(-1)
+
+        base = self.score_head(torch.cat([pooled, h], dim=-1)).squeeze(-1)
+        logits = base + delta
+
+        # Boolean questions carry one semantic path; its logit pairs with a
+        # fixed zero so the distribution is [P(false), P(true)].
+        is_boolean = batch["question_type"].eq(TYPE_INDEX["boolean"])
+        if is_boolean.any():
+            paired = torch.stack([torch.zeros_like(logits[:, 0]), logits[:, 0]], dim=-1)
+            padded = F.pad(paired, (0, max(kmax - 2, 0)), value=-1e9)[:, :kmax]
+            logits = torch.where(is_boolean.unsqueeze(-1), padded, logits)
+
+        return logits.masked_fill(~cand_valid, -1e9)
+
+    def num_parameters(self) -> int:
+        return sum(p.numel() for p in self.parameters())

jevon/planner.py

@@ -0,0 +1,227 @@
+"""Recurrent spatial planner: amortised value iteration over a grid.
+
+A fixed-depth transformer reading a flattened ASCII board cannot compute a
+shortest path: the answer needs a number of propagation steps proportional to
+the path length, and on a 50x50 corridor maze that is a couple of hundred.
+This module supplies that depth with a weight-shared message-passing block run
+for ``T`` iterations over the 4-neighbourhood, which is the same recurrence
+Bellman-Ford uses.  Walls block messages, so the signal follows corridors.
+
+Two properties matter for generalisation:
+
+* weights are shared across iterations, so ``T`` can be raised at inference to
+  suit a larger board than anything seen in training;
+* only the final ``grad_steps`` iterations carry gradient (the earlier ones run
+  under ``no_grad``), which keeps memory flat in ``T`` and is the standard
+  phantom-gradient trick for implicit/equilibrium models.
+"""
+from __future__ import annotations
+
+import torch
+from torch import nn
+import torch.nn.functional as F
+
+
+def _shift(x: torch.Tensor, dr: int, dc: int, fill: float = 0.0) -> torch.Tensor:
+    """Translate a ``(B, D, H, W)`` map, filling the exposed border with ``fill``."""
+    if dr:
+        x = F.pad(x, (0, 0, max(dr, 0), max(-dr, 0)), value=fill)
+        x = x[:, :, : x.shape[2] - abs(dr), :] if dr > 0 else x[:, :, abs(dr):, :]
+    if dc:
+        x = F.pad(x, (max(dc, 0), max(-dc, 0), 0, 0), value=fill)
+        x = x[:, :, :, : x.shape[3] - abs(dc)] if dc > 0 else x[:, :, :, abs(dc):]
+    return x
+
+
+class RMSNorm2d(nn.Module):
+    def __init__(self, dim: int, eps: float = 1e-6):
+        super().__init__()
+        self.weight = nn.Parameter(torch.ones(dim))
+        self.eps = eps
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        norm = x.float().pow(2).mean(dim=1, keepdim=True).add(self.eps).rsqrt()
+        return (x.float() * norm).to(x.dtype) * self.weight.view(1, -1, 1, 1)
+
+
+class PlannerBlock(nn.Module):
+    """One propagation step: gather from passable neighbours, then gate an update."""
+
+    def __init__(self, dim: int, static_dim: int, hidden_mult: int = 2):
+        super().__init__()
+        self.norm = RMSNorm2d(dim)
+        self.message = nn.Conv2d(dim, dim, 1, bias=False)
+        # max-pool and mean-pool over neighbours, the current cell, and the
+        # static board channels (walls, goal, food) which never change with t.
+        fan_in = dim * 3 + static_dim
+        hidden = dim * hidden_mult
+        self.mix = nn.Sequential(
+            nn.Conv2d(fan_in, hidden, 1),
+            nn.GELU(),
+            nn.Conv2d(hidden, dim * 2, 1),
+        )
+        # A zero final weight would start the recurrence at exactly the identity
+        # but also zero the gradient of everything feeding it, so the first step
+        # trains nothing upstream. Small random weights plus a negative gate bias
+        # give a near-identity start that is still differentiable everywhere.
+        nn.init.normal_(self.mix[-1].weight, std=0.02)
+        nn.init.zeros_(self.mix[-1].bias)
+        self.gate_bias = nn.Parameter(torch.full((dim,), -2.0))
+
+    def forward(self, h: torch.Tensor, passable: torch.Tensor,
+                static: torch.Tensor) -> torch.Tensor:
+        normed = self.norm(h)
+        msg = self.message(normed) * passable
+        neighbours = torch.stack(
+            [_shift(msg, -1, 0), _shift(msg, 1, 0), _shift(msg, 0, -1), _shift(msg, 0, 1)],
+            dim=0,
+        )
+        # Masked max-pool: a wall neighbour must not win the max.
+        agg_max = neighbours.amax(dim=0)
+        agg_mean = neighbours.mean(dim=0)
+        update, gate = self.mix(
+            torch.cat([normed, agg_max, agg_mean, static], dim=1)
+        ).chunk(2, dim=1)
+        gate = torch.sigmoid(gate + self.gate_bias.view(1, -1, 1, 1))
+        return (h + gate * update) * passable
+
+
+class SpatialPlanner(nn.Module):
+    """Stack of shared-weight propagation steps over a board."""
+
+    def __init__(self, in_channels: int, dim: int = 64, blocks: int = 2,
+                 hidden_mult: int = 2):
+        super().__init__()
+        self.dim = dim
+        self.stem = nn.Sequential(
+            nn.Conv2d(in_channels, dim, 3, padding=1),
+            nn.GELU(),
+            nn.Conv2d(dim, dim, 1),
+        )
+        self.static_proj = nn.Conv2d(in_channels, dim // 2, 1)
+        self.blocks = nn.ModuleList(
+            PlannerBlock(dim, dim // 2, hidden_mult) for _ in range(blocks)
+        )
+        self.out_norm = RMSNorm2d(dim)
+
+    def forward(self, board: torch.Tensor, passable: torch.Tensor, *,
+                iterations: int, grad_steps: int = 8) -> torch.Tensor:
+        """``board``: (B, C, H, W). ``passable``: (B, 1, H, W) with 1 on open cells.
+
+        Returns per-cell features of shape (B, dim, H, W).
+        """
+        static = self.static_proj(board)
+        stem = self.stem(board) * passable
+        h = stem
+
+        no_grad_steps = max(0, iterations - max(grad_steps, 1))
+        if no_grad_steps:
+            with torch.no_grad():
+                for step in range(no_grad_steps):
+                    h = self.blocks[step % len(self.blocks)](h, passable, static)
+            # Re-attach the stem so it still receives a gradient. Detaching the
+            # loop alone would sever the stem's only path to the loss and leave
+            # the input projection frozen at initialisation.
+            h = h.detach() + (stem - stem.detach())
+        for step in range(no_grad_steps, iterations):
+            h = self.blocks[step % len(self.blocks)](h, passable, static)
+        return self.out_norm(h)
+
+
+def default_iterations(size: int, cap: int = 4096) -> int:
+    """Propagation budget for a board of side ``size``.
+
+    One iteration moves information one cell, so the budget has to cover the
+    board's *diameter*, not its side length.  A spanning-tree maze winds through
+    nearly every free cell: measured diameters are 48 at 11x11, 312 at 31x31 and
+    750 at 51x51, all far beyond any multiple of the side length.  The quadratic
+    term tracks that growth with roughly 2x headroom, which is affordable because
+    one iteration is a pair of 1x1 convolutions.
+    """
+    return int(min(cap, max(32, 2 * size + (size * size) // 2)))
+
+
+class MinPlusField(nn.Module):
+    """Shortest-path distance under a learned per-cell cost.
+
+    The planner's features are read by a 1x1 convolution to get a distance, and
+    nothing about that arrangement makes the result traversable.  Measured on a
+    trained checkpoint, 72% of cells at 11x11 and 93% at 21x21 descended into a
+    spurious basin and cycled; penalising the local ordering directly moved the
+    reachable fraction only from 0.104 to 0.132 even at five times the weight.
+    Global monotonicity is not something a sum of local penalties delivers.
+
+    A min-plus recurrence delivers it by construction.  Iterating
+
+        v(c) <- cost(c) + min over passable neighbours n of v(n),   v(goal) = 0
+
+    from ``v = BIG`` is Bellman-Ford, so with strictly positive costs the fixed
+    point *is* a shortest-path distance: every non-goal cell has a neighbour
+    strictly below it, and greedy descent therefore terminates at the goal from
+    anywhere.  The trap mode is not reduced, it is removed.
+
+    What is left to learn is a cost per cell -- a local quantity, which is the
+    kind of thing a convolution is good at -- while the global structure comes
+    from the recurrence.  This is the Value-Iteration-Network idea (Tamar et
+    al., 2016) with the max-plus reward recurrence replaced by the min-plus
+    distance one the field head is actually supervised on.
+
+    Costs are emitted in units of ``1 / area``, so the output is on the same
+    scale as a ``linear`` distance target, whose steps are a uniform
+    ``1 / area`` apart. That mattered while this head was the one the field
+    loss trained. It no longer is: the conv head stayed supervised precisely so
+    the dense signal survives, and this head is only ever read. Nothing here is
+    compared against a target, so ``--field-target`` is free to be whatever
+    trains the planner best, and the two flags are independent.
+    """
+
+    BIG = 1.0e4
+
+    def __init__(self, dim: int, target_channel: int = 3):
+        super().__init__()
+        self.cost = nn.Conv2d(dim, 1, 1)
+        self.reach = nn.Conv2d(dim, 1, 1)
+        self.target_channel = target_channel
+        # softplus(0.54) ~= 1.0, so the recurrence starts out measuring plain
+        # step count and the model adjusts from a sensible place rather than
+        # from a cost of zero, which would make every distance zero.
+        nn.init.zeros_(self.cost.weight)
+        nn.init.constant_(self.cost.bias, 0.5413)
+
+    def forward(self, cells: torch.Tensor, board: torch.Tensor,
+                passable: torch.Tensor, *, iterations: int,
+                grad_steps: int = 8) -> torch.Tensor:
+        """``(S, dim, H, W)`` features -> ``(S, 2, H, W)`` distance / reach."""
+        inside = board.abs().sum(dim=1, keepdim=True) > 0      # (S,1,H,W)
+        area = inside.flatten(1).sum(dim=1).clamp(min=4.0)
+        area = area.to(cells.dtype).view(-1, 1, 1, 1)
+        cost = F.softplus(self.cost(cells)) / area
+
+        goal = board[:, self.target_channel: self.target_channel + 1] > 0.5
+        open_cell = (passable > 0.5) | goal            # the goal must be enterable
+        zero = torch.zeros((), dtype=cells.dtype, device=cells.device)
+        big = torch.full((), self.BIG, dtype=cells.dtype, device=cells.device)
+
+        v = torch.where(goal, zero, big).expand_as(cost).contiguous()
+
+        def sweep(v: torch.Tensor) -> torch.Tensor:
+            # Shifting in BIG rather than 0 is what makes the border correct
+            # without a separate mask: an off-board neighbour looks exactly like
+            # an unreached one.  Padding cells are already BIG because they are
+            # outside ``open_cell``, so the same argument covers them.
+            best = _shift(v, -1, 0, self.BIG)
+            for dr, dc in ((1, 0), (0, -1), (0, 1)):
+                best = torch.minimum(best, _shift(v, dr, dc, self.BIG))
+            out = (cost + best).clamp(max=self.BIG)
+            out = torch.where(goal, zero, out)
+            return torch.where(open_cell, out, big)
+
+        free_steps = max(0, iterations - max(grad_steps, 1))
+        if free_steps:
+            with torch.no_grad():
+                for _ in range(free_steps):
+                    v = sweep(v)
+            v = v.detach()
+        for _ in range(free_steps, iterations):
+            v = sweep(v)
+        return torch.cat([v, self.reach(cells)], dim=1)

jevon/tokenizer.py

@@ -0,0 +1,101 @@
+"""A compact word-level tokenizer with byte fallback.
+
+Jevon-S is trained from scratch, so a 150k-entry subword vocabulary would put
+most of the parameter budget in an embedding table that the task never
+exercises.  This tokenizer keeps the vocabulary in the low thousands: words seen
+during corpus construction become single ids, and anything unseen decomposes
+into bytes, so no input is ever rejected.
+"""
+from __future__ import annotations
+
+import json
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Iterable, Sequence
+
+PAD, UNK, BOS, EOS, SEP = "<pad>", "<unk>", "<bos>", "<eos>", "<sep>"
+SPECIALS: tuple[str, ...] = (PAD, UNK, BOS, EOS, SEP)
+
+# Words, signed integers, and single non-space symbols. Coordinates such as
+# "(12,7)" split into "(", "12", ",", "7", ")" so numbers stay atomic.
+_PATTERN = re.compile(r"[A-Za-z]+|\d+|[^\sA-Za-z\d]")
+
+
+class JevonTokenizer:
+    def __init__(self, vocab: Sequence[str]):
+        self.itos = list(vocab)
+        self.stoi = {tok: i for i, tok in enumerate(self.itos)}
+        for special in SPECIALS:
+            if special not in self.stoi:
+                raise ValueError(f"vocabulary is missing {special!r}")
+        self.pad_id = self.stoi[PAD]
+        self.unk_id = self.stoi[UNK]
+        self.bos_id = self.stoi[BOS]
+        self.eos_id = self.stoi[EOS]
+        self.sep_id = self.stoi[SEP]
+        self._byte_base = self.stoi.get("<byte_0>")
+
+    def __len__(self) -> int:
+        return len(self.itos)
+
+    @classmethod
+    def build(cls, corpus: Iterable[str], max_vocab: int = 4096,
+              min_count: int = 2) -> "JevonTokenizer":
+        counts: Counter[str] = Counter()
+        for text in corpus:
+            counts.update(_PATTERN.findall(text.lower()))
+        vocab = list(SPECIALS)
+        vocab += [f"<byte_{i}>" for i in range(256)]     # always-available fallback
+        room = max_vocab - len(vocab)
+        seen = set(vocab)
+        for token, count in counts.most_common():
+            if room <= 0:
+                break
+            if count < min_count or token in seen:
+                continue
+            vocab.append(token)
+            seen.add(token)
+            room -= 1
+        return cls(vocab)
+
+    def encode(self, text: str, *, add_bos: bool = False,
+               add_eos: bool = False) -> list[int]:
+        ids: list[int] = [self.bos_id] if add_bos else []
+        for token in _PATTERN.findall(text.lower()):
+            index = self.stoi.get(token)
+            if index is not None:
+                ids.append(index)
+            elif self._byte_base is not None:
+                ids.extend(self._byte_base + b for b in token.encode("utf-8"))
+            else:
+                ids.append(self.unk_id)
+        if add_eos:
+            ids.append(self.eos_id)
+        return ids
+
+    def decode(self, ids: Sequence[int]) -> str:
+        out, pending = [], bytearray()
+
+        def flush() -> None:
+            if pending:
+                out.append(pending.decode("utf-8", errors="replace"))
+                pending.clear()
+
+        for index in ids:
+            token = self.itos[index] if 0 <= index < len(self.itos) else UNK
+            if token.startswith("<byte_") and token.endswith(">"):
+                pending.append(int(token[6:-1]))
+                continue
+            flush()
+            if token not in SPECIALS:
+                out.append(token)
+        flush()
+        return " ".join(out)
+
+    def save(self, path: str | Path) -> None:
+        Path(path).write_text(json.dumps({"vocab": self.itos}, ensure_ascii=False))
+
+    @classmethod
+    def load(cls, path: str | Path) -> "JevonTokenizer":
+        return cls(json.loads(Path(path).read_text())["vocab"])

pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "jevon"
+version = "0.1.0"
+description = "A small typed-decision model with a recurrent spatial planner"
+readme = "README.md"
+requires-python = ">=3.10"
+# SPDX. The Hub's own vocabulary spells this `agpl-3.0`, which is what
+# README.md's front matter carries; the test suite checks the two agree.
+license = { text = "AGPL-3.0-or-later" }
+dependencies = ["torch>=2.4"]
+
+[project.optional-dependencies]
+# `from_pretrained` only. A local run directory loads without it.
+hub = ["huggingface_hub>=0.23"]
+dev = ["pytest>=8.0", "pyyaml>=6.0", "huggingface_hub>=0.23"]
+
+[project.urls]
+Homepage = "https://huggingface.co/lewislululu/jevon"
+Arcade = "https://github.com/lewislulu/jevon-arcade"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["jevon", "envs"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: exercises real optimisation and takes tens of seconds"]

requirements.txt

@@ -0,0 +1,9 @@
+torch>=2.4
+
+# Only `jevon.hub.from_pretrained` needs this; loading a local run directory
+# with `JevonRunner` does not, and the import is deferred so the absence is a
+# clear message rather than an ImportError at startup.
+huggingface_hub>=0.23
+
+pytest>=8.0
+pyyaml>=6.0

runs/jevon-final/args.json

@@ -0,0 +1,49 @@
+{
+  "argv": [
+    "scripts/train.py",
+    "--out",
+    "runs/jevon-final",
+    "--steps",
+    "9000",
+    "--eval-every",
+    "500",
+    "--planner-lr-mult",
+    "10",
+    "--field-weight",
+    "1.0",
+    "--seed",
+    "11",
+    "--min-plus-field",
+    "--expose-field"
+  ],
+  "args": {
+    "out": "runs/jevon-final",
+    "steps": 9000,
+    "states_per_batch": 12,
+    "lr": 0.0003,
+    "warmup": 300,
+    "weight_decay": 0.01,
+    "grad_clip": 1.0,
+    "seed": 11,
+    "device": "mps",
+    "d_model": 384,
+    "planner_dim": 96,
+    "planner_grad_steps": 8,
+    "planner_lr_mult": 10.0,
+    "field_target": "log",
+    "descent_weight": 0.0,
+    "descent_margin": 1.0,
+    "score_smoothing": 0.0,
+    "min_plus_field": true,
+    "expose_field": true,
+    "field_weight": 1.0,
+    "iteration_jitter": 0.5,
+    "snake_fraction": 0.45,
+    "eval_every": 500,
+    "eval_file": "data/frozen/val.jsonl",
+    "log_every": 25,
+    "resume": null,
+    "no_planner": false
+  },
+  "note": "recorded from the live process; this run predates train.py writing args.json itself"
+}

runs/jevon-final/balanced.json

@@ -0,0 +1,18 @@
+{
+  "loss": 0.4821357289950053,
+  "ce": 0.3864518404006958,
+  "brier": 0.1908059984445572,
+  "acc": 0.8717548251152039,
+  "acc_choice": 0.9944444457689922,
+  "acc_boolean": 0.9468833446502686,
+  "acc_score": 0.3500000014901161,
+  "tvd": 0.20573404928048453,
+  "field": 0.12298520555098852,
+  "field_reach": 0.007836632352943221,
+  "field_mae": 0.14491180615647178,
+  "field_r2": -0.20879205446084947,
+  "snake_action": 0.9864864864864865,
+  "maze_action": 1.0,
+  "step": 3000,
+  "balanced": 0.9864864864864865
+}

runs/jevon-final/balanced.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:42940a69544849f3e846f3e2119e3b01e769ba10ee1e21e68cd69203cfa4d64f
+size 80487109

runs/jevon-final/best.json

@@ -0,0 +1,17 @@
+{
+  "loss": 0.39986308813095095,
+  "ce": 0.3141382733980815,
+  "brier": 0.15380982756614686,
+  "acc": 0.8852876385052999,
+  "acc_choice": 0.9888888915379842,
+  "acc_boolean": 0.9673183560371399,
+  "acc_score": 0.3444444472591082,
+  "tvd": 0.1690053701400757,
+  "field": 0.08480164979894957,
+  "field_reach": 0.0087276277015917,
+  "field_mae": 0.10644824003896998,
+  "field_r2": 0.2261388042345791,
+  "snake_action": 0.972972972972973,
+  "maze_action": 1.0,
+  "step": 8500
+}

runs/jevon-final/best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2e43a60500265548e121acb902abc38953f4efeb959ce87e06f9ab72c8ec88be
+size 80474413

runs/jevon-final/config.json

@@ -0,0 +1,20 @@
+{
+  "vocab_size": 497,
+  "d_model": 384,
+  "n_heads": 6,
+  "prefix_layers": 6,
+  "candidate_layers": 2,
+  "set_layers": 2,
+  "ffn_mult": 4,
+  "dropout": 0.1,
+  "max_prefix_len": 320,
+  "max_candidate_len": 48,
+  "grid_channels": 8,
+  "planner_dim": 96,
+  "planner_blocks": 2,
+  "planner_grad_steps": 8,
+  "local_patch": 5,
+  "use_planner": true,
+  "expose_field": true,
+  "min_plus_field": true
+}

runs/jevon-final/eval.json

@@ -0,0 +1,359 @@
+{
+  "val": {
+    "states": 180,
+    "questions": 1325,
+    "ece": 0.08648470789194107,
+    "groups": {
+      "maze/action": {
+        "n": 97,
+        "boards": 97,
+        "accuracy": 1.0,
+        "uniform_control": 0.49054983073903113,
+        "tvd": 0.018844484970534103,
+        "brier": 0.002279498944011423
+      },
+      "maze/boolean": {
+        "n": 530,
+        "boards": 106,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.0006993013012381095,
+        "brier": 1.9829470994958475e-06
+      },
+      "maze/choice": {
+        "n": 97,
+        "boards": 97,
+        "accuracy": 1.0,
+        "uniform_control": 0.49054983073903113,
+        "tvd": 0.018844484970534103,
+        "brier": 0.002279498944011423
+      },
+      "maze/clear": {
+        "n": 424,
+        "boards": 106,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.0004252428954954804,
+        "brier": 8.113499066392354e-07
+      },
+      "maze/distance": {
+        "n": 106,
+        "boards": 106,
+        "accuracy": 0.39622641509433965,
+        "uniform_control": 0.1428571492433548,
+        "tvd": 0.7763906526115706,
+        "brier": 0.7639503164111443
+      },
+      "maze/score": {
+        "n": 106,
+        "boards": 106,
+        "accuracy": 0.39622641509433965,
+        "uniform_control": 0.1428571492433548,
+        "tvd": 0.7763906526115706,
+        "brier": 0.7639503164111443
+      },
+      "maze/solvable": {
+        "n": 106,
+        "boards": 106,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.001795534924208626,
+        "brier": 6.6693358709222975e-06
+      },
+      "snake/action": {
+        "n": 74,
+        "boards": 74,
+        "accuracy": 0.9864864864864865,
+        "uniform_control": 0.4954955098596779,
+        "tvd": 0.35000925611176,
+        "brier": 0.3147798128456769
+      },
+      "snake/boolean": {
+        "n": 444,
+        "boards": 74,
+        "accuracy": 0.8828828828828829,
+        "uniform_control": 0.5,
+        "tvd": 0.23378823729450102,
+        "brier": 0.20216913486784743
+      },
+      "snake/choice": {
+        "n": 74,
+        "boards": 74,
+        "accuracy": 0.9864864864864865,
+        "uniform_control": 0.4954955098596779,
+        "tvd": 0.35000925611176,
+        "brier": 0.3147798128456769
+      },
+      "snake/escape": {
+        "n": 222,
+        "boards": 74,
+        "accuracy": 0.8108108108108109,
+        "uniform_control": 0.5,
+        "tvd": 0.2772626264507438,
+        "brier": 0.28911788216246675
+      },
+      "snake/room": {
+        "n": 74,
+        "boards": 74,
+        "accuracy": 0.28378378378378377,
+        "uniform_control": 0.20000000298023224,
+        "tvd": 0.7990304521612219,
+        "brier": 0.7980756687151419
+      },
+      "snake/safe": {
+        "n": 222,
+        "boards": 74,
+        "accuracy": 0.954954954954955,
+        "uniform_control": 0.5,
+        "tvd": 0.19031384813825827,
+        "brier": 0.1152203875732281
+      },
+      "snake/score": {
+        "n": 74,
+        "boards": 74,
+        "accuracy": 0.28378378378378377,
+        "uniform_control": 0.20000000298023224,
+        "tvd": 0.7990304521612219,
+        "brier": 0.7980756687151419
+      }
+    }
+  },
+  "test": {
+    "states": 240,
+    "questions": 1765,
+    "ece": 0.059004783630371094,
+    "groups": {
+      "maze/action": {
+        "n": 141,
+        "boards": 140,
+        "accuracy": 1.0,
+        "uniform_control": 0.48817967269437534,
+        "tvd": 0.03961129047573943,
+        "brier": 0.007873877364980677
+      },
+      "maze/boolean": {
+        "n": 740,
+        "boards": 147,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.0006845150103578596,
+        "brier": 2.021968730086637e-06
+      },
+      "maze/choice": {
+        "n": 141,
+        "boards": 140,
+        "accuracy": 1.0,
+        "uniform_control": 0.48817967269437534,
+        "tvd": 0.03961129047573943,
+        "brier": 0.007873877364980677
+      },
+      "maze/clear": {
+        "n": 592,
+        "boards": 147,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.00038996367161539763,
+        "brier": 7.440200639129634e-07
+      },
+      "maze/distance": {
+        "n": 148,
+        "boards": 147,
+        "accuracy": 0.2972972972972973,
+        "uniform_control": 0.1428571492433548,
+        "tvd": 0.7846677939634066,
+        "brier": 0.7795776144878285
+      },
+      "maze/score": {
+        "n": 148,
+        "boards": 147,
+        "accuracy": 0.2972972972972973,
+        "uniform_control": 0.1428571492433548,
+        "tvd": 0.7846677939634066,
+        "brier": 0.7795776144878285
+      },
+      "maze/solvable": {
+        "n": 148,
+        "boards": 147,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.0018627203653277073,
+        "brier": 7.133763394781331e-06
+      },
+      "snake/action": {
+        "n": 92,
+        "boards": 92,
+        "accuracy": 0.967391304347826,
+        "uniform_control": 0.47826088349456375,
+        "tvd": 0.3106858467774304,
+        "brier": 0.2770434002752654
+      },
+      "snake/boolean": {
+        "n": 552,
+        "boards": 92,
+        "accuracy": 0.8894927536231884,
+        "uniform_control": 0.5,
+        "tvd": 0.22231864719314204,
+        "brier": 0.19377556414448022
+      },
+      "snake/choice": {
+        "n": 92,
+        "boards": 92,
+        "accuracy": 0.967391304347826,
+        "uniform_control": 0.47826088349456375,
+        "tvd": 0.3106858467774304,
+        "brier": 0.2770434002752654
+      },
+      "snake/escape": {
+        "n": 276,
+        "boards": 92,
+        "accuracy": 0.8188405797101449,
+        "uniform_control": 0.5,
+        "tvd": 0.26280311700226605,
+        "brier": 0.2747444752047
+      },
+      "snake/room": {
+        "n": 92,
+        "boards": 92,
+        "accuracy": 0.25,
+        "uniform_control": 0.20000000298023224,
+        "tvd": 0.7993024775515432,
+        "brier": 0.7986197102329006
+      },
+      "snake/safe": {
+        "n": 276,
+        "boards": 92,
+        "accuracy": 0.9601449275362319,
+        "uniform_control": 0.5,
+        "tvd": 0.18183417738401803,
+        "brier": 0.1128066530842604
+      },
+      "snake/score": {
+        "n": 92,
+        "boards": 92,
+        "accuracy": 0.25,
+        "uniform_control": 0.20000000298023224,
+        "tvd": 0.7993024775515432,
+        "brier": 0.7986197102329006
+      }
+    }
+  },
+  "ood": {
+    "states": 160,
+    "questions": 1167,
+    "ece": 0.05399147421121597,
+    "groups": {
+      "maze/action": {
+        "n": 107,
+        "boards": 107,
+        "accuracy": 1.0,
+        "uniform_control": 0.5132398789174089,
+        "tvd": 0.26991402065364,
+        "brier": 0.1504033250384964
+      },
+      "maze/boolean": {
+        "n": 550,
+        "boards": 110,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.0007242930423341353,
+        "brier": 2.258754991337562e-06
+      },
+      "maze/choice": {
+        "n": 107,
+        "boards": 107,
+        "accuracy": 1.0,
+        "uniform_control": 0.5132398789174089,
+        "tvd": 0.26991402065364,
+        "brier": 0.1504033250384964
+      },
+      "maze/clear": {
+        "n": 440,
+        "boards": 110,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.0004054153733622198,
+        "brier": 7.734664848157991e-07
+      },
+      "maze/distance": {
+        "n": 110,
+        "boards": 110,
+        "accuracy": 0.05454545454545454,
+        "uniform_control": 0.1428571492433548,
+        "tvd": 0.8541775340383703,
+        "brier": 0.9160033637827093
+      },
+      "maze/score": {
+        "n": 110,
+        "boards": 110,
+        "accuracy": 0.05454545454545454,
+        "uniform_control": 0.1428571492433548,
+        "tvd": 0.8541775340383703,
+        "brier": 0.9160033637827093
+      },
+      "maze/solvable": {
+        "n": 110,
+        "boards": 110,
+        "accuracy": 1.0,
+        "uniform_control": 0.5,
+        "tvd": 0.0019998037182217972,
+        "brier": 8.199909017424612e-06
+      },
+      "snake/action": {
+        "n": 50,
+        "boards": 50,
+        "accuracy": 0.98,
+        "uniform_control": 0.4866666805744171,
+        "tvd": 0.35739153509028254,
+        "brier": 0.3199479156875387
+      },
+      "snake/boolean": {
+        "n": 300,
+        "boards": 50,
+        "accuracy": 0.8333333333333334,
+        "uniform_control": 0.5,
+        "tvd": 0.26355026371777057,
+        "brier": 0.262066046569186
+      },
+      "snake/choice": {
+        "n": 50,
+        "boards": 50,
+        "accuracy": 0.98,
+        "uniform_control": 0.4866666805744171,
+        "tvd": 0.35739153509028254,
+        "brier": 0.3199479156875387
+      },
+      "snake/escape": {
+        "n": 150,
+        "boards": 50,
+        "accuracy": 0.68,
+        "uniform_control": 0.5,
+        "tvd": 0.35605070618291695,
+        "brier": 0.4470668915938586
+      },
+      "snake/room": {
+        "n": 50,
+        "boards": 50,
+        "accuracy": 0.2,
+        "uniform_control": 0.20000000298023224,
+        "tvd": 0.798902131319046,
+        "brier": 0.7978189885616302
+      },
+      "snake/safe": {
+        "n": 150,
+        "boards": 50,
+        "accuracy": 0.9866666666666667,
+        "uniform_control": 0.5,
+        "tvd": 0.1710498212526242,
+        "brier": 0.07706520154451331
+      },
+      "snake/score": {
+        "n": 50,
+        "boards": 50,
+        "accuracy": 0.2,
+        "uniform_control": 0.20000000298023224,
+        "tvd": 0.798902131319046,
+        "brier": 0.7978189885616302
+      }
+    }
+  }
+}

runs/jevon-final/history.json

@@ -0,0 +1,308 @@
+[
+  {
+    "loss": 0.6430396795272827,
+    "ce": 0.4291669289271037,
+    "brier": 0.22238269944985709,
+    "acc": 0.8309783538182577,
+    "acc_choice": 0.680606069167455,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.2240913321574529,
+    "field": 0.0648224376142025,
+    "field_reach": 0.008027789788320661,
+    "field_mae": 0.0873508279607331,
+    "field_r2": 0.5047728275363464,
+    "snake_action": 0.8108108108108109,
+    "maze_action": 0.5773195876288659,
+    "step": 500
+  },
+  {
+    "loss": 0.6268994410832723,
+    "ce": 0.43772715926170347,
+    "brier": 0.21867869893709818,
+    "acc": 0.8626200517018636,
+    "acc_choice": 0.8468686898549398,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.4222222218910853,
+    "tvd": 0.23100693821907042,
+    "field": 0.24834836920102438,
+    "field_reach": 0.00785924393373231,
+    "field_mae": 0.27680033871509113,
+    "field_r2": -2.787584755271071,
+    "snake_action": 0.9459459459459459,
+    "maze_action": 0.7731958762886598,
+    "step": 1000
+  },
+  {
+    "loss": 0.6161262154579162,
+    "ce": 0.42860496044158936,
+    "brier": 0.2166995237270991,
+    "acc": 0.8393356005350748,
+    "acc_choice": 0.666464650630951,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.4222222218910853,
+    "tvd": 0.2255744288365046,
+    "field": 0.09811665092905363,
+    "field_reach": 0.007819027624403436,
+    "field_mae": 0.12170105225125379,
+    "field_r2": 0.046098211747254925,
+    "snake_action": 0.5135135135135135,
+    "maze_action": 0.7835051546391752,
+    "step": 1500
+  },
+  {
+    "loss": 0.5040864706039428,
+    "ce": 0.39263187646865844,
+    "brier": 0.19500995179017386,
+    "acc": 0.8703148086865743,
+    "acc_choice": 0.9833333373069764,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.21229490141073862,
+    "field": 0.10865951577822368,
+    "field_reach": 0.007855451099264126,
+    "field_mae": 0.13416509528904144,
+    "field_r2": -0.13046405368830816,
+    "snake_action": 0.9594594594594594,
+    "maze_action": 1.0,
+    "step": 2000
+  },
+  {
+    "loss": 0.48423184355099996,
+    "ce": 0.3865963856379191,
+    "brier": 0.19062800109386444,
+    "acc": 0.853052802880605,
+    "acc_choice": 0.8498989899953207,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.20264210999011995,
+    "field": 0.09101995428403219,
+    "field_reach": 0.00942669656748573,
+    "field_mae": 0.11243784826426176,
+    "field_r2": 0.17141795311611863,
+    "snake_action": 0.6486486486486487,
+    "maze_action": 1.0,
+    "step": 2500
+  },
+  {
+    "loss": 0.4821357289950053,
+    "ce": 0.3864518404006958,
+    "brier": 0.1908059984445572,
+    "acc": 0.8717548251152039,
+    "acc_choice": 0.9944444457689922,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.20573404928048453,
+    "field": 0.12298520555098852,
+    "field_reach": 0.007836632352943221,
+    "field_mae": 0.14491180615647178,
+    "field_r2": -0.20879205446084947,
+    "snake_action": 0.9864864864864865,
+    "maze_action": 1.0,
+    "step": 3000
+  },
+  {
+    "loss": 0.4724984308083852,
+    "ce": 0.3778689761956533,
+    "brier": 0.18896289964516957,
+    "acc": 0.8717548251152039,
+    "acc_choice": 0.9944444457689922,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.19179949859778087,
+    "field": 0.10719771832227706,
+    "field_reach": 0.007806899095885456,
+    "field_mae": 0.12956693910768763,
+    "field_r2": 0.010277769420561245,
+    "snake_action": 0.9864864864864865,
+    "maze_action": 1.0,
+    "step": 3500
+  },
+  {
+    "loss": 0.47965741753578184,
+    "ce": 0.378563779592514,
+    "brier": 0.19039177348216374,
+    "acc": 0.8702458739280701,
+    "acc_choice": 0.9828282872835795,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.18964516123135886,
+    "field": 0.08818436115980148,
+    "field_reach": 0.00800159627882143,
+    "field_mae": 0.1098015543827379,
+    "field_r2": 0.2466056585560258,
+    "snake_action": 0.9864864864864865,
+    "maze_action": 0.979381443298969,
+    "step": 4000
+  },
+  {
+    "loss": 0.47649228970209756,
+    "ce": 0.3793632904688517,
+    "brier": 0.19014093180497488,
+    "acc": 0.8710301876068115,
+    "acc_choice": 0.9888888915379842,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.19629547695318858,
+    "field": 0.09085945089658101,
+    "field_reach": 0.007979249480801325,
+    "field_mae": 0.11260708531644582,
+    "field_r2": 0.20965784971410284,
+    "snake_action": 0.9864864864864865,
+    "maze_action": 0.9896907216494846,
+    "step": 4500
+  },
+  {
+    "loss": 0.47328211069107057,
+    "ce": 0.37875324686368306,
+    "brier": 0.18869826843341192,
+    "acc": 0.8717548251152039,
+    "acc_choice": 0.9944444457689922,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.1954862008492152,
+    "field": 0.09279383917649588,
+    "field_reach": 0.008081573558350404,
+    "field_mae": 0.11689527545097957,
+    "field_r2": 0.11475372426767272,
+    "snake_action": 0.9864864864864865,
+    "maze_action": 1.0,
+    "step": 5000
+  },
+  {
+    "loss": 0.4666572948296865,
+    "ce": 0.3724243978659312,
+    "brier": 0.18684656272331873,
+    "acc": 0.8724794665972392,
+    "acc_choice": 0.9944444457689922,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.35555555671453476,
+    "tvd": 0.1899937520424525,
+    "field": 0.11715173323949178,
+    "field_reach": 0.008021636578875283,
+    "field_mae": 0.14379776442470568,
+    "field_r2": -0.2881043439838695,
+    "snake_action": 0.9864864864864865,
+    "maze_action": 1.0,
+    "step": 5500
+  },
+  {
+    "loss": 0.45790409445762636,
+    "ce": 0.3650842885176341,
+    "brier": 0.1832037756840388,
+    "acc": 0.8672664841016133,
+    "acc_choice": 0.959494952360789,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.19846215347448984,
+    "field": 0.10857781569163004,
+    "field_reach": 0.008120695035904646,
+    "field_mae": 0.13411058857249636,
+    "field_r2": -0.1573779587982147,
+    "snake_action": 0.9054054054054054,
+    "maze_action": 1.0,
+    "step": 6000
+  },
+  {
+    "loss": 0.45433027148246763,
+    "ce": 0.3633299271265666,
+    "brier": 0.18349071244398754,
+    "acc": 0.8695062915484111,
+    "acc_choice": 0.9766666690508524,
+    "acc_boolean": 0.9468833446502686,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.20805268486340842,
+    "field": 0.08403789947430293,
+    "field_reach": 0.007841536616130422,
+    "field_mae": 0.10577063097931902,
+    "field_r2": 0.26262213095402853,
+    "snake_action": 0.9459459459459459,
+    "maze_action": 1.0,
+    "step": 6500
+  },
+  {
+    "loss": 0.4257788856824239,
+    "ce": 0.338992706934611,
+    "brier": 0.16655596445004145,
+    "acc": 0.8860452135403951,
+    "acc_choice": 0.9888888915379842,
+    "acc_boolean": 0.9673183560371399,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.1928422600030899,
+    "field": 0.10394345372915267,
+    "field_reach": 0.00819415650330484,
+    "field_mae": 0.12675953488266162,
+    "field_r2": 0.03251710439413491,
+    "snake_action": 0.972972972972973,
+    "maze_action": 1.0,
+    "step": 7000
+  },
+  {
+    "loss": 0.40878687500953675,
+    "ce": 0.32246087193489076,
+    "brier": 0.1595507149895032,
+    "acc": 0.8830990632375081,
+    "acc_choice": 0.9367676854133606,
+    "acc_boolean": 0.9673183560371399,
+    "acc_score": 0.3777777726451556,
+    "tvd": 0.16677065094312032,
+    "field": 0.13400054325660068,
+    "field_reach": 0.008717572259289834,
+    "field_mae": 0.15709024260702828,
+    "field_r2": -0.41707112606313124,
+    "snake_action": 0.8513513513513513,
+    "maze_action": 1.0,
+    "step": 7500
+  },
+  {
+    "loss": 0.4029513160387675,
+    "ce": 0.31686999201774596,
+    "brier": 0.15476668129364649,
+    "acc": 0.8860452135403951,
+    "acc_choice": 0.9888888915379842,
+    "acc_boolean": 0.9673183560371399,
+    "acc_score": 0.3500000014901161,
+    "tvd": 0.17156118750572205,
+    "field": 0.10043507615725199,
+    "field_reach": 0.00858972800488118,
+    "field_mae": 0.12331134686881152,
+    "field_r2": 0.06755961142045463,
+    "snake_action": 0.972972972972973,
+    "maze_action": 1.0,
+    "step": 8000
+  },
+  {
+    "loss": 0.39986308813095095,
+    "ce": 0.3141382733980815,
+    "brier": 0.15380982756614686,
+    "acc": 0.8852876385052999,
+    "acc_choice": 0.9888888915379842,
+    "acc_boolean": 0.9673183560371399,
+    "acc_score": 0.3444444472591082,
+    "tvd": 0.1690053701400757,
+    "field": 0.08480164979894957,
+    "field_reach": 0.0087276277015917,
+    "field_mae": 0.10644824003896998,
+    "field_r2": 0.2261388042345791,
+    "snake_action": 0.972972972972973,
+    "maze_action": 1.0,
+    "step": 8500
+  },
+  {
+    "loss": 0.4020693858464559,
+    "ce": 0.31669941544532776,
+    "brier": 0.1551360418399175,
+    "acc": 0.8958186864852905,
+    "acc_choice": 0.9888888915379842,
+    "acc_boolean": 0.9673183560371399,
+    "acc_score": 0.4222222218910853,
+    "tvd": 0.155249418814977,
+    "field": 0.09742864519357682,
+    "field_reach": 0.008850584997950743,
+    "field_mae": 0.11998297499025644,
+    "field_r2": 0.10834436235203748,
+    "snake_action": 0.972972972972973,
+    "maze_action": 1.0,
+    "step": 9000
+  }
+]

runs/jevon-final/play/maze_model_field_summary.json

@@ -0,0 +1,543 @@
+{
+  "controller": "model-field",
+  "episodes": [
+    {
+      "solved": true,
+      "steps": 32,
+      "collisions": 0,
+      "distinct_cells": 33,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901111,
+      "shortest": 32,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901148,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901185,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 44,
+      "collisions": 0,
+      "distinct_cells": 45,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901111,
+      "shortest": 44,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 34,
+      "collisions": 0,
+      "distinct_cells": 35,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901148,
+      "shortest": 34,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901185,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 22,
+      "collisions": 0,
+      "distinct_cells": 23,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901148,
+      "shortest": 22,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 18,
+      "collisions": 0,
+      "distinct_cells": 19,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901185,
+      "shortest": 18,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 16,
+      "collisions": 0,
+      "distinct_cells": 17,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901148,
+      "shortest": 16,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 13,
+      "collisions": 0,
+      "distinct_cells": 14,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901185,
+      "shortest": 13,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 142,
+      "collisions": 0,
+      "distinct_cells": 143,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902121,
+      "shortest": 142,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 116,
+      "collisions": 0,
+      "distinct_cells": 117,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902158,
+      "shortest": 116,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 156,
+      "collisions": 0,
+      "distinct_cells": 157,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902195,
+      "shortest": 156,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 118,
+      "collisions": 0,
+      "distinct_cells": 119,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902121,
+      "shortest": 118,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 172,
+      "collisions": 0,
+      "distinct_cells": 173,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902158,
+      "shortest": 172,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 140,
+      "collisions": 0,
+      "distinct_cells": 141,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902195,
+      "shortest": 140,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 46,
+      "collisions": 0,
+      "distinct_cells": 47,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902121,
+      "shortest": 46,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902158,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902195,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 41,
+      "collisions": 0,
+      "distinct_cells": 42,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902121,
+      "shortest": 41,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902158,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902195,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 264,
+      "collisions": 0,
+      "distinct_cells": 265,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903131,
+      "shortest": 264,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 194,
+      "collisions": 0,
+      "distinct_cells": 195,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903168,
+      "shortest": 194,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 286,
+      "collisions": 0,
+      "distinct_cells": 287,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903205,
+      "shortest": 286,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 268,
+      "collisions": 0,
+      "distinct_cells": 269,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903131,
+      "shortest": 268,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 282,
+      "collisions": 0,
+      "distinct_cells": 283,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903168,
+      "shortest": 282,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 252,
+      "collisions": 0,
+      "distinct_cells": 253,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903205,
+      "shortest": 252,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 66,
+      "collisions": 0,
+      "distinct_cells": 67,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903131,
+      "shortest": 66,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 72,
+      "collisions": 0,
+      "distinct_cells": 73,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903168,
+      "shortest": 72,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 88,
+      "collisions": 0,
+      "distinct_cells": 89,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903205,
+      "shortest": 88,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 57,
+      "collisions": 0,
+      "distinct_cells": 58,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903131,
+      "shortest": 57,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 56,
+      "collisions": 0,
+      "distinct_cells": 57,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903168,
+      "shortest": 56,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 58,
+      "collisions": 0,
+      "distinct_cells": 59,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903205,
+      "shortest": 58,
+      "efficiency": 1.0
+    }
+  ],
+  "summary": {
+    "maze": {
+      "episodes": 36,
+      "solve_rate": 1.0,
+      "mean_steps_when_solved": 93.19444444444444,
+      "mean_efficiency": 1.0,
+      "mean_collisions": 0.0,
+      "deadlock_rate": 0.0,
+      "mean_distinct_cells": 94.19444444444444,
+      "by_size": {
+        "11": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 27.25,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 27.25
+        },
+        "21": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 90.41666666666667,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 90.41666666666667
+        },
+        "31": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 161.91666666666666,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 161.91666666666666
+        }
+      }
+    }
+  }
+}

runs/jevon-final/play/maze_model_memory_summary.json

@@ -0,0 +1,543 @@
+{
+  "controller": "model+memory",
+  "episodes": [
+    {
+      "solved": true,
+      "steps": 32,
+      "collisions": 0,
+      "distinct_cells": 33,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901111,
+      "shortest": 32,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901148,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901185,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 44,
+      "collisions": 0,
+      "distinct_cells": 45,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901111,
+      "shortest": 44,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 34,
+      "collisions": 0,
+      "distinct_cells": 35,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901148,
+      "shortest": 34,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901185,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 22,
+      "collisions": 0,
+      "distinct_cells": 23,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901148,
+      "shortest": 22,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 18,
+      "collisions": 0,
+      "distinct_cells": 19,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901185,
+      "shortest": 18,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 16,
+      "collisions": 0,
+      "distinct_cells": 17,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901148,
+      "shortest": 16,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 13,
+      "collisions": 0,
+      "distinct_cells": 14,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901185,
+      "shortest": 13,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 142,
+      "collisions": 0,
+      "distinct_cells": 143,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902121,
+      "shortest": 142,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 116,
+      "collisions": 0,
+      "distinct_cells": 117,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902158,
+      "shortest": 116,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 156,
+      "collisions": 0,
+      "distinct_cells": 157,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902195,
+      "shortest": 156,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 118,
+      "collisions": 0,
+      "distinct_cells": 119,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902121,
+      "shortest": 118,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 172,
+      "collisions": 0,
+      "distinct_cells": 173,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902158,
+      "shortest": 172,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 140,
+      "collisions": 0,
+      "distinct_cells": 141,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902195,
+      "shortest": 140,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 46,
+      "collisions": 0,
+      "distinct_cells": 47,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902121,
+      "shortest": 46,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902158,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902195,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 41,
+      "collisions": 0,
+      "distinct_cells": 42,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902121,
+      "shortest": 41,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902158,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902195,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 264,
+      "collisions": 0,
+      "distinct_cells": 265,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903131,
+      "shortest": 264,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 194,
+      "collisions": 0,
+      "distinct_cells": 195,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903168,
+      "shortest": 194,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 286,
+      "collisions": 0,
+      "distinct_cells": 287,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903205,
+      "shortest": 286,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 268,
+      "collisions": 0,
+      "distinct_cells": 269,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903131,
+      "shortest": 268,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 282,
+      "collisions": 0,
+      "distinct_cells": 283,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903168,
+      "shortest": 282,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 252,
+      "collisions": 0,
+      "distinct_cells": 253,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903205,
+      "shortest": 252,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 66,
+      "collisions": 0,
+      "distinct_cells": 67,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903131,
+      "shortest": 66,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 72,
+      "collisions": 0,
+      "distinct_cells": 73,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903168,
+      "shortest": 72,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 88,
+      "collisions": 0,
+      "distinct_cells": 89,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903205,
+      "shortest": 88,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 57,
+      "collisions": 0,
+      "distinct_cells": 58,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903131,
+      "shortest": 57,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 56,
+      "collisions": 0,
+      "distinct_cells": 57,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903168,
+      "shortest": 56,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 58,
+      "collisions": 0,
+      "distinct_cells": 59,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903205,
+      "shortest": 58,
+      "efficiency": 1.0
+    }
+  ],
+  "summary": {
+    "maze": {
+      "episodes": 36,
+      "solve_rate": 1.0,
+      "mean_steps_when_solved": 93.19444444444444,
+      "mean_efficiency": 1.0,
+      "mean_collisions": 0.0,
+      "deadlock_rate": 0.0,
+      "mean_distinct_cells": 94.19444444444444,
+      "by_size": {
+        "11": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 27.25,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 27.25
+        },
+        "21": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 90.41666666666667,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 90.41666666666667
+        },
+        "31": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 161.91666666666666,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 161.91666666666666
+        }
+      }
+    }
+  }
+}

runs/jevon-final/play/maze_model_sampled_summary.json

@@ -0,0 +1,543 @@
+{
+  "controller": "model",
+  "episodes": [
+    {
+      "solved": true,
+      "steps": 32,
+      "collisions": 0,
+      "distinct_cells": 33,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901111,
+      "shortest": 32,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901148,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901185,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 44,
+      "collisions": 0,
+      "distinct_cells": 45,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901111,
+      "shortest": 44,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 34,
+      "collisions": 0,
+      "distinct_cells": 35,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901148,
+      "shortest": 34,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901185,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 22,
+      "collisions": 0,
+      "distinct_cells": 23,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901148,
+      "shortest": 22,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 18,
+      "collisions": 0,
+      "distinct_cells": 19,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901185,
+      "shortest": 18,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 16,
+      "collisions": 0,
+      "distinct_cells": 17,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901148,
+      "shortest": 16,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 13,
+      "collisions": 0,
+      "distinct_cells": 14,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901185,
+      "shortest": 13,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 144,
+      "collisions": 0,
+      "distinct_cells": 143,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902121,
+      "shortest": 142,
+      "efficiency": 0.9861111111111112
+    },
+    {
+      "solved": true,
+      "steps": 116,
+      "collisions": 0,
+      "distinct_cells": 117,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902158,
+      "shortest": 116,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 156,
+      "collisions": 0,
+      "distinct_cells": 157,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902195,
+      "shortest": 156,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 118,
+      "collisions": 0,
+      "distinct_cells": 119,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902121,
+      "shortest": 118,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 174,
+      "collisions": 0,
+      "distinct_cells": 173,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902158,
+      "shortest": 172,
+      "efficiency": 0.9885057471264368
+    },
+    {
+      "solved": true,
+      "steps": 140,
+      "collisions": 0,
+      "distinct_cells": 141,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902195,
+      "shortest": 140,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 46,
+      "collisions": 0,
+      "distinct_cells": 47,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902121,
+      "shortest": 46,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902158,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902195,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 41,
+      "collisions": 0,
+      "distinct_cells": 42,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902121,
+      "shortest": 41,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902158,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902195,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 328,
+      "collisions": 0,
+      "distinct_cells": 266,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903131,
+      "shortest": 264,
+      "efficiency": 0.8048780487804879
+    },
+    {
+      "solved": true,
+      "steps": 238,
+      "collisions": 0,
+      "distinct_cells": 195,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903168,
+      "shortest": 194,
+      "efficiency": 0.8151260504201681
+    },
+    {
+      "solved": true,
+      "steps": 332,
+      "collisions": 0,
+      "distinct_cells": 287,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903205,
+      "shortest": 286,
+      "efficiency": 0.8614457831325302
+    },
+    {
+      "solved": true,
+      "steps": 314,
+      "collisions": 0,
+      "distinct_cells": 270,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903131,
+      "shortest": 268,
+      "efficiency": 0.8535031847133758
+    },
+    {
+      "solved": true,
+      "steps": 330,
+      "collisions": 0,
+      "distinct_cells": 286,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903168,
+      "shortest": 282,
+      "efficiency": 0.8545454545454545
+    },
+    {
+      "solved": true,
+      "steps": 314,
+      "collisions": 0,
+      "distinct_cells": 254,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903205,
+      "shortest": 252,
+      "efficiency": 0.802547770700637
+    },
+    {
+      "solved": true,
+      "steps": 82,
+      "collisions": 0,
+      "distinct_cells": 69,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903131,
+      "shortest": 66,
+      "efficiency": 0.8048780487804879
+    },
+    {
+      "solved": true,
+      "steps": 82,
+      "collisions": 0,
+      "distinct_cells": 74,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903168,
+      "shortest": 72,
+      "efficiency": 0.8780487804878049
+    },
+    {
+      "solved": true,
+      "steps": 120,
+      "collisions": 0,
+      "distinct_cells": 90,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903205,
+      "shortest": 88,
+      "efficiency": 0.7333333333333333
+    },
+    {
+      "solved": true,
+      "steps": 75,
+      "collisions": 0,
+      "distinct_cells": 65,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903131,
+      "shortest": 57,
+      "efficiency": 0.76
+    },
+    {
+      "solved": true,
+      "steps": 102,
+      "collisions": 0,
+      "distinct_cells": 69,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903168,
+      "shortest": 56,
+      "efficiency": 0.5490196078431373
+    },
+    {
+      "solved": true,
+      "steps": 88,
+      "collisions": 0,
+      "distinct_cells": 74,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903205,
+      "shortest": 58,
+      "efficiency": 0.6590909090909091
+    }
+  ],
+  "summary": {
+    "maze": {
+      "episodes": 36,
+      "solve_rate": 1.0,
+      "mean_steps_when_solved": 106.13888888888889,
+      "mean_efficiency": 0.9264176063907187,
+      "mean_collisions": 0.0,
+      "deadlock_rate": 0.0,
+      "mean_distinct_cells": 95.41666666666667,
+      "by_size": {
+        "11": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 27.25,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 27.25
+        },
+        "21": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 90.75,
+          "mean_efficiency": 0.9978847381864623,
+          "mean_shortest": 90.41666666666667
+        },
+        "31": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 200.41666666666666,
+          "mean_efficiency": 0.7813680809856938,
+          "mean_shortest": 161.91666666666666
+        }
+      }
+    }
+  }
+}

runs/jevon-final/play/maze_model_summary.json

@@ -0,0 +1,543 @@
+{
+  "controller": "model",
+  "episodes": [
+    {
+      "solved": true,
+      "steps": 32,
+      "collisions": 0,
+      "distinct_cells": 33,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901111,
+      "shortest": 32,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901148,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901185,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 44,
+      "collisions": 0,
+      "distinct_cells": 45,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901111,
+      "shortest": 44,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 34,
+      "collisions": 0,
+      "distinct_cells": 35,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901148,
+      "shortest": 34,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901185,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 22,
+      "collisions": 0,
+      "distinct_cells": 23,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901148,
+      "shortest": 22,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 18,
+      "collisions": 0,
+      "distinct_cells": 19,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901185,
+      "shortest": 18,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 16,
+      "collisions": 0,
+      "distinct_cells": 17,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901148,
+      "shortest": 16,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 13,
+      "collisions": 0,
+      "distinct_cells": 14,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901185,
+      "shortest": 13,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 142,
+      "collisions": 0,
+      "distinct_cells": 143,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902121,
+      "shortest": 142,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 116,
+      "collisions": 0,
+      "distinct_cells": 117,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902158,
+      "shortest": 116,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 156,
+      "collisions": 0,
+      "distinct_cells": 157,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902195,
+      "shortest": 156,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 118,
+      "collisions": 0,
+      "distinct_cells": 119,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902121,
+      "shortest": 118,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 172,
+      "collisions": 0,
+      "distinct_cells": 173,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902158,
+      "shortest": 172,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 140,
+      "collisions": 0,
+      "distinct_cells": 141,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902195,
+      "shortest": 140,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 46,
+      "collisions": 0,
+      "distinct_cells": 47,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902121,
+      "shortest": 46,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902158,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902195,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 41,
+      "collisions": 0,
+      "distinct_cells": 42,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902121,
+      "shortest": 41,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902158,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902195,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 264,
+      "collisions": 0,
+      "distinct_cells": 265,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903131,
+      "shortest": 264,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 194,
+      "collisions": 0,
+      "distinct_cells": 195,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903168,
+      "shortest": 194,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 286,
+      "collisions": 0,
+      "distinct_cells": 287,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903205,
+      "shortest": 286,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 268,
+      "collisions": 0,
+      "distinct_cells": 269,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903131,
+      "shortest": 268,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 282,
+      "collisions": 0,
+      "distinct_cells": 283,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903168,
+      "shortest": 282,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 252,
+      "collisions": 0,
+      "distinct_cells": 253,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903205,
+      "shortest": 252,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 66,
+      "collisions": 0,
+      "distinct_cells": 67,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903131,
+      "shortest": 66,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 72,
+      "collisions": 0,
+      "distinct_cells": 73,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903168,
+      "shortest": 72,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 88,
+      "collisions": 0,
+      "distinct_cells": 89,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903205,
+      "shortest": 88,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 57,
+      "collisions": 0,
+      "distinct_cells": 58,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903131,
+      "shortest": 57,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 56,
+      "collisions": 0,
+      "distinct_cells": 57,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903168,
+      "shortest": 56,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 58,
+      "collisions": 0,
+      "distinct_cells": 59,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903205,
+      "shortest": 58,
+      "efficiency": 1.0
+    }
+  ],
+  "summary": {
+    "maze": {
+      "episodes": 36,
+      "solve_rate": 1.0,
+      "mean_steps_when_solved": 93.19444444444444,
+      "mean_efficiency": 1.0,
+      "mean_collisions": 0.0,
+      "deadlock_rate": 0.0,
+      "mean_distinct_cells": 94.19444444444444,
+      "by_size": {
+        "11": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 27.25,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 27.25
+        },
+        "21": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 90.41666666666667,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 90.41666666666667
+        },
+        "31": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 161.91666666666666,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 161.91666666666666
+        }
+      }
+    }
+  }
+}

runs/jevon-final/play/maze_random_memory_summary.json

@@ -0,0 +1,543 @@
+{
+  "controller": "random+memory",
+  "episodes": [
+    {
+      "solved": true,
+      "steps": 32,
+      "collisions": 0,
+      "distinct_cells": 33,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901111,
+      "shortest": 32,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901148,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 120,
+      "collisions": 0,
+      "distinct_cells": 49,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901185,
+      "shortest": 40,
+      "efficiency": 0.3333333333333333
+    },
+    {
+      "solved": true,
+      "steps": 44,
+      "collisions": 0,
+      "distinct_cells": 45,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901111,
+      "shortest": 44,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 34,
+      "collisions": 0,
+      "distinct_cells": 35,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901148,
+      "shortest": 34,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 74,
+      "collisions": 0,
+      "distinct_cells": 47,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901185,
+      "shortest": 36,
+      "efficiency": 0.4864864864864865
+    },
+    {
+      "solved": true,
+      "steps": 217,
+      "collisions": 0,
+      "distinct_cells": 48,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 0.06912442396313365
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 47,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901148,
+      "shortest": 22,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 26,
+      "collisions": 0,
+      "distinct_cells": 27,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901185,
+      "shortest": 18,
+      "efficiency": 0.6923076923076923
+    },
+    {
+      "solved": true,
+      "steps": 155,
+      "collisions": 0,
+      "distinct_cells": 58,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 0.0967741935483871
+    },
+    {
+      "solved": true,
+      "steps": 28,
+      "collisions": 0,
+      "distinct_cells": 27,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901148,
+      "shortest": 16,
+      "efficiency": 0.5714285714285714
+    },
+    {
+      "solved": true,
+      "steps": 61,
+      "collisions": 0,
+      "distinct_cells": 30,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901185,
+      "shortest": 13,
+      "efficiency": 0.21311475409836064
+    },
+    {
+      "solved": true,
+      "steps": 666,
+      "collisions": 0,
+      "distinct_cells": 175,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902121,
+      "shortest": 142,
+      "efficiency": 0.2132132132132132
+    },
+    {
+      "solved": true,
+      "steps": 164,
+      "collisions": 0,
+      "distinct_cells": 127,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902158,
+      "shortest": 116,
+      "efficiency": 0.7073170731707317
+    },
+    {
+      "solved": true,
+      "steps": 156,
+      "collisions": 0,
+      "distinct_cells": 157,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902195,
+      "shortest": 156,
+      "efficiency": 1.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 133,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902121,
+      "shortest": 118,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 312,
+      "collisions": 0,
+      "distinct_cells": 189,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902158,
+      "shortest": 172,
+      "efficiency": 0.5512820512820513
+    },
+    {
+      "solved": true,
+      "steps": 1536,
+      "collisions": 0,
+      "distinct_cells": 193,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902195,
+      "shortest": 140,
+      "efficiency": 0.09114583333333333
+    },
+    {
+      "solved": true,
+      "steps": 1296,
+      "collisions": 0,
+      "distinct_cells": 211,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902121,
+      "shortest": 46,
+      "efficiency": 0.035493827160493825
+    },
+    {
+      "solved": true,
+      "steps": 98,
+      "collisions": 0,
+      "distinct_cells": 79,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902158,
+      "shortest": 40,
+      "efficiency": 0.40816326530612246
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 171,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902195,
+      "shortest": 42,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 1705,
+      "collisions": 0,
+      "distinct_cells": 200,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902121,
+      "shortest": 41,
+      "efficiency": 0.02404692082111437
+    },
+    {
+      "solved": true,
+      "steps": 928,
+      "collisions": 0,
+      "distinct_cells": 168,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902158,
+      "shortest": 36,
+      "efficiency": 0.03879310344827586
+    },
+    {
+      "solved": true,
+      "steps": 1218,
+      "collisions": 0,
+      "distinct_cells": 264,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902195,
+      "shortest": 36,
+      "efficiency": 0.029556650246305417
+    },
+    {
+      "solved": true,
+      "steps": 744,
+      "collisions": 0,
+      "distinct_cells": 313,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903131,
+      "shortest": 264,
+      "efficiency": 0.3548387096774194
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 253,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903168,
+      "shortest": 194,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 1488,
+      "collisions": 0,
+      "distinct_cells": 369,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903205,
+      "shortest": 286,
+      "efficiency": 0.1922043010752688
+    },
+    {
+      "solved": true,
+      "steps": 2036,
+      "collisions": 0,
+      "distinct_cells": 375,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903131,
+      "shortest": 268,
+      "efficiency": 0.13163064833005894
+    },
+    {
+      "solved": true,
+      "steps": 1320,
+      "collisions": 0,
+      "distinct_cells": 345,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903168,
+      "shortest": 282,
+      "efficiency": 0.21363636363636362
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 335,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903205,
+      "shortest": 252,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 1218,
+      "collisions": 0,
+      "distinct_cells": 344,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903131,
+      "shortest": 66,
+      "efficiency": 0.054187192118226604
+    },
+    {
+      "solved": true,
+      "steps": 644,
+      "collisions": 0,
+      "distinct_cells": 264,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903168,
+      "shortest": 72,
+      "efficiency": 0.11180124223602485
+    },
+    {
+      "solved": true,
+      "steps": 430,
+      "collisions": 0,
+      "distinct_cells": 125,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903205,
+      "shortest": 88,
+      "efficiency": 0.20465116279069767
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 485,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903131,
+      "shortest": 57,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 2154,
+      "collisions": 0,
+      "distinct_cells": 446,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903168,
+      "shortest": 56,
+      "efficiency": 0.025998142989786442
+    },
+    {
+      "solved": true,
+      "steps": 1746,
+      "collisions": 0,
+      "distinct_cells": 577,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903205,
+      "shortest": 58,
+      "efficiency": 0.033218785796105384
+    }
+  ],
+  "summary": {
+    "maze": {
+      "episodes": 36,
+      "solve_rate": 0.8333333333333334,
+      "mean_steps_when_solved": 689.7333333333333,
+      "mean_efficiency": 0.3627915980599186,
+      "mean_collisions": 0.0,
+      "deadlock_rate": 0.0,
+      "mean_distinct_cells": 188.52777777777777,
+      "by_size": {
+        "11": {
+          "episodes": 12,
+          "solve_rate": 0.9166666666666666,
+          "mean_steps": 75.72727272727273,
+          "mean_efficiency": 0.5875063141059967,
+          "mean_shortest": 27.25
+        },
+        "21": {
+          "episodes": 12,
+          "solve_rate": 0.8333333333333334,
+          "mean_steps": 807.9,
+          "mean_efficiency": 0.30990119379816417,
+          "mean_shortest": 90.41666666666667
+        },
+        "31": {
+          "episodes": 12,
+          "solve_rate": 0.75,
+          "mean_steps": 1308.888888888889,
+          "mean_efficiency": 0.14690739429443908,
+          "mean_shortest": 161.91666666666666
+        }
+      }
+    }
+  }
+}

runs/jevon-final/play/maze_random_summary.json

@@ -0,0 +1,543 @@
+{
+  "controller": "random",
+  "episodes": [
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 14,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901111,
+      "shortest": 32,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 25,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901148,
+      "shortest": 42,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 42,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901185,
+      "shortest": 40,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 26,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901111,
+      "shortest": 44,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 444,
+      "collisions": 0,
+      "distinct_cells": 35,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901148,
+      "shortest": 34,
+      "efficiency": 0.07657657657657657
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 23,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901185,
+      "shortest": 36,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 47,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 36,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901148,
+      "shortest": 22,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 426,
+      "collisions": 0,
+      "distinct_cells": 48,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901185,
+      "shortest": 18,
+      "efficiency": 0.04225352112676056
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 56,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 53,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901148,
+      "shortest": 16,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 484,
+      "collisions": 0,
+      "distinct_cells": 30,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901185,
+      "shortest": 13,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 23,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902121,
+      "shortest": 142,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 57,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902158,
+      "shortest": 116,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 45,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902195,
+      "shortest": 156,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 116,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902121,
+      "shortest": 118,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 28,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902158,
+      "shortest": 172,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 84,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902195,
+      "shortest": 140,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 67,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902121,
+      "shortest": 46,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 105,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902158,
+      "shortest": 40,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 121,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902195,
+      "shortest": 42,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 1764,
+      "collisions": 0,
+      "distinct_cells": 121,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902121,
+      "shortest": 41,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 494,
+      "collisions": 0,
+      "distinct_cells": 130,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902158,
+      "shortest": 36,
+      "efficiency": 0.0728744939271255
+    },
+    {
+      "solved": true,
+      "steps": 894,
+      "collisions": 0,
+      "distinct_cells": 152,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902195,
+      "shortest": 36,
+      "efficiency": 0.040268456375838924
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 48,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903131,
+      "shortest": 264,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 73,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903168,
+      "shortest": 194,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 85,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903205,
+      "shortest": 286,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 62,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903131,
+      "shortest": 268,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 58,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903168,
+      "shortest": 282,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 75,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903205,
+      "shortest": 252,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 376,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903131,
+      "shortest": 66,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 166,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903168,
+      "shortest": 72,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 178,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903205,
+      "shortest": 88,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 246,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903131,
+      "shortest": 57,
+      "efficiency": 0.0
+    },
+    {
+      "solved": false,
+      "steps": 3844,
+      "collisions": 0,
+      "distinct_cells": 315,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903168,
+      "shortest": 56,
+      "efficiency": 0.0
+    },
+    {
+      "solved": true,
+      "steps": 544,
+      "collisions": 0,
+      "distinct_cells": 155,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903205,
+      "shortest": 58,
+      "efficiency": 0.10661764705882353
+    }
+  ],
+  "summary": {
+    "maze": {
+      "episodes": 36,
+      "solve_rate": 0.1388888888888889,
+      "mean_steps_when_solved": 560.4,
+      "mean_efficiency": 0.06771813901302501,
+      "mean_collisions": 0.0,
+      "deadlock_rate": 0.0,
+      "mean_distinct_cells": 92.25,
+      "by_size": {
+        "11": {
+          "episodes": 12,
+          "solve_rate": 0.16666666666666666,
+          "mean_steps": 435.0,
+          "mean_efficiency": 0.05941504885166857,
+          "mean_shortest": 27.25
+        },
+        "21": {
+          "episodes": 12,
+          "solve_rate": 0.16666666666666666,
+          "mean_steps": 694.0,
+          "mean_efficiency": 0.05657147515148221,
+          "mean_shortest": 90.41666666666667
+        },
+        "31": {
+          "episodes": 12,
+          "solve_rate": 0.08333333333333333,
+          "mean_steps": 544.0,
+          "mean_efficiency": 0.10661764705882353,
+          "mean_shortest": 161.91666666666666
+        }
+      }
+    }
+  }
+}

runs/jevon-final/play/maze_reference_summary.json

@@ -0,0 +1,543 @@
+{
+  "controller": "reference",
+  "episodes": [
+    {
+      "solved": true,
+      "steps": 32,
+      "collisions": 0,
+      "distinct_cells": 33,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901111,
+      "shortest": 32,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901148,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "corridor",
+      "seed": 901185,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 44,
+      "collisions": 0,
+      "distinct_cells": 45,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901111,
+      "shortest": 44,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 34,
+      "collisions": 0,
+      "distinct_cells": 35,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901148,
+      "shortest": 34,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "tree",
+      "seed": 901185,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 22,
+      "collisions": 0,
+      "distinct_cells": 23,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901148,
+      "shortest": 22,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 18,
+      "collisions": 0,
+      "distinct_cells": 19,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "loops",
+      "seed": 901185,
+      "shortest": 18,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 15,
+      "collisions": 0,
+      "distinct_cells": 16,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901111,
+      "shortest": 15,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 16,
+      "collisions": 0,
+      "distinct_cells": 17,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901148,
+      "shortest": 16,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 13,
+      "collisions": 0,
+      "distinct_cells": 14,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 11,
+      "topology": "random_obstacle",
+      "seed": 901185,
+      "shortest": 13,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 142,
+      "collisions": 0,
+      "distinct_cells": 143,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902121,
+      "shortest": 142,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 116,
+      "collisions": 0,
+      "distinct_cells": 117,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902158,
+      "shortest": 116,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 156,
+      "collisions": 0,
+      "distinct_cells": 157,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "corridor",
+      "seed": 902195,
+      "shortest": 156,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 118,
+      "collisions": 0,
+      "distinct_cells": 119,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902121,
+      "shortest": 118,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 172,
+      "collisions": 0,
+      "distinct_cells": 173,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902158,
+      "shortest": 172,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 140,
+      "collisions": 0,
+      "distinct_cells": 141,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "tree",
+      "seed": 902195,
+      "shortest": 140,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 46,
+      "collisions": 0,
+      "distinct_cells": 47,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902121,
+      "shortest": 46,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 40,
+      "collisions": 0,
+      "distinct_cells": 41,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902158,
+      "shortest": 40,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 42,
+      "collisions": 0,
+      "distinct_cells": 43,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "loops",
+      "seed": 902195,
+      "shortest": 42,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 41,
+      "collisions": 0,
+      "distinct_cells": 42,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902121,
+      "shortest": 41,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902158,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 36,
+      "collisions": 0,
+      "distinct_cells": 37,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 21,
+      "topology": "random_obstacle",
+      "seed": 902195,
+      "shortest": 36,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 264,
+      "collisions": 0,
+      "distinct_cells": 265,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903131,
+      "shortest": 264,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 194,
+      "collisions": 0,
+      "distinct_cells": 195,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903168,
+      "shortest": 194,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 286,
+      "collisions": 0,
+      "distinct_cells": 287,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "corridor",
+      "seed": 903205,
+      "shortest": 286,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 268,
+      "collisions": 0,
+      "distinct_cells": 269,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903131,
+      "shortest": 268,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 282,
+      "collisions": 0,
+      "distinct_cells": 283,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903168,
+      "shortest": 282,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 252,
+      "collisions": 0,
+      "distinct_cells": 253,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "tree",
+      "seed": 903205,
+      "shortest": 252,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 66,
+      "collisions": 0,
+      "distinct_cells": 67,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903131,
+      "shortest": 66,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 72,
+      "collisions": 0,
+      "distinct_cells": 73,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903168,
+      "shortest": 72,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 88,
+      "collisions": 0,
+      "distinct_cells": 89,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "loops",
+      "seed": 903205,
+      "shortest": 88,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 57,
+      "collisions": 0,
+      "distinct_cells": 58,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903131,
+      "shortest": 57,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 56,
+      "collisions": 0,
+      "distinct_cells": 57,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903168,
+      "shortest": 56,
+      "efficiency": 1.0
+    },
+    {
+      "solved": true,
+      "steps": 58,
+      "collisions": 0,
+      "distinct_cells": 59,
+      "longest_stuck": 0,
+      "deadlocked": false,
+      "game": "maze",
+      "size": 31,
+      "topology": "random_obstacle",
+      "seed": 903205,
+      "shortest": 58,
+      "efficiency": 1.0
+    }
+  ],
+  "summary": {
+    "maze": {
+      "episodes": 36,
+      "solve_rate": 1.0,
+      "mean_steps_when_solved": 93.19444444444444,
+      "mean_efficiency": 1.0,
+      "mean_collisions": 0.0,
+      "deadlock_rate": 0.0,
+      "mean_distinct_cells": 94.19444444444444,
+      "by_size": {
+        "11": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 27.25,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 27.25
+        },
+        "21": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 90.41666666666667,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 90.41666666666667
+        },
+        "31": {
+          "episodes": 12,
+          "solve_rate": 1.0,
+          "mean_steps": 161.91666666666666,
+          "mean_efficiency": 1.0,
+          "mean_shortest": 161.91666666666666
+        }
+      }
+    }
+  }
+}

runs/jevon-final/play/snake_model_summary.json

@@ -0,0 +1,74 @@
+{
+  "controller": "model",
+  "episodes": [
+    {
+      "food": 0,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 3,
+      "game": "snake",
+      "size": 12,
+      "seed": 610084
+    },
+    {
+      "food": 4,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 7,
+      "game": "snake",
+      "size": 12,
+      "seed": 610137
+    },
+    {
+      "food": 4,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 7,
+      "game": "snake",
+      "size": 12,
+      "seed": 610190
+    },
+    {
+      "food": 0,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 3,
+      "game": "snake",
+      "size": 12,
+      "seed": 610243
+    },
+    {
+      "food": 16,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 19,
+      "game": "snake",
+      "size": 12,
+      "seed": 610296
+    },
+    {
+      "food": 3,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 6,
+      "game": "snake",
+      "size": 12,
+      "seed": 610349
+    }
+  ],
+  "summary": {
+    "snake": {
+      "episodes": 6,
+      "mean_food": 4.5,
+      "max_food": 16,
+      "mean_steps": 288.0,
+      "survival_rate": 1.0
+    }
+  }
+}

runs/jevon-final/play/snake_random_summary.json

@@ -0,0 +1,74 @@
+{
+  "controller": "random",
+  "episodes": [
+    {
+      "food": 0,
+      "steps": 7,
+      "alive": false,
+      "death": "wall",
+      "length": 3,
+      "game": "snake",
+      "size": 12,
+      "seed": 610084
+    },
+    {
+      "food": 0,
+      "steps": 19,
+      "alive": false,
+      "death": "wall",
+      "length": 3,
+      "game": "snake",
+      "size": 12,
+      "seed": 610137
+    },
+    {
+      "food": 2,
+      "steps": 60,
+      "alive": false,
+      "death": "body",
+      "length": 5,
+      "game": "snake",
+      "size": 12,
+      "seed": 610190
+    },
+    {
+      "food": 0,
+      "steps": 85,
+      "alive": false,
+      "death": "wall",
+      "length": 3,
+      "game": "snake",
+      "size": 12,
+      "seed": 610243
+    },
+    {
+      "food": 1,
+      "steps": 21,
+      "alive": false,
+      "death": "wall",
+      "length": 4,
+      "game": "snake",
+      "size": 12,
+      "seed": 610296
+    },
+    {
+      "food": 1,
+      "steps": 11,
+      "alive": false,
+      "death": "wall",
+      "length": 4,
+      "game": "snake",
+      "size": 12,
+      "seed": 610349
+    }
+  ],
+  "summary": {
+    "snake": {
+      "episodes": 6,
+      "mean_food": 0.6666666666666666,
+      "max_food": 2,
+      "mean_steps": 33.833333333333336,
+      "survival_rate": 0.0
+    }
+  }
+}

runs/jevon-final/play/snake_reference_summary.json

@@ -0,0 +1,74 @@
+{
+  "controller": "reference",
+  "episodes": [
+    {
+      "food": 16,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 19,
+      "game": "snake",
+      "size": 12,
+      "seed": 610084
+    },
+    {
+      "food": 30,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 33,
+      "game": "snake",
+      "size": 12,
+      "seed": 610137
+    },
+    {
+      "food": 31,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 34,
+      "game": "snake",
+      "size": 12,
+      "seed": 610190
+    },
+    {
+      "food": 22,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 25,
+      "game": "snake",
+      "size": 12,
+      "seed": 610243
+    },
+    {
+      "food": 13,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 16,
+      "game": "snake",
+      "size": 12,
+      "seed": 610296
+    },
+    {
+      "food": 29,
+      "steps": 288,
+      "alive": true,
+      "death": null,
+      "length": 32,
+      "game": "snake",
+      "size": 12,
+      "seed": 610349
+    }
+  ],
+  "summary": {
+    "snake": {
+      "episodes": 6,
+      "mean_food": 23.5,
+      "max_food": 31,
+      "mean_steps": 288.0,
+      "survival_rate": 1.0
+    }
+  }
+}

runs/jevon-final/probe.json

@@ -0,0 +1,42 @@
+{
+  "11": {
+    "cells": 215,
+    "probe_r2": 0.09365391731262207,
+    "probe_mae": 7.971122741699219,
+    "head_r2": 0.9999997019767761,
+    "descent_acc": 1.0,
+    "reach_rate": 1.0,
+    "diameter": 48,
+    "iterations": 82
+  },
+  "21": {
+    "cells": 901,
+    "probe_r2": 0.04196900129318237,
+    "probe_mae": 29.71183204650879,
+    "head_r2": 0.9999999403953552,
+    "descent_acc": 1.0,
+    "reach_rate": 1.0,
+    "diameter": 152,
+    "iterations": 262
+  },
+  "31": {
+    "cells": 2011,
+    "probe_r2": 0.031648457050323486,
+    "probe_mae": 63.062259674072266,
+    "head_r2": 1.0,
+    "descent_acc": 1.0,
+    "reach_rate": 1.0,
+    "diameter": 310,
+    "iterations": 542
+  },
+  "51": {
+    "cells": 5679,
+    "probe_r2": 0.006791293621063232,
+    "probe_mae": 145.2346954345703,
+    "head_r2": 1.0,
+    "descent_acc": 1.0,
+    "reach_rate": 1.0,
+    "diameter": 672,
+    "iterations": 1402
+  }
+}

runs/jevon-final/tokenizer.json

@@ -0,0 +1 @@
+{"vocab": ["<pad>", "<unk>", "<bos>", "<eos>", "<sep>", "<byte_0>", "<byte_1>", "<byte_2>", "<byte_3>", "<byte_4>", "<byte_5>", "<byte_6>", "<byte_7>", "<byte_8>", "<byte_9>", "<byte_10>", "<byte_11>", "<byte_12>", "<byte_13>", "<byte_14>", "<byte_15>", "<byte_16>", "<byte_17>", "<byte_18>", "<byte_19>", "<byte_20>", "<byte_21>", "<byte_22>", "<byte_23>", "<byte_24>", "<byte_25>", "<byte_26>", "<byte_27>", "<byte_28>", "<byte_29>", "<byte_30>", "<byte_31>", "<byte_32>", "<byte_33>", "<byte_34>", "<byte_35>", "<byte_36>", "<byte_37>", "<byte_38>", "<byte_39>", "<byte_40>", "<byte_41>", "<byte_42>", "<byte_43>", "<byte_44>", "<byte_45>", "<byte_46>", "<byte_47>", "<byte_48>", "<byte_49>", "<byte_50>", "<byte_51>", "<byte_52>", "<byte_53>", "<byte_54>", "<byte_55>", "<byte_56>", "<byte_57>", "<byte_58>", "<byte_59>", "<byte_60>", "<byte_61>", "<byte_62>", "<byte_63>", "<byte_64>", "<byte_65>", "<byte_66>", "<byte_67>", "<byte_68>", "<byte_69>", "<byte_70>", "<byte_71>", "<byte_72>", "<byte_73>", "<byte_74>", "<byte_75>", "<byte_76>", "<byte_77>", "<byte_78>", "<byte_79>", "<byte_80>", "<byte_81>", "<byte_82>", "<byte_83>", "<byte_84>", "<byte_85>", "<byte_86>", "<byte_87>", "<byte_88>", "<byte_89>", "<byte_90>", "<byte_91>", "<byte_92>", "<byte_93>", "<byte_94>", "<byte_95>", "<byte_96>", "<byte_97>", "<byte_98>", "<byte_99>", "<byte_100>", "<byte_101>", "<byte_102>", "<byte_103>", "<byte_104>", "<byte_105>", "<byte_106>", "<byte_107>", "<byte_108>", "<byte_109>", "<byte_110>", "<byte_111>", "<byte_112>", "<byte_113>", "<byte_114>", "<byte_115>", "<byte_116>", "<byte_117>", "<byte_118>", "<byte_119>", "<byte_120>", "<byte_121>", "<byte_122>", "<byte_123>", "<byte_124>", "<byte_125>", "<byte_126>", "<byte_127>", "<byte_128>", "<byte_129>", "<byte_130>", "<byte_131>", "<byte_132>", "<byte_133>", "<byte_134>", "<byte_135>", "<byte_136>", "<byte_137>", "<byte_138>", "<byte_139>", "<byte_140>", "<byte_141>", "<byte_142>", "<byte_143>", "<byte_144>", "<byte_145>", "<byte_146>", "<byte_147>", "<byte_148>", "<byte_149>", "<byte_150>", "<byte_151>", "<byte_152>", "<byte_153>", "<byte_154>", "<byte_155>", "<byte_156>", "<byte_157>", "<byte_158>", "<byte_159>", "<byte_160>", "<byte_161>", "<byte_162>", "<byte_163>", "<byte_164>", "<byte_165>", "<byte_166>", "<byte_167>", "<byte_168>", "<byte_169>", "<byte_170>", "<byte_171>", "<byte_172>", "<byte_173>", "<byte_174>", "<byte_175>", "<byte_176>", "<byte_177>", "<byte_178>", "<byte_179>", "<byte_180>", "<byte_181>", "<byte_182>", "<byte_183>", "<byte_184>", "<byte_185>", "<byte_186>", "<byte_187>", "<byte_188>", "<byte_189>", "<byte_190>", "<byte_191>", "<byte_192>", "<byte_193>", "<byte_194>", "<byte_195>", "<byte_196>", "<byte_197>", "<byte_198>", "<byte_199>", "<byte_200>", "<byte_201>", "<byte_202>", "<byte_203>", "<byte_204>", "<byte_205>", "<byte_206>", "<byte_207>", "<byte_208>", "<byte_209>", "<byte_210>", "<byte_211>", "<byte_212>", "<byte_213>", "<byte_214>", "<byte_215>", "<byte_216>", "<byte_217>", "<byte_218>", "<byte_219>", "<byte_220>", "<byte_221>", "<byte_222>", "<byte_223>", "<byte_224>", "<byte_225>", "<byte_226>", "<byte_227>", "<byte_228>", "<byte_229>", "<byte_230>", "<byte_231>", "<byte_232>", "<byte_233>", "<byte_234>", "<byte_235>", "<byte_236>", "<byte_237>", "<byte_238>", "<byte_239>", "<byte_240>", "<byte_241>", "<byte_242>", "<byte_243>", "<byte_244>", "<byte_245>", "<byte_246>", "<byte_247>", "<byte_248>", "<byte_249>", "<byte_250>", "<byte_251>", "<byte_252>", "<byte_253>", "<byte_254>", "<byte_255>", ".", "the", ",", "is", "(", ")", "goal", "a", "to", "moves", "proposition", "true", "not", "moving", "move", ":", "snake", "maze", "from", "within", "=", "/", "and", "wall", "east", "west", "probability", "south", "north", "1", "reaches", "which", "inside", "decide", ";", "cell", "5", "3", "7", "your", "agent", "on", "-", "room", "2", "'", "s", "open", "4", "or", "6", "next", "tie", "ties", "should", "share", "evenly", "9", "report", "confidence", "length", "own", "game", "does", "end", "still", "dead", "weigh", "options", "carefully", "8", "answer", "with", "for", "each", "option", "than", "five", "sixty", "task", "read", "board", "path", "legal", "all", "question", "please", "11", "immediately", "after", "can", "reach", "its", "tail", "so", "it", "sealed", "into", "pocket", "times", "x", "coordinates", "are", "zero", "based", "row", "column", "one", "how", "?", "more", "choose", "equally", "10", "13", "12", "15", "food", "that", "topology", "no", "diagonals", "wraparound", "stop", "far", "current", "this", "already", "two", "ten", "twenty", "away", "cannot", "be", "reached", "of", "cells", "connects", "shortest", "short", "if", "unreachable", "0", "14", "16", "21", "head", "facing", "reversing", "onto", "neck", "offered", "hitting", "body", "ends", "keeps", "alive", "makes", "most", "progress", "towards", "eating", "prefer", "leave", "an", "escape", "route", "good", "much", "have", "manoeuvre", "in", "trapped", "less", "long", "barely", "enough", "fit", "likely", "limited", "under", "three", "comfortable", "several", "wide", "eight", "17", "19", "25", "22", "29", "31", "corridor", "tree", "loops", "23", "random", "_", "obstacle", "20", "18", "27", "28", "24", "26", "30", "36", "85", "79", "33", "35", "59", "61", "56", "64", "50", "39", "71", "40", "32", "69", "62", "54", "37", "41", "111", "43", "70", "106", "101", "98", "47", "58", "49", "38", "60"]}

scripts/benchmark.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Full evaluation suite for a trained checkpoint.
+#
+#   scripts/benchmark.sh runs/jevon-final [arcade-data-dir] [weights]
+#
+# `weights` selects which checkpoint the whole suite is run against, and
+# defaults to balanced.pt -- the one chosen on min(maze_action, snake_action)
+# rather than on aggregate eval loss, which the boolean questions dominate.
+# Falls back to best.pt for runs trained before that existed. Every number in
+# RESULTS.md comes from the single checkpoint named here, so the evaluation,
+# the probe and all the play configs cannot silently disagree about which
+# model they measured.
+#
+# Writes eval.json, probe.json and play/*.json under the run directory, then
+# regenerates RESULTS.md from them.
+set -euo pipefail
+
+RUN="${1:-runs/jevon-final}"
+ARCADE="${2:-}"
+WEIGHTS="${3:-}"
+PY="${PYTHON:-$(dirname "$0")/../../.venv/bin/python}"
+[ -x "$PY" ] || PY=python3
+PLAY="$RUN/play"
+mkdir -p "$PLAY"
+
+if [ -z "$WEIGHTS" ]; then
+  if [ -f "$RUN/balanced.pt" ]; then WEIGHTS=balanced.pt; else WEIGHTS=best.pt; fi
+fi
+[ -f "$RUN/$WEIGHTS" ] || { echo "no such checkpoint: $RUN/$WEIGHTS" >&2; exit 1; }
+echo "==> benchmarking $RUN/$WEIGHTS"
+
+echo "==> question-level metrics and calibration"
+"$PY" scripts/evaluate.py --checkpoint "$RUN" --weights "$WEIGHTS" \
+  --splits data/frozen/val.jsonl,data/frozen/test.jsonl,data/frozen/ood.jsonl \
+  --out "$RUN/eval.json"
+
+echo "==> planner field probe"
+"$PY" scripts/probe.py --checkpoint "$RUN" --weights "$WEIGHTS" \
+  --out "$RUN/probe.json"
+
+play () {  # play <name> <game> <controller> <extra...>
+  local name="$1" game="$2" ctrl="$3"; shift 3
+  echo "==> play: $name"
+  local trace=()
+  # --trace-max-steps shortens the replay, never the episode, so the summary is
+  # still measured over the full run. Without it a random walk on a 31x31 board
+  # contributes its whole 3844-step cap and the arcade data directory grows to
+  # megabytes of JSON nobody will scrub through. record.sh in the arcade repo
+  # uses the same cap; they must agree or the two repos ship different replays.
+  [ -n "$ARCADE" ] && trace=(--trace-out "$ARCADE/${name}.json" --trace-max-steps 400)
+  "$PY" scripts/play.py --checkpoint "$RUN" --weights "$WEIGHTS" \
+    --game "$game" --controller "$ctrl" \
+    --out "$PLAY/${name}_summary.json" "${trace[@]}" "$@"
+  [ -n "$ARCADE" ] && cp "$PLAY/${name}_summary.json" "$ARCADE/" || true
+}
+
+MAZE_ARGS=(--episodes 3 --maze-sizes 11,21,31)
+SNAKE_ARGS=(--episodes 6 --snake-sizes 12)
+
+play maze_model        maze  model        "${MAZE_ARGS[@]}"
+# Same network, same absence of search or memory, but sampling from the
+# distribution instead of taking its argmax. Now that only legal moves are
+# offered, a greedy controller cannot bang into a wall, but it can still cycle:
+# the planner is stateless, so a two-cell oscillation repeats forever. Sampling
+# breaks that with no memory at all, if the policy is calibrated enough for its
+# second choice to be worth taking. Whether it is, is the point of measuring.
+play maze_model_sampled maze model "${MAZE_ARGS[@]}" --temperature 1.0
+play maze_model_field  maze  model-field  "${MAZE_ARGS[@]}"
+play maze_model_memory maze  model+memory "${MAZE_ARGS[@]}"
+play maze_reference    maze  reference    "${MAZE_ARGS[@]}"
+play maze_random       maze  random       "${MAZE_ARGS[@]}"
+# The control for maze_model_memory, and the reason that row cannot be read on
+# its own. Identical bookkeeping, no network: whatever this solves, the memory
+# solved. On a small board near-exhaustive exploration is enough to match the
+# model on solve rate, so the two separate on path length, not on arrival.
+play maze_random_memory maze random+memory "${MAZE_ARGS[@]}"
+play snake_model       snake model        "${SNAKE_ARGS[@]}"
+play snake_reference   snake reference    "${SNAKE_ARGS[@]}"
+play snake_random      snake random       "${SNAKE_ARGS[@]}"
+
+echo "==> RESULTS.md"
+"$PY" scripts/make_results.py --run "$RUN" --eval "$RUN/eval.json" \
+  --probe "$RUN/probe.json" --play-dir "$PLAY"
+
+# The README headline is generated from the same JSON, so it cannot disagree
+# with RESULTS.md. Only refreshed when benchmarking the run the README is
+# about; benchmarking an experimental arm must not rewrite the front page.
+if [ "$RUN" = "runs/jevon-final" ]; then
+  echo "==> README headline"
+  "$PY" scripts/readme_table.py --run "$RUN"
+fi

scripts/build_dataset.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Freeze evaluation splits so every run is scored on identical states."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from jevon.data import SamplerConfig, freeze_split
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--out-dir", default="data/frozen")
+    p.add_argument("--val-states", type=int, default=180)
+    p.add_argument("--test-states", type=int, default=240)
+    p.add_argument("--ood-states", type=int, default=160)
+    p.add_argument("--seed", type=int, default=20260919)
+    args = p.parse_args()
+
+    out = Path(args.out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    base = SamplerConfig(augment=False)
+    # Sizes never sampled in training; this is the size-generalisation probe.
+    ood = SamplerConfig(maze_sizes=(41, 51), snake_sizes=(20, 24), augment=False)
+
+    manifest = {}
+    manifest["val"] = freeze_split(out / "val.jsonl", base, "val", args.val_states,
+                                   args.seed)
+    manifest["test"] = freeze_split(out / "test.jsonl", base, "test",
+                                    args.test_states, args.seed + 1)
+    manifest["ood"] = freeze_split(out / "ood.jsonl", ood, "test", args.ood_states,
+                                   args.seed + 2)
+    manifest["config"] = {"train_maze_sizes": list(base.maze_sizes),
+                          "train_snake_sizes": list(base.snake_sizes),
+                          "ood_maze_sizes": list(ood.maze_sizes),
+                          "ood_snake_sizes": list(ood.snake_sizes)}
+    (out / "manifest.json").write_text(json.dumps(manifest, indent=2))
+    print(json.dumps(manifest, indent=2))
+
+
+if __name__ == "__main__":
+    main()

scripts/evaluate.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Question-level evaluation: accuracy, distribution error, and calibration.
+
+Reported per split, per game, and per question type.  Two controls are printed
+alongside every accuracy so the numbers cannot be read as better than they are:
+``majority`` is the accuracy of always answering the most common label, and
+``uniform`` is the accuracy of guessing uniformly over the offered candidates.
+NanoJev's maze atomic accuracy matched its own always-true control exactly,
+which is the failure mode these columns are here to expose.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+import torch
+
+from jevon.data import collate, load_frozen
+from jevon.inference import JevonRunner
+from jevon.losses import calibration_bins
+from jevon.planner import default_iterations
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--checkpoint", default="runs/jevon-final")
+    # None means "prefer balanced.pt", the checkpoint every shipped number
+    # comes from. See jevon.inference.resolve_weights.
+    p.add_argument("--weights", default=None)
+    p.add_argument("--splits", default="data/frozen/test.jsonl,data/frozen/ood.jsonl")
+    p.add_argument("--batch-states", type=int, default=8)
+    p.add_argument("--device", default="mps")
+    p.add_argument("--out", default=None)
+    args = p.parse_args()
+
+    runner = JevonRunner(args.checkpoint, args.device, args.weights)
+    report = {}
+
+    for path in args.splits.split(","):
+        path = path.strip()
+        if not path or not Path(path).exists():
+            continue
+        name = Path(path).stem
+        states = load_frozen(path)
+        buckets: dict[tuple[str, str], list] = defaultdict(list)
+        # How many distinct boards a bucket's questions came from. Several
+        # questions about one maze would not be several independent tests of
+        # whether the model can read a maze -- they share walls, goal and
+        # distance field, so they succeed or fail together -- and n alone
+        # cannot tell you whether that is happening. Measured here it is not:
+        # the generator draws a fresh board per state, so boards tracks n on
+        # every split. The column exists to keep that checkable rather than
+        # assumed, because it is a property of the generator and generators
+        # get edited.
+        board_ids: dict[tuple[str, str], set] = defaultdict(set)
+        conf, hit = [], []
+        with torch.no_grad():
+            for start in range(0, len(states), args.batch_states):
+                group = states[start:start + args.batch_states]
+                batch = collate(group, runner.tokenizer, device=runner.device)
+                steps = default_iterations(int(batch["board_size"].max()))
+                logits = runner.model(batch, iterations=steps, grad_steps=0)
+                probs = logits.float().softmax(-1).cpu()
+                target = batch["target_probs"].cpu()
+                for row, meta in enumerate(batch["meta"]):
+                    k = len(meta["probs"])
+                    pr, tg = probs[row, :k], target[row, :k]
+                    picked = int(pr.argmax())
+                    correct = float(tg[picked] >= tg.max() - 1e-6)
+                    tvd = float(0.5 * (pr - tg).abs().sum())
+                    brier = float(((pr - tg) ** 2).sum())
+                    # Controls computed on the very same questions.
+                    majority = float(tg[int(tg.argmax())] >= tg.max() - 1e-6)
+                    uniform = float(tg.max() * 0 + (tg >= tg.max() - 1e-6).float().mean())
+                    key = (meta["game"], meta["type"])
+                    # The uid schema differs per game -- maze is
+                    # "maze:<topology>:<size>:<seed>:<row>_<col>" and snake is
+                    # "snake:<size>:<seed>:<step>" -- but the last segment is
+                    # the within-board position in both, so dropping it names
+                    # the board either way. Cross-checked against a hash of
+                    # channel 0 and the goal cell: the two agree to within
+                    # three coincidental duplicates across all three splits.
+                    board = (meta["size"], meta["topology"],
+                             meta["uid"].rsplit(":", 1)[0])
+                    kind_key = (meta["game"], meta["question"].split("_")[0])
+                    buckets[key].append((correct, tvd, brier, uniform))
+                    buckets[kind_key].append((correct, tvd, brier, uniform))
+                    board_ids[key].add(board)
+                    board_ids[kind_key].add(board)
+                    del majority
+                    conf.append(float(pr.max()))
+                    hit.append(correct)
+        rows = {}
+        for (game, kind), values in sorted(buckets.items()):
+            n = len(values)
+            rows[f"{game}/{kind}"] = {
+                "n": n,
+                "boards": len(board_ids[(game, kind)]),
+                "accuracy": sum(v[0] for v in values) / n,
+                "uniform_control": sum(v[3] for v in values) / n,
+                "tvd": sum(v[1] for v in values) / n,
+                "brier": sum(v[2] for v in values) / n,
+            }
+        calib = calibration_bins(torch.tensor(conf), torch.tensor(hit))
+        report[name] = {"states": len(states), "questions": len(conf),
+                        "ece": calib["ece"], "groups": rows}
+        print(f"\n=== {name}: {len(states)} states / {len(conf)} questions "
+              f"(ECE {calib['ece']:.4f}) ===")
+        print(f"{'group':28s} {'n':>5s} {'brds':>5s} {'acc':>7s} {'unif':>7s} "
+              f"{'tvd':>7s} {'brier':>7s}")
+        for key, row in rows.items():
+            print(f"{key:28s} {row['n']:5d} {row['boards']:5d} "
+                  f"{row['accuracy']:7.4f} {row['uniform_control']:7.4f} "
+                  f"{row['tvd']:7.4f} {row['brier']:7.4f}")
+
+    if args.out:
+        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.out).write_text(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()

scripts/make_results.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""Generate RESULTS.md from the evaluation artifacts.
+
+Every number in the document comes from a JSON file written by another
+script, so the documented results and the measured results cannot drift.
+Missing inputs are skipped with a note rather than guessed at.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def read(path: Path):
+    try:
+        return json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def training_section(run: Path, has_probe: bool = True) -> list[str]:
+    history = read(run / "history.json")
+    if not history:
+        return []
+    out = ["## Training curve", "",
+           "Frozen validation split, never sampled during training.", "",
+           "`conv field R²` scores `supervised_field()` -- the conv head the "
+           "field loss trains. It is **not** the field the controller "
+           "descends. Under `--min-plus-field` those are different objects: "
+           "the read-out is the min-plus recurrence" +
+           (", scored as `read-out R²` in the probe table above" if has_probe
+            else "") +
+           ", and nothing at inference reads the conv "
+           "head at all. It stays in the loss as an auxiliary task on the "
+           "shared trunk, so a negative value here means that auxiliary head "
+           "has stopped tracking the trunk the action head and the recurrence "
+           "are shaping -- it does not mean the planner is wrong, and `reach` "
+           "is where that would show up.", "",
+           "| step | loss | acc | choice | boolean | score | conv field R² | maze action | snake action |",
+           "| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |"]
+    for row in history:
+        out.append(
+            f"| {row['step']} | {row['loss']:.4f} | {row['acc']:.4f} | "
+            f"{row.get('acc_choice', float('nan')):.4f} | "
+            f"{row.get('acc_boolean', float('nan')):.4f} | "
+            f"{row.get('acc_score', float('nan')):.4f} | "
+            f"{row.get('field_r2', float('nan')):.4f} | "
+            f"{row.get('maze_action', float('nan')):.4f} | "
+            f"{row.get('snake_action', float('nan')):.4f} |")
+    return out + [""]
+
+
+def eval_section(data) -> list[str]:
+    if not data:
+        return []
+    out = ["## Question-level accuracy", "",
+           "`uniform` is the accuracy of guessing uniformly over the same "
+           "candidates. A model that matches its control has learned nothing, "
+           "which is the failure NanoJev's own log records for its maze model.", "",
+           "`boards` is how many distinct boards the row's questions came "
+           "from, and it is there so that `n` can be trusted. Questions that "
+           "share a board are not independent tests of whether the model can "
+           "read a board -- they share walls, goal and distance field, so "
+           "they succeed or fail together -- and a row reporting `n` alone "
+           "cannot tell you whether that is happening. Here it is not: the "
+           "generator draws a fresh board per state, so `boards` tracks `n` "
+           "on every split and `n` is the honest denominator. A row where "
+           "the two diverge is one whose precision should be read off "
+           "`boards`.", ""]
+    for split, block in data.items():
+        out += [f"### {split} — {block['questions']} questions, ECE {block['ece']:.4f}", "",
+                "| group | n | boards | accuracy | uniform control | TVD | Brier |",
+                "| --- | ---: | ---: | ---: | ---: | ---: | ---: |"]
+        for name, row in block["groups"].items():
+            boards = row.get("boards")
+            out.append(f"| `{name}` | {row['n']} | "
+                       f"{'--' if boards is None else boards} | "
+                       f"**{row['accuracy']:.4f}** | "
+                       f"{row['uniform_control']:.4f} | {row['tvd']:.4f} | "
+                       f"{row['brier']:.4f} |")
+        out.append("")
+    return out
+
+
+def probe_section(data) -> list[str]:
+    if not data:
+        return []
+    out = ["## Does the planner actually compute distances?", "",
+           "Ridge probe from the planner's per-cell features to true BFS "
+           "distance, on held-out mazes. `diameter` is the longest true "
+           "shortest-path in those boards; `T` is the iteration budget.", "",
+           "`descent` is the fraction of cells whose lowest-predicted "
+           "neighbour lies on a true shortest path. `reach` is the fraction "
+           "from which greedy descent actually arrives at the goal, and it "
+           "is the one that predicts solve rate: a field can be right 70% of "
+           "the time per step and still trap most walks in a spurious basin, "
+           "so `descent` is an upper bound on nothing in particular. R² "
+           "scores absolute values; only `reach` scores the behaviour.", "",
+           "`read-out R²` scores `predict_field()`, the field this "
+           "controller actually descends -- the min-plus recurrence when "
+           "the run enabled it, the conv head otherwise. The training "
+           "curve's `conv field R²` scores a different head; see the "
+           "note there.", "",
+           "| size | cells | probe R² | probe MAE (cells) | read-out R² | descent | reach | diameter | T |",
+           "| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |"]
+    for size, row in data.items():
+        out.append(f"| {size} | {row['cells']} | **{row['probe_r2']:.4f}** | "
+                   f"{row['probe_mae']:.2f} | {row['head_r2']:.4f} | "
+                   f"{row.get('descent_acc', float('nan')):.4f} | "
+                   f"**{row.get('reach_rate', float('nan')):.4f}** | "
+                   f"{row['diameter']} | {row['iterations']} |")
+    return out + [""]
+
+
+# Reading order, not alphabetical order. Sorting by filename puts
+# `maze_random_memory` three rows below the `maze_model_memory` it is the
+# control for, and `model+memory` above the plain `model` it is scaffolding
+# over. Anything not listed here still renders, at the end, so adding a play
+# config can never silently drop it from the table.
+PLAY_ORDER = ["maze_model", "maze_model_sampled", "maze_model_field",
+              "maze_model_memory", "maze_random_memory", "maze_reference",
+              "maze_random", "snake_model", "snake_reference", "snake_random"]
+
+
+def play_section(summaries: dict) -> list[str]:
+    maze, snake = [], []
+    ordered = sorted(summaries.items(),
+                     key=lambda kv: (PLAY_ORDER.index(kv[0])
+                                     if kv[0] in PLAY_ORDER else len(PLAY_ORDER),
+                                     kv[0]))
+    for label, data in ordered:
+        block = data.get("summary", data) if data else {}
+        if "maze" in block:
+            m = block["maze"]
+            steps = m.get("mean_steps_when_solved")
+            dead = m.get("deadlock_rate")
+            maze.append(f"| `{label}` | {m['solve_rate']:.2f} | "
+                        f"{'--' if steps is None else format(steps, '.1f')} | "
+                        f"{m['mean_efficiency']:.3f} | {m['mean_collisions']:.1f} | "
+                        f"{'--' if dead is None else format(dead, '.2f')} | "
+                        f"{m.get('mean_distinct_cells', float('nan')):.1f} |")
+        if "snake" in block:
+            s = block["snake"]
+            snake.append(f"| `{label}` | {s['mean_food']:.2f} | {s['max_food']} | "
+                         f"{s['mean_steps']:.1f} | {s['survival_rate']:.2f} |")
+    out = []
+    if maze:
+        out += ["## Closed-loop play", "",
+                "Read `model` and `model-field` as answering different "
+                "questions. `model` is the network's action head alone -- no "
+                "search, no memory, no visited set -- and is the "
+                "apples-to-apples comparison with NanoJev. `model-field` "
+                "descends a min-plus recurrence whose fixed point is a "
+                "shortest-path distance by construction, so it arrives from "
+                "anywhere; for a maze it does so at initialisation, before "
+                "any training, because uniform cost is already the right "
+                "answer. Its solve rate is a property of the architecture, "
+                "not a measurement of what this run learned.", "",
+                "### Maze", "",
+                "`deadlock` is the fraction of episodes in which the "
+                "controller spent a tenth of its step budget walking into the "
+                "same wall, and `cells` is how many distinct squares it stood "
+                "on. They separate two failures a solve rate of 0.00 reports "
+                "identically: standing still and touring the board. Deadlock "
+                "should now read 0.00 for every controller, because only legal "
+                "moves are offered as candidates -- it is kept as a regression "
+                "guard, not a finding. The failure that remains is cycling: "
+                "the planner never sees the agent, so a greedy policy that "
+                "steps A->B->A has no state with which to notice, and `cells` "
+                "is what exposes it.", "",
+                "| controller | solve rate | mean steps | efficiency | collisions | deadlock | cells |",
+                "| --- | ---: | ---: | ---: | ---: | ---: | ---: |"] + maze + [""]
+    if snake:
+        out += ["### Snake", "",
+                "| controller | mean food | max food | mean steps | survival |",
+                "| --- | ---: | ---: | ---: | ---: |"] + snake + [""]
+    return out
+
+
+def nanojev_section() -> list[str]:
+    """The numbers NanoJev reports for itself, quoted from its own repo.
+
+    Transcribed from docs/DEVELOPMENT_RESULTS.md in TianyuCodings/NanoJev so
+    the comparison is against what its authors measured, not a rerun of ours.
+    The point of the table is the control column: where a reported accuracy
+    equals the always-true rate, the number is reporting the class balance.
+    """
+    return [
+        "## Baseline: what NanoJev reports for itself", "",
+        "From `docs/DEVELOPMENT_RESULTS.md` in the NanoJev repository.", "",
+        "| NanoJev task | reported acc | always-true control | above control |",
+        "| --- | ---: | ---: | :---: |",
+        "| `scaled_maze` (test) | 0.5625 | 0.5625 | no |",
+        "| `scaled_maze` (ood) | 0.5625 | 0.5625 | no |",
+        "| `snake_one_step_safety_v4` | 0.9220 | 0.9220 | no |",
+        "",
+        "Closed-loop play, same source, 128-step limit:", "",
+        "| maze | Jev | NanoJev | reference |",
+        "| --- | ---: | ---: | ---: |",
+        "| all three mazes | 0/128 | 0/128 | solved 1/16, 1/24, 1/96 |",
+        "",
+        "> \"The learned direct-action models and Jev do not solve any of these",
+        "> three mazes within the shared 128-step limit.\"", "",
+        "Every accuracy in this file is therefore printed next to its",
+        "constant-prediction control, and gameplay is reported as solve rate",
+        "rather than per-question accuracy.", "",
+    ]
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--run", default="runs/jevon-final")
+    p.add_argument("--eval", default="runs/jevon-final/eval.json")
+    p.add_argument("--probe", default="runs/jevon-final/probe.json")
+    p.add_argument("--play-dir", default="runs/jevon-final/play")
+    p.add_argument("--out", default="RESULTS.md")
+    args = p.parse_args()
+
+    summaries = {}
+    play_dir = Path(args.play_dir)
+    if play_dir.is_dir():
+        for path in sorted(play_dir.glob("*_summary.json")):
+            summaries[path.stem.replace("_summary", "")] = read(path)
+
+    lines = ["# Results", "",
+             "Generated by `scripts/make_results.py` from the JSON written by "
+             "`train.py`, `evaluate.py`, `probe.py` and `play.py`. Do not edit "
+             "by hand.", ""]
+    lines += nanojev_section()
+    probe = read(Path(args.probe))
+    lines += probe_section(probe)
+    lines += eval_section(read(Path(args.eval)))
+    lines += play_section(summaries)
+    lines += training_section(Path(args.run), has_probe=bool(probe))
+
+    Path(args.out).write_text("\n".join(lines))
+    print(f"wrote {args.out} ({len(lines)} lines)")
+
+
+if __name__ == "__main__":
+    main()

scripts/play.py

@@ -0,0 +1,413 @@
+#!/usr/bin/env python3
+"""Closed-loop gameplay evaluation.
+
+Controllers are kept deliberately separable so it is clear what is doing the
+work.  ``model`` asks the network for the action distribution and does nothing
+else -- no search, no visited set, no memory.  ``model+memory`` adds the thin
+bookkeeping a deployed agent would have, which is roughly what NanoJev's
+showcase controller provides, and is reported separately rather than folded
+into the headline number.
+
+``random+memory`` is that second row's control, and the reason it exists: the
+memory is doing enough of the work that ``model+memory`` says very little on
+its own.  Running the identical bookkeeping with no network behind it says how
+much.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import random
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+import torch
+
+from envs import maze as mz
+from envs import snake as sk
+from jevon.inference import JevonRunner, maze_state_sample, snake_state_sample
+
+
+# ---------------------------------------------------------------- policies
+
+def model_action(runner, sample, legal, rng, temperature):
+    answers = {a["question"]: a for a in runner.answer([sample])}
+    row = answers.get("action")
+    if row is None:
+        # question_profile omits the action question when fewer than two moves
+        # are legal, because there is nothing to choose between. The answer is
+        # then forced, and taking it is not a guess -- but taking legal[0] is.
+        # That fallback used to fire at every one-exit cell and return `north`,
+        # a wall, so the agent never moved and was handed the identical state
+        # forever. Every maze figure for this controller measured that, not the
+        # network.
+        return (legal[0] if len(legal) == 1 else rng.choice(legal)), {}
+    distribution = {k: v for k, v in row["probabilities"].items() if k in legal}
+    if not distribution:
+        return rng.choice(legal), row["probabilities"]
+    if temperature <= 0:
+        return max(distribution, key=distribution.get), distribution
+    keys = list(distribution)
+    weights = [max(distribution[k], 1e-9) ** (1.0 / temperature) for k in keys]
+    return rng.choices(keys, weights=weights, k=1)[0], distribution
+
+
+def field_action(runner, sample, state, legal, rng):
+    """Move to the neighbouring cell the planner thinks is closest to the goal.
+
+    Pure greedy descent on the model's own learned field -- no search, no
+    memory, no visited set. It reads the planner's training read-out instead of
+    the text-conditioned action head, so it measures whether the recurrence
+    learned a usable value function rather than whether the language side
+    learned to describe one.
+    """
+    field = runner.distance_field(sample)
+    scores = {}
+    for action in legal:
+        dr, dc = mz.DIRECTIONS[action]
+        cell = (state.position[0] + dr, state.position[1] + dc)
+        if not state.free(cell):
+            continue
+        scores[action] = float(field[cell])
+    if not scores:
+        return rng.choice(legal), {}
+    best = min(scores.values())
+    # Report it as a distribution so traces render the same way as the others.
+    weights = {a: math.exp(-(v - best) * 8.0) for a, v in scores.items()}
+    total = sum(weights.values())
+    return min(scores, key=scores.get), {a: w / total for a, w in weights.items()}
+
+
+def episode_field(runner, state):
+    """The model's predicted distance-to-goal for every cell, once per episode.
+
+    The planner never sees the agent, so this is constant for the whole
+    episode -- the same property that lets the controller cache it.  Recorded
+    so the viewer can show what the model believes about the board, not just
+    which move it picked.
+    """
+    if runner is None:
+        return None
+    try:
+        field = runner.distance_field(maze_state_sample(state))
+    except RuntimeError:                       # checkpoint trained without a planner
+        return None
+    return [[round(float(v), 4) for v in row] for row in field]
+
+
+class Recorder(list):
+    """A step log with a ceiling, so a trace stays viewable without lying.
+
+    A random walk on a 31x31 maze runs to its 3844-step cap, and thirty-six of
+    those come to roughly six megabytes of JSON that nobody will ever scrub
+    through. Truncating the *recording* keeps the episode itself untouched, so
+    the summary -- solve rate, step count, collisions -- is still the real one;
+    only the replay is shortened, and ``truncated`` says by how much.
+    """
+
+    def __init__(self, cap: int = 0):
+        super().__init__()
+        self.cap = cap
+        self.seen = 0
+
+    def append(self, item) -> None:
+        self.seen += 1
+        if not self.cap or len(self) < self.cap:
+            super().append(item)
+
+    @property
+    def truncated(self) -> int:
+        return self.seen - len(self)
+
+
+def maze_steps(runner, state, controller, max_steps, rng, temperature=0.0):
+    """One decision per ``next()``, yielding the step it just recorded.
+
+    Written as a generator so the live server in the arcade repo can take a
+    single forward pass per request while ``play_maze`` below drains it in a
+    loop. The alternative was a second copy of this decision logic behind an
+    HTTP handler, which is the failure mode these two repos have hit more than
+    any other -- and this is the loop every shipped number is measured from,
+    so a divergent copy would be a viewer demonstrating a model nobody
+    benchmarked. Returns the episode result, so callers need ``StopIteration``
+    or ``yield from``.
+    """
+    # The set of cells stood on, read twice. It is the ``model+memory``
+    # controller's whole memory -- prefer a move that leaves ground already
+    # covered -- and it is also the wandering diagnostic, because an agent that
+    # visited one cell and an agent that toured forty both score 0.00.
+    #
+    # Memory used to mean remembering which (cell, action) pairs had bounced
+    # off a wall. Restricting the candidate set to legal moves made that set
+    # permanently empty, which would have left ``model+memory`` a silent
+    # duplicate of ``model`` and its row in the results table a lie. Cycles are
+    # what end these episodes now: the planner is stateless, so a greedy policy
+    # that steps A->B->A repeats it for the whole budget.
+    seen: set[tuple[int, int]] = {state.position}
+    stuck = longest_stuck = 0
+    while state.steps < max_steps and not state.solved():
+        # The action question offers only legal moves as criteria, so ranking
+        # all four here asks the model to score candidates it was never trained
+        # on and lets a wall win.
+        legal = state.legal_actions() or list(mz.ACTIONS)
+        # The memory, applied before any policy sees the list, so `model+memory`
+        # and `random+memory` differ in exactly one thing: who picks among the
+        # survivors. Anything `random+memory` already achieves is the memory's
+        # doing, not the network's.
+        options = legal
+        if controller.endswith("+memory"):
+            r, c = state.position
+            fresh = []
+            for a in legal:
+                dr, dc = mz.DIRECTIONS[a]
+                if (r + dr, c + dc) not in seen:
+                    fresh.append(a)
+            options = fresh or legal
+
+        if controller == "reference":
+            probs = mz.optimal_action_distribution(state)
+            action = max(probs, key=probs.get) if probs else rng.choice(legal)
+            distribution = probs
+        elif controller.startswith("random"):
+            action, distribution = rng.choice(options), {}
+        elif controller == "model-field":
+            sample = maze_state_sample(state)
+            action, distribution = field_action(runner, sample, state, legal, rng)
+        else:
+            sample = maze_state_sample(state)
+            action, distribution = model_action(runner, sample, options, rng, temperature)
+        before = state.position
+        moved = state.step(action)
+        if not moved:
+            stuck += 1
+            longest_stuck = max(longest_stuck, stuck)
+        else:
+            stuck = 0
+            seen.add(state.position)
+        yield {"position": list(before), "action": action, "moved": moved,
+               "probabilities": {k: round(float(v), 4)
+                                 for k, v in (distribution or {}).items()}}
+    return {"solved": state.solved(), "steps": state.steps,
+            "collisions": state.collisions, "distinct_cells": len(seen),
+            "longest_stuck": longest_stuck,
+            # Kept as a guard rather than a finding. It fired on every episode
+            # while blocked moves were being offered as candidates; with only
+            # legal moves on the list it should stay at zero, so a non-zero
+            # value means something has regressed.
+            "deadlocked": longest_stuck >= max(20, max_steps // 10)}
+
+
+def snake_steps(runner, state, controller, max_steps, rng, temperature=0.0):
+    """One decision per ``next()``. See ``maze_steps``."""
+    while state.alive and state.steps < max_steps:
+        legal = state.candidate_actions()
+        if controller == "reference":
+            probs, _ = sk.oracle_action_distribution(state)
+            action = max(probs, key=probs.get) if probs else rng.choice(legal)
+            distribution = probs
+        elif controller == "random":
+            action, distribution = rng.choice(legal), {}
+        else:
+            sample = snake_state_sample(state)
+            action, distribution = model_action(runner, sample, legal, rng, temperature)
+        head, food, body = state.head, state.food, list(state.body)
+        state.step(action)
+        yield {"head": list(head), "food": list(food),
+               "body": [list(c) for c in body], "action": action,
+               "probabilities": {k: round(float(v), 4)
+                                 for k, v in (distribution or {}).items()}}
+    return {"food": state.eaten, "steps": state.steps, "alive": state.alive,
+            "death": state.death, "length": len(state.body)}
+
+
+def default_max_steps(game: str, size: int) -> int:
+    """The step budget an episode gets when none is given.
+
+    Lives here rather than in each caller because the arcade's live server
+    plays the same games through the same generators, and a budget that
+    differed between the two would make a live episode and a recorded one
+    disagree about what "failed" means -- the model looks worse or better
+    purely by where it was run.
+    """
+    return (4 if game == "maze" else 2) * size * size
+
+
+def _drain(steps, record):
+    """Run a step generator to the end, recording as it goes.
+
+    The wrappers below keep ``play.py``'s own callers unchanged: the generator
+    is the shared thing, and running it to completion is what batch recording
+    happens to want.
+    """
+    while True:
+        try:
+            step = next(steps)
+        except StopIteration as stop:
+            return stop.value
+        if record is not None:
+            record.append(step)
+
+
+def play_maze(runner, state, controller, max_steps, rng, temperature=0.0,
+              record=None):
+    return _drain(maze_steps(runner, state, controller, max_steps, rng,
+                             temperature), record)
+
+
+def play_snake(runner, state, controller, max_steps, rng, temperature=0.0,
+               record=None):
+    return _drain(snake_steps(runner, state, controller, max_steps, rng,
+                              temperature), record)
+
+
+# ---------------------------------------------------------------- driver
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--checkpoint", default="runs/jevon-final")
+    # None means "prefer balanced.pt", the checkpoint every shipped number
+    # comes from. See jevon.inference.resolve_weights.
+    p.add_argument("--weights", default=None)
+    p.add_argument("--game", choices=("maze", "snake", "both"), default="both")
+    p.add_argument("--controller", default="model",
+                   choices=("model", "model+memory", "model-field",
+                            "reference", "random", "random+memory"))
+    p.add_argument("--episodes", type=int, default=12)
+    p.add_argument("--maze-sizes", default="11,21,31,51")
+    p.add_argument("--maze-topologies", default="corridor,tree,loops,random_obstacle")
+    p.add_argument("--snake-sizes", default="12")
+    p.add_argument("--max-steps", type=int, default=0, help="0 => 4*size^2 for maze, 2*size^2 for snake")
+    p.add_argument("--temperature", type=float, default=0.0)
+    p.add_argument("--seed", type=int, default=17)
+    p.add_argument("--device", default="mps")
+    p.add_argument("--out", default=None)
+    p.add_argument("--trace-out", default=None, help="write per-step replay JSON")
+    p.add_argument("--trace-max-steps", type=int, default=0,
+                   help="record at most this many steps per episode; the "
+                        "episode still runs to completion, so summaries are "
+                        "unaffected (0 => record everything)")
+    args = p.parse_args()
+
+    if args.controller == "model-field" and args.game != "maze":
+        # Snake's field is distance to food, which is the wrong thing to
+        # descend greedily -- survival dominates. Silently falling back to
+        # the action head would mislabel a row in the results table.
+        p.error("--controller model-field only applies to --game maze")
+
+    rng = random.Random(args.seed)
+    runner = None
+    if args.controller.startswith("model"):
+        runner = JevonRunner(args.checkpoint, args.device, args.weights)
+
+    results = {"controller": args.controller, "episodes": []}
+    traces = []
+
+    if args.game in ("maze", "both"):
+        for size in [int(s) for s in args.maze_sizes.split(",")]:
+            for topology in args.maze_topologies.split(","):
+                for i in range(args.episodes):
+                    seed = 900_000 + i * 37 + size * 101
+                    state = mz.generate_maze(size, topology, seed)
+                    shortest = mz.bfs_distances(size, state.walls,
+                                                state.goal)[state.position]
+                    cap = args.max_steps or default_max_steps("maze", size)
+                    record = Recorder(args.trace_max_steps) if args.trace_out else None
+                    # Before play, because play mutates the agent's position --
+                    # the field itself does not depend on it, but recording it
+                    # first keeps that independence obvious rather than assumed.
+                    field = episode_field(runner, state) if record is not None else None
+                    out = play_maze(runner, state, args.controller, cap, rng,
+                                    args.temperature, record)
+                    out.update(game="maze", size=size, topology=topology, seed=seed,
+                               shortest=shortest,
+                               efficiency=shortest / out["steps"] if out["solved"] else 0.0)
+                    results["episodes"].append(out)
+                    if record is not None:
+                        traces.append({"game": "maze", "size": size,
+                                       "topology": topology, "seed": seed,
+                                       "walls": sorted(map(list, state.walls)),
+                                       "goal": list(state.goal), "result": out,
+                                       "field": field, "steps": list(record),
+                                       "truncated": record.truncated})
+                    print(f"maze {size:3d} {topology:16s} seed={seed} "
+                          f"solved={out['solved']} steps={out['steps']:5d} "
+                          f"shortest={shortest} collisions={out['collisions']}",
+                          flush=True)
+
+    if args.game in ("snake", "both"):
+        for size in [int(s) for s in args.snake_sizes.split(",")]:
+            for i in range(args.episodes):
+                seed = 610_000 + i * 53 + size * 7
+                state = sk.new_game(size, seed)
+                cap = args.max_steps or default_max_steps("snake", size)
+                record = Recorder(args.trace_max_steps) if args.trace_out else None
+                out = play_snake(runner, state, args.controller, cap, rng,
+                                 args.temperature, record)
+                out.update(game="snake", size=size, seed=seed)
+                results["episodes"].append(out)
+                if record is not None:
+                    traces.append({"game": "snake", "size": size, "seed": seed,
+                                   "result": out, "steps": list(record),
+                                   "truncated": record.truncated})
+                print(f"snake {size:3d} seed={seed} food={out['food']:3d} "
+                      f"steps={out['steps']:4d} alive={out['alive']} "
+                      f"death={out['death']}", flush=True)
+
+    maze_eps = [e for e in results["episodes"] if e["game"] == "maze"]
+    snake_eps = [e for e in results["episodes"] if e["game"] == "snake"]
+    summary = {}
+    if maze_eps:
+        solved = [e for e in maze_eps if e["solved"]]
+        summary["maze"] = {
+            "episodes": len(maze_eps),
+            "solve_rate": len(solved) / len(maze_eps),
+            "mean_steps_when_solved": (sum(e["steps"] for e in solved) / len(solved)
+                                       if solved else None),
+            "mean_efficiency": (sum(e["efficiency"] for e in solved) / len(solved)
+                                if solved else 0.0),
+            "mean_collisions": sum(e["collisions"] for e in maze_eps) / len(maze_eps),
+            "deadlock_rate": sum(e.get("deadlocked", False)
+                                 for e in maze_eps) / len(maze_eps),
+            "mean_distinct_cells": sum(e.get("distinct_cells", 0)
+                                       for e in maze_eps) / len(maze_eps),
+            "by_size": {},
+        }
+        for size in sorted({e["size"] for e in maze_eps}):
+            rows = [e for e in maze_eps if e["size"] == size]
+            ok = [e for e in rows if e["solved"]]
+            summary["maze"]["by_size"][str(size)] = {
+                "episodes": len(rows),
+                "solve_rate": len(ok) / len(rows),
+                "mean_steps": sum(e["steps"] for e in ok) / len(ok) if ok else None,
+                # Over solved episodes only, matching the aggregate above: an
+                # unsolved episode has efficiency 0 by definition, so including
+                # them would make this a second, noisier solve rate rather than
+                # a statement about path length. It is here because the
+                # model-vs-control comparison separates on efficiency and not
+                # on arrival, and that comparison is per size.
+                "mean_efficiency": (sum(e["efficiency"] for e in ok) / len(ok)
+                                    if ok else 0.0),
+                "mean_shortest": sum(e["shortest"] for e in rows) / len(rows)}
+    if snake_eps:
+        summary["snake"] = {
+            "episodes": len(snake_eps),
+            "mean_food": sum(e["food"] for e in snake_eps) / len(snake_eps),
+            "max_food": max(e["food"] for e in snake_eps),
+            "mean_steps": sum(e["steps"] for e in snake_eps) / len(snake_eps),
+            "survival_rate": sum(e["alive"] for e in snake_eps) / len(snake_eps)}
+    results["summary"] = summary
+    print(json.dumps(summary, indent=2))
+    if args.out:
+        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.out).write_text(json.dumps(results, indent=2))
+    if args.trace_out:
+        Path(args.trace_out).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.trace_out).write_text(json.dumps(traces))
+
+
+if __name__ == "__main__":
+    main()

scripts/probe.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""Measure what the planner's field actually encodes.
+
+Fits a ridge probe from the planner's per-cell features to the true BFS
+distance and reports R^2. This is the diagnostic that caught the central
+training bug: with only the sparse decision questions supervising it, the
+recurrence scored R^2 = 0.21 -- it was running, it was differentiable, its
+accuracy numbers looked reasonable, and it was not computing distances.
+
+Also reports the field head's own predictions, which is what the decision
+heads actually read.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+import torch
+
+import envs.maze as mz
+from jevon.grid import bfs_field, encode_maze, pad_boards
+from jevon.inference import resolve_weights
+from jevon.modeling import JevonConfig, JevonModel
+from jevon.planner import default_iterations
+
+
+def ridge_r2(features: torch.Tensor, target: torch.Tensor) -> tuple[float, float]:
+    design = torch.cat([features, torch.ones(len(features), 1)], 1)
+    gram = design.T @ design + 1e-3 * torch.eye(design.shape[1])
+    weights = torch.linalg.lstsq(gram, design.T @ target.unsqueeze(1)).solution
+    pred = (design @ weights).squeeze(1)
+    ss_res = ((pred - target) ** 2).sum()
+    ss_tot = ((target - target.mean()) ** 2).sum()
+    return float(1 - ss_res / ss_tot), float((pred - target).abs().mean())
+
+
+def descent_accuracy(head: torch.Tensor, truth: torch.Tensor) -> float:
+    """Fraction of cells whose lowest-predicted neighbour is a correct step.
+
+    R^2 scores the field's absolute values, but greedy descent only ever
+    compares a cell's four neighbours, so a field can be numerically mediocre
+    and still route perfectly -- or fit well on average and still invert the
+    one comparison that matters.  This is the quantity that predicts solve
+    rate, so it is measured rather than inferred from R^2.
+    """
+    head = head.detach()
+    hits = total = 0
+    h, w = truth.shape
+    for r in range(h):
+        for c in range(w):
+            here = float(truth[r, c])
+            if here <= 0:                      # blocked, unreachable, or the goal
+                continue
+            options = [(rr, cc) for rr, cc in
+                       ((r - 1, c), (r + 1, c), (r, c - 1), (r, c + 1))
+                       if 0 <= rr < h and 0 <= cc < w and truth[rr, cc] >= 0]
+            if not options:
+                continue
+            pick = min(options, key=lambda x: float(head[x[0], x[1]]))
+            # Correct iff that neighbour lies on *a* shortest path.
+            hits += float(truth[pick]) == here - 1
+            total += 1
+    return hits / max(total, 1)
+
+
+def descent_outcomes(head: torch.Tensor, truth: torch.Tensor,
+                     cap_mult: int = 8) -> float:
+    """Fraction of cells from which greedy descent actually reaches the goal.
+
+    Per-step accuracy is not the quantity a controller lives or dies by.  A
+    field that is right 99% of the time but contains one spurious basin traps
+    forever; a field that is right 70% of the time with no basin still arrives,
+    just by a longer route.  Solve rate equals *this* number, so report it next
+    to the per-step figure and let the gap between them speak.
+    """
+    head = head.detach()
+    h, w = truth.shape
+    goal = min(((r, c) for r in range(h) for c in range(w)
+                if float(truth[r, c]) == 0.0), default=None)
+    if goal is None:
+        return 0.0
+    reached = total = 0
+    cap = cap_mult * h * w
+    for r in range(h):
+        for c in range(w):
+            if float(truth[r, c]) < 0:
+                continue
+            total += 1
+            cur, seen = (r, c), set()
+            for _ in range(cap):
+                if cur == goal:
+                    reached += 1
+                    break
+                if cur in seen:
+                    break                       # a cycle: descent never escapes
+                seen.add(cur)
+                options = [(rr, cc) for rr, cc in
+                           ((cur[0] - 1, cur[1]), (cur[0] + 1, cur[1]),
+                            (cur[0], cur[1] - 1), (cur[0], cur[1] + 1))
+                           if 0 <= rr < h and 0 <= cc < w and truth[rr, cc] >= 0]
+                if not options:
+                    break
+                cur = min(options, key=lambda x: float(head[x[0], x[1]]))
+    return reached / max(total, 1)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--checkpoint", default="runs/jevon-final")
+    # None means "prefer balanced.pt", the checkpoint every shipped number
+    # comes from. See jevon.inference.resolve_weights.
+    p.add_argument("--weights", default=None)
+    p.add_argument("--sizes", default="11,21,31,51")
+    p.add_argument("--episodes", type=int, default=4)
+    p.add_argument("--device", default="cpu")
+    p.add_argument("--out", default=None)
+    args = p.parse_args()
+
+    root = Path(args.checkpoint)
+    cfg = JevonConfig(**json.loads((root / "config.json").read_text()))
+    model = JevonModel(cfg)
+    model.load_state_dict(torch.load(resolve_weights(root, args.weights),
+                                     map_location="cpu"))
+    model.eval().to(args.device)
+
+    report = {}
+    print(f"{'size':>5s} {'cells':>7s} {'probe R2':>9s} {'probe MAE':>10s} "
+          f"{'head R2':>8s} {'descent':>8s} {'reach':>7s} "
+          f"{'diameter':>9s} {'T':>6s}")
+    for size in [int(s) for s in args.sizes.split(",")]:
+        feats, heads, dists, descents, reaches = [], [], [], [], []
+        diameter = 0
+        steps = default_iterations(size)
+        with torch.no_grad():
+            for i in range(args.episodes):
+                topology = mz.TOPOLOGIES[i % len(mz.TOPOLOGIES)]
+                # Seeds ending in 9 are the held-out test split.
+                state = mz.generate_maze(size, topology, 70_009 + i * 10)
+                board, _, target = encode_maze(state)
+                boards, passable, _ = pad_boards([board])
+                cells = model.encode_boards(boards.to(args.device),
+                                            passable.to(args.device), steps, 0)
+                head = model.predict_field(
+                    cells, boards.to(args.device),
+                    passable.to(args.device), iterations=steps)[0, 0]
+                truth = bfs_field(board, target)
+                mask = truth >= 0
+                diameter = max(diameter, int(truth.max()))
+                descents.append(descent_accuracy(head.cpu(), truth))
+                reaches.append(descent_outcomes(head.cpu(), truth))
+                feats.append(cells[0, :, mask].T.cpu())
+                heads.append(head[mask].cpu())
+                dists.append(truth[mask])
+        features = torch.cat(feats)
+        truth = torch.cat(dists)
+        r2, mae = ridge_r2(features, truth)
+        head_r2, _ = ridge_r2(torch.cat(heads).unsqueeze(1), truth)
+        descent = sum(descents) / max(len(descents), 1)
+        reach = sum(reaches) / max(len(reaches), 1)
+        report[size] = {"cells": len(truth), "probe_r2": r2, "probe_mae": mae,
+                        "head_r2": head_r2, "descent_acc": descent,
+                        "reach_rate": reach,
+                        "diameter": diameter, "iterations": steps}
+        print(f"{size:5d} {len(truth):7d} {r2:9.4f} {mae:10.2f} {head_r2:8.4f} "
+              f"{descent:8.4f} {reach:7.3f} {diameter:9d} {steps:6d}")
+
+    if args.out:
+        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.out).write_text(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()