coordinator-lifecycle

name	coordinator-lifecycle
description	Architectural patterns and lifecycle instructions for KeymasterCoordinator, KeymasterLockCoordinator, fan-out notification architecture, child entity platforms, and storage migrations.

Keymaster Coordinator & Entity Lifecycle Guide

This skill guides modifications to KeymasterCoordinator, KeymasterLockCoordinator (custom_components/keymaster/coordinator.py), entity platforms, and migration logic (migrate.py). For full design details, refer to docs/keymaster-fanout-architecture.md.

Coordinator Architecture & Fan-out Design

Keymaster separates durable storage and refresh ownership from entity-facing runtime notifications to prevent event loop exhaustion on large installations:

Component	Lifetime	Role	Target
KeymasterCoordinator	Runtime	Owns locks, storage, refresh	Keepalive
KeymasterLockCoordinator	Per lock	Mirrors one lock entry	Entities

• Entity Binding:

  • Entities bind to KeymasterLockCoordinator (CoordinatorEntity[KeymasterLockCoordinator]), resolved via manager.async_get_lock_coordinator(config_entry.entry_id).
  • Entities do NOT listen directly to KeymasterCoordinator.

• Notification Dispatch:

  • Manager state changes call async_schedule_keymaster_notifications(entry_ids, *, all_entry_ids=False).
  • Flushes are deferred with hass.loop.call_soon to coalesce updates and prevent nested event-queue overflow.
  • Updates are pushed to per-lock coordinators via lock_coordinator.async_set_updated_data(lock).

• Parent-to-Child Sync:

  • Batched inside async with self._parent_sync_transaction(): so multi-slot child sync operations emit a single coalesced notification flush upon outermost exit.

• Child Entity Platforms:

  • switch.py: Slot enable/disable, notifications, schedule toggles.
  • text.py / number.py: PIN configuration, slot count, autolock parameters.
  • datetime.py / time.py: Access schedule date and time limits.
  • sensor.py / binary_sensor.py: Active PIN status, connection state, slot status sensors.
  • button.py: Manual sync/clear/reset triggers.
  • event.py: Doorbell/unlock event logging.

Guidelines for Modifying Coordinator Logic

1. State Synchronization (Synced Enum):

   • Use the canonical states defined in custom_components/keymaster/const.py:
     • Synced.ADDING ("Adding")
     • Synced.DELETING ("Deleting")
     • Synced.DISCONNECTED ("Disconnected")
     • Synced.OUT_OF_SYNC ("Out of Sync")
     • Synced.SYNCED ("Synced")

2. Scheduling Notifications:

   • Always route updates through async_schedule_keymaster_notifications([entry_id]) rather than calling entity callbacks or async_set_updated_data directly on the manager.

3. Autolock Integration:

   • autolock/ logic interacts with lock state changes and door sensors. Ensure timer cancellations and rescheduled locks are clean upon entity removal or coordinator unload.

4. Storage & Migrations:

   • Runtime storage is coordinator-owned via Store(hass, STORAGE_VERSION, STORAGE_KEY).
   • migrate.py handles schema migrations only when loading legacy storage formats.
   • When modifying storage schemas, bump the version and ensure backward compatibility for prior schema revisions.