Close extension API gaps for operators defined outside HNDL

[martyn]

Closes three gaps found by writing a host package against the public API. Each one is tested in tests/test_extension_api.py the way an external package would use it: public imports only, operators registered on Registry.builtins().

1. ops follows the capture's registry

Before: network_from_callable(fn, registry=reg) with ops.my_op() inside fn failed with E_OPERATOR: Unknown operator alias, because the global ops always looked aliases up in a fresh Registry.builtins().

Design (src/hndl/capture.py, OperatorNamespace):

• Global ops, inside a capture: each alias is checked against capture.registry when the attribute is read, so a typo still fails where it is written. The returned factory looks the alias up again every time it is called, so a factory read outside a capture (for example linear = ops.linear at module level) follows whichever capture it is called in.
• Global ops, outside a capture: aliases are still checked against the built-in catalog, and calling a factory still fails with E_CAPTURE. Both match current behaviour.
• registry.ops: unchanged. It is bound to its registry and takes the declaration when the attribute is read.
• Capture.emit: now requires the capture's registry to hold the same declaration object (_identities.get(op.key) is op). It used to call by_identity and then compare .key with itself, a check that could never fail. The outcomes:
  • Mixing ops and reg.ops in one capture works, because they resolve to the same declaration.
  • reg2.ops.linear inside a capture of reg is allowed. Every Registry.builtins() shares the built-in declaration objects, so it binds exactly what reg would. The docstring and SPEC now say this.
  • reg2.ops.my_op inside a capture of reg fails with E_CAPTURE in two cases: reg lacks the identity, or reg declares the same identity with a different class. The message names the operator and says to pass the declaring registry, or to call ops.<alias> when the capture's registry has that alias.

Behaviour change: a foreign factory whose identity is missing used to fail with E_STATE_VERSION from by_identity. It now fails with E_CAPTURE. tests/test_capture.py::test_registry_factories_require_selected_exact_identity is updated, and the CHANGELOG records the change.

2. Public hndl.relations

• src/hndl/relations.py holds conv_output, conv_transpose_output, spatial, elementwise_join and broadcast, now with docstrings. It is torch-free.
• It adds four small helpers that a custom strided op needs for backward inference:
  • conv_input_range: the interval inverse of conv_output.
  • conv_transpose_input: the exact inverse of conv_transpose_output, or None if no input maps there.
  • conv_axis and conv_transpose_axis: relate one axis of x and out, in both directions.
• spatial() and conv1d are now built from these per-axis helpers instead of repeating the inverse arithmetic inline.
• spatial() rejects an unknown kind with E_REGISTRY instead of silently treating it as a forward convolution.
• conv1d's inverse error now says "extent" instead of "length". No test matched the old text.
• The built-ins (conv, deconv, conv1d, broadcast_add, broadcast_mul) import from ..relations. hndl/operators/_relations.py is a re-export shim, so existing imports of the private path keep working.
• docs/ADDING_OPERATORS.md has a new "Shared relations" section: a table of the helpers and a complete decimate operator whose relation is conv_axis(s, 2, kernel=1, stride=factor). I ran that example and confirmed three behaviours: it passes check_operator, it runs through ops in network_from_callable, and backward inference reports E_AMBIGUOUS for the 15-or-16 interval as the text says.

3. Public hndl.testing

src/hndl/testing.py is the former test_all_operators logic, now taking a registry argument.

Function	What it checks
check_declaration(registry, op)	Summary, docstring, category, help text on every argument, at least one example, and shape_text for a relation.
check_round_trip(registry, op, example)	The config and a native replay through registry.ops give the same digest. JSON round trip. Every arg is recorded except an Arg(since=...) left at its default.
check_build_and_run(registry, op, example, device=, dtype=)	Parameter dtype. repr draws no randomness. parameter_counts and receipt bytes. Output shape, dtype and finiteness. Finite input gradient. A same-seed rebuild reproduces the output.
check_reference(registry, op, example, device=)	Outputs and input gradients match reference=. Returns False when none is declared.
check_operator(registry, alias, devices=None, dtypes=None, network=False)	Runs all of the above for every example and device: float32 everywhere, plus float16/bfloat16 on CUDA by default (what the built-in suite runs).
example_params, operator_params	pytest.params with the existing alias-index ids and the network mark.
example_cases, example_contract, example_input, available_devices	Building blocks.

• Checks raise plain AssertionError, not bare assert, so they survive python -O and work outside pytest.
• pytest is imported only inside example_params/operator_params. hndl/__init__ does not import hndl.testing, so import hndl pulls in neither pytest nor torch through it. A subprocess test asserts this.
• tests/operators/test_all_operators.py is now thin wrappers over hndl.testing. It keeps the same parametrization and test ids, including the CUDA reduced-precision test. tests/operators/conftest.py keeps only DEVICES and the device fixture.
• The reduced-precision path now also runs the parameter-count, receipt, repr and rebuild-determinism checks that float32 already ran, so one function covers both. All pass on CUDA locally.
• ADDING_OPERATORS.md "Custom operators outside the package" gains three subsections: calling through ops, testing with hndl.testing, and evolving with Arg(since=...).

