W-008: ecs-relations spec (v0): relations, traversal, hierarchies¶
Type: design · Size: S · Epic: E-relations-v0 · Target: docs/specs/ecs-relations.md · Breaking: no
Depends: –
Refs: concept (§4 gap rows for transitive/symmetric, traversal, and hierarchies (ChildOf, names, paths), §6 @workspace/ecs-relations, §8 demo-ck3 mapping); flecs Relationships; flecs component traits (Symmetric, Transitive, Traversable); flecs hierarchies (ChildOf, names, paths, up/cascade traversal)
Goal¶
Write docs/specs/ecs-relations.md with SpecWriter for the v0 of ecs-relations, covering three areas:
- Relation traits: symmetric(rel) (mirrors pairs through onAdd/onRemove hooks) and transitive(rel) (isReachable(a, rel, b) and an optional materialized closure kept in sync by hooks).
- Traversal: helpers up(entity, rel, trait) and cascade(query, rel) (depth-first, depth-ordered iteration).
- Hierarchies: ChildOf parent-child relation, the Name trait, and path lookup.
Use the flecs docs as prior art only, and state the koota public-API limits the package works within. When the spec is approved, Triage creates the feature items.
Steps¶
- S1: write
docs/specs/ecs-relations.mdwithSpecWriterusingspec-formatrequirement groups for the v0 scope: relation traits (symmetric, transitive), traversal (up,cascade), and hierarchies (ChildOf, names, paths); files: docs/specs/ecs-relations.md - S2: user approves the spec
Log¶
- 2026-11-01 created from Later placeholder, promoted Later -> Next, epic – -> E-relations-v0 (Triage)
- 2026-11-01 scope extended by user decision:
ChildOf,Nameand path lookup are now in scope; title, Goal, Refs and S1 updated; size kept S (one spec document, one step); epic outcome extended (Triage) - 2026-11-01 started: Next -> Now, state active (Triage)
- 2026-11-01 S1 done and reviewed (APPROVED after 1 change round); spec draft; active -> review, awaiting user approval of S2 (Triage)
- 2026-11-01 S2 done: user approved the spec; review -> done; follow-up items W-060 to W-068 created (Triage)