There Was No Valid Config. The API Had No Word for the Subject.

Originally published on hexisteme notes.

A generated video failed review. The scene's caption read "French Guiana sits on Brazil's
border" and the frame was 93% grey Brazil, with French Guiana rendered at 57 pixels — 5.3% of
the width. Unpublishable.

Here's the scene definition:

scene:
  type: map
  focus: [BRA]        # what the camera aims at
  highlight: [FRA]    # what gets painted red
  zoom: country

Obvious fix: change focus: [BRA] to focus: [GUF].

That doesn't work, and it can't. focus takes country codes. French Guiana is not a country —
in the admin-0 dataset it's one polygon inside France's multipolygon. Measured: the 50m
boundary file has 241 features, the 110m has 177, and GUF is in neither.

There was no value I could have put in that field. The scene wasn't misconfigured. It was
inexpressible.

Why this costs two sessions instead of ten minutes

A misconfiguration and an expressiveness gap present identically: the output is wrong, the
config looks plausible, and the obvious move is to try different values.

But the fixes point in opposite directions:

• Misconfiguration → change the value.
• Expressiveness gap → change the grammar.

If you misdiagnose the second as the first, you burn time cycling through values that are all
equally impossible, and you converge on "the data must be wrong." That's exactly what
happened here — the script got "fixed" twice, across two sessions, and failed both times.

The tell is subtle, because nothing errors. focus: [GUF] doesn't raise. The code looks up
GUF, finds nothing, and falls back to something reasonable-looking. You get a frame. It's
just the wrong frame, in the same way it was the wrong frame before.

The diagnostic question isn't "what value should this be?" It's:

Does this parameter's domain cover the set of things a user will need to name?

Any API that identifies a target by code or enum — country codes, SKUs, tenant IDs, region
slugs — inherits this failure mode the moment the world subdivides more finely than the code
does. Subterritories. Product variants. Sub-accounts. The taxonomy was drawn once, and reality
kept going.

The same root cause, downstream

While tracing this I found a second defect with the same origin.

The camera grammar has zoom: region — "frame this wide enough to include the neighbours."
The code does exactly that: compute_scene_bbox(region) includes 100% of neighbouring
polygons.

Then the very next stage, a composition-budget pass, recomputes the frame from focus alone.

region and country end up producing nearly the same frame. Measured across all 19 region
scenes:

Neighbour retention	Scenes
0% — no neighbour in frame at all	12
Partial	5
100%	2

In the failing episode, a scene whose caption is "France borders eight countries" had four
of its neighbours entirely outside the frame. The subject of the sentence wasn't on screen,
and it got within one step of publication.

Both defects are the same assumption wearing two faces: the pipeline reduces "what should be
visible" to a single country code. The parameter's domain is too narrow, and the downstream
stage re-reads only that one field. A downstream normalization step that reads a subset of
the upstream declaration will silently void the rest of it — and because the output still looks
like a map, nobody notices. Twelve scenes at 0% retention, and not one test failed.

The fix: an opt-in escape hatch, not a global tweak

The tempting fix was to retune the composition budget's global constants (target subject width
0.70, etc.).

I rejected that. Other episodes already depend on those constants — episodes where a distant
territory should stay in frame. Changing a global means previously-passing cases break
silently, and they break only on screen, where the test suite can't see them. That's the
worst regression surface there is.

Instead I added camera_bbox — a scene can name its frame in raw coordinates, skipping the
zoom branch and padding entirely:

scene:
  focus: [BRA]
  highlight: [FRA]
  camera_bbox: [-55.5, 0.5, -50.5, 6.2]   # say in coordinates what the grammar can't say

Default None, so every existing script is untouched. Regression surface: zero.

French Guiana went from 57px (5.3%) to 449px (41.6%).

I deliberately did not fix zoom: region's global behaviour. Exactly one of the 19 scenes
actually needs neighbours as part of its claim; the other 18 look fine as they are. Recorded
the finding, deferred the fix, wrote down the condition that would change my mind (below).

Narrowing the camera exposed defects the wide frame was hiding

