# @hathor/characters

**Facade (shim) — CGI character packet contract only.** Character modeling logic
lives elsewhere; see the pointer table below.

## At a glance

- **Path:** `libs/hathor/characters`
- **Domain:** hathor (active)
- **Owner:** @GreyChimp
- **Docs:** [deep-dive](/docs/domains/hathor/deep-dive) ·
  [systems one-pager](/docs/systems/lib-hathor.md)
- **Nx project:** `@hathor/characters`

## Facade role

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

## The contract it owns

- `HathorCgiCharacterDefinition` — one character's engine-facing definition
  (appearance, costume designs, visual references).
- `HathorCharactersCgiPacket` — the packet envelope consumers exchange.
- `createHathorCharactersCgiPacket` / `validateHathorCharactersCgiPacket` /
  `serializeHathorCharactersCgiPacket` — build, check, wire-encode.

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

## Logic lives in

| Concern                                              | Where it actually lives                                          |
| ---------------------------------------------------- | ---------------------------------------------------------------- |
| Character entities, identity, traits, relationships  | `@hathor/domain-models` (`character`)                            |
| Physical appearance modeling                         | `@hathor/domain-models` (`character`)                            |
| Costume/wardrobe continuity, frame & shot references | `@hathor/pre-production`                                         |
| Character arcs (want/need/lie), arc validation       | `@hathor/ideation` (ladder) + `@yemaya/agents` quality-assurance |
| Ensemble balance & representation analysis           | `@yemaya/safety` (`EthicsManager`)                               |

## Adding logic here is a bug

New character behavior belongs in the owning library above — this facade should
only grow when the **packet 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`,
`@hathor/pre-production`), 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/characters
pnpm nx lint @hathor/characters
```