gnommo/docs/atomic_events.md

# Atomic Events — Design Spec

Status: **Stage A + Stage B implemented (2026-07-27).** Motivated by a future **Glitch
Studio GUI** that edits each video occurrence as a self-contained object.

Implemented:
- Per-occurrence presentation resolves via `transformer.resolve_video_presentation`
  (precedence: inline/GUI override > shorthand prefix > videos.json > default; video
  `end_on` default = `next_video`, `[narration:]` runs to end).
- events.json is materialized/atomic: `derive_events` writes `handle/cutout/layer/end_on/
  take`; `events_to_marker_timings` round-trips them as overrides.
- Inline grammar `[prefix:handle, key=value, …]` (`parser.parse_marker`), threaded through
  alignment into `MarkerTiming.overrides`. Supported inline keys: **cutout, layer, end_on,
  take** (the fully-wired per-event fields). Unknown keys are ignored.
- The key-reuse collision validator hard-error was removed (reuse is legal now).

Deferred (follow-ups): inline override of the *global* params (skip/zoom/volume/
use_audio_channels/pause_narration) — the renderer reads these from `video_source` in ~13
places, so wiring them per-event is a separate change; stripping the moved fields from
videos.json (kept as fallback defaults for now); a validator warning for unknown/unwired
inline keys.

## Problem

Presentation/timing properties (`cutout`, `layer`, `end_on`, `take`, `pause_narration`)
live on the **videos.json handle**, but they are really properties of *where a clip is
used*, not of the file. The shorthand prefix (`vst:` = square/above, `vsb:` =
square/below) is per-marker, but `_project_markers_to_videos` collapses it onto the
single handle record (last-wins). So one handle used two ways collides:

- `[vst:glitch_ccd_binning]` (above) and `[vsb:glitch_ccd_binning]` (below) → videos.json
  can only store `layer: below`, so the first occurrence renders under the slide (hidden).
- video5 has 5 such collisions today (glitch_ccd_binning, pexels/12471039…,
  mainvideopart1, shotnoiseacc, slide_periodogram).

A stopgap validator hard-error (`validate_project`, gnommo/validator.py) currently blocks
render on these. This spec removes the *cause* so that guard is no longer needed.

The naive fixes are both rejected: copying the file/handle (duplication on disk), and a
"hybrid override + materialize" layer (too much indirection). Instead: **the per-occurrence
properties move onto the event.**

## Field homes

**videos.json — asset + global defaults (one value per handle):**
`source_file`, `output_file`/`processed_file`, `filter`, `has_audio`, `is_shared`,
`src_mtime`, `duration` (probed; asset-only, never per-event), and the globals
`zoom`, `skip`, `volume`, `use_audio_channels`.

**events.json — per-occurrence (one value per event):**
`handle` (the video id, **prefix-free**), `cutout`, `layer`, `end_on`, `take`,
`pause_narration`.

**Resolution order for a rendered clip:** event field (if set) → videos.json value (for the
globals) → config default. The per-occurrence fields have no videos.json fallback — they
are always materialized onto the event at build time.

Notes:
- `end_on` **defaults to `next_video`** for videos when unspecified (was implicitly
  `next_slide`). Existing videos.json `end_on` values are migrated onto events explicitly,
  so current projects keep their behavior; only *new* unspecified markers get the new default.
- `take` is the event-level cut length, only meaningful when `end_on=take`; otherwise the
  end is implicit from `end_on` and `take` stays null.
- `skip` stays a global (asset trim-in) while `take` is per-event — a deliberate asymmetry:
  "where this asset generally starts" vs. "how long this occurrence plays."
- `zoom`/`volume`/`use_audio_channels` stay global but are inline-overridable per event
  (below), so they can diverge without a videos.json copy.

## Authoring: shorthand + inline overloads

The manuscript stays the compact authoring surface. The shorthand letters encode
`cutout`+`layer` (and `pause_narration` via the `…p:` variants). Anything the letters
don't encode — chiefly `end_on`, and any per-event override of a global — is given as
inline **`key=value`** pairs (simplified from the earlier `{"json":"form"}`):

```
[vsb:glitch_ccd_binning2]                          # square/below, end_on defaults to next_video
[vsb:glitch_ccd_binning2, end_on=next_video]       # + explicit end_on
[vsb:glitch_ccd_binning2, take=5, volume=0.5]      # + per-event overrides of globals
[video:glitch_ccd_binning2, cutout=square, layer=below]   # generic; equivalent to [vsb:…]
```

