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 | Accepted | 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 |