Detect cleared parameters on the fast path and tighten the parity tolerance

[martyn]

Two follow-ups to #83 (contracts checked once per input signature).

1. Hookless registered-state edits are caught on the next call

After the first validated call, del module.weight, linear.bias = None, and direct writes to _parameters/_buffers/_modules went unnoticed on the fast path, because PyTorch's global registration hooks don't fire for them. A layer could run without its bias until a new signature, a .to(), or a failing layer forced a full check.

Design (src/hndl/torch.py)

GraphModule._record_stores() builds a record whenever the registered state has just been found to match the build. That happens at construction, in __deepcopy__ for the clone's own modules, and once at the end of each _validate. _execute compares the record with the live dictionaries on every call, in C:

• Submodule dicts and empty _parameters/_buffers are compared as same == copies, a tuple of dict copies, with identity first. This catches a submodule added, removed, set to None or replaced, and any entry added to an empty dict. The copies hold only submodules and empty dicts.
• Non-empty _parameters/_buffers are compared by shape: each dict's length, then whether each value is None (map(operator.is_, chain(views), repeat(None))). This catches an entry removed, added or set to None without holding or comparing any tensor.

A mismatch goes down the existing _validate path, the same way a registration-hook bump does, and raises the usual E_RUNTIME naming the node and the change, for example registered state of linear 'hidden' no longer matches the build: parameter 'nodes.n_hidden.bias' was set to None.

A tensor swapped in under a registered name is not a change. It stays on the unchecked path, like an in-place update. So torch.func.functional_call (grad, vmap, ensembles, hypernetworks) costs what it cost on develop, no swapped-in tensor is kept alive, and copy.deepcopy after a functional call works for non-leaf, grad-tracking and vmap-batched tensors. __deepcopy__ skips the record and rebuilds it.

Not detected, and documented in SPEC §11, IMPLEMENTATION.md, the GraphModule docstring and the CHANGELOG:

• a whole dict replaced (module._parameters = {...});
• a reorder;
• one name removed and another added in the same _parameters/_buffers between two calls;
• a submodule replaced by one whose __eq__ says it equals the old one.

torch.compile: the compiling branch returns before the comparison, so this is unchanged.

Cost

The check alone, measured in isolation:

graph	dicts by identity	dicts by shape	per call
3-node test MLP	13	2	~0.57 us
5-node benchmark MLP	18	3	~0.7 us
transformer_block(4)	33	9	~1.3 us

This costs more than the first version's single stores == copies (~0.2 / 0.5 us). That version compared tensors with ==, which is what made functional_call 160x slower with a large first parameter. No C-level comparison of a tensor against a record avoids both holding the tensor and calling Tensor.__eq__ on a swap, so the tensor dicts pay for the map/chain iteration instead.

functional_call, alternating two parameter dicts, loaded machine: develop / this PR

• MLP: 77 / 102 us
• embedding(50000, 512) first: 84 / 87 us
• transformer block: 617 / 525 us

These are within noise. The first version of this PR measured 34,000 us for the embedding case.

2. Parity tolerance 2.0x -> 1.5x

_compare now times each side in 10 interleaved rounds, alternating which side goes first, and compares the fastest round's median on each side, instead of one sequential mean each. Twelve runs at load average 3-7:

case	ratio range	tolerance
mlp (batch 256)	1.02x – 1.10x	1.5x
conv_stack (batch 16)	0.60x – 1.58x	2.0x
transformer_block (batch 8)	1.06x – 1.22x	1.5x

With 20 extra busy-looping processes (load average 6-17), the MLP measured 0.95-1.06x and the transformer 1.16-1.38x. A single-thread trial put the transformer at 1.49x. The conv case is almost all arithmetic, and its ratio swings from process to process whatever the timing method, so it keeps 2.0x as a gross-regression check. The test docstring records all of this, including the 1.51x (MLP) and 2.12x (conv) that sequential timing gave under load.

Checks

• PYTHONPATH=src python -m pytest -q -m "not network and not benchmark": 3702 passed, 80 skipped
• ruff check src tests examples: clean
• PYTHONPATH=src python -m hndl.docs --check: current

🤖 Generated with Claude Code

[martyn]

Review findings, addressed in b3f74b8 (squashed as 0ac014f):

Fixed

• Blocker: deepcopy after functional_call. __deepcopy__ now skips _stores and rebuilds it. The record also no longer holds any tensor. New regression test test_deepcopy_after_functional_call[plain|grad|vmap].
• Blocker: functional_call slowdown. Non-empty _parameters/_buffers are now compared by length and which values are None, never with Tensor.__eq__. A same-name swap is no longer a change, so functional_call stays on the unchecked path. With embedding(50000, 512) first, a call alternating two parameter dicts takes 87 us, against 84 us on develop and 34 ms before this fix. _validate records the stores once per call.
• Should-fix: retention of generated weights. The record holds no tensors. New test test_functional_call_keeps_no_generated_weights_alive.
• Should-fix: parity tolerance headroom.
  • Each side is now timed in 10 interleaved rounds, and the ratio compares the fastest medians.
  • The MLP and transformer keep 1.5x.
  • The arithmetic-bound conv case keeps 2.0x. Its ratio swung from 0.60x to 1.58x even at load 3-7.
  • The docstring records the loaded-machine results honestly, including the 1.49x, 1.51x and 2.12x runs.
• Should-fix: CHANGELOG conflict. Rebased on develop. Both bullets now sit under the single ## Unreleased heading.
• Should-fix: SPEC/docs overclaim. SPEC §11, IMPLEMENTATION.md, the GraphModule docstring and the CHANGELOG now say "removing an entry, setting it to None, adding one, or replacing a submodule". They also list what is not detected: a same-name tensor swap, a whole-dict replacement, a reorder, a remove-plus-add in the same dict, and an equal-comparing submodule.
• Nit: the functional_call test proved nothing. Replaced by test_a_tensor_swapped_in_under_its_name_stays_on_the_unchecked_path, which uses _count_checks, plus the deepcopy and retention tests.
• Nit: inconsistent cost figures. One set of numbers is now used everywhere: ~0.7 us per call for the five-node MLP and ~1.3 us for the transformer block.

Declined

• None. One partial: the reviewer suggested keeping swap detection with a port re-check but skipping the state check. I didn't do that, because any detection of a swap needs either an elementwise compare or a held reference. Swaps are therefore undetected, which is develop's behaviour, and this is documented.

🤖 Generated with Claude Code