Style token format: three docs say RON, ADR-030 says KDL→rkyv and RON is dead

Источник: dev/fera-research/docs/oc1/002-style-token-ron-vs-kdl.md (read-only; сгенерировано scripts/sync-docs.mjs)

Style token format: three docs say RON, ADR-030 says KDL→rkyv and RON is dead

• kind: problem
• area: ui / modules
• evidence:
  • /home/nikki/dev/fera/project-design/context/ADR.md:1021-1031 — ADR-030 (Accepted): “Style token format: KDL source → rkyv binary. Authors write theme.kdl (human-readable); a compile step produces theme.rkv (rkyv archive) that the runtime mmaps for zero-copy token access… RON stays where it belongs — Lattice manifests (Rust-typed data).” Context at ADR.md:1008-1011 says explicitly that RON “was doubted as a token format — too human-oriented for runtime data”.
  • /home/nikki/dev/fera/project-design/context/ADR.md:282-285 — ADR-029 (Accepted, never amended): “three native dylib axes (Engine / Feature / Native) + Style as a data layer** (RON token files, structurally the same as the Lattice themes/ subtree…)”.
  • /home/nikki/dev/fera/project-design/context/TECHSPEC.md:269-272 — “Style: declarative data, not a dylib (ADR-029) — RON token files (colors.ron, typography.ron, spacing.ron, geometry.ron, icons), per-OS aesthetic sets”.
  • /home/nikki/dev/fera/project-design/context/RFC.md:131 — “Style is a declarative data layer (tokens, RON) loaded…”.
  • FUTURE-CHECKS.md:44 — still uses RON for “module manifests (RON source of truth → Turso queryable copies)”.
  • /home/nikki/dev/fera/project-design/context/OQ.md:1031 — no OQ of that number; the style-format question was raised inside ADR-030 and never filed as an OQ.
• severity: mid

Суть / Substance

ADR-030 was written after ADR-029 and explicitly reverses its format choice (RON → KDL source compiled to rkyv), but ADR-029 was not amended, so ADR.md simultaneously asserts two different token formats for the same subsystem. TECHSPEC §6 and RFC both still specify RON.

Why this matters mechanically, not just editorially:

• The two formats have incompatible loading models. ADR-030:1036-1037 makes theme load “an mmap + pointer fixup, not a parse — theme file size stops being a startup cost”. RON cannot do that; it needs a full parse into owned values at boot. So the two answers have different startup-cost, allocation and cache-behaviour consequences, which is exactly the class of thing the decision was made for.
• ADR-029:283-285 justifies RON by convergence with “the Lattice themes/ subtree — an intentional convergence”. ADR-030:1031 guts that justification by re-assigning RON to Lattice manifests. The convergence argument no longer exists, but nothing rewrote it.
• An implementer reading TECHSPEC §6 (the “concrete, buildable breakdown” per README.md:20) writes a RON loader; an implementer reading ADR-030 writes a KDL→rkyv compiler + .fera-cache/theme.rkv cache. Both are then “wrong” per the other doc, and a third party reading ADR-029 alone gets yet another answer.

Варианты решения (tradeoffs)

• (A) Amend ADR-029 with a format addendum (KDL→rkyv is the decision; keep the “Style is data, not a dylib” half of ADR-029 untouched).
• (B) Revert to RON — one fewer build tool, one fewer cache tier, no kdl crate dependency (ADR-030:1028-1030 already flags the kdl crate as “in maintenance lull… ~2–3k lines and forkable if needed”). Costs the mmap/zero-copy win and re-introduces a parse at boot.
• (C) KDL authoring + RON runtime (hybrid): KDL is far nicer to hand-edit, RON is trivial to parse and needs no cache. Keeps ADR-030’s authoring win, drops its zero-copy win.

Предлагаемое решение

(A) — amend ADR-029, do not revert. ADR-030’s reasoning (theme size as a startup cost; rkyv already the serialization boundary per ADR-007) is the stronger argument, and its kdl fork risk is small and pre-planned.

Concretely:

1. ADR-029 gets a “Format addendum → see ADR-030” paragraph replacing RON token files with theme.kdl → theme.rkv.
2. TECHSPEC §6 line 269 and RFC line 131 get the same one-line pointer.
3. The “structurally identical to the Lattice themes/ subtree” claim in ADR-029 must be restated as a naming/structure convergence only, since ADR-030 moves the format away from Lattice’s.
4. Note for whoever implements: the theme pipeline needs a kdl → rkv build/cache tool (ADR.md:1038-1040 calls it “a second small tool”), and that tool is not in the TECHSPEC §0 workspace layout (TECHSPEC.md:41-43 lists only manifest-signer and bench-scene under /tools/) — a concrete missing entry, not just prose.