Skip to content

Definition Of Done

Use this checklist to decide whether an adapter implementation or major adapter update is complete.

Your inputs are only the protocol/vendor documentation and this docs/adapter-development documentation set. The output must be the maximum feature set supported by both the protocol and the current framework.

Completion Rule

An adapter is done only when every discovered protocol capability has one of these final states:

  • implemented
  • not supported by protocol
  • not supported by framework
  • blocked by missing or ambiguous documentation
  • blocked by hardware-only verification
  • intentionally deferred by explicit user scope

Do not mark an adapter done because one vertical slice works. A vertical slice proves the architecture; it does not prove feature coverage.

Scoped Work Rule

For bug fixes and explicitly scoped feature extensions, do not expand implementation to unrelated protocol areas.

The changed capability still must satisfy the relevant gates in this document. Update the capability matrix, local documentation, and checklist only for affected capabilities, and preserve existing backlog/final states for unrelated areas.

For new adapters and major rewrites, the full maximum feature set rule applies.

Required Evidence

  • selected archetype from archetypes/
  • capability matrix with every capability marked by final state
  • Thing hierarchy table
  • command mapping table
  • event/status mapping table
  • access/enrollment/APB mapping when the protocol supports stored credentials, biometrics, readers, doors, zones, or entry/exit state
  • unknowns/evidence table when any protocol area is incomplete, ambiguous, or undocumented
  • adapter-local notes that let another developer continue without rediscovering architecture or protocol rules
  • verification summary with performed checks and remaining hardware-only gaps

Protocol Coverage Gate

  • all documented hardware object types are reviewed and either represented as Things or explicitly excluded with evidence
  • all documented protocol commands/actions are reviewed and either implemented, mapped to an existing framework command, or explicitly excluded with evidence
  • all documented event categories, status records, alarms, troubles, and restore events are reviewed
  • all documented credential, schedule, user, access level, holiday, biometric, card format, PIN, APB, time, I/O, intrusion, video, and enrollment capabilities are reviewed when present in the protocol
  • all protocol constants, event codes, command numbers, enum values, bitmasks, frame fields, and magic values are traceable to vendor documentation or provided source material
  • undocumented values are recorded as unknowns; they are not guessed from neighboring values or naming patterns
  • unknown values may appear in analysis or backlog documentation, but not as implemented protocol constants unless the user explicitly supplies authoritative evidence

Framework Coverage Gate

  • each protocol capability is mapped to the strongest current framework concept: Thing, function, command, event, status, polling, access sync, APB sync, enrollment, time sync, stream handling, or custom function
  • unsupported framework gaps are documented as not supported by framework, not silently omitted
  • capabilities-coverage.yaml exists at the adapter root and declares every integration capability from reference/capability-catalog.md with a final state and evidence, per reference/capabilities-coverage.md
  • generated framework patterns are used instead of manual plumbing when available
  • Things remain minimal and do not duplicate generated function state
  • no long-lived service, timer, callback, or closure keeps direct Thing references across async boundaries

YAML Gate

  • adapter-registration.yaml exists and defines adapter identity, security domains, capabilities, transport, protocol address/event/frame types, Thing types, functions, commands, properties, parents, and limits
  • adapter-registration.yaml validates against reference/adapter-registration.schema.json
  • access-model.yaml validates against reference/access-model.schema.json when present
  • YAML uses schema-defined block names and property names; custom structure is not invented to work around missing framework support
  • adapter_id is globally unique in the repository
  • secrets and keys are marked sensitive: true; private/internal configuration is marked private: true when appropriate
  • address ranges, natural keys, parent constraints, max siblings, and categories match protocol hardware limits
  • YAML-declared commands/functions/events match implemented handlers and generated usage
  • access-model.yaml and apb-model.yaml exist when the protocol supports local credential storage or antipassback state

Implementation Gate

  • connection lifecycle is implemented and documented: connect, authenticate, initialize, bind/register, start polling or event stream, graceful disconnect, reconnect
  • heartbeat/watchdog/status behavior is implemented when the protocol exposes liveness or requires keepalive
  • event replay, event deduplication, event loss, or lack of offline recovery is explicitly handled and documented
  • command handlers cover all implemented command mappings and report failure/timeout accurately
  • command-originated state changes are confirmed by device response or documented as ACK-only behavior
  • event routing covers every supported vendor event and preserves unresolved-address diagnostics
  • ignored or suppressed protocol events are intentional, documented, and do not pollute audit as unknown security events
  • unhandled relevant events are logged or published as unknown/unresolved; they are not silently dropped
  • status polling uses framework polling patterns when device state is not pushed as events
  • time synchronization is implemented when the device has a writable or readable clock
  • vendor-specific limitations and quirks are documented locally

Access Synchronization Gate

Apply when the protocol stores users, credentials, schedules, groups, access levels, biometric templates, PINs, or card formats.

  • access-model.yaml defines all supported device-side entities in dependency order
  • Transform() rejects invalid input by returning null or excluding the entity, not by throwing for normal unsupported data
  • tracked-entity Address is owned by the framework: do not call SetAddress() and do not read entity.Address for model references
  • stable natural keys are used where the protocol requires them
  • credential filtering rules are explicit: unsupported card/PIN/biometric formats are documented
  • first sync, reset sync, deletion, and device cleanup semantics are documented
  • unchanged double-sync is verified: running sync twice with unchanged input does not throw and does not create duplicate device state

Capability-Specific Gates

Every integration capability listed in reference/capability-catalog.md for each in-scope domain (cross-cutting, access, intrusion, video, I/O, gateway/native-SDK) must be evaluated and carry a final state. The catalog is the single source of the expected-capability lists; it also backs the directed survey pass and the capability matrix, so the same set is used to scope, build, and verify.

Verification Gate

  • adapter project build passes; do not require a full solution build
  • generated code shape is checked after YAML, source-generator, command, event, polling, access sync, or APB changes
  • one connection path is verified or marked hardware-blocked
  • one command path is verified or marked hardware-blocked
  • one event or status path is verified or marked hardware-blocked
  • access sync double-sync is verified when access sync is applicable
  • hardware-only tests are listed with exact prerequisites and current status
  • adapter review is performed against framework patterns, or the reason for skipping it is documented

Local Documentation Gate

Adapter-local documentation must include:

  • architecture and Thing tree
  • protocol or SDK source references
  • connection sequence and reconnect behavior
  • command table
  • event/status table
  • polling behavior
  • access/enrollment/APB model when applicable
  • configuration properties and sensitive fields
  • known quirks, protocol traps, unsupported capabilities, and backlog
  • build command for the adapter project

Failure Conditions

The adapter is not done if any of these are true:

  • a protocol feature is unreviewed
  • a protocol constant is invented or undocumented without being marked unknown
  • a capability is omitted without final state and evidence
  • events can be silently dropped without documentation
  • the adapter relies on manual framework plumbing where generated patterns exist
  • access sync can create duplicate state on unchanged repeated sync
  • local documentation is stale enough that another developer cannot safely continue