Skip to content

W-067: ecs-relations names, paths, and lookup (REL-F07)

Type: feature · Size: M · Epic: E-relations-v0 · Target: packages/ecs-relations · Breaking: no Depends: W-060, W-066 Refs: spec REL-120..REL-135 (group REL-F07; KL3, KL7, KL8); REL-135 is the README section

Goal

Implement the Name trait, getPath(world, entity, { from? }), and lookup(world, path, { from? }) in packages/ecs-relations, built on the ChildOf helpers of W-066. Paths join names with /; unnamed entities appear as #<id> and are not resolved by lookup.

Steps

  • S1 (REL-120, REL-121, REL-122): Name is a SoA trait with value defaulting to ''; getPath returns the names from the root to the entity joined by /, with #<id> for unnamed segments; files: packages/ecs-relations/src/name.ts, packages/ecs-relations/src/path.ts, packages/ecs-relations/src/index.ts, packages/ecs-relations/tests/get-path.test.ts
  • S2 (REL-123, REL-124, REL-125): getPath with from returns the path relative to an ancestor ('' for self) and throws naming getPath when from is not an ancestor; it throws on a parent cycle and on a name containing /; files: packages/ecs-relations/src/path.ts, packages/ecs-relations/tests/get-path-errors.test.ts
  • S3 (REL-126, REL-127, REL-128, REL-129): lookup resolves segments from the roots, then the children of each match; from resolves relative to the children of from and throws naming lookup if from is not alive; sibling duplicates return the lowest id; unnamed entities never match, and empty paths or empty segments return undefined; files: packages/ecs-relations/src/lookup.ts, packages/ecs-relations/src/index.ts, packages/ecs-relations/tests/lookup.test.ts
  • S4 (REL-130, REL-131, REL-132, REL-133, REL-134): a rename or reparent is seen immediately by lookup and getPath; the round trip lookup(getPath(e)) === e holds for unique sibling names; a named child is not a root and a named root is not a child; getPath and lookup throw naming the function for a dead or foreign entity argument; files: packages/ecs-relations/tests/lookup-consistency.test.ts, packages/ecs-relations/src/lookup.ts, packages/ecs-relations/src/path.ts
  • S5 (REL-135 [manual]; changeset): README section stating that lookup scans without an index, that names are not unique unless the caller makes them so, that / cannot appear in names used with paths, and that #id segments are for display only; files: packages/ecs-relations/README.md, .changeset/w-067-ecs-relations-names.md (patch, @workspace/ecs-relations)

Log

  • 2026-11-01 created (Triage), split from the approved spec W-008
  • 2026-11-01 placed in Later (Depends W-060 and W-066 not done)
  • 2026-11-02 moved from Later to Next (Triage): W-060 done, size M, target and Goal filled; second step of the demo-ck3 path, after W-066