Rules:
- The first token inside `[]` is `prefix:handle` (handle may contain `/`, e.g. `pexels/123`).
- Remaining comma-separated tokens are `key=value`. Values are type-inferred: numeric →
  float, `true`/`false` → bool, else string. Allowed keys: `cutout`, `layer`, `end_on`,
  `take`, `skip`, `zoom`, `volume`, `use_audio_channels`, `pause_narration`,
  `always_visible`.
- An inline key overrides whatever the shorthand implied (e.g. `[vst:x, layer=below]` →
  above from the prefix, then below from the override). Last-writer-wins, prefix first.
- `[video:handle, …]` is the fully-explicit form the GUI round-trips: no prefix magic, every
  presentation field named.

Why `key=value` over JSON: no braces/quotes to escape inside `[]`, one obvious separator,
and it reads cleanly in a script. The GUI still stores the resolved values as real JSON
fields on the event — the manuscript form is just sugar that populates them.

## Build-time materialization

At build (`build_render_plan` / scaffold construction), each video marker resolves to an
atomic event dict:

```json
{
  "type": "video",
  "handle": "glitch_ccd_binning",
  "cutout": "square",
  "layer": "above",
  "end_on": "next_video",
  "take": null,
  "pause_narration": 0.0,
  "narration_time": 0.0, "adjustment": 0.0, "final_time": 0.0,
  "mapping": "exact", "confidence": 1.0, "context": "…"
}
```

`id` (currently `"vst:glitch_ccd_binning"`) is replaced by `handle` + explicit fields. The
render pass reads presentation straight off the event and no longer consults the prefix or
the videos.json presentation fields. `merge_events` must preserve manual event edits (the
GUI's writes) across rebuilds, the same way it preserves `adjustment` today.

## Code touchpoints

- **models.py** — `VideoSource` sheds `cutout`/`layer`/`end_on`/`take`/`pause_narration`
  (or they become defaults-only); `VideoEvent` already carries `cutout`/`layer`/`end_on` —
  extend to `take`/`pause_narration` sourced from the event, not the handle.
- **parser.py `parse_manuscript`** — extend the marker grammar to accept
  `prefix:handle, key=value, …`; update the malformed-marker detector (which today flags
  spaces/commas inside `[]`).
- **transformer.py `_extract_video_events`** — resolve `cutout/layer/end_on/take/
  pause_narration` from (prefix ∪ inline overrides), not from `video_source`.
- **scaffold.py** — event schema: `handle` + presentation fields; `merge_events` preserves
  GUI edits; migration for existing events.json.
- **cli.py** — retire `_project_markers_to_videos` and `_writeback_video_metadata` (they
  project/writeback per-handle presentation) in favor of seeding event fields.
- **validator.py** — **remove** the key-reuse collision hard-error (reuse is legal now).
- **renderer.py** — read presentation from the event (mostly already does via `VideoEvent`).

## Migration

Existing projects (video0–video6, …) have presentation on the handle and prefixed `id`s in
events.json. A one-shot migration, run on build:

1. For each video event, split the prefixed `id` into `handle` + implied `cutout`/`layer`.
2. Fill `end_on`/`take`/`pause_narration` from the handle's current videos.json values
   (preserving today's behavior — including handles that explicitly set `next_slide`).
3. Strip the moved fields from videos.json handles (leave the globals).
4. Idempotent: a second run is a no-op once events carry `handle`.

## Staging

- **Stage A** — schema split + per-event resolution from the shorthand prefix, migration,
  remove the collision guard. Shorthand-only authoring keeps working; the 5 video5
  collisions resolve. (This is the part that fixes the bug.)
- **Stage B** — the inline `key=value` overload grammar + malformed-marker updates.

Keep the validator collision hard-error in place **until Stage A lands** — removing it
earlier would let the hidden-overlay bug back in on video5.

## Open questions

- `always_visible`, `use_audio_channels`: confirmed as inline-overridable globals — do any
  need to become fully per-event?
- Does the GUI want events fully flattened (every field present) or sparse (only overrides,
  inherit the rest)? Affects whether the build writes defaults explicitly.