Event-loop storm on large installs: single-coordinator fan-out to >10k entities trips HA 2026.7's new event-queue guard

[tykeal]

Summary

On a large parent/child deployment, Home Assistant Core repeatedly raises its endless-loop guard roughly every 15–30 seconds:

homeassistant.exceptions.HomeAssistantError: Event state_reported not fired: more than 10000 events were queued by event listeners while dispatching a single event; event listeners are likely firing events in an endless loop

The traceback surfaces in custom_components/keymaster/switch.py at _handle_coordinator_update → async_write_ha_state() (lines 209 and 278), but that switch is the victim, not the cause — it is simply the entity that happens to be writing state when the queued-event count crosses 10,000. The real cause is a self-perpetuating parent→child sync + coordinator fan-out loop.

Environment

• keymaster: current main
• Locks: 1 Akuvox X916 parent; 13 children (2 Akuvox incl. an A08S, 11 Schlage WiFi). 70 code slots per device (~980 keymaster entities total). Single parent → 13-child fan-out.
• Companion: local-akuvox v1.0.0+ / pylocal-akuvox 1.x, and 10 Rental Control integrations each driving 4 slots on the X916 parent.
• Most children inherit only parent slots 1–10, their 4 RC-managed slots, and one backup slot; remaining slots are set to override parent (empty).
• Symptom appeared when the Akuvox stack moved to pylocal-akuvox 1.x (see "Why it appeared" below).

Root cause

Every coordinator refresh runs parent→child sync for all locks:

• _async_update_data calls _sync_child_locks for every lock on each pass — coordinator.py:1942-1943.
• _update_child_code_slots copies parent slot attributes onto each inherited (non-overridden) child slot unconditionally (coordinator.py:2400-2420), then computes pin_mismatch (coordinator.py:2429-2431).
• On any pin_mismatch or Synced.OUT_OF_SYNC, it calls set_pin_on_lock / clear_pin_from_lock and sets self._quick_refresh = True — coordinator.py:2463-2483 (_quick_refresh at :2469).
• set_pin_on_lock calls self.async_set_updated_data(dict(self.kmlocks)) twice per invocation (coordinator.py:1574 and :1598, plus the failure path at :1587); clear_pin_from_lock does the same (coordinator.py:1656, :1679).
• Each async_set_updated_data synchronously notifies all ~980 coordinator entities, every one of which writes HA state in its _handle_coordinator_update (e.g. switch.py:188-209/:276-278, text.py, sensor.py, binary_sensor.py, number.py, datetime.py, time.py). HA emits state_reported even when nothing changed.

With many persistently-mismatched inherited slots across 13 children, a single sync pass produces dozens of async_set_updated_data calls × ~980 entities → well over 10,000 queued events in one dispatch → HA's loop guard fires.

It also self-perpetuates: because _quick_refresh = True is set on every mismatch, _schedule_quick_refresh_if_needed reschedules a full refresh QUICK_REFRESH_SECONDS later (15s — const.py:28). If any child slot never reaches Synced.SYNCED, the mismatch persists, so the loop re-fires every ~15–30s indefinitely — matching the observed cadence.

Secondary amplifier

Rental Control slot writes to the parent trigger the same parent→child fan-out on top of the periodic quick-refresh churn, compounding the event volume.

Why it appeared with pylocal-akuvox 1.x

Before 1.x, the X916 parent's user-code APIs were not supported, so parent slots carried no real PIN data and the parent→child PIN-sync path was effectively a no-op. pylocal-akuvox 1.x marks the X916's user APIs as supported, so keymaster now reads real PIN data on the parent and attempts to push it down to all 13 children on every refresh. Any child that does not read back an exact match stays perpetually OUT_OF_SYNC/mismatched, which drives the endless re-push + quick-refresh loop. This is a keymaster fan-out/re-entrancy problem that the Akuvox capability change merely exposed — not an Akuvox integration bug.

Impact / risk

• The integration currently still functions, but Core logs this error every ~15–30s (log flooding).
• HA drops the guarded event dispatch, so state updates can be missed/delayed, with elevated CPU from ~980-entity fan-outs firing several times per pass.
• Risk of cascading instability as slot/device counts grow, and potential to trip HA watchdogs under load.

Suggested fix direction (not prescriptive)

• Add change-detection guards before async_set_updated_data and before entity state writes / _set_property_value — skip notifying when nothing actually changed.
• Coalesce the parent→child sync pass into a single coordinator notification at the end, instead of 2× per changed slot × N slots.
• Sync only inherited child slots whose relevant attributes actually changed; avoid re-issuing set_pin_on_lock/clear_pin_from_lock for slots already in the desired state.
• Investigate why affected child slots never reach Synced.SYNCED (perpetual pin_mismatch) — a provider read-back that can never equal the written value would keep the loop alive regardless of the above.
• Consider debouncing/skipping no-op quick refreshes when the prior pass produced no real change.

To confirm on the reporting system

Debug logs for a few affected slots around the storm, specifically the [_sync_child_locks] ... mismatch=True lines showing parent vs child PIN values, to verify whether a specific provider read-back is causing the perpetual mismatch.

[tykeal]

---

Update — additional evidence, root-cause trigger needs revisiting.

New information from the reporting system changes the picture:

1. No code slots are OUT_OF_SYNC on any lock (Akuvox or Schlage) — everything is correctly synced. This means the mechanism described above (perpetual pin_mismatch / Synced.OUT_OF_SYNC driving repeated set_pin_on_lock/clear_pin_from_lock in _update_child_code_slots, coordinator.py:2463-2483) is likely not the active trigger. That path should be idle when slots are in sync, so it does not explain the recurring storm on this system.

2. Home Assistant Core was upgraded to 2026.7.0 (then 2026.7.1) concurrently with the Akuvox update (the HA bump was required by the new Akuvox integration). So the timeline has two simultaneous changes — pylocal-akuvox 1.x and HA 2026.7.x — and HA 2026.7.x is now a leading co-suspect for having changed event/state dispatch behavior in a way that turns keymaster's coordinator fan-out into a >10,000-event guard trip.

What still stands: the underlying amplifier — a single global coordinator whose async_set_updated_data fans out synchronously to ~980 entities, with multiple such calls reachable per pass and no coalescing/change-detection — remains a real scalability concern regardless of trigger (coordinator.py numerous async_set_updated_data call sites; switch.py:209/278 is the victim entity, not the cause).

What needs revisiting: the specific trigger in the steady-state (all-in-sync) case, and whether HA 2026.7.x changed dispatch semantics (e.g., synchronous/recursive processing of queued state events within a single event dispatch) such that the previously-tolerable fan-out now trips the guard.

Investigation is ongoing. The decisive next step is DEBUG-level logs from the affected system (keymaster coordinator + the relevant akuvox loggers) captured across ~2 minutes spanning several storms, to show exactly which code path repeats. Will update once the mechanism is confirmed.

[tykeal]

---

Root cause confirmed — correcting the analysis above.

The earlier "perpetual OUT_OF_SYNC re-push" theory is not the cause. Confirmed mechanism, verified by diffing Home Assistant Core source between the working and broken versions:

1. HA 2026.7.0 introduced a new event-bus guard that did not exist in 2026.6.4.

• _MAX_QUEUED_EVENT_DISPATCHES: Final = 10_000 and the exact error string (... more than 10000 events were queued by event listeners while dispatching a single event ...) are new in 2026.7.0 (homeassistant/core.py). They are absent in 2026.6.4.
• New EventBus.async_fire_internal logic: when an event is fired while the bus is already dispatching another event, it is queued as a nested fire and _queued_event_count is incremented; if that count exceeds 10,000 during a single dispatch, it raises. In 2026.6.4 the same volume of nested fires was tolerated silently.

2. Keymaster puts >10,000 entities on a single coordinator at this scale.

• Every platform (switch, text, sensor, number, binary_sensor, button, event, datetime, time) generates per-code-slot entities across all slots (for x in range(CONF_START, CONF_START + CONF_SLOTS)).
• For 70-slot locks that is roughly ~800+ entities per lock. On the reporting install (1 parent + 13 children = 14 locks) that is on the order of ~12,000 entities, all registered against one DataUpdateCoordinator.

3. The collision.
A single coordinator notification (async_set_updated_data → async_update_listeners) synchronously invokes every entity's _handle_coordinator_update → async_write_ha_state(), each firing a state event. When that fan-out executes inside an event dispatch (e.g. triggered from a state-change listener, an Akuvox push event, or a Rental Control state listener), all ~12,000 state writes become nested fires within that single dispatch and cross the new 10,000 ceiling, so Core aborts the dispatch and logs the error. The switch.py:209/278 frame is simply whichever entity was writing when the ceiling was hit — the victim, not the cause.

This explains all the reported facts:

• "Nothing is out of sync" — correct; sync state is irrelevant. The trigger is raw fan-out volume, not the re-push path.
• "Started with the HA 2026.7 upgrade" — exactly: 2026.6.4 tolerated the same fan-out; 2026.7.0's new guard aborts it.
• The Akuvox pylocal-akuvox 1.x upgrade only forced the required HA 2026.7 upgrade; it is not itself the cause, and this is not an Akuvox-integration bug.

Not an HA bug. The new guard is intentional and reasonable — 10,000 nested event fires in a single dispatch is a genuine pathology. The fix belongs here in keymaster.

