# Beat Composition

> Status: Current contract
> Authority: This note names the journal contribution pipeline alongside
> `JOURNAL_COMPOSE_CONTRACT.md`. The worked example is the
> `composed_beat_demo` world bundle and its loader test.

A journal step is a small **syuzhet** problem: the engine knows a set of
facts and consequences (the fabula), and the step's fragments are one
deliberate telling of them. The runtime already provides every channel that
telling needs; this note names them so mechanics and worlds compose beats
the same way instead of hand-rolling prose paths.

## The pipeline

One step's journal output is assembled in three moves:

**Gather.** `do_gather_ns` builds the scoped namespace: entity-local
`get_ns()` layers from the cursor and its ancestors (closest scope first),
then merged `gather_ns` dispatch contributions (later dispatch layers win).
Block content is rendered against this namespace with `format_map`, so any
named value — a *chunk* — is directly authorable as a `{placeholder}`.

**Enrich.** Extra fragments join the merged batch from two directions:
`render_journal` handlers contribute conditionally at render time, and
earlier phases (canonically UPDATE) stage delayed consequences through
`ctx.injected_journal_fragments`, which drain at the head of the merge.

**Compose.** `compose_journal` handlers fold over the merged batch in
dispatch order, each receiving the previous handler's output. This is where
the telling is shaped: reorder into slots, substitute what the viewpoint
cannot see, bind the result into a retrievable overlay.

## The override ladder

A named chunk can be defined — and overridden — at every scope, cheapest
first. Resolution order for a chunk read at the cursor:

1. **Block `locals:`** (authored YAML, no code)
2. **Ancestor `locals:`** — scene, then story containers, closest first
3. **`gather_ns` dispatch contributions**, merged later-wins across layers:
   AUTHOR beats APPLICATION beats SYSTEM; story-graph `locals:` beat world
   `locals:` within the story layer

Data overrides sit *above* handler overrides: an author writing
`locals: {dock_mood: ...}` on a block beats every registered handler. Use
data scopes for authored variation (skins, per-node mood) and handler
scopes for computed or stateful chunks.

A **narrative skin** is this ladder applied at presentation scale: one
selector chunk (`logic_skin` in `worlds/logic_demo`) chooses a sparse prose
overlay while the underlying machine stays untouched. Skins are a gather
concern (what the chunks say); beats are a compose concern (how the telling
is ordered). The two layers are orthogonal.

## The blessed stanzas

`tangl.journal.compose` names the recurring compose moves:

- `replace_first` — substitute the first fragment matching a predicate
  (the visibility/suppression move).
- `assemble_slots` — reorder the batch into named slots
  (`setting → incident → reaction → REST_SLOT` in the demo).
- `beat_overlay` — emit a `GroupFragment(group_type="beat")` whose
  `member_ids` bind the composed fragments and whose `content` names the
  beat. Segmentation-aware retrieval (`current_beat` style queries) slices
  on this overlay rather than re-deriving membership.

## Worked example

`worlds/composed_beat_demo` exercises every channel in one five-block
scene; `engine/tests/loaders/test_composed_beat_demo_world.py` pins one
channel per assertion. Mapping:

| Channel | Demo element |
| --- | --- |
| data-scope chunk override | `dock_mood` in story vs block `locals:` |
| handler-scope chunk override | `porter_greeting`, APPLICATION vs AUTHOR `gather_ns` |
| conditional render enrichment | Maro's reaction, gated on `reputation` |
| cross-phase enrichment | manifest incident injected during UPDATE |
| composition | slot ordering, fog substitution, beat overlay |

## Boundaries

Everything in `JOURNAL_COMPOSE_CONTRACT.md` applies unchanged: composition
shapes the telling, it does not mutate state, dereference media, or make
client-format decisions. Chunks are ordinary namespace entries — they are
visible to predicates, media facets, and dialog binding for free, so no
journal-private expression system should be introduced.