[ikalchev]

First PR of the callback interface refactor stack (see refactor.md, added here).

What

refactor.md records the agreed redesign of the setter/getter callback interface:

• Delegate objects (CharacteristicDelegate / ServiceDelegate) with frozen contexts (client_addr, client_uuid, connection handle, deadline, is_admin) — new input data arrives as new context fields, never as signature changes.
• Async by design: every delegate method is a coroutine function, validated at registration; no sync/async inference on the new path.
• A curated HapStatusError protocol so callbacks can answer a HAP status instead of the generic -70402 (closes Allow characteristics to indicate set value failure #75 for new and existing code).
• A grouped-first gate write pipeline (veto before side effects, deferred notify) with the legacy pipeline preserved byte-for-byte behind a facade.
• A uniform async read path, per-characteristic error isolation, lifecycle hooks, and a phased migration of per-client state from the (ip, port) tuple to a stable connection handle.

The document also details exactly what changes in behavior compared to today (split into guaranteed invariants, new behavior, and three deliberate changes affecting legacy users), the migration notes for embedders (Home Assistant), the parked driver-level listener registry alternative, and the five implementation phases.

Why a document PR

Reviewing the contract before the code: the stack's later PRs implement it phase by phase, each against the invariants recorded here.

The crash investigation note for the media worker segfaults is tracked separately in #558.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.97%. Comparing base (412b899) to head (34e5bc1).

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #559      +/-   ##
==========================================
- Coverage   92.00%   91.97%   -0.03%     
==========================================
  Files          50       50              
  Lines       10839    10839              
  Branches     1404     1404              
==========================================
- Hits         9972     9969       -3     
- Misses        579      582       +3     
  Partials      288      288              

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ikalchev]

Folded into #562: the design overview now lives in the API PR's description, and the final design will land in the Sphinx docs as the phases merge. No repo file needed - refactor.md is not committed anywhere.