ADR-0007: Versioned builders and canon locks

Status: Accepted (2026-09-29)
Date: 2026-09-29

Context

Locked instances are canon and must never be silently regenerated. But the code that turns an instance into a rig, a set or a frame will keep improving: better line taper, a new eye style, a fix to skinning weights. Any such change would silently alter every existing character, which is regeneration by the back door.

Decision

Each builder (character, set, prop, fx, graphic) has a major version. Every instance records builder.major.
Any change that alters a builder's output for existing inputs ships as a new major, with the previous major kept alive. Golden geometry hashes and golden frames make an unversioned output change fail CI.
Locked instances keep their major. Migrating one to a newer major is a change set with before/after model sheets, approved like any other change.
Samplers are versioned too (meta.derivation.sampler). A new sampler version never touches existing instances. It only affects new draws, or re-derivations the user approves.
reelwright status reports canon drift: locked instances whose re-rendered model sheet no longer matches the approved one, whatever the cause.

Consequences

Old builder majors stay in the tree until no show uses them, which costs maintenance. reelwright migrate --builder character@2 gives shows a guided path forward.
Engine upgrades (new Godot versions) can change frames. They are handled like builder majors: golden diffs are reviewed, and canon drift is reported.

Addendum (2026-09-30): before 1.0

Until Reelwright 1.0 no real show has locked canon, and the builders are still improving quickly: poses, hands, style coverage. Before 1.0:

builder output may change within major 1;
every such change ships with deliberately updated golden frames and model sheets, reviewed by eye in the same change. The CI demo-render job enforces this: stale goldens fail.

From 1.0 on, the strict rule above applies.