# @hathor/timeline

**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](/docs/domains/hathor/deep-dive) ·
  [systems one-pager](/docs/systems/lib-hathor.md)
- **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
```