writer: the rail owns mp, and the schema requires both documents

Two faults, both surfaced by swapping the writer model.

`mp` never survived a Write plan. `railRefs()` and `_pinned_refs()` dropped
the field, the model cannot author it (it is not in the prompt's valid-field
list), and Accept overwrites the register wholesale -- so every write
silently reset every cap to "full". chain_00047 ran three plates at 0.54 MP;
the next write put the same three back at native size, 3.23 MP of stills
against a 0.72 MP canvas, and the render came back as the reference
photograph instead of the beat. The rail is authoritative now: its value is
restored, and a value it does not have is REMOVED rather than left as
written. gemma4-26b read the units as pixels and returned 1000000000, which
cleared the 0.3 floor because there was no ceiling; refs.py has one, and the
rejection names the units.

SCHEMA.json had no top-level `required`, so a reply of {"shot_plan": ...}
alone was schema-valid. gemma4-26b emitted exactly that on all three
attempts: the register stayed empty, `_remap_pinned_tags` bailed on the
falsy ref_text before it could restore the rail's names, and every repair
turn was told its beats cited undeclared tags -- so it rewrote the beats it
had already got right and never emitted the document that was missing. Three
attempts and no convergence before; two attempts and ok after. Qwen3
volunteered both documents and hid this. `validate` also names the omission
directly, for use_schema=False and for servers that ignore the grammar.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014VB4Dw6F79643vySkf19KV

js/editor/ref_rail.js

