Q2: Pyodide is 3.14 and the pin is 3.15, so how do we handle the delta

[tamnd]

Pyodide 314 is CPython 3.14. The pin is 3.15. Every tier 0 experiment therefore runs one minor version behind the material, and sometimes that changes the bytecode the reader sees. A reader who is told the answer is one thing and watches their browser print another loses trust in the whole project, and they are right to.

Exit criterion. A version delta mechanism in the notebook lint, and a documented policy in the authoring guide.

The work

• A per cell annotation declaring whether an observation is version sensitive
• A CI check that runs every tier 0 cell on both 3.14 and 3.15 natively and flags any whose normalized output differs
• A visible note on differing cells saying what the reader is seeing and what 3.15 does instead
• A policy for what to do when a lesson's central observation is one of the differing ones, since a note is not enough in that case
• Track Pyodide's 3.15 release and bump as soon as it exists

Note

The check is worth building even after Pyodide catches up, because the same machinery is what tells us which cells are version sensitive when the pin moves to 3.16.

[tamnd]

Some evidence, now that #34 has landed and the test suite runs on both 3.15.0rc1 and 3.14.

Three differences between the pin and the browser tier version are known and asserted from both sides rather than described in a comment.

The small integer cache upper bound is 256 on 3.14 and 1024 on 3.15, which is #33 and which breaks the 257 is 257 example every tutorial uses.

RESUME carries no inline cache entry on 3.14 and one on 3.15. It is the first instruction of almost every code object, so it occupies two bytes on one and four on the other, and any prose that walks offsets by hand from a 3.14 disassembly is off by two from its second instruction onward. This one matters more than it looks, because offset arithmetic is exactly the kind of thing a lesson shows worked out by hand to build the reader's confidence.

LOAD_FAST_BORROW exists on both, and it is why sys.getrefcount stopped being reliably one too high in 3.14. Passing a local costs nothing, passing a global costs one. Same on both versions, so it is not a delta, but it is the reason a refcount helper cannot use a fixed correction.

What this suggests for the handling rule. Two of the three are the same shape: a number in the prose that is right on one version and wrong on the other, with nothing in the output to tell the reader which they are looking at. Neither is a case where the lesson cannot run in the browser, so the browser only promise survives both. What does not survive is prose that states a number.

So the rule that seems to fall out is that a lesson never writes a version dependent number in prose. It prints it from a probe, and the probe is what the surrounding sentence refers to. pyxray.obj.small_int_range() is the first instance of that pattern and it works: the cell shows the reader the bound on their interpreter and the paragraph talks about the bound rather than about 256.

Where a number genuinely has to be in the prose, the banner at the top of the lesson already says which interpreter is running, and the sentence can name the version it is describing. That is a weaker guarantee and it should be rare.

Still open: whether there is a class of lesson where the delta is structural rather than numeric, in which case printing a probe does not save it. The front end lessons are the place to look, because that is where bytecode differences are largest. T05 will tell us.

[tamnd]

Merged #72, which is the first half of this.

nbversion record runs every lesson on one interpreter and writes a small JSON file per notebook: cell id to normalised output. nbversion compare reads two of those directories and gives each cell one of four verdicts. declared means the cell differs and the notebook says so. undeclared means it differs and nothing says so. stale means the cell carries a note and the two interpreters now agree. missing means the two runs saw different sets of cells. The last three fail.

stale is the one that made this worth building properly. A note that has stopped being true is worse than no note, because 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.

The declaration lives in the cell's own metadata under cpython_internals.differs, written by passing differs= to lesson.code. It is on the cell rather than in a list somewhere else, so it survives being moved and disappears when the cell is deleted.

The normaliser is deliberately timid. It only rewrites addresses, absolute paths, temporary file names and durations, because those are the things that vary between two runs of the same interpreter. An opcode name, a size, a byte count and an offset all survive untouched, since those are exactly what we are looking for. There are tests asserting it leaves them alone.

just versions runs the whole thing locally. CONTRIBUTING.md gained a section on the 3.14 and 3.15 problem, and the definition of done for a lesson gained an item.

Checking two boxes: the per cell annotation mechanism, and the policy for a lesson whose central observation is one of the differing ones. The CI check and the visible notes are in the follow up, which annotates all twelve lessons.

[tamnd]

Merged #73, which annotates all twelve lessons and adds the CI job.

nbversion compare now reports 53 declared cells and 11 noted, with nothing undeclared, stale or missing. The versions job hangs off the notebooks matrix: each leg records what its interpreter printed and uploads it, and one job downloads both and compares. It is gating.

Four differences account for most of the 64. On 3.15 the implicit return None at the end of a module is a LOAD_COMMON_CONSTANT and None is not in co_consts at all, where on 3.14 it is a LOAD_CONST and None is in the table. RESUME and GET_ITER carry an inline cache on 3.15 and not on 3.14, which moves every offset in every listing by two to four. The shared range of small integers stops at 1024 on 3.15 and 256 on 3.14. And several cells count files in the reader's own standard library. Their wording lives in nbbuild.notes, so a reader who meets one in T05 and again in T10 gets the same words both times.

The first run of the new job found two stale notes that are not stale, which is the most useful thing it could have done. On a runner both interpreters come from the same builder, so the cell that prints your build's configure flags prints the same thing twice and the check called the note stale. On a laptop with a framework Python next to a uv-managed one it differs, and the note is right.

So the note split in two. differs= is a claim about the language, which two recordings can check and which fails when it stops being true. varies= is a claim about the reader's machine, which they cannot, because whether two runs agree about a machine difference depends on which two machines made them. Ten cells moved across. To a reader they look identical.

Three judgement calls worth recording. T08's central observation is the small integer cache, which is one of the differing ones, so the lesson measures the range rather than asserting a number and both answers are correct on the interpreter that produced them. T07's stack chain prints line numbers from asyncio and Jupyter, which belong to whatever is running the notebook, so the note points at the bottom of the list. And sys.monitoring allows 17 local events on 3.15 and 12 on 3.14, which T07 already discussed in prose before this check existed.

That closes the annotation, the CI check and the visible note. The only box left here is tracking Pyodide's 3.15 release, which is not ours to schedule, so this issue stays open on that one item.