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.
Two kinds of checks
Technical requirements protect the platform: memory safety, stable long-running operation and
correct use of the framework (for example, no direct EventBuilder calls). Protequ requires them.
The build enforces many of them with analyzers; review checks the rest.
Behavior checks describe how a device appears in PQ (for example, a detector alarm also raises its partition). We recommend that your adapter meets all of them. If you decide not to, for any reason, that is a legitimate choice and it is yours. How closely an adapter matches PQ behavior can only influence a customer's decision whether to install it.
The Kind column in the Rule Index shows which kind each rule is.
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, 054, 060 |
| Commands | commands.md | RULE-007, 011, 038 |
| Access Sync (incl. credentials) | access-sync.md | RULE-006, 014, 016, 035, 037, 039, 040, 056 + RULE-015, 021, 022, 041, 055, 059 (credentials) |
| Lifecycle | lifecycle.md | RULE-002, 017, 018, 052, 057, 058 |
| Hygiene | hygiene.md | RULE-004, 005, 019, 023, 033, 034, 036, 049 |
| Discovery | discovery.md | RULE-042–048 |
| Communication | communication.md | COMM-001–011 |
Rule Index¶
Rule numbers are allocated once and never reused; RULE-028 to RULE-031 are unassigned, so the sequence skips them.
| # | Name | Category | Kind | Severity |
|---|---|---|---|---|
| RULE-001 | No Repeated Events from Status Polling | Events | Technical | Critical |
| RULE-002 | No Direct Thing References Across Async | Lifecycle | Technical | Critical |
| RULE-003 | No EventBuilder - All Events via YAML | Events | Technical | High |
| RULE-004 | Protocol Constants Must Be Documented | Hygiene | Technical | High |
| RULE-005 | Address Resolution Must Handle Unknown | Hygiene | Technical | Medium |
| RULE-006 | Access Sync Transform Must Not Throw | Access Sync | Technical | High |
| RULE-007 | Command Handlers Must Report Accurate Results | Commands | Behavior | Critical |
| RULE-008 | Timestamp Source Must Match Event Source | Events | Behavior | Medium |
| RULE-009 | Initial State Must Use Snapshot | Events | Behavior | Medium |
| RULE-010 | HistoryPoll and StatusPoll Complementary | Events | Behavior | Medium |
| RULE-011 | Commands Must Use ExecuteCommand | Commands | Technical | Critical |
| RULE-012 | Control-Plane Noise Must Use Explicit Ignore | Events | Behavior | Medium |
| RULE-013 | Unknown Device Addresses Must Be Diagnosable | Events | Behavior | Medium |
| RULE-014 | Access Sync Must Be Idempotent | Access Sync | Technical | Critical |
| RULE-015 | Multi-Credential Projection Must Be Deterministic | Access Sync (credentials) | Behavior | High |
| RULE-016 | Cross-Entity References Must Use Object References | Access Sync | Technical | High |
| RULE-017 | Shared Resource Lifecycle Must Be Complete | Lifecycle | Technical | High |
| RULE-018 | Connection Must Be Fully Ready Before Returning True | Lifecycle | Technical | Critical |
| RULE-019 | No Empty Partial for Generated Things | Hygiene | Technical | Low |
| RULE-020 | Every Device Event Must Be Processed | Events (audit) | Behavior | Critical |
| RULE-021 | Credential Upload Coverage Must Match PQ and Protocol Capabilities | Access Sync (credentials) | Behavior | Critical |
| RULE-022 | Credential Format Transformations Must Be Documented | Access Sync (credentials) | Behavior | High |
| RULE-023 | Adapter Documentation Must Not Drift from Code | Hygiene | Technical | Medium |
| RULE-024 | Vendor Event Streams Must Preserve Semantics | Events (audit) | Behavior | Critical |
| RULE-025 | Startup Event Replay Must Use SkipReplayed | Events | Technical | High |
| RULE-026 | Archive Events Are Authoritative — Must Produce Audit Records Regardless of Current State | Events (audit) | Behavior | Critical |
| RULE-027 | Event Classification Ladder — Most Precise Audit Record Always | Events (audit) | Behavior | Critical |
| COMM-001 | Mandatory Follow-Up Must Use FollowUpFactory | Communication | Technical | Critical |
| COMM-002 | Follow-Up Factory Must Be Pure, Final-Match-Only, No-Reply | Communication | Technical | High |
| COMM-003 | Enabled or Vendor-Required Retries Must Be Declared | Communication | Technical | High |
| COMM-004 | Retries Must Be Bounded and Cancellation-Aware | Communication | Technical | Critical |
| COMM-005 | Mutating Command Retry Safety Must Be Explicitly Documented | Communication | Technical | Critical |
| COMM-006 | Retry Timing Must Not Starve Polling/Event Flow | Communication | Technical | High |
| COMM-007 | Multi-Step Mandatory Exchanges Must Use a Sequence Policy | Communication | Technical | Critical |
| COMM-008 | Protocol Traffic Must Be Trace-Readable by Packet Name | Communication | Technical | High |
| COMM-009 | Serialization Boundaries Must Have Exact Wire Vectors | Communication | Technical | High |
| COMM-010 | Multi-Packet Logical Operations Must Own the Wire via an Exclusive Session | Communication | Technical | Critical |
| COMM-011 | Frames Outside the Pending Reply Must Be Classified OutOfBand or Continue | Communication | Technical | Medium |
| RULE-032 | Event Publication Must Be Encapsulated in the Owning Thing | Events | Technical | High |
| RULE-033 | Persistent Settings Must Be Constructor-Injected Directly | Hygiene | Technical | Medium |
| RULE-034 | Adapter Global Usings Belong in the Project File | Hygiene | Technical | Low |
| RULE-035 | Holiday Entities Must Not Be Stubs When Protocol Documents Holiday Support | Access Sync | Behavior | High |
| RULE-036 | Framework-Bending Smell | Hygiene | Technical | High |
| RULE-037 | Person Profiles Must Use Generated Typed Input | Access Sync | Technical | High |
| RULE-038 | Door Semantics Must Follow the Door Behavior Contract | Commands | Behavior | Critical |
| RULE-039 | Access Sync Must Be Best-Effort — One Bad Item Must Not Abort the Batch | Access Sync | Technical | Critical |
| RULE-040 | Cross-Entity References Must Be Entity-Typed, Never Integers or Bit Masks | Access Sync | Technical | Critical |
| RULE-041 | PIN Credentials Must Be Projected by Role — Card-Bound vs Standalone | Access Sync (credentials) | Behavior | High |
| RULE-042 | Enumerable Protocols Should Ship Discovery | Discovery | Behavior | Recommendation |
| RULE-043 | Undeterminable deviceRef Bindings Must Be Left Untouched | Discovery | Behavior | Critical |
| RULE-044 | Protocol-Exposed deviceRef Bindings Must Be Emitted | Discovery | Behavior | High |
| RULE-045 | Scalars Must Be Emitted on Every Discovery | Discovery | Behavior | High |
| RULE-046 | Name Must Always Be Emitted and Never Read Back | Discovery | Behavior | Medium |
| RULE-047 | No Manual Dangling-Reference Handling; No Refs to Non-Included Devices | Discovery | Technical | High |
| RULE-048 | Every Discoverable Type Must Declare a Stable Identity | Discovery | Technical | High |
| RULE-049 | Closed-Set Properties Must Be Enums, Not Strings | Hygiene | Technical | High |
| RULE-050 | Poll Handlers Must Exist and Be Wired When the Protocol Exposes Them | Events | Behavior | Critical |
| RULE-051 | Poll Must Cover All Relevant States of Each Polled Element | Events | Behavior | High |
| RULE-052 | Time Synchronization Must Be Enabled When the Protocol Can Set the Device Clock | Lifecycle | Behavior | High |
| RULE-053 | Known Card Wire Bit-Length Must Be Propagated | Events | Behavior | Medium |
| RULE-054 | Audit Events Must Be Hardware-Sourced — No Fabricated Occurrences | Events (audit) | Behavior | Critical |
| RULE-055 | Record Shape Must Follow Panel Record Credential Capacity | Access Sync (credentials) | Behavior | High |
| RULE-056 | Selective-Sync Ownership Determines Identity Resolution in Transform | Access Sync | Behavior | High |
| RULE-057 | Set the Device Clock From the Wall Clock, Never a Re-Projected Local Time | Lifecycle | Behavior | High |
| RULE-058 | An Authentication Verdict Must Come From the Device, Never From a Transport Failure | Lifecycle | Technical | High |
| RULE-059 | One Record Position Belongs to One Person | Access Sync (credentials) | Behavior | High |
| RULE-060 | A Member Alarm Must Surface on Its Containing Partition | Events (audit) | Behavior | Critical |
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.