Skip to content

Cross-Cutting Review R2

Verdict: NOT SHIP

Previous review items

  • Incompatible YAML formats across tiers: Partially fixed, still open. Tier 3 now aligns its export/import examples to _meta.schema + component-centric payloads, but Tier 1 still contains lingering _schema examples and still presents author-friendly YAML as a parallel first-class format. Evidence: Tier 1 §5 (tier1-yaml-first-authoring.md:856-1017), Tier 1 schema export example (2189-2235), Tier 1 migration example (2124-2136), Tier 2 principle (198-199), Tier 3 canonical export (1057-1137).
  • No single source of truth defined: Fixed. Tier 1 clearly makes YAML canonical for repeatable content and export explicit (140-210); Tier 3 mirrors that with live-world/runtime nuance (143-167).
  • Tier 3 YAML was a third format: Fixed. Tier 3 now explicitly says its YAML matches Tier 1 / @export (1057-1137).
  • WebSocket endpoint inconsistencies: Partially fixed, still open. Tier 3 standardizes on /admin/ws, but its message format details are still internally inconsistent (see issues below).
  • Terminology drift: Still open. “Area” vs “Zone” remains inconsistent across tiers.
  • Balance analysis duplication: Partially fixed, still open. Tier 3 delegates some AI suggestions to Tier 2, but still defines separate balance data flows/endpoints without explicitly reusing Tier 2 analyzers.
  • Export concept overlap: Mostly fixed. Tier 1 and Tier 3 now consistently treat export as an explicit snapshot, not automatic sync.

Current issues

1) HIGH — Tiers 1, 2, 3 — YAML canonical format is still ambiguous

What’s wrong: Tier 2 and Tier 3 both describe the Tier 1-compatible/canonical machine format as _meta.schema + component-centric payloads (tier2...:198-199, tier3...:1057-1137), but Tier 1 still treats author-friendly YAML as a co-equal first-class format (tier1...:856-1017). That can work operationally, but the docs still do not name one canonical interchange/storage format versus one authoring dialect. Suggested fix: State explicitly: “Canonical interchange/export format is component-centric with _meta.schema; author-friendly YAML is a Tier 1 authoring dialect normalized by the Assembly Layer.”

2) HIGH — Tier 1 — _schema remnants reintroduce the old schema format

What’s wrong: Tier 1 still shows _schema in the JSON Schema export example (tier1...:2215-2218) and even in the migration adapter (2131-2136), despite §6 standardizing _meta.schema (1031-1042). Suggested fix: Replace all remaining _schema references with _meta.schema, including JSON Schema examples and migration code snippets.

3) HIGH — Tiers 1, 2, 3 — “Area” vs “Zone” is still not standardized

What’s wrong: Tier 1 defines Zone as the formal grouping concept (tier1...:19-24), Tier 3 says Area is only a metadata label and not a formal entity type (tier3...:17-25), while Tier 2 exposes maid ai generate area and writes data/areas/*.yaml as if “area” is a first-class authoring artifact (tier2...:676-697). Suggested fix: Choose one model and apply it everywhere: either (a) “zone” is the formal authored unit and “area” is UI metadata only, or (b) “area” is a generated bundle/document but not an entity type. Then rename commands/files/examples accordingly.

4) MEDIUM — Tier 2 vs Tiers ⅓ — in-game AI authoring is missing the canonical export/reconciliation story

What’s wrong: Tier 1 and Tier 3 clearly say live-world edits become canonical only through explicit export (tier1...:199-210, tier3...:158-167, 2848-2871). Tier 2’s @ai generate / @ai.accept flow stages then creates entities in the world (tier2...:3763-3829) but never says how accepted content becomes canonical YAML. Suggested fix: Add one explicit rule to Tier 2: accepted in-game AI output mutates live state only; persist it through maid data export (or visual-editor export) before treating it as canonical content.

5) MEDIUM — Tier 3 — WebSocket message contract is internally inconsistent

What’s wrong: Tier 3 defines enum values as lowercase wire strings like editor_cursor / room_created (tier3...:654-673), but Appendix B uses uppercase message types like EDITOR_CURSOR, ROOM_CREATED, and even EDITOR_LOCK_ACQUIRE which is not listed in the earlier enum set (3275-3399). Suggested fix: Pick one wire format (prefer lowercase, matching existing code style in packages/maid-engine/src/maid_engine/api/admin/websocket.py:160-191) and make Appendix B match it exactly; add any missing inbound message types explicitly.

6) MEDIUM — Tiers 2 and 3 — balance analysis ownership is still blurry

What’s wrong: Tier 2 defines concrete reusable analyzers (tier2...:3176-3525), but Tier 3 separately defines a balance dashboard backed by /admin/balance/* endpoints and “data aggregated from entity components” (tier3...:2222-2287, 3232-3253) without stating those endpoints are adapters over Tier 2 analyzers. Suggested fix: Declare Tier 2’s balance engine as the single backend for all balance calculations; Tier 3 should consume it only as UI/API presentation.

Overall assessment

The doc set is much better than the prior round: source-of-truth, export semantics, Tier 3 YAML alignment, and tier dependency direction are substantially clearer. But it is not ready to ship until the YAML canonical-format ambiguity, _schema leftovers, Area/Zone drift, and Tier 3 WebSocket contract mismatch are cleaned up.