Docs

• SPEC: the from hndl import ops ... fixed version bindings paragraph is rewritten. The identity rules cover foreign factories. The relations sentence points at hndl.relations. There is a new paragraph on hndl.testing, and two acceptance-gate rows are extended.
• README: the custom-operator section says ops.my_silu() works with the registry passed in, and mentions hndl.relations and hndl.testing.check_operator.
• CHANGELOG: new ## Unreleased section.

Tests

• PYTHONPATH=src python -m pytest -q -m "not network and not benchmark": 3669 passed, 80 skipped (reference-less operators), 53 deselected. This ran on a machine with CUDA, so the float16/bfloat16 harness ran too.
• ruff check src tests examples: clean.
• PYTHONPATH=src python -m hndl.docs --check: current. No operator declarations changed, so the docs were not regenerated.
• New tests/test_extension_api.py (24 tests) covers:
  • ops against a custom registry in resolve_callable and network_from_callable, with equal digests across config, ops and reg.ops.
  • Mixing ops and reg.ops in one capture.
  • ops outside a capture, and late binding of a factory read there.
  • An empty Registry() capture, where ops.linear is E_OPERATOR.
  • Nested captures with different registries.
  • Foreign factories: missing identity and different implementation are E_CAPTURE; a shared built-in is allowed.
  • Conv and transpose-conv arithmetic against torch, and the inverse properties.
  • Forward, backward and ambiguous inference through a host operator's conv_axis relation.
  • The shim re-export.
  • check_operator on a host operator that has an Arg(since=...).
  • A per-example parametrized harness.
  • Harness failure messages for a wrong reference, an example that doesn't use the op, and missing examples.
  • pytest not being imported.

Tradeoffs and open questions

• Error code change: E_STATE_VERSION becomes E_CAPTURE for foreign factories. E_STATE_VERSION describes restoring a plan, not authoring, and the old code path already intended E_CAPTURE. Anyone matching on the old code will see a different one.
• Same identity, different class: this is now rejected in capture. It was accepted before, because only the identity string was compared. The old behaviour let a capture record one class's arguments and resolve them against another's declaration.
• Outside a capture, ops only knows the built-ins. my_op = ops.my_op at module import raises E_OPERATOR; reading it inside the function, or using reg.ops, works. Validating against nothing would lose early typo detection for the common case.
• Shim kept: hndl.operators._relations is kept as a re-export rather than deleted. It is cheap, and code that imported the private path keeps working. It could be removed in a later minor release.
• Scope of the new relation helpers: _pooling.py has its own window arithmetic (dilation 1, zero-stride normalization) and is left untouched to keep this PR scoped.
• example_params needs the network mark registered: a host package using it must register that mark in its pytest config, or pytest warns. The docs say so.

🤖 Generated with Claude Code

[martyn]

Review follow-up (03627a5), all findings fixed:

• should-fix, harness failure paths untested: fixed. test_harness_reports_a_broken_operator now covers every operator-caused failure with a broken module or declaration and asserts the exact message: non-finite output, NaN input gradient, nondeterministic rebuild, parameter_counts mismatch, build-receipt mismatch, wrong parameter dtype, reference output/count/gradient mismatches, trailing-colon summary, missing own docstring, and missing shape_text. The checks that guard HNDL itself (repr drawing RNG, repr not naming the operator, replay digest mismatch, JSON round-trip change, Arg(since=...) default leaking into the plan) are tested by patching the resolver, repr and replay. Making check_build_and_run a no-op now fails 8 tests. There is no negative test for the help-text or category checks: Arg and registration already reject both, so an operator can't get past them. A wrong output shape is caught first by HNDL's own runtime check (E_RUNTIME). That path is tested and documented.
  • The new tests also found two harness bugs, both fixed. check_reference crashed with a RuntimeError when the reference dropped the gradient the module carries. check_declaration accepted a docstring inherited from nn.Module.
• should-fix, README check_operator on a declaration with no Example: fixed. my_silu now declares an Example, the README says the harness needs one, and a new test runs the README block through check_operator.
• nit, devices="cpu": fixed. devices and dtypes each take a single name or a list.
• nit, inconsistent exception for a foreign declaration: fixed. A declaration that isn't registered now fails with AssertionError: ... is not registered in this registry.
• nit, misleading E_CAPTURE hint: fixed. The hint suggests ops.<alias> only when that alias binds the same identity. Otherwise it names the operator the alias binds in the capture's registry.
• nit, raw IndexError from conv_axis: fixed. conv_axis and conv_transpose_axis now fail with E_CONSTRAINT ("Port x has rank 2, which has no axis 2").

Checks: full suite passed (3688 passed, 80 skipped, 53 deselected). ruff check is clean and hndl.docs --check passes.

🤖 Generated with Claude Code