ba1212361f
Commit the previously-untracked standard directories and catalog them in the
root README alongside proof:
- aac/ — communication cargo class: portable boards + a ten-level
offline-first cascade (Apache-2.0 code / CC-BY-4.0 spec).
- map/ — geospatial cargo class: range-requestable signed tilesets +
an F0–F4 fidelity cascade (Apache-2.0 code / CC-BY-4.0 spec).
- sandbox/— isolated, metered, attested execution across the heterogeneous
compute fabric (Apache-2.0 code / CC-BY-4.0 spec).
- jouleclaw-otel-authz, jouleclaw-trust — new jouleclaw reference crates.
Root README now lists aac, map, sandbox, and proof in the catalog, the tree,
and the contribution guide.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
32 lines
2.7 KiB
Markdown
32 lines
2.7 KiB
Markdown
# AAC sub-spec — Canonical serialization and interchange
|
||
|
||
Normative refinement of [SPEC §7–§8](../SPEC.md). Reference: `aac_core::{BackupManager, ExportFormat, MigrationEngine, ImportFormat}`.
|
||
|
||
A user's customization — added words, custom symbols, personal phrases, the exact geometry their muscle memory has learned — is the most valuable and least portable thing in assistive technology. This sub-spec makes portability a property of the standard.
|
||
|
||
## 1. Canonical form
|
||
|
||
A board MUST have a canonical serialization. JSON is the interchange encoding; the canonical form (sorted keys, normalized number forms) MUST round-trip **byte-identically** through a conforming serializer. Content identity MAY be expressed as a content address over the canonical bytes; two boards with equal canonical bytes are the same board.
|
||
|
||
## 2. Export — `ExportFormat`
|
||
|
||
A conforming engine MUST export to:
|
||
|
||
- `OpenBoardFormat` (`.obz`) — the open board interchange format, for cross-tool portability;
|
||
- `NativeJson` — full-fidelity canonical JSON (§1), the lossless form.
|
||
|
||
It MAY additionally export `PrintablePdf` — a low-tech paper backup, so a voice survives a dead battery. A round-trip through `NativeJson` MUST be lossless; a round-trip through `OpenBoardFormat` MUST preserve cell positions, content, actions, and symbol references, and MUST report any field it cannot represent as a non-fatal warning rather than dropping it silently.
|
||
|
||
## 3. Ingest — `ImportFormat`
|
||
|
||
Interchange is **one-directional and additive**: the engine reads existing work into the substrate so a user never starts over, and it does not compete with the tools that produced that work. A conforming engine SHOULD ingest `OpenBoardFormat` and `Cboard`, and MAY ingest other community and vendor exports (`Csv`, and others as they are added).
|
||
|
||
On ingest:
|
||
|
||
1. **Positions** present in the source MUST be preserved (motor stability — [`motor_stability.md`](motor_stability.md)). Positions **absent** from the source MUST be assigned deterministically by row-major fill and then fixed, so the same import always yields the same geometry.
|
||
2. **Unknown or unsupported fields** MUST be surfaced as non-fatal warnings, never silently discarded where they affect meaning.
|
||
3. A format the engine **cannot yet read** MUST fail explicitly — a named "format not yet supported" error — never partially and silently. The reference returns `MigrationError::FormatNotYetSupported(name)` for formats whose readers are not yet implemented.
|
||
|
||
## 4. No lock-in
|
||
|
||
A user MUST be able to take everything with them. An implementation that can export `NativeJson` but cannot re-import it, or that loses positions on its own round-trip, is non-conformant. The guarantee is symmetric: what goes in comes out, and what comes out goes back in.
|