Sequence contract

Input and output for scripts/verify-storyboard.py. The verifier reads structured state only; it never opens media.

Why the input is structured

The approved storyboard (e.g. SCREEN-PLAN.md in a demo repo) is prose, on purpose — a human approves visual intent, and conditions like "leave room for the laugh" are judgments, not predicates. The recording rig emits the machine-checkable half as the JSON below. Parsing prose pass-conditions is out of scope (rules/script-delegation.md The Regex Trap).

Input

{
  "delivery":  { "width": 1920, "height": 1080, "min_label_px": 14, "scale": 1.0 },
  "narration": { "source": "actual_word_timestamps",
                 "words": [ { "word": " Hi,", "start": 0.0, "end": 0.62 } ] },
  "clips":     [ { "id": "a0-hook", "entry": {manifest}, "exit": {manifest},
                   "events": [ {event} ] } ],
  "rows":      [ { "id": "a0-hook-r1", "clip": "a0-hook", "phrase": "...",
                   "proof_frame_t": 3.1, "require": {…} } ],
  "seam_tolerances": { "scroll": 2, "transform": 2 }
}

narration.source must be actual_word_timestamps. Any other value fails the time axis: WPM predicts whether a script is deliverable, never that a visual and a phrase coincide.

delivery.scale converts a recorded label height to its delivered height, and is required whenever min_label_px is set — defaulting it would assume the conversion. A label readable in the browser and unreadable in the encode is the case min_label_px exists to catch.

Manifest

route, data_fingerprint, viewport {width,height}, zoom, scroll {x,y}, transform {pan_x,pan_y,zoom}, tabs (ordered), active_tab, cursor [x,y], labels [{text, height_px}].

Events

{"type":"pan","axis":"x","delta":-640,"t":2.0} · {"type":"click","t":3.1,"pointer":[x,y],"target_rect":[x,y,w,h]}

Row requirements

A phrase spoken more than once is matched at every occurrence; a proof frame inside any of them passes.

Every declared requirement is type-checked: route and data_fingerprint are strings, visible_labels a list of strings, click_on_target a boolean. A rect — content_bounds or an event's target_rect — must describe a region with positive width and height; four numbers enclosing no area contain no point.

route · data_fingerprint · visible_labels · content_bounds [x,y,w,h] · margin_px · pan {axis, min_abs_delta} · click_on_target

A declared pan must carry a positive min_abs_delta. A threshold of zero, or an absent one, is satisfied by a take that never panned.

Output

{ "ok": false,
  "axes": {"semantic":"fail","geometry":"pass","motion":"pass","time":"pass",
           "pixels":"unverified"},
  "unverified_axes": {"pixels": "requires encoded frames; not checked by the manifest lane"},
  "finding_count": 1,
  "findings": [ {"code":"stale_data","axis":"semantic","subject":"a0-hook-r1",
                 "message":"...", "expected":"…","actual":"…"} ],
  "counts": {"rows":1,"clips":2,"seams":1} }

An axis is unverified for either of two reasons, and neither is a pass:

• pixels, always — this lane cannot examine encoded frames.
• Any axis no row exercised — a sequence that asserts nothing about geometry has not passed geometry.

unverified_axes says which case applies. An axis reported as passing without being examined is a false assurance, which is the failure the verification doctrine exists to prevent — and which the first draft of this script committed by passing an empty sequence on every axis.

Evidence is required before judgement

A requirement whose evidence the take does not carry is refused, never passed: require.content_bounds with no entry.viewport, visible_labels with no entry.labels, click_on_target with a click lacking pointer/target_rect, or proof_frame_t with no narration.words. Each yields evidence_missing naming the requirement and the absent field, on the axis that requirement is judged on — a missing viewport fails geometry, not semantic, so an axis can never read pass while its own evidence is absent.

A seam field absent from either manifest is refused for the same reason: two absences compare equal, and equality between nothing and nothing is not agreement.

A document that does not satisfy the contract exits 2 with the violation named, rather than failing later on a missing key. Validation covers structure (clips/rows as lists of objects with unique, non-empty string ids), completeness (scroll carries x/y, transform carries pan_x/pan_y/zoom, a proof_frame_t has a phrase), and finiteness of every number. Dimensions and thresholds must also be positive: min_label_px <= 0 makes readability vacuously true, a zero scale erases the measurement it converts, and a content_bounds with non-positive width or height describes no region. An explicit null is refused wherever a value is declared — it is not the same as an absent key, and accepting it let a requirement skip both its validation and the check it gates.

Finiteness is not pedantry: JSON admits NaN, and every comparison against NaN is false, so a NaN measurement or threshold satisfies whatever it is tested against. A bool is an int in Python and is rejected as a coordinate. A Python int is unbounded, so a value with no float representation (10**400) counts as non-finite rather than raising.

Exit 0 when every checked axis passes, 1 on any finding, 2 on usage error.

Finding codes

Coverage against the #369 negative tests

Seven of ten are checked here. Three need encoded frames and are not: