docs(specs): add spec 85 for truthful health and hold-then-swap cuts

[hyperb1iss]

Draft for review. Spec only; no code. Phase 1 is ready to implement once accepted; Phase 2 has open decisions listed in §9.1.

Every effect change today replaces a zone's layer stack and lets the new producer warm up in public. HTML effects flash a placeholder frame, the layer reports Active before it shows a real pixel, a page that fails to load stays Active forever with the placeholder on the LEDs, and nothing reports when a cut actually reached the devices. A scripted rehearsal of the demo film against the owner's rig measured each of these, and they make a beat-synced cut impossible. Spec 85 defines how the engine fixes them without lowering any performance baseline.

What this changes

The spec adds docs/specs/85-show-grade-cuts.md:

• Phase 1, truthful health. Every runtime producer gets an incarnation id. Every layer source declares its readiness (required, no default), placeholders are deleted in every build, a failed load is Failed exactly once, Degraded and Stalled are emitted honestly, deadlines survive session sleep, and GET /scene/runtime lets a reconnecting client recover the current truth. SDK pages get a minimal init and origin-frame handshake so readiness means real pixels.
• Phase 2, hold-then-swap. A zone keeps presenting its current graph, live, until every incoming producer has real output or has failed; geometry changes and interrupted scene transitions hold an immutable still instead of going empty; activation blends per physical target; and every cut ends with a terminal delivery outcome for every target it was routed to, with monotonic latency from the request's arrival.
• Follow-up, zone cues. Preparing an effect before the beat is the only way a cut to an HTML effect can land on it. That needs capacity admission measured from Phase 2, so it is deferred to its own spec, with every requirement the reviews surfaced recorded in §10.

Why

The film's cuts have to land on the music on real hardware, and the rehearsal showed the engine cannot do that or even report honestly whether it did. The evidence (raw runner reports and the daemon's audit log for the rehearsal windows) is committed on nova/demo-video under demo/evidence/.

Verification

• Added or updated tests
• Added or updated docs (README, AGENTS.md, relevant spec, or guide)
• just verify passes locally (Rust fmt + lint + test)
• just deny passes (required for dependency or license changes)
• just ui-test and just ui-build pass (required for crates/hypercolor-ui/)
• just sdk-lint, just sdk-check, and just sdk-build pass (required for sdk/)
• just python-verify passes (required for python/)
• just compat-check passes (required for data/drivers/vendors/*.toml)
• just docs-build passes (required for docs or README changes)
• cd docs && zola check passes (required for docs link/content changes)
• Packaging scripts were syntax-checked (required for scripts/ or packaging/)
• just e2e-build passes with the normal Servo stack (required for daemon/UI/effect integration changes)
• just e2e-build-cpu passes when validating the CPU smoke fallback
• just e2e passes against the Servo stack (required for end-to-end behavior changes; starts daemon/browser)
• Tested on real hardware, simulator, or e2e harness (describe below)

The spec went through five rounds of independent review against the code, each citing file and line receipts. Findings fell from 20 (5 blocking) to 18, 14, 8, and finally 5 open Phase 2 decisions with no blocker; §12 records each round's dispositions. The last round judged Phase 1 fully specified. The spec lives under docs/specs/, outside the Zola site, so the docs gates do not apply.

Notes for reviewers

• Start with §0 for the goals and the doctrine (no lowered baselines, no capacity refusal of live actions), then §2 and §3.
• §9.1 lists the Phase 2 decisions still open and a pre-existing doctrine conflict the review found: live media admission caps video counts and downshifts the FPS tier from estimated cost.
• The spec amends Spec 78's LayerHealth semantics and Appendix A (one route), and the effect-error fallback policy.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}