Eve library

@hathor/timeline

Other

Revision 1

On this page

Facade (shim) — scene-order packet contract only. Timeline logic lives elsewhere; see the pointer table below.

At a glance#

  • Path: libs/hathor/timeline
  • Domain: hathor (active)
  • Owner: @GreyChimp
  • Docs: deep-dive · systems one-pager
  • Nx project: @hathor/timeline

Facade role#

This library owns exactly one thing: the narrative scene-order packet contract that engine- and edit-facing consumers import, validate, and serialize. It holds no timeline modeling logic of its own and must not grow any.

The contract it owns#

  • HathorTimelineSceneOrderPacket — the ordered scene sequence consumers exchange, with its era/time-period anchors.
  • createHathorTimelineSceneOrderPacket / validateHathorTimelineSceneOrderPacket / serializeHathorTimelineSceneOrderPacket — build, check, wire-encode.

Golden-file round-trip contract tests (src/cgi-packet-contract.spec.ts) cover the shape, so consumers get explicit breakage instead of silent drift.

Logic lives in#

Concern Where it actually lives
Eras, time periods, world dates, calendars @hathor/domain-models (timeline)
Historical events, causality, chronology validation @hathor/validation + @hathor/domain-models (timeline)
Story beat ordering & act structure @hathor/ideation (ladder frameworks)
Traversal/runtime progression through story nodes @hathor/narrative (story-graph)

Adding logic here is a bug#

New timeline behavior belongs in the owning library above — this facade should only grow when the scene-order contract changes. A guard test (src/facade-guard.spec.ts) enforces that the source stays under a line budget and that imports resolve only to public entry points (@hathor/domain-models), never deep implementation paths. If the guard fails, move the logic to its owning library rather than raising the budget.

Commands#

bash
pnpm nx test @hathor/timeline
pnpm nx lint @hathor/timeline