@@ -387,12 +387,22 @@ export function createRefRail(node, { getPlan, setPlan, onChange, hopCount,
              * scales a reference DOWN -- a cap above the file's own size is a
              * dial wired to nothing, and a number there would imply upscaling
              * that never happens. */
-            const mp = select(REF_MP.map(String), r.mp ? String(r.mp) : "", (v) => {
+            /* A cap that is not one of the offered values still has to SHOW.
+             * `select` assigns a value matching no option, which renders the
+             * control blank -- and blank here reads as "full", so a row capped
+             * at 0.54 looked uncapped while it was working. Offer the row's
+             * own value alongside the standard ones. */
+            const mpOpts = REF_MP.map(String);
+            if (r.mp && !mpOpts.includes(String(r.mp))) {
+                mpOpts.push(String(r.mp));
+                mpOpts.sort((a, b) => Number(a) - Number(b));
+            }
+            const mp = select(mpOpts, r.mp ? String(r.mp) : "", (v) => {
                 r.mp = v ? Number(v) : 0;
                 commit();
             }, {
                 blankLabel: "full",
-                titles: Object.fromEntries(REF_MP.map((v) =>
+                titles: Object.fromEntries(mpOpts.map((v) =>
                     [String(v), `Cap this picture at ${v} MP before the encoder sees it.`])),
             });
             mp.classList.add("h3e-mp");

js/editor/writer_bar.js

@@ -333,6 +333,11 @@ export function createWriterBar(node, { onWritten, hopCount } = {}) {
                 subject: r.subject == null ? null : Number(r.subject),
                 retention: String(r.retention || ""),
                 desc: String(r.desc || ""),
+                // The writer never sees `mp` and cannot author one, but Accept
+                // replaces the whole register with what comes back. Send it up
+                // so the server can put it back, or every write silently
+                // resets every row to "full".
+                mp: r.mp ? Number(r.mp) : null,
             }));
     }
 

planner.py

@@ -157,6 +157,19 @@ def validate(shot_text, ref_text, *, hops=None, known_files=None, pinned=None):
         errors.append(f"the plan has {len(shots)} shot(s) but {hops} hop(s) "
                       f"were asked for. Write exactly {hops}.")
 
+    # An absent register is its own fault and has to say so. Reported only as
+    # undeclared beat tags it reads as a spelling problem, and a repair turn
+    # spends itself rewriting beats that were already right: gemma4-26b went
+    # @woman_face -> @ref_1 on attempt 2 and still shipped no `ref_plan`, three
+    # attempts, no convergence. The schema now requires both documents; this is
+    # the same guard for `use_schema=False` and for servers that ignore it.
+    if not str(ref_text or "").strip():
+        errors.append(
+            "the reply had no `ref_plan` document. Answer with BOTH JSON "
+            "documents: `shot_plan` and `ref_plan`. Every @tag a beat uses "
+            "must be declared as a `tag` in ref_plan.refs.")
+        return errors, warnings
+
     try:
         ref_plan = _refs.parse_ref_plan(ref_text)
     except Exception as exc:
@@ -529,6 +542,50 @@ def _merge_register(base_text, patch_text, keep=None):
     return json.dumps({"refs": refs, "subjects": subs}, indent=2)
 
 
+# Fields the RAIL owns and the model never authors. `mp` is a pixel budget the
+# person sets per row; it is absent from `schema()` and from the valid-fields
+# list in SYSTEM_PROMPT.md, so a written register cannot carry one. Accept
+# writes that register straight onto the rail, so without this a Write plan
+# silently reset every cap to "full": chain_00047 ran three plates at 0.54 MP
+# (1.58 MP total against a 0.72 MP canvas) and the next write put the same
+# three back at native size, 3.23 MP, which is the run that came back with the
+# reference photograph rendered instead of the beat.
+RAIL_ONLY_FIELDS = ("mp",)
+
+
+def _restore_rail_only(ref_text, pinned):
+    """Make the rail authoritative for its own per-row fields.
+
+    Authoritative, not merely restorative: a value the rail does not have is
+    REMOVED, it is not left as the model wrote it. `mp` is exposed in the
+    schema so a hand-authored plan can set one, which means a model can put a
+    number there too -- gemma4-26b read the units as pixels and returned
+    1000000000. On the pinned path the person owns that dial, so whatever came
+    back is discarded either way.
+    """
+    obj = _parse_obj(ref_text)
+    if not isinstance(obj, dict) or not pinned:
+        return ref_text
+    by_tag = {str(p.get("tag") or "").lstrip("@").strip(): p
+              for p in pinned if isinstance(p, dict)}
+    touched = False
+    for r in (obj.get("refs") or []):
+        if not isinstance(r, dict):
+            continue
+        row = by_tag.get(str(r.get("tag") or "").lstrip("@").strip())
+        if not row:
+            continue
+        for field in RAIL_ONLY_FIELDS:
+            value = row.get(field)
+            if value in (None, "", 0):
+                if r.pop(field, None) is not None:
+                    touched = True
+            elif r.get(field) != value:
+                r[field] = value
+                touched = True
+    return json.dumps(obj, indent=2) if touched else ref_text
+
+
 def _remap_pinned_tags(shot_text, ref_text, pinned):
     """Rename invented tags back to the rail's, matching on `file`.
 
@@ -789,6 +846,9 @@ async def write_plan(brief, hops, *, complete_fn, files=None,
                 ref_text = _merge_register(ref_text, new_refs, keep=rail_tags)
             else:
                 ref_text = new_refs
+            # Before validate, so a restored `mp` is what the lints and the
+            # returned plan both see, on the failure path as well as the ok one.
+            ref_text = _restore_rail_only(ref_text, pinned)
         if not shot_text:
             last_errors = ["the reply contained no JSON. Answer with the two "
                            "JSON blocks and nothing else."]

prompt_pack/SCHEMA.json

@@ -3,6 +3,10 @@
   "title": "H3 Ref Chain plans",
   "description": "Two documents. `shot_plan` goes in the shot_plan widget, `ref_plan` in the ref_plan widget. Generated by tools/gen_schema.py from the installed node -- do not edit by hand.",
   "type": "object",
+  "required": [
+    "shot_plan",
+    "ref_plan"
+  ],
   "properties": {
     "shot_plan": {
       "type": "object",
@@ -182,7 +186,8 @@
               "mp": {
                 "type": "number",
                 "minimum": 0,
-                "description": "Per-reference pixel budget in megapixels. 0 (or omit) means no cap. A set value has a 0.3 MP floor -- this is a token dial, so a location plate need not cost what a face costs."
+                "maximum": 16.0,
+                "description": "Per-reference pixel budget in MEGApixels, set by the person on the rail. Do not author it: omit the field. It is here so a hand-written plan can carry one, and a written value is discarded on the pinned path. A set value has a 0.3 MP floor and a 16 MP ceiling; 0 means no cap."
               }
             }
           },

refs.py

@@ -48,11 +48,17 @@ REF_FIELDS = ("tag", "file", "slot", "subject", "retention", "desc", "shots",
 # This is a TOKEN dial, not a quality one. H3 turns each reference into
 # `latent_h * latent_w` entries in the DiT payload and attends over all of them
 # on every step of every hop, so a location plate costing what a face costs is
-# waste. The floor is a picture you can still recognise a room in; there is no
-# ceiling, because H3 only ever scales a reference DOWN
-# (`min(1.0, ...)` in nodes_minimax_h3.py) and a cap above the file's own size
-# would be a dial wired to nothing.
+# waste. The floor is a picture you can still recognise a room in.
+#
+# The ceiling is a sanity rail, not a capability limit: H3 only ever scales a
+# reference DOWN (`min(1.0, ...)` in nodes_minimax_h3.py), so any cap above the
+# file's own size is already a dial wired to nothing and does no harm at render
+# time. It exists because a *model* can author this field, and one read the
+# units as pixels: gemma4-26b returned mp 1000000000, which passed the floor,
+# survived into the register and rendered in the rail as a dropdown full of
+# zeroes. Anything past this is a units mistake, not an intention.
 REF_MP_MIN = 0.3
+REF_MP_MAX = 16.0
 
 # Per-subject continuity text -- the half `HTCContinuityState` owned, moved here
 # so it is keyed by the same subject number that owns the picture ordinals.
@@ -172,6 +178,10 @@ def _norm_ref(raw, i):
         if mp < REF_MP_MIN:
             _fail(f"{where} (@{tag}): mp {mp:g} is below the {REF_MP_MIN:g} MP "
                   f"floor. Use 0 for no cap.")
+        if mp > REF_MP_MAX:
+            _fail(f"{where} (@{tag}): mp {mp:g} is above the {REF_MP_MAX:g} MP "
+                  f"ceiling -- this field is MEGApixels, not pixels. Use 0 for "
+                  f"no cap.")
 
     shots = raw.get("shots")
     if shots is not None:

routes.py

@@ -79,12 +79,21 @@ def _pinned_refs(raw, limit):
             subj = int(subj) if subj not in (None, "", False) else None
         except (TypeError, ValueError):
             subj = None
+        # `mp` rides along so planner._restore_rail_only can put it back on the
+        # written register. The model is never shown it and cannot author it,
+        # but Accept overwrites the rail with what comes back, so a cap that
+        # does not survive this round trip is a cap the next write deletes.
+        try:
+            mp = float(r.get("mp") or 0) or None
+        except (TypeError, ValueError):
+            mp = None
         out.append({
             "tag": tag,
             "file": fname,
             "subject": subj,
             "retention": str(r.get("retention") or ""),
             "desc": str(r.get("desc") or ""),
+            "mp": mp,
         })
         if len(out) >= int(limit):
             break

tools/check_planner.py

@@ -360,6 +360,49 @@ def main():
                           hops=2, known_files=kf)
     ck("the live plan is still accepted", not live)
 
+    # `mp` is the rail's, not the model's. It is absent from the schema, so
+    # every written register comes back without one -- and Accept overwrites
+    # the rail with that. chain_00047 ran three plates at 0.54 MP; the next
+    # Write plan put them back at native size (1.58 MP -> 3.23 MP against a
+    # 0.72 MP canvas) and the render came back as the reference photograph.
+    rail_mp = [{"tag": "ref_1", "file": "cook_face.png", "mp": 0.54},
+               {"tag": "ref_2", "file": "kitchen.png", "mp": 0.3}]
+    written = json.dumps({"refs": [{"tag": "ref_1", "file": "cook_face.png",
+                                    "subject": 1, "desc": "a face"},
+                                   {"tag": "ref_2", "file": "kitchen.png",
+                                    "retention": "reference",
+                                    "desc": "a kitchen"}],
+                          "subjects": {}})
+    back = json.loads(PL._restore_rail_only(written, rail_mp))
+    by_tag = {r["tag"]: r for r in back["refs"]}
+    ck("a written register gets the rail's `mp` back",
+       by_tag["ref_1"].get("mp") == 0.54 and by_tag["ref_2"].get("mp") == 0.3,
+       f"got {by_tag['ref_1'].get('mp')!r} / {by_tag['ref_2'].get('mp')!r}")
+    ck("and a rail with no caps set changes nothing",
+       PL._restore_rail_only(written, [{"tag": "ref_1", "file": "cook_face.png"}])
+       == written)
+
+    # The rail is authoritative, not merely restorative. gemma4-26b read `mp`
+    # as pixels and returned 1000000000; it cleared the floor, survived into
+    # the register and filled the rail dropdown with zeroes.
+    junk = json.dumps({"refs": [{"tag": "ref_1", "file": "cook_face.png",
+                                 "subject": 1, "desc": "a face",
+                                 "mp": 1000000000}], "subjects": {}})
+    cleared = json.loads(PL._restore_rail_only(
+        junk, [{"tag": "ref_1", "file": "cook_face.png"}]))
+    ck("a model-authored `mp` is dropped when the rail has no cap",
+       "mp" not in cleared["refs"][0], f"got {cleared['refs'][0].get('mp')!r}")
+    overruled = json.loads(PL._restore_rail_only(junk, rail_mp))
+    ck("and overruled when the rail has one",
+       overruled["refs"][0].get("mp") == 0.54)
+
+    bad = json.dumps({"refs": [{"tag": "ref_1", "file": "cook_face.png",
+                                "retention": "reference", "desc": "a face",
+                                "mp": 1000000000}], "subjects": {}})
+    errs, _ = PL.validate(json.dumps(rail_shots), bad, hops=2, known_files=kf)
+    ck("and a register that keeps one is rejected, naming the units",
+       any("MEGApixels" in e for e in errs), "; ".join(errs)[:130])
+
     kept = PL._merge_register(
         json.dumps({"refs": [{"tag": "ref_1", "file": "a.jpg",
                               "desc": "a woman in green"}],

tools/gen_schema.py

@@ -133,12 +133,14 @@ def build():
                                "the frame pin.",
             },
             "mp": {
-                "type": "number", "minimum": 0,
-                "description": "Per-reference pixel budget in megapixels. 0 "
-                               "(or omit) means no cap. A set value has a "
-                               f"{r.REF_MP_MIN:g} MP floor -- this is a token "
-                               "dial, so a location plate need not cost what "
-                               "a face costs.",
+                "type": "number", "minimum": 0, "maximum": r.REF_MP_MAX,
+                "description": "Per-reference pixel budget in MEGApixels, set "
+                               "by the person on the rail. Do not author it: "
+                               "omit the field. It is here so a hand-written "
+                               "plan can carry one, and a written value is "
+                               "discarded on the pinned path. A set value has "
+                               f"a {r.REF_MP_MIN:g} MP floor and a "
+                               f"{r.REF_MP_MAX:g} MP ceiling; 0 means no cap.",
             },
         },
     }
@@ -172,6 +174,15 @@ def build():
             "in the ref_plan widget. Generated by tools/gen_schema.py from the "
             "installed node -- do not edit by hand.",
         "type": "object",
+        # Both documents, or the grammar is not doing its job. Without this a
+        # reply of `{"shot_plan": {...}}` alone is schema-valid: observed live
+        # with gemma4-26b, which emitted no `ref_plan` on all three attempts.
+        # The register then stays empty, `_remap_pinned_tags` bails on the
+        # falsy ref_text before it can restore the rail's names, and every
+        # repair turn is told its beats cite undeclared tags -- so the model
+        # rewrites the beats it already got right and never emits the document
+        # that is actually missing. Qwen3 volunteered both and hid this.
+        "required": ["shot_plan", "ref_plan"],
         "properties": {
             "shot_plan": {
                 "type": "object",