Checks & lighting

v0.24.0 release

The check-and-light loop, explorer trail, and capture below all ship in the verified v0.24.0 release.

Why checks exist

Reading an explanation is the weakest form of learning. Codemble makes you prove understanding with short active checks before a region lights up.

Exploring earns something too, and it is deliberately something else. Flying to a system charts it: its routes stay drawn and the star chart counts it. Only a passed check turns it amber. Being somewhere and understanding it are different claims, and the two are kept apart so that neither can be mistaken for the other.

Where questions come from

Every check is generated from your code’s real graph, so the answer is always verifiably correct:

• “Which structures does main() call directly?” — from certain call edges
• “Which files import utils?” — from import edges
• “If you deleted foo(), what would break?” — from its callers
• “Where does execution start?” — from the entrypoint

Questions and answers are deterministic in v1. The check service uses exactly four parser-owned evidence families:

• every certain direct project call from one parser-owned structure
• direct project imports
• direct callers that depend on a structure
• parser-ranked execution entrypoint

The provider is not called to phrase, score, or explain a check. The response sent to the browser withholds the answer; submission is compared against the immutable generated option IDs. A correct answer is confirmed with the graph-owned answer and its real file:line evidence; a wrong one is not, so a second attempt cannot simply replay what the screen just showed. A check that cannot be derived with certainty is not offered.

Call checks deliberately make no execution-order claim. A source line can hold nested calls, and textual order is not Python evaluation order. When the graph proves several direct targets, all of them are required answers; the question is omitted unless the graph also supplies a real non-answer. v0.24.0 gives this contract a new deterministic check schema, so stale question IDs are refused. Saved amber understanding remains keyed to file hashes and is not silently retested or erased.

Lighting rules

Full-size product screen · drag, swipe, or use arrow keys to inspect the interface.

• Pass a region’s checks → its stars light permanently. Back at galaxy level that system plays a 1.2-second nebula dawn — amber washing out through its halo and fog and receding. The lit state is saved before the animation runs, so the dawn marks a fact rather than delivering it, and prefers-reduced-motion skips straight to the finished lit state.
• Progress is saved locally and survives restarts.
• Edit a file → only that region re-dims. Understanding is re-earned where the code actually changed, never globally revoked.

Progress lives in a project-keyed JSON record under ~/.codemble/progress and is written only after every offered check in the region passes. Each region is bound to a deterministic signature of its current parser file hashes. On the next run, matching regions light and changed regions stay dim; no background watcher or network service is involved.

Mutations are serialized across app threads and Codemble processes before the read/modify/replace sequence begins. Project mode and the learner-wide default are two files: ordinary second-write failures restore the project value, while an outcome that cannot confirm its own rollback is reported as uncertain and requires a reload. The pair is not claimed to be crash-atomic.

Right answers say so — wrong ones send you back to the code

A correct answer is confirmed in place — “Correct. That answer is fixed by the parser graph.” — along with the answer and the file:line evidence behind it, before the next question loads.

A wrong answer says only “Not yet. Re-read the relationship in your own code and try again.” It withholds both the answer and the citations, because for a question like which of your files imports this one the evidence lines are the answer. You can retry as often as you like; what you cannot do is light a region with an answer Codemble just handed you.

Why a region can stay dim forever

Every question Codemble asks is answered by the parser graph, and every question must offer at least one wrong option. A region with no certain relationship gives Codemble nothing to build a question from, so it stays dim and says so. Lighting it anyway would mean the amber said something untrue about what you understand. Import that module somewhere, or call something inside it, and its checks appear.

Starting a project over

The star chart has a Clear this project’s progress control behind a confirmation. It forgets both halves of your record for the project you have open — the understood regions and the systems you explored — and nothing else: progress is stored per project in ~/.codemble/progress/, and other projects keep theirs. Your Easy/Expert preference survives the reset.