Once the frame tightened onto French Guiana, an ocean appeared to its west that shouldn't have
been there — Suriname wasn't in the neighbour set. Nobody had noticed, because in every
previous framing that spot was off-screen.

The same thing happened with captions. Scene labels are deliberately allowed to overlap
territory: the obstacle-collection function excludes country polygons on purpose, because
otherwise labels get shoved off the map. That design holds on one premise — the territory is
wider than the label.

In the climax scene, mainland France was 115px wide and the label "One country, two
continents" was about 500px. It didn't overlap the territory. It covered it. The one payoff
frame of the whole episode — red pixels visible in Europe and South America simultaneously —
was hidden behind its own caption.

The fix needed no new threshold constant. Compare measured pixels to measured pixels: add the
territory rectangle to the obstacle set only when its rendered width is narrower than the
label's rendered width. Wide territories — the existing majority — change nothing.

Fixing a defect doesn't create new ones. It reveals the ones the defect was masking. Both
of these were invisible until the first fix landed.

78% of the time proving nothing

Third finding. During the hook, the narration says "including part of South America" while
South America has zero red pixels on screen.

The reveal animation sweeps France's combined bounding box — 62° of longitude — in a single
linear pass. Most of that span is the Atlantic Ocean.

t	France red px	Guiana red px
0.27s	4,238	0
1.33s	4,461	0
1.50s	4,603	428

I considered two renderer changes and rejected both:

• Fill disjoint pieces in parallel — kills the wave effect on archipelago-heavy episodes (Canada).
• Interpolate by landmass covered rather than longitude — Guiana is still at 83% of the sweep.

What shipped was one line of script: duration_s: 1.4 → 0.6. The problem was never the
animation's mechanics; it was that 78% of 1.4 seconds went into crossing an ocean. Rather than
changing what the sweep means, I cut the time that proved nothing. First red pixel in South
America: 1.50s → 0.60s. Both continents visible together for 62% → 85% of the four-second
hook.

The part where I was wrong

My first verification report said:

"France is not in frame during the hook" · "Guiana is a red dot in the upper right"

Re-measured at full resolution, both were false. France was in frame — about 90px wide,
hexagon silhouette identifiable — and that red dot in the upper right was mainland France.
Guiana was centre-left, at the northern edge of Brazil.

The funny part: the methodology section of that same report contained my own warning —
"a 1/3-scale thumbnail creates impressions that aren't defects; re-check anything suspicious at
full resolution." I wrote the warning and then walked into it.

The verdict survived. The episode was genuinely unpublishable. But the accurate statement
wasn't "the subject isn't on screen" — it was "the camera is framing something other than
the subject," and that difference was the diagnosis. The first phrasing makes you ask "why
didn't it render?" The second makes you ask "what is it aiming at?" Only the second question
leads to focus's domain.

Portable version

1. When a bug converges on "the data must be wrong," check whether the parameter's domain covers the set of things users need to name. Code-based targeting APIs turn expressiveness gaps into what looks like misconfiguration, and the two have opposite fixes.
2. Check whether a downstream normalization step silently voids an upstream declaration. region collapsed into country because the downstream stage re-read a subset of the input. When the output still looks plausible, nobody finds out — 12 of 19 at zero retention, zero test failures.
3. Prefer an opt-in escape hatch to retuning a global. Changing a shared constant breaks passing cases in a way that only shows up on screen. A hatch defaulting to None has no regression surface.
4. Expect a fix to expose defects the old behaviour was hiding. The missing neighbour and the label overlap were both only visible after the camera tightened.
5. Check that you're obeying your own report's methodology section. I banned judging from thumbnails and then judged from a thumbnail. Documenting a discipline and enforcing it are different jobs.

What would change my mind

• If camera_bbox spreads far enough that scripts turn into coordinate soup, it isn't an escape hatch any more — it's papering over a missing grammar, and the right move becomes widening focus to accept subregions (admin-1 dataset).
• If a second scene genuinely needs zoom: region, "only one case, not worth fixing" is dead, and the composition budget should read the region bbox instead of focus.
• If the label-width comparison produces false positives on wide territories, the pixel-versus- pixel premise is wrong. A regression test watches exactly that condition.

More notes at hexisteme.github.io/notes.