Section 26: Serialization and Data Interchange¶

TECHSPEC-27 — Section 26 · Version 0.1 · Status: Initial Draft

Numbering note: this is file TECHSPEC-27.md but it contains Section 26 of the specification. File numbers and section numbers diverge from TECHSPEC-23 onward; neither has been renumbered. See the specification index and audit AUDIT-001 in reports/documentation-audit.md for details.

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Serialization Philosophy¶

Serialization converts program values into formats that can be stored, transmitted, or exchanged with other systems.

Deserialization reconstructs program values from serialized data.

Both operations must preserve defined data semantics, handle malformed input safely, and make data loss explicit.

2. Supported Formats¶

The standard library should initially support:

JSON
UTF-8 text
Binary data
CSV

Additional formats may be introduced through versioned standard-library modules.

Each format must have documented compatibility and data-conversion rules.

3. Explicit Serialization¶

Serialization must be an explicit operation.

Example:

LET encoded: Result<String, SerializationError> =
    JSON.encode(account)

Rules: - The target format must be specified. - Unsupported values must produce explicit errors. - Serialization must not silently omit required fields. - Numeric precision must be preserved where the target format permits it. - Field names and representation rules must be deterministic. - Sensitive values must not be serialized without explicit authorization.

4. Explicit Deserialization¶

Deserialization must identify the expected destination type.

Example:

LET account: Result<Account, DeserializationError> =
    JSON.decode<Account>(input)

Rules: - The destination type must be explicit. - Malformed data must produce a structured failure. - Missing required fields must produce an error. - Unexpected fields must follow a documented policy. - Invalid values must not bypass type constraints or invariants. - Deserialization must not automatically establish trust.

5. Type and Constraint Preservation¶

Deserialized values must satisfy the destination type's requirements.

Rules: - Primitive types must be checked. - Structured fields must match their declared types. - Enum values must be valid. - Optional fields must follow their declared absence rules. - Numeric constraints must be enforced. - Object invariants must hold before the reconstructed object becomes available to ordinary application code.

6. Versioning and Compatibility¶

Serialized data may outlive the program version that created it.

The language must support explicit data format versioning.

Rules: - Serialized formats should identify their schema or version where necessary. - Schema changes must define compatibility behavior. - Required-field additions and removals must be handled explicitly. - Type changes must not silently reinterpret existing data. - Migration functions must declare their inputs, outputs, failures, and effects. - Old data must not be assumed compatible with new types.

7. Deterministic Serialization¶

Where deterministic output is required, equivalent values must produce identical serialized representations.

Rules: - Map field ordering must follow a defined rule. - Numeric formatting must be consistent. - Text encoding must be specified. - Unstable runtime details must not appear in serialized output. - Determinism guarantees must be documented for each format and serializer.

8. Resource and Security Limits¶

Deserialization can consume significant memory and processing time.

Rules: - APIs must support documented input-size limits. - Nesting and collection sizes must have defined limits or configurable safeguards. - Malformed or excessively large input must fail safely. - External references must not be loaded automatically during deserialization. - Deserialization must not execute embedded code. - Sensitive data must be protected according to declared security requirements.

9. Compiler and Runtime Responsibilities¶

The compiler and runtime must: - Validate serialization and deserialization types. - Enforce destination constraints and invariants. - Report malformed or incompatible data. - Preserve numeric and text semantics. - Support explicit schema versions. - Enforce relevant permissions and resource limits. - Distinguish successful decoding from successful validation and authorization.

10. Design Goal¶

An AI agent must never assume that data is valid merely because it can be decoded.

Successful deserialization establishes that data could be reconstructed. It does not automatically establish that the data is trustworthy, authorized, or appropriate for the application's intended use.

Source file: TECHSPEC-27.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.