Architecture Decision Records¶
This directory contains the Architecture Decision Records (ADRs) for the cosalette framework. ADRs document significant architectural decisions with their context, rationale, and consequences.
ADR Index¶
| ADR | Title | Status | Date |
|---|---|---|---|
| ADR-001 | Framework Architecture Style | Accepted | 2026-02-14 |
| ADR-002 | MQTT Topic Conventions | Accepted | 2026-02-14 |
| ADR-003 | Configuration System | Accepted | 2026-02-14 |
| ADR-004 | Logging Strategy | Accepted | 2026-02-14 |
| ADR-005 | CLI Framework | Accepted | 2026-02-14 |
| ADR-006 | Hexagonal Architecture (Ports & Adapters) | Accepted | 2026-02-14 |
| ADR-007 | Testing Strategy | Accepted | 2026-02-14 |
| ADR-008 | Packaging and Distribution | Superseded by ADR-070 | 2026-02-14 |
| ADR-009 | Python Version and Dependencies | Accepted | 2026-02-14 |
| ADR-010 | Device Archetypes | Accepted | 2026-02-14 |
| ADR-011 | Error Handling and Publishing | Accepted | 2026-02-14 |
| ADR-012 | Health and Availability Reporting | Accepted | 2026-02-14 |
| ADR-013 | Telemetry Publish Strategies | Accepted | 2026-02-22 |
| ADR-014 | Signal Filters | Accepted | 2026-02-22 |
| ADR-015 | Persistence | Accepted | 2026-02-25 |
| ADR-016 | Adapter Lifecycle Protocol | Accepted | 2026-02-26 |
| ADR-017 | SBOM Generation | Accepted | 2026-02-27 |
| ADR-018 | Telemetry Coalescing Groups | Accepted | 2026-03-03 |
| ADR-019 | Scoped Name Uniqueness | Accepted | 2026-03-04 |
| ADR-020 | Deferred Interval Resolution | Accepted | 2026-03-04 |
| ADR-021 | JSON Serialisation | Accepted | 2026-03-07 |
| ADR-022 | Rust-Only Signal Filters | Accepted | 2026-03-09 |
| ADR-023 | on_configure Lifecycle Phase and Dict-Name Device Registration |
Accepted | 2026-03-31 |
| ADR-024 | Telemetry Retry with Configurable Backoff | Accepted | 2026-03-31 |
| ADR-025 | Command Channel and Sub-Topic Routing | Accepted | 2026-03-31 |
| ADR-026 | Immutable Releases | Accepted | 2026-04-02 |
| ADR-027 | Lifespan-Yielded Injectable State | Superseded by ADR-039 | 2026-04-02 |
| ADR-028 | Adapter Health Check Protocol | Accepted | 2026-04-02 |
| ADR-029 | Adapter Auto-Restart Strategy | Accepted | 2026-04-03 |
| ADR-030 | Documentation Hosting Strategy | Accepted | 2026-04-05 |
| ADR-031 | Sub-Entity Context Manager | Accepted | 2026-04-06 |
| ADR-032 | Cron Scheduling and Wall-Clock Sleep | Accepted | 2026-04-06 |
| ADR-033 | MQTT Schema Enforcement | Accepted | 2026-04-09 |
| ADR-034 | AI-Friendly Downstream Framework Context | Accepted | 2026-04-12 |
| ADR-035 | Optional MCP Layer for Downstream AI Support | Accepted | 2026-04-14 |
| ADR-036 | Triggerable Telemetry | Superseded by ADR-064 | 2026-04-18 |
| ADR-037 | Lazy Store Resolution | Accepted | 2026-04-20 |
| ADR-038 | Deferred enabled= for Decorator Registrations | Accepted | 2026-04-20 |
| ADR-039 | @app.state Shared-State Factory | Accepted | 2026-04-25 |
| ADR-040 | Command Sub-Dispatch | Accepted | 2026-04-25 |
| ADR-041 | Periodic Background Tasks | Accepted | 2026-04-26 |
| ADR-042 | Streaming Protocol: StreamablePort and Stream[T] | Accepted | 2026-04-26 |
| ADR-043 | Domain-Event Reactors for State Objects | Accepted | 2026-05-04 |
| ADR-044 | Public Router and Composition API | Accepted | 2026-05-06 |
| ADR-045 | Stateful Stream Receiver Semantics | Accepted | 2026-05-08 |
| ADR-046 | Typed Handler Contract Validation | Accepted | 2026-05-09 |
| ADR-047 | Transport Availability Signaling | Accepted | 2026-06-23 |
| ADR-048 | Clear orphaned retained topics for removed entities | Accepted | 2026-07-11 |
| ADR-049 | Default store path resolution | Accepted | 2026-07-12 |
| ADR-050 | Typed consumer() Producer for x-cosalette-consumer | Accepted | 2026-07-27 |
| ADR-051 | Settings-Aware Schema Pipeline for Settings-Derived Entity Names | Accepted | 2026-08-04 |
| ADR-052 | Relocatable MCP Server Command and Per-Tool (Claude Code / Kilo) MCP Config Generation | Accepted | 2026-08-05 |
| ADR-053 | Semantics of T | None optional dependency injection |
Accepted | 2026-08-08 |
| ADR-054 | AsyncAPI Emission for the Stream Archetype | Accepted | 2026-08-08 |
| ADR-055 | Concurrent per-entity command dispatch | Accepted | 2026-08-10 |
| ADR-056 | Typed ha_discovery()/openhab() Producers and Open Passthrough for Consumer Overrides | Accepted | 2026-08-11 |
| ADR-057 | Component-Aware HA Payload Builders via Channel-Level Composite Entities | Accepted | 2026-08-11 |
| ADR-058 | HA Availability Keys and Per-Device Device Modelling in Discovery | Accepted | 2026-08-11 |
| ADR-059 | Runtime Home Assistant Discovery Publication with Enrichment Hook | Accepted | 2026-08-11 |
| ADR-060 | Bounded Handler Execution Defaults | Accepted | 2026-08-25 |
| ADR-061 | Decoupled Error-Message Disclosure | Superseded by ADR-091 | 2026-08-26 |
| ADR-062 | Default MQTT TLS to Enabled at the Next 0.x Minor Release | Accepted | 2026-08-27 |
| ADR-063 | Optional HMAC-Signed Retained-Cleanup Snapshots | Accepted | 2026-08-27 |
| ADR-064 | Local (in-process) trigger source for triggerable telemetry | Accepted | 2026-08-31 |
| ADR-065 | Local trigger source for the device archetype | Accepted | 2026-09-01 |
| ADR-066 | Min-interval storm throttle for trigger-initiated runs | Accepted | 2026-09-01 |
| ADR-067 | Per-member wake for a trigger source on a coalescing-group member | Accepted | 2026-09-02 |
| ADR-068 | state_model= Return-Value Enforcement on @app.telemetry and @app.command | Accepted | 2026-09-04 |
| ADR-069 | Machine-Readable state_model Drift Topic for Fleet Scraping | Accepted | 2026-09-04 |
| ADR-070 | maturin Build Backend and Distribution Metadata as the Version Source of Truth | Accepted | 2026-09-04 |
| ADR-071 | Test Clock Doubles for Tick and Throttle Timing Assertions | Accepted | 2026-09-04 |
| ADR-072 | Prefix-Aware AsyncAPI Generation and the Identity-vs-Address Split | Accepted | 2026-09-08 |
| ADR-073 | Author-controlled consumer-visibility opt-out for channels | Accepted | 2026-09-09 |
| ADR-074 | Per-channel consumer visibility for paired command and device channels | Accepted | 2026-09-09 |
| ADR-075 | Default json_attributes_topic to the channel address for composite entities | Accepted | 2026-09-09 |
| ADR-076 | Typed value aggregates on array-valued properties for cross-target consumer parity | Accepted | 2026-09-10 |
| ADR-077 | Automatic Transport Availability for the Telemetry and Device Archetypes | Accepted | 2026-09-12 |
| ADR-078 | Opt-in MQTT 5 with Retained Message Expiry and a Client-Owned Refresh Ledger | Accepted | 2026-09-13 |
| ADR-079 | OpenHAB Availability Wiring and Thing-Level Override Passthrough | Accepted | 2026-09-16 |
| ADR-080 | Telemetry freshness tracking and a stale device status | Accepted | 2026-10-02 |
| ADR-081 | Supervision of framework-started tasks with an on_task_failure policy | Accepted | 2026-10-02 |
| ADR-082 | Persistent-error reminders and a recovery log for telemetry | Accepted | 2026-10-02 |
| ADR-083 | Opt-in health file and a health CLI probe for container liveness | Accepted | 2026-10-02 |
| ADR-084 | Adapter reset() restart protocol and opt-in restart on stale telemetry | Accepted | 2026-10-02 |
| ADR-085 | Optional redaction hook for logs and disclosed error messages | Accepted | 2026-10-02 |
| ADR-086 | Framework availability channels in the generated AsyncAPI document | Accepted | 2026-10-03 |
| ADR-087 | Native cosalette-health probe binary shipped in platform wheels | Accepted | 2026-10-04 |
| ADR-088 | Opt-in event-loop stall watchdog with exit code 6 | Accepted | 2026-10-05 |
| ADR-089 | Opt-in instance identity for HA discovery and openHAB output | Accepted | 2026-10-05 |
| ADR-090 | Keep devcontainer tool checksums current under Renovate | Accepted | 2026-10-10 |
| ADR-091 | Labelling-Only Error Type Map and Secure-by-Default Message Disclosure | Accepted | 2026-10-12 |