Adapter Compliance Rules¶
Machine-checkable rules that static analysis cannot easily detect. Apply them by hand during code review; each is a compliance standard a developer checks against the adapter's source, and a violation is a finding recorded with its rule ID and severity.
Sibling registry: structural modeling conventions (category↔function, access points, reader↔door linkage, relationship mechanisms) live in modeling-conventions.md as
MODEL-00x. Compliance rules here check runtime/implementation correctness; modeling conventions check structural shape.
Rule Categories¶
Rules are organized into categories:
| Category | File | Rules |
|---|---|---|
| Events (mechanics) | events.md | RULE-001, 003, 008, 009, 010, 012, 013, 025, 032, 050, 051, 053 |
| Events (audit visibility & taxonomy) | events-audit.md | RULE-020, 024, 026, 027 |
| Commands | commands.md | RULE-007, 011, 038 |
| Access Sync (incl. credentials) | access-sync.md | RULE-006, 014, 016, 035, 037, 039, 040 + RULE-015, 021, 022, 041 (credentials) |
| Lifecycle | lifecycle.md | RULE-002, 017, 018, 052, 057 |
| Hygiene | hygiene.md | RULE-004, 005, 019, 023, 033, 034, 036, 049 |
| Discovery | discovery.md | RULE-042–048 |
| Communication | communication.md | COMM-001–010 |
Rule Index¶
| # | Name | Category | Severity |
|---|---|---|---|
| RULE-001 | No Repeated Events from Status Polling | Events | Critical |
| RULE-002 | No Direct Thing References Across Async | Lifecycle | Critical |
| RULE-003 | No EventBuilder - All Events via YAML | Events | High |
| RULE-004 | Protocol Constants Must Be Documented | Hygiene | High |
| RULE-005 | Address Resolution Must Handle Unknown | Hygiene | Medium |
| RULE-006 | Access Sync Transform Must Not Throw | Access Sync | High |
| RULE-007 | Command Handlers Must Report Accurate Results | Commands | Critical |
| RULE-008 | Timestamp Source Must Match Event Source | Events | Medium |
| RULE-009 | Initial State Must Use Snapshot | Events | Medium |
| RULE-010 | HistoryPoll and StatusPoll Complementary | Events | Medium |
| RULE-011 | Commands Must Use ExecuteCommand | Commands | Critical |
| RULE-012 | Control-Plane Noise Must Use Explicit Ignore | Events | Medium |
| RULE-013 | Unknown Device Addresses Must Be Diagnosable | Events | Medium |
| RULE-014 | Access Sync Must Be Idempotent | Access Sync | Critical |
| RULE-015 | Multi-Credential Projection Must Be Deterministic | Access Sync (credentials) | High |
| RULE-016 | Cross-Entity References Must Use Object References | Access Sync | High |
| RULE-017 | Shared Resource Lifecycle Must Be Complete | Lifecycle | High |
| RULE-018 | Connection Must Be Fully Ready Before Returning True | Lifecycle | Critical |
| RULE-019 | No Empty Partial for Generated Things | Hygiene | Low |
| RULE-020 | Every Device Event Must Be Processed | Events (audit) | Critical |
| RULE-021 | Credential Upload Coverage Must Match PQ and Protocol Capabilities | Access Sync (credentials) | Critical |
| RULE-022 | Credential Format Transformations Must Be Documented | Access Sync (credentials) | High |
| RULE-023 | Adapter Documentation Must Not Drift from Code | Hygiene | Medium |
| RULE-024 | Vendor Event Streams Must Preserve Semantics | Events (audit) | Critical |
| RULE-025 | Startup Event Replay Must Use SkipReplayed | Events | High |
| RULE-026 | Archive Events Are Authoritative — Must Produce Audit Records Regardless of Current State | Events (audit) | Critical |
| RULE-027 | Event Classification Ladder — Most Precise Audit Record Always | Events (audit) | Critical |
| COMM-001 | Mandatory Follow-Up Must Use FollowUpFactory | Communication | Critical |
| COMM-002 | Follow-Up Factory Must Be Pure, Final-Match-Only, No-Reply | Communication | High |
| COMM-003 | Enabled or Vendor-Required Retries Must Be Declared | Communication | High |
| COMM-004 | Retries Must Be Bounded and Cancellation-Aware | Communication | Critical |
| COMM-005 | Mutating Command Retry Safety Must Be Explicitly Documented | Communication | Critical |
| COMM-006 | Retry Timing Must Not Starve Polling/Event Flow | Communication | High |
| COMM-007 | Multi-Step Mandatory Exchanges Must Use a Sequence Policy | Communication | Critical |
| COMM-008 | Protocol Traffic Must Be Trace-Readable by Packet Name | Communication | High |
| COMM-009 | Serialization Boundaries Must Have Exact Wire Vectors | Communication | High |
| COMM-010 | Multi-Packet Logical Operations Must Own the Wire via an Exclusive Session | Communication | Critical |
| RULE-032 | Event Publication Must Be Encapsulated in the Owning Thing | Events | High |
| RULE-033 | Persistent Settings Must Be Constructor-Injected Directly | Hygiene | Medium |
| RULE-034 | Adapter Global Usings Belong in the Project File | Hygiene | Low |
| RULE-035 | Holiday Entities Must Not Be Stubs When Protocol Documents Holiday Support | Access Sync | High |
| RULE-036 | Framework-Bending Smell | Hygiene | High |
| RULE-037 | Person Profiles Must Use Generated Typed Input | Access Sync | High |
| RULE-038 | Door Semantics Must Follow the Door Behavior Contract | Commands | Critical |
| RULE-039 | Access Sync Must Be Best-Effort — One Bad Item Must Not Abort the Batch | Access Sync | Critical |
| RULE-040 | Cross-Entity References Must Be Entity-Typed, Never Integers or Bit Masks | Access Sync | Critical |
| RULE-041 | PIN Credentials Must Be Projected by Role — Card-Bound vs Standalone | Access Sync (credentials) | High |
| RULE-042 | Enumerable Protocols Should Ship Discovery | Discovery | Recommendation |
| RULE-043 | Undeterminable deviceRef Bindings Must Be Left Untouched | Discovery | Critical |
| RULE-044 | Protocol-Exposed deviceRef Bindings Must Be Emitted | Discovery | High |
| RULE-045 | Scalars Must Be Emitted on Every Discovery | Discovery | High |
| RULE-046 | Name Must Always Be Emitted and Never Read Back | Discovery | Medium |
| RULE-047 | No Manual Dangling-Reference Handling; No Refs to Non-Included Devices | Discovery | High |
| RULE-048 | Every Discoverable Type Must Declare a Stable Identity | Discovery | High |
| RULE-049 | Closed-Set Properties Must Be Enums, Not Strings | Hygiene | High |
| RULE-050 | Poll Handlers Must Exist and Be Wired When the Protocol Exposes Them | Events | Critical |
| RULE-051 | Poll Must Cover All Relevant States of Each Polled Element | Events | High |
| RULE-052 | Time Synchronization Must Be Enabled When the Protocol Can Set the Device Clock | Lifecycle | High |
| RULE-053 | Known Card Wire Bit-Length Must Be Propagated | Events | Medium |
| RULE-057 | Set the Device Clock From the Wall Clock, Never a Re-Projected Local Time | Lifecycle | High |
How to Use¶
Full adapter review: walk every category file and check the adapter's source, YAML, and docs against each rule. Record each violation as a finding with its rule ID and severity.
Specific category review: each category file is self-contained and can be reviewed on its own — events (mechanics + the audit-visibility safety gate), commands, access sync (incl. credentials), lifecycle, hygiene, communication, modeling, and discovery.