# pde-encoding Specification

## Purpose
Provide reusable primitive binary encoding and bounded structural decoding for positional AssetAZ journal data.

## Requirements

### Requirement: Primitive representation
The PDE layer SHALL implement Jenkov PDE integers, UTF-8, bytes, typed null and length-delimited OBJECT framing only. Integer magnitudes and lengths use little endian; negative integers encode -(value + 1). It MUST reject wrong types, malformed lengths, invalid UTF-8 and values outside the requested Java int/long range.

#### Scenario: Integer extremes
- **WHEN** signed long extrema and nullable strings/bytes are encoded
- **THEN** they round-trip without loss and null is distinguished from empty.

### Requirement: Bounded decoding
Every decoder SHALL operate on byte[], offset and length; child objects SHALL have independent logical bounds. requireEnd SHALL reject unconsumed values using the logical limit, never backing-array size. Framing SHALL expose total object size before payload decoding.

#### Scenario: Reused backing storage
- **WHEN** a short record follows a long record in one buffer
- **THEN** stale bytes are invisible and truncated children are rejected.

### Requirement: Abstraction boundary
PDE SHALL know nothing about UUID, Instant, events, sequence numbers or checksums. It MUST NOT implement object mapping, reflection, annotation schemas or PDL.

#### Scenario: Domain payload decoding
- **WHEN** a UUID byte value is decoded
- **THEN** PDE validates its binary framing while the codec validates its 16-byte schema.