feat(observability): Layer-2 on_error hooks, Layer-3 status() introspection

[maltsev-dev]

Summary

Builds on the Layer-1 structured exception hierarchy from
#31. Three deliverables: a nullrun.observability package,
two new nullrun.* public API entry points, and per-error-code
docs.

What lands in this PR

1. nullrun.observability package (was observability.py)

File	Responsibility
__init__.py	Public re-exports; previous single-file surface preserved.
error_hooks.py	Global hook registry — thread-safe register / unregister / dispatch. Multiple hooks fire in registration order. Hook exceptions are caught and logged at DEBUG. has_hooks() short-circuit keeps the hot path zero-cost when no hook is registered.
status.py	NullRunStatus (frozen dataclass) + RecentError ring buffer (capacity 10) + WorkflowState enum. State derivation covers four headline buckets: ok / degraded / offline / misconfigured.

2. New public API on nullrun

• nullrun.on_error(hook) — Layer 2 entry point. Fires for every
  structured NullRunError before the exception propagates so the
  call stack is still live. Skipped for WorkflowKilledInterrupt
  (BaseException subclass — kill is a signal, not an error). Returns
  an idempotent unregister callable.
• nullrun.status() — Layer 3 entry point. Synchronous,
  thread-safe, side-effect-free snapshot of runtime state. Raises
  NullRunConfigError (NR-C004) if no runtime has been
  init()'d. Never lazily creates a runtime as a side effect (pinned
  by test_status_never_lazily_creates_runtime).
• Both are added to __all__ so they show up in dir(nullrun) and
  tab-completion.

3. Docs (docs/errors/)

15 per-code pages (NR-A001..A003, NR-B001..B005, NR-C001/C003,
NR-L001, NR-R001, NR-T001, NR-W002/W003) plus a README.md
index. Each page documents:

• the trigger conditions
• the user_action (what to do next)
• the retryable hint
• a small reproducer / fix snippet

Plus docs/integration-baseline-2026-06-19.md pinning the next
integration run baseline.

4. Source wiring

• runtime.py — _emit_sdk_error / _emit_for_transport_error
  wire error_hooks.emit_error into the two SDK failure paths. The
  status() builder reads runtime state and feeds the recent-errors
  ring buffer.
• transport.py — failed batches emit NullRunBackendError
  (retryable=True) through the new path so the hook sees the
  correlation_id from the gateway in ErrorContext.
• decorators.py — @protect catches the structured
  NullRunBlockedException family and emits with stage='tool' so
  a hook can attribute the failure to the right gate.
• __init__.py — wires the new entry points, registers the
  curated symbols in __all__, and keeps the PEP-562 lazy export
  table backward-compatible.

Tests

File	Pins
tests/test_error_hooks.py	Registry basics (register returns unregister, idempotent unregister), emit_error (fires with both args, swallows hook exceptions, one-bad-hook-isolated, unregister-mid-dispatch is safe), ErrorContext validation, the WorkflowKilledInterrupt and WorkflowKilledException bypass rules, and that the global nullrun.on_error shim is wired through.
tests/test_status.py	No-runtime raises NR-C004, with-runtime snapshot is frozen / equality-stable, key prefix is truncated to 10 chars, state derivation (ok / degraded / misconfigured), recent-errors ring buffer (capacity 10, fed by _emit_sdk_error).
tests/test_integration_contract.py	track_event setdefault race pinned against the locked helper.
tests/test_dead_code_removed.py	test_dir_size_unchanged rewritten to key off nullrun.__all__ (source of truth) instead of a hardcoded symbol count — the curated-surface contract is still pinned (no rogue globals leak into dir()), but legitimate additions to the curated surface no longer break the test.

Back-compat

• from nullrun.observability import X (the old single-file surface)
  keeps working — the package's __init__ re-exports the same names.
• All Layer-1 except clauses from feat(exceptions): Layer-1 structured exception hierarchy with NR-* error codes #31 still match.
• The nullrun/__init__.py lazy-export table (_LAZY_EXPORTS) keeps
  every previously-importable name reachable — the new
  on_error / status / exception classes are additions, not
  replacements.

CI status (local verification on Windows / Python 3.14.2)

Step	Result
pytest	926 passed, 13 skipped (0:09:52)
ruff check src/ tests/	All checks passed
mypy src/	No issues found in 26 source files

Stacking

This PR targets feat/layer-1-exception-hierarchy (not master) so
the diff is the observability work alone. #31 should merge first;
this branch will rebase cleanly after that.

Diff

26 files changed, 2236 insertions(+), 39 deletions(-).

[codecov]

Codecov Report

❌ Patch coverage is 79.35943% with 58 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/nullrun/runtime.py	64.76%	24 Missing and 13 partials ⚠️
src/nullrun/observability/status.py	80.24%	7 Missing and 9 partials ⚠️
src/nullrun/transport.py	64.28%	4 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!