Decoder Model
Purpose
Section titled “Purpose”This document defines the initial decoder model.
Decoders transform Network Server payloads into normalized measurements.
V1 Decision
Section titled “V1 Decision”V1 uses controlled, versioned TypeScript decoders.
V1 does not allow arbitrary user-uploaded scripts to execute in the backend.
Decoder Requirements
Section titled “Decoder Requirements”A decoder must:
- Accept a documented input contract.
- Return a documented output contract.
- Be deterministic.
- Avoid side effects.
- Not access databases.
- Not access secrets.
- Not access the network.
- Not access the filesystem.
- Not depend on mutable global state.
- Return structured errors when decoding fails.
Decoder Versioning
Section titled “Decoder Versioning”Decoder behavior must be versioned.
A device type should reference a decoder version.
Changing decoder behavior should not silently change historical meaning.
Unit Conversion
Section titled “Unit Conversion”Unit conversion may happen inside decoders in V1.
Examples:
- liters to cubic meters
- watt-hours to kilowatt-hours
- raw temperature encoding to degrees Celsius
The decoder output should include units.
Decoder Testing
Section titled “Decoder Testing”Each decoder should have tests with:
- Example payloads.
- Expected decoded measurements.
- Invalid payloads.
- Edge cases.
- Counter value examples where relevant.
Future Runtime Scripts
Section titled “Future Runtime Scripts”Runtime user-managed decoders require:
- Sandboxing.
- Timeouts.
- Memory limits.
- No unrestricted network access.
- No unrestricted filesystem access.
- Versioning.
- Preview/test execution.
- Audit logging.
- Rollback.
This is not part of V1.