# DDR-0017: Application-Layer Ack/Head Byte Precedes JSON Payload

Status: Approved
Date: 2025-12-22

## Related Architecture Decisions
- ADR-0003: E27 API Message Layer Architecture
- ADR-0005: E27 Presentation Layer Responsibilities
- DDR-0008: Schema-0 Encryption and Decryption Rules

## Context

ADR-0005 defines the responsibilities of the E27 presentation layer, including
decryption and payload normalization before application-layer dispatch.

During schema-0 decryption of encrypted E27 messages, the resulting plaintext
buffer contains a leading single-byte field prior to the JSON document.

Initial implementations attempted to parse decrypted buffers directly as UTF-8
JSON, resulting in off-by-one failures.

This behavior was confirmed via:
- Node-RED reference flow
- Live panel decrypt traces
- Successful parsing only after removing the leading byte

## Decision

All decrypted schema-0 application payloads MUST be interpreted as:

    [ ack_or_head : 1 byte ][ UTF-8 JSON bytes ]

Before JSON parsing:
- Strip exactly one leading byte
- Parse the remaining bytes as UTF-8 JSON

This rule applies uniformly to:
- `api_link` encrypted responses
- `authenticate` responses
- All encrypted domain responses

## Consequences

- Presentation/application boundary code must explicitly remove the head byte
- JSON parsing utilities must not assume decrypted payloads begin with `{`
- This behavior must be consistently enforced to prevent subtle regressions

## Notes

The semantic meaning of the head byte is currently unused but may become
relevant for future protocol features.
