Cross-Cutting Review — Round 3¶
Verdict¶
NO-SHIP
Round 2 did not fully land. Two cross-tier issues remain genuinely unresolved: one HIGH (canonical format still ambiguous/inconsistent) and one MEDIUM (Area vs Zone terminology still not standardized across tiers/code).
R2 Fix Verification¶
| # | Check | Result | Evidence |
|---|---|---|---|
| 1 | Same canonical format across all three tiers (component-centric + _meta.schema) |
FAIL | Tier 1 defines canonical as component-centric with _meta.schema and says author-friendly top-level fields like exits require Assembly Layer; only canonical is loadable (tier1-yaml-first-authoring.md:24-25, :161-166, :875-877). Tier 2 still shows generated room YAML with top-level exits/zone (tier2-ai-content-pipeline.md:399-406, :434-436, :4644-4659) while also claiming it does not introduce new formats (:198). Tier 3 first says export is Tier 1 canonical format and the same format as @export (tier3-visual-tools.md:1073-1076), then says visual-editor export actually normalizes to the Tier 1 authoring format with top-level exits (:1093-1185). Code confirms the split: @export emits only components + tags (packages/maid-stdlib/src/maid_stdlib/commands/building/export.py:133-151), while the loader separately allows room top-level exits and zone (packages/maid-engine/src/maid_engine/loader/entity_types.py:7-13). |
| 2 | No _schema remnants anywhere |
PASS | Exact search for top-level _schema: across the three tier docs returned no matches. _meta.schema is used instead. |
| 3 | Area vs Zone standardized across all three docs | FAIL | Tier 1 says Area is only an informal synonym and "not a separate entity type or data concept" (tier1-yaml-first-authoring.md:23). Tier 2 says Area means a multi-entity bundle document (tier2-ai-content-pipeline.md:670-675, :4818-4820). Tier 3 says Area is a room metadata label/API field (tier3-visual-tools.md:21-22). Code also exposes real area_id / area_name fields in the admin world API (packages/maid-stdlib/src/maid_stdlib/api/admin/world.py:42-49). These are three different meanings, not one standardized term. |
| 4 | Tier 2 has export-to-canonical rule for in-game AI output | PASS | Explicitly stated: @ai.accept mutates live state only; canonical YAML requires explicit export via maid data export or visual-editor export (tier2-ai-content-pipeline.md:3834-3838). |
| 5 | Tier 3 WebSocket uses lowercase names consistent with enum | PASS | Tier 3 proposes metrics, entities, logs, events, plus editor and world as lowercase enum values (tier3-visual-tools.md:628-675). Existing code enum is also lowercase (packages/maid-engine/src/maid_engine/api/admin/websocket.py:185-191). |
| 6 | Balance analysis ownership is clean (Tier 2 backend, Tier 3 UI only) | PASS | Tier 2 owns generation/analysis pipeline behavior; Tier 3 only consumes it as optional UI capability (tier3-visual-tools.md:3323-3337). No contradictory backend logic is assigned to Tier 3. |
| 7 | Source of truth clearly defined across tiers | PASS | Tier 1 says YAML is canonical and world→YAML is explicit export (tier1-yaml-first-authoring.md:148-166). Tier 2 matches that for AI output (tier2-ai-content-pipeline.md:3834-3838). Tier 3 states YAML is canonical for repeatable content and live world is runtime-authoritative, with explicit export required (tier3-visual-tools.md:143-166). |
| 8 | Terminology consistent | FAIL | The Area/Zone split above is a real terminology inconsistency, so terminology is not yet fully consistent cross-tier. |
| 9 | CLI commands don’t conflict | PASS | maid data ... (Tier 1), maid ai ... (Tier 2), and maid world map (Tier 3) are namespaced distinctly in the docs; no real command collisions found. |
| 10 | Tier dependencies non-circular and clearly stated | PASS | Tier 3 depends on Tier 1 and only optionally integrates with Tier 2 (tier3-visual-tools.md:7-8, :3320-3337). No circular dependency is described. |
Remaining Cross-Tier Issues¶
HIGH — Canonical format is still not actually standardized across tiers¶
This was the main R2 cross-cutting risk, and it is still present.
- Tier 1 says the canonical interchange/storage format is component-centric YAML with
_meta.schema, and that top-level author-friendly fields likeexitsare a separate dialect requiring the proposed Assembly Layer (tier1-yaml-first-authoring.md:24-25,:161-166,:875-877). - Tier 2 still presents generated room output with top-level
exitsandzonewhile claiming its output matches the existing component-centric schemas exactly (tier2-ai-content-pipeline.md:198,:399-406,:434-436,:4644-4659). - Tier 3 is internally contradictory: it first says export uses Tier 1 canonical format and is the same as
@export, then later says visual-editor export must emit the Tier 1 authoring format with top-levelexits(tier3-visual-tools.md:1073-1076,:1093-1185). - Code reflects both shapes rather than one settled contract:
@exportis component-centric only, but the loader allows room top-levelexits/zone(export.py:133-151,entity_types.py:7-13).
Why this matters: the docs still do not define one unambiguous canonical round-trip format for Tier 1 / Tier 2 / Tier 3. That means export/import, AI output, and visual-tool round-tripping are still specified against different shapes.
Required fix: choose one contract and make all three tiers say the same thing. If top-level exits/zone are canonical exceptions, Tier 1 glossary/assembly language must be updated. If component-centric @export is canonical, Tier 2 and Tier 3 examples/rules must stop calling the authoring shape canonical.
MEDIUM — Area vs Zone is still overloaded, not standardized¶
Round 2 asked for one consistent concept. The docs still carry three meanings:
- Tier 1: Area is merely an informal synonym for Zone and not a separate data concept (
tier1-yaml-first-authoring.md:23). - Tier 2: Area is a multi-entity bundle document name (
tier2-ai-content-pipeline.md:670-675,:4818-4820). - Tier 3: Area is a room metadata label/API field (
tier3-visual-tools.md:21-22). - Code: the engine/admin APIs really do have
area_id/area_name(packages/maid-stdlib/src/maid_stdlib/api/admin/world.py:42-49).
Why this matters: the same term still means UI filter metadata, file bundle concept, and “just a synonym” depending on tier. That is not standardized terminology.
Required fix: either (a) formally define Area as a legacy/runtime API concept distinct from Zone and use that definition everywhere, or (b) remove Area from the new authoring model and explicitly map any legacy area_id fields to Zone terminology at the boundary.
What Convinced Me¶
I spot-checked all three docs plus the relevant code paths instead of relying on wording alone:
- Loader schema resolution reads
_meta.schema(packages/maid-engine/src/maid_engine/loader/phases/prepare.py:224-261). - Loader room config still allows room top-level
exits/zone(packages/maid-engine/src/maid_engine/loader/entity_types.py:7-13). @exportstill serializes component-centric entity payloads only (packages/maid-stdlib/src/maid_stdlib/commands/building/export.py:133-151).- Tier 3’s export/import section is self-contradictory on whether canonical ==
@exportoutput or canonical == authoring shape.
So this is not a cosmetic wording nit: the cross-tier contract is still materially ambiguous.