Suggested fix direction:

• Use per-lock coordinators (or shard the fan-out) so a single notification touches ~800 entities, not ~12,000.
• Ensure coordinator fan-outs are never emitted synchronously from within an event dispatch — defer (e.g. async_request_refresh / hass.loop.call_soon / a debounced task) so writes are dispatched top-level rather than nested.
• Add change-detection so entities whose value/attributes did not change do not write state (and skip async_set_updated_data when nothing changed), cutting the per-pass event volume dramatically.

Confirmation from the reporting system (nice-to-have, not required): DEBUG logs from custom_components.keymaster.coordinator around one occurrence to identify which event's dispatch the fan-out is nested inside (lock-state listener vs Akuvox push vs Rental Control), which will pinpoint the best place to break the re-entrancy.

[tykeal]

Proposed implementation plan for #670 — for maintainer discussion.

This is a design/planning document (not code) drafted to fix the HA 2026.7 event-queue-guard storm described in this issue. It has been through two rubber-duck design-review passes and carries a set of finalized decisions (see the "Finalized maintainer decisions" section) that I'd like the other maintainers to weigh in on before implementation. Nothing here is implemented yet.

Posted in two parts due to GitHub's comment size limit. Part 1 of 2 (Overview → §5 Detailed implementation plan).

---

Implementation plan for keymaster issue #670

Revision notes

This revision incorporates design-review findings that affected implementation order and
correctness. The plan now separates the fastest production relief into Phase A, a
global deferred-notification hotfix, from Phase B, the structural per-lock coordinator
work. It also keeps KeymasterCoordinator.data as a supported dict mirror, initializes
per-lock coordinators with live lock data before entity construction, adds lifecycle
cleanup for deferred callbacks, scopes quick/debounced refresh and parent-child sync by
entry ID, and replaces the event-bus regression test with a deterministic guard
reproduction.

Finalized maintainer decisions (2026-07-05)

The following decisions were confirmed by the repository owner and govern this plan:

1. Phase A ships standalone first. The global deferred-notification hotfix is its own
   PR for fast production relief, ahead of the Phase B per-lock coordinator refactor.
2. Architecture: runtime-only per-lock coordinators, with KeymasterCoordinator
   retained as the manager/data owner (migration-minimizing). No full data-model split.
3. Refresh scheduling: manager-pipelined. The manager staggers/pipelines the 60s
   polling across locks to avoid simultaneous provider polling (thundering herd) on
   installs with 14+ locks. Per-lock coordinators do not each own an independent interval.
4. Parent→child sync UI: coalesced final result only. Child slot sync-status is
   published once after the sync transaction completes; intermediate ADDING/DELETING
   states are not surfaced per child slot.
5. Very-large single lock: warn (do not hard-cap). Add a warning / repair issue when a
   single lock's entity count is very high; do not enforce a hard maximum slot count in the
   config flow.
6. Minimum HA version target: 2026.7.0 (the release that introduced the guard).

Additional decisions (2026-07-07)

