Skip to content

W-007: ecs-serialize spec (v0): trait registry, JSON snapshots

Type: design · Size: S · Epic: E-serialize-v0 · Target: docs/specs/ecs-serialize.md · Breaking: no Depends: – Refs: demo-dnd brief (DND-F08, save and resume); demo-dnd spec (DND-F08 out of M1); ecs-schedule spec (schedule state fields for serialization); ecs-prefab spec (prefab serialization out of scope); concept; flecs JSON serialization (world, entity and query JSON); flecs reflection (runtime component reflection, for trait registry design)

Goal

Write docs/specs/ecs-serialize.md with SpecWriter for the v0 of ecs-serialize: a trait registry that maps stable names to koota traits, and JSON snapshots of a koota world (entities, trait values, relations) that can be restored into a fresh world. Cover per-world isolation (two worlds never share registry or snapshot state), and the error cases (unknown trait name, unregistered trait on save, malformed or mismatched snapshot). Use the flecs JSON and reflection docs as prior art only, and state the koota public-API limits the package works within. Out of v0: binary formats, prefab and schedule state serialization, migrations between snapshot versions. When the spec is approved, Triage creates the feature items.

Steps

  • S1: write docs/specs/ecs-serialize.md with SpecWriter using spec-format requirement groups for the v0 scope; files: docs/specs/ecs-serialize.md
  • S2: user approves the spec

Log

  • 2026-11-01 created from Later placeholder, promoted Later -> Next, epic – (Triage)
  • 2026-11-01 started: Next -> Now, state active (Triage)
  • 2026-11-01 S1 done: spec written by SpecWriter, docs/specs/ecs-serialize.md, Status: draft
  • 2026-11-01 awaiting user approval (S2): spec has 14 open questions (OQ1..OQ14); key decisions: scratch-world probe for relation traits (OQ6, koota 16-world limit), restore-after-reset (OQ7), Rng handling (OQ9), unverified koota behaviours (OQ12)
  • 2026-11-01 state active -> review (Triage)
  • 2026-11-01 epic – -> E-serialize-v0 (Triage)
  • 2026-11-01 S2 done: user approved docs/specs/ecs-serialize.md; open-question defaults accepted (Triage)
  • 2026-11-01 spec Status line still says draft; to be set to approved outside Triage scope (Triage blocked by hook)
  • 2026-11-01 review -> done (Triage)
  • 2026-11-01 follow-ups: W-052 (scaffold), W-053 to W-059 (SER-F01 to SER-F07, one per group) (Triage)