chore(release): 0.16.8 — NR-A015 execute-capture wiring + AUTH-01 transport-error reclassification + HEART-01 public wrapper

[maltsev-dev]

Summary

Patch release 0.16.8 — closes the SDK-side leg of NR-A015 on the /execute require_approval arm, reclassifies transport-vs-auth errors on the runtime auth path, and adds a public Runtime.heartbeat(chain_id) wrapper. Three independent fixes plus tooling cleanup.

Wire shape: pure reliability, no wire-format change on /gate, /execute, /track, /cancel. Bytes are byte-identical to 0.16.7. Backend v3.79+ is required to land the /execute reservation_id echo that closes NR-A015; pre-v3.79 backends silently fall through the capture (helper is fail-OPEN).

Fixed

• DEF-EXECUTE-CAPTURE-WIRING — runtime.execute() now calls _capture_server_minted_execution_id(result) immediately after _transport.execute(...) and syncs the re-fire kwargs dict to the captured id (src/nullrun/runtime.py, 5f96b2e, tests/test_2026_09_11_execute_capture_wires_execution_id.py). The post-approval re-fire sends the freshly-minted execution_id stamped on the approval row, so consume_approved's WHERE execution_id = $3 predicate matches. Closes the SDK-side leg of NR-A015 on the /execute require_approval arm (backend v3.79+ lands the matching reservation_id echo).

• DEF-WAIT-FOR-APPROVAL-EXEC-ID — both _wait_for_approval_resolution call-sites (check_workflow_budget + runtime.execute) now pass the captured server-minted execution_id from the contextvar (with the prior org_id/workflow_id sentinel as fallback) instead of the workflow_id sentinel (src/nullrun/runtime.py, 5f96b2e). Diagnostic improvement only — the WS handler matches on approval_id — but log lines + entry metadata now reflect the server-minted id.

• DEF-CHAIN-END-REQUIRED-FIELDS — Runtime.chain_end forwards self.organization_id (from _authenticate) and the trace_id contextvar; action_digest is emitted as the NoImpact sentinel so the Phase-1+ version-gate at backend::gate::gate.rs:148 (proto>=3) accepts the control-plane call without triggering LEGACY_GRANT_REJECTED (src/nullrun/runtime.py, ebac334). Existing TestChainEndEndpoint test updated to pass organization_id; three new tests pin the full GateRequest body, the NullRunConfigError on missing organization_id, and trace_id passthrough.

• DEF-AUTH-01 — NullRunRuntime.__init__ auth path no longer reclassifies httpx.RequestError as NullRunAuthenticationError (src/nullrun/runtime.py + src/nullrun/transport.py, dcf11c8). The defensive duplicate arm in __init__ is removed; the real arm in _authenticate now raises NullRunTransportError(source=NETWORK_ERROR, endpoint="auth") — matching the convention Transport.heartbeat uses for the same condition on /heartbeat. Two existing tests (test_authenticate_network_error_raises in test_runtime.py and test_runtime_branches.py) were locking in the old misclassification and have been updated to assert the correct class.

  Back-compat: NullRunTransportError and NullRunAuthenticationError are siblings under NullRunInfrastructureError, so the parent class still catches both. Cookbook code that branches on except NullRunAuthenticationError: for retry needs to also catch NullRunTransportError.

Added

• DEF-HEART-01 — NullRunRuntime.heartbeat(chain_id) public method (src/nullrun/runtime.py, dcf11c8, tests/test_2026_09_11_auth_heartbeat_sweep.py). Thin forwarder to Transport.heartbeat mirroring the chain_end / cancel_execution pattern. Use for single-shot chain TTL extensions; Runtime.ping_chain() remains the wall-clock scheduler variant. Pure addition — no existing API surface changes.

Tooling

• 640ede2 chore(release): ruff cleanups (bundled into the release commit). F811 dedupe — TransportErrorSource was imported from both nullrun.breaker.exceptions and nullrun.transport (same class re-exported); removed the redundant clause. Two I001 multi-line import blocks (tests/test_runtime.py:973 and src/nullrun/transport.py:2159) re-formatted to parenthesised layout.

Compatibility

Pure reliability fixes — no wire-format change on /gate, /execute, /track, /cancel. Bytes byte-identical to 0.16.7. Backend v3.79+ required for the NR-A015 wire contract (the reservation_id echo is the v3.79+ field); pre-v3.79 backends silently fall through the capture (helper is fail-OPEN on malformed values), preserving pre-fix behaviour for un-deployed backends.

Verification

Check	Result
ruff check src tests	All checks passed
mypy src/nullrun	Success: no issues found in 37 source files
pytest -q	1796 passed, 4 skipped in 107.2s (vs 1784 baseline 0.16.7 — +12 new tests added by this release)
Scratch files in git diff origin/master..HEAD --stat	clean (none — dist_local/, *.defect* absent)
nullrun.__version__	0.16.8
Wire-format compatibility	unchanged from 0.16.7

Commits included

640ede2 chore(release): 0.16.8 — NR-A015 execute-capture wiring + AUTH-01 transport-error reclassification + HEART-01 public wrapper
2badf01 fix(sdk): AUTH-01 transport-error reclassification + HEART-01 public wrapper
6f28d0d fix(sdk): chain_end wire shape — populate required GateRequest fields
517b7c2 fix(sdk): DEF-EXECUTE-CAPTURE-WIRING — wire-shape NR-A015 closure on /execute arm

After merge to master, tag v0.16.8 will be created on the squash-merge commit, which triggers .github/workflows/publish.yml → PyPI Trusted Publishing + GitHub Release (auto-notes, wheel + sdist attached).

[codecov]

Codecov Report

❌ Patch coverage is 78.94737% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/nullrun/runtime.py	71.42%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!