Skip to content

Tier 1 YAML-First Authoring — Round 4 Review

Not SHIP. I found 3 factual issues that still do not match the current codebase.

1. Glossary still misstates Area vs Zone

  • Doc: docs/designs/authoring/tier1-yaml-first-authoring.md:23-24
  • Claim: "Area" is only an informal synonym for Zone and is not a separate data concept.
  • Code: packages/maid-engine/src/maid_engine/core/world.py:112,468-482 stores and manages _areas via register_area(), get_area(), and all_areas(). packages/maid-stdlib/src/maid_stdlib/api/admin/world.py:1046-1081 exposes /areas and lists concrete area records.
  • Why this is wrong: In the current codebase, Area is a real runtime concept. The doc can still propose a future Zone authoring model, but it should not describe Area as merely an informal synonym with no separate data concept.

2. Schema inference description is still inaccurate

  • Doc: docs/designs/authoring/tier1-yaml-first-authoring.md:1112-1115
  • Claim: When _meta.schema is omitted, the pipeline infers entity type from the filename or directory name.
  • Code: packages/maid-engine/src/maid_engine/loader/phases/prepare.py:224-265
  • Why this is wrong: _resolve_schema() infers from the top-level collection key (rooms -> room, etc.) and/or the parent directory name. It does not infer from the filename.

3. Appendix A still presents unsupported top-level NPC fields as if they are current authoring fields

  • Doc: docs/designs/authoring/tier1-yaml-first-authoring.md:4255-4264
  • Claim/implication: Top-level stats, health, mana, combat, inventory, dialogue, schedule, needs, and goals are listed as NPC-specific fields, but several are only labeled "author-friendly" without the explicit "requires Assembly Layer" warning, and others have no proposed warning at all.
  • Code: docs/designs/authoring/tier1-yaml-first-authoring.md:882-893 correctly says the Assembly Layer is not implemented and only component-centric components: YAML works today. Current loader validation only allows NPC top-level field location: packages/maid-engine/src/maid_engine/loader/entity_types.py:15-20 and packages/maid-engine/src/maid_engine/loader/assembler.py:55-79.
  • Why this is wrong: Those top-level component shorthands are not loadable today. Appendix A.4 still underspecifies that status, which directly conflicts with the code and the document's own earlier caveat.

Quick checklist results

  1. DataDrivenContentPack marked PROPOSED? Yes (:251-257)
  2. Assembly Layer marked PROPOSED with current format shown? Yes (:882-893, :899-918)
  3. maid data diff/export/watch marked PROPOSED? Yes (:3851-3852, :3888-3889, :3918-3919)
  4. assembly_rule on EntityTypeConfig marked proposed addition? Yes (:1089-1096)
  5. NPC autonomy enums match code? Yes for the checked values (:1533-1557 vs packages/maid-stdlib/src/maid_stdlib/models/npc/autonomy.py:18-37)
  6. All author-friendly YAML examples have PROPOSED callouts? Mostly, but Appendix A.4 still under-warns unsupported top-level fields
  7. Canonical format includes room-specific exits/zone allowance? Yes (:169-175; code: packages/maid-engine/src/maid_engine/loader/entity_types.py:7-13)
  8. Area vs Zone properly distinguished? No
  9. Component fields spot-check correct? Checked HealthComponent, InventoryComponent, NPCComponent, CombatComponent: okay
  10. _meta.schema used everywhere, no _schema? Yes in the document text/examples I checked