7. Guard-regression test lands xfail-first. The deterministic guard test is merged as
   xfail in the test PR (PR Refactor, bug fixes, and improvements #1) ahead of the fix, then flipped to passing in the Phase A
   fix PR. It is not bundled as a single failing-then-fixed change.
8. Test scale: both. Provide a fast unit test (small entity count with a lowered/patched
   guard threshold) AND a separate focused perf/smoke test using a realistic ~13.8k-entity
   case that exercises the real 10k ceiling.
9. always_update=False safety net: yes. Set it on per-lock coordinators in addition to
   explicit dirty-tracking; explicit dirty IDs remain the primary mechanism.
10. One-event-loop-turn UI delay: accepted. The deferral's single-loop-turn delay for UI
    state updates is acceptable; optimistic _attr_* setters continue to provide immediate
    local feedback where already present.
11. Developer-docs note: include. Add a short in-repo developer note documenting the HA
    2026.7 event-queue guard and why the coordinator defers/shards (PR Require unique name during config flow, delete base folder when empty, other potential bug fixes #6).

Execution status: plan finalized; implementation on hold pending the owner's go-ahead.

1. Overview & problem statement

Home Assistant Core 2026.7.0 added an intentional event-bus guard in
homeassistant/core.py: _MAX_QUEUED_EVENT_DISPATCHES = 10_000 is defined at
core.py:1439-1442, nested event fires are queued while _dispatching is true at
core.py:1550-1569, and the top-level dispatch drains that queue before clearing
_dispatching at core.py:1571-1580.

Keymaster currently has one global DataUpdateCoordinator for every lock in the
installation. KeymasterCoordinator owns a single self.kmlocks mapping at
custom_components/keymaster/coordinator.py:105-132, and async_setup_entry creates or
reuses one process-wide coordinator at custom_components/keymaster/__init__.py:138-146.
Every platform obtains that same object from hass.data[DOMAIN][COORDINATOR] and creates
entities for its config entry.

HA's coordinator fan-out is synchronous: DataUpdateCoordinator.async_set_updated_data()
sets self.data and immediately calls async_update_listeners() at
update_coordinator.py:604-620; async_update_listeners() loops every registered
listener synchronously at update_coordinator.py:197-208. CoordinatorEntity registers
each entity callback as a coordinator listener at update_coordinator.py:655-662, and
KeymasterEntity binds every Keymaster entity to the provided coordinator at
custom_components/keymaster/entity.py:31-62.

On a large install, one async_set_updated_data(dict(self.kmlocks)) therefore invokes
all Keymaster entities for all locks. If this happens inside an active HA event dispatch,
each entity's async_write_ha_state() fires a state event as a nested fire. With enough
entities, HA 2026.7+ correctly aborts after 10,000 queued nested events. The frame that
appears in logs, for example switch.py:209 or switch.py:278, is just the entity that
happened to be writing when the guard tripped; it is not the root cause.

The operator observation that the storms eventually pass is consistent with a transient
burst rather than a permanent loop: startup, quick-refresh, lock activity, parent/child
sync, or an external state-change automation can generate a large re-entrant fan-out;
once those updates settle and the coordinator becomes quiet, the system stops crossing
the guard. The fix must reduce the fan-out size and prevent re-entrant coordinator
notifications from running inside HA event dispatch.

2. Goals, non-goals, and constraints

Goals

• Keep Keymaster functional on HA 2026.7+ without tripping the 10,000 nested-event guard.
• Preserve parent/child lock sync semantics, including parent-to-child slot propagation
  from coordinator.py:2335-2485.
• Preserve entity registry stability. KeymasterEntity constructs unique IDs as
  {config_entry.entry_id}_{slugify(property)} at entity.py:48; device identifiers are
  {(DOMAIN, config_entry.entry_id)} at entity.py:56-58; entity names are based on the
  existing lock name and description at entity.py:59-60. The implementation must not
  rename or re-register entities as a side effect.
• Keep the stored lock data format stable if possible. KeymasterCoordinator already
  persists self.kmlocks through _async_save_data() at coordinator.py:256-285.
• Make the fix testable without production DEBUG logs. Production logs are known to be too
  noisy to collect, so reproduction and measurement must be done in tests/dev.
• Follow repository conventions in AGENTS.md: ruff, 100-character lines,
  from __future__ import annotations, type hints, double quotes, and HA entity patterns.

Non-goals

• Do not change HA Core or work around the guard by raising the limit.
• Do not remove entities, disable platforms, or change entity IDs to reduce the count.
• Do not require a one-time destructive entity migration.
• Do not rely on obtaining clean production DEBUG logs before implementing.

Constraints

• Existing service/entity methods assume a coordinator-like object exposes manager methods
  such as set_pin_on_lock(), clear_pin_from_lock(), reset_lock(),
  update_slot_active_state(), async_request_debounced_refresh(), and
  autolock_duration_seconds().
• Some refresh paths are provider or event driven, not only periodic:
  async_set_updated_data() call sites, async_refresh() call sites, quick refresh,
  ZHA programming events, and entity setter debounce paths all need attention.
• The solution should be independently reviewable in small PRs because it touches core
  integration lifecycle code.

3. Root-cause deep dive grounded in live source

3.1 Current coordinator topology

• KeymasterCoordinator subclasses DataUpdateCoordinator at
  coordinator.py:105-132, owns all locks in self.kmlocks (coordinator.py:112), and
  uses name=DOMAIN, update_interval=60s, and config_entry=None.
• The first config entry setup creates the global coordinator and refreshes it at
  __init__.py:138-144; later entries reuse it at __init__.py:145-146.
• Every entity platform pulls that same coordinator from hass.data[DOMAIN][COORDINATOR]:
  • binary sensor: binary_sensor.py:24-31
  • button: button.py:20-28
  • datetime: datetime.py:20-27
  • event: event.py:39-47
  • number: number.py:25-33
  • sensor: sensor.py:21-30
  • switch: switch.py:35-45
  • text: text.py:19-27
  • time: time.py:22-30
• KeymasterEntity._kmlock resolves the lock for an entity by looking up its config entry
  in the global coordinator at entity.py:69-72.
• HA DataUpdateCoordinator defaults always_update=True at
  update_coordinator.py:73-85. Because KeymasterCoordinator.__init__() does not pass
  always_update=False (coordinator.py:126-132), every successful refresh notifies all
  listeners even when the underlying lock objects are unchanged.

3.2 async_set_updated_data() call sites

All current manual notifications pass the entire global lock mapping,
dict(self.kmlocks), to the single coordinator. The following table classifies the live
call sites.

File:line	Context	Classification	Current fan-out scope
coordinator.py:618	_handle_lock_state_change() starts autolock for a push provider after an unlock transition	Conditional/guarded by state transition, push-provider mode, autolock enabled, and timer presence	All locks/entities
coordinator.py:633	_handle_lock_state_change() cancels autolock for a push provider after a lock transition	Conditional/guarded by state transition and timer state	All locks/entities
coordinator.py:961	_lock_unlocked() clears _state_change_autolock_started	Conditional/guarded by that set containing the lock entry	All locks/entities
coordinator.py:964	_lock_unlocked() starts autolock timer	Conditional/guarded by autolock enabled and timer present	All locks/entities
coordinator.py:996	_lock_unlocked() decrements parent access-limit count for a child unlock	Conditional/guarded by child/parent relationship, no child override, parent count enabled and > 0	All locks/entities
coordinator.py:1008	_lock_unlocked() decrements local access-limit count	Conditional/guarded by count enabled and > 0	All locks/entities
coordinator.py:1035	_lock_locked() cancels autolock while already locked but state-change autolock marker exists	Conditional/guarded by already-locked branch, marker, and timer	All locks/entities
coordinator.py:1073	_lock_locked() cancels autolock timer on lock	Conditional/guarded by timer presence	All locks/entities
coordinator.py:1215	_setup_timer() recovered a running timer during startup	Conditional/guarded by recovered timer running	All locks/entities
coordinator.py:1574	set_pin_on_lock() marks a slot ADDING, sets _quick_refresh=True before provider call	Always fires after method validation succeeds	All locks/entities
coordinator.py:1587	set_pin_on_lock() provider set failed, marks slot OUT_OF_SYNC	Conditional/guarded by provider failure	All locks/entities
coordinator.py:1598	set_pin_on_lock() provider set succeeded, marks slot SYNCED	Conditional/guarded by provider success	All locks/entities
coordinator.py:1656	clear_pin_from_lock() marks a slot DELETING, sets _quick_refresh=True before provider call	Always fires after method validation succeeds	All locks/entities
coordinator.py:1670	clear_pin_from_lock() provider clear failed, restores local PIN and marks OUT_OF_SYNC	Conditional/guarded by provider failure	All locks/entities
coordinator.py:1679	clear_pin_from_lock() provider clear succeeded, marks slot DISCONNECTED	Conditional/guarded by provider success	All locks/entities
switch.py:306	Turning on switch.autolock_enabled starts the timer while the lock is unlocked	Conditional/guarded by switch type, lock state, timer state	All locks/entities
switch.py:342	Turning off switch.autolock_enabled cancels a running timer	Conditional/guarded by switch type and timer running	All locks/entities

Other refresh paths also trigger the same global listener set through async_refresh():
initial setup (__init__.py:142, services.py:36, migrate.py:81), add/update/delete
lock (coordinator.py:1358, coordinator.py:1415, coordinator.py:1442), reset lock or
slot (coordinator.py:1706, coordinator.py:1754), quick refresh
(coordinator.py:1810-1812), debounced refresh (coordinator.py:1830-1833), and ZHA
programming events (providers/zha.py:481-487). _async_update_data() loops every lock,
then syncs every parent to children, then saves, then schedules quick refresh at
coordinator.py:1926-1955.

3.3 Entity count breakdown

Entity counts are conditional on config flags and parent/child status. The counts below
come directly from the live platform setup loops.

Assumptions for the main 14-lock example:

• 70 slots per lock (CONF_SLOTS = 70).
• 1 parent and 13 children.
• Door sensor configured for each lock, so switch adds door-related controls
  (switch.py:63-77). If a lock lacks a door sensor, subtract 2 switch entities for that
  lock.
• Provider either supports connection status or is not present at platform setup, so the
  connectivity binary sensor is created (binary_sensor.py:38-54). If not, subtract 1
  binary sensor for that lock.
• DEFAULT_ADVANCED_DATE_RANGE=True and DEFAULT_ADVANCED_DAY_OF_WEEK=True in
  const.py:87-88, but the observed "~12k" size aligns with advanced date range enabled
  and advanced day-of-week disabled. Both scenarios are shown.

Platform	Source	Parent count with 70 slots	Child count with 70 slots	Notes
Binary sensor	binary_sensor.py:38-75	1 connected + 70 active = 71	71	Connected sensor is conditional as above.
Button	button.py:28-60	1 reset lock + 70 reset slot = 71	71	All enabled by default.
DateTime	datetime.py:29-66	140 if advanced date range enabled	140 if enabled	2 per slot; 0 if disabled.
Event	event.py:47-66	70	70	1 per slot; also listens to Keymaster bus events at event.py:81-97.
Number	number.py:33-94	2 autolock + 70 count = 72	72	Count entity per slot.
Sensor	sensor.py:32-95	lock name + timer + 70 sync = 72	lock name + parent name + timer + 70 sync = 73	parent_name sensor only for children (sensor.py:46-59).
Switch, date on / DOW off	switch.py:51-163	4 base + 70 x (3 slot + 1 date) = 284	4 base + 70 x (1 override + 3 slot + 1 date) = 354	Door sensor contributes 2 of the 4 base switches.
Switch, date on / DOW on	switch.py:51-163	4 base + 70 x (3 + 1 date + 1 DOW + 21 DOW detail) = 1,824	4 base + 70 x (1 override + 3 + 1 date + 1 DOW + 21 detail) = 1,894	DAY_NAMES has 7 days at const.py:98-106; three DOW switches per day at switch.py:126-145.
Text	text.py:29-65	2 per slot = 140	140	Name and PIN per slot.
Time	time.py:31-71	980 if advanced DOW enabled	980 if enabled	14 per slot (start/end for 7 days); 0 if disabled.

Totals for 1 parent + 13 children, 70 slots:

• Advanced date range enabled, advanced day-of-week disabled: parent 920 +
  13 x child 991 = 13,803 entities. Without door sensors this is 13,775. This is the
  closest source-grounded count to the issue's "on the order of ~12,000" statement.
• Advanced date range enabled, advanced day-of-week enabled (current defaults):
  parent 3,440 + 13 x child 3,511 = 49,083 entities.
• Both advanced features disabled: parent 710 + 13 x child 781 = 10,863 entities.

Even the smallest 14-lock/70-slot configuration with all optional advanced entities off is
near or above HA's 10,000 nested-event guard if all entities write during one re-entrant
coordinator fan-out.

3.4 Entity update behavior

Most platform _handle_coordinator_update() methods write HA state unconditionally after
computing availability/value:

• Binary sensor: sets _attr_is_on and writes at binary_sensor.py:104-108.
• Button: every branch writes at button.py:84-101.
• DateTime: every branch writes at datetime.py:90-120.
• Event entity availability update writes at event.py:137-152; actual event/reset
  handlers write only when the event matches the slot and lock at event.py:99-134.
• Number: every branch writes at number.py:123-154.
• Sensor: KeymasterSensor writes at sensor.py:119-136; KeymasterAutoLockSensor
  writes at sensor.py:166-204.
• Switch: every branch writes at switch.py:187-278.
• Text: every branch writes at text.py:99-136.
• Time: every branch writes at time.py:95-142.

Because all entities listen to one coordinator, every manual data update currently causes
all of the above handlers to run for all locks, even when only one slot on one lock changed.

3.5 Re-entrancy paths

The dangerous pattern is: HA is already dispatching an event, Keymaster synchronously
notifies the global coordinator, then thousands of entity async_write_ha_state() calls
fire nested state_changed events.

Known paths:

1. Lock state-change listener

   • Registered by _create_listeners() through async_track_state_change_event() at
     coordinator.py:708-718.
   • _handle_lock_state_change() at coordinator.py:569-633 can call
     async_set_updated_data() directly at coordinator.py:618 and coordinator.py:633,
     or route into _lock_unlocked()/_lock_locked() at coordinator.py:604-625, which
     have additional update calls at coordinator.py:961-1073.

2. Provider push events

   • Keymaster subscribes provider callbacks at coordinator.py:687-692 and routes them
     into _handle_provider_lock_event() at coordinator.py:502-568.
   • Akuvox listens to local_akuvox_webhook_received on the HA bus at
     providers/akuvox.py:210-295 and schedules the Keymaster callback at
     providers/akuvox.py:288.
   • ZHA listens to zha_event at providers/zha.py:466-575; operation events schedule
     the callback at providers/zha.py:571, and programming events schedule a coordinator
     refresh at providers/zha.py:481-487.
   • Z-Wave JS listens to notification events and fallback lock state changes at
     providers/zwave_js.py:932-1065, scheduling callbacks at
     providers/zwave_js.py:983 and providers/zwave_js.py:1059.
   • Zigbee2MQTT parses MQTT actions at providers/zigbee2mqtt.py:168-182 and calls the
     registered callback from _async_handle_action() at providers/zigbee2mqtt.py:413-423.

3. Keymaster custom bus events

   • Unlock events are fired by _fire_unlock_state_changed() at coordinator.py:750-772.
   • Lock events are fired by _lock_locked() at coordinator.py:1083-1093.
   • Event entities subscribe to EVENT_KEYMASTER_LOCK_STATE_CHANGED and reset events at
     event.py:81-97; the matching event entity writes state at event.py:113-121 or
     event.py:133-134.

4. External automations / Rental Control style flows

   • If an automation reacts to a HA state change and calls Keymaster entity services
     before the original dispatch completes, switch.py can call the global coordinator
     directly at switch.py:306 or switch.py:342; text/date/number/time entity setters
     schedule debounced refreshes at text.py:203, datetime.py:150, number.py:188,
     and time.py:169.

5. Startup and quick refresh

   • _setup_timer() can notify when a timer recovers running state at
     coordinator.py:1183-1215.
   • _quick_refresh=True is set by set_pin_on_lock() at coordinator.py:1572,
     clear_pin_from_lock() at coordinator.py:1654, _sync_pin() at
     coordinator.py:2286, and parent/child slot propagation at coordinator.py:2469;
     _schedule_quick_refresh_if_needed() schedules another refresh after
     QUICK_REFRESH_SECONDS at coordinator.py:2487-2498.

4. Solution options

Option A: Per-lock/per-config-entry coordinators

Create one entity-facing DataUpdateCoordinator per Keymaster config entry instead of one
entity-facing coordinator for the entire integration. Keep a manager/registry responsible
for storage, services, lock relationships, and parent/child orchestration, but bind each
entity to the coordinator for its own lock.

Concrete shape:

• Keep hass.data[DOMAIN][COORDINATOR] as the manager for compatibility with services and
  provider code.
• Add hass.data[DOMAIN][LOCK_COORDINATORS][entry_id] (new constant) holding
  KeymasterLockCoordinator instances.
• A KeymasterLockCoordinator exposes data as one KeymasterLock and notifies only the
  entities for that config entry.
• Platform setup uses async_get_lock_coordinator(hass, config_entry.entry_id) instead of
  the global coordinator.
• Parent/child sync remains in the manager. When a parent changes, the manager computes
  which child locks were changed and schedules notifications for the parent coordinator
  and each affected child coordinator separately.

Pros:

• Structural fix for fan-out size. A single lock with 70 slots is approximately 710-3,511
  entities depending on options, not 10,863-49,083 entities for the 14-lock install.
• Preserves entity unique IDs and device identifiers because those are based on
  config_entry.entry_id and entity description keys (entity.py:48, entity.py:56-58),
  not on the coordinator object.
• Provides a clean place to refresh one lock, notify one lock, and test per-lock fan-out.

Cons/risks:

• Largest refactor. Many entity methods currently call manager methods through
  self.coordinator; either the per-lock coordinator must proxy those methods to the
  manager, or entity code must be updated to store both self.coordinator and
  self.manager.
• Parent/child sync is the hard part. Current code freely mutates any lock in
  self.kmlocks; after sharding, the implementation must notify every touched lock's
  coordinator and avoid synchronously notifying all children in one event-dispatch stack.
• If a parent update synchronously notified 13 child coordinators from inside an event
  dispatch, the combined nested writes could still cross 10,000. Therefore this option
  must be paired with deferred/coalesced notification.

Effort: high, but this is the durable fix.

Option B: Defer/decouple fan-out from HA event dispatch

Replace direct async_set_updated_data() calls from event paths with a helper that
coalesces dirty work and schedules coordinator notifications for the next event-loop turn
using hass.loop.call_soon() (not eager task creation). In Phase A the flush still targets
the global manager coordinator; in Phase B the same scheduling boundary targets per-lock
coordinators. In both phases, async_set_updated_data() runs only after the current HA
event dispatch has returned.

Pros:

• Directly addresses the HA 2026.7 nested-fire guard. If coordinator listener updates run
  outside an active bus dispatch, each entity write dispatches its own top-level state
  event and _queued_event_count resets between events.
• Lower risk as an initial patch; can be applied before the per-lock refactor.
• Explains why storms eventually pass: the current burst is re-entrant; moving fan-out out
  of the re-entrant stack removes the guard failure even when the system is busy.

Cons/risks:

• Alone, it does not reduce the raw event volume. A global fan-out may still write 13k-49k
  state events and stall the event loop.
• It does not prevent repeated redundant fan-outs when data did not actually change.
• Must avoid async_create_task() if HA's task helper starts coroutines eagerly in the
  current loop turn; call_soon() to a synchronous flush or a task that first awaits
  asyncio.sleep(0) is safer.

Effort: medium. Important as a safety layer even after per-lock coordinators.

Option C: Change detection / dirty tracking

Avoid writing HA state when an entity's availability, value, and attributes are unchanged.
Also avoid coordinator notifications when no lock data changed.

Implementation pieces:

• Add an entity base helper that compares the last published state signature to the newly
  computed signature before calling async_write_ha_state().
• In coordinator/manager methods, track which lock entry IDs are dirty. Do not rely on
  DataUpdateCoordinator(always_update=False) with shallow dict(self.kmlocks) copies,
  because the dictionary values are mutable KeymasterLock objects and may compare equal
  by identity after in-place mutation.
• For refresh methods, take lightweight per-lock snapshots before/after _update_lock_data()
  and _sync_child_locks() or explicitly mark dirty at every mutation site.

Pros:

• Reduces steady-state event volume dramatically.
• Helps startup and quick-refresh behavior: if a refresh only confirms existing state, most
  entities do not write.
• Improves performance independent of HA's event-bus guard.

Cons/risks:

• Alone, it cannot guarantee safety. A legitimate full refresh or parent sync can still
  change thousands of entities.
• Must be careful with event entities: actual event triggers should still write even if
  availability is unchanged.
• Requires platform-by-platform tests because each entity stores state differently
  (_attr_native_value, _attr_is_on, _attr_extra_state_attributes, event internals).

Effort: medium.

Option D: Combined phased approach

Use all three techniques:

1. Add a coalesced deferred notification helper so no coordinator fan-out runs
   synchronously inside HA event dispatch.
2. Add entity-level change detection and lock-level dirty tracking to suppress redundant
   writes and redundant notifications.
3. Introduce per-lock entity coordinators as the structural fix so a valid change on one
   lock cannot notify every entity in the installation.

Recommendation: implement the combined approach, with per-lock coordinators as the
structural end state, deferred notification as a required safety layer, and change
detection as the performance/steady-state layer. Any one option alone is incomplete:
per-lock coordinators alone can still synchronously notify many children in one re-entrant
parent sync; deferral alone still allows 13k-49k writes; change detection alone cannot
bound worst-case legitimate changes.

5. Detailed implementation plan for the recommended approach

5.1 Add constants, data-model guarantees, and lifecycle storage

Files: custom_components/keymaster/const.py, custom_components/keymaster/__init__.py,
custom_components/keymaster/coordinator.py.

Implementation has two deliberately separate phases:

• Phase A: global deferred-notification hotfix. Keep the current global coordinator as
  the entity-facing coordinator, but replace direct/nested listener fan-out with a deferred
  global flush. The flush still calls the manager/global coordinator with
  async_set_updated_data(dict(self.kmlocks)), but it does so from a fresh top-level
  event-loop callback (call_soon, a task created by that callback, or an equivalent
  debounce). This is the fastest production-relief PR because platforms currently bind to
  the global coordinator (switch.py:41, text.py:26, binary_sensor.py:30,
  sensor.py:28-29, plus the other platform setup files).
• Phase B: structural per-lock coordinators. Add one entity-facing coordinator per
  config entry, re-bind platforms, and switch the deferred flush target from the global
  manager to the affected per-lock coordinators.

Data-model decision for both phases:

• KeymasterCoordinator remains the manager and storage owner. self.kmlocks is still the
  authoritative mutable store (coordinator.py:112) persisted by _async_save_data()
  (coordinator.py:256-285).
• KeymasterCoordinator.data remains a supported dict mirror of kmlocks, not just an
  updater implementation detail. Non-entity readers already use it: config flow excludes
  locks through coordinator.data.values() at config_flow.py:240-245, and
  delete_coordinator() checks len(coordinator.data) at __init__.py:295-309.
  Therefore every manager refresh/mutation path must keep self.data in sync with
  dict(self.kmlocks) even after entity listeners move to per-lock coordinators.

Lifecycle/storage steps:

1. Phase A adds manager attributes near coordinator.py:112-124 for global deferral, for
   example:

   self._pending_global_notification = False
   self._global_notify_handle: asyncio.Handle | None = None
   self._deferred_notifications_shutting_down = False

2. Phase B adds a new hass-data key, for example:

   LOCK_COORDINATORS = "lock_coordinators"

   Keep COORDINATOR = "coordinator" as the manager key. Do not remove it because services
   and providers already look it up (services.py:31-40, providers/zha.py:481-487).

3. In async_setup_entry() (__init__.py:91-231):

   • Continue creating the manager at __init__.py:138-144 if missing.

   • After await coordinator.add_lock(...) at __init__.py:208-210, Phase B must ensure a
     per-entry lock coordinator exists before forwarding platforms at __init__.py:214:

     lock_coordinator = coordinator.async_get_lock_coordinator(config_entry.entry_id)
     hass.data[DOMAIN].setdefault(LOCK_COORDINATORS, {})[config_entry.entry_id] = lock_coordinator

4. In unload/remove/shutdown paths (__init__.py:239-309, coordinator.py:136-145):

   • On unload, unload entity platforms as today, unsubscribe listeners, unload provider,
     and cancel pending deferred-notification work for that entry.
   • On unload/shutdown, cancel any pending global/per-lock notification handles, clear the
     entry ID from pending notification sets, quick-refresh sets, and debounce maps, and set
     a shutdown flag so late flush callbacks become no-ops.
   • On remove, delete the lock through the manager as today (__init__.py:276-280), then
     remove the per-entry coordinator from LOCK_COORDINATORS.
   • During flush, skip entry IDs no longer present in self.kmlocks and skip missing or
     shut-down lock coordinators. This matters because unload currently leaves the lock in
     kmlocks (__init__.py:252-259), while removal is separate (__init__.py:276-280).
   • Only remove the manager and hass.data[DOMAIN] when no Keymaster entries remain, as
     delete_coordinator() already does at __init__.py:295-309.

5.2 Introduce an entity-facing lock coordinator

File: custom_components/keymaster/coordinator.py.

Phase B adds a small KeymasterLockCoordinator class near KeymasterCoordinator:

class KeymasterLockCoordinator(DataUpdateCoordinator[KeymasterLock | None]):
    """Entity-facing coordinator for one Keymaster lock."""

    def __init__(self, manager: KeymasterCoordinator, config_entry_id: str) -> None:
        self.manager = manager
        self.config_entry_id = config_entry_id
        super().__init__(
            manager.hass,
            _LOGGER,
            name=f"{DOMAIN}_{config_entry_id}",
            update_interval=timedelta(seconds=60),
            config_entry=manager.hass.config_entries.async_get_entry(config_entry_id),
            always_update=False,
        )
        self.data = manager.sync_get_lock_by_config_entry_id(config_entry_id)

    async def _async_update_data(self) -> KeymasterLock | None:
        await self.manager._initial_setup_done_event.wait()
        changed_entry_ids = await self.manager.async_refresh_lock(self.config_entry_id)
        self.manager.async_schedule_lock_notifications(changed_entry_ids - {self.config_entry_id})
        return self.manager.sync_get_lock_by_config_entry_id(self.config_entry_id)

The exact method names can differ, but the responsibilities should be:

• Initialize data from manager.sync_get_lock_by_config_entry_id(entry_id) before any
  platform constructs entities. KeymasterEntity.__init__() derives the entity name from
  _kmlock during construction (entity.py:59-60), and _kmlock currently calls
  sync_get_lock_by_config_entry_id() (entity.py:69-72), so data=None during setup
  risks unnamed/broken entities.
• Entity-facing coordinator data is one lock, not the global mapping.
• Per-lock refresh updates only that lock unless parent/child sync requires touching other
  locks.
• Other touched locks are scheduled for deferred notification on their own coordinators.
• The class proxies existing manager methods used by entities to minimize platform churn:
  set_pin_on_lock, clear_pin_from_lock, reset_lock, reset_code_slot,
  update_slot_active_state, async_request_debounced_refresh,
  autolock_duration_seconds, get_lock_by_config_entry_id,
  sync_get_lock_by_config_entry_id, and a read-only kmlocks property if needed during
  the transition. This lets existing code such as text.py:148-203, switch.py:313-352,
  and button.py:103-113 keep calling self.coordinator.<method>() while the coordinator
  object delegates to the manager.
• Platform setup-time lookups that only need to decide which entities to create can either
  continue to use the manager (switch.py:42-44, binary_sensor.py:31, sensor.py:29) or
  use the lock coordinator proxies above, but the plan must be consistent per platform.

5.3 Add deferred-notification helpers in two phases

File: custom_components/keymaster/coordinator.py.

Phase A helper: global target, deferred boundary. Add manager attributes in
KeymasterCoordinator.__init__() near coordinator.py:112-124 and a helper like:

@callback
def async_schedule_global_notification(self) -> None:
    """Coalesce and defer the current global coordinator notification."""
    if self._deferred_notifications_shutting_down:
        return
    self._pending_global_notification = True
    if self._global_notify_handle is None:
        self._global_notify_handle = self.hass.loop.call_soon(
            self._flush_pending_global_notification,
        )

@callback
def _flush_pending_global_notification(self) -> None:
    """Notify the current global coordinator outside active event dispatch."""
    self._global_notify_handle = None
    if not self._pending_global_notification or self._deferred_notifications_shutting_down:
        return
    self._pending_global_notification = False
    self.data = dict(self.kmlocks)
    self.async_set_updated_data(dict(self.kmlocks))

Rules for Phase A:

• The helper still fans out to the global coordinator because all entities still listen to
  it, but the fan-out must start from a fresh top-level event-loop callback so it is not
  nested inside an active HA bus dispatch.
• Use call_soon() (or a task created from the call_soon callback that first yields) to
  avoid eager task execution in the same dispatch stack.
• Replace direct event-path calls with this helper; do not call
  async_set_updated_data(dict(self.kmlocks)) inline from lock/provider/entity callbacks.
• On shutdown, cancel _global_notify_handle, clear _pending_global_notification, and make
  a late flush a no-op.

Phase B helper: per-lock target, same deferred boundary. Add manager attributes:

self._lock_coordinators: dict[str, KeymasterLockCoordinator] = {}
self._pending_notify_entry_ids: set[str] = set()
self._notify_handle: asyncio.Handle | None = None
self._quick_refresh_entry_ids: set[str] = set()
self._cancel_quick_refresh_by_entry: dict[str, Callable[[], None]] = {}
self._cancel_debounced_refresh_by_entry: dict[str, Callable[[], None]] = {}

Add methods:

def async_get_lock_coordinator(self, entry_id: str) -> KeymasterLockCoordinator:
    """Return/create the entity-facing coordinator for one lock."""

@callback
def async_schedule_lock_notifications(self, entry_ids: Iterable[str]) -> None:
    """Coalesce and defer lock coordinator notifications to the next loop turn."""

@callback
def _flush_pending_lock_notifications(self) -> None:
    """Notify each dirty lock coordinator outside the current event dispatch."""

Rules for Phase B:

• Accept one or more entry IDs and drop IDs not in self.kmlocks.
• Always coalesce duplicate IDs.
• Use self.hass.loop.call_soon(self._flush_pending_lock_notifications) so the flush runs
  after the current call stack and after any active HA bus dispatch returns.
• In the flush, call only each affected lock coordinator's
  async_set_updated_data(self.kmlocks[entry_id]).
• Keep the manager's data mirror up to date with dict(self.kmlocks), but do not use the
  manager/global coordinator for entity fan-out after platforms are bound to per-lock
  coordinators.
• On unload/shutdown, cancel _notify_handle, remove the entry from
  _pending_notify_entry_ids, _quick_refresh_entry_ids, and per-entry debounce/quick
  maps, and skip missing/shut-down lock coordinators.
• Tests can assert that direct inline async_set_updated_data(dict(self.kmlocks)) no longer
  exists outside compatibility-only flush code.

5.4 Replace direct global notifications with deferred notifications

Files: custom_components/keymaster/coordinator.py, custom_components/keymaster/switch.py.

Phase A replacement for every direct call in the table in section 3.2:

self.async_schedule_global_notification()

This is intentionally global in Phase A because every platform still listens to the manager.
It is still safe for the HA 2026.7 guard because the listener fan-out no longer runs nested
inside the active event dispatch.

Phase B replacement once platforms are bound to per-lock coordinators:

• Current lock state/timer notifications (coordinator.py:618, 633, 961, 964,
  1035, 1073, 1215) should schedule only kmlock.keymaster_config_entry_id.
• Parent access-count decrement (coordinator.py:996) should schedule the parent entry ID,
  not the child that unlocked, unless the child was also mutated.
• Local access-count decrement (coordinator.py:1008) should schedule the current lock.
• set_pin_on_lock() (coordinator.py:1574, 1587, 1598) should schedule the target
  config_entry_id, except when a parent-sync transaction explicitly suppresses per-slot
  scheduling and collects dirty IDs.
• clear_pin_from_lock() (coordinator.py:1656, 1670, 1679) should schedule the target
  config_entry_id, with the same parent-sync suppression rule.
• switch.py:306 and switch.py:342 should call a per-lock coordinator/manager helper,
  not async_set_updated_data(dict(self.coordinator.kmlocks)).

Pseudo-code replacement after Phase B:

self.async_schedule_lock_notifications({kmlock.keymaster_config_entry_id})

For code that can touch more than one lock:

dirty_entry_ids: set[str] = {parent_id, child_id}
self.async_schedule_lock_notifications(dirty_entry_ids)

Refresh paths need the same protection. HA's coordinator refresh completion synchronously
fires listeners after _async_update_data() (update_coordinator.py:579-584), and Keymaster
currently awaits or schedules global async_refresh() in add/update/delete/reset paths
(coordinator.py:1358, 1415, 1442, 1706, 1754) and from ZHA programming events
(providers/zha.py:481-487). Note that HA fires listeners after
_async_refresh_finished() (update_coordinator.py:574-584), so overriding only that hook
does NOT prevent the synchronous fan-out — the whole refresh/notify path must be diverted.
Before Phase A ships, replace those call sites so they do NOT call the base manager
async_refresh() while it still has entity listeners: route them through a manager refresh
pipeline that updates kmlocks/data and then calls async_schedule_global_notification()
(a wrapper that performs the data update but defers the listener fan-out to a fresh
top-level callback), rather than invoking base DataUpdateCoordinator refresh directly.
Before Phase
B switches the target to per-lock coordinators, ensure entity listeners have moved off the
manager, or the manager refresh path remains a global synchronous fan-out risk.

5.5 Refactor refresh paths while preserving the manager data mirror

File: custom_components/keymaster/coordinator.py.

Current _async_update_data() at coordinator.py:1926-1955 updates all locks, syncs all
children, saves data, schedules quick refresh, and returns the entire mapping. Convert this
into manager methods that can update either all locks for maintenance or one lock for an
entity-facing coordinator.

Suggested structure:

async def async_refresh_lock(self, entry_id: str) -> set[str]:
    """Refresh one lock and return entry IDs whose entities may need notification."""
    await self._initial_setup_done_event.wait()
    dirty = {entry_id}
    before = self._lock_snapshot(entry_id)
    await self._update_lock_data(entry_id)
    if self._lock_snapshot(entry_id) == before:
        dirty.discard(entry_id)
    dirty.update(await self._sync_child_locks(entry_id))
    await self._async_save_data()
    self.data = dict(self.kmlocks)
    await self._schedule_quick_refresh_if_needed(dirty)
    return dirty

async def async_refresh_all_locks(self) -> set[str]:
    """Refresh all locks for startup/maintenance and return dirty entry IDs."""

Then:

• Phase A should replace manager async_refresh() use with a deferred-refresh wrapper, for
  example async_refresh_all_locks_deferred(), that updates all locks, saves data, keeps
  self.data = dict(self.kmlocks), and schedules one global deferred notification. This
  wrapper is needed while the manager still has entity listeners.
• Phase B should keep the manager's _async_update_data() only as a compatibility or
  maintenance refresh that calls async_refresh_all_locks(), updates the data mirror, and
  schedules per-lock notifications for dirty entry IDs; or stop using the manager as a
  DataUpdateCoordinator refresh source and move periodic refresh responsibility to
  per-lock coordinators.
• Do not let manager refresh completion synchronously notify entity listeners. Entity
  listeners should live on KeymasterLockCoordinator instances only after Phase B.
• If maintainers choose to migrate non-entity readers away from coordinator.data, update
  config_flow.py:240-245 and __init__.py:303 in the same PR. Otherwise, the supported
  contract is that coordinator.data remains a dict mirror of kmlocks.

5.6 Parent-to-child sync across coordinators

Files: custom_components/keymaster/coordinator.py, tests in tests/test_coordinator_sync.py.

Current parent/child sync:

• _async_update_data() calls _sync_child_locks() for every lock at
  coordinator.py:1941-1943.
• _sync_child_locks() finds child IDs and calls _sync_child_lock() at
  coordinator.py:2335-2358.
• _sync_child_lock() compares code slot mappings and calls _update_child_code_slots()
  at coordinator.py:2359-2381.
• _update_child_code_slots() copies parent slot attributes to the child at
  coordinator.py:2403-2420, marks _quick_refresh=True and calls set/clear on the child
  at coordinator.py:2463-2485.
• set_pin_on_lock() and clear_pin_from_lock() publish ADDING/DELETING before
  awaiting provider I/O at coordinator.py:1570-1579 and coordinator.py:1652-1660, so a
  parent sync can publish many partial/duplicate child states while looping.

Refactor this flow as a parent-sync transaction:

async def _sync_child_locks(self, parent_entry_id: str) -> set[str]:
    dirty: set[str] = set()
    suppressed: set[str] = set()
    ...
    for child_entry_id in parent.child_config_entry_ids:
        child_dirty = await self._sync_child_lock(parent, child_entry_id, suppress_notify=True)
        if child_dirty:
            dirty.add(child_entry_id)
            suppressed.add(child_entry_id)
    dirty.update(suppressed)
    return dirty

Transaction rules:

• Track whether copied attributes changed before mutating.
• Mark the child dirty when any copied attribute changes.
• During _sync_child_locks(), suppress per-slot notification scheduling inside
  set_pin_on_lock()/clear_pin_from_lock() and collect dirty child entry IDs instead.
  Implementation can use an explicit suppress_notify parameter, a small async context
  manager, or a transaction-depth counter plus a set[str] accumulator.
• set_pin_on_lock()/clear_pin_from_lock() should still update slot state and quick-refresh
  tracking for provider retries, but should not schedule immediate child notifications while
  the parent-sync transaction is active.
• After the parent sync completes, call the appropriate Phase A/Phase B deferred helper once:
  Phase A schedules one global notification; Phase B schedules one coalesced per-lock
  notification for the parent plus affected children.
• Special case: child unlock decrementing a parent access limit at coordinator.py:972-1002
  mutates the parent. That path must notify the parent coordinator, not only the child
  coordinator.

5.7 Quick refresh and debounced refresh

Files: custom_components/keymaster/coordinator.py, custom_components/keymaster/const.py,
tests/test_debounce.py.

QUICK_REFRESH_SECONDS is 15 at const.py:28. Current quick refresh is one global boolean
(coordinator.py:118) and one global cancel handle (coordinator.py:119), scheduled by
_schedule_quick_refresh_if_needed() at coordinator.py:2487-2498; the current trigger has
no entry ID and simply calls async_request_refresh() at coordinator.py:1810-1812.

Change this to entry-specific tracking in Phase B:

• Replace _quick_refresh: bool with _quick_refresh_entry_ids: set[str].
• Convert every _quick_refresh = True mutation site to record the relevant entry ID:
  set_pin_on_lock() (coordinator.py:1572), clear_pin_from_lock()
  (coordinator.py:1654), _sync_pin() (coordinator.py:2286), and parent/child sync
  (coordinator.py:2469).
• In parent/child sync, add each child touched by set/clear to _quick_refresh_entry_ids,
  but let the parent-sync transaction suppress per-slot notification fan-out until the end.
• _schedule_quick_refresh_if_needed() schedules refreshes only for those entry IDs.
• _trigger_quick_refresh(entry_id) should call the corresponding per-lock coordinator's
  async_request_refresh() or the manager's async_refresh_lock(entry_id), then schedule
  only that lock's notification.
• During Phase A, before per-lock coordinators exist, the quick-refresh trigger may still
  refresh globally, but it must use the deferred global notification wrapper rather than
  manager async_request_refresh()/async_refresh() with synchronous listener fan-out.

For debounced entity edits:

• Current debounce is one global cancel handle (coordinator.py:120) and one global
  async_request_debounced_refresh() at coordinator.py:1813-1828.
• Make it entry-specific: async_request_debounced_refresh(config_entry_id: str | None = None).
• Per-lock coordinators can expose async_request_debounced_refresh() without parameters
  and delegate with their own entry ID.
• Existing entity setters then continue calling await self.coordinator.async_request_debounced_refresh().
• On unload/shutdown, cancel and remove per-entry debounce/quick-refresh handles.

5.8 Entity binding changes

Files: all platform files and custom_components/keymaster/entity.py.

1. Add a helper, probably in coordinator.py or __init__.py, to retrieve the per-entry
   coordinator:

   def get_lock_coordinator(hass: HomeAssistant, entry_id: str) -> KeymasterLockCoordinator:
       return hass.data[DOMAIN][LOCK_COORDINATORS][entry_id]

2. In every platform setup, replace the global coordinator lookup with the per-entry
   coordinator for entity construction. Setup-time lock lookups can continue to use the
   manager if that is clearer:

   manager: KeymasterCoordinator = hass.data[DOMAIN][COORDINATOR]
   kmlock = await manager.get_lock_by_config_entry_id(config_entry.entry_id)
   coordinator = manager.async_get_lock_coordinator(config_entry.entry_id)

3. Update KeymasterEntityDescription.coordinator typing to accept the new lock
   coordinator. If entities need direct manager access, add manager: KeymasterCoordinator
   to the description; otherwise keep the proxy approach.

4. Update KeymasterEntity._kmlock from the global lookup at entity.py:69-72 to either:

   return self.coordinator.data

   or, during transition:

   return self.coordinator.sync_get_lock_by_config_entry_id(self._config_entry.entry_id)

   The transition form requires KeymasterLockCoordinator.sync_get_lock_by_config_entry_id()
   to proxy to the manager. That proxy is also useful because KeymasterEntity.__init__()
   calls _kmlock before CoordinatorEntity.__init__() at entity.py:59-61.

5. Leave unique ID, name, and device info logic unchanged (entity.py:48, entity.py:56-60).

5.9 Entity-level change detection

Files: custom_components/keymaster/entity.py and all platform files.

Add a base helper to prevent redundant writes. One possible pattern:

class KeymasterEntity(...):
    _last_keymaster_state_signature: tuple[Any, ...] | None = None

    def _async_write_if_changed(self, *signature: Any, force: bool = False) -> None:
        if not force and signature == self._last_keymaster_state_signature:
            return
        self._last_keymaster_state_signature = signature
        self.async_write_ha_state()

Each platform handler should compute the values it is about to expose, assign _attr_*,
and pass the relevant signature:

• Availability-only entities: (self._attr_available,).
• Switch/binary sensor: (self._attr_available, self._attr_is_on).
• Sensor/number/date/time/text: (self._attr_available, self._attr_native_value, attrs_signature).
• Auto-lock timer sensor: include native value and sorted extra attributes.
• Event entity availability updates can dedupe, but actual _trigger_event() paths at
  event.py:113-121 and reset clearing at event.py:133-134 should force a write because
  those represent real events, not coordinator availability updates.

Tests should assert that a second coordinator update with identical lock data does not call
async_write_ha_state() again for representative entities from each platform.

5.10 Bus event handling

Files: custom_components/keymaster/coordinator.py, custom_components/keymaster/event.py.

Keep the custom EVENT_KEYMASTER_LOCK_STATE_CHANGED semantics stable:

• Unlock event fire site: coordinator.py:750-772.
• Lock event fire site: coordinator.py:1083-1093.
• Event entity listeners: event.py:81-97.

Do not use these custom events as a substitute for coordinator updates. They are event
entities' trigger mechanism and should stay scoped to event history. If testing shows
custom events can still run re-entrantly, prefer hass.bus.fire()/call_soon deferral over
synchronous hass.bus.async_fire() from inside event callbacks.

---

Continued in Part 2 of 2 (§6 Backwards compatibility → §9 Open questions).

[tykeal]

Proposed implementation plan for #670 — Part 2 of 2 (continued from the previous comment: §6 Backwards compatibility → §9 Open questions / maintainer decisions).

---

6. Backwards compatibility & migration

• Entity registry stability: No entity unique IDs should change. The existing formula
  at entity.py:48 must remain unchanged. Platform entity description keys must remain
  unchanged.
• Device registry stability: Keep identifiers {(DOMAIN, config_entry.entry_id)} from
  entity.py:56-58 and setup-time device creation at __init__.py:161-167.
• Storage/data compatibility: Keep the persisted kmlocks store (STORAGE_KEY at
  coordinator.py:90, load/save at coordinator.py:170-285) unchanged. Per-lock
  coordinators are runtime-only and do not require a config-entry migration. Unless the same
  PR migrates all readers, KeymasterCoordinator.data remains a dict mirror of kmlocks
  for config flow (config_flow.py:240-245) and coordinator cleanup (__init__.py:303).
• Config entry version: No migration step should be needed if stored data and config
  entry data are unchanged. Existing async_migrate_entry() can remain focused on older
  schema migrations.
• Public/internal imports: If tests or internal code import KeymasterCoordinator, keep
  that class available as the manager. Add the new KeymasterLockCoordinator rather than
  renaming KeymasterCoordinator.
• Upgrade behavior: On upgrade, the first setup creates the manager and per-lock
  coordinators. Existing entity registry entries bind to the same unique IDs and should be
  retained automatically.

7. Testing & verification strategy

Production DEBUG logs are not required. Build a synthetic large install in tests and
instrument the HA event bus/entity writes.

7.1 Synthetic large install fixture

Use existing test patterns:

• tests/conftest.py:43-89 has a MockProvider suitable for provider-independent tests.
• tests/test_entity.py:35-58 shows direct coordinator/config-entry setup.
• tests/test_coordinator_lifecycle.py:14-25 shows isolated coordinator lifecycle tests.
• Existing platform tests use small slot counts; add a new large-install test module or
  parametrized fixtures that create N MockConfigEntry objects with:
  • CONF_START = 1
  • CONF_SLOTS = 70
  • parent entry for one lock, 13 child entries with CONF_PARENT_ENTRY_ID
  • CONF_ADVANCED_DATE_RANGE=True
  • CONF_ADVANCED_DAY_OF_WEEK=False for the ~13.8k scenario, plus a smaller smoke case
    with DOW enabled to prove per-lock sharding still stays below 10k per lock
  • door sensors present to include the switch entities observed in production-like setups

Patch provider creation to return MockProvider instances with deterministic usercodes.
Avoid real Z-Wave/ZHA dependencies for this regression.

7.2 Event-bus guard regression

Add a deterministic unit test for the HA 2026.7 guard instead of relying only on "fire a HA
state change". A coroutine listener can yield before the dangerous fan-out
(core.py:730-735), which may make the old behavior look safe by accident.

Test shape:

1. Set up enough generated Keymaster entities or lightweight coordinator listeners that the
   old global fan-out would exceed a patched guard threshold.

2. Patch/lower HA's _MAX_QUEUED_EVENT_DISPATCHES for the test, or patch the bus's nested
   queue counter path so a much smaller listener count trips the same failure mode.

3. Register a synchronous HA bus listener for a test event. Inside that listener, assert
   the bus is actively dispatching (for example through the private _dispatching flag if
   available in the tested HA version), then invoke the old/global fan-out path:

   coordinator.async_set_updated_data(dict(coordinator.kmlocks))

4. Fire the test event and assert the old behavior raises the same guard error because the
   coordinator listeners write HA state while the bus dispatch is still active.

5. Repeat with the Phase A deferred helper and assert no guard error occurs; the synchronous
   bus listener should return before the deferred global fan-out runs.

6. Repeat after Phase B and assert one deferred notification fan-out is scoped to one lock or
   to the explicit dirty lock set.

The key assertion is not "no state writes"; it is "bulk coordinator fan-out is not executed
inside one active HA event dispatch" and, after Phase B, "one notification fan-out is scoped
to the dirty lock set."

7.3 Per-lock fan-out tests

• Create parent + children and patch each lock coordinator's async_update_listeners() or
  entity write helper.
• Mutate one child slot through set_pin_on_lock() and assert only that child coordinator
  is notified.
• Trigger a child unlock that decrements a parent access-limit count and assert the parent
  coordinator is notified, not all siblings.
• Trigger a parent slot change and assert only the parent and affected non-overriding
  children are notified.

7.4 Change-detection unit tests

For each platform, use a representative entity and call _handle_coordinator_update() twice
with unchanged lock data:

• First call writes state.
• Second call does not write.
• Changing the relevant property writes exactly once.
• Event entity actual events still write even when availability is unchanged.

Existing platform test files (tests/test_switch.py, tests/test_text.py,
tests/test_sensor.py, tests/test_number.py, tests/test_datetime.py,
tests/test_time.py, tests/test_button.py, tests/test_binary_sensor.py,
tests/test_event.py) are natural homes for targeted tests.

7.5 Quick-refresh/debounce tests

Extend tests/test_debounce.py:

• Multiple rapid entity edits for one lock coalesce into one per-lock refresh.
• Edits on two different locks schedule two independent per-lock refreshes, not one global
  fan-out.
• set_pin_on_lock() and clear_pin_from_lock() add only the target entry ID to quick
  refresh tracking.
• Quick refresh after QUICK_REFRESH_SECONDS refreshes only the target lock coordinator.

7.6 Cross-coordinator parent/child sync tests

Extend tests/test_coordinator_sync.py:

• Parent slot change propagates to non-overriding children and schedules child coordinator
  notifications.
• Children with override_parent=True are not mutated and not notified for copied parent
  fields.
• Provider set/clear retries inside _update_child_code_slots() still occur and mark only
  the affected child dirty.
• Parent access-limit decrement from child unlock notifies the parent coordinator.

7.7 Validation commands

Run targeted tests first, then broader checks:

pytest tests/test_coordinator_sync.py tests/test_debounce.py tests/test_entity.py
pytest tests/test_switch.py tests/test_text.py tests/test_sensor.py tests/test_number.py \
  tests/test_datetime.py tests/test_time.py tests/test_event.py tests/test_binary_sensor.py
ruff check custom_components/ tests/
ruff format --check custom_components/ tests/
mypy custom_components/keymaster/
tox

Use the smallest targeted command during development, then run the full tox suite before
merging.

8. Rollout, phasing, and risk

Suggested PR/commit breakdown

Use capitalized Conventional-Commits-style subjects compatible with gitlint, for example
Test: ..., Fix: ..., Refactor: ....

1. Test: Add deterministic coordinator fan-out guard coverage

   • Add the synchronous-bus-listener guard reproduction from section 7.2 as a fast unit
     test (small entity count with a lowered/patched guard threshold).
   • Add a separate focused perf/smoke test using a realistic ~13.8k-entity case that
     exercises the real 10k ceiling.
   • Add synthetic large-install fixtures/instrumentation from section 7.1.
   • The guard test lands xfail in this PR (it reproduces the storm against current
     code) and is flipped to passing in the Phase A fix PR (Remove helper entities on entry unload or options update #2).

2. Fix: Defer global Keymaster coordinator notifications out of event dispatch

   • Phase A / fastest production relief. Keep the global coordinator as the
     entity-facing coordinator, but add the global deferred-notification helper from section
     5.3.
   • Replace all direct inline async_set_updated_data(dict(self.kmlocks)) call sites with
     async_schedule_global_notification().
   • Convert/override manager async_refresh() paths so add/update/delete/reset
     (coordinator.py:1358, 1415, 1442, 1706, 1754), quick/debounce refresh, and
     ZHA programming refresh (providers/zha.py:481-487) update data and then use the same
     deferred global notification boundary.
   • Preserve KeymasterCoordinator.data = dict(self.kmlocks) for config flow and cleanup.
   • This PR is independently shippable and should be the hotfix for production systems
     tripping the HA 2026.7 guard.

3. Fix: Skip unchanged Keymaster entity state writes

   • Add base write-if-changed helper.
   • Convert platform handlers one platform at a time with tests.
   • This is shippable after Phase A because it reduces event volume without changing the
     coordinator topology.

4. Refactor: Add per-lock Keymaster coordinators

   • Phase B foundation. Add KeymasterLockCoordinator, initialize each instance's
     data from manager.sync_get_lock_by_config_entry_id(entry_id) before platform entity
     construction, and add lookup/manager-method proxies.
   • Add LOCK_COORDINATORS lifecycle storage and bind platforms to per-entry coordinators.
   • Ensure manager data remains a dict mirror, and ensure entity listeners no longer live
     on the manager before relying on manager refresh paths.
   • Switch the deferred flush target from the global coordinator to per-lock coordinators,
     with a conservative fallback that can notify all entry IDs when a mutation path is not
     yet precisely scoped.

5. Fix: Scope parent-child sync and quick refresh to dirty locks

   • Convert quick/debounced refresh to entry-specific tracking, including every
     _quick_refresh=True site (coordinator.py:1572, 1654, 2286, 2469).
   • Implement the parent-sync transaction from section 5.6 so set/clear operations during
     _sync_child_locks() collect dirty entry IDs and publish one coalesced notification
     after the sync completes.
   • Add cross-coordinator parent/child and debounce tests.

6. Docs/Test: Document HA 2026.7 fan-out guard and validation

   • Add a short developer note if maintainers want one.
   • Ensure all tests and lint/type checks pass.

Risks and mitigations

Risk	Mitigation
Phase A accidentally leaves an async_refresh() path with synchronous manager listener fan-out	Test refresh call sites explicitly; replace/override manager refresh completion before shipping the hotfix.
Parent/child sync misses a child notification	Return explicit dirty entry IDs from sync helpers; add tests for parent edits, child overrides, access-limit decrement, and retry paths.
Parent/child sync publishes noisy intermediate states	Use the transaction/suppression design so ADDING/DELETING/SYNCED/OUT_OF_SYNC changes during parent sync are coalesced unless maintainers explicitly choose intermediate UI states.
Entity registry churn	Do not change entity description keys, unique ID formula, device identifiers, or config entry IDs. Add tests that compare unique IDs before/after coordinator refactor.
Per-lock coordinator setup yields data=None and breaks names	Initialize lock coordinator data from the manager before platform setup and keep lookup proxies during the transition.
Deferred notifications hide immediate UI feedback	Use call_soon() coalescing, not long sleeps. The UI delay should be one event-loop turn. Entity setters can still optimistically set _attr_* for immediate local feedback where already done, such as number.py:185-188.
Per-lock coordinators break entity methods expecting manager methods	Add proxy methods on KeymasterLockCoordinator during the transition, then optionally clean up later.
Raw event volume remains high on full refresh	Combine per-lock sharding with write-if-changed; do not rely on deferral alone.
Tests become slow with 49k entities	Parametrize a realistic ~13.8k case for guard regression and use lower guard thresholds or representative listener counts for fast unit tests; reserve the full DOW-enabled scenario for a focused smoke/performance test if needed.
Large single-lock installs can still approach the guard after sharding	Consider a slot cap or config warning because CONF_SLOTS currently only enforces min=1 at config_flow.py:297-299; advanced day-of-week entities can make one lock very large.

9. Open questions / maintainer decisions

1. Is Phase A intended to ship as a standalone global-deferral hotfix separate from the
   per-lock coordinator work? This plan recommends yes: it is the fastest production relief
   and is independently shippable if all direct and refresh-completion fan-outs are deferred.
2. KeymasterCoordinator.data must stay a dict mirror of kmlocks (§5.1/§5.5 treat this
   as a fixed contract, since current readers depend on it — config flow
   config_flow.py:240-245 and coordinator cleanup __init__.py:303). The only open
   decision is whether a LATER, separate PR migrates those readers to kmlocks and drops
   the mirror; for the fix itself the mirror is retained. Not an open question for Phase A.
3. Should per-lock coordinators each own their own 60-second refresh interval, or should the
   manager pipeline refreshes to avoid simultaneous provider polling/thundering-herd behavior
   on installations with 14+ locks?
4. During parent-to-child sync, should the UI show intermediate ADDING/DELETING states
   per child slot, or only final coalesced results after the sync transaction completes?
5. Is there an intended maximum slot count? config_flow.py:297-299 only enforces
   CONF_SLOTS >= 1, so a single lock with advanced day-of-week enabled can generate about
   3,500 entities, and a large enough single lock could approach the 10k guard even after
   per-lock sharding. Should there be a cap or at least a warning?
6. Is the maintainer comfortable adding a runtime-only KeymasterLockCoordinator per config
   entry while keeping KeymasterCoordinator as the manager? This is the recommended
   migration-minimizing architecture.
7. Should always_update=False be used on per-lock coordinators in addition to explicit
   dirty tracking? It is useful as a safety net, but explicit dirty IDs should be the
   primary mechanism because Keymaster mutates dataclasses in place.
8. Is a one-event-loop-turn delay acceptable for all UI updates currently produced by direct
   async_set_updated_data() calls? This is expected to be imperceptible and is central to
   avoiding re-entrant HA bus dispatch.
9. What minimum HA version should the fix target? The issue is HA 2026.7+, but tests may
   need conditional instrumentation if private bus attributes differ across supported HA
   versions.

[tykeal]

@firstof9 and / or @raman325 can you give this a brief look over on the suggested plan? Since it's a bit of an architectural shift I don't want to just implement without discussion.

[firstof9]

13 locks is a lot of locks

I am fine with a re-structuring if it makes the integration work better.

[tykeal]

Yes it's a lot! I helped someone build out an HA system to manage a 10 unit short term rental building in Boston over the last 1.5 years. They're the reason there's now an integration I've created for managing Akuvox intercom devices locally. They're also the reason I worked with the maintainer of the Schlage integration to get the integration capable of easily managing codes!

Also, it's not 13 locks, but 14. 3 Akuvox devices (each one a different class of device) and 11 Schlage locks. All setup in parent / child configuration under Keymaster with a single Akuvox sitting at the top of it all. 10 Rental Control configurations driving into the thing. It's a lot of moving bits.

[firstof9]

Is Phase A intended to ship as a standalone global-deferral hotfix separate from the per-lock coordinator work?

This is fine by me to get a "quick fix" out the door.

Should per-lock coordinators each own their own 60-second refresh interval, or should the manager pipeline refreshes to avoid simultaneous provider polling/thundering-herd behavior on installations with 14+ locks?

I'd go with the manager handling the refreshes so we don't overload the networks/protocols.

During parent-to-child sync, should the UI show intermediate ADDING/DELETING states per child slot, or only final coalesced results after the sync transaction completes?

I'd say go with final states.

Is there an intended maximum slot count?

Ideally no, but if we need to enforce something due to constraints I'm all for that. Maybe a max of 20 per lock?

Is the maintainer comfortable adding a runtime-only KeymasterLockCoordinator per config entry while keeping KeymasterCoordinator as the manager?

I'm good with this.

Should always_update=False be used on per-lock coordinators in addition to explicit dirty tracking?

I like the safety net, but will defer to those more expert.

Is a one-event-loop-turn delay acceptable for all UI updates currently produced by direct async_set_updated_data() calls?

This is fine.

What minimum HA version should the fix target?

Likely 2026.6.7+ so we can keep the code efficient as possible.

[tykeal]

Thanks for the review @firstof9 — appreciate it. Sounds like we're aligned on the core shape: Phase A standalone hotfix first, the manager owning/pipelining refreshes (rather than per-lock intervals) to avoid hammering the networks, final coalesced sync states, the runtime-only per-lock KeymasterLockCoordinator with KeymasterCoordinator kept as the manager, the always_update=False safety net, and the one-event-loop-turn UI delay.

Two points where I'd steer differently:

Max slot count. I'd rather not enforce a hard cap. A limit like 20/lock would break existing production setups — the system that surfaced this issue runs 70 slots per lock across 14 locks, and a hard cap would strand their configuration (and anyone else already above the limit). Instead I'm planning a soft guardrail: a Home Assistant Repairs warning when a single lock's projected entity count approaches the guard ceiling (warn around ~8,000 entities; the HA guard trips at 10,000), auto-clearing when it drops back under. That gives operators a heads-up without bricking large existing installs. The real structural fix is the per-lock sharding + deferral, which keeps a single lock's fan-out well under the ceiling for normal configurations.

Minimum HA version. I'd target a 2026.7.0 floor rather than 2026.6.7. The event-queue guard that triggers this only exists in 2026.7.0+, so pinning there keeps the deterministic guard-regression test clean (no conditional instrumentation for pre-guard cores) and lets us lean on current APIs. The deferral fix itself isn't version-sensitive, but the floor bump keeps the test matrix simple.

Everything else in your feedback I've folded in as-is. I'll get the work broken into discrete sub-issues under this one so it's easy to track.

[firstof9]

Sounds good to me.

[raman325]

Non-goal: Do not remove entities, disable platforms, or change entity IDs to reduce the count.

that is OK I guess, but given that users have complained about entity counts generated, probably one that should be a goal at least secondarily.. is every entity including date/time selectors getting tied to the coordinator sync? If so, why? There are a limited number of entities that need to act on what the code is, so I'd hazard that you can stop 90+% of them from being coordinator entities to begin with.

That doesn't invalidate any of your suggestions, but it's worth considering in addition to everything else. I only got through the goals section so may have more once I have time to digest