open-standards/aac/spec/motor_stability.md

AAC sub-spec — Motor stability

Normative refinement of SPEC §3. Reference: aac_core::board::Cell::{position, locked}.

A configured board's most valuable property is not its content but its geometry: the learned muscle memory of where each word lives. A user who reaches for "want" in the top-left does so without looking, often without conscious thought. Anything that moves "want" destroys that — and motor relearning for a person with a significant physical impairment can cost weeks. This sub-spec makes geometry an invariant, not a preference.

1. Positions are immutable

A cell's position MUST NOT change once assigned, for the life of the cell, except by an explicit user or editor edit to a cell whose locked flag is false. In particular, the following MUST NOT move a cell:

• prediction or frequency (Cell::frequency weights ranking, never placement);
• context, time of day, partner, or activity (any L3+ enrichment, cascade.md);
• language switching (a code-switch is a traversal, not a re-layout — access_model.md);
• "tidying", auto-fill, or alphabetization.

2. Locked boards do not reflow

A client MUST NOT reflow, resort, auto-arrange, or re-pack the cells of a board whose cells are locked. Adding a cell to a locked board MUST place it in a free position without disturbing any existing cell.

3. Hiding is in place

Progressive disclosure — hiding advanced vocabulary while a user is still learning — MUST be done by rendering a cell visually inactive at its position, never by removing it and collapsing the grid. A word that reappears later MUST reappear in the exact position it would have occupied all along. This is why CellContent::Blank exists: it reserves geometry against a future word.

4. Determinism across clients

Two openings of the same board — on the same client, on a different conforming client, before and after an interchange round-trip (§7–§8) — MUST present identical cell positions. Position assignment during ingest of a positionless source MUST be deterministic (row-major fill) and then fixed (see interchange.md).

5. Conformance

An implementation that violates §1–§4 is non-conformant regardless of any other quality. Motor stability is checked by opening a vector board, applying a frequency/prediction update, re-serializing, and asserting position-set equality against the input.