Add nbversion, which finds the cells that differ between 3.14 and 3.15

[tamnd]

The lessons are written against the pinned 3.15. Every reader who clicks a Colab badge is on 3.14, and so is every widget that runs in the browser, because Pyodide has not shipped 3.15 yet. Most cells do not notice. Some do, and those are the dangerous ones: the cell still runs and still prints something that looks right.

The one that started this is LOAD_COMMON_CONSTANT. On 3.15 a function that falls off the end loads None with that instruction and co_consts does not contain None at all. On 3.14 it is a LOAD_CONST and None is in the table. T01 says "look, co_consts is (6,)" and a reader in Colab sees (6, None), with nothing on the page to tell them which of the two of them is wrong.

This is the first half of #2: the mechanism, not the annotations.

What is here

nbversion record runs every lesson on the interpreter it is invoked with and writes one small JSON file per notebook, mapping cell id to normalised output. It is not an executed notebook, because the diff of two executed notebooks is mostly metadata and unreadable. Cells are keyed by id rather than position, so inserting a cell does not report every cell after it as changed.

nbversion compare reads two of those directories and gives one of four verdicts per cell.

verdict	what it means	fails
declared	the cell differs and the notebook says so	no
undeclared	the cell differs and nothing says so	yes
stale	the cell carries a note and the two interpreters now agree	yes
missing	the two runs saw different sets of cells	yes

Both directions are checked on purpose. stale is the one that is tempting to leave out, and a note that has stopped being true is worse than no note at all: a reader who checks one against their own interpreter, finds it wrong, and decides the notes are decoration has been misled by the thing that was meant to help them.

Declaring a difference is one keyword in the lesson's build.py:

lesson.code(source, differs="On 3.14 the last instruction is LOAD_CONST rather than LOAD_COMMON_CONSTANT, and None is in co_consts.")

That writes the sentence into the cell's own metadata, under a cpython_internals namespace so it cannot collide with Jupyter or Colab, and adds a markdown cell underneath so a reader sees it without opening the metadata. The note lives on the cell rather than in a list somewhere else in the repository, because a list drifts: delete the cell and the entry stays behind. quiet=True skips the visible half, for the lessons where one paragraph near the top already explains a difference that a dozen cells then show.

The normaliser

This is the part the whole tool rests on, so it is deliberately timid. Every substitution throws away a real difference, and the differences worth finding are exactly the ones a careless normaliser sweeps up. The rule is that a pattern is normalised only when it varies between two runs of the same interpreter, which makes it noise rather than a version difference. That is addresses, absolute paths, temporary file names and durations, and nothing else. Opcode names, sizes, byte counts and jump offsets all survive, because those are the point. There are tests asserting each of those is left alone.

Errors keep the exception type and the message and lose the traceback, because a lesson that raises on purpose cares about which exception it got, not about how many frames were on the stack.

What it found

Running it locally right now, against the twelve committed lessons:

12 notebook(s) compared: 64 undeclared

Twelve of those are the build banner, which prints the version and is supposed to differ. The rest are real, and several are worth a paragraph of prose rather than a one line note:

• LOAD_COMMON_CONSTANT instead of LOAD_CONST for a trailing None, which also changes co_consts and the byte count of every code object in T01, T05, T06 and T10.
• 3.15 gives RESUME and GET_ITER a cache entry, so every offset in T06 and T07 is 2 to 4 higher than on 3.14, and the jump arithmetic worked through in T06 comes out different.
• The small integer cache is -5 to 1024 on 3.15 and -5 to 256 on 3.14, which is the central observation of two cells in T08.
• sys.monitoring has 17 events on 3.15 and 12 on 3.14.

None of that is annotated in this PR. Adding the notes changes every lesson and renumbers cells, so it is its own change, along with the CI job that makes the check gating.

Policy

CONTRIBUTING.md gets a section saying what to do when a cell differs, including the case the issue asks about: when the differing cell is the lesson's central observation, a note is not enough. Either the lesson gets a short section explaining both versions, because the difference is itself worth teaching, or the example changes to one that behaves the same on both. LOAD_COMMON_CONSTANT is interesting and gets explained. A line number inside asyncio is not, and the cell should stop printing it.

Checking

just versions   # record on both interpreters, then compare
just test       # 77 new tests, none of which need two interpreters

just versions is not part of just check, because it executes every notebook twice and takes minutes. CI will get it for free in the next change, since the notebooks job already runs on both versions and only has to keep its recording.