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]>
47 lines
3.4 KiB
Markdown
47 lines
3.4 KiB
Markdown
# AAC sub-spec — The board data model
|
||
|
||
Normative refinement of [SPEC §2](../SPEC.md). Reference: `aac_core::{Board, Cell, GridLayout, GridPosition, CellContent, CellAction, BoardType}`.
|
||
|
||
A **board** is a person's communication surface. It is a small, text-like document — artwork is referenced, not embedded (§4) — so a voice travels cheaply between devices and implementations.
|
||
|
||
```
|
||
Board = (id: BoardId, name: String, board_type: BoardType,
|
||
layout: GridLayout, cells: [Cell])
|
||
Cell = (id: CellId, position: GridPosition, content: CellContent,
|
||
action: CellAction, style: CellStyle, frequency: u64, locked: bool)
|
||
```
|
||
|
||
## 1. Identity — `id: BoardId`, `id: CellId`
|
||
|
||
Both are UUIDs, stable for the life of the structure. A `BoardId` is the target of a `Navigate` action, so it is also the edge label of the board graph (§5). Two openings of the same logical board MUST present the same `BoardId` and the same set of `CellId`s.
|
||
|
||
## 2. Board type — `board_type`
|
||
|
||
One of `Grid` (a symbol grid), `VisualScene` (photo-based with hotspots, for emerging communicators), `Keyboard` (text input, for literate users), `Hybrid` (mixed symbol + text), `QuickAccess` (high-frequency phrases — the home board). The type is a rendering hint and a vocabulary-strategy marker; it MUST NOT change a cell's `position` semantics (§3 of SPEC).
|
||
|
||
## 3. Layout — `layout: GridLayout { rows: u16, cols: u16 }`
|
||
|
||
The grid dimensions. `capacity = rows × cols` is the maximum number of non-overlapping cells. A board MAY hold fewer cells than its capacity; absent positions render as empty grid (distinct from a `Blank` cell, which is an explicit, addressable reservation — see §5).
|
||
|
||
## 4. Position — `position: GridPosition { row: u16, col: u16 }`
|
||
|
||
0-indexed. A position is assigned once and is **immutable** for the life of the cell (motor stability — see [`motor_stability.md`](motor_stability.md)). No two cells on a board MAY share a position.
|
||
|
||
## 5. Content — `content: CellContent`
|
||
|
||
One of:
|
||
|
||
- `Symbol { symbol_id, label }` — a symbol referenced by registry id plus its text label. The label MUST survive round-trip even where the artwork cannot be rendered ([`../SPEC.md` §4]).
|
||
- `Text(String)` — plain text, for keyboard boards and literate users.
|
||
- `Photo { image_ref, label }` — a referenced image with a label, for visual scenes.
|
||
- `Blank` — an intentional, addressable empty. A `Blank` reserves its position to preserve the surrounding motor grid and MUST NOT be elided on round-trip.
|
||
|
||
## 6. Action — `action: CellAction`
|
||
|
||
What activation does: `Speak(text)`, `Navigate(BoardId)`, `Modifier(GrammarModifier)`, `Backspace`, `Clear`, `Predict`, `SpeakAll`, `Buffer(text)`. `Navigate` edges the board graph; `Modifier` applies a grammatical transform (`Plural`, `PastTense`, `PresentProgressive`, `FutureTense`, `Possessive`, `Negation`, `Question`, `Pronoun(name)`) to the message bar; `Buffer` adds to the message bar without speaking.
|
||
|
||
The board graph is the source of truth; a grid is one projection of it. A conforming editor MUST keep the `Navigate` edges referentially intact: deleting a board MUST report, not silently break, any cell that navigates to it.
|
||
|
||
## 7. Canonicality
|
||
|
||
A board serializes to the canonical interchange form of [SPEC §7](../SPEC.md). Round-trip MUST preserve every `position`, `content`, `action`, and `symbol_id` byte-for-byte. Conformance suite **C4** pins the wire round-trip; the published vectors live in [`../conformance/v1/`](../conformance/v1/).
|